@shipeasy/openapi 2.1.0 → 2.3.0

package/openapi.yaml

@@ -21,9 +21,26 @@ security:
   - bearerSdkKey: []
 tags:
   - name: Release
-    summary: Feature delivery
+    summary: Feature delivery — flags, kill switches, dynamic configs, A/B experiments, and the universes they bucket in.
     kind: nav
-    description: Flags, kill switches, dynamic configs, experiments, and the universes they bucket in — the feature-delivery surface.
+    description: |-
+      Release: the feature-delivery surface. One roof over the five resources
+      that decide which code path a user gets — feature gates (flags), kill
+      switches, dynamic configs, A/B/n experiments, and the universes that bucket
+      them — each exposed as its own subcommand group.
+
+      **Groups.**
+      - `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.
+      - `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.
+      - `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.
+      - `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.
+
+      **Delivery model.** Every write rebuilds the project's KV blob and purges
+      the CDN — SDKs poll at the plan interval and never touch the database on
+      the hot path. The destructive verb is `archive` (soft-delete), never
+      `delete`.
+
+      Run `shipeasy release <group> --help` for the full contract of each group.
   - name: Flags
     parent: Release
     description: |-
@@ -161,6 +178,16 @@ tags:
       **Immutable metric.** The bound metric (and its aggregation) is fixed at create time — there is no update path for `metricId`. Tune `threshold`/`comparator`/`windowHours`/`severity`/`name`/`enabled` instead, or delete + recreate to repoint the rule at a different metric.
 
       **Delivery.** `notify` optionally targets a Slack channel and/or email for this rule; `null` falls back to the project's default notification settings. Slack targets require a connected Slack connector.
+  - name: Comments
+    parent: Ops
+    description: |-
+      Comments on a queue item — the discussion thread that hangs off any bug,
+      feature request, or auto-filed error/alert ticket. Append a comment or read
+      the thread; one level of threaded replies via `parentId`.
+
+      **Mentions.** `@teammate` in a body raises an in-app notification for that
+      person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
+      Comments authored by Jarvis carry `authorType: system`.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -229,6 +256,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List feature gates
@@ -380,6 +408,23 @@ paths:
               example:
                 id: gat_01j7w7m9q4hxbf6npe6s9zr3vc
                 name: checkout_v2
+          links:
+            UpdateGate:
+              operationId: updateGate
+              parameters:
+                id: $response.body#/id
+            EnableGate:
+              operationId: enableGate
+              parameters:
+                id: $response.body#/id
+            DisableGate:
+              operationId: disableGate
+              parameters:
+                id: $response.body#/id
+            DeleteGate:
+              operationId: deleteGate
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -398,6 +443,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -428,7 +474,7 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -534,7 +580,7 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a feature gate
@@ -583,9 +629,9 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Enable a gate
           content:
             application/json:
@@ -633,9 +679,9 @@ paths:
           required: true
           description: Stable opaque gate id (`gat_…`) or the gate's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Disable a gate
           content:
             application/json:
@@ -680,6 +726,13 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - name: status
+          in: query
+          required: false
+          description: Filter by lifecycle status. Pass `archived` to return the archive tab; any other value (or omitting it) returns the non-archived experiments.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List experiments
@@ -827,6 +880,31 @@ paths:
               example:
                 id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                 name: checkout_button_color
+          links:
+            GetExperiment:
+              operationId: getExperiment
+              parameters:
+                id: $response.body#/id
+            UpdateExperiment:
+              operationId: updateExperiment
+              parameters:
+                id: $response.body#/id
+            SetExperimentMetrics:
+              operationId: setExperimentMetrics
+              parameters:
+                id: $response.body#/id
+            SetExperimentStatus:
+              operationId: setExperimentStatus
+              parameters:
+                id: $response.body#/id
+            ReanalyzeExperiment:
+              operationId: reanalyzeExperiment
+              parameters:
+                id: $response.body#/id
+            DeleteExperiment:
+              operationId: deleteExperiment
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -869,14 +947,14 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one experiment
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/GetExperimentResponse'
+                $ref: '#/components/schemas/ExperimentApiRow'
               example:
                 id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                 name: checkout_button_color
@@ -949,7 +1027,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1014,6 +1092,7 @@ paths:
         - GROUPS_WEIGHT_SUM
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - EXPERIMENT_IMMUTABLE_FIELD
       x-cli:
         name: update
         positional:
@@ -1034,7 +1113,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete an experiment
@@ -1095,7 +1174,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1124,7 +1203,7 @@ paths:
                 value:
                   status: draft
       responses:
-        '201':
+        '200':
           description: Transition experiment status
           content:
             application/json:
@@ -1152,6 +1231,12 @@ paths:
         - NOT_FOUND
         - INVALID_TRANSITION
         - VALIDATION
+        - PLAN_LIMIT
+        - EXPERIMENT_NO_GOAL_METRIC
+        - EXPERIMENT_ARCHIVED_RESTART
+        - EXPERIMENT_NOT_RUNNING
+        - EXPERIMENT_RUNNING_ARCHIVE
+        - EXPERIMENT_RESTORE_INVALID
       x-cli:
         positional:
           - id
@@ -1190,7 +1275,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1213,7 +1298,7 @@ paths:
                 value:
                   metrics: []
       responses:
-        '201':
+        '200':
           description: Attach metrics
           content:
             application/json:
@@ -1246,6 +1331,7 @@ paths:
         - EVENT_PENDING
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - METRIC_UNKNOWN_ID
       x-cli:
         name: set-metrics
         positional:
@@ -1267,7 +1353,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get analysis results
@@ -1336,7 +1422,7 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
         - name: metric
           in: query
           required: false
@@ -1410,9 +1496,9 @@ paths:
           required: true
           description: Stable opaque experiment id (`exp_…`) or the experiment's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
-        '201':
+        '200':
           description: Re-queue analysis
           content:
             application/json:
@@ -1457,6 +1543,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List dynamic configs
@@ -1605,6 +1692,23 @@ paths:
               example:
                 id: cfg_01j7wae5h6j7k8l9m0n1p2q3r4
                 name: pricing.tiers
+          links:
+            GetConfig:
+              operationId: getConfig
+              parameters:
+                id: $response.body#/id
+            UpdateConfig:
+              operationId: updateConfig
+              parameters:
+                id: $response.body#/id
+            PublishConfigDraft:
+              operationId: publishConfigDraft
+              parameters:
+                id: $response.body#/id
+            DeleteConfig:
+              operationId: deleteConfig
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -1623,6 +1727,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -1644,7 +1749,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one config
@@ -1746,7 +1851,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1822,7 +1927,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a dynamic config
@@ -1872,7 +1977,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -1940,7 +2045,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2002,7 +2107,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2021,7 +2126,7 @@ paths:
                 value:
                   env: prod
       responses:
-        '201':
+        '200':
           description: Publish a draft
           content:
             application/json:
@@ -2071,7 +2176,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
         - name: limit
           in: query
           required: false
@@ -2135,7 +2240,7 @@ paths:
           required: true
           description: Stable opaque config id (`cfg_…`) or the config's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2201,6 +2306,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List killswitches
@@ -2303,6 +2409,27 @@ paths:
               example:
                 id: ksw_01j7w9d8h2k4m6n8p0q2r4s6t8
                 name: payments.checkout
+          links:
+            GetKillswitch:
+              operationId: getKillswitch
+              parameters:
+                id: $response.body#/id
+            UpdateKillswitch:
+              operationId: updateKillswitch
+              parameters:
+                id: $response.body#/id
+            SetKillswitchSwitch:
+              operationId: setKillswitchSwitch
+              parameters:
+                id: $response.body#/id
+            SetKillswitchValue:
+              operationId: setKillswitchValue
+              parameters:
+                id: $response.body#/id
+            DeleteKillswitch:
+              operationId: deleteKillswitch
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -2321,6 +2448,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -2342,7 +2470,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one killswitch
@@ -2414,7 +2542,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2491,7 +2619,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a killswitch
@@ -2544,7 +2672,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2618,7 +2746,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2687,7 +2815,7 @@ paths:
           required: true
           description: Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2758,6 +2886,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List universes
@@ -2846,6 +2975,15 @@ paths:
               example:
                 id: uni_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: primary_users
+          links:
+            UpdateUniverse:
+              operationId: updateUniverse
+              parameters:
+                id: $response.body#/id
+            DeleteUniverse:
+              operationId: deleteUniverse
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -2865,6 +3003,7 @@ paths:
         - PLAN_REQUIRED
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -2891,7 +3030,7 @@ paths:
           required: true
           description: Stable opaque universe id (`uni_…`) or the universe's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -2959,7 +3098,7 @@ paths:
           required: true
           description: Stable opaque universe id (`uni_…`) or the universe's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a universe
@@ -2998,17 +3137,19 @@ paths:
       description: |-
         Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in ["@team"]`) that the SDK expands to the resolved email list at rebuild.
 
-        **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `query`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.
+        **Turn "launch X in country Y" into a gated flag:** list templates (optionally with `q`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.
 
         The catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).
       tags:
         - Templates
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
         - name: query
           in: query
           required: false
-          description: Case-insensitive substring filter over each template's `name` + `description`. Omit to return the whole catalog.
+          deprecated: true
+          description: Deprecated alias for `q`, kept working for one release. Prefer `q`.
           schema:
             type: string
       responses:
@@ -3120,7 +3261,7 @@ paths:
           required: true
           description: Built-in slug (`country`) or customer template id (`gtpl_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one gate template
@@ -3158,7 +3299,7 @@ paths:
           required: true
           description: Customer template id (`gtpl_…`) or its `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3221,7 +3362,7 @@ paths:
           required: true
           description: Customer template id (`gtpl_…`) or its `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a gate template
