Astro + Starlight docs site + Warp docubot port + /update-docs decommission — PRODUCT

Astro + Starlight docs site + Warp docubot port + /update-docs decommission — PRODUCT

Status: RATIFIED — authored kh-prod-readiness-S58 as {9.2} of Task ID-9. Replaces the stale S47 PRODUCT scaffold (which covered only the docs-site foundation third of scope). Companion: ./TECH.md (authored at {9.3} by a fresh Planner instance per Q-PLANNER-2). Predecessor: docs/research/docs-site-rebuild-research.md (Subtask {9.1} RESEARCH).

---

Summary

Knowledge Hub gains a published documentation surface and the automation around it in a single Task. Four concerns ship together because they are mutually load-bearing:

1. Astro + Starlight docs site — a static, searchable, Warm-Meridian-themed site at a stable platform-team-facing URL, serving the canonical KH docs/ corpus through a five-space information architecture.
2. Warp docubot port — a .github/workflows/docubot.yml GitHub Action that, when a source-code PR merges, drives a Claude agent (via @anthropic-ai/claude-agent-sdk) to open a follow-up docs-PR with proposed changes. Replaces hand-curated narrative-doc maintenance.
3. Five-skill port — KH-adapted versions of 5 of Warp’s 6 docs skills (update-changelog skipped per OQ-3), each at .claude/skills/<name>/, composable with docubot (Phase 2) for richer post-merge maintenance.
4. /update-docs decommission — the bespoke .claude/skills/update-docs/ skill retires over a two-session sequence once docubot proves out and the generator step (bun run stats + bun run generate:mcp-inventory) is wired into ci.yml.

Authoring a keep-docs-in-sync skill and a repo-root AGENTS.md style guide are sibling deliverables within ID-9 (as {9.5+} implementation Subtasks per OQ-1 ratification) because five of the six Warp-ported skills depend on AGENTS.md as their canonical style source.

Per OQ-3 OVERRIDE, update-changelog is OUT-OF-SCOPE — skipped entirely (rationale: highly Warp-specific, no KH release cadence yet). Five Warp skills port; one is skipped.

---

Audiences

The docs site serves three audiences. The “future external users” framing in the stale S47 PRODUCT is dropped per the S47 Q4 reframing — the docs surface is platform-team-facing, not Phew-client-facing.

1. Liam (product owner). Primary reader. Navigates KH architecture, design system, ontology, and runbooks without grepping the repo.
2. AI development partner (Claude). Secondary reader. Consumes the docs corpus when reasoning about KH conventions, when authoring further specs, and when the docubot itself reads the published surface as its style oracle.
3. Future internal KH contributors. Tertiary reader. Engineers / agents joining the project after the foundation lands. They need a stable URL, predictable navigation, and the same content that lives in-repo.

Access control is deferred. No Phew-client login surface, no public read split, no external SMB-user framing. Internal-team-facing for the foreseeable future.

---

Scope (four-thirds envelope)

Task ID-9 is compound. PRODUCT.md MUST address all four scope-thirds; absence of any is a spec gap.

Third	What ships
(1) Docs site	Astro + Starlight project at docs-site/; five-space IA; Warm Meridian theming; Pagefind search; Vercel sibling-project deploy.
(2) Docubot port	.github/actions/docubot/ composite action + .github/workflows/docubot.yml trigger + envsubst’d prompt.txt + Claude Agent SDK.
(3) 5-skill port	KH-adapted versions of 5 of Warp’s 6 docs skills (update-changelog skipped per OQ-3). Each lives at .claude/skills/<name>/.
(4) /update-docs decommission	Gradual 2-session sequence: ship docubot + verify, then wire bun run stats into ci.yml + remove .claude/skills/update-docs/.

In-scope but supporting (per OQ-1 DEFAULT — authored as {9.5+} implementation Subtasks within ID-9):

• AGENTS.md repo-root style guide — the LLM-discoverable style/voice/terminology/frontmatter contract that the docubot + 5 skills all load.
• keep-docs-in-sync skill — the in-prompt-context skill loaded by docubot. Encodes KH conventions verbatim from AGENTS.md + the IA from RESEARCH §3.

---

OQ ratification map (1-to-1 with invariants)

Each ratification from Liam’s S58 close is mapped to a numbered invariant in this PRODUCT.md. The Checker uses this table to verify spec compliance against the RESEARCH-surfaced OQs.

