Explanation: Versioning Policy
v1.0.111 · docs-public.v0Gessa docs are a projection of engine contracts, not a separate knowledge base. The engine repository owns the content and the generated references; public docs render a version-pinned export. That means a page can be linked, audited, and reproduced against a specific engine version.
The route contract
The public route prefix is part of the version contract:
/docs/...is the current public route.- Product content is authored under
docs/product/v1/.... - Generated reference pages are emitted from code and catalogs under
docs/spec/generated/.... - AI context is emitted under
docs/ai-context/v1/....
Future major contracts should open a new authored source tree, not silently reinterpret old pages. A v1 citation should keep meaning the v1 contract.
The source-of-truth boundary
The engine repo owns:
- hand-authored product docs,
- generated component/action/MCP/script references,
- proof and readiness ledgers,
- the docs export manifest.
The web app consumes the generated export and serves it. It must not hand-edit engine docs content, fork reference tables, or invent product claims that are not backed by engine contracts.
Public docs are a one-way generated projection from the engine repository. The docs consumer may style and route the pages, but the engine repo owns the content, generated references, and version pin.
Page-level verification
Pages that describe an important workflow should state the engine version they were verified against and link to canonical references for exact fields or actions. The docs export manifest records:
engineVersion,engineVersionFull,generatedAt,- page source paths,
- page content hashes.
When a page explains a capability, the claim should be backed by one of:
- generated reference from code,
- a proof receipt,
- a focused test,
- a readiness-ledger row,
- clearly labeled context or explanation.
Compatibility policy
A normal docs update may clarify wording, fix links, or add examples without changing the engine contract. A contract-changing update needs a versioned engine change and a regenerated reference.
Use this rule of thumb:
| Change | Required handling |
|---|---|
| Typo or wording cleanup | Edit docs, regenerate export. |
| New component field | Update source schema, generated reference, docs, and tests. |
| New action or MCP tool | Update catalog, generated reference, docs, and parity checks. |
| Breaking script or component shape | Version, migration, or parallel support before public docs claim it. |
| New public capability claim | Add proof or label it as roadmap/context. |
Media placeholders
Screenshots and videos are presentation assets. They should support a verified page, not replace proof. For v1 docs, media should be added after the route contract and crawler checks are stable.
Media placeholder: add a short capture showing the docs version badge, a generated reference link, and a proof callout on this page.