@@ -3241,6 +3382,8 @@ paths:
           $ref: '#/components/responses/NotFound'
         '409':
           $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
       x-error-codes:
         - BAD_REQUEST
         - UNAUTHORIZED
@@ -3263,6 +3406,7 @@ paths:
         - Attributes
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List targeting attributes
@@ -3329,6 +3473,19 @@ paths:
               example:
                 id: attr_01j7w8a1b2c3
                 name: plan
+          links:
+            GetAttribute:
+              operationId: getAttribute
+              parameters:
+                id: $response.body#/id
+            UpdateAttribute:
+              operationId: updateAttribute
+              parameters:
+                id: $response.body#/id
+            DeleteAttribute:
+              operationId: deleteAttribute
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3368,7 +3525,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a targeting attribute
@@ -3422,7 +3579,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3481,7 +3638,7 @@ paths:
           required: true
           description: The attribute id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive a targeting attribute
@@ -3524,6 +3681,7 @@ paths:
         - Metrics
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List metrics
@@ -3625,6 +3783,19 @@ paths:
               example:
                 id: met_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: checkouts
+          links:
+            GetMetric:
+              operationId: getMetric
+              parameters:
+                id: $response.body#/id
+            UpdateMetric:
+              operationId: updateMetric
+              parameters:
+                id: $response.body#/id
+            DeleteMetric:
+              operationId: deleteMetric
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3645,6 +3816,7 @@ paths:
         - EVENT_PENDING
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -3666,7 +3838,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a metric
@@ -3725,7 +3897,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -3784,7 +3956,7 @@ paths:
           required: true
           description: Stable opaque metric id (`met_…`) or the metric's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive a metric
@@ -3828,6 +4000,7 @@ paths:
         - Events
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List events
@@ -3913,6 +4086,23 @@ paths:
               example:
                 id: evt_01j7w8a1b2c3d4e5f6g7h8i9j0
                 name: checkout_completed
+          links:
+            GetEvent:
+              operationId: getEvent
+              parameters:
+                id: $response.body#/id
+            UpdateEvent:
+              operationId: updateEvent
+              parameters:
+                id: $response.body#/id
+            ApproveEvent:
+              operationId: approveEvent
+              parameters:
+                id: $response.body#/id
+            DeleteEvent:
+              operationId: deleteEvent
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -3931,6 +4121,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -3952,7 +4143,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get an event
@@ -4011,7 +4202,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4079,7 +4270,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Archive an event
@@ -4130,7 +4321,7 @@ paths:
           required: true
           description: Stable opaque event id (`evt_…`) or the event's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4357,7 +4548,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get one queue item
@@ -4416,7 +4607,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4484,7 +4675,7 @@ paths:
           required: true
           description: Per-project item number (e.g. `7`) or the full ops item id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4525,6 +4716,117 @@ paths:
         name: link-pr
         positional:
           - handle
