ADR 007 Starlight Documentation Surface
Context
Section titled “Context”Shared documentation becomes contradictory when contract, backend, frontend, and assembly repositories each maintain independent architecture or API truth. Repository-local setup notes still need to remain close to owned code.
Decision
Section titled “Decision”Assembly apps/docs is shared documentation surface. It uses Astro Starlight
for architecture, ADRs, migration source maps, and generated contract reference.
- Contract OpenAPI and TypeScript exports remain source truth in contract repo.
- Starlight generates API and SDK reference from those owned artifacts.
- Hand-written shared API descriptions must not compete with generated pages.
- Repository READMEs may document local setup, commands, and contribution rules; they must link to Starlight for cross-repository architecture decisions.
- Docs lifecycle uses pnpm commands only.
Standard validation command is pnpm docs:check. It stages generated OpenAPI,
runs docs-tooling guard, then runs Astro/Starlight type and content checks.
Implementation Evidence
Section titled “Implementation Evidence”Evidence proves repository configuration at pinned commit. It does not claim current deployment availability.
Consequences
Section titled “Consequences”Cross-repository documentation changes land in assembly. Contract reference changes start in contract repo, then flow into generated Starlight output.
Revision History
Section titled “Revision History”- 2026-07-02: accepted Starlight-only shared documentation surface.
- 2026-07-10: clarified repository-local README allowance and evidence scope.