@seeed-studio/solution-cli 0.3.1 → 0.3.2

package/README.md

@@ -13,9 +13,18 @@ Compatible with **Claude Code, Codex, Google Antigravity (AGY), Work Buddy, and
 Install the underlying engine and configure the AI Agent Skill with one command:
 
 ```bash
-npx -y @seeed-studio/solution-cli@latest install -y
+npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
 ```
 
+This example targets WorkBuddy explicitly. Replace `workbuddy` 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 the corresponding 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.
+
 The same command is safe to repeat. It checks the signed stable Engine release,
 reuses an equal or newer local Engine, and upgrades an older one. Existing
 modified or unregistered skills and protected symlinks are preserved. Use
@@ -25,9 +34,8 @@ overwrites existing skill files, including user modifications; use it only when
 that overwrite is intended. Protected external symlinks are not followed, and
 it never downgrades a newer discovered Engine.
 
-Automatic reuse/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. A latest release or signature failure stops before changing the
+Automatic reuse/upgrade rules start with publicly published solution-cli 0.3.1.
+A latest release or signature failure stops before changing the
 Engine or skills; an offline host must use a valid explicit local Engine path.
 
 The interactive form remains available when prompts are wanted:
@@ -37,11 +45,11 @@ npx -y @seeed-studio/solution-cli@latest install
 ```
 
 ### Supported AI Agent Harnesses
-- **Claude Code**: `~/.claude/skills/sensecraft`
-- **Codex / OpenAI**: `~/.agents/skills/sensecraft` or `~/.codex/skills/sensecraft`
-- **Google Antigravity (AGY)**: `~/.gemini/config/skills/sensecraft`
-- **Work Buddy / Workbody**: `~/.workbuddy/skills/sensecraft`
-- **CodeBuddy**: `~/.codebuddy/skills/sensecraft`
+- **Claude Code**: `~/.claude/skills/solution-cli`
+- **Codex / OpenAI**: `~/.agents/skills/solution-cli` or `~/.codex/skills/solution-cli`
+- **Google Antigravity (AGY)**: `~/.gemini/config/skills/solution-cli`
+- **Work Buddy / Workbody**: `~/.workbuddy/skills/solution-cli`
+- **CodeBuddy**: `~/.codebuddy/skills/solution-cli`
 
 ---
 
@@ -57,7 +65,7 @@ The `solution-cli` provides unified commands for discovery, BOM calculation, dev
 | `solution-cli install [--agent <agents>] [-y]` | Inspect host environment, download/verify engine, and install Agent skills. |
 | `solution-cli status` | Inspect installed engine binary, content cache, and configured agent skills. |
 | `solution-cli doctor` | Run pre-flight diagnostics (OS, Docker daemon, serial permissions, PATH, ledger). |
-| `solution-cli uninstall [--agent <agents>]` | Cleanly remove SenseCraft skills using the installation ledger. |
+| `solution-cli uninstall [--agent <agents>]` | Cleanly remove Solution CLI skills using the installation ledger. |
 | `sensecraft-engine <subcommand>` | Direct proxy to the underlying high-performance Rust execution engine. |
 
 ---

package/bin/cli.js

@@ -15,18 +15,17 @@ const command = args[0] || 'install';
 
 function printHelp() {
   console.log(`
-SenseCraft Solution CLI & Skill Toolset (${pkg.name})
+Solution CLI & Agent Skill Toolset (${pkg.name})
 
 Usage:
   npx @seeed-studio/solution-cli [command] [options]
   solution-cli [command] [options]
-  sensecraft-solution-cli [command] [options]
 
 Commands:
   install     Inspect environment, verify/download engine, and configure AI Agent skills (default)
   status      Display current engine, solution content, and agent skills status
   doctor      Diagnose environment (platform, permissions, docker, PATH, ledger)
-  uninstall   Cleanly remove SenseCraft skills from specified agent(s)
+  uninstall   Cleanly remove Solution CLI skills from specified agent(s)
   hub         Search scenarios and reference designs from Seeed Solution Hub
               Usage: solution-cli hub search <keyword> [--limit 5] [--locale zh|en] [--json]
   product     Query product families, SKUs, and verified accessories
