@deepdockai/cli 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.0.2
+
+- The install commands no longer pin a major version: `npx @deepdockai/cli auth login`, `npm install -g @deepdockai/cli`.
+
+## 1.0.1
+
+- The agent skill: page with `nextCursor` until it is `null` (a short page can carry a cursor), and cover the codes `access_outdated`, `access_missing`, `record_locked`, `record_not_editable`, `unknown_provider`, `payload_too_large` and the system status `unknown`, in the skill and the CLI's exit-code table.
+- The agent skill: one statement on how to fetch the OpenAPI document, and a MEDICAL OFFICE recipe with its action names.
+- The agent skill states the id rule in full: reads and creates answer ids as integers, a create's new id included; every id you send is a string of digits without a leading zero, at most 10 characters, in a query string and a write body alike.
+
 ## 1.0.0
 
 First release of `@deepdockai/cli`, the `deepdock` command.

package/README.md

@@ -10,14 +10,14 @@ This repository holds the partner CLI, published as [`@deepdockai/cli`](https://
 with the command `deepdock`, and the skill it installs for coding agents.
 
 ```bash
-npx @deepdockai/cli@1 auth login
+npx @deepdockai/cli auth login
 ```
 
 The CLI manages: your organisations, the devices paired to them, and your API keys, and it lists
 the systems and actions a device offers. It never runs an action and never keeps or uses an API
 key. Actions run from your own code with a key the CLI wrote into your env file.
 
-Node 22.13 or newer. Installed globally (`npm install -g @deepdockai/cli@1`) the command is
+Node 22.13 or newer. Installed globally (`npm install -g @deepdockai/cli`) the command is
 `deepdock`; the examples below use that form.
 
 ## Before you start
@@ -94,7 +94,7 @@ deepdock skill
 | `auth logout`                                         | revoke the sign-in and every key this CLI created                                                                                                                       |
 | `org list`, `org select [slug]`                       | your organisations; set the default one                                                                                                                                 |
 | `systems list`                                        | the systems and actions assigned to your organisation                                                                                                                   |
-| `systems openapi <system>`                            | a system's OpenAPI document on stdout; redirect it to a file                                                                                                            |
+| `systems openapi <system>`                            | a system's OpenAPI document on stdout, bare when redirected; save it to a file                                                                                          |
 | `devices list`                                        | paired devices with id, label, status, systems and last seen                                                                                                            |
 | `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)                                                                                                                |
@@ -144,7 +144,9 @@ On a terminal you get tables and plain sentences. When stdout is not a terminal,
 }
 ```
 
-For list and show commands `data` is the API's answer unchanged, so what the CLI shows is what
+`systems openapi` is the one exception off a terminal: it prints the OpenAPI document itself, so
+`deepdock systems openapi <system> > openapi.json` saves a document a generator can read (`--json`
+gives the envelope). For list and show commands `data` is the API's answer unchanged, so what the CLI shows is what
 your code will receive; `auth`, `org select` and `keys create` build it from named fields. A
 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`.
@@ -235,7 +237,7 @@ macOS and Linux need nothing special. On Windows:
   CLI created (never their values) and a pending approval request. A file other users can read
   is refused with the `chmod` to run.
 - **Environment:** `DEEPDOCK_ORG`, `DEEPDOCK_BASE_URL` (https, or http for localhost only),
-  `NO_COLOR`. A sign-in or pending request is never sent to a different base URL than the one it
+  `NO_COLOR`, `FORCE_COLOR` (colours messages on a stream that is not a terminal; `NO_COLOR` wins). A sign-in or pending request is never sent to a different base URL than the one it
   was made against.
 
 Report a vulnerability by email to torben@deepdock.ai, not in a public issue: [SECURITY.md](SECURITY.md).
@@ -260,3 +262,11 @@ DEEPDOCK_BASE_URL=http://127.0.0.1:<port> node dist/deepdock.js auth login
 ## Licence
 
 [MIT](LICENSE).
+
+## Releases
+
+Publishing is automatic once a change is merged; nobody runs `npm publish`. To ship a change, bump `version` in `package.json` and add a matching
+`## <version>` entry to `CHANGELOG.md` in your pull request. A check on the pull request requires
+the bump whenever a published file changes. When the pull request merges to `main`, the release
+workflow tests the code, scans the exact tarball, publishes it to npm with provenance, then tags
+`v<version>` and creates a GitHub Release with the changelog entry as notes.

package/dist/deepdock.js

@@ -10864,10 +10864,17 @@ var EXIT_CODES = {
   check_failed: 2,
   idempotency_conflict: 2,
   conflict: 2,
+  already_member: 2,
   no_open_case: 2,
   unknown_author: 2,
+  unknown_provider: 2,
+  record_locked: 2,
+  record_not_editable: 2,
+  payload_too_large: 2,
   device_offline: 3,
   action_paused: 3,
+  access_outdated: 3,
+  access_missing: 3,
   system_unavailable: 3,
   target_busy: 3,
   temporarily_unavailable: 3,
@@ -10999,6 +11006,7 @@ var DEVICE_SYSTEM_COLUMNS = [
   "systems",
   "system",
   "name",
+  "action",
   "version",
   "status",
   "state",
@@ -11035,12 +11043,37 @@ var scalar = (value) => {
     return String(value);
   return "";
 };
+var GOOD = new Set(["connected", "active", "running", "ok"]);
+var WARN = new Set(["offline", "paused", "outdated", "unavailable", "degraded"]);
+var BAD = new Set(["revoked", "failed", "denied", "expired"]);
+var cellFor = (key, value) => {
+  const text = scalar(value);
+  if (text === "")
+    return text;
+  if (key === "reason" || key === "pausedReason")
+    return words(text);
+  if (key === "revokedAt")
+    return { text, style: "red" };
+  if (key === "name" || key === "action")
+    return { text, style: "bold" };
+  if (key.endsWith("At") || key === "since")
+    return { text, style: "dim" };
+  if (key === "status" || key === "state") {
+    if (GOOD.has(text))
+      return { text, style: "green" };
+    if (WARN.has(text))
+      return { text, style: "yellow" };
+    if (BAD.has(text))
+      return { text, style: "red" };
+  }
+  return text;
+};
 var genericTable = (items, style, allow) => {
   const records = items.filter(isRecord);
   const shown = allow.filter((key) => records.some((record) => (key in record) && isScalar(record[key])));
   if (shown.length === 0)
     return NOTHING_TO_SHOW;
-  return renderTable(shown.map(columnTitle), records.map((record) => shown.map((key) => scalar(record[key]))), style);
+  return renderTable(shown.map(columnTitle), records.map((record) => shown.map((key) => cellFor(key, record[key]))), style);
 };
 var relativeTime = (iso, now) => {
   if (typeof iso !== "string")
@@ -11084,10 +11117,10 @@ var deviceTable = (devices, now, style) => {
     return genericTable(records, style, DEVICE_COLUMNS);
   return renderTable(["ID", "LABEL", "STATUS", "SYSTEMS", "LAST SEEN"], records.map((device) => [
     field(device, "id"),
-    field(device, "label"),
+    { text: field(device, "label"), style: "bold" },
     deviceStatusCell(field(device, "status")),
     systemsLabel(device),
-    relativeTime(device.lastSeenAt, now)
+    { text: relativeTime(device.lastSeenAt, now), style: "dim" }
   ]), style);
 };
 var isScalar = (value) => value === null || ["string", "number", "boolean"].includes(typeof value);
@@ -11151,6 +11184,32 @@ var countValue = (data, word) => {
     return Object.values(data).reduce((sum, item) => sum + countValue(item, word), 0);
   return 0;
 };
+var roleLabel = (role) => {
+  const bare = role.replace(/^org:/, "").replace(/[_-]+/g, " ");
+  return bare === "" ? role : bare.charAt(0).toUpperCase() + bare.slice(1);
+};
+var orgTable = (orgs, defaultSlug, style) => {
+  const isDefault = (org) => org.slug !== null && org.slug === defaultSlug;
+  const ordered = [...orgs].sort((a, b) => Number(isDefault(b)) - Number(isDefault(a)));
+  return renderTable(["NAME", "SLUG", "ROLE", ""], ordered.map((org) => [
+    { text: org.name, style: "bold" },
+    { text: org.slug ?? "(no slug)", style: "dim" },
+    roleLabel(org.role),
+    isDefault(org) ? { text: "default", style: "green" } : ""
+  ]), style);
+};
+var words = (code) => code.replace(/_/g, " ");
+var systemsTable = (items, style) => {
+  const records = items.filter(isRecord);
+  if (!records.some((item) => ("system" in item)))
+    return genericTable(records, style, SYSTEM_COLUMNS);
+  return renderTable(["SYSTEM", "NAME", "ACTIONS"], records.map((item) => {
+    const actions = Array.isArray(item.actions) ? item.actions.filter(isRecord) : undefined;
+    const writes = actions?.filter((action) => action.kind === "write").length ?? 0;
+    const counted = actions ? `${actions.length} (${actions.length - writes} read, ${writes} write)` : "";
+    return [{ text: field(item, "system"), style: "bold" }, field(item, "label"), counted];
+  }), style);
+};
 
 // src/commands/actions.ts
 var fieldNames = (input) => {
@@ -11159,14 +11218,25 @@ var fieldNames = (input) => {
   const required = Array.isArray(input.required) ? input.required : [];
   return Object.keys(input.properties).map((name) => required.includes(name) ? name : `${name} (optional)`).join(", ");
 };
+var summary = (description) => {
+  if (typeof description !== "string")
+    return;
+  const line = description.split(`
+`).find((text) => text.trim() !== "")?.trim() ?? "";
+  const sentence = /^.*?[.!?](?=\s+\p{Lu}|$)/u.exec(line)?.[0] ?? line;
+  const chars = Array.from(sentence);
+  return chars.length > 160 ? `${chars.slice(0, 159).join("").trimEnd()}…` : sentence;
+};
 var actionRow = (action) => {
   const method = typeof action.method === "string" ? action.method : undefined;
   const fields = fieldNames(action.input);
-  const { name, method: _method, input: _input, output: _output, ...rest } = action;
+  const { name, method: _method, input: _input, output: _output, description, ...rest } = action;
+  const brief = summary(description);
   return {
     ...name === undefined ? {} : { name },
     ...method ? { kind: method.toUpperCase() === "GET" ? "read" : "write" } : {},
     ...fields ? { fields } : {},
+    ...brief ? { description: brief } : {},
     ...rest
   };
 };
@@ -11342,7 +11412,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.0.2";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -11831,7 +11901,8 @@ var updateConfig = (rt, change) => withLock(rt, async () => {
 // src/output/styles.ts
 import { styleText } from "node:util";
 var makeStyler = (rt, stream) => {
-  const enabled = stream.isTTY && !rt.env.NO_COLOR && rt.env.TERM !== "dumb";
+  const forced = rt.env.FORCE_COLOR !== undefined && !["", "0"].includes(rt.env.FORCE_COLOR);
+  const enabled = (stream.isTTY || forced) && !rt.env.NO_COLOR && rt.env.TERM !== "dumb";
   return (name, text) => enabled ? styleText(name, text, { validateStream: false }) : text;
 };
 
@@ -11958,7 +12029,7 @@ Examples
 
 More
   Exit codes: \`deepdock help exit-codes\`. API reference per system: \`deepdock systems openapi <system>\`.
-  Environment: DEEPDOCK_ORG, DEEPDOCK_BASE_URL, NO_COLOR.
+  Environment: DEEPDOCK_ORG, DEEPDOCK_BASE_URL, NO_COLOR, FORCE_COLOR.
   Actions run with an API key from your own code, never from this CLI: \`deepdock keys create --help\`.
 `;
 var AUTH_LOGIN_HELP = `Sign in to Deepdock as yourself.
@@ -12340,10 +12411,6 @@ var upsertPending = async (ctx, pending) => {
     ];
   });
 };
-var orgRows = (orgs) => orgs.map((org) => [org.slug ?? "(no slug)", org.name, org.role]);
-var orgTable = (ctx, orgs) => renderTable(["SLUG", "NAME", "ROLE"], orgRows(orgs), ctx.out).split(`
-`).map((line) => `  ${line}`).join(`
-`);
 var finishLogin = async (ctx, pending) => {
   const { answer, requestId } = await pollUntilApproved(ctx.rt, ctx.api, "loginPoll", {
     kind: "login",
@@ -12380,7 +12447,7 @@ var finishLogin = async (ctx, pending) => {
   if (answer.organisations.length === 0) {
     lines.push("You are not a member of an organisation yet.");
   } else {
-    lines.push("Your organisations:", orgTable(ctx, answer.organisations), "");
+    lines.push("Your organisations:", indented(orgTable(answer.organisations, config.defaultOrg, ctx.out)), "");
     lines.push("Choose one with `deepdock org select <slug>` or pass --org to each command.");
   }
   return {
@@ -12404,6 +12471,7 @@ var login = async (ctx, options) => {
     }
     assertSameBaseUrl(pending.baseUrl, ctx.baseUrl, "request");
     assertNotExpired(ctx.rt, "login", pending.expiresAt);
+    ctx.note("Waiting for approval in the browser.");
     return finishLogin(ctx, pending);
   }
   const started = await startLogin(ctx.api, ctx.rt);
@@ -12442,6 +12510,9 @@ var keyJson = (ctx, key) => ({
   expiresAt: key.expiresAt,
   written: { file: displayPath(ctx.rt, key.file), name: key.variable }
 });
+var indented = (table) => table.split(`
+`).map((line) => `  ${line}`).join(`
+`);
 var status = async (ctx) => {
   const config = await ctx.config();
   const baseUrl = ctx.baseUrl;
@@ -12472,11 +12543,15 @@ var status = async (ctx) => {
     organisations: signedIn ? config.organisations ?? [] : [],
     apiKeysCreated
   };
+  const defaultOrg = requestedSlug(ctx.opts.org, ctx.rt.env, config);
   const lines = [];
   if (signedIn && config.signIn) {
-    lines.push(`Signed in as ${config.signIn.email} (sign-in valid until ${config.signIn.expiresAt.slice(0, 10)}).`, `  API:           ${baseUrl}`, `  Default org:   ${config.defaultOrg ?? "(none, run `deepdock org select`)"}`);
-    if (data.organisations.length > 0)
-      lines.push("", "Organisations:", orgTable(ctx, data.organisations));
+    lines.push(`Signed in as ${config.signIn.email} (sign-in valid until ${config.signIn.expiresAt.slice(0, 10)}).`);
+    if (baseUrl !== DEFAULT_BASE_URL)
+      lines.push(ctx.out("yellow", `API: ${baseUrl} (not production)`));
+    if (data.organisations.length > 0) {
+      lines.push("", "Organisations:", indented(orgTable(data.organisations, defaultOrg, ctx.out)), "", defaultOrg ? "Switch the default with `deepdock org select <slug>`." : "No default yet: choose one with `deepdock org select <slug>`.");
+    }
   } else {
     lines.push(config.signIn ? "Your sign-in has expired. Run `deepdock auth login`." : "Not signed in. Run `deepdock auth login`.");
   }
@@ -12641,7 +12716,7 @@ var updateNotes = (ctx, devices) => {
     const update = field(device, "updateAvailable");
     if (update) {
       const name = field(device, "label") || field(device, "id");
-      ctx.note(`${stripControl(name)}: update available (client ${stripControl(update)}).`);
+      ctx.note(ctx.err("yellow", `${stripControl(name)}: update available (client ${stripControl(update)}).`));
     }
   }
 };
@@ -12878,6 +12953,7 @@ var create = async (ctx, name, options) => {
     if (!pending) {
       throw usageError(`There is no pending key request ${options.wait}.`, "Start one with `deepdock keys create ... --no-wait`.");
     }
+    ctx.note("Waiting for approval in the browser.");
     return finishKey(ctx, pending, false);
   }
   if (name === undefined || name.trim() === "" || name.length > 100 || stripControl(name) !== name) {
@@ -12986,12 +13062,12 @@ var list3 = async (ctx) => {
     current.organisations = orgs;
   });
   const defaultOrg = requestedSlug(ctx.opts.org, ctx.rt.env, config);
-  const text = orgs.length === 0 ? "You are not a member of an organisation yet." : renderTable(["SLUG", "NAME", "ROLE", "DEFAULT"], orgs.map((org) => [
-    org.slug ?? "(no slug)",
-    org.name,
-    org.role,
-    org.slug !== null && org.slug === defaultOrg ? "yes" : ""
-  ]), ctx.out);
+  const text = orgs.length === 0 ? "You are not a member of an organisation yet." : [
+    orgTable(orgs, defaultOrg, ctx.out),
+    "",
+    "Switch the default with `deepdock org select <slug>`."
+  ].join(`
+`);
   return {
     data: response.data,
     meta: response.requestId ? { requestId: response.requestId } : {},
@@ -13018,7 +13094,7 @@ var select = async (ctx, slug) => {
       throw usageError("You are not a member of an organisation yet.");
     ctx.note("Which organisation should be the default?");
     choices.forEach((org, index) => {
-      ctx.note(`  ${index + 1}  ${org.slug.padEnd(18)} ${org.name.padEnd(24)} ${org.role}`);
+      ctx.note(stripControl(`  ${index + 1}  ${org.slug.padEnd(18)} ${org.name.padEnd(24)} ${roleLabel(org.role)}`));
     });
     const current = Math.max(1, choices.findIndex((org) => org.slug === config.defaultOrg) + 1);
     const index = await pickIndex(ctx.rt, choices.length, current);
@@ -13171,10 +13247,10 @@ var registerSystems = (program, run) => {
   systems.command("list").description("List the systems assigned to the organisation").action((_options, cmd) => run(cmd, async (ctx) => {
     const response = await ctx.callInOrg({ method: "GET", path: "/partner/systems" });
     const items = Array.isArray(response.data) ? response.data : [];
-    const text = items.length === 0 ? "No systems are assigned to this organisation." : genericTable(items, ctx.out, SYSTEM_COLUMNS);
+    const text = items.length === 0 ? "No systems are assigned to this organisation." : systemsTable(items, ctx.out);
     return { data: response.data, meta: { requestId: response.requestId }, text };
   }));
-  systems.command("openapi").description("Print a system's OpenAPI document (redirect to keep it)").argument("<system>", "the system name").action((system, _options, cmd) => run(cmd, async (ctx) => {
+  systems.command("openapi").description("Print a system's OpenAPI document (the document itself when redirected)").argument("<system>", "the system name").action((system, _options, cmd) => run(cmd, async (ctx) => {
     const name = systemArg(system);
     const response = await ctx.callInOrg({
       method: "GET",
@@ -13184,7 +13260,8 @@ var registerSystems = (program, run) => {
     return {
       data: response.data,
       meta: { requestId: response.requestId },
-      text: JSON.stringify(document, null, 2)
+      text: JSON.stringify(document, null, 2),
+      bare: true
     };
   }));
 };
@@ -13278,7 +13355,10 @@ var buildProgram = (rt, state) => {
     const meta = { ...ctx.org ? { org: ctx.org } : {}, ...result.meta };
     if (meta.requestId === undefined)
       delete meta.requestId;
-    if (ctx.json)
+    if (ctx.json && result.bare && !ctx.opts.json)
+      rt.stdout.write(`${result.text}
+`);
+    else if (ctx.json)
       rt.stdout.write(toLine(successDoc(result.data, meta)));
     else
       rt.stdout.write(`${result.text}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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

@@ -1,6 +1,6 @@
 ---
 name: deepdock-integration
-description: Build, debug or test an integration with Deepdock's partner API, the REST actions under /v1 that read and write records in a customer's on-premise business system (for example Example ERP) through a paired Deepdock device. Use when code calls api.deepdock.ai, handles ddk_ API keys, pairs a device by code, calls a system action, handles error codes such as device_offline, action_paused, idempotency_conflict or outcome_unknown, or runs the deepdock CLI.
+description: Build, debug or test an integration with Deepdock's partner API, the REST actions under /v1 that read and write records in a customer's on-premise business system (for example MEDICAL OFFICE) through a paired Deepdock device. Use when code calls api.deepdock.ai, handles ddk_ API keys, pairs a device by code, calls a system action, handles error codes such as device_offline, action_paused, idempotency_conflict or outcome_unknown, or runs the deepdock CLI.
 metadata:
   cli: "@deepdockai/cli"
 ---
@@ -27,7 +27,7 @@ integration against a demo device. It is not for building or changing actions: D
 5. Every write needs an `Idempotency-Key`: a new key per intended write, the same key on every retry,
    and a repeat answers the stored result with `Idempotent-Replayed: true`, writing nothing twice.
 6. A write either fully applies or not: Deepdock checks its result before confirming, and a write
-   whose result does not match is undone and the action is paused.
+   whose result does not match is not saved and the action is paused.
 7. A device can be offline and an action can be paused; your code treats both as normal answers.
 8. Every answer is `{ "data": ... }` or `{ "error": { "code", "message" } }`; `code` is the contract,
    `message` is for people.

package/skill/references/calling-actions.md

@@ -19,8 +19,10 @@ curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions/searchCustomers?lastN
 { "data": { "items": [ { "customerId": 1001, "lastName": "Müller", "city": "Beispielstadt" } ], "nextCursor": null } }
 ```
 
-- `nextCursor` is set only when a page came back full; pass it back as `cursor` unchanged. It is
-  opaque: never parse, build or store it beyond the next request.
+- Pass `nextCursor` back as `cursor` unchanged while it is not `null`, and stop only on `null`,
+  never on a short page: a page of long entries (notes) ends before `limit` rows to keep the
+  device's answer under 1 MiB and still carries a cursor. It is opaque: never parse, build or store
+  it beyond the next request.
 - Items are the customer's records. Values can be `null` where the schema says so. Dates and other
   non-numeric values arrive as text in the system's own format (the schema and description say
   which); numbers as JSON numbers.
@@ -69,6 +71,37 @@ of a customer, the note id of an update. The pattern is always the same:
 
 Never invent an id, copy one from another device, or hard-code one from a test run.
 
+## Recipe: MEDICAL OFFICE (`medical-office`)
+
+The examples above use the placeholder system `example-erp`. For a practice running MEDICAL OFFICE
+the same patterns use real actions (the live OpenAPI document is still the authority for fields):
+
+1. `readUsers` lists the users who can author an entry; pass one id as `authorUserId`.
+2. `searchPatients?lastName=...` finds a patient: a prefix match with umlauts spelled out
+   (`Müller` and `Mueller` match, `Muller` does not), answering `patientId`, `lastName`,
+   `firstName`, `birthDate` (`yyyy-mm-dd`, `null` when the system holds no readable date).
+3. `readCases` lists the patient's cases; a write that needs an open case (`createDiagnosis` and
+   the note actions) refuses with `422 no_open_case` when there is none, or takes a `caseId`.
+   `readProviders` lists the providers for `providerId` (`422 unknown_provider` otherwise).
+4. Write with `createDiagnosis` (and the other create actions) under a fresh `Idempotency-Key`,
+   then read back.
+
+Things the schemas show but are 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 `entryId` or `diagnosisId` too); only an update echoes the key you sent, as the
+  string you sent. `patientId: 1001` in a search result goes back as `patientId=1001` in a read's
+  query string and as `"patientId": "1001"` in a write body: digits only, no leading zero, at most
+  10 characters.
+- **Nothing is undone through the API.** No action deletes or reverts a record; a write you
+  regret stays until someone removes it in MEDICAL OFFICE itself. Write only what you mean to keep.
+- **Mark every test text `TEST-DEEPDOCK-<id>`** (a diagnosis text, a note), on the demo device
+  only, and list what you created ([testing.md](testing.md)).
+- Text fields accept MEDICAL OFFICE's Windows-1252 repertoire only; anything else (a tab or line
+  break outside a note) answers `422 invalid_input` before a write. Note actions take a `format` of `text` (default, stored as
+  typed) or `markdown`.
+- A read action's query string treats `+` as a space: send a literal `+` as `%2B`.
+
 ## Timeouts and latency
 
 - Every action call is sent to the customer's PC and run there. Expect a read to take from a few

package/skill/references/cli.md

@@ -81,8 +81,8 @@ 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 |
-| 3 | retry later | `device_offline`, `action_paused`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `connection_lost` |
+| 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 practice repeats "Erneut einrichten" in the Deepdock client) | `device_offline`, `action_paused`, `access_outdated`, `access_missing`, `system_unavailable`, `target_busy`, `temporarily_unavailable`, `internal_error`, `connection_lost` |
 | 4 | the CLI is too old for the API: run `npx @deepdockai/cli@latest` | `client_outdated` |
 | 5 | sign-in needed: run `deepdock auth login` | `sign_in_needed`, `approval_denied`, `approval_expired` |
 

package/skill/references/concepts.md

@@ -50,10 +50,12 @@ has a display `label` (may be `null`), a `version` the device reported, a `statu
 | system `status` | `running` | the customer's program is running on the device | normal |
 | system `status` | `stopped` | the program is installed but not running | calls answer `system_unavailable`; the site starts the program |
 | system `status` | `missing` | the program was not found where the device expects it | calls answer `system_unavailable`; contact the site and Deepdock |
+| system `status` | `unknown` | the device could not tell whether the program runs (its probe failed or is unavailable on that PC) | do not read it as stopped; the device decides when a call arrives |
+| system `access` | `ok`, `outdated`, `missing`, `not_set_up`, or `null` | the database access the device last reported (`null`: none known yet) | `outdated` refuses the actions that need the missing right with `access_outdated`, `missing` refuses every action with `access_missing`; the practice repeats "Erneut einrichten" in the Deepdock client, the incident closes by itself once `access` is `ok`, nothing to resume |
 | action state | `active` | the action can be called | normal |
 | action state | `paused` | the action is paused with a `reason` and `pausedAt` | calls answer `action_paused`; show the feature as paused, poll `GET .../systems` at a low rate |
 | pause `reason` | `structure_changed` | the system changed in a way the action depends on (for example a vendor update); Deepdock reviews and resumes | wait; nothing to do on your side |
-| pause `reason` | `check_failed` | a write's result did not match and was undone | wait; tell the user the change was not saved |
+| pause `reason` | `check_failed` | a write's result did not match, so nothing was saved | wait; tell the user the change was not saved |
 | pause `reason` | `system_stopped`, `system_missing` | as the system statuses above; these need no resume and clear when the system is back | as above |
 
 Switch on these values; any value you do not know is shown as it is.
@@ -69,8 +71,8 @@ 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.
-- A write **either fully applies or not**: Deepdock checks the result before confirming, and undoes
-  the write and pauses the action if the check fails (`409 check_failed`).
+- 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 check_failed`).
 - An action is **active** or **paused**. `GET /v1/devices/{deviceId}/systems` shows each action's
   state with `reason` and `pausedAt`.
 
@@ -82,7 +84,7 @@ the action expects:
 | Reason | What you get | Meaning |
 |---|---|---|
 | `structure_changed` | `503 action_paused` | the system changed (for example a vendor update); Deepdock reviews and resumes |
-| `check_failed` | that call `409 check_failed`, later calls `503 action_paused` | a write's result did not match and was undone |
+| `check_failed` | that call `409 check_failed`, later calls `503 action_paused` | a write's result did not match, so nothing was saved |
 | `system_stopped`, `system_missing` | `503 system_unavailable` | the customer's program is stopped or not found on the device |
 
 Each pause opens an **incident** (`GET /v1/incidents`). Only Deepdock lifts a pause; staff at the

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>` or `deepdock actions list <device> <system>` (or `GET /v1/systems/{system}/openapi.json`) | CLI sign-in or API key |
+| 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 OpenAPI document
 
@@ -17,7 +17,9 @@ deepdock systems openapi example-erp --org <slug> > openapi/example-erp.json
 curl "$BASE/v1/systems/example-erp/openapi.json" -H "Authorization: Bearer $DEEPDOCK_API_KEY"
 ```
 
-OpenAPI 3.1, one document per system, cacheable for 60 seconds. Discover through the CLI; check the
+OpenAPI 3.1, one document per system, cacheable privately for 60 seconds. It is never public:
+`GET /v1/systems/{system}/openapi.json` needs your API key like the rest of `/v1`
+(`401 unauthenticated` without one), and the CLI fetches it with its sign-in instead. Discover through the CLI; check the
 document into the repository and refresh it with the same command when you touch the integration.
 
 What to read off it:

package/skill/references/errors.md

@@ -14,12 +14,14 @@ 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 of strings; 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 |
+| `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 |
 | `not_found` | 404 | no such route; an update whose id matches no record; a write naming a record that does not exist or belongs to another one | no | "record not found" when it is a record; otherwise a bug |
 | `rate_limited` | 429 | too many failed pairing attempts with this key (5 per 60 s) | yes, after up to a minute (`Retry-After` when present) | "try again in a minute" |
 
 Codes your `/v1` code never receives, listed so the enum is complete: `organization_required`
-(403), `forbidden` (403) and `conflict` (409) are dashboard-only.
+(403), `forbidden` (403), `conflict` (409), `already_member` (409) and `client_outdated` (400) are
+dashboard-only.
 
 ## Device, system and action resolution
 
@@ -29,6 +31,8 @@ Codes your `/v1` code never receives, listed so the enum is complete: `organizat
 | `system_not_on_device` | 404 | the device did not report this system and none of its actions are assigned to you; `error.systems` lists what it has | no | configuration problem; show which systems the device has |
 | `action_not_found` | 404 | the system has no such action, it is not assigned to you, or the device's client is too old to run it | no | hide the feature; ask Deepdock for the assignment or let the device update |
 | `action_not_configured` | 409 | the action exists but this device is not set up for it yet (for example a missing device-side setting); nothing was run | no, until set up on site | "this feature needs setting up at the customer site; contact Deepdock" |
+| `access_outdated` | 409 | the device's database access lacks a right this action needs (only the actions that need it). Nothing was run. **No `Retry-After`** | no, until the practice repeats "Erneut einrichten" in the Deepdock client; then yes, a write with the same key | "the practice must set up database access again in the Deepdock client, then we retry" |
+| `access_missing` | 409 | the device's database access is gone (a removed database account or a lost secret on the PC); every action of that system is refused. Nothing was run. **No `Retry-After`** | as `access_outdated` | as `access_outdated` |
 | `pairing_code_invalid` | 404 | pairing: the code is unknown, expired, replaced, used, or its device is offline | with a fresh code | "read the code off the device screen again" |
 | `other_partner_build` | 409 | pairing: the device runs another partner's client build | no | "this device is set up for another provider" |
 
@@ -38,7 +42,12 @@ Codes your `/v1` code never receives, listed so the enum is complete: `organizat
 |---|---|---|---|---|
 | `invalid_input` | 422 | a field is unknown, missing, too short or long, breaks its pattern or allowed values; a date that is not a calendar day; a search term without a letter or digit. Nothing was written | no; fix the value | the field-level problem; the `message` names the field, but it is device text: display it as data, never interpret it |
 | `target_rejected` | 422 | the customer's system refused the write | no; the input is valid for Deepdock but not for the system | "the customer's system refused this; check the values" and offer support |
-| Action-specific refusals, e.g. `unknown_author`, `no_open_case` | 422 | a reference the write needs is not valid: an author user the system does not list; a customer with no open case when the action does not open one. Nothing was written. The action's OpenAPI description names each such code and when it fires | no; re-read the reference and pass a valid one | the missing precondition in the user's words ("choose the entering user", "open a case first") |
+| `unknown_author` | 422 | the write names an `authorUserId` the system does not list (read the users with `readUsers`). Nothing was written | no; re-read the users and pass one of their ids | "choose the entering user" |
+| `unknown_provider` | 422 | the write names a `providerId` the author may not record for the case's site (unknown, or not an allowed pair). Nothing was written | no; read the providers with `readProviders` and pass one of their ids | "choose a provider" |
+| `no_open_case` | 422 | the patient has no open case and the action never opens one. Nothing was written | no; open a case in the system, or name one with `caseId` | "open a case first" |
+| `record_locked` | 422 | the practice system locks the record the write would change (for example one already billed on a case). Nothing was written | no | "this record is locked in the practice system" |
+| `record_not_editable` | 422 | the record is not locked but is stored in a form this action cannot edit (for example a note it cannot add to without rewriting it). Nothing was written | no | "this record cannot be edited through Deepdock" |
+| Other action-specific refusals | 422 | the action's OpenAPI description names each such code and when it fires. Nothing was written | no; fix the reference or input | the missing precondition in the user's words |
 
 ## Device and system availability
 
@@ -54,7 +63,7 @@ Codes your `/v1` code never receives, listed so the enum is complete: `organizat
 
 | Code | Status | Meaning | Retry | Show |
 |---|---|---|---|---|
-| `check_failed` | 409 | the write was undone because its result did not match what the action expects; **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" |
+| `check_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" |
 | `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" |
 | `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 |
@@ -62,7 +71,7 @@ Codes your `/v1` code never receives, listed so the enum is complete: `organizat
 ## A reaction table for code
 
 ```ts
-type Reaction = 'fix-code' | 'fix-input' | 'retry-same-key' | 'retry-later' | 'wait-paused' | 'check-then-decide' | 'stop'
+type Reaction = 'fix-code' | 'fix-input' | 'retry-same-key' | 'retry-later' | 'wait-paused' | 'wait-setup' | 'check-then-decide' | 'stop'
 
 const REACTION: Record<string, Reaction> = {
   invalid_request: 'fix-code',
@@ -79,6 +88,12 @@ const REACTION: Record<string, Reaction> = {
   target_rejected: 'fix-input',
   unknown_author: 'fix-input',
   no_open_case: 'fix-input',
+  unknown_provider: 'fix-input',
+  record_locked: 'stop',
+  record_not_editable: 'stop',
+  payload_too_large: 'fix-code',
+  access_outdated: 'wait-setup',
+  access_missing: 'wait-setup',
   device_offline: 'retry-same-key',
   action_paused: 'wait-paused',
   system_unavailable: 'retry-later',
@@ -92,8 +107,7 @@ const REACTION: Record<string, Reaction> = {
 const reactionFor = (code: string): Reaction => REACTION[code] ?? 'stop'
 ```
 
-Action-specific 422 codes (`unknown_author` and `no_open_case` are two; any the OpenAPI description
-lists) map to `fix-input`. Add them from the document, not from memory. `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 practice 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
 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/idempotency.md

@@ -13,7 +13,7 @@ refused with `400 invalid_request`.
 - Keys are remembered **per device**. The same key on another device is a different write.
 - A successful key is remembered for at least 7 days.
 - A write that was refused before anything was written (`invalid_input`, `target_rejected`, an
-  action-specific 422 such as `unknown_author`, `not_found`) or undone (`check_failed`) frees its
+  action-specific 422 such as `unknown_author`, `not_found`) or not saved (`check_failed`) frees its
   key: you may retry with the same key. After changing the input, use a new key; the old one may
   still be remembered with the old input. `idempotency_conflict` does **not** free a key.
 
@@ -59,7 +59,7 @@ create, search by the value you wrote; for an update, read the record by id) and
 
 ### `409 check_failed`
 
-The write was undone because its result did not match, and the action is now paused. Do not retry;
+The write's result did not match, so nothing was saved, and the action is now paused. Do not retry;
 the next calls answer `503 action_paused` until Deepdock resumes it. Tell the user the change was not
 saved.
 

package/skill/references/testing.md

@@ -27,7 +27,7 @@ gets written to. These rules are not optional.
 
 ## Cleanup
 
-No action deletes anything. So:
+No action deletes anything, and nothing is undone through the API. So:
 
 1. Every test run prints what it created: record id, device, time, and how many change-log entries
    the updates added. The CLI runs no action, so your own test prints this.