@shipeasy/openapi 3.2.0 → 3.3.0

package/openapi.yaml

@@ -216,6 +216,24 @@ 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: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -258,6 +276,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 +4592,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 +4634,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 +4648,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 +4671,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 +4758,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 +5471,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 +5485,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 +5495,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 +5604,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 +5702,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 +5783,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 +6102,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 +6228,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,6 +6373,275 @@ paths:
         positional:
           - handle
           - investigationId
+  /api/admin/ops/{handle}/questions:
+    get:
+      operationId: listOpsQuestions
+      summary: List an item's questions
+      description: |-
+        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:
+        - 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 an item's questions
+          content:
+            application/json:
+              schema:
+                $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
+        positional:
+          - handle
+    post:
+      operationId: askOpsQuestions
+      summary: Ask the team questions about an item
+      description: |-
+        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:
+        - 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'
+      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: The created questions, in the order asked
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AskOpsQuestionsResponse'
+        '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: ask
+        positional:
+          - handle
+  /api/admin/ops/{handle}/questions/{questionId}/answer:
+    post:
+      operationId: answerOpsQuestion
+      summary: Answer a question
+      description: |-
+        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:
+        - 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: 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/AnswerOpsQuestionRequest'
+            examples:
+              option:
+                summary: Pick an option
+                value:
+                  selected:
+                    - Keep it
+              other:
+                summary: Answer in free text
+                value:
+                  other: Keep it for a release, then drop it
+      responses:
+        '200':
+          description: The answered question
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpsQuestion'
+        '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
+        - NOT_FOUND
+        - INVALID_TRANSITION
+        - VALIDATION
+      x-cli:
+        name: answer
+        positional:
+          - handle
+          - questionId
+  /api/admin/ops/{handle}/questions/{questionId}/cancel:
+    post:
+      operationId: cancelOpsQuestion
+      summary: Withdraw a question
+      description: |-
+        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:** You asked, then answered it yourself from the code — take
+        it off the person's plate.
+      tags:
+        - 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: questionId
+          in: path
+          required: true
+          description: The question id (from `ask` or `list`).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: The withdrawn question
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpsQuestion'
+        '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'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - INVALID_TRANSITION
+      x-cli:
+        name: cancel
+        positional:
+          - handle
+          - questionId
   /api/admin/agent-profiles:
     get:
       operationId: listOpsAgents
@@ -6790,7 +7155,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 +7241,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 +7258,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 +7732,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 +9774,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
@@ -9505,16 +9874,16 @@ paths:
         - PLAN_LIMIT
       x-cli:
         name: create
-  /api/admin/keys/{id}/revoke:
-    post:
-      operationId: revokeKey
-      summary: Revoke an API key
+  /api/admin/keys/{id}:
+    patch:
+      operationId: updateKey
+      summary: Update an API key's label
       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.
+        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.
 
-        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.
+        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:** Rotate a leaked or stale credential — mint the replacement, then revoke the old key.
+        **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:
@@ -9525,16 +9894,43 @@ paths:
           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: Revoke an API key
+          description: Update an API key's label
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/RevokeKeyResponse'
+                $ref: '#/components/schemas/KeyRecord'
               example:
                 id: 3f2a9b1c-7d4e-4a8f-9c2b-1e5d6f7a8b90
-                revoked: true
+                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':
@@ -9551,18 +9947,69 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+        - VALIDATION
       x-cli:
-        name: revoke
+        name: update
         positional:
           - id
-  /api/admin/search:
-    get:
-      operationId: searchResources
-      summary: Search project resources
+  /api/admin/keys/{id}/revoke:
+    post:
+      operationId: revokeKey
+      summary: Revoke an API key
       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.
+        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.
 
-        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.
+        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:
@@ -9617,6 +10064,276 @@ paths:
         - 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/EntityTagsResponse'
