@deepdockai/cli 1.0.23 → 1.0.26

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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.
+- `system_version_unverified` can carry `error.reason: unreported` with `error.version: null`, and a system's `writes` can read `unverified` with reason `unreported`: such a write is verified for one exact release, and the system reported none.
+- `error.uncertain` is documented on `outcome_unknown`. The skill's error reference describes all of it.
+
+## 1.0.24
+
+- `devices list` and `incidents list` read every page of the API's paged answer (`limit` and `cursor`, following `nextCursor`), so no device or incident past the first 500 or 100 stays invisible. Output is unchanged. They stop after 200 pages with a warning on stderr. This needs the API that pages these lists; an older answer is refused with exit 3.
+
 ## 1.0.23
 
 - An incident's program version is named `programVersion` instead of `version`, in `GET /v1/incidents`, in `incidents list --json` and in the skill's concepts. Read the new name where you read the old one; the value is unchanged.

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                                                                                                                      |
@@ -154,14 +154,14 @@ your code will receive; `auth`, `org select` and `keys create` build it from nam
 failure is one document on stderr, `{ "error": { "code", "message" }, "meta": { "hint" } }`,
 with the API's error object unchanged. Switch on `code` or on the exit code, never on `message`.
 
-| Exit | Meaning                                                                                                                                                                                                                                                                        |
-| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 0    | done                                                                                                                                                                                                                                                                           |
-| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                                                                                                                                                         |
-| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)                                                                                                                                   |
-| 3    | retry later (`device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost`) |
-| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                                                                                                                                           |
-| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                                                                                                                                               |
+| Exit | Meaning                                                                                                                                                                                                                                                                                                                       |
+| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0    | done                                                                                                                                                                                                                                                                                                                          |
+| 1    | something on the command line to fix (`invalid_usage`, `org_required`)                                                                                                                                                                                                                                                        |
+| 2    | the API refused the request; do not repeat it unchanged (`invalid_request`, `not_found`, `forbidden`, `rate_limited` and the other refusals)                                                                                                                                                                                  |
+| 3    | retry later (`device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `credentials_rejected`, `certificate_changed`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost`) |
+| 4    | the CLI is too old for the API (`client_outdated`): run `npx @deepdockai/cli@latest`                                                                                                                                                                                                                                          |
+| 5    | sign-in needed (`sign_in_needed`, `approval_denied`, `approval_expired`); `auth status` when nobody is signed in                                                                                                                                                                                                              |
 
 The CLI never retries on its own: exit 3 says retry, you decide when. `deepdock commands --json`
 prints the whole command tree.

package/dist/deepdock.js

