Tapestry Display

Publish a readable frontend for the knowledge base: $ARGUMENTS

When to use this skill

Use this skill when:

• A user wants to browse the knowledge base visually
• You need to generate a readable frontend for the organized content
• The user asks to "view", "display", "publish", or "preview" the knowledge base or a specific book
• A lightweight site presentation is preferred over raw Markdown files
• The user wants a blog-like or research portal view of the content

Purpose

This skill acts as the presentation layer for the knowledge base.

It should:

• scan the specified data directory hierarchy (or default to

  _data/books/

  )
• preserve the topic and chapter structure defined by

  index.md

• generate a readable frontend that feels closer to a blog, notebook, or research portal than to a file browser
• support building viewers for specific books or the entire knowledge base

Workflow

1. Resolve the data path from the argument:

   • If a specific path is provided (e.g., "markets-and-trading"), use

     _data/books/markets-and-trading

   • If no argument is provided, default to

     _data/books/

     (entire knowledge base)

2. Ensure the data directory exists and contains markdown files

3. Publish the frontend bundle with the appropriate data path:

# For a specific book
python display/_scripts/publish_viewer.py --data-path _data/books/markets-and-trading --force

# For the entire knowledge base (default)
python display/_scripts/publish_viewer.py --force

4. IMPORTANT: The viewer is created at

   <data-path>/_viewer

   . Serve that generated directory directly:

# Serve from the viewer directory (entire KB — default, no --data-path)
python -m http.server 8766 --directory _data/books/_viewer

# Serve from the viewer directory (specific book)
python -m http.server 8766 --directory _data/books/markets-and-trading/_viewer

Critical: When the goal is to display ALL knowledge bases, always build without

--data-path

and serve

_data/books/_viewer

. Serving from a topic-specific

_viewer/

will show only that one topic. If you used

--data-path

by mistake, re-run

publish_viewer.py --force

(without

--data-path

), kill the old server, and restart from

_data/books/_viewer

.

5. Report back with:
   • the data source path
   • the viewer output directory
   • the generated manifest path
   • the local preview URL if served

Rules

• Treat the

  index.md

  hierarchy as the authoritative structural map.
• Do not flatten the topic/chapter tree into a single undifferentiated list.
• Preserve topic-level separation so semantically distant materials remain clearly separated.
• Make documents readable first, but keep enough structural information visible for navigation.
• If the knowledge base is sparse or incomplete, still generate the frontend and let empty sections remain honest rather than faking content.

Common Issues

Viewer Shows Only One Topic Instead of All Knowledge Bases

Symptom: The viewer loads but only displays one topic (e.g.,

dingyi-dex-weekly

) even though multiple KB topics exist under

_data/books/

.

Root cause:

publish_viewer.py

was called with

--data-path _data/books/<topic>

, which scopes the viewer to just that topic. The generated

_viewer/

inside the topic directory is then served instead of the full KB viewer.

Solution:

# 1. Rebuild the full-KB viewer (no --data-path)
python display/_scripts/publish_viewer.py --force

# 2. Kill any old server processes
fuser -k <port>/tcp   # or: kill <PID>

# 3. Serve from the FULL books/_viewer, not a topic-specific one
python -m http.server <port> --directory _data/books/_viewer

Rule: To show ALL KB topics, always build and serve from

_data/books/_viewer

. Only use

--data-path

when intentionally scoping to a single book.

Data Path Not Found

The generated viewer expects

data/knowledge-base.json

under

<data-path>/_viewer/

. If you see a JSON parsing error like "Unexpected token '<'", it usually means

_ui/

was served directly instead of the published

_viewer/

output.

Solution: Re-run

publish_viewer.py

and serve

<data-path>/_viewer

.

Resources

• display/_scripts/publish_viewer.py

  : scans

  _data/books/

  , copies frontend assets, and generates the JSON manifest.

• _ui/

  : custom static frontend assets for the viewer.