engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md
Date: 2026-07-10 Decided by: Chris Sells (interviewed decision-by-decision; each entry below is his explicit call) Status: settled — do not relitigate without new information
Scope: the migration of beads user documentation from the Docusaurus site
(website/, GitHub Pages) to a Mintlify site rooted at docs/.
bd help --docs-root emits generic MD + frontmatter (title, description —
nothing else). No Docusaurus-specific output (id:, slug:,
sidebar_position:) and no Mintlify-specific output (JSX comments, MDX
escaping conventions, nav fragments) from the binary, ever. Vendor targeting
lives in repo tooling, not in the OSS binary.
Why: keeps bd's OSS surface vendor-neutral while the repo still targets Mintlify.
website/ (including the four versioned doc snapshots), deploy-docs.yml,
generate-llms-full.sh, and the ci-website gate are deleted on this
branch. The live GitHub Pages site is unaffected until merge (it deploys
from main); at merge time it freezes until Chris points Pages at redirect
stubs or turns it off.
Why: the parallel run only protected the live site between merges; working on a branch already provides that. Merge-time steps that remain Chris's: connect the repo in the Mintlify dashboard, choose the docs domain, then replace Pages with redirects to it.
docs/cli-reference/ and the CLI pages array in docs/docs.json are
committed artifacts, regenerated by scripts/generate-cli-docs.sh. The
drift-check (--check, check-cli-docs-drift.sh) and the docs-autofix bot
keep their existing model, now covering the post-processed output.
tools/docsmint/ (package outside cmd/bd, run via go run from
generate-cli-docs.sh): transforms bd's generic pages into the Mintlify
pages and splices the docs.json CLI nav. Unit-tested with go test.
Implementation consequence (not separately interviewed, follows from 1+3):
bd writes the generic per-command tree to an uncommitted staging dir
(build/cli-docs/, gitignored) plus the already-generic
docs/CLI_REFERENCE.md; docsmint owns everything under docs/cli-reference/
and the nav splice. The generic tree does not exist at rest.
The Mintlify site documents the current release line only. The Docusaurus
version snapshots (1.1.0/1.0.5/1.0.4/1.0.0) are not ported; they remain in
git history. The --docs-version release snapshot flow retires with
website/. Mintlify versioning can be introduced later if a real need
appears.
The eleven pointer stubs at old docs/ paths (RECOVERY, PLUGIN, DOLT,
STORAGE-BACKENDS, JSON_SCHEMA, SYNC_CONCEPTS, SETUP, INSTALLING,
GIT_INTEGRATION, QUICKSTART, DOLT-BACKEND) are deleted. Old routes are
covered by the redirects array in docs/docs.json (Mintlify forwarding).
Accepted consequence: already-released bd binaries print GitHub paths/URLs
to the old locations (e.g. docs/RECOVERY.md#pk-fork-refused); after merge
those GitHub links 404. Future binaries print the new locations (decision 7).
Go string fixes land here (with regenerated docs): prime.go
(SETUP→getting-started/ide-setup), store_factory_nocgo.go
(INSTALLING→getting-started/installation), init_git_hooks.go
(GIT_INTEGRATION URL), dolt.go (RECOVERY URL→recovery/init-safety),
doctor/claude.go (PLUGIN→integrations/claude-code-plugin), output.go
(JSON_SCHEMA→reference/json-schema), init.go backend flag help
(STORAGE-BACKENDS→architecture/storage-backends), init_safety_help.go
(docs/adr→engdocs/adr), doctor/managed_handoff.go (DOLT→architecture/dolt),
setup/aider.go (QUICKSTART), agent templates (SYNC_CONCEPTS, QUICKSTART),
recipes.go stale claude ProjectPath metadata, and the bd mol pour help
wording "synced with git" → Dolt-sync phrasing.
Recorded, not fixed (behavior-level, needs its own change):
routing.mode accepts maintainer / contributor values that behave
identically to explicit (only auto is special-cased in
internal/routing/routing.go).sync.require_confirmation_on_mass_delete is a validated config key with
no apparent consumer implementing the confirmation.To engdocs/: ERROR_HANDLING.md, CONTRIBUTOR_NAMESPACE_ISOLATION.md,
messaging.md, UI_PHILOSOPHY.md, AGENT_SIGNING.md (plus the originally listed
internal set). Stays user-facing: graph-links.md → core-concepts/graph-links.
This clone gets no .beads/ writes (no bd bootstrap). Branch work,
findings, and follow-ups are tracked in the PR description and this record.
make diagrams-excalidraw and the committed-source/rendered-SVG convention
come over from Gas City on this branch; the nine existing diagrams stay
mermaid; no Excalidraw diagrams authored yet. Rendered images require
render-and-review before commit.
The branch is pushed when gates are green; no new draft PR from the agent (PR #4717 was closed during the interview).
Repo convention over the agent's default specs/ convention.
docs/docs.json).https://gastownhall.github.io/beads/* to the new domain (or disable
Pages).Docs: link and npm-package/plugin doc links to the new
domain.