+  /api/admin/ops/{handle}/comments:
+    get:
+      operationId: listOpsComments
+      summary: List an item's comments
+      description: |-
+        List the comment thread on a queue item, oldest first. Each comment
+        carries its author (a teammate email, or `system` for a comment authored by
+        Jarvis — the AI agent), its markdown body, and `parentId` for the single
+        level of threaded replies. Removed comments are omitted.
+
+        **Use case:** Read the discussion on an item before replying or acting on it.
+      tags:
+        - Comments
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: List an item's comments
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ListOpsCommentsResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+      x-cli:
+        name: list
+        positional:
+          - handle
+    post:
+      operationId: createOpsComment
+      summary: Comment on an item
+      description: |-
+        Append a comment to a queue item's thread. The body is markdown (mentions
+        like `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,
+        to reply). Pass `parentId` to reply under an existing top-level comment
+        (one level of threading — a reply to a reply attaches to the same parent).
+
+        Create-only and append-only, so it is safe for restricted ops keys — the
+        same channel the ops loop and Jarvis use to leave a note on an item.
+      tags:
+        - Comments
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: handle
+          in: path
+          required: true
+          description: Per-project item number (e.g. `7`) or the full ops item id.
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateOpsCommentRequest'
+            examples:
+              comment:
+                summary: Leave a comment
+                value:
+                  body: Repro'd on iOS Safari 17 — the button overflows its container. cc @alice
+              reply:
+                summary: Reply under an existing comment
+                value:
+                  body: Agreed, let's ship the fix behind @shipeasy's suggested flag.
+                  parentId: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+      responses:
+        '201':
+          description: Comment on an item
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CreateOpsCommentResponse'
+              example:
+                id: cm_01j7w8a1b2c3d4e5f6g7h8i9j0
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - BAD_REQUEST
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+        - VALIDATION
+      x-cli:
+        name: create
+        positional:
+          - handle
   /api/admin/notifications:
     post:
       operationId: notifyOps
@@ -4637,6 +4939,7 @@ paths:
         - Alerts
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List alert rules
@@ -4730,6 +5033,15 @@ paths:
                 $ref: '#/components/schemas/CreateAlertRuleResponse'
               example:
                 id: ar_01j7w8a1b2c3d4e5f6g7h8i9j0
+          links:
+            UpdateAlertRule:
+              operationId: updateAlertRule
+              parameters:
+                id: $response.body#/id
+            DeleteAlertRule:
+              operationId: deleteAlertRule
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -4747,6 +5059,7 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - ALREADY_EXISTS
+        - METRIC_NOT_FOUND
         - REFERENCED_NOT_FOUND
         - VALIDATION
       x-cli:
@@ -4773,7 +5086,7 @@ paths:
           required: true
           description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -4844,7 +5157,7 @@ paths:
           required: true
           description: Stable opaque alert-rule id (`ar_…`) or the rule's `name`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete an alert rule
@@ -4899,7 +5212,7 @@ paths:
                 name: Acme
                 domain: acme.com
                 ownerEmail: owner@acme.com
-                plan: paid
+                plan: pro
                 status: active
                 subscriptionStatus: active
                 billingInterval: monthly
@@ -5018,7 +5331,7 @@ paths:
           required: true
           description: Stable opaque project id. Must match the caller's own project.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5046,7 +5359,7 @@ paths:
                 name: Acme Rockets
                 domain: acme.com
                 ownerEmail: owner@acme.com
-                plan: paid
+                plan: pro
                 status: active
                 subscriptionStatus: active
                 billingInterval: monthly
@@ -5157,6 +5470,11 @@ paths:
               example:
                 id: i18n_01j7w8a1b2c4
                 name: fr:prod
+          links:
+            PublishI18nProfile:
+              operationId: publishI18nProfile
+              parameters:
+                profileId: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -5204,9 +5522,10 @@ paths:
         - name: q
           in: query
           required: false
-          description: Free-text search — matches keys whose name OR value contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
+          description: Free-text search — matches keys whose name, value, OR description contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.
           schema:
             type: string
+            maxLength: 100
         - name: limit
           in: query
           required: false
@@ -5215,6 +5534,14 @@ paths:
             type: integer
             minimum: 1
             maximum: 500
+        - name: offset
+          in: query
+          required: false
+          description: Number of keys to skip before returning `limit` rows (offset pagination).
+          schema:
+            type: integer
+            minimum: 0
+            default: 0
       responses:
         '200':
           description: List i18n keys
@@ -5319,7 +5646,7 @@ paths:
           required: true
           description: The key's id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5467,7 +5794,7 @@ paths:
           required: true
           description: The draft id to update.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5525,7 +5852,7 @@ paths:
           required: true
           description: The profile id to publish.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5535,7 +5862,7 @@ paths:
             example:
               chunk: default
       responses:
-        '201':
+        '200':
           description: Publish a profile chunk
           content:
             application/json:
@@ -5724,9 +6051,9 @@ paths:
       operationId: getError
       summary: Get a tracked error
       description: |-
-        Returns a single tracked error by its id, including the latest occurrence's stack, extras, and consequence. Returns `404` if no such error exists in the project.
+        Returns a single tracked error by its id, including the latest occurrence's stack, extras, and consequence, plus `occurrences` — the sampled per-instance detail rows behind the issue (newest first; exhaustive while the issue is small, thinned at volume, capped at 100). Returns `404` if no such error exists in the project.
 
-        **Use case:** Drill into one issue — fetch its full stack and `seenUrls` to investigate, or to render the detail panel behind a row in the errors list.
+        **Use case:** Drill into one issue — fetch its full stack and `seenUrls` to investigate, or walk `occurrences` to see how the failing message/stack varies across instances.
       tags:
         - Errors
       parameters:
@@ -5736,7 +6063,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a tracked error
@@ -5770,6 +6097,31 @@ paths:
                 lastSeenAt: '2026-06-28T14:55:31.000Z'
                 createdAt: '2026-06-20T08:11:02.000Z'
                 updatedAt: '2026-06-28T14:55:31.000Z'
+                occurrences:
+                  - id: occ_01j7w7qq0v3k9d2m5rc8t1xh4n
+                    message: Cannot read properties of undefined (reading 'id')
+                    stack: |-
+                      TypeError: Cannot read properties of undefined (reading 'id')
+                          at GateEditor (/app/gates/[id]/page.tsx:42:18)
+                    url: https://app.example.com/dashboard/gat_01j7/edit
+                    env: prod
+                    side: client
+                    sdkVersion: 6.0.0
+                    extrasJson: '{"gateId":"gat_01j7"}'
+                    sampleRate: 100
+                    seenAt: '2026-06-28T14:55:31.000Z'
+                  - id: occ_01j7w7pk8s6e3f9b0zad7y5w2q
+                    message: Cannot read properties of undefined (reading 'id')
+                    stack: |-
+                      TypeError: Cannot read properties of undefined (reading 'id')
+                          at GateEditor (/app/gates/[id]/page.tsx:42:18)
+                    url: https://app.example.com/dashboard/gat_02c4/edit
+                    env: prod
+                    side: client
+                    sdkVersion: 6.0.0
+                    extrasJson: '{"gateId":"gat_02c4"}'
+                    sampleRate: 10
+                    seenAt: '2026-06-24T09:12:05.000Z'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -5811,7 +6163,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -5900,7 +6252,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '201':
           description: File a feedback ticket for an error
@@ -5931,6 +6283,75 @@ paths:
         name: file
         positional:
           - id
+  /api/admin/errors/{id}/resolve:
+    post:
+      operationId: resolveError
+      summary: Resolve a tracked error
+      description: |-
+        Marks one tracked error `resolved` — the single-purpose "close out" action. Takes no body; it is `PATCH /api/admin/errors/{id}` pinned to `{ "status": "resolved" }`, exposed so tooling can close an error without being handed the full open/resolved/ignored status machine. A resolved error reopens automatically (ingestion-side) if it recurs, so resolving is always safe: a premature resolve un-does itself on the next occurrence. Returns the updated row; `404` if the error does not exist.
+
+        **Use case:** Close out a tracked error from an agent or script once its fix has shipped — e.g. after a deploy, resolve every open issue the change addressed and let recurrence reopen anything that wasn't actually fixed.
+      tags:
+        - Errors
+      parameters:
+        - $ref: '#/components/parameters/ProjectId'
+        - name: id
+          in: path
+          required: true
+          description: Stable opaque error id (`err_…`).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      responses:
+        '200':
+          description: Resolve a tracked error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorRecord'
+              example:
+                id: err_01j7w7m9q4hxbf6npe6s9zr3vc
+                projectId: e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90
+                fingerprint: 9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1
+                causedByFingerprint: null
+                message: Cannot read properties of undefined (reading 'id')
+                errorType: TypeError
+                stack: null
+                source: shipeasy
+                url: https://app.example.com/dashboard/gat_01j7/edit
+                seenUrls: null
+                subject: gate editor
+                outcome: crash on load
+                side: client
+                env: prod
+                kind: uncaught
+                lastExtrasJson: null
+                sdkVersion: 6.0.0
+                count: 137
+                status: resolved
+                firstSeenAt: '2026-06-20T08:11:02.000Z'
+                lastSeenAt: '2026-06-28T14:55:31.000Z'
+                createdAt: '2026-06-20T08:11:02.000Z'
+                updatedAt: '2026-06-28T15:02:10.000Z'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          $ref: '#/components/responses/Conflict'
+        '422':
+          $ref: '#/components/responses/UnprocessableEntity'
+      x-error-codes:
+        - UNAUTHORIZED
+        - FORBIDDEN
+        - NOT_FOUND
+      x-cli:
+        name: resolve
+        positional:
+          - id
   /api/admin/errors/{id}/series:
     post:
       operationId: getErrorSeries
@@ -5948,7 +6369,7 @@ paths:
           required: true
           description: Stable opaque error id (`err_…`).
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6022,6 +6443,7 @@ paths:
         - Connectors
       parameters:
         - $ref: '#/components/parameters/ProjectId'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List connectors
@@ -6140,6 +6562,23 @@ paths:
                 $ref: '#/components/schemas/CreateConnectorResponse'
               example:
                 id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+          links:
+            GetConnector:
+              operationId: getConnector
+              parameters:
+                id: $response.body#/id
+            UpdateConnector:
+              operationId: updateConnector
+              parameters:
+                id: $response.body#/id
+            TestConnector:
+              operationId: testConnector
+              parameters:
+                id: $response.body#/id
+            DeleteConnector:
+              operationId: deleteConnector
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6175,7 +6614,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Get a connector
@@ -6243,7 +6682,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6316,7 +6755,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Delete a connector
@@ -6365,7 +6804,7 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: false
         content:
@@ -6383,7 +6822,7 @@ paths:
                   text: Triage only the P0 bugs reported in the last 24h.
       responses:
         '200':
-          description: Fire a trigger connector
+          description: The trigger run was successfully kicked off.
           content:
             application/json:
               schema:
@@ -6402,6 +6841,8 @@ paths:
           $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '502':
+          $ref: '#/components/responses/BadGateway'
       x-error-codes:
         - UNAUTHORIZED
         - FORBIDDEN
@@ -6429,10 +6870,10 @@ paths:
           required: true
           description: Stable opaque connector id.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
-          description: Test a connector
+          description: The test dispatch reached the destination.
           content:
             application/json:
               schema:
@@ -6452,6 +6893,8 @@ paths:
           $ref: '#/components/responses/Conflict'
         '422':
           $ref: '#/components/responses/UnprocessableEntity'
+        '502':
+          $ref: '#/components/responses/BadGateway'
       x-error-codes:
         - UNAUTHORIZED
         - FORBIDDEN
@@ -6481,7 +6924,7 @@ paths:
           required: true
           description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       requestBody:
         required: true
         content:
@@ -6587,6 +7030,27 @@ paths:
                 $ref: '#/components/schemas/CreateConnectorResponse'
               example:
                 id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+          links:
+            FireConnector:
+              operationId: fireConnector
+              parameters:
+                id: $response.body#/id
+            TestConnector:
+              operationId: testConnector
+              parameters:
+                id: $response.body#/id
+            GetConnector:
+              operationId: getConnector
+              parameters:
+                id: $response.body#/id
+            UpdateTriggerConnector:
+              operationId: updateTriggerConnector
+              parameters:
+                id: $response.body#/id
+            DeleteConnector:
+              operationId: deleteConnector
+              parameters:
+                id: $response.body#/id
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6783,6 +7247,7 @@ paths:
         - $ref: '#/components/parameters/ProjectId'
         - $ref: '#/components/parameters/PaginationLimit'
         - $ref: '#/components/parameters/PaginationCursor'
+        - $ref: '#/components/parameters/Q'
       responses:
         '200':
           description: List API keys
@@ -6896,6 +7361,7 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
   /api/admin/keys/{id}/revoke:
@@ -6917,7 +7383,7 @@ paths:
           required: true
           description: Stable opaque key id (UUID) returned by `create` / `list`.
           schema:
-            type: string
+            $ref: '#/components/schemas/ResourceId'
       responses:
         '200':
           description: Revoke an API key
@@ -7042,6 +7508,14 @@ components:
       description: Opaque cursor returned in the previous page's `next_cursor`. Omit for the first page.
       schema:
         type: string
+    Q:
+      name: q
+      in: query
+      required: false
+      description: Case-insensitive substring filter across the resource's human-readable text columns (e.g. `name`, `title`, `description`). OR-matched across those columns; omit to return everything.
+      schema:
+        type: string
+        maxLength: 100
   schemas:
     ListGatesResponse:
       type: object
@@ -7066,6 +7540,12 @@ components:
                     minimum: 0
                     maximum: 1
                 description: Master switch. Returned as `1`/`0` from D1; treat truthy as enabled.
+              type:
+                type: string
+                enum:
+                  - targeting
+                  - holdout
+                description: Gate kind — `targeting` (normal flag) or `holdout` (restricted public % + whitelist).
               rolloutPct:
                 type: integer
                 minimum: 0
@@ -7357,6 +7837,15 @@ components:
         - GROUPS_WEIGHT_SUM
         - EVENT_PENDING
         - INTERNAL
+        - PLAN_LIMIT
+        - EXPERIMENT_NO_GOAL_METRIC
+        - EXPERIMENT_ARCHIVED_RESTART
+        - EXPERIMENT_RESTORE_INVALID
+        - EXPERIMENT_NOT_RUNNING
+        - EXPERIMENT_RUNNING_ARCHIVE
+        - EXPERIMENT_IMMUTABLE_FIELD
+        - METRIC_NOT_FOUND
+        - METRIC_UNKNOWN_ID
       x-enum-descriptions:
         BAD_REQUEST: Malformed request (bad JSON, missing project scope).
         UNAUTHORIZED: Missing or invalid admin SDK key.
@@ -7373,9 +7862,18 @@ components:
         GROUPS_WEIGHT_SUM: Experiment group weights must sum to 10000 (basis points).
         EVENT_PENDING: The referenced event is still pending review and cannot back a metric yet.
         INTERNAL: Unexpected server error.
+        PLAN_LIMIT: The action would exceed a plan quota (e.g. the tier's maximum experiments, metrics, or configs). Upgrade the plan or archive an existing resource.
+        EXPERIMENT_NO_GOAL_METRIC: The experiment has no goal metric set, which the requested action requires.
+        EXPERIMENT_ARCHIVED_RESTART: An archived experiment cannot be restarted.
+        EXPERIMENT_RESTORE_INVALID: The experiment cannot be restored from its current state.
+        EXPERIMENT_NOT_RUNNING: The action requires the experiment to be running.
+        EXPERIMENT_RUNNING_ARCHIVE: A running experiment cannot be archived — stop it first.
+        EXPERIMENT_IMMUTABLE_FIELD: A field that is immutable while the experiment is running was modified.
+        METRIC_NOT_FOUND: The referenced metric does not exist or is not visible to the caller.
+        METRIC_UNKNOWN_ID: The supplied metric id is malformed or not recognised.
     Error:
       type: object
-      description: Uniform error envelope returned by every admin endpoint on a non-2xx status. `error` is the human-readable message; `code` is the stable machine code (present whenever the failure maps to a catalogued `ErrorCode`); `detail` carries extra context (validation paths, conflicting field); `instructions` is optional actionable guidance for resolving the error.
+      description: Uniform error envelope returned by every admin endpoint on a non-2xx status. `error` is the human-readable message; `code` is the stable machine code (present whenever the failure maps to a catalogued `ErrorCode`); `detail` carries extra context (validation paths, conflicting field); `fields` maps each failing input field to its own message; `instructions` is optional actionable guidance for resolving the error; `schema` echoes back the expected JSON Schema when a value failed schema validation.
       required:
         - error
       additionalProperties: false
@@ -7388,9 +7886,18 @@ components:
         detail:
           type: string
           description: Extra context (validation details, conflicting field, referenced row).
+        fields:
+          type: object
+          additionalProperties:
+            type: string
+          description: Per-field validation messages, keyed by the submitted field's path (dot-notation for nested fields, e.g. `groups.0.weight`). Present when structural validation failed on one or more specific input fields, so a client form can attach each message to its own input instead of collapsing everything into one banner.
         instructions:
           type: string
           description: Actionable guidance for resolving this error — what to check or change next.
+        schema:
+          type: object
+          additionalProperties: true
+          description: The expected JSON Schema (draft 2020-12) the submitted value must satisfy. Returned only when a value failed schema validation (e.g. a config `value` that does not match its config's saved schema), so the caller can correct the value and retry without re-fetching.
     Folder:
       anyOf:
         - type: string
@@ -7406,6 +7913,13 @@ components:
           maxLength: 128
           pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
           description: Stable gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate.
+        type:
+          default: targeting
+          type: string
+          enum:
+            - targeting
+            - holdout
+          description: Gate kind. `targeting` (default) is a normal flag with the full builder. `holdout` is a **restricted** flag — only a public rollout % and a whitelist are allowed; attribute rules and a gatekeeper stack are rejected. Used as an experiment's `holdout_gate`.
         enabled:
           default: true
           description: Master switch. Defaults to `true`. Set `false` to create the gate disabled (evaluates to `false` regardless of rules/rollout); flip on via `POST /{id}/enable` or PATCH.
@@ -7690,6 +8204,11 @@ components:
         - id
         - name
       additionalProperties: false
+    ResourceId:
+      type: string
+      minLength: 1
+      maxLength: 128
+      description: A resource path identifier — an opaque `xxx_<ULID>` id (~30 chars) or the resource's `name`/`key`. 1–128 characters; the upper bound matches the longest name/key any resource accepts, so an over-long value can never name a real row.
     DeleteGateResponse:
       type: object
       properties:
@@ -7702,6 +8221,12 @@ components:
     UpdateGateRequest:
       type: object
       properties:
+        type:
+          type: string
+          enum:
+            - targeting
+            - holdout
+          description: Gate kind. Switching to `holdout` requires the gate carry only a public rollout % + whitelist (attribute rules / stack are rejected).
         rollout_pct:
           description: New rollout in **basis points** (0–10000 = 0%–100%) — `100` here means **1%**. Use `rollout_percent` (0–100) below for percent. Omit both to leave unchanged.
           type: integer
@@ -7993,155 +8518,292 @@ components:
         - id
         - enabled
       additionalProperties: false
-    ListExperimentsResponse:
+    ExperimentApiRow:
       type: object
       properties:
-        data:
-          type: array
+        id:
+          type: string
+          description: Stable opaque experiment id (`exp_…`).
+        name:
+          type: string
+          maxLength: 128
+          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
+          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
+        description:
+          anyOf:
+            - type: string
+            - type: 'null'
+        hypothesis:
+          anyOf:
+            - type: string
+            - type: 'null'
+        tag:
+          anyOf:
+            - type: string
+            - type: 'null'
+        ownerEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+        audience:
+          anyOf:
+            - type: string
+            - type: 'null'
+        bucketBy:
+          anyOf:
+            - type: string
+              minLength: 1
+              maxLength: 128
+              pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
+              description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
+            - type: 'null'
+        folder:
+          anyOf:
+            - type: string
+            - type: 'null'
+        status:
+          type: string
+          enum:
+            - draft
+            - running
+            - stopped
+            - archived
+        universe:
+          type: string
+          description: Universe name this experiment draws from.
+        targetingGate:
+          anyOf:
+            - type: string
+            - type: 'null'
+        holdoutGate:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Per-experiment holdout gate name (a `holdout`-type flag), or `null`.
+        allocationPct:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+          description: Allocation in basis points (0–10000).
+        reservedHeadroom:
+          type: integer
+          minimum: 0
+          maximum: 10000
+          description: Basis points of the split reserved for appended variants (group weights sum to 10000 − this).
+        hashVersion:
+          type: integer
+          minimum: 1
+          description: Bucketing hash algorithm version for the experiment's pool slice (§B4). Defaults to 1.
+        poolOffsetBp:
+          anyOf:
+            - type: integer
+              minimum: 0
+              maximum: 10000
+            - type: 'null'
+          description: Basis-point offset of the experiment's contiguous slice in the universe pool, or `null` before a slice is allocated.
+        poolSizeBp:
+          anyOf:
+            - type: integer
+              minimum: 0
+              maximum: 10000
+            - type: 'null'
+          description: Basis-point width of the experiment's pool slice (equal to its allocation), or `null` before a slice is allocated.
+        salt:
+          type: string
+        params:
+          type: object
+          additionalProperties:
+            type: string
+            enum:
+              - string
+              - bool
+              - number
+        groups:
+          type: array
           items:
             type: object
             properties:
-              id:
-                type: string
-                description: Stable opaque experiment id (`exp_…`).
               name:
                 type: string
-                maxLength: 128
-                pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
-                description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
-              description:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              hypothesis:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              tag:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              ownerEmail:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              audience:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              bucketBy:
-                anyOf:
-                  - type: string
-                    minLength: 1
-                    maxLength: 128
-                    pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
-                    description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
-                  - type: 'null'
-              folder:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              status:
-                type: string
-                enum:
-                  - draft
-                  - running
-                  - stopped
-                  - archived
-              universe:
-                type: string
-                description: Universe name this experiment draws from.
-              targetingGate:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-              allocationPct:
+                minLength: 1
+                maxLength: 64
+                description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
+              weight:
                 type: integer
-                minimum: -9007199254740991
-                maximum: 9007199254740991
-                description: Allocation in basis points (0–10000).
-              salt:
-                type: string
+                minimum: 0
+                maximum: 10000
+                description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
               params:
+                default: {}
+                description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
                 type: object
-                additionalProperties:
+                additionalProperties: {}
+            required:
+              - name
+              - weight
+            additionalProperties: false
+            description: One variant in the experiment. Weights across all groups must sum to 10000.
+        significanceThreshold:
+          type: number
+        minRuntimeDays:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        minSampleSize:
+          type: integer
+          minimum: -9007199254740991
+          maximum: 9007199254740991
+        sequentialTesting:
+          type: boolean
+        startedAt:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
+        stoppedAt:
+          anyOf:
+            - type: string
+            - type: 'null'
+        updatedAt:
+          type: string
+        version:
+          anyOf:
+            - type: integer
+            - type: 'null'
+          description: Save counter (number of published edits), or `null` on pre-versioning rows.
+        creatorEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: 'Resolved creator email (`created_by` → users). Enriched field: present on list rows, omitted from the by-id detail.'
+        updaterEmail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: 'Resolved last-editor email (`updated_by` → users). Enriched field: present on list rows, omitted from the by-id detail.'
+        verdict:
+          type: string
+          enum:
+            - ship
+            - hold
+            - wait
+            - invalid
+            - draft
+          description: 'Answer-first decision from the goal metric + guardrails + SRM vs. the significance threshold and min runtime: `ship`, `hold`, `wait`, `invalid`, `draft`. Enriched field: list rows only.'
+        verdictTitle:
+          type: string
+          description: 'Expanded verdict headline the results hero renders. Enriched field: list rows only.'
+        verdictWhy:
+          type: string
+          description: 'Verdict rationale the results hero renders. Enriched field: list rows only.'
+        goalMetric:
+          anyOf:
+            - type: object
+              properties:
+                id:
                   type: string
-                  enum:
-                    - string
-                    - bool
-                    - number
-              groups:
-                type: array
-                items:
-                  type: object
-                  properties:
-                    name:
-                      type: string
-                      minLength: 1
-                      maxLength: 64
-                      description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
-                    weight:
-                      type: integer
-                      minimum: 0
-                      maximum: 10000
-                      description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
-                    params:
-                      default: {}
-                      description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
-                      type: object
-                      additionalProperties: {}
-                  required:
-                    - name
-                    - weight
-                  additionalProperties: false
-                  description: One variant in the experiment. Weights across all groups must sum to 10000.
-              significanceThreshold:
-                type: number
-              minRuntimeDays:
-                type: integer
-                minimum: -9007199254740991
-                maximum: 9007199254740991
-              minSampleSize:
-                type: integer
-                minimum: -9007199254740991
-                maximum: 9007199254740991
-              sequentialTesting:
-                type: boolean
-              startedAt:
-                anyOf:
-                  - type: string
-                  - type: 'null'
-                description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
-              stoppedAt:
+                name:
+                  type: string
+              required:
+                - id
+                - name
+              additionalProperties: false
+            - type: 'null'
+          description: 'The experiment''s goal metric `{ id, name }`, or `null` when none is set. Enriched field: list rows only.'
+        guardrails:
+          type: array
+          items:
+            type: object
+            properties:
+              id:
+                type: string
+              name:
+                type: string
+              eventName:
                 anyOf:
                   - type: string
                   - type: 'null'
-              updatedAt:
-                type: string
             required:
               - id
               - name
-              - description
-              - hypothesis
-              - tag
-              - ownerEmail
-              - audience
-              - bucketBy
-              - folder
-              - status
-              - universe
-              - targetingGate
-              - allocationPct
-              - salt
-              - params
-              - groups
-              - significanceThreshold
-              - minRuntimeDays
-              - minSampleSize
-              - sequentialTesting
-              - startedAt
-              - updatedAt
             additionalProperties: false
+          description: 'Guardrail metrics `{ id, name, eventName? }`. Enriched field: list rows only.'
+        guardrailCount:
+          type: integer
+          minimum: 0
+          description: 'Number of guardrail metrics. Enriched field: list rows only.'
+        primaryLiftPct:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: 'Goal-metric lift of the leading variant vs. control, in percent, or `null` when not yet computed. Enriched field: list rows only.'
+        significancePct:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: 'Statistical significance (1 − p) as a percent, or `null` when not yet computed. Enriched field: list rows only.'
+        sampleSize:
+          anyOf:
+            - type: integer
+            - type: 'null'
+          description: 'Total distinct units analysed, or `null` when not yet computed. Enriched field: list rows only.'
+        exposure:
+          type: array
+          items:
+            type: object
+            properties:
+              ds:
+                type: string
+              value:
+                type: number
+            required:
+              - ds
+              - value
+            additionalProperties: false
+          description: 'Cumulative unique-users-enrolled series for the exposure sparkline. Enriched field: list rows only.'
+        exposureTotal:
+          anyOf:
+            - type: integer
+            - type: 'null'
+          description: 'Total distinct units ever exposed (sparkline headline), or `null`. Enriched field: list rows only.'
+      required:
+        - id
+        - name
+        - description
+        - hypothesis
+        - tag
+        - ownerEmail
+        - audience
+        - bucketBy
+        - folder
+        - status
+        - universe
+        - targetingGate
+        - holdoutGate
+        - allocationPct
+        - reservedHeadroom
+        - hashVersion
+        - poolOffsetBp
+        - poolSizeBp
+        - salt
+        - params
+        - groups
+        - significanceThreshold
+        - minRuntimeDays
+        - minSampleSize
+        - sequentialTesting
+        - startedAt
+        - stoppedAt
+        - updatedAt
+        - version
+      additionalProperties: false
+    ListExperimentsResponse:
+      type: object
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/ExperimentApiRow'
         next_cursor:
           anyOf:
             - type: string
@@ -8185,6 +8847,12 @@ components:
           minLength: 1
           maxLength: 256
           description: Numeric event property for `sum`/`avg` (with `event`).
+        min_effect_of_interest:
+          description: Per-experiment override of the metric's default minimum effect of interest (relative, 0–1) — the smallest change worth acting on for this experiment's decision. `null`/omitted inherits the metric default. For a guardrail, the non-inferiority margin.
+          default: null
+          anyOf:
+            - type: number
+            - type: 'null'
       additionalProperties: false
       description: Inline metric — a DSL `query`, or an `event` (+ `aggregation`/`value`) the server compiles into one.
     CreateExperimentRequest:
@@ -8247,13 +8915,19 @@ components:
           description: Name of an existing universe in the project. Returns `422` if the universe doesn't exist.
         targeting_gate:
           default: null
-          description: Optional gate name. Only callers that pass the gate are enrolled in the experiment.
+          description: Optional gate name (a `targeting`-type flag). Only callers that pass the gate are enrolled in the experiment.
+          anyOf:
+            - type: string
+            - type: 'null'
+        holdout_gate:
+          default: null
+          description: Optional per-experiment holdout gate — the name of a `holdout`-type flag (public % + whitelist). A caller the flag passes is *held out* (never assigned, sees the universe defaults). Distinct from the universe-level holdout.
           anyOf:
             - type: string
             - type: 'null'
         allocation_pct:
           default: 0
-          description: Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). `0` = unallocated. Use `allocation_percent` (0–100) below to think in percent. Immutable while the experiment is running.
+          description: Share of the (gated) audience allocated to the experiment, in basis points (0–10000 = 0%–100%). `0` = unallocated. Under pooled assignment this is the size of the universe-pool slice claimed. Use `allocation_percent` (0–100) below to think in percent. Immutable while the experiment is running.
           type: integer
           minimum: 0
           maximum: 10000
@@ -8262,6 +8936,11 @@ components:
           type: number
           minimum: 0
           maximum: 100
+        reserved_headroom:
+          description: Basis points of this experiment's split kept empty (0–10000) so a new variant can be appended into it while running without reshuffling. Group weights must sum to `10000 − reserved_headroom`. Defaults to the universe's `recommended_headroom` when omitted.
+          type: integer
+          minimum: 0
+          maximum: 10000
         salt:
           description: Hash salt for bucketing. Auto-generated if omitted. Immutable while running.
           type: string
@@ -8276,7 +8955,7 @@ components:
               - string
               - bool
               - number
-          description: 'Map of param-name → scalar type. Defines the shape of `groups[].params`. Example: `{ headline: ''string'', show_cta: ''bool'' }`.'
+          description: '**Deprecated** — the universe now owns the config schema (`param_schema`). Retained for back-compat; new experiments should leave this empty and declare params on the universe. Map of param-name → scalar type.'
         groups:
           minItems: 2
           type: array
@@ -8292,18 +8971,18 @@ components:
                 type: integer
                 minimum: 0
                 maximum: 10000
-                description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+                description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom` (100% minus any reserved tail).
               params:
                 default: {}
