--- name: ckb-export-starlight description: Export wiki/ into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use for "export the wiki to Starlight", "generate the docs site", "build a human-readable wiki site", or "publish the knowledge base as a website". --- # Export to Astro Starlight skill ## Purpose One-way and on demand: `wiki/` stays authoritative, `outputs/starlight/` is derived, never hand-edited, never fed back in. A deterministic script does the transform; the model asks the two setup questions below, invokes it, and relays its report. Human-readable counterpart of `ckb-export-okf`. ## How to run this skill ### Step 1 — Ask the two setup questions, every time The user has explicitly said they want to choose these on every invocation — do not assume a default or reuse an answer from a previous run. Use `AskUserQuestion` with: 1. **Export scope:** - "Full runnable scaffold" → `--mode full` — regenerates the whole `outputs/starlight/` project (package.json, astro.config.mjs with sidebar, tsconfig.json, src/content.config.ts, splash `index.mdx`) plus all content. Fully deletes and rebuilds `outputs/starlight/`. - "Content only" → `--mode content-only` — regenerates only `src/content/docs/**`, `public/assets/**`, and a `SIDEBAR-SNIPPET.md` with the sidebar config to paste in. Leaves any existing scaffold files (package.json, astro.config.mjs, tsconfig.json, content.config.ts, index.mdx) untouched — use this if the user is dropping the output into a Starlight project they already maintain elsewhere. 2. **Meta pages:** - "Include them" → add `--include-meta` — publishes `wiki/log.md` as a Change Log page and `wiki/error-book.md` as an Error Book page. - "Exclude them" → omit the flag — only entities, sources, graph, and overview get published. ### Step 2 — Run the script From the repository root: ```bash "/scripts/export_starlight.py" --mode [--include-meta] ``` Resolve `` to this skill's own directory and `` per "Scripts and the Python Runtime" in `AGENTS.md`. **Python 3.8+ is a hard requirement here** (and Node.js to build the site afterwards) — there is no manual fallback. If no interpreter is found, stop before asking the setup questions, say so, and point to "Prerequisites" in `docs/MANUAL.md`. Optional extra flag: `--site-title "Custom Title"` overrides the auto-derived site title (which otherwise comes from `wiki/overview.md`'s H1 — a serviceable but generic default like "Knowledge Base Overview"). Consider offering this to the user rather than always silently accepting the default, since it's the one piece of branding a reader sees first. ### Step 3 — Relay the script's report The script prints, and you should summarize back to the user: - Mode used and page count exported. - Assets (images) copied. - Which meta pages were skipped (if `--include-meta` was omitted). - Any unresolved `[[wikilinks]]` (bare wikilinks with no matching page title — these get silently degraded to plain text in the output; a small number is normal wiki-content noise, but flag the list so the user can fix the source page if it's not). - Any broken internal links the validation pass found (a link that was rewritten to a route with no corresponding generated file) — this is a real problem in the source `wiki/` content (a stale or malformed cross-reference), not a bug in the export, and is worth reporting back as something to fix at the source. - A reminder that `outputs/starlight/` has been regenerated on disk but not staged, committed, or `npm install`ed — those are separate steps for the user. For `--mode full`, the site is immediately runnable with `cd outputs/starlight && npm install && npm run dev`. ## What the transform does (for context, not something you need to re-derive) - **Frontmatter:** `tldr` → `description`; the first `# H1` in the body becomes Starlight's required `title` (and is removed from the body, since Starlight renders `title` as the page heading itself — leaving the H1 in would duplicate it). `type`/`confidence`/`quality`/`retention`/ `last_updated`/`review`/`tags`/`resource` have no native Starlight field, so they're rendered as a `:::note[Knowledge base metadata]` aside at the top of the page body instead of being dropped. - **Badges:** a page gets a `sidebar.badge` — "Superseded" (if `superseded_by` is set), else "Stale" (if `last_updated` + `freshness_window_days` has elapsed), else "Needs update" (if `review: needs_update`), else "Low confidence" (if `confidence` < 0.5) — priority in that order, one badge max. - **Links:** dual-linked cross-references (`[text](path) ([[Wikilink]])`, or the older `[[Wikilink]] / [text](path)` ordering) collapse to just the markdown link, since Starlight has no wikilink concept. Bare `[[Wikilinks]]` are resolved against every page's H1 title and converted to a proper link where a match exists, otherwise degraded to plain text. Root-absolute `/wiki/...` links become site routes (`/wiki/entities/foo.md` → `/entities/foo/`; a link to a directory's `index.md` maps to the bare directory route, e.g. `/entities/`). `linked/...`/`libs/...` cascade references (pointing outside any self-contained export) become plain text noting the path, not a broken link. - **Assets:** person photos referenced as `../assets/people/x.jpg` are copied to `public/assets/people/x.jpg` and rewritten to `/assets/people/x.jpg`. - **Graph:** `wiki/graph/edges.json` is not copied verbatim (Starlight doesn't render JSON as a page) — its content is fully rendered as a Markdown table appended to `graph/index.md`, sorted by `from`, so no information is lost. - **Sidebar:** one `autogenerate` group per top-level `wiki/` subdirectory (so new pages added to `entities/`/`sources`/`graph`/any future topic folder show up automatically on the next export without touching the sidebar config), plus explicit entries for the handful of root-level pages (Overview, the routing table, and the two optional meta pages). ## Edge cases Unusual situations — an empty target, a partial run, a conflicting state, a missing dependency — are catalogued in [`references/edge-cases.md`](references/edge-cases.md). Read that file when a run hits something the steps above don't cover; don't load it otherwise.