@deepdockai/cli 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.5
+
+- The agent skill's clients: `systems()` is typed as the list of systems the API answers, and a paired `Device` lists its systems as objects, with `outdated` and a `claimedAt` that can be `null`.
+- The TypeScript client runs with plain `node file.ts` (Node 22.18+, or 22.13+ with `--experimental-strip-types`).
+- Both clients take their base URL from `DEEPDOCK_BASE_URL` when it is set, like the CLI.
+- The agent skill holds nothing specific to one system: the recipe for one system is gone, and the skill points to the system's behaviour notes in its OpenAPI document instead.
+
+## 1.0.4
+
+- `DEEPDOCK_CONFIG_DIR` moves the settings file (and only it) to a directory of your choice, on every platform; it must be an absolute path. Useful for keeping separate sign-ins apart, for example one per project or account.
+
 ## 1.0.3
 
 - `auth logout --keep-keys` revokes only the sign-in. On a terminal, plain `auth logout` lists the API keys and asks before revoking them (default: keep); with `--json`, `--yes` or no terminal it still revokes them. `keys create` says so.
@@ -17,7 +28,7 @@
 ## 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: one statement on how to fetch the OpenAPI document, and a recipe for one system 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

package/README.md

@@ -236,12 +236,13 @@ macOS and Linux need nothing special. On Windows:
   revoked, and `data.alreadyRevoked` says so). `auth logout` reports the failure in
   `apiKeysRevoked[].removed` and in `meta.hint`, and clears its local records either way.
 - **Local state** lives in `$XDG_CONFIG_HOME/deepdock/config.json`, else
-  `~/.config/deepdock/config.json` (`%APPDATA%\deepdock\config.json` on Windows), mode 600 in a
-  mode 700 directory. It holds the sign-in, the default organisation, the ids of the keys this
+  `~/.config/deepdock/config.json` (`%APPDATA%\deepdock\config.json` on Windows), or in
+  `$DEEPDOCK_CONFIG_DIR/config.json` when that absolute path is set; mode 600, in a directory the
+  CLI creates mode 700 when it does not exist. It holds the sign-in, the default organisation, the ids of the keys this
   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`, `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
+  `DEEPDOCK_CONFIG_DIR`, `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).
@@ -256,11 +257,33 @@ bun run test:node     # the same tests under Node (needs dist/ from the build)
 bun run format && bun run lint && bun run typecheck && bun run check:public
 ```
 
-`tests/fakeApi.ts` is a local HTTP server answering the routes the CLI uses:
+### Trying a change locally
+
+`bun run dev` runs the CLI from source. Each API gets a settings directory of its own under
+`<config dir>/deepdock-dev/<api host>/`, so a sign-in made against one API never sits next to
+another's; only the CLI's own settings move (`DEEPDOCK_CONFIG_DIR`), nothing else on the machine:
+
+```bash
+bun run dev -- auth status                                      # the production API
+DEEPDOCK_BASE_URL=http://localhost:8787 bun run dev -- auth login --no-wait
+```
+
+The script does not depend on the current directory: from elsewhere, call it by its path
+(`bun /path/to/devkit/scripts/dev.ts ...`), or put the `DEEPDOCK_BASE_URL=... bun .../dev.ts` line
+in a shell alias per API. To run the exact tarball npm would publish, from any directory:
+
+```bash
+bun run pack:try -- auth status      # builds, packs, prints the one-line command to run it
+```
+
+It prints `DEEPDOCK_BASE_URL=... DEEPDOCK_CONFIG_DIR=... npx -y --package=/path/to/deepdockai-cli-<version>.tgz deepdock auth status`,
+for the same API and settings directory `bun run dev` would use (`npx <tarball>` alone would try
+to execute the archive). `tests/fakeApi.ts` is a local stand-in that approves every request at
+once:
 
 ```bash
 bun scripts/fakeServer.ts &              # prints its URL
-DEEPDOCK_BASE_URL=http://127.0.0.1:<port> node dist/deepdock.js auth login
+DEEPDOCK_BASE_URL=http://127.0.0.1:<port> bun run dev -- auth login
 ```
 
 ## Licence

