@seeed-studio/solution-cli 0.2.0 → 0.3.1

package/lib/knowledge.js

@@ -12,6 +12,44 @@ const DATA_FILE = path.join(__dirname, '..', 'catalog', 'knowledge-core.json');
 
 let cachedKnowledgeCore = null;
 
+/**
+ * Appends UTM tracking parameters to a URL while preserving existing query parameters.
+ *
+ * @param {string} urlStr - Target URL
+ * @param {Object} utmParams
+ * @param {string} [utmParams.source='sensecraft_agent']
+ * @param {string} [utmParams.medium='solution_consult']
+ * @param {string} [utmParams.campaign='']
+ * @param {string} [utmParams.content='']
+ * @returns {string} URL with appended UTM parameters
+ */
+export function appendUtm(urlStr, {
+  source = 'sensecraft_agent',
+  medium = 'solution_consult',
+  campaign = '',
+  content = '',
+} = {}) {
+  if (!urlStr || typeof urlStr !== 'string') return urlStr || '';
+  try {
+    const url = new URL(urlStr);
+    if (!url.searchParams.has('utm_source') && source) {
+      url.searchParams.set('utm_source', source);
+    }
+    if (!url.searchParams.has('utm_medium') && medium) {
+      url.searchParams.set('utm_medium', medium);
+    }
+    if (!url.searchParams.has('utm_campaign') && campaign) {
+      url.searchParams.set('utm_campaign', campaign);
+    }
+    if (!url.searchParams.has('utm_content') && content) {
+      url.searchParams.set('utm_content', content);
+    }
+    return url.toString();
+  } catch {
+    return urlStr;
+  }
+}
+
 /**
  * Loads the bundled offline knowledge core file.
  *
@@ -62,6 +100,28 @@ function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
   });
 }
 
+const CONFIG_FILE = path.resolve(__dirname, '../catalog/client-config.json');
+let cachedClientConfig = null;
+
+/**
+ * Loads build-time baked client configuration if present.
+ *
+ * @returns {Object|null}
+ */
+export function loadClientConfig() {
+  if (cachedClientConfig) return cachedClientConfig;
+  try {
+    if (fs.existsSync(CONFIG_FILE)) {
+      const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+      cachedClientConfig = JSON.parse(raw);
+      return cachedClientConfig;
+    }
+  } catch {
+    // Graceful fallback if missing or invalid
+  }
+  return null;
+}
+
 /**
  * Searches Seeed Solutions Hub scenarios and reference designs.
  *
@@ -73,34 +133,232 @@ function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
  */
 export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   const qLower = (query || '').toLowerCase().trim();
-  const searchKey = process.env.SENSECRAFT_TYPESENSE_PURCHASE_SEARCH_KEY || process.env.TYPESENSE_SEARCH_KEY;
-  const host = process.env.TYPESENSE_HOST || 'https://rel-search.seeedstudio.com';
+  const clientConfig = loadClientConfig();
+  const host = process.env.TYPESENSE_HOST || clientConfig?.typesense?.host || 'https://rel-search.seeedstudio.com';
+  const keySolution = process.env.TYPESENSE_SEARCH_KEY_SOLUTION || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_solution;
+  const keyRefDesign = process.env.TYPESENSE_SEARCH_KEY_REFERENCE_DESIGN || process.env.TYPESENSE_SEARCH_KEY || clientConfig?.typesense?.search_key_reference_design;
 
