Docs-site rebuild research — Astro+Starlight + Warp docubot port + decommission /update-docs

Docs-site rebuild research — Astro+Starlight + Warp docubot port + decommission /update-docs

Subtask: ID-9.1 RESEARCH. Parent Task: ID-9 — Implement Astro+Starlight docs site + Warp docubot port + decommission /update-docs. Scope: Pre-PRODUCT research. Inventories the missing two-thirds of Task ID-9 that the DRAFT specs at docs/specs/id-9-astro-starlight-docs-foundation/ do not cover; audits the current docs/ tree at HEAD 3e4ee5c2 post-S57 archival. Author: task-planner (fresh instance per Q-PLANNER-2).

---

Reframing — why this RESEARCH is necessary

The stale DRAFT specs at docs/specs/id-9-astro-starlight-docs-foundation/ (PRODUCT.md 221 lines, TECH.md 629 lines — both dated 15/05/2026) cover only the base docs-site implementation: Astro + Starlight scaffold, Warm Meridian theming, manifest-driven sync from docs/ to src/content/docs/, Vercel deploy. They were authored in kh-prod-readiness-S47 against a one-third slice of what Task ID-9 actually delivers.

The full Task ID-9 envelope is now compound — three concerns in one delivery:

1. IMPLEMENT Astro+Starlight docs site (covered by stale specs).
2. PORT Warp’s docubot mechanism + six Warp docs skills (NOT in stale specs).
3. DECOMMISSION the bespoke .claude/skills/update-docs/ skill once docubot auto-sync ships (NOT in stale specs).

Liam’s S48 feedback (preserved in MemPalace thread 3f640052-f37e-401f-9102-f20775abf792.jsonl) was the reframing trigger. Since then (15/05 → 20/05) the docs/ tree has been heavily restructured by the S57 archival sweep: roughly 700+ files moved from docs/audits/, docs/specs/, docs/plans/, docs/research/, docs/continuation-prompts/ into .planning/.archive/.audits/, .planning/.archive/.specs/, .planning/.archive/.research/, .planning/.archive/.continuation-prompts/. The Information Architecture (IA) assumptions baked into the stale specs are now stale themselves.

This RESEARCH does four things, mandated by the dispatch brief:

1. Inventory the six Warp docs skills at github.com/warpdotdev/docs/.agents/skills/.
2. Document the Warp docubot mechanism (composite action + envsubst prompt + workflow trigger).
3. Audit the current KH docs/ IA at HEAD 3e4ee5c2 so the new {9.2} PRODUCT spec can author against reality.
4. Enumerate the delta between stale specs and the new compound scope — what’s still valid / stale / missing / needs reratification.

The product of this RESEARCH is input for the fresh task-planner instance that will author {9.2} PRODUCT.md.

---

§1 Warp docs skills inventory (six skills at warpdotdev/docs/.agents/skills/)

The six skills referenced in the assessment (kh-workflow-orchestration-assessment.md §8 / §9) live in the public Warp docs repo at github.com/warpdotdev/docs/.agents/skills/. (Caveat: the assessment referenced them as .warp/skills/; the actual location on disk is .agents/skills/. README cross-references both paths — .warp/skills/ is the older convention, .agents/skills/ is current.) The skills directory contains 24 total skills as of 20/05/2026; the six docs-portable ones are listed below with full frontmatter, trigger conditions, dependencies, and KH portability notes.

For each: skill source is https://github.com/warpdotdev/docs/blob/main/.agents/skills/<name>/SKILL.md.

1.1 review-docs-pr (4.9 KB)

Frontmatter:

name: review-docs-pr
description: Reviews documentation pull requests for the Warp docs repository.
  Checks for broken links, style guide compliance, content quality, and Astro
  Starlight structure. Use when reviewing documentation PRs or when you need to
  provide feedback on markdown documentation changes.

Trigger conditions: Invoked on docs-PR review. Five review axes: (1) potential broken links, (2) style-guide compliance via AGENTS.md, (3) content quality (clarity, frontmatter, headers/lists), (4) code-snippet correctness via answer_question skill, (5) Astro Starlight structure integrity — sidebar config updates after file moves/renames, redirects in vercel.json.

Dependencies:

• Sibling skill answer_question for verifying technical details against docs + source code.
• Sibling skill check_for_broken_links (calls its check_links.py script directly).
• Repo-root AGENTS.md as the style-guide source of truth.
• astro.config.mjs for sidebar config.
• vercel.json for redirects.
• jq CLI for review.json validation.

Output contract: Writes a review.json with summary + comments[] array. Each comment has path, line, side ("LEFT"|"RIGHT"), body. Comment bodies prefixed with required severity labels: 🚨 [CRITICAL] / ⚠️ [IMPORTANT] / 💡 [SUGGESTION] / 🧹 [NIT]. Summary ends with verdict: “Approve” / “Approve with nits” / “Request changes”.

KH portability notes:

• Style-guide axis maps onto docs/reference/documentation-inventory.md + a future KH-equivalent AGENTS.md (which does not yet exist on KH side; surfaced as OQ below).
• Code-snippet axis would need a KH analogue of answer_question (closest fit: ccc semantic search + gitnexus AST graph). This is portable — the abstraction “search docs + search source for authoritative answer” works against KH’s existing semantic-search infrastructure.
• Severity labels (emoji + bracket) are PR-comment cosmetics; portable verbatim or adaptable to caveman-style compression ([C]/[I]/[S]/[N]).
• The review.json shape is generic — Warp authors emit JSON because their PR-comment posting is a separate step; KH can do the same or post via gh pr comment directly.
• Recommended port name: review-docs-pr (verbatim).

1.2 update-changelog (10.4 KB — largest of the six)

Frontmatter:

name: update-changelog
description: Update the public changelog at docs.warp.dev/changelog with the
  latest stable release. Fetches changelog data from channel-versions, formats
  a new entry, and opens a PR. Use after a stable release ships (typically
  Fridays).

Trigger conditions: Scheduled (post-release, “typically Fridays” — likely a cron on the docs repo) OR manually invoked after a stable release ships. Four-step workflow: (1) fetch latest stable version from releases.warp.dev/channel_versions.json, parse base + display date; (2) check src/content/docs/changelog/{year}.mdx for existing entry, skip if present; (3) fetch changelog data from warpdotdev/channel-versions repo via gh api, decode base64 content, extract markdown_sections (New features / Improvements / Bug fixes / Oz updates); (4) fallback path — fetch GCS-hosted changelog.json + query merged warp-internal PRs for bug fixes if channel-versions release PR has not merged.

Dependencies:

• Sibling skill create_pr for PR creation discipline.
• External release feed https://releases.warp.dev/channel_versions.json (Warp’s release infrastructure — Warp-specific).
• gh api for cross-repo content fetching.
• python3 for JSON parsing.
• The warpdotdev/channel-versions repo as the authoritative changelog source.
• warpdotdev/warp-internal for fallback PR-mining.

