chore: pre-release fixes and documentation for 0.28.0

[jeremi]

Summary

Content fixes from the v0.27.0..main pre-release review, ahead of the 0.28.0 release. This PR does not bump the version, write release notes, or touch the release manifest; a separate release PR does that on top of this one.

Decisions applied (recorded in products/breg/DECISIONS.md):

• D1a: registry-breg keeps its unconditional dependency on registry-evidence-client and registry-evidence-verifier; both composition directions are stated in root AGENTS.md; feature gate ticketed (Feature-gate the Evidence relying-party dependency in registry-breg #930).
• D2a: the 24 h retention of the signed JWS for action evidence stays, with operator-run bregctl evidence-retention erase-expired; scope documented on the retention operate page; configurable retention ticketed (Evidence-use retention: configurable duration, digest-only mode, in-process sweeper #931).
• D3a: next release is 0.28.0 (breaking: bregctl dev --project replaced by a positional project).
• D4a: the CLI reference is published by stamping docs/site/src/data/cli-reference.yaml to current; the re-stamp rule is written in docs/site/AGENTS.md, root AGENTS.md, and release/OPERATIONS.md.
• D5a: evidencectl source add is the documented local BReg-to-Evidence path; bregctl dev prepare-source is hidden from help but stays runnable; the three Evidence starter READMEs converge on source add; quickstart retirement ticketed (Retire products/breg/quickstart in favour of bregctl dev #935).
• D6a: unreleased inconsistencies fixed here (starters ship core/dev-clients.yaml; source add previews by default and performs with --apply, no --dry-run, no confirmation prompt); released flag inconsistencies ticketed as one batch (CLI consistency batch across bregctl and evidencectl #934).
• D7b: registry-extensibility.md, native-patterns.md, and membership-access.md from products/breg adapted into three site explanation pages; tutorials ticketed (Publish the BReg-to-Evidence tutorials on evidencectl source add #939, Rebuild review-registry-changes and first-breg on bregctl init, dev and examples #941).

Commits

1. feat(evidence): preview source add by default and hide bregctl dev prepare-source: source_add.rs, source_cli.rs, bregctl dev/mod.rs (hide = true), tests, verify-composition.py review-path coverage, CI comment, starter clients.yaml to dev-clients.yaml renames, BReg evidence READMEs, DEV.md, EVIDENCE.md.
2. docs(breg): record composition boundaries and align product contracts: root AGENTS.md (seven map rows, composition paragraphs, generated-outputs rule), products/breg AGENTS, README, DECISIONS, IMPLEMENTATION (W5 capability table), DEFINITION-OF-DONE and contracts/definition-of-done.yaml (nine rows), ACCEPTANCE-JOURNEYS (fifteen projects), external/README.md, release/notes/behavioral-guarantee-claims.md (thirteen links pinned to v0.19.0), Evidence deployment CONFIG.md (sourceConnections.*.baseUrl row).
3. docs(site): publish the CLI reference and add the re-stamp rule: cli-reference.yaml stamped at 0.27.0, cli-reference-digest.mjs and npm run cli-reference:digest, sidebar seats for every published command page, tests, docs/site/AGENTS.md, release/OPERATIONS.md.
4. docs(site): describe the unreleased BReg and Evidence changes: three explanation pages, retention page section, changelog Unreleased rewrite, pin advances v0.21.0 to v0.26.1, Evidence-from-BReg tutorial, sidebar and information-architecture test entries.

Security-sensitive review notes

• evidencectl source add behavior change: the command now applies nothing unless --apply is passed. The interactive confirmation is removed; the entity, field, facts, and scope prompts remain when omitted in a terminal. The JSON report carries status: "preview" with a next sentence. Test every_bregctl_invocation_names_the_public_flags_source_add_declares and verify_source_add_review in verify-composition.py cover it.
• Boundary statements (root AGENTS.md, products/breg/AGENTS.md): a governed action is an Evidence relying party and inherits no Evidence authorization; source add drives bregctl on PATH and neither product depends on the other's tooling crate.
• Retention page: erase-expired deletes assertion bytes and verification context; receipts stay replayable. Wording is the command's help text.
• No authentication, signing, or audit code changed.

Judgment calls worth a look

• Sidebar seating. With the CLI reference published, the information-architecture seat gate named all 134 subcommand pages. cli-reference-sidebar.mjs now walks the generated tree and seats them in one flat collapsed CLI commands group, labeled by full command path (bregctl audit export). Flat because limitSidebarDepth flattens below the second level anyway; nested groups would render the same with ambiguous labels.
• Definition of Done ids use a word suffix (BREG-V1-ACTION-HANDLERS), the precedent set by BREG-V1-PILOT, so validate_product.py needed no change. BREG-V1-ACTION-EVIDENCE-TRIAL and BREG-V1-EVIDENCE-RETENTION are the first partial rows; the journey mappings are best fit, not derived from the matrix.
• products/breg/evidence/starter/README.md keeps its manual export path beside source add: source add --apply creates the Evidence project itself, refuses a settings-only targets/local, and exposes one selector, so the plain starter's teaching flow needs the hand path.
• Changelog links for source add point at tutorials/first-breg because the two Evidence-from-BReg tutorials are still draft: true (Publish the BReg-to-Evidence tutorials on evidencectl source add #939).

Gates run

Rust (worktree, --locked): cargo fmt --check, cargo check --workspace --all-targets, clippy with -D warnings and tests for registry-evidencectl and registry-bregctl, products/evidence/scripts/check-contracts.sh, check-source-neutrality.sh, products/breg/scripts/check_source_neutrality.py, the non-live verify-composition.py path CI runs.

Products: validate_product.py and the products/breg unittests pass with the nine DoD rows.

Docs site: npm test 554 pass; npm run check exit 0 (check-llms 336 passed, SEO check passed, built link check 90388 internal links); npm run check:cli-reference exit 0; vale 0 errors on every changed or created page.

Left for the release PR

• Bump the workspace version, then re-stamp cli-reference.yaml: npm run cli-reference:digest from docs/site, record both values and a fresh last_reviewed. The docs build refuses the release tree otherwise.
• Older pins still on the site: tutorials/query-relay-client.mdx:249 and tutorials/itb-semic-evidence.mdx:34-35 (v0.20.0), reference/errors.mdx:147 and reference/apis/index.mdx:48 (v0.21.0), operate/breg.mdx:83 (bregctl 0.26.1, the majority pin on that page).

Out of scope, noted

• crates/registry-bregctl/src/init_from_model/render.rs:1211: the generated project README still points readers at the hidden bregctl dev prepare-source.
• products/breg/evidence/README.md:52 still documents --clients-file ./registry/clients.yaml for the copied fixture registry; that fixture was deliberately not renamed.

Follow-up tickets filed

#930 #931 #932 #933 #934 #935 #936 #937 #938 #939 #940 #941 #942 #943 #944 #945 #946 #947

[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-08T19:00:25.074570Z	c33e18c	PR opened

ℹ️ 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.