@shipeasy/openapi 2.4.0 → 3.0.0

package/openapi.yaml

@@ -207,6 +207,15 @@ tags:
       **Mentions.** `@teammate` in a body raises an in-app notification for that
       person; `@shipeasy` asks Jarvis (the AI agent) to read the item and reply.
       Comments authored by Jarvis carry `authorType: system`.
+  - name: Investigations
+    parent: Ops
+    description: |-
+      Investigation records on a queue item — the structured, read-only write-ups
+      an AI agent produces while working it (findings / a blocking question / QA
+      notes), plus the `working` run rows an ack or an AI hand-off opens. This is
+      the AI-write seam the cockpit's detail panel renders: `list` reads what a
+      previous run found, `create` appends a new record, and `update` fills in the
+      `working` run record you were handed (findings, PR, confidence) as you work.
   - name: Projects
     description: |-
       Projects: the account-level container every other resource is scoped to.
@@ -217,14 +226,14 @@ tags:
   - name: i18n
     description: |-
       String Manager (i18n): the worker-safe REST surface — locale profiles, the
-      insert-only key push, single-key overwrite, chunk publish, and the read-only
+      insert-only key push, single-key overwrite, profile publish, and the read-only
       key/draft listings.
 
       The fs/AST parts (scan, validate, install-loader, codemod) are NOT part of
       this API — they stay in the fs-having CLI/MCP.
   - name: Profiles
     parent: i18n
-    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile's chunks to the CDN.
+    description: Locale profiles (e.g. `en:prod`) — create, list, and publish a profile to the CDN.
   - name: Keys
     parent: i18n
     description: Translation keys — the insert-only push, single-key overwrite, and key listing.
@@ -1997,7 +2006,7 @@ paths:
 
         - **Minimal create** — `name` + `schema`. Initial value defaults to `{}`.
         - **Seeded create** — supply a flat `value` to publish the same object on every env.
-        - **Per-env seed** — supply a `{ env: value }` map for different per-env starting values.
+        - **Per-env seed** — supply a `{ env: value }` map under `value`, or pass the env keys `dev`/`staging`/`prod` directly (each overrides `value` for that env and is published at version 1).
       tags:
         - Configs
       parameters:
@@ -2039,8 +2048,8 @@ paths:
                       - name: free
                       - name: pro
               perEnvSeed:
-                summary: Per-env seed
-                description: 'Pass a `{ env: value }` map to seed different initial values per env.'
+                summary: Per-env seed (env keys)
+                description: Pass the env keys directly to seed different initial values per env. Each overrides `value` for that env and is published at version 1.
                 value:
                   name: pricing.tiers
                   schema:
@@ -2050,20 +2059,15 @@ paths:
                         type: array
                     required:
                       - tiers
-                  value:
-                    dev:
-                      tiers:
-                        - name: free
-                        - name: pro
-                        - name: enterprise
-                    stage:
-                      tiers:
-                        - name: free
-                        - name: pro
-                    prod:
-                      tiers:
-                        - name: free
-                        - name: pro
+                  dev:
+                    tiers:
+                      - name: free
+                      - name: pro
+                      - name: enterprise
+                  prod:
+                    tiers:
+                      - name: free
+                      - name: pro
       responses:
         '201':
           description: Create a dynamic config
@@ -2216,15 +2220,13 @@ paths:
       operationId: updateConfig
       summary: Update a dynamic config
       description: |-
-        Partial update. When `value` is supplied it is **republished on every env** (new version per env). When `schema` is supplied it replaces the current schema; every existing value is re-validated.
-
-        For env-scoped edits, use the draft/publish flow (`PUT /{id}/drafts` then `POST /{id}/publish`) instead.
+        Partial update. When `value` is supplied it is **republished on every env** (new version per env). A per-env key (`dev`/`staging`/`prod`) publishes a new version to **only that env**, immediately, overriding `value` for it. When `schema` is supplied it replaces the current schema; every existing value is re-validated.
 
         **Use cases**
 
         - **Republish flat value** — `{ "value": {…} }` sets the same value on every env.
