@shipeasy/openapi 2.1.0 → 2.3.0

package/openapi.json

@@ -31,9 +31,9 @@
   "tags": [
     {
       "name": "Release",
-      "summary": "Feature delivery",
+      "summary": "Feature delivery — flags, kill switches, dynamic configs, A/B experiments, and the universes they bucket in.",
       "kind": "nav",
-      "description": "Flags, kill switches, dynamic configs, experiments, and the universes they bucket in — the feature-delivery surface."
+      "description": "Release: the feature-delivery surface. One roof over the five resources\nthat decide which code path a user gets — feature gates (flags), kill\nswitches, dynamic configs, A/B/n experiments, and the universes that bucket\nthem — each exposed as its own subcommand group.\n\n**Groups.**\n- `flags` — boolean feature gates: AND-combined targeting rules + a percentage rollout (basis points), evaluated on the SDK hot path.\n- `killswitch` (`ks`) — per-env boolean overrides for incident response; no rules, no rollout, versioned per environment.\n- `configs` — JSON-Schema-validated structured values with a draft → publish workflow, delivered per environment.\n- `experiments` — randomised A/B/n assignment plus the analysis pipeline (t-test, sequential testing, SRM detection); `universes` hold the shared bucketing space and holdouts the experiments draw from.\n\n**Delivery model.** Every write rebuilds the project's KV blob and purges\nthe CDN — SDKs poll at the plan interval and never touch the database on\nthe hot path. The destructive verb is `archive` (soft-delete), never\n`delete`.\n\nRun `shipeasy release <group> --help` for the full contract of each group."
     },
     {
       "name": "Flags",
@@ -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."
@@ -157,6 +162,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -360,6 +368,32 @@
                   "name": "checkout_v2"
                 }
               }