@@ -10866,6 +10866,7 @@ var EXIT_CODES = {
   rate_limited: 2,
   target_rejected: 2,
   readback_failed: 2,
+  applied_unverified: 2,
   idempotency_conflict: 2,
   conflict: 2,
   already_member: 2,
@@ -10880,6 +10881,8 @@ var EXIT_CODES = {
   action_paused: 3,
   access_outdated: 3,
   access_missing: 3,
+  credentials_rejected: 3,
+  certificate_changed: 3,
   system_unavailable: 3,
   target_busy: 3,
   temporarily_unavailable: 3,
@@ -11233,13 +11236,20 @@ 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,
+    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
@@ -11429,7 +11439,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.23";
+var VERSION = "1.0.26";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -12160,6 +12170,7 @@ var EXIT_CODES_HELP = `Exit codes
   2  the API refused the request; do not repeat it unchanged
   3  retry later (device_offline, device_syncing, device_outdated,
      system_version_unverified, action_paused, access_outdated, access_missing,
+     credentials_rejected, certificate_changed,
      system_unavailable, target_busy, temporarily_unavailable, internal_error,
      outcome_unknown, connection_lost)
   4  the CLI is too old for the API (client_outdated)
@@ -12828,6 +12839,40 @@ var registerAuth = (program, run) => {
   auth.command("logout").description("Revoke the sign-in and the API keys this CLI created").option("--keep-keys", "revoke only the sign-in and leave the API keys active").action((options, cmd) => run(cmd, (ctx) => logout(ctx, options)));
 };
 
+// src/commands/pages.ts
+var PAGE_LIMIT = 500;
+var MAX_PAGES = 200;
+var unreadable = () => new CliError({
+  code: "connection_lost",
+  message: "The API answered a list in a shape this CLI does not read.",
+  hint: "Update the CLI with `npm install -g @deepdockai/cli@latest`, then retry."
+});
+var readAllPages = async (ctx, path, org) => {
+  const items = [];
+  let cursor = null;
+  let requestId;
+  for (let page = 1;page <= MAX_PAGES; page++) {
+    const query = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    if (cursor !== null)
+      query.set("cursor", cursor);
+    const url = `${path}?${query.toString()}`;
+    const response = org ? await ctx.call({ method: "GET", path: url, org }) : await ctx.callInOrg({ method: "GET", path: url });
+    const data = response.data;
+    if (!isRecord(data) || !Array.isArray(data.items))
+      throw unreadable();
+    const next = data.nextCursor;
+    if (next !== null && (typeof next !== "string" || next === ""))
+      throw unreadable();
+    items.push(...data.items);
+    requestId ??= response.requestId;
+    if (next === null)
+      return { items, requestId };
+    cursor = next;
+  }
+  ctx.note(`Warning: stopped after ${MAX_PAGES} pages; the list is longer than the ${items.length} rows shown.`);
+  return { items, requestId };
+};
+
 // src/commands/devices.ts
 var meta = (requestId) => requestId ? { requestId } : {};
 var updateNotes = (ctx, devices) => {
@@ -12840,19 +12885,18 @@ var updateNotes = (ctx, devices) => {
   }
 };
 var list = async (ctx) => {
-  const response = await ctx.callInOrg({ method: "GET", path: "/partner/devices" });
-  const devices = Array.isArray(response.data) ? response.data : [];
+  const { items: devices, requestId } = await readAllPages(ctx, "/partner/devices");
   if (devices.length === 0) {
     return {
-      data: response.data,
-      meta: meta(response.requestId),
+      data: devices,
+      meta: meta(requestId),
       text: "No devices are paired. Pair one with `deepdock devices pair <code>`."
     };
   }
   updateNotes(ctx, devices);
   return {
-    data: response.data,
-    meta: meta(response.requestId),
+    data: devices,
+    meta: meta(requestId),
     text: deviceTable(devices, ctx.rt.now(), ctx.out)
   };
 };
@@ -12906,8 +12950,8 @@ var release = async (ctx, id) => {
   if (!ctx.opts.yes) {
     let label = "";
     try {
-      const response = await ctx.call({ method: "GET", path: "/partner/devices", org: org.slug });
-      const found = Array.isArray(response.data) ? response.data.filter(isRecord).find((device) => field(device, "id") === deviceId) : undefined;
+      const { items } = await readAllPages(ctx, "/partner/devices", org.slug);
+      const found = items.filter(isRecord).find((device) => field(device, "id") === deviceId);
       label = found ? field(found, "label") : "";
     } catch {}
     const named = label ? ` (${stripControl(label)})` : "";
@@ -12966,10 +13010,9 @@ var registerDevices = (program, run) => {
 var registerIncidents = (program, run) => {
   const incidents = program.command("incidents").description("Incidents that paused an action on one of your devices");
   incidents.command("list").description("List open incidents and those closed within 30 days").action((_options, cmd) => run(cmd, async (ctx) => {
-    const response = await ctx.callInOrg({ method: "GET", path: "/partner/incidents" });
-    const items = Array.isArray(response.data) ? response.data : [];
+    const { items, requestId } = await readAllPages(ctx, "/partner/incidents");
     const text = items.length === 0 ? "No incidents." : genericTable(items, ctx.out, INCIDENT_COLUMNS);
-    return { data: response.data, meta: { requestId: response.requestId }, text };
+    return { data: items, meta: { requestId }, text };
   }));
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.23",
+  "version": "1.0.26",
   "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,9 @@ 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 is a `POST` with a flat JSON body, never a value in the URL. 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,35 @@
 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
 
-## Reads: `GET`
+Every action, whether it reads, creates or updates, is called with `POST` and a flat JSON object as
+the body. What the action does is its `operation` (`read`, `create` or `update`) in the action
+index and the OpenAPI document; the HTTP method never says. Any other method answers
+`405 invalid_request` with `Allow: POST`.
 
-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 +49,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 +64,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 `POST` too 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 +81,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 +91,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 any method but `POST`, 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` | any method but `POST` on an action path | call it with `POST` |
+| `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 +138,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` | always `POST`: every action is called with it |
 | `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 |
@@ -84,7 +84,7 @@ A failure is one document on stderr: the API's error object unchanged plus what
 | 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 (not `access_outdated` and `access_missing`, see exit 3) |
-| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `connection_lost` |
+| 3 | retry later (`access_outdated` and `access_missing`: after the customer repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `device_syncing`, `device_outdated`, `system_version_unverified`, `action_paused`, `access_outdated`, `access_missing`, `credentials_rejected`, `certificate_changed`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `outcome_unknown`, `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` |
 

package/skill/references/clients/deepdock.py

@@ -2,32 +2,38 @@
 
 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`."""
 
     def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None,
                  systems: Optional[List[str]] = None, version: Optional[str] = None,
-                 reason: Optional[str] = None):
+                 reason: Optional[str] = None, created: Optional[Dict[str, Any]] = None,
+                 uncertain: Optional[bool] = None):
         super().__init__(message)
         self.status = status
         self.code = code
         self.request_id = request_id
         self.systems = systems
-        self.version = version  # system_version_unverified: the version the system last reported
-        self.reason = reason  # system_version_unverified: unverified_version or unparseable
+        self.version = version  # system_version_unverified: the version the system last reported, None when it reported none
+        self.reason = reason  # system_version_unverified: unverified_version, unparseable or unreported
+        self.created = created  # applied_unverified, outcome_unknown with no rollback: {"chartId"} or None
+        self.uncertain = uncertain  # outcome_unknown: True when the write may or may not have landed
 
 
 class DeepdockTransportError(Exception):
@@ -67,7 +73,7 @@ class Deepdock:
         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"),
-                                e.get("version"), e.get("reason"))
+                                e.get("version"), e.get("reason"), e.get("created"), e.get("uncertain"))
         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
@@ -76,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
@@ -98,10 +105,10 @@ 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, idempotency_key: str,
+              body: Dict[str, InputValue]) -> WriteResult:
+        """Runs a write action (a create or an update) with POST; `body` values are typed as the action's schema declares."""
+        data, headers = self._send("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")
 
@@ -143,8 +150,7 @@ class PendingWrite:
     device_id: str
     system: str
     action: str
-    method: str
-    input: Dict[str, str]
+    input: Dict[str, InputValue]
     status: str = "pending"  # pending | sent | done | unknown | refused
     conflict_retries: int = 0
     result: Optional[Dict[str, Any]] = field(default=None)
@@ -155,7 +161,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.key, row.input)
         return replace(row, status="done", result=res.data)
     except DeepdockTransportError:
         return replace(row, status="sent")
@@ -166,8 +172,11 @@ def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
             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)