OQ from {9.1} RESEARCH	Ratification	PRODUCT invariant(s) encoding it
OQ-1 — Author KH AGENTS.md within Task ID-9 (as {9.5+}) or carve off?	DEFAULT (within ID-9)	Inv-51 (AGENTS.md in-scope as {9.5+}), Inv-52 (keep-docs-in-sync in-scope as {9.5+}), Inv-37 (each of 5 skills loads AGENTS.md).
OQ-2 — Hybrid sync priority: build-time vs docubot-driven vs schema-driven?	DEFAULT (docubot PRIMARY)	Inv-18 (docubot PRIMARY production path), Inv-19 (build-time SUPPLEMENTARY for dev-loop + first-build), Inv-20 (schema-driven SUPPLEMENTARY for code-generated content).
OQ-3 — update-changelog KH equivalent: skip, author fresh, or defer?	OVERRIDE (skip)	Inv-36 (explicit non-goal: update-changelog is NOT ported; 5 skills only, not 6).
OQ-4 — IA proposal: 4 spaces (platform/ / reference/ / runbooks/ / decisions/) — ratify or alternative?	OVERRIDE (5 spaces: split platform/ into product-functionality/ + ontology/)	Inv-4 (5-space IA listed + ordered), Inv-5 (each space’s document_purpose semantics), Inv-6 (cross-space link rule).
OQ-5 — Decommission ordering: Big-Bang or gradual?	DEFAULT (gradual, 2-session)	Inv-47 (Session A: ship docubot + verify), Inv-48 (Session B: wire ci.yml stats + remove .claude/skills/update-docs/), Inv-49 (CLAUDE.md atomic update), Inv-50 (hard-deadline forcing function).

All five OQs from {9.1} RESEARCH are mapped 1-to-1. No ratification is silently dropped or partially implemented.

---

Behaviour invariants — Docs site (third 1 of 4)

Information architecture

1. Authoring surface is in-repo markdown. A contributor writes markdown (or MDX) in the KH repo’s docs/ tree using the existing PRODUCT.md / TECH.md / runbook / design-spec conventions. They do not author content inside the docs site project (docs-site/) directly. Source-of-truth remains docs/.

2. Published surface is a static site at a stable platform-team-facing URL. Deployment is Vercel (same provider as the KH app). The site is hosted at a Vercel default subdomain (string TBC at deploy time per the residual S47 Q4 follow-up — NOT under kh.phew.org.uk). The site does not embed or proxy the KH application UI.

3. Content selection is include-by-default for canonical front-door directories, exclude by deny-list. Five canonical front-door directories under docs/ publish-by-default to their respective IA spaces (per Inv-4). Adding a new file to one of these directories publishes it automatically; opting OUT requires an explicit deny-list entry in the sync manifest. This inverts the stale S47 model (which was opt-in via manifest entry) — the corpus is now large enough (478 live docs/**/*.md files at HEAD) that an explicit allow-list does not scale.

4. Information architecture is a five-space layout. Per OQ-4 OVERRIDE — the top-level IA mirrors Warp’s “spaces” pattern but splits platform/ into two distinct spaces (product-functionality/ and ontology/) because these surfaces serve different reader intents in KH (feature reference vs. data-model reference). The five spaces, in sidebar order:

   1. product-functionality/ — sources from docs/product-functionality/. Per-feature behavioural docs. The primary front door for “what does Knowledge Hub do?”
   2. ontology/ — sources from docs/ontology/. Ontology, taxonomy, cardinality specs. The primary front door for understanding the KH data model.
   3. reference/ — sources from docs/reference/ + docs/design/ + docs/generated/. Canonical references: schema, AI policy, skill routing, state-of-the-product, taxonomies, Warm Meridian design spec, generated stats. The “authoritative facts” surface.
   4. runbooks/ — sources from docs/runbooks/ + selected docs/operations/. CI, local dev, staging refresh, deployments. The “how to do operational tasks” surface.
   5. decisions/ — sources from curated docs/specs/<id>/ (ratified PRODUCT.md/TECH.md pairs only). The “why we chose X” / ADR-style surface.

5. Each space carries document_purpose semantics. Each space’s sidebar landing index page declares a one-sentence purpose statement matching the table at Inv-4. The semantic distinction prevents readers from hunting in the wrong space (e.g. “where do I find the ontology?” → ontology/, never reference/).

6. Cross-space links use absolute URLs, never relative paths. Starlight’s content-collection routing means relative paths do NOT traverse spaces (per the check_for_broken_links SKILL.md research). Any cross-space link MUST be an absolute path-style URL (e.g. /reference/schema-quick-reference/). The build validator rejects relative paths that escape the current space.

