diff --git a/README.md b/README.md
index 96f361b5..5a0cafb2 100644
--- a/README.md
+++ b/README.md
@@ -414,4 +414,4 @@ MIT License - see LICENSE file for details
 
 ---
 
-**Getting Started:** Run `gt install ~/gt --git && cd ~/gt && gt mayor attach` and tell the Mayor what you want to build!
+**Getting Started:** Run `gt install ~/gt --git && cd ~/gt && gt config agent list && gt mayor attach` (or `gt mayor attach --agent codex`) and tell the Mayor what you want to build!
diff --git a/docs/INSTALLING.md b/docs/INSTALLING.md
index 5de572de..b191fb5b 100644
--- a/docs/INSTALLING.md
+++ b/docs/INSTALLING.md
@@ -130,6 +130,29 @@ gt doctor              # Run health checks
 gt status              # Show workspace status
 ```
 
+### Step 5: Configure Agents (Optional)
+
+Gas Town supports built-in runtimes (`claude`, `gemini`, `codex`) plus custom agent aliases.
+
+```bash
+# List available agents
+gt config agent list
+
+# Create an alias (aliases can encode model/thinking flags)
+gt config agent set codex-low "codex --thinking low"
+gt config agent set claude-haiku "claude --model haiku --dangerously-skip-permissions"
+
+# Set the town default agent (used when a rig doesn't specify one)
+gt config default-agent codex-low
+```
+
+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
+```
+
 ## Minimal Mode vs Full Stack Mode
 
 Gas Town supports two operational modes:
diff --git a/internal/cmd/install.go b/internal/cmd/install.go
index 153b34ec..72c79794 100644
--- a/internal/cmd/install.go
+++ b/internal/cmd/install.go
@@ -253,6 +253,8 @@ func runInstall(cmd *cobra.Command, args []string) error {
 	}
 	fmt.Printf("  %d. Add a rig: %s\n", step, style.Dim.Render("gt rig add <name> <git-url>"))
 	step++
+	fmt.Printf("  %d. (Optional) Configure agents: %s\n", step, style.Dim.Render("gt config agent list"))
+	step++
 	fmt.Printf("  %d. Enter the Mayor's office: %s\n", step, style.Dim.Render("gt mayor attach"))
 
 	return nil
@@ -337,9 +339,9 @@ func ensureRepoFingerprint(beadsPath string) error {
 
 // initTownAgentBeads creates town-level agent and role beads using hq- prefix.
 // This creates:
-// - hq-mayor, hq-deacon (agent beads for town-level agents)
-// - hq-mayor-role, hq-deacon-role, hq-witness-role, hq-refinery-role,
-//   hq-polecat-role, hq-crew-role (role definition beads)
+//   - hq-mayor, hq-deacon (agent beads for town-level agents)
+//   - hq-mayor-role, hq-deacon-role, hq-witness-role, hq-refinery-role,
+//     hq-polecat-role, hq-crew-role (role definition beads)
 //
 // These beads are stored in town beads (~/gt/.beads/) and are shared across all rigs.
 // Rig-level agent beads (witness, refinery) are created by gt rig add in rig beads.