- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
route spaces (1.0.0, 1.0.4, 1.0.5)
A second adversarial fact-check pass (372 claims across the 21 integration
and remaining getting-started pages: 291 verified, 22 contradicted) drove
these corrections, each reproduced against the binary or repo source:
- junie.md: the recipe-written MCP config invokes `bd mcp`, which does not
exist in current builds — the page now warns about that and points at
the working standalone beads-mcp server config. (The recipe itself,
cmd/bd/setup/junie.go, still writes the dead config — recorded as a
product follow-up, out of docs scope.)
- claude-code-plugin.md: the plugin (v1.1.0 manifest) ships skills,
commands, and hooks — no MCP server. Removed the bundled-server claims,
uv prerequisite, phantom `init` tool, stale 0.9.2 version pin, and the
unverified env-var list; MCP guidance now points at the standalone
server. installation.md's plugin-MCP troubleshooting entry updated to
the same reality.
- upgrading.md: `bd migrate --cleanup` doesn't exist; the doctor
migration-skew note was inverted (the check DOES run in embedded mode —
cmd/bd/doctor/migration_skew.go); `dolt sql-server --stop` is not a
flag.
- sync-setup.md: `bd vc log` doesn't exist (vc has commit/merge/status);
use `bd history`.
- azure-devops.md: sync flag table listed phantom --label/--status/--type
(real: --states/--types/--issues); error strings now quote the actual
binary messages (MDX-safe).
- github-copilot.md: beads-mcp has no --version flag; verify with
pip show beads-mcp. aider.md's config sample now matches the generated
file byte-for-byte.
Also restores three source edits that a mid-script failure silently
dropped from the earlier printed-paths commit (whose message claimed
them): bd mol pour's help no longer says molecules are "synced with git",
the claude recipe's stale ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json), and the shared
recipe template's quickstart URL. CLI docs regenerated accordingly.
Gates: docsync, docsmint, recipes tests, generate-cli-docs.sh --check,
mint broken-links (no broken links), vet — all pass.
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
Chris Sells