Documentation and Contract Pipeline
The documentation is a controlled contract system, not an all-in-one document maintained separately for AI.
Source flow
Today the architecture and domain contracts are authored Markdown. When the navigation registry exists, operation schemas and reference tables move to generated output while rationale and tutorials remain authored.
Required metadata
Every page declares:
| Field | Purpose |
|---|---|
hexis_status | policy, current, contract, future, implemented, or legacy |
last_verified | Freshness date tied to the stated evidence |
status_note | Important limitation shown beside status |
ai_context | implementation, api, or exclude |
executable | Whether target calls may be offered as runnable |
contract_version | Required for target-contract pages |
implementation_ref | Required for implemented pages |
The site status banner and AI artifacts read this metadata. Body prose does not duplicate it.
AI outputs
/llms.txtis a concise discovery index./llms-implementation.txtcontains architecture and planned contracts for agents implementing Hexis./llms-api.txtcontains only implemented, executable contracts for agents generating user scripts./docs-manifest.jsonexposes status and retrieval metadata./ai/...provides clean per-page Markdown for selective retrieval.
Archived reference pages are unlisted, excluded from normal search and sitemap discovery, and omitted from AI artifacts. The archive index remains discoverable so maintainers can reach those pages for historical investigation.
Quality gates
npm run docs:check validates metadata, status transitions, internal links,
target manifests, legacy isolation, Mermaid blocks, and AI bundle selection.
It also validates the representative retrieval and script-generation cases in
evals/api-authoring.json. Artifact tests prevent planned or legacy content
from entering the runnable bundle. TypeScript checks the site customizations.
The production build treats broken links as errors.
GitHub runs validation on pull requests, master, and weekly. Cloudflare Pages
builds and deploys master. A green deployment is not proof that an API is
implemented; promotion still requires the acceptance matrix.
Change protocol
- Identify current evidence and representative task.
- Update the contract and acceptance criteria.
- Implement the Java mechanism and registry entry.
- Generate or verify the binding and reference.
- Add lifecycle, security, pack, AI, and live evidence.
- Promote metadata only after every gate passes.
If code and docs disagree, downgrade the page rather than hiding uncertainty.