---
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:
```bash
# 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:
```bash
# 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**:
```bash
# 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.