* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference
The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.
- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
canonical pure-Go build), removing the unreleased commands/flags and
fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
builds and caches a canonical pure-Go bd from that tag, fetching the tag
first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
resolve bd through the pin and ignore a supplied binary while pinned
(BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
bd <= v1.1.0 emits and converts it to the generic form before its normal
Mintlify transform (tested); removable once the pin reaches a release
whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
beads-docs skill §8 updated to match.
* lint: annotate gosec G705 false positive in the docsmint legacy bridge
Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
Resolves modify/delete conflicts on website/* (Mintlify migration deleted
the tree in main; accept deletion). cmd/bd/prime.go auto-merged cleanly,
re-siting --no-memories on top of #4335's custom-PRIME.md/formatMemoriesForPrime
handling and #4230's doltSync gating without further edits.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Resolves the Mintlify website-tree deletion conflict (52aea3f7e) against
this PR's now-obsolete website/*/cli-reference/prime.md doc edits: accept
main's deletion. cmd/bd/prime.go merged cleanly (no conflict markers) —
the PR's --memories-only-before-custom-PRIME.md dispatch and its
memory-append-under-custom-PRIME.md logic both survived alongside main's
agent.profile Long-help bullet (#4585). Regenerated CLI docs
(scripts/generate-cli-docs.sh) produced no additional diff beyond the
merge itself.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Per decision 7, bd's user-facing strings now reference the Mintlify-era
paths: prime policy-profiles help, storage-backend comparison help
(store_factory_nocgo, init --backend), init-safety help (recovery
playbooks now docs/recovery/init-safety.md; the ADR reference now
engdocs/adr/), the pk-fork-refused recovery URL (dolt.go), doctor's plugin
suggestions (claude.go) and managed-handoff pointer, aider setup guidance
and the shared recipe template (quickstart URL), and the agent instruction
templates (sync-concepts URL, quickstart URL). bd mol pour's help no
longer claims molecules are 'synced with git' — they sync via Dolt like
any other bead.
Also corrects the stale claude recipe ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json; the dedicated
installer has written settings.json since the migration sweep).
This repo's AGENTS.md managed section is refreshed to the new template
body (hash bacef91e, has-remote variant preserved), and agents.md.tmpl's
embedded marker matches. Template tests updated to pin the new fragment;
CLI docs regenerated.
Recorded, not fixed (behavior-level, see the decision record):
routing.mode's maintainer/contributor no-op values and the
sync.require_confirmation_on_mass_delete key with no consumer.
Note: TestCheckBeadsRole_NotConfigured/_NotGitRepo in cmd/bd/doctor fail
on any machine with beads.role in the global git config (no HOME
isolation) — pre-existing, unrelated to this change.
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).