DEC-0015 — Docs-site generator (Astro Starlight) & the product/docs functions

Reversibility: two-way door — the generator is swappable (the OKF git repo is the source of truth and the design language is generator-agnostic); the renderer choice and curation can evolve.

Context

Establish the expert/principal agent team and first skills deferred a "docs-site / frontend agent" on the grounds that output rendering is one downstream surface, not the product. Establish the design system and the UX-engineering function lifted half of that deferral — it built @dossier/design and the ux-engineer subagent to own the design language — but it was explicit that "the docs-site/app surface choice remains explicitly deferred — this decides the design language, not the renderer," and that "Deciding the generator (Starlight vs. VitePress) is still deferred and now cheap — both run on Vite and consume this system unchanged." This change lifts the remaining half: it picks the generator and adds the functions that build and author the surface.

Options considered

1. Keep deferring the generator until a real client surface forces the choice.
2. VitePress — the other Vite-based generator DEC-0010 named as a candidate.
3. Astro Starlight (chosen) — a Vite-based docs generator, plus three new dev-team functions (product-owner, starlight-engineer, documentation-engineer) and a github-markdown skill.

Decision

Adopt Astro Starlight as Dossier's docs-site generator — the renderer for the surface that presents a client's OKF KB — and add to the dev-team layer (.claude/):

• product-owner subagent — owns what / for-whom / why / when (scope, prioritization, acceptance, success metrics; the customer voice = agency operators + their clients). Complements Principal Platform Architect (which owns how / topology / feasibility). Tools: Read, Glob, Grep, Bash, Write, WebSearch, WebFetch.
• starlight-engineer subagent — owns the Astro Starlight docs-site surface that renders a client's OKF KB: Astro/Starlight config, content collections mapping OKF→pages, OKF-native components (provenance, confidence, typed-edge navigation, concept badges), and theming Starlight onto @dossier/design. Consumes the design language (Establish the design system and the UX-engineering function); never forks it.
• documentation-engineer subagent — owns documentation as a craft (Diátaxis IA, READMEs, guides, GFM mastery). Docs reference OKF as the system of record, never fork it. Uses the github-markdown skill.
• github-markdown skill — the full GitHub-Flavored-Markdown toolkit (alerts, collapsible details, tables, task lists, mermaid, math, footnotes, themed images, anchors, badges) plus a GitHub↔Astro-Starlight portability matrix, for authoring world-class documentation.

Rationale

• The generator does not fight the build stack. Astro Starlight runs on Astro, which is Vite-based — consistent with the VoidZero/Vite lean in CLAUDE.md.
• It consumes the design language unchanged. Starlight is one of the two Vite surfaces Establish the design system and the UX-engineering function already noted consume @dossier/design; the user selected Starlight over the also-considered VitePress.
• Sovereignty is preserved (Adopt OKF as Dossier's canonical knowledge format): the site is a derived, replaceable surface over the OKF git repo (the system of record). A client can delete the site and lose nothing.
• These are product-building roles, so they live in .claude/ and are intentionally NOT added to the curated client-facing plugin subset (plugin/dossier/) — consistent with Plugin + marketplace packaging — distribution as the agency wedge, built from the canonical .claude/ primitives's scope, which already omits build-Dossier-itself roles (principal-architect, platform-engineer, ux-engineer).
• Claude-primitives-first (Claude-primitives-first build strategy): shipped as subagents + a skill, like the rest of the roster (Establish the expert/principal agent team and first skills).

Consequences

• The new subagents and skill activate on the next Claude Code session start (not picked up mid-session) — same as all subagents/hooks.
• DEC-0005's deferral of a frontend function is now fully lifted: the design language (DEC-0010) and the docs-site renderer + its building/authoring functions (this decision) both exist.
• The surface remains a derived, replaceable layer over the OKF repo — swapping the generator later costs only the surface, not the memory.
• product-owner now owns scope/prioritization/acceptance/success-metrics alongside Principal Platform Architect, splitting what/why/when from how/topology/feasibility.
• These roles stay out of the client-facing plugin subset (Plugin + marketplace packaging — distribution as the agency wedge, built from the canonical .claude/ primitives); the agency operator's toolkit is unchanged.

Review

Revisit when the first real client OKF surface ships — confirm Astro Starlight renders the reading experience (concept pages, provenance, confidence, typed-edge navigation, concept badges) on @dossier/design without forking the design language, and that the product-owner / starlight-engineer / documentation-engineer boundaries hold under real delivery.

Review update — 2026-06-14 (partially met; dogfooded)

The surface was built and verified this session as @dossier/site (packages/site): Astro 6.4.6 + @astrojs/starlight 0.40.0, rendering Dossier's own knowledge/ OKF repo zero-copy via a content-layer glob loader (the OKF repo stays SSOT — Adopt OKF as Dossier's canonical knowledge format). It consumes @dossier/design unchanged (a bridge.css aliases Starlight's --sl-* vars onto the --ds-* tokens; both flip on the same data-theme, so the chrome wears warm-paper/clay in light and dark; concept badges reuse .ds-badge--* with no hex duplication). OKF-native rendering confirmed: concept-type badge + confidence + status + provenance (source) meta strip per page; [[id]]/[[id|label]] resolved to real links via a remark plugin + id→route map (unresolved ids shown as marked spans); typed-edge "Related concepts" nav from frontmatter; sidebar generated from the KB.

Verification reproduced this session (no fabrication): astro build → 22 pages; astro check → 0 errors / 0 warnings; repo-wide pnpm lint 0 errors, pnpm typecheck (tsc -b) clean, pnpm test 268 passed / 1 skipped (baseline unchanged), pnpm build all 8 packages incl. the site, pnpm plugin:check in sync; visually confirmed light + dark via Playwright. Per this decision's scope, the site is build-side only and was intentionally NOT added to the client-facing plugin subset (Plugin + marketplace packaging — distribution as the agency wedge, built from the canonical .claude/ primitives).

This Review condition is therefore PARTIALLY met: Starlight renders concept pages / provenance / confidence / typed-edge nav on @dossier/design without forking — now demonstrated on Dossier's own KB (the dogfood). Still open: the product-owner / starlight-engineer / documentation-engineer boundaries holding under a real client delivery. Dogfooding the parser on the same KB surfaced OKF Integrity Audit — knowledge/ against @dossier/okf parse() (2026-06-14) (and the open Reconcile the decision reversibility field — free-text prose vs. the @dossier/okf enum) — a side benefit of building the surface on ourselves.