+              example:
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - 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
+        - NOT_FOUND
+      x-cli:
+        name: get
+        positional:
+          - entityType
+          - entityId
+    put:
+      operationId: setEntityTags
+      summary: Replace an item's tags
+      description: |-
+        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`).
+
+        **Use cases**
+
+        - **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:
+        - 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'
+      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: Replace an item's tags
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityTagsResponse'
+              example:
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - 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
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: set
+        positional:
+          - entityType
+          - entityId
+    patch:
+      operationId: updateEntityTags
+      summary: Add or remove tags on an item
+      description: |-
+        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.
+
+        **Use cases**
+
+        - **Add a tag** — `{ "add": ["regression"] }`.
+        - **Swap a tag** — `{ "add": ["p1"], "remove": ["p2"] }`.
+      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'
+      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: Add or remove tags on an item
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EntityTagsResponse'
+              example:
+                entityType: ops
+                entityId: fb_01j7w8a1b2c3d4e5f6g7h8i9j0
+                tags:
+                  - checkout
+                  - 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
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: update
+        positional:
+          - entityType
+          - entityId
 components:
   securitySchemes:
     bearerSdkKey:
@@ -11134,13 +11851,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
@@ -13557,253 +14271,60 @@ components:
         - 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: Typed query IR — the structured alternative to the `query` DSL string. Exactly one of `query` / `query_ir` is supplied per metric body.
+      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:
-        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.
+        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 +14333,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 +14453,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 +14498,8 @@ components:
       properties:
         name:
           $ref: '#/components/schemas/MetricName'
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -13983,6 +14514,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - name
         - event_name
@@ -13994,6 +14527,8 @@ components:
       properties:
         name:
           $ref: '#/components/schemas/MetricName'
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14008,6 +14543,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - name
         - event_name
@@ -14133,6 +14670,8 @@ components:
     UpdateMetricWithQuery:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14147,6 +14686,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - query
       additionalProperties: false
@@ -14154,6 +14695,8 @@ components:
     UpdateMetricWithQueryIr:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14168,6 +14711,8 @@ components:
           $ref: '#/components/schemas/MetricDirection'
         unit:
           $ref: '#/components/schemas/MetricDisplayUnit'
+        display:
+          $ref: '#/components/schemas/MetricDisplayConfig'
       required:
         - query_ir
       additionalProperties: false
@@ -14175,6 +14720,8 @@ components:
     UpdateMetricFields:
       type: object
       properties:
+        display_name:
+          $ref: '#/components/schemas/MetricDisplayName'
         folder:
           $ref: '#/components/schemas/Folder'
         event_name:
@@ -14187,8 +14734,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 +14836,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 +14887,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 +14904,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 +14936,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 +14954,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 +15027,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 +15044,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 +15098,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 +15150,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 +15209,7 @@ components:
       enum:
         - pr_ready
         - pr_merged
+        - pr_closed
         - investigated
         - detected
         - question
@@ -14648,7 +15217,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 +15377,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 +15420,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 +15444,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 +15549,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 +15557,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 +15570,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 +15594,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 +15985,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 +16042,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 +16134,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 +16245,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 +16280,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 +16292,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 +16305,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 +16354,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 +16383,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 +16395,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 +16739,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:
@@ -16542,91 +17164,338 @@ components:
       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.
-    OpsAgentProfile:
+    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:
-        connectorId:
-          type: string
-          description: The connector row id — what an agent assignment stores.
-        provider:
-          type: string
-          enum:
-            - claude_trigger
-            - cursor_trigger
-            - copilot_trigger
-            - jules_trigger
-          description: The trigger-connector provider backing this agent.
-        name:
-          type: string
-          description: Display name — the connector's `name`, or the provider default (e.g. "Claude").
-        handle:
-          type: string
-          description: Mention/search handle — the kebab-cased name (e.g. `claude`).
+        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:
-        - connectorId
-        - provider
-        - name
-        - handle
+        - selected
+        - other
       additionalProperties: false
-      description: One connected, assignable AI agent (an authenticated trigger connector).
-    ListOpsAgentsResponse:
-      type: array
-      items:
-        $ref: '#/components/schemas/OpsAgentProfile'
-      description: The project's connected AI agents — the agent types `POST /api/admin/ops/{handle}/ack` accepts. Empty when no trigger connector is connected yet.
-    OpsCommentAuthorType:
+      description: A person's answer to a question.
+    OpsQuestionDelivery:
       type: string
       enum:
-        - user
-        - system
-      description: Who wrote a comment. `user` is a teammate (their email is in `authorEmail`); `system` is Jarvis — the AI agent — which authors comments when an ops-notify escalation lands on the item and when it is `@shipeasy`-mentioned in a thread.
-    OpsComment:
+        - 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: Comment id.
+          description: Question id.
         feedbackId:
           type: string
-          description: The queue item this comment hangs off.
-        parentId:
+          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: The top-level comment this is a reply to, or `null` for a top-level comment.
-        authorType:
-          $ref: '#/components/schemas/OpsCommentAuthorType'
-        authorEmail:
+          description: Email of the person who answered, or `null`.
+        answeredAt:
           anyOf:
             - type: string
             - type: 'null'
-          description: The teammate who wrote it, or `null` for a `system` (Jarvis) comment.
-        body:
-          type: string
-          description: Comment body as markdown (may contain sanitised inline image/video embeds).
+          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-edit timestamp.
+          description: ISO-8601 last-update timestamp.
       required:
         - id
         - feedbackId
-        - parentId
-        - authorType
-        - authorEmail
-        - body
+        - header
+        - question
+        - options
+        - multiSelect
+        - status
+        - answer
+        - answeredBy
+        - answeredAt
+        - agent
+        - askedBy
+        - runId
+        - delivery
+        - deliveredAt
+        - deliveryError
         - createdAt
         - updatedAt
       additionalProperties: false
-      description: A single comment on a queue item.
-    ListOpsCommentsResponse:
+      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:
-        comments:
-          type: array
-          items:
+        label:
+          type: string
+          minLength: 1
+          maxLength: 120
+          description: The option's display text — short (1–5 words). Answers name options by this label.
+        description:
+          type: string
+          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
+          minLength: 1
+          maxLength: 24
+          description: Very short chip label for the question (max 24 chars), e.g. `Auth method`.
+        question:
+          type: string
+          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 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
+          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: 4
+          items:
+            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
+          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).
+    OpsAgentProfile:
+      type: object
+      properties:
+        connectorId:
+          type: string
+          description: The connector row id — what an agent assignment stores.
+        provider:
+          type: string
+          enum:
+            - claude_trigger
+            - cursor_trigger
+            - copilot_trigger
+            - jules_trigger
+          description: The trigger-connector provider backing this agent.
+        name:
+          type: string
+          description: Display name — the connector's `name`, or the provider default (e.g. "Claude").
+        handle:
+          type: string
+          description: Mention/search handle — the kebab-cased name (e.g. `claude`).
+      required:
+        - connectorId
+        - provider
+        - name
+        - handle
+      additionalProperties: false
+      description: One connected, assignable AI agent (an authenticated trigger connector).
+    ListOpsAgentsResponse:
+      type: array
+      items:
+        $ref: '#/components/schemas/OpsAgentProfile'
+      description: The project's connected AI agents — the agent types `POST /api/admin/ops/{handle}/ack` accepts. Empty when no trigger connector is connected yet.
+    OpsCommentAuthorType:
+      type: string
+      enum:
+        - user
+        - system
+      description: Who wrote a comment. `user` is a teammate (their email is in `authorEmail`); `system` is Jarvis — the AI agent — which authors comments when an ops-notify escalation lands on the item and when it is `@shipeasy`-mentioned in a thread.
+    OpsComment:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Comment id.
+        feedbackId:
+          type: string
+          description: The queue item this comment hangs off.
+        parentId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The top-level comment this is a reply to, or `null` for a top-level comment.
+        authorType:
+          $ref: '#/components/schemas/OpsCommentAuthorType'
+        authorEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The teammate who wrote it, or `null` for a `system` (Jarvis) comment.
+        body:
+          type: string
+          description: Comment body as markdown (may contain sanitised inline image/video embeds).
+        createdAt:
+          type: string
+          description: ISO-8601 creation timestamp.
+        updatedAt:
+          type: string
+          description: ISO-8601 last-edit timestamp.
+      required:
+        - id
+        - feedbackId
+        - parentId
+        - authorType
+        - authorEmail
+        - body
+        - createdAt
+        - updatedAt
+      additionalProperties: false
+      description: A single comment on a queue item.
+    ListOpsCommentsResponse:
+      type: object
+      properties:
+        comments:
+          type: array
+          items:
             $ref: '#/components/schemas/OpsComment'
       required:
         - comments
@@ -16735,6 +17604,27 @@ 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
     ListAlertRulesResponse:
       type: array
       items:
@@ -16754,6 +17644,15 @@ components:
               - type: string
               - type: 'null'
             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:
@@ -16761,15 +17660,90 @@ components:
               - gte
               - lt
               - lte
-            description: How the metric value is compared to the threshold (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.
+            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:
@@ -16793,9 +17767,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 +17805,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
@@ -16849,8 +17935,6 @@ components:
       required:
         - name
         - metricId
-        - comparator
-        - threshold
       additionalProperties: false
     CreateAlertRuleResponse:
       type: object
@@ -16877,6 +17961,14 @@ components:
           type: string
           minLength: 1
           maxLength: 120
+        kind:
+          type: string
+          enum:
+            - normal
+            - anomaly
+            - outliers
+            - no_data
+            - composite
         comparator:
           type: string
           enum:
@@ -16886,10 +17978,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:
@@ -16913,13 +18088,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 +18117,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 +18143,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 +18208,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 +18394,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 +18479,8 @@ components:
         - moduleUser
         - moduleEvents
         - allowPublicTickets
+        - errorAutocloseDays
+        - errorTicketMinOccurrences
         - slug
         - logo
         - defaultEnv
@@ -17514,6 +18699,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 +19777,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 +19855,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 +19867,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 +19901,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 +19973,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 +20176,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 +20302,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
@@ -19065,6 +20328,7 @@ components:
         - expires_at
         - created_by_email
         - name
+        - description
         - scopes
         - last4
       additionalProperties: false
@@ -19172,6 +20436,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.
@@ -19232,6 +20520,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).