···11-# SQLite databases
22-*.db
33-*.db?*
44-*.db-journal
55-*.db-wal
66-*.db-shm
11+# Dolt database (managed by Dolt, not git)
22+dolt/
33+dolt-access.lock
7488-# Daemon runtime files
99-daemon.lock
1010-daemon.log
1111-daemon.pid
55+# Runtime files
126bd.sock
77+bd.sock.startlock
138sync-state.json
149last-touched
15101611# Local version tracking (prevents upgrade notification spam after git ops)
1712.local_version
18131919-# Legacy database files
2020-db.sqlite
2121-bd.db
2222-2314# Worktree redirect file (contains relative path to main repo's .beads/)
2415# Must not be committed as paths would be wrong in other clones
2516redirect
26172727-# Merge artifacts (temporary files from 3-way merge)
2828-beads.base.jsonl
2929-beads.base.meta.json
3030-beads.left.jsonl
3131-beads.left.meta.json
3232-beads.right.jsonl
3333-beads.right.meta.json
1818+# Sync state (local-only, per-machine)
1919+# These files are machine-specific and should not be shared across clones
2020+.sync.lock
2121+export-state/
34223535-# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
3636-# They would override fork protection in .git/info/exclude, allowing
3737-# contributors to accidentally commit upstream issue databases.
3838-# The JSONL files (issues.jsonl, interactions.jsonl) and config files
3939-# are tracked by git by default since no pattern above ignores them.
2323+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
2424+ephemeral.sqlite3
2525+ephemeral.sqlite3-journal
2626+ephemeral.sqlite3-wal
2727+ephemeral.sqlite3-shm
2828+2929+# Dolt server management (auto-started by bd)
3030+dolt-server.pid
3131+dolt-server.log
3232+dolt-server.lock
3333+dolt-server.port
3434+dolt-server.activity
3535+dolt-monitor.pid
3636+3737+# Backup data (auto-exported JSONL, local-only)
3838+backup/
3939+4040+# Legacy files (from pre-Dolt versions)
4141+*.db
4242+*.db?*
4343+*.db-journal
4444+*.db-wal
4545+*.db-shm
4646+db.sqlite
4747+bd.db
4848+# NOTE: Do NOT add negation patterns here.
4949+# They would override fork protection in .git/info/exclude.
5050+# Config files (metadata.json, config.yaml) are tracked by git by default
5151+# since no pattern above ignores them.
···11+22+# Dolt database files (added by bd init)
33+.dolt/
44+*.db
+113
AGENTS.md
···3838- NEVER say "ready to push when you are" - YOU must push
3939- If push fails, resolve and retry until it succeeds
40404141+4242+<!-- BEGIN BEADS INTEGRATION -->
4343+## Issue Tracking with bd (beads)
4444+4545+**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
4646+4747+### Why bd?
4848+4949+- Dependency-aware: Track blockers and relationships between issues
5050+- Git-friendly: Dolt-powered version control with native sync
5151+- Agent-optimized: JSON output, ready work detection, discovered-from links
5252+- Prevents duplicate tracking systems and confusion
5353+5454+### Quick Start
5555+5656+**Check for ready work:**
5757+5858+```bash
5959+bd ready --json
6060+```
6161+6262+**Create new issues:**
6363+6464+```bash
6565+bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
6666+bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
6767+```
6868+6969+**Claim and update:**
7070+7171+```bash
7272+bd update <id> --claim --json
7373+bd update bd-42 --priority 1 --json
7474+```
7575+7676+**Complete work:**
7777+7878+```bash
7979+bd close bd-42 --reason "Completed" --json
8080+```
8181+8282+### Issue Types
8383+8484+- `bug` - Something broken
8585+- `feature` - New functionality
8686+- `task` - Work item (tests, docs, refactoring)
8787+- `epic` - Large feature with subtasks
8888+- `chore` - Maintenance (dependencies, tooling)
8989+9090+### Priorities
9191+9292+- `0` - Critical (security, data loss, broken builds)
9393+- `1` - High (major features, important bugs)
9494+- `2` - Medium (default, nice-to-have)
9595+- `3` - Low (polish, optimization)
9696+- `4` - Backlog (future ideas)
9797+9898+### Workflow for AI Agents
9999+100100+1. **Check ready work**: `bd ready` shows unblocked issues
101101+2. **Claim your task atomically**: `bd update <id> --claim`
102102+3. **Work on it**: Implement, test, document
103103+4. **Discover new work?** Create linked issue:
104104+ - `bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>`
105105+5. **Complete**: `bd close <id> --reason "Done"`
106106+107107+### Auto-Sync
108108+109109+bd automatically syncs via Dolt:
110110+111111+- Each write auto-commits to Dolt history
112112+- Use `bd dolt push`/`bd dolt pull` for remote sync
113113+- No manual export/import needed!
114114+115115+### Important Rules
116116+117117+- ✅ Use bd for ALL task tracking
118118+- ✅ Always use `--json` flag for programmatic use
119119+- ✅ Link discovered work with `discovered-from` dependencies
120120+- ✅ Check `bd ready` before asking "what should I work on?"
121121+- ❌ Do NOT create markdown TODO lists
122122+- ❌ Do NOT use external issue trackers
123123+- ❌ Do NOT duplicate tracking systems
124124+125125+For more details, see README.md and docs/QUICKSTART.md.
126126+127127+## Landing the Plane (Session Completion)
128128+129129+**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
130130+131131+**MANDATORY WORKFLOW:**
132132+133133+1. **File issues for remaining work** - Create issues for anything that needs follow-up
134134+2. **Run quality gates** (if code changed) - Tests, linters, builds
135135+3. **Update issue status** - Close finished work, update in-progress items
136136+4. **PUSH TO REMOTE** - This is MANDATORY:
137137+ ```bash
138138+ git pull --rebase
139139+ bd sync
140140+ git push
141141+ git status # MUST show "up to date with origin"
142142+ ```
143143+5. **Clean up** - Clear stashes, prune remote branches
144144+6. **Verify** - All changes committed AND pushed
145145+7. **Hand off** - Provide context for next session
146146+147147+**CRITICAL RULES:**
148148+- Work is NOT complete until `git push` succeeds
149149+- NEVER stop before pushing - that leaves work stranded locally
150150+- NEVER say "ready to push when you are" - YOU must push
151151+- If push fails, resolve and retry until it succeeds
152152+153153+<!-- END BEADS INTEGRATION -->