Clarify convoy vs swarm terminology in docs and code

- Convoy: Persistent tracking unit for batched work across rigs
- Swarm: Ephemeral workers on a convoy (no separate tracking)

Changes:
- docs/convoy.md: New comprehensive convoy documentation
- docs/swarm.md: Updated to explain ephemeral nature
- docs/reference.md: Replace swarm section with convoy commands
- internal/cmd/convoy.go: Clarify help text
- internal/cmd/swarm.go: Mark as deprecated

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

internal/cmd/convoy.go

@@ -26,26 +26,34 @@ var (
 var convoyCmd = &cobra.Command{
 	Use:     "convoy",
 	GroupID: GroupWork,
-	Short:   "Manage cross-rig issue tracking",
-	Long: `Manage convoys for tracking issues across multiple rigs.
+	Short:   "Track batches of work across rigs",
+	Long: `Manage convoys - the primary unit for tracking batched work.
 
-A convoy is a tracking unit that monitors issues across project chains.
-Unlike swarms (which coordinate parallel work), convoys simply track
-related issues and auto-close when all tracked issues complete.
+A convoy is a persistent tracking unit that monitors related issues across
+rigs. When you kick off work (even a single issue), a convoy tracks it so
+you can see when it lands and what was included.
 
-CONVOY VS SWARM:
-  Swarm:  Multiple polecats working on tasks from a shared base commit
-  Convoy: Cross-rig issue tracker, monitors progress without spawning workers
+WHAT IS A CONVOY:
+  - Persistent tracking unit with an ID (hq-*)
+  - Tracks issues across rigs (frontend+backend, beads+gastown, etc.)
+  - Auto-closes when all tracked issues complete → notifies subscribers
+  - Can be reopened by adding more issues
+
+WHAT IS A SWARM:
+  - Ephemeral: "the workers currently assigned to a convoy's issues"
+  - No separate ID - uses the convoy ID
+  - Dissolves when work completes
 
 TRACKING SEMANTICS:
   - 'tracks' relation is non-blocking (tracked issues don't block convoy)
   - Cross-prefix capable (convoy in hq-* tracks issues in gt-*, bd-*)
-  - Reactive completion: convoy auto-closes when all tracked issues close
+  - Landed: all tracked issues closed → notification sent to subscribers
 
 COMMANDS:
-  create    Create a new convoy tracking specified issues
-  status    Show convoy progress and tracked issues
-  list      List all convoys`,
+  create    Create a convoy tracking specified issues
+  add       Add issues to an existing convoy (reopens if closed)
+  status    Show convoy progress, tracked issues, and active workers
+  list      List convoys (the dashboard view)`,
 }
 
 var convoyCreateCmd = &cobra.Command{

internal/cmd/swarm.go

@@ -36,48 +36,25 @@ var (
 )
 
 var swarmCmd = &cobra.Command{
-	Use:     "swarm",
-	GroupID: GroupWork,
-	Short:   "Manage multi-agent swarms",
-	Long: `Manage coordinated multi-agent work units (swarms).
+	Use:        "swarm",
+	GroupID:    GroupWork,
+	Short:      "[DEPRECATED] Use 'gt convoy' instead",
+	Deprecated: "Use 'gt convoy' for work tracking. A 'swarm' is now just the ephemeral workers on a convoy.",
+	Long: `DEPRECATED: Use 'gt convoy' instead.
 
-A swarm coordinates multiple polecats working on related tasks from a shared
-base commit. Work is merged to an integration branch, then landed to main.
+The term "swarm" now refers to the ephemeral set of workers on a convoy's issues,
+not a persistent tracking unit. Use 'gt convoy' for creating and tracking batched work.
 
-SWARM LIFECYCLE:
-                          epic (tasks)
-                              │
-                              ▼
-  ┌────────────────────────────────────────────┐
-  │                   SWARM                    │
-  │  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
-  │  │ Polecat  │ │ Polecat  │ │ Polecat  │   │
-  │  │  Toast   │ │   Nux    │ │ Capable  │   │
-  │  └────┬─────┘ └────┬─────┘ └────┬─────┘   │
-  │       │            │            │         │
-  │       ▼            ▼            ▼         │
-  │  ┌──────────────────────────────────────┐ │
-  │  │        integration/<epic>            │ │
-  │  └───────────────────┬──────────────────┘ │
-  └──────────────────────┼────────────────────┘
-                         │
-                         ▼ land
-                      main
+TERMINOLOGY:
+  Convoy: Persistent tracking unit (what this command was trying to be)
+  Swarm:  Ephemeral workers on a convoy (no separate tracking needed)
 
-STATES:
-  creating  → Swarm being set up
-  active    → Workers executing tasks
-  merging   → Work being integrated
-  landed    → Successfully merged to main
-  cancelled → Swarm aborted
+MIGRATION:
+  gt swarm create  →  gt convoy create
+  gt swarm status  →  gt convoy status
+  gt swarm list    →  gt convoy list
 
-COMMANDS:
-  create    Create a new swarm from an epic
-  status    Show swarm progress
-  list      List swarms in a rig
-  land      Manually land completed swarm
-  cancel    Cancel an active swarm
-  dispatch  Assign next ready task to a worker`,
+See 'gt convoy --help' for the new workflow.`,
 }
 
 var swarmCreateCmd = &cobra.Command{