-  // Attempt online Typesense search if key is provided and not explicitly running offline
-  if (searchKey && !process.env.SENSECRAFT_OFFLINE_ONLY) {
+  // Attempt online Typesense search if keys are provided and not explicitly running offline
+  if ((keySolution || keyRefDesign) && !process.env.SENSECRAFT_OFFLINE_ONLY) {
     try {
-      const searchUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title,description,tags&per_page=${limit}`;
-      const data = await fetchJson(searchUrl, { 'X-TYPESENSE-API-KEY': searchKey }, 2500);
-      if (data && Array.isArray(data.hits)) {
-        const records = data.hits.map((hit) => {
-          const doc = hit.document || {};
-          return {
-            type: doc.doc_type || 'scenario',
-            id: doc.id || doc.slug,
-            title: doc.title,
-            summary: doc.summary || doc.description,
-            tags: doc.tags || [],
-            family_ids: doc.family_ids || [],
-            source: 'typesense',
-          };
-        });
+      const core = loadKnowledgeCore();
+      const onlinePromises = [];
+
+      const locKey = locale === 'zh' ? 'zh_hans' : locale;
+      const fetchLimit = Math.max(limit * 5, 30);
+
+      if (keySolution) {
+        const solFilter = 'published:!=false';
+        const solUrl = `${host}/collections/Solution/documents/search?q=${encodeURIComponent(query)}&query_by=title_zh_hans,title_en,excerpt_zh_hans,excerpt_en,display_tags_zh_hans&filter_by=${encodeURIComponent(solFilter)}&per_page=${fetchLimit}`;
+        onlinePromises.push(
+          fetchJson(solUrl, { 'X-TYPESENSE-API-KEY': keySolution }, 2500)
+            .then((data) => ({ type: 'scenario', hits: data?.hits || [] }))
+            .catch(() => ({ type: 'scenario', hits: [] }))
+        );
+      }
+
+      if (keyRefDesign) {
+        const rdFilter = 'published:!=false';
+        const rdUrl = `${host}/collections/reference_design/documents/search?q=${encodeURIComponent(query)}&query_by=name_zh_hans,name_en,summary_zh_hans,summary_en,tags&filter_by=${encodeURIComponent(rdFilter)}&per_page=${fetchLimit}`;
+        onlinePromises.push(
+          fetchJson(rdUrl, { 'X-TYPESENSE-API-KEY': keyRefDesign }, 2500)
+            .then((data) => ({ type: 'reference_design', hits: data?.hits || [] }))
+            .catch(() => ({ type: 'reference_design', hits: [] }))
+        );
+      }
+
+      const results = await Promise.all(onlinePromises);
+      const onlineScenarios = [];
+      const onlineRefDesigns = [];
+
+      for (const res of results) {
+        if (res.type === 'scenario') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            // Filter unreleased or staging scenarios from production recommendations
+            if (doc.published === false || doc.visibility === 'staging' || doc.visibility === 'draft') continue;
+            if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
+
+            const docId = doc.id || doc.slug;
+            const docType = doc.doc_type || 'scenario';
+            const title = locale === 'en'
+              ? (doc.title_en || doc.title_zh_hans || docId)
+              : (doc.title_zh_hans || doc.title_en || docId);
+            const summary = locale === 'en'
+              ? (doc.excerpt_en || doc.seo_description_en || doc.excerpt_zh_hans || '')
+              : (doc.excerpt_zh_hans || doc.seo_description_zh_hans || doc.excerpt_en || '');
+            const tags = (locale === 'en' ? doc.display_tags_en : doc.display_tags_zh_hans) || doc.display_tags || [];
+            const pb = core.diagnostic_playbooks?.[docId] || doc.diagnostic_playbook || null;
+            const rawLanding = doc.external_url || doc.landing_url || `https://www.seeedstudio.com/solutions/${docId}`;
+
+            onlineScenarios.push({
+              type: docType,
+              id: docId,
+              title,
+              summary,
+              tags,
+              family_ids: doc.family_ids || [],
+              reference_designs: doc.reference_designs || [],
+              landing_url: appendUtm(rawLanding, {
+                source: 'sensecraft_agent',
+                medium: 'solution_consult',
+                campaign: docId,
+                content: `${docType}_landing`,
+              }),
+              repo_url: doc.repo_url || '',
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        } else if (res.type === 'reference_design') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            // Filter unreleased or staging reference designs from production recommendations
+            if (doc.published === false || doc.visibility === 'staging' || doc.visibility === 'draft') continue;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (doc[`visibility_${locKey}`] === 'staging' || doc[`visibility_${locKey}`] === 'draft') continue;
+            const docId = doc.id;
+            const title = locale === 'en'
+              ? (doc.name_en || doc.name_zh_hans || docId)
+              : (doc.name_zh_hans || doc.name_en || docId);
+            const summary = locale === 'en'
+              ? (doc.summary_en || doc.tagline_en || doc.summary_zh_hans || '')
+              : (doc.summary_zh_hans || doc.tagline_zh_hans || doc.summary_en || '');
+
+            let pb = doc.diagnostic_playbook || core.diagnostic_playbooks?.[docId] || null;
+            if (!pb) {
+              for (const sc of core.scenarios || []) {
+                if ((sc.reference_designs || []).includes(docId)) {
+                  pb = sc.diagnostic_playbook || core.diagnostic_playbooks?.[sc.id] || null;
+                  break;
+                }
+              }
+            }
+
+            const rawPresets = doc.presets || [];
+            const presets = rawPresets.map((p) => {
+              if (typeof p === 'string') return p;
+              if (p && typeof p === 'object') {
+                return (locale === 'en' ? (p.name_en || p.name || p.id) : (p.name_zh_hans || p.name || p.id)) || p.id || '';
+              }
+              return String(p || '');
+            }).filter(Boolean);
+
+            const bundledRd = (core.reference_designs || []).find((r) => r.id === docId);
+            const repoUrl = doc.repo_url || bundledRd?.repo_url || '';
+
+            onlineRefDesigns.push({
+              type: 'reference_design',
+              id: docId,
+              title,
+              summary,
+              presets,
+              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/reference-designs/${docId}`, {
+                source: 'sensecraft_agent',
+                medium: 'solution_consult',
+                campaign: docId,
+                content: 'solution_landing',
+              }),
+              wiki_url: doc.wiki_url ? appendUtm(doc.wiki_url, {
+                source: 'sensecraft_agent',
+                medium: 'tech_wiki',
+                campaign: docId,
+              }) : '',
+              repo_url: repoUrl,
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        }
+      }
+
+      // If one collection returned results but the other was unavailable/failed/empty, supplement from bundled catalog
+      if ((onlineScenarios.length > 0 && onlineRefDesigns.length === 0) || (onlineRefDesigns.length > 0 && onlineScenarios.length === 0)) {
+        const tokens = qLower.split(/\s+/).filter(Boolean);
+        if (onlineScenarios.length === 0) {
+          for (const s of core.scenarios || []) {
+            if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
+
+            const haystack = [s.id, s.title?.zh, s.title?.en, s.subtitle?.zh, s.subtitle?.en, s.summary, ...(s.tags || [])].join(' ').toLowerCase();
+            const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
+            if (tokens.length === 0 || score > 0) {
+              onlineScenarios.push({
+                type: 'scenario',
+                id: s.id,
+                title: s.title?.[locale] || s.title?.zh || s.title?.en || s.id,
+                summary: s.subtitle?.[locale] || s.subtitle?.zh || s.summary || '',
+                tags: s.tags || [],
+                family_ids: s.family_ids || [],
+                reference_designs: s.reference_designs || [],
+                landing_url: appendUtm(s.landing_url || `https://www.seeedstudio.com/solutions/${s.id}`, {
+                  source: 'sensecraft_agent',
+                  medium: 'solution_consult',
+                  campaign: s.id,
+                  content: 'scenario_landing',
+                }),
+                repo_url: s.repo_url || '',
+                diagnostic_playbook: s.diagnostic_playbook || null,
+                source: 'bundled_manifest',
+              });
+            }
+          }
+        }
+        if (onlineRefDesigns.length === 0) {
+          for (const rd of core.reference_designs || []) {
+            if (rd.published === false || rd.visibility === 'staging' || rd.visibility === 'draft') continue;
+            const locKey = locale === 'zh' ? 'zh_hans' : locale;
+            if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
+
+            const haystack = [rd.id, rd.title?.zh, rd.title?.en, rd.summary?.zh, rd.summary?.en, ...(rd.presets || [])].join(' ').toLowerCase();
+            const score = tokens.reduce((acc, t) => (haystack.includes(t) ? acc + 1 : acc), 0);
+            if (tokens.length === 0 || score > 0) {
+              onlineRefDesigns.push({
+                type: 'reference_design',
+                id: rd.id,
+                title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
+                summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
+                presets: rd.presets || [],
+                landing_url: appendUtm(rd.landing_url || `https://www.seeedstudio.com/solutions/reference-designs/${rd.id}`, {
+                  source: 'sensecraft_agent',
+                  medium: 'solution_consult',
+                  campaign: rd.id,
+                  content: 'solution_landing',
+                }),
+                wiki_url: rd.wiki_url ? appendUtm(rd.wiki_url, {
+                  source: 'sensecraft_agent',
+                  medium: 'tech_wiki',
+                  campaign: rd.id,
+                }) : '',
+                repo_url: rd.repo_url || '',
+                diagnostic_playbook: rd.diagnostic_playbook || null,
+                source: 'bundled_manifest',
+              });
+            }
+          }
+        }
+      }
+
+      const mergedRecords = [];
+      const maxOnline = Math.max(onlineScenarios.length, onlineRefDesigns.length);
+      for (let i = 0; i < maxOnline && mergedRecords.length < limit; i++) {
+        if (i < onlineScenarios.length && mergedRecords.length < limit) {
+          mergedRecords.push(onlineScenarios[i]);
+        }
+        if (i < onlineRefDesigns.length && mergedRecords.length < limit) {
+          mergedRecords.push(onlineRefDesigns[i]);
+        }
+      }
+
+      if (mergedRecords.length > 0) {
         return createCatalogDto({
-          source: 'typesense',
+          source: (onlineScenarios.some(r => r.source === 'typesense') || onlineRefDesigns.some(r => r.source === 'typesense')) ? 'typesense' : 'bundled_manifest',
           freshness: 'FRESH',
-          records: records.slice(0, limit),
+          records: mergedRecords,
         });
       }
