From fd3c6094de65ce7e60bd0d108b1857c348fbefb6 Mon Sep 17 00:00:00 2001 From: matt wilkie Date: Tue, 5 May 2026 14:35:18 -0700 Subject: [PATCH] docs: fix FAQ "git-based" misframing (Dolt-native, not git-based) (#3712) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The FAQ opened by calling beads a "git-based issue tracker", which contradicts the Dolt-native architecture documented elsewhere (README opens with "Distributed graph issue tracker for AI agents, powered by Dolt"; the FAQ itself later explains `bd dolt push` / `bd dolt pull` and Dolt branches independent of git branches). Newcomers reading the FAQ first formed an incorrect mental model: storage backend = git, sync mechanism = git push/pull. In reality, issues live in a local Dolt database and sync via Dolt remotes; git is only involved for project code (and optionally for ferrying the exported `.beads/issues.jsonl` between machines). Replaced "git-based issue tracker" with "version-controlled issue tracker" — accurate without dropping the "Dolt" vendor name in the opening line (newcomers do not yet recognize Dolt; it is introduced later in the FAQ where context is built up). Also fixed downstream misframings in the same file: - "Git-First, ..." differentiator header -> "Offline-First, ..." - "git-synchronized task memory" -> "version-controlled task memory" - "Git-native sync" -> "Built-in sync" (Taskwarrior comparison) - "Sync via git commits" -> "Sync via `bd dolt push` / `bd dolt pull`" - "bd's git-based sync" -> "bd's version-controlled storage" + cell-level merge - "Sync happens via git push/pull" -> "Sync happens via `bd dolt push` / `bd dolt pull`" Left genuine git references untouched: the merge-conflict section showing JSONL diffs (issues.jsonl is a real git-tracked artifact for portability), git hooks, `bd init`'s git interaction, the "walks up like git" auto-discovery analogy, and the worktree FAQs. Tracking: mybd-ujr GH: #3683 PR: #3706 (precursor) Co-authored-by: CI Bot Co-authored-by: Claude Opus 4.7 (1M context) --- docs/FAQ.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index 14b93dde0..668da20c1 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -6,7 +6,7 @@ Common questions about bd (beads) and how to use it effectively. ### What is bd? -bd is a lightweight, git-based issue tracker designed for AI coding agents. It provides dependency-aware task management with automatic sync across machines via git. +bd is a lightweight, version-controlled issue tracker designed for AI coding agents. It provides dependency-aware task management with built-in sync across machines, so agents and humans can collaborate from the same task graph. ### Why not just use GitHub Issues? @@ -22,7 +22,7 @@ GitHub Issues + gh CLI can approximate some features, but fundamentally cannot r - bd: `bd ready` computes transitive blocking offline in ~10ms, no network required - GH: No built-in "ready" concept; would require custom GraphQL + sync service + ongoing maintenance -3. **Git-First, Offline, Branch-Scoped Task Memory** +3. **Offline-First, Branch-Scoped Task Memory** - bd: Works offline, issues live on branches, hash IDs prevent collisions on merge - GH: Cloud-first, requires network/auth, global per-repo, no branch-scoped task state @@ -38,7 +38,7 @@ GitHub Issues + gh CLI can approximate some features, but fundamentally cannot r - bd: Consistent `--json` on all commands, dedicated MCP server with auto workspace detection - GH: Mixed JSON/text output, GraphQL requires custom queries, no agent-focused MCP layer -**When to use each:** GitHub Issues excels for human teams in web UI with cross-repo dashboards and integrations. bd excels for AI agents needing offline, git-synchronized task memory with graph semantics and deterministic queries. +**When to use each:** GitHub Issues excels for human teams in web UI with cross-repo dashboards and integrations. bd excels for AI agents needing offline, version-controlled task memory with graph semantics and deterministic queries. See [GitHub issue #125](https://github.com/gastownhall/beads/issues/125) for detailed comparison. @@ -48,7 +48,7 @@ Taskwarrior is excellent for personal task management, but bd is built for AI ag - **Explicit agent semantics**: `discovered-from` dependency type, `bd ready` for queue management - **JSON-first design**: Every command has `--json` output -- **Git-native sync**: No sync server setup required +- **Built-in sync**: Version-controlled storage with native push/pull, no separate sync server to run - **Dolt merge**: Cell-level merge with AI-resolvable conflicts - **SQL database**: Full SQL queries against Dolt database @@ -371,13 +371,13 @@ Yes! Each agent can: 2. Assign issues: `bd update --assignee agent-name` 3. Start work (as assigned agent): `bd update --status in_progress` 4. Create discovered work: `bd create "Found issue" --deps discovered-from:` -5. Sync via git commits +5. Sync via `bd dolt push` / `bd dolt pull` Note: In orchestrated workflows, assignment is usually done by an orchestrator. If the issue is already assigned, start with `bd update --status in_progress`. If an agent picks work directly, use atomic `bd update --claim --assignee agent-name`. -bd's git-based sync means agents work independently and merge their changes like developers do. +bd's version-controlled storage means agents work independently and merge their changes like developers do, with cell-level merge resolving most conflicts automatically. ### Does bd work offline? @@ -385,7 +385,7 @@ Yes! bd is designed for offline-first operation: - All queries run against local Dolt database - No network required for any commands -- Sync happens via git push/pull when you're online +- Sync happens via `bd dolt push` / `bd dolt pull` when you're online - Full functionality available without internet This makes bd ideal for: