From 11e3e85e9dc75a0e517286e7dfd6499ac10ffb7a Mon Sep 17 00:00:00 2001
From: jv <git@codewithjv.com>
Date: Wed, 7 Jan 2026 13:05:16 +1300
Subject: [PATCH] docs: document --agent overrides

---
 README.md         | 3 +++
 docs/reference.md | 7 +++++++
 2 files changed, 10 insertions(+)

diff --git a/README.md b/README.md
index b5b44694..96f361b5 100644
--- a/README.md
+++ b/README.md
@@ -255,7 +255,9 @@ 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 <issue> <rig> --agent codex    # Override runtime for this sling/spawn
 gt mayor attach             # Start Mayor session
+gt mayor start --agent gemini           # Run Mayor with a specific agent alias
 gt prime                    # Alternative to mayor attach
 ```
 
@@ -273,6 +275,7 @@ gt convoy add-issue <issue> # Add issue to convoy
 ```bash
 # Set custom agent command
 gt config agent set claude-glm "claude-glm --model glm-4"
+gt config agent set codex-low "codex --thinking low"
 
 # Set default agent
 gt config default-agent claude-glm
diff --git a/docs/reference.md b/docs/reference.md
index a8895a65..e0c1f196 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -264,12 +264,19 @@ Note: "Swarm" is ephemeral (workers on a convoy's issues). See [Convoys](convoy.
 # Standard workflow: convoy first, then sling
 gt convoy create "Feature X" gt-abc gt-def
 gt sling gt-abc <rig>                    # Assign to polecat
+gt sling gt-abc <rig> --agent codex      # Override runtime for this sling/spawn
 gt sling <proto> --on gt-def <rig>       # With workflow template
 
 # Quick sling (auto-creates convoy)
 gt sling <bead> <rig>                    # Auto-convoy for dashboard visibility
 ```
 
+Agent overrides:
+
+- `gt start --agent <alias>` overrides the Mayor/Deacon runtime for this launch.
+- `gt mayor start|attach|restart --agent <alias>` and `gt deacon start|attach|restart --agent <alias>` do the same.
+- `gt start crew <name> --agent <alias>` and `gt crew at <name> --agent <alias>` override the crew worker runtime.
+
 ### Communication
 
 ```bash