@1claw/openapi-spec 0.59.9 → 0.60.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.59.9",
+    "version": "0.60.0",
     "description": "Secure secret management for AI agents. Provides vaults, secrets,\npolicy-based access control, agent identity, Intents API,\nsharing, billing, and audit logging. Automations (workflow_spec,\nwebhook tokens, event triggers, Assist), cloud runtimes with\ninteractive shell sessions, agent memory, and discovery.\n\n## Domains\n\n`api.1claw.co` is canonical: it is the OIDC issuer, the `aud` the API\nmints, and the first entry in `servers` — a generated client takes its\nbase URL from there, and the previous ordering pointed every SDK at the\ndomain the issuer had already left. `api.1claw.xyz` still answers and is\nstill accepted on token validation, because tokens minted before the\nmove carry it; it is never minted now.\n\nOne deliberate exception: the Shroud attestation identity token is\nrequested from GCP with `audience: https://api.1claw.xyz`, so\n`/v1/shroud/attestation` reports that as its `expected_audience`. That\nis accurate rather than stale — the audience is a verification contract\nwith anyone already checking the token, and moving it is a breaking\nchange for them, not a rename.\n\nAll endpoints require JWT Bearer authentication unless marked with\n`security: []`.\n",
     "contact": {
       "email": "ops@1claw.co"
@@ -1228,7 +1228,7 @@
           "Approvals"
         ],
         "summary": "Request human approval (agent-only)",
-        "description": "Agents can request policy changes or other sensitive actions that require human approval.",
+        "description": "Ask a human to approve an action.\n\nTwo families of action are accepted:\n\n* the control-plane requests `access_request`, `policy_request`\n  and `binding_request`, which widen the agent's own authority; and\n* business actions named `namespace.verb` (`refund.create`,\n  `social.post`), whose meaning is carried by `summary` and `payload`.\n\nActions that 1Claw itself executes on approval — `policy_change`,\n`card_order`, `agent_transaction`, `agent_execution`,\n`agent_sign_intent` — are created by the platform and rejected here,\nbecause the summary a human reads would be agent-supplied while the\nside effect would not be.\n",
         "operationId": "requestApproval",
         "requestBody": {
           "required": true,
@@ -1245,7 +1245,9 @@
                 "properties": {
                   "action": {
                     "type": "string",
-                    "description": "Type of action (e.g. policy_change)"
+                    "maxLength": 64,
+                    "description": "Control-plane action, or a business action named `namespace.verb`.",
+                    "example": "refund.create"
                   },
                   "target_type": {
                     "type": "string"
@@ -1255,15 +1257,35 @@
                   },
                   "summary": {
                     "type": "object",
-                    "description": "JSON payload describing the request"
+                    "description": "What the human is shown: title, body, and key-value fields.",
+                    "example": {
+                      "title": "Refund $49.99",
+                      "body": "Order #1234 arrived damaged."
+                    }
+                  },
+                  "payload": {
+                    "type": "object",
+                    "description": "What the action will actually do. The enforced risk tier and\nthe human-readable line are derived from this, not from\n`summary` — the two can disagree, and only this one describes\nwhat happens if the human approves.\n",
+                    "example": {
+                      "amount_usd": "49.99",
+                      "customer_email": "a.user@example.com"
+                    }
                   },
                   "reason": {
                     "type": "string"
                   },
+                  "declared_risk_tier": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 3,
+                    "description": "Advisory. The server derives the enforced tier from the agent's\n`action_approval_policy` and the payload, then takes the higher\nof the two: a caller may raise its own bar, never lower it.\nThe response returns both.\n"
+                  },
                   "risk_tier": {
                     "type": "integer",
                     "minimum": 1,
-                    "maximum": 5
+                    "maximum": 3,
+                    "deprecated": true,
+                    "description": "Former name for `declared_risk_tier`. Still accepted."
                   }
                 }
               }
@@ -2442,7 +2464,24 @@
             }
           },
           "400": {
-            "$ref": "#/components/responses/BadRequest"
+            "description": "The name is empty or longer than 255 characters. Checked before the consensus gate and the quota, so a malformed request consumes neither an approval nor a rate-limit slot.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "A vault with that name already exists in this organization. Names are unique per org; this previously surfaced as a 500.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       },
@@ -10295,13 +10334,14 @@
         }
       }
     },
-    "/v1/platform/apps/{appId}/templates/{template_id}/preview": {
-      "post": {
+    "/v1/platform/apps/{appId}/fleets/{template_id}": {
+      "get": {
         "tags": [
           "Platform"
         ],
-        "summary": "Preview resolved template spec",
-        "description": "Resolves `{{params.*}}` and `{{subject.*}}` placeholders in a template spec\nwithout provisioning resources. Useful for validating parameterized bootstrap templates.\n",
+        "summary": "Fleet summary for a template",
+        "description": "Every agent this template provisioned, as one cohort: how many there are, how they split across the template versions they were built from, and how many a previous rollout declined to touch. plt_ or user JWT.\n",
+        "operationId": "getFleet",
         "security": [
           {
             "BearerAuth": []
@@ -10327,23 +10367,81 @@
             }
           }
         ],
-        "requestBody": {
-          "required": false,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/TemplatePreviewRequest"
+        "responses": {
+          "200": {
+            "description": "Fleet summary",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FleetSummaryResponse"
+                }
               }
             }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
-        },
+        }
+      }
+    },
+    "/v1/platform/apps/{appId}/fleets/{template_id}/agents": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "List the agents in a fleet",
+        "operationId": "listFleetAgents",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "query",
+            "name": "limit",
+            "schema": {
+              "type": "integer",
+              "default": 50,
+              "minimum": 1,
+              "maximum": 500
+            }
+          },
+          {
+            "in": "query",
+            "name": "offset",
+            "schema": {
+              "type": "integer",
+              "default": 0,
+              "minimum": 0
+            }
+          }
+        ],
         "responses": {
           "200": {
-            "description": "Resolved template spec",
+            "description": "Agents in the fleet",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/TemplatePreviewResponse"
+                  "$ref": "#/components/schemas/ListFleetAgentsResponse"
                 }
               }
             }
@@ -10354,108 +10452,178 @@
         }
       }
     },
-    "/v1/platform/users/upsert": {
+    "/v1/platform/apps/{appId}/fleets/{template_id}/bulk-patch": {
       "post": {
         "tags": [
           "Platform"
         ],
-        "summary": "Provision or look up a platform user",
-        "description": "Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.",
+        "summary": "Patch every agent in a fleet",
+        "description": "Applies one patch to every agent in the cohort. The field allowlist is deliberately narrower than a single-agent PATCH: guardrails and capability flags (intents_api_enabled, execution_intents_enabled) cannot be changed here, because at cohort scale nobody reviews the change per agent. Read the allowlist from bulk_patchable_fields on the fleet summary rather than hard-coding it. A field outside it returns 400 naming the field.\n",
+        "operationId": "bulkPatchFleet",
         "security": [
           {
             "BearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/UpsertPlatformUserRequest"
+                "type": "object",
+                "required": [
+                  "patch"
+                ],
+                "properties": {
+                  "patch": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "Fields to set on every agent in the cohort."
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Existing user found",
+            "description": "Patch applied",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/PlatformUserResponse"
+                  "type": "object",
+                  "properties": {
+                    "fields_applied": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "agents_matched": {
+                      "type": "integer",
+                      "format": "int64"
+                    },
+                    "agents_updated": {
+                      "type": "integer",
+                      "format": "int64"
+                    }
+                  }
                 }
               }
             }
           },
-          "201": {
-            "description": "New user created",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PlatformUserResponse"
-                }
-              }
-            }
+          "400": {
+            "description": "A field outside the bulk-patch allowlist, or an empty patch"
           },
-          "409": {
-            "description": "User exists in a different organization. Contains a link_required payload with an OAuth authorize URL for cross-org consent.",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PlatformUserLinkRequiredResponse"
-                }
-              }
-            }
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "/v1/platform/siwe/challenge": {
+    "/v1/platform/apps/{appId}/fleets/{template_id}/rollout": {
       "post": {
         "tags": [
           "Platform"
         ],
-        "summary": "Issue SIWE nonce",
-        "description": "Creates a one-time nonce for Sign-In With Ethereum user provisioning.\nRequires platform (`plt_`) authentication. The nonce expires in 5 minutes.\n",
+        "summary": "Roll the current template version out to its fleet",
+        "description": "Brings every agent in the cohort up to the template's current version. An agent changed outside fleet control is skipped rather than corrected, and the fields that caused the skip are recorded on it. force=true overrides that skip but still cannot carry a guardrail or a capability flag. dry_run=true reports what would happen and claims nothing, so it never blocks a real rollout. Only one rollout may run per template at a time; a second returns 409.\n",
+        "operationId": "rolloutFleet",
         "security": [
           {
             "BearerAuth": []
           }
         ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
         "requestBody": {
           "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/SiweChallengeRequest"
+                "type": "object",
+                "properties": {
+                  "force": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Overwrite hand edits. Cannot carry guardrails."
+                  },
+                  "dry_run": {
+                    "type": "boolean",
+                    "default": false,
+                    "description": "Report the plan without applying it."
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Nonce issued",
+            "description": "Rollout result",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/SiweChallengeResponse"
+                  "$ref": "#/components/schemas/FleetRolloutResponse"
                 }
               }
             }
           },
-          "400": {
-            "description": "SIWE domain not configured"
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "A rollout is already running for this template"
           }
         }
       }
     },
