@shipeasy/openapi 3.2.0 → 3.4.0

package/openapi.yaml

@@ -216,6 +216,35 @@ tags:
       the AI-write seam the cockpit's detail panel renders: `list` reads what a
       previous run found, `create` appends a new record, and `update` fills in the
       `working` run record you were handed (findings, PR, confidence) as you work.
+  - name: Questions
+    parent: Ops
+    description: |-
+      Structured questions an agent asks the team about a queue item — the
+      `AskUserQuestion` shape: a short `header`, the `question`, 2–4 `options`
+      (label + description), and `multiSelect` for checkboxes instead of radios.
+      Every question also accepts a free-text "Other" answer. Open questions sit
+      at the very top of the item's detail panel and mark the row in the queue.
+
+      **Asking.** `ask` posts 1–4 questions at once. Several agents (or several
+      runs) may have questions open on the same item at the same time.
+
+      **Getting the answer back.** `delivery: resume` (the default for a run
+      launched through a trigger connector) re-fires that same agent on the
+      item once every question its run asked is answered, continuing the same
+      run record with the answers in the prompt. `delivery: poll` (the default
+      for a live, connector-less session such as Claude Code in a terminal)
+      fires nothing — call `list` until the status reads `completed`.
+  - name: QA notes
+    parent: Ops
+    description: |-
+      Typed QA notes on a queue item — the QA follow-up that is not discussion.
+      Each note is one of four kinds: `narrowing` (only part of the bug still
+      fails), `clarification` (changes what "fixed" means), `verification` (a
+      `pass` / `fail` verdict on a fix) or `correction` (withdraws an earlier
+      framing). Notes are append-only, carry their author and time, and render in
+      their own section of the item's detail panel, separate from the comment
+      thread. A failing verification offers a "Reopen item" action in the
+      dashboard; it is always an explicit click, never a side effect of `create`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -258,6 +287,19 @@ tags:
       Continue) schedule on their own surface — typically a GitHub Actions
       `schedule:` cron running the platform's headless CLI with the shared
       trigger prompt.
+  - name: Tags
+    description: |-
+      Tags: free-form, project-scoped labels any item can carry — queue items
+      (bugs, feature requests, error/alert tickets), flags, configs, kill
+      switches, metrics, tracked errors, alert rules, and experiments all share
+      one tag roster.
+
+      **Identity.** A tag is its name, unique case-insensitively per project. A
+      tag is born the first time it's attached — there is no separate create.
+
+      **Addressing.** An item is named by `entityType` + its handle (an ops
+      item's number, a resource's name, or any id). `set` replaces the full tag
+      set; `update` adds/removes names incrementally.
   - name: Connectors
     description: |-
       Outbound integrations: the per-project destinations feedback + trigger
@@ -4561,12 +4603,15 @@ paths:
                   name: checkouts
                   folder: null
                   eventName: checkout_completed
-                  query: count_users(checkout_completed)
+                  query: count(checkout_completed)
                   queryIr:
-                    agg:
-                      kind: count_users
-                    metric: checkout_completed
-                    filters: []
+                    v: 2
+                    expr:
+                      node: agg
+                      event: checkout_completed
+                      agg:
+                        kind: count
+                      filters: []
                   direction: higher_better
                   version: 1
         '400':
@@ -4600,7 +4645,7 @@ paths:
 
         **Use cases**
 
-        - **Track an event** — `count_users(<event>)` for unique-user counts.
+        - **Track an event** — `count(<event>)` for event counts.
         - **Sum a value** — `sum(<event>, <label>)` for revenue / quantity metrics.
         - **Experiment success metric** — create the metric, then attach its id to an experiment.
       tags:
@@ -4614,13 +4659,13 @@ paths:
             schema:
               $ref: '#/components/schemas/CreateMetricRequest'
             examples:
-              countUsers:
-                summary: Count unique users (DSL)
-                description: Unique users who completed checkout, expressed with the query DSL.
+              countEvents:
+                summary: Count an event (DSL)
+                description: Completed checkouts, expressed with the query DSL.
                 value:
                   name: checkouts
                   event_name: checkout_completed
-                  query: count_users(checkout_completed)
+                  query: count(checkout_completed)
               sumRevenue:
                 summary: Sum a value label (DSL)
                 description: Total revenue, summing the `amount` property of the `purchase` event.
@@ -4637,10 +4682,13 @@ paths:
                   name: checkouts
                   event_name: checkout_completed
                   query_ir:
-                    agg:
-                      kind: count_users
-                    metric: checkout_completed
-                    filters: []
+                    v: 2
+                    expr:
+                      node: agg
+                      event: checkout_completed
+                      agg:
+                        kind: count
+                      filters: []
       responses:
         '201':
           description: Create a metric
@@ -4721,11 +4769,14 @@ paths:
                 eventName: purchase
                 query: sum(purchase, amount)
                 queryIr:
-                  agg:
-                    kind: sum
-                  metric: purchase
-                  valueLabel: amount
-                  filters: []
+                  v: 2
+                  expr:
+                    node: agg
+                    event: purchase
+                    agg:
+                      kind: sum
+                    valueLabel: amount
+                    filters: []
                 direction: higher_better
                 winsorizePct: 99
                 version: 1
@@ -5431,7 +5482,11 @@ paths:
       operationId: listOpsItems
       summary: List the operational queue
       description: |-
-        Returns the unified ops queue (bugs, feature requests, errors, alerts) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Filter by `type` and/or `status`, and cap with `limit`. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.
+        Returns the unified ops queue (bugs, feature requests, errors, alerts, measurement plans) in work order — highest priority first, oldest first within a priority — so consumers work it top-down. Every filter is applied in SQL before paging, and filters combine with AND. Human-gated holding states (items awaiting human sign-off in the dashboard) are never returned by `all`/default status.
+
+        **Filters:** `type` (one item type), `status` (one lifecycle status, or `unresolved` — everything not yet `resolved`/`wont_fix`), `priority` (one triage priority), `owner` (one person or agent), and `scope=ready` — the items ready to be picked up right now: `open`, with nobody working them (no open run), and either unowned or reopened (sent back to `open` after an earlier run finished).
+
+        **Paging:** `limit` is the page size and `offset` the number of items to skip. The order is stable, so walk the queue with `offset += limit`; a page shorter than `limit` is the last one.
 
         **Use case:** Pull the open queue to triage — e.g. every `bug` still `open` — before working items down one by one.
       tags:
@@ -5441,8 +5496,9 @@ paths:
         - name: type
           in: query
           required: false
-          description: Filter by item type (`bug`/`feature_request`/`error`/`alert`), or `all`.
+          description: Filter by item type, or `all` (the default). Every type a returned item can carry is filterable, including the auto-filed ones.
           schema:
+            default: all
             anyOf:
               - type: string
                 enum:
@@ -5450,30 +5506,70 @@ paths:
                   - feature_request
                   - error
                   - alert
-                description: Queue item type. `bug` and `feature_request` are user-fileable; `error` and `alert` tickets are auto-filed by the platform.
+                  - measure_plan
+                description: Queue item type. `bug` and `feature_request` are user-fileable; `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform.
               - type: string
                 const: all
         - name: status
           in: query
           required: false
-          description: Filter by lifecycle status, or `all`. The human-gated holding state (`pending_approval`) is excluded from `all`/default and returned only when requested as the exact status.
+          description: Filter by one lifecycle status, `unresolved` for every status that is not `resolved` or `wont_fix`, or `all` for every status. Defaults to `all` over HTTP; the CLI and MCP tool default to `unresolved`, so pass `all` there to include resolved and won't-fix items. The human-gated holding state (`pending_approval`) is excluded from `unresolved` and `all`, and returned only when requested as the exact status.
           schema:
+            default: all
             anyOf:
               - $ref: '#/components/schemas/OpsItemStatus'
+              - type: string
+                const: unresolved
+              - type: string
+                const: all
+          x-cli:
+            default: unresolved
+          x-mcp:
+            default: unresolved
+        - name: priority
+          in: query
+          required: false
+          description: Filter by triage priority, or `all` (the default). Items with no priority set are returned only under `all`.
+          schema:
+            default: all
+            anyOf:
+              - $ref: '#/components/schemas/OpsItemPriority'
               - type: string
                 const: all
+        - name: scope
+          in: query
+          required: false
+          description: '`ready` narrows to the items ready to be picked up right now: status `open`, no open run (nobody has acked it and is still working), and either unowned (no person and no agent) or reopened (sent back to `open` after an earlier run finished). Leave `status` unset with it. `all` (the default) applies no such narrowing.'
+          schema:
+            type: string
+            enum:
+              - all
+              - ready
+            default: all
         - name: limit
           in: query
           required: false
-          description: Max items to return (1–500).
+          description: Page size — max items to return (1–500). A page shorter than `limit` is the last one.
           schema:
             type: integer
             minimum: 1
             maximum: 500
+            default: 200
+          x-mcp:
+            required: true
+        - name: offset
+          in: query
+          required: false
+          description: Number of items to skip before the page starts. Defaults to 0. The order is stable, so `offset += limit` walks the queue page by page.
+          schema:
+            type: integer
+            minimum: 0
+            maximum: 100000
+            default: 0
         - name: owner
           in: query
           required: false
-          description: Narrow to items owned by one person OR one agent. Matches a person by `users.id`, email, or display name, and an agent by connector id, display name, or kebab-case handle — e.g. `owner=Claude` or `owner=alice@acme.dev`. Case-insensitive exact match, applied over the returned page.
+          description: Narrow to items owned by one person OR one agent. Matches a person by `users.id`, email, or display name, and an agent by connector id, display name, or kebab-case handle — e.g. `owner=Claude` or `owner=alice@acme.dev`. Case-insensitive exact match.
           schema:
             type: string
       responses:
@@ -5519,6 +5615,8 @@ paths:
         - FORBIDDEN
       x-cli:
         name: list
+      x-mcp:
+        description: 'List the operational queue (bugs, feature requests, errors, alerts, measurement plans) in work order — highest priority first, oldest first within a priority. PAGING: `limit` (page size, 1–500) is REQUIRED — the call fails without it. Start at `offset: 0` and add `limit` to `offset` for the next page; a page shorter than `limit` is the last one. FILTERS (all optional, combined with AND, applied before paging): `type` = bug | feature_request | error | alert | measure_plan; `status` = open | in_progress | investigating_by_ai | blocked | ready_for_qa | resolved | wont_fix | pending_approval | unresolved | all — DEFAULTS TO `unresolved` (omitted = items still being worked: open, in_progress, blocked, ready_for_qa…; no resolved or wont_fix ones). Pass `status: "all"` to include resolved and wont_fix too (pending_approval is only returned when asked for exactly); `priority` = critical | high | medium | nice_to_have; `owner` = a person (id, email or name) or an agent (connector id, name or handle, e.g. "Claude"); `scope: "ready"` = what to work on now — open items nobody is working (no open run) that are unowned or were reopened after an earlier run. Use `scope: "ready"` to pick the next item, then `ops_ack` it.'
     post:
       operationId: createOpsItem
       summary: File a queue item
@@ -5615,6 +5713,8 @@ paths:
 
         The project is the key's own project; there is no `X-Project-Id` to pass and no way to file into someone else's queue. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
 
+        Send a `dedupKey` to own that grain yourself — the same key from a monitor, a job, or a retried install re-triggers its open ticket: the ticket's fields are refreshed from the new payload and a "re-triggered" comment is appended (`200` with `deduped: true, updated: true`), so one recurring failure stays one ticket with its history intact.
+
         This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
 
         **Use case:** `shipeasy setup` fails on a customer's machine and self-reports the failure with the user's consent — `{ "title": "Setup failed at Feature installs", "stepsToReproduce": "…", "actualResult": "…" }`.
@@ -5694,7 +5794,7 @@ paths:
       description: |-
         Files one feature request onto a project's queue, awaiting human approval. The feature-request counterpart to `POST /ops/bug`, with the same three gates: a `client` key carrying `tickets:public_create`, a project that has opted in, and a `pending_approval` state forced server-side.
 
-        The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again.
+        The project is the key's own project; there is no `X-Project-Id` to pass. Repeat submissions of the same title dedupe against the open ticket already tracking it, which returns `200` with `deduped: true` instead of filing again. A `dedupKey` works exactly as on `POST /ops/bug`: a repeat carrying the same key refreshes the open ticket and comments that it was re-triggered.
 
         This endpoint is served by the Shipeasy **edge worker** (`api.shipeasy.ai`), not the admin API — see `servers` below.
 
@@ -6013,6 +6113,11 @@ paths:
         list` and use one of those (or connect the agent under Settings →
         Triggers).
 
+        **Launching.** When the named agent has a connected trigger and you pass
+        no `sessionId`, the ack also fires that trigger — a new provider run
+        starts working the item. Pass `launch: false` to only claim the item and
+        record the run (you are doing the work yourself), without starting one.
+
         **Completion.** The run closes automatically on the loop's final actions —
         linking the fixing PR (`link-pr`), an ops-notify escalation, or a
         completion status change (`ready_for_qa`/`resolved`) — and the dashboard
@@ -6134,7 +6239,9 @@ paths:
         (`kind: investigated`), a blocking question for the team (`kind:
         question`), or how to verify the fix (`kind: ready_for_qa` with
         `qaNotes`). Append-only and create-only, so it is safe for restricted ops
-        keys.
+        keys. For a decision between options you can name, ask a structured
+        question instead (`ops questions ask`) — it is answerable in one tap and
+        the answer comes back to your run.
 
         **Use case:** After working an item, leave a findings write-up (summary,
         markdown findings, sources inspected, confidence) so the team — and the
@@ -6277,53 +6384,88 @@ paths:
         positional:
           - handle
           - investigationId
-  /api/admin/agent-profiles:
+  /api/admin/ops/{handle}/questions:
     get:
-      operationId: listOpsAgents
-      summary: List connected AI agents
+      operationId: listOpsQuestions
+      summary: List an item's questions
       description: |-
-        The project's connected AI agents — one per authenticated trigger
-        connector (Claude / Cursor / Copilot / Jules). These are the agent types
-        `ops ack` accepts and the agents a queue item can be assigned to.
-
-        **Use case:** Discover which `agent` values an AI ack can use, e.g. after
-        an `AGENT_NOT_CONNECTED` error.
+        The structured questions asked on a queue item, with their answers —
+        newest first (max 100). Pull this to read the answers to questions you
+        asked: an answered question reads `status: completed` and carries
+        `answer.selected` (the option labels picked) and `answer.other` (the
+        free-text "Other" reply, or `null`).
+
+        **Use case:** You asked with `delivery: poll` from a live session — poll
+        this until your questions read `completed`, then continue with the answers.
       tags:
-        - Agents
+        - Questions
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+        - name: status
+          in: query
+          required: false
+          description: Filter by question status, or `all` (the default).
+          schema:
+            default: all
+            anyOf:
+              - $ref: '#/components/schemas/OpsQuestionStatus'
+              - type: string
+                const: all
       responses:
         '200':
