@1claw/openapi-spec 0.59.10 → 0.60.0

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "1Claw API",
-    "version": "0.59.10",
+    "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."
                   }
                 }
               }
@@ -10312,6 +10334,344 @@
         }
       }
     },
+    "/v1/platform/apps/{appId}/fleets/{template_id}": {
+      "get": {
+        "tags": [
+          "Platform"
+        ],
+        "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": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "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": "Agents in the fleet",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ListFleetAgentsResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/apps/{appId}/fleets/{template_id}/bulk-patch": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "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": {
+                "type": "object",
+                "required": [
+                  "patch"
+                ],
+                "properties": {
+                  "patch": {
+                    "type": "object",
+                    "additionalProperties": true,
+                    "description": "Fields to set on every agent in the cohort."
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Patch applied",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "fields_applied": {
+                      "type": "array",
+                      "items": {
+                        "type": "string"
+                      }
+                    },
+                    "agents_matched": {
+                      "type": "integer",
+                      "format": "int64"
+                    },
+                    "agents_updated": {
+                      "type": "integer",
+                      "format": "int64"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "A field outside the bulk-patch allowlist, or an empty patch"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/apps/{appId}/fleets/{template_id}/rollout": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "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": {
+                "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": "Rollout result",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/FleetRolloutResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "description": "A rollout is already running for this template"
+          }
+        }
+      }
+    },
+    "/v1/platform/apps/{appId}/fleets/{template_id}/pause": {
+      "post": {
+        "tags": [
+          "Platform"
+        ],
+        "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": []
+          }
+        ],
+        "parameters": [
+          {
+            "in": "path",
+            "name": "appId",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          {
+            "in": "path",
+            "name": "template_id",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Agents paused",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "agents_paused": {
+                      "type": "integer",
+                      "format": "int64"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
     "/v1/platform/apps/{appId}/templates/{template_id}/preview": {
       "post": {
         "tags": [
@@ -17623,6 +17983,1770 @@
         }
       }
     },
+    "/v1/platform/apps/{app_id}/usage": {
+      "get": {
+        "tags": [
+          "Platform API"
+        ],
+        "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": "app_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Usage report",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/AppUsageReport"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/platform/apps/{app_id}/usage/export": {
+      "get": {
+        "tags": [
+          "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"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "CSV",
+            "content": {
+              "text/csv": {
+                "schema": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        }
+      }
+    },
+    "/v1/org/apply": {
+      "post": {
+        "tags": [
+          "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": {
+                "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": "What happened to each resource",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "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."
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        }
+      }
+    },
+    "/v1/org/approval-learning/shadow-report": {
+      "get": {
+        "tags": [
+          "Organization"
+        ],
+        "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": [
@@ -17682,6 +19806,192 @@
         }
       }
     },
+    "/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": [
@@ -24861,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": [
@@ -25106,350 +27422,362 @@
             "nullable": true,
             "description": "Graduated transaction approval policy (HITL thresholds)."
           },
-          "typed_data_policy": {
-            "type": "string",
-            "enum": [
-              "deny",
-              "approve"
-            ],
-            "nullable": true,
-            "description": "EIP-712 escalation policy."
-          },
-          "simulation_failure_policy": {
-            "type": "string",
-            "enum": [
-              "deny",
-              "approve"
-            ],
-            "nullable": true,
-            "description": "Simulation failure escalation policy."
-          },
-          "tx_block_unlimited_approvals": {
-            "type": "boolean",
-            "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)."
-          },
-          "tx_per_recipient_max_per_day": {
-            "type": "integer",
-            "nullable": true,
-            "description": "Max transactions to the same recipient per UTC day. Null clears."
-          },
-          "tx_per_recipient_daily_limit": {
-            "type": "string",
-            "nullable": true,
-            "description": "Max native spend to same recipient per UTC day. Null clears."
-          },
-          "new_recipient_cap_native": {
-            "type": "string",
-            "nullable": true,
-            "description": "First-time recipient native cap. Null clears."
-          },
-          "tx_max_value_usd": {
-            "type": "string",
-            "nullable": true,
-            "description": "Per-tx USD cap. Null clears."
-          },
-          "tx_daily_limit_usd": {
-            "type": "string",
-            "nullable": true,
-            "description": "Rolling 24h USD spend cap. Null clears."
-          },
-          "raw_signing_policy": {
-            "type": "string",
-            "enum": [
-              "allow",
-              "deny",
-              "approve"
-            ],
-            "description": "Raw digest signing policy."
-          },
-          "personal_sign_policy": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "personal_sign guardrails JSON."
-          },
-          "allow_erc4337": {
-            "type": "boolean",
-            "description": "Allow ERC-4337 gasless UserOperations."
-          },
-          "allow_eip7702": {
-            "type": "boolean",
-            "description": "Allow EIP-7702 (tx type 4)."
-          },
-          "clear_auto_suspended": {
-            "type": "boolean",
-            "description": "When true, clears circuit-breaker auto-suspension (human owner/admin only)."
-          },
-          "federation_enabled": {
-            "type": "boolean",
-            "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
-          },
-          "federation_audiences": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "format": "uri"
-            },
-            "description": "Allowlist of `aud` values the federation token-exchange may issue\ntokens for (e.g. `[\"https://api.anthropic.com\"]`). Empty array\nblocks all federation requests (zero-trust default).\n"
-          },
-          "federated_token_ttl_seconds": {
-            "type": "integer",
-            "minimum": 60,
-            "maximum": 3600,
-            "nullable": true,
-            "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n"
-          },
-          "tx_token_allowlist": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
-          },
-          "tx_known_tokens_only": {
-            "type": "boolean",
-            "default": false,
-            "description": "When true, only tokens in the known_tokens registry may be used."
-          },
-          "xrpl_allowed_tx_types": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
-          },
-          "per_chain_guardrails": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted),\nmax_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units).\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n"
-          },
-          "api_key_expires_at": {
-            "type": "string",
-            "format": "date-time",
-            "nullable": true,
-            "description": "Optional expiration time for the agent's API key. Set to null to clear."
-          },
-          "environment": {
-            "type": "string",
-            "nullable": true,
-            "description": "Named environment for this agent (production, preview, development, or custom)."
-          },
-          "environment_locked": {
-            "type": "boolean",
-            "description": "When true, the environment tag cannot be changed after creation."
-          },
-          "env_auto_resolve": {
-            "type": "boolean",
-            "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag."
-          },
-          "per_environment_guardrails": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Per-environment guardrail overrides keyed by environment slug."
-          },
-          "address_screening_policy": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`."
-          },
-          "approval_id": {
-            "type": "string",
-            "format": "uuid",
-            "description": "Approved policy_change id when applying a queued guardrail widening. Resubmit PATCH with this field after the approval has been approved via POST /v1/approvals/{approval_id}/decide.\n"
-          }
-        }
-      },
-      "AgentResponse": {
-        "type": "object",
-        "required": [
-          "id",
-          "name",
-          "auth_method",
-          "is_active",
-          "intents_api_enabled",
-          "shroud_enabled",
-          "created_at"
-        ],
-        "properties": {
-          "id": {
-            "type": "string",
-            "format": "uuid"
-          },
-          "name": {
-            "type": "string"
-          },
-          "description": {
-            "type": "string"
-          },
-          "auth_method": {
-            "type": "string",
-            "enum": [
-              "api_key",
-              "mtls",
-              "oidc_client_credentials"
-            ]
-          },
-          "scopes": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "is_active": {
-            "type": "boolean"
-          },
-          "intents_api_enabled": {
-            "type": "boolean"
-          },
-          "tx_to_allowlist": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "tx_max_value": {
-            "type": "string",
-            "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)."
-          },
-          "tx_daily_limit": {
-            "type": "string",
-            "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time."
-          },
-          "tx_max_value_eth": {
-            "type": "string",
-            "deprecated": true,
-            "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)."
-          },
-          "tx_daily_limit_eth": {
-            "type": "string",
-            "deprecated": true,
-            "description": "Deprecated alias for tx_daily_limit."
-          },
-          "tx_spent_today": {
-            "type": "string",
-            "description": "Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain."
-          },
-          "tx_spent_today_eth": {
-            "type": "string",
-            "deprecated": true,
-            "description": "Deprecated alias for tx_spent_today."
-          },
-          "tx_allowed_chains": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            }
-          },
-          "token_ttl_seconds": {
-            "type": "integer",
-            "nullable": true
-          },
-          "vault_ids": {
-            "type": "array",
-            "items": {
-              "type": "string",
-              "format": "uuid"
-            }
-          },
-          "client_cert_fingerprint": {
-            "type": "string",
-            "description": "SHA-256 fingerprint of the client certificate (mTLS agents)"
-          },
-          "oidc_issuer": {
-            "type": "string",
-            "description": "OIDC issuer URL (oidc_client_credentials agents)"
-          },
-          "oidc_client_id": {
-            "type": "string",
-            "description": "OIDC client ID (oidc_client_credentials agents)"
-          },
-          "ssh_public_key": {
-            "type": "string",
-            "description": "Ed25519 SSH public key (base64-encoded, auto-generated at creation)"
-          },
-          "ecdh_public_key": {
-            "type": "string",
-            "description": "P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)"
-          },
-          "shroud_enabled": {
-            "type": "boolean",
-            "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy"
-          },
-          "shroud_config": {
-            "$ref": "#/components/schemas/ShroudConfig"
-          },
-          "system_prompt": {
-            "type": "string",
-            "description": "Default system prompt for agent chat when requests do not override it."
-          },
-          "execution_intents_enabled": {
-            "type": "boolean",
-            "description": "Whether Execution Intents (bindings and execute endpoint) are enabled for this agent"
-          },
-          "execution_guardrails": {
-            "type": "object",
-            "additionalProperties": true,
-            "description": "Guardrails applied to all execution intents for this agent"
-          },
-          "intents_require_tee": {
-            "type": "boolean",
-            "description": "When true, transaction/sign requests must arrive via a TEE host (Pro+ only)"
-          },
-          "execution_require_tee": {
-            "type": "boolean",
-            "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)"
-          },
-          "tx_max_per_day": {
-            "type": "integer",
-            "nullable": true,
-            "description": "Max transactions per UTC calendar day. Null = unlimited."
-          },
-          "tx_overhead_budget": {
-            "type": "object",
-            "nullable": true,
-            "additionalProperties": {
-              "type": "string"
-            },
-            "description": "Per-chain daily overhead budget in native units."
-          },
-          "solana_ata_allowlist": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Solana wallet addresses whose ATAs may be created."
-          },
-          "cards_enabled": {
-            "type": "boolean",
-            "description": "Whether this agent may order payment cards (x402 card ordering)."
-          },
-          "card_max_order_usd": {
-            "type": "string",
-            "description": "Maximum USD amount for a single card order."
-          },
-          "card_daily_limit_usd": {
-            "type": "string",
-            "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
-          },
-          "card_payto_allowlist": {
-            "type": "array",
-            "items": {
-              "type": "string"
-            },
-            "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
-          },
-          "card_reveal_enabled": {
-            "type": "boolean",
-            "description": "Whether agents may reveal card details subject to per-card reveal policy."
-          },
-          "card_require_approval": {
-            "type": "boolean",
-            "description": "When true, card orders route through the human approval queue before x402 payment."
-          },
-          "tx_approval_policy": {
+          "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": [
+              "deny",
+              "approve"
+            ],
+            "nullable": true,
+            "description": "EIP-712 escalation policy."
+          },
+          "simulation_failure_policy": {
+            "type": "string",
+            "enum": [
+              "deny",
+              "approve"
+            ],
+            "nullable": true,
+            "description": "Simulation failure escalation policy."
+          },
+          "tx_block_unlimited_approvals": {
+            "type": "boolean",
+            "description": "Block unlimited ERC-20 approvals (max uint256 / setApprovalForAll)."
+          },
+          "tx_per_recipient_max_per_day": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Max transactions to the same recipient per UTC day. Null clears."
+          },
+          "tx_per_recipient_daily_limit": {
+            "type": "string",
+            "nullable": true,
+            "description": "Max native spend to same recipient per UTC day. Null clears."
+          },
+          "new_recipient_cap_native": {
+            "type": "string",
+            "nullable": true,
+            "description": "First-time recipient native cap. Null clears."
+          },
+          "tx_max_value_usd": {
+            "type": "string",
+            "nullable": true,
+            "description": "Per-tx USD cap. Null clears."
+          },
+          "tx_daily_limit_usd": {
+            "type": "string",
+            "nullable": true,
+            "description": "Rolling 24h USD spend cap. Null clears."
+          },
+          "raw_signing_policy": {
+            "type": "string",
+            "enum": [
+              "allow",
+              "deny",
+              "approve"
+            ],
+            "description": "Raw digest signing policy."
+          },
+          "personal_sign_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "personal_sign guardrails JSON."
+          },
+          "allow_erc4337": {
+            "type": "boolean",
+            "description": "Allow ERC-4337 gasless UserOperations."
+          },
+          "allow_eip7702": {
+            "type": "boolean",
+            "description": "Allow EIP-7702 (tx type 4)."
+          },
+          "clear_auto_suspended": {
+            "type": "boolean",
+            "description": "When true, clears circuit-breaker auto-suspension (human owner/admin only)."
+          },
+          "federation_enabled": {
+            "type": "boolean",
+            "description": "Enable OIDC federation (RFC 8693 token-exchange) for this agent.\nWhen true, the agent may call POST /v1/auth/federated-token to mint\nfederation tokens for the audiences listed in `federation_audiences`.\n"
+          },
+          "federation_audiences": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uri"
+            },
+            "description": "Allowlist of `aud` values the federation token-exchange may issue\ntokens for (e.g. `[\"https://api.anthropic.com\"]`). Empty array\nblocks all federation requests (zero-trust default).\n"
+          },
+          "federated_token_ttl_seconds": {
+            "type": "integer",
+            "minimum": 60,
+            "maximum": 3600,
+            "nullable": true,
+            "description": "Per-agent TTL override for federation tokens (seconds). NULL falls\nback to the global default (`ONECLAW_JWT_FEDERATED_TOKEN_EXPIRY_SECS`).\nHard-capped at 3600 seconds.\n"
+          },
+          "tx_token_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Token contract/mint addresses this agent may interact with. Empty = unrestricted."
+          },
+          "tx_known_tokens_only": {
+            "type": "boolean",
+            "default": false,
+            "description": "When true, only tokens in the known_tokens registry may be used."
+          },
+          "xrpl_allowed_tx_types": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed XRP Ledger transaction types (Payment, TrustSet, etc.). Empty = all allowed."
+          },
+          "per_chain_guardrails": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-chain guardrail overrides. Keys are signing chains (ethereum, bitcoin, solana, xrp, cardano, tron).\nEach value may include max_value, daily_limit, to_allowlist, token_allowlist (legacy *_eth keys accepted),\nmax_fee_per_gas_gwei, max_gas_limit, gas_daily_budget_native (UTC-day cumulative EVM gas in native units).\nStrictest of global and per-chain limits wins. Daily limits apply per chain family spend, not cross-chain totals.\n"
+          },
+          "api_key_expires_at": {
+            "type": "string",
+            "format": "date-time",
+            "nullable": true,
+            "description": "Optional expiration time for the agent's API key. Set to null to clear."
+          },
+          "environment": {
+            "type": "string",
+            "nullable": true,
+            "description": "Named environment for this agent (production, preview, development, or custom)."
+          },
+          "environment_locked": {
+            "type": "boolean",
+            "description": "When true, the environment tag cannot be changed after creation."
+          },
+          "env_auto_resolve": {
+            "type": "boolean",
+            "description": "When true, env var resolve endpoints auto-fill environment from this agent's tag."
+          },
+          "per_environment_guardrails": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Per-environment guardrail overrides keyed by environment slug."
+          },
+          "address_screening_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Recipient address screening policy. `mode` may be `off`, `deny`, or `approve`."
+          },
+          "approval_id": {
+            "type": "string",
+            "format": "uuid",
+            "description": "Approved policy_change id when applying a queued guardrail widening. Resubmit PATCH with this field after the approval has been approved via POST /v1/approvals/{approval_id}/decide.\n"
+          }
+        }
+      },
+      "AgentResponse": {
+        "type": "object",
+        "required": [
+          "id",
+          "name",
+          "auth_method",
+          "is_active",
+          "intents_api_enabled",
+          "shroud_enabled",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "name": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "auth_method": {
+            "type": "string",
+            "enum": [
+              "api_key",
+              "mtls",
+              "oidc_client_credentials"
+            ]
+          },
+          "scopes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "is_active": {
+            "type": "boolean"
+          },
+          "intents_api_enabled": {
+            "type": "boolean"
+          },
+          "tx_to_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "tx_max_value": {
+            "type": "string",
+            "description": "Maximum value per transaction in native major units for the transacting chain family (ETH on EVM, BTC on Bitcoin, SOL on Solana, XRP, ADA, TRX)."
+          },
+          "tx_daily_limit": {
+            "type": "string",
+            "description": "Rolling daily spend cap in native major units, enforced per chain family at signing time."
+          },
+          "tx_max_value_eth": {
+            "type": "string",
+            "deprecated": true,
+            "description": "Deprecated alias for tx_max_value. Same unit semantics (native major units, not ETH-only)."
+          },
+          "tx_daily_limit_eth": {
+            "type": "string",
+            "deprecated": true,
+            "description": "Deprecated alias for tx_daily_limit."
+          },
+          "tx_spent_today": {
+            "type": "string",
+            "description": "Sum of today's spend across all chain families in major units. Prefer tx_spent_today_by_chain."
+          },
+          "tx_spent_today_eth": {
+            "type": "string",
+            "deprecated": true,
+            "description": "Deprecated alias for tx_spent_today."
+          },
+          "tx_allowed_chains": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "token_ttl_seconds": {
+            "type": "integer",
+            "nullable": true
+          },
+          "vault_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "format": "uuid"
+            }
+          },
+          "client_cert_fingerprint": {
+            "type": "string",
+            "description": "SHA-256 fingerprint of the client certificate (mTLS agents)"
+          },
+          "oidc_issuer": {
+            "type": "string",
+            "description": "OIDC issuer URL (oidc_client_credentials agents)"
+          },
+          "oidc_client_id": {
+            "type": "string",
+            "description": "OIDC client ID (oidc_client_credentials agents)"
+          },
+          "ssh_public_key": {
+            "type": "string",
+            "description": "Ed25519 SSH public key (base64-encoded, auto-generated at creation)"
+          },
+          "ecdh_public_key": {
+            "type": "string",
+            "description": "P-256 ECDH public key (base64 SEC1 uncompressed point, auto-generated at creation)"
+          },
+          "shroud_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent routes LLM traffic through the Shroud TEE proxy"
+          },
+          "shroud_config": {
+            "$ref": "#/components/schemas/ShroudConfig"
+          },
+          "system_prompt": {
+            "type": "string",
+            "description": "Default system prompt for agent chat when requests do not override it."
+          },
+          "execution_intents_enabled": {
+            "type": "boolean",
+            "description": "Whether Execution Intents (bindings and execute endpoint) are enabled for this agent"
+          },
+          "execution_guardrails": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Guardrails applied to all execution intents for this agent"
+          },
+          "intents_require_tee": {
+            "type": "boolean",
+            "description": "When true, transaction/sign requests must arrive via a TEE host (Pro+ only)"
+          },
+          "execution_require_tee": {
+            "type": "boolean",
+            "description": "When true, execute requests must arrive via TEE and all direct secret reads are blocked (Pro+ only)"
+          },
+          "tx_max_per_day": {
+            "type": "integer",
+            "nullable": true,
+            "description": "Max transactions per UTC calendar day. Null = unlimited."
+          },
+          "tx_overhead_budget": {
+            "type": "object",
+            "nullable": true,
+            "additionalProperties": {
+              "type": "string"
+            },
+            "description": "Per-chain daily overhead budget in native units."
+          },
+          "solana_ata_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Solana wallet addresses whose ATAs may be created."
+          },
+          "cards_enabled": {
+            "type": "boolean",
+            "description": "Whether this agent may order payment cards (x402 card ordering)."
+          },
+          "card_max_order_usd": {
+            "type": "string",
+            "description": "Maximum USD amount for a single card order."
+          },
+          "card_daily_limit_usd": {
+            "type": "string",
+            "description": "Maximum cumulative USD spent ordering cards per rolling 24h window."
+          },
+          "card_payto_allowlist": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Allowed x402 payTo recipients for card orders (empty = built-in Laso recipients)."
+          },
+          "card_reveal_enabled": {
+            "type": "boolean",
+            "description": "Whether agents may reveal card details subject to per-card reveal policy."
+          },
+          "card_require_approval": {
+            "type": "boolean",
+            "description": "When true, card orders route through the human approval queue before x402 payment."
+          },
+          "tx_approval_policy": {
+            "type": "object",
+            "additionalProperties": true,
+            "nullable": true,
+            "description": "Graduated transaction approval policy (HITL thresholds)."
+          },
+          "action_approval_policy": {
             "type": "object",
             "additionalProperties": true,
             "nullable": true,
-            "description": "Graduated transaction approval policy (HITL thresholds)."
+            "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",
@@ -30386,6 +32714,207 @@
           }
         }
       },