+            },
+            "links": {
+              "UpdateGate": {
+                "operationId": "updateGate",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "EnableGate": {
+                "operationId": "enableGate",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DisableGate": {
+                "operationId": "disableGate",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteGate": {
+                "operationId": "deleteGate",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -386,7 +420,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -414,7 +449,7 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -569,7 +604,7 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -639,12 +674,12 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
         "responses": {
-          "201": {
+          "200": {
             "description": "Enable a gate",
             "content": {
               "application/json": {
@@ -710,12 +745,12 @@
             "required": true,
             "description": "Stable opaque gate id (`gat_…`) or the gate's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
         "responses": {
-          "201": {
+          "200": {
             "description": "Disable a gate",
             "content": {
               "application/json": {
@@ -780,6 +815,18 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "name": "status",
+            "in": "query",
+            "required": false,
+            "description": "Filter by lifecycle status. Pass `archived` to return the archive tab; any other value (or omitting it) returns the non-archived experiments.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -990,6 +1037,44 @@
                   "name": "checkout_button_color"
                 }
               }
+            },
+            "links": {
+              "GetExperiment": {
+                "operationId": "getExperiment",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateExperiment": {
+                "operationId": "updateExperiment",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "SetExperimentMetrics": {
+                "operationId": "setExperimentMetrics",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "SetExperimentStatus": {
+                "operationId": "setExperimentStatus",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "ReanalyzeExperiment": {
+                "operationId": "reanalyzeExperiment",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteExperiment": {
+                "operationId": "deleteExperiment",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -1047,7 +1132,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1057,7 +1142,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/GetExperimentResponse"
+                  "$ref": "#/components/schemas/ExperimentApiRow"
                 },
                 "example": {
                   "id": "exp_01j7wb12c3d4e5f6g7h8j9k0l1",
@@ -1148,7 +1233,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1245,7 +1330,8 @@
           "INVALID_TRANSITION",
           "GROUPS_WEIGHT_SUM",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "EXPERIMENT_IMMUTABLE_FIELD"
         ],
         "x-cli": {
           "name": "update",
@@ -1271,7 +1357,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1341,7 +1427,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1386,7 +1472,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Transition experiment status",
             "content": {
               "application/json": {
@@ -1425,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": [
@@ -1475,7 +1567,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1515,7 +1607,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Attach metrics",
             "content": {
               "application/json": {
@@ -1564,7 +1656,8 @@
           "NOT_FOUND",
           "EVENT_PENDING",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "METRIC_UNKNOWN_ID"
         ],
         "x-cli": {
           "name": "set-metrics",
@@ -1592,7 +1685,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -1688,7 +1781,7 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           },
           {
@@ -1792,12 +1885,12 @@
             "required": true,
             "description": "Stable opaque experiment id (`exp_…`) or the experiment's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
         "responses": {
-          "201": {
+          "200": {
             "description": "Re-queue analysis",
             "content": {
               "application/json": {
@@ -1862,6 +1955,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -2089,6 +2185,32 @@
                   "name": "pricing.tiers"
                 }
               }
+            },
+            "links": {
+              "GetConfig": {
+                "operationId": "getConfig",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateConfig": {
+                "operationId": "updateConfig",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "PublishConfigDraft": {
+                "operationId": "publishConfigDraft",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteConfig": {
+                "operationId": "deleteConfig",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -2115,7 +2237,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -2143,7 +2266,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2298,7 +2421,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2414,7 +2537,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2483,7 +2606,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2586,7 +2709,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2674,7 +2797,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2705,7 +2828,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Publish a draft",
             "content": {
               "application/json": {
@@ -2773,7 +2896,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           },
           {
@@ -2864,7 +2987,7 @@
             "required": true,
             "description": "Stable opaque config id (`cfg_…`) or the config's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -2965,6 +3088,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -3102,6 +3228,38 @@
                   "name": "payments.checkout"
                 }
               }
+            },
+            "links": {
+              "GetKillswitch": {
+                "operationId": "getKillswitch",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateKillswitch": {
+                "operationId": "updateKillswitch",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "SetKillswitchSwitch": {
+                "operationId": "setKillswitchSwitch",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "SetKillswitchValue": {
+                "operationId": "setKillswitchValue",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteKillswitch": {
+                "operationId": "deleteKillswitch",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -3128,7 +3286,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -3156,7 +3315,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3246,7 +3405,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3357,7 +3516,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3426,7 +3585,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3527,7 +3686,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3619,7 +3778,7 @@
             "required": true,
             "description": "Stable opaque killswitch id (`ksw_…`) or the killswitch's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3724,6 +3883,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -3843,6 +4005,20 @@
                   "name": "primary_users"
                 }
               }
+            },
+            "links": {
+              "UpdateUniverse": {
+                "operationId": "updateUniverse",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteUniverse": {
+                "operationId": "deleteUniverse",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -3870,7 +4046,8 @@
           "FORBIDDEN",
           "PLAN_REQUIRED",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -3898,7 +4075,7 @@
             "required": true,
             "description": "Stable opaque universe id (`uni_…`) or the universe's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -3996,7 +4173,7 @@
             "required": true,
             "description": "Stable opaque universe id (`uni_…`) or the universe's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4052,7 +4229,7 @@
       "get": {
         "operationId": "listGateTemplates",
         "summary": "List gate templates",
-        "description": "Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in [\"@team\"]`) that the SDK expands to the resolved email list at rebuild.\n\n**Turn \"launch X in country Y\" into a gated flag:** list templates (optionally with `query`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.\n\nThe catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).",
+        "description": "Returns the merged targeting-rule template catalog — read-only **built-ins first** (the `@team`/`@owner` audience aliases, country, email-domain, region presets, …), then this project's **customer** templates. Each item carries a `rules: [{ attr, op, value }]` definition; the alias templates carry a symbol value (`email in [\"@team\"]`) that the SDK expands to the resolved email list at rebuild.\n\n**Turn \"launch X in country Y\" into a gated flag:** list templates (optionally with `q`), take the matching template's `rules`, substitute the concrete value(s), and pass them as the `rules` arg of `release_flags_create`.\n\nThe catalog is small and bounded, so the full merged set is returned in one page — this endpoint is **not** paginated (`next_cursor` is always `null`; there are no `limit`/`cursor` params).",
         "tags": [
           "Templates"
         ],
@@ -4060,11 +4237,15 @@
           {
             "$ref": "#/components/parameters/ProjectId"
           },
+          {
+            "$ref": "#/components/parameters/Q"
+          },
           {
             "name": "query",
             "in": "query",
             "required": false,
-            "description": "Case-insensitive substring filter over each template's `name` + `description`. Omit to return the whole catalog.",
+            "deprecated": true,
+            "description": "Deprecated alias for `q`, kept working for one release. Prefer `q`.",
             "schema": {
               "type": "string"
             }
@@ -4233,7 +4414,7 @@
             "required": true,
             "description": "Built-in slug (`country`) or customer template id (`gtpl_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4291,7 +4472,7 @@
             "required": true,
             "description": "Customer template id (`gtpl_…`) or its `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4388,7 +4569,7 @@
             "required": true,
             "description": "Customer template id (`gtpl_…`) or its `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4420,6 +4601,9 @@
           },
           "409": {
             "$ref": "#/components/responses/Conflict"
+          },
+          "422": {
+            "$ref": "#/components/responses/UnprocessableEntity"
           }
         },
         "x-error-codes": [
@@ -4448,6 +4632,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -4547,6 +4734,26 @@
                   "name": "plan"
                 }
               }
+            },
+            "links": {
+              "GetAttribute": {
+                "operationId": "getAttribute",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateAttribute": {
+                "operationId": "updateAttribute",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteAttribute": {
+                "operationId": "deleteAttribute",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -4601,7 +4808,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4676,7 +4883,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4761,7 +4968,7 @@
             "required": true,
             "description": "The attribute id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -4823,6 +5030,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -4953,6 +5163,26 @@
                   "name": "checkouts"
                 }
               }
+            },
+            "links": {
+              "GetMetric": {
+                "operationId": "getMetric",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateMetric": {
+                "operationId": "updateMetric",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteMetric": {
+                "operationId": "deleteMetric",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -4981,7 +5211,8 @@
           "ALREADY_EXISTS",
           "EVENT_PENDING",
           "REFERENCED_NOT_FOUND",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -5009,7 +5240,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5090,7 +5321,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5174,7 +5405,7 @@
             "required": true,
             "description": "Stable opaque metric id (`met_…`) or the metric's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5237,6 +5468,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -5355,6 +5589,32 @@
                   "name": "checkout_completed"
                 }
               }
+            },
+            "links": {
+              "GetEvent": {
+                "operationId": "getEvent",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateEvent": {
+                "operationId": "updateEvent",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "ApproveEvent": {
+                "operationId": "approveEvent",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteEvent": {
+                "operationId": "deleteEvent",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -5381,7 +5641,8 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create",
@@ -5409,7 +5670,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5489,7 +5750,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5589,7 +5850,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5659,7 +5920,7 @@
             "required": true,
             "description": "Stable opaque event id (`evt_…`) or the event's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -5989,7 +6250,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6062,7 +6323,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6162,7 +6423,7 @@
             "required": true,
             "description": "Per-project item number (e.g. `7`) or the full ops item id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6228,51 +6489,35 @@
         }
       }
     },
-    "/api/admin/notifications": {
-      "post": {
-        "operationId": "notifyOps",
-        "summary": "Raise an attention notification",
-        "description": "Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.\n\n**Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.",
+    "/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": [
-          "Ops"
+          "Comments"
         ],
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
-          }
-        ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/NotifyOpsRequest"
-              },
-              "example": {
-                "title": "Alert rule @alert:checkout-error-rate needs a human edit for #42",
-                "summary": "#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human.",
-                "steps": [
-                  "Open @alert:checkout-error-rate in the dashboard alerts page.",
-                  "Raise the threshold from `2%` to `5%` and widen the window to `1h`.",
-                  "Re-run the shipeasy-ops-work loop — #42 will be acknowledged."
-                ],
-                "dedupeKey": "feedback:42",
-                "href": "/dashboard/prj_0abc/bugs/42"
-              }
+          },
+          {
+            "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": {
-          "201": {
-            "description": "Raise an attention notification",
+          "200": {
+            "description": "List an item's comments",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/NotifyOpsResponse"
-                },
-                "example": {
-                  "dedupeKey": "error:checkout:5xx",
-                  "dispatched": true
+                  "$ref": "#/components/schemas/ListOpsCommentsResponse"
                 }
               }
             }
@@ -6288,44 +6533,210 @@
           },
           "404": {
             "$ref": "#/components/responses/NotFound"
-          },
-          "409": {
-            "$ref": "#/components/responses/Conflict"
-          },
-          "422": {
-            "$ref": "#/components/responses/UnprocessableEntity"
           }
         },
         "x-error-codes": [
           "BAD_REQUEST",
           "UNAUTHORIZED",
           "FORBIDDEN",
-          "VALIDATION"
+          "NOT_FOUND"
         ],
         "x-cli": {
-          "name": "notify"
+          "name": "list",
+          "positional": [
+            "handle"
+          ]
         }
-      }
-    },
-    "/api/admin/slack/channels": {
-      "get": {
-        "operationId": "listSlackChannels",
-        "summary": "List Slack channels",
-        "description": "List the project's connected Slack channels — used to resolve an alert rule's notification target.\n\n**Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.",
+      },
+      "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": [
-          "Alerts"
+          "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 Slack channels",
-            "content": {
-              "application/json": {
-                "schema": {
+        "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",
+        "summary": "Raise an attention notification",
+        "description": "Raise a 'needs your attention' bell notification. Create-only and idempotent on `dedupeKey` — re-raising with the same key updates the one card instead of stacking duplicates. It never reads, marks read, or deletes the feed, so it is safe for restricted ops keys.\n\n**Use case:** Escalate work that can't land in code (a product decision, a credential only a human has, a resource only a human may edit), deduped so repeats don't spam the bell.",
+        "tags": [
+          "Ops"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/NotifyOpsRequest"
+              },
+              "example": {
+                "title": "Alert rule @alert:checkout-error-rate needs a human edit for #42",
+                "summary": "#42 is a false positive — the rule fires on the expected nightly batch spike, and rule definitions can only be edited by a human.",
+                "steps": [
+                  "Open @alert:checkout-error-rate in the dashboard alerts page.",
+                  "Raise the threshold from `2%` to `5%` and widen the window to `1h`.",
+                  "Re-run the shipeasy-ops-work loop — #42 will be acknowledged."
+                ],
+                "dedupeKey": "feedback:42",
+                "href": "/dashboard/prj_0abc/bugs/42"
+              }
+            }
+          }
+        },
+        "responses": {
+          "201": {
+            "description": "Raise an attention notification",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/NotifyOpsResponse"
+                },
+                "example": {
+                  "dedupeKey": "error:checkout:5xx",
+                  "dispatched": true
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "422": {
+            "$ref": "#/components/responses/UnprocessableEntity"
+          }
+        },
+        "x-error-codes": [
+          "BAD_REQUEST",
+          "UNAUTHORIZED",
+          "FORBIDDEN",
+          "VALIDATION"
+        ],
+        "x-cli": {
+          "name": "notify"
+        }
+      }
+    },
+    "/api/admin/slack/channels": {
+      "get": {
+        "operationId": "listSlackChannels",
+        "summary": "List Slack channels",
+        "description": "List the project's connected Slack channels — used to resolve an alert rule's notification target.\n\n**Use case:** Populate a channel picker, or validate an alert rule's `--slack-channel` before saving.",
+        "tags": [
+          "Alerts"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "List Slack channels",
+            "content": {
+              "application/json": {
+                "schema": {
                   "$ref": "#/components/schemas/ListSlackChannelsResponse"
                 },
                 "example": {
@@ -6384,6 +6795,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -6506,6 +6920,20 @@
                   "id": "ar_01j7w8a1b2c3d4e5f6g7h8i9j0"
                 }
               }
+            },
+            "links": {
+              "UpdateAlertRule": {
+                "operationId": "updateAlertRule",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteAlertRule": {
+                "operationId": "deleteAlertRule",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -6532,6 +6960,7 @@
           "UNAUTHORIZED",
           "FORBIDDEN",
           "ALREADY_EXISTS",
+          "METRIC_NOT_FOUND",
           "REFERENCED_NOT_FOUND",
           "VALIDATION"
         ],
@@ -6558,7 +6987,7 @@
             "required": true,
             "description": "Stable opaque alert-rule id (`ar_…`) or the rule's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6660,7 +7089,7 @@
             "required": true,
             "description": "Stable opaque alert-rule id (`ar_…`) or the rule's `name`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6737,7 +7166,7 @@
                   "name": "Acme",
                   "domain": "acme.com",
                   "ownerEmail": "owner@acme.com",
-                  "plan": "paid",
+                  "plan": "pro",
                   "status": "active",
                   "subscriptionStatus": "active",
                   "billingInterval": "monthly",
@@ -6891,7 +7320,7 @@
             "required": true,
             "description": "Stable opaque project id. Must match the caller's own project.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -6932,7 +7361,7 @@
                   "name": "Acme Rockets",
                   "domain": "acme.com",
                   "ownerEmail": "owner@acme.com",
-                  "plan": "paid",
+                  "plan": "pro",
                   "status": "active",
                   "subscriptionStatus": "active",
                   "billingInterval": "monthly",
@@ -7088,6 +7517,14 @@
                   "name": "fr:prod"
                 }
               }
+            },
+            "links": {
+              "PublishI18nProfile": {
+                "operationId": "publishI18nProfile",
+                "parameters": {
+                  "profileId": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -7155,9 +7592,10 @@
             "name": "q",
             "in": "query",
             "required": false,
-            "description": "Free-text search — matches keys whose name OR value contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.",
+            "description": "Free-text search — matches keys whose name, value, OR description contains this substring (case-insensitive). Use it to find the key behind a piece of on-screen copy.",
             "schema": {
-              "type": "string"
+              "type": "string",
+              "maxLength": 100
             }
           },
           {
@@ -7170,6 +7608,17 @@
               "minimum": 1,
               "maximum": 500
             }
+          },
+          {
+            "name": "offset",
+            "in": "query",
+            "required": false,
+            "description": "Number of keys to skip before returning `limit` rows (offset pagination).",
+            "schema": {
+              "type": "integer",
+              "minimum": 0,
+              "default": 0
+            }
           }
         ],
         "responses": {
@@ -7319,7 +7768,7 @@
             "required": true,
             "description": "The key's id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7533,7 +7982,7 @@
             "required": true,
             "description": "The draft id to update.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7617,7 +8066,7 @@
             "required": true,
             "description": "The profile id to publish.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7635,7 +8084,7 @@
           }
         },
         "responses": {
-          "201": {
+          "200": {
             "description": "Publish a profile chunk",
             "content": {
               "application/json": {
@@ -7888,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"
         ],
@@ -7902,7 +8351,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -7937,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"
+                    }
+                  ]
                 }
               }
             }
@@ -7990,7 +8465,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8107,7 +8582,7 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8158,11 +8633,11 @@
         }
       }
     },
-    "/api/admin/errors/{id}/series": {
+    "/api/admin/errors/{id}/resolve": {
       "post": {
-        "operationId": "getErrorSeries",
-        "summary": "Get an error's occurrence series",
-        "description": "Returns a bucketed occurrence timeseries for one tracked error (by its fingerprint), read from the `shipeasy_errors` Analytics Engine dataset (near-real-time; ingest lag is seconds). The window bounds are epoch **seconds**; `to` must be strictly greater than `from`. The response echoes the SQL that produced the rows.\n\n**Use case:** Render the trend sparkline / occurrence chart on the error detail panel, or pull the raw bucketed counts to alert when an issue's rate spikes.",
+        "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"
         ],
@@ -8176,73 +8651,163 @@
             "required": true,
             "description": "Stable opaque error id (`err_…`).",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
-        "requestBody": {
-          "required": true,
-          "content": {
-            "application/json": {
-              "schema": {
-                "$ref": "#/components/schemas/ErrorSeriesRequest"
-              },
-              "examples": {
-                "lastDayHourly": {
-                  "summary": "Last 24h, hourly buckets",
-                  "description": "Hourly occurrence counts over a one-day window (bounds in epoch seconds).",
-                  "value": {
-                    "from": 1751000400,
-                    "to": 1751086800,
-                    "bucket": 3600
-                  }
-                }
-              }
-            }
-          }
-        },
         "responses": {
           "200": {
-            "description": "Get an error's occurrence series",
+            "description": "Resolve a tracked error",
             "content": {
               "application/json": {
                 "schema": {
-                  "$ref": "#/components/schemas/ErrorSeriesResponse"
+                  "$ref": "#/components/schemas/ErrorRecord"
                 },
                 "example": {
-                  "sql": "SELECT intDiv(toUInt32(double2), 3600) * 3600 AS t,\n  sum(double1 * _sample_interval) AS v\nFROM shipeasy_errors\nWHERE index1 = 'e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90'\n  AND blob1 = '9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1'\n  AND double2 >= 1751000400 AND double2 < 1751086800\nGROUP BY t\nORDER BY t",
-                  "rows": [
-                    {
-                      "t": 1751000400,
-                      "v": 12
-                    },
-                    {
-                      "t": 1751004000,
-                      "v": 31
-                    },
-                    {
-                      "t": 1751007600,
-                      "v": 27
-                    }
-                  ]
-                }
-              }
-            }
-          },
-          "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"
+                  "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",
+        "summary": "Get an error's occurrence series",
+        "description": "Returns a bucketed occurrence timeseries for one tracked error (by its fingerprint), read from the `shipeasy_errors` Analytics Engine dataset (near-real-time; ingest lag is seconds). The window bounds are epoch **seconds**; `to` must be strictly greater than `from`. The response echoes the SQL that produced the rows.\n\n**Use case:** Render the trend sparkline / occurrence chart on the error detail panel, or pull the raw bucketed counts to alert when an issue's rate spikes.",
+        "tags": [
+          "Errors"
+        ],
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "name": "id",
+            "in": "path",
+            "required": true,
+            "description": "Stable opaque error id (`err_…`).",
+            "schema": {
+              "$ref": "#/components/schemas/ResourceId"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/ErrorSeriesRequest"
+              },
+              "examples": {
+                "lastDayHourly": {
+                  "summary": "Last 24h, hourly buckets",
+                  "description": "Hourly occurrence counts over a one-day window (bounds in epoch seconds).",
+                  "value": {
+                    "from": 1751000400,
+                    "to": 1751086800,
+                    "bucket": 3600
+                  }
+                }
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Get an error's occurrence series",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorSeriesResponse"
+                },
+                "example": {
+                  "sql": "SELECT intDiv(toUInt32(double2), 3600) * 3600 AS t,\n  sum(double1 * _sample_interval) AS v\nFROM shipeasy_errors\nWHERE index1 = 'e976b15e-2f0d-4c6e-9b1a-3a7c1f2d8e90'\n  AND blob1 = '9c1f4f1f2c0c4a5fa1c2b6d3e7c8e3a1'\n  AND double2 >= 1751000400 AND double2 < 1751086800\nGROUP BY t\nORDER BY t",
+                  "rows": [
+                    {
+                      "t": 1751000400,
+                      "v": 12
+                    },
+                    {
+                      "t": 1751004000,
+                      "v": 31
+                    },
+                    {
+                      "t": 1751007600,
+                      "v": 27
+                    }
+                  ]
+                }
+              }
+            }
+          },
+          "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"
@@ -8273,6 +8838,9 @@
         "parameters": [
           {
             "$ref": "#/components/parameters/ProjectId"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -8426,6 +8994,32 @@
                   "id": "9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10"
                 }
               }
+            },
+            "links": {
+              "GetConnector": {
+                "operationId": "getConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateConnector": {
+                "operationId": "updateConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "TestConnector": {
+                "operationId": "testConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteConnector": {
+                "operationId": "deleteConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -8475,7 +9069,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8558,7 +9152,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8664,7 +9258,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8732,7 +9326,7 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -8761,7 +9355,7 @@
         },
         "responses": {
           "200": {
-            "description": "Fire a trigger connector",
+            "description": "The trigger run was successfully kicked off.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8790,6 +9384,9 @@
           },
           "422": {
             "$ref": "#/components/responses/UnprocessableEntity"
+          },
+          "502": {
+            "$ref": "#/components/responses/BadGateway"
           }
         },
         "x-error-codes": [
@@ -8823,13 +9420,13 @@
             "required": true,
             "description": "Stable opaque connector id.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
         "responses": {
           "200": {
-            "description": "Test a connector",
+            "description": "The test dispatch reached the destination.",
             "content": {
               "application/json": {
                 "schema": {
@@ -8859,6 +9456,9 @@
           },
           "422": {
             "$ref": "#/components/responses/UnprocessableEntity"
+          },
+          "502": {
+            "$ref": "#/components/responses/BadGateway"
           }
         },
         "x-error-codes": [
@@ -8892,7 +9492,7 @@
             "required": true,
             "description": "Stable opaque connector id. Its stored `provider` must match the body's `provider`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -9038,6 +9638,38 @@
                   "id": "9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10"
                 }
               }
+            },
+            "links": {
+              "FireConnector": {
+                "operationId": "fireConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "TestConnector": {
+                "operationId": "testConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "GetConnector": {
+                "operationId": "getConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "UpdateTriggerConnector": {
+                "operationId": "updateTriggerConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              },
+              "DeleteConnector": {
+                "operationId": "deleteConnector",
+                "parameters": {
+                  "id": "$response.body#/id"
+                }
+              }
             }
           },
           "400": {
@@ -9129,6 +9761,9 @@
           },
           {
             "$ref": "#/components/parameters/PaginationCursor"
+          },
+          {
+            "$ref": "#/components/parameters/Q"
           }
         ],
         "responses": {
@@ -9281,7 +9916,8 @@
         "x-error-codes": [
           "UNAUTHORIZED",
           "FORBIDDEN",
-          "VALIDATION"
+          "VALIDATION",
+          "PLAN_LIMIT"
         ],
         "x-cli": {
           "name": "create"
@@ -9306,7 +9942,7 @@
             "required": true,
             "description": "Stable opaque key id (UUID) returned by `create` / `list`.",
             "schema": {
-              "type": "string"
+              "$ref": "#/components/schemas/ResourceId"
             }
           }
         ],
@@ -9484,6 +10120,16 @@
         "schema": {
           "type": "string"
         }
+      },
+      "Q": {
+        "name": "q",
+        "in": "query",
+        "required": false,
+        "description": "Case-insensitive substring filter across the resource's human-readable text columns (e.g. `name`, `title`, `description`). OR-matched across those columns; omit to return everything.",
+        "schema": {
+          "type": "string",
+          "maxLength": 100
+        }
       }
     },
     "schemas": {
@@ -9518,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,
@@ -9928,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).",
@@ -9945,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"
         ],
@@ -9967,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."
           }
         }
       },
@@ -9995,6 +10679,15 @@
             "pattern": "^[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9_-]*[a-z0-9])?)?$",
             "description": "Stable gate key used by SDKs (`Shipeasy.checkGate(user, '<name>')`). Single segment or `folder.name`. Lowercase letters, digits, `_` or `-`; max 128 chars. Immutable after create — rename = delete + recreate."
           },
+          "type": {
+            "default": "targeting",
+            "type": "string",
+            "enum": [
+              "targeting",
+              "holdout"
+            ],
+            "description": "Gate kind. `targeting` (default) is a normal flag with the full builder. `holdout` is a **restricted** flag — only a public rollout % and a whitelist are allowed; attribute rules and a gatekeeper stack are rejected. Used as an experiment's `holdout_gate`."
+          },
           "enabled": {
             "default": true,
             "description": "Master switch. Defaults to `true`. Set `false` to create the gate disabled (evaluates to `false` regardless of rules/rollout); flip on via `POST /{id}/enable` or PATCH.",
@@ -10370,6 +11063,12 @@
         ],
         "additionalProperties": false
       },
+      "ResourceId": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128,
+        "description": "A resource path identifier — an opaque `xxx_<ULID>` id (~30 chars) or the resource's `name`/`key`. 1–128 characters; the upper bound matches the longest name/key any resource accepts, so an over-long value can never name a real row."
+      },
       "DeleteGateResponse": {
         "type": "object",
         "properties": {
@@ -10386,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",
@@ -10775,307 +11482,13 @@
         ],
         "additionalProperties": false
       },
-      "ListExperimentsResponse": {
+      "ExperimentApiRow": {
         "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": {
-        "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,
@@ -11083,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"
@@ -11096,12 +11506,9 @@
             ]
           },
           "hypothesis": {
-            "default": null,
-            "description": "Hypothesis statement shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string",
-                "maxLength": 4000
+                "type": "string"
               },
               {
                 "type": "null"
@@ -11109,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"
@@ -11135,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",
@@ -11163,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"
@@ -11182,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.",
-            "type": "integer",
-            "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
+          "holdoutGate": {
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Per-experiment holdout gate name (a `holdout`-type flag), or `null`."
+          },
+          "allocationPct": {
+            "type": "integer",
+            "minimum": -9007199254740991,
+            "maximum": 9007199254740991,
+            "description": "Allocation in basis points (0–10000)."
+          },
+          "reservedHeadroom": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 10000,
+            "description": "Basis points of the split reserved for appended variants (group weights sum to 10000 − this)."
+          },
+          "hashVersion": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Bucketing hash algorithm version for the experiment's pool slice (§B4). Defaults to 1."
+          },
+          "poolOffsetBp": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 10000
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Basis-point offset of the experiment's contiguous slice in the universe pool, or `null` before a slice is allocated."
+          },
+          "poolSizeBp": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 10000
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Basis-point width of the experiment's pool slice (equal to its allocation), or `null` before a slice is allocated."
           },
           "salt": {
-            "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",
@@ -11211,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",
@@ -11245,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": {
+          "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": {
+            "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": {
-          "id": {
-            "type": "string",
-            "description": "Stable opaque experiment id (`exp_…`)."
-          },
           "name": {
             "type": "string",
             "maxLength": 128,
@@ -11330,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"
@@ -11340,9 +12048,12 @@
             ]
           },
           "hypothesis": {
+            "default": null,
+            "description": "Hypothesis statement shown in the editor. Display-only.",
             "anyOf": [
               {
-                "type": "string"
+                "type": "string",
+                "maxLength": 4000
               },
               {
                 "type": "null"
@@ -11350,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"
@@ -11370,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",
@@ -11394,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"
@@ -11403,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"
@@ -11426,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",
@@ -11444,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",
@@ -11461,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": {}
                 }
@@ -11475,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
       },
@@ -11649,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",
@@ -11681,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": {
@@ -11700,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": {}
                 }
@@ -11714,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": {
@@ -11749,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",
@@ -11826,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": [
@@ -11864,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
             }
@@ -11977,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": [
@@ -11987,7 +12780,8 @@
                 "mean",
                 "delta_pct",
                 "p_value",
-                "srm_detected"
+                "srm_detected",
+                "realized_mde"
               ],
               "additionalProperties": false
             }
@@ -13140,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": {
@@ -13158,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."
@@ -13178,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."
@@ -13222,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.",
@@ -13245,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": [
@@ -13292,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": [
               {
@@ -13309,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",
@@ -13327,7 +14248,7 @@
         ],
         "additionalProperties": false
       },
-      "GateTemplateRule": {
+      "GateTemplateRuleResponse": {
         "type": "object",
         "properties": {
           "attr": {
@@ -13362,11 +14283,10 @@
         },
         "required": [
           "attr",
-          "op",
-          "value"
+          "op"
         ],
         "additionalProperties": false,
-        "description": "Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`."
+        "description": "Single targeting predicate as returned by the API. `value` is optional here — read-only built-in templates (e.g. `@owner`, or presets whose operand is supplied at substitution time) legitimately omit it. Request bodies still require `value`."
       },
       "GateTemplate": {
         "type": "object",
@@ -13414,7 +14334,7 @@
           "rules": {
             "type": "array",
             "items": {
-              "$ref": "#/components/schemas/GateTemplateRule"
+              "$ref": "#/components/schemas/GateTemplateRuleResponse"
             },
             "description": "The rule definition — copy, substitute the value(s), pass as `rules`."
           },
@@ -13478,6 +14398,62 @@
         ],
         "additionalProperties": false
       },
+      "GateTemplateRule": {
+        "type": "object",
+        "properties": {
+          "attr": {
+            "type": "string",
+            "description": "Attribute key on the evaluation context (e.g. `country`, `plan`, `email`). Matched case-sensitively against `Shipeasy.checkGate(user, name)` input. May be empty on a built-in template whose attribute is supplied at substitution time (e.g. the `exp_in` \"in any experiment\" preset — you fill in the experiment name)."
+          },
+          "op": {
+            "type": "string",
+            "enum": [
+              "eq",
+              "neq",
+              "in",
+              "not_in",
+              "gt",
+              "gte",
+              "lt",
+              "lte",
+              "contains",
+              "regex",
+              "semver_gt",
+              "semver_gte",
+              "semver_lt",
+              "semver_lte",
+              "gate_pass",
+              "exp_in"
+            ],
+            "description": "Comparison operator. Equality: `eq`/`neq`. Set membership: `in`/`not_in` (value is an array). Numeric order: `gt`/`gte`/`lt`/`lte`. Semver order: `semver_gt`/`semver_gte`/`semver_lt`/`semver_lte`. String: `contains` (substring), `regex` (JS-flavour pattern). Cross-resource: `gate_pass` (value is another gate's name), `exp_in` (attr is an experiment name, value is a variant / `\"$holdout\"` / `\"$any\"`)."
+          },
+          "value": {
+            "description": "Operand. Shape depends on `op`: scalar for `eq/neq/gt/gte/lt/lte/contains/semver_*`; array of scalars for `in/not_in`; string pattern for `regex`; referenced gate name for `gate_pass`; variant selector for `exp_in`. Required on every request rule (value-ops need it; the valueless built-in presets are read-only and never created via the API).",
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "number"
+              },
+              {
+                "type": "boolean"
+              },
+              {
+                "type": "array",
+                "items": {}
+              }
+            ]
+          }
+        },
+        "required": [
+          "attr",
+          "op",
+          "value"
+        ],
+        "additionalProperties": false,
+        "description": "Single targeting predicate. Copy a template's rules, substitute the concrete `value`(s), and pass them as the `rules` arg of `release_flags_create`."
+      },
       "CreateGateTemplateRequest": {
         "type": "object",
         "description": "Body for `POST /api/admin/gate-templates`. Creates a per-project (customer) template. At minimum supply `name` + `rules`.",
@@ -14289,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"
@@ -14340,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"
@@ -14380,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"
@@ -14413,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"
@@ -14511,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"
@@ -14571,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"
@@ -14599,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"
@@ -14624,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": [
@@ -15673,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": [
               {
@@ -15974,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": {
@@ -16500,82 +17498,209 @@
           "priority": {
             "$ref": "#/components/schemas/OpsItemPriorityOrNull"
           },
-          "notify": {
-            "$ref": "#/components/schemas/OpsItemNotifyOrNull"
-          }
-        },
-        "additionalProperties": false,
-        "description": "Triage-only update — the shape accepted for any item, and the ONLY shape for auto-filed `error`/`alert`/`measure_plan` tickets (their content is not user-editable)."
-      },
-      "UpdateOpsItemRequest": {
-        "anyOf": [
-          {
-            "$ref": "#/components/schemas/UpdateBugRequest"
+          "notify": {
+            "$ref": "#/components/schemas/OpsItemNotifyOrNull"
+          }
+        },
+        "additionalProperties": false,
+        "description": "Triage-only update — the shape accepted for any item, and the ONLY shape for auto-filed `error`/`alert`/`measure_plan` tickets (their content is not user-editable)."
+      },
+      "UpdateOpsItemRequest": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/UpdateBugRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateFeatureRequestRequest"
+          },
+          {
+            "$ref": "#/components/schemas/UpdateOpsItemStatusRequest"
+          }
+        ],
+        "description": "Body for `PATCH /api/admin/ops/{handle}`. The body is type-less — the server validates it against the stored item's type: a `bug` accepts the bug content fields, a `feature_request` the feature fields, and `error`/`alert`/`measure_plan` only `status`/`priority`/`notify`. Pass at least one field."
+      },
+      "UpdateOpsItemResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Item id that was updated."
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false,
+        "description": "Response for the update / link-pr endpoints."
+      },
+      "LinkPrToOpsItemRequest": {
+        "type": "object",
+        "properties": {
+          "prNumber": {
+            "anyOf": [
+              {
+                "type": "integer",
+                "exclusiveMinimum": 0,
+                "maximum": 9007199254740991
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "PR number to record on the item. `null` unlinks the PR."
+          },
+          "prUrl": {
+            "description": "Explicit PR URL. Required for error/alert tickets (no GitHub issue to derive the URL from).",
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "required": [
+          "prNumber"
+        ],
+        "additionalProperties": false,
+        "description": "Body for `POST /api/admin/ops/{handle}/link-pr`."
+      },
+      "LinkPrToOpsItemResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Item id that was updated."
+          }
+        },
+        "required": [
+          "id"
+        ],
+        "additionalProperties": false,
+        "description": "Response for the update / link-pr endpoints."
+      },
+      "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)."
           },
-          {
-            "$ref": "#/components/schemas/UpdateFeatureRequestRequest"
+          "createdAt": {
+            "type": "string",
+            "description": "ISO-8601 creation timestamp."
           },
-          {
-            "$ref": "#/components/schemas/UpdateOpsItemStatusRequest"
+          "updatedAt": {
+            "type": "string",
+            "description": "ISO-8601 last-edit timestamp."
           }
+        },
+        "required": [
+          "id",
+          "feedbackId",
+          "parentId",
+          "authorType",
+          "authorEmail",
+          "body",
+          "createdAt",
+          "updatedAt"
         ],
-        "description": "Body for `PATCH /api/admin/ops/{handle}`. The body is type-less — the server validates it against the stored item's type: a `bug` accepts the bug content fields, a `feature_request` the feature fields, and `error`/`alert`/`measure_plan` only `status`/`priority`/`notify`. Pass at least one field."
+        "additionalProperties": false,
+        "description": "A single comment on a queue item."
       },
-      "UpdateOpsItemResponse": {
+      "ListOpsCommentsResponse": {
         "type": "object",
         "properties": {
-          "id": {
-            "type": "string",
-            "description": "Item id that was updated."
+          "comments": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/OpsComment"
+            }
           }
         },
         "required": [
-          "id"
+          "comments"
         ],
         "additionalProperties": false,
-        "description": "Response for the update / link-pr endpoints."
+        "description": "Response for `GET /api/admin/ops/{handle}/comments` — the thread, oldest first."
       },
-      "LinkPrToOpsItemRequest": {
+      "CreateOpsCommentRequest": {
         "type": "object",
         "properties": {
-          "prNumber": {
+          "body": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 10000,
+            "description": "The comment body as markdown. Mentions (`@teammate`, `@shipeasy`) are parsed from it."
+          },
+          "parentId": {
             "anyOf": [
               {
-                "type": "integer",
-                "exclusiveMinimum": 0,
-                "maximum": 9007199254740991
+                "type": "string"
               },
               {
                 "type": "null"
               }
             ],
-            "description": "PR number to record on the item. `null` unlinks the PR."
-          },
-          "prUrl": {
-            "description": "Explicit PR URL. Required for error/alert tickets (no GitHub issue to derive the URL from).",
-            "type": "string",
-            "format": "uri"
+            "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": [
-          "prNumber"
+          "body"
         ],
         "additionalProperties": false,
-        "description": "Body for `POST /api/admin/ops/{handle}/link-pr`."
+        "description": "Body for `POST /api/admin/ops/{handle}/comments`."
       },
-      "LinkPrToOpsItemResponse": {
+      "CreateOpsCommentResponse": {
         "type": "object",
         "properties": {
           "id": {
             "type": "string",
-            "description": "Item id that was updated."
+            "description": "Newly created comment id."
           }
         },
         "required": [
           "id"
         ],
         "additionalProperties": false,
-        "description": "Response for the update / link-pr endpoints."
+        "description": "Response for `POST /api/admin/ops/{handle}/comments`."
       },
       "NotifyOpsRequest": {
         "type": "object",
@@ -16600,8 +17725,15 @@
             }
           },
           "href": {
-            "description": "Dashboard-relative deep link to the related item.",
-            "type": "string"
+            "description": "Dashboard-relative deep link to the related item. `null` is accepted and treated as \"no link\".",
+            "anyOf": [
+              {
+                "type": "string"
+              },
+              {
+                "type": "null"
+              }
+            ]
           },
           "dedupeKey": {
             "description": "Stable per-escalation key (e.g. `feedback:7`) so re-runs dedupe to one row.",
@@ -16940,7 +18072,9 @@
             "type": "string",
             "enum": [
               "free",
-              "paid"
+              "pro",
+              "business",
+              "enterprise"
             ],
             "description": "Billing plan tier."
           },
@@ -17045,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."
@@ -17237,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,
@@ -17902,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.",
@@ -17916,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.",
@@ -18075,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",
@@ -18119,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"
         }
@@ -18816,25 +20207,21 @@
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "`true` when the trigger run was successfully kicked off; `false` when the dispatch itself failed (still HTTP 200, with `error` set)."
-          },
-          "error": {
-            "type": "string",
-            "description": "Failure reason. Present only when `ok` is `false` — the fire reached the handler but the underlying dispatch to the provider failed."
+            "description": "Always `true` — a successful fire returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body."
           }
         },
         "required": [
           "ok"
         ],
         "additionalProperties": false,
-        "description": "Result of firing a trigger connector. `{ ok: true }` on success; `{ ok: false, error }` when the dispatch fails (the request still returns HTTP 200)."
+        "description": "Result of a successful trigger fire: `{ ok: true }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`."
       },
       "TestConnectorResponse": {
         "type": "object",
         "properties": {
           "ok": {
             "type": "boolean",
-            "description": "`true` when the test dispatch reached the destination; `false` when the dispatch itself failed (still HTTP 200, with `error` set)."
+            "description": "Always `true` — a successful test returns HTTP 200. A dispatch failure returns HTTP 502 with the `Error` envelope, not this body."
           },
           "issueUrl": {
             "anyOf": [
@@ -18845,11 +20232,7 @@
                 "type": "null"
               }
             ],
-            "description": "URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact (or the dispatch failed)."
-          },
-          "error": {
-            "type": "string",
-            "description": "Failure reason. Present only when `ok` is `false` — the test reached the handler but the underlying dispatch to the provider failed."
+            "description": "URL of the artifact the test produced (e.g. the GitHub Issue created by a `github` connector), or `null` when the provider produces no linkable artifact."
           }
         },
         "required": [
@@ -18857,7 +20240,7 @@
           "issueUrl"
         ],
         "additionalProperties": false,