KH portability notes:

• High Warp-specificity. This is the most Warp-specific of the six. KH has no equivalent release cadence; the “changelog” surface on KH is docs/reference/state-of-the-product.md + the roadmap JSON + the session continuation prompts in docs/continuation-prompts/.
• The portable pattern is the workflow shape: scheduled fetch → check if already documented → fetch structured data from authoritative source → format → open PR. KH analogue could be: scheduled fetch of docs/reference/product-roadmap.json changes since last release tag → format into a per-session retrospective doc → commit. But this is a NEW skill, not a port.
• The fallback-cascade pattern (primary source → GCS file → PR-mining) is a generally-useful pattern for any “release notes” feature, including a future KH “Change Reports” surface.
• Recommended port name: defer. This skill is closer to “reference pattern” than “verbatim port”. A KH equivalent would more usefully be authored from scratch against KH’s release-tracking primitives (which currently are minimal — see OQ 3).

1.3 sync-error-docs (5.6 KB)

Frontmatter:

name: sync-error-docs
description: >-
  Detect new platform error codes in warp-server that are missing
  documentation pages in the docs repo. Creates doc pages, astro.config.mjs
  (sidebar config) entries, and redirects for any gaps. Use on a weekly
  schedule or when error codes change.

Trigger conditions: Scheduled weekly OR triggered manually when error codes change. Eight-step workflow: (1) grep 'ErrorCode = "' against warp-server/logic/ai/ambient_agents/platformerrors/platformerrors.go to extract canonical error codes; (2) list existing docs/src/content/docs/reference/api-and-sdk/troubleshooting/errors/*.mdx; (3) diff to find missing pages; (4) read each missing error’s Go source (doc comment + FromError() + constructor) to populate the doc-page template; (5) update astro.config.mjs sidebar; (6) add vercel.json redirect from underscore-form to hyphen-form; (7) create site-level redirect via legacy docs_redirects.py (GitBook leftover); (8) commit + open PR.

Dependencies:

• Sibling references/error-page-template.md (Warp-internal template).
• warpdotdev/warp-server repo for the Go source of truth.
• docs/scripts/docs_redirects.py + GITBOOK_TOKEN env (Warp-specific, GitBook legacy).
• git, grep, basic shell.

KH portability notes:

• Pattern is highly portable; specific contents are not. KH has analogous “live source vs docs” pairs that drift constantly:
  • supabase/types/database.types.ts (auto-generated) vs docs/reference/SCHEMA-QUICK-REFERENCE.md.
  • MCP tool/resource/prompt registrations in lib/mcp/ vs docs/generated/mcp-inventory.md.
  • Migrations in supabase/migrations/ vs docs/reference/documentation-inventory.md.
  • Routes in app/ vs any future API reference page.
• Each KH analogue would be a separate KH-specific sync skill: sync-schema-docs, sync-mcp-docs, sync-route-docs. The sync-error-docs SKILL.md is the template for what each looks like (audit → fill missing → update sidebar → add redirect → PR).
• The redirect dual-step (vercel.json Astro redirect + site-level GitBook redirect via custom Python script) is Warp-specific (GitBook legacy). KH’s port only needs the vercel.json step — no legacy GitBook to bridge.
• Recommended port: extract sync-error-docs SKILL.md as a reusable scaffold; rename to sync-source-docs (or three sibling skills, one per source); replace platformerrors.go references with KH-specific source paths.

1.4 missing_docs (4.3 KB — has references/ + scripts/ subdirectories)

Frontmatter:

name: missing_docs
description: >-
  Find and fill documentation gaps in Warp's Astro Starlight docs by auditing
  coverage against code surfaces in warp-internal and warp-server, then
  drafting missing pages. Use when asked to find missing docs, audit
  documentation coverage, identify undocumented features, draft docs for new
  features, or do a docs coverage check. Runs a Python audit script to
  identify gaps, then researches source code and writes first-pass doc pages.
  Can run audit-only, draft-only, or end-to-end.

Trigger conditions: Two phases, each independently triggerable: Phase 1 audit (“run a docs audit”), Phase 2 draft (“draft docs for X”), or both end-to-end (“find and fix missing docs”). Phase 1 runs python3 .agents/skills/missing_docs/scripts/audit_docs.py with four sub-audits: feature flags (compared against warp_core/src/features.rs + app/Cargo.toml), CLI commands (against warp_cli/src/lib.rs), API endpoints (against router/router.go + OpenAPI spec), docs staleness (terminology drift). Phase 2 reads references/feature_surface_map.md to determine the target docs section + reads 2-3 strong examples for formatting, then drafts.

Dependencies:

• Sibling references/feature_surface_map.md (curated flag/command → doc mapping; also lists internal-only flags to ignore).
• Sibling references/stale_terms.md (deprecated terminology to flag).
• Sibling scripts/audit_docs.py (Python audit driver).
• warpdotdev/warp-internal and warpdotdev/warp-server sibling clones.
• Repo-root AGENTS.md as the style guide.

KH portability notes:

• Most ambitious of the six. This is the “find unknown unknowns” surface — much harder than syncing one source.
• KH analogue: audit against lib/mcp/tools/, lib/mcp/resources/, lib/mcp/prompts/, route definitions in app/, MCP registrations vs docs/generated/mcp-inventory.md; against migrations in supabase/migrations/ vs schema docs; against environment variables in .env.example vs docs/runbooks/local-development.md.
• The two-phase shape (audit script outputs JSON → human picks gaps → draft per gap) is portable verbatim.
• The “research the source code + draft against style guide” Phase-2 pattern composes with KH’s existing skill chain (ccc + gitnexus_context + write-product-spec / write-tech-spec if the missing doc is spec-shaped).
• Recommended port: missing-docs (kebab-case for KH convention). KH version would need KH-specific references/kh_surface_map.md and a new audit script targeting KH inputs.

1.5 check_for_broken_links (mid-size, has check_links.py script)

Frontmatter:

name: check_for_broken_links
description: Check the Warp Astro Starlight documentation for broken links by
  scanning source markdown files. Run the diagnostic script, review the
  output, fix broken links, and optionally notify Slack.

Trigger conditions: Scheduled OR pre-PR-merge OR ad-hoc. Runs python3 .warp/skills/check_for_broken_links/check_links.py against src/content/docs/**/*.md and **.mdx. Options: --internal-only (fast, no HTTP), --external-only, --timeout, --output JSON_FILE, --slack-notify (requires SLACK_BOT_TOKEN + SLACK_CHANNEL_ID).

Output sections: scanned files count, internal links checked, external links checked, broken count. Each broken link includes source file + line, link text, error type, suggested replacement.

Five error types handled in the workflow narrative: (1) file-not-found, (2) case-mismatch (Astro is case-sensitive), (3) missing .mdx extension on directory link, (4) cross-space link (relative paths don’t traverse Starlight “spaces” — must use absolute URLs), (5) HTTP 4xx/timeout for external links.

