@shipeasy/openapi 2.2.0 → 2.3.0

package/openapi.json

@@ -98,6 +98,11 @@
       },
       "description": "Alert rules: the metric-threshold definitions the analysis cron evaluates each run.\n\n**What fires.** Each rule binds a `metricId`, a `comparator` (`gt`/`gte`/`lt`/`lte`), and a `threshold`. On every cron pass the cron aggregates the metric over the trailing `windowHours` and raises an alert at `severity` when `value comparator threshold` holds.\n\n**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.\n\n**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,\nfeature request, or auto-filed error/alert ticket. Append a comment or read\nthe thread; one level of threaded replies via `parentId`.\n\n**Mentions.** `@teammate` in a body raises an in-app notification for that\nperson; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.\nComments authored by Jarvis carry `authorType: system`."
+    },
     {
       "name": "Projects",
       "description": "Projects: the account-level container every other resource is scoped to.\n\n**Account-level, not bound-project-level.** Both operations resolve from the caller's credential rather than the `.shipeasy`-bound project — `current` reads the project the auth header maps to, and `upsert` find-or-creates under the session's owner. Neither touches the local `.shipeasy` binding; recording the result there is a consumer side-effect layered on top.\n\n**Idempotent upsert.** A project is keyed by `(owner_email, domain)`. Calling `upsert` again with the same domain returns the existing project with `created: false`, so it is safe to run on every install."
@@ -415,7 +420,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -1136,7 +1142,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetExperimentResponse"
+                  "$ref": "#/components/schemas/ExperimentApiRow"
                 },
                 "example": {
                   "id": "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
@@ -1324,7 +1330,8 @@
           "INVALID_TRANSITION",
           "GROUPS_WEIGHT_SUM",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "EXPERIMENT_IMMUTABLE_FIELD"
         ],
         "x-cli": {
           "name": "update",
@@ -1504,7 +1511,13 @@
           "FORBIDDEN",
           "NOT_FOUND",
           "INVALID_TRANSITION",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT",
+          "EXPERIMENT_NO_GOAL_METRIC",
+          "EXPERIMENT_ARCHIVED_RESTART",
+          "EXPERIMENT_NOT_RUNNING",
+          "EXPERIMENT_RUNNING_ARCHIVE",
+          "EXPERIMENT_RESTORE_INVALID"
         ],
         "x-cli": {
           "positional": [
@@ -1643,7 +1656,8 @@
           "NOT_FOUND",
           "EVENT_PENDING",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "METRIC_UNKNOWN_ID"
         ],
         "x-cli": {
           "name": "set-metrics",
@@ -2223,7 +2237,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -3271,7 +3286,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -4030,7 +4046,8 @@
           "FORBIDDEN",
           "PLAN_REQUIRED",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -5194,7 +5211,8 @@
           "ALREADY_EXISTS",
           "EVENT_PENDING",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -5623,7 +5641,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -6470,6 +6489,156 @@
         }
       }
     },
+    "/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\ncarries its author (a teammate email, or `system` for a comment authored by\nJarvis — the AI agent), its markdown body, and `parentId` for the single\nlevel of threaded replies. Removed comments are omitted.\n\n**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\nlike `@teammate` notify that person; `@shipeasy` asks Jarvis, the AI agent,\nto reply). Pass `parentId` to reply under an existing top-level comment\n(one level of threading — a reply to a reply attaches to the same parent).\n\nCreate-only and append-only, so it is safe for restricted ops keys — the\nsame 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",
@@ -6791,6 +6960,7 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
+          "METRIC_NOT_FOUND",
           "REFERENCED_NOT_FOUND",
           "VALIDATION"
         ],
@@ -6996,7 +7166,7 @@
                   "name": "Acme",
                   "domain": "acme.com",
                   "ownerEmail": "owner@acme.com",
-                  "plan": "paid",
+                  "plan": "pro",
                   "status": "active",
                   "subscriptionStatus": "active",
                   "billingInterval": "monthly",
@@ -7191,7 +7361,7 @@
                   "name": "Acme Rockets",
                   "domain": "acme.com",
                   "ownerEmail": "owner@acme.com",
-                  "plan": "paid",
+                  "plan": "pro",
                   "status": "active",
                   "subscriptionStatus": "active",
                   "billingInterval": "monthly",
@@ -8167,7 +8337,7 @@
       "get": {
         "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.\n\n**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.",
+        "description": "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.\n\n**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"
         ],