-    } catch (err) {
+    } catch {
       // Graceful fallback to offline core with notice
     }
   }
@@ -113,6 +371,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   const tokens = qLower.split(/\s+/).filter(Boolean);
 
   for (const s of core.scenarios || []) {
+    if (s.published === false || s.visibility === 'staging' || s.visibility === 'draft') continue;
+    const locKey = locale === 'zh' ? 'zh_hans' : locale;
+    if (s[`visibility_${locKey}`] === 'staging' || s[`visibility_${locKey}`] === 'draft') continue;
+
     const haystack = [
       s.id,
       s.title?.zh,
@@ -133,12 +395,24 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         tags: s.tags || [],
         family_ids: s.family_ids || [],
         reference_designs: s.reference_designs || [],
+        landing_url: appendUtm(s.landing_url || `https://www.seeedstudio.com/solutions/${s.id}`, {
+          source: 'sensecraft_agent',
+          medium: 'solution_consult',
+          campaign: s.id,
+          content: 'scenario_landing',
+        }),
+        repo_url: s.repo_url || '',
+        diagnostic_playbook: s.diagnostic_playbook || null,
         score,
       });
     }
   }
 
   for (const rd of core.reference_designs || []) {
+    if (rd.published === false || rd.visibility === 'staging' || rd.visibility === 'draft') continue;
+    const locKey = locale === 'zh' ? 'zh_hans' : locale;
+    if (rd[`visibility_${locKey}`] === 'staging' || rd[`visibility_${locKey}`] === 'draft') continue;
+
     const haystack = [
       rd.id,
       rd.title?.zh,
@@ -156,7 +430,19 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         title: rd.title?.[locale] || rd.title?.zh || rd.title?.en || rd.id,
         summary: rd.summary?.[locale] || rd.summary?.zh || rd.summary?.en || '',
         presets: rd.presets || [],
-        wiki_url: rd.wiki_url || '',
+        landing_url: appendUtm(rd.landing_url || `https://www.seeedstudio.com/solutions/reference-designs/${rd.id}`, {
+          source: 'sensecraft_agent',
+          medium: 'solution_consult',
+          campaign: rd.id,
+          content: 'solution_landing',
+        }),
+        wiki_url: rd.wiki_url ? appendUtm(rd.wiki_url, {
+          source: 'sensecraft_agent',
+          medium: 'tech_wiki',
+          campaign: rd.id,
+        }) : '',
+        repo_url: rd.repo_url || '',
+        diagnostic_playbook: rd.diagnostic_playbook || null,
         score,
       });
     }
