docs: fix FAQ "git-based" misframing (Dolt-native, not git-based) (#3712)
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 <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
33235723df
commit
fd3c6094de
1 changed files with 7 additions and 7 deletions
14
docs/FAQ.md
14
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 <id> --assignee agent-name`
|
||||
3. Start work (as assigned agent): `bd update <id> --status in_progress`
|
||||
4. Create discovered work: `bd create "Found issue" --deps discovered-from:<parent-id>`
|
||||
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 <id> --status in_progress`.
|
||||
If an agent picks work directly, use atomic `bd update <id> --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:
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue