topology-mutation-and-seat-management

1# Topology Mutation and Seat Management
2 
3The ability to change a rig **while it is alive**: expand, shrink,
4launch, remove, discover, bind, adopt, and attach seats or sessions.
5Seat management includes the **stable identifiers, edges, roles, and
6startup context** that make those mutations coherent.
7 
8**OpenRig should be easy to reach for.** A user should be able to add
9capacity, retire capacity, adopt an existing session, or attach a
10terminal **without rebuilding the whole topology.** If mutation is
11rarely tested, users avoid it and the product collapses back into
12static launch scripts.
13 
14## Use this when
15 
16- Adding seats to a running rig (`rig grow <rig-id> <member...>` for the simple case, a fragment with `rig expand` or `rig add` otherwise; see below)
17- Removing capacity (`rig shrink` / `rig remove`)
18- Launching/relaunching a node in a running rig (`rig launch`)
19- Binding a discovered session into an existing logical node (`rig bind`)
20- Adopting a topology + binding live sessions (`rig adopt`)
21- Attaching a shell or agent into a rig node (`rig attach --self`)
22 
23## Adding seats: `rig grow` first, a fragment when you need more
24 
25`rig grow <rig-id> <member...>` adds one or more seats to a running rig without
26writing YAML. Each seat gets the default agent spec and its `default` profile.
27Check `rig grow --help` on your installed version; at the time of writing:
28 
29- `--pod <pod>`: the target pod; inferred when the rig has one pod
30…