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>