API Reference Site (DOCS-OAS-62-001)

Last updated: 2025-11-25

Goal

Publish a deterministic, offline-friendly API reference site generated from the consolidated OpenAPI (out/api/stella.yaml) and integrate it into the developer portal navigation.

Generation steps

Build the consolidated spec:

pnpm api:build        # produces out/api/stella.yaml
pnpm api:lint         # optional: spectral lint
pnpm api:compat       # optional: compat check vs stella-baseline.yaml

Generate static reference:
```
pnpm api:reference    # expected to write to out/api/reference/
```
The command should:
- Use the bundled out/api/stella.yaml.
- Produce deterministic HTML/CSS/JS assets (no timestamps in bundles).
- Avoid external CDNs; fonts/assets must be local for air-gap.
Verify determinism/offline:
- Compare hashes of out/api/reference/ across two runs → must match.
- Open out/api/reference/index.html without network access.

Portal integration

Copy out/api/reference/ into the developer portal static assets under /reference/.
Add nav link “API Reference” pointing to /reference/.
Ensure CSP allows only self-hosted assets (default-src 'self').

Artifacts to publish

out/api/stella.yaml (signed checksum).
out/api/reference/ (static site; checksum manifest).
out/api/reference.sha256 manifest listing all files/hashes.

Notes

Keep OpenAPI examples deterministic (sorted keys, stable ordering).
Do not embed secrets or environment-specific URLs; use placeholders where needed.