@deepdockai/cli 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@deepdockai/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Deepdock",
+  "homepage": "https://github.com/deepdockai/devkit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepdockai/devkit.git"
+  },
+  "bin": {
+    "deepdock": "dist/deepdock.js"
+  },
+  "files": ["dist/deepdock.js", "skill", "README.md", "CHANGELOG.md", "LICENSE", "SECURITY.md"],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "format": "biome format .",
+    "format:fix": "biome format --write .",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "typecheck": "tsc --noEmit",
+    "gen:codes": "bun scripts/genCodes.ts",
+    "check:public": "bun scripts/checkPublic.ts --pack",
+    "test": "bun run build && bun --bun vitest run",
+    "test:node": "vitest run",
+    "ci": "bun run format && bun run lint && bun run typecheck && bun run test && bun run test:node && bun run check:public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.6.2",
+    "@commander-js/extra-typings": "15",
+    "@types/bun": "^1.4.3",
+    "@types/node": "^26.6.5",
+    "arktype": "^2.2.9",
+    "commander": "15",
+    "openapi-typescript": "7",
+    "typescript": "~5.9",
+    "vitest": "^5.0.5"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: deepdock-integration
+description: Build, debug or test an integration with Deepdock's partner API, the REST actions under /v1 that read and write records in a customer's on-premise business system (for example Example ERP) through a paired Deepdock device. Use when code calls api.deepdock.ai, handles ddk_ API keys, pairs a device by code, calls a system action, handles error codes such as device_offline, action_paused, idempotency_conflict or outcome_unknown, or runs the deepdock CLI.
+metadata:
+  cli: "@deepdockai/cli"
+---
+
+# Deepdock integration
+
+Deepdock makes a customer's on-premise system (a business's software,
+installed on a PC in their office) reachable as a REST API. A small Deepdock client
+runs next to that system; your code talks to Deepdock's cloud API, never to the customer's network.
+
+Use this skill to integrate Deepdock into a product, write or review a client for it, or test an
+integration against a demo device. It is not for building or changing actions: Deepdock does that.
+
+## The model in eight sentences
+
+1. Your **organisation** holds **API keys** (`ddk_live_...`), the only credential that runs
+   actions; one is sent as `Authorization: Bearer` on every `/v1` request.
+2. A **device** is the Deepdock client on the customer's PC; you **pair** it with a code shown on its
+   screen, and from then on it belongs to your organisation until you release it.
+3. A device reports the **systems** it runs; each system has **actions**, deterministic operations
+   that Deepdock builds and verifies before offering them.
+4. A **read** action is a `GET` with query parameters and pages with `limit` and `cursor`; a **write**
+   action is a `POST` (create) or `PATCH` (update) with a JSON body of string fields.
+5. Every write needs an `Idempotency-Key`: a new key per intended write, the same key on every retry,
+   and a repeat answers the stored result with `Idempotent-Replayed: true`, writing nothing twice.
+6. A write either fully applies or not: Deepdock checks its result before confirming, and a write
+   whose result does not match is undone and the action is paused.
+7. A device can be offline and an action can be paused; your code treats both as normal answers.
+8. Every answer is `{ "data": ... }` or `{ "error": { "code", "message" } }`; `code` is the contract,
+   `message` is for people.
+
+## The recipe
+
+Work through these in order. Each step names the CLI command (see [references/cli.md](references/cli.md))
+and what your code does with the result.
+
+1. **Sign in.** `deepdock auth login --json`: without a terminal the CLI prints the request and
+   exits; show the human the link and wait for them to click Approve in the dashboard, then run
+   `deepdock auth login --wait <request>`. You never see the resulting sign-in. Then pass
+   `--org <slug>` on every command (`deepdock org list --json` shows the slugs).
+2. **See what you have.** `deepdock systems list --json` (the systems and actions assigned to your
+   organisation) and `deepdock devices list --json` (your paired devices). If the human has a demo
+   device that is not yet paired, they read the code off its screen and you run
+   `deepdock devices pair <code> --label "Demo"`.
+3. **Fetch the schemas.** `deepdock systems openapi <system> --org <slug> > openapi/<system>.json`
+   and read it; `deepdock actions list <device> <system> --json` shows the same fields per device.
+   Check the document into the repository and refresh it with the same command. Write code only for
+   actions that appear both in the document and in `systems list`.
+4. **Write the client.** A thin client in the project's own language: bearer header, envelope
+   unwrap, idempotency header with replay detection, and an error-code switch. Read
+   [references/calling-actions.md](references/calling-actions.md) and
+   [references/example-integration.md](references/example-integration.md) first.
+5. **Get a key into the app.** `deepdock keys create "<project> dev" --expires 30d --write-env
+   .env.local --org <slug> --json`, then `--wait <request>` once a human has clicked Approve in the
+   dashboard. The CLI receives the key once, writes `DEEPDOCK_API_KEY=<key>` into that file (it
+   must be ignored by git) and keeps no copy. It is displayed to you or to the human by nobody.
+   You work only with the key's id, prefix and the file name. Never ask for, read, print or paste
+   a key value.
+6. **Test it.** Run your own code against the demo device the human named, with the key from
+   `.env.local`, and read back with the read action. The CLI runs no action. Read
+   [references/testing.md](references/testing.md) before any write.
+7. **Ship.** The human creates the production key the same way, from their own CLI, into the
+   production secret store. Tell the human to revoke the development key.
+
+## Rules that are not in the OpenAPI document
+
+- **Discover, never hard-code.** Field names, patterns, enums and lengths come from the live OpenAPI
+  document (`deepdock systems openapi <system>`, or `GET /v1/systems/{system}/openapi.json` with
+  your key), never from memory or from this skill. The document lists Deepdock's whole catalogue for the system; your organisation's assigned
+  subset is `systems list` (or `GET /v1/devices/{deviceId}/systems/{system}/actions`).
+  [references/discovery.md](references/discovery.md).
+- **Keys.** API keys run actions and pair devices. The CLI sign-in manages only, never runs an
+  action and never holds an API key. Keys are created and placed by `keys create`; you never ask
+  for, read, print or paste a key value, and never put one in a command argument, a URL, a log
+  line, a commit or this conversation. In code, read it from the destination the CLI wrote to
+  (`DEEPDOCK_API_KEY` by convention).
+  [references/auth-and-keys.md](references/auth-and-keys.md).
+- **Idempotency.** New key per intended write, persisted before sending; same key per retry; after
+  `device_offline` retry with the same key; after `outcome_unknown` or a persisting
+  `idempotency_conflict` do not write again under a new key until a read shows the write did not
+  land. [references/idempotency.md](references/idempotency.md).
+- **Errors.** Every `/v1` code, whether to retry, and what to show the user:
+  [references/errors.md](references/errors.md). Switch on `code`, never on `message`.
+- **Timeouts.** A call waits for the device; Deepdock gives up after 20 seconds and answers
+  `503 device_offline`. Set your own client timeout to 30 seconds and expect a read to take a
+  second or more. A client-side timeout or network failure on a write is handled exactly like
+  `device_offline`: retry with the same key.
+- **Test data only.** Test against a demo device with invented, marked data: a `TEST-DEEPDOCK-`
+  marker in every created record, no real customer data in fixtures, logs or prompts. [references/testing.md](references/testing.md).
+- **Authoring fields.** Some writes need a reference the system already knows (an author user, an
+  open case). Read it first with the matching read action and pass the id back; never invent one.
+  [references/calling-actions.md](references/calling-actions.md).
+
+## Reference files
+
+| File | Read when |
+|---|---|
+| [references/concepts.md](references/concepts.md) | you need the vocabulary: device, system, action, pause, incident, release |
+| [references/auth-and-keys.md](references/auth-and-keys.md) | creating, storing, sending or revoking a key; pairing or releasing a device |
+| [references/discovery.md](references/discovery.md) | reading the action index or the OpenAPI document |
+| [references/calling-actions.md](references/calling-actions.md) | writing the client: reads, writes, paging, authoring fields, timeouts |
+| [references/errors.md](references/errors.md) | handling any `error.code` |
+| [references/idempotency.md](references/idempotency.md) | retries, replays, unknown outcomes |
+| [references/cli.md](references/cli.md) | any `deepdock ...` command |
+| [references/testing.md](references/testing.md) | before the first write against a device |
+| [references/example-integration.md](references/example-integration.md) | the full TypeScript and Python clients (`references/clients/`), curl for any other language, and a create-then-read flow |