-          description: List connected AI agents
+          description: List an item's questions
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ListOpsAgentsResponse'
+                $ref: '#/components/schemas/ListOpsQuestionsResponse'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
           $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
+        - NOT_FOUND
       x-cli:
         name: list
-  /api/admin/ops/{handle}/comments:
-    get:
-      operationId: listOpsComments
-      summary: List an item's comments
+        positional:
+          - handle
+    post:
+      operationId: askOpsQuestions
+      summary: Ask the team questions about an item
       description: |-
-        List the comment thread on a queue item, oldest first. Each comment
-        carries its author (a teammate email, or `system` for a comment authored by
-        Jarvis — the AI agent), its markdown body, and `parentId` for the single
-        level of threaded replies. Removed comments are omitted.
-
-        **Use case:** Read the discussion on an item before replying or acting on it.
+        Ask 1–4 structured questions about a queue item — the way to get a
+        decision from a person when the implementation needs one. Each question
+        is the `AskUserQuestion` shape: a short `header` chip, the full
+        `question`, 2–4 `options` (`label` + `description`), and `multiSelect`
+        (checkboxes instead of radios). The person can always answer "Other" in
+        free text, so never add an "Other" option yourself. The questions render
+        at the very top of the item's detail panel and mark the row in the queue.
+
+        **Delivery.** `resume` re-fires your trigger-connector run on the item
+        once every question it asked is answered, continuing the same run record
+        with the answers in the prompt — stop after asking. `poll` fires nothing;
+        poll `GET .../questions` instead. Omitted, it is `resume` when `runId`
+        names a run launched through a trigger connector, else `poll`.
+
+        **Use case:** Blocked on a product decision (which behaviour to keep,
+        which of two fixes to ship) — ask instead of guessing, then wait for the
+        answer.
       tags:
-        - Comments
+        - Questions
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -6332,13 +6474,33 @@ paths:
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
             $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AskOpsQuestionsRequest'
+            examples:
+              single:
+                summary: Ask one radio question
+                value:
+                  runId: 0d3f4c8e-7a51-4c2e-9b1f-1e2d3c4b5a69
+                  questions:
+                    - header: Legacy param
+                      question: Should the fix keep honouring the legacy `?v=1` query param?
+                      multiSelect: false
+                      options:
+                        - label: Keep it
+                          description: Old links keep working; the redirect stays
+                        - label: Drop it
+                          description: Simpler code; old links land on the default view
       responses:
         '200':
-          description: List an item's comments
+          description: The created questions, in the order asked
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ListOpsCommentsResponse'
+                $ref: '#/components/schemas/AskOpsQuestionsResponse'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6347,28 +6509,33 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+        - VALIDATION
       x-cli:
-        name: list
+        name: ask
         positional:
           - handle
+  /api/admin/ops/{handle}/questions/{questionId}/answer:
     post:
-      operationId: createOpsComment
-      summary: Comment on an item
+      operationId: answerOpsQuestion
+      summary: Answer a question
       description: |-
-        Append a comment to a queue item's thread. The body is markdown (mentions
-        like `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,
-        to reply). Pass `parentId` to reply under an existing top-level comment
-        (one level of threading — a reply to a reply attaches to the same parent).
-
-        Create-only and append-only, so it is safe for restricted ops keys — the
-        same channel the ops loop and Jarvis use to leave a note on an item.
+        Answer one open question on a queue item — pick option labels in
+        `selected` (exactly one unless the question is `multiSelect`) and/or
+        write a free-text `other`. The question moves to `completed`. When it was
+        the last open question of a `resume` run, that agent is re-fired on the
+        item with every answer. A person's action: never allow-listed for
+        restricted ops keys.
+
+        **Use case:** Unblock an agent from the CLI instead of the dashboard.
       tags:
-        - Comments
+        - Questions
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -6377,31 +6544,35 @@ paths:
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
             $ref: '#/components/schemas/ResourceId'
+        - name: questionId
+          in: path
+          required: true
+          description: The question id (from `ask` or `list`).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/CreateOpsCommentRequest'
+              $ref: '#/components/schemas/AnswerOpsQuestionRequest'
             examples:
-              comment:
-                summary: Leave a comment
+              option:
+                summary: Pick an option
                 value:
-                  body: Repro'd on iOS Safari 17 — the button overflows its container. cc @alice
-              reply:
-                summary: Reply under an existing comment
+                  selected:
+                    - Keep it
+              other:
+                summary: Answer in free text
                 value:
-                  body: Agreed, let's ship the fix behind @shipeasy's suggested flag.
-                  parentId: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+                  other: Keep it for a release, then drop it
       responses:
-        '201':
-          description: Comment on an item
+        '200':
+          description: The answered question
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/CreateOpsCommentResponse'
-              example:
-                id: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+                $ref: '#/components/schemas/OpsQuestion'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6410,6 +6581,8 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
@@ -6417,48 +6590,48 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+        - INVALID_TRANSITION
         - VALIDATION
       x-cli:
-        name: create
+        name: answer
         positional:
           - handle
-  /api/admin/notifications:
+          - questionId
+  /api/admin/ops/{handle}/questions/{questionId}/cancel:
     post:
-      operationId: notifyOps
-      summary: Raise an attention notification
+      operationId: cancelOpsQuestion
+      summary: Withdraw a question
       description: |-
-        Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.
+        Withdraw one open question you asked — it no longer needs an answer
+        (you found it out yourself, or the item moved on). The question moves to
+        `cancelled` and leaves the detail panel. Withdrawing the last open
+        question of a run delivers nothing.
 
-        **Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.
+        **Use case:** You asked, then answered it yourself from the code — take
+        it off the person's plate.
       tags:
-        - Ops
+        - Questions
       parameters:
         - $ref: '#/components/parameters/ProjectId'
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/NotifyOpsRequest'
-            example:
-              title: 'Alert rule @alert:checkout-error-rate needs a human edit for #42'
-              summary: '#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human.'
-              steps:
-                - Open @alert:checkout-error-rate in the dashboard alerts page.
-                - Raise the threshold from `2%` to `5%` and widen the window to `1h`.
-                - 'Re-run the shipeasy-ops-work loop — #42 will be acknowledged.'
-              dedupeKey: feedback:42
-              href: /dashboard/prj_0abc/bugs/42
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+        - name: questionId
+          in: path
+          required: true
+          description: The question id (from `ask` or `list`).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
-          description: Raise an attention notification
+        '200':
+          description: The withdrawn question
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/NotifyOpsResponse'
-              example:
-                dedupeKey: error:checkout:5xx
-                dispatched: true
+                $ref: '#/components/schemas/OpsQuestion'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6469,41 +6642,53 @@ paths:
           $ref: '#/components/responses/NotFound'
         '409':
           $ref: '#/components/responses/Conflict'
-        '422':
-          $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
-        - VALIDATION
+        - NOT_FOUND
+        - INVALID_TRANSITION
       x-cli:
-        name: notify
-  /api/admin/slack/channels:
+        name: cancel
+        positional:
+          - handle
+          - questionId
+  /api/admin/ops/{handle}/qa-notes:
     get:
-      operationId: listSlackChannels
-      summary: List Slack channels
+      operationId: listOpsQaNotes
+      summary: List an item's QA notes
       description: |-
-        List the project's connected Slack channels — used to resolve an alert rule's notification target.
-
-        **Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.
+        The typed QA notes on a queue item, newest first (max 200) — narrowing,
+        clarification, verification and correction notes, each with its author and
+        time. They are separate from the comment thread: read these to learn the
+        CURRENT QA state of a ticket (what remains failing, what "fixed" now means,
+        the last verification verdict) without parsing prose comments.
+
+        **Use case:** A coding agent picks an item up and checks the latest
+        `verification` verdict and any `narrowing` note before touching the code.
       tags:
-        - Alerts
+        - QA notes
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+        - name: kind
+          in: query
+          required: false
+          description: Only notes of this kind.
+          schema:
+            $ref: '#/components/schemas/OpsQaNoteKind'
       responses:
         '200':
-          description: List Slack channels
+          description: List an item's QA notes
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ListSlackChannelsResponse'
-              example:
-                connected: true
-                channels:
-                  - id: C0123
-                    name: alerts
-                  - id: C0456
-                    name: general
+                $ref: '#/components/schemas/ListOpsQaNotesResponse'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6512,49 +6697,68 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
-        '409':
-          $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
+        - NOT_FOUND
       x-cli:
-        name: channels
-  /api/admin/alert-rules:
-    get:
-      operationId: listAlertRules
-      summary: List alert rules
+        name: list
+        positional:
+          - handle
+    post:
+      operationId: createOpsQaNote
+      summary: Add a QA note to an item
       description: |-
-        Returns every alert rule in the project (not paginated). Each rule carries its bound `metricId`, the denormalised `metricName` (or `null` if the metric was removed), the comparator/threshold/window, severity, enabled flag, and delivery target.
-
-        **Use case:** Audit which metrics have alerting configured — for example to confirm an on-call threshold is set before a launch.
+        Append one typed QA note to a queue item. `kind` is `narrowing` (what now
+        passes vs what still fails), `clarification` (what "fixed" now means),
+        `verification` (requires a `verdict` of `pass` or `fail`, and `body` says
+        what was checked) or `correction` (withdraws an earlier framing). Notes
+        are append-only and appear in the item's QA notes section, not in the
+        comment thread. The author is the caller's identity; pass `agent` to
+        record the note as written by that agent type's QA automation. A `fail` verdict never changes the item's
+        status by itself: the dashboard offers an explicit "Reopen item" action,
+        and `ops update --status open` does the same from the CLI.
+
+        **Use case:** QA automation records "verified on production: FAIL, the
+        second facet still errors" as data an agent can read back.
       tags:
-        - Alerts
+        - QA notes
       parameters:
         - $ref: '#/components/parameters/ProjectId'
-        - $ref: '#/components/parameters/Q'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOpsQaNoteRequest'
+            examples:
+              verification:
+                summary: A failing verification
+                value:
+                  kind: verification
+                  verdict: fail
+                  body: Retested on production after the deploy — the export still drops the second sheet
+              narrowing:
+                summary: Narrow a bug to the facet that still fails
+                value:
+                  kind: narrowing
+                  body: The list view is fixed; only the detail panel still shows the stale count
       responses:
         '200':
-          description: List alert rules
+          description: The created note
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/ListAlertRulesResponse'
-              example:
-                - id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
-                  name: Checkout error rate
-                  metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
-                  metricName: checkout_errors
-                  comparator: gt
-                  threshold: 50
-                  windowHours: 24
-                  severity: warn
-                  enabled: true
-                  notify: null
-                  createdAt: '2026-04-12T10:14:08.000Z'
-                  updatedAt: '2026-04-12T10:14:08.000Z'
+                $ref: '#/components/schemas/OpsQaNote'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6563,17 +6767,315 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '404':
           $ref: '#/components/responses/NotFound'
-        '409':
-          $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
       x-cli:
-        name: list
-    post:
+        name: create
+        positional:
+          - handle
+  /api/admin/agent-profiles:
+    get:
+      operationId: listOpsAgents
+      summary: List connected AI agents
+      description: |-
+        The project's connected AI agents — one per authenticated trigger
+        connector (Claude / Cursor / Copilot / Jules). These are the agent types
+        `ops ack` accepts and the agents a queue item can be assigned to.
+
+        **Use case:** Discover which `agent` values an AI ack can use, e.g. after
+        an `AGENT_NOT_CONNECTED` error.
+      tags:
+        - Agents
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: List connected AI agents
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListOpsAgentsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+      x-cli:
+        name: list
+  /api/admin/ops/{handle}/comments:
+    get:
+      operationId: listOpsComments
+      summary: List an item's comments
+      description: |-
+        List the comment thread on a queue item, oldest first. Each comment
+        carries its author (a teammate email, or `system` for a comment authored by
+        Jarvis — the AI agent), its markdown body, and `parentId` for the single
+        level of threaded replies. Removed comments are omitted.
+
+        **Use case:** Read the discussion on an item before replying or acting on it.
+      tags:
+        - Comments
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: List an item's comments
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListOpsCommentsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+      x-cli:
+        name: list
+        positional:
+          - handle
+    post:
+      operationId: createOpsComment
+      summary: Comment on an item
+      description: |-
+        Append a comment to a queue item's thread. The body is markdown (mentions
+        like `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,
+        to reply). Pass `parentId` to reply under an existing top-level comment
+        (one level of threading — a reply to a reply attaches to the same parent).
+
+        Create-only and append-only, so it is safe for restricted ops keys — the
+        same channel the ops loop and Jarvis use to leave a note on an item.
+      tags:
+        - Comments
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOpsCommentRequest'
+            examples:
+              comment:
+                summary: Leave a comment
+                value:
+                  body: Repro'd on iOS Safari 17 — the button overflows its container. cc @alice
+              reply:
+                summary: Reply under an existing comment
+                value:
+                  body: Agreed, let's ship the fix behind @shipeasy's suggested flag.
+                  parentId: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+      responses:
+        '201':
+          description: Comment on an item
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateOpsCommentResponse'
+              example:
+                id: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: create
+        positional:
+          - handle
+  /api/admin/notifications:
+    post:
+      operationId: notifyOps
+      summary: Raise an attention notification
+      description: |-
+        Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.
+
+        **Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.
+      tags:
+        - Ops
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NotifyOpsRequest'
+            example:
+              title: 'Alert rule @alert:checkout-error-rate needs a human edit for #42'
+              summary: '#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human.'
+              steps:
+                - Open @alert:checkout-error-rate in the dashboard alerts page.
+                - Raise the threshold from `2%` to `5%` and widen the window to `1h`.
+                - 'Re-run the shipeasy-ops-work loop — #42 will be acknowledged.'
+              dedupeKey: feedback:42
+              href: /dashboard/prj_0abc/bugs/42
+      responses:
+        '201':
+          description: Raise an attention notification
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/NotifyOpsResponse'
+              example:
+                dedupeKey: error:checkout:5xx
+                dispatched: true
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - VALIDATION
+      x-cli:
+        name: notify
+  /api/admin/slack/channels:
+    get:
+      operationId: listSlackChannels
+      summary: List Slack channels
+      description: |-
+        List the project's connected Slack channels — used to resolve an alert rule's notification target.
+
+        **Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.
+      tags:
+        - Alerts
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+      responses:
+        '200':
+          description: List Slack channels
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListSlackChannelsResponse'
+              example:
+                connected: true
+                channels:
+                  - id: C0123
+                    name: alerts
+                  - id: C0456
+                    name: general
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+      x-cli:
+        name: channels
+  /api/admin/alert-rules:
+    get:
+      operationId: listAlertRules
+      summary: List alert rules
+      description: |-
+        Returns every alert rule in the project (not paginated). Each rule carries its bound `metricId`, the denormalised `metricName` (or `null` if the metric was removed), the comparator/threshold/window, severity, enabled flag, and delivery target.
+
+        **Use case:** Audit which metrics have alerting configured — for example to confirm an on-call threshold is set before a launch.
+      tags:
+        - Alerts
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
+      responses:
+        '200':
+          description: List alert rules
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListAlertRulesResponse'
+              example:
+                - id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+                  name: Checkout error rate
+                  metricId: met_01j6abc2d3e4f5g6h7i8j9k0l1
+                  metricName: checkout_errors
+                  comparator: gt
+                  threshold: 50
+                  windowHours: 24
+                  severity: warn
+                  enabled: true
+                  notify: null
+                  createdAt: '2026-04-12T10:14:08.000Z'
+                  updatedAt: '2026-04-12T10:14:08.000Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+      x-cli:
+        name: list
+    post:
       operationId: createAlertRule
       summary: Create an alert rule
       description: |-