Dependencies:

• scripts/check_links.py (Python — uses requests for external HTTP, file-system walk for internal).
• Optional Slack tokens for --slack-notify mode.
• Astro Starlight content-collection structure (src/content/docs/<space>/...).

KH portability notes:

• Most directly portable of the six. The Python script logic is generic: walk markdown tree, parse links, validate against filesystem + HTTP.
• Astro’s “spaces” concept (per Warp: warp/, agent-platform/, support-and-community/, reference/) maps onto KH’s planned IA top-level groupings (TBD at {9.2} PRODUCT — see §3 for current state).
• Slack notify is optional; KH would likely skip (no current KH Slack workflow integration) or replace with a gh pr comment post.
• Pairs naturally with review-docs-pr (which calls the script internally per §1.1).
• Recommended port: check-for-broken-links (kebab-case). Underscore-named original check_for_broken_links can be aliased.

1.6 docs-seo-audit (largest of the six in narrative; has scripts/ + references/)

Frontmatter:

name: docs-seo-audit
description: >-
  Audit docs.warp.dev for SEO issues like duplicate titles, missing meta
  descriptions, title length problems, and H1 tag issues. Crawls the live
  sitemap, generates a report, and fixes issues in the source files. Use when
  asked to check SEO, fix duplicate titles, audit meta tags, improve search
  rankings, or run an SEO check on the docs site.

Trigger conditions: Ad-hoc or scheduled. Runs python3 .agents/skills/docs-seo-audit/scripts/seo_audit.py --repo-root . --output /tmp/seo-report.json against the live docs.warp.dev/sitemap-index.xml. Identifies 11+ issue types across three severity tiers:

• Errors (must fix): duplicate_title, missing_title, fetch_error.
• Warnings (should fix): duplicate_description, missing_description, title_too_short (<20 chars), title_too_long (>70 chars), missing_h1, multiple_h1.
• Info (nice to fix): description_too_short (<50), description_too_long (>160), og_title_mismatch, og_description_mismatch.

Workflow: (1) run script, (2) report back to user grouped by severity with example offenders, (3) ASK which issues to fix before changing files, (4) fix via frontmatter edits (title + description) OR sidebar config edits in src/sidebar.ts (Starlight derives title tags from sidebar config labels unless the page sets explicit frontmatter title).

Dependencies:

• Sibling scripts/seo_audit.py (Python — crawls live sitemap-index, parses HTML, checks SEO metadata).
• Sibling references/starlight-seo.md (non-obvious Starlight title-tag derivation rules).
• Repo-root AGENTS.md for style/voice/terminology authoritativeness.
• Live site at docs.warp.dev (so requires the site to be deployed).

KH portability notes:

• Mid-portability. Issue catalogue (duplicate titles, missing meta descriptions, title length) is generic SEO; the script logic is portable.
• The reliance on a LIVE site means KH must have deployed first before this skill can run usefully — chronologically last of the six.
• The “ASK before fixing” guardrail is a worthwhile pattern to preserve verbatim — it prevents mass-rewrites without human review.
• Recommended port: docs-seo-audit (verbatim kebab-case). Defer until the docs site is live (post-Phase-1 docubot foundation).

1.7 Cross-cutting observations