+        - **Publish one env** — `{ "prod": {…} }` publishes a new version to prod only, instantly.
         - **Schema migration** — `{ "schema": {…} }` replaces the schema; existing values are re-validated.
-        - **Env-scoped edits** — use `PUT /{id}/drafts` + `POST /{id}/publish` instead of PATCH.
       tags:
         - Configs
       parameters:
@@ -2250,6 +2252,15 @@ paths:
                     tiers:
                       - name: free
                       - name: pro
+              prodOnly:
+                summary: Per-env — publish prod only
+                description: Publishes a new version to prod only, immediately. dev/staging untouched.
+                value:
+                  prod:
+                    tiers:
+                      - name: free
+                      - name: pro
+                      - name: enterprise
               schemaOnly:
                 summary: Schema-only update
                 description: Replaces the schema. Existing values must still validate or the update fails.
@@ -2410,6 +2421,7 @@ paths:
         - VALIDATION
       x-cli:
         name: draft
+        hidden: true
         positional:
           - id
     delete:
@@ -2469,6 +2481,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: discard-draft
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/publish:
@@ -2540,6 +2553,7 @@ paths:
         - VALIDATION
       x-cli:
         name: publish
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/activity:
@@ -2604,6 +2618,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: activity
+        hidden: true
         positional:
           - id
   /api/admin/configs/{id}/schema:
@@ -2739,6 +2754,7 @@ paths:
         - NOT_FOUND
       x-cli:
         name: versions
+        hidden: true
         positional:
           - id
   /api/admin/killswitches:
@@ -5531,7 +5547,7 @@ paths:
         **Use case:** Read what a previous agent run already found before starting
         your own investigation of the item.
       tags:
-        - Ops
+        - Investigations
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -5562,6 +5578,10 @@ paths:
         - UNAUTHORIZED
         - FORBIDDEN
         - NOT_FOUND
+      x-cli:
+        name: list
+        positional:
+          - handle
     post:
       operationId: createOpsInvestigation
       summary: Record an investigation
@@ -5577,7 +5597,7 @@ paths:
         markdown findings, sources inspected, confidence) so the team — and the
         next agent run — sees what you learned.
       tags:
-        - Ops
+        - Investigations
       parameters:
         - $ref: '#/components/parameters/ProjectId'
         - name: handle
@@ -5635,6 +5655,85 @@ paths:
         - FORBIDDEN
         - NOT_FOUND
         - VALIDATION
+      x-cli:
+        name: create
+        positional:
+          - handle
+  /api/admin/ops/{handle}/investigation/{investigationId}:
+    patch:
+      operationId: updateOpsInvestigation
+      summary: Update an investigation record
+      description: |-
+        Update one existing investigation record in place — the write-back seam for
+        the `working` run record you were handed when a run was launched. Fill in
+        the `summary`/`findings`, attach the fixing PR, record your `confidence`
+        and the `sources` you inspected, or flip its `kind` off `working` once the
+        investigation is done. A partial patch: send only the fields you want to
+        change. Safe for restricted ops keys (it never reads or deletes).
+
+        **Use case:** A run started with an empty `working` record; as you work,
+        PATCH it with your findings so the cockpit's detail panel fills in live —
+        no need to append a second record.
+      tags:
+        - Investigations
+      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'
+        - name: investigationId
+          in: path
+          required: true
+          description: The investigation record id (from `POST`/`GET .../investigation` or the `runId` an ack/launch returned).
+          schema:
+            $ref: '#/components/schemas/ResourceId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateOpsInvestigationRequest'
+            examples:
+              findings:
+                summary: Fill in the run record's findings
+                value:
+                  kind: investigated
+                  summary: Root cause is a stale KV read on the checkout flag.
+                  findings: The `checkout.cta` gate is rebuilt without a CDN purge, so…
+                  confidence: high
+                  prNumber: 4821
+                  prUrl: https://github.com/acme/web/pull/4821
+      responses:
+        '200':
+          description: The updated investigation record
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/OpsInvestigation'
+        '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: update
+        positional:
+          - handle
+          - investigationId
   /api/admin/agent-profiles:
     get:
       operationId: listOpsAgents
