---
name: export-starlight
description: Export the local wiki/ knowledge base into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use when the user asks to "export the wiki to Starlight", "generate the docs site", "export as Astro Starlight", "build a human-readable wiki site", or "publish the knowledge base as a website".
---

# Export to Astro Starlight skill

## Purpose

Regenerate `outputs/starlight/` from the current `wiki/` tree so it can be
built and served as an Astro + Starlight documentation website — a
human-readable, browsable version of this knowledge base (unlike
`export-okf`, which targets machine/tool consumption). This is a one-way,
on-demand export — `wiki/` stays the authoritative source; `outputs/starlight/`
is always a derived artifact of it, never edited by hand and never fed back
in.

This skill only runs when explicitly invoked — it is deliberately not part
of the always-loaded `CLAUDE.md`/`AGENTS.md` Ingest/Lint workflows.

The heavy lifting (frontmatter remapping, link rewriting, asset copying,
sidebar generation) is done by a deterministic Python script, not by
reading and rewriting every page by hand — the wiki now has 60+ pages, and
a mechanical transform like this belongs in code, not in per-page model
reasoning. Nothing in this skill needs an LLM to run correctly; the model's
job is just to ask the two setup questions below, invoke the script, and
relay its report.

## Trigger phrases

Use this skill when the user says things like:
- "export the wiki to Starlight" / "export as Astro Starlight"
- "generate the docs site" / "build the Starlight site"
- "publish the knowledge base as a website"
- "sync outputs/starlight"

## 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
python3 "<skill-dir>/scripts/export_starlight.py" --mode <full|content-only> [--include-meta]
```

Resolve `<skill-dir>` to this skill's own directory. 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`/`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 "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

- **A future `wiki/<newtopic>/` subdirectory:** handled automatically —
  the script discovers top-level `wiki/` subdirectories dynamically and
  adds a sidebar `autogenerate` group for each; no script changes needed.
- **Re-running with no wiki changes:** should produce byte-identical
  output (directory listings are sorted before writing). If asset copying
  or link rewriting ever introduces nondeterminism, that's a bug in the
  script, not expected behavior.
- **A wiki page with no `tldr`:** `description` is simply omitted from
  that page's frontmatter — Starlight tolerates a missing description.
- **A wiki page with no H1:** falls back to a slugified filename as the
  title (e.g. `foo-bar.md` → "Foo Bar"), same fallback rule `export-okf`
  uses.