Rendering & UX

7. Versioning is single-version at foundation. One version — “the current state of the docs as committed on main.” No version switcher, no per-version sidebar, no archived snapshot. Versioning may be added later if a stable external API or schema demands it; the foundation must not preclude that addition.

8. Search is built-in and offline-capable across all five spaces. Pagefind is the search surface. Full-corpus search indexes all five spaces (no per-space search silos). Keyboard-navigable, ranked-results.

9. Navigation supports keyboard, screen reader, and mobile users. Sidebar, table of contents, search, and content links are keyboard-traversable. ARIA landmarks (navigation, main, search) are present. The site meets WCAG 2.1 AA. Callouts and admonitions carry an icon plus a text label (never colour alone for meaning).

10. Branding consumes the Warm Meridian design system. Palette, typography (Instrument Sans), accent (Warm Meridian amber --primary), borders, code-block surfaces all draw from docs/design/warm-meridian-implementation-spec.md’s semantic-token vocabulary. Light and dark modes both supported via Starlight’s data-theme attribute (parity with the app’s class-based .dark toggle is not required — independent toggle, identical palette values).

11. Code blocks and tables render at KH quality. Code: syntax-highlighted, line numbers available, copy-to-clipboard, language label visible. Tables: header emphasis, aligned columns. Inline code: mono face with a tonal-warm background.

12. Internal links resolve to canonical published paths. A markdown link from one published doc to another resolves to the published-site URL. Links to in-repo paths that are NOT published render as plain text or as an outbound GitHub link (never as a dead anchor). A link to a path that was published but later removed produces a build failure, not a silent 404.

13. “Edit this page on GitHub” link points at canonical source. Every published page carries an editLink.baseUrl-derived link to its source markdown file on main. Reader can always reach the markdown file.

14. Last-updated timestamp is honest. Each page shows a last-updated date derived from the source file’s git history on main, formatted DD/MM/YYYY (UK convention). NOT the docs-site build time.

15. Authoring stays in markdown by default; MDX where genuinely needed. Pure-markdown documents render correctly. Contributors never have to convert .md → .mdx just to publish.

16. Front matter is minimal and Zod-validated. Required: title. Optional: description, sidebar (order/label), lastUpdated override. Sync-managed (do not hand-edit): kh_source, kh_last_verified. Build fails on unknown or malformed fields (loud failure, never silent skip).

17. Empty / loading / error states behave gracefully. Empty sidebar group → omit, don’t render an empty header. No-match search → clear “no results” state. 404 page exists, branded, offers search + home link. Build with malformed front matter / broken internal link / missing referenced page → CI fail-loud.

Sync mechanism (OQ-2 hierarchy)

18. PR-merge docubot is the PRIMARY production sync path. When a source-code PR merges to main, docubot (third 2 of 4) opens a follow-up docs PR that writes directly to docs-site/src/content/docs/<space>/ for any docs that need updating. This is the dominant path for narrative-doc updates in steady-state operation.

19. Build-time sync is the SUPPLEMENTARY dev-loop primitive. A docs-site/scripts/sync-content.ts script + docs-site/sync-manifest.json handle include-by-default-with-deny-list mirroring from docs/ to docs-site/src/content/docs/. Runs as a pre-build step (bun run sync && astro check && astro build). Used for: (a) developer dev-loop (so localhost preview works against unmerged changes), (b) first-build bootstrap (before docubot ships), (c) deterministic re-mirror after content moves. NOT the primary steady-state path.

20. Schema-driven scheduled syncs are SUPPLEMENTARY for code-generated content. The KH analogues of Warp’s sync-error-docs skill (see Inv-39 / third 3 of 4) run on schedules against code surfaces — supabase/types/database.types.ts, MCP registrations in lib/mcp/, route handlers in app/. They write to specific reference-space pages (e.g. /reference/schema-quick-reference/, /reference/mcp-inventory/) and open scheduled PRs. NOT the primary path for narrative docs.

21. Search and navigation are stable across worktrees. The docs site builds from main. Long-lived worktrees (production-readiness) do not fork published docs — their changes land via merge to main like any other change.

22. Content removal is explicit and tracked. Removing a doc from the site requires removing its source file (or adding it to the manifest deny-list). A removed doc’s published URL surfaces in the build’s diff so redirect decisions can be made deliberately. The site does not silently drop a previously-published page on a manifest typo.

