docs: clarify bead ID format in README and INSTALLING

Replace placeholder issue-123 style IDs with realistic bead ID format
(prefix + 5-char alphanumeric, e.g., gt-abc12). Add explanation of bead
ID format in Beads Integration section. Update command references and
mermaid diagrams to use consistent "bead" terminology.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

README.md

@@ -71,12 +71,14 @@ Git worktree-based persistent storage for agent work. Survives crashes and resta
 
 ### Convoys 🚚
 
-Work tracking units. Bundle multiple issues/tasks that get assigned to agents.
+Work tracking units. Bundle multiple beads that get assigned to agents.
 
 ### Beads Integration 📿
 
 Git-backed issue tracking system that stores work state as structured data.
 
+**Bead IDs** use a prefix + 5-character alphanumeric format (e.g., `gt-abc12`, `hq-x7k2m`). The prefix indicates the bead's origin or purpose. Commands like `gt sling` and `gt convoy` accept these bead IDs to reference specific work items.
+
 > **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.
 
 ## Installation
@@ -140,8 +142,8 @@ sequenceDiagram
     participant Hook
 
     You->>Mayor: Tell Mayor what to build
-    Mayor->>Convoy: Create convoy with issues
+    Mayor->>Convoy: Create convoy with beads
-    Mayor->>Agent: Sling issue to agent
+    Mayor->>Agent: Sling bead to agent
     Agent->>Hook: Store work state
     Agent->>Agent: Complete work
     Agent->>Convoy: Report completion
@@ -154,11 +156,11 @@ sequenceDiagram
 # 1. Start the Mayor
 gt mayor attach
 
-# 2. In Mayor session, create a convoy
+# 2. In Mayor session, create a convoy with bead IDs
-gt convoy create "Feature X" issue-123 issue-456 --notify --human
+gt convoy create "Feature X" gt-abc12 gt-def34 --notify --human
 
 # 3. Assign work to an agent
-gt sling issue-123 myproject
+gt sling gt-abc12 myproject
 
 # 4. Track progress
 gt convoy list
@@ -190,7 +192,7 @@ flowchart LR
 gt mayor attach
 
 # In Mayor, create convoy and let it orchestrate
-gt convoy create "Auth System" issue-101 issue-102 --notify
+gt convoy create "Auth System" gt-x7k2m gt-p9n4q --notify
 
 # Track progress
 gt convoy list
@@ -201,8 +203,8 @@ gt convoy list
 Run individual runtime instances manually. Gas Town just tracks state.
 
 ```bash
-gt convoy create "Fix bugs" issue-123  # Create convoy (sling auto-creates if skipped)
+gt convoy create "Fix bugs" gt-abc12   # Create convoy (sling auto-creates if skipped)
-gt sling issue-123 myproject           # Assign to worker
+gt sling gt-abc12 myproject            # Assign to worker
 claude --resume                        # Agent reads mail, runs work (Claude)
 # or: codex                            # Start Codex in the workspace
 gt convoy list                         # Check progress
@@ -276,11 +278,11 @@ bd mol pour release --var version=1.2.0
 # Create convoy manually
 gt convoy create "Bug Fixes" --human
 
-# Add issues
+# Add beads to convoy
-gt convoy add-issue bug-101 bug-102
+gt convoy add-issue gt-m3k9p gt-w5t2x
 
 # Assign to specific agents
-gt sling bug-101 myproject/my-agent
+gt sling gt-m3k9p myproject/my-agent
 
 # Check status
 gt convoy show
@@ -325,8 +327,8 @@ gt crew add <name> --rig <rig>  # Create crew workspace
 
 ```bash
 gt agents                   # List active agents
-gt sling <issue> <rig>      # Assign work to agent
+gt sling <bead-id> <rig>    # Assign work to agent
-gt sling <issue> <rig> --agent cursor   # Override runtime for this sling/spawn
+gt sling <bead-id> <rig> --agent cursor   # Override runtime for this sling/spawn
 gt mayor attach             # Start Mayor session
 gt mayor start --agent auggie           # Run Mayor with a specific agent alias
 gt prime                    # Context recovery (run inside existing session)
@@ -337,10 +339,10 @@ gt prime                    # Context recovery (run inside existing session)
 ### Convoy (Work Tracking)
 
 ```bash
-gt convoy create <name> [issues...] # Create convoy
+gt convoy create <name> [bead-ids...] # Create convoy with beads
 gt convoy list              # List all convoys
 gt convoy show [id]         # Show convoy details
-gt convoy add-issue <issue> # Add issue to convoy
+gt convoy add-issue <bead-id> # Add bead to convoy
 ```
 
 ### Configuration
@@ -419,9 +421,9 @@ MEOW is the recommended pattern:
 
 1. **Tell the Mayor** - Describe what you want
 2. **Mayor analyzes** - Breaks down into tasks
-3. **Convoy creation** - Mayor creates convoy with issues
+3. **Convoy creation** - Mayor creates convoy with beads
 4. **Agent spawning** - Mayor spawns appropriate agents
-5. **Work distribution** - Issues slung to agents via hooks
+5. **Work distribution** - Beads slung to agents via hooks
 6. **Progress monitoring** - Track through convoy status
 7. **Completion** - Mayor summarizes results
 

docs/INSTALLING.md

@@ -152,7 +152,7 @@ You can also override the agent per command without changing defaults:
 
 ```bash
 gt start --agent codex-low
-gt sling issue-123 myproject --agent claude-haiku
+gt sling gt-abc12 myproject --agent claude-haiku
 ```
 
 ## Minimal Mode vs Full Stack Mode
@@ -165,8 +165,8 @@ Run individual runtime instances manually. Gas Town only tracks state.
 
 ```bash
 # Create and assign work
-gt convoy create "Fix bugs" issue-123
+gt convoy create "Fix bugs" gt-abc12
-gt sling issue-123 myproject
+gt sling gt-abc12 myproject
 
 # Run runtime manually
 cd ~/gt/myproject/polecats/<worker>
@@ -188,9 +188,9 @@ Agents run in tmux sessions. Daemon manages lifecycle automatically.
 gt daemon start
 
 # Create and assign work (workers spawn automatically)
-gt convoy create "Feature X" issue-123 issue-456
+gt convoy create "Feature X" gt-abc12 gt-def34
-gt sling issue-123 myproject
+gt sling gt-abc12 myproject
-gt sling issue-456 myproject
+gt sling gt-def34 myproject
 
 # Monitor on dashboard
 gt convoy list
@@ -303,6 +303,6 @@ rm -rf ~/gt
 After installation:
 
 1. **Read the README** - Core concepts and workflows
-2. **Try a simple workflow** - `gt convoy create "Test" test-issue`
+2. **Try a simple workflow** - `bd create "Test task"` then `gt convoy create "Test" <bead-id>`
 3. **Explore docs** - `docs/reference.md` for command reference
 4. **Run doctor regularly** - `gt doctor` catches problems early