-                description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+                description: Per-variant **override map** — a subset of the universe's `param_schema` keys. A key the variant doesn't set inherits the universe default. Unknown keys (not in the universe schema) are rejected.
                 type: object
                 additionalProperties: {}
             required:
               - name
               - weight
             additionalProperties: false
-            description: One variant in the experiment. Weights across all groups must sum to 10000.
-          description: Two or more variants. Weights must sum to exactly 10000 (100%). Immutable while running.
+            description: One variant. Its `params` may only override keys declared on the universe schema.
+          description: Two or more variants. Weights must sum to `10000 − reserved_headroom`. Existing weights are immutable while running, but a new variant may be appended into the reserved tail.
         significance_threshold:
           default: 0.05
           description: p-value cutoff used by the analysis pass. Defaults to `0.05`. Values other than 0.05 require Pro plan or higher.
@@ -8357,150 +9036,6 @@ components:
         - id
         - name
       additionalProperties: false
-    GetExperimentResponse:
-      type: object
-      properties:
-        id:
-          type: string
-          description: Stable opaque experiment id (`exp_…`).
-        name:
-          type: string
-          maxLength: 128
-          pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
-          description: Stable experiment key. Single segment or `folder.name` (a-z, 0-9, `_`/`-`; max 128 chars). Used by SDKs as `Shipeasy.getExperiment(user, '<name>')`. Immutable after create.
-        description:
-          anyOf:
-            - type: string
-            - type: 'null'
-        hypothesis:
-          anyOf:
-            - type: string
-            - type: 'null'
-        tag:
-          anyOf:
-            - type: string
-            - type: 'null'
-        ownerEmail:
-          anyOf:
-            - type: string
-            - type: 'null'
-        audience:
-          anyOf:
-            - type: string
-            - type: 'null'
-        bucketBy:
-          anyOf:
-            - type: string
-              minLength: 1
-              maxLength: 128
-              pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
-              description: User-attribute name used as the bucketing key — e.g. `user_id` (default), `session_id`, `device_id`, or a custom attribute like `company_id` to keep a whole org on one variant. Defaults to `user_id` when omitted.
-            - type: 'null'
-        folder:
-          anyOf:
-            - type: string
-            - type: 'null'
-        status:
-          type: string
-          enum:
-            - draft
-            - running
-            - stopped
-            - archived
-        universe:
-          type: string
-          description: Universe name this experiment draws from.
-        targetingGate:
-          anyOf:
-            - type: string
-            - type: 'null'
-        allocationPct:
-          type: integer
-          minimum: -9007199254740991
-          maximum: 9007199254740991
-          description: Allocation in basis points (0–10000).
-        salt:
-          type: string
-        params:
-          type: object
-          additionalProperties:
-            type: string
-            enum:
-              - string
-              - bool
-              - number
-        groups:
-          type: array
-          items:
-            type: object
-            properties:
-              name:
-                type: string
-                minLength: 1
-                maxLength: 64
-                description: Group label (e.g. `control`, `treatment_a`). Max 64 chars.
-              weight:
-                type: integer
-                minimum: 0
-                maximum: 10000
-                description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
-              params:
-                default: {}
-                description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
-                type: object
-                additionalProperties: {}
-            required:
-              - name
-              - weight
-            additionalProperties: false
-            description: One variant in the experiment. Weights across all groups must sum to 10000.
-        significanceThreshold:
-          type: number
-        minRuntimeDays:
-          type: integer
-          minimum: -9007199254740991
-          maximum: 9007199254740991
-        minSampleSize:
-          type: integer
-          minimum: -9007199254740991
-          maximum: 9007199254740991
-        sequentialTesting:
-          type: boolean
-        startedAt:
-          anyOf:
-            - type: string
-            - type: 'null'
-          description: ISO-8601 timestamp the experiment last transitioned to `running`, or `null`.
-        stoppedAt:
-          anyOf:
-            - type: string
-            - type: 'null'
-        updatedAt:
-          type: string
-      required:
-        - id
-        - name
-        - description
-        - hypothesis
-        - tag
-        - ownerEmail
-        - audience
-        - bucketBy
-        - folder
-        - status
-        - universe
-        - targetingGate
-        - allocationPct
-        - salt
-        - params
-        - groups
-        - significanceThreshold
-        - minRuntimeDays
-        - minSampleSize
-        - sequentialTesting
-        - startedAt
-        - updatedAt
-      additionalProperties: false
     DeleteExperimentResponse:
       type: object
       properties:
