@seeed-studio/solution-cli 0.3.0 → 0.3.2

package/docs/cli-guide.md

@@ -30,37 +30,78 @@
 `@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
 1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
 2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
-3. **AI Agent 的物理世界触手**：一键将 SenseCraft Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+3. **AI Agent 的物理世界触手**：一键将 solution-cli Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
 
 ---
 
 ## 2. 安装与 Agent 技能挂载
 
 ### 2.1 一键免安装即时调用 (推荐)
-无需全局安装，利用 `npx` 即可随时调用：
+无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
 ```bash
-# 查看帮助与版本
-npx @seeed-studio/solution-cli --help
-
-# 交互式扫描并为本机所有 Agent 安装技能
-npx @seeed-studio/solution-cli install
+npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
 ```
 
+上面的示例明确安装到 WorkBuddy。其他宿主将 `workbuddy` 替换为当前实际的
+Agent ID。需要交互选择时使用 `npx -y @seeed-studio/solution-cli@latest install`；
+检测到一个或多个 Agent 时，直接回车默认选择全部已检测的 Agent，输入对应序号
+选择指定宿主。非交互模式下，`install -y` 未提供 `--agent` 且检测到 Agent 时也会
+选择全部已检测的 Agent。未检测到 Agent 时，这些默认仍使用 CLI 的默认目标集合；
+需要明确控制范围时请提供 `--agent <agent-id>`。
+
+首次安装和重复执行都会检查签名稳定版 Engine：本机已有相同或更新版本
+时复用，版本较旧时升级。普通安装保留用户修改、未登记的 Skill 文件和受
+保护的符号链接。需要指定宿主时追加 `--agent claude,antigravity`；需要固
+定有效本地 Engine 时使用 `--engine-path <path>`。`--force` 可重新下载相同
+或较旧版本并覆盖已有 Skill 文件（包括用户修改），请只在有意覆盖时使用；
+受保护的外部符号链接不会追写，也不能降级更新的本机 Engine。
+
+自动复用/升级规则自 solution-cli 0.3.1 起生效；该版本已公开发布。latest 检查或签名校验失败会在
+修改 Engine、指针或 Skill 前停止；离线时请提供有效的 `--engine-path`。
+
+The same command handles a fresh install and a user-requested upgrade. It checks
+the signed stable Engine, reuses an equal/newer local version, preserves modified
+skills, and stops before writes on latest/signature failure. Automatic reuse and
+upgrade rules start with publicly published solution-cli 0.3.1. The example
+targets WorkBuddy with `--agent workbuddy`; replace it with the current Agent ID
+for another host. Use `npx -y @seeed-studio/solution-cli@latest install` for the
+interactive form: when one or more Agents are detected, pressing Enter selects
+all detected Agents, while entering a number selects one host. In non-interactive
+mode, `install -y` without `--agent` also selects all detected Agents when any
+are detected. If none are detected, these defaults still use the CLI's default
+target set; pass `--agent <agent-id>` to control the scope explicitly.
+
 ### 2.2 全局安装
 ```bash
 npm install -g @seeed-studio/solution-cli
