up

docs/api/reference/README.md

@@ -0,0 +1,40 @@
+# 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
+1) Build the consolidated spec:
+   ```bash
+   pnpm api:build        # produces out/api/stella.yaml
+   pnpm api:lint         # optional: spectral lint
+   pnpm api:compat       # optional: compat check vs stella-baseline.yaml
+   ```
+2) Generate static reference:
+   ```bash
+   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.
+
+3) 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.