up

docs/api/overview.md

@@ -0,0 +1,54 @@
+# StellaOps API Overview
+
+Last updated: 2025-11-25 (Md.V docs stream)
+
+## Scope
+Shared conventions for all StellaOps HTTP APIs. Service-specific schemas live under `src/Api/StellaOps.Api.OpenApi` and composed `out/api/stella.yaml`.
+
+## Authentication & tenancy
+- **Auth**: Bearer tokens (`Authorization: Bearer <token>`); service accounts must include `aud` for the target service.
+- **Tenancy**: Multi-tenant endpoints require `X-Stella-Tenant` (or embedded tenant in token claims). Requests without tenant fail with `403` + `error.code = TENANT_REQUIRED`.
+- **Scopes**: Each endpoint documents required scopes; clients must send least-privilege tokens.
+
+## Pagination
+- Cursor-based: `page_token` (opaque), `page_size` (default 50, max 500 unless noted).
+- Responses include `next_page_token` when more results are available.
+- Ordering is deterministic per endpoint (documented under each path).
+
+## Idempotency
+- Write endpoints accept optional `Idempotency-Key` header (UUID). Servers must de-duplicate on key + tenant + path.
+- Idempotent methods: GET/HEAD/OPTIONS always; POST/PUT/PATCH/DELETE idempotent only when key is provided and documented.
+
+## Rate limits
+- Standard headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` (UTC epoch seconds).
+- 429 responses use the standard error envelope; clients should back off using `Retry-After` when present.
+
+## Error envelope
+All error responses use:
+```json
+{
+  "error": {
+    "code": "STRING_ENUM",
+    "message": "human readable",
+    "trace_id": "<trace or correlation id>"
+  }
+}
+```
+- `trace_id` maps to server traces/logs; CLI/Console surface it in verbose output.
+
+## Headers
+- Required observability headers: `traceparent` (W3C), optional `baggage` for routing; services echo correlation IDs in responses.
+- Content negotiation: `Accept` defaults to `application/json`; NDJSON endpoints use `application/x-ndjson`.
+- All times are UTC ISO-8601; hashes are lowercase hex.
+
+## Determinism & offline
+- APIs must return stable ordering for identical inputs; list endpoints document their sort keys.
+- Clients should operate offline using cached responses where supported; air-gap endpoints document required bundles/trust roots.
+
+## Checklist for new/changed endpoints
+- [ ] Added request/response examples (see `examples/` folders).
+- [ ] Spectral lint passes (`pnpm api:lint`).
+- [ ] Compat report reviewed (`pnpm api:compat` vs `stella-baseline.yaml`).
+- [ ] Changelog artefacts generated (`out/api/changelog/*` with checksums/signature).
+- [ ] Error envelope and headers documented.
+- [ ] Pagination, idempotency, tenancy, scopes documented.

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.

docs/api/versioning.md

@@ -0,0 +1,41 @@
+# API Versioning
+
+Last updated: 2025-11-25 (Docs Tasks Md.V)
+
+## Principles
+- **Semantic versioning**: OpenAPI artifacts follow `MAJOR.MINOR.PATCH` where breaking changes bump MAJOR, additive changes bump MINOR, fixes/docs bump PATCH.
+- **Long-lived compatibility**: At least N-1 major versions remain runnable for 12 months; minor versions remain compatible for 6 months after release unless a security fix requires earlier removal.
+- **Explicit deprecations**: Every breaking removal/change is preceded by a deprecation window with headers and changelog entries.
+- **Deterministic specs**: Generated `out/api/*.yaml` are reproducible from a pinned manifest and committed checksums.
+
+## How versions are expressed
+- **Base URL**: `/api/v{major}/...` (e.g., `/api/v1/policy`). Major only; minor/patch controlled via headers.
+- **Headers**:
+  - `X-Stella-Api-Version: <major.minor.patch>` → client-requested minor/patch; server chooses the highest compatible available ≤ requested. If omitted, server serves the latest compatible minor/patch for that major.
+  - `Deprecation: true` + `Sunset: <rfc7231-date>` returned when an endpoint or field is scheduled for removal.
+  - `X-Stella-Api-Deprecated-Fields: field1,field2` lists soon-to-be-removed members for the response.
+- **Error codes**:
+  - `error.code = API_VERSION_UNSUPPORTED` when requested major is not served.
+  - `error.code = API_VERSION_TOO_OLD` when requested minor/patch is below the minimum supported for the major.
+
+## Compatibility rules
+- Additive changes (new fields/enums/paths) are allowed within the same major; fields default to `null`/empty and must not change meaning.
+- Breaking changes require a new major: field removals/renames, required field additions, behavior changes that alter contracts.
+- Enum extensions: existing values remain; new values must be tolerated by clients.
+- Pagination/order: sort keys and determinism must be preserved across versions.
+
+## Release & lifecycle
+1) Draft OpenAPI in `src/Api/StellaOps.Api.OpenApi` and update `out/api/stella.yaml`.
+2) Run `pnpm api:lint` + `pnpm api:compat --baseline stella-baseline.yaml` to ensure no unintended breaks.
+3) Publish changelog entry under `out/api/changelog/<yyyyMMdd>-<version>.md` with checksums/signature.
+4) Announce deprecations via release notes; include `Deprecation`/`Sunset` headers in affected endpoints for at least 60 days before removal.
+5) Sunset execution: remove endpoints/fields only after the sunset date and after the major bump ships.
+
+## Client guidance
+- Always send `X-Stella-Api-Version` to lock to a tested minor/patch; pin SDK versions accordingly.
+- Handle `Deprecation`/`Sunset` headers by warning users and planning upgrades.
+- Prefer server-provided pagination tokens; avoid relying on incidental field order.
+
+## Testing
+- Contract tests must cover the lowest and highest supported minor/patch for each major.
+- Deterministic fixtures for each version live under `tests/fixtures/api/versioning/`; CI runs `pnpm api:compat` against these fixtures.