+solution-cli install --agent workbuddy -y
 ```
 
+全局安装后的挂载规则相同：示例明确选择 WorkBuddy；其他宿主请将
+`workbuddy` 替换为当前实际 Agent ID。交互执行 `solution-cli install` 时，
+检测到一个或多个 Agent 后直接回车选择全部已检测的 Agent，输入对应序号选择指定
+宿主；非交互执行 `solution-cli install -y` 且未提供 `--agent` 时，检测到 Agent
+也会选择全部已检测的 Agent。未检测到 Agent 时，这些默认仍使用 CLI 的默认目标集合；
+需要明确控制范围时请提供 `--agent <agent-id>`。
+
+The global command targets WorkBuddy explicitly. Replace `workbuddy` with the
+current Agent ID for another host. Interactive `solution-cli install` selects all
+detected Agents on Enter when any are detected, or one host by number;
+non-interactive `solution-cli install -y` without `--agent` also selects all
+detected Agents when any are detected. If none are detected, these defaults still
+use the CLI's default target set; pass `--agent <agent-id>` to control the scope
+explicitly.
+
 ### 2.3 跨 Agent 平台技能挂载
-执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `sensecraft` Skill 和全套参考手册安全复制到对应目录：
+执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `solution-cli` Skill 和全套参考手册安全复制到对应目录：
 
 | Agent 宿主平台 | 技能默认配置路径 | 支持能力 |
 |---|---|---|
-| **Claude Code** | `~/.claude/skills/sensecraft` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
-| **Codex (OpenAI)** | `~/.agents/skills/sensecraft` 或 `~/.codex/skills/sensecraft` | 代码审查、参数重构、二次开发自动化 |
-| **Google Antigravity (AGY)** | `~/.gemini/config/skills/sensecraft` | 端到端自主诊断、多 Agent 协同实施 |
-| **Work Buddy / Workbody** | `~/.workbuddy/skills/sensecraft` | 桌面端交互、方案展示、一键部署联动 |
-| **CodeBuddy** | `~/.codebuddy/skills/sensecraft` | 代码库配对开发与自研模型构建 |
+| **Claude Code** | `~/.claude/skills/solution-cli` | 完整方案咨询、工况诊断、BOM 生成、现场部署 |
+| **Codex (OpenAI)** | `~/.agents/skills/solution-cli` 或 `~/.codex/skills/solution-cli` | 代码审查、参数重构、二次开发自动化 |
+| **Google Antigravity (AGY)** | `~/.gemini/config/skills/solution-cli` | 端到端自主诊断、多 Agent 协同实施 |
+| **Work Buddy / Workbody** | `~/.workbuddy/skills/solution-cli` | 桌面端交互、方案展示、一键部署联动 |
+| **CodeBuddy** | `~/.codebuddy/skills/solution-cli` | 代码库配对开发与自研模型构建 |
 
 **非交互式多选安装示例**：
 ```bash
@@ -100,11 +141,11 @@ solution-cli hub search "跌倒检测" --json
      把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
      预设模式: cloud, tts_local, chirpstack_local
      现场工况诊断提问指引:
-       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？ 
+       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？
          (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
-       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？ 
+       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？
          (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
-       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？ 
+       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？
          (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
 ```
 
@@ -209,7 +250,7 @@ solution-cli product accessories recomputer_j40 --json
 4. **驱动本地快速联调**：
    使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
    ```bash
-   sensecraft-engine deploy --solution fall_detection --solutions-dir ./my-solutions/solutions
+   sensecraft-engine deploy fall_detection --solutions-dir ./my-solutions/solutions
    ```
 
 ---

package/lib/agent.js

@@ -15,8 +15,8 @@ export function getKnownAgents() {
         // Check where an existing installation might already be
         const p1 = path.join(home, '.workbuddy', 'skills');
         const p2 = path.join(home, '.workbody', 'skills');
-        if (fs.existsSync(path.join(p1, 'sensecraft', 'SKILL.md'))) return p1;
-        if (fs.existsSync(path.join(p2, 'sensecraft', 'SKILL.md'))) return p2;
+        if (fs.existsSync(path.join(p1, 'solution-cli', 'SKILL.md'))) return p1;
+        if (fs.existsSync(path.join(p2, 'solution-cli', 'SKILL.md'))) return p2;
         if (fs.existsSync(path.join(home, '.workbuddy'))) return p1;
         if (fs.existsSync(path.join(home, '.workbody'))) return p2;
         return p1;
@@ -36,8 +36,8 @@ export function getKnownAgents() {
         // Honor existing installation first to avoid path drift (Codex Medium 13)
         const pAgents = path.join(home, '.agents', 'skills');
         const pCodex = path.join(home, '.codex', 'skills');
-        if (fs.existsSync(path.join(pAgents, 'sensecraft', 'SKILL.md'))) return pAgents;
-        if (fs.existsSync(path.join(pCodex, 'sensecraft', 'SKILL.md'))) return pCodex;
+        if (fs.existsSync(path.join(pAgents, 'solution-cli', 'SKILL.md'))) return pAgents;
+        if (fs.existsSync(path.join(pCodex, 'solution-cli', 'SKILL.md'))) return pCodex;
         // Default to .agents/skills if .agents exists, otherwise .codex/skills if .codex exists
         if (fs.existsSync(path.join(home, '.agents'))) return pAgents;
         if (fs.existsSync(path.join(home, '.codex'))) return pCodex;
@@ -69,7 +69,7 @@ export function scanLocalAgents() {
   return agents.map(a => {
     const skillsDir = a.getSkillsDir();
     const detected = a.homeDirs.some(dir => fs.existsSync(dir)) || fs.existsSync(skillsDir);
-    const installed = fs.existsSync(path.join(skillsDir, 'sensecraft', 'SKILL.md'));
+    const installed = fs.existsSync(path.join(skillsDir, 'solution-cli', 'SKILL.md'));
     return {
       ...a,
       detected,

package/lib/detector.js

@@ -226,7 +226,7 @@ export function detectDesktopApp() {
         appPath: appBase,
         binPath: path.join(appBase, 'Contents', 'MacOS', 'sensecraft-engine'),
         solutionsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'solutions'),
-        skillsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'skills', 'sensecraft')
+        skillsPath: path.join(appBase, 'Contents', 'Resources', '_up_', 'sensecraft-solutions', 'skills', 'solution-cli')
       });
       const cacheBin = path.join(
         os.homedir(),
@@ -258,7 +258,7 @@ export function detectDesktopApp() {
           appPath,
           binPath: path.join(appPath, 'resources', 'bin', 'sensecraft-engine.exe'),
           solutionsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'solutions'),
-          skillsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'skills', 'sensecraft')
+          skillsPath: path.join(appPath, 'resources', 'sensecraft-solutions', 'skills', 'solution-cli')
         });
       }
     }
@@ -271,7 +271,7 @@ export function detectDesktopApp() {
           appPath,
           binPath: path.join(appPath, 'sensecraft-engine'),
           solutionsPath: path.join(appPath, 'sensecraft-solutions', 'solutions'),
-          skillsPath: path.join(appPath, 'skills', 'sensecraft')
+          skillsPath: path.join(appPath, 'skills', 'solution-cli')
         });
       }
     }

package/lib/downloader.js

@@ -4,13 +4,41 @@ import fs from 'node:fs';
 import crypto from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { getPlatformInfo, getEngineBinDir, getEngineBinaryPath, getScHome } from './platform.js';
-import { verifyEngineBinary } from './detector.js';
+import { verifyEngineBinary, parseSemver } from './detector.js';
 
 const LATEST_MANIFEST_URL = 'https://sensecraft-statics.seeed.cc/solution-app/engine/latest.json';
+const VERSIONED_MANIFEST_BASE_URL = 'https://sensecraft-statics.seeed.cc/solution-app/engine';
 const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024; // 50MB limit
 const NETWORK_TIMEOUT_MS = 60000; // 60s timeout
 
 export const PINNED_MINISIGN_PUBKEY = 'RWTg282IuJHsoMOFZC0DP1q0LrS384gJsCLrXyX3CIzIKLPUHm3GGmBv';
+const verifiedReleases = new WeakSet();
+
+function deepFreeze(value) {
+  if (!value || typeof value !== 'object' || Object.isFrozen(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+export function validateReleaseManifest(manifest, platform) {
+  if (!manifest || typeof manifest !== 'object') throw new Error('Engine release manifest is not an object');
+  if (manifest.channel !== 'stable') throw new Error(`Engine release manifest channel must be stable (got ${manifest.channel || 'missing'})`);
+  const version = manifest.version;
+  const parsedVersion = parseSemver(version);
+  if (!parsedVersion || parsedVersion.raw !== version || parsedVersion.prerelease) {
+    throw new Error(`Engine release manifest contains an invalid release version: ${version || 'missing'}`);
+  }
+  const asset = manifest.assets?.[platform.target];
+  let assetUrl;
+  try { assetUrl = new URL(asset?.url); } catch {}
+  if (!asset || typeof asset !== 'object' || typeof asset.url !== 'string' || assetUrl?.protocol !== 'https:' || !/^[a-f0-9]{64}$/i.test(asset.sha256 || '')) {
+    throw new Error(`No valid compatible release asset found for target "${platform.target}" in version ${version}`);
+  }
+  if (asset.size !== undefined && (!Number.isInteger(asset.size) || asset.size <= 0 || asset.size > MAX_ARCHIVE_BYTES)) {
+    throw new Error(`Declared asset size (${asset.size} bytes) is invalid or exceeds safety maximum (${MAX_ARCHIVE_BYTES} bytes)`);
+  }
+  return manifest;
+}
 
 export function verifyManifestSignature(manifestBytes, sigText, pubKeyB64 = PINNED_MINISIGN_PUBKEY) {
   try {
@@ -30,20 +58,30 @@ export function verifyManifestSignature(manifestBytes, sigText, pubKeyB64 = PINN
   }
 }
 
-export async function fetchManifest() {
+export async function fetchManifest({ version } = {}) {
+  let manifestUrl = LATEST_MANIFEST_URL;
+  if (version !== undefined) {
+    const parsedVersion = parseSemver(version);
+    if (!parsedVersion || parsedVersion.raw !== version || parsedVersion.prerelease) {
+      throw new Error(`Invalid stable Engine release version requested: ${version}`);
+    }
+    manifestUrl = `${VERSIONED_MANIFEST_BASE_URL}/${version}/manifest.json`;
+  }
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), 15000);
+  let requestUrl = manifestUrl;
   try {
-    const res = await fetch(LATEST_MANIFEST_URL, { signal: controller.signal });
+    const res = await fetch(requestUrl, { signal: controller.signal });
     if (!res.ok) {
-      throw new Error(`Failed to fetch engine manifest from ${LATEST_MANIFEST_URL}: HTTP ${res.status}`);
+      throw new Error(`Failed to fetch engine manifest from ${manifestUrl}: HTTP ${res.status}`);
     }
     const manifestBytes = Buffer.from(await res.arrayBuffer());
 
     // Fetch and verify detached signature (Codex P1)
-    const sigRes = await fetch(`${LATEST_MANIFEST_URL}.minisig`, { signal: controller.signal });
+    requestUrl = `${manifestUrl}.minisig`;
+    const sigRes = await fetch(requestUrl, { signal: controller.signal });
     if (!sigRes.ok) {
-      throw new Error(`Failed to fetch manifest signature from ${LATEST_MANIFEST_URL}.minisig: HTTP ${sigRes.status}`);
+      throw new Error(`Failed to fetch manifest signature from ${manifestUrl}.minisig: HTTP ${sigRes.status}`);
     }
     const sigText = await sigRes.text();
     const isSigValid = verifyManifestSignature(manifestBytes, sigText);
@@ -51,7 +89,24 @@ export async function fetchManifest() {
       throw new Error('Engine manifest signature verification failed against trusted Seeed public key');
     }
 
-    return JSON.parse(manifestBytes.toString('utf8'));
+    let manifest;
+    try { manifest = JSON.parse(manifestBytes.toString('utf8')); } catch (err) {
+      throw new Error(`Engine release manifest is not valid JSON: ${err.message}`);
+    }
+    if (version !== undefined && manifest.version !== version) {
+      throw new Error(`Versioned Engine manifest mismatch: requested ${version}, received ${manifest.version || 'missing'}`);
+    }
+    const release = deepFreeze(manifest);
+    verifiedReleases.add(release);
+    return release;
+  } catch (err) {
+    if (err?.name === 'AbortError' || err?.name === 'TypeError') {
+      throw new Error(
+        `Unable to fetch Engine release metadata/signature from ${requestUrl}. Check CDN network connectivity and retry, or use a valid --engine-path.`,
+        { cause: err }
+      );
+    }
+    throw err;
   } finally {
     clearTimeout(timeout);
   }
@@ -65,17 +120,14 @@ export async function downloadEngine(options = {}) {
     throw new Error(`Cannot download engine: ${platform.note}`);
   }
 
-  onProgress('Fetching latest release manifest...');
-  const manifest = await fetchManifest();
-  const asset = manifest.assets ? manifest.assets[platform.target] : null;
-
-  if (!asset || !asset.url || !asset.sha256) {
-    throw new Error(`No compatible release asset found for target "${platform.target}" in version ${manifest.version}`);
-  }
-
-  if (asset.size && asset.size > MAX_ARCHIVE_BYTES) {
-    throw new Error(`Declared asset size (${asset.size} bytes) exceeds safety maximum (${MAX_ARCHIVE_BYTES} bytes)`);
+  let manifest = options.release;
+  if (manifest === undefined) {
+    onProgress('Fetching latest release manifest...');
+    manifest = await fetchManifest();
   }
+  if (!verifiedReleases.has(manifest)) throw new Error('Engine release metadata was not verified by the trusted manifest flow');
+  validateReleaseManifest(manifest, platform);
+  const asset = manifest.assets[platform.target];
 
   onProgress(`Downloading sensecraft-engine v${manifest.version}...`);
   const controller = new AbortController();
@@ -113,6 +165,10 @@ export async function downloadEngine(options = {}) {
     clearTimeout(timeout);
   }
 
+  if (asset.size !== undefined && buffer.length !== asset.size) {
+    throw new Error(`Downloaded archive size ${buffer.length} bytes does not match signed manifest size ${asset.size} bytes`);
+  }
+
   onProgress('Verifying cryptographic SHA256 integrity...');
   const computedHash = crypto.createHash('sha256').update(buffer).digest('hex').toLowerCase();
   const expectedHash = asset.sha256.toLowerCase();
@@ -165,12 +221,20 @@ export async function downloadEngine(options = {}) {
     if (!verifyResult.valid) {
       throw new Error(`Downloaded engine verification failed: ${verifyResult.reason}`);
     }
+    if (verifyResult.version !== manifest.version) {
+      throw new Error(`Downloaded engine version ${verifyResult.version} does not match signed manifest version ${manifest.version}`);
+    }
 
     const finalBin = getEngineBinaryPath();
     const backupBin = path.join(binDir, `.backup-${platform.binaryName}-${nonce}`);
+    const hasEntry = filePath => Boolean(fs.lstatSync(filePath, { throwIfNoEntry: false }));
 
-    if (fs.existsSync(finalBin)) {
-      try { fs.renameSync(finalBin, backupBin); } catch {}
+    if (hasEntry(finalBin)) {
+      try {
+        fs.renameSync(finalBin, backupBin);
+      } catch (err) {
+        throw new Error(`Unable to back up existing Engine before swap: ${err.message}`);
+      }
     }
 
     try {
@@ -179,11 +243,11 @@ export async function downloadEngine(options = {}) {
       } else {
         fs.renameSync(stagedBin, finalBin);
       }
-      if (fs.existsSync(backupBin)) {
+      if (hasEntry(backupBin)) {
         try { fs.unlinkSync(backupBin); } catch {}
       }
     } catch (swapErr) {
-      if (fs.existsSync(backupBin)) {
+      if (hasEntry(backupBin)) {
         try { fs.renameSync(backupBin, finalBin); } catch {}
       }
       throw swapErr;

package/lib/installer.js

@@ -8,9 +8,9 @@ import {
   setConfiguredEnginePath,
   getConfiguredEnginePath
 } from './platform.js';
-import { detectExistingEngine, detectDesktopApp, verifyEngineBinary } from './detector.js';
-import { downloadEngine, pullSolutionContent } from './downloader.js';
-import { scanLocalAgents, promptAgentSelection } from './agent.js';
+import { detectExistingEngine, detectDesktopApp, verifyEngineBinary, compareSemver } from './detector.js';
+import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent } from './downloader.js';
+import { getKnownAgents, scanLocalAgents, promptAgentSelection } from './agent.js';
 import {
   recordInstallation,
   removeInstallation,
@@ -22,7 +22,31 @@ import {
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const BUNDLED_SKILLS_SRC = path.resolve(__dirname, '..', 'skills', 'sensecraft');
+const SKILL_DIR_NAME = 'solution-cli';
+const LEGACY_SKILL_DIR_NAME = 'sensecraft';
+const BUNDLED_SKILLS_SRC = path.resolve(__dirname, '..', 'skills', SKILL_DIR_NAME);
+
+function assertCanonicalSkillState(ledger, agents) {
+  const allAgents = agents;
+  const errors = [];
+
+  for (const agent of allAgents) {
+    const skillsDir = agent.skillsDir || agent.getSkillsDir();
+    const expectedTarget = path.resolve(path.join(skillsDir, SKILL_DIR_NAME));
+    const legacySkill = path.join(skillsDir, LEGACY_SKILL_DIR_NAME, 'SKILL.md');
+    if (fs.lstatSync(legacySkill, { throwIfNoEntry: false })) {
+      errors.push(`${agent.id} still has legacy skill at ${legacySkill}; run uninstall --agent ${agent.id} before installing solution-cli. If the file is untracked or remains after uninstall because it was modified, back it up and retire the legacy skill directory before retrying; user files are not removed automatically.`);
+    }
+    const record = ledger.installations?.[agent.id];
+    if (record && path.resolve(record.target_dir) !== expectedTarget) {
+      errors.push(`${agent.id} is managed at legacy target ${record.target_dir}; run uninstall --agent ${agent.id} before installing solution-cli`);
+    }
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Legacy SenseCraft skill state blocks canonical solution-cli installation:\n- ${errors.join('\n- ')}`);
+  }
+}
 
 export async function runInstall(options = {}) {
   const {
@@ -36,7 +60,7 @@ export async function runInstall(options = {}) {
   } = options;
 
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m');
-  logger('\x1b[1m\x1b[34m  SenseCraft Engine & AI Agent Skill Installer     \x1b[0m');
+  logger('\x1b[1m\x1b[34m  Solution CLI Installer                         \x1b[0m');
   logger('\x1b[1m\x1b[34m====================================================\x1b[0m\n');
 
   const platform = getPlatformInfo();
@@ -53,6 +77,9 @@ export async function runInstall(options = {}) {
     return { success: true, engineBin: null, installedAgents: [] };
   }
 
+  // Validate ownership and legacy targets before engine selection or pointer/download writes.
+  assertCanonicalSkillState(loadLedger(), selectedAgents);
+
   // --- Step 1: Detect & Verify Engine Candidate ---
   logger('🔍 Phase 1: Inspecting host environment for existing Engine/App...');
   let engineBin = null;
@@ -69,52 +96,40 @@ export async function runInstall(options = {}) {
     engineBin = resolvedPath;
     engineVersion = check.version;
     reusedSource = 'custom';
-  } else if (!force) {
-    // 1.1 Check default / PATH engine
+  } else {
+    // Discover every compatible local source before comparing with the signed stable release.
     const existing = detectExistingEngine();
-    if (existing) {
-      logger(`✔ Found existing compatible Engine v${existing.version} (${existing.path})`);
-      engineBin = path.resolve(existing.path);
-      engineVersion = existing.version;
-      reusedSource = existing.source;
-    } else {
-      // 1.2 Check Desktop App
-      const app = detectDesktopApp();
-      if (app.detected && app.compatible) {
-        logger(`✔ Found compatible SenseCraft Desktop App at: ${app.appPath || app.binPath}`);
-        logger(`  Engine binary inside App: ${app.binPath} (v${app.version})`);
-
-        const targetBin = path.resolve(getEngineBinaryPath());
-        if (!dryRun) {
-          fs.mkdirSync(path.dirname(targetBin), { recursive: true });
-          if (platform.isWindows) {
-            fs.copyFileSync(app.binPath, targetBin);
-          } else {
-            if (fs.existsSync(targetBin)) fs.unlinkSync(targetBin);
-            fs.symlinkSync(app.binPath, targetBin);
-          }
-          engineBin = targetBin;
-        } else {
-          engineBin = app.binPath;
-        }
-        engineVersion = app.version;
-        reusedSource = 'desktop_app';
-      } else if (app.detected && !app.compatible) {
-        logger(`ℹ Detected existing App but its engine is outdated/incompatible: ${app.reason}. Falling back to fresh engine download.`);
-      }
+    const app = detectDesktopApp();
+    const candidates = [];
+    if (existing) candidates.push({ ...existing, kind: 'local' });
+    if (app.detected && app.compatible) candidates.push({ ...app, path: app.binPath, kind: 'desktop_app' });
+    if (app.detected && !app.compatible) {
+      logger(`ℹ Detected existing App but its engine is outdated/incompatible: ${app.reason}`);
     }
-  }
-
-  // 1.3 If no compatible local candidate, download standalone binary
-  if (!engineBin) {
-    if (dryRun) {
-      logger('ℹ [dry-run] Would download standalone engine from CDN...');
+    candidates.sort((a, b) => compareSemver(b.version, a.version));
+    const selected = candidates[0] || null;
+
+    logger('🔐 Checking the signed stable Engine release manifest...');
+    const release = await fetchManifest();
+    validateReleaseManifest(release, platform);
+    const releaseVersion = release.version;
+    const selectedIsCurrent = selected && (compareSemver(selected.version, releaseVersion) > 0 ||
+      (compareSemver(selected.version, releaseVersion) === 0 && !force));
+
+    if (selectedIsCurrent) {
+      engineBin = path.resolve(selected.path);
+      engineVersion = selected.version;
+      reusedSource = selected.kind === 'desktop_app' ? 'desktop_app' : selected.source;
+      logger(`✔ Reusing highest compatible Engine v${engineVersion} (${engineBin}); signed stable is v${releaseVersion}`);
+    } else if (dryRun) {
       engineBin = path.resolve(getEngineBinaryPath());
-      engineVersion = '0.0.3';
+      engineVersion = releaseVersion;
       reusedSource = 'download';
+      logger(`ℹ [dry-run] Would ${selected ? `upgrade Engine v${selected.version} to` : 'download'} signed stable Engine v${releaseVersion} to ${engineBin}`);
     } else {
-      logger('⬇ Downloading latest standalone engine binary from CDN...');
+      logger(`⬇ ${selected ? `Upgrading Engine v${selected.version} to` : 'Downloading'} signed stable Engine v${releaseVersion} from CDN...`);
       const dl = await downloadEngine({
+        release,
         onProgress: msg => logger(`  ${msg}`)
       });
       engineBin = path.resolve(dl.path);
@@ -147,9 +162,10 @@ export async function runInstall(options = {}) {
 
   runWithLock(() => {
     const ledger = dryRun ? { installations: {} } : loadLedger();
+    assertCanonicalSkillState(ledger, selectedAgents);
 
     for (const a of selectedAgents) {
-      const destDir = path.resolve(path.join(a.skillsDir, 'sensecraft'));
+      const destDir = path.resolve(path.join(a.skillsDir, SKILL_DIR_NAME));
       logger(`\nConfiguring ${a.name} at: ${destDir}...`);
 
       if (dryRun) {
@@ -168,6 +184,21 @@ export async function runInstall(options = {}) {
 
       Object.assign(filesWritten, copyResult.filesWritten);
 
+      if (copyResult.preservedFiles.includes('SKILL.md')) {
+        const preservedSkillPath = path.join(destDir, 'SKILL.md');
+        const preservedStat = fs.lstatSync(preservedSkillPath, { throwIfNoEntry: false });
+        if (preservedStat && !preservedStat.isSymbolicLink()) {
+          const preservedSkill = fs.readFileSync(preservedSkillPath, 'utf8');
+          const oldPathMatch = preservedSkill.match(/\*\*Solution CLI Runtime\*\*:[\s\S]*?full absolute path: `"([^"]+)"/);
+          const normalizePath = value => path.normalize(value.replaceAll('\\', '/'));
+          if (oldPathMatch && normalizePath(oldPathMatch[1]) !== normalizePath(engineBin)) {
+            logger(`  ⚠️ Preserved user-modified SKILL.md still contains its previous Engine path; user text was not rewritten.`);
+          } else {
+            logger('  ⚠️ Preserved user-modified SKILL.md; user text was not rewritten.');
+          }
+        }
+      }
+
       // Customize SKILL.md only if actually copied by this install and not an external symlink (Codex P1)
       const skillMdPath = path.join(destDir, 'SKILL.md');
       if (fs.existsSync(skillMdPath) && copyResult.updatedFiles.includes('SKILL.md')) {
@@ -175,9 +206,9 @@ export async function runInstall(options = {}) {
         if (skillStat && !skillStat.isSymbolicLink()) {
           let content = fs.readFileSync(skillMdPath, 'utf8');
           const escapedBinPath = engineBin.replace(/\\/g, '/');
-          const instructionBlock = `\n> **SenseCraft Runtime**: All steps run via \`${escapedBinPath}\`. If shell $PATH does not contain \`sensecraft-engine\`, always invoke using the full absolute path: \`"${escapedBinPath}" <subcommand>\`.\n\n`;
+          const instructionBlock = `\n> **Solution CLI Runtime**: Engine operations such as \`device\`, \`deploy\`, and \`logs\` must use the full absolute path: \`"${escapedBinPath}" <subcommand>\`. Use \`solution-cli\` for catalog and product queries; if it is not on $PATH, invoke \`npx -y --package=@seeed-studio/solution-cli@latest solution-cli <args>\`.\n\n`;
 
-          if (!content.includes('SenseCraft Runtime:')) {
+          if (!content.includes('**Solution CLI Runtime**:')) {
             content = content.replace(/(---[\s\S]*?---\n)/, `$1${instructionBlock}`);
             fs.writeFileSync(skillMdPath, content, 'utf8');
           }
@@ -186,7 +217,7 @@ export async function runInstall(options = {}) {
       }
 
       // Write installation marker safely without following external symlinks (Codex P2)
-      const markerPath = path.join(destDir, '.installed-by-sensecraft');
+      const markerPath = path.join(destDir, '.installed-by-solution-cli');
       if (isSafePathInside(markerPath, destDir)) {
         const markerStat = fs.lstatSync(markerPath, { throwIfNoEntry: false });
         if (markerStat && markerStat.isSymbolicLink()) {
@@ -207,7 +238,7 @@ export async function runInstall(options = {}) {
   });
 
   logger('\n\x1b[1m\x1b[32m====================================================\x1b[0m');
-  logger('\x1b[1m\x1b[32m  🎉 SenseCraft Setup Completed Successfully!      \x1b[0m');
+  logger('\x1b[1m\x1b[32m  🎉 Solution CLI Setup Completed Successfully!   \x1b[0m');
   logger('\x1b[1m\x1b[32m====================================================\x1b[0m');
   logger(`\n🔧 Engine Binary: ${engineBin}`);
   logger(`🤖 Configured Agents:`);
@@ -259,7 +290,7 @@ export function runStatus(options = {}) {
     return statusObj;
   }
 
-  logger('\n📊 SenseCraft System Status:\n');
+  logger('\n📊 Solution CLI System Status:\n');
   logger(`  Engine Binary: ${binPath}`);
   logger(`  Engine Version: ${engineCheck.version || 'Not installed'} (${engineCheck.valid ? 'Valid' : 'Invalid'})`);
   logger(`  Deployers Available: ${engineCheck.deployers?.length || 0}`);
@@ -283,7 +314,7 @@ export function runUninstall(options = {}) {
   const installedIds = Object.keys(ledger.installations || {});
 
   if (installedIds.length === 0) {
-    logger('No managed SenseCraft skills are currently recorded in the ledger.');
+    logger('No managed Solution CLI skills are currently recorded in the ledger.');
     return;
   }
 
@@ -315,6 +346,7 @@ export function runUninstall(options = {}) {
 function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logger) {
   const filesWritten = {};
   const updatedFiles = [];
+  const preservedFiles = [];
   const entries = fs.readdirSync(srcDir, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -333,6 +365,7 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
       const sub = copyFolderSafely(srcPath, destPath, baseDestDir, priorFiles, force, logger);
       Object.assign(filesWritten, sub.filesWritten);
       updatedFiles.push(...sub.updatedFiles);
+      preservedFiles.push(...sub.preservedFiles);
     } else {
       let shouldCopy = true;
 
@@ -348,12 +381,14 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
             // CRUCIAL (Codex High 1): Keep the ORIGINAL baseline hash in the ledger!
             // Do NOT record destHash, otherwise future uninstall will consider it unmodified!
             filesWritten[relPath] = recordedBaselineHash;
+            preservedFiles.push(relPath);
           }
         } else {
           // File exists on disk but was never in ledger (unmanaged foreign file)
           if (!force) {
             logger(`  ⚠️ Refused overwriting unmanaged pre-existing file: ${relPath} (use --force)`);
             shouldCopy = false;
+            preservedFiles.push(relPath);
           }
         }
       }
@@ -371,5 +406,5 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
     }
   }
 
-  return { filesWritten, updatedFiles };
+  return { filesWritten, updatedFiles, preservedFiles };
 }