@seeed-studio/solution-cli 0.0.0-stage → 0.1.0

package/skills/sensecraft/references/app-only.md

@@ -0,0 +1,273 @@
+# Desktop-app-only capabilities
+
+> **Requires the SenseCraft Solution desktop app** running on this computer.
+> Everything here talks to the app's local HTTP API with `curl`. The engine
+> CLI path in `SKILL.md` does not need any of it. Use this file when the user
+> has the app open and wants to change a solution's configuration, deployed
+> from the app, or asks what the app is showing.
+
+Sections: 1. Connect to the app · 2. Deploy through the app · 3. Diagnose
+through the app · 4. Change a solution's configuration (edit copy).
+
+> **Windows PowerShell:** `curl` there is an alias for `Invoke-WebRequest`.
+> Always type `curl.exe`. Send JSON bodies from a file (`--data @body.json`)
+> instead of inline strings to avoid quoting problems.
+
+## 1. Connect to the app (every app task)
+
+1. Read the runtime file:
+   - macOS / Linux: `~/.sensecraft/runtime.json`
+   - Windows: `%USERPROFILE%\.sensecraft\runtime.json`
+
+   It holds `base_url`, `contract_version`, `logs_dir`, `solutions_dir` and
+   `solutions_edits_dir`.
+2. Check the app is really there: `curl -s <base_url>/api/health` must return
+   `"status": "healthy"`. The file can be left over after a crash.
+3. If the file is missing or the check fails, the app is not running: ask the
+   user to open **SenseCraft Solution** and try again. (Developers running
+   `./dev.sh` from source: `base_url` is `http://127.0.0.1:3260`.)
+4. If `contract_version` is below 6, deploying and diagnosing still work, but
+   config editing is not available: tell the user to update the app.
+5. The `sensecraft-engine` CLI writes the same file for its own instance. A
+   file with `"schema_version": 2` and `"python_backend": null` points at an
+   engine instance started by the CLI, not at the app: the app is not running.
+
+Below, `BASE` means the `base_url` value. Add `lang=zh` to API calls that take
+`lang` when the user writes in Chinese, `lang=en` otherwise.
+
+## 2. Deploy through the app
+
+`BASE` comes from §1. Examples use `lang=en`; use `lang=zh`
+for a Chinese-speaking user.
+
+### 2.1 Find the solution
+
+```
+curl -s "BASE/api/solutions?lang=en"
+```
+
+Match the user's wording against `name` / `summary`. Confirm the `id` with the
+user if more than one fits.
+
+### 2.2 Read what the deployment needs
+
+```
+curl -s "BASE/api/solutions/<id>/deploy-info?lang=en"
+```
+
+- `presets[]` — deployment variants. If there is more than one, ask the user which
+  one, then call again with `&preset_id=<preset>`.
+- `steps[]` — each step's `device_id`, `type`, `required`, parameters, and for
+  `docker_deploy` steps the `targets` (local = this computer's Docker, remote =
+  a device over SSH).
+- `request_template` — a ready request body. Values shaped like
+  `<REQUIRED: ...>` must be filled in; everything else has a working default.
+
+Never make up step or device IDs: the keys of `device_connections` and the
+entries of `selected_devices` are exactly the ones in `request_template`.
+
+Optional device discovery, to pre-fill hosts:
+
+```
+curl -s "BASE/api/devices/detect/<id>?preset=<preset>"     # USB / serial
+curl -s "BASE/api/devices/scan-mdns"                        # SSH devices on the LAN
+curl -s "BASE/api/docker-devices/local/check"               # local Docker
+```
+
+### 2.3 Fill in and confirm
+
+Ask the user for every `<REQUIRED: ...>` value (device IP, username, password,
+and any user inputs). For `docker_deploy` steps pick the target with
+`"target": "<target id>"` **and set `"target_type"` to that target's own type**
+(`local` / `remote`, from deploy-info `targets`) — or remove `target_type`. The
+template carries the default target's type; leaving it while switching
+`target` is rejected with a 400. Remote targets also need `host`, `username`,
+`password`. Add `"auto_replace_containers": true` only if the user agrees to
+replace existing containers with the same name.
+
+Write the filled body to a file, e.g. `body.json`:
+
+```json
+{
+  "solution_id": "<id>",
+  "preset_id": "<preset>",
+  "selected_devices": ["<step_id>"],
+  "device_connections": {
+    "<step_id>": {"target": "<target_id>", "host": "192.168.1.50",
+                  "username": "<user>", "password": "<password>"}
+  }
+}
+```
+
+Show the user the body with the password as `<REDACTED>` before starting.
+
+### 2.4 Start and wait
+
+```
+curl -s -X POST "BASE/api/deployments/start" -H "Content-Type: application/json" --data @body.json
+```
+
+Keep the returned `deployment_id`. The response also lists each device with
+`status`: `deploying`, or `skipped` with a `reason` (manual / info-only steps
+are always skipped — that is normal, not an error).
+
+Poll every 3–5 seconds:
+
+```
+curl -s "BASE/api/deployments/<deployment_id>/summary"
+```
+
+`status` is `running` while in progress and ends as `completed`, `failed` or
+`cancelled`. Each `devices[].steps[]` entry has its own `status` (`pending`,
+`running`, `completed`, `failed`) and a `message`. The JSON is compact
+(`"status":"failed"`, no spaces) — parse it rather than grepping. The user sees the same
+deployment live in the app. Delete `body.json` afterwards (it holds a password).
+
+### 2.5 Verify
+
+`completed` is not enough. Check the result is actually usable:
+
+- Docker steps: on the target (`docker ps` locally, or over SSH) the
+  solution's containers are `Up` and, if they define a health check, `(healthy)`.
+- Services with a port: `curl -s -o /dev/null -w "%{http_code}" http://<host>:<port>/`
+  returns 2xx/3xx.
+- Tell the user the URL to open and anything the guide says to do next.
+
+### 2.6 If anything failed
+
+Go straight to §3 below with the `deployment_id`. Do not stop to ask.
+
+To retry after a fix, send the same body again — same `preset_id` and
+`device_connections` — with `selected_devices` listing only the device(s) that
+failed; the others are already done. Leaving manual steps in is harmless (they
+are skipped).
+
+## 3. Diagnose through the app
+
+The general method (classify, retry, report, issue form) is in `diagnose.md`; these are the app-specific evidence sources.
+
+### 3.1 Find the deployment
+
+If you started it, you already have the `deployment_id`. Otherwise:
+
+```
+curl -s "BASE/api/deployments"           # newest first: id, solution_id, status
+curl -s "BASE/api/ai/context"            # what is running right now, and what the user is looking at in the app
+```
+
+### 3.2 Collect evidence
+
+`/summary` and `/logs` only know deployments made since the app last started;
+an older id from the list returns 404. In that case read the engine log (below)
+for that time, or reproduce the failure by deploying again.
+
+Start with the summary. **The real error is usually in the failing step's
+`message`** (`devices[].steps[]` with `status: failed`); the top-level `errors`
+list and the error-level logs may only say "Device X deployment failed".
+
+```
+curl -s "BASE/api/deployments/<deployment_id>/summary"
+```
+
+For more context around the failure, the full device log:
+
+```
+curl -s "BASE/api/deployments/<deployment_id>/logs?device_id=<device_id>&limit=300"
+```
+
+If the deployment logs are empty or end abruptly, read the engine log:
+`<logs_dir>/provisioning-station.log` (last ~200 lines) and, if present,
+`<logs_dir>/provisioning-station-crash.log`. `logs_dir` is in `runtime.json`.
+
+Note the failing device, step and the first error — later errors are usually
+consequences of the first.
+
+### 3.3 Device checks, classification, retry, report
+
+As in `diagnose.md` §3–6, with these differences: the solution folder is
+`<solutions_dir>/<id>/` from `runtime.json`, or the edit copy if one exists;
+configuration fixes go through §4; the issue form's `app_version` is
+`app_version` from `runtime.json`, and its `diff` field is the output of
+`/api/editor/solutions/<id>/diff`.
+
+## 4. Change a solution's configuration
+
+Needs `contract_version` 6 or later (see §1).
+
+The app never changes its bundled solutions. Edits go into an **edit copy** of
+one solution; while the edit copy exists, the app uses it instead of the
+bundled one. Deleting it ("discard") restores the original. The app marks
+the solution as "locally modified", shows the changes, and offers "restore
+official version" — so the user can always see and undo what you changed.
+
+### 4.1 Open the edit copy
+
+```
+curl -s -X POST "BASE/api/editor/solutions/<id>/enter"
+```
+
+Returns `path` — the edit copy's folder. Calling it again is safe; it keeps
+existing edits and returns the same `path`.
+
+### 4.2 Edit files in `path`
+
+| File | Holds |
+|---|---|
+| `solution.yaml` | Name, presets, intro metadata |
+| `guide.md`, `guide_zh.md` | Deployment steps; each `## Step` header has `config=devices/<x>.yaml` |
+| `devices/<x>.yaml` | One step's settings: `docker.compose_file`, `docker.environment`, `docker.services[].port` / `health_check_endpoint`, `pre_checks`, `ssh.default_user`, firmware source, ... |
+| `assets/...` | What gets deployed: compose files, Node-RED flows, scripts, firmware |
+
+Field definitions:
+https://raw.githubusercontent.com/suharvest/sensecraft-solutions/main/spec/device.schema.json
+and `.../spec/solution.schema.json`.
+
+Keep changes minimal: change what the evidence points at, nothing else. When a
+value appears in several places (a port in compose, in `services[].port` and in
+`pre_checks`), change all of them.
+
+**Device YAMLs and assets are read from disk at deploy time**, so they take
+effect as soon as you save them. Always validate before redeploying.
+
+### 4.3 Validate
+
+```
+curl -s -X POST "BASE/api/editor/solutions/<id>/validate"
+```
+
+`ok: false` → fix each entry in `errors` (`file` is relative to `path`, `line`
+is 1-based or null) and validate again. `warnings` do not block; leave
+existing ones (e.g. "missing Chinese translation") alone unless the user asked
+for guide changes.
+
+### 4.4 Apply
+
+```
+curl -s -X POST "BASE/api/editor/solutions/<id>/apply"
+```
+
+- `200` with `active_path` equal to `path` → the edit copy is live, including
+  changes to `solution.yaml` and the guides.
+- `422` → `{"detail": <the same report as validate>}`; nothing was reloaded.
+  Fix the `detail.errors` entries and retry.
+
+Then redeploy the affected device (§2.6, or `deploy.md` §6 on the engine path).
+
+### 4.5 Show what changed
+
+```
+curl -s "BASE/api/editor/solutions/<id>/diff"
+```
+
+Returns `files[]` with `path`, `status` (`modified` / `added` / `removed`) and a
+unified `diff` for text files. Show the user these diffs. The same changes are
+visible in the app.
+
+### 4.6 Undo, share
+
+- Undo all edits: `curl -s -X POST "BASE/api/editor/solutions/<id>/discard"`
+- Package the edit copy as a zip (returns `zip_path`) to send to the solution
+  maintainers or turn into a pull request:
+  `curl -s -X POST "BASE/api/editor/solutions/<id>/export"`
+- An app content update does not overwrite the edit copy. If the user later
+  wants the updated official version, discard the edit copy.

