KERNIT Documentation
Docs release workflow
A docs release is acceptable only when the OpenAPI contract, generated pages, changelog, feedback sink, and publish output are checked together. The release gate is designed to catch drift before users see it.
Required Release Steps#
| Step | Command or artifact | Blocks release when |
|---|---|---|
| 1 | app/docs/openapi.json | Endpoint fields, response shapes, route policy, or auth rules changed without updating the contract. |
| 2 | app/docs/openapi-snapshots/2026-05-12.json | The current contract has no matching versioned snapshot. |
| 3 | npm run docs:generate | Generated HTML, search index, manifest, RSS, or OpenAPI output is stale. |
| 4 | npm run docs:validate | OpenAPI lint, snapshot diff, generated docs, or docs-events checks fail. |
| 5 | /docs/changelog | User-facing API, Hyperlinker, or docs behavior changed without a release note. |
Validation Command#
npm run docs:generate
npm run docs:validateOpenAPI Snapshot Rule#
If the API contract changes, update the contract version and add a new snapshot. The snapshot gate rejects a current contract that is not pinned in app/docs/openapi-snapshots, and it rejects obvious breaking changes between published snapshots.
Changelog Rule#
Any change that affects how researchers, developers, platform teams, or support use KERNIT belongs in the changelog. The RSS feed and changelog page are generated from the same release entries, so the docs release has one public history.
Publish Readiness Checklist#
- Endpoint examples still match the OpenAPI source.
- Decision and runbook pages are reachable from the API navigation.
- Feedback and playground events remain sanitized before storage.
- Generated docs include sitemap, robots, RSS,
llms.txt, anddocs-manifest.json. - The Cloudflare Pages publish directory still points at
src.
Was this page useful?Send a lightweight docs feedback event.