@1claw/openapi-spec 0.59.10 → 0.60.0

package/openapi.yaml

@@ -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,
         policy-based access control, agent identity, Intents API,
@@ -836,7 +836,21 @@ paths:
         post:
             tags: [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.
+
+                Two families of action are accepted:
+
+                * the control-plane requests `access_request`, `policy_request`
+                  and `binding_request`, which widen the agent's own authority; and
+                * business actions named `namespace.verb` (`refund.create`,
+                  `social.post`), whose meaning is carried by `summary` and `payload`.
+
+                Actions that 1Claw itself executes on approval — `policy_change`,
+                `card_order`, `agent_transaction`, `agent_execution`,
+                `agent_sign_intent` — are created by the platform and rejected here,
+                because the summary a human reads would be agent-supplied while the
+                side effect would not be.
             operationId: requestApproval
             requestBody:
                 required: true
@@ -848,20 +862,42 @@ paths:
                             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
                                 target_id:
                                     type: string
                                 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
+                                        the human-readable line are derived from this, not from
+                                        `summary` — the two can disagree, and only this one describes
+                                        what happens if the human approves.
+                                    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
+                                        `action_approval_policy` and the payload, then takes the higher
+                                        of the two: a caller may raise its own bar, never lower it.
+                                        The response returns both.
                                 risk_tier:
                                     type: integer
                                     minimum: 1
-                                    maximum: 5
+                                    maximum: 3
+                                    deprecated: true
+                                    description: "Former name for `declared_risk_tier`. Still accepted."
             responses:
                 "202":
                     description: Approval request created
@@ -6662,6 +6698,224 @@ paths:
                 "404":
                     $ref: "#/components/responses/NotFound"
 
+    /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.
+            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.
+            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.
+            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"
+                "409":
+                    description: A rollout is already running for this template
+                "404":
+                    $ref: "#/components/responses/NotFound"
+    /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.
+            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: [Platform]
@@ -11345,85 +11599,1409 @@ paths:
                 "200":
                     description: Webhook processed
 
-    /v1/webhooks/discord/{webhook_path}:
-        post:
-            tags: [Agent Channels]
-            summary: Discord webhook
-            description: Public webhook endpoint for receiving Discord bot interactions.
-            operationId: discordWebhook
-            security: []
+    /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,
+                **plus what could not be charged to one**.
+
+                The `unattributed` block is not an implementation detail. Summing only the
+                per-connection numbers gives a figure that will not match the invoice you
+                are reconciling against, and the gap is usage that belongs to a real
+                end-user we cannot name.
+
+                Two kinds, deliberately kept apart:
+
+                * `none` — no platform linkage at all. Normal for most traffic, not a problem.
+                * `ambiguous` — the agent belongs to several connections and no
+                  `X-Platform-Connection` header said which. This usage belongs to
+                  *someone*. `has_ambiguous_usage` flags it so you do not have to notice
+                  a non-zero nested number.
+
+                `totals` is derived from the parts, never queried separately, so it cannot
+                disagree with its own breakdown.
+            operationId: getAppUsage
             parameters:
-                - name: webhook_path
+                - name: app_id
                   in: path
                   required: true
-                  schema:
-                      type: string
-            requestBody:
-                required: true
-                content:
-                    application/json:
-                        schema:
-                            type: object
+                  schema: { type: string, format: uuid }
             responses:
                 "200":
-                    description: Webhook processed
-
-    # ---------------------------------------------------------------------------
-    # OAuth Connect
-    # ---------------------------------------------------------------------------
+                    description: Usage report
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/AppUsageReport"
+                "404":
+                    $ref: "#/components/responses/NotFound"
 
-    /v1/oauth/providers:
+    /v1/platform/apps/{app_id}/usage/export:
         get:
-            tags: [OAuth Connect]
-            summary: List OAuth providers
+            tags: [Platform API]
+            summary: Usage as CSV for billing reconciliation
             description: |
-                Returns the list of supported OAuth providers with their metadata,
-                available scopes, and authorization URLs. No authentication required.
-            operationId: listOAuthProviders
-            security: []
+                The same report as `GET /usage`, as CSV. Includes the `ambiguous`, `none`
+                and `total` rows — a CSV listing only connections looks complete and is
+                not, and whoever imports it has no way to tell.
+            operationId: exportAppUsage
+            parameters:
+                - name: app_id
+                  in: path
+                  required: true
+                  schema: { type: string, format: uuid }
             responses:
                 "200":
-                    description: Provider list
+                    description: CSV
                     content:
-                        application/json:
-                            schema:
-                                $ref: "#/components/schemas/OAuthProviderListResponse"
+                        text/csv:
+                            schema: { type: string }
+                "404":
+                    $ref: "#/components/responses/NotFound"
 
-    /v1/agents/{agent_id}/oauth/connect:
+    /v1/org/apply:
         post:
-            tags: [OAuth Connect]
-            summary: Initiate OAuth connection
+            tags: [Organization]
+            summary: Apply a chart
             description: |
-                Start an OAuth authorization flow for the specified agent and provider.
-                Returns the authorization URL to redirect the user to. Human-only.
-            operationId: connectOAuth
-            parameters:
-                - $ref: "#/components/parameters/AgentId"
+                Create what the chart describes. Human users only.
+
+                **Apply calls the same handlers the HTTP routes call.** Creating a vault
+                runs five gates before anything is written — the delegation scope, a name
+                check, control-plane consensus, a creation rate limit and the tier quota
+                — and creating an agent runs its own. A reconciler that wrote through the
+                repositories would skip all of them and would look, in review, exactly
+                like one that did not.
+
+                So if your org has consensus configured on `vault.create`, applying a
+                chart queues an approval exactly as a dashboard click would. That resource
+                comes back as `awaiting_approval` rather than failing the whole chart.
+
+                Per-resource results: `created`, `unchanged`, `skipped`, `refused`,
+                `awaiting_approval`, `failed`. `needs_attention` is true when the chart is
+                not fully applied — something is waiting on a person, whether an approval,
+                an OAuth sign-in, or a resource that drifted and was left alone.
+
+                Save `applied_state` to `.1claw/apply-state.json`. It records what apply
+                set, which is what lets the next run tell drift from a first apply.
+
+                v1 creates and reports; it does not delete, prune, or patch in place. An
+                apply that silently deletes is an apply nobody runs twice.
+            operationId: applyChart
             requestBody:
                 required: true
                 content:
                     application/json:
                         schema:
-                            $ref: "#/components/schemas/ConnectOAuthRequest"
+                            type: object
+                            required: [chart]
+                            properties:
+                                chart:
+                                    type: object
+                                    description: A chart document — `apiVersion`, `kind`, `metadata`, `spec`.
+                                applied_state:
+                                    type: object
+                                    additionalProperties: true
             responses:
                 "200":
-                    description: Authorization URL generated
+                    description: What happened to each resource
                     content:
                         application/json:
                             schema:
-                                $ref: "#/components/schemas/ConnectOAuthResponse"
+                                type: object
+                                properties:
+                                    chart_name: { type: string }
+                                    resources:
+                                        type: array
+                                        items:
+                                            type: object
+                                            properties:
+                                                kind: { type: string }
+                                                name: { type: string }
+                                                result:
+                                                    type: string
+                                                    enum: [created, unchanged, skipped, refused, awaiting_approval, failed]
+                                                id: { type: string, format: uuid }
+                                                detail: { type: string }
+                                    warnings:
+                                        type: array
+                                        items: { type: string }
+                                    applied_state:
+                                        type: object
+                                        additionalProperties: true
+                                        description: Save to `.1claw/apply-state.json`.
+                                    needs_attention:
+                                        type: boolean
+                                        description: The chart is not fully applied — something is waiting on a person.
                 "400":
                     $ref: "#/components/responses/BadRequest"
                 "403":
                     $ref: "#/components/responses/Forbidden"
-                "404":
-                    $ref: "#/components/responses/NotFound"
 
-    /v1/agents/{agent_id}/oauth/connections:
+    /v1/org/approval-learning/shadow-report:
         get:
-            tags: [OAuth Connect]
-            summary: List OAuth connections
-            description: List all active OAuth connections for the specified agent.
+            tags: [Organization]
+            summary: What would have been approved automatically
+            description: |
+                Every approval decision is observed, per **fingerprint bucket** — the
+                action, the amount band, whether the recipient was new, and who they
+                were. This reports the buckets a person has approved without exception,
+                and what promoting one would write into an agent's policy.
+
+                Observing is not acting. In the default `shadow` mode nothing changes who
+                gets asked; `can_promote` is false and the promote endpoint refuses.
+
+                Each suggestion carries `would_write_rule` — the actual rule, built by the
+                same function promotion uses, so the report cannot promise something
+                promotion would refuse.
+            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
+                only, and only when the organisation is in `enforce` mode.
+
+                **The rule covers only what was actually approved.** Five approved $5
+                refunds to one customer produce `{ refund.create, asks above $10, that
+                recipient }` — a $49 request does not match it and still reaches a human.
+
+                Refused when: fewer than five consecutive approvals; *any* past rejection
+                on the bucket (a long recent run must not hide a history of refusals); the
+                bucket is for a recipient never paid before; the amount band has no upper
+                edge; or the action grants or destroys authority.
+
+                `widen_to_action_type` drops the amount and recipient constraints. It is
+                never the default and should be an explicit choice in your UI, not a
+                checkbox someone skims past.
+
+                The written rule is marked `promoted_from_learning` so an operator can
+                tell it apart from one they wrote, and it replaces any existing rule for
+                the same action type — appending would leave two rules where only the
+                first ever applies.
+            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
+                document. Public — a description of what 1Claw offers, not tenant data.
+
+                Each carries a `headline`: the one-line consequence someone should read
+                before choosing it, in the words they would use.
+            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
+                **widen** — loosen relative to what the agent can already do.
+
+                Widening detection errs toward flagging: a false positive costs one extra
+                approval, a false negative is a limit raised without review. Enabling a
+                capability widens; disabling does not. Raising a cap widens; setting a
+                first cap does not, because absent means unlimited.
+            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
+                columns. A preset that wrote them directly would be a way around the
+                guardrail widening approval flow wearing a friendlier interface.
+
+                So if the preset loosens something and your organisation gates that, you
+                get the same **202 with a pending approval** you would get from editing
+                the agent by hand — not a quietly applied change. Pass `approval_id`
+                once that approval is granted.
+            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.
+                These are the parts they cannot write: whether a human reviewed the
+                listing, how many people installed it, what they rated it.
+
+                Public, because its purpose is to be read by someone deciding whether to
+                install a stranger's agent. Only listed agents have public trust.
+
+                **A listing with reports shows no badges at all.** "Platform reviewed"
+                beside an active complaint tells a reader the opposite of what they need.
+                An average rating appears only from three reviews — one rating is not an
+                average.
+            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
+                competitor's listing at machine speed.
+
+                The response does not include the report count. Telling a reporter how
+                close a listing is to being flagged tells them how many more to file.
+            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
+                review an agent from your own organisation.
+
+                Comments are shown only once moderated. The rating counts either way — a
+                number is harder to abuse than free text.
+            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
+                of a person, and an agent that could do that could add itself.
+
+                Idempotent on `(org, peer_type, peer_ref)`. Observers are **merged**, not
+                replaced — a second call adding one agent does not revoke the others
+                already watching. Every named observer must be an agent in this
+                organisation, so a typo or an id copied from elsewhere is an error rather
+                than a silent no-op that leaves an operator believing an agent is
+                watching when none is.
+            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
+                users only, behind strong-factor re-auth — this is exactly what a stolen
+                session would want.
+
+                Each fact carries `why_we_believe_this`: its provenance, including
+                tombstones for observations that have since expired. An export listing
+                conclusions without their basis answers only the easy half of the
+                question.
+            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,
+                behind strong-factor re-auth, and irreversible.
+
+                Returns counts of what was removed — "deleted" with no numbers is not
+                something anyone can check. The audit entry records that a deletion
+                happened and deliberately omits the identifier someone asked to have
+                forgotten.
+            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
+                processor will not re-derive over it, because someone correcting what a
+                system believes about them outranks the inference that got it wrong.
+
+                The correction is appended to the fact's provenance as a `human` entry,
+                so the record shows both what was inferred and that a person disagreed.
+            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
+                prompt. Best-supported facts first, so a tight budget drops the
+                least-supported beliefs rather than an arbitrary tail — and a fact a
+                human corrected sorts ahead of everything, because a correction someone
+                took the trouble to make is the last thing to cut.
+
+                Never truncates mid-line: half a sentence about a person is worse than
+                one fewer sentence. A peer with no facts returns an empty string rather
+                than a header claiming to describe someone.
+
+                The blob ends by saying these are observations and not instructions,
+                because an agent reading it needs to know the difference.
+            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
+                not need to know a peer id.
+
+                An agent may only ask for its own — otherwise this route would be a way
+                to read a peer through an agent that observes it, from one that does not.
+                The observer check still applies: being the agent named in the path is
+                not the same as observing that connection's peer.
+            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.
+
+                **An agent reaches a peer only by being named in its observer list.**
+                Being in the same organisation, the same platform connection, or holding
+                a broad scope grants nothing. A peer with no observers is readable by no
+                agent at all — forgetting to set observers must not expose someone's
+                behavioural profile to every agent in the org.
+
+                A peer in another organisation returns 404, the same as an unknown id:
+                whether one exists elsewhere is not something a caller should learn.
+
+                Each fact carries `provenance` — why it is believed. Entries for events
+                that have since expired become tombstones keeping the shape of what was
+                seen without the content, so a belief about a person always has a
+                recoverable basis.
+            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.
+
+                `likelihood` is an **observation about a person** — how they have decided
+                comparable requests before. Comparable means the same fingerprint bucket,
+                not the same action type: three approvals of $5 say nothing about $500.
+
+                `suggest_auto` is a **statement about a policy**. It is true only where a
+                rule the operator already wrote would auto-approve this exact case. It is
+                never derived from `likelihood`, and a confident model never becomes new
+                authority. It is false, with `blocked_reason`, when:
+
+                * no rule covers the action (`no_matching_rule`);
+                * a rule says a human decides (`rule_requires_approval`);
+                * the amount is above the rule's own threshold (`above_configured_threshold`);
+                * the derived risk tier is above the lowest (`risk_tier_requires_step_up`);
+                * the action grants or destroys authority (`action_is_sensitive`).
+
+                The policy consulted is the calling agent's own, so a prediction cannot
+                inherit authority from another agent that happens to observe the same
+                person.
+            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
+                only — a chart provisions agents, vaults and access policies, so an agent
+                that could apply one could grant itself access to a vault it cannot
+                currently read.
+
+                A POST rather than a GET because the chart is the request body, and a GET
+                carrying a body is one many proxies and clients drop or mangle. Read-only
+                either way.
+
+                The plan reports five outcomes per resource:
+
+                * `create` — not present, would be created.
+                * `patch` — present, differs only in fields safe to change in place.
+                * `unchanged` — present and matching.
+                * `skipped_drifted` — **changed outside this chart**, so left alone.
+                  Someone edited it by hand for a reason; overwriting that because a file
+                  says otherwise is how a deployment tool destroys an incident fix.
+                * `refused` — the chart asks for a change apply will not make. Guardrail
+                  fields are never patched here: editing them routes through the guardrail
+                  approval flow, and a reconciler writing them directly would be a way
+                  around it.
+
+                Pass `applied_state` from `.1claw/apply-state.json` so drift can be told
+                from a first run — a pre-existing resource is not drifted, it was simply
+                not created by this chart.
+            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
+                https webhook, an email address, or a push token.
+
+                An SMS target is created **unverified** and stays that way until someone
+                proves they hold the number. Adding a number must not itself be an
+                authorisation — otherwise a session borrowed for five minutes leaves
+                behind a number that can approve things long after it is gone. An
+                unverified target still receives notifications; it just cannot reply to
+                decide one.
+            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),
+                                        `{"url": "https://…"}` for webhook (https only),
+                                        `{"email": "…"}`, or `{"push_token": "…"}`.
+                                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
+                will come from — a code arriving from a different number than the one
+                the recipient will later see is a code they are right to distrust.
+
+                Expires in 10 minutes. Five wrong answers void it.
+            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
+                the provider calls it — so the `X-Twilio-Signature` header is the only
+                thing establishing that a message is genuine, and it is verified over the
+                exact public URL and every POST parameter.
+
+                A verified signature proves the message came from Twilio, **not** that it
+                came from the right person: anyone who knows the number can text it and
+                their message arrives correctly signed. So the sending number must also
+                match a *verified* SMS notification target.
+
+                A reply may decide an approval only when its server-derived
+                `risk_tier` is 1. Anything higher is answered with a link to confirm in
+                the app; replying cannot decide it. When more than one approval is
+                pending, a bare YES/NO is answered with a request for the reference code
+                rather than applied to a guess.
+
+                Always answers 200 with TwiML — a non-2xx makes Twilio retry a message
+                that was deliberately refused. The exception is a bad signature, which is
+                403, because a persistently failing signature is a misconfiguration as
+                often as an attack and silence would hide both.
+            operationId: smsWebhook
+            security: []
+            parameters:
+                - name: webhook_path
+                  in: path
+                  required: true
+                  schema: { type: string }
+                - name: X-Twilio-Signature
+                  in: header
+                  required: true
+                  schema: { type: string }
+            requestBody:
+                required: true
+                content:
+                    application/x-www-form-urlencoded:
+                        schema:
+                            type: object
+                            properties:
+                                From: { type: string, example: "+14155550123" }
+                                To: { type: string, example: "+14155550999" }
+                                Body: { type: string, example: "YES A1" }
+            responses:
+                "200":
+                    description: TwiML response; `<Response/>` when there is nothing to reply
+                    content:
+                        application/xml:
+                            schema: { type: string }
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/webhooks/discord/{webhook_path}:
+        post:
+            tags: [Agent Channels]
+            summary: Discord webhook
+            description: Public webhook endpoint for receiving Discord bot interactions.
+            operationId: discordWebhook
+            security: []
+            parameters:
+                - name: webhook_path
+                  in: path
+                  required: true
+                  schema:
+                      type: string
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            type: object
+            responses:
+                "200":
+                    description: Webhook processed
+
+    # ---------------------------------------------------------------------------
+    # OAuth Connect
+    # ---------------------------------------------------------------------------
+
+    /v1/oauth/providers:
+        get:
+            tags: [OAuth Connect]
+            summary: List OAuth providers
+            description: |
+                Returns the list of supported OAuth providers with their metadata,
+                available scopes, and authorization URLs. No authentication required.
+            operationId: listOAuthProviders
+            security: []
+            responses:
+                "200":
+                    description: Provider list
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/OAuthProviderListResponse"
+
+    /v1/connectors/presets:
+        get:
+            tags: [Connectors]
+            summary: List connector presets
+            description: |
+                The catalogue of pre-built connectors — Gmail, Slack, GitHub and the rest.
+                Each preset carries the OAuth provider and scopes to request, plus the
+                binding config and host/path guardrails the agent will execute under.
+
+                No authentication required: this describes what 1Claw supports, not
+                anything belonging to an organisation.
+            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
+                been connected — an install creates the binding, but the binding is not
+                usable until the OAuth round trip completes.
+            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
+                paths — and starts the OAuth flow for it. Send the user to the returned
+                `authorization_url` to finish; until they do, the binding exists but
+                holds no credential.
+
+                Human users only. Installing gives an agent reach into a third-party
+                account, and the flow it starts is a person's browser.
+
+                Idempotent by binding name: re-installing re-runs the OAuth flow against
+                the existing binding rather than creating a second one holding a second
+                token for the same account. A name already taken by a binding that is
+                not this connector returns 409.
+            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
+                                        preset's scope list is the reviewed part of a one-click
+                                        install. Must still include the preset's required scopes.
+                                redirect_after:
+                                    type: string
+                                    description: Where to send the user after the OAuth round trip.
+            responses:
+                "201":
+                    description: Connector installed; OAuth may still be pending
+                    content:
+                        application/json:
+                            schema:
+                                type: object
+                                required: [binding_id, binding_name, preset_slug, next_step]
+                                properties:
+                                    binding_id: { type: string, format: uuid }
+                                    binding_name: { type: string }
+                                    preset_slug: { type: string }
+                                    authorization_url:
+                                        type: string
+                                        nullable: true
+                                        description: Absent for connectors that use a pasted API key rather than OAuth.
+                                    next_step:
+                                        type: string
+                                        description: What the user still has to do, in words.
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+                "409":
+                    $ref: "#/components/responses/Conflict"
+
+    /v1/agents/{agent_id}/oauth/connect:
+        post:
+            tags: [OAuth Connect]
+            summary: Initiate OAuth connection
+            description: |
+                Start an OAuth authorization flow for the specified agent and provider.
+                Returns the authorization URL to redirect the user to. Human-only.
+            operationId: connectOAuth
+            parameters:
+                - $ref: "#/components/parameters/AgentId"
+            requestBody:
+                required: true
+                content:
+                    application/json:
+                        schema:
+                            $ref: "#/components/schemas/ConnectOAuthRequest"
+            responses:
+                "200":
+                    description: Authorization URL generated
+                    content:
+                        application/json:
+                            schema:
+                                $ref: "#/components/schemas/ConnectOAuthResponse"
+                "400":
+                    $ref: "#/components/responses/BadRequest"
+                "403":
+                    $ref: "#/components/responses/Forbidden"
+                "404":
+                    $ref: "#/components/responses/NotFound"
+
+    /v1/agents/{agent_id}/oauth/connections:
+        get:
+            tags: [OAuth Connect]
+            summary: List OAuth connections
+            description: List all active OAuth connections for the specified agent.
             operationId: listOAuthConnections
             parameters:
                 - $ref: "#/components/parameters/AgentId"
@@ -16041,6 +17619,22 @@ components:
                     additionalProperties: true
                     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
+                        amount. `{}` means no per-action rules.
+
+                        Shape: `{ "default_mode": "deny|approve|allow", "rules": [ { "action_type":
+                        "refund.create", "mode": "approve", "require_for_amount_above_usd": "50",
+                        "summary_template": "Refund {{amount_usd}} to {{customer_email}}" } ] }`.
+
+                        A rule can only raise the bar. Editing this is classified as a guardrail
+                        widening, so it routes through the same approval flow as loosening a
+                        transaction limit. Malformed rules are rejected on write rather than
+                        ignored at request time.
                 typed_data_policy:
                     type: string
                     enum: [deny, approve]
@@ -16223,6 +17817,22 @@ components:
                     additionalProperties: true
                     nullable: true
                     description: Graduated transaction approval policy (HITL thresholds).
+                action_approval_policy:
+                    type: object
+                    additionalProperties: true
+                    nullable: true
+                    description: |
+                        Which business actions this agent must ask a human about, and above what
+                        amount. `{}` means no per-action rules.
+
+                        Shape: `{ "default_mode": "deny|approve|allow", "rules": [ { "action_type":
+                        "refund.create", "mode": "approve", "require_for_amount_above_usd": "50",
+                        "summary_template": "Refund {{amount_usd}} to {{customer_email}}" } ] }`.
+
+                        A rule can only raise the bar. Editing this is classified as a guardrail
+                        widening, so it routes through the same approval flow as loosening a
+                        transaction limit. Malformed rules are rejected on write rather than
+                        ignored at request time.
                 typed_data_policy:
                     type: string
                     enum: [deny, approve]