@@ -6790,7 +7292,9 @@ paths:
       description: |-
         Returns the project's FIRED alerts as a **bare JSON array** (no pagination envelope), ordered by `createdAt desc`. Defaults to the currently-firing ones (`status=active`); pass a `status` to widen to resolved/dismissed history or `all`.
 
-        Fired alerts are raised only by the platform — the UI's killswitch handlers plus the worker's analysis consumer and alerts cron — never filed by hand, so this surface is list + triage (via PATCH), with no create. The rules that *define* metric-threshold alerts live at `/api/admin/alert-rules`.
+        A fired alert is an **instance** of an alert rule, and an instance IS its ops queue item — the same row `/api/admin/ops` returns with `type: "alert"`, viewed through the alert lens. One rule produces many instances over its life and at most one is open at a time: when the condition clears the instance closes, and the next firing is a NEW instance with its own id and history. That is why `severity` reads off the rule (the queue item carries it as `priority`) and why resolving the queue item and clearing the alert are one act, not two rows to keep in step.
+
+        Instances are opened only by the platform — the UI's killswitch handlers plus the worker's analysis consumer and alerts cron — never filed by hand, so this surface is list + triage (via PATCH), with no create. The rules that *define* metric-threshold alerts live at `/api/admin/alert-rules`.
 
         **Use case:** Snapshot what is currently firing for an on-call view or the home Alerts block, or pull `status=all` to audit how a noisy rule has behaved over time.
       tags:
@@ -6874,7 +7378,7 @@ paths:
       description: |-
         Triage writes on one fired alert — the only mutations this surface allows. All body fields are optional (at least one required); only the fields present are changed.
 
-        - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. A resolved alert re-fires (as the same row, re-activated) if its condition is raised again.
+        - **`status`** — flip between `active` / `resolved` / `dismissed`. `resolved` and `dismissed` stamp `resolvedAt` / `dismissedAt`; `active` re-opens and clears both. These write the underlying queue item's own status (`resolved` / `wont_fix` / `open`), so clearing an alert here and resolving it in the ops queue are the same act. A cleared instance is never revived: if the condition fires again it opens a NEW instance with its own id.
         - **`assigneeId`** — the PERSON owner (a `users.id`), or `null` to unassign.
         - **`agent`** — the AGENT owner: a connected trigger connector's id, or the built-in `"jarvis"` (**Enterprise plan only** — `403` otherwise), or `null` to clear. Person and agent halves are independent.
 
@@ -6891,7 +7395,7 @@ paths:
         - name: id
           in: path
           required: true
-          description: Stable opaque alert id (`al_…`).
+          description: Stable opaque instance id — the same id as the `alert` ops item this instance is.
           schema:
             $ref: '#/components/schemas/ResourceId'
       requestBody:
@@ -7365,11 +7869,12 @@ paths:
         - name: limit
           in: query
           required: false
-          description: Max keys to return (1–500).
+          description: Max keys to return (1–500). Defaults to 200.
           schema:
             type: integer
             minimum: 1
             maximum: 500
+            default: 200
         - name: offset
           in: query
           required: false
@@ -9406,6 +9911,7 @@ paths:
                     expires_at: null
                     created_by_email: ana@example.com
                     name: production back-end
+                    description: Held by the checkout service; rotate with the quarterly credential sweep
                     scopes:
                       - gates:evaluate
                       - events:write
@@ -9474,18 +9980,313 @@ paths:
                 value:
                   type: ops
       responses:
-        '201':
-          description: Create an API key
+        '201':
+          description: Create an API key
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateKeyResponse'
+              example:
+                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
+                type: server
+                env: prod
+                key: sdk_server_9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
+                expires_at: null
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - VALIDATION
+        - PLAN_LIMIT
+      x-cli:
+        name: create
+  /api/admin/keys/{id}:
+    patch:
+      operationId: updateKey
+      summary: Update an API key's label
+      description: |-
+        Renames a key or re-notes what it is for. **Only `name` and `description` are editable** — everything that gives the key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint, because the worker derives the read env and permissions from the key itself. To change any of those, rotate: mint a replacement and revoke this one.
+
+        Omitted fields are left untouched; send `null` to clear one. Returns the updated key row. Revoked keys can still be relabelled (the audit trail outlives the credential). Returns `404` if no such key exists in the project.
+
+        **Use case:** A key minted by `shipeasy setup` carries an auto-composed provenance label — rename it to the service that actually holds it and note the rotation owner.
+      tags:
+        - API Keys
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: id
+          in: path
+          required: true
+          description: Stable opaque key id (UUID) returned by `create` / `list`.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateKeyRequest'
+            examples:
+              rename:
+                summary: Rename and note the key
+                value:
+                  name: checkout-service · production
+                  description: Held by the checkout service; rotation owner is the payments team
+              clearDescription:
+                summary: Clear the note
+                value:
+                  description: null
+      responses:
+        '200':
+          description: Update an API key's label
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/KeyRecord'
+              example:
+                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
+                type: server
+                env: prod
+                created_at: '2026-05-09T16:01:22.000Z'
+                revoked_at: null
+                expires_at: null
+                created_by_email: ana@example.com
+                name: checkout-service · production
+                description: Held by the checkout service; rotation owner is the payments team
+                scopes:
+                  - gates:evaluate
+                  - events:write
+                last4: a1b2
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: update
+        positional:
+          - id
+  /api/admin/keys/{id}/revoke:
+    post:
+      operationId: revokeKey
+      summary: Revoke an API key
+      description: |-
+        Revokes a key by id — stamps its `revoked_at` and deletes the hot-path KV entry so the token stops authenticating immediately. Takes no body.
+
+        Idempotent: revoking an already-revoked key is a no-op and returns the same `{ id, revoked: true }`. Returns `404` if no such key exists in the project.
+
+        **Use case:** Rotate a leaked or stale credential — mint the replacement, then revoke the old key.
+      tags:
+        - API Keys
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: id
+          in: path
+          required: true
+          description: Stable opaque key id (UUID) returned by `create` / `list`.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: Revoke an API key
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RevokeKeyResponse'
+              example:
+                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
+                revoked: true
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+      x-cli:
+        name: revoke
+        positional:
+          - id
+  /api/admin/search:
+    get:
+      operationId: searchResources
+      summary: Search project resources
+      description: |-
+        Universal substring search across the project's primary resources — feature gates, experiments, dynamic configs, killswitches, metrics, and team members. Matches the trimmed `q` against each resource's immutable `name` and its human title/display name (members match on display name or email), newest-first, capped per resource family so one noisy type can't crowd out the rest.
+
+        Returns a flat, ranked-by-type list of hits (members first); an empty or whitespace-only `q` returns no hits. Each hit carries a project-relative `href` that deep-links to the row.
+
+        **Use case:** Back a command-palette / quick-switcher in the dashboard, or look up the id of a resource by a fragment of its name before driving another API call.
+      tags:
+        - Projects
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: q
+          in: query
+          required: false
+          description: Search query. Matched as a case-insensitive substring against each resource's `name` and title/display name. Trimmed; empty returns no hits.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Search project resources
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SearchResponse'
+              example:
+                hits:
+                  - type: member
+                    id: ana@example.com
+                    name: Ana Ng
+                    title: ana@example.com
+                    href: /team
+                  - type: gate
+                    id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
+                    name: checkout_v2
+                    title: Checkout v2
+                    href: /gates?open=gat_01j7w7m9q4hxbf6npe6s9zr3vc
+                  - type: experiment
+                    id: exp_01j7w7m9q4hxbf6npe6s9zr3vd
+                    name: checkout_button_color
+                    title: Checkout button colour test
+                    href: /experiments?open=exp_01j7w7m9q4hxbf6npe6s9zr3vd
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+      x-cli:
+        name: search
+  /api/admin/tags:
+    get:
+      operationId: listTags
+      summary: List the project's tags
+      description: |-
+        Returns every tag in the project — the shared roster any item (queue items, flags, configs, kill switches, metrics, tracked errors, alert rules, experiments) can carry. Sorted by name.
+
+        **Use case:** See which tags already exist before tagging an item, so you reuse `ios` instead of minting `iOS-app`.
+      tags:
+        - Tags
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: q
+          in: query
+          required: false
+          description: Case-insensitive substring filter on the tag name. Omit to return every tag.
+          schema:
+            type: string
+            maxLength: 64
+      responses:
+        '200':
+          description: List the project's tags
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListTagsResponse'
+              example:
+                - id: tag_01j7w8a1b2c3d4e5f6g7h8i9j0
+                  name: checkout
+                - id: tag_01j7w8a1b2c3d4e5f6g7h8i9j1
+                  name: ios
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+      x-cli:
+        name: list
+  /api/admin/tags/{entityType}/{entityId}:
+    get:
+      operationId: getEntityTags
+      summary: Read an item's tags
+      description: |-
+        Returns the tags attached to one item. The item is addressed by kind (`entityType`) plus its handle, so the same call reads tags off a queue item, a flag, a config, a kill switch, a metric, a tracked error, an alert rule, or an experiment.
+
+        **Use case:** Check an item's current tags before editing them.
+      tags:
+        - Tags
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: entityType
+          in: path
+          required: true
+          description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
+          schema:
+            $ref: '#/components/schemas/TaggableEntityType'
+        - name: entityId
+          in: path
+          required: true
+          description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: Read an item's tags
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/CreateKeyResponse'
+                $ref: '#/components/schemas/EntityTagsResponse'
               example:
-                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
-                type: server
-                env: prod
-                key: sdk_server_9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
-                expires_at: null
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - ios
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -9499,42 +10300,73 @@ paths:
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
+        - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
-        - VALIDATION
-        - PLAN_LIMIT
+        - NOT_FOUND
       x-cli:
-        name: create
-  /api/admin/keys/{id}/revoke:
-    post:
-      operationId: revokeKey
-      summary: Revoke an API key
+        name: get
+        positional:
+          - entityType
+          - entityId
+    put:
+      operationId: setEntityTags
+      summary: Replace an item's tags
       description: |-
-        Revokes a key by id — stamps its `revoked_at` and deletes the hot-path KV entry so the token stops authenticating immediately. Takes no body.
+        Replaces the item's whole tag set with `tags`: names not yet in the project are created, attached names not in the list are detached, and `[]` clears every tag. Names are deduped case-insensitively, reusing an existing tag's casing (sending `iOS` when `ios` exists attaches `ios`).
 
-        Idempotent: revoking an already-revoked key is a no-op and returns the same `{ id, revoked: true }`. Returns `404` if no such key exists in the project.
+        **Use cases**
 
-        **Use case:** Rotate a leaked or stale credential — mint the replacement, then revoke the old key.
+        - **Tag an item** — `{ "tags": ["checkout", "ios"] }`.
+        - **Clear tags** — `{ "tags": [] }`.
+
+        To add or remove a few tags without restating the rest, use the incremental `PATCH` instead.
       tags:
-        - API Keys
+        - Tags
       parameters:
         - $ref: '#/components/parameters/ProjectId'
-        - name: id
+        - name: entityType
           in: path
           required: true
-          description: Stable opaque key id (UUID) returned by `create` / `list`.
+          description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
+          schema:
+            $ref: '#/components/schemas/TaggableEntityType'
+        - name: entityId
+          in: path
+          required: true
+          description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
           schema:
             $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SetEntityTagsRequest'
+            examples:
+              tag:
+                summary: Set the item's tags
+                value:
+                  tags:
+                    - checkout
+                    - ios
+              clear:
+                summary: Remove every tag
+                value:
+                  tags: []
       responses:
         '200':
-          description: Revoke an API key
+          description: Replace an item's tags
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/RevokeKeyResponse'
+                $ref: '#/components/schemas/EntityTagsResponse'
               example:
-                id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
-                revoked: true
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - ios
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -9548,57 +10380,74 @@ paths:
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
+        - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+        - VALIDATION
       x-cli:
-        name: revoke
+        name: set
         positional:
-          - id
-  /api/admin/search:
-    get:
-      operationId: searchResources
-      summary: Search project resources
+          - entityType
+          - entityId
+    patch:
+      operationId: updateEntityTags
+      summary: Add or remove tags on an item
       description: |-
-        Universal substring search across the project's primary resources — feature gates, experiments, dynamic configs, killswitches, metrics, and team members. Matches the trimmed `q` against each resource's immutable `name` and its human title/display name (members match on display name or email), newest-first, capped per resource family so one noisy type can't crowd out the rest.
+        Edits an item's tags incrementally: attaches every name in `add` (creating project tags as needed) and detaches every name in `remove`, leaving the item's other tags untouched. Matching is case-insensitive; a name in both lists ends up removed.
 
-        Returns a flat, ranked-by-type list of hits (members first); an empty or whitespace-only `q` returns no hits. Each hit carries a project-relative `href` that deep-links to the row.
+        **Use cases**
 
-        **Use case:** Back a command-palette / quick-switcher in the dashboard, or look up the id of a resource by a fragment of its name before driving another API call.
+        - **Add a tag** — `{ "add": ["regression"] }`.
+        - **Swap a tag** — `{ "add": ["p1"], "remove": ["p2"] }`.
       tags:
-        - Projects
+        - Tags
       parameters:
         - $ref: '#/components/parameters/ProjectId'
-        - name: q
-          in: query
-          required: false
-          description: Search query. Matched as a case-insensitive substring against each resource's `name` and title/display name. Trimmed; empty returns no hits.
+        - name: entityType
+          in: path
+          required: true
+          description: The kind of item — `ops`, `flag`, `config`, `killswitch`, `metric`, `error`, `alert_rule`, or `experiment`.
           schema:
-            type: string
+            $ref: '#/components/schemas/TaggableEntityType'
+        - name: entityId
+          in: path
+          required: true
+          description: The item's handle — an ops item's number (e.g. `7`) or id; a flag/config/killswitch/metric/alert rule/experiment's name or id; a tracked error's id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateEntityTagsRequest'
+            examples:
+              add:
+                summary: Attach one tag
+                value:
+                  add:
+                    - regression
+              swap:
+                summary: Replace one tag with another
+                value:
+                  add:
+                    - p1
+                  remove:
+                    - p2
       responses:
         '200':