package/dist/deepdock.js

@@ -11424,7 +11424,7 @@ import { spawn } from "node:child_process";
 import { homedir, hostname } from "node:os";
 
 // src/version.ts
-var VERSION = "1.0.3";
+var VERSION = "1.0.5";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -11714,17 +11714,21 @@ var renameWithRetry = async (from, to) => {
 // src/config/store.ts
 var PENDING_KEPT_MS = 60 * 60 * 1000;
 var emptyConfig = () => ({ keys: [], pending: [] });
-var configPath = (rt) => {
-  if (rt.platform === "win32") {
-    const base = rt.env.APPDATA ?? join(rt.homedir, "AppData", "Roaming");
-    return join(base, "deepdock", "config.json");
-  }
-  const xdg = rt.env.XDG_CONFIG_HOME;
-  if (xdg && !isAbsolute(xdg)) {
-    throw usageError("XDG_CONFIG_HOME must be an absolute path.", "Unset it or give a full path.");
+var absoluteDir = (env, name) => {
+  const value = env[name];
+  if (value && !isAbsolute(value)) {
+    throw usageError(`${name} must be an absolute path.`, "Unset it or give a full path.");
   }
-  const base = xdg || join(rt.homedir, ".config");
-  return join(base, "deepdock", "config.json");
+  return value || undefined;
+};
+var configBaseDir = (rt) => {
+  if (rt.platform === "win32")
+    return rt.env.APPDATA || join(rt.homedir, "AppData", "Roaming");
+  return absoluteDir(rt.env, "XDG_CONFIG_HOME") ?? join(rt.homedir, ".config");
+};
+var configPath = (rt) => {
+  const own = absoluteDir(rt.env, "DEEPDOCK_CONFIG_DIR");
+  return own ? join(own, "config.json") : join(configBaseDir(rt), "deepdock", "config.json");
 };
 var isRecord3 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var text = (value) => typeof value === "string" ? value : undefined;
@@ -12079,7 +12083,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, FORCE_COLOR.
+  Environment: DEEPDOCK_ORG, DEEPDOCK_BASE_URL, DEEPDOCK_CONFIG_DIR, 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepdockai/cli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Deepdock partner CLI: pair devices, see systems and actions, create the API key your code runs them with.",
   "type": "module",
   "license": "MIT",
@@ -23,6 +23,8 @@
   },
   "scripts": {
     "build": "bun scripts/build.ts",
+    "dev": "bun scripts/dev.ts",
+    "pack:try": "bun scripts/packTry.ts",
     "format": "biome format .",
     "format:fix": "biome format --write .",
     "lint": "biome lint .",

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 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.
+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 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"
 ---
@@ -58,7 +58,8 @@ and what your code does with the result.
    dashboard. The CLI receives the key once, writes `DEEPDOCK_API_KEY=<key>` into that file (it
    must be ignored by git) and keeps no copy. It is displayed to you or to the human by nobody.
    You work only with the key's id, prefix and the file name. Never ask for, read, print or paste
-   a key value.
+   a key value. If the CLI runs with `DEEPDOCK_BASE_URL` set (a non-production API), add the same
+   `DEEPDOCK_BASE_URL=<url>` line to that file ([auth-and-keys.md](references/auth-and-keys.md)).
 6. **Test it.** Run your own code against the demo device the human named, with the key from
    `.env.local`, and read back with the read action. The CLI runs no action. Read
    [references/testing.md](references/testing.md) before any write.
@@ -67,6 +68,9 @@ and what your code does with the result.
 
 ## Rules that are not in the OpenAPI document
 
+- **Read the system's behaviour notes first.** Before the first write, read the system's behaviour
+  notes in its OpenAPI document (each action's `description`): what it needs (an author, an open
+  case), what it accepts and what cannot be undone. Nothing system-specific lives in this skill.
 - **Discover, never hard-code.** Field names, patterns, enums and lengths come from the live OpenAPI
   document (`deepdock systems openapi <system>`, or `GET /v1/systems/{system}/openapi.json` with
   your key), never from memory or from this skill. The document lists Deepdock's whole catalogue for the system; your organisation's assigned

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

@@ -34,6 +34,9 @@ in the dashboard" and stop retrying.
 - Read it from the environment or a secret store (`DEEPDOCK_API_KEY` is the convention the
   dashboard's examples use). Never a literal in source, a test fixture, a log or a URL.
 - One key per deployment is enough; there is no per-device key.
+- A key works only against the API it was created on. The CLI uses production unless
+  `DEEPDOCK_BASE_URL` is set; when it is (`deepdock auth status --json` shows it as `baseUrl`), put
+  the same `DEEPDOCK_BASE_URL=<url>` line next to the key. The bundled clients read it too.
 - Getting a key into the app is the CLI's job: `deepdock keys create <name> --expires <d>
   --write-env <file>` opens a link to the dashboard; a human clicks Approve (or Deny); the CLI
   receives the key once and writes `DEEPDOCK_API_KEY=<key>` into the file, which must be ignored

package/skill/references/calling-actions.md

@@ -71,35 +71,14 @@ 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:
+## 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 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.
+- **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`.
 
 ## Timeouts and latency

package/skill/references/cli.md

@@ -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 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` |
+| 3 | retry later (`access_outdated` and `access_missing`: after the customer 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/clients/deepdock.py

@@ -7,6 +7,7 @@ Everything action-specific (paths, fields, methods) comes from the live OpenAPI
 
 from __future__ import annotations
 
+import os
 from dataclasses import dataclass, field, replace
 from typing import Any, Dict, Iterator, List, Optional, Tuple
 from urllib.parse import quote
@@ -43,9 +44,11 @@ class WriteResult:
 
 
 class Deepdock:
-    def __init__(self, api_key: str, base: str = "https://api.deepdock.ai", timeout: float = 30.0,
+    def __init__(self, api_key: str, base: Optional[str] = None, timeout: float = 30.0,
                  client: Optional[httpx.Client] = None):
         # 30 s is above Deepdock's 20 s device wait, so device_offline arrives before a client timeout.
+        # Default: DEEPDOCK_BASE_URL from the environment (the CLI's own variable), else production.
+        base = base or os.environ.get("DEEPDOCK_BASE_URL") or "https://api.deepdock.ai"
         self.c = client or httpx.Client(base_url=base.rstrip("/"), timeout=timeout)
         self.c.headers["Authorization"] = f"Bearer {api_key}"
 
@@ -98,7 +101,7 @@ class Deepdock:
                                    headers={"Idempotency-Key": idempotency_key})
         return WriteResult(data=data, replayed=headers.get("Idempotent-Replayed") == "true")
 
-    def systems(self, device_id: str) -> Dict[str, Any]:
+    def systems(self, device_id: str) -> List[Dict[str, Any]]:
         """The device's systems and each action's state. A live call: can answer device_offline."""
         data, _ = self._send("GET", f"/v1/devices/{quote(device_id, safe='')}/systems")
         return data

package/skill/references/clients/deepdock.ts

@@ -6,16 +6,21 @@
  * Everything action-specific (paths, fields, methods) comes from the live OpenAPI document.
  */
 
+// Plain fields, no constructor parameter properties: Node runs this file with its default type
+// stripping, which refuses syntax that needs a transform.
 export class DeepdockError extends Error {
-  constructor(
-    readonly status: number,
-    readonly code: string,
-    message: string,
-    readonly requestId?: string,
-    readonly systems?: string[],
-  ) {
+  readonly status: number
+  readonly code: string
+  readonly requestId?: string
+  readonly systems?: string[]
+
+  constructor(status: number, code: string, message: string, requestId?: string, systems?: string[]) {
     super(message)
     this.name = 'DeepdockError'
+    this.status = status
+    this.code = code
+    this.requestId = requestId
+    this.systems = systems
   }
 }
 
@@ -34,6 +39,10 @@ export type Page<Item> = { items: Item[]; nextCursor: string | null }
 export type WriteResult<T> = { data: T; replayed: boolean }
 export type WriteMethod = 'POST' | 'PATCH'
 
+export type SystemStatus = 'running' | 'stopped' | 'missing' | 'unknown'
+/** The database access the device last reported; `null` while none is known. */
+export type SystemAccess = 'ok' | 'outdated' | 'missing' | 'not_set_up' | null
+
 export type Device = {
   id: string
   label: string | null
@@ -42,38 +51,55 @@ export type Device = {
   clientVersion: string
   status: 'connected' | 'offline' | 'inactive'
   lastSeenAt: string | null
-  claimedAt: string
-  systems: string[]
+  claimedAt: string | null
+  /** True when an action assigned to you needs a newer client: that action answers device_outdated. */
+  outdated: boolean
   updateAvailable?: string
+  systems: { system: string; version: string | null; status: SystemStatus; access: SystemAccess; reportedAt: string }[]
 }
 
 export type ActionState =
-  | { state: 'active' }
-  | { state: 'paused'; reason: string; pausedAt: string }
+  | { action: string; state: 'active' }
+  | { action: string; state: 'paused'; reason: 'structure_changed' | 'check_failed'; pausedAt: string }
 
 export type DeviceSystem = {
+  system: string
   label: string | null
-  version: string
-  status: 'running' | 'stopped' | 'missing'
-  actions: Record<string, ActionState>
+  version?: string
+  status: SystemStatus
+  access: SystemAccess
+  actions: ActionState[]
 }
 
 export type DeepdockOptions = {
+  /** Default: `DEEPDOCK_BASE_URL` from the environment (the CLI's own variable), else production. */
   base?: string
   /** Above Deepdock's 20 s device wait, so you receive device_offline instead of timing out first. */
   timeoutMs?: number
   fetch?: typeof fetch
 }
 
+// `process` is absent in a browser, and Deno throws on `process.env` without --allow-env; then the
+// base comes from the options or is production.
+const envBase = (): string | undefined => {
+  try {
+    return process.env.DEEPDOCK_BASE_URL || undefined
+  } catch {
+    return undefined
+  }
+}
+
 export class Deepdock {
+  private readonly apiKey: string
   private readonly base: string
   private readonly timeoutMs: number
   private readonly fetchImpl: typeof fetch
 
   constructor(
-    private readonly apiKey: string,
-    { base = 'https://api.deepdock.ai', timeoutMs = 30_000, fetch: fetchImpl = fetch }: DeepdockOptions = {},
+    apiKey: string,
+    { base = envBase() ?? 'https://api.deepdock.ai', timeoutMs = 30_000, fetch: fetchImpl = fetch }: DeepdockOptions = {},
   ) {
+    this.apiKey = apiKey
     this.base = base.replace(/\/$/, '')
     this.timeoutMs = timeoutMs
     this.fetchImpl = fetchImpl
@@ -167,8 +193,8 @@ export class Deepdock {
   }
 
   /** The device's systems and each action's state. A live call to the device: can answer device_offline. */
-  async systems(deviceId: string): Promise<Record<string, DeviceSystem>> {
-    return (await this.send<Record<string, DeviceSystem>>(`/v1/devices/${encodeURIComponent(deviceId)}/systems`, { method: 'GET' })).data
+  async systems(deviceId: string): Promise<DeviceSystem[]> {
+    return (await this.send<DeviceSystem[]>(`/v1/devices/${encodeURIComponent(deviceId)}/systems`, { method: 'GET' })).data
   }
 
   /** Claims a device by the pairing code it shows. Keep the returned `id`. */

package/skill/references/concepts.md

@@ -24,7 +24,8 @@ Details: [auth-and-keys.md](auth-and-keys.md).
 The Deepdock client installed on the customer's Windows PC next to their system. It connects
 outwards to Deepdock; nothing in the customer's network is opened to the internet. A device is
 identified by a UUID (`id`), carries a `label`, `hostname`, `os`, `clientVersion`, `status`
-(`connected`, `offline` or `inactive`), `lastSeenAt`, `claimedAt` and the `systems` it reported.
+(`connected`, `offline` or `inactive`), `lastSeenAt`, `claimedAt` (may be `null`), `outdated` (an
+assigned action needs a newer client: it answers `device_outdated`) and the `systems` it reported.
 
 - **Pair**: claim a device for your organisation with the 6-character code it shows while unpaired.
 - **Release**: `DELETE /v1/devices/{deviceId}` gives the device back; it shows a new code.
@@ -36,7 +37,7 @@ identified by a UUID (`id`), carries a `label`, `hostname`, `os`, `clientVersion
 ## System
 
 A program on the device that Deepdock has made reachable, named by a slug such as `example-erp`. Each
-has a display `label` (may be `null`), a `version` the device reported, a `status`, and actions.
+has a display `label` (may be `null`), a `version` the device reported (may be absent), a `status`, and actions.
 `GET /v1/devices/{deviceId}/systems` is a live call to the device, so it can answer
 `device_offline`.
 
@@ -51,7 +52,7 @@ has a display `label` (may be `null`), a `version` the device reported, a `statu
 | 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 |
+| 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 customer 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 |

package/skill/references/discovery.md

@@ -67,8 +67,9 @@ action exists before offering it in your UI, or to validate input client-side be
 curl "$BASE/v1/devices/$DEVICE/systems" -H "Authorization: Bearer $DEEPDOCK_API_KEY"
 ```
 
-A live call to the device. Each system: `label`, `version`, `status`, and per action `active` or
-`paused` with `reason` and `pausedAt`. Answers `503 device_offline` when the device is not
+A live call to the device. A list; each entry has `system`, `label`, `version` (may be absent),
+`status`, `access` and `actions`, each with `action` and `state` (`active`, or `paused` with
+`reason` and `pausedAt`). Answers `503 device_offline` when the device is not
 connected: that is a normal state, not an error in your code. Do not poll it tightly; it reaches the
 customer's PC.
 

package/skill/references/errors.md

@@ -31,7 +31,7 @@ dashboard-only.
 | `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_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 customer repeats "Erneut einrichten" in the Deepdock client; then yes, a write with the same key | "the customer 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" |
@@ -42,10 +42,10 @@ dashboard-only.
 |---|---|---|---|---|
 | `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 |
-| `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" |
+| `unknown_author` | 422 | the write names an `authorUserId` the system does not list (read them with the users read the description names). 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 the providers read the description names and pass one of their ids | "choose a provider" |
+| `no_open_case` | 422 | the customer 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 customer's 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 customer's 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 |
 
@@ -107,7 +107,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 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
+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
 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

@@ -20,7 +20,7 @@ Copy the file into the project; do not reach into the skill directory at runtime
 ```ts
 import { Deepdock, DeepdockError, DeepdockTransportError, attempt, type PendingWrite } from './deepdock'
 
-const dd = new Deepdock(process.env.DEEPDOCK_API_KEY!)          // 30 s timeout by default
+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)
@@ -109,7 +109,7 @@ export const run = async (store: { save: (row: PendingWrite) => Promise<void> })
 ## curl, for any other language
 
 ```bash
-BASE=https://api.deepdock.ai
+BASE=${DEEPDOCK_BASE_URL:-https://api.deepdock.ai}
 AUTH="Authorization: Bearer $DEEPDOCK_API_KEY"
 
 # Pair a device (keep data.id)