Merge pull request #2526 from maphew/fix/docs-purge-stale-refs

fix(docs): purge stale command/flag refs + add CI doc validation (GH#2522)

Author: steveyegge

.github/workflows/ci.yml

@@ -17,6 +17,24 @@ jobs:
       - name: Check all versions match
         run: ./scripts/check-versions.sh
 
+  # Check documentation references match actual CLI flags
+  check-doc-flags:
+    name: Check doc flags freshness
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Go
+        uses: actions/setup-go@v6
+        with:
+          go-version-file: 'go.mod'
+
+      - name: Build bd
+        run: CGO_ENABLED=0 go build -o bd ./cmd/bd/
+
+      - name: Validate docs against CLI
+        run: ./scripts/check-doc-flags.sh ./bd
+
   # Fast check to catch accidental .beads/issues.jsonl changes from contributors
   check-no-beads-changes:
     name: Check for .beads changes

AGENT_INSTRUCTIONS.md

@@ -93,9 +93,9 @@ bd hooks install
 
 ### Git Integration
 
-**Dolt sync**: Dolt handles sync natively via `bd sync`. No JSONL export/import needed.
+**Dolt sync**: Dolt handles sync natively via `bd dolt push` / `bd dolt pull`. No JSONL export/import needed.
 
-**Protected branches**: Use `bd init --branch beads-metadata` to commit to separate branch. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
+**Protected branches**: Dolt stores data under `refs/dolt/data`, separate from standard Git refs. See [docs/PROTECTED_BRANCHES.md](docs/PROTECTED_BRANCHES.md).
 
 **Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md).
 

Makefile

@@ -160,6 +160,10 @@ fmt-check:
 	fi
 	@echo "All Go files are properly formatted"
 
+# Validate documentation references against actual CLI flags
+check-docs: build
+	@./scripts/check-doc-flags.sh ./bd
+
 # Clean build artifacts and benchmark profiles
 clean:
 	@echo "Cleaning..."
@@ -181,5 +185,6 @@ help:
 	@echo "  make install-force - Install bd, skipping the origin/main update check"
 	@echo "  make fmt          - Format all Go files with gofmt"
 	@echo "  make fmt-check    - Check Go formatting (for CI)"
+	@echo "  make check-docs   - Validate docs against CLI flags"
 	@echo "  make clean        - Remove build artifacts and profile files"
 	@echo "  make help         - Show this help message"

claude-plugin/commands/audit.md

@@ -23,6 +23,6 @@ Each line is one event. Labeling is done by appending a new `"label"` event refe
 ## Notes
 
 - Audit entries are **append-only** (no in-place edits).
-- `bd sync` includes `.beads/interactions.jsonl` in the commit allowlist.
+- `bd dolt push` includes `.beads/interactions.jsonl` in the commit allowlist.
 
 

claude-plugin/commands/import.md

@@ -1,36 +1,18 @@
 ---
-description: Import issues from JSONL format
-argument-hint: [-i input-file]
+description: Import issues from JSONL format (removed)
+argument-hint: (removed)
 ---
 
-Import issues from JSON Lines format (one JSON object per line).
+`bd import` has been **removed**.
 
-## Usage
+## Migration
 
-- **From stdin**: `bd import` (reads from stdin)
-- **From file**: `bd import -i issues.jsonl`
-- **Preview**: `bd import -i issues.jsonl --dry-run`
-
-## Behavior
-
-- **Existing issues** (same ID): Updated with new data
-- **New issues**: Created
-- **Same-ID scenarios**: With hash-based IDs (v0.20.1+), same ID = same issue being updated (not a collision)
-
-## Preview Changes
-
-Use `--dry-run` to see what will change before importing:
+If you need to import issues from a JSONL file, use `bd init` with the `--from-jsonl` flag:
 
 ```bash
-bd import -i issues.jsonl --dry-run
-# Shows: new issues, updates, exact matches
+bd init <prefix> --from-jsonl issues.jsonl
 ```
 
-## When to Use
-
-Dolt is the primary storage backend, so manual import is rarely needed. Use `bd import` when you need to load data from an external JSONL file or migrate from a legacy JSONL-based setup.
-
-## Options
+## Note
 
-- **--skip-existing**: Skip updates to existing issues
-- **--strict**: Fail on dependency errors instead of warnings
+Dolt is the primary storage backend. Manual JSONL import is no longer supported as a standalone command.

claude-plugin/commands/workflow.md

@@ -39,7 +39,7 @@ After closing, check if other work became ready:
 - **Priority levels**: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
 - **Issue types**: bug, feature, task, epic, chore
 - **Dependencies**: Use `blocks` for hard dependencies, `related` for soft links
-- **Auto-sync**: Changes are stored in Dolt and synced via `bd sync`
+- **Auto-sync**: Changes are stored in Dolt and synced via `bd dolt push` / `bd dolt pull`
 
 ## Available Commands
 - `/beads:ready` - Find unblocked work

claude-plugin/skills/beads/resources/CLI_REFERENCE.md

@@ -467,37 +467,7 @@ bd rename-prefix kw- --json     # Apply rename
 
 ### Import/Export
 
