diff --git a/openapi/crucible-control.json b/openapi/crucible-control.json
index f3539a605..0af24347a 100644
--- a/openapi/crucible-control.json
+++ b/openapi/crucible-control.json
@@ -233,12 +233,35 @@
         ]
       },
       "ConnectionMode": {
-        "type": "string",
-        "enum": [
-          "offline",
-          "new",
-          "faulted",
-          "replaced"
+        "oneOf": [
+          {
+            "description": "Connect through reconciliation once a quorum has come online",
+            "type": "string",
+            "enum": [
+              "new"
+            ]
+          },
+          {
+            "description": "Replay cached jobs when reconnecting",
+            "type": "string",
+            "enum": [
+              "offline"
+            ]
+          },
+          {
+            "description": "Reconnect through live-repair",
+            "type": "string",
+            "enum": [
+              "faulted"
+            ]
+          },
+          {
+            "description": "Reconnect through live-repair; the address is allowed to change",
+            "type": "string",
+            "enum": [
+              "replaced"
+            ]
+          }
         ]
       },
       "DownstairsWork": {
@@ -264,6 +287,7 @@
         ]
       },
       "DsState": {
+        "description": "High-level states for a Downstairs\n\nThe state machine for a Downstairs is relatively simple:\n\n```text ┌────────────┐ ┌────► LiveRepair ├─────┐ ┌─────────┴┐   └─────┬──────┘   ┌─▼──────┐ │Connecting│         │          │Stopping│ └─▲───────┬┘   ┌─────▼──────┐   └─▲────┬─┘ │       └────►   Active   ├─────┘    │ │            └─────┬──────┘          │ │                  │                 │ └─────────────────◄┴─────────────────┘ ```\n\nComplexity is hidden in the `Connecting` state, which wraps a [`NegotiationState`] implementing the negotiation state machine.",
         "oneOf": [
           {
             "description": "New connection",
@@ -367,7 +391,7 @@
         ]
       },
       "NegotiationState": {
-        "description": "Tracks client negotiation progress",
+        "description": "Tracks client negotiation progress\n\nThe exact path through negotiation depends on the [`ConnectionMode`].\n\nThere are three main paths, shown below:\n\n```text ┌───────┐ │ Start ├────────┐ └───┬───┘        │ │            │ ┌─────▼──────┐     │ │ WaitActive │     │ auto-promote └─────┬──────┘     │ │            │ ┌───────▼────────┐   │ │ WaitForPromote ◄───┘ └───────┬────────┘ │ ┌────────▼──────────┐ │ WaitForRegionInfo │ └──┬──────────────┬─┘ Offline │              │ New / Faulted / Replaced ┌──────▼─────┐   ┌────▼────────────┐ │GetLastFlush│   │GetExtentVersions│ └──────┬─────┘   └─┬─────────────┬─┘ │           │ New         │ Faulted / Replaced │    ┌──────▼───┐    ┌────▼──────────┐ │    │WaitQuorum│    │LiveRepairReady│ │    └────┬─────┘    └────┬──────────┘ │         │               │ │    ┌────▼────┐          │ │    │Reconcile│          │ │    └────┬────┘          │ │         │               │ │     ┌───▼──┐            │ └─────► Done ◄────────────┘ └──────┘ ```\n\n`Done` isn't actually present in the state machine; it's indicated by returning a [`NegotiationResult`] other than [`NegotiationResult::NotDone`].",
         "oneOf": [
           {
             "description": "Initial state, waiting to hear `YesItsMe` from the client\n\nOnce this message is heard, transitions to either `WaitActive` (if `auto_promote` is `false`) or `WaitQuorum` (if `auto_promote` is `true`)",
@@ -412,13 +436,13 @@
             ]
           },
           {
-            "description": "Waiting for the minimum number of downstairs to be present.",
+            "description": "Waiting to hear `YouAreNowActive` from the client",
             "type": "object",
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "wait_quorum"
+                  "wait_for_promote"
                 ]
               }
             },
@@ -427,12 +451,13 @@
             ]
           },
           {
+            "description": "Waiting to hear `RegionInfo` from the client",
             "type": "object",
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "wait_for_promote"
+                  "wait_for_region_info"
                 ]
               }
             },
@@ -441,12 +466,13 @@
             ]
           },
           {
+            "description": "Waiting to hear `LastFlushAck` from the client",
             "type": "object",
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "wait_for_region_info"
+                  "get_last_flush"
                 ]
               }
             },
@@ -455,12 +481,13 @@
             ]
           },
           {
+            "description": "Waiting to hear `ExtentVersions` from the client",
             "type": "object",
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "get_last_flush"
+                  "get_extent_versions"
                 ]
               }
             },
@@ -469,12 +496,13 @@
             ]
           },
           {
+            "description": "Waiting for the minimum number of downstairs to be present.",
             "type": "object",
             "properties": {
               "type": {
                 "type": "string",
                 "enum": [
-                  "get_extent_versions"
+                  "wait_quorum"
                 ]
               }
             },