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/.
979 B
979 B
| title | description |
|---|---|
| Database Corruption | Recover from Dolt database corruption |
This runbook helps you recover from database corruption in Beads.
Symptoms
- Error messages during
bdcommands - "database is locked" errors that persist
- Missing issues that should exist
- Inconsistent database state
Diagnosis
# Check database integrity
bd doctor
# Check Dolt server health
bd dolt show
Solution
Step 1: Stop the Dolt server
bd dolt stop
Step 2: Back up current state
cp -r .beads .beads.backup
Step 3: Preview what doctor would fix
bd doctor --dry-run
Step 4: Rebuild database
bd doctor --fix
Step 5: Verify recovery
bd doctor
bd list
Step 6: Restart the Dolt server
dolt sql-server
Prevention
- Let the Dolt server handle synchronization
- Use
bd dolt stopbefore system shutdown - Run
bd doctorperiodically to catch issues early