@@ -6599,7 +6698,7 @@ paths:
       description: |-
         Returns every locale profile in the project (e.g. `en:prod`, `fr:prod`).
 
-        **Use case:** Discover which locale profiles exist before pushing keys or publishing a chunk.
+        **Use case:** Discover which locale profiles exist before pushing keys or publishing.
       tags:
         - Profiles
       parameters:
@@ -6768,11 +6867,13 @@ paths:
         name: list
     post:
       operationId: pushI18nKeys
-      summary: Push new i18n keys (insert-only)
+      summary: Push i18n keys (insert-only, or `force` to overwrite)
       description: |-
-        Add NEW keys to a profile. Insert-only — existing keys are left untouched (overwrite one with `updateI18nKey`).
+        Add NEW keys to a profile. Insert-only by default — existing keys are left untouched and reported back as `skipped`.
 
-        **Use case:** Seed newly-extracted keys without clobbering translations already in the profile.
+        Pass `force: true` to overwrite the existing ones in bulk with the submitted values: they come back as `updated` instead of `skipped`. Without `force` the only overwrite paths are `updateI18nKey` (one key) and the devtools-only `upsertI18nKeys`.
+
+        **Use case:** Seed newly-extracted keys without clobbering translations already in the profile — or re-push a whole source-language file with `force` after the copy changed.
       tags:
         - Keys
       parameters:
@@ -6790,7 +6891,7 @@ paths:
                   value: Buy now
       responses:
         '201':
-          description: Push new i18n keys (insert-only)
+          description: Push i18n keys (insert-only, or `force` to overwrite)
           content:
             application/json:
               schema:
@@ -6799,8 +6900,10 @@ paths:
                 added:
                   - checkout.cta
                 skipped: []
+                updated: []
                 pushed_count: 1
                 skipped_count: 0
+                updated_count: 0
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -6854,7 +6957,6 @@ paths:
                 $ref: '#/components/schemas/UpsertI18nKeysResponse'
               example:
                 upserted: 1
-                chunk: default
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
@@ -7321,7 +7423,7 @@ paths:
       operationId: publishI18nProfile
       summary: Publish a profile live
       description: |-
-        Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the optional `chunk` in the body is an audit label only (it does not scope what ships).
+        Publish a profile to the CDN — rebuild its KV snapshot + purge the edge. Publishing is PROFILE-WIDE: the whole profile is snapshotted into one KV blob, so the body takes no options.
 
         **Use case:** Ship the latest translations live after pushing/updating keys.
       tags:
@@ -7335,16 +7437,15 @@ paths:
           schema:
             $ref: '#/components/schemas/ResourceId'
       requestBody:
-        required: true
+        required: false
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/PublishI18nProfileRequest'
-            example:
-              chunk: default
+            example: {}
       responses:
         '200':
-          description: Publish a profile chunk
+          description: Publish a profile
           content:
             application/json:
               schema:
@@ -9217,6 +9318,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -9618,6 +9722,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -9917,6 +10024,9 @@ components:
                       locked:
                         description: If `true`, dashboard hides edit controls (e.g. the trailing public-floor entry).
                         type: boolean
+                      whitelist:
+                        description: Cosmetic marker. When `true`, the dashboard renders this condition as the pinned, always-first "whitelist" allowlist block (a direct `email`/`user_id` `in […]` list) rather than a numbered targeting step. Purely presentational — ignored by evaluation, which treats the entry as an ordinary condition.
+                        type: boolean
                     required:
                       - id
                       - type
@@ -11405,12 +11515,26 @@ components:
           additionalProperties: {}
           description: JSON Schema (draft 2020-12) describing the shape of the config value. Top-level `type` must be `'object'`; every published value is validated against this schema.
         value:
+          type: object
+          additionalProperties: {}
           description: 'Initial config value. Either a single JSON object applied to every env, or a `{ env: value }` map seeding per-env values. Must match `schema`. Defaults to `{}` on every env when omitted.'