@@ -8216,7 +8386,33 @@
                   "firstSeenAt": "2026-06-20T08:11:02.000Z",
                   "lastSeenAt": "2026-06-28T14:55:31.000Z",
                   "createdAt": "2026-06-20T08:11:02.000Z",
-                  "updatedAt": "2026-06-28T14:55:31.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')\n    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')\n    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"
+                    }
+                  ]
                 }
               }
             }
@@ -8437,6 +8633,96 @@
         }
       }
     },
+    "/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.\n\n**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",
@@ -9630,7 +9916,8 @@
         "x-error-codes": [
           "UNAUTHORIZED",
           "FORBIDDEN",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create"
@@ -9877,6 +10164,14 @@
                   ],
                   "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,
@@ -10287,7 +10582,16 @@
           "REFERENCED_NOT_FOUND",
           "GROUPS_WEIGHT_SUM",
           "EVENT_PENDING",
-          "INTERNAL"
+          "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).",
@@ -10304,12 +10608,21 @@
           "REFERENCED_NOT_FOUND": "A referenced entity (universe, metric, gate, event) does not exist.",
           "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."
+          "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"
         ],
@@ -10326,9 +10639,21 @@
             "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."
           }
         }
       },
@@ -10354,7 +10679,16 @@
             "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."
           },
-          "enabled": {
+          "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.",
             "type": "boolean"
@@ -10751,6 +11085,14 @@
       "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",
@@ -11140,307 +11482,13 @@
         ],
         "additionalProperties": false
       },
-      "ListExperimentsResponse": {
-        "type": "object",
-        "properties": {
-          "data": {
-            "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": {
-                  "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
-            }
-          },
-          "next_cursor": {
-            "anyOf": [
-              {
-                "type": "string"
-              },
-              {
-                "type": "null"
-              }
-            ]
-          }
-        },
-        "required": [
-          "data",
-          "next_cursor"
-        ],
-        "additionalProperties": false
-      },
-      "MetricName": {
-        "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 metric key. Single segment or `folder.name`; lowercase letters, digits, `_`/`-`; max 128 chars."
-      },
-      "ExperimentInlineMetric": {
+      "ExperimentApiRow": {
         "type": "object",
         "properties": {
-          "name": {
-            "$ref": "#/components/schemas/MetricName"
-          },
-          "query": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 4096,
-            "description": "Metric DSL string. Provide this OR `event`."
-          },
-          "event": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 256,
-            "description": "Event name to build the metric from server-side. Auto-created if missing."
-          },
-          "aggregation": {
+          "id": {
             "type": "string",
-            "enum": [
-              "count_users",
-              "count_events",
-              "retention_7d",
-              "retention_30d",
-              "sum",
-              "avg"
-            ],
-            "description": "Reducer for the `event` form. Defaults to `count_users`."
+            "description": "Stable opaque experiment id (`exp_…`)."
           },
-          "value": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 256,
-            "description": "Numeric event property for `sum`/`avg` (with `event`)."
-          }
-        },
-        "additionalProperties": false,
-        "description": "Inline metric — a DSL `query`, or an `event` (+ `aggregation`/`value`) the server compiles into one."
-      },
-      "CreateExperimentRequest": {
-        "type": "object",
-        "properties": {
           "name": {
             "type": "string",
             "maxLength": 128,
@@ -11448,12 +11496,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": {
-            "default": null,
-            "description": "Free-form description. Max 2000 chars, markdown rendered in the dashboard.",
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 2000
+                "type": "string"
               },
               {
                 "type": "null"
@@ -11461,12 +11506,9 @@
             ]
           },
           "hypothesis": {
-            "default": null,
-            "description": "Hypothesis statement shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 4000
+                "type": "string"
               },
               {
                 "type": "null"
@@ -11474,25 +11516,19 @@
             ]
           },
           "tag": {
-            "default": null,
-            "description": "Short tag chip rendered next to the name. Display-only.",
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 64
+                "type": "string"
               },
               {
                 "type": "null"
               }
             ]
           },
-          "owner_email": {
-            "default": null,
-            "description": "Owner email. Display-only.",
+          "ownerEmail": {
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 254
+                "type": "string"
               },
               {
                 "type": "null"
@@ -11500,20 +11536,16 @@
             ]
           },
           "audience": {
-            "default": null,
-            "description": "Audience label shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 256
+                "type": "string"
               },
               {
                 "type": "null"
               }
             ]
           },
