@deepdockai/cli 0.0.0-stage → 1.0.2

package/skill/references/clients/deepdock.py

@@ -0,0 +1,163 @@
+"""Minimal Deepdock /v1 client. Depends on httpx only (Python 3.9+).
+
+It does the four things the OpenAPI document cannot tell you: the bearer header, the envelope
+unwrap, the Idempotency-Key header with replay detection, and a typed error carrying the code.
+Everything action-specific (paths, fields, methods) comes from the live OpenAPI document.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, Iterator, List, Optional, Tuple
+from urllib.parse import quote
+
+import httpx
+
+
+class DeepdockError(Exception):
+    """Deepdock answered `{ "error": { "code", ... } }`. Switch on `code`, never on `message`."""
+
+    def __init__(self, status: int, code: str, message: str, request_id: Optional[str] = None,
+                 systems: Optional[List[str]] = None):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.request_id = request_id
+        self.systems = systems
+
+
+class DeepdockTransportError(Exception):
+    """No answer, or not Deepdock's envelope (timeout, network, a proxy page): a write may still have landed."""
+
+
+@dataclass
+class Page:
+    items: List[Dict[str, Any]]
+    next_cursor: Optional[str]
+
+
+@dataclass
+class WriteResult:
+    data: Dict[str, Any]
+    replayed: bool
+
+
+class Deepdock:
+    def __init__(self, api_key: str, base: str = "https://api.deepdock.ai", 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.
+        self.c = client or httpx.Client(base_url=base.rstrip("/"), timeout=timeout)
+        self.c.headers["Authorization"] = f"Bearer {api_key}"
+
+    def _send(self, method: str, path: str, **kw: Any) -> Tuple[Any, httpx.Headers]:
+        try:
+            r = self.c.request(method, path, **kw)
+        except httpx.HTTPError as e:  # timeouts and network errors
+            raise DeepdockTransportError(f"no answer from Deepdock: {type(e).__name__}") from e
+        try:
+            body = r.json()
+        except ValueError:
+            raise DeepdockTransportError(f"non-JSON answer with status {r.status_code}")
+        if isinstance(body, dict) and "error" in body:
+            e = body["error"]
+            raise DeepdockError(r.status_code, e["code"], e["message"], e.get("requestId"), e.get("systems"))
+        if not isinstance(body, dict) or "data" not in body:
+            raise DeepdockTransportError(f"unexpected body with status {r.status_code}")
+        return body["data"], r.headers
+
+    @staticmethod
+    def _action_path(device_id: str, system: str, action: str) -> str:
+        return f"/v1/devices/{quote(device_id, safe='')}/systems/{quote(system, safe='')}/actions/{quote(action, safe='')}"
+
+    def read(self, device_id: str, system: str, action: str, params: Dict[str, str],
+             limit: Optional[int] = None, cursor: Optional[str] = None) -> Page:
+        """Runs a read action. Pass `next_cursor` back as `cursor` for the next page."""
+        query: Dict[str, str] = dict(params)
+        if limit is not None:
+            query["limit"] = str(limit)
+        if cursor is not None:
+            query["cursor"] = cursor
+        data, _ = self._send("GET", self._action_path(device_id, system, action), params=query)
+        return Page(items=data["items"], next_cursor=data.get("nextCursor"))
+
+    def read_all(self, device_id: str, system: str, action: str, params: Dict[str, str],
+                 limit: Optional[int] = None) -> Iterator[Dict[str, Any]]:
+        """Reads every page of a read action, in order."""
+        cursor: Optional[str] = None
+        while True:
+            page = self.read(device_id, system, action, params, limit=limit, cursor=cursor)
+            yield from page.items
+            if page.next_cursor is None:
+                return
+            cursor = page.next_cursor
+
+    def write(self, device_id: str, system: str, action: str, method: str, idempotency_key: str,
+              body: Dict[str, str]) -> WriteResult:
+        """Runs a write action. `method` is POST or PATCH from the action index; `body` values are all strings."""
+        data, headers = self._send(method, self._action_path(device_id, system, action), json=body,
+                                   headers={"Idempotency-Key": idempotency_key})
+        return WriteResult(data=data, replayed=headers.get("Idempotent-Replayed") == "true")
+
+    def systems(self, device_id: str) -> 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
+
+    def pair(self, code: str, label: Optional[str] = None) -> Dict[str, Any]:
+        """Claims a device by the pairing code it shows. Keep the returned `id`."""
+        body: Dict[str, str] = {"code": code}
+        if label is not None:
+            body["label"] = label
+        data, _ = self._send("POST", "/v1/devices", json=body)
+        return data
+
+    def release(self, device_id: str) -> None:
+        self._send("DELETE", f"/v1/devices/{quote(device_id, safe='')}")
+
+
+# --------------------------------------------------------------------------------------------------
+# Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
+# crash between send and answer cannot produce a second record under a new key. A job retries rows
+# left in "sent" with backoff (seconds, then minutes, for hours if the device stays offline).
+# --------------------------------------------------------------------------------------------------
+
+CONFLICT_RETRIES = 5  # a running write finishes within seconds; beyond this, treat it as unknown
+
+RETRY_SAME_KEY = {"device_offline", "target_busy", "temporarily_unavailable", "internal_error",
+                  "action_paused", "system_unavailable"}
+
+
+@dataclass
+class PendingWrite:
+    key: str  # 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event
+    device_id: str
+    system: str
+    action: str
+    method: str
+    input: Dict[str, str]
+    status: str = "pending"  # pending | sent | done | unknown | refused
+    conflict_retries: int = 0
+    result: Optional[Dict[str, Any]] = field(default=None)
+    request_id: Optional[str] = None
+    refused_code: Optional[str] = None
+
+
+def attempt(dd: Deepdock, row: PendingWrite) -> PendingWrite:
+    """One attempt; returns the row with its new status. The caller persists it."""
+    try:
+        res = dd.write(row.device_id, row.system, row.action, row.method, row.key, row.input)
+        return replace(row, status="done", result=res.data)
+    except DeepdockTransportError:
+        return replace(row, status="sent")
+    except DeepdockError as e:
+        if e.code in RETRY_SAME_KEY:
+            return replace(row, status="sent", request_id=e.request_id)
+        if e.code == "idempotency_conflict":
+            if row.conflict_retries < CONFLICT_RETRIES:
+                return replace(row, status="sent", conflict_retries=row.conflict_retries + 1)
+            return replace(row, status="unknown")
+        if e.code == "outcome_unknown":
+            return replace(row, status="unknown", request_id=e.request_id)
+        # invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+        # resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
+        return replace(row, status="refused", refused_code=e.code, result={"message": str(e)})

package/skill/references/clients/deepdock.ts

@@ -0,0 +1,244 @@
+/**
+ * Minimal Deepdock /v1 client. No dependencies beyond fetch (Node 18+, Bun, Deno, browsers).
+ *
+ * It does the four things the OpenAPI document cannot tell you: the bearer header, the envelope
+ * unwrap, the Idempotency-Key header with replay detection, and a typed error carrying the code.
+ * Everything action-specific (paths, fields, methods) comes from the live OpenAPI document.
+ */
+
+export class DeepdockError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly requestId?: string,
+    readonly systems?: string[],
+  ) {
+    super(message)
+    this.name = 'DeepdockError'
+  }
+}
+
+/** No answer, or not Deepdock's envelope (timeout, network, a proxy page): a write may still have landed. */
+export class DeepdockTransportError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'DeepdockTransportError'
+  }
+}
+
+type ErrorBody = { code: string; message: string; requestId?: string; systems?: string[] }
+type Envelope<T> = { data: T } | { error: ErrorBody }
+
+export type Page<Item> = { items: Item[]; nextCursor: string | null }
+export type WriteResult<T> = { data: T; replayed: boolean }
+export type WriteMethod = 'POST' | 'PATCH'
+
+export type Device = {
+  id: string
+  label: string | null
+  hostname: string
+  os: string
+  clientVersion: string
+  status: 'connected' | 'offline' | 'inactive'
+  lastSeenAt: string | null
+  claimedAt: string
+  systems: string[]
+  updateAvailable?: string
+}
+
+export type ActionState =
+  | { state: 'active' }
+  | { state: 'paused'; reason: string; pausedAt: string }
+
+export type DeviceSystem = {
+  label: string | null
+  version: string
+  status: 'running' | 'stopped' | 'missing'
+  actions: Record<string, ActionState>
+}
+
+export type DeepdockOptions = {
+  base?: string
+  /** Above Deepdock's 20 s device wait, so you receive device_offline instead of timing out first. */
+  timeoutMs?: number
+  fetch?: typeof fetch
+}
+
+export class Deepdock {
+  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 = {},
+  ) {
+    this.base = base.replace(/\/$/, '')
+    this.timeoutMs = timeoutMs
+    this.fetchImpl = fetchImpl
+  }
+
+  private async send<T>(
+    path: string,
+    init: { method: string; headers?: Record<string, string>; body?: string },
+  ): Promise<{ data: T; headers: Headers }> {
+    let res: Response
+    try {
+      res = await this.fetchImpl(`${this.base}${path}`, {
+        method: init.method,
+        headers: { Authorization: `Bearer ${this.apiKey}`, ...init.headers },
+        body: init.body,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      })
+    } catch (err) {
+      // TimeoutError from AbortSignal.timeout, AbortError, or a network TypeError.
+      throw new DeepdockTransportError(`no answer from Deepdock: ${(err as Error).name}`)
+    }
+    let body: Envelope<T>
+    try {
+      body = (await res.json()) as Envelope<T>
+    } catch {
+      throw new DeepdockTransportError(`non-JSON answer with status ${res.status}`)
+    }
+    if (body !== null && typeof body === 'object' && 'error' in body) {
+      const { code, message, requestId, systems } = body.error
+      throw new DeepdockError(res.status, code, message, requestId, systems)
+    }
+    if (body === null || typeof body !== 'object' || !('data' in body)) {
+      throw new DeepdockTransportError(`unexpected body with status ${res.status}`)
+    }
+    return { data: body.data, headers: res.headers }
+  }
+
+  private actionPath(deviceId: string, system: string, action: string): string {
+    return `/v1/devices/${encodeURIComponent(deviceId)}/systems/${encodeURIComponent(system)}/actions/${encodeURIComponent(action)}`
+  }
+
+  /** Runs a read action. Pass `nextCursor` back as `cursor` for the next page. */
+  async read<Item>(
+    deviceId: string,
+    system: string,
+    action: string,
+    input: Record<string, string>,
+    page: { limit?: number; cursor?: string } = {},
+  ): Promise<Page<Item>> {
+    const query = new URLSearchParams(input)
+    if (page.limit !== undefined) query.set('limit', String(page.limit))
+    if (page.cursor !== undefined) query.set('cursor', page.cursor)
+    const suffix = query.size > 0 ? `?${query}` : ''
+    return (await this.send<Page<Item>>(`${this.actionPath(deviceId, system, action)}${suffix}`, { method: 'GET' })).data
+  }
+
+  /** Reads every page of a read action, in order. */
+  async *readAll<Item>(
+    deviceId: string,
+    system: string,
+    action: string,
+    input: Record<string, string>,
+    limit?: number,
+  ): AsyncGenerator<Item> {
+    let cursor: string | undefined
+    do {
+      const page = await this.read<Item>(deviceId, system, action, input, { limit, cursor })
+      for (const item of page.items) yield item
+      cursor = page.nextCursor ?? undefined
+    } while (cursor !== undefined)
+  }
+
+  /**
+   * Runs a write action. `method` comes from the action index or the OpenAPI document; `input`
+   * values are all strings. `idempotencyKey` is new per intended write and the same on every retry.
+   */
+  async write<Result>(
+    deviceId: string,
+    system: string,
+    action: string,
+    method: WriteMethod,
+    idempotencyKey: string,
+    input: Record<string, string>,
+  ): Promise<WriteResult<Result>> {
+    const { data, headers } = await this.send<Result>(this.actionPath(deviceId, system, action), {
+      method,
+      headers: { 'Content-Type': 'application/json', 'Idempotency-Key': idempotencyKey },
+      body: JSON.stringify(input),
+    })
+    return { data, replayed: headers.get('Idempotent-Replayed') === 'true' }
+  }
+
+  /** 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
+  }
+
+  /** Claims a device by the pairing code it shows. Keep the returned `id`. */
+  async pair(code: string, label?: string): Promise<Device> {
+    return (
+      await this.send<Device>('/v1/devices', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(label === undefined ? { code } : { code, label }),
+      })
+    ).data
+  }
+
+  async release(deviceId: string): Promise<void> {
+    await this.send<unknown>(`/v1/devices/${encodeURIComponent(deviceId)}`, { method: 'DELETE' })
+  }
+}
+
+/* ------------------------------------------------------------------------------------------------
+ * Pending writes: one attempt against persisted state. Persist the row BEFORE the first send, so a
+ * crash between send and answer cannot produce a second record under a new key. A job retries rows
+ * left in `sent` with backoff (seconds, then minutes, for hours if the device stays offline).
+ * ---------------------------------------------------------------------------------------------- */
+
+export type PendingStatus = 'pending' | 'sent' | 'done' | 'unknown' | 'refused'
+
+export type PendingWrite = {
+  /** 8 to 128 chars of A-Z a-z 0-9 _ -, stable per business event. */
+  key: string
+  deviceId: string
+  system: string
+  action: string
+  method: WriteMethod
+  input: Record<string, string>
+  status: PendingStatus
+  conflictRetries: number
+  result?: unknown
+  requestId?: string
+  refusedCode?: string
+}
+
+/** A running write finishes within seconds; beyond this, treat a conflict as an unknown outcome. */
+export const CONFLICT_RETRIES = 5
+
+const RETRY_SAME_KEY = new Set([
+  'device_offline',
+  'target_busy',
+  'temporarily_unavailable',
+  'internal_error',
+  'action_paused',
+  'system_unavailable',
+])
+
+/** One attempt; returns the row with its new status. The caller persists it. */
+export const attempt = async (dd: Deepdock, row: PendingWrite): Promise<PendingWrite> => {
+  try {
+    const { data } = await dd.write(row.deviceId, row.system, row.action, row.method, row.key, row.input)
+    return { ...row, status: 'done', result: data }
+  } catch (err) {
+    if (err instanceof DeepdockTransportError) return { ...row, status: 'sent' }
+    if (!(err instanceof DeepdockError)) throw err
+    if (RETRY_SAME_KEY.has(err.code)) return { ...row, status: 'sent', requestId: err.requestId }
+    if (err.code === 'idempotency_conflict') {
+      return row.conflictRetries < CONFLICT_RETRIES
+        ? { ...row, status: 'sent', conflictRetries: row.conflictRetries + 1 }
+        : { ...row, status: 'unknown' }
+    }
+    if (err.code === 'outcome_unknown') return { ...row, status: 'unknown', requestId: err.requestId }
+    // invalid_input, target_rejected, action-specific 422s, not_found, check_failed, auth and
+    // resolution codes: nothing was written. Fix the cause; a changed input gets a new key.
+    return { ...row, status: 'refused', refusedCode: err.code, result: { message: err.message } }
+  }
+}

