From de0200ff774d9e7569c2830e46317b295d76fcf0 Mon Sep 17 00:00:00 2001 From: Chris Sells Date: Sat, 11 Jul 2026 10:21:09 -0700 Subject: [PATCH] docs(emitter): Cobra-accurate usage lines, published global flags, MDX ESM guard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three generated-content defects from the adversarial review, all structurally invisible to the drift gate (generated-vs-generated): - Usage lines now mirror Cobra's help template: a runnable command shows its UseLine, a command with subcommands shows ' [command]', both when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on 30 parent pages — a line the binary never prints. - The generated CLI index publishes the Global Flags block; the binary prints it on every --help but no page carried it. - docsmint neutralizes prose lines that Mintlify's prebuild would dedent into MDX ESM blocks (a line beginning 'export'/'import' outside a fence gets wrapped in a code span). This is why /cli-reference/mail returned HTTP 200 while rendering only a parse-error placeholder — reproduced, fixed, and covered by a planted-hazard test; fenced content stays verbatim. Also rewords check-cli-docs-drift.sh's early-PASS message, which asserted 'the supplied binary differs' as the cause when uncommitted local edits produce the same result. All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline; TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go. Verified live: /cli-reference/mail renders real content, zero parse errors; generate-cli-docs.sh --check, docsync, freshness, and mint broken-links all pass on this tree. --- cmd/bd/help_all.go | 28 +++++++++++-- cmd/bd/help_all_test.go | 58 +++++++++++++++++++++++++++ docs/CLI_REFERENCE.md | 67 ++++++++++++++++++-------------- docs/cli-reference/admin.md | 2 +- docs/cli-reference/ado.md | 2 +- docs/cli-reference/audit.md | 2 +- docs/cli-reference/backup.md | 2 +- docs/cli-reference/comments.md | 1 + docs/cli-reference/completion.md | 2 +- docs/cli-reference/config.md | 2 +- docs/cli-reference/dep.md | 1 + docs/cli-reference/dolt.md | 4 +- docs/cli-reference/epic.md | 2 +- docs/cli-reference/formula.md | 4 +- docs/cli-reference/gate.md | 2 +- docs/cli-reference/github.md | 2 +- docs/cli-reference/gitlab.md | 2 +- docs/cli-reference/graph.md | 1 + docs/cli-reference/hooks.md | 2 +- docs/cli-reference/human.md | 1 + docs/cli-reference/index.md | 19 +++++++++ docs/cli-reference/init.md | 2 +- docs/cli-reference/jira.md | 2 +- docs/cli-reference/kv.md | 2 +- docs/cli-reference/label.md | 2 +- docs/cli-reference/linear.md | 2 +- docs/cli-reference/mail.md | 2 +- docs/cli-reference/merge-slot.md | 2 +- docs/cli-reference/metrics.md | 1 + docs/cli-reference/migrate.md | 1 + docs/cli-reference/mol.md | 3 +- docs/cli-reference/notion.md | 2 +- docs/cli-reference/repo.md | 2 +- docs/cli-reference/rules.md | 2 +- docs/cli-reference/state.md | 1 + docs/cli-reference/swarm.md | 2 +- docs/cli-reference/todo.md | 1 + docs/cli-reference/upgrade.md | 2 +- docs/cli-reference/vc.md | 2 +- docs/cli-reference/worktree.md | 2 +- scripts/check-cli-docs-drift.sh | 7 +++- tools/docsmint/docsmint.go | 31 +++++++++++++++ tools/docsmint/docsmint_test.go | 51 ++++++++++++++++++++++++ 43 files changed, 265 insertions(+), 65 deletions(-) diff --git a/cmd/bd/help_all.go b/cmd/bd/help_all.go index f2ae0da2d..b55fed936 100644 --- a/cmd/bd/help_all.go +++ b/cmd/bd/help_all.go @@ -210,8 +210,21 @@ func writeCommandBody(w io.Writer, cmd *cobra.Command) { fmt.Fprintf(w, "%s\n\n", escapeMDXText(cmd.Short)) } - // Usage - fmt.Fprintf(w, "```\n%s\n```\n\n", strings.TrimRight(cmd.UseLine(), " ")) + // Usage — mirror : a runnable command shows its + // UseLine; a command with subcommands also shows ` [command]`. + // UseLine() alone appends "[flags]" even on non-runnable parents, which + // the binary's help never prints. + var usage []string + if cmd.Runnable() { + usage = append(usage, strings.TrimRight(cmd.UseLine(), " ")) + } + if cmd.HasAvailableSubCommands() { + usage = append(usage, cmd.CommandPath()+" [command]") + } + if len(usage) == 0 { + usage = append(usage, strings.TrimRight(cmd.UseLine(), " ")) + } + fmt.Fprintf(w, "```\n%s\n```\n\n", strings.Join(usage, "\n")) // Aliases if len(cmd.Aliases) > 0 { @@ -298,7 +311,7 @@ func writeGenericCLIDocsDir(outDir string, root *cobra.Command) error { } commands := availableCommandNames(root) - if err := writeMarkdownFile(filepath.Join(outDir, "index.md"), genericCLIReferenceIndex(commands)); err != nil { + if err := writeMarkdownFile(filepath.Join(outDir, "index.md"), genericCLIReferenceIndex(root, commands)); err != nil { return err } @@ -316,7 +329,7 @@ func writeGenericCLIDocsDir(outDir string, root *cobra.Command) error { return nil } -func genericCLIReferenceIndex(commands []string) string { +func genericCLIReferenceIndex(root *cobra.Command, commands []string) string { var b strings.Builder fmt.Fprintf(&b, "---\n") fmt.Fprintf(&b, "title: CLI Reference\n") @@ -328,6 +341,13 @@ func genericCLIReferenceIndex(commands []string) string { fmt.Fprintf(&b, "```bash\n") fmt.Fprintf(&b, "./scripts/generate-cli-docs.sh\n") fmt.Fprintf(&b, "```\n\n") + // The per-command pages list only local flags, mirroring `--help`; the + // global flags apply everywhere and are published once, here. + if root.PersistentFlags().HasFlags() { + fmt.Fprintf(&b, "## Global Flags\n\n") + fmt.Fprintf(&b, "These flags apply to all commands:\n\n") + fmt.Fprintf(&b, "```\n%s```\n\n", root.PersistentFlags().FlagUsages()) + } fmt.Fprintf(&b, "## Commands\n\n") for _, cmd := range commands { fmt.Fprintf(&b, "- [`bd %s`](./%s.md)\n", cmd, commandDocID(cmd)) diff --git a/cmd/bd/help_all_test.go b/cmd/bd/help_all_test.go index d5cf37b5d..aa5d8f257 100644 --- a/cmd/bd/help_all_test.go +++ b/cmd/bd/help_all_test.go @@ -167,6 +167,64 @@ func TestHelpDocFlagTextDoesNotClaimDashMeansStdout(t *testing.T) { } } +// Parent commands must document the usage line the binary actually prints: +// Cobra shows `bd mol [command]` for a non-runnable parent (and both lines +// for a runnable one), while UseLine() alone yields the misleading +// `bd mol [flags]` (reproduced against the live binary on 30 pages). +func TestCommandBodyUsageMatchesCobraForParentCommands(t *testing.T) { + root := &cobra.Command{Use: "bd"} + mol := &cobra.Command{Use: "mol", Short: "Molecule commands"} // no Run: not runnable + mol.AddCommand(testHelpCmd("pour ", "Start a workflow")) + root.AddCommand(mol) + + var out bytes.Buffer + if err := writeSingleCommandDoc(&out, root, "mol"); err != nil { + t.Fatalf("writeSingleCommandDoc() error = %v", err) + } + got := out.String() + + if !strings.Contains(got, "bd mol [command]") { + t.Errorf("parent usage missing 'bd mol [command]':\n%s", got) + } + if strings.Contains(got, "bd mol [flags]") { + t.Errorf("parent usage shows 'bd mol [flags]', which the binary never prints:\n%s", got) + } + + // A runnable command with subcommands gets both lines, like Cobra help. + root2 := &cobra.Command{Use: "bd"} + mail := testHelpCmd("mail [subcommand]", "Mail commands") + mail.AddCommand(testHelpCmd("inbox", "List inbox")) + root2.AddCommand(mail) + + out.Reset() + if err := writeSingleCommandDoc(&out, root2, "mail"); err != nil { + t.Fatalf("writeSingleCommandDoc() error = %v", err) + } + got = out.String() + if !strings.Contains(got, "bd mail [subcommand]") { + t.Errorf("runnable parent should keep its UseLine:\n%s", got) + } + if !strings.Contains(got, "bd mail [command]") { + t.Errorf("runnable parent should also show the [command] form:\n%s", got) + } +} + +// The generated index must publish the global (persistent) flags — the +// binary prints them on every --help, and no per-command page carries them. +func TestGenericIndexIncludesGlobalFlags(t *testing.T) { + root := &cobra.Command{Use: "bd"} + root.PersistentFlags().Bool("json", false, "JSON output for scripting") + root.AddCommand(testHelpCmd("show ", "Show an issue")) + dir := t.TempDir() + + if err := writeGeneratedCLIDocs(root, dir); err != nil { + t.Fatalf("writeGeneratedCLIDocs() error = %v", err) + } + indexPath := filepath.Join(dir, "build", "cli-docs", "index.md") + assertFileContains(t, indexPath, "## Global Flags") + assertFileContains(t, indexPath, "--json") +} + func TestWriteGeneratedCLIDocsWritesGenericStagingTree(t *testing.T) { root := &cobra.Command{Use: "bd"} mol := testHelpCmd("mol", "Molecule commands") diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 170e49a1a..5bedc4b04 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -429,6 +429,7 @@ Examples: ``` bd comments [issue-id] [flags] +bd comments [command] ``` **Flags:** @@ -645,7 +646,7 @@ Examples: bd gate resolve <id> # Close a gate manually ``` -bd gate +bd gate [command] ``` #### bd gate add-waiter @@ -849,7 +850,7 @@ bd heartbeat Manage issue labels ``` -bd label +bd label [command] ``` #### bd label add @@ -1007,7 +1008,7 @@ Examples: bd merge-slot release # Release the slot ``` -bd merge-slot +bd merge-slot [command] ``` #### bd merge-slot acquire @@ -1422,6 +1423,7 @@ Examples: ``` bd state +bd state [command] ``` #### bd state list @@ -1469,6 +1471,7 @@ TODOs can be promoted to full issues by changing type or priority: ``` bd todo +bd todo [command] ``` #### bd todo add @@ -1883,6 +1886,7 @@ Examples: ``` bd dep [issue-id] [flags] +bd dep [command] ``` **Flags:** @@ -2093,7 +2097,7 @@ bd duplicates [flags] Epic management commands ``` -bd epic +bd epic [command] ``` #### bd epic close-eligible @@ -2157,6 +2161,7 @@ Examples: ``` bd graph [issue-id] [flags] +bd graph [command] ``` **Flags:** @@ -2207,7 +2212,7 @@ A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work. ``` -bd swarm +bd swarm [command] ``` #### bd swarm create @@ -2337,7 +2342,7 @@ DoltHub is recommended for cloud backup: Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication. ``` -bd backup +bd backup [command] ``` #### bd backup init @@ -2614,7 +2619,7 @@ Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access. This subcommand provides additional operations like merge and commit. ``` -bd vc +bd vc [command] ``` #### bd vc commit @@ -2787,7 +2792,7 @@ Examples: bd config unset jira.url ``` -bd config +bd config [command] ``` #### bd config apply @@ -3012,7 +3017,7 @@ Examples: bd dolt test ``` -bd dolt +bd dolt [command] ``` #### bd dolt clean-databases @@ -3131,7 +3136,7 @@ Subcommands: remove <name> Remove a remote ``` -bd dolt remote +bd dolt remote [command] ``` ##### bd dolt remote add @@ -3288,7 +3293,7 @@ The hooks provide: - prepare-commit-msg: Add agent identity trailers for forensics ``` -bd hooks +bd hooks [command] ``` #### bd hooks install @@ -3375,6 +3380,7 @@ SUBCOMMANDS: ``` bd human +bd human [command] ``` #### bd human dismiss @@ -3490,7 +3496,7 @@ and its storage (a Dolt database by default). Optionally specify a custom issue Dolt is the default backend and the only one with version control (history, branching, sync). Select an alternative with --backend=<postgres|mysql|sqlite>; -see docs/STORAGE-BACKENDS.md for the trade-offs and setup. +see docs/architecture/storage-backends.md for the trade-offs and setup. Use --database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) @@ -3592,7 +3598,7 @@ Examples: bd kv list # List all key-value pairs ``` -bd kv +bd kv [command] ``` #### bd kv clear @@ -4198,6 +4204,7 @@ BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use. ``` bd migrate [flags] +bd migrate [command] ``` **Flags:** @@ -4532,7 +4539,7 @@ bd rename-prefix [flags] Audit and compact Claude rules ``` -bd rules +bd rules [command] ``` #### bd rules audit @@ -4607,7 +4614,7 @@ The upgrade command helps you stay aware of bd version changes: Version tracking is automatic - bd updates metadata.json on every run. ``` -bd upgrade +bd upgrade [command] ``` #### bd upgrade ack @@ -4680,7 +4687,7 @@ Examples: bd worktree info # Show info about current worktree ``` -bd worktree +bd worktree [command] ``` #### bd worktree create @@ -4785,7 +4792,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations. ``` -bd admin +bd admin [command] ``` #### bd admin cleanup @@ -4950,7 +4957,7 @@ Examples: bd jira status # Show sync status ``` -bd jira +bd jira [command] ``` #### bd jira pull @@ -5103,7 +5110,7 @@ Examples: bd linear status # Show sync status ``` -bd linear +bd linear [command] ``` #### bd linear pull @@ -5278,7 +5285,7 @@ Examples: bd repo sync # Sync from all configured repos ``` -bd repo +bd repo [command] ``` #### bd repo add @@ -5373,7 +5380,7 @@ Configuration can be set via 'bd config' or environment variables: ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem) ``` -bd ado +bd ado [command] ``` #### bd ado projects @@ -5486,7 +5493,7 @@ bd history <id> --events. The JSONL sidecar is for explicit interaction ca Entries are append-only. Labeling creates a new "label" entry that references a parent entry. ``` -bd audit +bd audit [command] ``` #### bd audit label @@ -5547,7 +5554,7 @@ See each sub-command's help for details on how to use the generated script. ``` -bd completion +bd completion [command] ``` #### bd completion bash @@ -5784,10 +5791,10 @@ Discovering primitives: bd formula schema loop # show LoopSpec fields, types, and tags bd formula primitives gate # alias; same handler as 'schema' examples/formulas/primitives/ # curated, smoke-tested wired fixtures - website/docs/workflows/formulas.md # narrative reference + docs/workflows/formulas.md # narrative reference ``` -bd formula +bd formula [command] ``` #### bd formula convert @@ -5911,7 +5918,7 @@ Configuration can be set via 'bd config' or environment variables: github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise) ``` -bd github +bd github [command] ``` #### bd github pull @@ -6003,7 +6010,7 @@ Configuration can be set via 'bd config' or environment variables: gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode ``` -bd gitlab +bd gitlab [command] ``` #### bd gitlab projects @@ -6227,6 +6234,7 @@ any user-supplied text. ``` bd metrics +bd metrics [command] ``` #### bd metrics example @@ -6279,7 +6287,7 @@ Commands: Use "bd formula list" to list available formulas. ``` -bd mol +bd mol [command] ``` **Aliases:** protomolecule @@ -6739,6 +6747,7 @@ Subcommands: ``` bd mol wisp [proto-id] [flags] +bd mol wisp [command] ``` **Flags:** @@ -6868,7 +6877,7 @@ bd mol wisp list [flags] Commands for syncing issues between beads and Notion. ``` -bd notion +bd notion [command] ``` #### bd notion connect diff --git a/docs/cli-reference/admin.md b/docs/cli-reference/admin.md index 644812350..4ae453c44 100644 --- a/docs/cli-reference/admin.md +++ b/docs/cli-reference/admin.md @@ -18,7 +18,7 @@ For routine maintenance, prefer 'bd doctor --fix' which handles common repairs automatically. Use these admin commands for targeted database operations. ``` -bd admin [flags] +bd admin [command] ``` ## bd admin cleanup diff --git a/docs/cli-reference/ado.md b/docs/cli-reference/ado.md index ba87cc1dc..f70320b24 100644 --- a/docs/cli-reference/ado.md +++ b/docs/cli-reference/ado.md @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: ado.url / AZURE_DEVOPS_URL - Custom base URL (on-prem) ``` -bd ado [flags] +bd ado [command] ``` ## bd ado projects diff --git a/docs/cli-reference/audit.md b/docs/cli-reference/audit.md index b22410ba1..c98cbc609 100644 --- a/docs/cli-reference/audit.md +++ b/docs/cli-reference/audit.md @@ -16,7 +16,7 @@ Each line is one event. This file is intended to be versioned in git and used fo Entries are append-only. Labeling creates a new "label" entry that references a parent entry. ``` -bd audit [flags] +bd audit [command] ``` ## bd audit label diff --git a/docs/cli-reference/backup.md b/docs/cli-reference/backup.md index 6bd6b0722..eed664b20 100644 --- a/docs/cli-reference/backup.md +++ b/docs/cli-reference/backup.md @@ -26,7 +26,7 @@ DoltHub is recommended for cloud backup: Set DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD for authentication. ``` -bd backup [flags] +bd backup [command] ``` ## bd backup init diff --git a/docs/cli-reference/comments.md b/docs/cli-reference/comments.md index ccb3390f0..1ec06f612 100644 --- a/docs/cli-reference/comments.md +++ b/docs/cli-reference/comments.md @@ -24,6 +24,7 @@ Examples: ``` bd comments [issue-id] [flags] +bd comments [command] ``` **Flags:** diff --git a/docs/cli-reference/completion.md b/docs/cli-reference/completion.md index d72448ad0..53cc05b50 100644 --- a/docs/cli-reference/completion.md +++ b/docs/cli-reference/completion.md @@ -12,7 +12,7 @@ See each sub-command's help for details on how to use the generated script. ``` -bd completion [flags] +bd completion [command] ``` ## bd completion bash diff --git a/docs/cli-reference/config.md b/docs/cli-reference/config.md index 37f42f445..f82e81381 100644 --- a/docs/cli-reference/config.md +++ b/docs/cli-reference/config.md @@ -79,7 +79,7 @@ Examples: bd config unset jira.url ``` -bd config [flags] +bd config [command] ``` ## bd config apply diff --git a/docs/cli-reference/dep.md b/docs/cli-reference/dep.md index 998752957..dc6498c1c 100644 --- a/docs/cli-reference/dep.md +++ b/docs/cli-reference/dep.md @@ -21,6 +21,7 @@ Examples: ``` bd dep [issue-id] [flags] +bd dep [command] ``` **Flags:** diff --git a/docs/cli-reference/dolt.md b/docs/cli-reference/dolt.md index 17c2c0486..b331113f5 100644 --- a/docs/cli-reference/dolt.md +++ b/docs/cli-reference/dolt.md @@ -50,7 +50,7 @@ Examples: bd dolt test ``` -bd dolt [flags] +bd dolt [command] ``` ## bd dolt clean-databases @@ -169,7 +169,7 @@ Subcommands: remove <name> Remove a remote ``` -bd dolt remote [flags] +bd dolt remote [command] ``` ### bd dolt remote add diff --git a/docs/cli-reference/epic.md b/docs/cli-reference/epic.md index 9fe61582e..d91337256 100644 --- a/docs/cli-reference/epic.md +++ b/docs/cli-reference/epic.md @@ -10,7 +10,7 @@ Generated from `bd help --doc epic`. Epic management commands ``` -bd epic [flags] +bd epic [command] ``` ## bd epic close-eligible diff --git a/docs/cli-reference/formula.md b/docs/cli-reference/formula.md index 46e7879cc..49517015b 100644 --- a/docs/cli-reference/formula.md +++ b/docs/cli-reference/formula.md @@ -28,10 +28,10 @@ Discovering primitives: bd formula schema loop # show LoopSpec fields, types, and tags bd formula primitives gate # alias; same handler as 'schema' examples/formulas/primitives/ # curated, smoke-tested wired fixtures - website/docs/workflows/formulas.md # narrative reference + docs/workflows/formulas.md # narrative reference ``` -bd formula [flags] +bd formula [command] ``` ## bd formula convert diff --git a/docs/cli-reference/gate.md b/docs/cli-reference/gate.md index fd3fc4ccd..f58342dd6 100644 --- a/docs/cli-reference/gate.md +++ b/docs/cli-reference/gate.md @@ -29,7 +29,7 @@ Examples: bd gate resolve <id> # Close a gate manually ``` -bd gate [flags] +bd gate [command] ``` ## bd gate add-waiter diff --git a/docs/cli-reference/github.md b/docs/cli-reference/github.md index f6b75e26a..aaace89c0 100644 --- a/docs/cli-reference/github.md +++ b/docs/cli-reference/github.md @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: github.url / GITHUB_API_URL - Custom API URL (GitHub Enterprise) ``` -bd github [flags] +bd github [command] ``` ## bd github pull diff --git a/docs/cli-reference/gitlab.md b/docs/cli-reference/gitlab.md index 175949709..3697ba2b9 100644 --- a/docs/cli-reference/gitlab.md +++ b/docs/cli-reference/gitlab.md @@ -17,7 +17,7 @@ Configuration can be set via 'bd config' or environment variables: gitlab.default_project_id / GITLAB_DEFAULT_PROJECT_ID - Project for creating issues in group mode ``` -bd gitlab [flags] +bd gitlab [command] ``` ## bd gitlab projects diff --git a/docs/cli-reference/graph.md b/docs/cli-reference/graph.md index 4d1b53bac..149e17919 100644 --- a/docs/cli-reference/graph.md +++ b/docs/cli-reference/graph.md @@ -38,6 +38,7 @@ Examples: ``` bd graph [issue-id] [flags] +bd graph [command] ``` **Flags:** diff --git a/docs/cli-reference/hooks.md b/docs/cli-reference/hooks.md index 00b281d4f..148d9a66d 100644 --- a/docs/cli-reference/hooks.md +++ b/docs/cli-reference/hooks.md @@ -17,7 +17,7 @@ The hooks provide: - prepare-commit-msg: Add agent identity trailers for forensics ``` -bd hooks [flags] +bd hooks [command] ``` ## bd hooks install diff --git a/docs/cli-reference/human.md b/docs/cli-reference/human.md index 1395d4d28..949dcf47d 100644 --- a/docs/cli-reference/human.md +++ b/docs/cli-reference/human.md @@ -22,6 +22,7 @@ SUBCOMMANDS: ``` bd human [flags] +bd human [command] ``` ## bd human dismiss diff --git a/docs/cli-reference/index.md b/docs/cli-reference/index.md index 93da3625a..d67edebf5 100644 --- a/docs/cli-reference/index.md +++ b/docs/cli-reference/index.md @@ -13,6 +13,25 @@ This reference covers all 112 live top-level `bd` commands. Regenerate it with: ./scripts/generate-cli-docs.sh ``` +## Global Flags + +These flags apply to all commands: + +``` + --actor string Actor name for audit trail (default: $BEADS_ACTOR, git user.name, $USER) + --db string Database path (default: auto-discover .beads/*.db) + -C, --directory string Change to this directory before running the command (like git -C) + --dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit + --global Use the global shared-server database (beads_global) + --ignore-schema-skew Proceed despite forward schema drift (some queries may fail) + --json Output in JSON format + --profile Generate CPU profile for performance analysis + -q, --quiet Suppress non-essential output (errors only) + --readonly Read-only mode: block write operations (for worker sandboxes) + --sandbox Sandbox mode: disables Dolt auto-push + -v, --verbose Enable verbose/debug output +``` + ## Commands - [`bd admin`](/cli-reference/admin) diff --git a/docs/cli-reference/init.md b/docs/cli-reference/init.md index db50607b8..092da4f57 100644 --- a/docs/cli-reference/init.md +++ b/docs/cli-reference/init.md @@ -12,7 +12,7 @@ and its storage (a Dolt database by default). Optionally specify a custom issue Dolt is the default backend and the only one with version control (history, branching, sync). Select an alternative with --backend=<postgres|mysql|sqlite>; -see docs/STORAGE-BACKENDS.md for the trade-offs and setup. +see docs/architecture/storage-backends.md for the trade-offs and setup. Use --database to specify an existing server database name, overriding the default prefix-based naming. This is useful when an external tool (e.g. an orchestrator) diff --git a/docs/cli-reference/jira.md b/docs/cli-reference/jira.md index 881bc6070..d069f7d14 100644 --- a/docs/cli-reference/jira.md +++ b/docs/cli-reference/jira.md @@ -31,7 +31,7 @@ Examples: bd jira status # Show sync status ``` -bd jira [flags] +bd jira [command] ``` ## bd jira pull diff --git a/docs/cli-reference/kv.md b/docs/cli-reference/kv.md index 5ff572ff8..502d8b6af 100644 --- a/docs/cli-reference/kv.md +++ b/docs/cli-reference/kv.md @@ -19,7 +19,7 @@ Examples: bd kv list # List all key-value pairs ``` -bd kv [flags] +bd kv [command] ``` ## bd kv clear diff --git a/docs/cli-reference/label.md b/docs/cli-reference/label.md index 34fdf95c8..f59cfebae 100644 --- a/docs/cli-reference/label.md +++ b/docs/cli-reference/label.md @@ -10,7 +10,7 @@ Generated from `bd help --doc label`. Manage issue labels ``` -bd label [flags] +bd label [command] ``` ## bd label add diff --git a/docs/cli-reference/linear.md b/docs/cli-reference/linear.md index 73c3084af..9445a8715 100644 --- a/docs/cli-reference/linear.md +++ b/docs/cli-reference/linear.md @@ -70,7 +70,7 @@ Examples: bd linear status # Show sync status ``` -bd linear [flags] +bd linear [command] ``` ## bd linear pull diff --git a/docs/cli-reference/mail.md b/docs/cli-reference/mail.md index 817b06c6e..e6d967135 100644 --- a/docs/cli-reference/mail.md +++ b/docs/cli-reference/mail.md @@ -19,7 +19,7 @@ Configuration (checked in order): Examples: # Configure delegation (one-time setup) - export BEADS_MAIL_DELEGATE="gt mail" + `export BEADS_MAIL_DELEGATE="gt mail"` # or bd config set mail.delegate "gt mail" diff --git a/docs/cli-reference/merge-slot.md b/docs/cli-reference/merge-slot.md index c7d8f62ec..dc23dab57 100644 --- a/docs/cli-reference/merge-slot.md +++ b/docs/cli-reference/merge-slot.md @@ -27,7 +27,7 @@ Examples: bd merge-slot release # Release the slot ``` -bd merge-slot [flags] +bd merge-slot [command] ``` ## bd merge-slot acquire diff --git a/docs/cli-reference/metrics.md b/docs/cli-reference/metrics.md index e01464b80..f53b4b3da 100644 --- a/docs/cli-reference/metrics.md +++ b/docs/cli-reference/metrics.md @@ -22,6 +22,7 @@ any user-supplied text. ``` bd metrics [flags] +bd metrics [command] ``` ## bd metrics example diff --git a/docs/cli-reference/migrate.md b/docs/cli-reference/migrate.md index ed59998c9..62ea887ec 100644 --- a/docs/cli-reference/migrate.md +++ b/docs/cli-reference/migrate.md @@ -27,6 +27,7 @@ BD_ALLOW_REMOTE_MIGRATE=1 remains supported for scripted/CI use. ``` bd migrate [flags] +bd migrate [command] ``` **Flags:** diff --git a/docs/cli-reference/mol.md b/docs/cli-reference/mol.md index 4f6a0b0e6..5a317f664 100644 --- a/docs/cli-reference/mol.md +++ b/docs/cli-reference/mol.md @@ -31,7 +31,7 @@ Commands: Use "bd formula list" to list available formulas. ``` -bd mol [flags] +bd mol [command] ``` **Aliases:** protomolecule @@ -491,6 +491,7 @@ Subcommands: ``` bd mol wisp [proto-id] [flags] +bd mol wisp [command] ``` **Flags:** diff --git a/docs/cli-reference/notion.md b/docs/cli-reference/notion.md index 774f7bd56..3670b3623 100644 --- a/docs/cli-reference/notion.md +++ b/docs/cli-reference/notion.md @@ -10,7 +10,7 @@ Generated from `bd help --doc notion`. Commands for syncing issues between beads and Notion. ``` -bd notion [flags] +bd notion [command] ``` ## bd notion connect diff --git a/docs/cli-reference/repo.md b/docs/cli-reference/repo.md index 6e428212f..c9a4e5794 100644 --- a/docs/cli-reference/repo.md +++ b/docs/cli-reference/repo.md @@ -28,7 +28,7 @@ Examples: bd repo sync # Sync from all configured repos ``` -bd repo [flags] +bd repo [command] ``` ## bd repo add diff --git a/docs/cli-reference/rules.md b/docs/cli-reference/rules.md index c1c1bbf68..1fc721bbc 100644 --- a/docs/cli-reference/rules.md +++ b/docs/cli-reference/rules.md @@ -10,7 +10,7 @@ Generated from `bd help --doc rules`. Audit and compact Claude rules ``` -bd rules [flags] +bd rules [command] ``` ## bd rules audit diff --git a/docs/cli-reference/state.md b/docs/cli-reference/state.md index 280c6829c..291da54fa 100644 --- a/docs/cli-reference/state.md +++ b/docs/cli-reference/state.md @@ -23,6 +23,7 @@ Examples: ``` bd state [flags] +bd state [command] ``` ## bd state list diff --git a/docs/cli-reference/swarm.md b/docs/cli-reference/swarm.md index 697d95a59..c4efdf0a4 100644 --- a/docs/cli-reference/swarm.md +++ b/docs/cli-reference/swarm.md @@ -13,7 +13,7 @@ A swarm is a structured body of work defined by an epic and its children, with dependencies forming a DAG (directed acyclic graph) of work. ``` -bd swarm [flags] +bd swarm [command] ``` ## bd swarm create diff --git a/docs/cli-reference/todo.md b/docs/cli-reference/todo.md index c250ef536..ba57af7a1 100644 --- a/docs/cli-reference/todo.md +++ b/docs/cli-reference/todo.md @@ -19,6 +19,7 @@ TODOs can be promoted to full issues by changing type or priority: ``` bd todo [flags] +bd todo [command] ``` ## bd todo add diff --git a/docs/cli-reference/upgrade.md b/docs/cli-reference/upgrade.md index b245947be..4d9367548 100644 --- a/docs/cli-reference/upgrade.md +++ b/docs/cli-reference/upgrade.md @@ -17,7 +17,7 @@ The upgrade command helps you stay aware of bd version changes: Version tracking is automatic - bd updates metadata.json on every run. ``` -bd upgrade [flags] +bd upgrade [command] ``` ## bd upgrade ack diff --git a/docs/cli-reference/vc.md b/docs/cli-reference/vc.md index b486a226d..6bb01ffd6 100644 --- a/docs/cli-reference/vc.md +++ b/docs/cli-reference/vc.md @@ -16,7 +16,7 @@ Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access. This subcommand provides additional operations like merge and commit. ``` -bd vc [flags] +bd vc [command] ``` ## bd vc commit diff --git a/docs/cli-reference/worktree.md b/docs/cli-reference/worktree.md index 18b45d901..649eced2a 100644 --- a/docs/cli-reference/worktree.md +++ b/docs/cli-reference/worktree.md @@ -23,7 +23,7 @@ Examples: bd worktree info # Show info about current worktree ``` -bd worktree [flags] +bd worktree [command] ``` ## bd worktree create diff --git a/scripts/check-cli-docs-drift.sh b/scripts/check-cli-docs-drift.sh index 1194206f3..ff4631685 100755 --- a/scripts/check-cli-docs-drift.sh +++ b/scripts/check-cli-docs-drift.sh @@ -172,8 +172,11 @@ fi if git -C "$W_HEAD" diff --quiet; then echo "PASS: committed docs are fresh under the canonical pinned build." - echo "(The strict probe failed only because the supplied bd binary differs" - echo " from the canonical one. Build with: CGO_ENABLED=0 go build -tags gms_pure_go)" + echo "(The strict probe failed for a reason that does not affect committed state:" + echo " either the supplied bd binary differs from the canonical pinned build" + echo " [CGO_ENABLED=0 go build -tags gms_pure_go], or uncommitted local edits" + echo " to generated docs made the working tree diverge. Attribution compares" + echo " committed states only - commit local changes before relying on it.)" exit 0 fi diff --git a/tools/docsmint/docsmint.go b/tools/docsmint/docsmint.go index 9f46c41f3..6a2ba5b36 100644 --- a/tools/docsmint/docsmint.go +++ b/tools/docsmint/docsmint.go @@ -74,9 +74,40 @@ func run(root string) error { func transformPage(content string) string { content = htmlCommentRE.ReplaceAllString(content, "{/* $1 */}") content = relativePageLinkRE.ReplaceAllString(content, "](/cli-reference/$1)") + content = neutralizeESMHazards(content) return content } +// neutralizeESMHazards wraps prose lines whose first token is `export` or +// `import` in inline code spans. Such lines are legal CommonMark in bd's +// generic output (indented example lines in help text), but Mintlify's +// prebuild dedents them to column 0 and then parses them as MDX ESM blocks, +// which fails the entire page (observed on cli-reference/mail). Lines inside +// code fences are left untouched. +func neutralizeESMHazards(content string) string { + lines := strings.Split(content, "\n") + inFence := false + for i, line := range lines { + trimmed := strings.TrimSpace(line) + if strings.HasPrefix(trimmed, "```") { + inFence = !inFence + continue + } + if inFence { + continue + } + if strings.HasPrefix(trimmed, "export ") || strings.HasPrefix(trimmed, "import ") { + indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))] + delim := "`" + if strings.Contains(trimmed, "`") { + delim = "``" + } + lines[i] = indent + delim + trimmed + delim + } + } + return strings.Join(lines, "\n") +} + func removeMarkdownFiles(dir string) error { entries, err := os.ReadDir(dir) if err != nil { diff --git a/tools/docsmint/docsmint_test.go b/tools/docsmint/docsmint_test.go index a5e0991d5..6db3682b1 100644 --- a/tools/docsmint/docsmint_test.go +++ b/tools/docsmint/docsmint_test.go @@ -169,6 +169,57 @@ func TestRunSplicesNavAndPreservesOtherGroups(t *testing.T) { } } +// Mintlify's prebuild re-serializes markdown and dedents indented prose, so a +// line whose first token is `export` or `import` — legal CommonMark in bd's +// generic output — lands at column 0 and gets parsed as an MDX ESM block, +// failing the whole page (reproduced on /cli-reference/mail). docsmint must +// neutralize such lines outside code fences. +func TestRunNeutralizesMDXESMHazardLines(t *testing.T) { + root := t.TempDir() + seedStaging(t, root) + writeFile(t, filepath.Join(root, "build", "cli-docs", "mail.md"), `--- +title: "bd mail" +--- + +Examples: + # Configure delegation (one-time setup) + export BEADS_MAIL_DELEGATE="gt mail" + # or + import something-that-looks-like-esm + +`+"```"+` + export FENCED_STAYS_VERBATIM=1 +`+"```"+` +`) + + if err := run(root); err != nil { + t.Fatalf("run() error = %v", err) + } + + data, err := os.ReadFile(filepath.Join(root, "docs", "cli-reference", "mail.md")) + if err != nil { + t.Fatal(err) + } + + inFence := false + for i, line := range strings.Split(string(data), "\n") { + if strings.HasPrefix(strings.TrimSpace(line), "```") { + inFence = !inFence + continue + } + trimmed := strings.TrimSpace(line) + if !inFence && (strings.HasPrefix(trimmed, "export ") || strings.HasPrefix(trimmed, "import ")) { + t.Errorf("line %d is a bare ESM-hazard outside a fence: %q", i+1, line) + } + } + if !strings.Contains(string(data), `export BEADS_MAIL_DELEGATE="gt mail"`) { + t.Errorf("hazard line content was lost, not neutralized:\n%s", data) + } + if !strings.Contains(string(data), " export FENCED_STAYS_VERBATIM=1") { + t.Errorf("fenced export line must stay verbatim:\n%s", data) + } +} + func TestRunRemovesStaleTargetPages(t *testing.T) { root := t.TempDir() seedStaging(t, root)