@deepdockai/cli 1.0.0 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 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.
+- `keys create` no longer advises revoking the key "when you ship"; it prints the expiry and how to revoke.
+- With exactly one organisation it is used automatically (and named), and `auth login` selects it. With several and none chosen, `org_required` stays.
+- The approval page opens in your browser on a terminal (not in CI, without a display, with `--no-browser` or `DEEPDOCK_NO_BROWSER=1`). The line says "Opening the approval page in your browser" when it does.
+- `Organisation:` is printed once per command, not again after the wait.
+- Output colours by role: warning and error labels, success verbs, bold organisation and approval prompt, dim waiting line.
+- The approval link is blue and underlined, and clickable in terminals that support links. Plain text when output is piped, under `--json`, or with `NO_COLOR`.
+
+## 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
@@ -30,14 +30,16 @@ holding only invented, marked data. While unpaired, the client shows a pairing c
 
 ## Quick start
 
-Sign in. The CLI prints a link; open it, check that the page names your computer and CLI version,
+Sign in. The CLI prints the link and opens it in your browser (not in CI, without a display, with
+`--no-browser` or `DEEPDOCK_NO_BROWSER=1`). Check that the page names your computer and CLI version,
 and click Approve. No password is typed into the terminal.
 
 ```
 $ deepdock auth login
-Open this link to approve the sign-in (it expires in 10 minutes):
+Opening the approval page in your browser (it expires in 10 minutes):
   https://dash.deepdock.ai/cli?request=rq_...
 The page shows this computer's name and the CLI version: check them before you approve.
+Opened in your browser.
 Waiting for approval in the browser.
 
 Signed in as anna.mueller@muster-it.example.
@@ -91,10 +93,10 @@ deepdock skill
 | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `auth login`                                          | sign in as yourself, approved in the browser; the sign-in lasts 90 days                                                                                                 |
 | `auth status`                                         | who is signed in, the organisations, and the keys this CLI created (id, name, prefix, expiry, file; never the value); exits 5 when not signed in, like `gh auth status` |
-| `auth logout`                                         | revoke the sign-in and every key this CLI created                                                                                                                       |
+| `auth logout [--keep-keys]`                           | revoke the sign-in and every key this CLI created (`--keep-keys`: only the sign-in)                                                                                     |
 | `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)                                                                                                                |
@@ -110,7 +112,8 @@ and `keys revoke` without a question, `-h, --help` everywhere and `-v, --version
 
 Two things are never guessed. A device is always named by its full id: no default device, no
 lookup by label. The organisation comes from `--org`, then `DEEPDOCK_ORG`, then the default
-chosen with `deepdock org select`; with none the command stops and lists your organisations.
+chosen with `deepdock org select`. With exactly one organisation it is used without asking (and
+named on stderr); with several and none chosen the command stops and lists them.
 
 ## The approval flow
 
@@ -144,7 +147,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`.
@@ -220,7 +225,8 @@ macOS and Linux need nothing special. On Windows:
 - **Keys expire and can be revoked.** A key reaches every device of the organisation until it
   expires (at most 90 days from the CLI) or is revoked. `deepdock keys revoke <id>` revokes it and
   removes the line the CLI wrote; `deepdock auth logout` revokes the sign-in and every key this
-  CLI created. In `--json`, `data.removed` says what happened to the line: `null` for a key this
+  CLI created, unless you pass `--keep-keys`. On a terminal it lists the keys and asks first
+  (default: keep); with `--json` or without a terminal it revokes them unless `--keep-keys` is passed. In `--json`, `data.removed` says what happened to the line: `null` for a key this
   CLI never wrote, otherwise `{ file, name, removal }` with `removal` `done`, `absent` (the line
   was already gone or holds another value) or `failed` (with a `reason`). If the file is held open
   by another program (a dev server watching it, on Windows), the key is still revoked and the
@@ -235,7 +241,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 +266,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
   };
 };
@@ -11253,6 +11323,18 @@ var parseAnswer = async (name, value) => {
   return result;
 };
 
+// src/approval/browser.ts
+var isSet = (value) => value !== undefined && !["", "0", "false"].includes(value.toLowerCase());
+var browserAllowed = (rt, noBrowser) => {
+  if (noBrowser || isSet(rt.env.DEEPDOCK_NO_BROWSER) || isSet(rt.env.CI))
+    return false;
+  if (isSet(rt.env.SSH_CONNECTION) && rt.platform !== "linux")
+    return false;
+  if (rt.platform === "linux" && !rt.env.DISPLAY && !rt.env.WAYLAND_DISPLAY)
+    return false;
+  return true;
+};
+
 // src/approval/poll.ts
 var MAX_CONSECUTIVE_FAILURES = 5;
 var EXPIRY_GRACE_MS = 15000;