@@ -8557,11 +9092,21 @@ components:
           anyOf:
             - type: string
             - type: 'null'
+        holdout_gate:
+          description: Per-experiment holdout gate — the name of a `holdout`-type flag, or `null` to clear. A caller the flag passes is held out.
+          anyOf:
+            - type: string
+            - type: 'null'
         allocation_pct:
           description: Basis-points allocation (0–10000). Use `allocation_percent` (0–100) for percent. Immutable while the experiment is running.
           type: integer
           minimum: 0
           maximum: 10000
+        reserved_headroom:
+          description: Basis points of the split kept empty for appended variants. Group weights must sum to `10000 − reserved_headroom`. May be shrunk (never grown into existing weights) while running when appending a variant.
+          type: integer
+          minimum: 0
+          maximum: 10000
         allocation_percent:
           description: Allocation as a **percentage** (0–100). Friendlier alias for `allocation_pct`; converted to basis points server-side. Wins over `allocation_pct` if both are supplied. Immutable while running.
           type: number
@@ -8583,9 +9128,9 @@ components:
               - string
               - bool
               - number
-          description: 'Map of param-name → scalar type. Defines the shape of `groups[].params`. Example: `{ headline: ''string'', show_cta: ''bool'' }`.'
+          description: '**Deprecated** — the universe owns the config schema (`param_schema`). Retained for back-compat. Map of param-name → scalar type.'
         groups:
-          description: Replacement groups. Weights must sum to 10000. Immutable while running.
+          description: Replacement groups. Weights must sum to `10000 − reserved_headroom`. Existing weights/values are immutable while running; a new variant may be appended into the reserved tail.
           minItems: 2
           type: array
           items:
@@ -8600,17 +9145,17 @@ components:
                 type: integer
                 minimum: 0
                 maximum: 10000
-                description: Allocation weight in basis points (0–10000). The sum across all groups must equal exactly **10000** (100%).
+                description: Allocation weight in basis points (0–10000). Weights across all groups must sum to `10000 − reserved_headroom`.
               params:
                 default: {}
-                description: Per-group parameter values delivered to the SDK when a caller is hashed into this group. Keys must match the experiment's `params` schema.
+                description: Per-variant **override map** — a subset of the universe's `param_schema` keys. Unknown keys are rejected; unset keys inherit the universe default.
                 type: object
                 additionalProperties: {}
             required:
               - name
               - weight
             additionalProperties: false
-            description: One variant in the experiment. Weights across all groups must sum to 10000.
+            description: One variant. Its `params` may only override keys declared on the universe schema.
         significance_threshold:
           type: number
           minimum: 0.0001
@@ -8635,7 +9180,7 @@ components:
           items:
             $ref: '#/components/schemas/ExperimentInlineMetric'
       additionalProperties: false
-      description: Body for `PATCH /api/admin/experiments/{id}`. Partial — only supplied fields change. `allocation_pct`, `groups`, `salt`, `universe`, `params` are immutable while the experiment is running (stop first).
+      description: Body for `PATCH /api/admin/experiments/{id}`. Partial — only supplied fields change. `allocation_pct`, `salt`, `universe` and existing group weights/values are immutable while running (stop first); a new variant may still be appended into the reserved tail.
     UpdateExperimentResponse:
       type: object
       properties:
@@ -8694,6 +9239,12 @@ components:
                   - guardrail
                   - secondary
                 description: Metric role. `goal` drives the decision, `guardrail` blocks ship if degraded, `secondary` is informational.
+              min_effect_of_interest:
+                description: Per-experiment override of the metric's `default_min_effect_of_interest` (relative, 0–1) — the smallest change worth acting on for THIS experiment's decision, which depends on the intervention's cost/risk. `null`/omitted falls back to the metric default. For a `guardrail` this is the non-inferiority margin (how large a regression is tolerated); for a `goal` it is the superiority threshold.
+                default: null
+                anyOf:
+                  - type: number
+                  - type: 'null'
             required:
               - metric_id
               - role
@@ -8721,9 +9272,15 @@ components:
                   - goal
                   - guardrail
                   - secondary
+              min_effect_of_interest:
+                description: The resolved per-experiment override, or `null` when this attachment inherits the metric's `default_min_effect_of_interest`.
+                anyOf:
+                  - type: number
+                  - type: 'null'
             required:
               - metric_id
               - role
+              - min_effect_of_interest
             additionalProperties: false
       required:
         - id
@@ -8787,6 +9344,11 @@ components:
                   - type: number
                   - type: 'null'
                 description: '`1` if sample-ratio mismatch detected, else `0`.'
+              realized_mde:
+                anyOf:
+                  - type: number
+                  - type: 'null'
+                description: Realized minimum detectable effect (absolute, in metric units) — the smallest true effect this run could detect at the experiment's significance level and target power GIVEN the observed variance and per-arm sample sizes. A derived OUTPUT, not an input knob; compare it against the metric's minimum effect of interest to judge whether the run is adequately powered. `null` on the control row and on empty arms.
             required:
               - metric
               - group_name
@@ -8796,6 +9358,7 @@ components:
               - delta_pct
               - p_value
               - srm_detected
+              - realized_mde
             additionalProperties: false
         verdict:
           type: string
@@ -9602,6 +10165,35 @@ components:
         - version
         - published
       additionalProperties: false
+    UniverseParam:
+      type: object
+      properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 128
+          pattern: ^[a-zA-Z_][a-zA-Z0-9_]*$
+          description: Param key, referenced by `groups[].params` on every experiment in the universe.
+        type:
+          type: string
+          enum:
+            - bool
+            - string
+            - int
+            - number
+          description: Scalar type of the param's value.
+        default:
+          description: 'Universe-wide default. Returned when the assigned variant doesn''t override this param (resolution: variant override → universe default).'
+      required:
+        - name
+        - type
+        - default
+      additionalProperties: false
+    UniverseParamSchema:
+      type: array
+      items:
+        $ref: '#/components/schemas/UniverseParam'
+      description: The universe's ordered config schema — the single source of truth for its params.
     ListUniversesResponse:
       type: object
       properties:
@@ -9618,6 +10210,11 @@ components:
                 maxLength: 128
                 pattern: ^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$
                 description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
+              description:
+                anyOf:
+                  - type: string
+                  - type: 'null'
+                description: Human-readable blurb shown in the universe picker/hovercard.
               unitType:
                 type: string
                 description: Unit of randomisation. Snake-case in request (`unit_type`), camelCase in response.
@@ -9630,6 +10227,16 @@ components:
                     maxItems: 2
                   - type: 'null'
                 description: Reserved holdout bucket range, or `null` if none.
+              recommendedHeadroom:
+                type: integer
+                minimum: 0
+                maximum: 10000
+                description: Basis points of headroom seeded into each new experiment's reserved tail (0 = none).
+              paramSchema:
+                anyOf:
+                  - $ref: '#/components/schemas/UniverseParamSchema'
+                  - type: 'null'
+                description: The universe-owned config schema, or `null` on pre-rework universes not yet seeded.
               createdAt:
                 type: string
                 description: ISO-8601 timestamp of creation.
@@ -9658,6 +10265,13 @@ components:
           description: Stable universe key. Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create.
         folder:
           $ref: '#/components/schemas/Folder'
+        description:
+          default: null
+          anyOf:
+            - type: string
+              maxLength: 2000
+            - type: 'null'
+          description: Human-readable blurb shown in the universe picker/hovercard.
         unit_type:
           default: user_id
           description: Unit of randomisation. Typically `user_id`. Use `account_id` to keep whole accounts in the same group across an experiment.
@@ -9674,6 +10288,18 @@ components:
               maxItems: 2
             - type: 'null'
           description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
+        recommended_headroom:
+          default: 0
+          type: integer
+          minimum: 0
+          maximum: 10000
+          description: Basis points of reserved headroom seeded into each new experiment created in this universe (0 = none). Lets variants be appended into a running experiment without reshuffling.
+        param_schema:
+          default: null
+          anyOf:
+            - $ref: '#/components/schemas/UniverseParamSchema'
+            - type: 'null'
+          description: The universe-owned config schema — an ordered `{ name, type, default }[]`. Experiments may only override values per variant, never add fields. `null` starts an empty schema.
       required:
         - name
       additionalProperties: false
@@ -9707,6 +10333,12 @@ components:
       properties:
         folder:
           $ref: '#/components/schemas/Folder'
+        description:
+          anyOf:
+            - type: string
+              maxLength: 2000
+            - type: 'null'
+          description: Human-readable blurb shown in the universe picker/hovercard.
         holdout_range:
           anyOf:
             - type: array
@@ -9718,8 +10350,18 @@ components:
               maxItems: 2
             - type: 'null'
           description: Inclusive `[lo, hi]` bucket range (0–9999) reserved as the **holdout** — callers hashed into this slice are excluded from every experiment in the universe. `null` disables the holdout. Pro plan or higher required.
+        recommended_headroom:
+          type: integer
+          minimum: 0
+          maximum: 10000
+          description: Basis points of reserved headroom seeded into new experiments in this universe.
+        param_schema:
+          anyOf:
+            - $ref: '#/components/schemas/UniverseParamSchema'
+            - type: 'null'
+          description: Replace the universe config schema. Additive changes + default edits are always allowed; removing a param a running experiment overrides is rejected (deprecate-only).
       additionalProperties: false
-      description: Body for `PATCH /api/admin/universes/{id}`. Only `holdout_range` is mutable — name and unit_type are immutable after create.
+      description: Body for `PATCH /api/admin/universes/{id}`. `name` and `unit_type` are immutable after create; `holdout_range`, `description`, `recommended_headroom` and `param_schema` are mutable.
     UpdateUniverseResponse:
       type: object
       properties:
@@ -9729,7 +10371,7 @@ components:
       required:
         - id
       additionalProperties: false
-    GateTemplateRule:
+    GateTemplateRuleResponse:
       type: object
       properties:
         attr:
@@ -9760,9 +10402,8 @@ components:
       required:
         - attr
         - op
-        - value
       additionalProperties: false
-      description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
+      description: Single targeting predicate as returned by the API. `value` is optional here — read-only built-in templates (e.g. `@owner`, or presets whose operand is supplied at substitution time) legitimately omit it. Request bodies still require `value`.
     GateTemplate:
       type: object
       description: 'A reusable targeting-rule template. Built-ins are read-only (`builtin: true`, stable slug `id`); per-project customer templates are `builtin: false` with a `gtpl_…` id.'
@@ -9796,7 +10437,7 @@ components:
         rules:
           type: array
           items:
-            $ref: '#/components/schemas/GateTemplateRule'
+            $ref: '#/components/schemas/GateTemplateRuleResponse'
           description: The rule definition — copy, substitute the value(s), pass as `rules`.
         createdAt:
           anyOf:
@@ -9832,6 +10473,46 @@ components:
         - data
         - next_cursor
       additionalProperties: false
+    GateTemplateRule:
+      type: object
+      properties:
+        attr:
+          type: string
+          description: Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` "in any experiment" preset — you fill in the experiment name).
+        op:
+          type: string
+          enum:
+            - eq
+            - neq
+            - in
+            - not_in
+            - gt
+            - gte
+            - lt
+            - lte
+            - contains
+            - regex
+            - semver_gt
+            - semver_gte
+            - semver_lt
+            - semver_lte
+            - gate_pass
+            - exp_in
+          description: 'Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate''s name), `exp_in` (attr is an experiment name, value is a variant / `"$holdout"` / `"$any"`).'
+        value:
+          description: 'Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`. Required on every request rule (value-ops need it; the valueless built-in presets are read-only and never created via the API).'
+          anyOf:
+            - type: string
+            - type: number
+            - type: boolean
+            - type: array
+              items: {}
+      required:
+        - attr
+        - op
+        - value
+      additionalProperties: false
+      description: Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`.
     CreateGateTemplateRequest:
       type: object
       description: Body for `POST /api/admin/gate-templates`. Creates a per-project (customer) template. At minimum supply `name` + `rules`.
@@ -10393,8 +11074,8 @@ components:
           winsorizePct:
             description: Winsorise percentile applied to the metric.
             type: number
-          minDetectableEffect:
-            description: Configured MDE, or `null`.
+          defaultMinEffectOfInterest:
+            description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
             anyOf:
               - type: number
               - type: 'null'
@@ -10429,9 +11110,9 @@ components:
       type: integer
       minimum: 1
       maximum: 99
-    MetricMinDetectableEffect:
+    MetricDefaultMinEffectOfInterest:
       default: null
-      description: Minimum detectable effect (relative, 0–1) for power planning. `null` to omit.
+      description: Default minimum effect of interest (relative, 0–1) — the smallest change in this metric worth acting on, used as the power-planning baseline. Intrinsic to the metric; an experiment overrides it per-attachment with `min_effect_of_interest` when a specific decision has a different cost/risk bar. `null` to omit.
       anyOf:
         - type: number
         - type: 'null'
@@ -10456,8 +11137,8 @@ components:
           $ref: '#/components/schemas/MetricQueryDsl'
         winsorize_pct:
           $ref: '#/components/schemas/MetricWinsorizePct'
-        min_detectable_effect:
-          $ref: '#/components/schemas/MetricMinDetectableEffect'
+        default_min_effect_of_interest:
+          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
       required:
@@ -10479,8 +11160,8 @@ components:
           $ref: '#/components/schemas/QueryIr'
         winsorize_pct:
           $ref: '#/components/schemas/MetricWinsorizePct'
-        min_detectable_effect:
-          $ref: '#/components/schemas/MetricMinDetectableEffect'
+        default_min_effect_of_interest:
+          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
       required:
@@ -10542,8 +11223,8 @@ components:
         winsorizePct:
           description: Winsorise percentile applied to the metric.
           type: number
-        minDetectableEffect:
-          description: Configured MDE, or `null`.
+        defaultMinEffectOfInterest:
+          description: Metric-level default minimum effect of interest (relative, 0–1), or `null`.
           anyOf:
             - type: number
             - type: 'null'
@@ -10583,8 +11264,8 @@ components:
           $ref: '#/components/schemas/MetricQueryDsl'
         winsorize_pct:
           $ref: '#/components/schemas/MetricWinsorizePct'
-        min_detectable_effect:
-          $ref: '#/components/schemas/MetricMinDetectableEffect'
+        default_min_effect_of_interest:
+          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
       required:
@@ -10602,8 +11283,8 @@ components:
           $ref: '#/components/schemas/QueryIr'
         winsorize_pct:
           $ref: '#/components/schemas/MetricWinsorizePct'
-        min_detectable_effect:
-          $ref: '#/components/schemas/MetricMinDetectableEffect'
+        default_min_effect_of_interest:
+          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
       required:
@@ -10619,12 +11300,12 @@ components:
           $ref: '#/components/schemas/MetricEventName'
         winsorize_pct:
           $ref: '#/components/schemas/MetricWinsorizePct'
-        min_detectable_effect:
-          $ref: '#/components/schemas/MetricMinDetectableEffect'
+        default_min_effect_of_interest:
+          $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
       additionalProperties: false
-      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, MDE, direction).
+      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
     UpdateMetricRequest:
       oneOf:
         - $ref: '#/components/schemas/UpdateMetricWithQuery'
@@ -11293,6 +11974,11 @@ components:
           items:
             type: string
           description: Distinct, id-normalized routes this error has surfaced on (UUIDs/ids collapsed to `#`).
+        stackTail:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The last 3 non-empty lines of the latest occurrence's stack — the innermost frames closest to where the throw bubbled out, baked in as an at-a-glance locator. `null` when the source supplied no stack. Fetch the full stack via `related.error`.
         sdkVersion:
           anyOf:
             - type: string
@@ -11482,6 +12168,11 @@ components:
     OpsMeasurePlanContext:
       type: object
       properties:
+        goal:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The customer's underlying intent in their own words — WHAT they want to learn or achieve and WHY, independent of the specific steps. The plan below is a best-effort proposal made without repo access; when the code reveals a better path, this goal is the target you optimize for, not literal step-adherence.
         created:
           type: array
           items:
@@ -11888,6 +12579,91 @@ components:
         - id
       additionalProperties: false
       description: Response for the update / link-pr endpoints.
+    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
+      additionalProperties: false
+      description: Response for `GET /api/admin/ops/{handle}/comments` — the thread, oldest first.
+    CreateOpsCommentRequest:
+      type: object
+      properties:
+        body:
+          type: string
+          minLength: 1
+          maxLength: 10000
+          description: The comment body as markdown. Mentions (`@teammate`, `@shipeasy`) are parsed from it.
+        parentId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: Reply under this top-level comment. Omit / `null` for a top-level comment. Replying to a reply attaches to the same top-level parent (threading is one level deep).
+      required:
+        - body
+      additionalProperties: false
+      description: Body for `POST /api/admin/ops/{handle}/comments`.
+    CreateOpsCommentResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Newly created comment id.
+      required:
+        - id
+      additionalProperties: false
+      description: Response for `POST /api/admin/ops/{handle}/comments`.
     NotifyOpsRequest:
       type: object
       properties:
@@ -11907,8 +12683,10 @@ components:
           items:
             type: string
         href:
-          description: Dashboard-relative deep link to the related item.
-          type: string
+          description: Dashboard-relative deep link to the related item. `null` is accepted and treated as "no link".
+          anyOf:
+            - type: string
+            - type: 'null'
         dedupeKey:
           description: Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.
           type: string
@@ -12158,7 +12936,9 @@ components:
           type: string
           enum:
             - free
-            - paid
+            - pro
+            - business
+            - enterprise
           description: Billing plan tier.
         status:
           type: string
@@ -12213,6 +12993,50 @@ components:
             - type: boolean
             - type: number
           description: Whether the feedback/ops module is enabled.
+        minSampleSize:
+          type: integer
+          description: Verdict power guard — minimum users per arm before a ship/hold verdict.
+        minRuntimeDays:
+          type: integer
+          description: Minimum days an experiment must run before a verdict (peeking guard).
+        defaultPower:
+          type: number
+          description: Target statistical power (1−β) feeding the realized-MDE calculation.
+        ciConfidence:
+          type: number
+          description: Confidence level for the interval surfaced on results.
+        defaultAllocationPct:
+          type: integer
+          description: Default traffic allocation (basis points) new experiments start with.
+        defaultHoldout:
+          type: integer
+          description: Default holdout carve-out (basis points) that seeds each new universe's holdout.
+        defaultWinsorizePct:
+          type: integer
+          description: Default winsorization percentile new metrics start with.
+        defaultMei:
+          anyOf:
+            - type: number
+            - type: 'null'
+          description: Default minimum effect of interest (relative, 0–1) new metrics start with, or null.
+        cupedBaselineDays:
+          type: integer
+          description: CUPED baseline window — days of pre-experiment history, frozen at start.
+        cupedMinOverlap:
+          type: number
+          description: CUPED selection-bias guard — min share of users with a baseline, else skip.
+        cupedMinBaselineUsers:
+          type: integer
+          description: CUPED — minimum users with a baseline before it runs at all.
+        msprtTauMeiFactor:
+          type: number
+          description: mSPRT prior width — τ = minimum effect of interest × this factor.
+        msprtTauSdFactor:
+          type: number
+          description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
+        srmThreshold:
+          type: number
+          description: SRM chi-square p-value below which the run is called invalid.
         createdAt:
           type: string
           description: ISO-8601 timestamp of project creation.