-```bash
-# Import issues from JSONL
-bd import -i .beads/issues.jsonl --dry-run      # Preview changes
-bd import -i .beads/issues.jsonl                # Import and update issues
-bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
-
-# Handle missing parents during import
-bd import -i issues.jsonl --orphan-handling allow      # Default: import orphans without validation
-bd import -i issues.jsonl --orphan-handling resurrect  # Auto-resurrect deleted parents as tombstones
-bd import -i issues.jsonl --orphan-handling skip       # Skip orphans with warning
-bd import -i issues.jsonl --orphan-handling strict     # Fail if parent is missing
-
-# Configure default orphan handling behavior
-bd config set import.orphan_handling "resurrect"
-bd sync  # Now uses resurrect mode by default
-```
-
-**Orphan handling modes:**
-
-- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
-- **`resurrect`** - Search history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
-- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
-- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
-
-**When to use:**
-- Use `allow` (default) for daily imports and auto-sync
-- Use `resurrect` when importing from databases with deleted parents
-- Use `strict` for controlled imports requiring guaranteed parent existence
-- Use `skip` rarely - only for selective imports
-
-See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
+> **Note:** `bd import` has been removed. For JSONL migration, use `bd init <prefix> --from-jsonl <file>`.
 
 ### Migration
 
@@ -531,16 +501,15 @@ These invariants prevent data loss and would have caught issues like GH #201 (mi
 ### Sync Operations
 
 ```bash
-# Manual sync (force immediate export/import/commit/push)
-bd sync
-
-# What it does:
-# 1. Commit pending changes to Dolt
-# 2. Pull from remote
-# 3. Merge any updates
-# 4. Push to remote
+# Sync via Dolt commands
+bd dolt push                   # Push changes to remote
+bd dolt pull                   # Pull from remote
+bd dolt commit                 # Commit pending changes
+bd dolt show                   # Check connection status
 ```
 
+> **Note:** `bd sync` is deprecated (now a no-op). Use the Dolt commands above instead.
+
 ## Issue Types
 
 - `bug` - Something broken that needs fixing
@@ -660,10 +629,10 @@ bd update bd-42 --claim --json
 # ... work ...
 
 # End of session (IMPORTANT!)
-bd sync  # Force immediate sync, bypass debounce
+bd dolt push  # Push changes to remote
 ```
 
-**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
+**ALWAYS run `bd dolt push` at end of agent sessions** to ensure changes are pushed to remote.
 
 ## See Also
 

claude-plugin/skills/beads/resources/TROUBLESHOOTING.md

@@ -243,7 +243,7 @@ This is a **known SQLite limitation**, not a bd bug.
 
 3. **Import existing issues (if you have a JSONL backup):**
    ```bash
-   bd import -i issues-backup.jsonl
+   bd init myproject --from-jsonl issues-backup.jsonl
    ```
 
 **Alternative: Use global `~/.beads/` database**

docs/ADVANCED.md

@@ -73,8 +73,8 @@ bd duplicates --auto-merge
 # Preview what would be merged
 bd duplicates --dry-run
 
-# Detect duplicates during import
-bd import -i issues.jsonl --dedupe-after
+# Detect duplicates after initializing from JSONL
+bd init --from-jsonl  # then: bd duplicates
 ```
 
 **How it works:**
@@ -255,25 +255,19 @@ bd vc resolve
 
 ### Understanding Same-ID Scenarios
 
-When you encounter the same ID during import, it's an **update operation**, not a collision:
+When you encounter the same ID during a Dolt pull or database bootstrap, it's an **update operation**, not a collision:
 
 - Hash IDs are content-based and remain stable across updates
 - Same ID + different fields = normal update to existing issue
-- bd automatically applies updates when importing
+- Dolt's cell-level merge resolves updates automatically
 
-**Preview changes before importing:**
+**Bootstrapping from an export:**
 ```bash
-# Preview an import
-bd import -i data.jsonl --dry-run
-
-# Output shows:
-# Exact matches (idempotent): 15
-# New issues: 5
-# Updates: 3
-#
-# Issues to be updated:
-#   bd-a3f2: Fix authentication (changed: priority, status)
-#   bd-b8e1: Add feature (changed: description)
+# Export from one database
+bd export -o data.jsonl
+
+# Bootstrap a new database from the export
+bd init --from-jsonl
 ```
 
 ## Custom Git Hooks

docs/ARCHITECTURE.md

@@ -49,7 +49,7 @@ bd's core design enables a distributed, git-backed issue tracker that feels like
 
 **Dolt for distribution:** Native push/pull to Dolt remotes (DoltHub, S3, GCS). No special sync server needed. Issues travel with your code. Offline work just works.
 
-**Import/export for portability:** `bd import` and `bd export` support JSONL format for data migration, bootstrapping new clones, and interoperability.
+**Export for portability:** `bd export` outputs JSONL format for data migration and interoperability. Use `bd init --from-jsonl` to bootstrap a new database from an export.
 
 ## Write Path
 
@@ -115,18 +115,18 @@ Branch B: bd create "Add Stripe"  → bd-f14c (no collision)
 1. **Issue creation:** Generate random UUID, derive short hash as ID
 2. **Progressive scaling:** IDs start at 4 chars, grow to 5-6 chars as database grows
 3. **Content hashing:** Each issue has a content hash for change detection
-4. **Import merge:** Same ID + different content = update, same ID + same content = skip
+4. **Merge logic:** Same ID + different content = update, same ID + same content = skip
 
 ```
 ┌─────────────────────────────────────────────────────────────────┐
-│                        Import Logic                              │
-│                  (used by bd import for migration)               │
+│                        Merge Logic                               │
+│             (used by Dolt pull and init --from-jsonl)            │
 │                                                                  │
-│  For each issue in import data:                                  │
+│  For each issue in incoming data:                                │
 │    1. Compute content hash                                       │
 │    2. Look up existing issue by ID                               │
 │    3. Compare hashes:                                            │
-│       - Same hash → skip (already imported)                      │
+│       - Same hash → skip (already present)                       │
 │       - Different hash → update (newer version)                  │
 │       - No match → create (new issue)                            │
 └─────────────────────────────────────────────────────────────────┘