@seeed-studio/solution-cli 0.3.0 → 0.3.1

package/docs/cli-guide.md

@@ -37,15 +37,28 @@
 ## 2. 安装与 Agent 技能挂载
 
 ### 2.1 一键免安装即时调用 (推荐)
-无需全局安装，利用 `npx` 即可随时调用：
+无需全局安装，安装或按需升级 Engine 与 Agent Skill 使用同一条命令：
 ```bash
-# 查看帮助与版本
-npx @seeed-studio/solution-cli --help
-
-# 交互式扫描并为本机所有 Agent 安装技能
-npx @seeed-studio/solution-cli install
+npx -y @seeed-studio/solution-cli@latest install -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
@@ -100,11 +113,11 @@ solution-cli hub search "跌倒检测" --json
      把 SenseCAP 土壤与空气传感器接到 Home Assistant 看板上，支持本地私有 ChirpStack 运行，断网可用。
      预设模式: cloud, tts_local, chirpstack_local
      现场工况诊断提问指引:
-       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？ 
+       • 监测区域是集中式连栋温室大棚（百米级），还是大面积户外大田/果园（数公里级）？
          (决断考量: 大棚内百米级可采用 RS485 总线；广域大田推荐 LoRaWAN 远距无线，配 SenseCAP M2 网关)
-       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？ 
+       • 现场测点是否有 220V 市电供电，还是需要野外太阳能板/锂电池长续航供电？
          (决断考量: 市电支持持续高频数据上报；无市电需选配支持休眠唤醒的超低功耗无线传感器)
-       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？ 
+       • 需要监测哪些核心指标？仅空气温湿度，还是包括土壤剖面水肥墒情（水分/EC/pH）？
          (决断考量: 决定是配置多合一微气象站，还是选配工业级土壤三参数探头与变送器)
 ```
 
@@ -209,7 +222,7 @@ solution-cli product accessories recomputer_j40 --json
 4. **驱动本地快速联调**：
    使用 `--solutions-dir` 参数，强制底层引擎加载本地修改版方案，彻底不碰官方缓存：
    ```bash
-   sensecraft-engine deploy --solution fall_detection --solutions-dir ./my-solutions/solutions
+   sensecraft-engine deploy fall_detection --solutions-dir ./my-solutions/solutions
    ```
 
 ---

package/lib/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 };
 }

package/lib/knowledge.js

@@ -144,8 +144,12 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       const core = loadKnowledgeCore();
       const onlinePromises = [];
 
+      const locKey = locale === 'zh' ? 'zh_hans' : locale;
+      const fetchLimit = Math.max(limit * 5, 30);
+
       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}`;
+        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 || [] }))
@@ -154,7 +158,8 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       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}`;
+        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 || [] }))
@@ -163,13 +168,19 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
       }
 
       const results = await Promise.all(onlinePromises);
-      const onlineRecords = [];
+      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);
@@ -178,22 +189,23 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               : (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}`;
 
-            onlineRecords.push({
-              type: 'scenario',
+            onlineScenarios.push({
+              type: docType,
               id: docId,
               title,
               summary,
               tags,
               family_ids: doc.family_ids || [],
               reference_designs: doc.reference_designs || [],
-              landing_url: appendUtm(`https://www.seeedstudio.com/solutions/${docId}`, {
+              landing_url: appendUtm(rawLanding, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
                 campaign: docId,
-                content: 'scenario_landing',
+                content: `${docType}_landing`,
               }),
-              repo_url: '',
+              repo_url: doc.repo_url || '',
               diagnostic_playbook: pb,
               source: 'typesense',
             });
@@ -201,6 +213,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         } 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)
@@ -209,7 +225,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               ? (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;
+            let pb = doc.diagnostic_playbook || core.diagnostic_playbooks?.[docId] || null;
             if (!pb) {
               for (const sc of core.scenarios || []) {
                 if ((sc.reference_designs || []).includes(docId)) {
@@ -219,12 +235,24 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
               }
             }
 
-            onlineRecords.push({
+            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: doc.presets || [],
+              presets,
               landing_url: appendUtm(`https://www.seeedstudio.com/solutions/reference-designs/${docId}`, {
                 source: 'sensecraft_agent',
                 medium: 'solution_consult',
@@ -236,7 +264,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
                 medium: 'tech_wiki',
                 campaign: docId,
               }) : '',
-              repo_url: doc.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${docId}`,
+              repo_url: repoUrl,
               diagnostic_playbook: pb,
               source: 'typesense',
             });
@@ -244,11 +272,90 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
         }
       }
 
-      if (onlineRecords.length > 0) {
+      // 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: onlineRecords.slice(0, limit),
+          records: mergedRecords,
         });
       }
     } catch {
@@ -264,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,
@@ -298,6 +409,10 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
   }
 
   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,
@@ -326,7 +441,7 @@ export async function searchHub({ query = '', locale = 'zh', limit = 5 } = {}) {
           medium: 'tech_wiki',
           campaign: rd.id,
         }) : '',
-        repo_url: rd.repo_url || `https://github.com/suharvest/sensecraft-solutions/tree/main/solutions/${rd.id}`,
+        repo_url: rd.repo_url || '',
         diagnostic_playbook: rd.diagnostic_playbook || null,
         score,
       });
@@ -337,7 +452,16 @@ 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',