AI-invisibility & UK English

23. AI is invisible infrastructure throughout the docs surface. No “AI-powered” badges, no Sparkles icons, no model names in user-facing copy. AI-derived platform outputs (quality scores, summaries, classifications) are documented as platform features when documented at all — never as “AI features.” See docs/reference/ai-visibility-policy.md. CI guard (grep-test) blocks publication of synced content matching AI-powered|Sparkles|powered by (Claude|GPT|Anthropic|OpenAI).

24. UK English throughout. Body copy, navigation labels, callout titles, footer text — all UK English (colour, organisation, DD/MM/YYYY). Spell-check / lint guidance enforces this at build time where possible.

---

Behaviour invariants — Docubot port (third 2 of 4)

Trigger & lifecycle

25. Trigger surface is workflow_dispatch + pull_request.types: [closed] filtered to merged == true. Per RESEARCH §2.1 — Warp’s commented-out issue_comment / pull_request_review_comment triggers (which caused org-wide noise) are NOT ported. Manual invocation via workflow_dispatch with pr_number / prompt / warp_channel (renamed claude_model for KH) inputs is supported.

26. Docubot opens exactly one follow-up docs PR per source-code PR merge. Single-PR-per-trigger guarantee. If multiple doc surfaces need updates from one source PR, they cluster into ONE docs-PR. No fan-out.

27. Docubot posts exactly ONE comment on the source PR per run. Warp’s single-comment guardrail ported verbatim. Comment either (a) provides docs-PR link + summary + tags source-PR author as reviewer, or (b) explains why no doc changes were needed.

28. Time-to-docs-PR has a soft target. Docubot SHALL open the follow-up docs PR within 15 minutes of source-PR merge under normal load. If the run exceeds 30 minutes, CI alerts via standard workflow-failure notification.

Authoring contract