@@ -166,15 +452,24 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   matchedScenarios.sort((a, b) => b.score - a.score);
   matchedRefDesigns.sort((a, b) => b.score - a.score);
 
-  const combined = [...matchedScenarios, ...matchedRefDesigns].slice(0, limit);
+  const combined = [];
+  const maxOffline = Math.max(matchedScenarios.length, matchedRefDesigns.length);
+  for (let i = 0; i < maxOffline && combined.length < limit; i++) {
+    if (i < matchedScenarios.length && combined.length < limit) {
+      combined.push(matchedScenarios[i]);
+    }
+    if (i < matchedRefDesigns.length && combined.length < limit) {
+      combined.push(matchedRefDesigns[i]);
+    }
+  }
 
   return createCatalogDto({
     source: 'bundled_manifest',
     freshness: 'FRESH',
     records: combined,
-    warnings: searchKey
-      ? ['Online Typesense request timed out; fell back to local bundled manifest.']
-      : ['No Typesense API key configured. Displaying verified local catalog.'],
+    warnings: (keySolution || keyRefDesign)
+      ? ['Online Typesense request timed out or returned no hits. Displaying verified local catalog.']
+      : ['No Typesense API key configured or baked. Displaying verified local catalog.'],
   });
 }
 
@@ -208,7 +503,15 @@ export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
       default_sku: family.default_sku,
       regions: family.regions || [],
       skus_count: (family.skus || []).length,
