display

name	display
description	Expose the organized knowledge base through a readable frontend experience. Use when a user wants to browse the knowledge base visually as a lightweight site instead of reading raw Markdown files directly. Supports building viewers for specific data paths (e.g., individual books) or the entire knowledge base.
argument-hint	["optional-data-path"]
allowed-tools	Bash(*), Read, Glob, Grep, Write, Edit

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.