@@ -16494,6 +18104,22 @@ components:
                     additionalProperties: true
                     nullable: true
                     description: Graduated transaction approval policy (HITL thresholds).
+                action_approval_policy:
+                    type: object
+                    additionalProperties: true
+                    nullable: true
+                    description: |
+                        Which business actions this agent must ask a human about, and above what
+                        amount. `{}` means no per-action rules.
+
+                        Shape: `{ "default_mode": "deny|approve|allow", "rules": [ { "action_type":
+                        "refund.create", "mode": "approve", "require_for_amount_above_usd": "50",
+                        "summary_template": "Refund {{amount_usd}} to {{customer_email}}" } ] }`.
+
+                        A rule can only raise the bar. Editing this is classified as a guardrail
+                        widening, so it routes through the same approval flow as loosening a
+                        transaction limit. Malformed rules are rejected on write rather than
+                        ignored at request time.
                 typed_data_policy:
                     type: string
                     enum: [deny, approve]
@@ -19969,6 +21595,140 @@ components:
                     type: string
                     format: date-time
 
+        FleetSummaryResponse:
+            type: object
+            properties:
+                template_id:
+                    type: string
+                    format: uuid
+                template_name:
+                    type: string
+                current_version:
+                    type: integer
+                spec_hash:
+                    type: [string, "null"]
+                    description: >
+                        SHA-256 of the template spec. Lets a caller tell a version bump that
+                        changed nothing from one that did. Null on templates written before
+                        migration 245.
+                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.
+                    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?".
+                    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:
@@ -20531,6 +22291,170 @@ components:
                     type: string
                     description: Optional human-readable reason for the decision
 
