Version: Current

Documentation versions

Current docs stay at the normal page URLs. They can change with each docs commit. A release snapshot keeps the rendered pages, assets, search index, and source record from one build. It does not change when current docs change.

Release routes

Only acumen and studio release tags in vX.Y.Z form can create public versions. A branch is not a public version. With the /site/ deploy prefix:

View	Example URL
Current	`/site/reference/api/`
Acumen release	`/site/versions/acumen-v1.2.3/reference/api/`
Studio release	`/site/versions/studio-v2.0.0/reference/rpc/`

These are route examples, not claims that those releases exist. Each snapshot contains the whole docs build tied to that product release. The source record names every contract source revision, so an acumen release does not imply that studio was released at the same time.

The Version menu appears above the page title. Choose a release to keep the same page if it exists there. A missing page goes to that release’s home page. The Current link goes to the current home page, since old pages may no longer exist in current docs. The menu uses native links and a keyboard disclosure on small and large screens. Without JavaScript or a catalogue response, a snapshot still shows a frozen-docs warning and a link to current docs.

Metadata and immutable bytes

Migration migrations/0012_docs_release_snapshot.sql extends the docs metadata boundary:

Table	Record
`docs.release_snapshot`	Release tag, product, docs commit, source commits, build time, prefix, page list, SHA-256, and rendered artifact bytes
`docs.release_lifecycle`	Supported, deprecated, or retired status; message; actor; request; revision
`docs.setting_audit_event`	Lifecycle changes in the same transaction

The artifact is stored in Postgres suite. Generated files are publish outputs, not a second metadata store. A unique release key rejects a second capture. Database triggers reject update, delete, and truncate of published snapshots. Lifecycle edits use a checked revision and leave the snapshot bytes unchanged. A retired release remains readable. There is no automatic retention deletion. The DB owner must keep application roles from schema changes or trigger bypass.

Each snapshot includes release-provenance.json. It records the product tag, docs commit, full source commits, UTC generation time, and publish prefix. The catalogue adds the artifact checksum. No database credential reaches the browser.

Capture a release

This is a release operator procedure. This card does not apply migrations, capture real releases, or deploy to production.

Apply the versioned migrations through the metadata owner’s migration path. Use suite via the local leader proxy for writes. Bootstrap only the secret DSN reference as DOCS_ENGINE_PG_DSN; do not put it in a command or a file.
Use clean committed docs and source checkouts. Check out the product release tag in its source repo. Pass every repo from the docs-engine source contract, plus the product repo if it is separate.
Run the capture command. For an acumen release, with local paths replaced:
Terminal window
```
node tools/versioning/cli.mjs capture --product acumen --tag v1.2.3 \
  --base /site/ --actor release-owner \
  --source acumen=/checkout/acumen --source cli=/checkout/cli
```
A studio release also needs --source studio=/checkout/studio. The command checks that the product HEAD is the tag’s commit. It runs the authoritative reference drift check against the explicit source checkouts, builds under the release prefix, and stores the artifact and initial lifecycle row atomically. Missing sources or drift fail capture. Reusing a release id fails; corrections need a new product/contract release.
Build current docs with the metadata DSN available. The build reads one consistent Postgres view and adds all frozen releases to dist/versions/:
Terminal window
```
DOCS_BASE=/site/ npm run build
node tools/versioning/check.mjs dist
```
The publish check requires a DB-backed build and hashes each exported snapshot. Without a DSN, a build is a current-only preview. Both publish recipes reject such a preview before any remote mutation. A prefix change fails assembly: existing immutable URLs require a separate reviewed migration.

Deprecate a release

Use the trusted admin command with an actor, request id, and expected revision:

node tools/versioning/cli.mjs lifecycle --product acumen --tag v1.2.3 \
  --status deprecated --message 'Move to current docs for supported behavior.' \
  --revision 1 --actor release-owner --request release-review-123

Status may be supported, deprecated, or retired. The DB change is audited at once. Rebuild and publish the current catalogue to expose the change on the static site. Old pages fetch that catalogue and show its banner; their stored HTML and source record remain frozen. An offline page keeps its generic warning. No runtime server or direct browser-to-DB connection is required.

Release artifact handoff

The release owner packages dist/, tools/live-site/manifest.mjs, tools/versioning/{check,artifacts}.mjs, and src/lib/versions.mjs in the Nomad artifact. The version publish check uses only Node built-ins. The fallback publisher runs the same check after its DB-backed build. Existing backup, subtree scope, shared-root index, and URL verification rules still apply. The current machine index and search cover current docs. Each frozen build keeps its own machine index and search. The served-root generator inventories both.

Local verification

Run tools/testdb.sh with a unique name and port, supply its disposable DSN as DOCS_TEST_DSN, then run node --test tools/docs-engine/tests/versioning.test.mjs. The DB tests apply the migrations, test immutability and audited edits, check exported bytes, and run EXPLAIN for catalogue, artifact, and lifecycle reads. Without that test DSN, only the database test is skipped. The normal site gate runs the route, UI, artifact, and built-page accessibility tests.