docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4)

Replace JSONL storage/sync references with Dolt-native equivalents across
documentation, plugin resources, website docs, agent instructions, and
example READMEs. Preserves legitimate JSONL references (bd import/export
commands, CHANGELOG history, routes.jsonl/interactions.jsonl concepts).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: steveyegge

.agent/workflows/resolve-beads-conflict.md

@@ -1,59 +1,51 @@
 ---
-description: How to resolve merge conflicts in .beads/issues.jsonl
+description: How to resolve merge conflicts in the beads Dolt database
 ---
 
-# Resolving `issues.jsonl` Merge Conflicts
+# Resolving Beads Merge Conflicts
 
-If you encounter a merge conflict in `.beads/issues.jsonl` that doesn't have standard git conflict markers (or if `bd merge` failed automatically), follow this procedure.
+Beads uses Dolt as its storage backend. Dolt handles merges natively using its built-in three-way merge, similar to git.
 
-## 1. Identify the Conflict
-Check if `issues.jsonl` is in conflict:
-```powershell
-git status
-```
+## 1. Check for Conflicts
 
-## 2. Extract the 3 Versions
-Git stores three versions of conflicted files in its index:
-1. Base (common ancestor)
-2. Ours (current branch)
-3. Theirs (incoming branch)
-
-Extract them to temporary files:
-```powershell
-git show :1:.beads/issues.jsonl > beads.base.jsonl
-git show :2:.beads/issues.jsonl > beads.ours.jsonl
-git show :3:.beads/issues.jsonl > beads.theirs.jsonl
+```bash
+bd doctor
+bd sync
 ```
 
-## 3. Run `bd merge` Manually
-Run the `bd merge` tool manually with the `--debug` flag to see what's happening.
-Syntax: `bd merge <output> <base> <ours> <theirs>`
+If `bd sync` reports merge conflicts, Dolt will list the conflicting tables and rows.
+
+## 2. Resolve Conflicts
+
+Dolt provides SQL-based conflict resolution:
+
+```bash
+# View conflicts
+bd sql "SELECT * FROM dolt_conflicts"
 
-```powershell
-bd merge beads.merged.jsonl beads.base.jsonl beads.ours.jsonl beads.theirs.jsonl --debug
+# Resolve by accepting ours or theirs
+bd sql "CALL dolt_conflicts_resolve('--ours')"
+# OR
+bd sql "CALL dolt_conflicts_resolve('--theirs')"
 ```
 
-## 4. Verify the Result
-Check the output of the command.
-- **Exit Code 0**: Success. `beads.merged.jsonl` contains the clean merge.
-- **Exit Code 1**: Conflicts remain. `beads.merged.jsonl` will contain conflict markers. You must edit it manually to resolve them.
+## 3. Verify and Complete
 
-Optionally, verify the content (e.g., check for missing IDs if you suspect data loss).
+```bash
+# Verify the resolution
+bd list --json | head
 
-## 5. Apply the Merge
-Overwrite the conflicted file with the resolved version:
-```powershell
-cp beads.merged.jsonl .beads/issues.jsonl
+# Complete the sync
+bd sync
 ```
 
-## 6. Cleanup and Continue
-Stage the resolved file and continue the merge:
-```powershell
+## Legacy: JSONL Merge Conflicts
+
+If you encounter merge conflicts in `.beads/issues.jsonl` from a legacy setup, import the resolved file:
+
+```bash
+# Resolve the git conflict in the JSONL file manually, then:
+bd import -i .beads/issues.jsonl
 git add .beads/issues.jsonl
 git merge --continue
 ```
-
-## 7. Cleanup Temporary Files
-```powershell
-rm beads.base.jsonl beads.ours.jsonl beads.theirs.jsonl beads.merged.jsonl
-```

.beads/BD_GUIDE.md

@@ -18,7 +18,7 @@ It is auto-generated and version-stamped to track bd upgrades.
 ### Why bd?
 
 - Dependency-aware: Track blockers and relationships between issues
