@shipeasy/openapi 1.6.0 → 2.2.0

package/spec/paths/connectors.yaml

@@ -0,0 +1,782 @@
+/api/admin/connectors:
+  get:
+    operationId: listConnectors
+    summary: List connectors
+    description: |-
+      Returns every connector in the project as a bare array (no pagination envelope).
+
+      The encrypted credentials backing each connector are never serialised — only the connector's non-secret `config`, `accountLabel`, and last-attempt health (`lastError`, `lastAttemptAt`, `lastSuccessAt`) are returned.
+
+      **Use case:** Render the integrations/triggers settings page, or drive a CI check that asserts every `github` connector is `enabled` and last dispatched without error.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - $ref: ../components/parameters.yaml#/Q
+    responses:
+      "200":
+        description: List connectors
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/ListConnectorsResponse
+            example:
+              - id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+                projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
+                provider: github
+                name: Bugs → acme/app issues
+                enabled: true
+                events:
+                  - bug.created
+                config:
+                  owner: acme
+                  repo: app
+                accountLabel: acme/app
+                lastError: null
+                lastAttemptAt: 2026-06-27T18:04:11.000Z
+                lastSuccessAt: 2026-06-27T18:04:11.000Z
+                createdAt: 2026-06-01T09:12:00.000Z
+                updatedAt: 2026-06-27T18:04:11.000Z
+              - id: 2d44f0aa-9c81-4e6b-8a17-7b3e0f9c1a22
+                projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
+                provider: claude_trigger
+                name: Nightly ops sweep
+                enabled: true
+                events: []
+                config:
+                  routineId: rtn_8fk20
+                accountLabel: rtn_8fk20
+                lastError: null
+                lastAttemptAt: null
+                lastSuccessAt: null
+                createdAt: 2026-06-20T22:00:00.000Z
+                updatedAt: 2026-06-20T22:00:00.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+    x-cli:
+      name: list
+  post:
+    operationId: createConnector
+    summary: Create a connector
+    description: |-
+      Creates a connector. The request body is discriminated on `provider`.
+
+      - **OAuth/app providers** (`google_sheets`, `github`, `slack`) — supply `{ provider, name, events }`. The connector is created `enabled: false` with empty `config` and no credentials; the provider's OAuth flow then attaches credentials and enables it.
+      - **Trigger providers** (`claude_trigger`, `cursor_trigger`, `copilot_trigger`, `jules_trigger`) — supply `config` plus the provider's credential field(s) and the connector is fireable immediately. Trigger creates are **idempotent** by their natural key (`config.routineId` / `config.repoUrl` / `config.owner`+`config.repo` / `config.source`): re-creating updates the existing row rather than duplicating it.
+
+      **Use cases**
+
+      - **File bugs as GitHub Issues** — `{ "provider": "github", "name": "Bugs → acme/app", "events": ["bug.created"] }`, then finish the GitHub App install.
+      - **Nightly ops sweep** — register a `claude_trigger` with its `routineId` and (optionally) a fire `token`; subscribe `events` later to auto-fire on new bugs.
+      - **Cold cloud-agent run** — register a `cursor_trigger`/`jules_trigger` with the repo coordinates plus both keys, or a `copilot_trigger` with the repo + user PAT.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/connectors.yaml#/CreateConnectorRequest
+          examples:
+            githubStub:
+              summary: GitHub — OAuth/app stub
+              description: "Creates a disabled `github` connector subscribed to `bug.created`. Finish the GitHub App install to attach credentials and enable it."
+              value:
+                provider: github
+                name: Bugs → acme/app issues
+                events:
+                  - bug.created
+            claudeTrigger:
+              summary: Claude trigger — tokened
+              description: "Registers a Claude Code routine trigger with its fire token. Idempotent by `config.routineId`. `events` left empty so it does not auto-fire paid runs yet."
+              value:
+                provider: claude_trigger
+                name: Nightly ops sweep
+                config:
+                  routineId: rtn_8fk20
+                  fireText: Burn down the open bug + feature-request queue.
+                token: rtk_live_3f9a…
+            cursorTrigger:
+              summary: Cursor trigger — cold cloud agent
+              description: "Both keys required up front: the Cursor `apiKey` launches the run, the `opsKey` is injected as SHIPEASY_CLI_TOKEN. Idempotent by `config.repoUrl`."
+              value:
+                provider: cursor_trigger
+                name: Cursor ops agent
+                config:
+                  repoUrl: https://github.com/acme/app
+                  projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
+                apiKey: cur_live_…
+                opsKey: ops_…
+    responses:
+      "201":
+        description: Create a connector
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/CreateConnectorResponse
+            example:
+              id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+        links:
+          GetConnector:
+            operationId: getConnector
+            parameters: { id: $response.body#/id }
+          UpdateConnector:
+            operationId: updateConnector
+            parameters: { id: $response.body#/id }
+          TestConnector:
+            operationId: testConnector
+            parameters: { id: $response.body#/id }
+          DeleteConnector:
+            operationId: deleteConnector
+            parameters: { id: $response.body#/id }
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - VALIDATION
+    x-cli:
+      name: create
+/api/admin/connectors/{id}:
+  get:
+    operationId: getConnector
+    summary: Get a connector
+    description: |-
+      Returns a single connector by id. The encrypted credentials are never serialised.
+
+      **Use case:** Inspect one connector's health — its `enabled` state, subscribed `events`, and last-attempt outcome (`lastError`/`lastSuccessAt`).
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Get a connector
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/GetConnectorResponse
+            example:
+              id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+              projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
+              provider: github
+              name: Bugs → acme/app issues
+              enabled: true
+              events:
+                - bug.created
+              config:
+                owner: acme
+                repo: app
+              accountLabel: acme/app
+              lastError: null
+              lastAttemptAt: 2026-06-27T18:04:11.000Z
+              lastSuccessAt: 2026-06-27T18:04:11.000Z
+              createdAt: 2026-06-01T09:12:00.000Z
+              updatedAt: 2026-06-27T18:04:11.000Z
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: get
+      positional:
+        - id
+  patch:
+    operationId: updateConnector
+    summary: Update a connector
+    description: |-
+      Partial update — only supplied fields change. `events` and `config` **replace** wholesale; there is no merge or append. Secrets cannot be set through this endpoint (credential rotation goes through the provider-specific re-register flow).
+
+      The response carries only `{ id }` — re-fetch via `GET /api/admin/connectors/{id}` for the new row.
+
+      **Use cases**
+
+      - **Pause a connector** — `{ "enabled": false }`. Stops all dispatch / auto-fire without deleting it.
+      - **Change subscribed events** — send the full new `events` array. An empty array unsubscribes the connector from every event.
+      - **Rename** — `{ "name": "Bugs → acme/app issues" }`.
+      - **Retarget** — send a new `config` (e.g. a different Sheets `sheetTitle`); it replaces the stored config wholesale.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/connectors.yaml#/UpdateConnectorRequest
+          examples:
+            pause:
+              summary: Pause — disable the connector
+              description: 'Stops all dispatch / auto-fire. Re-enable with `{ "enabled": true }`.'
+              value:
+                enabled: false
+            resubscribe:
+              summary: Replace subscribed events
+              description: "Array fields replace wholesale. Send the full new list; an empty array unsubscribes from everything."
+              value:
+                events:
+                  - bug.created
+                  - feature_request.created
+            retarget:
+              summary: Retarget config
+              description: Replaces the stored non-secret config wholesale.
+              value:
+                config:
+                  spreadsheetId: 1AbC…
+                  sheetTitle: Bugs Q3
+    responses:
+      "200":
+        description: Update a connector
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/UpdateConnectorResponse
+            example:
+              id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: update
+      positional:
+        - id
+  delete:
+    operationId: deleteConnector
+    summary: Delete a connector
+    description: |-
+      Permanently removes the connector and its stored credentials.
+
+      **Use case:** Disconnect an integration for good — e.g. tear down a `github` connector after migrating bug routing elsewhere.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: Delete a connector
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/DeleteConnectorResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: archive
+      positional:
+        - id
+/api/admin/connectors/{id}/fire:
+  post:
+    operationId: fireConnector
+    summary: Fire a trigger connector
+    description: |-
+      Manually kicks a trigger connector's run — Claude (kicks its preconfigured routine) or Cursor / Copilot / Jules (launches a cold cloud-agent run). Firing is event-less: it kicks the run with an optional caller-supplied prompt override rather than dispatching a single lifecycle payload.
+
+      Only trigger providers can be fired, and only once authenticated (a tokenless trigger cannot fire). The attempt's outcome is recorded on the connector's `lastAttemptAt` / `lastError` / `lastSuccessAt`.
+
+      **Use case:** Kick a one-off ops sweep on demand from the dashboard's "Fire now" button, optionally overriding the routine's default prompt.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: false
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/connectors.yaml#/FireConnectorRequest
+          examples:
+            default:
+              summary: Fire with the provider default prompt
+              description: Empty body — kicks the run with the provider's own default (Claude → configured `fireText`, others → built cold-start prompt).
+              value: {}
+            override:
+              summary: Fire with a prompt override
+              value:
+                text: Triage only the P0 bugs reported in the last 24h.
+    responses:
+      "200":
+        description: The trigger run was successfully kicked off.
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/FireConnectorResponse
+            example:
+              ok: true
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: fire
+      positional:
+        - id
+/api/admin/connectors/{id}/test:
+  post:
+    operationId: testConnector
+    summary: Test a connector
+    description: |-
+      Dispatches a single synthetic `bug.created` payload to the connector's destination so you can verify the integration end-to-end. Unlike `fire`, this runs the real dispatch path (posts a Slack message / appends a Sheets row / files a GitHub Issue) with throwaway test content. The attempt's outcome is recorded on the connector's `lastAttemptAt` / `lastError` / `lastSuccessAt`.
+
+      When the provider produces a linkable artifact (e.g. a GitHub Issue), its URL is returned as `issueUrl`; otherwise `issueUrl` is `null`.
+
+      **Use case:** Click "Send test" after wiring up a connector to confirm credentials and config are correct before relying on it for real events.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    responses:
+      "200":
+        description: The test dispatch reached the destination.
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/TestConnectorResponse
+            example:
+              ok: true
+              issueUrl: https://github.com/acme/app/issues/4217
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+      "502":
+        $ref: ../components/responses.yaml#/BadGateway
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+    x-cli:
+      name: test
+      positional:
+        - id
+/api/admin/connectors/{id}/trigger:
+  patch:
+    operationId: updateTriggerConnector
+    summary: Update a trigger connector
+    description: |-
+      Edit an existing coding-agent **trigger** connector (`claude_trigger` / `cursor_trigger` / `copilot_trigger` / `jules_trigger`) — replace its non-secret `config` and, optionally, rotate its credential secret(s). Discriminated on `provider`; the id in the path selects the connector and its `provider` must match the body.
+
+      Unlike the generic `PATCH /api/admin/connectors/{id}` (which cannot touch secrets), this endpoint always replaces the non-secret `config` wholesale and merges any supplied secret over the stored credential cipher — so a single half of a two-key pair (e.g. just the ops key) can be rotated on its own. A blank/omitted secret leaves the stored cipher untouched.
+
+      The response carries only `{ id }` — re-fetch via `GET /api/admin/connectors/{id}` for the new row.
+
+      **Use case:** Re-point a Cursor trigger at a new repo ref, or rotate a Claude trigger's fire token, without deleting and re-creating the connector.
+    tags:
+      - Connectors
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+      - name: id
+        in: path
+        required: true
+        description: Stable opaque connector id. Its stored `provider` must match the body's `provider`.
+        schema:
+          $ref: ../components/schemas/common.yaml#/ResourceId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/connectors.yaml#/UpdateTriggerConnectorRequest
+          examples:
+            claude:
+              summary: Claude — repoint routine, rotate token
+              description: Replaces the routine config and rotates the fire token.
+              value:
+                provider: claude_trigger
+                config:
+                  routineId: rtn_9f2c
+                token: fire_live_a1b2c3
+            cursor:
+              summary: Cursor — rotate just the ops key
+              description: Leaves the launch key untouched, rotates only the restricted ops key.
+              value:
+                provider: cursor_trigger
+                config:
+                  repoUrl: https://github.com/acme/app
+                  projectId: f81d4fae-7dec-11d0-a765-00a0c91e6bf6
+                opsKey: sdk_ops_live_x9y8z7
+    responses:
+      "200":
+        description: Update a trigger connector
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/UpdateConnectorResponse
+            example:
+              id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "404":
+        $ref: ../components/responses.yaml#/NotFound
+      "409":
+        $ref: ../components/responses.yaml#/Conflict
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - NOT_FOUND
+      - VALIDATION
+    x-cli:
+      name: trigger
+      positional:
+        - id
+/api/admin/connectors/trigger:
+  post:
+    operationId: createTriggerConnector
+    summary: Create a recurring coding-agent trigger
+    description: |-
+      Creates (or idempotently updates) a coding-agent **trigger** connector — the recurring, unattended run that burns down the ops queue in `--pr` mode. Discriminated on `provider`; only the four Shipeasy-fireable providers are accepted (`claude_trigger`, `cursor_trigger`, `copilot_trigger`, `jules_trigger`). Config + credential(s) arrive together; creates are idempotent by the provider's natural key, so re-creating updates the existing row.
+
+      Platforms without a fire endpoint (Codex, Windsurf, Cline, OpenClaw, OpenCode, Continue) cannot be created here — they are scheduled on their own platform (typically a GitHub Actions `schedule:` cron running the platform's headless CLI with the trigger prompt).
+
+      **Use cases**
+
+      - **Register a Claude routine** — after `RemoteTrigger {action:"create"}` returns `trig_…`, `{ "provider": "claude_trigger", "config": { "routineId": "trig_…" } }` (tokenless is fine; add the fire token later).
+      - **Cold Cursor/Jules run** — repo coordinates + both keys; Shipeasy launches the run and the PR opens via the provider's GitHub App.
+      - **Copilot cloud agent** — repo + a Copilot-licensed user PAT with the "Agent tasks" permission.
+    tags:
+      - Trigger
+    parameters:
+      - $ref: ../components/parameters.yaml#/ProjectId
+    requestBody:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: ../components/schemas/connectors.yaml#/CreateTriggerConnectorRequest
+          examples:
+            claude:
+              summary: Claude routine (tokenless)
+              value:
+                provider: claude_trigger
+                name: Nightly ops sweep
+                config:
+                  routineId: trig_8fk20
+            cursor:
+              summary: Cursor cold cloud agent
+              value:
+                provider: cursor_trigger
+                name: Cursor ops agent
+                config:
+                  repoUrl: https://github.com/acme/app
+                  projectId: prj_01j7w7m9q4hxbf6npe6s9zr3vc
+                apiKey: cur_live_…
+                opsKey: ops_…
+    responses:
+      "201":
+        description: Trigger connector created (or idempotently updated)
+        content:
+          application/json:
+            schema:
+              $ref: ../components/schemas/connectors.yaml#/CreateConnectorResponse
+            example:
+              id: 9b0e7c2a-1f3d-4a8e-bf21-0c6a2e5d7f10
+        links:
+          FireConnector:
+            operationId: fireConnector
+            parameters: { id: $response.body#/id }
+          TestConnector:
+            operationId: testConnector
+            parameters: { id: $response.body#/id }
+          GetConnector:
+            operationId: getConnector
+            parameters: { id: $response.body#/id }
+          UpdateTriggerConnector:
+            operationId: updateTriggerConnector
+            parameters: { id: $response.body#/id }
+          DeleteConnector:
+            operationId: deleteConnector
+            parameters: { id: $response.body#/id }
+      "400":
+        $ref: ../components/responses.yaml#/BadRequest
+      "401":
+        $ref: ../components/responses.yaml#/Unauthorized
+      "403":
+        $ref: ../components/responses.yaml#/Forbidden
+      "422":
+        $ref: ../components/responses.yaml#/UnprocessableEntity
+    x-error-codes:
+      - UNAUTHORIZED
+      - FORBIDDEN
+      - VALIDATION
+    x-cli:
+      helpPreamble: |-
+        A trigger is an unattended, scheduled agent run: on a cron cadence it runs the
+        shipeasy-ops-work loop in --pr mode against your project — one atomic diff and
+        ONE pull request per fixed item, nothing auto-merges.
+
+        Whatever the provider, the scheduled run executes this trigger prompt (headless
+        CLIs take it as the prompt; cloud agents as the task body):
+
+          You are an unattended Shipeasy maintenance run. Authenticate every `shipeasy`
+          call with these env vars (the CLI reads them directly — do NOT run
+          `shipeasy login`, never echo the token). Put them at the top of EVERY shell
+          invocation that calls `shipeasy`; each command runs in a fresh shell:
+
+          export SHIPEASY_CLI_TOKEN="<OPS_KEY>"
+          export SHIPEASY_PROJECT_ID="<PROJECT_ID>"
+
+          Ensure the repo is bound: test -f .shipeasy || printf '{"project_id":"<PROJECT_ID>"}\n' > .shipeasy
+          (never commit .shipeasy).
+
+          Refresh to the latest plugin + CLI, then run the ops work loop in --pr mode:
+            <PLUGIN-INSTALL-FOR-THIS-HOST>       # plugin install for claude/copilot, or `npx -y skills add …`
+            npm install -g @shipeasy/cli@latest
+          Then follow the installed shipeasy-ops-work (--pr) workflow verbatim: burn down
+          the queue, one atomic diff per item, open ONE PR per item from a safe branch
+          prefix, flip each to ready_for_qa, add "Closes #<issue>" where an item has a
+          connected GitHub issue. If the queue is empty, exit cleanly. Never merge.
+
+        <OPS_KEY> is a restricted `ops` key — mint with
+        `npx -y @shipeasy/cli@latest keys create --type ops`. It reads the queue, flips
+        status, links the PR it opens, and creates resources only; it can never edit or
+        delete existing resources, and auto-extends its 7-day expiry on each run.
+        <PROJECT_ID> comes from the bound .shipeasy. Never print either value.
+
+        Safety: auto-approve flags (--approval-mode=yolo, --dangerously-skip-permissions,
+        …) remove the human gate — run only in an isolated env. Unattended loops spend
+        tokens/credits on a cadence: start weekly/daily and watch the first runs.
+      commands:
+        - name: create claude
+          summary: Register a Claude Code scheduled routine as the trigger connector
+          preset: { provider: claude_trigger }
+          help: |-
+            The reference implementation — a routine in Anthropic's cloud, no GitHub
+            Actions. The routines API is reachable only by the agent's in-process
+            RemoteTrigger tool, so provisioning is a hybrid split:
+
+            1. `shipeasy ops trigger prep --frequency <4h|6h|daily|weekdays|weekly|cron>`
+               mints the restricted ops key, resolves repo + cron, and writes the exact
+               RemoteTrigger create body to a 0600 temp file (the key is never printed).
+            2. The agent picks an environment_id from its RemoteTrigger env list — the
+               environment's network access must allow shipeasy.ai + api.shipeasy.ai
+               (Custom network; new envs default to Trusted, which fails every shipeasy
+               call) — then calls RemoteTrigger {action:"create"} and captures trig_….
+               Verify with {action:"run"} (confirm first — it spends tokens and may open
+               a real PR).
+            3. Register the connector (idempotent by routineId; tokenless is fine):
+
+                 shipeasy ops trigger create claude --config '{"routineId":"trig_…"}'
+
+            The fire token ("Fire now" + event auto-fire) is web-UI-only: open
+            https://claude.ai/code/routines → the routine → add an API trigger →
+            Generate token, then re-run the create with --token <token> and optionally
+            --events '["bug.created","feature_request.created"]' — the same row is
+            upgraded in place. GitHub access is connected once via /web-setup or the
+            Claude GitHub App. Manage/pause the routine at claude.ai/code/routines.
+        - name: create cursor
+          summary: Register a Cursor cloud-agent trigger (cold-fire; Shipeasy launches the run)
+          preset: { provider: cursor_trigger }
+          help: |-
+            Cursor cloud agents are cold-fireable: one authenticated POST to
+            https://api.cursor.com/v1/agents starts a run from nothing, and
+            autoCreatePR opens the PR via Cursor's GitHub App. Registering the
+            connector stores both credentials, so Shipeasy can fire it on demand and
+            on subscribed events; the ops key rides the launch envVars (never the
+            prompt):
+
+              shipeasy ops trigger create cursor \
+                --config '{"repoUrl":"https://github.com/<owner>/<repo>","projectId":"<prj_…>"}' \
+                --api-key <CURSOR_API_KEY> --ops-key <ops_…>
+
+            For a fixed cadence (nightly runs without new feedback) add a Cursor
+            Automation (cursor.com/automations) with the same trigger prompt — cron +
+            "Pull request creation" enabled. Note: Automations always run in Max Mode
+            (billed on cloud-agent usage).
+        - name: create copilot
+          summary: Register a GitHub Copilot cloud-agent trigger
+          preset: { provider: copilot_trigger }
+          help: |-
+            Copilot's cloud agent starts from one authenticated POST to
+            https://api.github.com/agents/repos/<owner>/<repo>/tasks with
+            { prompt, create_pull_request: true }. Auth is a user-to-server token
+            ONLY: a fine-grained user PAT with the "Agent tasks" repo permission
+            (read+write) for a Copilot-licensed account — the Actions GITHUB_TOKEN and
+            GitHub App installation tokens are rejected. The agent reads
+            SHIPEASY_CLI_TOKEN from the repo's own Agents secret store, so Shipeasy
+            stores only the PAT:
+
+              shipeasy ops trigger create copilot \
+                --config '{"owner":"<owner>","repo":"<repo>"}' --token <fine-grained PAT>
+
+            Set SHIPEASY_CLI_TOKEN (the restricted ops key) + SHIPEASY_PROJECT_ID in
+            the repo's Agents secrets first. For a fixed cadence use Copilot
+            automations (repo Agents tab; hourly/daily/weekly, private/internal repos
+            only) or a scheduled Actions job running `gh agent-task create`.
+        - name: create jules
+          aliases: [gemini]
+          summary: Register a Google Jules (Gemini) trigger
+          preset: { provider: jules_trigger }
+          help: |-
+            Jules — Google's async coding agent (the fireable Gemini path) — starts a
+            session from one POST to https://jules.googleapis.com/v1alpha/sessions
+            (header X-Goog-Api-Key) with sourceContext.source =
+            sources/github/<owner>/<repo> and automationMode: "AUTO_CREATE_PR". Jules
+            exposes no env channel, so the restricted ops key is embedded in the
+            session prompt (safe — it is the limited ops key):
+
+              shipeasy ops trigger create jules \
+                --config '{"source":"sources/github/<owner>/<repo>"}' \
+                --api-key <JULES_API_KEY> --ops-key <ops_…>
+
+            Connect the repo to Jules once (jules.google.com → connect GitHub). For a
+            fixed cadence use Jules scheduled tasks (UI-only), or fall back to the
+            Gemini CLI in a GitHub Actions schedule: job
+            (`gemini -p "<TRIGGER PROMPT>" --approval-mode=yolo`; auth GEMINI_API_KEY).
+      fallback:
+        argument: provider
+        platforms: [codex, windsurf, cline, openclaw, opencode, continue]
+        help: |-
+          Direct (Shipeasy-fired) triggers are not supported for this platform — it
+          exposes no HTTP "start a run" endpoint our Worker can call. Supported here:
+          claude, cursor, copilot, jules (alias: gemini) — see
+          `shipeasy ops trigger create <provider> --help`.
+
+          Platform-scheduled setup instead (the platform's own scheduler fires the
+          run; nothing to register in Shipeasy):
+
+          1. Mint the restricted ops key (`shipeasy sdk keys create --type ops --json`)
+             and read the project id from .shipeasy. Never print either.
+          2. Build the trigger prompt (run `shipeasy ops trigger create claude --help`
+             for the shared template) with the key, project id, and your platform's
+             install line substituted.
+          3. Schedule a headless run with it — a GitHub Actions `schedule:` cron
+             (always-on; credentials as repo secrets incl. a GH_TOKEN/PAT with
+             contents:write + pull-requests:write) or a local cron/daemon (machine
+             must stay awake):
+
+               codex     GitHub Actions cron → `codex cloud exec --env <ENV_ID> "<PROMPT>"`
+                         (submits a Codex Cloud task — machine-off; configure network +
+                         SHIPEASY_* secrets once at chatgpt.com/codex/cloud/settings/environments)
+               windsurf  Devin Scheduled Sessions (cloud cron; WINDSURF/DEVIN API key)
+               cline     `cline schedule create --cron "…" --prompt "<PROMPT>"` (local daemon)
+               openclaw  `openclaw cron create "…" "<PROMPT>"` (local gateway; static API key)
+               opencode  `opencode run "<PROMPT>"` + external cron (permission: "allow")
+               continue  `cn -p --auto "<PROMPT>"` + external cron (CONTINUE_API_KEY)
+
+          4. Verify one manual fire (expect a PR or a clean empty-queue exit) and
+             manage/pause it on that platform's scheduler.