@deepdockai/cli 1.0.25 → 1.0.27

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.0.27
+
+- An update is called with `PATCH` again; a read and a create stay `POST`. All three take a flat JSON body and nothing in the URL. The method must be the action's own: any other answers `405 invalid_request` with `Allow` naming the one method (`POST` or `PATCH`), so a `POST` to an update is refused and does nothing. A query string on an action path is still `400 invalid_request`. A write still needs an `Idempotency-Key`; a read ignores it.
+- Each entry of the action index has a `method` (`POST` or `PATCH`) beside its `operation` (`read`, `create` or `update`).
+- The bundled clients' `write` takes the action's operation after the action name (`write(deviceId, system, action, 'create' | 'update', key, input)`) and sends `POST` for a create and `PATCH` for an update; `PendingWrite` carries it as `operation`. Reads are unchanged. Idempotency handling is unchanged.
+- The skill's references describe the contract.
+
+## 1.0.26
+
+- Every action is called with `POST /v1/devices/{deviceId}/systems/{system}/actions/{action}` and its inputs in a flat JSON body, reads and updates included. There is no `GET` read and no `PATCH` update any more: any other method answers `405 invalid_request` with `Allow: POST`, and a query string on an action path answers `400 invalid_request` ("inputs go in the JSON body, not in the URL"), so no value reaches a URL, a request log or a proxy. A read takes `limit` (a JSON integer) and `cursor` (a string) in the same body; a write still needs an `Idempotency-Key`, a read ignores it. Values are typed as given: an integer input is a JSON number, and `"1001"` is refused where it is declared as one.
+- The action index keeps its route, but each entry's `method` is replaced by `operation` (`read`, `create` or `update`). `actions list` derives its read/write column from it.
+- The bundled TypeScript and Python clients send reads as `POST` with a JSON body, including `limit` and `cursor`. `write` always sends `POST`, so its `method` parameter (and `PendingWrite.method`) is gone; input values are typed (`string | number | boolean`) instead of text only. Idempotency handling is unchanged.
+- The skill's references describe the new contract.
+
 ## 1.0.25
 
 - Three new error codes for writes over a customer system's own HTTP interface: `applied_unverified` (409, exit 2: the write landed but its read-back did not finish; `error.created` names the entry as `{ chartId }`, or null), `credentials_rejected` and `certificate_changed` (503, exit 3: a person at the practice renews the login or confirms the certificate in the Deepdock client). An earlier CLI already exits with the same codes through its status fallback.

package/README.md

@@ -101,7 +101,7 @@ deepdock skill
 | `devices pair <code> [--label <text>]`                | claim a device by the code on its screen                                                                                                                                |
 | `devices rename <id> <label>`, `devices release <id>` | rename a device; unpair it from the organisation (admin)                                                                                                                |
 | `devices systems <id>`                                | a device's live systems and action state, paused reasons included                                                                                                       |
-| `actions list <device> <system>`                      | every action a device offers, with its method and fields                                                                                                                |
+| `actions list <device> <system>`                      | every action a device offers, with its operation and fields                                                                                                             |
 | `keys list`, `keys create <name>`, `keys revoke <id>` | the organisation's API keys (create and revoke: admin)                                                                                                                  |
 | `incidents list`                                      | open incidents, and those closed within the last 30 days                                                                                                                |
 | `skill [--agent claude\|codex\|cursor\|all]`          | install the agent skill into the current directory                                                                                                                      |

package/dist/deepdock.js