-- Git-friendly: Auto-syncs to JSONL for version control
+- Git-friendly: Dolt provides version control with branching and merging
 - Agent-optimized: JSON output, ready work detection, discovered-from links
 - Prevents duplicate tracking systems and confusion
 
@@ -70,13 +70,13 @@ bd close bd-42 --reason "Completed" --json
 4. **Discover new work?** Create linked issue:
    - `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
 5. **Complete**: `bd close <id> --reason "Done"`
-6. **Commit together**: Always commit the `.beads/issues.jsonl` file together with the code changes so issue state stays in sync with code state
+6. **Sync**: Run `bd sync` at end of sessions to ensure changes are committed and pushed
 
 ### Auto-Sync
 
-bd automatically syncs with git:
-- Exports to `.beads/issues.jsonl` after changes (5s debounce)
-- Imports from JSONL when newer (e.g., after `git pull`)
+bd uses Dolt for storage and sync:
+- All changes are stored directly in the Dolt database
+- `bd sync` handles commit, pull, merge, and push via Dolt-native replication
 - No manual export/import needed!
 
 ### GitHub Copilot Integration
@@ -156,15 +156,15 @@ For more details, see README.md and QUICKSTART.md.
 
 **Key Features:**
 - Dependency-aware issue tracking
-- Auto-sync with Git via JSONL
+- Auto-sync via Dolt-native replication
 - AI-optimized CLI with JSON output
-- Built-in daemon for background operations
+- Dolt server mode for background operations
 - MCP server integration for Claude and other AI assistants
 
 ## Tech Stack
 
 - **Language**: Go 1.21+
-- **Storage**: SQLite (internal/storage/sqlite/)
+- **Storage**: Dolt (version-controlled SQL database)
 - **CLI Framework**: Cobra
 - **Testing**: Go standard testing + table-driven tests
 - **CI/CD**: GitHub Actions
@@ -174,7 +174,7 @@ For more details, see README.md and QUICKSTART.md.
 
 ### Testing
 - Always write tests for new features
-- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database
+- Use `t.TempDir()` in Go tests to avoid polluting production database
 - Run `go test -short ./...` before committing
 - Never create test issues in production DB (use temporary DB)
 
@@ -185,9 +185,8 @@ For more details, see README.md and QUICKSTART.md.
 - Update docs when changing behavior
 
 ### Git Workflow
-- Always commit `.beads/issues.jsonl` with code changes
 - Run `bd sync` at end of work sessions
-- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency)
+- Install git hooks: `bd hooks install`
 
 ## Issue Tracking with bd
 
@@ -238,14 +237,13 @@ beads/
 ├── internal/
 │   ├── types/           # Core data types
 │   └── storage/         # Storage layer
-│       └── sqlite/      # SQLite implementation
+│       └── dolt/        # Dolt implementation
 ├── integrations/
 │   └── beads-mcp/       # MCP server (Python)
 ├── examples/            # Integration examples
 ├── docs/                # Documentation
 └── .beads/
-    ├── beads.db         # SQLite database (DO NOT COMMIT)
-    └── issues.jsonl     # Git-synced issue storage
+    └── dolt/            # Dolt database (source of truth)
 ```
 
 ## Available Resources
@@ -272,10 +270,10 @@ Use the beads MCP server for native function calls instead of shell commands:
 - ✅ Use bd for ALL task tracking
 - ✅ Always use `--json` flag for programmatic use
 - ✅ Run `bd sync` at end of sessions
-- ✅ Test with `BEADS_DB=/tmp/test.db`
+- ✅ Test with `t.TempDir()` in Go tests
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT create test issues in production DB
-- ❌ Do NOT commit `.beads/beads.db` (JSONL only)
+- ❌ Do NOT manually modify `.beads/dolt/`
 
 ---
 

.beads/README.md

@@ -33,7 +33,7 @@ bd sync
 ### Working with Issues
 
 Issues in Beads are:
-- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **Git-native**: Stored in Dolt database with version control and branching
 - **AI-friendly**: CLI-first design works perfectly with AI coding agents
 - **Branch-aware**: Issues can follow your branch workflow
 - **Always in sync**: Auto-syncs with your commits
