# 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.