• All six are Python-scripted + skill-described. The SKILL.md is the workflow narrative; the actual auditing/syncing/fixing logic is Python at <skill>/scripts/*.py. This shape lets the agent reason about the workflow without re-implementing Python in TS/Bun.
• Five of six depend on AGENTS.md at the docs repo root. KH has no equivalent file. Authoring a KH AGENTS.md (style guide + terminology + voice rules) is a prerequisite for porting at least review-docs-pr + missing_docs + docs-seo-audit with high fidelity. Surfaced as OQ 1 below.
• Two of six (sync-error-docs, update-changelog) depend on a sibling source repo (Warp’s warp-internal, warp-server, channel-versions). KH’s equivalent is single-repo for the foreseeable future (docs/ lives in the same repo as app/ and lib/), which simplifies the port — no cross-repo gh api calls needed.
• All six are PR/branch-flow integrated. Each emits a PR rather than committing directly; this matches KH’s existing commit-commands:commit-push-pr discipline.
• None of the six handle the actual base sync from in-repo markdown to Starlight content collection. That responsibility lives at the build-pipeline layer (Warp’s astro.config.mjs + their sync from src/content/docs/ which IS their authoring root). KH’s stale TECH.md proposes a manifest-driven sync script (docs-site/scripts/sync-content.ts) — this base layer is still needed; docubot + the six skills are additive maintenance surfaces.

---

§2 Warp docubot mechanism

The docubot is the base PR-driven docs-update bot that opens follow-up doc PRs when source-code PRs merge. Distinct from the six maintenance skills (which run scheduled or ad-hoc against the docs repo); docubot runs against the SOURCE repo and pushes changes into the DOCS repo.

2.1 Trigger conditions

Source: /Users/liamj/Documents/development/warp/.github/workflows/docubot_reply_to_comment.yml (line counts: 70 total).

Trigger surface as committed:

• workflow_dispatch with four inputs: pr_number (optional), prompt (required, default: “Analyze this PR for documentation needs”), warp_channel (choice: dev / preview / stable, default dev), profile_id (optional Warp profile ID).
• issue_comment + pull_request_review_comment triggers are commented out (lines 6-9). Inline comment in the YAML: “These triggers are currently disabled because they cause workflow runs for ALL comments in the org, even though the job only executes when @docubot is mentioned, which is noisy.”

Job gating:

if: >
  (
    contains(github.event.comment.body, '@docubot') || inputs.prompt
  )
  && github.actor != 'github-actions[bot]'

The mention-based gate is preserved in code even though the comment triggers are off — Warp evidently plans to re-enable once the noise is addressed. Lesson for KH: wire only workflow_dispatch + pull_request.types: [closed] filtered to merged == true (per the assessment’s §8 Phase 1 plan). Skip issue_comment to avoid the same noise problem.

Permissions block: contents: write, issues: write, pull-requests: write, id-token: write, actions: read.

Runner: namespace-profile-ubuntu-20-04 (Warp’s custom runner; KH would use ubuntu-latest or whatever standard runner the ci.yml uses).

2.2 Composite action structure

Source: /Users/liamj/Documents/development/warp/.github/actions/docubot/action.yml (171 lines).

Inputs:

inputs:
  prompt: { required: true }
  warp_api_key: { required: true }
  warp_channel: { default: 'dev' }
  profile_id: { required: false }
  github_token: { required: false } # used to clone the private docs repo

Steps (in order):

1. Setup Warp CLI — uses: ./.github/actions/setup_warp_cli with warp_channel input. Installs warp-cli{-dev|-preview|} binary.
2. Clone Warp GitBook repository — actions/checkout@v6 against repository: warpdotdev/gitbook, target path: gitbook, auth via github_token. (Note: post-Astro pivot, Warp now uses warpdotdev/docs instead, but the action file still says warpdotdev/gitbook — this is a snapshot of pre-pivot state; the action would have been updated post-pivot in their fork.)
3. Create prompt file — Renders prompt.txt via envsubst < .github/actions/docubot/prompt.txt > prompt.output.txt. The envsubst step exports an extensive set of GitHub context variables (lines 38-117), including:
   • Repository context (owner, ID, URL).
   • Event context (name, action, path).
   • Actor context (login, ID).
   • Git context (ref, SHA, base/head refs).
   • PR/issue context (title, body, number, URL, author login, assignees, labels — fallback chained between github.event.issue.* and github.event.pull_request.*).
   • PR-specific (head SHA/ref/repo, base SHA/ref/repo, draft flag, merged flag, mergeable state, commits/additions/deletions/changed-files counts).
   • Issue-specific (closed_at, milestone).
   • Comment context (body, user, timestamps, URL).
   • GITBOOK_PATH = ${{ github.workspace }}/gitbook — the path where the docs repo was checked out.
4. Configure git identity — git config user.name "Warp Agent" + user.email "agent@warp.dev".
5. Run Warp agent — Invokes warp-cli-{channel-suffix} agent run --prompt "$(cat prompt.output.txt)" --api-key "$WARP_API_KEY" --cwd "$GITHUB_WORKSPACE" --profile "$PROFILE_ID".
6. Upload Warp logs (always) — actions/upload-artifact@v4 from /home/runner/.local/state/warp-terminal-dev/warp_dev.log (Warp-CLI’s own log path).
7. Upload Warp prompt (always) — Uploads the rendered prompt.output.txt for debugging.

2.3 The envsubst’d prompt template

Source: /Users/liamj/Documents/development/warp/.github/actions/docubot/prompt.txt (79 lines).

Structure (verbatim shape, with substituted variables wrapped in XML-style tags for clarity):

You are Warp, the world's best AI coding assistant for helping with GitHub
PRs and issues. Here is the context for your current task:

<pr_or_issue_title>$PR_OR_ISSUE_TITLE</pr_or_issue_title>
<pr_or_issue_body>$PR_OR_ISSUE_BODY</pr_or_issue_body>
<pr_or_issue_url>$PR_OR_ISSUE_URL</pr_or_issue_url>
<changed_files>$PR_CHANGED_FILES</changed_files>
<trigger_comment>$COMMENT_USER_LOGIN: $COMMENT_BODY</trigger_comment>

Your persona: You are **docubot**, living inside Warp's internal codebase.
When triggered, you read the context of the invoking PR and update Warp's
documentation repo (`https://github.com/warpdotdev/gitbook`). The GitBook
repository is already available locally at `$GITBOOK_PATH` — you have
direct access to it and should use it without attempting to clone it again.
The repo is organized into Markdown files and assets. Your job is to
create a new branch, apply accurate documentation changes, and open a
well-scoped PR with a high-quality description. You need to post the link
to the PR to the original PR in Warp-internal where the changes were made.

Key rules:
- Truth first: Only document behavior present in the PR or linked issues.
  Add `<!-- TODO -->` if something is unclear.
- Scope: Update only affected pages plus any directly impacted references.
- Consistency: Match existing style, tone, and structure in GitBook.
- Assets: Place images in `.gitbook/assets/`, use kebab-case names, add alt
  text.
- Privacy: No secrets, tokens, or internal data.
- Cross-linking: Update or add links between related sections.

Commit & PR conventions:
- Branch name: `docubot/<short-slug-from-invoking-pr-title>`
- Commit message style: `docs(area): concise summary of change`
- PR title: `Docs: <concise summary> (from <repo>#<PR>)`
- PR description: must include Summary, Pages/sections updated, Why.

IMPORTANT OUTPUT INSTRUCTIONS:
- You are only allowed to leave ONE comment on the source PR. Do so at the
  end of your run.
- Push the local branch with `-u` before creating the PR.
- Comment must either: (1) Provide PR summary + next steps OR
  (2) Explain blockers/clarifications needed.

ADDITIONAL WORKFLOW REQUIREMENTS:
- After creating GitBook PR: comment on the original warp-internal PR to
  (1) provide GitBook PR link, (2) tag original author as reviewer,
  (3) include summary of what was updated.
- Comment format template included (with @author tag).

2.4 Claude integration — the chosen substitute for warp-cli agent run

Per Liam’s S46 feedback (workflow-orchestration-feedback-response.md §2.3) and the assessment §8’s three options, the preferred Claude integration is @anthropic-ai/claude-agent-sdk (TypeScript / Node), not Claude Code headless and not Anthropic API direct.

Rationale:

• Claude Code headless — install in CI, invoke claude --prompt. Less programmable; tied to Claude Code’s specific binary lifecycle.
• Claude Agent SDK (@anthropic-ai/claude-agent-sdk) — script-driven; better for parameterised prompts and CI integration. Cleanest balance between scripting + control. Native MCP integration.
• Anthropic API direct — most control, most code; manual context management; tool-calls re-implemented from scratch.

KH would script the docubot driver in TypeScript using the SDK, invoking it from the GH Action’s “Run Claude agent” step (replacing Warp’s warp-cli agent run step). The envsubst’d prompt template feeds in directly; the SDK provides the tool-loop loop + MCP server access.

2.5 Doc-only PR open mechanism

The doc-only PR is created by the agent itself within the run step, not by a separate GitHub Action. Flow:

1. Agent runs inside the source-repo’s working tree (cwd $GITHUB_WORKSPACE), with the docs repo checked out at $GITBOOK_PATH (sibling).
2. Agent reads the source PR’s changed files (via $PR_CHANGED_FILES substituted into the prompt) and decides what doc updates are needed.
3. Agent creates a branch docubot/<slug> in the docs repo’s worktree (cd $GITBOOK_PATH; git checkout -b docubot/...).
4. Agent edits, commits with docs(area): summary message, pushes with -u origin.
5. Agent opens the docs PR via gh pr create (CLI, in the docs-repo cwd) with Docs: <summary> (from <repo>#<PR>) title and the Summary/Updated/Why body template.
6. Agent switches to the source repo cwd and runs gh pr comment $PR_NUMBER --body "..." to back-link, tag the original author as reviewer, summarise what was updated.
7. Single-comment guardrail enforced via prompt rule.

The agent is doing all branch/commit/push/PR/comment work via shell tool calls; no extra GH-Action peter-evans/create-pull-request style helper. This is intentional — agent autonomy is preserved end-to-end.

2.6 Phase 2 future-state: composable with the six maintenance skills

The docubot foundation (this section) is Phase 1. Phase 2 (per assessment §8 / feedback §2.3) layers the six skills atop the docubot infrastructure:

• review-docs-pr runs ON the docubot-opened docs PR (a second auto-review pass on the bot’s output).
• update-changelog runs scheduled (post-release).
• sync-error-docs runs scheduled (weekly).
• missing_docs runs scheduled (monthly?) OR ad-hoc.
• check_for_broken_links runs scheduled (daily?) AND inside review-docs-pr.
• docs-seo-audit runs scheduled (monthly?) post-deploy.

Each becomes a .github/workflows/<name>.yml matching docubot.yml’s shape, invoking the Claude Agent SDK with the relevant skill loaded.

---

§3 Current KH docs/ IA audit (HEAD 3e4ee5c2)

The current state at HEAD 3e4ee5c2d (commit docs: draft session 58 continuation prompt, 2026-05-20). The S57 archival sweep (commit 4592cc5c and predecessors) relocated significant content to .planning/.archive/.{audits,specs,research,continuation-prompts}/ — so the IA the stale specs assumed is materially smaller than what the stale TECH.md (15/05) inspected.

3.1 docs/ subdirectory inventory at HEAD 3e4ee5c2

Sixteen subdirectories under docs/ (depth-1):

Subdir	.md count	Nested-dirs	Classification	Notes
audits/	20	4	internal-only	Historical audit reports; mostly point-in-time. Candidate to archive further per .planning pattern.
client-briefs/	8	1	internal-only	Pre-product positioning for Phew client work. Not for public docs site.
client-documentation-corpus/	24	0	internal-only	Test fixtures for ingestion pipelines. Not docs.
continuation-prompts/	75	1	internal-only	Session handoff prompts. Internal workflow artefact — not docs-site material.
design/	3	1	public-docs-site candidate	warm-meridian-implementation-spec.md, warm-meridian-philosophy.md, identity PDF. Reference material.
generated/	3	1	public-docs-site candidate (conditional)	codebase-stats.md, mcp-inventory.md, etc — generated; would need build-time regeneration before publishing.
handover-guides/	1	1	mixed	One file. Status unclear.
ontology/	32	1	public-docs-site candidate	Ontology + taxonomy spec content. Critical reference material.
operations/	8	1	mixed	Likely contains a mix of public-facing operational docs + internal-only.
plans/	123	5	mostly-internal	Phase-0/1/2 investigation docs + active plans. Largely internal but some plans are publishable.
product-functionality/	27	9	public-docs-site candidate	Per-feature behavioural docs; the primary user-product surface.
reference/	29	1	public-docs-site candidate (canonical front door)	Schema, AI policy, skill routing, state-of-the-product, taxonomies, roadmap JSON, backlog JSON.
research/	13	2	internal-only	Research artefacts (this file goes here).
runbooks/	12	1	public-docs-site candidate (canonical front door)	Operational playbooks: CI, local dev, staging refresh, deployments, GitHub Environments.
specs/	91	29	mixed	PRODUCT.md / TECH.md pairs; some shippable, many in-flight. Curation manifest needed.
testing/	9	9	internal-only	Test plans, test philosophy. Test philosophy itself is a public-docs candidate.

Total live docs/**/*.md count: 478 files across 67 directories.