+        # applied_unverified: the entry exists but was not verified; never write it again under a new
+        # key. result["created"] names it for the check.
+        if e.code in ("outcome_unknown", "applied_unverified"):
+            return replace(row, status="unknown", request_id=e.request_id,
+                           result={"created": e.created, "uncertain": e.uncertain})
         # invalid_input, target_rejected, action-specific 422s, not_found, readback_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)})

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
@@ -13,15 +13,21 @@ export class DeepdockError extends Error {
   readonly code: string
   readonly requestId?: string
   readonly systems?: string[]
-  /** system_version_unverified: the version the system last reported. */
-  readonly version?: string
-  /** system_version_unverified: `unverified_version` or `unparseable`. */
+  /** system_version_unverified: the version the system last reported, `null` when it reported none. */
+  readonly version?: string | null
+  /** system_version_unverified: `unverified_version`, `unparseable` or `unreported`. */
   readonly reason?: string
+  /** applied_unverified, outcome_unknown on a system with no rollback: the entry, or `null` when not known. */
+  readonly created?: { chartId?: string } | null
+  /** outcome_unknown: `true` when the write may or may not have landed. */
+  readonly uncertain?: boolean
 
   constructor(status: number, code: string, message: string, requestId?: string,
     systems?: string[],
-    version?: string,
+    version?: string | null,
     reason?: string,
+    created?: { chartId?: string } | null,
+    uncertain?: boolean,
   ) {
     super(message)
     this.name = 'DeepdockError'
@@ -31,6 +37,8 @@ export class DeepdockError extends Error {
     this.systems = systems
     this.version = version
     this.reason = reason
+    this.created = created
+    this.uncertain = uncertain
   }
 }
 
@@ -42,12 +50,14 @@ export class DeepdockTransportError extends Error {
   }
 }
 