-          "bucket_by": {
-            "default": null,
+          "bucketBy": {
             "anyOf": [
               {
                 "type": "string",
@@ -11528,16 +11560,29 @@
             ]
           },
           "folder": {
-            "$ref": "#/components/schemas/Folder"
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "draft",
+              "running",
+              "stopped",
+              "archived"
+            ]
           },
           "universe": {
             "type": "string",
-            "minLength": 1,
-            "description": "Name of an existing universe in the project. Returns `422` if the universe doesn't exist."
+            "description": "Universe name this experiment draws from."
           },
-          "targeting_gate": {
-            "default": null,
-            "description": "Optional gate name. Only callers that pass the gate are enrolled in the experiment.",
+          "targetingGate": {
             "anyOf": [
               {
                 "type": "string"
@@ -11547,27 +11592,64 @@
               }
             ]
           },
-          "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.",
+          "holdoutGate": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Per-experiment holdout gate name (a `holdout`-type flag), or `null`."
+          },
+          "allocationPct": {
             "type": "integer",
-            "minimum": 0,
-            "maximum": 10000
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991,
+            "description": "Allocation in basis points (0–10000)."
           },
-          "allocation_percent": {
-            "description": "Allocation as a **percentage** (0–100, fractional ok). Friendlier alias for `allocation_pct`; converted to basis points server-side (e.g. `50` = 5000 bp). If both are set, `allocation_percent` wins.",
-            "type": "number",
+          "reservedHeadroom": {
+            "type": "integer",
             "minimum": 0,
-            "maximum": 100
+            "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": {
-            "description": "Hash salt for bucketing. Auto-generated if omitted. Immutable while running.",
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 64
+            "type": "string"
           },
           "params": {
-            "default": {},
             "type": "object",
             "additionalProperties": {
               "type": "string",
@@ -11576,11 +11658,9 @@
                 "bool",
                 "number"
               ]
-            },
-            "description": "Map of param-name → scalar type. Defines the shape of `groups[].params`. Example: `{ headline: 'string', show_cta: 'bool' }`."
+            }
           },
           "groups": {
-            "minItems": 2,
             "type": "array",
             "items": {
               "type": "object",
@@ -11610,84 +11690,344 @@
               ],
               "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."
+            }
           },
-          "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.",
-            "type": "number",
-            "minimum": 0.0001,
-            "maximum": 0.5
+          "significanceThreshold": {
+            "type": "number"
           },
-          "min_runtime_days": {
-            "default": 0,
-            "description": "Minimum days the experiment must run before results are considered conclusive.",
+          "minRuntimeDays": {
             "type": "integer",
-            "minimum": 0,
-            "maximum": 365
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991
           },
-          "min_sample_size": {
-            "default": 100,
-            "description": "Minimum exposures per group before results are considered conclusive.",
+          "minSampleSize": {
             "type": "integer",
-            "minimum": 1,
+            "minimum": -9007199254740991,
             "maximum": 9007199254740991
           },
-          "sequential_testing": {
-            "default": false,
-            "description": "Enable sequential testing (always-valid p-values). Requires Premium plan or higher.",
+          "sequentialTesting": {
             "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"
+          "startedAt": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "ISO-8601 timestamp the experiment last transitioned to `running`, or `null`."
           },
-          "guardrail_metrics": {
-            "default": [],
-            "description": "Up to 10 guardrail metrics defined inline. Each is upserted (event + metric) and attached with role=guardrail.",
-            "maxItems": 10,
+          "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"
+                  },
+                  "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": {
-              "$ref": "#/components/schemas/ExperimentInlineMetric"
-            }
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "name": {
+                  "type": "string"
+                },
+                "eventName": {
+                  "anyOf": [
+                    {
+                      "type": "string"
+                    },
+                    {
+                      "type": "null"
+                    }
+                  ]
+                }
+              },
+              "required": [
+                "id",
+                "name"
+              ],
+              "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",
-          "groups"
+          "targetingGate",
+          "holdoutGate",
+          "allocationPct",
+          "reservedHeadroom",
+          "hashVersion",
+          "poolOffsetBp",
+          "poolSizeBp",
+          "salt",
+          "params",
+          "groups",
+          "significanceThreshold",
+          "minRuntimeDays",
+          "minSampleSize",
+          "sequentialTesting",
+          "startedAt",
+          "stoppedAt",
+          "updatedAt",
+          "version"
         ],
-        "additionalProperties": false,
-        "description": "Body for `POST /api/admin/experiments`. `name`, `universe`, and `groups` (≥2, weights sum to 10000) required."
+        "additionalProperties": false
       },
