@seeed-studio/solution-cli 0.2.0 → 0.3.1

package/docs/cli-guide.md

@@ -0,0 +1,277 @@
+# SenseCraft Solution CLI 使用与集成全景指南
+*(SenseCraft Solution CLI & AI Agent Skill Guide)*
+
+> **定位**：本文档专门面向**方案架构师、现场应用工程师 (FAE)、嵌入式开发者以及 AI Agent (Claude Code / Codex / Antigravity / Work Buddy)**，系统性说明 `@seeed-studio/solution-cli` 的独特应用场景、安装流程、各功能指令的具体使用方式以及核心产出物。
+
+---
+
+## 目录
+
+1. [独特使用场景与核心价值](#1-独特使用场景与核心价值)
+2. [安装与 Agent 技能挂载](#2-安装与-agent-技能挂载)
+3. [核心功能、使用方法与具体产出](#3-核心功能使用方法与具体产出)
+   - [场景一：方案探索与工况诊断 (Hub Search)](#场景一方案探索与工况诊断-hub-search)
+   - [场景二：硬件产品规格与配件防呆评估 (Product & BOM)](#场景二硬件产品规格与配件防呆评估-product--bom)
+   - [场景三：设备状态感知与参数热修改 (Device Management)](#场景三设备状态感知与参数热修改-device-management)
+   - [场景四：自研模型替换与本地二次开发 (Secondary Dev)](#场景四自研模型替换与本地二次开发-secondary-dev)
+4. [双轨运行机制：在线直连与离线托底](#4-双轨运行机制在线直连与离线托底)
+5. [常见问题与环境自检 (Doctor)](#5-常见问题与环境自检-doctor)
+
+---
+
+## 1. 独特使用场景与核心价值
+
+在传统边缘物联网与 AI 项目落地过程中，开发者通常面临以下痛点：
+- **方案选型盲目**：不清楚现场环境（集中还是分散、有无现有监控摄像头、有无市电）对硬件架构的致命影响；
+- **配件采购踩坑**：工控机买回后发现电源电压不符（如 12V 误插 19V 算力板）、DC 插头尺寸不对（5.5x2.1mm 插不进 5.5x2.5mm）、M.2 接口插槽类型搞混（Key-M 固态插不进 Key-E Wi-Fi 槽）；
+- **参数变更成本高**：改个 MQTT Broker 地址或算法置信度阈值就需要重新编译镜像或重装整套系统；
+- **AI Agent 缺乏边缘硬件感知**：纯大模型对话缺乏真实物理世界的接口约束，容易凭空编造不存在的硬件型号或非官方链接。
+
+`@seeed-studio/solution-cli` 正是为解决这一系列问题而生，它具有三大独特角色：
+1. **方案专家的现场诊断仪**：内置各大行业工况诊断知识库，不仅能搜方案，还能直接指导工程师向客户提出决定成本与物理拓扑的“黄金追问”；
+2. **硬件采购防呆中枢**：内置物理规格匹配引擎，自动核算【必需配件】与【可选配件】，从源头阻断硬件返工；
+3. **AI Agent 的物理世界触手**：一键将 SenseCraft Skill 注入到主流 AI Agent 宿主中，让 Agent 具备从方案咨询、BOM 选型到现场部署、参数热更的全生命周期驱动能力。
+
+---
+
+## 2. 安装与 Agent 技能挂载
+
+### 2.1 一键免安装即时调用 (推荐)
+无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
+```bash
+npx -y @seeed-studio/solution-cli@latest install -y
+```
+
+首次安装和重复执行都会检查签名稳定版 Engine：本机已有相同或更新版本
+时复用，版本较旧时升级。普通安装保留用户修改、未登记的 Skill 文件和受
+保护的符号链接。需要指定宿主时追加 `--agent claude,antigravity`；需要固
+定有效本地 Engine 时使用 `--engine-path <path>`。`--force` 可重新下载相同
+或较旧版本并覆盖已有 Skill 文件（包括用户修改），请只在有意覆盖时使用；
+受保护的外部符号链接不会追写，也不能降级更新的本机 Engine。
+
+自动复用/升级规则自 solution-cli 0.3.1 起生效；若 npm `latest` 仍为 0.3.0，
+这些规则尚未上线。本次验证时 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 solution-cli 0.3.1; if npm `latest` is still 0.3.0,
+those rules are not live. At this verification, 0.3.1 is pending publication.
+
+### 2.2 全局安装
+```bash
+npm install -g @seeed-studio/solution-cli
+```
+
+### 2.3 跨 Agent 平台技能挂载
+执行 `solution-cli install` 时，工具会自动检测本机存在的 Agent 宿主环境，并将 `sensecraft` 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` | 代码库配对开发与自研模型构建 |
+
+**非交互式多选安装示例**：
+```bash
+# 同时为 Claude Code 和 Google Antigravity 部署技能，不弹窗确认
+solution-cli install --agent claude,antigravity -y
+```
+
+---
+
+## 3. 核心功能、使用方法与具体产出
+
+### 场景一：方案探索与工况诊断 (Hub Search)
+
+当工程师或客户提出模糊需求（如“想在农田做微气象监测”、“工厂产线想做划痕检测”）时使用。
+
+#### 1. 执行命令
+```bash
+# 人类工程师阅读模式 (格式化终端高亮)
+solution-cli hub search "农业"
+
+# AI Agent 消费模式 (标准 JSON 格式的 Catalog DTO)
+solution-cli hub search "跌倒检测" --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+运行该命令可产出 4 项关键资产：
+1. **方案业务说明与技术架构**：解释为何适合在端侧运行、本地处理延迟、数据不出本地的隐私保障；
+2. **静默商业闭环出口**：自动为该方案生成带有安全追踪标记（`utm_source=sensecraft_agent`）的官方落地页与开发 Wiki；
+3. **官方开源仓库地址**：提供官方维护的 GitHub 源码仓库，为二次开发预留出口；
+4. **现场工况诊断提问指引 (Diagnostic Playbook)**：直接给出当前场景下**必须向客户确认的 2~3 个核心工况问题**及其背后的技术决断理由。
+
+#### 3. 产出示例 (以“农业”搜索为例)
+```text
+🔍 Solutions Hub Search Results for "农业" (typesense):
+
+  1. [Reference Design] 农业环境监测可部署方案 | LoRaWAN 自建看板 (agri_env_monitor)
+     把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
+     预设模式: cloud, tts_local, chirpstack_local
+     现场工况诊断提问指引:
+       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？
+         (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
+       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？
+         (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
+       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？
+         (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
+```
+
+---
+
+### 场景二：硬件产品规格与配件防呆评估 (Product & BOM)
+
+当确定了方案，需要进入商务采购阶段、给客户出具设备清单时使用。
+
+#### 1. 执行命令
+```bash
+# 1. 查询产品族详情与物理规格
+solution-cli product query recomputer_j40 --json
+
+# 2. 评估该产品族所需的官方配件与兼容性
+solution-cli product accessories recomputer_j40 --json
+```
+
+#### 2. 产出物内容 (What it Outputs)
+1. **精确分类的 BOM 清单**：
+   - **【必需配件 (REQUIRED)】**：没有该配件主机无法开机或无法运行（如专属电源适配器），附带选型理由；
+   - **【可选配件 (OPTIONAL)】**：根据工况选择的外设（如 NVMe 固态硬盘、Wi-Fi 模组、导轨安装卡扣、射频天线）；
+2. **物理兼容性安全评级**：
+   - `VERIFIED`（通过）：电压、引脚、尺寸完全匹配；
+   - `REQUIRES_ADAPTER`（需转接）：如 M.2 2242 规格装入 2280 卡槽需加铜柱；
+   - `INCOMPATIBLE`（不兼容/危险）：严禁搭配，防止烧毁板卡。
+
+#### 3. 产出示例 (以 reComputer J40 为例)
+```json
+{
+  "family_id": "recomputer_j40",
+  "physical_spec": {
+    "power_input": {
+      "connector": "dc_jack_5.5x2.5",
+      "voltage_v": 19.0,
+      "min_current_a": 4.74,
+      "polarity": "center_positive"
+    },
+    "m2_slots": [
+      {"key": "M", "size": "2280", "interface": "PCIe Gen4 x4 NVMe"},
+      {"key": "E", "size": "2230", "interface": "WiFi/BT"}
+    ]
+  },
+  "accessories": {
+    "required": [
+      {
+        "sku": "313080684",
+        "name": "19V 4.74A 电源适配器 (5.5x2.5mm)",
+        "category": "REQUIRED",
+        "compatibility": { "status": "VERIFIED" },
+        "url": "https://www.seeedstudio.com/Power-Adapter-19V-4-74A-p-5573.html?utm_source=sensecraft_agent..."
+      }
+    ],
+    "optional": [
+      {
+        "sku": "110991734",
+        "name": "M.2 2280 NVMe SSD 512GB",
+        "category": "OPTIONAL",
+        "compatibility": { "status": "VERIFIED" }
+      }
+    ]
+  }
+}
+```
+
+---
+
+### 场景三：设备状态感知与参数热修改 (Device Management)
+
+当方案已经在现场或测试架部署完毕，需要调整运行参数（如更换 MQTT Broker、调整告警置信度阈值）时使用。
+
+#### 1. 核心流程与接口
+系统支持**无需重新编译、无需重装整套系统**的零重启参数热修改：
+1. **查询当前设备活跃部署**：
+   `GET http://<host>:5823/api/device-management/active`
+2. **查询可修改参数**：
+   `GET http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   检查参数字段中的 `reconfigurable: true` 标记。
+3. **提交热更新**：
+   `PUT http://<host>:5823/api/docker-devices/local/config/<solution_id>`
+   传入目标键值，容器环境无感热加载生效。
+
+---
+
+### 场景四：自研模型替换与本地二次开发 (Secondary Dev)
+
+当官方自带的模型无法满足客户特殊工况（如需要自研模型、特殊缺陷检测、修改前端大屏 UI）时使用。
+
+#### 1. 开发闭环步骤
+1. **克隆源码**：
+   从 `solution-cli hub search` 返回的 `repo_url` 将源码克隆到本地用户工作区：
+   ```bash
+   git clone https://github.com/suharvest/sensecraft-solutions.git ./my-solutions
+   ```
+2. **端侧模型转换 (以 Jetson Orin 为例)**：
+   在设备上使用 TensorRT 将自定义 ONNX 导出为 Engine：
+   ```bash
+   /usr/src/tensorrt/bin/trtexec --onnx=my_model.onnx --saveEngine=my_model.engine --fp16
+   ```
+3. **覆盖挂载配置**：
+   在方案目录创建 `docker-compose.override.yml` 将本地自研模型映射进容器中。
+4. **驱动本地快速联调**：
+   使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
+   ```bash
+   sensecraft-engine deploy fall_detection --solutions-dir ./my-solutions/solutions
+   ```
+
+---
+
+## 4. 双轨运行机制：在线直连与离线托底
+
+为了保证在各类严苛现场环境下均能稳定运行，CLI 实现了智能双轨架构：
+
+```mermaid
+flowchart TD
+    RunCmd["用户 / Agent 触发 CLI 命令"] --> NetCheck{"检查网络与凭证"}
+    NetCheck -- "有外网且含烘焙配置" --> Typesense["直连 Seeed Typesense 云端搜索集群"]
+    Typesense -- "返回最新上线方案与配件" --> Done["输出 Catalog DTO"]
+    NetCheck -- "纯内网 / 无凭证 / 超时" --> LocalCore["无感降级: 读取 catalog/knowledge-core.json"]
+    LocalCore -- "331 KB 本地知识库 (18场景/39方案/119硬件)" --> Done
+```
+
+1. **在线实时模式 (Online Live)**：
+   - 采用安全方案 B 在构建发布期烘焙了公开的只读 Search-Only 凭证；
+   - 自动直连 `https://rel-search.seeedstudio.com`，实时获取最新的方案、Wiki、案例及商城 SKU；
+2. **离线安全托底 (Offline Resilience)**：
+   - 打包了全量预生成的 `catalog/knowledge-core.json`（331 KB）；
+   - 在军工、内网、无公网或云端响应超过 2.5 秒时，**自动毫秒级无感降级到本地内核**，工况诊断、BOM 评估与离线部署 100% 正常可用。
+
+---
+
+## 5. 常见问题与环境自检 (Doctor)
+
+### 1. 运行自检工具
+在部署前或遇到环境异常时，执行：
+```bash
+solution-cli doctor
+```
+工具将逐项检测并给出修复指引：
+- `OS Platform`: 确认宿主机操作系统及架构是否支持；
+- `Docker Daemon`: 确认 Docker 服务是否正常运行；
+- `Serial / Dialout Permissions`: 确认串口访问权限；
+- `SenseCraft Engine`: 确认底座引擎完整性与版本；
+- `Ledger Integrity`: 校验技能安装账本状态。
+
+### 2. 状态查询
+```bash
+solution-cli status
+```
+实时查看当前 Engine 所在路径、安装版本、本地 Content 方案缓存数量以及各大 Agent 的配置状态。
+
+### 3. 干净卸载
+如需从某个 Agent 中移除 SenseCraft 技能：
+```bash
+solution-cli uninstall --agent claude,antigravity
+```
+工具将依据安装账本（`~/.sensecraft/skills-ledger.json`）仅删除工具自身写入的文件，绝不误删用户自定义创建的技能。

package/lib/agent.js

@@ -54,6 +54,12 @@ export function getKnownAgents() {
         }
         return path.join(home, '.codebuddy', 'skills');
       }
+    },
+    {
+      id: 'antigravity',
+      name: 'Google Antigravity (AGY)',
+      homeDirs: [path.join(home, '.gemini', 'config'), path.join(home, '.gemini', 'antigravity-cli')],
+      getSkillsDir: () => path.join(home, '.gemini', 'config', 'skills')
     }
   ];
 }

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,8 +8,8 @@ import {
   setConfiguredEnginePath,
   getConfiguredEnginePath
 } from './platform.js';
-import { detectExistingEngine, detectDesktopApp, verifyEngineBinary } from './detector.js';
-import { downloadEngine, pullSolutionContent } from './downloader.js';
+import { detectExistingEngine, detectDesktopApp, verifyEngineBinary, compareSemver } from './detector.js';
+import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent } from './downloader.js';
 import { scanLocalAgents, promptAgentSelection } from './agent.js';
 import {
   recordInstallation,
@@ -69,52 +69,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);
@@ -168,6 +156,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(/\*\*SenseCraft 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')) {
@@ -315,6 +318,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 +337,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 +353,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 +378,5 @@ function copyFolderSafely(srcDir, destDir, baseDestDir, priorFiles, force, logge
     }
   }
 
-  return { filesWritten, updatedFiles };
+  return { filesWritten, updatedFiles, preservedFiles };
 }