Beads + Dolt Initialization

Purpose

Use this skill when a repository needs beads initialized or recovered with the current Dolt-based workflow.

This skill is specifically tuned for the common Trimble setup where:

• .beads/config.yaml already exists
• sync.git-remote points at an Azure Dolt remote such as az://...
• the remote may be empty on first use
• agents need a non-destructive, verifiable setup path

When to Use

• A repo has .beads/config.yaml but bd status says no beads database exists
• bd bootstrap fails because the configured Azure remote has no Dolt data yet
• bd doctor reports missing metadata.json, missing database, or failed Dolt connection
• bd doctor reports Database belongs to different repository even though the configured Dolt remote looks correct
• You need to seed a fresh Azure Dolt remote from a new local beads database
• You need the exact safe sequence for bootstrap, init, Dolt server startup, and remote push

Non-Goals

• Do not wipe an existing healthy beads database just to re-run setup
• Do not use legacy SQLite-era instructions
• Do not invent bd commands or remote-management syntax; use bd dolt remote ...

Preflight

Run these checks first:

git --no-pager status --short --branch
bd version
bd doctor --json || true
bd dolt remote list
bd bootstrap --dry-run --json

Then inspect .beads/config.yaml and confirm:

• the expected issue-prefix
• whether sync.git-remote is present
• whether Dolt auto-commit or other repo-specific settings already exist
• whether bd dolt remote list matches the configured remote exactly (origin URL should equal sync.git-remote)

Decision Rules

Case 1: Existing database already present

If bd bootstrap --dry-run --json reports action: "none" or bd status works, do not reinitialize immediately.

If bd doctor is clean, verify and stop:

bd status --json
bd where
bd dolt remote list

If bd doctor reports a repository fingerprint mismatch, follow Case 1b instead of stopping here.

If bd doctor reports a different error, continue to the matching case below instead of stopping just because bd status works.

Case 1b: Existing database present, but repo fingerprint mismatch

If bd status --json works and bd dolt remote list matches .beads/config.yaml, but bd doctor reports an error like:

Database belongs to different repository

Prefer the least-destructive repair first: execute Path C: Repo fingerprint mismatch recovery.

If the remote reported by bd dolt remote list does not exactly match .beads/config.yaml, stop and reconcile remote configuration first. Do not run bd migrate --update-repo-id --yes against an ambiguous or unexpected remote.

Case 2: Remote configured and contains data

If bd bootstrap --dry-run --json reports action: "sync" and the remote is already seeded, prefer bootstrap:

bd bootstrap --json

If bd bootstrap prompts Proceed? [Y/n], only confirm after the dry-run output matches the intended remote and target directory.

Case 3: Remote configured but empty

If bootstrap fails with an error like:

clone failed; remote at that url contains no Dolt data

treat this as an empty remote, not a bad configuration.

The correct recovery is:

1. Start the project Dolt server
2. Initialize a fresh local beads database
3. Keep the configured Dolt remote
4. Push local Dolt data to seed the empty remote

Recommended Workflow

Path A: Normal bootstrap from remote

bd bootstrap --dry-run --json
bd bootstrap --json
bd status --json
bd where
bd dolt remote list

Path B: Empty Azure remote fallback

Use this exact sequence when clone-based bootstrap fails because the Azure remote is empty:

bd dolt start
bd init --sandbox --json
bd status --json
bd where
bd dolt remote list
bd dolt push

Why this works:

• bd dolt start clears the common "circuit breaker is open" / server-not-running failure mode
• bd init --sandbox --json safely initializes the local Dolt database without destructive re-bootstrap behavior
• bd init still honors .beads/config.yaml, so it can keep/configure the Azure remote as origin
• bd dolt push seeds the remote after local init succeeds

Path C: Repo fingerprint mismatch recovery

Use this when the local beads database exists and the remote is correct, but bd doctor reports a repository fingerprint mismatch:

bd where
bd status --json
bd dolt remote list
bd migrate --update-repo-id --yes
bd doctor --json || true
bd where
bd status --json
bd dolt remote list
bd dolt pull

Why this works:

• bd where should point at the expected repo-local .beads path before and after the migrate
• the local Dolt/beads database already exists, so re-init is unnecessary
• bd migrate --update-repo-id repairs the local repository binding without discarding beads state
• bd dolt pull confirms the clone can talk to the configured remote after the metadata fix

Failure handling:

• If bd dolt remote list does not exactly match .beads/config.yaml, stop and reconcile the remote configuration first.
• If bd migrate --update-repo-id --yes fails, do not keep retrying blindly. Investigate whether the local database actually belongs to a different repository, then return to bd bootstrap --dry-run --json and follow Case 2 or Case 3 if re-bootstrap is actually required.
• If bd dolt pull fails after a successful migrate, treat that as a remote/auth/connectivity problem. Verify credentials and remote reachability before considering any local reset.

Interactive Prompts

Some bd commands may still prompt even when using --json.

Common prompts and the correct response:

• Proceed? [Y/n] during bd bootstrap: answer Y only after validating the dry-run plan
• Already configured as: maintainer / Change role? [y/N]: answer N unless the user explicitly asked to change role

Do not leave the session hanging on prompts. If a command pauses, respond explicitly and continue verification.

Verification Checklist

After initialization or recovery, verify all of the following:

bd status --json
bd where
bd dolt remote list
bd doctor --json
# If a remote is configured:
bd dolt pull
git --no-pager status --short --branch

Success indicators:

• bd status --json returns summary data instead of "no beads database found"
• bd where shows the .beads directory and Dolt data path
• bd dolt remote list shows the expected Azure remote as origin
• bd doctor --json no longer reports "No dolt database found"
• bd doctor no longer reports a repository fingerprint mismatch
• bd dolt pull succeeds against the configured remote when a remote is configured (for example Pull complete. or Already up to date.)
• the repo branch is pushed if bd init created tracked file changes

Git Persistence

bd init may update tracked files under .beads/ and create local commits as part of setup. Do not leave those changes stranded.

Finish the session with:

git pull --rebase
bd dolt push
git push
git --no-pager status --short --branch

The final git status should show the branch aligned with origin.

Troubleshooting

Symptom	Meaning	Fix
Error: no beads database found	Repo has config but no local Dolt DB	Start with bd bootstrap --dry-run --json
clone failed; remote at that url contains no Dolt data	Azure remote exists but is empty	Run the empty-remote fallback flow
dolt circuit breaker is open	Dolt server is down or unhealthy	bd dolt start, then retry init
database "<name>" not found on Dolt server	Server is running, but the project DB is not initialized yet	Run bd init --sandbox --json
Database belongs to different repository	Local beads DB exists, but its stored repo fingerprint does not match this clone	Run bd migrate --update-repo-id --yes, then re-verify remote access
unknown command "remote" for "bd"	Used an outdated command surface	Use bd dolt remote ... instead

Rules

• Always run bd bootstrap --dry-run --json before mutating setup commands
• Prefer bd bootstrap first; fall back to local init only when the remote is empty or bootstrap cannot complete
• Prefer bd migrate --update-repo-id --yes over re-init when the only failure is a repository fingerprint mismatch
• Treat an empty remote as recoverable
• Start the Dolt server before retrying if you see circuit-breaker or connection errors
• Verify remote configuration with bd dolt remote list, not guesswork
• Push Dolt data after local init so future sessions can bootstrap from the remote immediately