package/skill/references/concepts.md

@@ -0,0 +1,97 @@
+# Concepts
+
+The words the API, the CLI and the dashboard use. Use them unchanged in code and copy.
+
+## Organisation and partner
+
+You, the partner, are an **organisation** in Deepdock. Everything you own (keys, devices,
+incidents) is scoped to it. Members of your organisation see the dashboard; admins manage keys,
+release devices.
+
+## Keys
+
+- **API key** (`ddk_live_` on production; a `ddk_test_` key belongs to a test deployment): your product's
+  credential on `/v1`. It runs actions, pairs and releases devices, and reads incidents. Created by an
+  admin in the dashboard (shown once) or from the CLI, which writes it straight into the app's env
+  file, keeps no copy and shows it to nobody; optionally expiring.
+- **CLI sign-in**: one person's credential, used only by the `deepdock` CLI after `deepdock auth
+  login`. Valid 90 days. It manages (devices, keys, listing systems) and never runs an action.
+
+Details: [auth-and-keys.md](auth-and-keys.md).
+
+## Device
+
+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.
+
+- **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.
+- **Inactive**: a paired device that has not connected for 7 days. It stays yours and is active again
+  when it connects.
+- **Update**: the client updates itself. A device on an older build than Deepdock ships reports
+  `updateAvailable`.
+
+## 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.
+`GET /v1/devices/{deviceId}/systems` is a live call to the device, so it can answer
+`device_offline`.
+
+### Every status value and what it means for you
+
+| Field | Value | Meaning | What to do |
+|---|---|---|---|
+| device `status` | `connected` | the device is online and can run actions | normal |
+| device `status` | `offline` | the device is not connected right now (PC off, no network) | calls answer `device_offline`; retry later, show "offline" |
+| device `status` | `inactive` | not connected for 7 days; still paired | as offline; check with the site whether the PC still exists |
+| 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, 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.
+
+## Action
+
+One deterministic, validated operation on a system: for example search customers by surname prefix,
+create a note, update a note's text. Deepdock builds and verifies each action before
+offering it; it then runs the same way every time. Actions are
+**assigned** to your organisation by Deepdock, so the set you can call is yours, not the whole
+catalogue.
+
+- A **read** is `GET` with query parameters and pages.
+- A **write** is `POST` (creates a record, answers `201`) or `PATCH` (updates a record, answers
+  `200`), with a JSON body of string fields and an `Idempotency-Key` header.
+- 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`.
+
+## Pause and incident
+
+Deepdock pauses an action instead of guessing when the customer's system no longer looks the way
+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, 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
+customer's site see that an action is paused but cannot resume it; there is no partner call to
+resume. A stopped or missing system needs no resume: its incident closes once the system is back.
+
+An incident has `id`, `system`, `version`, `action` (`null` for a system-level incident), `reason`,
+`openedAt`, `closedAt`, and `devices` with `deviceId`, `pausedAt`, `resumedAt` and `inactiveAt`. It
+closes once none of its devices is still paused. `GET /v1/incidents` lists incidents that are open
+or closed within the last 30 days, newest first, at most 100.

