* 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.
- docsmint: all page rewrites (HTML-comment, relative-link, ESM) now skip
fenced code blocks; fence contents render verbatim
- docsmint: spliceCLINav fails closed when the "pages" key found after
"group": "CLI Reference" is not a sibling key of the same object, and
validates the spliced docs.json parses before writing
- docsmint: neutralize MDX ESM hazards in docs/CLI_REFERENCE.md too (bd
emits it without the per-page transforms, but Mintlify serves it as a
hidden page); regenerated docs/CLI_REFERENCE.md accordingly
- help_all: fail loudly when two commands collide on the same doc page ID
instead of letting the later write win; repair a garbled comment
- generate-cli-docs.sh: --check no longer trusts a repo-root ./bd it was
not explicitly given (the CGO guard detects CGO-ness, not staleness)
- docsync: validate the docs.json redirects array (well-formed, no dup
sources, destinations resolve)
- pour: runtime strings match the corrected Long text (Dolt sync, issue
database — not "sync to git" / "persistent in .beads/")
- testdata: formula_help.txt asserts the new docs/workflows/formulas.md path
check-build-tags requires every go test/go run in tracked scripts,
workflows, and the Makefile to carry -tags=gms_pure_go (ICU-linkage
guard): added to the docsync invocations in docs-mintlify.yml and
make check-docs, and to the docsmint stage of generate-cli-docs.sh
(the flagged workflow job name no longer embeds a bare invocation).
docsmint's two variable-path os.ReadFile sites get justified
#nosec G304 annotations — both read only repo-owned files derived
from the tool's repo-root argument. golangci-lint: 0 issues.
Per the decision record (engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md):
bd's doc generator is vendor-neutral. `bd help --docs-root` now writes
docs/CLI_REFERENCE.md plus a generic per-command tree (title/description
frontmatter, portable CommonMark, HTML-comment markers) into build/cli-docs/
— uncommitted staging, gitignored. All site-generator-specific output leaves
the binary: Docusaurus frontmatter, sidebarPositionMap, the website/ writers,
the Mintlify writers, the docs.json nav splice, and the --docs-version
snapshot flag are gone from cmd/bd.
tools/docsmint (Go, unit-tested) is the Mintlify post-processor: it turns
the staging tree into the committed docs/cli-reference/ pages (JSX comment
markers, extensionless route links) and splices the CLI Reference pages
array in docs/docs.json. scripts/generate-cli-docs.sh runs both stages;
--check seeds the committed artifacts into a scratch root, regenerates, and
diffs, exactly as before.
Regenerated output: the 113 pages are byte-identical through the new
pipeline; docs.json nav ordering is now plain filename sort;
docs/CLI_REFERENCE.md drops the removed --docs-version flag.
`bd help --doc <cmd>` stdout is likewise generic now (no Docusaurus
id/slug/sidebar_position).
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).
Why: regenerating CLI docs on a machine with a C compiler links CGO by
default, so `bd federation --help` emits the full federation subcommand tree.
The committed docs are built by CI with CGO_ENABLED=0, which stubs federation
("built without CGO support"), so a naive regen produces ~hundreds of lines of
spurious federation churn (federation.md, CLI_REFERENCE.md, llms-full.txt)
unrelated to the actual change. The existing guard force-rebuilds a pure-go
binary but offered no escape hatch and announced the swap on stdout.
What:
- Route the CGO-mismatch notice to stderr (keeps --check/CI stdout clean and
makes it a proper warning).
- Add a documented BD_DOCS_ALLOW_CGO=1 override hook so an intentional
full-federation regen can trust the supplied binary as-is; default stays
safe (rebuild pinned CGO_ENABLED=0 -tags gms_pure_go).
- Make the message name the pure-go recipe and reference the stub marker
("Federation commands require CGO", cmd/bd/federation_nocgo.go).
- Document the override in the script's --help text.
generate-llms-full.sh builds no bd binary, so it needs no change.
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
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
Complete mybd-pnm docs evidence review.\n\n- Add verified docs disposition inventory and canonical seams.\n- Stage stale duplicate docs under docs/staged-for-removal with a manifest.\n- Refresh generated CLI docs and harden the generator for CRLF/stdin handling.\n\nFollow-up: mybd-xfr for automated docs freshness checks.
* docs: generate CLI reference from live help
* docs(cli): move bd version stamp from per-command pages to index only
Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on
every per-command CLI reference page (writeSingleCommandDoc) and the
docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now
lives only on the index page emitted by scripts/generate-cli-docs.sh:
- Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md):
labelled "Latest"
- Versioned snapshots (website/versioned_docs/version-X.Y.Z/...):
labelled with the explicit semver tag parsed from the directory name
This eliminates the 100+-file no-signal diff a release version bump
otherwise produces, restoring the "regen as a separate small commit"
workflow PR #3704 enables. After this change a version bump alone
yields zero diff on the dev tree; only the new versioned snapshot
created at release-cut time carries the new tag. No datestamps are
introduced anywhere — scripts/generate-cli-docs.sh --check remains
deterministic across CI runs.
Refs: mybd-afb, PR #3704
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Chris Sells