-    "/v1/platform/apps/{appId}/users": {
-      "get": {
+    "/v1/platform/apps/{appId}/fleets/{template_id}/pause": {
+      "post": {
         "tags": [
           "Platform"
         ],
-        "summary": "List connected users",
-        "description": "List all users connected to this platform app.",
+        "summary": "Deactivate every agent in a fleet",
+        "description": "Sets is_active=false on the whole cohort. The blast radius is the point: this exists for the moment an operator needs a thousand agents to stop at once.\n",
+        "operationId": "pauseFleet",
         "security": [
           {
             "BearerAuth": []
@@ -10470,40 +10638,47 @@
               "type": "string",
               "format": "uuid"
             }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
           }
         ],
         "responses": {
           "200": {
-            "description": "Connected users",
+            "description": "Agents paused",
             "content": {
               "application/json": {
                 "schema": {
                   "type": "object",
-                  "required": [
-                    "users"
-                  ],
                   "properties": {
-                    "users": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/PlatformConnectedUserResponse"
-                      }
+                    "agents_paused": {
+                      "type": "integer",
+                      "format": "int64"
                     }
                   }
                 }
               }
             }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "/v1/platform/connections/{connectionId}/bootstrap": {
+    "/v1/platform/apps/{appId}/templates/{template_id}/preview": {
       "post": {
         "tags": [
           "Platform"
         ],
-        "summary": "Bootstrap resources for a connected user",
-        "description": "Executes a template to create vault, agent, and policies for the connected user. Returns a claim URL and token for the user to claim their resources.",
+        "summary": "Preview resolved template spec",
+        "description": "Resolves `{{params.*}}` and `{{subject.*}}` placeholders in a template spec\nwithout provisioning resources. Useful for validating parameterized bootstrap templates.\n",
         "security": [
           {
             "BearerAuth": []
@@ -10512,7 +10687,16 @@
         "parameters": [
           {
             "in": "path",
-            "name": "connectionId",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
             "required": true,
             "schema": {
               "type": "string",
@@ -10521,26 +10705,219 @@
           }
         ],
         "requestBody": {
-          "required": true,
+          "required": false,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/BootstrapRequest"
+                "$ref": "#/components/schemas/TemplatePreviewRequest"
               }
             }
           }
         },
         "responses": {
-          "201": {
-            "description": "Resources bootstrapped",
+          "200": {
+            "description": "Resolved template spec",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/BootstrapResponse"
+                  "$ref": "#/components/schemas/TemplatePreviewResponse"
                 }
               }
             }
-          }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/users/upsert": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Provision or look up a platform user",
+        "description": "Upserts a user using either an OIDC subject_token (verified against the platform app's JWKS) or an email address. Returns the user handle and connection ID.",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/UpsertPlatformUserRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Existing user found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlatformUserResponse"
+                }
+              }
+            }
+          },
+          "201": {
+            "description": "New user created",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlatformUserResponse"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "User exists in a different organization. Contains a link_required payload with an OAuth authorize URL for cross-org consent.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PlatformUserLinkRequiredResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/platform/siwe/challenge": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Issue SIWE nonce",
+        "description": "Creates a one-time nonce for Sign-In With Ethereum user provisioning.\nRequires platform (`plt_`) authentication. The nonce expires in 5 minutes.\n",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/SiweChallengeRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Nonce issued",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/SiweChallengeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "SIWE domain not configured"
+          }
+        }
+      }
+    },
+    "/v1/platform/apps/{appId}/users": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "List connected users",
+        "description": "List all users connected to this platform app.",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Connected users",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "users"
+                  ],
+                  "properties": {
+                    "users": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PlatformConnectedUserResponse"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connectionId}/bootstrap": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Bootstrap resources for a connected user",
+        "description": "Executes a template to create vault, agent, and policies for the connected user. Returns a claim URL and token for the user to claim their resources.",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BootstrapRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Resources bootstrapped",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BootstrapResponse"
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -11651,6 +12028,40 @@
             "$ref": "#/components/responses/NotFound"
           }
         }
+      },
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Create an approval on a platform connection",
+        "operationId": "createConnectionApproval",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "201": {
+            "description": "Approval created"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
       }
     },
     "/v1/platform/connections/{connectionId}/approvals/{approvalId}": {
@@ -12250,16 +12661,13 @@
             "$ref": "#/components/responses/NotFound"
           }
         }
-      }
-    },
-    "/v1/platform/connections/{connectionId}/portfolio": {
-      "get": {
+      },
+      "post": {
         "tags": [
           "Platform"
         ],
-        "summary": "Portfolio for connection agents",
-        "description": "Aggregates signing-key and smart-account balances for agents provisioned on\nthe connection. plt_ auth only.\n",
-        "operationId": "getConnectionPortfolio",
+        "summary": "Alias for PATCH on this path — same handler, same limited settings. Present because some clients cannot send PATCH.",
+        "operationId": "postConnectionAgent",
         "security": [
           {
             "BearerAuth": []
@@ -12276,31 +12684,77 @@
             }
           },
           {
-            "in": "query",
-            "name": "chains",
-            "required": false,
+            "in": "path",
+            "name": "agentId",
+            "required": true,
             "schema": {
               "type": "string",
-              "description": "Comma-separated chain filter (e.g. `ethereum,base`)"
-            }
-          },
-          {
-            "in": "query",
-            "name": "include_tokens",
-            "required": false,
-            "schema": {
-              "type": "boolean"
+              "format": "uuid"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Connection-scoped portfolio",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/PortfolioResponse"
-                }
+            "description": "Agent updated"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/connections/{connectionId}/portfolio": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "summary": "Portfolio for connection agents",
+        "description": "Aggregates signing-key and smart-account balances for agents provisioned on\nthe connection. plt_ auth only.\n",
+        "operationId": "getConnectionPortfolio",
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "connectionId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "query",
+            "name": "chains",
+            "required": false,
+            "schema": {
+              "type": "string",
+              "description": "Comma-separated chain filter (e.g. `ethereum,base`)"
+            }
+          },
+          {
+            "in": "query",
+            "name": "include_tokens",
+            "required": false,
+            "schema": {
+              "type": "boolean"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Connection-scoped portfolio",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PortfolioResponse"
+                }
               }
             }
           },
@@ -13426,6 +13880,50 @@
             "$ref": "#/components/responses/Conflict"
           }
         }
+      },
+      "post": {
+        "tags": [
+          "Approvals"
+        ],
+        "summary": "One-click approve or deny, as an API call. The GET on this path is the preview an email link opens; this is the decision itself.",
+        "operationId": "quickDecide",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "token",
+                  "decision"
+                ],
+                "properties": {
+                  "token": {
+                    "type": "string"
+                  },
+                  "decision": {
+                    "type": "string",
+                    "enum": [
+                      "approve",
+                      "deny"
+                    ]
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Decision recorded"
+          },
+          "400": {
+            "description": "Malformed or expired token"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
       }
     },
     "/v1/deposit-destinations": {
@@ -16317,6 +16815,16 @@
           },
           "404": {
             "$ref": "#/components/responses/NotFound"
+          },
+          "503": {
+            "description": "The runtime's last start failed less than 120 seconds ago and is not\nbeing retried yet. Chat starts a stopped runtime, so a client that\nretries on failure turns every attempt into another deploy — one\npolling client did exactly that every 8 seconds for days. Wait out\nthe cooldown, or call the start endpoint to see the underlying error.\n",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ProblemDetails"
+                }
+              }
+            }
           }
         }
       }
@@ -16391,6 +16899,37 @@
             "$ref": "#/components/responses/NotFound"
           }
         }
+      },
+      "delete": {
+        "tags": [
+          "Agent Memory"
+        ],
+        "summary": "Delete a memory namespace and every entry in it. Destructive and not reversible; there is no per-entry confirmation.",
+        "operationId": "deleteMemoryNamespace",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          },
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Namespace deleted"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
       }
     },
     "/v1/agents/{agent_id}/memory/{namespace}/{key}": {
@@ -17444,95 +17983,168 @@
         }
       }
     },