package/skills/sensecraft/references/deploy.md

@@ -0,0 +1,300 @@
+# Deploy a solution
+
+Run Step 0 in `SKILL.md` first (engine installed, solutions pulled). Examples
+use `--lang en`; use `--lang zh` for a Chinese-speaking user.
+
+## 1. Find the solution
+
+```
+sensecraft-engine solution list --json
+```
+
+Match the user's wording against `name` / `summary`. Confirm the `id` with the
+user if more than one fits. `sensecraft-engine solution show <id> --lang en`
+prints the full solution if you need more detail.
+
+## 2. Read what the deployment needs
+
+```
+sensecraft-engine deploy-info <id> --lang en
+```
+
+- `presets[]` — deployment variants. If there is more than one, ask the user which
+  one, then run again with `--preset <preset>`. Without `--preset` the template
+  lists the steps of every preset.
+- `steps[]` — each step's `device_id`, `type`, `required`, `connection_type`
+  (`ssh` / `serial` / `none` / ...), `parameters`, `category` (`deploy` or
+  `verify`) and `interactive`. Steps with `has_targets: true` (e.g.
+  `docker_deploy`) list `targets`: `local` = this computer's Docker, `remote` =
+  a device over SSH.
+- Verify steps that need the user carry a ready command list:
+  `counting_cli`, `face_cli`, `wizard_cli` or `robot_cli` (see `verify.md`).
+- `request_template` — a ready request body. Values shaped like
+  `<REQUIRED: ...>` must be filled in; everything else has a working default.
+
+Never make up step or device IDs: the keys of `device_connections` and the
+entries of `selected_devices` are exactly the ones in `request_template`.
+
+Optional discovery, to pre-fill values:
+
+```
+sensecraft-engine device ports            # serial ports (USB devices)
+sensecraft-engine device scan --timeout 5 # SSH devices on the LAN (mDNS, IPv4)
+sensecraft-engine device list             # device catalog
+sensecraft-engine doctor --json           # this computer: serial permission, Docker, disk, network
+```
+
+## 3. Fill in and confirm
+
+Ask the user for every `<REQUIRED: ...>` value (device IP, username, password,
+serial port, and any user inputs). Serial steps carry both `port` and
+`serial_port` placeholders; fill both with the port name from `device ports`.
+
+For `docker_deploy` steps pick the target with `"target": "<target id>"` **and
+set `"target_type"` to that target's own type** (`local` / `remote`) — or
+remove `target_type`. Leaving the template's type while switching `target` is
+rejected. Each deploy-info target carries `type` (`local` / `remote`) and,
+when the target is tied to a board, `device` / `device_name` /
+`device_class` (for example `rk3576`, `RK3576`): pick the target whose
+`type` and device match the user's hardware, and copy its `type` into
+`target_type`. `device` is null for targets that run on any Docker host. On
+engine builds whose targets have no `type` yet, the target id suffix (for
+example `_local`, `_remote`) is only a hint; confirm the type with `validate`
+(§3, dry run) before starting. Remote targets need `host`, `username`
+and either `password` or `key_file`:
+
+Windows native `local` Docker is unsupported by both deployers and returns the
+platform check failure; use a `remote` target over SSH to a Linux Docker host.
+WSL must use the Linux engine binary and is Linux-host evidence, not Windows
+native local Docker support. On macOS, the local target uses the literal
+`docker` executable visible to the new engine process. If Docker Desktop's CLI
+is only in its application bundle, provide that bundle's `bin` directory in a
+temporary engine-process `PATH`; do not alter global shell configuration or
+assume an already-running instance inherits the path. Docker Desktop being
+running is a prerequisite check, not a deployment result.
+
+- Password: `"password": "<the user's password>"`.
+- SSH key: `"key_file": "~/.ssh/id_ed25519"` and no `password` field. The key
+  must be a regular file inside `~/.ssh` (or the engine's data directory); a
+  relative path is resolved under `~/.ssh`; other locations are refused.
+
+Add `"auto_replace_containers": true` (or the `--replace-existing` flag) only if
+the user agrees to replace existing containers with the same name.
+
+Write the filled body to `./.sensecraft-work/body.json` in the current working
+directory, not `/tmp` (a file keeps the password out of the process list and
+avoids shell quoting problems, notably in PowerShell):
+
+```json
+{
+  "solution_id": "<id>",
+  "preset_id": "<preset>",
+  "selected_devices": ["<step_id>"],
+  "device_connections": {
+    "<step_id>": {"target": "<target_id>", "target_type": "remote",
+                  "host": "192.168.1.50", "username": "<user>",
+                  "password": "<password>"}
+  }
+}
+```
+
+Show the user the body with the password as `<REDACTED>` before starting.
+
+On Windows PowerShell 5.1, write the JSON as UTF-8 **without a BOM**. The
+default `Set-Content -Encoding UTF8` adds a BOM, which the Rust request reader
+rejects. Keep the request file under the current workspace and do not print it
+when it contains a password:
+
+```powershell
+$RequestPath = [System.IO.Path]::GetFullPath('.sensecraft-work/body.json')
+$RequestDir = [System.IO.Path]::GetDirectoryName($RequestPath)
+New-Item -ItemType Directory -Force -Path $RequestDir | Out-Null
+$body = @{
+  solution_id = '<id>'
+  preset_id = '<preset>'
+  selected_devices = @('<step_id>')
+  device_connections = @{
+    '<step_id>' = @{
+      target = '<target_id>'
+      target_type = 'remote'
+      host = '192.168.1.50'
+      username = '<user>'
+      password = '<password>'
+    }
+  }
+}
+$json = $body | ConvertTo-Json -Depth 50
+[System.IO.File]::WriteAllText($RequestPath, $json, [System.Text.UTF8Encoding]::new($false))
+```
+
+`-Depth 50` preserves nested `device_connections`; PowerShell's default depth
+of 2 is insufficient. Replace placeholders with user-provided values and keep
+the file protected; never print the password.
+
+Before a remote deploy, run the dry run (no changes on any device):
+
+```
+sensecraft-engine validate --params ./.sensecraft-work/body.json
+```
+
+It reports parameter errors and previews which verify steps will need the user
+(`verify_required`). It also lists the changes the deployment may make on each
+target beyond the solution's own files and containers, as
+`side_effects: {"<step_id>": [{"kind", "what", "when", "decided_in"}, ...]}`:
+
+| `kind` | Change on the target |
+|---|---|
+| `sudo` | Commands run with `sudo` (Docker through `sudo docker`, actions marked `sudo`) |
+| `daemon_json_write` | Merges `registry-mirrors` into `/etc/docker/daemon.json` (other keys kept) |
+| `docker_daemon_restart` | Restarts the Docker daemon (all containers on the device restart with it) |
+| `package_install` | Installs packages (Docker / Compose, `.deb`, apt / pip in an action) |
+| `system_config` | Changes system settings (`usermod`, `update-alternatives`, services) |
+| `reboot` | Reboots the device |
+| `firmware_flash` | Flashes firmware |
+| `local_script` | Runs a script on this computer |
+
+`what` says what happens in plain words, `when` the condition: `always`, a
+condition the engine checks during the deploy (for example "the device cannot
+reach Docker Hub"), or "the action's script decides". `decided_in` points at
+engine code; it is for bug reports, not something to read.
+
+Tell the user what the list contains. If the user forbade a kind that is
+listed (Docker restart, daemon.json changes, reboot, package installs) and
+has not agreed to it, stop and ask before starting, also when `when` is a
+condition: the deploy may meet it. Exception: when the action's script is in
+the solution's step file (`devices/<x>.yaml` under `actions` or
+`remote_overrides.actions` in `~/.sensecraft/content/solutions/<id>/`, or
+`$SC_HOME/content/solutions/<id>/` when `SC_HOME` is set), read
+it; if its condition can be checked read-only on the device and is not met,
+say so and continue. Actions that come from the engine's built-in device
+profile are not in that file: treat them as possible. Builds without a
+`side_effects` field: assume a remote Docker deploy may write
+`/etc/docker/daemon.json` and ask when the user restricted that.
+
+Before the deploy, save the target's current Docker daemon config so changes
+can be shown and restored:
+
+```
+ssh <user>@<ip> cat /etc/docker/daemon.json > ./.sensecraft-work/daemon.json.before
+```
+
+(a missing file is fine: note that it did not exist). After the deploy, `cat`
+it again and show the user any difference; restoring it is a change on the
+device and needs the user's OK.
+
+## 4. Start and follow
+
+```
+sensecraft-engine deploy --params ./.sensecraft-work/body.json --yes --detach --lang en
+```
+
+`--detach` prints `{"deployment_id": "...", "log": "..."}` and returns. Keep the
+`deployment_id`. Exit code 2 means the request or arguments are invalid. When
+the JSON error contains a `missing[]` list, ask for those fields
+(`preset_id`, `device_connections.<id>.<key>`); for `bad_request` without
+`missing[]`, inspect the solution ID, JSON shape, and parameter spelling before
+asking for another value.
+Exit code 3 with a 409 means the device is busy with another deployment.
+
+Follow progress in one of two ways:
+
+- **Poll** (works with any agent's command timeout): every 3–5 seconds run
+  `sensecraft-engine status <deployment_id> --json`. `status` is `running`
+  while in progress and ends as `completed`, `failed`, `cancelled` or
+  `interrupted`; each device and step has its own `status` and `message`.
+  Exit code: 0 while running or completed, 1 for failed / cancelled /
+  interrupted.
+- **Event stream:** `sensecraft-engine logs <deployment_id> --since <N>`
+  prints NDJSON events (`{seq, type, ...}`) with `seq > N` and exits; add
+  `--follow` to keep streaming until the deployment ends (run it in the
+  background if your command timeout is short). Remember the last `seq` and
+  pass it as `--since` next time, so you never read the same events twice.
+
+Event types to act on:
+
+| `type` | Meaning |
+|---|---|
+| `log` | `level`, `message`; `error`-level lines are evidence for `diagnose.md` |
+| `step_skipped` with `reason: verify_required` | The step needs the user — the `verify_required` event before it has the details |
+| `verify_required` | Go to `verify.md` with this event |
+| `device_completed` | One device finished |
+| `deployment_completed` | Last event; `status` is the final result |
+
+Read the JSON directly instead of grepping it (no interpreter, see `SKILL.md`
+rule 5). Delete `./.sensecraft-work/` afterwards (`body.json` holds a
+password).
+
+Without `--detach`, `deploy --json` streams the same events on stdout and ends
+with one `{"type": "result", "deployment_id", "status", "devices"}` line; the
+exit code is the deployment's result. Ctrl-C or a killed agent command only
+detaches: the deployment keeps running in the engine instance; continue with
+`status` / `logs`.
+
+If `--detach` prints `"backend": "python"`, the desktop app's backend is
+running this deployment: `logs` then has `log` and `deployment_completed`
+events only, no `verify_required`. Do the guide's verify steps with the user
+as described in `verify.md` §1.
+
+## 5. Verify
+
+`completed` is not enough. Check the result is actually usable:
+
+- `verify_required` events: handle each one with `verify.md`.
+- Docker steps: on the target the solution's containers have `status`
+  `running` (and are `(healthy)` in `docker ps` when they define a health
+  check):
+  `sensecraft-engine docker ps --json` (this computer),
+  `sensecraft-engine docker ps --host <ip> --username <user> --key-file ~/.ssh/id_ed25519 --json`
+  (remote with an SSH key; same path rules as `key_file` in §3), or
+  `SC_SSH_PASSWORD=<password> sensecraft-engine docker ps --host <ip> --username <user> --json`
+  (remote with a password; `--password-stdin` reads it from stdin instead).
+  `docker logs <container> --host ... --key-file ...` takes the same options.
+  Older engines without `--key-file` accept a password only; with a key-only
+  device use `ssh <user>@<ip> docker ps`.
+- Services with a port: `curl -s -o /dev/null -w "%{http_code}" http://<host>:<port>/`
+  returns 2xx/3xx.
+- Stay running: `completed` can precede a crash loop. CLI deploys already
+  watch each Docker service for about 60 seconds after its health check
+  answers and fail the step with `Service <name> is not healthy: ...` when a
+  container restarts, exits or disappears. Check once more yourself: run `docker ps` once,
+  wait about 60 seconds, then run it again and read the container restart
+  count (`docker inspect -f '{{.Name}} {{.RestartCount}} {{.State.Status}}' <container>`
+  over SSH, or the `Restarting` / `Up Less than a second` status in `docker ps`).
+  The counts must stay 0 and the verify endpoint (the step's `url`, or the
+  port check above) must still answer after the wait. If a container restarts
+  or the endpoint stops answering, report a crash loop, not success, and go to
+  `diagnose.md`.
+- Tell the user the URL to open and anything the guide says to do next.
+
+## 6. If anything failed
+
+Go straight to `diagnose.md` with the `deployment_id`. Do not stop to ask.
+
+To retry after a fix, send the same body again — same `preset_id` and
+`device_connections` — with `selected_devices` listing only the device(s) that
+failed (or `--device <step_id>` for one device); the others are already done.
+Leaving manual steps in is harmless (they are skipped).
+
+Two kinds of failure, two policies:
+
+- **Transient registry or network errors** (image pull answered 401 / 429 /
+  500 / 502 / 503 / 504, `TLS handshake timeout`, `i/o timeout`,
+  `connection reset`, a mirror that flaps): retry the same body without
+  asking, up to 5 times, waiting 15, 30, 60, 120, 240 seconds between tries.
+  These retries do not count as fix rounds. If the engine log shows the
+  mirror changing between tries, that is the same transient case. After the
+  5th failure, stop and report the error text, the waits and the registry host.
+- **Deterministic failures** (bad parameter or credentials, port taken, disk
+  full, missing file, a container that exits on start, the same error with the
+  same text after a fix): stop retrying blindly. First retry after a fix
+  without asking; later retries need the user's OK; at most 3 rounds, then
+  report.
+
+If you cannot tell which kind it is, treat the second occurrence of the same
+error after a wait as deterministic.
+
+## Cancel
+
+Only with the user's OK: `sensecraft-engine cancel <deployment_id>`. Then check
+`status` until it is `cancelled`, and tell the user which steps had already run:
+the device may be half-configured.