---
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.