-        "description": "Result of testing a connector. `{ ok: true, issueUrl }` on success; `{ ok: false, issueUrl: null, error }` when the dispatch fails (the request still returns HTTP 200)."
+        "description": "Result of a successful connector test: `{ ok: true, issueUrl }`. When the downstream dispatch fails the endpoint returns HTTP 502 (see the `Error` response), never `ok: false`."
       },
       "UpdateClaudeTriggerRequest": {
         "type": "object",
@@ -19221,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": [
@@ -19555,6 +20939,24 @@
             }
           }
         }
+      },
+      "BadGateway": {
+        "description": "The request was well-formed and the resource exists, but a downstream provider\nthe endpoint delegates to (e.g. a connector's Slack/GitHub/cloud-agent dispatch)\nfailed. The failure is upstream of this API, not a client error. No stable\n`ErrorCode` is assigned to upstream failures, so `code` is omitted.",
+        "content": {
+          "application/json": {
+            "schema": {
+              "$ref": "#/components/schemas/Error"
+            },
+            "examples": {
+              "UPSTREAM_FAILURE": {
+                "summary": "Downstream provider dispatch failed",
+                "value": {
+                  "error": "GitHub API responded 403: resource not accessible by integration."
+                }
+              }
+            }
+          }
+        }
       }
     }
   }