Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
2.3 KiB
| title |
|---|
| Sync Concepts |
Beads issue data lives in Dolt. The local Dolt database is the source of truth
for bd list, bd show, bd ready, and every write command.
The Wire Format
Cross-machine sync uses Dolt remotes:
bd dolt push
bd dolt pull
For normal git-hosted projects, the Dolt remote can be the same origin URL
used for source code. Dolt stores issue history under refs/dolt/data, separate
from source branches such as refs/heads/main.
On new projects, bd init auto-detects git remote get-url origin and
configures a Dolt remote named origin. The first bd dolt push publishes
refs/dolt/data. Fresh clones should run bd bootstrap to clone that Dolt
history. When bootstrap finds refs/dolt/data on git origin, it also wires
that origin as the Dolt remote for future bd dolt push and bd dolt pull.
What JSONL Is For
.beads/issues.jsonl is an export. It exists for viewers, interchange,
migration, and backup. It is not the canonical cross-machine sync channel.
Do not use routine bd import .beads/issues.jsonl as a replacement for
bd dolt pull. JSONL import is upsert-only; it cannot infer that records absent
from an export were deleted, pruned, or simply never exported.
Hooks
The pre-commit hook refreshes .beads/issues.jsonl when export.auto=true.
That keeps the export current for tools, but it does not push Dolt history.
The post-merge and post-checkout hooks skip JSONL import when sync.remote is
configured. For old projects with no Dolt remote, they may import JSONL as a
compatibility fallback and print a warning that this is not durable sync.
Repair
For projects initialized before automatic git-origin remote wiring, pick the machine with the authoritative local Dolt database first. Then run:
bd dolt remote list
bd export -o .beads/issues.pre-remote.jsonl # optional issue audit export
bd dolt remote add origin <git-origin-url>
bd dolt push
Use the Dolt-compatible git URL form when needed. For example,
git+ssh://git@github.com/org/repo.git or
git+https://github.com/org/repo.git. bd dolt remote add origin ...
persists sync.remote into .beads/config.yaml; commit and push that config
change so fresh clones can run bd bootstrap.
Other machines should then run:
bd dolt pull
# or, if the local database is stale or missing:
bd bootstrap