-type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[]; version?: string; reason?: string }
+type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[]; version?: string | null; reason?: string; created?: { chartId?: string } | null; uncertain?: boolean }
 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
+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. */
@@ -56,11 +66,12 @@ export type SystemAccess = 'ok' | 'outdated' | 'missing' | 'password_missing' |
 /**
  * Whether writes on the system run. `unverified` makes writes answer system_version_unverified:
  * `unverified_version` clears once Deepdock verifies the version; `unparseable` does not clear by
- * waiting (contact Deepdock).
+ * waiting (contact Deepdock); `unreported` clears once the device reports the system's version (a
+ * write verified for one exact release needs it).
  */
 export type SystemWrites =
   | { state: 'verified' | 'unknown' | 'partial' }
-  | { state: 'unverified'; reason: 'unverified_version' | 'unparseable' }
+  | { state: 'unverified'; reason: 'unverified_version' | 'unparseable' | 'unreported' }
 
 export type Device = {
   id: string
@@ -165,8 +176,8 @@ export class Deepdock {
       throw new DeepdockTransportError(`non-JSON answer with status ${res.status}`)
     }
     if (body !== null && typeof body === 'object' && 'error' in body) {
-      const { code, message, requestId, systems, version, reason } = body.error
-      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason)
+      const { code, message, requestId, systems, version, reason, created, uncertain } = body.error
+      throw new DeepdockError(res.status, code, message, requestId, systems, version, reason, created, uncertain)
     }
     if (body === null || typeof body !== 'object' || !('data' in body)) {
       throw new DeepdockTransportError(`unexpected body with status ${res.status}`)
@@ -178,19 +189,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. */
@@ -198,7 +217,7 @@ export class Deepdock {
     deviceId: string,
     system: string,
     action: string,
-    input: Record<string, string>,
+    input: ActionInput,
     limit?: number,
   ): AsyncGenerator<Item> {
     let cursor: string | undefined
@@ -210,19 +229,18 @@ 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 (a create or an update) with POST. `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,
     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: 'POST',
       headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
       body: JSON.stringify(input),
     })
@@ -267,8 +285,7 @@ export type PendingWrite = {
   deviceId: string
   system: string
   action: string
-  method: WriteMethod
-  input: Record<string, string>
+  input: ActionInput
   status: PendingStatus
   conflictRetries: number
   result?: unknown
@@ -294,7 +311,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.key, row.input)
     return { ...row, status: 'done', result: data }
   } catch (err) {
     if (err instanceof DeepdockTransportError) return { ...row, status: 'sent' }
@@ -305,7 +322,15 @@ export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingW
         ? { ...row, status: 'sent', conflictRetries: row.conflictRetries + 1 }
         : { ...row, status: 'unknown' }
     }
-    if (err.code === 'outcome_unknown') return { ...row, status: 'unknown', requestId: err.requestId }
+    // applied_unverified: the entry exists but was not verified; never write it again under a new
+    // key. `result.created` names it for the check.
+    if (err.code === 'outcome_unknown' || err.code === 'applied_unverified')
+      return {
+        ...row,
+        status: 'unknown',
+        requestId: err.requestId,
+        result: { created: err.created, uncertain: err.uncertain },
+      }
     // invalid_input, target_rejected, action-specific 422s, not_found, readback_failed, auth and
     // resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
     return { ...row, status: 'refused', refusedCode: err.code, result: { message: err.message } }

package/skill/references/concepts.md

@@ -72,9 +72,10 @@ 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 is called with `POST` and a flat JSON body; its `operation` says what it does.
+- 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}`; every one is a `post`;
+  its `operation` says whether it reads, creates or updates. Any other method answers
+  `405 invalid_request` with `Allow: POST`.
 - **`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, 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 but `POST`) | 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 any method but `POST` (`405`, `Allow: POST`) | 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" |
@@ -62,10 +62,12 @@ dashboard-only.
 | `device_offline` | 503 | the device is not connected, is shutting down, did not answer within 20 s, or the call was cut off inside Deepdock by a restart or deploy. **A write may still have landed** | yes, with backoff (seconds to minutes); a write only with the same key | "the customer PC is offline; we will retry" |
 | `device_syncing` | 503 | the device has not reported its Deepdock client yet (just paired, or its report did not come through); Deepdock asks it again. Nothing was written | yes, after `Retry-After` (5 s); a write with the same key | "the customer PC is connecting; retrying" |
 | `device_outdated` | 409 | the device's Deepdock client is too old for this call. It updates itself when a newer version is released for your organisation, once nobody is signed in on the PC. Nothing was written | after the update (`outdated` on `GET /v1/devices/{deviceId}` turns `false`); retrying before it gets the same answer. A write keeps its key | "the Deepdock client on the customer PC needs an update" |
-| `system_version_unverified` | 409 | a write on a system whose vendor version Deepdock has not verified yet. Nothing was sent to the device; reads still work. `error.version` is the version the system last reported and `error.reason` is `unverified_version`, or `unparseable` when that version is not dotted digits | `unverified_version`: after Deepdock has verified that version (`writes` on the system in `GET /v1/devices/{deviceId}` turns `verified`); retrying before it gets the same answer. `unparseable`: retrying does not help, contact Deepdock; only a different reported version changes it. A write keeps its key | "the customer's system was updated to a version Deepdock has not yet verified; changes will work once it has" |
+| `system_version_unverified` | 409 | a write on a system whose vendor version Deepdock has not verified yet. Nothing was sent to the device; reads still work. `error.version` is the version the system last reported (null when it reported none) and `error.reason` is `unverified_version`, `unparseable` when that version is not dotted digits, or `unreported` when the system reported no version: a write over the system's own HTTP interface is verified for one exact release and needs it | `unverified_version`: after Deepdock has verified that version (`writes` on the system in `GET /v1/devices/{deviceId}` turns `verified`); retrying before it gets the same answer. `unparseable`: retrying does not help, contact Deepdock; only a different reported version changes it. `unreported`: later, once the device reports the system's version. A write keeps its key | "the customer's system was updated to a version Deepdock has not yet verified; changes will work once it has" |
 | `action_paused` | 503 | the action is paused on the device (`GET .../systems` shows `reason`); only Deepdock resumes it | later, when `GET .../systems` shows it active; do not loop | "this feature is paused while Deepdock checks the customer system" |
 | `system_unavailable` | 503 | the customer's program is stopped or missing on the device | later; often resolves when the customer restarts the program | "the customer's software is not running" |
 | `target_busy` | 503 | the customer's system is busy or unreachable | yes, with backoff | "the customer's system is busy; retrying" |
+| `credentials_rejected` | 503 | the customer's system refused the device's login. Nothing was sent | later, after a person at the customer has renewed the access in the Deepdock client; do not loop. A write keeps its key | "the connection to the customer's software needs to be renewed at the practice" |
+| `certificate_changed` | 503 | the customer's system shows a certificate other than the one the device trusts. Nothing was sent | later, after a person at the customer has confirmed the new certificate in the Deepdock client; do not loop. A write keeps its key | "the connection to the customer's software needs to be confirmed at the practice" |
 | `temporarily_unavailable` | 503 | Deepdock could not check the key or reach its own database (sent with `Retry-After: 5`) | yes, with backoff | "temporary problem; retrying" |
 
 ## Write outcomes
@@ -73,8 +75,9 @@ dashboard-only.
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
 | `readback_failed` | 409 | the write's result did not match what the action expects, so nothing was saved; **the action is now paused** and an incident is open | no; the next calls answer `action_paused` | "the change was not saved; Deepdock is checking the customer system" |
+| `applied_unverified` | 409 | a write on a system with no rollback was applied, but its read-back did not finish. The entry exists: `error.created` names it as `{ chartId }`, or is null when the entry is not known | **no.** The entry is there; writing again creates a second one. Check it in the customer system | "the change was saved but could not be confirmed; please check it in the customer system" |
 | `idempotency_conflict` | 409 | the key was used with a different input, its write is still running, or its outcome is unknown. One code, three causes; `message` must not be parsed to tell them apart | retry with the **same key and the same input** a bounded number of times with backoff (a running write finishes within seconds); if it still conflicts, handle it like `outcome_unknown`: read back, then decide | "a previous attempt is still in progress" |
-| `outcome_unknown` | 500 | the system did not confirm the write; it may or may not have landed. The key stays blocked | **no.** Read the record back (a search) to see whether it landed before writing again under a new key; involve a human when the read cannot tell | "we could not confirm the change; please check in the customer system before trying again" |
+| `outcome_unknown` | 500 | the system did not confirm the write; it may or may not have landed. The key stays blocked. On a system with no rollback, `error.uncertain` is true and `error.created` names the entry when one is known | **no.** Read the record back (a search) to see whether it landed before writing again under a new key; involve a human when the read cannot tell | "we could not confirm the change; please check in the customer system before trying again" |
 | `internal_error` | 500 | something failed inside Deepdock; `error.requestId` is set | once, later; a write with the same key | "something went wrong"; log `requestId` for Deepdock support |
 
 ## A reaction table for code
@@ -104,6 +107,8 @@ const REACTION: Record<string, Reaction> = {
   payload_too_large: 'fix-code',
   access_outdated: 'wait-setup',
   access_missing: 'wait-setup',
+  credentials_rejected: 'wait-setup',
+  certificate_changed: 'wait-setup',
   device_offline: 'retry-same-key',
   device_syncing: 'retry-same-key',
   device_outdated: 'retry-later',
@@ -113,6 +118,7 @@ const REACTION: Record<string, Reaction> = {
   target_busy: 'retry-same-key',
   temporarily_unavailable: 'retry-same-key',
   readback_failed: 'wait-paused',
+  applied_unverified: 'check-then-decide', // the entry exists; reading it back shows it
   idempotency_conflict: 'retry-same-key', // bounded; then 'check-then-decide'
   outcome_unknown: 'check-then-decide',
   internal_error: 'retry-same-key',
@@ -120,7 +126,7 @@ const REACTION: Record<string, Reaction> = {
 const reactionFor = (code: string): Reaction => REACTION[code] ?? 'stop'
 ```
 
-Action-specific 422 codes beyond the ones above (any the OpenAPI description lists) map to `fix-input`. Add them from the document, not from memory. `wait-setup` means a person at the customer must repeat the database access setup ("Erneut einrichten") in the Deepdock client first; there is no `Retry-After`, so do not loop. Check `access` on the system in `GET .../systems` (`ok` again), then retry; a write keeps its key. `retry-same-key` means the
+Action-specific 422 codes beyond the ones above (any the OpenAPI description lists) map to `fix-input`. Add them from the document, not from memory. `wait-setup` means a person at the customer must act in the Deepdock client first: repeat the database access setup ("Erneut einrichten") for `access_*`, renew the login for `credentials_rejected`, confirm the new certificate for `certificate_changed`; there is no `Retry-After`, so do not loop. Check `access` on the system in `GET .../systems` (`ok` again), then retry; a write keeps its key. `retry-same-key` means the
 pending write stays persisted and is retried from that state with backoff, also across process
 restarts; a device can be offline for hours, so the retry loop lives in a job or queue, not in the
 request that started the write.

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', 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", 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, 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',
   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',
     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)
@@ -131,10 +132,10 @@ curl -sS -i -X POST "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/create
   -H "$AUTH" -H "Idempotency-Key: demo-$(date +%s)-create" -H 'Content-Type: application/json' \
   -d '{"text":"TEST-DEEPDOCK-K3M9QA","orderNumber":"1001"}'
 
-# An update: PATCH, same rules
-curl -sS -i -X PATCH "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/updateNote" \
+# An update: also POST, same rules
+curl -sS -i -X POST "$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` 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? 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` or `update` action, called with `POST`) carries an `Idempotency-Key` header. Without it the request is
+refused with `400 invalid_request`. A read ignores the header.
 
 ## The key
 
@@ -74,6 +74,7 @@ pending ──send──▶ sent ──2xx (fresh or replayed)──────
                    │  ──idempotency_conflict, retries left ───▶ sent     (retry, same key, same input)
                    │  ──idempotency_conflict, retries spent ──▶ unknown  (read back before anything else)
                    │  ──outcome_unknown ──────────────────────▶ unknown  (read back before anything else)
+                   │  ──applied_unverified ───────────────────▶ unknown  (the entry exists: check it by result.created, never write it again)
                    │  ──invalid_input, target_rejected, action-specific 422, not_found, readback_failed ▶ refused  (key is free; new input gets a new key)
                    │  ──action_paused, system_unavailable ────▶ sent     (retry once the action is active again)
 ```