@shipeasy/openapi 2.2.0 → 2.3.0

package/openapi.yaml

@@ -178,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.
@@ -433,6 +443,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -943,7 +954,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/GetExperimentResponse'
+                $ref: '#/components/schemas/ExperimentApiRow'
               example:
                 id: exp_01j7wb12c3d4e5f6g7h8j9k0l1
                 name: checkout_button_color
@@ -1081,6 +1092,7 @@ paths:
         - GROUPS_WEIGHT_SUM
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - EXPERIMENT_IMMUTABLE_FIELD
       x-cli:
         name: update
         positional:
@@ -1219,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
@@ -1313,6 +1331,7 @@ paths:
         - EVENT_PENDING
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - METRIC_UNKNOWN_ID
       x-cli:
         name: set-metrics
         positional:
@@ -1708,6 +1727,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -2428,6 +2448,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -2982,6 +3003,7 @@ paths:
         - PLAN_REQUIRED
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -3794,6 +3816,7 @@ paths:
         - EVENT_PENDING
         - REFERENCED_NOT_FOUND
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -4098,6 +4121,7 @@ paths:
         - FORBIDDEN
         - ALREADY_EXISTS
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
         positional:
@@ -4692,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
@@ -4924,6 +5059,7 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - ALREADY_EXISTS
+        - METRIC_NOT_FOUND
         - REFERENCED_NOT_FOUND
         - VALIDATION
       x-cli:
@@ -5076,7 +5212,7 @@ paths:
                 name: Acme
                 domain: acme.com
                 ownerEmail: owner@acme.com
-                plan: paid
+                plan: pro
                 status: active
                 subscriptionStatus: active
                 billingInterval: monthly
@@ -5223,7 +5359,7 @@ paths:
                 name: Acme Rockets
                 domain: acme.com
                 ownerEmail: owner@acme.com
-                plan: paid
+                plan: pro
                 status: active
                 subscriptionStatus: active
                 billingInterval: monthly
@@ -5915,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:
@@ -5961,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':
@@ -6122,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
@@ -7131,6 +7361,7 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - VALIDATION
+        - PLAN_LIMIT
       x-cli:
         name: create
   /api/admin/keys/{id}/revoke:
@@ -7309,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
@@ -7600,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.
@@ -7616,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
@@ -7631,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
@@ -7649,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.
@@ -7950,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
@@ -8241,155 +8518,292 @@ components:
         - id
         - enabled
       additionalProperties: false
-    ListExperimentsResponse:
+    ExperimentApiRow:
       type: object
       properties:
-        data:
+        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
@@ -8433,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:
@@ -8495,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
@@ -8510,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
@@ -8524,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
@@ -8540,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.
@@ -8566,188 +8997,44 @@ components:
           maximum: 365
         min_sample_size:
           default: 100
-          description: Minimum exposures per group before results are considered conclusive.
-          type: integer
-          minimum: 1
-          maximum: 9007199254740991
-        sequential_testing:
-          default: false
-          description: Enable sequential testing (always-valid p-values). Requires Premium plan or higher.
-          type: boolean
-        goal_metric:
-          description: Single goal metric defined inline — either a DSL `query` or an `event` (+`aggregation`/`value`) the server compiles. Attaching one is required before the experiment can be started. The underlying event is auto-created if missing.
-          $ref: '#/components/schemas/ExperimentInlineMetric'
-        guardrail_metrics:
-          default: []
-          description: Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail.
-          maxItems: 10
-          type: array
-          items:
-            $ref: '#/components/schemas/ExperimentInlineMetric'
-      required:
-        - name
-        - universe
-        - groups
-      additionalProperties: false
-      description: Body for `POST /api/admin/experiments`. `name`, `universe`, and `groups` (≥2, weights sum to 10000) required.
-    CreateExperimentResponse:
-      type: object
-      properties:
-        id:
-          type: string
-          description: Newly assigned experiment id.
-        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.
-      required:
-        - 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
+          description: Minimum exposures per group before results are considered conclusive.
+          type: integer
+          minimum: 1
+          maximum: 9007199254740991
+        sequential_testing:
+          default: false
+          description: Enable sequential testing (always-valid p-values). Requires Premium plan or higher.
+          type: boolean
+        goal_metric:
+          description: Single goal metric defined inline — either a DSL `query` or an `event` (+`aggregation`/`value`) the server compiles. Attaching one is required before the experiment can be started. The underlying event is auto-created if missing.
+          $ref: '#/components/schemas/ExperimentInlineMetric'
+        guardrail_metrics:
+          default: []
+          description: Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail.
+          maxItems: 10
+          type: array
+          items:
+            $ref: '#/components/schemas/ExperimentInlineMetric'
       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: Body for `POST /api/admin/experiments`. `name`, `universe`, and `groups` (≥2, weights sum to 10000) required.
+    CreateExperimentResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          description: Newly assigned experiment id.
+        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.
+      required:
+        - id
+        - name
       additionalProperties: false
     DeleteExperimentResponse:
       type: object
@@ -8805,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
@@ -8831,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:
@@ -8848,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
@@ -8883,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:
@@ -8942,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
@@ -8969,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
@@ -9035,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
@@ -9044,6 +9358,7 @@ components:
               - delta_pct
               - p_value
               - srm_detected
+              - realized_mde
             additionalProperties: false
         verdict:
           type: string
@@ -9850,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:
@@ -9866,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.
@@ -9878,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.
@@ -9906,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.
@@ -9922,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
@@ -9955,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
@@ -9966,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:
@@ -10680,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'
@@ -10716,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'
@@ -10743,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:
@@ -10766,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:
@@ -10829,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'
@@ -10870,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:
@@ -10889,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:
@@ -10906,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'
@@ -11580,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
@@ -11769,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:
@@ -12175,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:
@@ -12447,7 +12936,9 @@ components:
           type: string
           enum:
             - free
-            - paid
+            - pro
+            - business
+            - enterprise
           description: Billing plan tier.
         status:
           type: string
@@ -12502,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.
@@ -12652,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:
@@ -13128,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: |-
@@ -13143,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:
@@ -13221,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:
@@ -13255,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:
@@ -14036,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