-    "/v1/webhooks/discord/{webhook_path}": {
-      "post": {
+    "/v1/platform/apps/{app_id}/usage": {
+      "get": {
         "tags": [
-          "Agent Channels"
+          "Platform API"
         ],
-        "summary": "Discord webhook",
-        "description": "Public webhook endpoint for receiving Discord bot interactions.",
-        "operationId": "discordWebhook",
-        "security": [],
+        "summary": "Usage for every connection on an app",
+        "description": "Billable activity for the current month, grouped by end-user connection,\n**plus what could not be charged to one**.\n\nThe `unattributed` block is not an implementation detail. Summing only the\nper-connection numbers gives a figure that will not match the invoice you\nare reconciling against, and the gap is usage that belongs to a real\nend-user we cannot name.\n\nTwo kinds, deliberately kept apart:\n\n* `none` — no platform linkage at all. Normal for most traffic, not a problem.\n* `ambiguous` — the agent belongs to several connections and no\n  `X-Platform-Connection` header said which. This usage belongs to\n  *someone*. `has_ambiguous_usage` flags it so you do not have to notice\n  a non-zero nested number.\n\n`totals` is derived from the parts, never queried separately, so it cannot\ndisagree with its own breakdown.\n",
+        "operationId": "getAppUsage",
         "parameters": [
           {
-            "name": "webhook_path",
+            "name": "app_id",
             "in": "path",
             "required": true,
             "schema": {
-              "type": "string"
+              "type": "string",
+              "format": "uuid"
             }
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "object"
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "Webhook processed"
+            "description": "Usage report",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AppUsageReport"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "/v1/oauth/providers": {
+    "/v1/platform/apps/{app_id}/usage/export": {
       "get": {
         "tags": [
-          "OAuth Connect"
+          "Platform API"
+        ],
+        "summary": "Usage as CSV for billing reconciliation",
+        "description": "The same report as `GET /usage`, as CSV. Includes the `ambiguous`, `none`\nand `total` rows — a CSV listing only connections looks complete and is\nnot, and whoever imports it has no way to tell.\n",
+        "operationId": "exportAppUsage",
+        "parameters": [
+          {
+            "name": "app_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
         ],
-        "summary": "List OAuth providers",
-        "description": "Returns the list of supported OAuth providers with their metadata,\navailable scopes, and authorization URLs. No authentication required.\n",
-        "operationId": "listOAuthProviders",
-        "security": [],
         "responses": {
           "200": {
-            "description": "Provider list",
+            "description": "CSV",
             "content": {
-              "application/json": {
+              "text/csv": {
                 "schema": {
-                  "$ref": "#/components/schemas/OAuthProviderListResponse"
+                  "type": "string"
                 }
               }
             }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "/v1/agents/{agent_id}/oauth/connect": {
+    "/v1/org/apply": {
       "post": {
         "tags": [
-          "OAuth Connect"
-        ],
-        "summary": "Initiate OAuth connection",
-        "description": "Start an OAuth authorization flow for the specified agent and provider.\nReturns the authorization URL to redirect the user to. Human-only.\n",
-        "operationId": "connectOAuth",
-        "parameters": [
-          {
-            "$ref": "#/components/parameters/AgentId"
-          }
+          "Organization"
         ],
+        "summary": "Apply a chart",
+        "description": "Create what the chart describes. Human users only.\n\n**Apply calls the same handlers the HTTP routes call.** Creating a vault\nruns five gates before anything is written — the delegation scope, a name\ncheck, control-plane consensus, a creation rate limit and the tier quota\n— and creating an agent runs its own. A reconciler that wrote through the\nrepositories would skip all of them and would look, in review, exactly\nlike one that did not.\n\nSo if your org has consensus configured on `vault.create`, applying a\nchart queues an approval exactly as a dashboard click would. That resource\ncomes back as `awaiting_approval` rather than failing the whole chart.\n\nPer-resource results: `created`, `unchanged`, `skipped`, `refused`,\n`awaiting_approval`, `failed`. `needs_attention` is true when the chart is\nnot fully applied — something is waiting on a person, whether an approval,\nan OAuth sign-in, or a resource that drifted and was left alone.\n\nSave `applied_state` to `.1claw/apply-state.json`. It records what apply\nset, which is what lets the next run tell drift from a first apply.\n\nv1 creates and reports; it does not delete, prune, or patch in place. An\napply that silently deletes is an apply nobody runs twice.\n",
+        "operationId": "applyChart",
         "requestBody": {
           "required": true,
           "content": {
             "application/json": {
               "schema": {
-                "$ref": "#/components/schemas/ConnectOAuthRequest"
+                "type": "object",
+                "required": [
+                  "chart"
+                ],
+                "properties": {
+                  "chart": {
+                    "type": "object",
+                    "description": "A chart document — `apiVersion`, `kind`, `metadata`, `spec`."
+                  },
+                  "applied_state": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
+                }
               }
             }
           }
         },
         "responses": {
           "200": {
-            "description": "Authorization URL generated",
+            "description": "What happened to each resource",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ConnectOAuthResponse"
+                  "type": "object",
+                  "properties": {
+                    "chart_name": {
+                      "type": "string"
+                    },
+                    "resources": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "kind": {
+                            "type": "string"
+                          },
+                          "name": {
+                            "type": "string"
+                          },
+                          "result": {
+                            "type": "string",
+                            "enum": [
+                              "created",
+                              "unchanged",
+                              "skipped",
+                              "refused",
+                              "awaiting_approval",
+                              "failed"
+                            ]
+                          },
+                          "id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "detail": {
+                            "type": "string"
+                          }
+                        }
+                      }
+                    },
+                    "warnings": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "applied_state": {
+                      "type": "object",
+                      "additionalProperties": true,
+                      "description": "Save to `.1claw/apply-state.json`."
+                    },
+                    "needs_attention": {
+                      "type": "boolean",
+                      "description": "The chart is not fully applied — something is waiting on a person."
+                    }
+                  }
                 }
               }
             }
@@ -17542,19 +18154,1896 @@
           },
           "403": {
             "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
           }
         }
       }
     },
-    "/v1/agents/{agent_id}/oauth/connections": {
+    "/v1/org/approval-learning/shadow-report": {
       "get": {
         "tags": [
-          "OAuth Connect"
+          "Organization"
         ],
-        "summary": "List OAuth connections",
+        "summary": "What would have been approved automatically",
+        "description": "Every approval decision is observed, per **fingerprint bucket** — the\naction, the amount band, whether the recipient was new, and who they\nwere. This reports the buckets a person has approved without exception,\nand what promoting one would write into an agent's policy.\n\nObserving is not acting. In the default `shadow` mode nothing changes who\ngets asked; `can_promote` is false and the promote endpoint refuses.\n\nEach suggestion carries `would_write_rule` — the actual rule, built by the\nsame function promotion uses, so the report cannot promise something\npromotion would refuse.\n",
+        "operationId": "getApprovalLearningShadowReport",
+        "responses": {
+          "200": {
+            "description": "Report",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "mode": {
+                      "type": "string",
+                      "enum": [
+                        "shadow",
+                        "enforce"
+                      ]
+                    },
+                    "threshold": {
+                      "type": "integer",
+                      "description": "Consecutive approvals in one bucket before it appears here."
+                    },
+                    "can_promote": {
+                      "type": "boolean"
+                    },
+                    "observed_buckets": {
+                      "type": "integer"
+                    },
+                    "total_decisions": {
+                      "type": "integer"
+                    },
+                    "suggestions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "profile_id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "action_type": {
+                            "type": "string"
+                          },
+                          "fingerprint_bucket": {
+                            "type": "string",
+                            "example": "refund.create|0-10|known|a@b.co"
+                          },
+                          "consecutive_approvals": {
+                            "type": "integer"
+                          },
+                          "total_requests": {
+                            "type": "integer"
+                          },
+                          "would_write_rule": {
+                            "type": "object",
+                            "nullable": true
+                          },
+                          "blocked": {
+                            "type": "string",
+                            "description": "Present when a bound prevents promotion, saying which."
+                          },
+                          "last_decision_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/org/approval-learning/{profile_id}/promote": {
+      "post": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "Turn an observed pattern into a policy rule",
+        "description": "Writes a rule into the named agent's `action_approval_policy`. Human users\nonly, and only when the organisation is in `enforce` mode.\n\n**The rule covers only what was actually approved.** Five approved $5\nrefunds to one customer produce `{ refund.create, asks above $10, that\nrecipient }` — a $49 request does not match it and still reaches a human.\n\nRefused when: fewer than five consecutive approvals; *any* past rejection\non the bucket (a long recent run must not hide a history of refusals); the\nbucket is for a recipient never paid before; the amount band has no upper\nedge; or the action grants or destroys authority.\n\n`widen_to_action_type` drops the amount and recipient constraints. It is\nnever the default and should be an explicit choice in your UI, not a\ncheckbox someone skims past.\n\nThe written rule is marked `promoted_from_learning` so an operator can\ntell it apart from one they wrote, and it replaces any existing rule for\nthe same action type — appending would leave two rules where only the\nfirst ever applies.\n",
+        "operationId": "promoteApprovalLearningProfile",
+        "parameters": [
+          {
+            "name": "profile_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "agent_id"
+                ],
+                "properties": {
+                  "agent_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "widen_to_action_type": {
+                    "type": "boolean",
+                    "default": false
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Promoted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "profile_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "agent_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "rule": {
+                      "type": "object"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    },
+    "/v1/policy-presets": {
+      "get": {
+        "tags": [
+          "Policies"
+        ],
+        "summary": "Named starting points for an agent's policy",
+        "description": "Four presets an operator can choose between without reading a policy\ndocument. Public — a description of what 1Claw offers, not tenant data.\n\nEach carries a `headline`: the one-line consequence someone should read\nbefore choosing it, in the words they would use.\n",
+        "operationId": "listPolicyPresets",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Catalogue",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "presets": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/policy-preset/preview": {
+      "post": {
+        "tags": [
+          "Policies"
+        ],
+        "summary": "What a preset would change",
+        "description": "Compiles a preset against this agent and reports which fields it would\n**widen** — loosen relative to what the agent can already do.\n\nWidening detection errs toward flagging: a false positive costs one extra\napproval, a false negative is a limit raised without review. Enabling a\ncapability widens; disabling does not. Raising a cap widens; setting a\nfirst cap does not, because absent means unlimited.\n",
+        "operationId": "previewPolicyPreset",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "preset"
+                ],
+                "properties": {
+                  "preset": {
+                    "type": "string",
+                    "example": "small-business-spender"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Proposal",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "preset_slug": {
+                      "type": "string"
+                    },
+                    "guardrails": {
+                      "type": "object"
+                    },
+                    "action_approval_policy": {
+                      "type": "object"
+                    },
+                    "access_policy": {
+                      "type": "object"
+                    },
+                    "widens": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      },
+                      "description": "Fields this preset would loosen. Show these, not a generic warning."
+                    },
+                    "requires_guardrail_approval": {
+                      "type": "boolean"
+                    },
+                    "explanation": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/policy-preset": {
+      "post": {
+        "tags": [
+          "Policies"
+        ],
+        "summary": "Apply a policy preset",
+        "description": "**Applies through the agent update handler**, not by writing guardrail\ncolumns. A preset that wrote them directly would be a way around the\nguardrail widening approval flow wearing a friendlier interface.\n\nSo if the preset loosens something and your organisation gates that, you\nget the same **202 with a pending approval** you would get from editing\nthe agent by hand — not a quietly applied change. Pass `approval_id`\nonce that approval is granted.\n",
+        "operationId": "applyPolicyPreset",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "preset"
+                ],
+                "properties": {
+                  "preset": {
+                    "type": "string"
+                  },
+                  "approval_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Applied"
+          },
+          "202": {
+            "description": "Queued behind a guardrail approval"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/trust": {
+      "get": {
+        "tags": [
+          "Discovery"
+        ],
+        "summary": "What a listed agent has earned",
+        "description": "Everything a publisher writes — name, description, tags — is a claim.\nThese are the parts they cannot write: whether a human reviewed the\nlisting, how many people installed it, what they rated it.\n\nPublic, because its purpose is to be read by someone deciding whether to\ninstall a stranger's agent. Only listed agents have public trust.\n\n**A listing with reports shows no badges at all.** \"Platform reviewed\"\nbeside an active complaint tells a reader the opposite of what they need.\nAn average rating appears only from three reviews — one rating is not an\naverage.\n",
+        "operationId": "getAgentTrust",
+        "security": [],
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Trust signals",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "trust": {
+                      "type": "object",
+                      "properties": {
+                        "tier": {
+                          "type": "string",
+                          "enum": [
+                            "unverified",
+                            "platform_reviewed",
+                            "identity_verified",
+                            "enterprise"
+                          ]
+                        },
+                        "install_count": {
+                          "type": "integer"
+                        },
+                        "avg_rating": {
+                          "type": "number",
+                          "nullable": true
+                        },
+                        "review_count": {
+                          "type": "integer"
+                        },
+                        "badges": {
+                          "type": "array",
+                          "items": {
+                            "type": "string"
+                          }
+                        },
+                        "flagged_for_review": {
+                          "type": "boolean"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/report": {
+      "post": {
+        "tags": [
+          "Discovery"
+        ],
+        "summary": "Report a listed agent",
+        "description": "Human users only — an agent reporting another agent is a way to bury a\ncompetitor's listing at machine speed.\n\nThe response does not include the report count. Telling a reporter how\nclose a listing is to being flagged tells them how many more to file.\n",
+        "operationId": "reportAgent",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "Received"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/review": {
+      "post": {
+        "tags": [
+          "Discovery"
+        ],
+        "summary": "Rate an agent you have used",
+        "description": "One review per person per agent; a second replaces the first. You cannot\nreview an agent from your own organisation.\n\nComments are shown only once moderated. The rating counts either way — a\nnumber is harder to abuse than free text.\n",
+        "operationId": "reviewAgent",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "rating"
+                ],
+                "properties": {
+                  "rating": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 5
+                  },
+                  "comment": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Recorded"
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers": {
+      "post": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Create a peer and name its observers",
+        "description": "Human users only. Creating a peer decides which agents may read a model\nof a person, and an agent that could do that could add itself.\n\nIdempotent on `(org, peer_type, peer_ref)`. Observers are **merged**, not\nreplaced — a second call adding one agent does not revoke the others\nalready watching. Every named observer must be an agent in this\norganisation, so a typo or an id copied from elsewhere is an error rather\nthan a silent no-op that leaves an operator believing an agent is\nwatching when none is.\n",
+        "operationId": "createPeer",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "peer_type",
+                  "peer_ref"
+                ],
+                "properties": {
+                  "peer_type": {
+                    "type": "string",
+                    "enum": [
+                      "user",
+                      "platform_connection",
+                      "external"
+                    ]
+                  },
+                  "peer_ref": {
+                    "type": "string"
+                  },
+                  "display_name": {
+                    "type": "string"
+                  },
+                  "platform_connection_id": {
+                    "type": "string",
+                    "format": "uuid"
+                  },
+                  "observer_agent_ids": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "description": "Empty means nobody. A peer with no observers is readable by no agent."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Peer created or updated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "peer": {
+                      "$ref": "#/components/schemas/Peer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/export": {
+      "get": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Everything held about this person",
+        "description": "The whole behavioural profile plus the raw observations behind it. Human\nusers only, behind strong-factor re-auth — this is exactly what a stolen\nsession would want.\n\nEach fact carries `why_we_believe_this`: its provenance, including\ntombstones for observations that have since expired. An export listing\nconclusions without their basis answers only the easy half of the\nquestion.\n",
+        "operationId": "exportPeerData",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Export",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "peer": {
+                      "type": "object"
+                    },
+                    "facts": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "fact_key": {
+                            "type": "string"
+                          },
+                          "fact_value": {
+                            "type": "object"
+                          },
+                          "confidence": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "why_we_believe_this": {
+                            "type": "array",
+                            "items": {
+                              "type": "object"
+                            }
+                          },
+                          "corrected_by_a_human": {
+                            "type": "boolean"
+                          }
+                        }
+                      }
+                    },
+                    "raw_observations": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/data": {
+      "delete": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Forget this person",
+        "description": "Deletes the peer, its facts and its observations. Human users only,\nbehind strong-factor re-auth, and irreversible.\n\nReturns counts of what was removed — \"deleted\" with no numbers is not\nsomething anyone can check. The audit entry records that a deletion\nhappened and deliberately omits the identifier someone asked to have\nforgotten.\n",
+        "operationId": "deletePeerData",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Deleted",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "deleted": {
+                      "type": "boolean"
+                    },
+                    "facts_deleted": {
+                      "type": "integer"
+                    },
+                    "observations_deleted": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/facts": {
+      "patch": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Correct what the system believes",
+        "description": "Human users only. A correction **pins** the fact: the background\nprocessor will not re-derive over it, because someone correcting what a\nsystem believes about them outranks the inference that got it wrong.\n\nThe correction is appended to the fact's provenance as a `human` entry,\nso the record shows both what was inferred and that a person disagreed.\n",
+        "operationId": "editPeerFact",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "fact_key",
+                  "fact_value"
+                ],
+                "properties": {
+                  "fact_key": {
+                    "type": "string"
+                  },
+                  "fact_value": {
+                    "type": "object"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Corrected",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "fact_key": {
+                      "type": "string"
+                    },
+                    "edited_by_human": {
+                      "type": "boolean"
+                    },
+                    "note": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/context": {
+      "get": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "A context blob for prompt injection",
+        "description": "What this person's history suggests, as prose an agent can put in a\nprompt. Best-supported facts first, so a tight budget drops the\nleast-supported beliefs rather than an arbitrary tail — and a fact a\nhuman corrected sorts ahead of everything, because a correction someone\ntook the trouble to make is the last thing to cut.\n\nNever truncates mid-line: half a sentence about a person is worse than\none fewer sentence. A peer with no facts returns an empty string rather\nthan a header claiming to describe someone.\n\nThe blob ends by saying these are observations and not instructions,\nbecause an agent reading it needs to know the difference.\n",
+        "operationId": "getPeerContext",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "budget",
+            "in": "query",
+            "description": "Characters. Default 2000, capped at 8000.",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Context",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "context": {
+                      "type": "string"
+                    },
+                    "characters": {
+                      "type": "integer"
+                    },
+                    "budget": {
+                      "type": "integer"
+                    },
+                    "facts_available": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/peer-context": {
+      "get": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "An agent's own peer context",
+        "description": "Resolves the peer from the agent's platform connection, so an agent does\nnot need to know a peer id.\n\nAn agent may only ask for its own — otherwise this route would be a way\nto read a peer through an agent that observes it, from one that does not.\nThe observer check still applies: being the agent named in the path is\nnot the same as observing that connection's peer.\n",
+        "operationId": "getAgentPeerContext",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "budget",
+            "in": "query",
+            "schema": {
+              "type": "integer"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Context",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "peer_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "context": {
+                      "type": "string"
+                    },
+                    "characters": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}": {
+      "get": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "A peer's profile and derived facts",
+        "description": "A peer is a shared model of one human, across the agents serving them.\n\n**An agent reaches a peer only by being named in its observer list.**\nBeing in the same organisation, the same platform connection, or holding\na broad scope grants nothing. A peer with no observers is readable by no\nagent at all — forgetting to set observers must not expose someone's\nbehavioural profile to every agent in the org.\n\nA peer in another organisation returns 404, the same as an unknown id:\nwhether one exists elsewhere is not something a caller should learn.\n\nEach fact carries `provenance` — why it is believed. Entries for events\nthat have since expired become tombstones keeping the shape of what was\nseen without the content, so a belief about a person always has a\nrecoverable basis.\n",
+        "operationId": "getPeer",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Peer and facts",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "peer": {
+                      "$ref": "#/components/schemas/Peer"
+                    },
+                    "facts": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/PeerFact"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/events": {
+      "post": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Record something observed about a person",
+        "operationId": "recordPeerEvent",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "event_type",
+                  "content"
+                ],
+                "properties": {
+                  "event_type": {
+                    "type": "string",
+                    "enum": [
+                      "message",
+                      "approval",
+                      "action",
+                      "observation"
+                    ]
+                  },
+                  "content": {
+                    "type": "object",
+                    "additionalProperties": true
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Recorded",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "event_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/{peer_id}/predict-approval": {
+      "post": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "How has this person decided this before?",
+        "description": "Answers two different questions, and keeps them apart on purpose.\n\n`likelihood` is an **observation about a person** — how they have decided\ncomparable requests before. Comparable means the same fingerprint bucket,\nnot the same action type: three approvals of $5 say nothing about $500.\n\n`suggest_auto` is a **statement about a policy**. It is true only where a\nrule the operator already wrote would auto-approve this exact case. It is\nnever derived from `likelihood`, and a confident model never becomes new\nauthority. It is false, with `blocked_reason`, when:\n\n* no rule covers the action (`no_matching_rule`);\n* a rule says a human decides (`rule_requires_approval`);\n* the amount is above the rule's own threshold (`above_configured_threshold`);\n* the derived risk tier is above the lowest (`risk_tier_requires_step_up`);\n* the action grants or destroys authority (`action_is_sensitive`).\n\nThe policy consulted is the calling agent's own, so a prediction cannot\ninherit authority from another agent that happens to observe the same\nperson.\n",
+        "operationId": "predictApproval",
+        "parameters": [
+          {
+            "name": "peer_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "action_type",
+                  "effective_risk_tier"
+                ],
+                "properties": {
+                  "action_type": {
+                    "type": "string",
+                    "example": "refund.create"
+                  },
+                  "payload": {
+                    "type": "object",
+                    "additionalProperties": true
+                  },
+                  "effective_risk_tier": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 3
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Prediction",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "reasoning",
+                    "suggest_auto"
+                  ],
+                  "properties": {
+                    "likelihood": {
+                      "type": "number",
+                      "nullable": true,
+                      "description": "Absent when there is no comparable history."
+                    },
+                    "reasoning": {
+                      "type": "string"
+                    },
+                    "suggest_auto": {
+                      "type": "boolean",
+                      "description": "Whether the operator's own policy already permits this."
+                    },
+                    "blocked_reason": {
+                      "type": "string",
+                      "enum": [
+                        "no_matching_rule",
+                        "rule_requires_approval",
+                        "above_configured_threshold",
+                        "risk_tier_requires_step_up",
+                        "action_is_sensitive"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/peers/by-connection/{connection_id}": {
+      "get": {
+        "tags": [
+          "Memory"
+        ],
+        "summary": "Resolve the peer for a platform connection",
+        "operationId": "getPeerByConnection",
+        "parameters": [
+          {
+            "name": "connection_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Peer",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "peer": {
+                      "$ref": "#/components/schemas/Peer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/org/apply/diff": {
+      "post": {
+        "tags": [
+          "Organization"
+        ],
+        "summary": "What would this chart change?",
+        "description": "Reconcile a chart against the org without changing anything. Human users\nonly — a chart provisions agents, vaults and access policies, so an agent\nthat could apply one could grant itself access to a vault it cannot\ncurrently read.\n\nA POST rather than a GET because the chart is the request body, and a GET\ncarrying a body is one many proxies and clients drop or mangle. Read-only\neither way.\n\nThe plan reports five outcomes per resource:\n\n* `create` — not present, would be created.\n* `patch` — present, differs only in fields safe to change in place.\n* `unchanged` — present and matching.\n* `skipped_drifted` — **changed outside this chart**, so left alone.\n  Someone edited it by hand for a reason; overwriting that because a file\n  says otherwise is how a deployment tool destroys an incident fix.\n* `refused` — the chart asks for a change apply will not make. Guardrail\n  fields are never patched here: editing them routes through the guardrail\n  approval flow, and a reconciler writing them directly would be a way\n  around it.\n\nPass `applied_state` from `.1claw/apply-state.json` so drift can be told\nfrom a first run — a pre-existing resource is not drifted, it was simply\nnot created by this chart.\n",
+        "operationId": "diffChart",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "chart"
+                ],
+                "properties": {
+                  "chart": {
+                    "type": "object",
+                    "description": "A chart document — `apiVersion`, `kind`, `metadata`, `spec`."
+                  },
+                  "applied_state": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "What a previous apply recorded, keyed `kind/name`."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "The plan",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "chart_name": {
+                      "type": "string"
+                    },
+                    "actions": {
+                      "type": "array",
+                      "items": {
+                        "type": "object"
+                      }
+                    },
+                    "warnings": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "summary": {
+                      "type": "object",
+                      "properties": {
+                        "create": {
+                          "type": "integer"
+                        },
+                        "patch": {
+                          "type": "integer"
+                        },
+                        "skipped_drifted": {
+                          "type": "integer"
+                        },
+                        "unchanged": {
+                          "type": "integer"
+                        },
+                        "refused": {
+                          "type": "integer"
+                        },
+                        "no_changes": {
+                          "type": "boolean"
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/notification-targets": {
+      "get": {
+        "tags": [
+          "Notifications"
+        ],
+        "summary": "List your notification targets",
+        "operationId": "listNotificationTargets",
+        "responses": {
+          "200": {
+            "description": "Your targets",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "targets": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/NotificationTarget"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
+      "post": {
+        "tags": [
+          "Notifications"
+        ],
+        "summary": "Add a notification target",
+        "description": "Where approvals and automation output reach a human: a phone number, an\nhttps webhook, an email address, or a push token.\n\nAn SMS target is created **unverified** and stays that way until someone\nproves they hold the number. Adding a number must not itself be an\nauthorisation — otherwise a session borrowed for five minutes leaves\nbehind a number that can approve things long after it is gone. An\nunverified target still receives notifications; it just cannot reply to\ndecide one.\n",
+        "operationId": "createNotificationTarget",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "target_type",
+                  "config"
+                ],
+                "properties": {
+                  "target_type": {
+                    "type": "string",
+                    "enum": [
+                      "sms",
+                      "webhook",
+                      "expo",
+                      "email"
+                    ]
+                  },
+                  "config": {
+                    "type": "object",
+                    "description": "`{\"phone_number\": \"+14155550123\"}` for sms (E.164 only),\n`{\"url\": \"https://…\"}` for webhook (https only),\n`{\"email\": \"…\"}`, or `{\"push_token\": \"…\"}`.\n"
+                  },
+                  "events": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Empty means every event."
+                  },
+                  "agent_id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "The agent whose SMS channel sends to this target."
+                  },
+                  "user_id": {
+                    "type": "string",
+                    "format": "uuid",
+                    "description": "Defaults to the caller."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Target created, unverified",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/NotificationTarget"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    },
+    "/v1/notification-targets/{id}": {
+      "delete": {
+        "tags": [
+          "Notifications"
+        ],
+        "summary": "Remove a notification target",
+        "operationId": "deleteNotificationTarget",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Removed"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/notification-targets/{id}/verify/start": {
+      "post": {
+        "tags": [
+          "Notifications"
+        ],
+        "summary": "Text a verification code to an SMS target",
+        "description": "Sends a six-digit code from the same channel the target's notifications\nwill come from — a code arriving from a different number than the one\nthe recipient will later see is a code they are right to distrust.\n\nExpires in 10 minutes. Five wrong answers void it.\n",
+        "operationId": "startNotificationTargetVerification",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Code sent",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {
+                      "type": "string"
+                    },
+                    "expires_in_seconds": {
+                      "type": "integer"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/notification-targets/{id}/verify": {
+      "post": {
+        "tags": [
+          "Notifications"
+        ],
+        "summary": "Submit the verification code",
+        "operationId": "completeNotificationTargetVerification",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "code"
+                ],
+                "properties": {
+                  "code": {
+                    "type": "string",
+                    "example": "042913"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Verified",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "verified": {
+                      "type": "boolean"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/sms/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Channels"
+        ],
+        "summary": "Inbound SMS webhook (Twilio)",
+        "description": "Called by Twilio when someone texts the channel's number. Public, because\nthe provider calls it — so the `X-Twilio-Signature` header is the only\nthing establishing that a message is genuine, and it is verified over the\nexact public URL and every POST parameter.\n\nA verified signature proves the message came from Twilio, **not** that it\ncame from the right person: anyone who knows the number can text it and\ntheir message arrives correctly signed. So the sending number must also\nmatch a *verified* SMS notification target.\n\nA reply may decide an approval only when its server-derived\n`risk_tier` is 1. Anything higher is answered with a link to confirm in\nthe app; replying cannot decide it. When more than one approval is\npending, a bare YES/NO is answered with a request for the reference code\nrather than applied to a guess.\n\nAlways answers 200 with TwiML — a non-2xx makes Twilio retry a message\nthat was deliberately refused. The exception is a bad signature, which is\n403, because a persistently failing signature is a misconfiguration as\noften as an attack and silence would hide both.\n",
+        "operationId": "smsWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "X-Twilio-Signature",
+            "in": "header",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/x-www-form-urlencoded": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "From": {
+                    "type": "string",
+                    "example": "+14155550123"
+                  },
+                  "To": {
+                    "type": "string",
+                    "example": "+14155550999"
+                  },
+                  "Body": {
+                    "type": "string",
+                    "example": "YES A1"
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "TwiML response; `<Response/>` when there is nothing to reply",
+            "content": {
+              "application/xml": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/webhooks/discord/{webhook_path}": {
+      "post": {
+        "tags": [
+          "Agent Channels"
+        ],
+        "summary": "Discord webhook",
+        "description": "Public webhook endpoint for receiving Discord bot interactions.",
+        "operationId": "discordWebhook",
+        "security": [],
+        "parameters": [
+          {
+            "name": "webhook_path",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Webhook processed"
+          }
+        }
+      }
+    },
+    "/v1/oauth/providers": {
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "List OAuth providers",
+        "description": "Returns the list of supported OAuth providers with their metadata,\navailable scopes, and authorization URLs. No authentication required.\n",
+        "operationId": "listOAuthProviders",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Provider list",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/OAuthProviderListResponse"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/connectors/presets": {
+      "get": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "List connector presets",
+        "description": "The catalogue of pre-built connectors — Gmail, Slack, GitHub and the rest.\nEach preset carries the OAuth provider and scopes to request, plus the\nbinding config and host/path guardrails the agent will execute under.\n\nNo authentication required: this describes what 1Claw supports, not\nanything belonging to an organisation.\n",
+        "operationId": "listConnectorPresets",
+        "security": [],
+        "responses": {
+          "200": {
+            "description": "Preset catalogue",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "presets": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/ConnectorPreset"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/connectors": {
+      "get": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "List installed connectors",
+        "description": "Connectors installed on this agent, and whether each one has actually\nbeen connected — an install creates the binding, but the binding is not\nusable until the OAuth round trip completes.\n",
+        "operationId": "listInstalledConnectors",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Installed connectors",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "connectors": {
+                      "type": "array",
+                      "items": {
+                        "$ref": "#/components/schemas/InstalledConnector"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/connectors/{slug}/install": {
+      "post": {
+        "tags": [
+          "Connectors"
+        ],
+        "summary": "Install a connector",
+        "description": "Creates a binding from the preset — base URL, allowed hosts, allowed\npaths — and starts the OAuth flow for it. Send the user to the returned\n`authorization_url` to finish; until they do, the binding exists but\nholds no credential.\n\nHuman users only. Installing gives an agent reach into a third-party\naccount, and the flow it starts is a person's browser.\n\nIdempotent by binding name: re-installing re-runs the OAuth flow against\nthe existing binding rather than creating a second one holding a second\ntoken for the same account. A name already taken by a binding that is\nnot this connector returns 409.\n",
+        "operationId": "installConnector",
+        "parameters": [
+          {
+            "name": "agent_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "name": "slug",
+            "in": "path",
+            "required": true,
+            "description": "Connector preset slug, e.g. `gmail`.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "binding_name": {
+                    "type": "string",
+                    "description": "Defaults to the preset slug."
+                  },
+                  "scopes": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Narrow the preset's scopes. Widening is refused — the\npreset's scope list is the reviewed part of a one-click\ninstall. Must still include the preset's required scopes.\n"
+                  },
+                  "redirect_after": {
+                    "type": "string",
+                    "description": "Where to send the user after the OAuth round trip."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Connector installed; OAuth may still be pending",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "binding_id",
+                    "binding_name",
+                    "preset_slug",
+                    "next_step"
+                  ],
+                  "properties": {
+                    "binding_id": {
+                      "type": "string",
+                      "format": "uuid"
+                    },
+                    "binding_name": {
+                      "type": "string"
+                    },
+                    "preset_slug": {
+                      "type": "string"
+                    },
+                    "authorization_url": {
+                      "type": "string",
+                      "nullable": true,
+                      "description": "Absent for connectors that use a pasted API key rather than OAuth."
+                    },
+                    "next_step": {
+                      "type": "string",
+                      "description": "What the user still has to do, in words."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/oauth/connect": {
+      "post": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "Initiate OAuth connection",
+        "description": "Start an OAuth authorization flow for the specified agent and provider.\nReturns the authorization URL to redirect the user to. Human-only.\n",
+        "operationId": "connectOAuth",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/AgentId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ConnectOAuthRequest"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Authorization URL generated",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ConnectOAuthResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/agents/{agent_id}/oauth/connections": {
+      "get": {
+        "tags": [
+          "OAuth Connect"
+        ],
+        "summary": "List OAuth connections",
         "description": "List all active OAuth connections for the specified agent.",
         "operationId": "listOAuthConnections",
         "parameters": [
@@ -19570,58 +22059,11 @@
     "/v1/auth/credential-recovery/requests/{id}/approve": {
       "post": {
         "tags": [
-          "Credential Recovery"
-        ],
-        "summary": "Approve a recovery request",
-        "description": "Admin/owner approves a pending recovery request. May return a one-time recovery code.",
-        "operationId": "approveCredentialRecovery",
-        "security": [
-          {
-            "BearerAuth": []
-          }
-        ],
-        "parameters": [
-          {
-            "name": "id",
-            "in": "path",
-            "required": true,
-            "schema": {
-              "type": "string",
-              "format": "uuid"
-            }
-          }
-        ],
-        "responses": {
-          "200": {
-            "description": "Request approved",
-            "content": {
-              "application/json": {
-                "schema": {
-                  "$ref": "#/components/schemas/CredentialRecoveryApproveResponse"
-                }
-              }
-            }
-          },
-          "401": {
-            "$ref": "#/components/responses/Unauthorized"
-          },
-          "403": {
-            "$ref": "#/components/responses/Forbidden"
-          },
-          "404": {
-            "$ref": "#/components/responses/NotFound"
-          }
-        }
-      }
-    },
-    "/v1/auth/credential-recovery/requests/{id}/execute": {
-      "post": {
-        "tags": [
-          "Credential Recovery"
-        ],
-        "summary": "Execute an approved credential recovery request",
-        "description": "Execute an approved credential recovery request after the delay window has elapsed. Only org owners or admins can execute.",
-        "operationId": "executeCredentialRecovery",
+          "Credential Recovery"
+        ],
+        "summary": "Approve a recovery request",
+        "description": "Admin/owner approves a pending recovery request. May return a one-time recovery code.",
+        "operationId": "approveCredentialRecovery",
         "security": [
           {
             "BearerAuth": []
@@ -19640,11 +22082,11 @@
         ],
         "responses": {
           "200": {
-            "description": "Recovery executed",
+            "description": "Request approved",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/CredentialRecoveryExecuteResponse"
+                  "$ref": "#/components/schemas/CredentialRecoveryApproveResponse"
                 }
               }
             }
@@ -19661,13 +22103,14 @@
         }
       }
     },
-    "/v1/auth/credential-recovery/requests/{id}": {
-      "delete": {
+    "/v1/auth/credential-recovery/requests/{id}/execute": {
+      "post": {
         "tags": [
           "Credential Recovery"
         ],
-        "summary": "Cancel or reject a recovery request",
-        "operationId": "cancelCredentialRecovery",
+        "summary": "Execute an approved credential recovery request",
+        "description": "Execute an approved credential recovery request after the delay window has elapsed. Only org owners or admins can execute.",
+        "operationId": "executeCredentialRecovery",
         "security": [
           {
             "BearerAuth": []
@@ -19685,8 +22128,15 @@
           }
         ],
         "responses": {
-          "204": {
-            "description": "Request cancelled"
+          "200": {
+            "description": "Recovery executed",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CredentialRecoveryExecuteResponse"
+                }
+              }
+            }
           },
           "401": {
             "$ref": "#/components/responses/Unauthorized"
@@ -22204,6 +24654,99 @@
             "description": "That label is already pinned to a different key"
           }
         }
+      },
+      "get": {
+        "tags": [
+          "Browser Bridge"
+        ],
+        "summary": "List the browser bridges paired to this organization. Revoked devices are included: 'was this machine ever paired' is the question asked after a laptop goes missing.",
+        "operationId": "list_browser_devices",
+        "responses": {
+          "200": {
+            "description": "The paired devices. No credential material is returned — the row holds an Argon2 hash and a prefix, and neither is exposed.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "devices": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {
+                            "type": "string",
+                            "format": "uuid"
+                          },
+                          "label": {
+                            "type": "string"
+                          },
+                          "platform": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "bridge_version": {
+                            "type": "string",
+                            "nullable": true
+                          },
+                          "last_seen_at": {
+                            "type": "string",
+                            "format": "date-time",
+                            "nullable": true
+                          },
+                          "revoked_at": {
+                            "type": "string",
+                            "format": "date-time",
+                            "nullable": true,
+                            "description": "Set once revoked. A revoked credential stops resolving."
+                          },
+                          "created_at": {
+                            "type": "string",
+                            "format": "date-time"
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Unauthenticated"
+          }
+        }
+      }
+    },
+    "/v1/browser/devices/{id}": {
+      "delete": {
+        "tags": [
+          "Browser Bridge"
+        ],
+        "summary": "Revoke a paired bridge. This is what makes a leaked bb_ credential stop working.",
+        "operationId": "revoke_browser_device",
+        "parameters": [
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "204": {
+            "description": "Revoked. Subsequent use of that credential resolves to nothing."
+          },
+          "401": {
+            "description": "Unauthenticated"
+          },
+          "404": {
+            "description": "No such device in this organization"
+          }
+        }
       }
     },
     "/v1/browser/credentials": {
@@ -22249,7 +24792,7 @@
                     "items": {
                       "type": "string"
                     },
-                    "description": "Bare hostnames, compared exactly. URLs, ports and wildcards are refused: a wildcard would match nothing while looking like it allowed something."
+                    "description": "Hostnames. A bare entry matches only itself; a leading dot ('.example.com') matches that host and any subdomain. URLs, ports and '*' are refused — '*' has no meaning to the matcher, so it would be stored and then match nothing."
                   },
                   "sso_hosts": {
                     "type": "array",
@@ -22475,7 +25018,11 @@
                   "tab_origin",
                   "frame_origin",
                   "frame_id",
-                  "generation"
+                  "generation",
+                  "form_path",
+                  "field_names",
+                  "redirect_chain",
+                  "current_generation"
                 ],
                 "properties": {
                   "session_id": {
@@ -22498,7 +25045,30 @@
                   },
                   "form_action_origin": {
                     "type": "string",
-                    "description": "Where the form would POST. Checked as well as the two origins — a login form on an allowed page can still submit to somebody else's host."
+                    "description": "Where the form would POST. Checked as well as the two origins — a login form on an allowed page can still submit to somebody else's host. Absent is not treated as 'same as the tab'; it denies."
+                  },
+                  "form_path": {
+                    "type": "string",
+                    "description": "Path of the form being filled, checked against the binding's fingerprint."
+                  },
+                  "field_names": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Field names on that form. Every field the fingerprint expects must be present; extra fields are fine, since sites add hidden inputs."
+                  },
+                  "redirect_chain": {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    },
+                    "description": "Hosts the login has redirected through, in order. Each is checked against the binding's allowed hosts union its sso hosts."
+                  },
+                  "current_generation": {
+                    "type": "integer",
+                    "format": "int64",
+                    "description": "The target's generation now. A mismatch with `generation` means the page moved and the fill is denied."
                   },
                   "tab_origin": {
                     "type": "string",
@@ -23769,7 +26339,10 @@
         ],
         "properties": {
           "name": {
-            "type": "string"
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 255,
+            "description": "Unique within the organization. Trimmed before it is stored, and the trimmed value is what must be unique. Counted in characters, not bytes."
           },
           "description": {
             "type": "string"
@@ -24598,6 +27171,12 @@
             "nullable": true,
             "description": "Graduated transaction approval policy (HITL thresholds). Separate from hard guardrails."
           },
+          "action_approval_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "nullable": true,
+            "description": "Which business actions this agent must ask a human about, and above what\namount. `{}` means no per-action rules.\n\nShape: `{ \"default_mode\": \"deny|approve|allow\", \"rules\": [ { \"action_type\":\n\"refund.create\", \"mode\": \"approve\", \"require_for_amount_above_usd\": \"50\",\n\"summary_template\": \"Refund {{amount_usd}} to {{customer_email}}\" } ] }`.\n\nA rule can only raise the bar. Editing this is classified as a guardrail\nwidening, so it routes through the same approval flow as loosening a\ntransaction limit. Malformed rules are rejected on write rather than\nignored at request time.\n"
+          },
           "typed_data_policy": {
             "type": "string",
             "enum": [
@@ -24843,6 +27422,12 @@
             "nullable": true,
             "description": "Graduated transaction approval policy (HITL thresholds)."
           },
+          "action_approval_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "nullable": true,
+            "description": "Which business actions this agent must ask a human about, and above what\namount. `{}` means no per-action rules.\n\nShape: `{ \"default_mode\": \"deny|approve|allow\", \"rules\": [ { \"action_type\":\n\"refund.create\", \"mode\": \"approve\", \"require_for_amount_above_usd\": \"50\",\n\"summary_template\": \"Refund {{amount_usd}} to {{customer_email}}\" } ] }`.\n\nA rule can only raise the bar. Editing this is classified as a guardrail\nwidening, so it routes through the same approval flow as loosening a\ntransaction limit. Malformed rules are rejected on write rather than\nignored at request time.\n"
+          },
           "typed_data_policy": {
             "type": "string",
             "enum": [
@@ -25188,6 +27773,12 @@
             "nullable": true,
             "description": "Graduated transaction approval policy (HITL thresholds)."
           },
+          "action_approval_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "nullable": true,
+            "description": "Which business actions this agent must ask a human about, and above what\namount. `{}` means no per-action rules.\n\nShape: `{ \"default_mode\": \"deny|approve|allow\", \"rules\": [ { \"action_type\":\n\"refund.create\", \"mode\": \"approve\", \"require_for_amount_above_usd\": \"50\",\n\"summary_template\": \"Refund {{amount_usd}} to {{customer_email}}\" } ] }`.\n\nA rule can only raise the bar. Editing this is classified as a guardrail\nwidening, so it routes through the same approval flow as loosening a\ntransaction limit. Malformed rules are rejected on write rather than\nignored at request time.\n"
+          },
           "typed_data_policy": {
             "type": "string",
             "enum": [
@@ -30087,39 +32678,240 @@
           }
         }
       },
-      "PlatformTemplateResponse": {
+      "PlatformTemplateResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "platform_app_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "version": {
+            "type": "integer"
+          },
+          "spec": {
+            "type": "object"
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "FleetSummaryResponse": {
+        "type": "object",
+        "properties": {
+          "template_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "template_name": {
+            "type": "string"
+          },
+          "current_version": {
+            "type": "integer"
+          },
+          "spec_hash": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "description": "SHA-256 of the template spec. Lets a caller tell a version bump that changed nothing from one that did. Null on templates written before migration 245.\n"
+          },
+          "total_agents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "version_skew": {
+            "type": "array",
+            "description": "How the cohort splits across the versions it was provisioned from.",
+            "items": {
+              "type": "object",
+              "properties": {
+                "template_version": {
+                  "type": [
+                    "integer",
+                    "null"
+                  ]
+                },
+                "agents": {
+                  "type": "integer",
+                  "format": "int64"
+                }
+              }
+            }
+          },
+          "agents_on_current_version": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "agents_behind": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "drifted_agents": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Agents a previous rollout declined to touch."
+          },
+          "bulk_patchable_fields": {
+            "type": "array",
+            "description": "The fields bulk-patch and rollout will carry. Read this rather than hard-coding the list; it is deliberately narrower than a single-agent PATCH and may narrow further.\n",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "ListFleetAgentsResponse": {
+        "type": "object",
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/FleetAgent"
+            }
+          },
+          "limit": {
+            "type": "integer"
+          },
+          "offset": {
+            "type": "integer"
+          },
+          "current_version": {
+            "type": "integer"
+          }
+        }
+      },
+      "FleetAgent": {
+        "type": "object",
+        "properties": {
+          "agent_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "org_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "platform_connection_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uuid"
+          },
+          "provisioned_from_version": {
+            "type": [
+              "integer",
+              "null"
+            ]
+          },
+          "last_fleet_sync_at": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "date-time"
+          },
+          "drift_fields": {
+            "type": "array",
+            "description": "Fields a rollout skipped because they were changed outside fleet control. The standing answer to \"why is this agent behind?\".\n",
+            "items": {
+              "type": "string"
+            }
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "is_current": {
+            "type": "boolean"
+          }
+        }
+      },
+      "FleetRolloutResponse": {
         "type": "object",
         "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid"
+          "job_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uuid",
+            "description": "Null for a dry run, which claims no job."
           },
-          "platform_app_id": {
-            "type": "string",
-            "format": "uuid"
+          "to_version": {
+            "type": "integer"
           },
-          "name": {
-            "type": "string"
+          "dry_run": {
+            "type": "boolean"
           },
-          "description": {
-            "type": "string"
+          "forced": {
+            "type": "boolean"
           },
-          "version": {
-            "type": "integer"
+          "total_agents": {
+            "type": "integer",
+            "format": "int64"
           },
-          "spec": {
-            "type": "object"
+          "synced": {
+            "type": "integer"
           },
-          "is_active": {
-            "type": "boolean"
+          "already_current": {
+            "type": "integer"
           },
-          "created_at": {
-            "type": "string",
-            "format": "date-time"
+          "skipped_drifted": {
+            "type": "integer"
           },
-          "updated_at": {
-            "type": "string",
-            "format": "date-time"
+          "outcomes": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "outcome": {
+                  "type": "string",
+                  "enum": [
+                    "already_current",
+                    "synced",
+                    "skipped_drifted"
+                  ]
+                },
+                "agent_id": {
+                  "type": "string",
+                  "format": "uuid"
+                },
+                "fields": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                },
+                "drift_fields": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              }
+            }
           }
         }
       },
@@ -30784,13 +33576,277 @@
           }
         }
       },
-      "DeviceResponse": {
+      "DeviceResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "platform",
+          "attestation_verified",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "platform": {
+            "type": "string"
+          },
+          "attestation_verified": {
+            "type": "boolean"
+          },
+          "last_used_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "CreateDeviceChallengeRequest": {
+        "type": "object",
+        "required": [
+          "action",
+          "target_id"
+        ],
+        "properties": {
+          "action": {
+            "type": "string",
+            "description": "The action this challenge authorizes (e.g. \"approve_transaction\")"
+          },
+          "target_id": {
+            "type": "string",
+            "description": "ID of the resource the action targets"
+          }
+        }
+      },
+      "DeviceChallengeResponse": {
+        "type": "object",
+        "required": [
+          "challenge_nonce",
+          "expires_at",
+          "action_bound_hash"
+        ],
+        "properties": {
+          "challenge_nonce": {
+            "type": "string"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "action_bound_hash": {
+            "type": "string",
+            "description": "SHA-256 binding the challenge to the requested action and target"
+          }
+        }
+      },
+      "AttestDeviceChallengeRequest": {
+        "type": "object",
+        "required": [
+          "challenge_nonce",
+          "signature"
+        ],
+        "properties": {
+          "challenge_nonce": {
+            "type": "string"
+          },
+          "signature": {
+            "type": "string",
+            "description": "Signature over the challenge nonce using the device's private key"
+          }
+        }
+      },
+      "AttestDeviceChallengeResponse": {
+        "type": "object",
+        "required": [
+          "step_up_token",
+          "expires_at"
+        ],
+        "properties": {
+          "step_up_token": {
+            "type": "string",
+            "description": "Short-lived token authorizing the bound action"
+          },
+          "expires_at": {
+            "type": "string",
+            "format": "date-time"
+          }
+        }
+      },
+      "RegisterPushTokenRequest": {
+        "type": "object",
+        "required": [
+          "token",
+          "platform"
+        ],
+        "properties": {
+          "token": {
+            "type": "string",
+            "description": "Push notification token from APNs or FCM"
+          },
+          "platform": {
+            "type": "string",
+            "enum": [
+              "apns",
+              "fcm"
+            ]
+          }
+        }
+      },
+      "DecideApprovalRequest": {
+        "type": "object",
+        "required": [
+          "decision"
+        ],
+        "properties": {
+          "decision": {
+            "type": "string",
+            "enum": [
+              "approve",
+              "reject"
+            ]
+          },
+          "reason": {
+            "type": "string",
+            "description": "Optional human-readable reason for the decision"
+          }
+        }
+      },
+      "UsageCounts": {
+        "type": "object",
+        "required": [
+          "api_requests",
+          "signatures",
+          "execution_intents",
+          "execution_intents_tee",
+          "inference_usd",
+          "credits_debited_cents"
+        ],
+        "properties": {
+          "api_requests": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "signatures": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "execution_intents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "execution_intents_tee": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "inference_usd": {
+            "type": "string",
+            "description": "A decimal string. Money is not a float; zero is \"0\".",
+            "example": "3.42"
+          },
+          "credits_debited_cents": {
+            "type": "integer",
+            "format": "int64"
+          }
+        }
+      },
+      "AppUsageReport": {
+        "type": "object",
+        "required": [
+          "app_id",
+          "period_start",
+          "period_end",
+          "connections",
+          "unattributed",
+          "totals",
+          "has_ambiguous_usage"
+        ],
+        "properties": {
+          "app_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "period_start": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "period_end": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Exclusive. The period is half-open, so an event at midnight belongs to one month, not two."
+          },
+          "connections": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "connection_id",
+                "usage"
+              ],
+              "properties": {
+                "connection_id": {
+                  "type": "string",
+                  "format": "uuid"
+                },
+                "usage": {
+                  "$ref": "#/components/schemas/UsageCounts"
+                }
+              }
+            }
+          },
+          "unattributed": {
+            "type": "object",
+            "description": "Usage that could not be charged to a connection.",
+            "properties": {
+              "ambiguous": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UsageCounts"
+                  }
+                ],
+                "description": "The agent belongs to several connections and none was named. This belongs to someone."
+              },
+              "none": {
+                "allOf": [
+                  {
+                    "$ref": "#/components/schemas/UsageCounts"
+                  }
+                ],
+                "description": "No platform linkage. Normal for most traffic."
+              }
+            }
+          },
+          "totals": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UsageCounts"
+              }
+            ],
+            "description": "Connections plus both unattributed buckets. Derived, not queried."
+          },
+          "has_ambiguous_usage": {
+            "type": "boolean",
+            "description": "Some usage this period belongs to an end-user who cannot be identified."
+          }
+        }
+      },
+      "Peer": {
         "type": "object",
         "required": [
           "id",
-          "name",
-          "platform",
-          "attestation_verified",
+          "peer_type",
+          "peer_ref",
+          "profile",
+          "status",
+          "observer_count",
           "created_at"
         ],
         "properties": {
@@ -30798,133 +33854,255 @@
             "type": "string",
             "format": "uuid"
           },
-          "name": {
-            "type": "string"
+          "peer_type": {
+            "type": "string",
+            "enum": [
+              "user",
+              "platform_connection",
+              "external"
+            ]
           },
-          "platform": {
+          "peer_ref": {
             "type": "string"
           },
-          "attestation_verified": {
-            "type": "boolean"
-          },
-          "last_used_at": {
+          "display_name": {
             "type": "string",
-            "format": "date-time",
             "nullable": true
           },
+          "profile": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "active",
+              "archived"
+            ],
+            "description": "Archived when a connection is disconnected. Agents lose observation;\nthe person keeps export and delete.\n"
+          },
+          "observer_count": {
+            "type": "integer",
+            "description": "How many agents observe this peer. The list itself is not returned here."
+          },
           "created_at": {
             "type": "string",
             "format": "date-time"
           }
         }
       },
-      "CreateDeviceChallengeRequest": {
+      "PeerFact": {
         "type": "object",
         "required": [
-          "action",
-          "target_id"
+          "fact_key",
+          "fact_value",
+          "provenance",
+          "edited_by_human",
+          "updated_at"
         ],
         "properties": {
-          "action": {
+          "fact_key": {
             "type": "string",
-            "description": "The action this challenge authorizes (e.g. \"approve_transaction\")"
+            "example": "approval_tendency:refund.create|0-10|known|a@b.co"
           },
-          "target_id": {
+          "fact_value": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "confidence": {
             "type": "string",
-            "description": "ID of the resource the action targets"
+            "nullable": true,
+            "description": "0..1, capped below certainty — no history makes the next decision certain."
+          },
+          "provenance": {
+            "type": "array",
+            "items": {
+              "type": "object"
+            },
+            "description": "Why this is believed. Entries are `event`, `tombstone` (the event has\nexpired; kind and decision are kept, content is not) or `human`.\n"
+          },
+          "edited_by_human": {
+            "type": "boolean",
+            "description": "A person corrected this. The processor will not overwrite it."
+          },
+          "updated_at": {
+            "type": "string",
+            "format": "date-time"
           }
         }
       },
-      "DeviceChallengeResponse": {
+      "NotificationTarget": {
         "type": "object",
         "required": [
-          "challenge_nonce",
-          "expires_at",
-          "action_bound_hash"
+          "id",
+          "target_type",
+          "config",
+          "events",
+          "is_active",
+          "verified",
+          "created_at"
         ],
         "properties": {
-          "challenge_nonce": {
-            "type": "string"
+          "id": {
+            "type": "string",
+            "format": "uuid"
           },
-          "expires_at": {
+          "target_type": {
             "type": "string",
-            "format": "date-time"
+            "enum": [
+              "sms",
+              "webhook",
+              "expo",
+              "email"
+            ]
           },
-          "action_bound_hash": {
+          "user_id": {
             "type": "string",
-            "description": "SHA-256 binding the challenge to the requested action and target"
+            "format": "uuid",
+            "nullable": true
+          },
+          "agent_id": {
+            "type": "string",
+            "format": "uuid",
+            "nullable": true
+          },
+          "config": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "events": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "verified": {
+            "type": "boolean",
+            "description": "An unverified SMS target receives notifications but cannot decide\nan approval by reply.\n"
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
           }
         }
       },
-      "AttestDeviceChallengeRequest": {
+      "ConnectorPreset": {
         "type": "object",
         "required": [
-          "challenge_nonce",
-          "signature"
+          "slug",
+          "display_name",
+          "description",
+          "category",
+          "binding_type",
+          "base_url",
+          "requires_oauth"
         ],
         "properties": {
-          "challenge_nonce": {
+          "slug": {
+            "type": "string",
+            "example": "gmail"
+          },
+          "display_name": {
+            "type": "string",
+            "example": "Gmail"
+          },
+          "description": {
             "type": "string"
           },
-          "signature": {
+          "category": {
             "type": "string",
-            "description": "Signature over the challenge nonce using the device's private key"
-          }
-        }
-      },
-      "AttestDeviceChallengeResponse": {
-        "type": "object",
-        "required": [
-          "step_up_token",
-          "expires_at"
-        ],
-        "properties": {
-          "step_up_token": {
+            "example": "communication"
+          },
+          "provider_slug": {
             "type": "string",
-            "description": "Short-lived token authorizing the bound action"
+            "nullable": true,
+            "description": "`oauth_providers.slug`, or null when the connector uses a pasted API key."
           },
-          "expires_at": {
+          "oauth_scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "required_scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Scopes without which the connector cannot do anything."
+          },
+          "binding_type": {
             "type": "string",
-            "format": "date-time"
-          }
-        }
-      },
-      "RegisterPushTokenRequest": {
-        "type": "object",
-        "required": [
-          "token",
-          "platform"
-        ],
-        "properties": {
-          "token": {
+            "example": "http"
+          },
+          "base_url": {
             "type": "string",
-            "description": "Push notification token from APNs or FCM"
+            "format": "uri"
           },
-          "platform": {
+          "allowed_hosts": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Hosts the installed binding may reach. Always includes the base URL's host."
+          },
+          "documentation_url": {
             "type": "string",
-            "enum": [
-              "apns",
-              "fcm"
-            ]
+            "format": "uri"
+          },
+          "tier_required": {
+            "type": "string",
+            "example": "free"
+          },
+          "requires_oauth": {
+            "type": "boolean"
           }
         }
       },
-      "DecideApprovalRequest": {
+      "InstalledConnector": {
         "type": "object",
         "required": [
-          "decision"
+          "binding_id",
+          "binding_name",
+          "preset_slug",
+          "is_active",
+          "connected",
+          "needs_reauth",
+          "created_at"
         ],
         "properties": {
-          "decision": {
+          "binding_id": {
             "type": "string",
-            "enum": [
-              "approve",
-              "reject"
-            ]
+            "format": "uuid"
           },
-          "reason": {
+          "binding_name": {
+            "type": "string"
+          },
+          "preset_slug": {
+            "type": "string"
+          },
+          "display_name": {
             "type": "string",
-            "description": "Optional human-readable reason for the decision"
+            "nullable": true,
+            "description": "Null if the preset has since been retired from the catalogue."
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "connected": {
+            "type": "boolean",
+            "description": "The OAuth round trip completed and a token is stored."
+          },
+          "needs_reauth": {
+            "type": "boolean",
+            "description": "The stored token was rejected; the user must reconnect."
+          },
+          "created_at": {
+            "type": "string",
+            "format": "date-time"
           }
         }
       },
@@ -30972,7 +34150,28 @@
           "risk_tier": {
             "type": "integer",
             "minimum": 1,
-            "maximum": 3
+            "maximum": 3,
+            "description": "The tier actually enforced. Authoritative."
+          },
+          "declared_risk_tier": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 3,
+            "nullable": true,
+            "description": "What the caller asked for, when it asked for anything."
+          },
+          "declared_below_floor": {
+            "type": "boolean",
+            "description": "The caller asked for a lower tier than policy required."
+          },
+          "human_summary": {
+            "type": "string",
+            "nullable": true,
+            "description": "Plain-language line sent to SMS, push and email."
+          },
+          "payload": {
+            "type": "object",
+            "description": "What the action will do, as submitted."
           },
           "status": {
             "type": "string",
@@ -31486,7 +34685,10 @@
         "required": [
           "connection_id",
           "period",
-          "inference_spent_usd"
+          "inference_spent_usd",
+          "usage",
+          "period_start",
+          "period_end"
         ],
         "properties": {
           "connection_id": {
@@ -31498,7 +34700,25 @@
             "description": "UTC month (YYYY-MM)"
           },
           "inference_spent_usd": {
-            "type": "string"
+            "type": "string",
+            "description": "Kept for compatibility — this field predates the breakdown below and\nexisting integrations read it. Same number as `usage.inference_usd`.\n"
+          },
+          "usage": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UsageCounts"
+              }
+            ],
+            "description": "Everything billable for this connection in the period. Derived from the\nsame grouped query as the app report, so a connection can never report a\nnumber the app report disagrees with.\n"
+          },
+          "period_start": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "period_end": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Exclusive. The period is half-open."
           }
         }
       },