Per the decision record: no parallel run and no cutover PR. Removes
website/ (including the four versioned doc snapshots — current-only
versioning; snapshots remain in git history), deploy-docs.yml,
generate-llms-full.sh (Mintlify serves llms.txt natively), the ci-website
package gate (Makefile target, scripts/ci/website.sh, the package-website
jobs and their aggregate-gate entries in pr.yml/main.yml/release.yml, the
ci-measurements suite, detect-package-gates wiring), and the release-time
docs snapshot flow (snapshot-release-docs.sh, check-docs-version.sh, their
call sites in update-versions.sh/check-versions.sh, RELEASING.md section
rewritten for the Mintlify reality).
Drift machinery now covers exactly the Mintlify artifacts:
check-cli-docs-drift.sh pathspecs/fingerprint, docs-autofix-push.sh
allowlist, and check-doc-flags.sh scans drop the website/llms paths. The
beads-docs skill's generated-content and verification sections updated to
the bd-generic + docsmint pipeline.
NOTE for merge time: if branch protection requires the 'Package Gate
(website)' check by name (rather than the aggregate gate), drop it from
the required checks or PRs will wait forever.
Gates: docsync PASS, generate-cli-docs.sh --check PASS, freshness PASS.
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.
generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.
Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.
TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
Add a bulk help docs writer that emits the root CLI reference and website command pages from a single Cobra walk. Update the shell generator to call that mode, preserve the pure-Go docs binary guard, and refresh historical versioned CLI docs only when release snapshotting requests a specific version.
Agent-Signature: codex-gpt-5.5-medium on behalf of matt wilkie
The doc freshness gate regenerated all generated doc artifacts and failed
the PR on any diff, even drift the contributor did not cause: staleness
inherited from the base branch, or local regeneration environments that
do not match CI's canonical build. Contributors ended up futzing with
regeneration loops for docs unrelated to their change (#4300, #4301).
New scripts/check-cli-docs-drift.sh keeps the strict regenerate-and-diff
probe as the fast path, but on failure in a PR it attributes the drift
before failing anyone: it regenerates the artifacts at HEAD and at the
merge-base in scratch worktrees, each with the canonical pinned build
(CGO_ENABLED=0 -tags gms_pure_go). If the PR neither changed the
regenerated CLI surface nor touched generated files, the drift is
inherited: warn and pass. Contributors only own docs for code they
actually touched.
When the drift IS attributable, CI now writes the exact regenerated fix
as a patch and uploads it as the cli-docs-freshness-patch artifact, so
the fix never depends on the contributor's local environment: download,
git apply, push.
Strict behavior is preserved wherever there is no PR base ref: pushes to
main, releases, and plain local runs. The pr-policy wrapper picks up the
same logic through check-doc-flags.sh.
Refs #4301, #4203. Complements #4312 (docgen binary pinning).
Agent-Signature: claude-unknown-model-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>