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

package/lib/platform.js

@@ -0,0 +1,113 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+
+export function getPlatformInfo() {
+  const p = os.platform();
+  const a = os.arch();
+
+  let target = null;
+  let supported = true;
+  let note = '';
+
+  if (p === 'darwin') {
+    if (a === 'arm64') {
+      target = 'aarch64-apple-darwin';
+    } else {
+      supported = false;
+      note = 'macOS x86_64 (Intel) is not supported for standalone binary releases. Under Rosetta, run from a native ARM shell.';
+    }
+  } else if (p === 'linux') {
+    if (a === 'x64') {
+      target = 'x86_64-unknown-linux-musl';
+    } else if (a === 'arm64') {
+      target = 'aarch64-unknown-linux-musl';
+    } else {
+      supported = false;
+      note = `Linux architecture ${a} is not supported. Supported: x64, arm64.`;
+    }
+  } else if (p === 'win32') {
+    if (a === 'x64') {
+      target = 'x86_64-pc-windows-msvc';
+    } else {
+      supported = false;
+      note = `Windows architecture ${a} is not supported. Supported: x64.`;
+    }
+  } else {
+    supported = false;
+    note = `Operating system ${p} is not supported.`;
+  }
+
+  const isWindows = p === 'win32';
+  const binaryName = isWindows ? 'sensecraft-engine.exe' : 'sensecraft-engine';
+
+  return {
+    platform: p,
+    arch: a,
+    target,
+    supported,
+    note,
+    isWindows,
+    binaryName
+  };
+}
+
+export function getScHome() {
+  return process.env.SC_HOME || path.join(os.homedir(), '.sensecraft');
+}
+
+export function getEngineBinDir() {
+  return path.join(getScHome(), 'bin');
+}
+
+export function getEngineBinaryPath() {
+  const { binaryName } = getPlatformInfo();
+  return path.join(getEngineBinDir(), binaryName);
+}
+
+export function getContentDir() {
+  return path.join(getScHome(), 'content');
+}
+
+export function getConfiguredEnginePath() {
+  const pointerFile = path.join(getScHome(), 'engine.json');
+  if (fs.existsSync(pointerFile)) {
+    try {
+      const data = JSON.parse(fs.readFileSync(pointerFile, 'utf8'));
+      if (data && data.bin && fs.existsSync(data.bin) && isExecutable(data.bin)) {
+        return path.resolve(data.bin);
+      }
+    } catch {}
+  }
+  return path.resolve(getEngineBinaryPath());
+}
+
+export function setConfiguredEnginePath(binPath, version = null, source = null) {
+  const pointerFile = path.join(getScHome(), 'engine.json');
+  const dir = path.dirname(pointerFile);
+  fs.mkdirSync(dir, { recursive: true });
+  const payload = {
+    schema_version: 1,
+    bin: path.resolve(binPath),
+    version: version || 'unknown',
+    source: source || 'unknown',
+    updated_at: new Date().toISOString()
+  };
+  const tempFile = path.join(dir, `.engine.tmp-${Date.now()}`);
+  fs.writeFileSync(tempFile, JSON.stringify(payload, null, 2), 'utf8');
+  fs.renameSync(tempFile, pointerFile);
+}
+
+export function isExecutable(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) return false;
+    if (os.platform() === 'win32') {
+      return filePath.toLowerCase().endsWith('.exe') || filePath.toLowerCase().endsWith('.cmd');
+    }
+    // Unix: check execute permissions (owner/group/others)
+    return Boolean(stat.mode & 0o111);
+  } catch {
+    return false;
+  }
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
+  "type": "module",
+  "main": "./lib/installer.js",
+  "bin": {
+    "solution-cli": "bin/cli.js",
+    "sensecraft-solution-cli": "bin/cli.js",
+    "sensecraft": "bin/cli.js",
+    "sensecraft-engine": "bin/runner.js",
+    "sensecraft-skill": "bin/cli.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "catalog",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test tests/cli.test.mjs",
+    "install:self": "node bin/cli.js install",
+    "status": "node bin/cli.js status",
+    "doctor": "node bin/cli.js doctor"
+  },
+  "keywords": [
+    "seeed-studio",
+    "sensecraft",
+    "sensecraft-solution",
+    "iot",
+    "workbuddy",
+    "claude-code",
+    "codex",
+    "codebuddy",
+    "skills",
+    "edge-ai",
+    "jetson",
+    "raspberry-pi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Seeed-Studio/app_collaboration.git",
+    "directory": "packages/solution-cli"
+  },
+  "author": "Seeed Studio",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/skills/sensecraft/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: sensecraft
+description: Consult, select, deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) and hardware products (reComputer Jetson, reCamera, SenseCAP, Grove Vision AI, ESP32) using the `sensecraft-engine` and `solution-cli` toolset. Use whenever the user asks for edge IoT solutions, hardware recommendations, accessory compatibility, deployment, or troubleshooting.
+---
+
+# SenseCraft Solution
+
+This skill drives the `sensecraft-engine` execution engine and `solution-cli` toolset. It operates across the complete lifecycle: **Solution Consultation ➔ Hardware & Accessory BOM Selection ➔ Local Deployment ➔ Self-Healing Diagnostics**.
+
+## Workflow Routing & Progressive Disclosure
+
+Do NOT read all reference files at once. Determine the user's workflow state and intent, then load **at most ONE** reference file on demand:
+
+| User State & Intent | Reference to Load | Primary CLI Tool to Call | Guardrails & Forbidden Actions |
+|---|---|---|---|
+| **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json` | **DO NOT run deploy**; user is exploring scenarios and has not confirmed hardware. |
+| **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. |
+| **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检” | `references/diagnose.md` | `solution-cli doctor` / `sensecraft-engine device scan` | Freeze hardware requirements into DeploymentLockfile before proceeding to apply. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy --solution <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. |
+| **TROUBLESHOOTING**<br>“部署报错”、“黑屏”、“无视频流” | `references/error-catalog.md` | `sensecraft-engine logs` / `solution-cli product verify-compatibility` | Max 3 fix-and-retry rounds. Follow local auto-patching rule. |
+
+Capabilities that need the **SenseCraft Solution desktop app** (editing a
+solution's configuration, the app's `/api/ai/context`, diagnosing through the
+app's logs) are in `references/app-only.md`. Use them only when the user has
+the app running.
+
+## Host platform boundary
+
+The standalone engine supports four host platforms: macOS ARM
+(`aarch64-apple-darwin`), Linux ARM (`aarch64-unknown-linux-musl`), Linux
+x86_64 (`x86_64-unknown-linux-musl`), and Windows x86_64
+(`x86_64-pc-windows-msvc`). macOS x86_64 is not maintained; under Rosetta,
+run the installer from a native ARM shell.
+
+`docker_deploy` target `local` requires a supported Docker host. Windows native
+`docker_local` is intentionally unsupported by both the Python and Rust
+deployers; a Windows CLI can still use a `remote` target over SSH to a Linux
+Docker host. WSL uses the Linux engine binary and Linux host behavior; do not
+describe a WSL run as Windows-native local Docker support. USB device steps
+remain hardware-dependent and require the user to connect and confirm the
+device.
+
+On macOS, local Docker uses the literal `docker` command found by the engine's
+process environment. If Docker Desktop's CLI is only inside its application
+bundle, start a new engine process with a temporary `PATH` containing that
+bundle's `bin` directory; do not change global shell configuration or assume an
+existing engine daemon inherits the new path. Verify the new engine instance
+with `doctor --json` before selecting a local target. A running Docker Desktop
+daemon is a host prerequisite, not evidence that a deployment has passed.
+
+## Rules
+
+1. **Credentials and secrets:** never invent a host, username or password —
+   ask the user. Replace passwords, tokens, API keys and any other secret a
+   deployment prints (for example a gateway token) with `<REDACTED>` in
+   anything you show or log. Tell the user where to find the value (on the
+   device, in the solution's page, in the file that holds it) instead of
+   printing it.
+2. **What you may do without asking, and what needs the user's OK:**
+
+   | Action | Ask first? |
+   |---|---|
+   | Read deployment status and logs (`status`, `logs`), engine log files, `doctor`, `device list/ports/scan` | No |
+   | Read-only checks on a device over SSH (`docker ps`, `docker logs`, `df -h`, `ss -ltnp`, `ping`) | No |
+   | Edit the solution's edit copy (desktop app only, see `references/app-only.md`) | No — show the diff afterwards; the user sees it in the app as "locally modified" and can restore the official version in one click |
+   | Anything a person does with their hands: plug in or swap a cable, connect a servo, sit in front of a camera, walk across a counting line, move or stand near a robot arm | **Yes** — tell the user what to do and wait for them to confirm it is done |
+   | Commands that move hardware (`robot torque`, `robot actions test`) | **Yes** — the user confirms nobody is within reach first |
+   | Change anything on a device: stop/remove containers, delete files, install packages, change system settings; `--replace-existing` | **Yes** |
+   | Redeploy | First retry: no. Every later retry: **yes** |
+   | Cancel a running deployment | **Yes** — it can leave a device half-configured |
+   | Prepare an issue report (the user submits it) or open a pull request | **Yes** |
+
+3. **At most 3 fix-and-retry rounds** per problem for deterministic failures
+   (wrong parameter, missing file, port taken, bad credentials, a container
+   that exits). After that, stop and give the user a report (what failed, what
+   you checked, what you changed). Transient registry or network errors follow
+   the backoff rule in `references/deploy.md` §6 and do not use up a round.
+4. **Preserving official cache & Local auto-patching**: Never edit files directly under the official content cache directory (`~/.sensecraft/content/`). When fixing a solution-level bug (timeout too short, wrong port/env var, minor syntax/transfer glitch, broken health check):
+   - In CLI / Engine mode: copy the solution from `~/.sensecraft/content/solutions/<id>` into `./.sensecraft-work/solutions/<id>`, apply the minimal fix in that copy. **Crucial engine switch step**: Because an existing engine daemon instance retains its initial solution directory in memory, you MUST stop the running instance first: `sensecraft-engine daemon stop`. Then re-run deployment with `--solutions-dir ./.sensecraft-work/solutions` so the fresh engine instance picks up the patched files. Show the user the patch diff.
+   - If running with the Desktop App: use the app's edit copy mechanism (`references/app-only.md` §4).
+5. **Reading output:** read the CLI's JSON output directly; it is small. If a
+   filter is needed, use `jq` only when it is already installed. Do not start
+   python, node or any other interpreter to parse output. Where a command has
+   a flag that prints just what you need (`--json`, `--preset`, `--device`,
+   `--since`), use it.
+6. **Temp files:** keep request bodies and scratch files in the current
+   working directory under `./.sensecraft-work/`, never in `/tmp`. Remove the
+   directory when the task ends, also after a failure.
+
+## Step 0 — Install the engine and the solutions (every task)
+
+1. Check whether it is installed: `sensecraft-engine --version`. If the command
+   is not found, also try `~/.sensecraft/bin/sensecraft-engine --version`
+   (Windows: `%USERPROFILE%\.sensecraft\bin\sensecraft-engine.cmd`); the
+   installer puts it there and prints the `PATH` line to add.
+2. Before running an installer, check its local prerequisites. On Unix run
+   `command -v curl || command -v wget`, `command -v sha256sum || command -v shasum`,
+   `command -v tar`, `command -v jq`, and `command -v minisign`. If wget is the
+   selected downloader, also require `wget --help | grep -- --compression` to
+   succeed; otherwise stop because the CDN may return gzip content. On Windows
+   PowerShell run `Get-Command irm`, `Get-Command Invoke-WebRequest`,
+   `Get-Command Expand-Archive`, `Get-Command ConvertFrom-Json`, and
+   `Get-Command minisign`. Windows uses PowerShell/.NET ZIP and JSON support;
+   it does not require `tar` or `jq`. If any check fails, report the missing
+   command and stop; do not install packages or start another interpreter.
+   `minisign` is required to verify the signed release manifest; Unix `jq` is
+   required by the shell installer to read it.
+3. Not installed → install it together with the solutions (ask the user first,
+   it downloads a program):
+
+   **Recommended (Zero-friction via solution-cli, auto-detects existing app & agents)**:
+   ```bash
+   npx @seeed-studio/solution-cli install -y
+   ```
+
+   **Fallback (Standalone shell script when Node.js is not present)**:
+   ```bash
+   curl --compressed -fsSL https://sensecraft-statics.seeed.cc/solution-app/engine/install.sh | sh -s -- --with-content
+   ```
+
+   If `curl` is unavailable but `wget` passed the prerequisite check, use the
+   equivalent command:
+
+   ```
+   wget --compression=auto -qO- https://sensecraft-statics.seeed.cc/solution-app/engine/install.sh | sh -s -- --with-content
+   ```
+
+   Windows PowerShell:
+
+   ```
+   & ([scriptblock]::Create((irm https://sensecraft-statics.seeed.cc/solution-app/engine/install.ps1))) -WithContent
+   ```
+
+4. Solutions are downloaded separately from the engine:
+
+   | Command | Does |
+   |---|---|
+   | `sensecraft-engine content status --offline --json` | Reads the local content store only; an empty store is a normal result with `installed: 0` and exit code 0 |
+   | `sensecraft-engine content status --json` | Compares local solutions with the online list |
+   | `sensecraft-engine content pull` | Downloads every solution (first run), or only `--solution <id>` |
+   | `sensecraft-engine content update` | Re-downloads installed solutions that changed online |
+
+   Run the offline status check before deciding whether content is installed.
+   If it returns exit code 0 with `installed: 0`, run `content pull`; do not
+   treat that status result as an error. A solution query such as `solution
+   list` or `deploy-info` exits with code 3 when no usable resource/solution
+   directory is available and tells you to run `content pull`. If a usable
+   directory exists but the requested solution ID is unknown, the query exits
+   with code 2. After `content pull` / `update`, if an engine instance is
+   already running it keeps the solutions it loaded at start: run
+   `sensecraft-engine daemon stop` when no deployment is running.
+5. Device pre-checks on this computer: `sensecraft-engine doctor --json`. Each
+   check has `status` (`ok` / `warn` / `fail`) and a `fix` command. Show the
+   user any `fail` and its `fix`; running a `fix` changes this computer and
+   needs their OK.
+
+Use `--lang zh` on commands that take `--lang` when the user writes in Chinese,
+`--lang en` otherwise.
+
+## Exit codes (all commands)
+
+| Code | Meaning | Next step |
+|---|---|---|
+| 0 | Success / accepted | Continue |
+| 1 | Deployment failed, cancelled or interrupted; for `counting` / `face` / `wizard` / `robot`: the device did not confirm | `references/diagnose.md` |
+| 2 | Invalid arguments or request. A `missing_params` error includes `missing[]`; an unknown ID or malformed JSON is also code 2 and may have no `missing[]` | Ask for each field only when `missing[]` is present; otherwise inspect the ID, JSON shape and parameter spelling, then correct or ask for the specific value |
+| 3 | Environment or conflict: a solution query has no usable resource/solution directory (`content pull`), device busy with another deployment (409), engine instance shutting down or incompatible, serial port busy | Read the message; pull content or fix the environment, then run again. An empty `content status --offline` store is exit 0, not this case |
+| 4 | This step needs the desktop app (deployer not in the engine) | Tell the user to deploy this solution from the SenseCraft Solution app |
+| 5 | Internal engine error | Engine bug: `references/diagnose.md` §6 |
+
+## Pick the task
+
+| The user wants to... | Read |
+|---|---|
+| Deploy a solution | `references/deploy.md` |
+| Finish a step that reported `verify_required` (dashboards, counting lines, face enrollment, servo setup, robot arm) | `references/verify.md` |
+| Find out why a deployment failed or a deployed solution misbehaves | `references/diagnose.md` |
+| Deploy on a site without internet (prepare an offline package first) | `references/offline.md` |
+| Change a solution's configuration, or use the desktop app's API | `references/app-only.md` (requires the desktop app) |
+
+They connect: **a failed deployment goes straight to `diagnose.md`** without
+stopping to ask; a `verify_required` event goes to `verify.md`; the retry goes
+back to `deploy.md` for the failed device only.

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.