-      skus: (family.skus || []).slice(0, 10),
+      skus: (family.skus || []).slice(0, 10).map((s) => ({
+        ...s,
+        url: appendUtm(s.url, {
+          source: 'sensecraft_agent',
+          medium: 'bom_recommendation',
+          campaign: family.id,
+          content: `sku_${s.sku}`,
+        }),
+      })),
       physical_spec: family.physical_spec || null,
       required_accessories_count: (family.required_accessories || []).length,
       optional_accessories_count: (family.optional_accessories || []).length,
@@ -248,7 +551,12 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
       id: acc.id,
       name: acc.name,
       sku: acc.sku,
-      url: acc.url,
+      url: appendUtm(acc.url, {
+        source: 'sensecraft_agent',
+        medium: 'bom_recommendation',
+        campaign: family.id,
+        content: `required_${acc.id}`,
+      }),
       qty: acc.qty || 1,
       reason: acc.reason || 'Required for standard operation',
       applies_when: acc.applies_when || null,
@@ -268,7 +576,12 @@ export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
       id: acc.id,
       name: acc.name,
       sku: acc.sku,
-      url: acc.url,
+      url: appendUtm(acc.url, {
+        source: 'sensecraft_agent',
+        medium: 'bom_recommendation',
+        campaign: family.id,
+        content: `optional_${acc.id}`,
+      }),
       type: acc.type || 'peripheral',
       compatibility: {
         is_compatible: comp.isCompatible,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -19,9 +19,12 @@
     "lib",
     "catalog",
     "skills",
+    "docs",
     "README.md"
   ],
   "scripts": {
+    "build": "node scripts/bake-client-config.mjs",
+    "prepack": "node scripts/bake-client-config.mjs",
     "test": "node --test tests/cli.test.mjs",
     "install:self": "node bin/cli.js install",
     "status": "node bin/cli.js status",

package/skills/sensecraft/SKILL.md

@@ -16,7 +16,9 @@ Do NOT read all reference files at once. Determine the user's workflow state and
 | **DISCOVERY / CONSULT**<br>“我想做防跌倒监控”、“有智慧农场方案吗” | `references/consult-and-select.md` | `solution-cli hub search "<keyword>" --json` | **DO NOT run deploy**; user is exploring scenarios and has not confirmed hardware. |
 | **PROCUREMENT / VERIFY_BOM**<br>“买什么硬件？”、“J4012 需要配什么配件？” | `references/hardware-bom.md` | `solution-cli product accessories <id> --json` | **DO NOT fabricate** third-party SKUs or prices. Always distinguish REQUIRED vs OPTIONAL accessories. |
 | **ONBOARDING / PRECHECK**<br>“设备到了，插上了网线/USB”、“环境自检” | `references/diagnose.md` | `solution-cli doctor` / `sensecraft-engine device scan` | Freeze hardware requirements into DeploymentLockfile before proceeding to apply. |
-| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy --solution <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. |
+| **DEPLOYING / APPLY**<br>“开始安装”、“部署 fall_detection” | `references/deploy.md` | `sensecraft-engine deploy <id>` | **DEPLOYMENT CRITICAL SECTION**: Zero external commercial queries allowed during apply. |
+| **MANAGE / RECONFIG**<br>“改一下 MQTT 地址”、“查看已安装应用”、“重启服务”、“修改配置” | `references/device-management.md` | `curl BASE/api/docker-devices/local/config/<id>` | **Check before write**: Only alter `reconfigurable: true` fields; check current value before modifying. |
+| **CUSTOMIZE / SECONDARY_DEV**<br>“我想改源码”、“换成自研模型”、“改前端看板”、“GitHub 仓库” | `references/secondary-development.md` | `git clone <repo_url>` / `sensecraft-engine --solutions-dir` | **Never edit cached content**: Clone to user workspace, pair-program, test locally with `--solutions-dir`. |
 | **TROUBLESHOOTING**<br>“部署报错”、“黑屏”、“无视频流” | `references/error-catalog.md` | `sensecraft-engine logs` / `solution-cli product verify-compatibility` | Max 3 fix-and-retry rounds. Follow local auto-patching rule. |
 
 Capabilities that need the **SenseCraft Solution desktop app** (editing a
@@ -76,7 +78,7 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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.
+   - In CLI / Engine mode: copy the solution from `~/.sensecraft/content/solutions/<id>` into `./.sensecraft-work/solutions/<id>`, apply the minimal fix in that copy. Then re-run deployment with `sensecraft-engine deploy <id> --solutions-dir ./.sensecraft-work/solutions` so the engine 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
@@ -86,8 +88,22 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
 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)
+7. **Conversational tone & soft referral:** Agent is an IoT domain expert and
+   answers technical, business, hardware, and configuration questions directly
+   and thoroughly using local knowledge and tools. Do NOT dump raw link lists
+   or write pushy sales pitches. External links (`landing_url`, `wiki_url`,
+   product purchase URLs, `repo_url`) must be smoothly integrated as
+   supplemental reading / procurement / code exploration. All URLs generated by
+   `solution-cli` automatically carry silent UTM parameters
+   (`utm_source=sensecraft_agent`) for analytics attribution.
+8. **Proactive diagnosis & domain-specific questioning:** During solution consultation,
+   Agent must avoid one-way monologues. Proactively inspect the `diagnostic_playbook`
+   returned by `solution-cli hub search` (or cross-reference `references/consult-and-select.md` §3).
+   Ask 2–3 targeted domain questions explaining the engineering rationale (topology,
+   asset reuse, power/cabling, inspection speed/materials) to help the user converge
+   on the optimal hardware architecture and budget.
+
+## Step 0 — Install the engine and the solutions (when needed)
 
 1. Check whether it is installed: `sensecraft-engine --version`. If the command
    is not found, also try `~/.sensecraft/bin/sensecraft-engine --version`
@@ -105,14 +121,28 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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):
+3. If it is not installed, install it together with the solutions (ask the user
+   first, it downloads a program). If the user explicitly asks to upgrade or
+   reinstall, use the same solution-cli command; do not reinstall on every
+   deployment:
 
    **Recommended (Zero-friction via solution-cli, auto-detects existing app & agents)**:
    ```bash
-   npx @seeed-studio/solution-cli install -y
+   npx -y @seeed-studio/solution-cli@latest install -y
    ```
 
+   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
+   explicit agent selection or `--engine-path <path>` for a valid custom pin.
+   `--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
+   stops before writes; offline use requires a valid explicit local Engine path.
+
    **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
@@ -146,9 +176,8 @@ daemon is a host prerequisite, not evidence that a deployment has passed.
    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.
+   with code 2. After `content pull` / `update`, newly downloaded or updated
+   solutions are available to subsequent deployment and query commands.
 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