package/skill/references/discovery.md

@@ -0,0 +1,80 @@
+# Discovering systems and actions
+
+Never hard-code an action's fields. Three sources, each authoritative for one thing:
+
+| Question | Source | Key |
+|---|---|---|
+| Which systems and actions does my organisation have? | `deepdock systems list --json` | CLI sign-in |
+| What does this device run, and is each action active or paused? | `GET /v1/devices/{deviceId}/systems` | organisation |
+| Which actions can I call on this device's system, with which schemas? | `GET /v1/devices/{deviceId}/systems/{system}/actions` | organisation |
+| The exact paths, methods, fields, patterns, enums, lengths, responses | `deepdock systems openapi <system>` (CLI sign-in) or `GET /v1/systems/{system}/openapi.json` (API key); per device `deepdock actions list <device> <system>` (CLI sign-in) | CLI sign-in or API key |
+
+## The OpenAPI document
+
+```bash
+deepdock systems openapi example-erp --org <slug> > openapi/example-erp.json
+# from your backend, with the API key:
+curl "$BASE/v1/systems/example-erp/openapi.json" -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+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:
+
+- **`paths`**: one operation per action at
+  `/v1/devices/{deviceId}/systems/{system}/actions/{action}`; the HTTP method is the action's
+  kind (`get` read, `post` create, `patch` update). Use the method the document gives; the other
+  write method answers `405 invalid_request` with an `Allow` header.
+- **`summary` and `description`**: what the action does and what it changes in the system, what
+  an omitted optional input becomes, action-specific refusals (`code` and when), and what the
+  system only warns about and what the action does then. Read the description before mapping your
+  fields.
+- **Read inputs** are query parameters, all `type: string`, each with `maxLength` and possibly
+  `minLength`, `pattern`, `enum` and a `description` such as "prefix match: case, punctuation and
+  umlaut spelling are ignored". Plus `limit` (integer, 1 to 250, default 25) and `cursor` (opaque).
+  An optional parameter is not in `required` and its description says what an omitted value
+  becomes.
+- **Write inputs** are the `requestBody` object schema: `additionalProperties: false`, every
+  property `type: string`, `required` lists the mandatory ones. The `Idempotency-Key` header
+  parameter carries its own pattern (8 to 128 characters of `A-Z a-z 0-9 _ -`).
+- **Responses**: a read's `200` is `{ data: { items: [...], nextCursor } }`; a create's `201` and a
+  replayed `200`; an update's `200`. Item and result fields are typed `string`, `integer` or `number`,
+  often nullable (`["integer", "null"]`). The `Error` schema's `code` enum is the full list of codes.
+- **`servers`**: the base URL of the API.
+
+The document describes **Deepdock's whole catalogue** for the system. Your organisation may be
+assigned a subset. Write code only for actions that appear in both the document and `systems list`
+(or the device's action index); an action in the document but not assigned to you answers
+`404 action_not_found`.
+
+## The action index
+
+```bash
+curl "$BASE/v1/devices/$DEVICE/systems/example-erp/actions" \
+  -H "Authorization: Bearer $DEEPDOCK_API_KEY"
+```
+
+Answers `{ data: [ { name, method, description, input, output } ] }`, filtered to your assigned
+actions, with the same JSON Schemas the OpenAPI document carries. Use it at runtime to confirm an
+action exists before offering it in your UI, or to validate input client-side before sending.
+
+## The device's systems
+
+```bash
+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
+connected: that is a normal state, not an error in your code. Do not poll it tightly; it reaches the
+customer's PC.
+
+## Generated clients
+
+If the project already uses an OpenAPI generator (`openapi-typescript`, `openapi-generator`,
+`kiota`), generating from the document is fine. The generator will not produce the envelope unwrap,
+the idempotency rule or the error-code reactions; those come from this skill. Remember the
+document is the whole catalogue, not your assigned set.