+        dev:
+          type: object
+          additionalProperties: {}
+          description: Seed the **dev** env's initial value (version 1), overriding `value` for dev. Published immediately. Must match `schema`.
+        staging:
+          type: object
+          additionalProperties: {}
+          description: Seed the **staging** env's initial value (version 1), overriding `value` for staging. Published immediately. Must match `schema`.
+        prod:
+          type: object
+          additionalProperties: {}
+          description: Seed the **prod** env's initial value (version 1), overriding `value` for prod. Published immediately. Must match `schema`.
       required:
         - name
         - schema
       additionalProperties: false
-      description: Body for `POST /api/admin/configs`. `name` + `schema` required.
+      description: Body for `POST /api/admin/configs`. `name` + `schema` required. Per-env `dev`/`staging`/`prod` values are published to that env at version 1 (overriding `value`).
     CreateConfigResponse:
       type: object
       properties:
@@ -11540,11 +11664,25 @@ components:
           type: object
           additionalProperties: {}
         value:
-          description: Flat value applied to **every** env. Publishes a new version per env. To target one env, use `PUT /{id}/drafts` then `POST /{id}/publish`.
+          type: object
+          additionalProperties: {}
+          description: Flat value applied to **every** env. Publishes a new version per env. To publish one env only, pass that env's key (`dev`/`staging`/`prod`) instead.
+        dev:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **dev** env only, immediately (no draft). Overrides `value` for dev. Must match the effective schema.
+        staging:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **staging** env only, immediately (no draft). Overrides `value` for staging. Must match the effective schema.
+        prod:
+          type: object
+          additionalProperties: {}
+          description: Publish a new version to the **prod** env only, immediately (no draft). Overrides `value` for prod. Must match the effective schema.
         folder:
           $ref: '#/components/schemas/Folder'
       additionalProperties: false
-      description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env.
+      description: Body for `PATCH /api/admin/configs/{id}`. Partial — only supplied fields change. `value` republishes on every env; per-env `dev`/`staging`/`prod` publish a new version to just that env.
     UpdateConfigResponse:
       type: object
       properties:
@@ -11567,6 +11705,8 @@ components:
         env:
           $ref: '#/components/schemas/Env'
         value:
+          type: object
+          additionalProperties: {}
           description: Draft value to stage on `env`. Validated against the config's current schema.
       required:
         - env
@@ -13123,6 +13263,11 @@ components:
         - lower_better
         - neutral
       description: Desired direction of movement. `higher_better` (default), `lower_better`, or `neutral` (guardrail).
+    MetricDisplayUnit:
+      description: Display unit (e.g. `ms`, `%`, `$`), or `null` when unitless.
+      anyOf:
+        - type: string
+        - type: 'null'
     CreateMetricWithQuery:
       type: object
       properties:
@@ -13140,6 +13285,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - name
         - event_name
@@ -13163,6 +13310,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - name
         - event_name
@@ -13300,6 +13449,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - query
       additionalProperties: false
@@ -13319,6 +13470,8 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       required:
         - query_ir
       additionalProperties: false
@@ -13336,8 +13489,10 @@ components:
           $ref: '#/components/schemas/MetricDefaultMinEffectOfInterest'
         direction:
           $ref: '#/components/schemas/MetricDirection'
+        unit:
+          $ref: '#/components/schemas/MetricDisplayUnit'
       additionalProperties: false
-      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction).
+      description: Update-metric variant that leaves the query untouched (metadata-only edit — folder, event, winsorisation, default minimum effect of interest, direction, display unit).
     UpdateMetricRequest:
       oneOf:
         - $ref: '#/components/schemas/UpdateMetricWithQuery'
@@ -14329,6 +14484,19 @@ components:
         - agent
       additionalProperties: false
       description: 'The fully-resolved owner of a queue item — a person and/or an AI agent. The two halves are independent: an item may have a person, an agent, both, or neither (both `null`).'