@@ -11236,13 +11236,21 @@ var summary = (description) => {
   return chars.length > 160 ? `${chars.slice(0, 159).join("").trimEnd()}…` : sentence;
 };
 var actionRow = (action) => {
-  const method = typeof action.method === "string" ? action.method : undefined;
+  const operation = typeof action.operation === "string" ? action.operation : undefined;
   const fields = fieldNames(action.input);
-  const { name, method: _method, input: _input, output: _output, description, ...rest } = action;
+  const {
+    name,
+    operation: _operation,
+    method: _method,
+    input: _input,
+    output: _output,
+    description,
+    ...rest
+  } = action;
   const brief = summary(description);
   return {
     ...name === undefined ? {} : { name },
-    ...method ? { kind: method.toUpperCase() === "GET" ? "read" : "write" } : {},
+    ...operation ? { kind: operation === "read" ? "read" : "write" } : {},
     ...fields ? { fields } : {},
     ...brief ? { description: brief } : {},
     ...rest
@@ -11432,7 +11440,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.25";
+var VERSION = "1.0.27";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",

package/skill/SKILL.md

@@ -22,8 +22,10 @@ integration against a demo device. It is not for building or changing actions: D
    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.
+4. Every action takes a flat JSON body, never a value in the URL: `POST` for a read or create,
+   `PATCH` for an update. A **read** (the
+   action's `operation`) also takes `limit` and `cursor` in that body to page; a **write** (`create`
+   or `update`) needs an `Idempotency-Key` as well.
 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

package/skill/references/calling-actions.md

@@ -3,16 +3,36 @@
 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.
+## Calling an action: POST, or PATCH for an update
 
-## Reads: `GET`
+Every action is called with a flat JSON object as the body. A read and a create are `POST`, an
+update is `PATCH`. What the action does is its `operation` (`read`, `create` or `update`), and its
+`method` (`POST` or `PATCH`), in the action index and the OpenAPI document. Any other method
+answers `405 invalid_request` with `Allow` naming the action's one method, so a `POST` to an update
+is refused, not run.
 
-Input as query parameters; `limit` (1 to 250, default 25) and `cursor` for paging.
+Inputs are typed as the action's schema declares them and are never sent as text when they are not:
+an integer is a JSON number (`"patientId": 4711`, not `"4711"`; the text form is refused with
+`400 invalid_request`). Text is normalised to Unicode NFC before anything else happens; a composed
+and a decomposed spelling are the same value.
+
+**Never put an input in the URL.** A value in a URL reaches request logs, proxies and browser
+history, which is where a patient's name or id must not end up. Any query string on an action
+path, whatever it holds, answers `400 invalid_request` ("inputs go in the JSON body, not in the
+URL") without repeating a name or a value. Because the body is JSON, a `+` or a non-ASCII letter
+needs no escaping.
+
+### Reads
+
+A read takes its inputs, and `limit` (a JSON integer from 1 to 250, default 25) and `cursor` (a
+string) for paging, in the same body. No `Idempotency-Key`: a repeated read changes nothing, and the
+header is ignored.
 
 ```bash
-curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchCustomers?lastName=M%C3%BCl&limit=50" \
-  -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+curl -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchCustomers" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"lastName":"Müller","limit":50}'
 ```
 
 ```json
@@ -30,11 +50,10 @@ curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchCustomers?lastN
   punctuation, umlaut spelling). Design your search UI around that rule rather than filtering
   client-side.
 
-## Writes: `POST` (create) or `PATCH` (update)
+### Writes (create and 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.
+Body: a flat JSON object with only the fields the schema lists (`additionalProperties: false`) and
+all of its `required` ones, each typed as the schema declares. Header `Idempotency-Key`, required.
 
 ```bash
 curl -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/createNote" \
@@ -46,11 +65,11 @@ curl -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/createNote" \
 
 - 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.
+- An update is a `PATCH` to the same path, with the same body rules, and 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.
+  do not predict or re-key it. Result field types come from each action's own output schema: 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.
 
@@ -63,7 +82,7 @@ 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.
+2. Pass its id back in the type the write's schema declares, usually the integer the read returned.
 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
@@ -73,13 +92,23 @@ Never invent an id, copy one from another device, or hard-code one from a test r
 
 ## Easy to get wrong
 
-- **Ids come back as integers and go in as strings.** A read and a create answer ids as integers
-  (a create's new id too); only an update echoes the key you sent, as the string you sent.
-  `customerId: 1001` in a search result goes back as `customerId=1001` in a read's query string and
-  as `"customerId": "1001"` in a write body: digits only, no leading zero, at most 10 characters.
+- **Send each input as the type its schema declares.** An id the schema declares as an integer goes
+  in as a JSON number (`"customerId": 1001`), one it declares as text goes in as text
+  (`"customerId": "1001"`: digits only, no leading zero, at most 10 characters). A value of the
+  wrong type is refused with `400 invalid_request`, never converted. Result field types also come
+  from the action's own output schema.
 - **Mark every test text `TEST-DEEPDOCK-<id>`** on the demo device only, and list what you created
   ([testing.md](testing.md)).
-- A read action's query string treats `+` as a space: send a literal `+` as `%2B`.
+- A call with a query string, or with a method other than the action's own, is refused (`400` and `405`), so a
+  client library that puts parameters in the URL for you needs its body mode.
+
+## Refusals specific to the call shape
+
+| Answer | Cause | Fix |
+|---|---|---|
+| `405 invalid_request`, `Allow: POST` or `Allow: PATCH` | a method other than the action's own (for example `POST` to an update, or `PATCH` to a read or create) | use the method `Allow` names: `POST` for a read or create, `PATCH` for an update |
+| `400 invalid_request` | a query string on an action path | move every value into the JSON body |
+| `400 invalid_request` | an input of the wrong type, such as `"4711"` where an integer is declared | send the type the schema declares |
 
 ## Timeouts and latency
 
@@ -110,7 +139,7 @@ attempts per key per rolling 60 seconds, whose `429` carries neither the header
 | 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 |
+| `Allow` | `405 invalid_request` | the action's one method: `POST` for a read or create, `PATCH` for an update |
 | `WWW-Authenticate: Bearer` | `401` | the key was refused |
 | `Retry-After` | `429` | seconds to wait, when present |
 

package/skill/references/cli.md

@@ -24,7 +24,7 @@ the API key the CLI wrote to the app's env file.
 | `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 |
+| `actions list <device> <system>` | the action index: every action with its operation 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 |

package/skill/references/clients/deepdock.py

@@ -2,18 +2,21 @@
 
 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.
+Everything action-specific (fields, types, patterns) comes from the live OpenAPI document.
 """
 
 from __future__ import annotations
 
 import os
 from dataclasses import dataclass, field, replace
-from typing import Any, Dict, Iterator, List, Optional, Tuple
+from typing import Any, Dict, Iterator, List, Optional, Tuple, Union
 from urllib.parse import quote
 
 import httpx
 
+# A flat JSON value as the action's schema declares it: a number is a number, never its text.
+InputValue = Union[str, int, float, bool]
+
 
 class DeepdockError(Exception):
     """Deepdock answered `{ "error": { "code", ... } }`. Switch on `code`, never on `message`."""
@@ -79,18 +82,19 @@ class Deepdock:
     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],
+    def read(self, device_id: str, system: str, action: str, params: Dict[str, InputValue],
              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)
+        """Runs a read action: a POST whose JSON body holds the inputs and the paging fields, no
+        Idempotency-Key. Pass `next_cursor` back as `cursor` for the next page."""
+        body: Dict[str, InputValue] = dict(params)
         if limit is not None:
-            query["limit"] = str(limit)
+            body["limit"] = limit
         if cursor is not None:
-            query["cursor"] = cursor
-        data, _ = self._send("GET", self._action_path(device_id, system, action), params=query)
+            body["cursor"] = cursor
+        data, _ = self._send("POST", self._action_path(device_id, system, action), json=body)
         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],
+    def read_all(self, device_id: str, system: str, action: str, params: Dict[str, InputValue],
                  limit: Optional[int] = None) -> Iterator[Dict[str, Any]]:
         """Reads every page of a read action, in order."""
         cursor: Optional[str] = None
@@ -101,10 +105,15 @@ class Deepdock:
                 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,
+    def write(self, device_id: str, system: str, action: str, operation: str, idempotency_key: str,
+              body: Dict[str, InputValue]) -> WriteResult:
+        """Runs a write action: POST for operation "create", PATCH for "update" (from the action index; any
+        other method answers 405 with `Allow` naming the right one). `body` values are typed as the
+        action's schema declares. Any other `operation` raises ValueError before anything is sent."""
+        if operation not in ("create", "update"):
+            raise ValueError(f"operation must be 'create' or 'update', got {operation!r}")
+        data, headers = self._send("PATCH" if operation == "update" else "POST",
+                                   self._action_path(device_id, system, action), json=body,
                                    headers={"Idempotency-Key": idempotency_key})
         return WriteResult(data=data, replayed=headers.get("Idempotent-Replayed") == "true")
 
@@ -146,8 +155,8 @@ class PendingWrite:
     device_id: str
     system: str
     action: str
-    method: str
-    input: Dict[str, str]
+    operation: str  # create | update, from the action index
+    input: Dict[str, InputValue]
     status: str = "pending"  # pending | sent | done | unknown | refused
     conflict_retries: int = 0
     result: Optional[Dict[str, Any]] = field(default=None)
@@ -158,7 +167,7 @@ class PendingWrite:
 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)
+        res = dd.write(row.device_id, row.system, row.action, row.operation, row.key, row.input)
         return replace(row, status="done", result=res.data)
     except DeepdockTransportError:
         return replace(row, status="sent")

package/skill/references/clients/deepdock.ts

@@ -3,7 +3,7 @@
  *
  * 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.
+ * Everything action-specific (fields, types, patterns) comes from the live OpenAPI document.
  */
 
 // Plain fields, no constructor parameter properties: Node runs this file with its default type
@@ -55,7 +55,11 @@ type Envelope<T> = { data: T } | { error: ErrorBody }
 
 export type Page<Item> = { items: Item[]; nextCursor: string | null }
 export type WriteResult<T> = { data: T; replayed: boolean }
-export type WriteMethod = 'POST' | 'PATCH'
+/** A flat JSON value as the action's schema declares it: a number is a number, never its text. */
+export type InputValue = string | number | boolean
+/** What a write action does, from `operation` in the action index: a create is POST, an update PATCH. */
+export type WriteOperation = 'create' | 'update'
+export type ActionInput = Record<string, InputValue>
 
 export type SystemStatus = 'running' | 'stopped' | 'missing' | 'unknown'
 /** The database access the device last reported; `null` while none is known. */
@@ -187,19 +191,27 @@ export class Deepdock {
     return `/v1/devices/${encodeURIComponent(deviceId)}/systems/${encodeURIComponent(system)}/actions/${encodeURIComponent(action)}`
   }
 
-  /** Runs a read action. Pass `nextCursor` back as `cursor` for the next page. */
+  /**
+   * Runs a read action: a POST whose JSON body holds the inputs and the paging fields, no
+   * Idempotency-Key. Pass `nextCursor` back as `cursor` for the next page.
+   */
   async read<Item>(
     deviceId: string,
     system: string,
     action: string,
-    input: Record<string, string>,
+    input: ActionInput,
     page: { limit?: number; cursor?: string } = {},
   ): Promise<Page<Item>> {
-    const query = new URLSearchParams(input)
-    if (page.limit !== undefined) query.set('limit', String(page.limit))
-    if (page.cursor !== undefined) query.set('cursor', page.cursor)
-    const suffix = query.size > 0 ? `?${query}` : ''
-    return (await this.send<Page<Item>>(`${this.actionPath(deviceId, system, action)}${suffix}`, { method: 'GET' })).data
+    const body: ActionInput = { ...input }
+    if (page.limit !== undefined) body.limit = page.limit
+    if (page.cursor !== undefined) body.cursor = page.cursor
+    return (
+      await this.send<Page<Item>>(this.actionPath(deviceId, system, action), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+      })
+    ).data
   }
 
   /** Reads every page of a read action, in order. */
@@ -207,7 +219,7 @@ export class Deepdock {
     deviceId: string,
     system: string,
     action: string,
-    input: Record<string, string>,
+    input: ActionInput,
     limit?: number,
   ): AsyncGenerator<Item> {
     let cursor: string | undefined
@@ -219,19 +231,21 @@ export class Deepdock {
   }
 
   /**
-   * Runs a write action. `method` comes from the action index or the OpenAPI document; `input`
-   * values are all strings. `idempotencyKey` is new per intended write and the same on every retry.
+   * Runs a write action: POST for a `create`, PATCH for an `update`. Take `operation` from the
+   * action index; any other method answers 405 with `Allow` naming the right one. `input` values
+   * are typed as the action's schema declares. `idempotencyKey` is new per intended write and the
+   * same on every retry.
    */
   async write<Result>(
     deviceId: string,
     system: string,
     action: string,
-    method: WriteMethod,
+    operation: WriteOperation,
     idempotencyKey: string,
-    input: Record<string, string>,
+    input: ActionInput,
   ): Promise<WriteResult<Result>> {
     const { data, headers } = await this.send<Result>(this.actionPath(deviceId, system, action), {
-      method,
+      method: operation === 'update' ? 'PATCH' : 'POST',
       headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
       body: JSON.stringify(input),
     })
@@ -276,8 +290,8 @@ export type PendingWrite = {
   deviceId: string
   system: string
   action: string
-  method: WriteMethod
-  input: Record<string, string>
+  operation: WriteOperation
+  input: ActionInput
   status: PendingStatus
   conflictRetries: number
   result?: unknown
@@ -303,7 +317,7 @@ const RETRY_SAME_KEY = new Set([
 /** One attempt; returns the row with its new status. The caller persists it. */
 export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingWrite> => {
   try {
-    const { data } = await dd.write(row.deviceId, row.system, row.action, row.method, row.key, row.input)
+    const { data } = await dd.write(row.deviceId, row.system, row.action, row.operation, row.key, row.input)
     return { ...row, status: 'done', result: data }
   } catch (err) {
     if (err instanceof DeepdockTransportError) return { ...row, status: 'sent' }

package/skill/references/concepts.md

@@ -72,9 +72,11 @@ offering it; it then runs the same way every time. Actions are
 **assigned** to your organisation by Deepdock, so the set you can call is yours, not the whole
 catalogue.
 
-- A **read** is `GET` with query parameters and pages.
-- A **write** is `POST` (creates a record, answers `201`) or `PATCH` (updates a record, answers
-  `200`), with a JSON body of string fields and an `Idempotency-Key` header.
+- Every action takes a flat JSON body; its `operation` says what it does: `POST` for a read or a
+  create, `PATCH` for an update.
+- A **read** also pages with `limit` and `cursor` in the body.
+- A **write** is a `create` (answers `201`) or an `update` (answers `200`), and needs an
+  `Idempotency-Key` header.
 - A write **either fully applies or not**: Deepdock checks the result before confirming, and if the check fails it saves nothing
   and pauses the action (`409 readback_failed`).
 - An action is **active** or **paused**. `GET /v1/devices/{deviceId}/systems` shows each action's

package/skill/references/discovery.md

@@ -7,7 +7,7 @@ Never hard-code an action's fields. Three sources, each authoritative for one th
 | Which systems and actions does my organisation have? | `deepdock systems list --json` | CLI sign-in |
 | What does this device run, and is each action active or paused? | `GET /v1/devices/{deviceId}/systems` | organisation |
 | Which actions can I call on this device's system, with which schemas? | `GET /v1/devices/{deviceId}/systems/{system}/actions` | organisation |
-| The exact paths, methods, fields, patterns, enums, lengths, responses | `deepdock systems openapi <system>` (CLI sign-in) or `GET /v1/systems/{system}/openapi.json` (API key); per device `deepdock actions list <device> <system>` (CLI sign-in) | CLI sign-in or API key |
+| The exact paths, operations, fields, patterns, enums, lengths, responses | `deepdock systems openapi <system>` (CLI sign-in) or `GET /v1/systems/{system}/openapi.json` (API key); per device `deepdock actions list <device> <system>` (CLI sign-in) | CLI sign-in or API key |
 
 ## The OpenAPI document
 
@@ -25,20 +25,19 @@ document into the repository and refresh it with the same command when you touch
 What to read off it:
 
 - **`paths`**: one operation per action at
-  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; the HTTP method is the action's
-  kind (`get` read, `post` create, `patch` update). Use the method the document gives; the other
-  write method answers `405 invalid_request` with an `Allow` header.
+  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; each is a `post` (read, create) or a `patch` (update);
+  its `operation` says which. Any other method answers `405 invalid_request` with `Allow` naming
+  the right one.
 - **`summary` and `description`**: what the action does and what it changes in the system, what
   an omitted optional input becomes, action-specific refusals (`code` and when), and what the
   system only warns about and what the action does then. Read the description before mapping your
   fields.
-- **Read inputs** are query parameters, all `type: string`, each with `maxLength` and possibly
-  `minLength`, `pattern`, `enum` and a `description` such as "prefix match: case, punctuation and
-  umlaut spelling are ignored". Plus `limit` (integer, 1 to 250, default 25) and `cursor` (opaque).
-  An optional parameter is not in `required` and its description says what an omitted value
-  becomes.
-- **Write inputs** are the `requestBody` object schema: `additionalProperties: false`, every
-  property `type: string`, `required` lists the mandatory ones. The `Idempotency-Key` header
+- **Inputs** are the `requestBody` object schema of every action, read or write:
+  `additionalProperties: false`, each property with its declared `type`, and for text `maxLength`
+  and possibly `minLength`, `pattern`, `enum` and a `description` such as "prefix match: case, punctuation and
+  umlaut spelling are ignored". A read's body also takes `limit` (integer, 1 to 250, default 25) and
+  `cursor` (opaque). An optional input is not in `required` and its description says what an
+  omitted value becomes. A write's `Idempotency-Key` header
   parameter carries its own pattern (8 to 128 characters of `A-Z a-z 0-9 _ -`).
 - **Responses**: a read's `200` is `{ data: { items: [...], nextCursor } }`; a create's `201` and a
   replayed `200`; an update's `200`. Item and result fields are typed `string`, `integer` or `number`,
@@ -57,7 +56,7 @@ curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" \
   -H "Authorization: Bearer $DEEPDOCK_API_KEY"
 ```
 
-Answers `{ data: [ { name, method, description, input, output } ] }`, filtered to your assigned
+Answers `{ data: [ { name, operation, method, description, input, output } ] }`, filtered to your assigned
 actions, with the same JSON Schemas the OpenAPI document carries. Use it at runtime to confirm an
 action exists before offering it in your UI, or to validate input client-side before sending.
 

package/skill/references/errors.md

@@ -17,7 +17,7 @@ with the **same** `Idempotency-Key`); **Show** says what the end user should see
 
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
-| `invalid_request` | 400 (405 for a wrong method) | malformed request: bad query, `limit` or `cursor`; missing or malformed `Idempotency-Key`; a body that is not an object; an action input that is unknown, missing, of the wrong type, too short or long, out of bounds or not an allowed value (`fields` names each); a malformed pairing code or device id; a write called with the other method (`Allow` names the right one) | no; fix the code | nothing; a developer bug |
+| `invalid_request` | 400 (405 for a method other than the action's own) | malformed request: bad `limit` or `cursor` in a read's body; missing or malformed `Idempotency-Key`; a body that is not an object; an action input that is unknown, missing, too short or long, out of bounds or not an allowed value (`fields` names each); a malformed pairing code or device id; a query string on an action path (inputs go in the JSON body), an input of the wrong type, such as `"4711"` where an integer is declared, an action called with a method other than its own (`405`, `Allow` names the one: `POST` for a read or create, `PATCH` for an update) | no; fix the code | nothing; a developer bug |
 | `payload_too_large` | 413 | the request body is over 1 MiB | no; send less | nothing; a developer bug, or shorten the text |
 | `unauthenticated` | 401 | the key is missing, malformed, for the other environment, unknown, revoked or expired | no | "Deepdock API key refused; check it in the dashboard" to an operator |
 | `partner_not_approved` | 403 | your organisation is waiting for approval by Deepdock; no key of it works yet. Keys made before the approval start working once it is given | no, until Deepdock approves; then yes | "our Deepdock account is waiting for approval; contact Deepdock" |

package/skill/references/example-integration.md

@@ -23,7 +23,7 @@ import { Deepdock, DeepdockError, DeepdockTransportError, attempt, type PendingW
 const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // base from DEEPDOCK_BASE_URL, else production; 30 s timeout
 const page = await dd.read<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' }, { limit: 50 })
 for await (const p of dd.readAll<Note>(deviceId, 'example-erp', 'searchNotes', { text: 'TEST-DEEPDOCK-' })) { /* every page */ }
-const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', 'POST', key, input)
+const { data, replayed } = await dd.write<{ noteId: number }>(deviceId, 'example-erp', 'createNote', 'create', key, input)
 const systems = await dd.systems(deviceId)                      // live; can throw device_offline
 const device = await dd.pair('K7Q-4MX', 'Demo')                 // keep device.id
 ```
@@ -33,7 +33,7 @@ from deepdock import Deepdock, DeepdockError, DeepdockTransportError, PendingWri
 
 dd = Deepdock(os.environ["DEEPDOCK_API_KEY"])
 page = dd.read(device_id, "example-erp", "searchNotes", {"text": "TEST-DEEPDOCK-"}, limit=50)
-res = dd.write(device_id, "example-erp", "createNote", "POST", key, body)   # res.data, res.replayed
+res = dd.write(device_id, "example-erp", "createNote", "create", key, body)   # res.data, res.replayed
 ```
 
 Errors: `DeepdockError` has `status`, `code`, `requestId`, `systems`; switch on `code`
@@ -42,7 +42,7 @@ Errors: `DeepdockError` has `status`, `code`, `requestId`, `systems`; switch on
 
 ## Sending a write: persist first, then one attempt at a time
 
-Persist the pending write (key, device, action, method, input, status) **before** the first send,
+Persist the pending write (key, device, action, operation, input, status) **before** the first send,
 so a crash between send and answer cannot produce a second record under a new key. `attempt()`
 moves the row to `done`, `sent` (retry later, same key), `unknown` (read back before anything
 else) or `refused` (nothing was written; a changed input gets a new key). A job retries `sent`
@@ -51,7 +51,7 @@ rows with backoff: seconds, then minutes, for hours if the device stays offline.
 ```ts
 const row: PendingWrite = {
   key: `order-${order.id}-create-note`, // 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event
-  deviceId, system: 'example-erp', action: 'createNote', method: 'POST',
+  deviceId, system: 'example-erp', action: 'createNote', operation: 'create',
   input, status: 'pending', conflictRetries: 0,
 }
 await store.save(row)                      // before the first send
@@ -74,7 +74,7 @@ const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms))
 export const run = async (store: { save: (row: PendingWrite) => Promise<void> }) => {
   const marker = `TEST-DEEPDOCK-${randomUUID().replaceAll('-', '').slice(0, 6).toUpperCase()}`
   let row: PendingWrite = {
-    key: `demo-${marker}-create`, deviceId, system, action: 'createNote', method: 'POST',
+    key: `demo-${marker}-create`, deviceId, system, action: 'createNote', operation: 'create',
     input: { text: marker, orderNumber: '1001' },
     status: 'pending', conflictRetries: 0,
   }
@@ -122,8 +122,9 @@ curl -sS "$BASE/v1/devices/$DEVICE/systems" -H "$AUTH"
 # The action index (your assigned actions, with schemas)
 curl -sS "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" -H "$AUTH"
 
-# A read, paged: pass data.nextCursor back as cursor
-curl -sS "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchNotes?text=TEST-DEEPDOCK-&limit=50" -H "$AUTH"
+# A read is a POST too, with its inputs and limit/cursor in the body; paged: pass data.nextCursor back as cursor
+curl -sS -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchNotes" \
+  -H "$AUTH" -H 'Content-Type: application/json' -d '{"text":"TEST-DEEPDOCK-","limit":50}'
 
 # A create: new Idempotency-Key per intended write, the same on every retry; 201, or 200 with
 # Idempotent-Replayed: true on a replay (-i shows the headers)
@@ -134,7 +135,7 @@ curl -sS -i -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/create
 # An update: PATCH, same rules
 curl -sS -i -X PATCH "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/updateNote" \
   -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-update" -H 'Content-Type: application/json' \
-  -d '{"noteId":"1001","text":"TEST-DEEPDOCK-K3M9QA edited"}'
+  -d '{"noteId":1001,"text":"TEST-DEEPDOCK-K3M9QA edited"}'
 
 # Release a device
 curl -sS -X DELETE "$BASE/v1/devices/$DEVICE" -H "$AUTH"
@@ -142,7 +143,7 @@ curl -sS -X DELETE "$BASE/v1/devices/$DEVICE" -H "$AUTH"
 
 A port in another language keeps the clients' shape: one `send` that sets the bearer header,
 parses the envelope, throws a typed error with `code` on `{ error }` and a transport error on no
-answer or non-JSON; `read` with `limit` and `cursor`; `write` with `Idempotency-Key` and the
+answer or non-JSON; `read` as a POST with `limit` and `cursor` in the body; `write` (POST for a create, PATCH for an update) with `Idempotency-Key` and the
 `Idempotent-Replayed` header; `attempt` over a persisted pending write.
 
 ## Mapping the user's intent to a call (checklist)
@@ -150,9 +151,9 @@ answer or non-JSON; `read` with `limit` and `cursor`; `write` with `Idempotency-
 1. Which device? From your product's configuration for that customer site; never from the
    user's free text.
 2. Is the action active? `systems()` once per session; show paused features as paused.
-3. Which action and method? From the stored index for that system.
+3. Which action and operation (create is POST, update is PATCH)? From the stored index for that system.
 4. Does the write need a reference (author user, open case, record id)? Read it first.
-5. Build the input as strings; validate against the schema (`pattern`, `minLength`, `maxLength`,
+5. Build the input in the types the schema declares; validate against the schema (`pattern`, `minLength`, `maxLength`,
    `enum`) before sending so the user sees the rule where they typed.
 6. Choose the idempotency key from your business event and persist it with the pending write.
 7. Send; map the code with the reaction table; show the user the right sentence.

package/skill/references/idempotency.md

@@ -1,7 +1,7 @@
 # Idempotency for writes
 
-Every `POST` or `PATCH` to an action carries an `Idempotency-Key` header. Without it the request is
-refused with `400 invalid_request`.
+Every write (a `create` action, called with `POST`, or an `update`, called with `PATCH`) carries an `Idempotency-Key` header. Without it the request is
+refused with `400 invalid_request`. A read ignores the header.
 
 ## The key