-          description: Search project resources
+          description: Add or remove tags on an item
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/SearchResponse'
+                $ref: '#/components/schemas/EntityTagsResponse'
               example:
-                hits:
-                  - type: member
-                    id: ana@example.com
-                    name: Ana Ng
-                    title: ana@example.com
-                    href: /team
-                  - type: gate
-                    id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
-                    name: checkout_v2
-                    title: Checkout v2
-                    href: /gates?open=gat_01j7w7m9q4hxbf6npe6s9zr3vc
-                  - type: experiment
-                    id: exp_01j7w7m9q4hxbf6npe6s9zr3vd
-                    name: checkout_button_color
-                    title: Checkout button colour test
-                    href: /experiments?open=exp_01j7w7m9q4hxbf6npe6s9zr3vd
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - ios
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -9615,8 +10464,13 @@ paths:
         - BAD_REQUEST
         - UNAUTHORIZED
         - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
       x-cli:
-        name: search
+        name: update
+        positional:
+          - entityType
+          - entityId
 components:
   securitySchemes:
     bearerSdkKey:
@@ -11134,13 +11988,10 @@ components:
         aggregation:
           type: string
           enum:
-            - count_users
             - count_events
-            - retention_7d
-            - retention_30d
             - sum
             - avg
-          description: Reducer for the `event` form. Defaults to `count_users`.
+          description: 'Reducer for the `event` form. Defaults to `count_events`. `count_users` was removed: Analytics Engine samples rows and weights the survivors, and a distinct count cannot be reweighted, so it under-reports by the sample interval. `retention_7d` / `retention_30d` were removed on 2026-08-10: the day count reached no query and no reducer, so both produced the same number as a distinct user count and reported it as a returning-user rate.'
         value:
           type: string
           minLength: 1
@@ -13538,272 +14389,79 @@ components:
           description: Replacement allowed values (for `enum`), or `null` to clear.
         required:
           type: boolean
-          description: Whether the attribute must be present on the evaluation context.
-        description:
-          type: string
-          description: Optional human note shown in the dashboard.
-        sdk_path:
-          type: string
-          description: Optional dotted path the SDK reads the value from.
-      additionalProperties: false
-      description: Body for `PATCH /api/admin/attributes/{id}`. Every field is optional; `name` is immutable.
-    UpdateAttributeResponse:
-      type: object
-      properties:
-        id:
-          type: string
-          description: Id of the attribute that was updated.
-      required:
-        - id
-      additionalProperties: false
-      description: Response for `PATCH /api/admin/attributes/{id}`.
-    QueryIr:
-      description: Typed query IR — the structured alternative to the `query` DSL string. Exactly one of `query` / `query_ir` is supplied per metric body.
-      type: object
-      properties:
-        agg:
-          oneOf:
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: count_users
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: count_events
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: sum
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: avg
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: min
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: max
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: unique
-              required:
-                - kind
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: quantile
-                p:
-                  anyOf:
-                    - type: number
-                      const: 0.5
-                    - type: number
-                      const: 0.75
-                    - type: number
-                      const: 0.9
-                    - type: number
-                      const: 0.95
-                    - type: number
-                      const: 0.99
-                    - type: number
-                      const: 0.999
-                  description: Quantile fraction (0.5 = p50 … 0.999 = p999).
-              required:
-                - kind
-                - p
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: retention_Nd
-                'n':
-                  type: integer
-                  minimum: 1
-                  maximum: 90
-                  description: Retention window in days (1–90).
-              required:
-                - kind
-                - 'n'
-              additionalProperties: false
-            - type: object
-              properties:
-                kind:
-                  type: string
-                  const: ratio
-                numerator:
-                  type: object
-                  properties:
-                    agg:
-                      type: string
-                      enum:
-                        - count_users
-                        - count_events
-                      description: Counting mode for this ratio arm.
-                    metric:
-                      type: string
-                      minLength: 1
-                      maxLength: 128
-                      description: Source event name for this ratio arm.
-                    filters:
-                      description: Optional label filters.
-                      maxItems: 16
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          label:
-                            type: string
-                            pattern: ^[a-z_][a-z0-9_]{0,63}$
-                            description: Event property / label identifier.
-                          op:
-                            type: string
-                            enum:
-                              - '='
-                              - '!='
-                              - '=~'
-                              - '!~'
-                            description: Match operator (`=~`/`!~` are regex).
-                          value:
-                            type: string
-                            maxLength: 512
-                            description: Quoted filter value (coerced for numeric labels).
-                        required:
-                          - label
-                          - op
-                          - value
-                        additionalProperties: false
-                        description: One label filter on the source event.
-                  required:
-                    - agg
-                    - metric
-                  additionalProperties: false
-                  description: Numerator or denominator arm of a `ratio` aggregation.
-                denominator:
-                  type: object
-                  properties:
-                    agg:
-                      type: string
-                      enum:
-                        - count_users
-                        - count_events
-                      description: Counting mode for this ratio arm.
-                    metric:
-                      type: string
-                      minLength: 1
-                      maxLength: 128
-                      description: Source event name for this ratio arm.
-                    filters:
-                      description: Optional label filters.
-                      maxItems: 16
-                      type: array
-                      items:
-                        type: object
-                        properties:
-                          label:
-                            type: string
-                            pattern: ^[a-z_][a-z0-9_]{0,63}$
-                            description: Event property / label identifier.
-                          op:
-                            type: string
-                            enum:
-                              - '='
-                              - '!='
-                              - '=~'
-                              - '!~'
-                            description: Match operator (`=~`/`!~` are regex).
-                          value:
-                            type: string
-                            maxLength: 512
-                            description: Quoted filter value (coerced for numeric labels).
-                        required:
-                          - label
-                          - op
-                          - value
-                        additionalProperties: false
-                        description: One label filter on the source event.
-                  required:
-                    - agg
-                    - metric
-                  additionalProperties: false
-                  description: Numerator or denominator arm of a `ratio` aggregation.
-              required:
-                - kind
-                - numerator
-                - denominator
-              additionalProperties: false
-          description: Aggregation function applied to the source event.
-        metric:
-          type: string
-          minLength: 1
-          maxLength: 128
-          description: Source event name (must equal `event_name`).
-        valueLabel:
-          description: Numeric property summed/averaged for `sum`/`avg`/quantile aggregations.
-          type: string
-          minLength: 1
-          maxLength: 128
-        filters:
-          default: []
-          description: Label filters on the event.
-          maxItems: 16
-          type: array
-          items:
-            type: object
-            properties:
-              label:
-                type: string
-                pattern: ^[a-z_][a-z0-9_]{0,63}$
-                description: Event property / label identifier.
-              op:
-                type: string
-                enum:
-                  - '='
-                  - '!='
-                  - '=~'
-                  - '!~'
-                description: Match operator (`=~`/`!~` are regex).
-              value:
-                type: string
-                maxLength: 512
-                description: Quoted filter value (coerced for numeric labels).
-            required:
-              - label
-              - op
-              - value
-            additionalProperties: false
-            description: One label filter on the source event.
+          description: Whether the attribute must be present on the evaluation context.
+        description:
+          type: string
+          description: Optional human note shown in the dashboard.
+        sdk_path:
+          type: string
+          description: Optional dotted path the SDK reads the value from.
+      additionalProperties: false
+      description: Body for `PATCH /api/admin/attributes/{id}`. Every field is optional; `name` is immutable.
+    UpdateAttributeResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Id of the attribute that was updated.
+      required:
+        - id
+      additionalProperties: false
+      description: Response for `PATCH /api/admin/attributes/{id}`.
+    MetricDisplayConfig:
+      description: How the metric's series is DRAWN, as opposed to what it measures. Both parts used to be DSL functions (`expected(q, seasonal)`, `forecast(q, …)`), which meant turning a band on minted a different metric; they are properties now, so every chart of the metric picks them up and nothing that JUDGES the metric — an alert rule, the experiment analyzer — reads them at all.
+      type: object
+      properties:
+        band:
+          description: Shade the seasonal baseline around the series. The fit is the median of this hour of the week over the four weeks before the window, and it is the SAME fit an `anomaly` alert rule fires on — so the shaded region is exactly where such a rule would stay quiet, whether or not one exists.
+          type: object
+          properties:
+            method:
+              type: string
+              enum:
+                - seasonal
+            sigma:
+              type: number
+              exclusiveMinimum: 0
+              description: Half-width of the band in sigma-equivalents. Omit for 3, the sigma an alert rule also defaults to.
+          required:
+            - method
+          additionalProperties: false
+        forecast:
+          description: Project the series past the end of the window. Projected buckets are marked, so a chart can draw an estimate differently from a measurement.
+          type: object
+          properties:
+            method:
+              type: string
+              enum:
+                - linear
+                - seasonal
+              description: '`linear` continues a least-squares slope over the window it is already reading. `seasonal` de-seasonalises against the four weeks before the window, fits the trend on the remainder and adds the hour-of-week term back — ask for it when the metric has a shape.'
+            horizon:
+              type: integer
+              minimum: 1
+              maximum: 500
+              description: Buckets to project. Omit for a quarter of the window, which is the same claim at every bucket width.
+          required:
+            - method
+          additionalProperties: false
+      additionalProperties: false
+    QueryIr:
+      description: |-
+        A metric definition as a typed expression tree — the structured alternative to the `query` DSL string, and what the API stores. Exactly one of `query` / `query_ir` is supplied per metric body; `query` is the same definition written as text, and is the spelling to prefer.
+        Until 2026-08-10 this documented a single aggregation (`{agg, metric, filters}`, with `ratio` as a special case). That shape no longer exists — stored metrics were migrated and the code that read it was deleted — so a body sending it is rejected. Send the `query` string instead, or the tree below.
+      type: object
+      properties:
+        v:
+          type: integer
+          const: 2
+          description: Storage version of the definition. `2` is the only one.
+        expr:
+          type: object
+          additionalProperties: true
+          description: |-
+            The expression tree: aggregate leaves (`{node: "agg", event, agg, filters, valueLabel?}`), arithmetic over them (`{node: "binary", op, left, right}`), scalars, and function calls (`{node: "call", fn, arg, params?}`). A ratio is ordinary division of two leaves.
+            Deliberately opaque here rather than mirrored node by node: the grammar belongs to the query language, a second copy of it in this spec would drift from the one the server enforces, and the server validates every tree by planning it before the metric saves. `GET /api/admin/metrics` returns the grammar itself; the `query` string is the same tree in the form humans and the CLI write.
         groupBy:
           type: object
           properties:
@@ -13812,23 +14470,25 @@ components:
               enum:
                 - by
                 - without
-              description: '`by` keeps the listed labels; `without` drops them.'
+              description: '`by` names the output dimensions; `without` names the ones to drop.'
             labels:
-              maxItems: 5
               type: array
+              maxItems: 8
               items:
                 type: string
                 pattern: ^[a-z_][a-z0-9_]{0,63}$
                 description: Event property / label identifier.
-              description: Labels to group by (max 5).
+              description: Labels the grouping names.
           required:
             - op
             - labels
           additionalProperties: false
-          description: Optional group-by clause (ignored for experiment analysis).
+          description: How the series is split. On the envelope rather than in `expr` because every leaf of one expression shares it.
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
-        - agg
-        - metric
+        - v
+        - expr
       additionalProperties: false
     ListMetricsResponse:
       type: array
@@ -13930,6 +14590,12 @@ components:
         additionalProperties: {}
         description: A metric definition.
       description: Every metric in the project (the list endpoint is not paginated).
+    MetricDisplayName:
+      description: 'What a human calls the metric — "Checkout revenue" beside the `checkout.revenue` that identifies it. Unlike `name` it is free text, it is editable, and nothing addresses the metric by it: the dashboard leads with it and falls back to `name` when it is absent, so a metric nobody named simply reads as its key. Send `null` to clear it.'
+      maxLength: 200
+      anyOf:
+        - type: string
+        - type: 'null'
     MetricEventName:
       type: string
       minLength: 1
@@ -13969,6 +14635,8 @@ components:
       properties:
         name:
           $ref: '#/components/schemas/MetricName'
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -13983,6 +14651,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - name
         - event_name
@@ -13994,6 +14664,8 @@ components:
       properties:
         name:
           $ref: '#/components/schemas/MetricName'
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14008,6 +14680,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - name
         - event_name
@@ -14133,6 +14807,8 @@ components:
     UpdateMetricWithQuery:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14147,6 +14823,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - query
       additionalProperties: false
@@ -14154,6 +14832,8 @@ components:
     UpdateMetricWithQueryIr:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14168,6 +14848,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - query_ir
       additionalProperties: false
@@ -14175,6 +14857,8 @@ components:
     UpdateMetricFields:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14187,8 +14871,10 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       additionalProperties: false
-      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
+      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit, band and projection).
     UpdateMetricRequest:
       oneOf:
         - $ref: '#/components/schemas/UpdateMetricWithQuery'
@@ -14287,6 +14973,14 @@ components:
               v:
                 type: number
                 description: Aggregated metric value in the bucket (sample-interval weighted).
+              lo:
+                type: number
+                description: |
+                  Lower edge of the seasonal band — what this hour of the week normally holds, `sigma` below the median of the four weeks before the window. Present only for a metric whose `display.band` is on, and always alongside `hi`.
+              hi:
+                type: number
+                description: |
+                  Upper edge of the seasonal band. Present only for a metric whose `display.band` is on, and always alongside `lo`. A point outside `[lo, hi]` is exactly a bucket an `anomaly` alert rule at the same sigma would breach on — the band a chart draws and the condition a rule fires on come from one fit.
             required:
               - t
               - v
@@ -14330,7 +15024,8 @@ components:
                   type: string
                   minLength: 1
                   maxLength: 64
-                  description: Property key, e.g. `amount` or `plan`.
+                  pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+                  description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
                 type:
                   type: string
                   enum:
@@ -14346,11 +15041,14 @@ components:
                   default: ''
                   description: Human-readable description of the property.
                   type: string
+                pending:
+                  description: '`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event''s schema irreversibly.'
+                  type: boolean
               required:
                 - name
                 - type
               additionalProperties: false
-              description: One typed property declared on a catalogued event.
+              description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
             description: Typed properties declared on the event.
           pending:
             type: integer
@@ -14375,8 +15073,8 @@ components:
       properties:
         name:
           type: string
-          pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,127}$
-          description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 128 chars. Immutable after create — this is the handle metric queries reference.
+          pattern: ^[a-zA-Z0-9_][a-zA-Z0-9_\-.]{0,49}$
+          description: Event name. Starts with a letter, digit, or `_`; letters, digits, `_`, `-`, `.`; max 50 characters. The cap is the Analytics Engine index budget — 96 bytes total, less a 36-byte project UUID and a separator — and the API has always enforced 50 while this spec advertised 128. The charset is ASCII, so characters and bytes are the same count. Immutable after create — this is the handle metric queries reference.
         folder:
           $ref: '#/components/schemas/Folder'
         description:
@@ -14393,7 +15091,8 @@ components:
                 type: string
                 minLength: 1
                 maxLength: 64