+    OpsRunAction:
+      type: string
+      enum:
+        - link_pr
+        - notify
+        - status
+        - superseded
+      description: The final action that closed a run record — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing an open run.
+    OpsRunActionOrNull:
+      anyOf:
+        - $ref: '#/components/schemas/OpsRunAction'
+        - type: 'null'
+      description: Which final action closed the run, or `null` while it is open (or a non-run record).
     OpsRun:
       type: object
       properties:
@@ -14355,6 +14523,11 @@ components:
             - type: string
             - type: 'null'
           description: The agent-run session id recorded on the ack (dashboard deep-links to the run page), or `null`.
+        sessionUrl:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone.'
         startedAt:
           type: string
           description: ISO-8601 timestamp the run started (the ack time).
@@ -14364,15 +14537,7 @@ components:
             - type: 'null'
           description: ISO-8601 timestamp the run closed, or `null` while still open.
         completedAction:
-          anyOf:
-            - type: string
-              enum:
-                - link_pr
-                - notify
-                - status
-                - superseded
-            - type: 'null'
-          description: Which final action closed the run — `link_pr`/`notify` are the agent's terminal ops actions, `status` a completion status flip (ready_for_qa/resolved), `superseded` a newer ack replacing it. `null` while the run is open.
+          $ref: '#/components/schemas/OpsRunActionOrNull'
         prNumber:
           anyOf:
             - type: number
@@ -14389,6 +14554,7 @@ components:
         - connectorId
         - ackedBy
         - sessionId
+        - sessionUrl
         - startedAt
         - completedAt
         - completedAction
@@ -14562,6 +14728,28 @@ components:
             - $ref: '#/components/schemas/OpsItemPriority'
             - type: 'null'
           description: Initial triage priority, or `null`.
+        status:
+          anyOf:
+            - $ref: '#/components/schemas/OpsItemStatus'
+          description: Initial lifecycle status; defaults to `open` when omitted.
+        assigneeId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The `users.id` of the person to assign as owner at creation, or `null`.
+        subscribers:
+          type: array
+          items:
+            type: string
+            format: email
+          default: []
+          description: Emails of teammates to subscribe to this item's Slack pings at creation.
+        tags:
+          type: array
+          items:
+            type: string
+          default: []
+          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
         reporterEmail:
           anyOf:
             - type: string
@@ -14631,6 +14819,28 @@ components:
             - $ref: '#/components/schemas/OpsItemPriority'
             - type: 'null'
           description: Initial triage priority, or `null`.
+        status:
+          anyOf:
+            - $ref: '#/components/schemas/OpsItemStatus'
+          description: Initial lifecycle status; defaults to `open` when omitted.
+        assigneeId:
+          anyOf:
+            - type: string
+            - type: 'null'
+          description: The `users.id` of the person to assign as owner at creation, or `null`.
+        subscribers:
+          type: array
+          items:
+            type: string
+            format: email
+          default: []
+          description: Emails of teammates to subscribe to this item's Slack pings at creation.
+        tags:
+          type: array
+          items:
+            type: string
+          default: []
+          description: Tag names to attach at creation (get-or-created by name, deduped case-insensitively).
         reporterEmail:
           anyOf:
             - type: string
@@ -15210,21 +15420,18 @@ components:
             - type: string
             - type: 'null'
           description: The agent-run session id, or `null`.
-        ackedBy:
+        sessionUrl:
           anyOf:
             - type: string
             - type: 'null'
-          description: Email of the human who acked (run records for a human ack), or `null`.
-        completedAction:
+          description: 'The run''s session-page deep link, or `null`. DERIVED (never stored): rebuilt from `sessionId` + the run''s trigger connector — Claude''s routine id (`?trigger=`), Copilot''s repo (`/tasks/`), Cursor/Jules from the id alone. Only `working` run records carry one.'
+        ackedBy:
           anyOf:
             - type: string
-              enum:
-                - link_pr
-                - notify
-                - status
-                - superseded
             - type: 'null'
-          description: Which final action closed a `working` run record, or `null` (open run / non-run record).
+          description: Email of the human who acked (run records for a human ack), or `null`.
+        completedAction:
+          $ref: '#/components/schemas/OpsRunActionOrNull'
         createdAt:
           type: string
           description: ISO-8601 creation timestamp.
