From ce9cd72c377e6f7c7a8861b27f4ec3dcefd27738 Mon Sep 17 00:00:00 2001
From: furiosa <gt@gastown.local>
Date: Sun, 11 Jan 2026 10:55:10 -0500
Subject: [PATCH] docs: clarify Beads issue ID format in README (gt-uzx2c)

Added "Issue IDs" section to Core Concepts explaining that Gas Town
uses Beads' auto-generated short IDs (e.g., gt-x7k2m) rather than
sequential numbers like GitHub issues.

Updated all example issue IDs throughout the README to use realistic
Beads-style IDs instead of confusing "issue-123" format.

Fixes: GitHub #309
---
 README.md | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index e9e39ed1..da6dbf13 100644
--- a/README.md
+++ b/README.md
@@ -77,6 +77,27 @@ Work tracking units. Bundle multiple issues/tasks that get assigned to agents.
 
 Git-backed issue tracking system that stores work state as structured data.
 
+### Issue IDs 🔢
+
+Gas Town uses [Beads](https://github.com/steveyegge/beads) for issue tracking, which generates **short random IDs** - not sequential numbers like GitHub issues.
+
+```
+gt-x7k2m    ← Gas Town issue (gt prefix)
+bd-9np4q    ← Beads issue (bd prefix)
+myproj-abc3 ← Your project (custom prefix)
+```
+
+The prefix comes from your project's Beads configuration. Find yours with `bd config get prefix`.
+
+**Common commands:**
+```bash
+bd list                    # List all issues
+bd show gt-x7k2m           # Show issue details
+bd ready                   # Issues ready for work
+```
+
+> **Note:** These are Beads IDs, not GitHub issue numbers. GitHub issue #309 might have Beads ID `gt-uzx2c`.
+
 > **New to Gas Town?** See the [Glossary](docs/glossary.md) for a complete guide to terminology and concepts.
 
 ## Installation
@@ -142,10 +163,10 @@ sequenceDiagram
 gt mayor attach
 
 # 2. In Mayor session, create a convoy
-gt convoy create "Feature X" issue-123 issue-456 --notify --human
+gt convoy create "Feature X" gt-x7k2m gt-9np4q --notify --human
 
 # 3. Assign work to an agent
-gt sling issue-123 myproject
+gt sling gt-x7k2m myproject
 
 # 4. Track progress
 gt convoy list
@@ -177,7 +198,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-a3k7x gt-b2m9y --notify
 
 # Track progress
 gt convoy list
@@ -188,8 +209,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 sling issue-123 myproject           # Assign to worker
+gt convoy create "Fix bugs" gt-f4n8p   # Create convoy (sling auto-creates if skipped)
+gt sling gt-f4n8p myproject            # Assign to worker
 claude --resume                        # Agent reads mail, runs work (Claude)
 # or: codex                            # Start Codex in the workspace
 gt convoy list                         # Check progress
@@ -264,10 +285,10 @@ bd mol pour release --var version=1.2.0
 gt convoy create "Bug Fixes" --human
 
 # Add issues
-gt convoy add-issue bug-101 bug-102
+gt convoy add-issue gt-c5p2q gt-d8r3s
 
 # Assign to specific agents
-gt sling bug-101 myproject/my-agent
+gt sling gt-c5p2q myproject/my-agent
 
 # Check status
 gt convoy show