@seeed-studio/solution-cli 0.1.0 → 0.3.0

package/lib/knowledge.js

@@ -0,0 +1,516 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import https from 'node:https';
+import http from 'node:http';
+import { createCatalogDto } from './catalog-dto.js';
+import { assertCompatibility, COMPATIBILITY_STATUS } from './compatibility.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+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.
+ *
+ * @returns {Object} Bundled knowledge core data
+ */
+export function loadKnowledgeCore() {
+  if (cachedKnowledgeCore) return cachedKnowledgeCore;
+  if (!fs.existsSync(DATA_FILE)) {
+    throw new Error(`Knowledge core manifest not found at ${DATA_FILE}. Run "npm run build:knowledge" to generate.`);
+  }
+  const raw = fs.readFileSync(DATA_FILE, 'utf-8');
+  cachedKnowledgeCore = JSON.parse(raw);
+  return cachedKnowledgeCore;
+}
+
+/**
+ * Performs an HTTP GET request with a timeout.
+ *
+ * @param {string} urlStr
+ * @param {Object} headers
+ * @param {number} timeoutMs
+ * @returns {Promise<Object>}
+ */
+function fetchJson(urlStr, headers = {}, timeoutMs = 2500) {
+  return new Promise((resolve, reject) => {
+    const url = new URL(urlStr);
+    const client = url.protocol === 'https:' ? https : http;
+    const req = client.get(url, { headers, timeout: timeoutMs }, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            resolve(JSON.parse(body));
+          } catch (e) {
+            reject(new Error(`Invalid JSON from ${urlStr}: ${e.message}`));
+          }
+        } else {
+          reject(new Error(`HTTP ${res.statusCode} from ${urlStr}`));
+        }
+      });
+    });
+    req.on('timeout', () => {
+      req.destroy();
+      reject(new Error(`Timeout after ${timeoutMs}ms from ${urlStr}`));
+    });
+    req.on('error', reject);
+  });
+}
+
+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.
+ *
+ * @param {Object} options
+ * @param {string} options.query - Free text search query
+ * @param {'zh' | 'en'} [options.locale='zh'] - Language preference
+ * @param {number} [options.limit=5] - Maximum number of results
+ * @returns {Promise<Object>} Standardized Catalog DTO
+ */
+export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
+  const qLower = (query || '').toLowerCase().trim();
+  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 keys are provided and not explicitly running offline
+  if ((keySolution || keyRefDesign) && !process.env.SENSECRAFT_OFFLINE_ONLY) {
+    try {
+      const core = loadKnowledgeCore();
+      const onlinePromises = [];
+
+      if (keySolution) {
+        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&per_page=${limit}`;
+        onlinePromises.push(
+          fetchJson(solUrl, { 'X-TYPESENSE-API-KEY': keySolution }, 2500)
+            .then((data) => ({ type: 'scenario', hits: data?.hits || [] }))
+            .catch(() => ({ type: 'scenario', hits: [] }))
+        );
+      }
+
+      if (keyRefDesign) {
+        const rdUrl = `${host}/collections/reference_design/documents/search?q=${encodeURIComponent(query)}&query_by=name_zh_hans,name_en,summary_zh_hans,summary_en,tags&per_page=${limit}`;
+        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 onlineRecords = [];
+
+      for (const res of results) {
+        if (res.type === 'scenario') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            const docId = doc.id || doc.slug;
+            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;
+
+            onlineRecords.push({
+              type: 'scenario',
+              id: docId,
+              title,
+              summary,
+              tags,
+              family_ids: doc.family_ids || [],
+              reference_designs: doc.reference_designs || [],
+              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/${docId}`, {
+                source: 'sensecraft_agent',
+                medium: 'solution_consult',
+                campaign: docId,
+                content: 'scenario_landing',
+              }),
+              repo_url: '',
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        } else if (res.type === 'reference_design') {
+          for (const hit of res.hits) {
+            const doc = hit.document || {};
+            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 || 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;
+                }
+              }
+            }
+
+            onlineRecords.push({
+              type: 'reference_design',
+              id: docId,
+              title,
+              summary,
+              presets: doc.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: doc.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${docId}`,
+              diagnostic_playbook: pb,
+              source: 'typesense',
+            });
+          }
+        }
+      }
+
+      if (onlineRecords.length > 0) {
+        return createCatalogDto({
+          source: 'typesense',
+          freshness: 'FRESH',
+          records: onlineRecords.slice(0, limit),
+        });
+      }
+    } catch {
+      // Graceful fallback to offline core with notice
+    }
+  }
+
+  // Offline fallback search over knowledge-core
+  const core = loadKnowledgeCore();
+  const matchedScenarios = [];
+  const matchedRefDesigns = [];
+
+  const tokens = qLower.split(/\s+/).filter(Boolean);
+
+  for (const s of core.scenarios || []) {
+    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, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedScenarios.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,
+        score,
+      });
+    }
+  }
+
+  for (const rd of core.reference_designs || []) {
+    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, token) => (haystack.includes(token) ? acc + 1 : acc), 0);
+    if (tokens.length === 0 || score > 0) {
+      matchedRefDesigns.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 || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${rd.id}`,
+        diagnostic_playbook: rd.diagnostic_playbook || null,
+        score,
+      });
+    }
+  }
+
+  // Sort by score descending and take top results
+  matchedScenarios.sort((a, b) => b.score - a.score);
+  matchedRefDesigns.sort((a, b) => b.score - a.score);
+
+  const combined = [...matchedScenarios, ...matchedRefDesigns].slice(0, limit);
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: combined,
+    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.'],
+  });
+}
+
+/**
+ * Queries product family information, SKUs, and official purchase links.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with product details
+ */
+export function queryProductFamily(familyId, { locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      title: family.title?.[locale] || family.title?.zh || family.title?.en || family.id,
+      default_sku: family.default_sku,
+      regions: family.regions || [],
+      skus_count: (family.skus || []).length,
+      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,
+    }],
+  });
+}
+
+/**
+ * Queries and verifies accessories for a product family, running physical compatibility checks.
+ *
+ * @param {string} familyId
+ * @param {Object} [options]
+ * @param {string} [options.sku] - Specific host SKU
+ * @param {string} [options.locale='zh']
+ * @returns {Object} Catalog DTO with structured, verified accessories
+ */
+export function queryAccessories(familyId, { sku = null, locale = 'zh' } = {}) {
+  const core = loadKnowledgeCore();
+  const family = core.product_families?.[familyId];
+
+  if (!family) {
+    return createCatalogDto({
+      source: 'bundled_manifest',
+      freshness: 'FRESH',
+      records: [],
+      warnings: [`Product family "${familyId}" not found in local catalog.`],
+    });
+  }
+
+  const hostPhysicalSpec = family.physical_spec || null;
+
+  // Process required accessories
+  const required = (family.required_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'REQUIRED',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      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,
+      compatibility: {
+        is_compatible: comp.isCompatible,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  // Process optional accessories
+  const optional = (family.optional_accessories || []).map((acc) => {
+    const comp = assertCompatibility(hostPhysicalSpec, acc);
+    return {
+      category: 'OPTIONAL',
+      id: acc.id,
+      name: acc.name,
+      sku: acc.sku,
+      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,
+        status: comp.status,
+        details: comp.dimensions,
+      },
+    };
+  });
+
+  return createCatalogDto({
+    source: 'bundled_manifest',
+    freshness: 'FRESH',
+    records: [{
+      family_id: family.id,
+      host_title: family.title?.[locale] || family.title?.zh || family.title?.en,
+      host_sku: sku || family.default_sku,
+      physical_spec: hostPhysicalSpec,
+      accessories: {
+        required,
+        optional,
+      },
+    }],
+  });
+}
+
+/**
+ * Generates an immutable DeploymentLockfile to isolate deployment apply from external network.
+ *
+ * @param {Object} options
+ * @param {string} options.solutionId
+ * @param {string} options.solutionVersion
+ * @param {Array<string>} options.selectedHardware
+ * @param {Array<Object>} [options.verifiedCompatibility=[]]
+ * @returns {Object} DeploymentLockfile
+ */
+export function createDeploymentLockfile({
+  solutionId,
+  solutionVersion = '1.0.0',
+  selectedHardware = [],
+  verifiedCompatibility = [],
+}) {
+  return {
+    $schema: 'https://spec.seeedstudio.com/schemas/v2/deployment-lock.json',
+    solution_id: solutionId,
+    solution_version: solutionVersion,
+    locked_at: new Date().toISOString(),
+    dataset_version: '2026-10-13.1',
+    selected_hardware: selectedHardware,
+    compatibility_assertions: verifiedCompatibility,
+    unresolved_requirements: [],
+    network_policy: {
+      commercial_queries_allowed: false,
+      apply_isolated: true,
+    },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seeed-studio/solution-cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Zero-friction installer and CLI runner for SenseCraft Engine and AI Agent Skills (Work Buddy, Claude Code, Codex, CodeBuddy)",
   "type": "module",
   "main": "./lib/installer.js",
@@ -17,10 +17,14 @@
   "files": [
     "bin",
     "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

@@ -1,16 +1,25 @@
 ---
 name: sensecraft
-description: Deploy, manage, and troubleshoot SenseCraft / Seeed Studio edge IoT solutions (智慧农业, 摔倒检测, 边缘安全, 智慧仓库, 语音助手, people counting, face recognition 等) on hardware devices (NVIDIA Jetson, Raspberry Pi 树莓派, reComputer, reCamera, SenseCAP Watcher, Grove Vision AI, ESP32) using the `sensecraft-engine` command-line engine (no desktop app needed). Use whenever the user asks to deploy (部署), install (安装方案), test, inspect, or troubleshoot a SenseCraft edge IoT solution or configure devices and sensors. Changing a solution's configuration needs the desktop app (references/app-only.md).
+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.
 ---
 
 # SenseCraft Solution
 
-This skill drives the `sensecraft-engine` command-line engine. It works in any
-agent that can read files and run shell commands. Every step is a
-`sensecraft-engine` command; the engine starts its own background instance when
-a command needs one. Do not call the instance's HTTP port with `curl`: use the
-CLI, and `sensecraft-engine api <METHOD> <path>` for anything without its own
-command.
+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**.
+
+## Workflow Routing & Progressive Disclosure
+
+Do NOT read all reference files at once. Determine the user's workflow state and intent, then load **at most ONE** reference file on demand:
+
+| User State & Intent | Reference to Load | Primary CLI Tool to Call | Guardrails & Forbidden Actions |
+|---|---|---|---|
+| **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. |
+| **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
 solution's configuration, the app's `/api/ai/context`, diagnosing through the
@@ -79,6 +88,20 @@ 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.
+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 (every task)