Serve the Guide locally with Astro and Starlight

[davideimola]

Parent

#1

What to build

A reader can browse the Argus Guide locally: navigation, working internal links and search. This is the tracer bullet through the whole publishing path, and it exists first because it verifies the two constraints most likely to be wrong.

Astro with Starlight, styled with Tailwind. The Mirror is seeded by hand, once, from argusappsec/argus under docs/guide/ — this is a bootstrap, and the Sync (a later ticket) must be able to replace it.

Two received requirements from argus ADR 0022 get proven here. The Mirror's location is fixed, not chosen: Starlight's docsLoader() hard-codes its base and does not expose it, so the Mirror must physically sit at src/content/docs/guide/ — that is also what makes the URL prefix /guide/, which the Guide's own internal links are already written against. And sidebar group labels must be set in this repository's Astro config, because an autogenerated group takes its directory name verbatim and would render channels and deployment lowercase.

The Astro application lives at the repository root. Astro reads only src/, public/ and its config, so the root docs/ directory holding the Agent docs and this repository's ADRs is invisible to it — there is no collision to resolve.

Content conventions and the docsLoader() behaviour were researched against Starlight 0.41.5 / Astro 7.1.6 and recorded in argusappsec/argus under docs/research/starlight-content-conventions.md. Read it before configuring the mount or the sidebar.

Acceptance criteria

• The dev server serves every Guide page under /guide/…, matching the slugs the Guide's own internal links point at
• Every internal link in the Guide resolves — no 404 on any of them
• The sidebar shows all eight pages in sidebar.order sequence, with human-readable group labels rather than lowercase directory names
• Pagefind search returns results for a configuration key looked up by name, with no external service configured
• ::: asides in the Guide render as typed callouts, not literal text
• The production build completes clean
• The Mirror sits where docsLoader() requires, and nothing else in the repository is edited to make that work

Blocked by

• None — can start immediately.