@@ -11342,7 +11424,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.3";
 
 // src/runtime.ts
 var DEFAULT_BASE_URL = "https://api.deepdock.ai";
@@ -11353,16 +11435,19 @@ var browserCommand = (platform, url) => {
     return { command: "rundll32", args: ["url.dll,FileProtocolHandler", url] };
   return { command: "xdg-open", args: [url] };
 };
-var openInBrowser = (url) => {
+var openInBrowser = (url) => new Promise((resolve) => {
   const { command, args } = browserCommand(process.platform, url);
   try {
     const child = spawn(command, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {
-      return;
+    child.once("error", () => resolve(false));
+    child.once("spawn", () => {
+      child.unref();
+      resolve(true);
     });
-    child.unref();
-  } catch {}
-};
+  } catch {
+    resolve(false);
+  }
+});
 var defaultRuntime = () => {
   const interrupt = new AbortController;
   process.once("SIGINT", () => interrupt.abort());
@@ -11568,6 +11653,9 @@ var requestedSlug = (flag, env, config) => flag || env.DEEPDOCK_ORG || config.de
 var resolveOrg = (requested, orgs, fromStoredDefault = false) => {
   const choices = selectableOrgs(orgs);
   const slugs = choices.map((org) => org.slug);
+  const [only] = choices;
+  if (!requested && only && choices.length === 1)
+    return { ...only, onlyOne: true };
   if (!requested) {
     throw new CliError({
       code: "org_required",
@@ -11677,7 +11765,16 @@ var pickKey = (value) => {
   const { org, id, name, prefix, expiresAt, file, variable } = entry;
   if (!org || !id || !name || !prefix || !expiresAt || !file || !variable)
     return;
-  return { org, id, name, prefix, expiresAt, file, variable };
+  return {
+    org,
+    id,
+    name,
+    prefix,
+    expiresAt,
+    file,
+    variable,
+    ...value.kept === true ? { kept: true } : {}
+  };
 };
 var pickPending = (value) => {
   if (!isRecord3(value))
@@ -11830,10 +11927,29 @@ var updateConfig = (rt, change) => withLock(rt, async () => {
 
 // src/output/styles.ts
 import { styleText } from "node:util";
+var OSC = "\x1B]";
+var ST = "\x1B\\";
+var ROLES = {
+  warn: "yellow",
+  error: "red",
+  success: "green",
+  emphasis: "bold",
+  quiet: "dim",
+  link: "link"
+};
 var makeStyler = (rt, stream) => {
-  const enabled = stream.isTTY && !rt.env.NO_COLOR && rt.env.TERM !== "dumb";
-  return (name, text) => enabled ? styleText(name, text, { validateStream: false }) : text;
+  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) => {
+    if (!enabled)
+      return text;
+    if (name !== "link")
+      return styleText(name, text, { validateStream: false });
+    const styled = styleText(["blue", "underline"], text, { validateStream: false });
+    return `${OSC}8;;${text}${ST}${styled}${OSC}8;;${ST}`;
+  };
 };
+var paint = (style, role, text) => style(ROLES[role], text);
 
 // src/output/terminal.ts
 var isInteractive = (rt, json) => rt.stdin.isTTY && rt.stdout.isTTY && !json;
@@ -11855,6 +11971,7 @@ var createContext = (rt, opts) => {
   const baseUrl = baseUrlFor(rt);
   const api = createApi(rt);
   let loaded;
+  let announcedOrg = false;
   const config = async () => {
     loaded ??= await loadConfig(rt);
     return loaded;
@@ -11875,7 +11992,8 @@ var createContext = (rt, opts) => {
       return loaded;
     },
     note: (line) => {
-      rt.stderr.write(`${line}
+      const warning = "Warning:";
+      rt.stderr.write(`${line.startsWith(warning) ? `${paint(ctx.err, "warn", warning)}${line.slice(warning.length)}` : line}
 `);
     },
     signInSecret: async () => {
@@ -11907,7 +12025,10 @@ var createContext = (rt, opts) => {
       }
       const resolved = resolveOrg(requested, orgs, fromStoredDefault);
       ctx.org = { slug: resolved.slug, name: resolved.name };
-      ctx.note(ctx.err("dim", `Organisation: ${resolved.name} (${resolved.slug})`));
+      if (!announcedOrg) {
+        announcedOrg = true;
+        ctx.note(resolved.onlyOne ? `${paint(ctx.err, "quiet", "Using organisation")} ${paint(ctx.err, "emphasis", resolved.name)} ${paint(ctx.err, "quiet", `(${resolved.slug}).`)}` : `${paint(ctx.err, "quiet", "Organisation:")} ${paint(ctx.err, "emphasis", resolved.name)} ${paint(ctx.err, "quiet", `(${resolved.slug})`)}`);
+      }
       return resolved;
     },
     callInOrg: async (req) => {
@@ -11958,7 +12079,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.
@@ -11973,12 +12094,14 @@ an action; actions run from your code with an API key (\`deepdock keys create\`)
 Usage
   deepdock auth login [flags]
 
-The link is printed either way; opening the browser is a convenience that may fail silently.
+The link is printed either way. On a terminal the CLI also opens it in your browser, unless
+CI is set, there is no display, DEEPDOCK_NO_BROWSER=1 is set or you pass --no-browser.
 
 Flags
   --no-wait           Print the request and exit; finish it later with --wait (the default
                       when there is no terminal)
   --wait <request>    Finish a request started with --no-wait
+  --no-browser        Do not open the link in a browser
 
 Examples
   $ deepdock auth login
@@ -11986,7 +12109,7 @@ Examples
   $ deepdock auth login --wait <request>
 
 More
-  \`deepdock auth status\` shows who is signed in (exit 5 when nobody is). \`deepdock auth logout\` revokes the sign-in.
+  \`deepdock auth status\` shows who is signed in (exit 5 when nobody is). \`deepdock auth logout\` revokes the sign-in and, unless you pass --keep-keys, the API keys this CLI created.
 `;
 var KEYS_CREATE_HELP = `Create an API key for your organisation (admin).
 
@@ -11995,7 +12118,8 @@ key once, writes it into the env file named by --write-env, and keeps no copy. T
 never printed and the CLI never uses it; your code reads it from that file.
 
 A key reaches every device of the organisation until it expires or is revoked. Keep the
-expiry short while you build, and revoke it when you ship: \`deepdock keys revoke <id>\`.
+expiry short, and revoke a key you no longer need: \`deepdock keys revoke <id>\`. \`deepdock auth logout\`
+revokes the keys this CLI created unless you pass --keep-keys.
 
 Usage
   deepdock keys create <name> --expires <duration> --write-env <file> [flags]
@@ -12010,6 +12134,7 @@ Flags
                         the CLI warns
   --no-wait             Print the request and exit; finish it with --wait
   --wait <request>      Finish a request started with --no-wait
+  --no-browser          Do not open the link in a browser (also DEEPDOCK_NO_BROWSER=1)
 
 Examples
   $ deepdock keys create "myapp dev" --expires 30d --write-env .env.local
@@ -12082,6 +12207,34 @@ var formatHelp = (command) => {
 `;
 };
 
+// src/output/confirm.ts
+import { createInterface } from "node:readline";
+var ask = (rt, prompt) => new Promise((resolve) => {
+  const rl = createInterface({ input: rt.stdin.stream, output: undefined, terminal: false });
+  rt.stderr.write(prompt);
+  let settled = false;
+  rl.once("line", (line) => {
+    settled = true;
+    rl.close();
+    resolve(line.trim());
+  });
+  rl.once("close", () => {
+    if (!settled)
+      resolve("");
+  });
+});
+var confirm = async (rt, question) => {
+  const answer = await ask(rt, `${question} [y/N]: `);
+  return /^y(es)?$/i.test(answer);
+};
+var pickIndex = async (rt, count, defaultIndex) => {
+  const answer = await ask(rt, `Number [${defaultIndex}]: `);
+  const chosen = answer === "" ? defaultIndex : Number.parseInt(answer, 10);
+  if (!Number.isInteger(chosen) || chosen < 1 || chosen > count)
+    return;
+  return chosen;
+};
+
 // src/writeEnv/ledger.ts
 import { relative, sep } from "node:path";
 var addKey = (config, entry) => {
@@ -12322,11 +12475,19 @@ var settleWrittenLine = async (ctx, entry, keepEntryOnFailure) => {
 
 // src/commands/auth.ts
 var minutesLeft = (ctx, expiresAt) => Math.max(1, Math.ceil((Date.parse(expiresAt) - ctx.rt.now().getTime()) / 60000));
-var announceApproval = (ctx, what, url, expiresAt, extra) => {
-  ctx.note(`Open this link to approve ${what} (it expires in ${minutesLeft(ctx, expiresAt)} minutes):`);
-  ctx.note(`  ${url}`);
-  ctx.note(extra ?? "The page shows this computer's name and the CLI version: check them before you approve.");
-  ctx.note("Waiting for approval in the browser.");
+var noteWaiting = (ctx) => {
+  ctx.note(paint(ctx.err, "quiet", "Waiting for approval in the browser."));
+};
+var announceApproval = async (ctx, what, url, expiresAt, options) => {
+  const open = browserAllowed(ctx.rt, options.noBrowser);
+  const minutes = minutesLeft(ctx, expiresAt);
+  ctx.note(open ? `Opening the approval page in your browser (it expires in ${minutes} minutes):` : `Open this link to approve ${what} (it expires in ${minutes} minutes):`);
+  ctx.note(`  ${ctx.err("link", url)}`);
+  ctx.note(options.extra ?? "The page shows this computer's name and the CLI version: check them before you approve.");
+  if (open) {
+    ctx.note(await ctx.rt.openBrowser(url) ? "Opened in your browser." : "Could not open a browser; use the link above.");
+  }
+  noteWaiting(ctx);
 };
 var pendingResult = (pending, url, text) => ({
   data: { pending: { request: pending.request, url, expiresAt: pending.expiresAt } },
@@ -12340,10 +12501,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",
@@ -12374,14 +12531,22 @@ var finishLogin = async (ctx, pending) => {
     current.organisations = answer.organisations;
     if (current.defaultOrg && !slugs.includes(current.defaultOrg))
       current.defaultOrg = undefined;
+    if (!current.defaultOrg && slugs.length === 1)
+      current.defaultOrg = slugs[0];
     current.pending = current.pending.filter((entry) => entry.request !== pending.request);
   });
-  const lines = [`Signed in as ${answer.user.email}.`, ""];
+  const lines = [`${paint(ctx.out, "success", "Signed in")} as ${answer.user.email}.`, ""];
   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("Choose one with `deepdock org select <slug>` or pass --org to each command.");
+    lines.push("Your organisations:", indented(orgTable(answer.organisations, config.defaultOrg, ctx.out)), "");
+    const only = selectableOrgs(answer.organisations);
+    const [sole] = only;
+    if (sole && only.length === 1 && config.defaultOrg === sole.slug) {
+      lines.push(`${paint(ctx.out, "success", "Selected")} ${sole.name} (${sole.slug}) as your organisation.`);
+    } else {
+      lines.push("Choose one with `deepdock org select <slug>` or pass --org to each command.");
+    }
   }
   return {
     data: {
@@ -12404,6 +12569,7 @@ var login = async (ctx, options) => {
     }
     assertSameBaseUrl(pending.baseUrl, ctx.baseUrl, "request");
     assertNotExpired(ctx.rt, "login", pending.expiresAt);
+    noteWaiting(ctx);
     return finishLogin(ctx, pending);
   }
   const started = await startLogin(ctx.api, ctx.rt);
@@ -12417,13 +12583,14 @@ var login = async (ctx, options) => {
   await upsertPending(ctx, pending);
   if (options.wait === false || !ctx.interactive) {
     return pendingResult(pending, started.url, [
-      `Open this link to approve the sign-in: ${started.url}`,
+      `Open this link to approve the sign-in: ${ctx.out("link", started.url)}`,
       `Then run \`deepdock auth login --wait ${started.request}\`.`
     ].join(`
 `));
   }
-  announceApproval(ctx, "the sign-in", started.url, started.expiresAt);
-  ctx.rt.openBrowser(started.url);
+  await announceApproval(ctx, "the sign-in", started.url, started.expiresAt, {
+    noBrowser: options.browser === false
+  });
   return finishLogin(ctx, pending);
 };
 var keyRows = (ctx, keys) => keys.map((key) => [
@@ -12442,6 +12609,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 +12642,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`.");
   }
@@ -12527,7 +12701,19 @@ var revokeSignInById = async (ctx, id) => {
       throw error;
   }
 };
-var logout = async (ctx) => {
+var keyLabel = (key) => `"${key.name}" (${key.id})`;
+var wantsKeysKept = async (ctx, keys, options) => {
+  if (options.keepKeys)
+    return true;
+  if (keys.length === 0 || ctx.opts.yes || !ctx.interactive)
+    return false;
+  ctx.note(`Logging out revokes the API keys this CLI created (${keys.length}):`);
+  for (const key of keys)
+    ctx.note(`  ${key.org}   ${keyLabel(key)}   ${key.prefix}…`);
+  ctx.note("Programs using them stop working. Answer N to keep them active.");
+  return !await confirm(ctx.rt, `Revoke ${keys.length === 1 ? "this key" : `these ${keys.length} keys`} too?`);
+};
+var logout = async (ctx, options) => {
   const config = await ctx.config();
   const signIn = config.signIn;
   const email = signIn?.email ?? null;
@@ -12535,8 +12721,10 @@ var logout = async (ctx) => {
   const revokedKeys = [];
   const failedKeys = [];
   let signInRevoked = false;
+  const candidates = config.keys.filter((entry) => !entry.kept);
+  const keepKeys = usable ? await wantsKeysKept(ctx, candidates, options) : Boolean(options.keepKeys);
   if (usable) {
-    for (const entry of [...config.keys]) {
+    for (const entry of keepKeys ? [] : candidates) {
       const outcome = await revokeRecordedKey(ctx, entry);
       if ("error" in outcome)
         failedKeys.push(outcome);
@@ -12548,7 +12736,7 @@ var logout = async (ctx) => {
       signInRevoked = true;
     }
   } else {
-    for (const entry of config.keys) {
+    for (const entry of keepKeys ? [] : candidates) {
       failedKeys.push({
         ...factsOf(entry),
         error: { code: "sign_in_needed", message: "Your sign-in is missing or expired." }
@@ -12560,27 +12748,40 @@ var logout = async (ctx) => {
     current.defaultOrg = undefined;
     current.organisations = undefined;
     current.pending = [];
+    if (keepKeys) {
+      for (const entry of current.keys)
+        entry.kept = true;
+    }
   });
+  const signedOut = paint(ctx.out, "success", "Signed out");
+  const keptKeys = (await ctx.config()).keys.filter((entry) => entry.kept).map((entry) => ({
+    ...factsOf(entry),
+    written: { file: displayPath(ctx.rt, entry.file), name: entry.variable }
+  }));
   const lines = [];
   if (!email)
     lines.push("Not signed in.");
   else if (signInRevoked)
-    lines.push(`Signed out ${email}. The sign-in is revoked.`);
+    lines.push(`${signedOut} ${email}. The sign-in is revoked.`);
   else if (usable) {
-    lines.push(`Signed out ${email}. The stored sign-in has no id (the settings file is damaged), so it was only removed from this computer; revoke it in the Deepdock dashboard.`);
+    lines.push(`${signedOut} ${email}. The stored sign-in has no id (the settings file is damaged), so it was only removed from this computer; revoke it in the Deepdock dashboard.`);
   } else {
-    lines.push(`Signed out ${email}. The sign-in was only removed from this computer; revoke it in the Deepdock dashboard.`);
+    lines.push(`${signedOut} ${email}. The sign-in was only removed from this computer; revoke it in the Deepdock dashboard.`);
   }
   if (revokedKeys.length > 0) {
-    lines.push("Revoked the API keys this CLI created:");
+    lines.push(`${paint(ctx.out, "success", "Revoked")} the API keys this CLI created:`);
     for (const key of revokedKeys) {
       const where = key.removed.removal === "done" ? `   ${describeRemoval(key.removed)}` : "";
       lines.push(`  ${key.org}   "${key.name}"   ${key.prefix}…   ${key.id}${where}`);
     }
     lines.push("Programs still using one of them stop working now.");
   }
+  if (keptKeys.length > 0) {
+    lines.push(`${paint(ctx.out, "success", "Kept")} ${keptKeys.length} API ${keptKeys.length === 1 ? "key" : "keys"} active: ${keptKeys.map(keyLabel).join(", ")}`);
+    lines.push("Revoke one later with `deepdock keys revoke <id>` after `deepdock auth login`.");
+  }
   for (const key of failedKeys) {
-    lines.push(`Could not revoke "${key.name}" (${key.id}): run \`deepdock keys revoke ${key.id}\` after \`deepdock auth login\`.`);
+    lines.push(`${paint(ctx.out, "error", "Could not revoke")} "${key.name}" (${key.id}): run \`deepdock keys revoke ${key.id}\` after \`deepdock auth login\`.`);
   }
   const hints = [
     ...failedKeys.length > 0 ? ["Revoke the remaining keys with `deepdock keys revoke <id>`."] : [],
@@ -12591,6 +12792,7 @@ var logout = async (ctx) => {
       revoked: signInRevoked,
       email,
       apiKeysRevoked: revokedKeys,
+      apiKeysKept: keptKeys,
       ...failedKeys.length > 0 ? { apiKeysNotRevoked: failedKeys } : {}
     },
     meta: hints.length > 0 ? { hint: hints.join(" ") } : {},
@@ -12600,38 +12802,10 @@ var logout = async (ctx) => {
 };
 var registerAuth = (program, run) => {
   const auth = program.command("auth").description("Sign in to Deepdock as yourself, see who is signed in, sign out");
-  const loginCommand = auth.command("login").description("Sign in to Deepdock as yourself").option("--wait <request>", "finish a request started with --no-wait").option("--no-wait", "print the request and exit").action((options, cmd) => run(cmd, (ctx) => login(ctx, options)));
+  const loginCommand = auth.command("login").description("Sign in to Deepdock as yourself").option("--wait <request>", "finish a request started with --no-wait").option("--no-wait", "print the request and exit").option("--no-browser", "do not open the link in a browser").action((options, cmd) => run(cmd, (ctx) => login(ctx, options)));
   loginCommand.helpInformation = () => AUTH_LOGIN_HELP;
   auth.command("status").description("Show who is signed in").action((_options, cmd) => run(cmd, status));
-  auth.command("logout").description("Revoke the sign-in and the API keys this CLI created").action((_options, cmd) => run(cmd, logout));
-};
-
-// src/output/confirm.ts
-import { createInterface } from "node:readline";
-var ask = (rt, prompt) => new Promise((resolve) => {
-  const rl = createInterface({ input: rt.stdin.stream, output: undefined, terminal: false });
-  rt.stderr.write(prompt);
-  let settled = false;
-  rl.once("line", (line) => {
-    settled = true;
-    rl.close();
-    resolve(line.trim());
-  });
-  rl.once("close", () => {
-    if (!settled)
-      resolve("");
-  });
-});
-var confirm = async (rt, question) => {
-  const answer = await ask(rt, `${question} [y/N]: `);
-  return /^y(es)?$/i.test(answer);
-};
-var pickIndex = async (rt, count, defaultIndex) => {
-  const answer = await ask(rt, `Number [${defaultIndex}]: `);
-  const chosen = answer === "" ? defaultIndex : Number.parseInt(answer, 10);
-  if (!Number.isInteger(chosen) || chosen < 1 || chosen > count)
-    return;
-  return chosen;
+  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/devices.ts
@@ -12641,7 +12815,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)}).`));
     }
   }
 };
@@ -12676,7 +12850,9 @@ var pair = async (ctx, code, label) => {
   const device = isRecord(response.data) ? response.data : {};
   const id = field(device, "id");
   const name = field(device, "label");
-  const lines = [`Paired device ${id}${name ? ` (${stripControl(name)})` : ""}.`];
+  const lines = [
+    `${paint(ctx.out, "success", "Paired")} device ${id}${name ? ` (${stripControl(name)})` : ""}.`
+  ];
   const status = field(device, "status");
   if (status)
     lines.push(`  Status:   ${status}`);
@@ -12698,7 +12874,7 @@ var rename = async (ctx, id, label) => {
   return {
     data: response.data,
     meta: meta(response.requestId),
-    text: `Renamed device ${deviceId} to ${stripControl(label)}.`
+    text: `${paint(ctx.out, "success", "Renamed")} device ${deviceId} to ${stripControl(label)}.`
   };
 };
 var release = async (ctx, id) => {
@@ -12727,7 +12903,7 @@ var release = async (ctx, id) => {
   return {
     data: response.data,
     meta: meta(response.requestId),
-    text: `Released device ${deviceId}.`
+    text: `${paint(ctx.out, "success", "Released")} device ${deviceId}.`
   };
 };
 var renderSystems = (ctx, data) => {
@@ -12850,13 +13026,14 @@ var finishKey = async (ctx, pending, warned) => {
   const file = displayPath(ctx.rt, pending.file);
   const days = Math.round((Date.parse(created.expiresAt) - ctx.rt.now().getTime()) / DAY_MS);
   const text = [
-    `Created API key "${stripControl(created.name)}".`,
+    `${paint(ctx.out, "success", "Created")} API key "${stripControl(created.name)}".`,
     `  ID:        ${created.id}`,
     `  Prefix:    ${created.keyPrefix}`,
     `  Expires:   ${created.expiresAt.slice(0, 10)} (${days} days)`,
     `  Written:   ${file} (${pending.variable})`,
     `The key value was shown to nobody and this CLI keeps no copy; your code reads it from ${file}.`,
-    `Revoke it when you ship: \`deepdock keys revoke ${created.id}\`.`
+    `To revoke it: ${paint(ctx.out, "emphasis", `deepdock keys revoke ${created.id}`)}`,
+    `${paint(ctx.out, "emphasis", "`deepdock auth logout`")} revokes this key; use ${paint(ctx.out, "emphasis", "`auth logout --keep-keys`")} to keep it.`
   ].join(`
 `);
   return {
@@ -12878,6 +13055,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`.");
     }
+    noteWaiting(ctx);
     return finishKey(ctx, pending, false);
   }
   if (name === undefined || name.trim() === "" || name.length > 100 || stripControl(name) !== name) {
@@ -12914,13 +13092,15 @@ var create = async (ctx, name, options) => {
   await upsertPending(ctx, pending);
   if (options.wait === false || !ctx.interactive) {
     return pendingResult(pending, started.url, [
-      `Open this link to approve the key: ${started.url}`,
+      `Open this link to approve the key: ${ctx.out("link", started.url)}`,
       `Then run \`deepdock keys create --wait ${started.request}\`.`
     ].join(`
 `));
   }
-  announceApproval(ctx, "the key", started.url, started.expiresAt, `A human approves "Create an API key in ${org.name}?" there; the page shows this computer's name.`);
-  ctx.rt.openBrowser(started.url);
+  await announceApproval(ctx, "the key", started.url, started.expiresAt, {
+    extra: `A human approves ${paint(ctx.err, "emphasis", `"Create an API key in ${org.name}?"`)} there; the page shows this computer's name.`,
+    noBrowser: options.browser === false
+  });
   return finishKey(ctx, pending, true);
 };
 var revoke = async (ctx, id) => {
@@ -12962,7 +13142,7 @@ Every program using it stops working at once.`;
   const removed = entry ? await settleWrittenLine(ctx, entry, true) : null;
   const apiData = isRecord(response.data) ? response.data : {};
   const label = entry ? `API key "${stripControl(entry.name)}"` : `API key ${keyId}`;
-  const text = removed?.removal === "done" ? `Revoked ${label} and ${describeRemoval(removed)}.` : `Revoked ${label}.`;
+  const text = removed?.removal === "done" ? `${paint(ctx.out, "success", "Revoked")} ${label} and ${describeRemoval(removed)}.` : `${paint(ctx.out, "success", "Revoked")} ${label}.`;
   return {
     data: { ...apiData, ...alreadyRevoked ? { alreadyRevoked: true } : {}, removed },
     meta: { requestId: response.requestId },
@@ -12973,7 +13153,7 @@ var registerKeys = (program, run) => {
   const keys = program.command("keys").description("Create, list and revoke your organisation's API keys");
   keys.command("list").description("List the API keys of the organisation").action((_options, cmd) => run(cmd, list2));
   const allowed = Object.keys(EXPIRY_DAYS).join("|");
-  const createCommand = keys.command("create").description("Create an API key for your organisation (admin)").argument("[name]", "a name that says what the key is for").option("--expires <duration>", `${allowed}; 90 days is the maximum from the CLI`).option("--write-env <file>", "write DEEPDOCK_API_KEY=<key> into this env file").option("--wait <request>", "finish a request started with --no-wait").option("--no-wait", "print the request and exit").action((name, options, cmd) => run(cmd, (ctx) => create(ctx, name, options)));
+  const createCommand = keys.command("create").description("Create an API key for your organisation (admin)").argument("[name]", "a name that says what the key is for").option("--expires <duration>", `${allowed}; 90 days is the maximum from the CLI`).option("--write-env <file>", "write DEEPDOCK_API_KEY=<key> into this env file").option("--wait <request>", "finish a request started with --no-wait").option("--no-wait", "print the request and exit").option("--no-browser", "do not open the link in a browser").action((name, options, cmd) => run(cmd, (ctx) => create(ctx, name, options)));
   createCommand.helpInformation = () => KEYS_CREATE_HELP;
   keys.command("revoke").description("Revoke an API key (admin)").argument("<id>", "the key id").action((id, _options, cmd) => run(cmd, (ctx) => revoke(ctx, id)));
 };
@@ -12986,12 +13166,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 +13198,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);
@@ -13042,7 +13222,7 @@ var select = async (ctx, slug) => {
   return {
     data: { slug: found.slug, name: found.name, role: found.role },
     meta: response.requestId ? { requestId: response.requestId } : {},
-    text: `Default organisation: ${found.name} (${found.slug}).`
+    text: `${paint(ctx.out, "success", "Default organisation:")} ${found.name} (${found.slug}).`
   };
 };
 var registerOrg = (program, run) => {
@@ -13171,10 +13351,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 +13364,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 +13459,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.3",
   "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/auth-and-keys.md

@@ -42,8 +42,8 @@ in the dashboard" and stop retrying.
 - Never ask for, read, print or paste a key value, and never try to extract it from the file.
   Code reads it at runtime from where the CLI put it.
 - A development key reaches every device of the organisation until it expires or is revoked; keep
-  the expiry short (`30d`), use it only against the demo device, and tell the human to revoke it
-  (`deepdock keys revoke <id>`) when the integration ships. The live key is created the same way,
+  the expiry short (`30d`), use it only against the demo device, and tell the human its expiry
+  date and that `deepdock keys revoke <id>` ends it. The live key is created the same way,
   by the human from their own CLI, into the live secret store.
 
 ## The CLI sign-in (CLI only)
@@ -54,7 +54,7 @@ permissions. The sign-in belongs to the person, not to an organisation: every co
 `--org <slug>`. It does what that person can do in the dashboard (members read, pair and rename;
 admins also release devices, create and revoke API keys) and never runs an action.
 `deepdock auth status` shows the signed-in person, organisations and expiry (exit 5 when not signed in); `deepdock auth
-logout` revokes the sign-in and every API key the CLI created.
+logout` revokes the sign-in and every API key the CLI created, unless `--keep-keys` is passed (it then revokes only the sign-in). On a terminal it lists the keys and asks first; with `--json` or without a terminal it revokes them unless `--keep-keys` is passed.
 
 Without a terminal `auth login` prints the request and exits; show the human the link, wait for
 them to approve, then run `deepdock auth login --wait <request>`. Do not try to answer for them.

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

@@ -14,7 +14,7 @@ the API key the CLI wrote to the app's env file.
 |---|---|---|
 | `auth login` | opens a link to the dashboard where the human clicks Approve; prints `Signed in as <email>.` and the person's organisations; the sign-in lasts 90 days | anyone |
 | `auth status` | signed-in person, sign-in expiry, organisations, default organisation, the API keys this CLI created (id, prefix, expiry, where it was written); prints the same document and exits 5 when not signed in | anyone |
-| `auth logout` | revokes the sign-in and every API key this CLI created, removes the entries it wrote, says what it revoked | anyone |
+| `auth logout [--keep-keys]` | revokes the sign-in and, unless `--keep-keys`, every API key this CLI created (on a terminal it lists them and asks, default keep; with `--json` or no terminal it revokes them unless `--keep-keys`); removes the entries it wrote, says what it revoked or kept | anyone |
 | `org list` | the person's organisations: slug, name, role, which one is the default | member |
 | `org select [slug]` | sets the default organisation; without a slug, a pick-list on a terminal | member |
 | `systems list` | the systems and actions assigned to the organisation | member |
@@ -32,11 +32,13 @@ the API key the CLI wrote to the app's env file.
 | `skill [--agent claude\|codex\|cursor\|all]` | writes this skill into the current repository | anyone |
 
 Every command that acts in an organisation uses `--org <slug>` after the command, else
-`DEEPDOCK_ORG`, else the default from `org select`; with none it stops with `org_required` and
-lists the organisations. Always pass `--org` from an agent: `org select` changes the human's
+`DEEPDOCK_ORG`, else the default from `org select`; if you belong to exactly one organisation it is used and named on
+stderr; with several and none chosen it stops with `org_required` and lists them. Always pass `--org` from an agent: `org select` changes the human's
 default in every terminal.
 
-Global flags: `--org <slug>`, `--json`, `--yes`, `-h`, `-v`. Environment: `DEEPDOCK_ORG`,
+`auth login` and `keys create` also open the approval link in the human's browser on a terminal, unless `--no-browser`, `DEEPDOCK_NO_BROWSER=1`, `CI` or a missing display says otherwise.
+
+Global flags: `--org <slug>`, `--json`, `--yes`, `-h`, `-v`. Environment: `DEEPDOCK_ORG`, `DEEPDOCK_NO_BROWSER`,
 `DEEPDOCK_BASE_URL`, `NO_COLOR`.
 
 ## Waiting for the browser
@@ -81,8 +83,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.
@@ -60,8 +60,8 @@ The proof is your client; the CLI only shows what the device offers.
   Neither you nor the human sees the value; you work with its id, prefix and file name only.
 - Never ask for, read, print, echo, log or commit a key value. Use the key only against the demo
   device.
-- It reaches every device of the organisation until it expires or is revoked. Tell the human to
-  revoke it when the integration ships and to create the live key with the same flow from their
+- It reaches every device of the organisation until it expires or is revoked. Tell the human its
+  expiry date and that `deepdock keys revoke <id>` ends it, and that they create the live key with the same flow from their
   own CLI.
 
 ## Logs and prompts