-                description: Property key, e.g. `amount` or `plan`.
+                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
               type:
                 type: string
                 enum:
@@ -14465,7 +15164,8 @@ components:
                 type: string
                 minLength: 1
                 maxLength: 64
-                description: Property key, e.g. `amount` or `plan`.
+                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
               type:
                 type: string
                 enum:
@@ -14481,11 +15181,14 @@ components:
                 default: ''
                 description: Human-readable description of the property.
                 type: string
+              pending:
+                description: '`true` when this property was DISCOVERED in live traffic rather than declared. Nothing is recorded for it yet — a property is written to Analytics Engine only once it owns a column, and a column is allocated when an admin declares the property (include it in a `PATCH .../events/{id}` body). Approval is a gate rather than a formality: columns are finite and permanently reserved, so auto-allocating them from customer payload keys would exhaust an event''s schema irreversibly.'
+                type: boolean
             required:
               - name
               - type
             additionalProperties: false
-            description: One typed property declared on a catalogued event.
+            description: One typed property on a catalogued event — declared by an admin, or discovered in traffic and awaiting declaration.
           description: Typed properties declared on the event.
         pending:
           type: integer
@@ -14532,7 +15235,8 @@ components:
                 type: string
                 minLength: 1
                 maxLength: 64
-                description: Property key, e.g. `amount` or `plan`.
+                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
               type:
                 type: string
                 enum:
@@ -14583,7 +15287,8 @@ components:
                 type: string
                 minLength: 1
                 maxLength: 64
-                description: Property key, e.g. `amount` or `plan`.
+                pattern: ^[a-zA-Z_][a-zA-Z_0-9]*$
+                description: Property key, e.g. `amount` or `plan`. Must be a bare identifier — it is emitted as a SQL alias when the property is used as a `by()` dimension, and there is no way to quote one in the Analytics Engine dialect.
               type:
                 type: string
                 enum:
@@ -14641,6 +15346,7 @@ components:
       enum:
         - pr_ready
         - pr_merged
+        - pr_closed
         - investigated
         - detected
         - question
@@ -14648,7 +15354,7 @@ components:
         - pending_approval
         - working
         - backlog
-      description: 'Where automation has taken an item in the investigation lifecycle — the signal the ops cockpit renders as "what AI did" plus the one action expected of the user. It is **written as a side-effect of the actions that already happen**, never authored on its own: linking a PR sets `pr_ready`, moving to `in_progress` sets `working`, `ready_for_qa` sets `ready_for_qa`, a system/assistant reply sets `question`, resolving clears it, and creation seeds `backlog` or `investigated`/`detected` for auto-filed error/alert tickets. `backlog` is the single "nothing has happened yet" state — how urgent that is reads off `priority`, not off a separate state, and its one action is to hand the item to an agent. `pr_merged` is derived client-side by scanning the linked pull request on GitHub, so it is accepted on write but not currently emitted by the API. Absent on rows filed before the field existed — consumers should treat a missing value as "derive from the other fields".'
+      description: 'Where automation has taken an item in the investigation lifecycle — the signal the ops cockpit renders as "what AI did" plus the one action expected of the user. It is **written as a side-effect of the actions that already happen**, never authored on its own: linking a PR sets `pr_ready`, moving to `in_progress` sets `working`, `ready_for_qa` sets `ready_for_qa`, a system/assistant reply sets `question`, resolving clears it, and creation seeds `backlog` for every untouched item (bugs, features, and auto-filed error/alert tickets alike — type is not a signal). `backlog` is the single "nothing has happened yet" state — how urgent that is reads off `priority`, not off a separate state, and its one action is to hand the item to an agent. `investigated`/`detected` are set when a completed agent run leaves findings to review, not at filing time. `pr_merged` and `pr_closed` are written by the GitHub `pull_request` webhook when the linked PR reaches a terminal outcome — merged (the fix shipped, resolve the item) or closed without merging (the fix was rejected, decide what happens next). Absent on rows filed before the field existed — consumers should treat a missing value as "derive from the other fields".'
     OpsBrowserContext:
       type: object
       properties:
@@ -14808,20 +15514,31 @@ components:
           type: string
           enum:
             - metric_rule
+            - killswitch_armed
             - experiment_srm
             - experiment_peek
             - guardrail
-          description: What kind of alert transitioned to active.
+          description: What kind of condition opened this alert instance.
         dedupeKey:
           type: string
           description: Stable per-condition key; with `source` forms the ticket's `sourceRef`.
+        detail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The instance's one-line reading — the observed condition in words.
+        ruleId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Id of the alert rule that opened this instance, or `null` for a built-in condition.
         severity:
           type: string
           enum:
             - danger
             - warn
             - info
-          description: Alert severity.
+          description: How loud the alert is. Severity belongs to the RULE and is carried by this ticket as `priority`; it is DERIVED from that on the hydrated single-item read, and absent from the raw stored context list rows return.
         observedValue:
           anyOf:
             - type: number
@@ -14840,7 +15557,7 @@ components:
                 - resolved
                 - dismissed
             - type: 'null'
-          description: Current status of the underlying alert (`active` while the condition holds), or `null` if the alert row is gone.
+          description: Firing state of this instance, projected from the ticket's own status (`active` while it is open, i.e. while the condition holds). Absent from the raw stored context list rows return.
         activeSince:
           anyOf:
             - type: string
@@ -14864,9 +15581,8 @@ components:
       required:
         - source
         - dedupeKey
-        - severity
       additionalProperties: {}
-      description: Hydrated detail for an auto-filed `alert` ticket, resolving the rule → metric → event chain at request time.
+      description: Detail for an `alert` ticket — the fired-alert INSTANCE this ticket is. List rows carry the stored capture subset (`source`, `dedupeKey`, `ruleId`, `detail`, `href`, `observedValue`); the single-item read hydrates the rest, resolving `severity`/`status` off the ticket itself and the rule → metric → event chain at request time.
     MeasurePlanResource:
       type: object
       properties:
@@ -14970,7 +15686,7 @@ components:
                 properties:
                   t:
                     type: number
-                    description: Bucket start — unix epoch **milliseconds** (hourly buckets).
+                    description: Bucket start — unix epoch **milliseconds**. Bucket width scales with the window (hourly up to ~5 days, coarser beyond).
                   v:
                     type: number
                     description: Occurrence count in the bucket (sample-rate weighted).
@@ -14978,11 +15694,11 @@ components:
                   - t
                   - v
                 additionalProperties: {}
-                description: One hourly occurrence bucket.
-              description: Hourly occurrence buckets, oldest first. Hours with no occurrences are omitted.
+                description: One occurrence bucket.
+              description: Occurrence buckets, oldest first. Buckets with no occurrences are omitted.
             domainFrom:
               type: number