+      "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": {
+          "job_id": {
+            "type": [
+              "string",
+              "null"
+            ],
+            "format": "uuid",
+            "description": "Null for a dry run, which claims no job."
+          },
+          "to_version": {
+            "type": "integer"
+          },
+          "dry_run": {
+            "type": "boolean"
+          },
+          "forced": {
+            "type": "boolean"
+          },
+          "total_agents": {
+            "type": "integer",
+            "format": "int64"
+          },
+          "synced": {
+            "type": "integer"
+          },
+          "already_current": {
+            "type": "integer"
+          },
+          "skipped_drifted": {
+            "type": "integer"
+          },
+          "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"
+                  }
+                }
+              }
+            }
+          }
+        }
+      },
       "UpsertPlatformUserRequest": {
         "type": "object",
         "properties": {
@@ -31191,6 +33720,392 @@
           }
         }
       },
+      "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",
+          "peer_type",
+          "peer_ref",
+          "profile",
+          "status",
+          "observer_count",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "peer_type": {
+            "type": "string",
+            "enum": [
+              "user",
+              "platform_connection",
+              "external"
+            ]
+          },
+          "peer_ref": {
+            "type": "string"
+          },
+          "display_name": {
+            "type": "string",
+            "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"
+          }
+        }
+      },
+      "PeerFact": {
+        "type": "object",
+        "required": [
+          "fact_key",
+          "fact_value",
+          "provenance",
+          "edited_by_human",
+          "updated_at"
+        ],
+        "properties": {
+          "fact_key": {
+            "type": "string",
+            "example": "approval_tendency:refund.create|0-10|known|a@b.co"
+          },
+          "fact_value": {
+            "type": "object",
+            "additionalProperties": true
+          },
+          "confidence": {
+            "type": "string",
+            "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"
+          }
+        }
+      },
+      "NotificationTarget": {
+        "type": "object",
+        "required": [
+          "id",
+          "target_type",
+          "config",
+          "events",
+          "is_active",
+          "verified",
+          "created_at"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "target_type": {
+            "type": "string",
+            "enum": [
+              "sms",
+              "webhook",
+              "expo",
+              "email"
+            ]
+          },
+          "user_id": {
+            "type": "string",
+            "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"
+          }
+        }
+      },
+      "ConnectorPreset": {
+        "type": "object",
+        "required": [
+          "slug",
+          "display_name",
+          "description",
+          "category",
+          "binding_type",
+          "base_url",
+          "requires_oauth"
+        ],
+        "properties": {
+          "slug": {
+            "type": "string",
+            "example": "gmail"
+          },
+          "display_name": {
+            "type": "string",
+            "example": "Gmail"
+          },
+          "description": {
+            "type": "string"
+          },
+          "category": {
+            "type": "string",
+            "example": "communication"
+          },
+          "provider_slug": {
+            "type": "string",
+            "nullable": true,
+            "description": "`oauth_providers.slug`, or null when the connector uses a pasted API key."
+          },
+          "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",
+            "example": "http"
+          },
+          "base_url": {
+            "type": "string",
+            "format": "uri"
+          },
+          "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",
+            "format": "uri"
+          },
+          "tier_required": {
+            "type": "string",
+            "example": "free"
+          },
+          "requires_oauth": {
+            "type": "boolean"
+          }
+        }
+      },
+      "InstalledConnector": {
+        "type": "object",
+        "required": [
+          "binding_id",
+          "binding_name",
+          "preset_slug",
+          "is_active",
+          "connected",
+          "needs_reauth",
+          "created_at"
+        ],
+        "properties": {
+          "binding_id": {
+            "type": "string",
+            "format": "uuid"
+          },
+          "binding_name": {
+            "type": "string"
+          },
+          "preset_slug": {
+            "type": "string"
+          },
+          "display_name": {
+            "type": "string",
+            "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"
+          }
+        }
+      },
       "ApprovalResponse": {
         "type": "object",
         "required": [
@@ -31235,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",
@@ -31749,7 +34685,10 @@
         "required": [
           "connection_id",
           "period",
-          "inference_spent_usd"
+          "inference_spent_usd",
+          "usage",
+          "period_start",
+          "period_end"
         ],
         "properties": {
           "connection_id": {
@@ -31761,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."
           }
         }
       },