29. Docubot adheres to KH commit conventions. Branch name: docubot/<short-slug-from-invoking-pr-title>. Commit message: docs(area): concise summary. PR title: Docs: <concise summary> (from #<source-PR-number>). PR body MUST include Summary / Pages updated / Why sections.

30. Docubot writes directly to docs-site/src/content/docs/<space>/<file>.md. Per Inv-18 — docubot is the PR-merge fast-path writer to the published collection (matches RESEARCH §4.3.6 + OQ-2 ratified default). The docs/ source tree is NOT updated by docubot on this path; human authors continue to write docs/ directly, with Inv-19 build-time sync mirroring docs/ → docs-site/. Divergence handling for docubot-touched paths (where docs/<path>.md and docs-site/src/content/docs/<path>.md may drift over time) is a TECH-phase concern ({9.3}) — candidate approaches include reverse-sync, docubot-write-to-both, or marking docubot-owned paths in sync-manifest.json.

31. Docubot follows the KH AGENTS.md style guide. Loads repo-root AGENTS.md (delivered as {9.5+} Subtask per Inv-51) in its prompt context. Loads .claude/skills/keep-docs-in-sync/SKILL.md (delivered as {9.5+} Subtask per Inv-52) for KH-specific IA + sync conventions. NEVER recreates docs that already exist (must consult docs/reference/documentation-inventory.md).

Authentication & runtime

32. Claude integration is via @anthropic-ai/claude-agent-sdk (NOT Claude Code headless, NOT raw Anthropic API). Per Liam’s S46 ratification (workflow-orchestration-feedback-response.md §2.3). The GH Action’s “Run Claude agent” step invokes a TypeScript driver that loads the envsubst’d prompt + initiates the SDK’s tool-loop with KH MCP server registrations available.

33. Secrets contract. ${{ secrets.ANTHROPIC_API_KEY }} for the SDK. ${{ secrets.GITHUB_TOKEN }} for git operations + gh CLI (same-repo, so no PAT needed). Runs on ubuntu-latest (NOT Warp’s namespace-profile-ubuntu-20-04).

34. Run artefacts are always uploaded. Per RESEARCH §2.2 — the rendered prompt.output.txt + the Claude SDK’s run log upload as actions/upload-artifact@v4 on EVERY run (success or fail). Debugging signal must not depend on run success.

Phase 2 composability (with the 5 ported skills)

35. Docubot is composable with the 5 ported skills. When the docs-PR docubot opens lands, a separate review-docs-pr workflow (Inv-37) runs against it as a second auto-review pass on the bot’s output. Other scheduled skills (check_for_broken_links, sync-error-docs, missing_docs, docs-seo-audit) operate independently of docubot but share the same keep-docs-in-sync + AGENTS.md context.

---

Behaviour invariants — Five-skill port (third 3 of 4)

Skill set scope

36. 5 of Warp’s 6 docs skills port; 1 is skipped. Per OQ-3 OVERRIDE — update-changelog is OUT-OF-SCOPE (explicit non-goal). The 5 skills that DO port: review-docs-pr, sync-source-docs (KH-renamed from Warp’s sync-error-docs), missing-docs, check-for-broken-links, docs-seo-audit. Each lives at .claude/skills/<name>/SKILL.md + (where applicable) scripts/*.py + references/*.md.

37. Each ported skill loads AGENTS.md. Per Inv-31 / Inv-51 — every skill that needs KH style/voice/terminology context loads the repo-root AGENTS.md. Without it, ports lose fidelity (the audit found 5 of 6 Warp skills depended on Warp’s AGENTS.md).

Per-skill triggers & ports

38. review-docs-pr ports verbatim in workflow shape; KH-adapted in dependencies. Triggers on docs-PR review (typically the docubot-opened docs-PR, or human-authored docs PRs). Emits review.json with summary + comments[] array per Warp’s contract. Severity-label prefixes ([CRITICAL] / [IMPORTANT] / [SUGGESTION] / [NIT]) ported without emoji to match KH’s no-emoji rule. Comments posted via gh pr comment.

39. sync-source-docs (renamed from Warp’s sync-error-docs) is the KH-adapted code-source-vs-docs sync skill. Operates against three KH source-vs-docs pairs:

    • supabase/types/database.types.ts → /reference/schema-quick-reference/ (and per-table pages where they exist).
    • MCP tool/resource/prompt registrations in lib/mcp/ → /reference/mcp-inventory/ (currently generated by bun run generate:mcp-inventory).
    • Route definitions in app/ → /reference/api-routes/ (NEW reference page; sync-source-docs is responsible for first creation + ongoing sync). Runs on schedule (weekly) AND ad-hoc. Opens a docs-PR per detected drift (per Warp’s pattern). The original sync-error-docs SKILL.md is the structural template.

40. missing-docs ports the “audit + draft” two-phase pattern. Phase 1 (audit): a Python script .claude/skills/missing-docs/scripts/audit_docs.py runs four sub-audits — (a) feature flags / env vars (against .env.example + docs/runbooks/local-development.md), (b) CLI commands (against package.json scripts vs docs/runbooks/), (c) MCP / route surfaces (against lib/mcp/ + app/ vs /reference/mcp-inventory/ + /reference/api-routes/), (d) terminology staleness (against references/stale_terms.md — KH-specific). Phase 2 (draft): reads references/kh_surface_map.md (KH-specific feature → doc-path mapping) + 2-3 strong examples for format, then drafts. Independently triggerable per phase.

41. check-for-broken-links is the most directly portable. Generic Python link-walker. Runs scheduled (daily) AND inside review-docs-pr (per Warp’s pattern). Five error types handled per RESEARCH §1.5: file-not-found, case-mismatch (Astro is case-sensitive), missing .mdx extension on directory link, cross-space relative path (per Inv-6), HTTP 4xx/timeout for external links. --slack-notify mode is NOT ported (KH has no current Slack workflow integration); replace with optional --gh-pr-comment mode that posts via gh pr comment.

42. docs-seo-audit ports the 11+ SEO-issue-type catalogue across three severity tiers (errors / warnings / info — per RESEARCH §1.6). Crawls the live docs-site sitemap. Workflow preserves the “ASK before fixing” guardrail verbatim (prevents mass-rewrites without human review). Deferred chronologically — runs only after the docs site is live + deployed (so the sitemap exists).

43. Each skill is workflow_dispatch-triggerable as a .github/workflows/<skill-name>.yml. Per Inv-35 — each skill ports to a sibling workflow file mirroring docubot.yml’s shape: workflow_dispatch + (where applicable) schedule: cron. Each invokes the Claude Agent SDK with the relevant skill loaded into the prompt.

---

Behaviour invariants — /update-docs decommission (third 4 of 4)

Per OQ-5 DEFAULT — gradual two-session decommission. The current /update-docs skill does four things; each is replaced by a specific successor before removal.

Current /update-docs responsibilities (auditor’s reference)

The skill at .claude/skills/update-docs/SKILL.md currently performs four functions per RESEARCH §4.3.3:

• (a) refreshes docs/reference/product-roadmap.json,
• (b) refreshes docs/reference/state-of-the-product.md,
• (c) runs bun run stats + bun run generate:mcp-inventory to refresh docs/generated/,
• (d) refreshes docs/reference/product-backlog.json. Plus an auto-chain to /handoff.

Successor mapping

44. Functions (a) + (b) + (d) move to docubot. The PR-merge-triggered narrative-doc refresh is exactly the docubot’s job (third 2 of 4). When a source-PR merges, docubot reads the diff and updates the roadmap / state-of-the-product / backlog as needed (alongside any other narrative-doc that the PR affects). Per Inv-31, docubot consults documentation-inventory.md so it does not recreate docs that already exist.

45. Function (c) — bun run stats + bun run generate:mcp-inventory — moves to ci.yml as a merge-to-main step. Generated-from-code outputs (codebase-stats.md, mcp-inventory.md) MUST remain build-step generated, not LLM-authored. A new ci.yml job regenerate-stats runs on push: main, executes both commands, and commits the regenerated files via the standard git config user.email ...; git commit flow (or via a side-PR if direct main-commits are blocked by branch protection — TBC at implementation per New OQ-6 below).

46. /handoff auto-chain is preserved as a standalone skill. /handoff remains a session-scoped continuation-prompt generator independent of any docs-site concerns. It is not removed in this Task; only the /update-docs → /handoff chain wires through /handoff directly going forward (callers invoke /handoff standalone).

Two-session sequence

47. Session A (decommission gate 1): ship docubot + verify end-to-end. Acceptance: (i) docubot opens at least 3 sample docs-PRs on real source-PR merges; (ii) all 3 narrative-doc updates ((a) + (b) + (d) workloads) execute correctly (manual review); (iii) docubot’s single-comment + commit-conventions hold across all 3 samples. Once gate 1 closes, decommission proceeds to Session B.

48. Session B (decommission gate 2): wire ci.yml stats job + remove .claude/skills/update-docs/. Acceptance: (i) ci.yml regenerate-stats job runs successfully on at least one merge-to-main commit; (ii) .claude/skills/update-docs/ directory removed; (iii) any callers of /update-docs in .claude/ configs / hooks updated to either invoke /handoff directly (where applicable) or removed (where the call was redundant with docubot).

49. CLAUDE.md atomic update. In the same commit as Session B’s removal: CLAUDE.md’s /update-docs references are replaced with docubot + keep-docs-in-sync references. The “Implementation Workflow” + “Memory (MemPalace)” + reference-doc tables are updated atomically. No transition window where CLAUDE.md and the skill set are out of sync.

50. Hard deadline (forcing function). /update-docs MUST be removed by end of Session B regardless of corner-case discoveries. Corner-case findings get filed as Subtask {9.M} follow-ups against docubot OR against the 5 skills, never as “keep /update-docs around for a bit longer.” Two-session bound is non-negotiable to prevent decision-fatigue + dual-path drift.

---

Supporting deliverables — within ID-9 as {9.5+} Subtasks (OQ-1 DEFAULT)

51. AGENTS.md at repo root is delivered as one or more {9.5+} Subtasks within ID-9. Per OQ-1 ratification. Contents per RESEARCH §4.3.5:

    • Voice + tone rules (UK English, professional-direct, no marketing copy, no emoji per the project no-emoji guidance).
    • Terminology table (Knowledge Hub vs “the platform” vs “the app”; “Change Reports” vs “Digest” per the S248 rename; canonical taxonomy terms).
    • Frontmatter contract (matching the Zod schema in TECH.md).
    • Content-type style guides (concept docs, procedural docs, reference docs, troubleshooting docs).
    • AI-invisibility rules (per Inv-23). All 5 ported skills + docubot load AGENTS.md. Without it, ports lose fidelity.

52. keep-docs-in-sync skill at .claude/skills/keep-docs-in-sync/SKILL.md is delivered as a {9.5+} Subtask within ID-9. Per OQ-1 ratification. Contents per RESEARCH §4.3.4:

    • KH docs/ IA conventions (five-space layout per Inv-4).
    • Warm Meridian palette + typography references (per docs/design/warm-meridian-implementation-spec.md).
    • AI-invisibility policy reference (per docs/reference/ai-visibility-policy.md).
    • UK English requirements.
    • The docs/reference/documentation-inventory.md index (so docubot does not recreate existing docs).
    • Commit + PR conventions (matching commit-commands:commit-push-pr).
    • Single-comment guardrail (matching Warp’s pattern). The docubot loads this skill in its prompt by default. Acts as the canonical “how does docubot author KH docs?” reference.

---

Acceptance criteria

The compound Task ID-9 is considered shipped when all four scope-thirds have demonstrable acceptance — measured per third, not as one monolithic gate.

Third 1 — Docs site

• The Astro + Starlight site builds reproducibly from a fresh clone via cd docs-site && bun install && bun run build.
• All five canonical front-door directories (docs/product-functionality/, docs/ontology/, docs/reference/, docs/runbooks/, docs/specs/<ratified>/) publish to their assigned spaces with the 5-space sidebar visible.
• The site deploys to a Vercel sibling project (knowledge-hub-docs) at a Vercel default subdomain Liam can browse.
• Warm Meridian palette + Instrument Sans + light/dark switch visibly applied. No default Starlight cobalt-blue accent.
• CI gates the docs build: malformed front matter, broken internal link, removed referenced page → build fails before deploy.
• Pagefind search returns ranked results across all five spaces.

Third 2 — Docubot port

• .github/actions/docubot/action.yml + .github/workflows/docubot.yml + .github/actions/docubot/prompt.txt all present.
• workflow_dispatch invocation succeeds end-to-end on at least one sample run.
• pull_request.types: [closed] filter to merged == true triggers docubot on at least one real source-PR merge.
• Docubot opens a single docs-PR + posts a single comment on the source PR per Inv-26 / Inv-27.
• Time-to-docs-PR ≤ 15 minutes on at least 80% of sample runs (Inv-28).
• Run artefacts (prompt.output.txt + SDK log) upload on every run regardless of outcome.

Third 3 — 5-skill port

• .claude/skills/review-docs-pr/SKILL.md, .claude/skills/sync-source-docs/SKILL.md, .claude/skills/missing-docs/SKILL.md, .claude/skills/check-for-broken-links/SKILL.md, .claude/skills/docs-seo-audit/SKILL.md all present.
• Each has its .github/workflows/<name>.yml workflow file matching docubot.yml’s shape.
• review-docs-pr runs against at least one docubot-opened docs-PR + emits review.json per Warp’s contract.
• sync-source-docs runs at least once against the schema source pair + opens a docs-PR.
• check-for-broken-links runs at least once + reports findings.
• missing-docs runs Phase 1 audit at least once + reports gap list.
• docs-seo-audit runs at least once against the live site (post-deploy).
• update-changelog is explicitly NOT present (OQ-3 OVERRIDE non-goal confirmed).

Third 4 — /update-docs decommission

• Session A gate closed: docubot demonstrably handled (a)+(b)+(d) workloads on at least 3 sample source-PR merges.
• Session B gate closed: ci.yml regenerate-stats job ran successfully on at least one merge-to-main.
• .claude/skills/update-docs/ removed.
• CLAUDE.md atomically updated to remove /update-docs references + add docubot + keep-docs-in-sync references.
• No dual-path drift window — Session B closes ≤ 2 sessions after Session A opens (Inv-50 hard deadline).

Supporting deliverables (in-scope per OQ-1)

• AGENTS.md exists at repo root with all five content sections per Inv-51.
• .claude/skills/keep-docs-in-sync/SKILL.md exists with all seven content sections per Inv-52.
• All five ported skills + docubot demonstrably load AGENTS.md (verified by grep of their prompt construction OR by their workflow YAML).

---

Non-goals (explicit OUT-OF-SCOPE)

• update-changelog port (OQ-3 OVERRIDE). The Warp skill is highly Warp-specific (depends on Warp’s release infra: releases.warp.dev/channel_versions.json, warpdotdev/channel-versions, warp-internal PR-mining). KH has no equivalent release cadence; building a KH analogue prematurely creates a parallel surface to /update-docs decommission. Revisit only when KH has tagged releases.
• Version switcher / archived docs snapshots. Single-version at foundation per Inv-7.
• Per-locale content / i18n. English-only at foundation.
• Algolia / hosted search. Pagefind covers foundation per Inv-8.
• Phew-client-facing docs surface / kh.phew.org.uk subdomain. Platform-team-facing only per Audiences section + Inv-2.
• External-user / UK-SMB audience. Dropped per S47 Q4 reframing — confirmed not in PRODUCT scope.
• Visual regression suite (Percy / Chromatic). Manual visual checks at foundation per Inv-10. Defer until a second Warm Meridian consumer materialises.
• Per-request rendering on the docs site. Static-only via @astrojs/vercel/static. If on-demand behaviour is ever needed, swap to @astrojs/vercel/serverless post-foundation.
• Vendor-style admin-restricted area of the docs site. Deferred. No Vercel auth or path-prefix split at foundation.
• The other 18 Warp skills beyond the 6 highlighted (per RESEARCH §“Findings + surprises”). Out-of-scope for ID-9; candidate for a future expansion Task.

---

New open questions (≤3 ceiling)

This PRODUCT introduces three new OQs beyond the five ratified from {9.1} RESEARCH. The Orchestrator routes each to Liam before {9.3} TECH begins (or, if non-blocking, before implementation).

New OQ-6 — ci.yml regenerate-stats direct-commit vs side-PR?

Question: Per Inv-45, the bun run stats + bun run generate:mcp-inventory job runs on push: main. It writes regenerated files to docs/generated/. Two options for commit-back:

• Option A (direct commit): Workflow commits regenerated files directly to main. Requires CI to have contents: write permission + the workflow bot identity bypasses branch protection’s “require PR” rule (if enabled). Faster, cleaner.
• Option B (side-PR): Workflow opens a small PR titled chore: regenerate stats that auto-merges once CI passes. Slower, but uniform with branch-protection rules.

Default proposed: Option A (direct commit), provided branch-protection on main allows the workflow bot identity to push. If branch-protection disallows, fall back to Option B. The Executor verifies at implementation time.

New OQ-7 — Cross-worktree docs-site preview for sub-agent worktrees?

Question: The docs site builds from main. Sub-agent worktrees (cmux-spawned .claude/worktrees/agent-<id>/) frequently have unmerged docs changes that the author wants to preview before opening a PR. Three options:

• Option A (recommended): Each worktree runs cd docs-site && bun run dev locally. The sync script (scripts/sync-content.ts) accepts a --source-root flag that defaults to ../docs (this worktree’s docs) but can target a sibling worktree’s docs/ directory.
• Option B: Skip local-preview entirely; rely on Vercel preview URLs once the worktree’s branch pushes.
• Option C: Build a hosted preview service that polls all open worktrees + renders each at a separate preview URL.

Default proposed: Option A. Aligns with the existing bun run dev pattern for the Next.js app. Per-worktree localhost is cheap. Option C is over-engineered for a 1-developer-1-AI-partner setup.

New OQ-8 — AGENTS.md versus existing CLAUDE.md — separation of concerns?

Question: KH already has CLAUDE.md (project instructions). AGENTS.md (per OQ-1) covers docs-authoring conventions specifically. Risk of overlap: voice rules, UK English rules, terminology. Two options:

• Option A (recommended): AGENTS.md is docs-corpus-specific. CLAUDE.md remains the project-wide instruction file. AGENTS.md cross-references CLAUDE.md for project-wide rules (UK English, no-emoji, package-manager-bun, etc.) and ADDS docs-specific rules (frontmatter contract, content-type style guides, AI-invisibility rules per Inv-23). The two files are complementary, not redundant.
• Option B: Merge AGENTS.md content into CLAUDE.md as a new section. Pro: one file. Con: violates the Warp convention that the 5 ported skills are designed against (they look for AGENTS.md by name, per RESEARCH §1.7).

Default proposed: Option A. The skills look for AGENTS.md by name; renaming/merging breaks the port fidelity. Cross-reference keeps the two files clean.

---

Findings carried over from {9.1} RESEARCH (informational, not action-requiring at {9.2})

• wp6-ontology-harness directory absence at HEAD. The stale TECH.md’s “first content-sync target” referenced a directory that does not exist at HEAD. Replaced by the include-by-default canonical-directory model (Inv-3) — there is no “first sync target” any more; the 5 canonical directories all publish-by-default.
• The docs/ corpus is large (478 live files). This is why Inv-3 inverts the manifest model from opt-in to opt-out.
• 24 Warp docs skills exist; only 6 are in scope here; only 5 of those port. Future expansion Task could revisit the other 18 (draft_conceptual, draft_procedural, style_lint, sync_terminology, sync-openapi-spec, etc.) — out-of-scope for ID-9.
• The docubot composite action snapshot references warpdotdev/gitbook not warpdotdev/docs. Predates the Warp GitBook → Astro pivot. The port adapts repo names + persona; the workflow pattern is unchanged.

---

End of PRODUCT spec {9.2} for Task ID-9.