-      "CreateExperimentResponse": {
+      "ListExperimentsResponse": {
         "type": "object",
         "properties": {
-          "id": {
-            "type": "string",
-            "description": "Newly assigned experiment id."
+          "data": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExperimentApiRow"
+            }
           },
-          "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."
+          "next_cursor": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
           }
         },
         "required": [
-          "id",
-          "name"
+          "data",
+          "next_cursor"
         ],
         "additionalProperties": false
       },
-      "GetExperimentResponse": {
+      "MetricName": {
+        "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 metric key. Single segment or `folder.name`; lowercase letters, digits, `_`/`-`; max 128 chars."
+      },
+      "ExperimentInlineMetric": {
         "type": "object",
         "properties": {
-          "id": {
+          "name": {
+            "$ref": "#/components/schemas/MetricName"
+          },
+          "query": {
             "type": "string",
-            "description": "Stable opaque experiment id (`exp_…`)."
+            "minLength": 1,
+            "maxLength": 4096,
+            "description": "Metric DSL string. Provide this OR `event`."
           },
+          "event": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "description": "Event name to build the metric from server-side. Auto-created if missing."
+          },
+          "aggregation": {
+            "type": "string",
+            "enum": [
+              "count_users",
+              "count_events",
+              "retention_7d",
+              "retention_30d",
+              "sum",
+              "avg"
+            ],
+            "description": "Reducer for the `event` form. Defaults to `count_users`."
+          },
+          "value": {
+            "type": "string",
+            "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": {
+        "type": "object",
+        "properties": {
           "name": {
             "type": "string",
             "maxLength": 128,
@@ -11695,9 +12035,12 @@
             "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": {
+            "default": null,
+            "description": "Free-form description. Max 2000 chars, markdown rendered in the dashboard.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 2000
               },
               {
                 "type": "null"
@@ -11705,9 +12048,12 @@
             ]
           },
           "hypothesis": {
+            "default": null,
+            "description": "Hypothesis statement shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 4000
               },
               {
                 "type": "null"
@@ -11715,19 +12061,25 @@
             ]
           },
           "tag": {
+            "default": null,
+            "description": "Short tag chip rendered next to the name. Display-only.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 64
               },
               {
                 "type": "null"
               }
             ]
           },
-          "ownerEmail": {
+          "owner_email": {
+            "default": null,
+            "description": "Owner email. Display-only.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 254
               },
               {
                 "type": "null"
@@ -11735,16 +12087,20 @@
             ]
           },
           "audience": {
+            "default": null,
+            "description": "Audience label shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 256
               },
               {
                 "type": "null"
               }
             ]
           },
-          "bucketBy": {
+          "bucket_by": {
+            "default": null,
             "anyOf": [
               {
                 "type": "string",
@@ -11759,6 +12115,16 @@
             ]
           },
           "folder": {
+            "$ref": "#/components/schemas/Folder"
+          },
+          "universe": {
+            "type": "string",
+            "minLength": 1,
+            "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 (a `targeting`-type flag). Only callers that pass the gate are enrolled in the experiment.",
             "anyOf": [
               {
                 "type": "string"
@@ -11768,20 +12134,9 @@
               }
             ]
           },
-          "status": {
-            "type": "string",
-            "enum": [
-              "draft",
-              "running",
-              "stopped",
-              "archived"
-            ]
-          },
-          "universe": {
-            "type": "string",
-            "description": "Universe name this experiment draws from."
-          },
-          "targetingGate": {
+          "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"
@@ -11791,16 +12146,33 @@
               }
             ]
           },
-          "allocationPct": {
+          "allocation_pct": {
+            "default": 0,
+            "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": -9007199254740991,
-            "maximum": 9007199254740991,
-            "description": "Allocation in basis points (0–10000)."
+            "minimum": 0,
+            "maximum": 10000
+          },
+          "allocation_percent": {
+            "description": "Allocation as a **percentage** (0–100, fractional ok). Friendlier alias for `allocation_pct`; converted to basis points server-side (e.g. `50` = 5000 bp). If both are set, `allocation_percent` wins.",
+            "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": {
-            "type": "string"
+            "description": "Hash salt for bucketing. Auto-generated if omitted. Immutable while running.",
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
           },
           "params": {
+            "default": {},
             "type": "object",
             "additionalProperties": {
               "type": "string",
@@ -11809,9 +12181,11 @@
                 "bool",
                 "number"
               ]
-            }
+            },
+            "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",
             "items": {
               "type": "object",
@@ -11826,11 +12200,11 @@
                   "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": {}
                 }
@@ -11840,73 +12214,75 @@
                 "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."
+            },
+            "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."
           },