@@ -12363,6 +13187,78 @@ components:
         moduleEvents:
           type: boolean
           description: Enable/disable the events module.
+        minSampleSize:
+          type: integer
+          minimum: 2
+          maximum: 1000000
+          description: Verdict power guard — minimum users per arm before a ship/hold verdict.
+        minRuntimeDays:
+          type: integer
+          minimum: 0
+          maximum: 365
+          description: Minimum days an experiment must run before a verdict (peeking guard).
+        defaultPower:
+          type: number
+          minimum: 0.5
+          maximum: 0.99
+          description: Target statistical power (1−β) feeding the realized-MDE calculation.
+        ciConfidence:
+          type: number
+          minimum: 0.5
+          maximum: 0.999
+          description: Confidence level for the interval surfaced on results (any value in [0.5, 0.999], e.g. 0.90, 0.95, 0.975, 0.99).
+        defaultAllocationPct:
+          type: integer
+          minimum: 1
+          maximum: 10000
+          description: Default traffic allocation (basis points, 1000 = 10%) new experiments start with; overridable per experiment.
+        defaultHoldout:
+          type: integer
+          minimum: 0
+          maximum: 10000
+          description: Default holdout carve-out (basis points) that seeds each new universe's holdout (0 = none).
+        defaultWinsorizePct:
+          type: integer
+          minimum: 1
+          maximum: 99
+          description: Default winsorization percentile new metrics start with; overridable per metric.
+        defaultMei:
+          anyOf:
+            - type: number
+              minimum: 0
+              maximum: 1
+            - type: 'null'
+          description: Default minimum effect of interest (relative, 0–1) new metrics start with; overridable per metric and per experiment. Null clears it.
+        cupedBaselineDays:
+          type: integer
+          minimum: 1
+          maximum: 365
+          description: CUPED baseline window — days of pre-experiment history, frozen at start.
+        cupedMinOverlap:
+          type: number
+          minimum: 0.01
+          maximum: 0.99
+          description: CUPED selection-bias guard — min share of users with a baseline, else skip.
+        cupedMinBaselineUsers:
+          type: integer
+          minimum: 10
+          maximum: 100000
+          description: CUPED — minimum users with a baseline before it runs at all.
+        msprtTauMeiFactor:
+          type: number
+          minimum: 0.1
+          maximum: 2
+          description: mSPRT prior width — τ = minimum effect of interest × this factor.
+        msprtTauSdFactor:
+          type: number
+          minimum: 0.05
+          maximum: 1
+          description: mSPRT fallback prior width — τ = this × control SD when no MEI is set.
+        srmThreshold:
+          type: number
+          minimum: 0.0001
+          maximum: 0.05
+          description: SRM chi-square p-value below which the run is called invalid.
       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:
@@ -12839,6 +13735,59 @@ components:
         - kv_verified
       additionalProperties: false
       description: Result of a one-shot set-and-publish.
+    ErrorOccurrence:
+      type: object
+      description: One sampled instance behind a tracked error — the minimal per-occurrence payload (what varies between instances; everything else lives on the parent `ErrorRecord`).
+      properties:
+        id:
+          type: string
+          description: Stable opaque occurrence id.
+        message:
+          type: string
+          description: This instance's raw message (unlike the fingerprint, never normalized).
+        stack:
+          description: This instance's stack trace, or `null` if none was captured.
+          anyOf:
+            - type: string
+            - type: 'null'
+        url:
+          description: This instance's raw URL (ids intact), or `null`.
+          anyOf:
+            - type: string
+            - type: 'null'
+        env:
+          description: Published env this instance ran against, or `null`.
+          anyOf:
+            - type: string
+            - type: 'null'
+        side:
+          description: Which SDK side reported it — `client` or `server`. `null` if unknown.
+          anyOf:
+            - type: string
+            - type: 'null'
+        sdkVersion:
+          description: '`@shipeasy/sdk` version of this instance, or `null`.'
+          anyOf:
+            - type: string
+            - type: 'null'
+        extrasJson:
+          description: This instance's sanitized extras, JSON-encoded. `null` if none.
+          anyOf:
+            - type: string
+            - type: 'null'
+        sampleRate:
+          type: integer
+          minimum: 1
+          description: 1-in-N sampling rate in force when this instance was kept (`1` = the issue was still being recorded exhaustively).
+        seenAt:
+          type: string
+          description: ISO-8601 timestamp this instance was ingested.
+      required:
+        - id
+        - message
+        - sampleRate
+        - seenAt
+      additionalProperties: false
     ErrorRecord:
       type: object
       description: |-
@@ -12854,7 +13803,7 @@ components:
           description: Project this issue belongs to.
         fingerprint:
           type: string
-          description: Stable dedupe key (hash of `errorType` + normalized `message` + consequence). Unique per project — every occurrence with the same fingerprint folds into this one row.
+          description: Stable dedupe key — the issue TITLE (hash of `errorType` + `subject` + `outcome`, plus the violation name for violations). Unique per project — every occurrence with the same title folds into this one row; per-instance variety (message/stack/extras) lives in `occurrences`.
         causedByFingerprint:
           description: Fingerprint of the issue this one descends from — set when `see()` reported the same error (re-throw) or its `{ cause }` (wrap) at an inner boundary first. Points at another error's `fingerprint` in the same project (soft reference, no FK). `null` for a root issue.
           anyOf:
@@ -12932,7 +13881,12 @@ components:
         count:
           type: integer
           minimum: 1
-          description: Number of folded occurrences for this fingerprint.
+          description: EXACT number of folded occurrences for this fingerprint — every occurrence increments it, regardless of detail-row sampling.
+        occurrences:
+          type: array
+          description: Sampled per-instance detail rows behind this issue, newest first. Returned only by `GET /api/admin/errors/{id}` (never in list responses). The parent row's `count` / `firstSeenAt` / `lastSeenAt` are exact; these rows are a *sampled sketch* of the instances — exhaustive while the issue is small, thinning to roughly 1-in-10 past 10 occurrences, 1-in-100 past 100, and 1-in-1000 past 1000 (each row's `sampleRate` records the rate in force when it was kept), capped at the newest 100 rows.
+          items:
+            $ref: '#/components/schemas/ErrorOccurrence'
         status:
           type: string
           enum:
@@ -12966,7 +13920,7 @@ components:
       additionalProperties: false
     ListErrorsResponse:
       type: array
-      description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size.
+      description: A bare JSON array of tracked errors, ordered by `lastSeenAt` descending. There is no pagination envelope — `limit` caps the page size. List rows never include `occurrences` — read one error to get them.
       items:
         $ref: '#/components/schemas/ErrorRecord'
     UpdateErrorStatusRequest:
@@ -13478,33 +14432,27 @@ components:
       properties:
         ok:
           type: boolean
-          description: '`true` when the trigger run was successfully kicked off; `false` when the dispatch itself failed (still HTTP 200, with `error` set).'
-        error:
-          type: string
-          description: Failure reason. Present only when `ok` is `false` — the fire reached the handler but the underlying dispatch to the provider failed.
+          description: Always `true` — a successful fire returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
       required:
         - ok
       additionalProperties: false
-      description: 'Result of firing a trigger connector. `{ ok: true }` on success; `{ ok: false, error }` when the dispatch fails (the request still returns HTTP 200).'
+      description: 'Result of a successful trigger fire: `{ ok: true }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
     TestConnectorResponse:
       type: object
       properties:
         ok:
           type: boolean
-          description: '`true` when the test dispatch reached the destination; `false` when the dispatch itself failed (still HTTP 200, with `error` set).'
+          description: Always `true` — a successful test returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body.
         issueUrl:
           anyOf:
             - type: string
             - type: 'null'
-          description: URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact (or the dispatch failed).
-        error:
-          type: string
-          description: Failure reason. Present only when `ok` is `false` — the test reached the handler but the underlying dispatch to the provider failed.
+          description: URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact.
       required:
         - ok
         - issueUrl
       additionalProperties: false
-      description: 'Result of testing a connector. `{ ok: true, issueUrl }` on success; `{ ok: false, issueUrl: null, error }` when the dispatch fails (the request still returns HTTP 200).'
+      description: 'Result of a successful connector test: `{ ok: true, issueUrl }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`.'
     UpdateClaudeTriggerRequest:
       type: object
       properties:
@@ -13753,7 +14701,8 @@ components:
               - events:write
               - configs:write
               - experiments:write
-          description: Optional permission strings recorded on the key for audit/display.
+              - tickets:public_create
+          description: 'Optional permission strings recorded on the key. `tickets:public_create` is enforced: a client key needs it (plus the project''s `allowPublicTickets` setting) to file a `pending_approval` bug via the public `POST /cli/report` endpoint. The rest are audit/display only.'
         expiresInDays:
           anyOf:
             - type: integer
@@ -13977,3 +14926,18 @@ components:
               value:
                 error: The referenced event is still pending review and cannot back a metric yet.
                 code: EVENT_PENDING
+    BadGateway:
+      description: |-
+        The request was well-formed and the resource exists, but a downstream provider
+        the endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)
+        failed. The failure is upstream of this API, not a client error. No stable
+        `ErrorCode` is assigned to upstream failures, so `code` is omitted.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            UPSTREAM_FAILURE:
+              summary: Downstream provider dispatch failed
+              value:
+                error: 'GitHub API responded 403: resource not accessible by integration.'