documentation service

Responsibility

docs/docs builds the repository-local documentation into a static Astro site. The same versioned image is promoted through environments. Documentation is a source of truth for behavior, contracts, configuration, deployment, operations, and planned work; it is not generated from arbitrary runtime state.

Build-time inputs

• Starlight renders Markdown content and localized fallback pages.
• Celestia supplies the visual theme and the custom header exposes the four audience areas.
• starlight-openapi generates searchable endpoint pages from src/openapi/platform-api.v1.yaml.
• The self-hosted Scalar client renders the interactive API console from that same YAML file. No hosted Scalar service or request proxy is used.
• Pagefind builds the full-text search index.

The downloadable /openapi/platform-api.v1.yaml route is generated from the same source file. This prevents the interactive console and generated reference from drifting into separate contracts.

Runtime server

docs/docs/server.mjs serves only the static build and accepts GET or HEAD. It exposes /healthz, /readyz, /metrics, and static content with immutable caching for hashed Astro assets. Runtime configuration is limited to bind host, port, environment, and version. The service has no database or Secret.

The API console sends browser requests directly to the selected API server. The API therefore allows the exact test and production documentation origins. Authentication and authorization remain enforced by platform-api, and the console intentionally does not persist entered authentication. The static server applies content-type, frame, referrer, and browser-capability protection headers. Changes to docs browser code or dependencies are security-sensitive because the documentation origin is an allowed API origin.

Change rule

Update documentation in the same change whenever behavior, an API or event contract, configuration, deployment, security, tenancy, operations, or user workflow changes. Roadmap state belongs in the Internal Roadmap, whose localized page must remain semantically synchronized.

Failure diagnosis

Symptom	First check
Page missing from navigation	astro.config.mjs sidebar and content slug.
German page unexpectedly shows English	Whether a localized page exists; technical fallback is intentional.
Endpoint missing from reference	OpenAPI path and successful docs build.
API console loads but request is blocked	Browser console, selected server, and API CORS exact-origin list.
Docs version differs from platform	Argo CD image selection and /version endpoints.