Gas Town Rig Setup

Overview

Add a Git repository as a Gas Town rig with Dolt-native beads integration. The process requires seeding .beads/ in the upstream repo first, then adding the rig, initializing Dolt, and configuring remotes.

Why seed .beads/ first? gt rig add behaves differently depending on whether the cloned repo has a tracked .beads/ directory. Seeding ensures the correct code path runs. See "Why Seeding Matters" below for the technical details.

When to Use

• Adding a new repository as a Gas Town rig

• User says "add a rig", "set up a rig", "onboard this repo"

When NOT to Use

• Setting up beads in a standalone repo (use beads-setup skill)

• Migrating an existing rig from SQLite to Dolt (see MEMORY.md migration notes)

Prerequisites

Before starting, confirm with the user:

• Rig name - Short, single-word, no hyphens (hyphens cause SQL quoting issues). E.g., toolkit not gt-toolkit .

• Beads prefix - 2-3 letter abbreviation. E.g., tk . Must not conflict with existing prefixes in ~/gt/.beads/routes.jsonl .

• Git remote URL - SSH (git@github.com:Org/repo.git ) or HTTPS (https://github.com/Org/repo.git ). Both work with gt rig add .

Check existing prefixes:

cat ~/gt/.beads/routes.jsonl

Steps

1. Clone repo into ~/projects/

cd ~/projects && git clone <SSH_URL> <repo-dir-name>

2. Seed minimal .beads/ in the clone

Create four files using an existing rig as template (e.g., ~/projects/onyx/.beads/ ):

.beads/.gitignore — Copy from template rig verbatim.

.beads/config.yaml :

sync.mode: "dolt-native"

.beads/metadata.json — Set dolt_database to the rig name:

{ "backend": "dolt", "database": "dolt", "dolt_database": "<RIG_NAME>", "dolt_mode": "server", "dolt_server_port": 3307 }

.beads/README.md — Copy from template rig verbatim.

3. Commit and push .beads/

cd ~/projects/<repo-dir> git add .beads/ git commit -m "feat: add minimal .beads/ for Gastown rig integration" git push

4. Add the rig

gt rig add <RIG_NAME> <SSH_URL> --prefix <PREFIX>

This creates ~/gt/<RIG_NAME>/ with the full rig structure (mayor/rig, crew/, refinery/, witness/, polecats/).

5. Initialize the Dolt database

gt dolt init-rig <RIG_NAME>

Creates ~/gt/.dolt-data/<RIG_NAME>/ .

6. Restart Dolt server

gt dolt stop && gt dolt start

Verify the new database appears:

gt dolt list

STOP if the rig database doesn't appear. Investigate before proceeding.

7. Configure Dolt remote

mkdir -p ~/dolt-remotes/<RIG_NAME> cd ~/gt/.dolt-data/<RIG_NAME> && dolt remote add origin file:///home/xexr/dolt-remotes/<RIG_NAME> cd ~/gt/.dolt-data/<RIG_NAME> && dolt push origin main

8. Verify configuration

Check these files have correct values:

File Key fields

~/gt/<RIG_NAME>/config.json

git_url , prefix

~/gt/<RIG_NAME>/.beads/redirect

Points to mayor/rig/.beads

~/gt/<RIG_NAME>/mayor/rig/.beads/metadata.json

dolt_database: "<RIG_NAME>" , dolt_mode: "server" , dolt_server_port: 3307

9. Run diagnostics

cd ~/gt/<RIG_NAME>/mayor/rig && bd doctor gt doctor

Investigate and fix any issues before declaring complete.

Known false positive: bd doctor reports ✖ Database: No dolt database found in server mode. This is cosmetic — it checks for a local .beads/dolt/ directory which doesn't exist when using the centralized Dolt server at .dolt-data/ . Verify actual connectivity with bd list instead; if that returns results, the database is working.

Verification Checklist

[ ] gt rig list — shows new rig [ ] gt dolt list — shows new database [ ] bd list — returns results (from within rig's mayor/rig/) [ ] gt doctor — passes (marketplace-related checks) [ ] ~/dolt-remotes/<RIG_NAME>/ — has data after push [ ] cat ~/gt/.dolt-data/<RIG_NAME>/.dolt/repo_state.json — shows origin remote

Common Mistakes

Mistake Fix

Hyphen in rig name (gt-toolkit ) Use single word (toolkit ). Hyphens require SQL backtick quoting everywhere.

Skipping .beads/ seeding Without seeding, bd init writes dolt_database: "beads_<prefix>" which mismatches the actual database name. See "Why Seeding Matters".

Forgetting to restart Dolt New database won't be visible until gt dolt stop && gt dolt start .

Prefix conflicts Check routes.jsonl before choosing. Conflicts cause routing errors.

Not pushing .beads/ before gt rig add

The clones created by gt rig add pull from remote. If .beads/ isn't pushed, they won't have it.

Treating bd doctor "No dolt database found" as real False positive in server mode — checks for local .beads/dolt/ not the centralized server. Use bd list to verify connectivity instead.

Why Seeding Matters

gt rig add (internal/rig/manager.go:AddRig ) takes two different code paths depending on whether the cloned repo has a tracked .beads/ directory. The unseeded path has a database naming bug that breaks Dolt connectivity.

The bug in the unseeded path

When .beads/ is NOT in the repo, the following sequence creates a name mismatch:

• doltserver.InitRig(townRoot, "toolkit") at manager.go:485 creates a Dolt database named toolkit

• InitBeads at manager.go:765 runs bd init --prefix tk --server (no existing .beads/ to redirect to)

• bd init at init.go:457 writes dolt_database: "beads_tk" to metadata.json — this is bd's own naming convention ("beads_" + prefix )

• EnsureMetadata at doltserver.go:1570 checks if dolt_database == nil || == "" — it's "beads_tk" , so it does not override

• Result: metadata.json says dolt_database: "beads_tk" but the actual database is "toolkit" . bd cannot connect.

How seeding prevents this

When .beads/ IS in the repo (with the correct dolt_database: "<RIG_NAME>" in metadata.json ):

• After cloning into mayor/rig/ , the code detects .beads/ at manager.go:419

• doltserver.InitRig at manager.go:485 creates database "toolkit" and calls EnsureMetadata — which finds mayor/rig/.beads/metadata.json already has the correct dolt_database: "toolkit" and leaves it alone

• InitBeads at manager.go:734 sees mayor/rig/.beads exists → creates a redirect file at <rig>/.beads/redirect → mayor/rig/.beads → returns early without running bd init (so the correct dolt_database is never overwritten)

• Route registration at manager.go:644 sets the route path to <name>/mayor/rig

• EnsureMetadata at manager.go:503 confirms dolt_mode: "server" , dolt_database: "toolkit" — all correct

Result: mayor/rig/.beads/ is the canonical beads location (tracked in git). The rig-level .beads/redirect points all agents there. The database name matches. Config persists across clones.

Summary

Seeding .beads/ with the correct metadata.json is not just a preference — it's a workaround for a bug where bd init --server writes dolt_database: "beads_<prefix>" which conflicts with the centralized Dolt database named <rigName> . Without seeding, bd connects to a non-existent database.

Quick Reference

Full sequence for adding rig "myrig" with prefix "mr" from git@github.com:Org/repo.git

1. Clone and seed

cd ~/projects && git clone git@github.com:Org/repo.git repo-dir

Create .beads/ files (see Step 2 above)

cd ~/projects/repo-dir && git add .beads/ && git commit -m "feat: add .beads/" && git push

2. Add rig + init dolt

gt rig add myrig git@github.com:Org/repo.git --prefix mr gt dolt init-rig myrig gt dolt stop && gt dolt start gt dolt list # verify "myrig" appears

3. Configure remote

mkdir -p ~/dolt-remotes/myrig cd ~/gt/.dolt-data/myrig && dolt remote add origin file:///home/xexr/dolt-remotes/myrig cd ~/gt/.dolt-data/myrig && dolt push origin main

4. Verify

cd ~/gt/myrig/mayor/rig && bd doctor gt doctor