-              description: Chart domain start — unix epoch milliseconds (24h before the read).
+              description: Chart domain start — unix epoch milliseconds (the window's start).
             domainTo:
               type: number
               description: Chart domain end — unix epoch milliseconds (the read time).
@@ -14991,7 +15707,7 @@ components:
             - domainFrom
             - domainTo
           additionalProperties: {}
-          description: Occurrence timeline for an `error` ticket — hourly buckets over the last 24h from the sampled occurrences, hydrated at read time by the single-item read only. ABSENT (not `null`) on non-error tickets, on list rows (raw context), and when no occurrence landed in the window.
+          description: 'Occurrence timeline for an `error` ticket — buckets over the project''s error auto-close window (Settings → Errors: `errorAutocloseDays`, 7 days when auto-close is off, capped at 30) from the sampled occurrences, hydrated at read time by the single-item read only. Plotting exactly the quiet window that auto-resolves the error is what makes an empty right-hand edge meaningful. ABSENT (not `null`) on non-error tickets, on list rows (raw context), and when no occurrence landed in the window.'
       additionalProperties: {}
       description: Per-type capture context on a queue item. Exactly one of `browser` (bug/feature), `error`, `alert`, or `measurePlan` is populated depending on `type`; other keys (e.g. the AI dedupe block on bugs) may also be present.
     GithubPrLink:
@@ -15015,6 +15731,25 @@ components:
             - closes
             - comment
           description: How the PR was connected to the issue.
+        owner:
+          type: string
+          description: Repository owner (org or user) the pull request lives in. Absent on links recorded before the field existed — `url` still carries it.
+        repo:
+          type: string
+          description: Repository name the pull request lives in. Absent on links recorded before the field existed — `url` still carries it.
+        state:
+          type: string
+          enum:
+            - open
+            - merged
+            - closed
+          description: Outcome of the pull request on GitHub, kept current by the `pull_request` webhook. `merged` and `closed` (closed WITHOUT merging, i.e. rejected) are terminal. Absent means the outcome has never been observed — treat it as `open`.
+        mergedAt:
+          type: string
+          description: ISO-8601 timestamp the pull request merged, when `state` is `merged`.
+        closedAt:
+          type: string
+          description: ISO-8601 timestamp the pull request closed unmerged, when `state` is `closed`.
       required:
         - number
         - url
@@ -15387,6 +16122,11 @@ components:
         additionalProperties: {}
         description: One queue item — any type — plus its resolved `owner` and run state.
       description: A page of queue items, newest first.
+    TagName:
+      type: string
+      minLength: 1
+      maxLength: 64
+      description: A tag name. Trimmed; matched case-insensitively against the project's existing tags.
     CreateBugRequest:
       type: object
       properties:
@@ -15439,10 +16179,11 @@ components:
           description: Emails of teammates to subscribe to this item's Slack pings at creation.
         tags:
           type: array
+          maxItems: 50
           items:
-            type: string
+            $ref: '#/components/schemas/TagName'
           default: []
-          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+          description: Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name is matched case-insensitively against the project's existing tags and reuses that tag (keeping its stored casing) when one matches; a name with no match creates a new project tag.
         reporterEmail:
           anyOf:
             - type: string
@@ -15530,10 +16271,11 @@ components:
           description: Emails of teammates to subscribe to this item's Slack pings at creation.
         tags:
           type: array
+          maxItems: 50
           items:
-            type: string
+            $ref: '#/components/schemas/TagName'
           default: []
-          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+          description: Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name is matched case-insensitively against the project's existing tags and reuses that tag (keeping its stored casing) when one matches; a name with no match creates a new project tag.
         reporterEmail:
           anyOf:
             - type: string
@@ -15640,10 +16382,11 @@ components:
           description: Emails of teammates to subscribe to this item's Slack pings at creation.
         tags:
           type: array
+          maxItems: 50
           items:
-            type: string
+            $ref: '#/components/schemas/TagName'
           default: []
-          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+          description: 'Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name is matched case-insensitively against the project''s existing tags and reuses that tag (keeping its stored casing) when one matches; a name with no match creates a new project tag. Here the tags only label the ticket: the project''s tag rules (owner/status/agent routing) are not applied to a public report while it awaits approval.'
         reporterEmail:
           anyOf:
             - type: string
@@ -15674,6 +16417,10 @@ components:
               additionalProperties: {}
             - type: 'null'
           description: Arbitrary capture context, or `null`.
+        dedupKey:
+          type: string
+          maxLength: 200
+          description: 'Caller-chosen dedupe identity for this report, stored on the ticket. A repeat submission carrying the same key does NOT file a second ticket: the open ticket already holding that key is refreshed from this payload (title and the report fields overwritten, a "re-triggered" comment appended) and returned with `deduped: true` and `updated: true`. Triage state a human owns — status, priority, assignee, tags — is left untouched, and a `resolved`/`wont_fix` ticket no longer holds the key, so a failure that comes back after being closed files a fresh ticket. Omit it to fall back to the derived (title + `context.step`) dedupe, whose repeats return the existing ticket unchanged.'
         notify:
           anyOf:
             - $ref: '#/components/schemas/NotificationTarget'
@@ -15682,7 +16429,7 @@ components:
       required:
         - title
       additionalProperties: false
-      description: Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed.
+      description: Body for `POST /ops/bug`. The same bug fields as `CreateBugRequest`, minus the `type` discriminator — the path already says what is being filed, plus the public intake's own `dedupKey`.
     CreatePublicTicketResponse:
       type: object
       properties:
@@ -15695,10 +16442,13 @@ components:
         deduped:
           type: boolean
           description: '`true` when an open ticket already tracked this report and nothing was filed (HTTP 200). Absent on a fresh file (HTTP 201).'
+        updated:
+          type: boolean
+          description: '`true` when the deduped ticket was REFRESHED from this payload and got a "re-triggered" comment — only ever set alongside `deduped` on a submission that carried a `dedupKey`. Absent when the existing ticket was returned untouched.'
       required:
         - number
       additionalProperties: false
-      description: 'Response for the public ticket intake. A fresh file returns `201` with `id` + `number`; a repeat of a report already tracked by an open ticket returns `200` with that ticket''s `number` and `deduped: true`.'
+      description: 'Response for the public ticket intake. A fresh file returns `201` with `id` + `number`; a repeat of a report already tracked by an open ticket returns `200` with that ticket''s `number` and `deduped: true` — plus `updated: true` when a `dedupKey` re-triggered it and its fields were refreshed.'
     CreatePublicFeatureRequestRequest:
       type: object
       properties:
@@ -15741,10 +16491,11 @@ components:
           description: Emails of teammates to subscribe to this item's Slack pings at creation.
         tags:
           type: array
+          maxItems: 50
           items:
-            type: string
+            $ref: '#/components/schemas/TagName'
           default: []
-          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
+          description: 'Tag names to label the item with, e.g. `["ios", "checkout"]`. Each name is matched case-insensitively against the project''s existing tags and reuses that tag (keeping its stored casing) when one matches; a name with no match creates a new project tag. Here the tags only label the ticket: the project''s tag rules (owner/status/agent routing) are not applied to a public report while it awaits approval.'
         reporterEmail:
           anyOf:
             - type: string
@@ -15769,6 +16520,10 @@ components:
               additionalProperties: {}
             - type: 'null'
           description: Arbitrary capture context, or `null`.
+        dedupKey:
+          type: string
+          maxLength: 200
+          description: 'Caller-chosen dedupe identity for this request, stored on the ticket. Behaves exactly as on `POST /ops/bug`: a repeat carrying the same key refreshes the open ticket already holding it (fields overwritten, a "re-triggered" comment appended) and returns `deduped: true` with `updated: true`, instead of filing a second one.'
         notify:
           anyOf:
             - $ref: '#/components/schemas/NotificationTarget'
@@ -15777,7 +16532,7 @@ components:
       required:
         - title
       additionalProperties: false
-      description: Body for `POST /ops/feature-request`. The same feature-request fields as `CreateFeatureRequestRequest`, minus the `type` discriminator — the path already says what is being filed.
+      description: Body for `POST /ops/feature-request`. The same feature-request fields as `CreateFeatureRequestRequest`, minus the `type` discriminator — the path already says what is being filed, plus the public intake's own `dedupKey`.
     OpsItemAttachment:
       type: object
       properties:
@@ -16121,6 +16876,10 @@ components:
           type: string
           maxLength: 300
           description: The agent-run session id (e.g. Claude's `session_01…`), so the dashboard can deep-link to the exact run page. Omit when the harness has no session id.
+        launch:
+          type: boolean
+          default: true
+          description: 'Whether an AI ack may FIRE the agent''s connected trigger. Default `true`: an ack naming a connected agent, with no `sessionId`, starts a new provider run of that agent. Pass `false` to only record the ack — claim the item and open the run record — without starting anything, e.g. when you ARE that agent working the item yourself and have no session id to pass. Ignored on a human ack.'
       additionalProperties: false
       description: Body for `POST /api/admin/ops/{handle}/ack`. With `agent` set this is an AI ack — the named agent type must have a connected trigger connector in the project, or the call fails with `AGENT_NOT_CONNECTED` and instructions to query the available agents (`ops agents list`). `gemini` is accepted as an alias for `jules`. Without `agent` it is a HUMAN ack by the authenticated caller.
     AckOpsItemResponse:
@@ -16448,100 +17207,441 @@ components:
           description: ISO-8601 timestamp the work finished.
         sessionId:
           type: string
-          maxLength: 300
-          description: The agent-run session id, so the dashboard can deep-link to the run.
+          maxLength: 300
+          description: The agent-run session id, so the dashboard can deep-link to the run.
+      required:
+        - kind
+      additionalProperties: false
+      description: Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets.
+    UpdateOpsInvestigationRequest:
+      type: object
+      properties:
+        kind:
+          type: string
+          enum:
+            - investigated
+            - detected
+            - question
+            - ready_for_qa
+            - working
+            - note
+          description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
+        summary:
+          type: string
+          maxLength: 2000
+          description: One-line summary of the record.
+        findings:
+          type: string
+          maxLength: 50000
+          description: The full findings write-up (markdown).
+        question:
+          type: string
+          maxLength: 10000
+          description: A blocking question for the team (markdown).
+        qaNotes:
+          type: string
+          maxLength: 50000
+          description: How to verify the fix — QA notes (markdown).
+        model:
+          type: string
+          maxLength: 200
+          description: The model the agent ran on.
+        prNumber:
+          type: integer
+          description: A PR the record references.
+        prUrl:
+          type: string
+          format: uri
+          maxLength: 2000
+          description: HTML URL of that PR.
+        sources:
+          type: array
+          maxItems: 200
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: Repo-relative file path inspected.
+              url:
+                type: string
+                description: External link consulted.
+              label:
+                type: string
+                description: Human-readable label for the source.
+            additionalProperties: false
+            description: One file/link inspected while producing the record.
+          description: The files/links inspected.
+        confidence:
+          type: string
+          enum:
+            - low
+            - medium
+            - high
+          description: Self-reported confidence in the record.
+        tokensUsed:
+          type: integer
+          description: Tokens the run consumed.
+        durationMs:
+          type: integer
+          description: Run duration in milliseconds.
+        visibility:
+          type: string
+          enum:
+            - draft
+            - published
+          description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
+        completedAt:
+          type: string
+          description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
+        sessionId:
+          type: string
+          maxLength: 300
+          description: The agent-run session id, so the dashboard can deep-link to the run.
+      additionalProperties: false
+      minProperties: 1
+      description: Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required.
+    OpsQuestionStatus:
+      type: string
+      enum:
+        - open
+        - completed
+        - cancelled
+      description: Where a question stands — `open` (waiting on a person), `completed` (answered), or `cancelled` (withdrawn by the asker).
+    OpsQuestionAnswer:
+      type: object
+      properties:
+        selected:
+          type: array
+          items:
+            type: string
+          description: The option labels the person picked (empty when they only answered "Other").
+        other:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The free-text "Other" answer, or `null`.
+      required:
+        - selected
+        - other
+      additionalProperties: false
+      description: A person's answer to a question.
+    OpsQuestionDelivery:
+      type: string
+      enum:
+        - resume
+        - poll
+      description: How the answer gets back to the asker — `resume` re-fires the asking run's trigger connector on the item once every question that run asked is answered; `poll` fires nothing and the asker reads `GET .../questions`.
+    OpsQuestion:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Question id.
+        feedbackId:
+          type: string
+          description: The queue item the question hangs off.
+        header:
+          type: string
+          description: Short chip label for the question.
+        question:
+          type: string
+          description: The full question (markdown).
+        options:
+          type: array
+          items:
+            type: object
+            properties:
+              label:
+                type: string
+                description: The option's display text.
+              description:
+                anyOf:
+                  - type: string
+                  - type: 'null'
+                description: What picking the option means, or `null`.
+            required:
+              - label
+              - description
+            additionalProperties: false
+            description: One offered choice.
+          description: The offered choices, in order.
+        multiSelect:
+          type: boolean
+          description: Whether several options may be picked.
+        status:
+          $ref: '#/components/schemas/OpsQuestionStatus'
+        answer:
+          anyOf:
+            - $ref: '#/components/schemas/OpsQuestionAnswer'
+            - type: 'null'
+          description: The person's answer, or `null` while the question is open (or was withdrawn).
+        answeredBy:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Email of the person who answered, or `null`.
+        answeredAt:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: ISO-8601 timestamp of the answer, or `null`.
+        agent:
+          anyOf:
+            - type: string
+              enum:
+                - jarvis
+                - claude
+                - cursor
+                - copilot
+                - jules
+            - type: 'null'
+          description: The agent that asked, or `null` (asked by a person or an unattributed key).
+        askedBy:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Email of the person who asked, when a human asked, or `null`.
+        runId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The run (investigation record id) the question was asked under, or `null`.
+        delivery:
+          $ref: '#/components/schemas/OpsQuestionDelivery'
+        deliveredAt:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: ISO-8601 timestamp the answer was re-delivered to the asking run (`resume` only), or `null`.
+        deliveryError:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Why a `resume` re-delivery failed, or `null`.
+        createdAt:
+          type: string
+          description: ISO-8601 creation timestamp.
+        updatedAt:
+          type: string
+          description: ISO-8601 last-update timestamp.
       required:
-        - kind
+        - id
+        - feedbackId
+        - header
+        - question
+        - options
+        - multiSelect
+        - status
+        - answer
+        - answeredBy
+        - answeredAt
+        - agent
+        - askedBy
+        - runId
+        - delivery
+        - deliveredAt
+        - deliveryError
+        - createdAt
+        - updatedAt
       additionalProperties: false
-      description: Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets.
-    UpdateOpsInvestigationRequest:
+      description: One structured question on a queue item and, once answered, its answer.
+    ListOpsQuestionsResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/OpsQuestion'
+      description: Response for `GET /api/admin/ops/{handle}/questions` — the item's questions, newest first (max 100).
+    OpsQuestionOption:
       type: object
       properties:
-        kind:
+        label:
           type: string
-          enum:
-            - investigated
-            - detected
-            - question
-            - ready_for_qa
-            - working
-            - note
-          description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
-        summary:
+          minLength: 1
+          maxLength: 120
+          description: The option's display text — short (1–5 words). Answers name options by this label.
+        description:
           type: string
-          maxLength: 2000
-          description: One-line summary of the record.
-        findings:
+          maxLength: 500
+          description: What picking this option means — its trade-off or consequence.
+      required:
+        - label
+      additionalProperties: false
+      description: One choice offered by a question — rendered as a radio, or a checkbox when the question is `multiSelect`.
+    AskOpsQuestionInput:
+      type: object
+      properties:
+        header:
           type: string
-          maxLength: 50000
-          description: The full findings write-up (markdown).
+          minLength: 1
+          maxLength: 24
+          description: Very short chip label for the question (max 24 chars), e.g. `Auth method`.
         question:
           type: string
-          maxLength: 10000
-          description: A blocking question for the team (markdown).
-        qaNotes:
-          type: string
-          maxLength: 50000
-          description: How to verify the fix — QA notes (markdown).
-        model:
+          minLength: 1
+          maxLength: 2000
+          description: The complete question, ending with a question mark (markdown).
+        options:
+          type: array
+          minItems: 2
+          maxItems: 4
+          items:
+            $ref: '#/components/schemas/OpsQuestionOption'
+          description: 2–4 distinct choices. Do not add an "Other" option — a free-text answer is always offered.
+        multiSelect:
+          type: boolean
+          default: false
+          description: '`true` lets the person pick several options (checkboxes); `false` (the default) exactly one (radios).'
+      required:
+        - header
+        - question
+        - options
+      additionalProperties: false
+      description: One question to ask — the `AskUserQuestion` shape.
+    AskOpsQuestionsRequest:
+      type: object
+      properties:
+        questions:
+          type: array
+          minItems: 1
+          maxItems: 4
+          items:
+            $ref: '#/components/schemas/AskOpsQuestionInput'
+          description: 1–4 questions to ask at once.
+        runId:
           type: string
           maxLength: 200
-          description: The model the agent ran on.
-        prNumber:
-          type: integer
-          description: A PR the record references.
-        prUrl:
+          description: The run (investigation record id) you are working the item under — the `runId` an ack or a launch handed you. Ties the questions to that run so a `resume` delivery continues it.
+        agent:
           type: string
-          format: uri
-          maxLength: 2000
-          description: HTML URL of that PR.
-        sources:
+          enum:
+            - jarvis
+            - claude
+            - cursor
+            - copilot
+            - jules
+          description: The agent type asking — pass your own type when you are a coding agent. Defaults to the run's agent.
+        delivery:
+          $ref: '#/components/schemas/OpsQuestionDelivery'
+      required:
+        - questions
+      additionalProperties: false
+      description: Body for `POST /api/admin/ops/{handle}/questions`.
+    AskOpsQuestionsResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/OpsQuestion'
+      description: Response for `POST /api/admin/ops/{handle}/questions` — the created questions, in the order asked.
+    AnswerOpsQuestionRequest:
+      type: object
+      properties:
+        selected:
           type: array
-          maxItems: 200
+          maxItems: 4
           items:
-            type: object
-            properties:
-              path:
-                type: string
-                description: Repo-relative file path inspected.
-              url:
-                type: string
-                description: External link consulted.
-              label:
-                type: string
-                description: Human-readable label for the source.
-            additionalProperties: false
-            description: One file/link inspected while producing the record.
-          description: The files/links inspected.
-        confidence:
+            type: string
+            maxLength: 120
+          description: The option labels picked — exactly one for a single-select question (unless answering only with `other`), one or more for `multiSelect`.
+        other:
           type: string
-          enum:
-            - low
-            - medium
-            - high
-          description: Self-reported confidence in the record.
-        tokensUsed:
-          type: integer
-          description: Tokens the run consumed.
-        durationMs:
-          type: integer
-          description: Run duration in milliseconds.
-        visibility:
+          maxLength: 10000
+          description: A free-text "Other" answer.
+      additionalProperties: false
+      minProperties: 1
+      description: Body for `POST /api/admin/ops/{handle}/questions/{questionId}/answer` — pick option labels, write a free-text answer, or both (multi-select only).
+    OpsQaNoteKind:
+      type: string
+      enum:
+        - narrowing
+        - clarification
+        - verification
+        - correction
+      description: What a QA note is — `narrowing` (only part of the bug still fails), `clarification` (changes what "fixed" means), `verification` (a pass/fail verdict on a fix) or `correction` (withdraws an earlier framing).
+    OpsQaNoteVerdict:
+      type: string
+      enum:
+        - pass
+        - fail
+      description: The outcome a `verification` note records.
+    OpsQaNote:
+      type: object
+      properties:
+        id:
           type: string
-          enum:
-            - draft
-            - published
-          description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
-        completedAt:
+          description: Note id.
+        feedbackId:
           type: string
-          description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
-        sessionId:
+          description: The queue item the note hangs off.
+        kind:
+          $ref: '#/components/schemas/OpsQaNoteKind'
+        verdict:
+          anyOf:
+            - $ref: '#/components/schemas/OpsQaNoteVerdict'
+            - type: 'null'
+          description: The pass/fail verdict of a `verification` note; `null` for every other kind.
+        body:
           type: string
-          maxLength: 300
-          description: The agent-run session id, so the dashboard can deep-link to the run.
+          description: The note (markdown) — for a `verification`, what was checked.
+        authorEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Email of the person (or the key's actor) who wrote the note, or `null` when an agent wrote it.
+        authorAgent:
+          anyOf:
+            - type: string
+              enum:
+                - jarvis
+                - claude
+                - cursor
+                - copilot
+                - jules
+            - type: 'null'
+          description: The agent type that wrote the note (QA automation), or `null` for a person.
+        createdAt:
+          type: string
+          description: ISO-8601 creation timestamp.
+      required:
+        - id
+        - feedbackId
+        - kind
+        - verdict
+        - body
+        - authorEmail
+        - authorAgent
+        - createdAt
       additionalProperties: false
-      minProperties: 1
-      description: Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required.
+      description: One typed, append-only QA note on a queue item.
+    ListOpsQaNotesResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/OpsQaNote'
+      description: Response for `GET /api/admin/ops/{handle}/qa-notes` — the item's QA notes, newest first (max 200).
+    CreateOpsQaNoteRequest:
+      type: object
+      properties:
+        kind:
+          $ref: '#/components/schemas/OpsQaNoteKind'
+        body:
+          type: string
+          minLength: 1
+          maxLength: 10000
+          description: The note (markdown).
+        verdict:
+          $ref: '#/components/schemas/OpsQaNoteVerdict'
+        agent:
+          type: string
+          enum:
+            - jarvis
+            - claude
+            - cursor
+            - copilot
+            - jules
+          description: The agent type writing the note — pass your own type when you are QA automation. Omitted, the note is attributed to the caller's identity.
+      required:
+        - kind
+        - body
+      additionalProperties: false
+      description: Body for `POST /api/admin/ops/{handle}/qa-notes`. A `verification` note requires `verdict`; every other kind rejects it.
     OpsAgentProfile:
       type: object
       properties:
@@ -16735,6 +17835,59 @@ components:
         - channels
       additionalProperties: false
       description: Response for `GET /api/admin/slack/channels`.
+    AlertCompositeSpec:
+      type: object
+      description: 'What a `composite` rule is a boolean over. `rules` are sibling alert-rule ids in the same project and `op` is how their states combine. A child''s state is what the current pass concluded about it, falling back to whether it has an open instance — so a composite still means something on a tick where a child could not be evaluated, which is exactly the tick a "two of these are broken at once" rule is for. One level deep: a child may not itself be composite.'
+      properties:
+        op:
+          type: string
+          enum:
+            - and
+            - or
+          description: How the children's states combine.
+        rules:
+          type: array
+          minItems: 2
+          items:
+            type: string
+            minLength: 1
+          description: Ids of the alert rules to combine. Stored sorted and de-duplicated.
+      required:
+        - op
+        - rules
+      additionalProperties: false
+    AlertRuleNotify:
+      anyOf:
+        - type: object
+          properties:
+            slackChannel:
+              anyOf:
+                - type: object
+                  properties:
+                    id:
+                      type: string
+                      minLength: 1
+                    name:
+                      type: string
+                      minLength: 1
+                  required:
+                    - id
+                    - name
+                  additionalProperties: false
+                - type: 'null'
+            email:
+              anyOf:
+                - type: string
+                  format: email
+                - type: 'null'
+            inApp:
+              anyOf:
+                - type: boolean
+                - type: 'null'
+              description: Whether the in-app notification (the dashboard bell and Home) is recorded when the rule fires. Absent or `null` means on; `false` skips it for this rule.
+          additionalProperties: false
+        - type: 'null'
+      description: Delivery target for a rule's alert; `null` = use the project default. The `NotificationTarget` shape plus the in-app switch.
     ListAlertRulesResponse:
       type: array
       items:
@@ -16753,23 +17906,107 @@ components:
             anyOf:
               - type: string
               - type: 'null'
-            description: Display name of the bound metric, or `null` if the metric no longer exists.
-          comparator:
-            type: string
-            enum:
-              - gt
-              - gte
-              - lt
-              - lte
-            description: How the metric value is compared to the threshold (gt/gte/lt/lte).
-          threshold:
-            type: number
-            description: Threshold the metric value is compared against.
+            description: Display name of the bound metric, or `null` if the metric no longer exists.
+          kind:
+            type: string
+            enum:
+              - normal
+              - anomaly
+              - outliers
+              - no_data
+              - composite
+            description: What the rule watches for. `normal` compares the metric's own value — against `threshold` via `comparator`, or against the [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly` compares it against ITS OWN seasonal baseline in sigmas, which is the same fit a chart draws as the band. `outliers` compares each `by()` group against its peers in the same bucket, so it needs a grouped metric. `no_data` fires when the metric records nothing at all for `noDataMinutes` — a count of zero is not silence, and the two are distinguished by the reader's presence columns. `composite` is a boolean over OTHER rules' current state and watches no metric of its own.
+          comparator:
+            type: string
+            enum:
+              - gt
+              - gte
+              - lt
+              - lte
+            description: How the metric value is compared to the threshold (gt/gte/lt/lte). Read only by a `normal` rule with no range set.
+          threshold:
+            type: number
+            description: Threshold the metric value is compared against. Read only by a `normal` rule with no range set.
+          rangeMin:
+            anyOf:
+              - type: number
+              - type: 'null'
+            description: Lower edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
+          rangeMax:
+            anyOf:
+              - type: number
+              - type: 'null'
+            description: Upper edge of the corridor a `normal` rule must stay inside; `null` if the rule is judged by comparator and threshold.
+          sigma:
+            anyOf:
+              - type: number
+              - type: 'null'
+            description: How far from normal is too far, for `anomaly` and `outliers`, in sigma-equivalents. `null` takes the default of 3, which is also the width of the band a chart draws.
+          direction:
+            anyOf:
+              - type: string
+                enum:
+                  - above
+                  - below
+                  - either
+              - type: 'null'
+            description: Which side of the baseline an `anomaly` or `outliers` rule watches. `null` means either.
+          sustained:
+            type: boolean
+            description: Whether the rule is judged by ACCUMULATED departure rather than bucket by bucket. `anomaly` and `outliers` only.
+          warnThreshold:
+            anyOf:
+              - type: number
+              - type: 'null'
+            description: The milder bound, in the same unit the kind judges in. `null` means the rule has one level.
+          recoveryThreshold:
+            anyOf:
+              - type: number
+              - type: 'null'
+            description: What the metric must get back to before a live alert closes. `null` means no hysteresis — the firing bound clears it.
+          groupAlerts:
+            type: boolean
+            description: Whether the rule fires one alert per `by()` group rather than one for the whole metric.
+          maxGroups:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: How many groups this rule may alert on at once. `null` takes the shipped cap of 10.
+          noDataMinutes:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: How long the silence must last for a `no_data` rule. `null` on every other kind.
+          delayMinutes:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: How far behind live the evaluated window is held, on top of the reader's settle grace. `null` means no extra delay.
+          autoResolveMinutes:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: Close a live instance that has gone this long without a fresh verdict. `null` never auto-resolves.
+          composite:
+            anyOf:
+              - $ref: '#/components/schemas/AlertCompositeSpec'
+              - type: 'null'
+            description: For a `composite` rule, the child rules and how their states combine. `null` on every other kind.
           windowHours:
             type: integer
             minimum: -9007199254740991
             maximum: 9007199254740991
             description: Lookback window (hours) the metric is aggregated over.
+          bucketMinutes:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: Width of the buckets the window is split into, in minutes. `null` divides the window into 12 equal buckets.
+          requiredBuckets:
+            anyOf:
+              - type: integer
+              - type: 'null'
+            description: How many buckets must breach before the rule fires. `null` means every bucket that had data.
           severity:
             type: string
             enum:
@@ -16781,7 +18018,7 @@ components:
             type: boolean
             description: Whether the rule is evaluated by the cron.
           notify:
-            $ref: '#/components/schemas/NotificationTarget'
+            $ref: '#/components/schemas/AlertRuleNotify'
           createdAt:
             type: string
             description: ISO-8601 timestamp of creation.
@@ -16793,9 +18030,25 @@ components:
           - name
           - metricId
           - metricName
+          - kind
           - comparator
           - threshold
+          - rangeMin
+          - rangeMax
+          - sigma
+          - direction
+          - sustained
+          - warnThreshold
+          - recoveryThreshold
+          - groupAlerts
+          - maxGroups
+          - noDataMinutes
+          - delayMinutes
+          - autoResolveMinutes
+          - composite
           - windowHours
+          - bucketMinutes
+          - requiredBuckets
           - severity
           - enabled
           - notify
@@ -16815,26 +18068,122 @@ components:
           type: string
           minLength: 1
           description: Id of the metric to evaluate.
+        kind:
+          default: normal
+          description: 'What the rule watches for. `normal` compares the metric''s own value — against `threshold` via `comparator`, or against the [`rangeMin`, `rangeMax`] corridor it must stay inside. `anomaly` compares it against its own seasonal baseline in sigmas: the same fit a chart draws as the band, so a point outside the drawn band is exactly a breaching bucket, and one metric can back rules at several sigmas. `outliers` compares each `by()` group against its peers in the same bucket and is refused on a metric with no grouping.'
+          type: string
+          enum:
+            - normal
+            - anomaly
+            - outliers
+            - no_data
+            - composite
         comparator:
+          default: gt
+          description: How the metric value is compared to the threshold. Read only by a `normal` rule with no range set.
           type: string
           enum:
             - gt
             - gte
             - lt
             - lte
-          description: How the metric value is compared to the threshold (gt/gte/lt/lte).
         threshold:
           type: number
-          description: Threshold the metric value is compared against.
+          description: Threshold the metric value is compared against. Required for a `normal` rule unless a range is given; ignored by every other kind.
+        rangeMin:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: Lower edge of the corridor the metric must stay inside. Setting either bound switches a `normal` rule off `comparator`/`threshold` and onto the range, which breaches on LEAVING it in either direction. One bound alone is a one-sided range.
+        rangeMax:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: Upper edge of the corridor the metric must stay inside.
+        sigma:
+          anyOf:
+            - type: number
+              exclusiveMinimum: 0
+            - type: 'null'
+          description: How far from normal is too far, for `anomaly` and `outliers`, in sigma-equivalents. Omit (or `null`) for 3, which is also the half-width of the band a chart draws — so an unconfigured rule fires exactly where the picture says it would.
+        direction:
+          anyOf:
+            - type: string
+              enum:
+                - above
+                - below
+                - either
+            - type: 'null'
+          description: Which side of the baseline an `anomaly` or `outliers` rule watches. Omit (or `null`) for either, which is what "is this unusual" means; name a side for a metric that is only bad in one direction.
+        sustained:
+          default: false
+          type: boolean
+          description: 'Judge the window by ACCUMULATED departure instead of bucket by bucket. The ordinary check asks every bucket to be past `sigma`, which a slow regression never manages: a metric running 1.5σ worse than normal since Tuesday puts no single bucket past 3σ and pages nobody. A sustained rule adds up each bucket''s excess over half a sigma and fires once the total passes twice `sigma` — four buckets at 2σ do it, a lone 3σ spike does not. `anomaly` and `outliers` only, and refused alongside `requiredBuckets`: the accumulated bar IS the evidence bar, and a second one counted in buckets would silently override it.'
         windowHours:
           default: 24
           description: Lookback window (hours) the metric is aggregated over. 1–720.
           type: integer
           minimum: 1
           maximum: 720
+        bucketMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 43200
+            - type: 'null'
+          description: Width of the buckets the window is split into, in minutes. Omit (or `null`) to divide the window into 12 equal buckets. The rule is judged per bucket, so this is the resolution at which "sustained" is measured — a short bucket asks the condition to hold through finer detail.
+        requiredBuckets:
+          anyOf:
+            - type: integer
+              minimum: 1
+            - type: 'null'
+          description: How many buckets must breach before the rule fires. Omit (or `null`) to require every bucket that had data. Buckets with nothing in them are excluded before this is counted, so on a sparse metric `null` can mean a single bucket — set this to 2 or more where one lone sample must never page.
+        warnThreshold:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: 'The milder bound — a second level, in the same unit the kind judges in, that raises a quieter alert before the firing level is reached. Must be strictly milder than the level the rule fires at, or it could never fire on its own. Refused on a range rule and on a `sustained` one: neither condition is a single number, so there is nothing to substitute.'
+        recoveryThreshold:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: What the metric must get back to before a live alert closes. Without it a metric sitting on its threshold pages and clears once per tick. Must be on the safe side of the firing level, or equal to it. Omit (or `null`) for no hysteresis.
+        groupAlerts:
+          default: false
+          type: boolean
+          description: Fire one alert per `by()` group instead of one for the whole metric. The firing key becomes (rule, group), so each group raises, dedupes and recovers on its own. Refused on a metric with no `by()`, and on `no_data` — a group that went silent has no rows left to be missing from.
+        maxGroups:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 50
+            - type: 'null'
+          description: How many groups this rule may alert on at once. Omit (or `null`) for 10. Past the cap the worst groups fire and the count of the rest is stated on each ticket — a group set is customer data, and an uncapped rule on `by(user_id)` would file a ticket per user.
+        noDataMinutes:
+          anyOf:
+            - type: integer
+              minimum: 5
+              maximum: 43200
+            - type: 'null'
+          description: 'For a `no_data` rule: how long the silence must last. Omit (or `null`) for 15 minutes. Five is the floor — below it, ordinary ingest lag empties the trailing bucket and reads as an outage.'
+        delayMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 1440
+            - type: 'null'
+          description: Hold the evaluated window back this far behind live, on top of the reader's own settle grace. For a metric assembled from a source that lands in batches, whose trailing buckets are legitimately incomplete for longer than the grace covers.
+        autoResolveMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+            - type: 'null'
+          description: Close a live instance that has gone this long without a fresh verdict. A rule that cannot reach a verdict deliberately leaves its alert alone, which is right for a tick and wrong for a week. Never closes an instance that is currently breaching. Omit (or `null`) to never auto-resolve.
+        composite:
+          $ref: '#/components/schemas/AlertCompositeSpec'
         severity:
           default: warn
-          description: Severity of the raised alert.
+          description: Severity of the raised alert. A `warnThreshold` breach opens one step quieter than this.
           type: string
           enum:
             - danger
@@ -16845,12 +18194,10 @@ components:
           description: Whether the rule is evaluated by the cron.
           type: boolean
         notify:
-          $ref: '#/components/schemas/NotificationTarget'
+          $ref: '#/components/schemas/AlertRuleNotify'
       required:
         - name
         - metricId
-        - comparator
-        - threshold
       additionalProperties: false
     CreateAlertRuleResponse:
       type: object
@@ -16877,6 +18224,14 @@ components:
           type: string
           minLength: 1
           maxLength: 120
+        kind:
+          type: string
+          enum:
+            - normal
+            - anomaly
+            - outliers
+            - no_data
+            - composite
         comparator:
           type: string
           enum:
@@ -16886,10 +18241,93 @@ components:
             - lte
         threshold:
           type: number
+        rangeMin:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: Lower edge of the corridor; `null` drops it, returning the rule to comparator and threshold when both bounds are gone.
+        rangeMax:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: Upper edge of the corridor; `null` drops it.
+        sigma:
+          anyOf:
+            - type: number
+              exclusiveMinimum: 0
+            - type: 'null'
+          description: Sigmas an `anomaly` or `outliers` rule fires at; `null` restores the default of 3.
+        direction:
+          anyOf:
+            - type: string
+              enum:
+                - above
+                - below
+                - either
+            - type: 'null'
+          description: Which side an `anomaly` or `outliers` rule watches; `null` restores either.
+        sustained:
+          type: boolean
+          description: Judge the window by accumulated departure rather than bucket by bucket. `anomaly` and `outliers` only; refused alongside `requiredBuckets`.
+        warnThreshold:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: The milder bound; `null` drops the warning level, leaving the rule with one.
+        recoveryThreshold:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: What the metric must get back to before a live alert closes; `null` drops the hysteresis.
+        groupAlerts:
+          type: boolean
+          description: Fire one alert per `by()` group. Refused on a metric with no grouping.
+        maxGroups:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 50
+            - type: 'null'
+          description: How many groups may alert at once; `null` restores the default of 10.
+        noDataMinutes:
+          anyOf:
+            - type: integer
+              minimum: 5
+              maximum: 43200
+            - type: 'null'
+          description: How long a `no_data` rule's silence must last; `null` restores 15 minutes.
+        delayMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 1440
+            - type: 'null'
+          description: How far behind live the window is held; `null` drops the delay.
+        autoResolveMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+            - type: 'null'
+          description: Close a stale live instance after this long; `null` never auto-resolves.
+        composite:
+          $ref: '#/components/schemas/AlertCompositeSpec'
         windowHours:
           type: integer
           minimum: 1
           maximum: 720
+        bucketMinutes:
+          anyOf:
+            - type: integer
+              minimum: 1
+              maximum: 43200
+            - type: 'null'
+          description: Bucket width in minutes; `null` restores the default 12 buckets per window.
+        requiredBuckets:
+          anyOf:
+            - type: integer
+              minimum: 1
+            - type: 'null'
+          description: Buckets that must breach to fire; `null` restores "every bucket that had data".
         severity:
           type: string
           enum:
@@ -16899,7 +18337,7 @@ components:
         enabled:
           type: boolean
         notify:
-          $ref: '#/components/schemas/NotificationTarget'
+          $ref: '#/components/schemas/AlertRuleNotify'
       additionalProperties: false
     UpdateAlertRuleResponse:
       type: object
@@ -16913,13 +18351,15 @@ components:
     AlertApiRow:
       type: object
       description: |-
-        One FIRED alert — a condition the platform observed and raised, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Alerts are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) raise them, keyed by `(source, dedupeKey)` so re-raising refreshes the active row and a clearing condition auto-resolves it.
+        One FIRED alert — an INSTANCE of a condition the platform observed, not the rule that defines it (alert *rules* are the `/api/admin/alert-rules` resource). Instances are never filed by hand: the UI (killswitch flips) and the worker (analysis consumer + alerts cron) open them, keyed by `(source, dedupeKey)`, and at most one instance per condition is open at a time — re-raising refreshes the open one, and the condition clearing closes it.
+
+        An instance IS an ops queue item (`/api/admin/ops` with `type: "alert"`) seen through the alert lens: same `id`, `severity` is that item's `priority`, and `status` is its work status projected onto three states. Resolving the queue item and clearing the alert are therefore the same act.
 
         Every field is always present on the wire; nullable fields are `null`, never absent.
       properties:
         id:
           type: string
-          description: Stable opaque alert id.
+          description: Stable opaque instance id — also the id of the ops queue item this instance is.
         source:
           type: string
           enum:
@@ -16940,10 +18380,10 @@ components:
             - danger
             - warn
             - info
-          description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only.
+          description: How loud the alert is — `danger` pages, `warn` is the default, `info` is FYI-only. Severity belongs to the RULE and seeds the instance's queue `priority` (`danger`→`critical`, `warn`→`high`, `info`→`medium`); it is read back from there, so re-prioritising the queue item changes what this reports.
         dedupeKey:
           type: string
-          description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the existing active row instead of stacking duplicates, and the condition clearing flips that row to `resolved`.
+          description: Idempotency + reconcile key within `(project, source)` — re-raising the same condition refreshes the open instance instead of stacking duplicates, and the condition clearing closes it. A later firing of the same condition opens a NEW instance with its own `id`.
         title:
           type: string
           description: Short human-readable headline (what fired).
@@ -16966,10 +18406,10 @@ components:
             - active
             - resolved
             - dismissed
-          description: Lifecycle state. `active` means the condition currently holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off.
+          description: Lifecycle state, projected from the queue item's work status. `active` means the item is still open, i.e. the condition holds (shown as "Firing" in the UI); `resolved` means it cleared (auto, when the raiser reconciles, or by hand); `dismissed` means a human waved it off (the item is closed `wont_fix`).
         createdAt:
           type: string
-          description: ISO-8601 timestamp the alert was first raised.
+          description: ISO-8601 timestamp this instance opened — when the condition started firing.
         resolvedAt:
           description: ISO-8601 timestamp the alert flipped to `resolved`, or `null` while it hasn't.
           anyOf:
@@ -17031,7 +18471,7 @@ components:
             - active
             - resolved
             - dismissed
-          description: New lifecycle state. `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
+          description: New lifecycle state, written through to the queue item (`resolved` / `wont_fix` / `open`). `resolved` / `dismissed` stamp their timestamp; `active` re-opens and clears both.
         assigneeId:
           description: PERSON owner — a `users.id`, or `null` to clear the assignment.
           anyOf:
@@ -17217,6 +18657,12 @@ components:
             - type: boolean
             - type: number
           description: Whether key-authenticated public ticket creation (`POST /cli/report`) is allowed into this project. Off by default.
+        errorAutocloseDays:
+          type: integer
+          description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project. Ingest reopens a resolved error the moment it recurs, so this never hides a live issue.
+        errorTicketMinOccurrences:
+          type: integer
+          description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Customising it requires a paid plan; unentitled projects always run at the platform default of 10.
         stripeSubscriptionId:
           anyOf:
             - type: string
@@ -17296,6 +18742,8 @@ components:
         - moduleUser
         - moduleEvents
         - allowPublicTickets
+        - errorAutocloseDays
+        - errorTicketMinOccurrences
         - slug
         - logo
         - defaultEnv
@@ -17514,6 +18962,16 @@ components:
           minimum: 0.0001
           maximum: 0.05
           description: SRM chi-square p-value below which the run is called invalid.
+        errorAutocloseDays:
+          type: integer
+          minimum: 0
+          maximum: 365
+          description: Days an `open` tracked error may go unseen before the nightly sweep auto-resolves it. `0` disables auto-close for this project.
+        errorTicketMinOccurrences:
+          type: integer
+          minimum: 1
+          maximum: 10000
+          description: Occurrence count a tracked error must cross before an `error` ticket is auto-filed into the ops queue. Requires a paid plan — the request is rejected with 403 on a plan without the `ops_auto_error_issues` entitlement.
       additionalProperties: false
       description: Body for `PATCH /api/admin/projects/{id}`. Partial — every field is optional; only supplied fields change. The project id in the path must match the caller's own project.
     ListI18nProfilesResponse:
@@ -18582,21 +20040,50 @@ components:
         - config
       additionalProperties: false
       description: Create a Claude Code routine trigger in one shot. Idempotent by `config.routineId` — re-creating with the same routine id updates the existing row.
+    CursorTriggerRepo:
+      type: object
+      properties:
+        url:
+          type: string
+          format: uri
+          description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`.
+        startingRef:
+          type: string
+          minLength: 1
+          description: Optional branch this repo's runs start from. Omit for the repo's default branch.
+      required:
+        - url
+      additionalProperties: false
+      description: One repo a trigger runs against, with the branch its runs start from.
     CursorTriggerConfig:
       type: object
       properties:
         repoUrl:
           type: string
           format: uri
-          description: Repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector.
+          description: '**First** repo the cloud agent runs against, e.g. `https://github.com/owner/repo`. Idempotency key for the connector, and always a mirror of `repos[0].url` when `repos` is supplied.'
         startingRef:
           type: string
           minLength: 1
-          description: Optional git ref the run starts from.
+          description: Optional git ref the run starts from. Mirrors `repos[0].startingRef`. Pinned onto the Cursor agent at creation, so changing it provisions a replacement agent.
+        repos:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/CursorTriggerRepo'
+          description: Every repo this trigger runs against, each with its own starting branch — Cursor launches ONE agent across the whole set. Omit for a single-repo trigger, which is then described by `repoUrl`/`startingRef` alone; when supplied, the first entry must match them. Changing the set re-provisions the agent (its repos are pinned at creation).
         projectId:
           type: string
           minLength: 1
           description: Shipeasy project id the run targets.
+        agentId:
+          type: string
+          minLength: 1
+          description: Server-managed. The reusable Cursor cloud agent (`bc-…`) Shipeasy provisions once at connect and then starts every run on. A supplied value is ignored on create; if Cursor stops recognising the id (404), the next fire provisions a replacement and stores it here.
+        fireText:
+          type: string
+          minLength: 1
+          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
       required:
         - repoUrl
         - projectId
@@ -18631,7 +20118,7 @@ components:
         opsKey:
           type: string
           minLength: 1
-          description: Restricted Shipeasy ops key, injected into the run as `SHIPEASY_CLI_TOKEN` via the launch envVars (secret). Encrypted; never returned.
+          description: Restricted Shipeasy ops key (secret). Sent as the Bearer for the Shipeasy MCP server handed to each run inline — never in the prompt text or the run env. Encrypted; never returned.
         enabled:
           type: boolean
           default: true
@@ -18643,13 +20130,33 @@ components:
         - opsKey
       additionalProperties: false
       description: Create a Cursor cloud-agent trigger. Both keys are required up front (never tokenless). Idempotent by `config.repoUrl`.
+    CopilotTriggerRepo:
+      type: object
+      properties:
+        owner:
+          type: string
+          minLength: 1
+          description: GitHub repo owner.
+        repo:
+          type: string
+          minLength: 1
+          description: GitHub repo name.
+        baseRef:
+          type: string
+          minLength: 1
+          description: Optional base ref this repo's agent task branches from. Omit for the repo's default branch.
+      required:
+        - owner
+        - repo
+      additionalProperties: false
+      description: One repo a Copilot trigger runs against, with the base branch its tasks branch from.
     CopilotTriggerConfig:
       type: object
       properties:
         owner:
           type: string
           minLength: 1
-          description: GitHub repo owner. Together with `repo` forms the connector's idempotency key (`owner/repo`).
+          description: '**First** GitHub repo owner. Together with `repo` forms the connector''s idempotency key (`owner/repo`), and both mirror `repos[0]` when `repos` is supplied.'
         repo:
           type: string
           minLength: 1
@@ -18657,11 +20164,21 @@ components:
         baseRef:
           type: string
           minLength: 1
-          description: Optional base ref the agent branches from.
+          description: Optional base ref the agent branches from. Mirrors `repos[0].baseRef`.
+        repos:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/CopilotTriggerRepo'
+          description: Every repo this trigger runs against, each with its own base branch. GitHub's agent-tasks API is per-repo, so ONE fire starts one task per entry. Omit for a single-repo trigger, which is then described by `owner`/`repo`/`baseRef` alone; when supplied, the first entry must match them.
         projectId:
           type: string
           minLength: 1
           description: Shipeasy project id the run targets.
+        fireText:
+          type: string
+          minLength: 1
+          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
       required:
         - owner
         - repo
@@ -18719,6 +20236,10 @@ components:
           type: string
           minLength: 1
           description: Shipeasy project id the run targets.
+        fireText:
+          type: string
+          minLength: 1
+          description: Optional standing instruction prepended to every run's prompt — the trigger's base prompt. Lets two triggers on different repos steer their runs differently without changing the `/shipeasy-ops-work` task block.
       required:
         - source
         - projectId
@@ -18918,7 +20439,7 @@ components:
         - provider
         - config
       additionalProperties: false
-      description: Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale; `name` and either credential are optional (a supplied credential rotates just that key).
+      description: 'Per-provider PATCH body for editing an existing `cursor_trigger` connector. `config` replaces the stored config wholesale, except for the server-managed keys: the provisioned `agentId` is carried over (and dropped, so a replacement agent is provisioned, when `repoUrl`/`startingRef` change), as is the last-run pointer. `name` and either credential are optional (a supplied credential rotates just that key).'
     UpdateCopilotTriggerRequest:
       type: object
       properties:
@@ -19044,6 +20565,11 @@ components:
             - type: string
             - type: 'null'
           description: Human label for the key. `null` for unnamed dashboard mints; programmatic mints auto-name themselves.
+        description:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Free-text note recording what the key is for (the service that holds it, the rotation owner, the ticket it was minted under). Display only — `null` unless someone set it via `PATCH /api/admin/keys/{id}`.
         scopes:
           anyOf:
             - type: array
@@ -19056,6 +20582,14 @@ components:
             - type: string
             - type: 'null'
           description: Last 4 characters of the raw token, so the dashboard mask is matchable against the held key. `null` for keys minted before this column.
+        origin:
+          type: string
+          enum:
+            - cli
+            - mobile
+            - dashboard
+            - api
+          description: Where the key was minted. `cli` (a signed-in CLI session from device auth), `mobile` (a mobile app login), `dashboard` (the "New API key" dialog) or `api` (minted with another key — CLI, MCP, agents). Set at mint time; keys that predate the column were backfilled from their label, defaulting to `dashboard`.
       required:
         - id
         - type
@@ -19065,8 +20599,10 @@ components:
         - expires_at
         - created_by_email
         - name
+        - description
         - scopes
         - last4
+        - origin
       additionalProperties: false
     ListKeysResponse:
       type: object
@@ -19172,6 +20708,30 @@ components:
         - key
         - expires_at
       additionalProperties: false
+    UpdateKeyRequest:
+      type: object
+      description: |-
+        Body for `PATCH /api/admin/keys/{id}`. Only the key's **label** is editable — `name` and `description`.
+
+        Everything that gives a key its authority (`type`, `env`, `scopes`, `expires_at`) is fixed at mint: those are the isolation boundary the worker derives the read env and permissions from, so changing them would silently re-point a credential that is already deployed. Rotate instead — mint a replacement and revoke the old key.
+
+        Omitted fields are left untouched; send `null` to clear one.
+      properties:
+        name:
+          anyOf:
+            - type: string
+              minLength: 1
+              maxLength: 160
+            - type: 'null'
+          description: New human label, or `null` to clear it. Same 160-char budget as create — provenance labels are composed, not typed.
+        description:
+          anyOf:
+            - type: string
+              minLength: 1
+              maxLength: 500
+            - type: 'null'
+          description: New free-text note, or `null` to clear it.
+      additionalProperties: false
     RevokeKeyResponse:
       type: object
       description: Confirms the key is revoked. Idempotent — revoking an already-revoked key returns the same shape.
@@ -19199,6 +20759,7 @@ components:
             - config
             - killswitch
             - metric
+            - ops
           description: Resource family — drives the result group + icon in the palette. (`member` hits are surfaced first.)
         id:
           type: string
@@ -19232,6 +20793,85 @@ components:
       required:
         - hits
       additionalProperties: false
+    Tag:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Stable opaque tag id.
+        name:
+          type: string
+          description: Display name — also the tag's identity, unique case-insensitively within the project.
+      required:
+        - id
+        - name
+      additionalProperties: false
+    ListTagsResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/Tag'
+      description: The project's tags, sorted by name.
+    TaggableEntityType:
+      type: string
+      enum:
+        - ops
+        - flag
+        - config
+        - killswitch
+        - metric
+        - error
+        - alert_rule
+        - experiment
+      description: 'The kind of item a tag set hangs off: `ops` (any queue item — bug, feature request, error/alert/measure-plan ticket), `flag` (feature gate), `config` (dynamic config), `killswitch`, `metric`, `error` (tracked error group), `alert_rule`, or `experiment`.'
+    EntityTagsResponse:
+      type: object
+      properties:
+        entityType:
+          $ref: '#/components/schemas/TaggableEntityType'
+        entityId:
+          type: string
+          description: The item's canonical id (the handle you passed, resolved).
+        tags:
+          type: array
+          items:
+            type: string
+          description: The tag names now attached to the item, sorted by name.
+      required:
+        - entityType
+        - entityId
+        - tags
+      additionalProperties: false
+    SetEntityTagsRequest:
+      type: object
+      properties:
+        tags:
+          type: array
+          maxItems: 50
+          items:
+            $ref: '#/components/schemas/TagName'
+          description: The complete tag set the item should carry — tags not listed are detached. Names are get-or-created (a new name mints a project tag), deduped case-insensitively; `[]` clears every tag.
+      required:
+        - tags
+      additionalProperties: false
+    UpdateEntityTagsRequest:
+      type: object
+      properties:
+        add:
+          type: array
+          maxItems: 50
+          items:
+            $ref: '#/components/schemas/TagName'
+          default: []
+          description: Tag names to attach (get-or-created by name, case-insensitive). Already-attached names are a no-op.
+        remove:
+          type: array
+          maxItems: 50
+          items:
+            $ref: '#/components/schemas/TagName'
+          default: []
+          description: Tag names to detach (case-insensitive). Names the item doesn't carry are a no-op. A name in both lists is removed.
+      additionalProperties: false
+      description: Incremental tag edit — pass `add`, `remove`, or both. Every other tag on the item is left as is.
   responses:
     BadRequest:
       description: The request was malformed (bad JSON or missing project scope).