beads/docs
matt wilkie fd3c6094de
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>
2026-05-05 14:35:18 -07:00
..
adr fix(init): refuse --force when remote has Dolt history (#3455) 2026-04-24 09:01:35 -07:00
design cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
dev-notes docs: remove stale daemon refs and bd sync --status/--merge references 2026-02-28 19:54:49 -07:00
ADAPTIVE_IDS.md feat: support issue_id_mode=counter for sequential IDs (#2013) 2026-02-22 23:49:46 -08:00
ADO_CONFIG.md Add ADO round-trip integration tests and config documentation (#3305) 2026-04-20 18:16:53 -07:00
ADVANCED.md docs: fix broken xref to docs/EXTENDING.md in extension example (#3713) 2026-05-05 13:18:43 -07:00
AIDER_INTEGRATION.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
ANTIVIRUS.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
ARCHITECTURE.md /{README,cmd}: go back to init 2026-03-28 13:47:20 -07:00
ATTRIBUTION.md fix: remove dead 3-way merge config remnants (GH#2353) 2026-03-05 15:57:33 -08:00
audit-sync-mode-complexity.md fix: complete UUID primary keys cleanup across codebase 2026-03-14 10:12:04 -07:00
CLAUDE.md docs: fix stale agent instructions across 5 files (#3436) 2026-04-25 11:45:39 -07:00
CLAUDE_INTEGRATION.md docs: document bd setup command 2025-12-16 01:08:42 -08:00
CLI_REFERENCE.md Add atomic ready claim (GH-3570) 2026-04-28 07:11:13 -07:00
COLLISION_MATH.md docs: fix broken relative links across documentation 2025-12-16 00:46:08 -08:00
COMMUNITY_TOOLS.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
CONFIG.md docs: fix broken xref to docs/EXTENDING.md in extension example (#3713) 2026-05-05 13:18:43 -07:00
CONTRIBUTOR_NAMESPACE_ISOLATION.md cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
COPILOT_INTEGRATION.md fix: replace stale 'bd sync' references with bd dolt push/commit (GH#2435) 2026-03-07 17:00:19 +01:00
DEPENDENCIES.md docs(deps): add DEPENDENCIES.md covering dependency system and gates 2026-02-27 10:09:05 -08:00
DOLT-BACKEND.md /{cmd,docs,internal}: more cleanup 2026-03-31 12:33:52 -07:00
DOLT.md Add external server CLI dir override (bd-fn9) (#3498) 2026-04-25 19:57:04 -07:00
ERROR_HANDLING.md docs: remove stale daemon refs and bd sync --status/--merge references 2026-02-28 19:54:49 -07:00
EXCLUSIVE_LOCK.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
FAQ.md docs: fix FAQ "git-based" misframing (Dolt-native, not git-based) (#3712) 2026-05-05 14:35:18 -07:00
GETTING_STARTED_ANALYSIS.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
GIT_INTEGRATION.md Add bd init --remote bootstrap path (#3527) 2026-04-27 13:45:26 -07:00
graph-links.md refactor: remove Gas Town references from codebase 2025-12-30 14:13:32 -08:00
ICU-POLICY.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
INSTALLING.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
INTEGRATION_CHARTER.md Add Integration Charter: define scope boundary for tracker integrations 2026-03-30 09:12:28 -07:00
INTERNALS.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
JSON_SCHEMA.md feat: BD_JSON_ENVELOPE=1 opt-in for uniform JSON wrapping (#3393) 2026-04-21 13:24:17 -07:00
LABELS.md cleanup: remove remaining Gas Town terminology from help text, docs, and comments 2026-03-22 13:27:43 -07:00
LINTING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
messaging.md refactor: remove gastown/Gas Town string references from beads code and docs (bd-1ue8) 2026-03-20 18:39:50 -07:00
METADATA.md schema: make DROP COLUMN migrations idempotent (fixes migration 0032 loop) (#3418) 2026-04-27 09:15:20 -07:00
MOLECULES.md Keep regular epics open after the last child closes (#3276) 2026-04-17 15:10:38 -07:00
MULTI_REPO_AGENTS.md fix: add shared Dolt server mode for multi-repo/agent setups (GH#2416) 2026-03-10 17:38:00 -07:00
MULTI_REPO_MIGRATION.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
OBSERVABILITY.md /{cmd,docs,internal}: more cleanup 2026-03-31 12:33:52 -07:00
PERFORMANCE_TESTING.md docs: update stale SQLite references to Dolt across 10 documentation files 2026-02-16 01:22:58 -08:00
PLUGIN.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
pr-752-chaos-testing-review.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
PROTECTED_BRANCHES.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
QUICKSTART.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
README_TESTING.md DOCTOR IMPROVEMENTS: visual improvements/grouping + add comprehensive tests + fix gosec warnings (#656) 2025-12-20 03:10:06 -08:00
RECOVERY.md fix(init): refuse --force when remote has Dolt history (#3455) 2026-04-24 09:01:35 -07:00
RELEASE-STABILITY-GATE.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
RELEASING.md Add shared Beads plugin package 2026-05-02 10:59:40 -07:00
REPO_CONTEXT.md docs: replace stale bd sync references with bd dolt push/pull (GH#2442, GH#2435) 2026-03-08 10:12:08 -07:00
ROUTING.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
RULES_AUDIT_DESIGN.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00
SECURITY-DEPENDENCY-EXCEPTIONS.md chore: harden release and dependency security 2026-04-28 08:45:22 +00:00
SETUP.md Follow up remaining runtime .beads fallbacks after GH#3124 (#3183) 2026-04-10 21:23:14 -07:00
SYNC_SETUP.md /{cmd,docs,internal}: remove file removal that can cause data corruption 2026-03-31 12:04:55 -07:00
TESTING.md Rename ICU-only test path to explicit opt-in workflow (bd-b18) (#3291) 2026-04-16 08:54:24 -07:00
TESTING_PHILOSOPHY.md fix: remove dead 3-way merge config remnants (GH#2353) 2026-03-05 15:57:33 -08:00
TODO.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
TROUBLESHOOTING.md Document supported go install modes (bd-o5a) (#3480) 2026-04-25 11:30:19 -07:00
UI_PHILOSOPHY.md docs: consolidate duplicate UI_PHILOSOPHY files (GH#745) 2025-12-27 18:01:59 -08:00
UNINSTALLING.md docs: remove stale JSONL references from ~73 markdown files (bd-9ni.4) 2026-02-22 22:18:02 -08:00
WORKTREES.md docs: update user-facing URLs from steveyegge/beads to gastownhall/beads 2026-04-24 08:17:42 -07:00