package/skill/references/auth-and-keys.md

@@ -0,0 +1,102 @@
+# Auth, keys and pairing
+
+| Environment | Base URL | API key prefix |
+|---|---|---|
+| Production | `https://api.deepdock.ai` | `ddk_live_` |
+
+A deployment accepts only its own environment's keys. Test against a demo device of your own with
+invented, marked data ([testing.md](testing.md)).
+
+## API keys
+
+- Format: the prefix, then 43 characters from `A-Z a-z 0-9 _ -`, then a 6-character checksum. Treat
+  it as opaque; never parse it beyond the prefix.
+- Created by an organisation admin in the dashboard (Keys page), where it is shown **once**, or
+  with `deepdock keys create <name> --expires <d> --write-env <file>`, where the CLI writes it
+  straight into the app's env file and shows it to nobody. Deepdock stores only a hash. The key list shows the
+  first 8 characters after the prefix so keys can be told apart.
+- Expiry is optional in the dashboard. A key created from the CLI must expire within 90 days; the
+  skill's default is `--expires 30d` with a name that says what it is for (`"<project> dev"`).
+- Revoked by an admin in the dashboard or with `deepdock keys revoke <id>`, immediately.
+- Sent on every `/v1` request, the OpenAPI document included:
+
+```http
+Authorization: Bearer ddk_live_<your key>
+```
+
+Every reason a key is refused (missing, malformed, wrong environment, bad checksum, unknown,
+revoked, expired) answers the same `401 unauthenticated` with `WWW-Authenticate: Bearer`. Your code
+cannot tell them apart and should not try: surface "the Deepdock API key was refused; check the key
+in the dashboard" and stop retrying.
+
+### Handling the key in code
+
+- Read it from the environment or a secret store (`DEEPDOCK_API_KEY` is the convention the
+  dashboard's examples use). Never a literal in source, a test fixture, a log or a URL.
+- One key per deployment is enough; there is no per-device key.
+- Getting a key into the app is the CLI's job: `deepdock keys create <name> --expires <d>
+  --write-env <file>` opens a link to the dashboard; a human clicks Approve (or Deny); the CLI
+  receives the key once and writes `DEEPDOCK_API_KEY=<key>` into the file, which must be ignored
+  by git (if git cannot answer, the CLI writes the file and warns on stderr). It is displayed to nobody, neither you nor the human, and the CLI keeps no copy. The
+  CLI answers with the key's id, prefix, name, expiry and the file; that is all you work with.
+- Never ask for, read, print or paste a key value, and never try to extract it from the file.
+  Code reads it at runtime from where the CLI put it.
+- A development key reaches every device of the organisation until it expires or is revoked; keep
+  the expiry short (`30d`), use it only against the demo device, and tell the human to revoke it
+  (`deepdock keys revoke <id>`) when the integration ships. The live key is created the same way,
+  by the human from their own CLI, into the live secret store.
+
+## The CLI sign-in (CLI only)
+
+`deepdock auth login` opens a link to the dashboard; the human clicks Approve. The CLI then holds
+the sign-in for that person, valid 90 days, stored in the CLI's own config with owner-only
+permissions. The sign-in belongs to the person, not to an organisation: every command takes
+`--org <slug>`. It does what that person can do in the dashboard (members read, pair and rename;
+admins also release devices, create and revoke API keys) and never runs an action.
+`deepdock auth status` shows the signed-in person, organisations and expiry (exit 5 when not signed in); `deepdock auth
+logout` revokes the sign-in and every API key the CLI created.
+
+Without a terminal `auth login` prints the request and exits; show the human the link, wait for
+them to approve, then run `deepdock auth login --wait <request>`. Do not try to answer for them.
+There is no sign-in from an environment variable.
+
+## Pairing a device
+
+A device is the Deepdock client installed next to the customer's system. The installer is at
+`/public/client/download` under the base URL (production:
+`https://api.deepdock.ai/public/client/download`); the link carries no credential, so it can be
+sent to a new site as is. The pairing code is what ties the device to your organisation.
+
+1. While unpaired, the client shows a code such as `K7Q-4MX`: 6 characters from
+   `ABCDEFGHJKMNPQRSTVWXYZ23456789`. Case and the dash do not matter.
+2. A code is valid for 10 minutes and is replaced shortly before it expires: read it off the screen
+   when you pair.
+3. Claim it:
+
+```bash
+curl -X POST "$BASE/v1/devices" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"code":"K7Q-4MX","label":"Reception PC"}'
+```
+
+`label` is optional, 1 to 100 characters. The device must be online. Answer: `201` with the device
+(`id`, `label`, `hostname`, `os`, `clientVersion`, `status`, `lastSeenAt`, `claimedAt`, `systems`,
+and `updateAvailable` when it runs an older build). Keep `id`: it is the `deviceId` of every later
+call, and there is no `/v1` call to list devices (use `deepdock devices list` or the dashboard).
+
+4. Release with `DELETE /v1/devices/{deviceId}`; the device then shows a new code.
+
+Pairing answers:
+
+| Code | Status | Do |
+|---|---|---|
+| `invalid_request` | 400 | the code is malformed; fix the input |
+| `pairing_code_invalid` | 404 | unknown, expired, replaced, already used, or the device is offline; ask for a fresh code |
+| `other_partner_build` | 409 | the device runs another partner's branded client; only that partner can claim it |
+| `rate_limited` | 429 | more than 5 failed claim attempts in 60 seconds with this key; wait up to a minute |
+
+Successful claims do not count against the limit; malformed codes are refused before counting.
+
+With the CLI: `deepdock devices pair <code> [--label <text>]`, `deepdock devices release <id>`
+(admin).

package/skill/references/calling-actions.md

@@ -0,0 +1,111 @@
+# Calling actions
+
+All paths are under `/v1/devices/{deviceId}/systems/{system}/actions/{action}`. `deviceId` is the
+UUID from pairing; `system` and `action` are the slugs from the action index.
+
+Every input value is text and is normalised to Unicode NFC before anything else happens; a
+composed and a decomposed spelling are the same value.
+
+## Reads: `GET`
+
+Input as query parameters; `limit` (1 to 250, default 25) and `cursor` for paging.
+
+```bash
+curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchCustomers?lastName=M%C3%BCl&limit=50" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+```json
+{ "data": { "items": [ { "customerId": 1001, "lastName": "Müller", "city": "Beispielstadt" } ], "nextCursor": null } }
+```
+
+- `nextCursor` is set only when a page came back full; pass it back as `cursor` unchanged. It is
+  opaque: never parse, build or store it beyond the next request.
+- Items are the customer's records. Values can be `null` where the schema says so. Dates and other
+  non-numeric values arrive as text in the system's own format (the schema and description say
+  which); numbers as JSON numbers.
+- A read's description may say a field is a **prefix match** and what it ignores (case,
+  punctuation, umlaut spelling). Design your search UI around that rule rather than filtering
+  client-side.
+
+## Writes: `POST` (create) or `PATCH` (update)
+
+Body: a JSON object whose values are all strings (numbers and ids too, as strings), with only the
+fields the schema lists (`additionalProperties: false`) and all of its `required` ones. Header
+`Idempotency-Key`, required.
+
+```bash
+curl -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/createNote" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY" \
+  -H "Idempotency-Key: order-8f1c2a-create-note" \
+  -H "Content-Type: application/json" \
+  -d '{"text":"TEST-DEEPDOCK-K3M9QA","orderNumber":"1001"}'
+```
+
+- A create answers `201` with `{ data: { <returned fields> } }`, typically the new record's id. A
+  replay of the same key answers `200` with the same data and `Idempotent-Replayed: true`.
+- An update answers `200` whether it ran now or is a replay; the header tells you which.
+- The returned id is the system's own id (for example `noteId`). Store it as the system gave it;
+  do not predict or re-key it. Result field types come from each action's own output schema: a
+  create typically returns the new id as an integer, while an update echoes the id you sent as a
+  string. Do not reuse one action's result type for another.
+- Each update under a new key writes again and may add an entry to the system's own change log,
+  even when values are unchanged. Do not "update" to no-op.
+
+Full idempotency rules: [idempotency.md](idempotency.md).
+
+## Authoring and reference fields
+
+Some writes need a reference the system already knows: an author user for an entry, an open case
+of a customer, the note id of an update. The pattern is always the same:
+
+1. Read the reference with the matching read action (for example a users read, a case read, a
+   customer search).
+2. Pass its id back as a string field in the write.
+3. Handle the action-specific refusal the description names: for example `422 unknown_author` when
+   the user is not one the system lists, or `422 no_open_case` when the customer has no open case and
+   the action does not open one. Both mean nothing was written; fix the reference, do not retry
+   blindly.
+
+Never invent an id, copy one from another device, or hard-code one from a test run.
+
+## Timeouts and latency
+
+- Every action call is sent to the customer's PC and run there. Expect a read to take from a few
+  hundred milliseconds to a few seconds; a write about the same plus its verification.
+- Deepdock waits at most 20 seconds for the device, then answers `503 device_offline`. Set your HTTP
+  client timeout to 30 seconds so you receive the code instead of timing out first. A write that
+  timed out or failed on the network on your side may still have landed: retry with the same
+  `Idempotency-Key`.
+- An answer that is not JSON (a proxy's 502 or 504 page) is a transport failure: for a write, the
+  same rule, retry with the same key; never treat it as refused.
+- Run calls sequentially per device where order matters; there is no documented concurrency limit,
+  but the device is one PC in one office.
+- `GET /v1/devices/{deviceId}/systems` is a live call too; cache it for the duration of a user
+  session rather than calling it per request.
+
+## Rate limits
+
+The only documented limit is on pairing: 5 failed claim attempts per key per rolling 60 seconds
+(`429 rate_limited`). Handle `429` generically anyway (honour `Retry-After` when present, back off,
+do not loop), since limits can be added additively.
+
+## Response headers worth reading
+
+| Header | When | Meaning |
+|---|---|---|
+| `Idempotent-Replayed: true` | a write's `200` | the stored result of an earlier run; nothing written again |
+| `Allow` | `405 invalid_request` | the method the action has |
+| `WWW-Authenticate: Bearer` | `401` | the key was refused |
+| `Retry-After` | `429` | seconds to wait, when present |
+
+## The envelope
+
+```ts
+type Ok<T> = { data: T }
+type Err = { error: { code: string; message: string; requestId?: string; systems?: string[] } }
+```
+
+`requestId` comes with a `500`: give it to Deepdock support. `systems` comes with
+`system_not_on_device`: the systems this device reported or you were assigned. Unwrap once in one
+place; never read `message` in code paths, only show it or log it.

package/skill/references/cli.md

@@ -0,0 +1,97 @@
+# The `deepdock` CLI
+
+Package `@deepdockai/cli`. Run with `npx @deepdockai/cli <command>` or
+`bunx @deepdockai/cli <command>`; installed globally it is `deepdock`. If the CLI is missing,
+install it; do not fall back to hand-written HTTP calls with a key in an argument.
+
+The CLI runs with the person's sign-in and manages things: organisations, devices, keys, what a
+device offers. It never runs an action and never holds an API key. Actions run from your code with
+the API key the CLI wrote to the app's env file.
+
+## Commands
+
+| Command | What it does | Who |
+|---|---|---|
+| `auth login` | opens a link to the dashboard where the human clicks Approve; prints `Signed in as <email>.` and the person's organisations; the sign-in lasts 90 days | anyone |
+| `auth status` | signed-in person, sign-in expiry, organisations, default organisation, the API keys this CLI created (id, prefix, expiry, where it was written); prints the same document and exits 5 when not signed in | anyone |
+| `auth logout` | revokes the sign-in and every API key this CLI created, removes the entries it wrote, says what it revoked | anyone |
+| `org list` | the person's organisations: slug, name, role, which one is the default | member |
+| `org select [slug]` | sets the default organisation; without a slug, a pick-list on a terminal | member |
+| `systems list` | the systems and actions assigned to the organisation | member |
+| `systems openapi <system>` | the system's OpenAPI document on stdout; redirect it to a file | member |
+| `devices list` | paired devices with id, label, status, systems, last seen | member |
+| `devices pair <code> [--label <text>]` | claim a device by the code on its screen | member |
+| `devices rename <id> <label>` | rename a device | member |
+| `devices release <id>` | release a device (asks on a terminal; `--yes` otherwise) | admin |
+| `devices systems <id>` | the device's live systems and action state, paused reasons included; `device_offline` is a normal answer | member |
+| `actions list <device> <system>` | the action index: every action with its method and field schemas | member |
+| `keys list` | the organisation's API keys: name, prefix, created, last used, expires, status | member |
+| `keys create <name> --expires <7d\|30d\|90d> --write-env <file>` | create an API key: opens a link, a human approves "Create an API key in <Org>?", the CLI receives the key once and writes `DEEPDOCK_API_KEY=<key>` into the file. It keeps no copy and shows the value to nobody. Answers id, name, prefix, expiry and where it was written | admin |
+| `keys revoke <id>` | revoke a key (asks on a terminal; `--yes` otherwise); removes the env entry if this CLI wrote it | admin |
+| `incidents list` | incidents of the last 30 days | member |
+| `skill [--agent claude\|codex\|cursor\|all]` | writes this skill into the current repository | anyone |
+
+Every command that acts in an organisation uses `--org <slug>` after the command, else
+`DEEPDOCK_ORG`, else the default from `org select`; with none it stops with `org_required` and
+lists the organisations. Always pass `--org` from an agent: `org select` changes the human's
+default in every terminal.
+
+Global flags: `--org <slug>`, `--json`, `--yes`, `-h`, `-v`. Environment: `DEEPDOCK_ORG`,
+`DEEPDOCK_BASE_URL`, `NO_COLOR`.
+
+## Waiting for the browser
+
+`auth login` and `keys create` need a human to click Approve. Without a terminal (your shell)
+they do not wait: they print the request and exit 0, and you finish it later:
+
+```bash
+deepdock auth login --json              # { "data": { "pending": { "request": "rq_…", "url": "…", "expiresAt": "…" } } }
+# show the human the url and wait for them to approve, then:
+deepdock auth login --wait rq_…
+deepdock keys create "<project> dev" --expires 30d --write-env .env.local --org <slug> --json
+deepdock keys create --wait rq_… --json
+```
+
+A request lives 10 minutes; `--wait` on an expired one answers `approval_expired`. Never try to
+approve for the human.
+
+## Output
+
+JSON is the default when stdout is not a terminal; pass `--json` to be sure. One document on
+stdout:
+
+```json
+{ "data": <the API's data, unchanged>, "meta": { "org": { "slug": "…", "name": "…" }, "requestId": "…" } }
+```
+
+`data` is what the API answered, so what you see is what your code will receive. `meta` holds the
+organisation the command acted in, the request id, and, where it applies, `written` (`{ file,
+name }` from `keys create`) and `pending` (from `--no-wait`). `keys create` builds its `data` from
+id, name, prefix, createdAt and expiresAt; the key value is in neither stream.
+
+A failure is one document on stderr: the API's error object unchanged plus what to do:
+
+```json
+{ "error": { "code": "device_offline", "message": "…", "requestId": "…" }, "meta": { "org": { "…": "…" }, "hint": "Retry later." } }
+```
+
+## Exit codes
+
+| Exit | Meaning | Codes |
+|---|---|---|
+| 0 | done | |
+| 1 | something on the command line to fix | `invalid_usage` (a bad flag, an unknown slug, a question with no terminal and no `--yes`, an env file git does not ignore), `org_required` |
+| 2 | the API refused the request; do not repeat it unchanged | `invalid_request`, `not_found`, `device_not_found`, `pairing_code_invalid`, `other_partner_build`, `rate_limited`, `forbidden`, `conflict` and the other refusals |
+| 3 | retry later | `device_offline`, `action_paused`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `connection_lost` |
+| 4 | the CLI is too old for the API: run `npx @deepdockai/cli@latest` | `client_outdated` |
+| 5 | sign-in needed: run `deepdock auth login` | `sign_in_needed`, `approval_denied`, `approval_expired` |
+
+Branch on the exit code or on `error.code`, never on `message`.
+
+## What the CLI never does
+
+- It never prints a key value, neither the sign-in nor an API key, under any flag.
+- It never runs an action and never holds an API key: `actions list` shows what a device offers;
+  your code runs the actions.
+- It never names a device by label or picks one for you: a device is its full id, every time.
+- It never retries: exit 3 says retry, you decide when.

package/skill/references/clients/deepdock.py

@@ -0,0 +1,163 @@
+"""Minimal Deepdock /v1 client. Depends on httpx only (Python 3.9+).
+
+It does the four things the OpenAPI document cannot tell you: the bearer header, the envelope
+unwrap, the Idempotency-Key header with replay detection, and a typed error carrying the code.
+Everything action-specific (paths, fields, methods) comes from the live OpenAPI document.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+
+
+class DeepdockError(Exception):
+    """Deepdock answered `{ "error": { "code", ... } }`. Switch on `code`, never on `message`."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None,
+                 systems: Optional[List[str]] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.systems = systems
+
+
+class DeepdockTransportError(Exception):
+    """No answer, or not Deepdock's envelope (timeout, network, a proxy page): a write may still have landed."""
+
+
+@dataclass
+class Page:
+    items: List[Dict[str, Any]]
+    next_cursor: Optional[str]
+
+
+@dataclass
+class WriteResult:
+    data: Dict[str, Any]
+    replayed: bool
+
+
+class Deepdock:
+    def __init__(self, api_key: str, base: str = "https://api.deepdock.ai", timeout: float = 30.0,
+                 client: Optional[httpx.Client] = None):
+        # 30 s is above Deepdock's 20 s device wait, so device_offline arrives before a client timeout.
+        self.c = client or httpx.Client(base_url=base.rstrip("/"), timeout=timeout)
+        self.c.headers["Authorization"] = f"Bearer {api_key}"
+
+    def _send(self, method: str, path: str, **kw: Any) -> Tuple[Any, httpx.Headers]:
+        try:
+            r = self.c.request(method, path, **kw)
+        except httpx.HTTPError as e:  # timeouts and network errors
+            raise DeepdockTransportError(f"no answer from Deepdock: {type(e).__name__}") from e
+        try:
+            body = r.json()
+        except ValueError:
+            raise DeepdockTransportError(f"non-JSON answer with status {r.status_code}")
+        if isinstance(body, dict) and "error" in body:
+            e = body["error"]
+            raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"))
+        if not isinstance(body, dict) or "data" not in body:
+            raise DeepdockTransportError(f"unexpected body with status {r.status_code}")
+        return body["data"], r.headers
+
+    @staticmethod
+    def _action_path(device_id: str, system: str, action: str) -> str:
+        return f"/v1/devices/{quote(device_id, safe='')}/systems/{quote(system, safe='')}/actions/{quote(action, safe='')}"
+
+    def read(self, device_id: str, system: str, action: str, params: Dict[str, str],
+             limit: Optional[int] = None, cursor: Optional[str] = None) -> Page:
+        """Runs a read action. Pass `next_cursor` back as `cursor` for the next page."""
+        query: Dict[str, str] = dict(params)
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        data, _ = self._send("GET", self._action_path(device_id, system, action), params=query)
+        return Page(items=data["items"], next_cursor=data.get("nextCursor"))
+
+    def read_all(self, device_id: str, system: str, action: str, params: Dict[str, str],
+                 limit: Optional[int] = None) -> Iterator[Dict[str, Any]]:
+        """Reads every page of a read action, in order."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.read(device_id, system, action, params, limit=limit, cursor=cursor)
+            yield from page.items
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def write(self, device_id: str, system: str, action: str, method: str, idempotency_key: str,
+              body: Dict[str, str]) -> WriteResult:
+        """Runs a write action. `method` is POST or PATCH from the action index; `body` values are all strings."""
+        data, headers = self._send(method, self._action_path(device_id, system, action), json=body,
+                                   headers={"Idempotency-Key": idempotency_key})
+        return WriteResult(data=data, replayed=headers.get("Idempotent-Replayed") == "true")
+
+    def systems(self, device_id: str) -> Dict[str, Any]:
+        """The device's systems and each action's state. A live call: can answer device_offline."""
+        data, _ = self._send("GET", f"/v1/devices/{quote(device_id, safe='')}/systems")
+        return data
+
+    def pair(self, code: str, label: Optional[str] = None) -> Dict[str, Any]:
+        """Claims a device by the pairing code it shows. Keep the returned `id`."""
+        body: Dict[str, str] = {"code": code}
+        if label is not None:
+            body["label"] = label
+        data, _ = self._send("POST", "/v1/devices", json=body)
+        return data
+
+    def release(self, device_id: str) -> None:
+        self._send("DELETE", f"/v1/devices/{quote(device_id, safe='')}")
+
+
+# --------------------------------------------------------------------------------------------------
+# Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
+# crash between send and answer cannot produce a second record under a new key. A job retries rows
+# left in "sent" with backoff (seconds, then minutes, for hours if the device stays offline).
+# --------------------------------------------------------------------------------------------------
+
+CONFLICT_RETRIES = 5  # a running write finishes within seconds; beyond this, treat it as unknown
+
+RETRY_SAME_KEY = {"device_offline", "target_busy", "temporarily_unavailable", "internal_error",
+                  "action_paused", "system_unavailable"}
+
+
+@dataclass
+class PendingWrite:
+    key: str  # 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event
+    device_id: str
+    system: str
+    action: str
+    method: str
+    input: Dict[str, str]
+    status: str = "pending"  # pending | sent | done | unknown | refused
+    conflict_retries: int = 0
+    result: Optional[Dict[str, Any]] = field(default=None)
+    request_id: Optional[str] = None
+    refused_code: Optional[str] = None
+
+
+def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
+    """One attempt; returns the row with its new status. The caller persists it."""
+    try:
+        res = dd.write(row.device_id, row.system, row.action, row.method, row.key, row.input)
+        return replace(row, status="done", result=res.data)
+    except DeepdockTransportError:
+        return replace(row, status="sent")
+    except DeepdockError as e:
+        if e.code in RETRY_SAME_KEY:
+            return replace(row, status="sent", request_id=e.request_id)
+        if e.code == "idempotency_conflict":
+            if row.conflict_retries < CONFLICT_RETRIES:
+                return replace(row, status="sent", conflict_retries=row.conflict_retries + 1)
+            return replace(row, status="unknown")
+        if e.code == "outcome_unknown":
+            return replace(row, status="unknown", request_id=e.request_id)
+        # invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+        # resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
+        return replace(row, status="refused", refused_code=e.code, result={"message": str(e)})