Doc Consolidation Platform (Starlight + Log4brains + AGENTS.md root)

ADR-063 — Doc Consolidation Platform (Starlight + Log4brains + AGENTS.md root)

Status: Proposed (2026-05-20) Author: Mishaal Murawala Companion plan: docs/plans/doc-consolidation-platform.md INVARIANTS-UNCHANGED — the 15 V5 gateway invariants in .claude/rules/v5-invariants.md are not modified. This ADR governs the documentation surface only.

Context

The repo currently maintains six parallel documentation surfaces that each claim to be canonical for some subset of project knowledge:

AGENTS.md — cross-tool agent entrypoint (Linux Foundation AGENTS.md standard).
.claude/CLAUDE.md + .cursor/, .windsurf/, .vscode/, .codex/ tool-specific instruction files.
docs/CURRENT-STACK.md — human-facing canonical stack reference.
docs/decisions/ADR-*.md — architecture decisions (no supersession graph; supersession encoded only in prose).
docs/plans/*.md + docs/projects/<slug>/GOAL.md — write-once plan documents.
docs/projects/LEDGER.md + HANDOVER.md — project status + operational state, hand-maintained.
docs/composio/toolkit-registry.md, docs/architecture/*.md, docs/composio/*.md — provider-specific runbooks/registries.

Drift problem (proven 2026-05-19 → 2026-05-20): ADR-061 (Pipedream Connect gap-fill) merged 2026-05-19. Within 24 hours, three downstream docs were already stale — docs/composio/missing-toolkit-runbook.md still led with Path C (CF Worker), the LEDGER row for ADR-060 was still marked active, and HANDOVER’s Quick State YAML did not mention Pipedream. Each of those is a structural failure: the canonical doctrine (ADR) and the operational doctrine (LEDGER/HANDOVER/runbooks) are two physically separate surfaces with no enforcement link.

This is not a discipline problem. It is a surface count problem. Drift is the inevitable outcome of N humans-or-agents needing to remember to update M downstream docs every time a single decision lands. The fix is structural: collapse the surfaces and enforce the links in CI.

Doctrine D6 (“drift prevention is built-in, not aspirational”) mandates that every doc/code pair where one is the source of truth for the other gets a CI check. This ADR operationalizes D6 across the documentation surface.

Decision

Adopt an OSS doc consolidation stack with five components:

Astro Starlight (MIT) — single rendered doc site at docs.ascendgtm.net. Replaces the implicit “everything in /docs is a website” assumption; gives navigation, search, and a build step that can fail on broken links.
starlight-llms-txt — auto-generates llms.txt + llms-full.txt from the Starlight build so LLMs (Claude, Cursor, Codex) can index the docs without scraping HTML.
Log4brains (MIT) — MADR-2 ADR site generator with first-class supersession graph. Replaces the prose-only “Supersedes ADR-060” pattern with machine-readable links; produces a visualizable graph of decision evolution.
GitHub Projects v2 — replaces docs/projects/LEDGER.md as the project status source of truth. Accessed via the GitHub MCP projects_list / projects_get tools (added January 2026). LEDGER.md becomes a build artifact rendered from Projects v2, not a hand-maintained file.
AGENTS.md hoisted to root as the single agent entrypoint — .claude/CLAUDE.md, .cursor/rules, .windsurf/rules, .codex/AGENTS.md, .vscode/* all become thin symlinks or generated stubs that include AGENTS.md. Removes 5 separate “tool context” surfaces.

Glue layer: ~250–400 LOC of Zod schemas + pre-commit checks (#26–#30) that enforce:

Every ADR has machine-readable supersedes: / superseded-by: front-matter (check #26).
Every LEDGER row maps to a GitHub Projects v2 item (check #27).
Every plan doc has a non-orphan companion ADR (check #28).
Every invariant referenced by number resolves to a real entry in .claude/rules/v5-invariants.md (check #29).
Every toolkit-registry row has a corresponding capability_index entry in Vectorize (check #30, deferred to Phase 2).

Cost: $0/month recurring (all OSS) vs. $250/month for Mintlify Pro (rejected — see alternatives).

Explicitly rejected alternatives

Alternative	Rejection reason
Mintlify Pro ($250/mo)	Cost — user explicitly ruled out. Vendor lock-in on a non-differentiated surface. Closed-source rendering pipeline.
Custom Worker-based doc site	Build-and-maintain a renderer when Starlight is one `npm create astro@latest -- --template starlight` away. Violates “simplicity first” (Karpathy law 2). Linear maintenance cost.
Status quo + more pre-commit checks	Doesn’t solve the surface-count problem. Each new check covers one drift vector; adding checks faster than surfaces grow is unsustainable. The 2026-05-19→20 ADR-061 fallout happened with 25 checks already in place.
Notion / Confluence	External SaaS, not source-controlled with the code, no PR review of doc changes, additional vendor in the security audit.
GitBook	Vendor lock-in, weaker LLM integration story than `starlight-llms-txt`.
Docusaurus	Heavier, React-bound, slower builds. Archived Docusaurus instance already deleted per ADR-064. Starlight is the modern Astro-native equivalent.
Keep `LEDGER.md` as hand-maintained	Drift between LEDGER and reality is the most common single failure mode in this repo (ADR-060 stayed “active” 1 day after supersession). GitHub Projects v2 is the structural fix.

Consequences

Adds:

Astro Starlight site under apps/docs/ (new workspace package).
starlight-llms-txt plugin → docs.ascendgtm.net/llms.txt + /llms-full.txt.
Log4brains site under apps/adrs/ (or merged into Starlight via plugin — Phase 1 decision).
GitHub Projects v2 board “Ascend GTM Platform” mirroring LEDGER schema.
5 new pre-commit checks (#26–#30 — #30 deferred to Phase 2).
~250–400 LOC of Zod schemas under scripts/checks/lib/.

Removes / archives:

Mintlify configuration if any survives (already archived per cutover-2026-05-19).
Hand-maintenance of LEDGER.md (becomes generated).
Per-tool agent context files (.cursor/, .windsurf/, .codex/, .vscode/ agent rules) — replaced by symlinks/includes to root AGENTS.md.

Operational:

New deploy target: docs.ascendgtm.net (CF Pages or Worker static assets).
Drift becomes a CI failure, not a discovered-3-days-later operational issue.
LLMs (Claude, Cursor, Codex, Aider, Cline, Qwen, DeepSeek) all read the same AGENTS.md root + the same llms.txt index.

Cost:

$0/month recurring.
One-time engineering: ~1 week across Phase 1 (Starlight + AGENTS.md hoist + checks 26–28). Phase 2 (Log4brains + Projects v2 + checks 29–30) ~1 additional week.

Reversal triggers

This decision must be re-litigated if:

Starlight or Log4brains abandons MIT licensing or the upstream project goes dormant >6 months.
The drift CI checks have a false-positive rate >10%, indicating the Zod schemas don’t model reality. Either fix the schemas or remove the checks — never let them rot to ignored.
Cost creep — if hosting docs.ascendgtm.net plus any add-on plugins exceeds $50/month, re-evaluate.
GitHub Projects v2 MCP support degrades — if projects_list / projects_get MCP tools are removed or rate-limited below usable thresholds, fall back to LEDGER.md and re-open the question.
A frontier-tier OSS doc platform ships that subsumes Starlight + Log4brains + llms.txt in a single tool with better LLM integration. Run head-to-head, then ADR to migrate.

Implementation sequencing

See companion plan docs/plans/doc-consolidation-platform.md for the full 4-phase workstream breakdown. ADR-gated milestones:

PR-A (plan-first): this ADR + plan doc + LEDGER row. No code.
PR-B (Phase 1.1): Starlight scaffold under apps/docs/ rendering existing /docs/**/*.md unchanged.
PR-C (Phase 1.2): AGENTS.md hoisted to root; per-tool files become includes/symlinks; checks #26–#28 land.
PR-D (Phase 2.1): Log4brains ADR site; supersedes: front-matter backfilled across ADR-001..ADR-064; check #29.
PR-E (Phase 2.2): GitHub Projects v2 board live; LEDGER.md becomes generated; check #30 (toolkit-registry ↔ capability_index).

Each PR is independently revertible. No PR depends on a later PR for correctness.

Invariants — unchanged

The 15 V5 gateway invariants in .claude/rules/v5-invariants.md are NOT touched by this ADR. This decision governs:

The documentation surface (how docs are authored, rendered, indexed).
The agent context surface (how AGENTS.md + tool-specific files relate).
The project status surface (LEDGER → GitHub Projects v2).
The drift-prevention surface (new pre-commit checks).

It does NOT touch the gateway runtime, KV schema, hot path, OAuth ownership, or capability index — all of which remain governed by ADR-042, ADR-054, ADR-057, ADR-061, and the invariants file.