3.2 Archive cross-reference (.planning/.archive/)

The archived counterpart at .planning/.archive/ holds the S57-evacuated content:

Archive subdir	files	Notes
.audits/	333	Old audit reports (much larger than live docs/audits/’s 20 files).
.continuation-prompts/	239	Historical session prompts (live docs/continuation-prompts/ has 75).
.specs/	319	Old specs (live docs/specs/ has 91 across 29 dirs — many are still ratified).
.research/	75	Old research docs (live docs/research/ has 13).
.tracks/	2	Decommissioned track snapshots (per CLAUDE.md’s note on the kh-knowledge-platform archive).
.client-briefs/	0	(Empty — perhaps moved-out or never populated.)
.plans/	0	(Empty — live docs/plans/ still has 123 files. S57 did not evacuate plans.)

Implication for {9.2} PRODUCT.md author: the IA the stale specs imagined (broad span across docs/audits/**, docs/specs/**, docs/plans/**, docs/research/**) is now substantially narrower in scope. Stale-spec assumptions like “publish curated specs from docs/specs/wp6-ontology-harness/” (TECH.md §“Open questions” Q3) need re-verification against the live tree — wp6-ontology-harness may have been archived (it’s not in docs/specs/ at HEAD, suggesting it was either renamed, deferred, or archived).

3.3 Canonical “front door” candidates for the public docs site

Based on the classifications above, the high-priority publish-set is:

1. docs/reference/ (29 files) — canonical schema, AI policy, skill routing, state-of-the-product, taxonomies. The primary front door for AI-development reference material. Likely the home page or top sidebar group.
2. docs/runbooks/ (12 files) — CI, local dev, staging refresh, deployments. The primary front door for operational tasks.
3. docs/ontology/ (32 files) — ontology / taxonomy / cardinality specs. The primary front door for data-model understanding.
4. docs/product-functionality/ (27 files) — per-feature behaviour reference. The primary front door for “what does Knowledge Hub do?”
5. docs/design/ (3 files) — Warm Meridian spec, philosophy, identity. The primary front door for design-system reference.

Conditional / curate-by-manifest:

6. docs/specs/<id>/ (91 files / 29 dirs) — only the ratified, shippable specs publish. The manifest pattern in stale TECH.md §5 is correct in spirit; needs updating to reflect actual ratified spec list.
7. docs/generated/ (3 files) — codebase-stats.md, mcp-inventory.md, etc. Publish IF build-time regeneration is wired into docubot.yml / ci.yml.
8. docs/testing/test-philosophy.md — single file from a mostly-internal directory; should be promoted to docs/reference/test-philosophy.md (it’s referenced from CLAUDE.md as canonical) OR included via explicit manifest entry.
9. docs/operations/ (8 files) — review which are public-facing vs internal-only.

Excluded by IA design:

• docs/audits/, docs/continuation-prompts/, docs/research/, docs/handover-guides/, docs/client-briefs/, docs/client-documentation-corpus/, docs/plans/, docs/testing/ (excluding test-philosophy.md).

3.4 Mapping to Warp’s “spaces” concept

Warp Starlight uses four top-level “spaces” per check_for_broken_links SKILL.md §“Cross-space links”: warp/, agent-platform/, support-and-community/, reference/. Spaces drive src/content/docs/<space>/ directory layout and have implications for cross-link rules (relative paths don’t traverse spaces).

KH-natural mapping (proposed; for {9.2} PRODUCT to ratify):

KH space	Sources	Purpose
platform/	docs/product-functionality/, docs/ontology/, selected docs/specs/	”What KH does” — feature reference
reference/	docs/reference/, docs/design/, docs/generated/	”Authoritative facts” — canonical references
runbooks/	docs/runbooks/, selected docs/operations/	”How to do operational tasks”
decisions/	curated docs/specs/ (ratified architectural decisions)	“Why we chose X” — ADR-style ratified specs

Four spaces vs Warp’s four — clean. This is a starting suggestion only; {9.2} PRODUCT is the source of truth for the final IA.

---

§4 Delta audit vs stale Astro+Starlight specs

The DRAFT specs at docs/specs/id-9-astro-starlight-docs-foundation/{PRODUCT.md,TECH.md} (15/05/2026) cover roughly one-third of Task ID-9’s actual scope. This section enumerates the delta in four buckets.

4.1 What’s still valid (preserve into {9.2} PRODUCT and {9.3} TECH)

The following decisions and framings from the stale specs remain accurate and should be inherited:

1. Framework: Astro + Starlight. Confirmed by Warp’s open-sourced docs repo at github.com/warpdotdev/docs — Astro + Starlight is the reference implementation. No alternative considered.
2. Static site, no per-request rendering. @astrojs/vercel/static adapter. Pagefind search (offline-capable, built-in). Stable.
3. Theming: Warm Meridian via CSS custom property mirroring. Token vocabulary documented in stale TECH.md §6 (lines 351-409). Specifically: mirror app/globals.css tokens into docs-site/src/styles/warm-meridian.css, override Starlight’s --sl-color-* variables, support light + dark mode via Starlight’s data-theme attribute.
4. Sibling docs-site/ directory inside KH repo. Confirmed in stale TECH.md §“Open questions” Q2 resolution (line 582-585): “Markdown source-of-truth stays at docs/; Astro project root + content collection + sync script live at docs-site/. Mirrors Warp’s separation.”
5. Sibling Vercel project knowledge-hub-docs. Confirmed at Q1 resolution (line 578-581): independent deploy boundary, independent rollback cadence.
6. Build-time CI gate. Loud failure on malformed front matter, broken internal link, removed referenced page, manifest typo. Generic Astro + Starlight invariant.
7. Edit-this-page-on-GitHub link pointing at the canonical source on main. Built-in Starlight via editLink.baseUrl. Useful for “AI is invisible infrastructure” — readers always know where the markdown lives.
8. Front-matter discipline: minimal + Zod-validated. Stale TECH.md §4 (lines 213-247) — title, optional description, sidebar order/label, optional lastUpdated, KH-specific kh_source + kh_last_verified. Sound.
9. Behaviour invariants 7, 8, 12, 15, 16 (accessibility, branding, last-updated honesty, AI-invisibility, UK English). All carry forward unchanged.
10. Invariant 18 — “auto-sync from main-track content is not a user concern”. The principle is right; what changes is the IMPLEMENTATION (Phase 1 docubot + Phase 2 the six skills, not just a manifest-driven sync script).
11. Domain resolution at TECH Q4 (line 595-603): docs site is internal-team-facing (KH platform team), NOT under kh.phew.org.uk. Uses pre-Phew Vercel default subdomain (string TBC at deploy time). This reframing is correct and should be inherited; the corresponding “Audiences” reframe (drop “future external users”) at PRODUCT Q4 follow-up is owed.

4.2 What’s now stale (replace or refresh in {9.2} PRODUCT and {9.3} TECH)

The following decisions in the stale specs are outdated:

1. First content-sync target. Stale TECH.md Q3 (line 587-594): content-types-and-cardinality.md from docs/specs/wp6-ontology-harness/. At HEAD 3e4ee5c2, docs/specs/wp6-ontology-harness/ does not exist — likely archived or renamed during S57. Stale. Replace with a verified-extant target (candidates: any of the canonical docs/reference/ files, or a ratified docs/specs/<id>/ directory at HEAD).
2. The “publish a curated set of paths” mental model. Stale spec assumes a small manifest with a few canonical entries. The actual scope per §3 is 5+ canonical front-door directories totaling ~100+ files (29 in docs/reference/, 12 in docs/runbooks/, 32 in docs/ontology/, 27 in docs/product-functionality/, 3 in docs/design/). Stale. The manifest-driven sync pattern is right, but the manifest itself needs to be much larger (or the model needs to flip: include-by-default for canonical front-door directories, exclude by explicit deny-list — more scalable).
3. PRODUCT.md “Audiences” § (lines 21-35): lists “future external users” (UK SMBs) as audience 3. Already known-stale per TECH Q4 follow-up edits (line 609-616). Stale. Drop external-user framing; replace with platform-team-internal audiences (Liam, AI dev partner, future internal contributors).
4. Stale spec’s silence on Warp’s six skills. The skills are absent — only the foundation site is covered. Missing rather than wrong, but the stale specs imply the foundation IS the destination.
5. The stale TECH.md’s content-collection schema (§4, lines 213-247) is minimal but does not anticipate space-prefix structure (the four-space proposal in §3.4 above) that comes from porting Warp’s IA convention. Stale by omission.
6. The stale TECH.md’s scripts/sync-content.ts design (§5, lines 266-342) treats sync as a build-step transform from ../docs into ./src/content/docs. Post-Phase-1 docubot port, the dominant sync path becomes PR-merge-triggered (docubot opens a docs PR) rather than build-time only. The build-time sync still exists as a fallback / dev-loop primitive, but is no longer the only sync mechanism. Architecture stale.
7. The stale TECH.md’s vercel.json reference to docs.kh.phew.org.uk (line 148, line 622-624). Stale per Q4 reframing — domain confirmed NOT to be under the Phew client surface.
8. Invariant 21 (“Cross-link to Knowledge Hub app stays explicit”): refers to the running app at https://www.kh.phew.org.uk. This is correct for cross-links to the APP itself, but the DOCS site domain framing in surrounding text is wrong (per stale Q4). Partially stale.
9. The stale TECH.md’s “Cross-worktree / cross-repo source” subsection (§5 / lines 326-342) describes fetching content from a sibling main-track clone. Post-S58 worktree-isolation work + the single production-readiness long-lived worktree assumption: partially stale — the cross-worktree concern is now narrower (the docs site is built from main; long-lived worktrees merge in via the normal git merge path).

4.3 What’s missing entirely (author from scratch in {9.2} PRODUCT and {9.3} TECH)

The bulk of Task ID-9’s scope. Six missing topic areas:

4.3.1 Warp docubot port

• Composite action at .github/actions/docubot/action.yml adapted from Warp’s. Steps documented in §2.2.
• Workflow trigger at .github/workflows/docubot.yml — workflow_dispatch + pull_request.types: [closed] filtered to merged == true. Skip issue_comment triggers (Warp’s lesson learned).
• Prompt template at .github/actions/docubot/prompt.txt — KH-adapted from Warp’s 79-line template per §2.3. Replace Warp persona / GitBook references with KH persona / KH docs/ tree references. Reuse commit-conventions, PR-conventions, single-comment guardrail.
• Claude integration via @anthropic-ai/claude-agent-sdk (per §2.4 / Liam’s stated preference). NOT Claude Code headless, NOT raw API.
• Authentication. ${{ secrets.GITHUB_TOKEN }} for same-repo docs-PR; ${{ secrets.ANTHROPIC_API_KEY }} for the SDK.
• Loaded skill: keep-docs-in-sync (extend update-docs or author fresh) — the in-prompt-context skill that encodes KH conventions for the docubot to follow. This skill is the analogue of Warp’s AGENTS.md style guide.

4.3.2 Six docs skills, KH-adapted

Per §1, each requires a port + KH-specific adaptation. Phase 1 priority order (per assessment §9 takeaway 2): review-docs-pr, sync-error-docs analogue (likely renamed sync-source-docs or split into sync-schema-docs / sync-mcp-docs / sync-route-docs), check_for_broken_links. Phase 2: missing_docs (large; needs references/kh_surface_map.md), update-changelog (high Warp-specificity; KH equivalent likely a different shape), docs-seo-audit (chronologically last; needs live site).

Each ports as: .claude/skills/<skill-name>/SKILL.md + (where applicable) .claude/skills/<skill-name>/scripts/*.py + (where applicable) .claude/skills/<skill-name>/references/*.md.

4.3.3 /update-docs decommission

Per the assessment’s “redundancy survival assessment” (§11) and the feedback’s response (line 76-80): /update-docs currently does four things:

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

Post-docubot decommission plan:

• (a) + (b) + (d) → handled by docubot on PR merge (narrative-doc updates).
• (c) → moves into ci.yml as a merge to main CI step (generated-from-code; needs to remain a build step).
• The auto-chain to /handoff behaviour of /update-docs → keeps via /handoff as a session-scoped continuation-prompt generator (independent of docs-site concerns).

Decommission ordering (must be in the PRODUCT.md acceptance):

1. Ship docubot foundation + base Astro+Starlight site.
2. Verify docubot on a sample PR end-to-end.
3. Wire (c) generation into ci.yml.
4. Remove .claude/skills/update-docs/ (and any callers).
5. Update CLAUDE.md to remove /update-docs reference; add docubot reference.

4.3.4 keep-docs-in-sync (or extended update-docs) skill

The in-prompt-context skill the docubot loads. Encodes:

• KH docs/ IA conventions (per §3 above).
• The Warm Meridian palette + typography rules (per docs/design/warm-meridian-implementation-spec.md).
• The AI-invisibility policy (per docs/reference/ai-visibility-policy.md).
• UK English requirements.
• The docs/reference/documentation-inventory.md index (so docubot doesn’t recreate existing docs).
• Commit-conventions + PR-conventions (matching KH’s commit-commands:commit-push-pr patterns).
• Same single-comment guardrail Warp uses.

4.3.5 KH AGENTS.md

Per §1.7, five of the six Warp skills depend on a repo-root AGENTS.md as the canonical style guide. KH does not have one. The pattern is generally useful — it’s an LLM-discoverable style guide (the agent reads it via the prompt’s “Available context” block).

KH equivalent would contain:

• Voice + tone rules (UK English, professional-direct, no marketing copy).
• Terminology table (Knowledge Hub vs “the platform” vs “the app”; “Change Reports” vs “Digest”; canonical taxonomy terms).
• Frontmatter contract (matching Zod schema in TECH).
• Content-type style guides (concept docs, procedural docs, reference docs, troubleshooting docs).
• AI-invisibility rules (no Sparkles icons, no “AI-powered” badges).

This is a substantial side-output — likely a full PRODUCT.md / TECH.md pair on its own. Could be authored as part of {9.5+} Subtask in this Task, or carved off as its own Task.

4.3.6 Auto-sync content contract

The stale TECH.md’s manifest-driven sync (docs-site/scripts/sync-content.ts + sync-manifest.json) needs to be replaced with a hybrid:

• Build-time sync (for dev-loop + first-build): include-by-default the five canonical front-door directories; exclude by explicit deny-list.
• PR-merge sync (docubot): docubot writes directly to docs-site/src/content/docs/ in the docs-PR it opens; no separate sync script run.
• Schema-driven sync (sync-error-docs-style for KH-specific sources): driven by sync-schema-docs / sync-mcp-docs / sync-route-docs skills against supabase/types/database.types.ts, MCP registrations, route handlers.

4.4 What needs PRODUCT-level reratification at {9.2}

Specific invariants from stale PRODUCT.md that need explicit refresh:

Stale invariant	Refresh needed
1 (audiences)	Drop “future external users”. Three audiences: Liam, AI dev partner (Claude), future internal contributors.
3 (curation)	Flip model: include-by-default canonical directories, exclude by deny-list. Manifest becomes overrides + additions only.
4 (IA mirrors product domains)	Ratify the four-space proposal (or alternative): platform/ / reference/ / runbooks/ / decisions/.
6 (search)	Confirm Pagefind unchanged. Add: full-corpus search includes platform + reference + runbooks + decisions spaces.
8 (Warm Meridian)	Confirm: identity assets at docs/design/warm-meridian-identity.pdf are the source. Defer logo + favicon until ratification.
10 (internal links)	Confirm Starlight link validator + manifest pre-flight catch both same-space and cross-space link breakage.
17 (404/empty)	Add: 404 page references the KH platform team domain (not Phew client surface).
18 (auto-sync)	Most stale. Rewrite to cover the hybrid sync (build + docubot + schema-driven) per §4.3.6.
21 (cross-link)	Confirm: https://www.kh.phew.org.uk for app references (production); add docs-domain framing once Q4 string lands.

New invariants to add at {9.2}:

• N-new-1 (docubot autonomy): When a source-code PR merges, docubot SHALL open a follow-up docs PR within X minutes (target: 15 min) with proposed changes. If no docs change is warranted, docubot SHALL comment on the source PR confirming “no doc changes needed” with reasoning.
• N-new-2 (docubot single-comment): docubot SHALL post exactly ONE comment on the source PR per run (Warp’s lesson).
• N-new-3 (six skills lifecycle): Each of the six ported skills SHALL be triggerable independently via workflow_dispatch AND on its appropriate schedule.
• N-new-4 (decommission): .claude/skills/update-docs/ SHALL be removed once (a) + (b) + (d) of its current behaviours are demonstrably handled by docubot, and (c) is handled by ci.yml. The CLAUDE.md reference SHALL be updated atomically.
• N-new-5 (AGENTS.md): A AGENTS.md at repo root SHALL exist, containing voice, terminology, frontmatter, content-type, and AI-invisibility rules. All six docs skills SHALL load it.
• N-new-6 (keep-docs-in-sync): A .claude/skills/keep-docs-in-sync/SKILL.md SHALL exist, loaded by docubot in its prompt. Encodes KH conventions verbatim from AGENTS.md + the docs-tree IA from this RESEARCH §3.

---

Open Questions (≤5 ceiling per dispatch brief)

Each OQ proposes a default with rationale. Each is intended for Liam to ratify at {9.2} PRODUCT dispatch.

OQ 1 — Author KH AGENTS.md as part of Task ID-9 or carve off?

Question: Five of the six docs skills depend on a AGENTS.md repo-root style guide that KH does not have. Authoring it is a substantial deliverable (estimate: PRODUCT + TECH pair + content). Two options:

• Option A (recommended): Author within Task ID-9 as a new Subtask {9.5+}. Pro: ports of the six skills land usable. Con: bloats Task ID-9.
• Option B: Carve off as Task ID-23 (separate). Pro: keeps Task ID-9 scoped to the docubot + site foundation. Con: blocks the six-skill ports until ID-23 ships.

Default: Option A. The six-skill ports are core scope; their AGENTS.md dependency is not optional. Better to absorb the slip than to ship a half-functional six-skill set.

OQ 2 — Hybrid sync: build-time vs docubot-driven vs schema-driven priority?

Question: The stale TECH.md proposed a single build-time manifest-driven sync. Post-research, three sync mechanisms coexist:

1. Build-time include-by-default from canonical front-door directories (dev-loop primitive).
2. PR-merge docubot writes directly to docs-site content collection (PR-flow primary).
3. Schema-driven scheduled syncs (sync-schema-docs, sync-mcp-docs, sync-route-docs) for code-generated content (steady-state primary).

Which is primary?

Default: Build-time = dev-loop only. PR-merge docubot = the PRIMARY production path. Schema-driven = layered on top for code-generated content. The PRODUCT.md should make this hierarchy explicit so the Executor knows where to focus the foundation-vs-Phase-2 split.

OQ 3 — update-changelog KH equivalent: skip, author fresh, or defer?

Question: update-changelog is the most Warp-specific of the six (depends on Warp’s release infra). KH has minimal release-tracking infrastructure today. Three options:

• Skip the port; document as “Warp-specific, no KH analogue authored at this Task.”
• Author fresh a KH equivalent (e.g. update-state-of-the-product that diffs docs/reference/state-of-the-product.md against last-tagged release and proposes changes).
• Defer to a later Task when KH’s release cadence is more mature.

Default: Defer. State-of-the-product is currently maintained by /update-docs (per §4.3.3); the docubot decommission already handles narrative-doc updates. Authoring update-changelog equivalent prematurely creates a parallel surface that overlaps /update-docs decommission. Revisit when KH has tagged releases.

OQ 4 — Four-space IA proposal (platform/ / reference/ / runbooks/ / decisions/) — ratify or alternative?

Question: §3.4 proposes a four-space IA mirroring Warp’s structure. Alternatives include:

• Three spaces collapsing runbooks into reference.
• Five spaces splitting platform/ into product-functionality/ + ontology/.
• Flat (no spaces; sidebar-grouped only).

Default: Four spaces as proposed. Mirrors a known-good model (Warp’s), aligns cleanly with current KH docs/ structure, gives docubot + the six skills clear cross-link targets (the cross-space-link rules in check_for_broken_links skill assume meaningful space boundaries).

OQ 5 — Decommission ordering: Big-Bang or gradual?

Question: /update-docs decommission could be:

• Big-Bang: Ship docubot, immediately delete .claude/skills/update-docs/. Pro: clean. Con: if docubot has gaps, recovery is reverting both at once.
• Gradual: Ship docubot, keep /update-docs for 2-3 sessions of overlap, then delete. Pro: safer. Con: two paths exist, decision fatigue, risk of /update-docs drift.

Default: Gradual. Two-session overlap (one to verify docubot’s narrative-doc output is faithful, one to verify the ci.yml bun run stats integration). Hard deadline at which /update-docs is removed regardless. Documented atomically in the decommission Subtask’s acceptance criteria.

---

Findings + surprises

Documented for {9.2} Planner awareness (not requiring action here):

• The “six skills” label was approximate. The actual .agents/skills/ directory at github.com/warpdotdev/docs has 24 skills, including draft_conceptual, draft_procedural, draft_quickstart, draft_reference, draft_troubleshooting, draft_faq, draft_guide, draft_feature_doc, style_lint, sync_terminology, sync-openapi-spec, validate_ui_refs, afdocs-audit, afdocs-fix, answer_question, create_pr. Several of these are also docs-relevant (style_lint, sync_terminology, sync-openapi-spec). The brief’s six were the assessment-§8 highlight set, but a future “Phase 3 expansion” Task could revisit the other 18.
• The docubot’s underlying composite action references warpdotdev/gitbook, not warpdotdev/docs. That snapshot at /Users/liamj/Documents/development/warp/.github/actions/docubot/action.yml predates the GitBook → Astro pivot in the public docs repo. Warp’s internal docubot may have been updated separately; that update is not visible in our local Warp clone. Implication: when porting prompt.txt, the “create a new branch, apply doc changes, open a well-scoped PR” pattern is unchanged; just the repo names change.
• AGENTS.md-at-repo-root is the standard Warp convention. The Warp blog post on open-sourcing docs frames AGENTS.md as the “single source of truth that all agents read.” Adopting this convention for KH is a leverage point — it composes with any future agentic skill, not just the six docs skills.
• Cross-space link rules in check_for_broken_links explicitly call out that relative paths do NOT traverse Starlight “spaces” — only absolute URLs work cross-space. This is a hard architectural constraint that ripples back to the four-space IA proposal: every cross-space reference becomes an absolute URL.
• The docs/ tree growth pattern. 478 .md files at HEAD vs ~700+ archived in S57. The corpus is large enough that include-by-default + deny-list (per OQ 2 default) makes considerably more sense than a hand-curated allow-list.
• The wp6-ontology-harness directory absence at HEAD suggests the stale TECH.md’s “first content-sync target” (Q3) was already broken even at the time of authoring (15/05/2026) — wp6-ontology-harness may have lived in a separate worktree. Implication for {9.2} PRODUCT: the first-sync-target choice is open; pick a known-extant target (docs/reference/test-philosophy.md, docs/runbooks/local-development.md, and docs/design/warm-meridian-implementation-spec.md are all good candidates).

---

Out-of-scope (deferred to {9.2} / {9.3} / {9.4} / future Tasks)

Per the dispatch brief’s “out-of-scope for THIS Subtask” rules:

• PRODUCT.md authoring ({9.2}).
• TECH.md authoring ({9.3}).
• Subtask decomposition ({9.4}, conditional).
• Architectural decisions (surfaced as OQs above, not decided here).
• Modifications to stale specs at docs/specs/id-9-astro-starlight-docs-foundation/ (preserved for diff visibility).
• Modifications to docs/reference/task-list.json ID-9 details / sibling Subtasks (status + journal block on {9.1} only).

Future-Task candidates surfaced by this research:

• Task ID-23 (proposed) — KH AGENTS.md (if OQ 1 lands at Option B).
• Future Task — extend skill suite from 6 → 18+ skills (the deferred Warp-side skills inventoried in “Findings + surprises”).
• Future Task — update-state-of-the-product skill (if OQ 3 lands at Option B).

---

End of RESEARCH ID-9.1.