docs: hand-authored Astro site at site/

Supersedes !12 (closed) (@graysongordon-gl). Adopts the public-sector/reference Astro template so postern matches kaniko and the rest of the estate.

Closes #5 (closed) ("Documentation Improvements").

What's here

Hand-authored Astro 6 docs site at site/, modeled on public-sector/reference/templates/docs/. No Starlight; shared chrome loads from the reference's Pages CDN. Five sections, 23 pages, all written from scratch against the Go source code — README.md was deliberately NOT consulted.

Section	Pages
Start	Getting started (5-step path from podman pull to first triggered pipeline)
Sources	Overview + per-adapter: azure.eventgrid, gcp.pubsub, aws.sqs, kafka, cloudevents
Guides	Routing, Schema versioning, Observability, OpenTelemetry, Config reload, Kubernetes
Reference	CLI, Config schema, Security model, Metrics
Contributing	Add a source (the v2 pluggability story @graysongordon-gl asked for in !9 (closed)), Testing

Deploy

Published to https://gitlab-com.gitlab.io/public-sector/postern/ via a new pages stage. The build-docs job (in the existing build stage) builds on every MR that touches site/** and on every push to main.

Why not Starlight

The estate already has a hand-authored Astro pattern in public-sector/reference/templates/docs/. Lifting it here gives postern the same visual register as the reference, kaniko, and every other Public Sector project — header band, type stack, palette, dark mode, breadcrumbs, sidebar — without forking an upstream framework. Updates to the design language land on next page load via the CDN.

Authoring conventions

• .ai/docs-authoring.md (lifted from the template) is the page-archetype contract. Five archetypes; nothing else.
• nav.ts is the declarative sidebar truth.
• withBase() on every internal link — required for Pages-base resolution.
• Every page: one h1, sections each with subtitle + title + prose.

Verification

• npm install && npm run build is green: 23 pages, 554ms.
• Each adapter page was verified against internal/source/<name>/<name>.go — the agents writing them flagged a few inconsistencies between my instructions and the actual code (e.g. OTel namespace default is public-sector, not public-sector-tools; SQS/Kafka backoff field exists internally but isn't yaml-tagged for users). The flagged behaviors won out; the page reflects code, not instructions.

Reference enhancements

The docs template covered postern's needs out of the box. Two estate-wide enhancements worth filing against reference separately (not blocking):

1. Pagefind search integration — drop-in static-site search.
2. JSON Schema renderer — generate reference pages from a committed postern.schema.json so docs derive from source instead of drift-prone hand-authored tables. Aligns with the Derived Obligations principle.

I'll open both as issues on reference after this lands.

For @graysongordon-gl

Issue #5 (closed) ("more comprehensive docs") is what triggered this. The /contributing/add-a-source/ page is your decomp issue answered in long form — three steps, four discipline rules, worked examples pointing at the five built-in adapters. If anything's missing for someone adding a sixth adapter, that's the real test of whether the docs serve the contributor — please call it out.