@@ -53,7 +53,7 @@ Issues in Beads are:
 🔧 **Git Integration**
 - Automatic sync with git commits
 - Branch-aware issue tracking
-- Intelligent JSONL merge resolution
+- Dolt-native three-way merge resolution
 
 ## Get Started with Beads
 

.github/copilot-instructions.md

@@ -6,15 +6,15 @@
 
 **Key Features:**
 - Dependency-aware issue tracking
-- Auto-sync with Git via JSONL
+- Auto-sync via Dolt-native replication
 - AI-optimized CLI with JSON output
 - Dolt server mode for background operations
 - MCP server integration for Claude and other AI assistants
 
 ## Tech Stack
 
 - **Language**: Go 1.21+
-- **Storage**: Dolt (internal/storage/dolt/)
+- **Storage**: Dolt (version-controlled SQL database)
 - **CLI Framework**: Cobra
 - **Testing**: Go standard testing + table-driven tests
 - **CI/CD**: GitHub Actions
@@ -36,7 +36,7 @@
 
 ### Git Workflow
 - Install git hooks: `bd hooks install`
-- Use `bd dolt push` / `bd dolt pull` for remote sync
+- Use `bd sync` for remote sync (Dolt-native replication)
 
 ## Issue Tracking with bd
 
@@ -59,7 +59,7 @@ bd list --status open --priority 1 --json
 bd show <id> --json
 
 # Sync (if remote configured)
-bd dolt push  # Push to Dolt remote
+bd sync  # Sync with Dolt remote
 ```
 
 ### Workflow
@@ -69,7 +69,7 @@ bd dolt push  # Push to Dolt remote
 3. **Work on it**: Implement, test, document
 4. **Discover new work?** `bd create "Found bug" --description="What was found and why" -p 1 --deps discovered-from:<parent-id> --json`
 5. **Complete**: `bd close <id> --reason "Done" --json`
-6. **Sync**: `bd dolt push` (push to Dolt remote if configured)
+6. **Sync**: `bd sync` (sync with Dolt remote if configured)
 
 **IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.
 
@@ -95,8 +95,7 @@ beads/
 ├── examples/            # Integration examples
 ├── docs/                # Documentation
 └── .beads/
-    ├── dolt/            # Dolt database (DO NOT COMMIT)
-    └── issues.jsonl     # Git-synced issue storage
+    └── dolt/            # Dolt database (source of truth)
 ```
 
 ## Available Resources
@@ -122,11 +121,11 @@ Use the beads MCP server for native function calls instead of shell commands:
 
 - ✅ Use bd for ALL task tracking
 - ✅ Always use `--json` flag for programmatic use
-- ✅ Use `bd dolt push` for remote sync
+- ✅ Use `bd sync` for remote sync
 - ✅ Test with `t.TempDir() in Go tests`
 - ❌ Do NOT create markdown TODO lists
 - ❌ Do NOT create test issues in production DB
-- ❌ Do NOT commit `.beads/dolt/` (JSONL only)
+- ❌ Do NOT manually modify `.beads/dolt/`
 
 ---
 

AGENT_INSTRUCTIONS.md

@@ -60,7 +60,7 @@ func TestMyFeature(t *testing.T) {
    - For full CGO validation: `make test-full-cgo`
 2. **Run linter**: `golangci-lint run ./...` (ignore baseline warnings)
 3. **Update docs**: If you changed behavior, update README.md or other docs
-4. **Commit**: With git hooks installed (`bd hooks install`), JSONL is auto-exported on commit
+4. **Commit**: With git hooks installed (`bd hooks install`), Dolt changes are auto-committed
 
 ### Commit Message Convention
 
@@ -75,24 +75,22 @@ This enables `bd doctor` to detect **orphaned issues** - work that was committed
 
 ### Git Workflow
 
-bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command). JSONL is maintained for git portability via hooks.
+bd uses **Dolt** as its primary database. Changes are committed to Dolt history automatically (one Dolt commit per write command).
 
-**Install git hooks** for automatic JSONL sync:
+**Install git hooks** for automatic sync:
 ```bash
 bd hooks install
 ```
 