@@ -15252,6 +15459,7 @@ components:
         - startedAt
         - completedAt
         - sessionId
+        - sessionUrl
         - ackedBy
         - completedAction
         - createdAt
@@ -15368,6 +15576,94 @@ components:
         - kind
       additionalProperties: false
       description: Body for `POST /api/admin/ops/{handle}/investigation`. `kind` is required; include at least one content field (`summary`/`findings`/`question`/`qaNotes`) — the panel renders whatever it gets.
+    UpdateOpsInvestigationRequest:
+      type: object
+      properties:
+        kind:
+          type: string
+          enum:
+            - investigated
+            - detected
+            - question
+            - ready_for_qa
+            - working
+            - note
+          description: Reclassify the record's lifecycle stage (e.g. flip a `working` run into `investigated` once findings land).
+        summary:
+          type: string
+          maxLength: 2000
+          description: One-line summary of the record.
+        findings:
+          type: string
+          maxLength: 50000
+          description: The full findings write-up (markdown).
+        question:
+          type: string
+          maxLength: 10000
+          description: A blocking question for the team (markdown).
+        qaNotes:
+          type: string
+          maxLength: 50000
+          description: How to verify the fix — QA notes (markdown).
+        model:
+          type: string
+          maxLength: 200
+          description: The model the agent ran on.
+        prNumber:
+          type: integer
+          description: A PR the record references.
+        prUrl:
+          type: string
+          format: uri
+          maxLength: 2000
+          description: HTML URL of that PR.
+        sources:
+          type: array
+          maxItems: 200
+          items:
+            type: object
+            properties:
+              path:
+                type: string
+                description: Repo-relative file path inspected.
+              url:
+                type: string
+                description: External link consulted.
+              label:
+                type: string
+                description: Human-readable label for the source.
+            additionalProperties: false
+            description: One file/link inspected while producing the record.
+          description: The files/links inspected.
+        confidence:
+          type: string
+          enum:
+            - low
+            - medium
+            - high
+          description: Self-reported confidence in the record.
+        tokensUsed:
+          type: integer
+          description: Tokens the run consumed.
+        durationMs:
+          type: integer
+          description: Run duration in milliseconds.
+        visibility:
+          type: string
+          enum:
+            - draft
+            - published
+          description: Record visibility. `draft` keeps it out of the panel; `published` surfaces it.
+        completedAt:
+          type: string
+          description: ISO-8601 timestamp the work finished. Set it (or flip `kind` off `working`) to mark a run record done.
+        sessionId:
+          type: string
+          maxLength: 300
+          description: The agent-run session id, so the dashboard can deep-link to the run.
+      additionalProperties: false
+      minProperties: 1
+      description: Body for `PATCH /api/admin/ops/{handle}/investigation/{investigationId}` — a partial update of one existing investigation record (typically the `working` run record you were handed). Send only the fields you want to change; at least one is required.
     OpsAgentProfile:
       type: object
       properties:
@@ -16436,14 +16732,6 @@ components:
                 anyOf:
                   - type: string
                   - type: 'null'
-              chunkId:
-                description: Owning chunk (authoring grouping) id.
-                type: string
-              chunkName:
-                description: Name of the owning chunk (authoring grouping), or `null` when it cannot be resolved.
-                anyOf:
-                  - type: string
-                  - type: 'null'
               updatedAt:
                 description: ISO-8601 timestamp of the last edit.
                 type: string
@@ -16458,8 +16746,6 @@ components:
               - variables
               - profileId
               - profileName
-              - chunkId
-              - chunkName
               - updatedAt
               - updatedBy
             additionalProperties: false
@@ -16480,12 +16766,6 @@ components:
           type: string
           format: uuid
           description: Target profile id to upsert keys into.
-        chunk:
-          description: Logical grouping the keys are filed under. Defaults to `default`.
-          type: string
-          minLength: 1
-          maxLength: 64
-          default: default
         keys:
           type: array
           minItems: 1
@@ -16528,12 +16808,8 @@ components:
         upserted:
           type: number
           description: Number of keys written (inserted or overwritten).
