Clarify git vs dolt as source of truth for issue data

[josh-m-sharpe]

bd version 1.0.0 (Homebrew)

I started using beads in the pre-dolt days when issues were persisted in git via JSONL. It was simple - one source of truth, synced through normal git workflows.

After the dolt migration, I'm finding it difficult to keep beads in sync across working directories, and it's unclear whether issue data is still tracked in git.

Context: I have three checkouts of the same repo on my workstation (for running multiple agents). Each has its own dolt instance, but they've gotten out of sync. After stopping all work, bringing all three up to origin/master, bd list --limit 0 reports different issue counts across directories. One checkout has .beads/embeddeddolt while the others have .beads/dolt - should those differ? bd doctor reports it doesn't work in embedded mode, so it's hard to diagnose further.

After some debugging, I resolved it by manually running bd export from one checkout and re-initializing the others. But bd init --force shows this:

WARNING: Re-initializing will destroy the existing database.
  Existing issues: 511
  This action CANNOT be undone.

This raises the question: is destroying the local dolt DB actually unrecoverable? I assumed everything was backed by git, but the warning suggests otherwise.

I also noticed the README description changed from "Distributed, git-backed graph issue tracker" (v0.60.0) to "Distributed graph issue tracker, powered by Dolt" (v0.61.0).

Questions:

1. Is it a bug that dolt isn't reliably flushing back to issues.jsonl (or another git-tracked format)?
2. Or is git sync intentionally deprecated in favor of dolt remotes?
3. If dolt is now the primary store, what's the recommended way to back up and sync issue data - especially across multiple working directories of the same repo?

[coffeegoddd]

in 1.0.0 Beads no longer persists issues in jsonl and committed to the Git repo, it uses Dolt exclusively. By default, Embedded Dolt is used, which means that each git repo you have (despite them being the same one, checked out three different places) all use their own Dolt database, and their is no coordination between them by default.

I think the bd export and bd import commands can be used to dump to jsonl, or import from jsonl though. But this will not be committed to Git or anything.

In order for you to coordinate youre different directories using Embedded Dolt, you'd need to have a Dolt remote set (this can be the git repo's remote url), and then your three Beads clients would need to push, pull, fetch merge changes from the shared remote. Thats how they stay in sync, same flow as you have with git, where changes need to be pulled and conflicts resolved, etc.

I believe that by default also, the registered origin git remote in your dirs will be used as the default dolt remote, and syncs to your Git remote should happend automatically.

Alternatively, there is a --shared-server mode, which will run a single Dolt server (not embedded) on your host, and the three clients would use that single Dolt server, however I believe this would also require the same remote sync workflow, since each client will be using a separate beads database on the Dolt server.

As far as I know, there is no way to have coordinated writes across different directories without syncing to a remote, but Dolt is the primary store regardless.

You can backup your beads with the bd backup command, it will turn a directory into a full Dolt backup, then you can restore it with bd backup restore.

[coffeegoddd]

I'll come up with some example configurations the demonstrate this and how you can get it working, will post here when theyre ready!

[josh-m-sharpe]

Ack. I've migrated all the things to the remote dolt storage. Various amounts of import/export to consolidate one good project dir, then a force push, then verifying the remote was setup correctly across the dirs. Seems solid now.

I think the missing piece from beads would be better articulation in the upgrade path - but I think we're past that. I assumed beads tracked state in git automagically well past the dolt migration - but not sure anything from beads told me that was going sideways.

Maybe none of this matters if v1 is going to be stable on dolt, but might make sense to better articulate git/sync/storage best practices somewhere.