@shipeasy/openapi 1.5.0 → 2.1.0

package/spec/components/schemas/ops.yaml

@@ -0,0 +1,1011 @@
+ListOpsItemsResponse:
+  type: array
+  items:
+    type: object
+    properties:
+      id:
+        type: string
+        description: Stable opaque item id.
+      number:
+        anyOf:
+          - type: number
+          - type: "null"
+        description: Per-project item number (the `#7` handle), or `null` if unnumbered.
+      type:
+        type: string
+        enum:
+          - bug
+          - feature_request
+          - error
+          - alert
+          - 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 (a tracked production error, a metric-threshold alert, and an assistant-proposed measurement plan respectively)."
+      title:
+        type: string
+        description: One-line item title.
+      status:
+        $ref: "#/OpsItemStatus"
+      priority:
+        anyOf:
+          - $ref: "#/OpsItemPriority"
+          - type: "null"
+        description: Triage priority, or `null` if not yet set.
+      sourceRef:
+        description: Source reference for auto-filed tickets (e.g. an error fingerprint).
+        anyOf:
+          - type: string
+          - type: "null"
+      createdAt:
+        type: string
+        description: ISO-8601 creation timestamp.
+    required:
+      - id
+      - number
+      - type
+      - title
+      - status
+      - priority
+      - createdAt
+    additionalProperties: {}
+    description: One queue item — any type.
+  description: A page of queue items, newest first.
+GetOpsItemResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Stable opaque item id.
+    number:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: Per-project item number (the `#7` handle), or `null` if unnumbered.
+    type:
+      type: string
+      enum:
+        - bug
+        - feature_request
+        - error
+        - alert
+        - 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 (a tracked production error, a metric-threshold alert, and an assistant-proposed measurement plan respectively)."
+    title:
+      type: string
+      description: One-line item title (all types).
+    status:
+      $ref: "#/OpsItemStatus"
+    priority:
+      anyOf:
+        - $ref: "#/OpsItemPriority"
+        - type: "null"
+      description: Triage priority, or `null` if not yet set (all types).
+    source:
+      type: string
+      enum:
+        - team
+        - system
+      description: "How the item was filed: `team` (a human admin/teammate — bug/feature) or `system` (auto-filed — error/alert/measure_plan)."
+    sourceRef:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Stable key of the originating record for auto-filed tickets (error fingerprint, `<alert source>:<dedupeKey>`, or measurement-plan ref); `null` for human-filed bugs/features."
+    reporterEmail:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Reporter email (bug/feature), or `null`.
+    stepsToReproduce:
+      type: string
+      description: Reproduction steps — populated for `bug`, empty string otherwise.
+    actualResult:
+      type: string
+      description: What actually happened — `bug` only, empty string otherwise.
+    expectedResult:
+      type: string
+      description: What was expected — `bug` only, empty string otherwise.
+    description:
+      type: string
+      description: Feature description — populated for `feature_request`, empty string otherwise.
+    useCase:
+      type: string
+      description: Feature use case — `feature_request` only, empty string otherwise.
+    context:
+      anyOf:
+        - $ref: "#/OpsItemContext"
+        - type: "null"
+      description: "Type-specific capture context. For `bug`/`feature_request` it carries `browser` (the auto-collected page URL / user-agent / viewport). For auto-filed tickets it carries the hydrated `error`, `alert`, or `measurePlan` block. `null` only for legacy rows with nothing captured."
+    attachments:
+      type: array
+      items:
+        $ref: "#/OpsItemAttachment"
+      description: "Files attached to the report — screenshots, recordings, logs. Populated for `bug`/`feature_request`; always an empty array for auto-filed `error`/`alert`/`measure_plan` tickets. Fetch each via its `fetchUrl` with the same admin/ops key (the download route is ops-key allow-listed)."
+    related:
+      $ref: "#/OpsItemRelated"
+    connectorData:
+      anyOf:
+        - $ref: "#/ConnectorData"
+        - type: "null"
+      description: "Per-connector linkage recorded for this item, keyed by connector provider. Populated as connectors act on the item (e.g. GitHub opens an issue, Slack posts a message); more than one provider can be present at once. `null` if no connector has touched the item."
+    notify:
+      anyOf:
+        - $ref: ./common.yaml#/NotificationTarget
+        - type: "null"
+      description: Per-item completion-notification target, or `null` (falls back to the project default).
+    createdAt:
+      type: string
+      description: ISO-8601 creation timestamp.
+    updatedAt:
+      type: string
+      description: ISO-8601 last-update timestamp.
+  required:
+    - id
+    - number
+    - type
+    - title
+    - status
+    - priority
+    - context
+    - attachments
+    - related
+    - createdAt
+  additionalProperties: {}
+  description: "One queue item, any of the five types. Shared fields apply to all; `stepsToReproduce`/`actualResult`/`expectedResult` are bug-specific, `description`/`useCase` feature-specific. The auto-collected browser fields (page URL, user-agent, viewport) live under `context.browser` for bug/feature. `context` also carries the hydrated per-type payload for auto-filed `error`/`alert`/`measure_plan` tickets, `attachments` lists any uploaded files, and `related` gives deep links to the underlying resources."
+OpsItemContext:
+  type: object
+  properties:
+    browser:
+      $ref: "#/OpsBrowserContext"
+    error:
+      $ref: "#/OpsErrorContext"
+    alert:
+      $ref: "#/OpsAlertContext"
+    measurePlan:
+      $ref: "#/OpsMeasurePlanContext"
+  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."
+OpsBrowserContext:
+  type: object
+  properties:
+    pageUrl:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: URL of the page the report was filed from, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    viewport:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Reporter's viewport (e.g. `1280x720`), or `null`."
+  additionalProperties: {}
+  description: "Auto-collected browser environment for a `bug`/`feature_request`, captured at file time."
+OpsErrorContext:
+  type: object
+  properties:
+    id:
+      type: string
+      description: The tracked `errors` row id (fetch full detail via `related.error`).
+    fingerprint:
+      type: string
+      description: Stable dedupe key of the tracked error.
+    causedByFingerprint:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Fingerprint of the upstream issue this error descends from (set when the same error was reported at an inner boundary first), or `null` for a root issue."
+    errorType:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Error class/name, e.g. `TypeError`, or `null` when the source didn't supply one."
+    message:
+      type: string
+      description: The error message.
+    subject:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The `see()` consequence subject — the `causes_the(<subject>)` value. Grep the codebase for this to find the throw site. `null` if the error was never instrumented."
+    outcome:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "The `see()` consequence outcome — the `.to(<outcome>)` value. `null` if uninstrumented."
+    kind:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "`see()` error kind: `caught` | `uncaught` | `unhandled_rejection` | `network` | `violation`."
+    side:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "Which SDK side reported it: `client` | `server`."
+    env:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Published env the reporting SDK ran against (dev/staging/prod).
+    count:
+      type: number
+      description: Folded occurrence count for this fingerprint.
+    firstSeenAt:
+      type: string
+      description: ISO-8601 timestamp of the first occurrence.
+    lastSeenAt:
+      type: string
+      description: ISO-8601 timestamp of the most recent occurrence.
+    seenUrls:
+      type: array
+      items:
+        type: string
+      description: "Distinct, id-normalized routes this error has surfaced on (UUIDs/ids collapsed to `#`)."
+    sdkVersion:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "@shipeasy/sdk version of the latest occurrence, or `null`."
+  required:
+    - id
+    - fingerprint
+    - message
+    - count
+    - firstSeenAt
+    - lastSeenAt
+    - seenUrls
+  additionalProperties: {}
+  description: "Hydrated detail for an auto-filed `error` ticket, read from the tracked `errors` row at request time (so `count`/`lastSeenAt` reflect the latest state)."
+OpsAlertContext:
+  type: object
+  properties:
+    source:
+      type: string
+      enum:
+        - metric_rule
+        - experiment_srm
+        - experiment_peek
+        - guardrail
+      description: What kind of alert transitioned to active.
+    dedupeKey:
+      type: string
+      description: Stable per-condition key; with `source` forms the ticket's `sourceRef`.
+    severity:
+      type: string
+      enum:
+        - danger
+        - warn
+        - info
+      description: Alert severity.
+    observedValue:
+      anyOf:
+        - type: number
+        - type: "null"
+      description: The metric value that tripped the rule, or `null`.
+    href:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Dashboard deep link to the alert, or `null`.
+    status:
+      anyOf:
+        - type: string
+          enum:
+            - active
+            - resolved
+            - dismissed
+        - type: "null"
+      description: "Current status of the underlying alert (`active` while the condition holds), or `null` if the alert row is gone."
+    activeSince:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the alert became active, or `null`.
+    resolvedAt:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: ISO-8601 timestamp the alert cleared, or `null` while still active.
+    rule:
+      anyOf:
+        - $ref: "#/OpsAlertRuleSummary"
+        - type: "null"
+      description: "The alert rule condition that tripped (metric-rule alerts only); `null` for SRM/peek/guardrail alerts with no rule."
+    metric:
+      anyOf:
+        - $ref: "#/OpsAlertMetricSummary"
+        - type: "null"
+      description: "The metric the alert watches, hydrated with its backing event(s); `null` if not resolvable."
+  required:
+    - source
+    - dedupeKey
+    - severity
+  additionalProperties: {}
+  description: "Hydrated detail for an auto-filed `alert` ticket, resolving the rule → metric → event chain at request time."
+OpsAlertRuleSummary:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Alert-rule id.
+    name:
+      type: string
+      description: Alert-rule name.
+    comparator:
+      type: string
+      enum:
+        - gt
+        - gte
+        - lt
+        - lte
+      description: How `observedValue` is compared to `threshold`.
+    threshold:
+      type: number
+      description: The threshold value the rule fires on.
+    windowHours:
+      type: number
+      description: Rolling evaluation window in hours.
+  required:
+    - id
+    - name
+    - comparator
+    - threshold
+    - windowHours
+  additionalProperties: {}
+  description: "The condition of a metric-rule alert."
+OpsAlertMetricSummary:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Metric id (fetch full detail via `related.metric`).
+    name:
+      type: string
+      description: Metric name.
+    events:
+      type: array
+      items:
+        type: string
+      description: "The event name(s) the metric aggregates over — one for count metrics, numerator + denominator for ratio metrics. Grep the codebase for `track('<event>')` on each to find the instrumentation feeding the metric."
+  required:
+    - id
+    - name
+    - events
+  additionalProperties: {}
+  description: "The metric an alert watches, with its backing events."
+OpsMeasurePlanContext:
+  type: object
+  properties:
+    created:
+      type: array
+      items:
+        $ref: "#/MeasurePlanResource"
+      description: Resources the assistant already created on approval (live now) — don't recreate them.
+    pending:
+      type: array
+      items:
+        $ref: "#/MeasurePlanResource"
+      description: Resources the assistant couldn't create yet (usually a metric whose backing event isn't emitted); create these after the instrumentation lands.
+    instrumentation:
+      type: array
+      items:
+        $ref: "#/MeasurePlanStep"
+      description: The code instrumentation to implement before the metrics can collect data.
+  required:
+    - created
+    - instrumentation
+  additionalProperties: {}
+  description: "An assistant-proposed measurement plan: what it already built, what it still needs, and the event instrumentation you implement."
+MeasurePlanResource:
+  type: object
+  properties:
+    kind:
+      type: string
+      enum:
+        - metric
+        - experiment
+        - alert_rule
+        - event
+      description: Resource kind.
+    id:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: Resource id when it was created; absent/`null` for resources still to be made.
+    name:
+      type: string
+      description: Resource name.
+  required:
+    - kind
+    - name
+  additionalProperties: {}
+  description: "A resource referenced by a measurement plan."
+MeasurePlanStep:
+  type: object
+  properties:
+    event:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: The event name the instrumentation should emit, when known.
+    attribute:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "A new user attribute the project must start sending on its identify/evaluate context (when a gate's targeting needs a field that doesn't exist yet)."
+    label:
+      type: string
+      description: Short human-readable name for the moment being instrumented.
+    description:
+      anyOf:
+        - type: string
+        - type: "null"
+      description: "What to track and why, described conceptually — which user moment/action to capture and what it enables. Deliberately NOT a file path (the assistant has no repo access and can't name real files); you locate the call site yourself."
+    properties:
+      type: array
+      items:
+        type: string
+      description: "Event properties the downstream metric needs attached (e.g. `method`, `plan`)."
+  required:
+    - label
+  additionalProperties: {}
+  description: "One piece of code instrumentation a measurement plan still needs."
+OpsItemAttachment:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Attachment id.
+    kind:
+      type: string
+      description: "`screenshot` | `video` | `log`."
+    filename:
+      type: string
+      description: Sanitized original filename.
+    mimeType:
+      type: string
+      description: "MIME type, e.g. `image/png`."
+    sizeBytes:
+      type: number
+      description: Upload size in bytes.
+    fetchUrl:
+      type: string
+      description: "Admin-API path to download the file (`GET` with the admin/ops key — screenshots render inline; recordings can't be watched)."
+  required:
+    - id
+    - kind
+    - filename
+    - mimeType
+    - sizeBytes
+    - fetchUrl
+  additionalProperties: {}
+  description: "A file uploaded with a bug/feature report."
+OpsItemRelated:
+  type: object
+  properties:
+    dashboard:
+      type: string
+      description: Dashboard-relative deep link to this item.
+    error:
+      type: string
+      description: Admin-API path to the tracked error (error tickets only).
+    alertRule:
+      type: string
+      description: Admin-API path to the alert rule (metric-rule alerts only).
+    metric:
+      type: string
+      description: Admin-API path to the metric the alert watches (alert tickets only).
+    githubIssue:
+      type: string
+      description: HTML URL of the connected GitHub issue, if any.
+    githubPr:
+      type: string
+      description: HTML URL of the linked GitHub pull request, if any.
+  additionalProperties: {}
+  description: "Deep links to the resources behind this item — every value is either a dashboard-relative path or an admin-API path fetchable with the same key."
+ConnectorData:
+  type: object
+  properties:
+    github:
+      $ref: "#/GithubConnectorData"
+    slack:
+      $ref: "#/SlackConnectorData"
+  additionalProperties: {}
+  description: "Connector linkage for one queue item, keyed by provider. Each provider's driver deep-merges its own trace into this blob, so any subset of providers may be present. Unknown/future providers may appear as additional keys."
+GithubConnectorData:
+  type: object
+  properties:
+    issue:
+      type: object
+      properties:
+        number:
+          type: number
+          description: GitHub issue number.
+        url:
+          type: string
+          description: HTML URL of the opened issue.
+        owner:
+          type: string
+          description: Repository owner (org or user).
+        repo:
+          type: string
+          description: Repository name.
+        createdAt:
+          type: string
+          description: ISO-8601 timestamp the issue was opened.
+      required:
+        - number
+        - url
+        - owner
+        - repo
+      additionalProperties: {}
+      description: The GitHub issue this item opened.
+    pr:
+      type: object
+      properties:
+        number:
+          type: number
+          description: Pull request number.
+        url:
+          type: string
+          description: HTML URL of the linked pull request.
+        linkedAt:
+          type: string
+          description: ISO-8601 timestamp the PR was linked.
+        connectedToIssue:
+          type: boolean
+          description: "Whether the PR was wired to the issue on GitHub (via a closing keyword or a comment)."
+        method:
+          type: string
+          enum:
+            - closes
+            - comment
+          description: How the PR was connected to the issue.
+      required:
+        - number
+        - url
+      additionalProperties: {}
+      description: The pull request linked to this item via `link-pr`.
+  additionalProperties: {}
+  description: "GitHub connector trace — the issue it opened and, once linked, the pull request."
+SlackConnectorData:
+  type: object
+  properties:
+    message:
+      type: object
+      properties:
+        channel:
+          type: string
+          description: Slack channel id the message was posted to.
+        ts:
+          type: string
+          description: Slack message timestamp (`ts`) — the message handle used for in-place `chat.update`.
+        postedAt:
+          type: string
+          description: ISO-8601 timestamp the message was posted.
+      required:
+        - channel
+        - ts
+      additionalProperties: {}
+      description: The Slack message the driver posted for this item.
+  additionalProperties: {}
+  description: "Slack connector trace — the message the driver posted for this item. The linked pull request is recorded on `github.pr`, not here."
+CreateBugRequest:
+  type: object
+  properties:
+    type:
+      type: string
+      enum:
+        - bug
+      description: Discriminator — files a bug.
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line bug title (no leading/trailing whitespace).
+    stepsToReproduce:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: How to reproduce the bug.
+    actualResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What actually happened.
+    expectedResult:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What was expected instead.
+    priority:
+      anyOf:
+        - $ref: "#/OpsItemPriority"
+        - type: "null"
+      description: Initial triage priority, or `null`.
+    reporterEmail:
+      anyOf:
+        - type: string
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the bug relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    viewport:
+      anyOf:
+        - type: string
+          maxLength: 40
+        - type: "null"
+      description: Reporter's viewport (e.g. `1280x720`), or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    notify:
+      anyOf:
+        - $ref: ./common.yaml#/NotificationTarget
+        - type: "null"
+      description: Where this bug's completion notification lands.
+  required:
+    - type
+    - title
+  additionalProperties: false
+  description: "Bug-kind fields for `POST /api/admin/ops` (sent with `type: bug`)."
+CreateFeatureRequestRequest:
+  type: object
+  properties:
+    type:
+      type: string
+      enum:
+        - feature_request
+      description: Discriminator — files a feature request.
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: One-line feature-request title (no leading/trailing whitespace).
+    description:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: What the feature is.
+    useCase:
+      type: string
+      maxLength: 8000
+      default: ""
+      description: Why it's needed / the use case.
+    priority:
+      anyOf:
+        - $ref: "#/OpsItemPriority"
+        - type: "null"
+      description: Initial triage priority, or `null`.
+    reporterEmail:
+      anyOf:
+        - type: string
+          format: email
+        - type: "null"
+      description: Email of the reporter, or `null`.
+    pageUrl:
+      anyOf:
+        - type: string
+          format: uri
+        - type: "null"
+      description: URL of the page the request relates to, or `null`.
+    userAgent:
+      anyOf:
+        - type: string
+          maxLength: 500
+        - type: "null"
+      description: Reporter's user-agent string, or `null`.
+    context:
+      anyOf:
+        - type: object
+          additionalProperties: {}
+        - type: "null"
+      description: Arbitrary capture context, or `null`.
+    notify:
+      anyOf:
+        - $ref: ./common.yaml#/NotificationTarget
+        - type: "null"
+      description: Where this request's completion notification lands.
+  required:
+    - type
+    - title
+  additionalProperties: false
+  description: "Feature-request-kind fields for `POST /api/admin/ops` (sent with `type: feature_request`)."
+CreateOpsItemRequest:
+  oneOf:
+    - $ref: "#/CreateBugRequest"
+    - $ref: "#/CreateFeatureRequestRequest"
+  discriminator:
+    propertyName: type
+    mapping:
+      bug: "#/CreateBugRequest"
+      feature_request: "#/CreateFeatureRequestRequest"
+  description: "Body for `POST /api/admin/ops`. A discriminated union on `type`: `bug` carries the bug fields, `feature_request` the feature fields. Only these two user-fileable types are accepted — `error`, `alert`, and `measure_plan` tickets are auto-filed by the platform and cannot be created over the API."
+CreateOpsItemResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Newly created item id.
+    number:
+      description: Per-project item number assigned to the new item.
+      anyOf:
+        - type: number
+        - type: "null"
+  required:
+    - id
+  additionalProperties: false
+  description: Response for `POST /api/admin/ops`.
+OpsItemStatus:
+  type: string
+  enum:
+    - open
+    - pending_approval
+    - triage
+    - triaged
+    - in_progress
+    - ready_for_qa
+    - resolved
+    - wont_fix
+  description: >-
+    Lifecycle status of a queue item. The working flow is `open` → `triaged` →
+    `in_progress` → `ready_for_qa` → `resolved` (or `wont_fix`, terminal from
+    any earlier stage). `ready_for_qa` is what a developer sets once a fix
+    lands; `resolved` is the QA sign-off, normally flipped in the dashboard
+    after verification — set it directly from code only when the fix has been
+    verified end-to-end. Two
+    human-gated holding states park an item OUT of the work queue until a human
+    promotes it to `open` in the dashboard, so `GET /api/admin/ops` excludes
+    them under `status=all`/default and returns them only when requested as an
+    exact `status`: `pending_approval` is the pre-open approval gate for
+    untriaged inbound (e.g. connector requests filed from a customer's
+    connectors panel) so it never gets auto-implemented — approving = flipping
+    the status to `open`; `triage` is the onboarding-help bucket —
+    questions/errors submitted to the "Stuck in onboarding?" assistant are
+    funnelled into the platform project as `triage` rows so the team can see
+    where people get stuck and follow up, keeping onboarding chatter out of the
+    work queue until a human moves real items to `open`.
+OpsItemPriority:
+  type: string
+  enum:
+    - nice_to_have
+    - medium
+    - high
+    - critical
+  description: >-
+    Triage priority of a queue item. The lowest tier is `nice_to_have` (not
+    `low`) — carried over from the feature-request "importance" scale this
+    priority set replaced.
+OpsItemPriorityOrNull:
+  anyOf:
+    - $ref: "#/OpsItemPriority"
+    - type: "null"
+  description: Triage priority, or `null` when not set (in an update, `null` clears it).
+OpsItemNotifyOrNull:
+  anyOf:
+    - $ref: ./common.yaml#/NotificationTarget
+    - type: "null"
+  description: Where this item's completion notification lands, or `null`.
+UpdateOpsItemStatusRequest:
+  type: object
+  properties:
+    status:
+      $ref: "#/OpsItemStatus"
+    priority:
+      $ref: "#/OpsItemPriorityOrNull"
+    notify:
+      $ref: "#/OpsItemNotifyOrNull"
+  additionalProperties: false
+  description: "Triage-only update — the shape accepted for any item, and the ONLY shape for auto-filed `error`/`alert`/`measure_plan` tickets (their content is not user-editable)."
+UpdateBugRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: New bug title (no leading/trailing whitespace).
+    stepsToReproduce:
+      type: string
+      maxLength: 8000
+      description: Updated reproduction steps.
+    actualResult:
+      type: string
+      maxLength: 8000
+      description: Updated actual result.
+    expectedResult:
+      type: string
+      maxLength: 8000
+      description: Updated expected result.
+    status:
+      $ref: "#/OpsItemStatus"
+    priority:
+      $ref: "#/OpsItemPriorityOrNull"
+    githubPrNumber:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: Link (or, when `null`, unlink) a GitHub pull request to this bug.
+    notify:
+      $ref: "#/OpsItemNotifyOrNull"
+  additionalProperties: false
+  description: "Content + triage update for a `bug` item (`PATCH /api/admin/ops/{handle}` when the item is a bug)."
+UpdateFeatureRequestRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      pattern: '^\S(.*\S)?$'
+      description: New feature-request title (no leading/trailing whitespace).
+    description:
+      type: string
+      maxLength: 8000
+      description: Updated description.
+    useCase:
+      type: string
+      maxLength: 8000
+      description: Updated use case.
+    status:
+      $ref: "#/OpsItemStatus"
+    priority:
+      $ref: "#/OpsItemPriorityOrNull"
+    githubPrNumber:
+      anyOf:
+        - type: integer
+          minimum: 1
+        - type: "null"
+      description: Link (or, when `null`, unlink) a GitHub pull request to this request.
+    notify:
+      $ref: "#/OpsItemNotifyOrNull"
+  additionalProperties: false
+  description: "Content + triage update for a `feature_request` item (`PATCH /api/admin/ops/{handle}` when the item is a feature request)."
+UpdateOpsItemRequest:
+  anyOf:
+    - $ref: "#/UpdateBugRequest"
+    - $ref: "#/UpdateFeatureRequestRequest"
+    - $ref: "#/UpdateOpsItemStatusRequest"
+  description: "Body for `PATCH /api/admin/ops/{handle}`. The body is type-less — the server validates it against the stored item's type: a `bug` accepts the bug content fields, a `feature_request` the feature fields, and `error`/`alert`/`measure_plan` only `status`/`priority`/`notify`. Pass at least one field."
+UpdateOpsItemResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Item id that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Response for the update / link-pr endpoints.
+LinkPrToOpsItemRequest:
+  type: object
+  properties:
+    prNumber:
+      anyOf:
+        - type: integer
+          exclusiveMinimum: 0
+          maximum: 9007199254740991
+        - type: "null"
+      description: PR number to record on the item. `null` unlinks the PR.
+    prUrl:
+      description: Explicit PR URL. Required for error/alert tickets (no GitHub issue to derive the URL from).
+      type: string
+      format: uri
+  required:
+    - prNumber
+  additionalProperties: false
+  description: Body for `POST /api/admin/ops/{handle}/link-pr`.
+LinkPrToOpsItemResponse:
+  type: object
+  properties:
+    id:
+      type: string
+      description: Item id that was updated.
+  required:
+    - id
+  additionalProperties: false
+  description: Response for the update / link-pr endpoints.
+NotifyOpsRequest:
+  type: object
+  properties:
+    title:
+      type: string
+      minLength: 1
+      maxLength: 200
+      description: One-line headline of what's blocked.
+    summary:
+      type: string
+      minLength: 1
+      maxLength: 280
+      description: "One sentence: why it can't be fixed in code. Renders markdown."
+    steps:
+      description: Ordered steps the human should take to unblock — self-contained (the human reads only this card, not the agent's transcript), 3–6 steps, each naming the exact file, command, env var, or dashboard page. Renders markdown.
+      type: array
+      items:
+        type: string
+    href:
+      description: Dashboard-relative deep link to the related item.
+      type: string
+    dedupeKey:
+      description: Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.
+      type: string
+  required:
+    - title
+    - summary
+  additionalProperties: false
+  description: >-
+    Body for `POST /api/admin/notifications`. In `title`, `summary`, and each
+    step, reference admin entities inline with tokens — `#42` (feedback item),
+    `@gate:<name>` (alias `@flag:`), `@experiment:<name>` (`@exp:`),
+    `@config:<name>`, `@killswitch:<name>` (`@ks:`), `@metric:<name>`,
+    `@universe:<name>`, `@alert:<name>` — where `<name>` is the entity's
+    immutable name/slug (e.g. `features.checkout`). The dashboard renders each
+    token as a live hover chip deep-linking to the entity; tokens degrade to
+    plain text elsewhere, so they're always safe to use.
+NotifyOpsResponse:
+  type: object
+  properties:
+    dedupeKey:
+      type: string
+      description: The dedupe key the escalation was recorded under.
+    dispatched:
+      type: boolean
+      description: "`true` if a new escalation was dispatched; `false` on an idempotent repeat."
+  required:
+    - dedupeKey
+    - dispatched
+  additionalProperties: false
+  description: Response for `POST /api/admin/notifications`.
+ListSlackChannelsResponse:
+  type: object
+  properties:
+    connected:
+      type: boolean
+      description: Whether a Slack connector is connected and authenticated.
+    channels:
+      type: array
+      items:
+        type: object
+        properties:
+          id:
+            type: string
+            description: Slack channel id.
+          name:
+            type: string
+            description: Slack channel name (without the leading `#`).
+          isPrivate:
+            description: Whether the channel is private.
+            type: boolean
+        required:
+          - id
+          - name
+        additionalProperties: false
+        description: One Slack channel the project can post to.
+      description: The project's Slack channels (empty when no Slack is connected).
+  required:
+    - connected
+    - channels
+  additionalProperties: false
+  description: Response for `GET /api/admin/slack/channels`.