Dolt

Skill: Dolt for Beads

Dolt is the data plane for beads. All issues, mail, and metadata live in Dolt databases served by a shared SQL server on port 3307.

{"k":"meta","s":"dolt","v":"1.0.0","f":"jsonl-progressive"}
{"k":"mission","g":"Keep beads dolt layer operational: server, routing, remotes, metadata."}
{"k":"rule","id":"metadata_required","t":"Every .beads/ MUST have metadata.json with dolt_database matching server. Missing = all bd commands fail."}
{"k":"rule","id":"diagnostics_first","t":"NEVER restart Dolt without capturing goroutine dump + status first. Blind restart destroys hang evidence."}
{"k":"rule","id":"never_rm_dolt_data","t":"NEVER rm -rf ~/.dolt-data/ directories. Use gt dolt cleanup instead."}
{"k":"rule","id":"always_priorlewis43","t":"ALL DoltHub remotes use priorlewis43/ prefix. NEVER use lprior-repo/. The creds auth as priorlewis43."}
{"k":"rule","id":"naming_pattern","t":"DoltHub repo name = <rig>-database. e.g. hardline -> priorlewis43/hardline-database."}
{"k":"anti_hallucination","id":"no_fabricated_output","t":"NEVER fabricate dolt CLI output, database names, or query results. Run actual commands."}

Rig Registry — ALL DoltHub Remotes

Every rig uses the pattern: https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database

CRITICAL: The DoltHub user is ALWAYS priorlewis43. NEVER use lprior-repo (that's a GitHub org, not DoltHub).

Diagnosis Protocol

When ANY bd command fails for ANY rig, run these checks IN ORDER:

# 1. Server alive?
gt dolt status

# 2. metadata.json exists and has correct database?
cat <rig-source-dir>/.beads/metadata.json

# 3. embeddeddolt trap?
ls <rig-source-dir>/.beads/embeddeddolt/ 2>/dev/null && echo "DELETE THIS"

# 4. Dolt remote correct?
cd <rig-source-dir>/.beads/dolt && dolt remote -v
# MUST be: origin https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database

Fix Procedures

Fix 1: Missing metadata.json

cat > <rig-source-dir>/.beads/metadata.json << 'EOF'
{
  "backend": "dolt",
  "database": "dolt",
  "dolt_database": "<rig-name>",
  "dolt_mode": "server",
  "dolt_server_host": "127.0.0.1",
  "dolt_server_port": 3307
}
EOF

Fix 2: Wrong or Missing Remote

cd <rig-source-dir>/.beads/dolt
dolt remote remove origin
dolt remote add origin https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database
dolt push origin main

If the local dolt database is corrupted (panic on every dolt command):

rm -rf <rig-source-dir>/.beads/dolt
cd <rig-source-dir>/.beads
dolt init --name Lewis --email priorlewis43@gmail.com dolt
cd dolt
dolt remote add origin https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database
dolt push origin main --force

Fix 3: embeddeddolt trap

rm -rf <rig-source-dir>/.beads/embeddeddolt

Fix 4: Dolt hang (NOT just restart)

kill -QUIT $(cat ~/gt/.dolt-data/dolt.pid)      # goroutine dump
gt dolt status 2>&1 | tee /tmp/dolt-hang-$(date +%s).log  # capture state
gt escalate -s HIGH "Dolt: <symptom>"             # THEN escalate

Fix 5: PermissionDenied on push

1. Verify creds: dolt creds check — must show priorlewis43
2. Verify remote uses priorlewis43/ prefix, NOT lprior-repo/
3. Verify DoltHub repo exists at dolthub.com/priorlewis43/<rig>-database
4. If repo doesn't exist, create it on dolthub.com first

Fix 6: Corrupted local .beads/dolt/

The local .beads/dolt/ is only for DoltHub remote sync. The live beads data is on the shared Dolt server (port 3307). It is safe to nuke and re-initialize:

rm -rf <rig-source-dir>/.beads/dolt
mkdir -p <rig-source-dir>/.beads/dolt
cd <rig-source-dir>/.beads/dolt
dolt init --name Lewis --email priorlewis43@gmail.com
dolt remote add origin https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database
dolt push origin main --force

New Rig Setup

Three files required for beads on a new rig:

1. metadata.json — see Fix 1 above (set dolt_database to rig name)
2. config.yaml — prefix: <pfx>, issue-prefix: <pfx>, dolt.idle-timeout: "0"
3. Dolt remote — create repo on dolthub.com as priorlewis43/<rig>-database, then:

   cd <rig-source-dir>/.beads/dolt
   dolt init --name Lewis --email priorlewis43@gmail.com
   dolt remote add origin https://doltremoteapi.dolthub.com/priorlewis43/<rig>-database
   dolt push origin main
   

Mandatory Verification Gate

After ANY dolt configuration change:

gt dolt status                              # Server must be healthy
cd <rig-source-dir> && bd ready -n 1        # Must return beads (not error)

Push Workflow

# Always run from the .beads/dolt directory
cd <rig-source-dir>/.beads/dolt

# Push to DoltHub
dolt push origin main

Common Errors and Fixes

Progressive Disclosure

• references/cli-reference.md — Full Dolt CLI command catalog
• references/beads-integration.md — bd + Dolt sync, backup, cross-machine workflows