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

package/lib/ledger.js

@@ -0,0 +1,302 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import { getScHome } from './platform.js';
+
+export function getLedgerPath() {
+  return path.join(getScHome(), 'skills-ledger.json');
+}
+
+export function getLockPath() {
+  return path.join(getScHome(), '.skills.lock');
+}
+
+export function withLedgerLock(fn) {
+  const lockFile = getLockPath();
+  const dir = path.dirname(lockFile);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const maxAttempts = 60;
+  let attempts = 0;
+  let fd = null;
+
+  while (attempts++ < maxAttempts) {
+    try {
+      fd = fs.openSync(lockFile, 'wx');
+      // Record PID and timestamp into lock file
+      fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, time: Date.now() }), 'utf8');
+      break;
+    } catch {
+      // Check if lock is stale or holder process is dead
+      try {
+        const raw = fs.readFileSync(lockFile, 'utf8');
+        const lockInfo = JSON.parse(raw);
+        let isDead = false;
+
+        if (lockInfo && lockInfo.pid) {
+          try {
+            // Check if process exists: kill(0) throws ESRCH if process is dead
+            process.kill(lockInfo.pid, 0);
+          } catch (err) {
+            if (err.code === 'ESRCH') {
+              isDead = true;
+            }
+          }
+        }
+
+        // Break stale lock only if process is dead or older than 60s
+        if (isDead || (Date.now() - lockInfo.time > 60000)) {
+          fs.unlinkSync(lockFile);
+          continue;
+        }
+      } catch {}
+
+      // Sleep 100ms synchronously
+      const end = Date.now() + 100;
+      while (Date.now() < end) {}
+    }
+  }
+
+  if (fd === null) {
+    throw new Error('Could not acquire installation lock; another SenseCraft operation may be running.');
+  }
+
+  try {
+    return fn();
+  } finally {
+    try { fs.closeSync(fd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+export function loadLedger() {
+  const ledgerPath = getLedgerPath();
+  if (!fs.existsSync(ledgerPath)) {
+    return {
+      schema_version: 1,
+      installations: {}
+    };
+  }
+  try {
+    const raw = fs.readFileSync(ledgerPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || !parsed.installations) {
+      throw new Error('Malformed skills ledger JSON schema');
+    }
+    return parsed;
+  } catch (err) {
+    throw new Error(`Corrupted skills ledger at ${ledgerPath}: ${err.message}. Please inspect or backup.`);
+  }
+}
+
+export function saveLedger(ledger) {
+  const ledgerPath = getLedgerPath();
+  const dir = path.dirname(ledgerPath);
+  fs.mkdirSync(dir, { recursive: true });
+
+  const tempFile = path.join(dir, `.skills-ledger.tmp-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`);
+  fs.writeFileSync(tempFile, JSON.stringify(ledger, null, 2), 'utf8');
+  fs.renameSync(tempFile, ledgerPath);
+}
+
+export function computeFileHash(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+// Ensure target file stays strictly inside targetDir, refusing symlink escapes (Codex High 2 & P2)
+export function isSafePathInside(childPath, parentDir) {
+  try {
+    const parentReal = fs.realpathSync(parentDir);
+
+    // Codex P2: Detect symlinks even if target does not exist yet (dangling symlinks)
+    const lstat = fs.lstatSync(childPath, { throwIfNoEntry: false });
+    if (lstat && lstat.isSymbolicLink()) {
+      const linkTarget = fs.readlinkSync(childPath);
+      const resolved = path.resolve(path.dirname(childPath), linkTarget);
+      if (!fs.existsSync(resolved)) {
+        return false; // Reject dangling symlink destination
+      }
+      const targetReal = fs.realpathSync(resolved);
+      const relTarget = path.relative(parentReal, targetReal);
+      return !relTarget.startsWith('..') && !path.isAbsolute(relTarget);
+    }
+
+    // If child exists, verify its realpath
+    if (fs.existsSync(childPath)) {
+      const childReal = fs.realpathSync(childPath);
+      const rel = path.relative(parentReal, childReal);
+      return !rel.startsWith('..') && !path.isAbsolute(rel);
+    }
+    // If child doesn't exist yet, verify its nearest existing ancestor
+    let cur = path.resolve(childPath);
+    while (cur !== path.dirname(cur)) {
+      if (fs.existsSync(cur)) {
+        const curReal = fs.realpathSync(cur);
+        const rel = path.relative(parentReal, curReal);
+        return !rel.startsWith('..') && !path.isAbsolute(rel);
+      }
+      cur = path.dirname(cur);
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+export function checkFileModifications(targetDir, filesMap) {
+  const modified = [];
+  const missing = [];
+  const intact = [];
+
+  for (const [relPath, recordedHash] of Object.entries(filesMap || {})) {
+    if (relPath.includes('..') || path.isAbsolute(relPath)) {
+      continue;
+    }
+    const fullPath = path.join(targetDir, relPath);
+    if (!isSafePathInside(fullPath, targetDir)) {
+      continue;
+    }
+
+    if (!fs.existsSync(fullPath)) {
+      missing.push(relPath);
+    } else {
+      const currentHash = computeFileHash(fullPath);
+      if (currentHash !== recordedHash) {
+        modified.push(relPath);
+      } else {
+        intact.push(relPath);
+      }
+    }
+  }
+
+  return { modified, missing, intact };
+}
+
+export function recordInstallation(agentId, skillsDir, targetDir, skillVersion, filesMap) {
+  const ledger = loadLedger();
+  ledger.installations = ledger.installations || {};
+
+  ledger.installations[agentId] = {
+    agent_id: agentId,
+    skills_dir: path.resolve(skillsDir),
+    target_dir: path.resolve(targetDir),
+    skill_version: skillVersion,
+    installed_at: new Date().toISOString(),
+    files: filesMap
+  };
+
+  ledger.last_updated = new Date().toISOString();
+  saveLedger(ledger);
+}
+
+export function removeInstallation(agentId, options = {}) {
+  const { force = false, dryRun = false } = options;
+  const runWithLock = dryRun ? fn => fn() : withLedgerLock;
+
+  return runWithLock(() => {
+    const ledger = loadLedger();
+
+    if (!ledger.installations || !ledger.installations[agentId]) {
+      return { success: false, reason: `No tracked installation found for agent "${agentId}".` };
+    }
+
+  const record = ledger.installations[agentId];
+  const targetDir = path.resolve(record.target_dir);
+
+  if (!fs.existsSync(targetDir)) {
+    if (!dryRun) {
+      delete ledger.installations[agentId];
+      saveLedger(ledger);
+    }
+    return { success: true, message: 'Target directory already absent. Cleaned ledger record.' };
+  }
+
+  const files = record.files || {};
+  let removedCount = 0;
+  let preservedCount = 0;
+  const actions = [];
+
+  for (const [relPath, recordedHash] of Object.entries(files)) {
+    if (relPath.includes('..') || path.isAbsolute(relPath)) {
+      continue;
+    }
+    const fullPath = path.join(targetDir, relPath);
+
+    // Verify safe path inside targetDir (Codex High 2: Prevent symlink escape)
+    if (!isSafePathInside(fullPath, targetDir)) {
+      actions.push({ file: fullPath, action: 'skip_symlink_escape' });
+      continue;
+    }
+
+    if (fs.existsSync(fullPath)) {
+      const currentHash = computeFileHash(fullPath);
+      if (currentHash === recordedHash || force) {
+        actions.push({ file: fullPath, action: 'delete' });
+        if (!dryRun) {
+          fs.unlinkSync(fullPath);
+        }
+        removedCount++;
+      } else {
+        actions.push({ file: fullPath, action: 'preserve_modified' });
+        preservedCount++;
+      }
+    }
+  }
+
+  // Remove marker file
+  const marker = path.join(targetDir, '.installed-by-sensecraft');
+  if (fs.existsSync(marker) && isSafePathInside(marker, targetDir)) {
+    actions.push({ file: marker, action: 'delete_marker' });
+    if (!dryRun) {
+      try { fs.unlinkSync(marker); } catch {}
+    }
+  }
+
+  if (!dryRun) {
+    cleanEmptyDirs(targetDir);
+    try {
+      if (fs.existsSync(targetDir) && fs.readdirSync(targetDir).length === 0) {
+        fs.rmdirSync(targetDir);
+      }
+    } catch {}
+
+    delete ledger.installations[agentId];
+    saveLedger(ledger);
+  }
+
+    return {
+      success: true,
+      removedCount,
+      preservedCount,
+      targetDir,
+      dryRun,
+      actions
+    };
+  });
+}
+
+function cleanEmptyDirs(dir) {
+  if (!fs.existsSync(dir)) return;
+  // Don't clean inside external symlinks
+  try {
+    const stat = fs.lstatSync(dir);
+    if (stat.isSymbolicLink()) return;
+  } catch {
+    return;
+  }
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && !entry.isSymbolicLink()) {
+      const sub = path.join(dir, entry.name);
+      cleanEmptyDirs(sub);
+      try {
+        if (fs.readdirSync(sub).length === 0) {
+          fs.rmdirSync(sub);
+        }
+      } catch {}
+    }
+  }
+}

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,53 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.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",
+    "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,176 @@
+---
+name: sensecraft
+description: Deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) on hardware devices (NVIDIA Jetson, Raspberry Pi 树莓派, reComputer, reCamera, SenseCAP Watcher, Grove Vision AI, ESP32) using the `sensecraft-engine` command-line engine (no desktop app needed). Use whenever the user asks to deploy (部署), install (安装方案), test, inspect, or troubleshoot a SenseCraft edge IoT solution or configure devices and sensors. Changing a solution's configuration needs the desktop app (references/app-only.md).
+---
+
+# SenseCraft Solution
+
+This skill drives the `sensecraft-engine` command-line engine. It works in any
+agent that can read files and run shell commands. Every step is a
+`sensecraft-engine` command; the engine starts its own background instance when
+a command needs one. Do not call the instance's HTTP port with `curl`: use the
+CLI, and `sensecraft-engine api <METHOD> <path>` for anything without its own
+command.
+
+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.