+        UsageCounts:
+            type: object
+            required: [api_requests, signatures, execution_intents, execution_intents_tee, inference_usd, credits_debited_cents]
+            properties:
+                api_requests: { type: integer, format: int64 }
+                signatures: { type: integer, format: int64 }
+                execution_intents: { type: integer, format: int64 }
+                execution_intents_tee: { type: integer, format: int64 }
+                inference_usd:
+                    type: string
+                    description: A decimal string. Money is not a float; zero is "0".
+                    example: "3.42"
+                credits_debited_cents: { type: integer, format: int64 }
+
+        AppUsageReport:
+            type: object
+            required: [app_id, period_start, period_end, connections, unattributed, totals, has_ambiguous_usage]
+            properties:
+                app_id: { type: string, format: uuid }
+                period_start: { type: string, format: date-time }
+                period_end:
+                    type: string
+                    format: date-time
+                    description: Exclusive. The period is half-open, so an event at midnight belongs to one month, not two.
+                connections:
+                    type: array
+                    items:
+                        type: object
+                        required: [connection_id, usage]
+                        properties:
+                            connection_id: { type: string, format: uuid }
+                            usage: { $ref: "#/components/schemas/UsageCounts" }
+                unattributed:
+                    type: object
+                    description: Usage that could not be charged to a connection.
+                    properties:
+                        ambiguous:
+                            allOf:
+                                - $ref: "#/components/schemas/UsageCounts"
+                            description: The agent belongs to several connections and none was named. This belongs to someone.
+                        none:
+                            allOf:
+                                - $ref: "#/components/schemas/UsageCounts"
+                            description: No platform linkage. Normal for most traffic.
+                totals:
+                    allOf:
+                        - $ref: "#/components/schemas/UsageCounts"
+                    description: Connections plus both unattributed buckets. Derived, not queried.
+                has_ambiguous_usage:
+                    type: boolean
+                    description: Some usage this period belongs to an end-user who cannot be identified.
+
+        Peer:
+            type: object
+            required: [id, 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;
+                        the person keeps export and delete.
+                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
+                        expired; kind and decision are kept, content is not) or `human`.
+                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
+                        an approval by reply.
+                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: [id, org_id, user_id, action, target_type, target_id, risk_tier, status, summary, created_at]
@@ -20558,6 +22482,23 @@ components:
                     type: integer
                     minimum: 1
                     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
                     enum: [pending, approved, rejected, expired]
@@ -20912,7 +22853,7 @@ components:
 
         ConnectionUsageResponse:
             type: object
-            required: [connection_id, period, inference_spent_usd]
+            required: [connection_id, period, inference_spent_usd, usage, period_start, period_end]
             properties:
                 connection_id:
                     type: string
@@ -20922,6 +22863,23 @@ components:
                     description: UTC month (YYYY-MM)
                 inference_spent_usd:
                     type: string
+                    description: |
+                        Kept for compatibility — this field predates the breakdown below and
+                        existing integrations read it. Same number as `usage.inference_usd`.
+                usage:
+                    allOf:
+                        - $ref: "#/components/schemas/UsageCounts"
+                    description: |
+                        Everything billable for this connection in the period. Derived from the
+                        same grouped query as the app report, so a connection can never report a
+                        number the app report disagrees with.
+                period_start:
+                    type: string
+                    format: date-time
+                period_end:
+                    type: string
+                    format: date-time
+                    description: Exclusive. The period is half-open.
 
         EntitlementsListResponse:
             type: object