@@ -58,7 +57,15 @@ Examples:
 `);
 }
 
+class CliArgumentError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'CliArgumentError';
+  }
+}
+
 function parseFlags(rawArgs) {
+  const usedFlags = new Set();
   const flags = {
     agent: null,
     yes: false,
@@ -75,62 +82,121 @@ function parseFlags(rawArgs) {
     solution: null,
     version: '1.0.0',
     hardware: null,
+    positionals: [],
+    usedFlags,
   };
 
   for (let i = 0; i < rawArgs.length; i++) {
     const a = rawArgs[i];
-    if (a === '--agent' && rawArgs[i + 1]) {
-      flags.agent = rawArgs[++i];
-    } else if (a.startsWith('--agent=')) {
-      flags.agent = a.split('=')[1];
+    const valueFlag = (name, setter) => {
+      const inlinePrefix = `${name}=`;
+      if (a.startsWith(inlinePrefix)) {
+        const value = a.slice(inlinePrefix.length);
+        if (!value) throw new CliArgumentError(`${name} requires a value`);
+        usedFlags.add(name);
+        setter(value);
+        return true;
+      }
+      if (a === name) {
+        const value = rawArgs[i + 1];
+        if (!value || value.startsWith('-')) {
+          throw new CliArgumentError(`${name} requires a value`);
+        }
+        usedFlags.add(name);
+        setter(value);
+        i += 1;
+        return true;
+      }
+      return false;
+    };
+
+    if (valueFlag('--agent', value => { flags.agent = value; })) {
     } else if (a === '-y' || a === '--yes') {
+      usedFlags.add('--yes');
       flags.yes = true;
     } else if (a === '--dry-run') {
+      usedFlags.add('--dry-run');
       flags.dryRun = true;
     } else if (a === '--skip-content') {
+      usedFlags.add('--skip-content');
       flags.skipContent = true;
     } else if (a === '--force') {
+      usedFlags.add('--force');
       flags.force = true;
     } else if (a === '--json') {
+      usedFlags.add('--json');
       flags.json = true;
-    } else if (a === '--engine-path' && rawArgs[i + 1]) {
-      flags.enginePath = rawArgs[++i];
-    } else if (a === '--limit' && rawArgs[i + 1]) {
-      flags.limit = parseInt(rawArgs[++i], 10) || 5;
-    } else if (a === '--locale' && rawArgs[i + 1]) {
-      flags.locale = rawArgs[++i];
-    } else if (a === '--sku' && rawArgs[i + 1]) {
-      flags.sku = rawArgs[++i];
-    } else if (a === '--host' && rawArgs[i + 1]) {
-      flags.host = rawArgs[++i];
-    } else if (a === '--accessory' && rawArgs[i + 1]) {
-      flags.accessory = rawArgs[++i];
-    } else if (a === '--solution' && rawArgs[i + 1]) {
-      flags.solution = rawArgs[++i];
-    } else if (a === '--version' && rawArgs[i + 1]) {
-      flags.version = rawArgs[++i];
-    } else if (a === '--hardware' && rawArgs[i + 1]) {
-      flags.hardware = rawArgs[++i];
+    } else if (valueFlag('--engine-path', value => { flags.enginePath = value; })) {
+    } else if (valueFlag('--limit', value => {
+      if (!/^[1-9]\d*$/.test(value)) throw new CliArgumentError('--limit requires a positive integer');
+      const limit = Number(value);
+      if (!Number.isSafeInteger(limit)) throw new CliArgumentError('--limit is too large');
+      flags.limit = limit;
+    })) {
+    } else if (valueFlag('--locale', value => { flags.locale = value; })) {
+    } else if (valueFlag('--sku', value => { flags.sku = value; })) {
+    } else if (valueFlag('--host', value => { flags.host = value; })) {
+    } else if (valueFlag('--accessory', value => { flags.accessory = value; })) {
+    } else if (valueFlag('--solution', value => { flags.solution = value; })) {
+    } else if (valueFlag('--version', value => { flags.version = value; })) {
+    } else if (valueFlag('--hardware', value => { flags.hardware = value; })) {
+    } else if (a.startsWith('-')) {
+      throw new CliArgumentError(`Unknown option "${a}"`);
+    } else {
+      flags.positionals.push(a);
     }
   }
 
   return flags;
 }
 
-async function main() {
-  const flags = parseFlags(args.slice(1));
+function validatePositionals(command, positionals) {
+  if (['install', 'uninstall', 'status', 'doctor'].includes(command) && positionals.length > 0) {
+    throw new CliArgumentError(`${command} does not accept positional arguments`);
+  }
+}
 
-  if (command === 'help' || command === '--help' || command === '-h') {
+function validateCommandFlags(command, flags) {
+  const allowed = {
+    install: ['--agent', '--yes', '--dry-run', '--skip-content', '--force', '--engine-path'],
+    uninstall: ['--agent', '--dry-run', '--force'],
+    status: ['--json'],
+    doctor: ['--json'],
+    hub: ['--json', '--locale', '--limit'],
+    product: ['--json', '--locale', '--sku', '--host', '--accessory'],
+    lockfile: ['--json', '--solution', '--version', '--hardware'],
+    help: [],
+  };
+  const supported = allowed[command];
+  if (!supported) return;
+  for (const flag of flags.usedFlags) {
+    if (!supported.includes(flag)) {
+      throw new CliArgumentError(`${flag} is not supported for ${command}`);
+    }
+  }
+}
+
+async function main() {
+  if (args.some(a => a === '--help' || a === '-h')) {
     printHelp();
-    process.exit(0);
+    return;
   }
 
   if (command === '--version' || command === '-v') {
     console.log(pkg.version);
-    process.exit(0);
+    return;
   }
 
   try {
+    const flags = parseFlags(args.slice(1));
+    validatePositionals(command, flags.positionals);
+    validateCommandFlags(command, flags);
+
+    if (command === 'help') {
+      printHelp();
+      return;
+    }
+
     switch (command) {
       case 'install':
         await runInstall(flags);
@@ -145,7 +211,7 @@ async function main() {
         if (flags.json) {
           console.log(JSON.stringify(report, null, 2));
         } else {
-          console.log('\n🩺 SenseCraft Doctor Environment Report:\n');
+          console.log('\n🩺 Solution CLI Doctor Environment Report:\n');
           report.checks.forEach(c => {
             const symbol = c.status === 'ok' ? '\x1b[32m✔\x1b[0m' : c.status === 'warn' ? '\x1b[33m⚠️\x1b[0m' : '\x1b[31m✖\x1b[0m';
             console.log(`  ${symbol} ${c.title}`);
@@ -161,12 +227,12 @@ async function main() {
         break;
 
       case 'hub': {
-        const sub = args[1] || 'search';
+        const sub = flags.positionals[0] || 'search';
         if (sub !== 'search') {
           console.error(`Unknown hub action "${sub}". Supported: "solution-cli hub search <keyword>"`);
           process.exit(1);
         }
-        const query = args.slice(2).filter((a) => !a.startsWith('-')).join(' ');
+        const query = flags.positionals.slice(1).join(' ');
         const dto = await searchHub({ query, locale: flags.locale, limit: flags.limit });
         if (flags.json) {
           console.log(JSON.stringify(dto, null, 2));
@@ -200,8 +266,8 @@ async function main() {
       }
 
       case 'product': {
-        const sub = args[1] || 'query';
-        const familyId = args.slice(2).find((a) => !a.startsWith('-')) || flags.host;
+        const sub = flags.positionals[0] || 'query';
+        const familyId = flags.positionals[1] || flags.host;
 
         if (sub === 'query') {
           if (!familyId) {
@@ -296,7 +362,7 @@ async function main() {
       }
 
       case 'lockfile': {
-        const sub = args[1] || 'create';
+        const sub = flags.positionals[0] || 'create';
         if (sub !== 'create') {
           console.error(`Unknown lockfile action "${sub}". Supported: "solution-cli lockfile create"`);
           process.exit(1);
@@ -326,7 +392,7 @@ async function main() {
     }
   } catch (err) {
     console.error(`\n\x1b[31mError:\x1b[0m ${err.message}\n`);
-    process.exit(1);
+    process.exitCode = err instanceof CliArgumentError ? 2 : 1;
   }
 }
 

package/bin/runner.js

@@ -8,7 +8,7 @@ const binPath = getConfiguredEnginePath();
 
 if (!fs.existsSync(binPath) || !isExecutable(binPath)) {
   console.error(`\x1b[31mError:\x1b[0m SenseCraft Engine binary not found at "${binPath}".`);
-  console.error('Please run "npx @sensecraft/cli install" first to provision the engine.\n');
+  console.error('Please run "npx -y --package=@seeed-studio/solution-cli@latest solution-cli install --agent <agent-id>" first to provision the engine.\n');
   process.exit(1);
 }
 

package/docs/cli-guide.md

@@ -30,7 +30,7 @@
 `@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 选型到现场部署、参数热更的全生命周期驱动能力。
 
 ---
 
@@ -39,9 +39,16 @@
 ### 2.1 一键免安装即时调用 (推荐)
 无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
 ```bash
-npx -y @seeed-studio/solution-cli@latest install -y
+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`；需要固
@@ -49,31 +56,52 @@ npx -y @seeed-studio/solution-cli@latest install -y
 或较旧版本并覆盖已有 Skill 文件（包括用户修改），请只在有意覆盖时使用；
 受保护的外部符号链接不会追写，也不能降级更新的本机 Engine。
 
-自动复用/升级规则自 solution-cli 0.3.1 起生效；若 npm `latest` 仍为 0.3.0，
-这些规则尚未上线。本次验证时 0.3.1 待发布。latest 检查或签名校验失败会在
+自动复用/升级规则自 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 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.
+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

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/installer.js

@@ -10,7 +10,7 @@ import {
 } from './platform.js';
 import { detectExistingEngine, detectDesktopApp, verifyEngineBinary, compareSemver } from './detector.js';
 import { downloadEngine, fetchManifest, validateReleaseManifest, pullSolutionContent } from './downloader.js';
-import { scanLocalAgents, promptAgentSelection } from './agent.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;
@@ -135,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) {
@@ -161,7 +189,7 @@ export async function runInstall(options = {}) {
         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 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.`);
@@ -178,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');
           }
@@ -189,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()) {
@@ -210,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:`);
@@ -262,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}`);
@@ -286,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;
   }
 

package/lib/ledger.js

@@ -246,7 +246,7 @@ export function removeInstallation(agentId, options = {}) {
   }
 
   // Remove marker file
-  const marker = path.join(targetDir, '.installed-by-sensecraft');
+  const marker = path.join(targetDir, '.installed-by-solution-cli');
   if (fs.existsSync(marker) && isSafePathInside(marker, targetDir)) {
     actions.push({ file: marker, action: 'delete_marker' });
     if (!dryRun) {

package/package.json

@@ -1,15 +1,12 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.3.1",
-  "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
+  "version": "0.3.2",
+  "description": "Installer for the Rust deployment engine and Solution CLI 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"
+    "sensecraft-engine": "bin/runner.js"
   },
   "publishConfig": {
     "access": "public"

package/skills/{sensecraft → solution-cli}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-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.
+name: solution-cli
+description: 用于客户询盘、客户需求、方案选型、我们能提供什么、怎么回复客户等边缘/IoT 方案咨询，涵盖智慧农业、跌倒检测、楼宇温控、恒温器、传感器及相关硬件。Use for customer inquiries, requirements analysis, solution selection, proposal guidance, edge IoT deployments, hardware compatibility, deployment, and troubleshooting. First search the SenseCraft solution catalog with `solution-cli`; do not trigger for general business writing, generic proposal drafting, or unrelated coding.
 ---
 
-# SenseCraft Solution
+# Solution CLI
 
-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**.
+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**. For Engine-only operations, use the injected absolute Engine path. If the wrapper is not on `PATH`, invoke the CLI as `npx -y --package=@seeed-studio/solution-cli@latest solution-cli <args>`. Keep catalog queries such as `hub` and `product` on `solution-cli`; do not forward them to the Engine.
 
 ## Workflow Routing & Progressive Disclosure
 
@@ -126,11 +126,25 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    reinstall, use the same solution-cli command; do not reinstall on every
    deployment:
 
-   **Recommended (Zero-friction via solution-cli, auto-detects existing app & agents)**:
+   **Recommended (Zero-friction via solution-cli, target the current Agent explicitly)**:
    ```bash
-   npx -y @seeed-studio/solution-cli@latest install -y
+   npx -y @seeed-studio/solution-cli@latest install --agent <current-agent-id> -y
    ```
 
+   Fill `<current-agent-id>` with the actual host ID: `workbuddy`, `claude`,
+   `codex`, `codebuddy`, or `antigravity`. The WorkBuddy example is:
+   ```bash
+   npx -y @seeed-studio/solution-cli@latest install --agent workbuddy -y
+   ```
+   An AI agent must use its current host ID; Codex must not hardcode WorkBuddy.
+   Use `npx -y @seeed-studio/solution-cli@latest install` for interactive
+   selection. When one or more Agents are detected, pressing Enter selects all
+   detected Agents; entering the matching 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.
+
    The command checks the signed stable Engine on fresh and repeat runs, reuses
    an equal or newer local version, and upgrades an older one. It preserves
    modified/unregistered skills and protected symlinks. Add `--agent ...` for an
@@ -138,9 +152,8 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    `--force` can re-download equal/older versions and overwrite existing skill
    files, including user modifications; use it only when that overwrite is
    intended. Protected external symlinks are not followed, and it never
-   downgrades a newer discovered Engine. Automatic 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. Latest/signature failure
+   downgrades a newer discovered Engine. Automatic reuse/upgrade rules start with
+   publicly published solution-cli 0.3.1. Latest/signature failure
    stops before writes; offline use requires a valid explicit local Engine path.
 
    **Fallback (Standalone shell script when Node.js is not present)**:

package/skills/{sensecraft → solution-cli}/references/consult-and-select.md

@@ -18,6 +18,8 @@
 | **建筑能耗 / 暖通** | 楼宇能耗、电表、水表、空调节能、HVAC, energy retrofit | `building-energy-retrofit` | `building_energy_management` |
 | **室内外定位 / 资产** | 蓝牙信标、资产定位、人员卡片、防丢、GNSS, tracker, beacon, T1000 | `indoor-outdoor-positioning` | `indoor_positioning_ble_lorawan` |
 
+客户询盘、客户需求分析、方案选型、如何回复客户或“我们能提供什么”也属于咨询路由；涉及楼宇温控、恒温器、温度/湿度/空气质量传感器等需求时，先用客户原话和关键技术词搜索方案库。若搜不到匹配结果，明确说明官方方案库缺少现成能力，再给出需定制验证的边界；不要把通用 IoT 能力编造成已有的 thermostat 硬件或现成方案。
+
 ---
 
 ## 2. 工具调用标准动作
@@ -27,6 +29,8 @@
 ```bash
 solution-cli hub search "<用户关键词>" --limit 5 --json
 ```
+- **咨询顺序**：先用用户原话和同义技术词查询，再根据返回的场景与 `diagnostic_playbook` 拆解需求；向用户确认点位、协议、供电、通信、控制闭环和预算等关键参数后，给出可提供的方案、硬件方向和缺口说明。
+- **交付边界**：咨询阶段只做检索、需求澄清和方案建议，不自动执行 `deploy`；用户确认硬件和部署目标后，再转入硬件校验或部署流程。
 - **输出结果说明**：
   - `Scenario`：业务场景、痛点、成效、官方场景落地页（`landing_url`）；
   - `Reference Design`：技术路线、预设模式 presets、开发 wiki（`wiki_url`）、官方方案落地页（`landing_url`）、源码仓库（`repo_url`）；