-This ensures JSONL is exported on commit and imported after pull/merge.
-
 ### Git Integration
 
-**JSONL portability**: JSONL is exported via git hooks for sharing through git. The Dolt database is the source of truth.
+**Dolt sync**: Dolt handles sync natively via `bd sync`. 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).
 
 **Git worktrees**: Work directly with Dolt — no special flags needed. See [docs/ADVANCED.md](docs/ADVANCED.md).
 
-**Merge conflicts**: Rare with hash IDs. If conflicts occur in JSONL, use `git checkout --theirs .beads/issues.jsonl` and `bd import`. Dolt uses cell-level 3-way merge for better conflict resolution.
+**Merge conflicts**: Rare with hash IDs. Dolt uses cell-level 3-way merge for conflict resolution.
 
 ## Landing the Plane
 
@@ -111,11 +109,6 @@ This ensures JSONL is exported on commit and imported after pull/merge.
    # Pull first to catch any remote changes
    git pull --rebase
 
-   # If conflicts in .beads/issues.jsonl, resolve thoughtfully:
-   #   - git checkout --theirs .beads/issues.jsonl (accept remote)
-   #   - bd import -i .beads/issues.jsonl (re-import)
-   #   - Or manual merge, then import
-
    # MANDATORY: Push everything to remote
    # DO NOT STOP BEFORE THIS COMMAND COMPLETES
    git push
@@ -158,10 +151,6 @@ bd close bd-42 bd-43 --reason "Completed" --json
 
 # 4. PUSH TO REMOTE - MANDATORY, NO STOPPING BEFORE THIS IS DONE
 git pull --rebase
-# If conflicts in .beads/issues.jsonl, resolve thoughtfully:
-#   - git checkout --theirs .beads/issues.jsonl (accept remote)
-#   - bd import -i .beads/issues.jsonl (re-import)
-#   - Or manual merge, then import
 git push       # MANDATORY - THE PLANE IS STILL IN THE AIR UNTIL THIS SUCCEEDS
 git status     # MUST verify "up to date with origin/main"
 
@@ -215,8 +204,8 @@ bd dolt push
 
 This installs:
 
-- **pre-commit** — Exports Dolt changes to JSONL and stages it
-- **post-merge** — Imports pulled JSONL changes into Dolt
+- **pre-commit** — Commits pending Dolt changes
+- **post-merge** — Pulls remote Dolt changes after git merge
 
 **Note:** Hooks are embedded in the bd binary and work for all bd users (not just source repo users).
 
@@ -398,6 +387,6 @@ gh issue view 201
 
 - **README.md** - Main documentation (keep this updated!)
 - **EXTENDING.md** - Database extension guide
-- **ADVANCED.md** - JSONL format analysis
+- **ADVANCED.md** - Advanced features (rename, merge, compaction)
 - **CONTRIBUTING.md** - Contribution guidelines
 - **SECURITY.md** - Security policy

BENCHMARKS.md

@@ -36,7 +36,7 @@ Tests on graphs with different topologies (linear chains, trees, dense graphs):
 ### Ready Work / Filtering
 - **BenchmarkGetReadyWork_Large** - Filter unblocked issues (10K dataset)
 - **BenchmarkGetReadyWork_XLarge** - Filter unblocked issues (20K dataset)
-- **BenchmarkGetReadyWork_FromJSONL** - Ready work on JSONL-imported database
+- **BenchmarkGetReadyWork_FromJSONL** - Ready work on imported database
 
 ### Search Operations
 - **BenchmarkSearchIssues_Large_NoFilter** - Search all open issues (10K dataset)
@@ -71,7 +71,7 @@ Tests on graphs with different topologies (linear chains, trees, dense graphs):
 Benchmark datasets are cached in `/tmp/beads-bench-cache/`:
 - `large.db` - 10,000 issues (16.6 MB)
 - `xlarge.db` - 20,000 issues (generated on demand)
-- `large-jsonl.db` - 10K issues via JSONL import
+
 
 Cached databases are reused across runs. To regenerate:
 ```bash