-          "significanceThreshold": {
-            "type": "number"
+          "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.",
+            "type": "number",
+            "minimum": 0.0001,
+            "maximum": 0.5
           },
-          "minRuntimeDays": {
+          "min_runtime_days": {
+            "default": 0,
+            "description": "Minimum days the experiment must run before results are considered conclusive.",
             "type": "integer",
-            "minimum": -9007199254740991,
-            "maximum": 9007199254740991
+            "minimum": 0,
+            "maximum": 365
           },
-          "minSampleSize": {
+          "min_sample_size": {
+            "default": 100,
+            "description": "Minimum exposures per group before results are considered conclusive.",
             "type": "integer",
-            "minimum": -9007199254740991,
+            "minimum": 1,
             "maximum": 9007199254740991
           },
-          "sequentialTesting": {
+          "sequential_testing": {
+            "default": false,
+            "description": "Enable sequential testing (always-valid p-values). Requires Premium plan or higher.",
             "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"
-              }
-            ]
+          "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"
           },
-          "updatedAt": {
-            "type": "string"
+          "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"
+          "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
       },
@@ -12014,12 +12390,29 @@
               }
             ]
           },
+          "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",
@@ -12046,10 +12439,10 @@
                 "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": {
@@ -12065,11 +12458,11 @@
                   "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": {}
                 }
@@ -12079,7 +12472,7 @@
                 "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": {
@@ -12114,7 +12507,7 @@
           }
         },
         "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",
@@ -12191,6 +12584,18 @@
                     "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": [
@@ -12229,11 +12634,23 @@
                     "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"
+                "role",
+                "min_effect_of_interest"
               ],
               "additionalProperties": false
             }
@@ -12342,6 +12759,17 @@
                     }
                   ],
                   "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": [
@@ -12352,7 +12780,8 @@
                 "mean",
                 "delta_pct",
                 "p_value",
-                "srm_detected"
+                "srm_detected",
+                "realized_mde"
               ],
               "additionalProperties": false
             }
@@ -13505,6 +13934,44 @@
         ],
         "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": {
@@ -13523,6 +13990,17 @@
                   "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."
@@ -13543,6 +14021,23 @@
                   ],
                   "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."
@@ -13587,6 +14082,19 @@
           "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.",
@@ -13610,6 +14118,25 @@
               }
             ],
             "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": [
@@ -13657,6 +14184,18 @@
           "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": [
               {
@@ -13674,10 +14213,27 @@
               }
             ],
             "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",
@@ -14709,8 +15265,8 @@
               "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"
@@ -14760,9 +15316,9 @@
         "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"
@@ -14800,8 +15356,8 @@
           "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"
@@ -14833,8 +15389,8 @@
           "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"
@@ -14931,8 +15487,8 @@
             "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"
@@ -14991,8 +15547,8 @@
           "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"
@@ -15019,8 +15575,8 @@
           "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"
@@ -15044,15 +15600,15 @@
           "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": [
@@ -16093,6 +16649,17 @@
             },
             "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": [
               {
@@ -16394,6 +16961,17 @@
       "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": {
@@ -16997,6 +17575,133 @@
         "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": {
@@ -17367,7 +18072,9 @@
             "type": "string",
             "enum": [
               "free",
-              "paid"
+              "pro",
+              "business",
+              "enterprise"
             ],
             "description": "Billing plan tier."
           },
@@ -17472,6 +18179,69 @@
             ],
             "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."
@@ -17664,6 +18434,97 @@
           "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,
@@ -18329,6 +19190,102 @@
         "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": "A tracked production error — one row per distinct issue, keyed by `fingerprint`. Rows are never created by hand: an ingestion path (worker log drain / the `see()` SDK reporter) folds each occurrence into the matching row, bumping `count` and `lastSeenAt`. The admin surface only lists them, reads one, and flips `status`.\n\nField names are camelCase (the D1 row projected through Drizzle). Many columns are nullable because the reporting source may not supply them.",
@@ -18343,7 +19300,7 @@
           },
           "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.",
@@ -18502,7 +19459,14 @@
           "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",
@@ -18546,7 +19510,7 @@
       },
       "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"
         }
@@ -19640,10 +20604,11 @@
                 "gates:evaluate",
                 "events:write",
                 "configs:write",
-                "experiments:write"
+                "experiments:write",
+                "tickets:public_create"
               ]
             },
-            "description": "Optional permission strings recorded on the key for audit/display."
+            "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": [