-        chunk:
-          type: string
-          description: The chunk the keys were filed under.
       required:
         - upserted
-        - chunk
       additionalProperties: false
       description: Result of a bulk key upsert. The affected profile's KV snapshot is rebuilt (and the CDN purged) before this returns.
     PushI18nKeysRequest:
@@ -16543,12 +16819,6 @@ components:
           type: string
           format: uuid
           description: Target profile id to add keys to.
-        chunk:
-          description: Logical grouping the new keys are filed under. Defaults to `default`.
-          type: string
-          minLength: 1
-          maxLength: 64
-          default: default
         keys:
           type: array
           minItems: 1
@@ -16579,12 +16849,16 @@ components:
               - key
               - value
             additionalProperties: false
-          description: Keys to add. Insert-only — existing keys are reported back as `skipped`.
+          description: Keys to add. Insert-only by default — existing keys are reported back as `skipped` (set `force` to overwrite them instead).
+        force:
+          type: boolean
+          default: false
+          description: Overwrite keys that already exist with the submitted value instead of skipping them. Overwritten keys come back as `updated`. Off by default so a routine push can never clobber live translations.
       required:
         - profile_id
         - keys
       additionalProperties: false
-      description: 'Body for `POST /api/admin/i18n/keys`. Insert-only: keys that already exist are never overwritten — use `PUT /keys/{id}` to change a value.'
+      description: 'Body for `POST /api/admin/i18n/keys`. Insert-only by default: keys that already exist are never overwritten — pass `force: true` to overwrite them in bulk, or use `PUT /keys/{id}` to change one value.'
     PushI18nKeysResponse:
       type: object
       properties:
@@ -16597,23 +16871,30 @@ components:
           type: array
           items:
             type: string
-          description: Key names that already existed and were left untouched.
+          description: Key names that already existed and were left untouched. Always empty when `force` was set — those key names come back under `updated` instead.
+        updated:
+          type: array
+          items:
+            type: string
+          description: Key names that already existed and were overwritten with the submitted value. Only ever non-empty when the push set `force`.
         pushed_count:
           type: number
           description: Number of keys inserted (== `added.length`).
         skipped_count:
           type: number
           description: Number of keys skipped (== `skipped.length`).
-        chunk:
-          description: The chunk the keys were filed under.
-          type: string
+        updated_count:
+          type: number
+          description: Number of existing keys overwritten (== `updated.length`).
       required:
         - added
         - skipped
+        - updated
         - pushed_count
         - skipped_count
+        - updated_count
       additionalProperties: false
-      description: Result of an insert-only key push.
+      description: Result of a key push — what was inserted, what was left alone, and (with `force`) what was overwritten.
     UpdateI18nKeyRequest:
       type: object
       properties:
@@ -16808,12 +17089,9 @@ components:
       description: Body for `POST /api/admin/i18n/drafts/{draftId}/keys`. Upserts one staged key into an open draft — inserted when new, overwritten when it already exists. `{{var}}` placeholder names are auto-derived from the value.
     PublishI18nProfileRequest:
       type: object
-      properties:
-        chunk:
-          description: Optional chunk label to stamp on the audit log. Publishing is profile-wide regardless — the whole profile is snapshotted into one KV blob.
-          type: string
+      properties: {}
       additionalProperties: false
-      description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. The `chunk` is an audit label only.
+      description: Body for `POST /api/admin/i18n/profiles/{profileId}/publish`. Publishing is profile-wide — the whole profile is snapshotted into one KV blob — so the body takes no options.
     PublishI18nProfileResponse:
       type: object
       properties:
@@ -16824,11 +17102,6 @@ components:
         profile_id:
           type: string
           description: Profile that was published.
-        chunk:
-          anyOf:
-            - type: string
-            - type: 'null'
-          description: Audit chunk label, or `null` when none was given.
         published_at:
           type: string
           description: ISO-8601 timestamp of the publish.
@@ -16857,7 +17130,6 @@ components:
       required:
         - ok
         - profile_id
-        - chunk
         - published_at
         - version
         - key_count