fix(docs): generate site references at build time

[jeremi]

A change to one public command currently changes the whole CLI catalog digest embedded in 133 checked-in pages. Together with generated JSON mirrors, this creates large diffs and repeated merge conflicts across unrelated PRs.

Generate site references during development, tests, validation, and builds, and keep their 144 rendered files out of Git. Source definitions, authored documentation, schemas, generators, and review metadata remain reviewable. Product-owned generated schemas and released artifacts retain their existing contracts.

Release preparation now reads authored docset metadata independently of local build output. Archive generation uses pinned source exports for new refs and preserves legacy committed-output handling. Generated-output regression coverage and CI routing verify source changes without relying on rendered diffs.

Validation:

• 551 docs script tests (including a run with both generated directories absent) and 88 CI routing tests passed.
• Full npm run check passed, including Astro build and 26,873 internal links/assets.
• 106 release tool tests, 34 archive tests, and 4 release rehearsal tests passed.
• Real clean-export generation matched source-generated artifacts and restored local output.
• Updated from main after the concurrent starter PR; all 131 generated-only conflicts were resolved by retaining ignored outputs, and all 551 docs tests passed again.

The large deletion is a one-time migration. Older branches may need to accept generated-file removals once when updating from main, then regenerate locally. Independent and PR review findings are resolved, including scoped BReg contributor guidance. Cold-output generation leaves the Git worktree clean. The Docker archive recipe was updated and shell-syntax checked; the full Docker recipe was not executed locally. Protected CI supplies Linux validation.

The full updated-source CI matrix passed. An unchanged PostgreSQL test with an 80 ms deadline timed out before handler evaluation once; its job passed on a focused retry without code changes. The final guidance-only commit also passed its complete required CI matrix before merge.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-08T11:55:40.546456Z	ffe34a5	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c00fbffb8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".