@blxzer/cursor-trellis 0.2.7 → 0.2.9

package/dist/commands/validate-rules.js

@@ -0,0 +1,33 @@
+import chalk from "chalk";
+import { assertCursorRulesValid, formatRuleValidationErrors, validateRulesDir, validateTemplateRules, } from "../utils/validate-rules.js";
+export async function runValidateRules(cwd, options = {}) {
+    if (options.dir) {
+        const result = validateRulesDir(options.dir);
+        if (!result.ok) {
+            console.error(chalk.red("Cursor rules validation failed:"));
+            console.error(formatRuleValidationErrors(result));
+            process.exit(1);
+        }
+        console.log(chalk.green(`✓ Cursor rules valid (${options.dir})`));
+        return;
+    }
+    const templateResult = validateTemplateRules();
+    if (!templateResult.ok) {
+        console.error(chalk.red("Cursor rules template validation failed:"));
+        console.error(formatRuleValidationErrors(templateResult));
+        process.exit(1);
+    }
+    console.log(chalk.green("✓ Cursor rules templates valid"));
+    if (options.templatesOnly) {
+        return;
+    }
+    try {
+        assertCursorRulesValid(cwd);
+        console.log(chalk.green(`✓ Cursor rules installation valid (${cwd})`));
+    }
+    catch (error) {
+        console.error(chalk.red("Error:"), error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=validate-rules.js.map

package/dist/commands/validate-rules.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-rules.js","sourceRoot":"","sources":["../../src/commands/validate-rules.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,4BAA4B,CAAC;AAOpC,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,GAAW,EACX,UAAgC,EAAE;IAElC,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7C,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC,CAAC;YAC5D,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,yBAAyB,OAAO,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC;QAClE,OAAO;IACT,CAAC;IAED,MAAM,cAAc,GAAG,qBAAqB,EAAE,CAAC;IAC/C,IAAI,CAAC,cAAc,CAAC,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC,CAAC;QACrE,OAAO,CAAC,KAAK,CAAC,0BAA0B,CAAC,cAAc,CAAC,CAAC,CAAC;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC,CAAC;IAE3D,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;QAC1B,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,sBAAsB,CAAC,GAAG,CAAC,CAAC;QAC5B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,sCAAsC,GAAG,GAAG,CAAC,CAAC,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EACnB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/configurators/cursor2plus-local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cursor2plus-local.d.ts","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAwB5E"}
+{"version":3,"file":"cursor2plus-local.d.ts","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAsB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB5E"}

package/dist/configurators/cursor2plus-local.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { DIR_NAMES } from "../constants/paths.js";
 import { ensureDir, writeFile } from "../utils/file-writer.js";
-import { cursor2plusPatchScript, cursor2plusReadme, cursor2plusConfigExample, subagentModelsExample, trellisTaskModelsJson5Example, trellisTaskModelsConfigPy, } from "../templates/trellis/local/index.js";
+import { cursor2plusPatchScript, cursor2plusReadme, cursor2plusSmokeScript, cursor2plusConfigExample, subagentModelsExample, trellisTaskModelsJson5Example, trellisTaskModelsConfigPy, } from "../templates/trellis/local/index.js";
 /**
  * Materialize Cursor++ BYOK local operator bundle (strategy C).
  * Native Cursor API users can ignore. Never overwrites config.local.json.
@@ -12,6 +12,7 @@ export async function writeCursor2plusLocalBundle(cwd) {
     ensureDir(bundleDir);
     await writeFile(path.join(bundleDir, "patch_wpelc8.py"), cursor2plusPatchScript);
     await writeFile(path.join(bundleDir, "trellis_task_models_config.py"), trellisTaskModelsConfigPy);
+    await writeFile(path.join(bundleDir, "smoke.py"), cursor2plusSmokeScript);
     await writeFile(path.join(bundleDir, "README.md"), cursor2plusReadme);
     await writeFile(path.join(bundleDir, "config.local.json.example"), cursor2plusConfigExample);
     await writeFile(path.join(localRoot, "subagent-models.json.example"), subagentModelsExample);

package/dist/configurators/cursor2plus-local.js.map

@@ -1 +1 @@
-{"version":3,"file":"cursor2plus-local.js","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAW;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACtD,SAAS,CAAC,SAAS,CAAC,CAAC;IAErB,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACjF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,+BAA+B,CAAC,EACrD,yBAAyB,CAC1B,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtE,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC,EACjD,wBAAwB,CACzB,CAAC;IAEF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,EACpD,qBAAqB,CACtB,CAAC;IACF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mCAAmC,CAAC,EACzD,6BAA6B,CAC9B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cursor2plus-local.js","sourceRoot":"","sources":["../../src/configurators/cursor2plus-local.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,6BAA6B,EAC7B,yBAAyB,GAC1B,MAAM,qCAAqC,CAAC;AAE7C;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,GAAW;IAC3D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC;IACtD,SAAS,CAAC,SAAS,CAAC,CAAC;IAErB,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,iBAAiB,CAAC,EAAE,sBAAsB,CAAC,CAAC;IACjF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,+BAA+B,CAAC,EACrD,yBAAyB,CAC1B,CAAC;IACF,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,EAAE,sBAAsB,CAAC,CAAC;IAC1E,MAAM,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,EAAE,iBAAiB,CAAC,CAAC;IACtE,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC,EACjD,wBAAwB,CACzB,CAAC;IAEF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,EACpD,qBAAqB,CACtB,CAAC;IACF,MAAM,SAAS,CACb,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,mCAAmC,CAAC,EACzD,6BAA6B,CAC9B,CAAC;AACJ,CAAC"}

package/dist/migrations/manifests/0.2.2.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.2",
-  "description": "v0.2.2 — smart-search wrapper path fix (backfilled manifest).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.2 / @blxzer/cursor-trellis-core 0.2.2**\n\n### Fixed\n- fix: smart-search wrapper path resolution\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.2\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Manifest backfilled for npm continuity; shipped without repo manifest."
+{
+  "version": "0.2.2",
+  "description": "v0.2.2 — smart-search wrapper path fix (backfilled manifest).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.2 / @blxzer/cursor-trellis-core 0.2.2**\n\n### Fixed\n- fix: smart-search wrapper path resolution\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.2\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Manifest backfilled for npm continuity; shipped without repo manifest."
 }

package/dist/migrations/manifests/0.2.4.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.4",
-  "description": "v0.2.4 — aligned core/cli publish (backfilled manifest).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.4 / @blxzer/cursor-trellis-core 0.2.4**\n\n### Changed\n- chore: synchronized @blxzer/cursor-trellis-core with CLI release line\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.4\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Manifest backfilled for npm continuity."
+{
+  "version": "0.2.4",
+  "description": "v0.2.4 — aligned core/cli publish (backfilled manifest).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.4 / @blxzer/cursor-trellis-core 0.2.4**\n\n### Changed\n- chore: synchronized @blxzer/cursor-trellis-core with CLI release line\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.4\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Manifest backfilled for npm continuity."
 }

package/dist/migrations/manifests/0.2.5.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.5",
-  "description": "v0.2.5 — smart-search bin wrapper path fix.",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.5 / @blxzer/cursor-trellis-core 0.2.5**\n\n### Fixed\n- fix(bin): smart-search wrapper path under npm/bin/\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.5\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Matches chore(release): 0.2.5 on main."
+{
+  "version": "0.2.5",
+  "description": "v0.2.5 — smart-search bin wrapper path fix.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.5 / @blxzer/cursor-trellis-core 0.2.5**\n\n### Fixed\n- fix(bin): smart-search wrapper path under npm/bin/\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.5\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Matches chore(release): 0.2.5 on main."
 }

package/dist/migrations/manifests/0.2.6.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.6",
-  "description": "v0.2.6 — public docs expansion (skills, subagents, task-system).",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.6 / @blxzer/cursor-trellis-core 0.2.6**\n\n### Changed\n- docs: GitHub docs — workflow, retrieval, skills, subagents, task-system, spec-system\n- docs(community): Linux.do release companion doc\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.6\ntrellis update\n```",
-  "migrations": [],
-  "notes": "Published at 0.2.6; manifest added in 0.2.7 release train."
+{
+  "version": "0.2.6",
+  "description": "v0.2.6 — public docs expansion (skills, subagents, task-system).",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.6 / @blxzer/cursor-trellis-core 0.2.6**\n\n### Changed\n- docs: GitHub docs — workflow, retrieval, skills, subagents, task-system, spec-system\n- docs(community): Linux.do release companion doc\n\n### Upgrade\n```bash\nnpm install -g @blxzer/cursor-trellis@0.2.6\ntrellis update\n```",
+  "migrations": [],
+  "notes": "Published at 0.2.6; manifest added in 0.2.7 release train."
 }

package/dist/migrations/manifests/0.2.7.json

@@ -1,9 +1,9 @@
-{
-  "version": "0.2.7",
-  "description": "v0.2.7 — execution strategy suggest + contract-aware workflow dispatch.",
-  "breaking": false,
-  "recommendMigrate": false,
-  "changelog": "**@blxzer/cursor-trellis 0.2.7 / @blxzer/cursor-trellis-core 0.2.7**\n\n### Added\n- feat(task): `suggest-execution-strategy`, `execution-strategy-rules.json`, drift WARN on `start-execution --check`\n- docs: `execution-strategy.md` guide; backfilled manifests 0.2.2–0.2.6\n\n### Changed\n- workflow: Phase 2 dispatch follows `execution_mode` (`worker` vs `inline` vs `child-task`)\n\nRun `trellis update` in each project.",
-  "migrations": [],
-  "notes": "Full code-touching tasks default-suggest worker + main-worktree; contract in implement.md remains authoritative."
+{
+  "version": "0.2.7",
+  "description": "v0.2.7 — execution strategy suggest + contract-aware workflow dispatch.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.7 / @blxzer/cursor-trellis-core 0.2.7**\n\n### Added\n- feat(task): `suggest-execution-strategy`, `execution-strategy-rules.json`, drift WARN on `start-execution --check`\n- docs: `execution-strategy.md` guide; backfilled manifests 0.2.2–0.2.6\n\n### Changed\n- workflow: Phase 2 dispatch follows `execution_mode` (`worker` vs `inline` vs `child-task`)\n\nRun `trellis update` in each project.",
+  "migrations": [],
+  "notes": "Full code-touching tasks default-suggest worker + main-worktree; contract in implement.md remains authoritative."
 }

package/dist/migrations/manifests/0.2.8.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.2.8",
+  "description": "v0.2.8 — Cursor platform adaptation Phase 0 + Phase 1+2: validate-rules gate, agent entry-points, cursor2plus safety, retrieval compliance, evidence pack, task path fallback.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.8 / @blxzer/cursor-trellis-core 0.2.8**\n\n### Added\n- feat(cursor): `trellis validate-rules` hard gate + `pnpm mirror-check` for rules/agents templates\n- feat(cursor): agent templates open with Entry points + Context source (Layer 2 PRIMARY)\n- feat(cursor2plus): Method 2.5 safety gate (`--approve`, `--check-compat`, `smoke.py`, Native safe-to-ignore)\n- feat(retrieval): BYOK/Native compliance, `unknown` conservative, LSP caveat, telemetry planned/executed split\n- feat(cli): task.py select fallback tip + `generate_dispatch_prompt.py --task` primary fallback\n- feat(retrieval): evidence pack integration (finish/check cite pack) + research prompt provider caveats\n\n### Changed\n- agent templates now open with Entry points / Context source sections\n- retrieval router: LSP/GO_TO_DEFINITION → codegraph + Read + caveat\n- `patch_wpelc8.py` bare invocation no longer implicit writes\n\nRun `trellis update` in each project.",
+  "migrations": [],
+  "notes": "init/update now run assertCursorRulesValid(); Cursor++ patch requires --approve; unknown cursorEnv routes conservatively to BYOK + warning."
+}

package/dist/migrations/manifests/0.2.9.json

@@ -0,0 +1,9 @@
+{
+  "version": "0.2.9",
+  "description": "v0.2.9 — Adapt to @blxzer/smart-search 0.1.15: research flags, structured citations in evidence manifests, bundled skill sync for non-Cursor platforms.",
+  "breaking": false,
+  "recommendMigrate": false,
+  "changelog": "**@blxzer/cursor-trellis 0.2.9 / @blxzer/cursor-trellis-core 0.2.9**\n\n### Added\n- feat(retrieval): `run_smart_search.py` passthrough for `--locale-scope`, `--dry-run`, `--progress` (deep-research)\n- feat(retrieval): Trellis evidence manifest preserves `outputSchemaVersion`, structured citation fields, and `dryRun`\n\n### Changed\n- chore(deps): bump `@blxzer/smart-search` to `^0.1.15`\n- docs: sync bundled `smart-search-cli` skill from smart-search v0.1.15 (`.agents/skills/` platforms only; Cursor stays commands-only)\n- docs: retrieval-daily-guide documents smart-search 0.1.15 research flags and Cursor skill-surface policy\n\nRun `trellis update` in each project.",
+  "migrations": [],
+  "notes": "Cursor projects still use run_smart_search.py + rules — no new .cursor/skills/ entries."
+}

package/dist/templates/common/bundled-skills/smart-search-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: smart-search-cli
-description: CLI-first web research and source retrieval through the local smart-search command. Use when the agent needs current web facts (not repo symbol lookup). Prefer this over Cursor WebSearch/WebFetch unless the user explicitly opts in. Covers fact checking, URL fetch, site mapping, official/API/docs search, and reproducible evidence via Skill + CLI.
+description: CLI-first web research and source retrieval through the local smart-search command. Use when Codex needs current web search, source-backed fact checking, URL fetching, site mapping, official/API/documentation search, or reproducible search evidence via Skill + CLI instead of MCP tools.
 ---
 
 # Smart Search CLI
@@ -12,8 +12,7 @@ Use the local `smart-search` command as the default execution layer for web rese
 1. Run `smart-search doctor --format json` when configuration or availability is uncertain.
 2. If `doctor` reports missing configuration, use `smart-search setup` or `smart-search config set KEY VALUE` when the user provides keys. Do not ask users to edit global environment variables by default.
 3. If OpenAI-compatible `search` hangs or times out after `doctor` succeeds, run `smart-search diagnose openai-compatible --format markdown` and use its summary/recommendation. This one command tests quick chat plus real search-shape `stream=false` and `stream=true`.
-4. If `doctor` returns `ok: true`, use only `smart-search` CLI subcommands for web research. Do not call platform built-in web search (`WebSearch`/`WebFetch` in Cursor, or native web tools elsewhere) in the same task unless the user explicitly requests it.
-4b. **Cursor fallback** — when `doctor` is not ok, or `run_smart_search.py` / CLI status is `not_configured` or `failed`, use **Cursor WebSearch/WebFetch** for external facts, then **persist** to `{TASK}/research/<topic>.md` with YAML frontmatter `source: cursor-web-fallback` and URLs cited. Do not treat fallback output as verified without cross-check when claim risk is high.
+4. If `doctor` returns `ok: true`, use only `smart-search` CLI subcommands for web research. Do not call Codex native web search in the same task.
 5. For every research question, run a bilingual `smart-search search` pair: one Chinese-source query and one English-source query. Save both JSON outputs.
 6. Use `smart-search search` as the first hop for realtime, broad exploration, community signals, multi-source summaries, and routing metadata. The default broad pass is bilingual, not Zhipu-backed.
 7. Do not use `smart-search zhipu-search` in normal workflows. Zhipu is deprecated and not used by default routing because quota may be unavailable; the command remains only for manual legacy compatibility when the user explicitly asks for it.
@@ -123,7 +122,7 @@ Default evidence policy is `fetch_before_claim`: key claims in the final answer
 
 Live Deep Research executor:
 
-- `smart-search research QUERY [--budget quick|standard|deep] [--evidence-dir PATH] [--fallback auto|off] [--format json|markdown|content] [--output PATH]` runs the staged workflow directly.
+- `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--format json|markdown|content] [--output PATH]` runs the staged workflow directly. Use `--dry-run` to preview plan/routing without live providers; `--progress` for stderr stage logs; `--locale-scope cn` or `en` to skip bilingual discovery when cost matters.
 - Default `--fallback auto` permits same-capability fallback inside selected routes. Use `--fallback off` only for debugging or deterministic provider checks.
 - Research output includes `final_answer`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `fallback_used`, `degraded`, `route_policy_version`, and `evidence_dir`.
 - The synthesis is evidence-only. It may cite fetched/read evidence, but it must not cite unfetched discovery candidates as proof.
@@ -137,7 +136,7 @@ Research provider advantage routing:
 - Jina: known public URL, PDF, and arXiv clean extraction; ReaderLM-v2 requires `JINA_API_KEY`.
 - Firecrawl: robust fetch fallback, JS-heavy/dynamic pages, browser-like extraction, OCR/PDF/structured extraction.
 
-Safe research overrides are `SMART_SEARCH_RESEARCH_PREFERRED_PROVIDERS` and `SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS`. They may reorder or disable providers only within capabilities the provider already supports; they must not move a provider across capability boundaries.
+Safe research overrides are `SMART_SEARCH_RESEARCH_PREFERRED_PROVIDERS`, `SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS`, and `SMART_SEARCH_CACHE` (`on` by default; `off` disables the in-process provider TTL cache). Preferred/disabled provider CSV values may reorder or disable providers only within capabilities the provider already supports; they must not move a provider across capability boundaries.
 
 Deep Research test coverage for workflow maintenance should verify trigger phrases, normal search requests that should not trigger Deep Research, required `research_plan` fields, allowed tool whitelist, bilingual search steps, `fetch_before_claim`, evidence output paths, capability boundaries, `intent_signals`, `capability_plan`, `gap_check`, simple current prompts such as `深度搜索一下最近的比特币行情`, docs/API prompts, claim-verification prompts, user-provided URL fetch-first flows, missing-provider failure guidance, and the rule that fixed topic recipe ids are not required schema. When real keys are available and the user expects live checks, a small live pass can run `doctor`, two broad `search` commands (Chinese and English), one `exa-search`, and one `fetch`.
 
@@ -262,10 +261,10 @@ Use this when the user wants work that can be inspected, resumed, or audited.
 - Prefer the CLI's local config file managed by `smart-search setup` / `smart-search config`.
 - Environment variables remain supported for CI and advanced users, and override the local config file.
 - Do not ask users to set Windows global API-key environment variables by default.
-- If keys are changed with `smart-search config set`, rerun the CLI; no Cursor reload is needed.
-- If PATH is changed, a new terminal or Cursor reload may be needed.
+- If keys are changed with `smart-search config set`, rerun the CLI; no Codex restart is needed.
+- If PATH is changed, a new terminal or Codex restart may be needed.
 - On Windows, the default local config file is `%LOCALAPPDATA%\smart-search\config.json`. Linux/macOS default to `~/.config/smart-search/config.json`.
-- In sandboxed runtimes (Cursor agent-sandbox subprocesses, containers, CI) where the default config directory is not writable or must be pinned, set `SMART_SEARCH_CONFIG_DIR` to an absolute writable path. The CLI uses it for both config and relative logs and skips default-directory selection.
+- In sandboxed runtimes (Codex CLI, containers, CI) where the default config directory is not writable or must be pinned, set `SMART_SEARCH_CONFIG_DIR` to an absolute writable path. The CLI uses it for both config and relative logs and skips default-directory selection.
 - The default research evidence root is `evidence` under the active config directory. Set `SMART_SEARCH_EVIDENCE_DIR` only when evidence needs a separate absolute location; `config path` and `doctor` report both the configured and resolved evidence paths.
 - Earlier Windows source defaults used `~\.config\smart-search\config.json`, while some installs were already pinned to `%LOCALAPPDATA%\smart-search` through `SMART_SEARCH_CONFIG_DIR`. If the new default file is missing but the old file exists, `doctor` reports `legacy_windows_home` as the active source so upgrades do not silently lose configuration. It also reports the override value and whether it matches the current default.
 - Use `smart-search doctor --format json` for agent/script parsing and `smart-search doctor --format markdown` when a human wants a detailed diagnostic report.

package/dist/templates/common/bundled-skills/smart-search-cli/references/cli-contract.md

@@ -10,10 +10,10 @@
 - Environment variables remain supported for CI and advanced users, and override the local config file.
 - Do not depend on MCP inline `env` values or committed API-key environment variables for CLI use.
 - On Windows with mise, the managed package name is `npm:@konbakuyomu/smart-search`; the executable remains `smart-search`. Diagnose mise managed installs with `mise ls "npm:@konbakuyomu/smart-search"` and `mise which smart-search` (the bare name `smart-search` is the bin, not a mise tool identifier).
-- On Windows, the default config file is `%LOCALAPPDATA%\smart-search\config.json`. Linux/macOS default to `~/.config/smart-search/config.json`.
-- `SMART_SEARCH_CONFIG_DIR` is an advanced override for CI, containers, sandboxes, or portable installs. The CLI uses it for config and relative logs and skips default-directory selection.
-- The default research evidence root is `evidence` under the active config directory. `SMART_SEARCH_EVIDENCE_DIR` overrides that root; relative values resolve under the active config directory and absolute values are used as-is.
-- Earlier Windows source defaults used `~\.config\smart-search\config.json`, while some installs were already pinned to `%LOCALAPPDATA%\smart-search` through `SMART_SEARCH_CONFIG_DIR`. If the new Windows default file is missing but the old file exists, the active config source is `legacy_windows_home` so upgrades do not silently lose configuration. Diagnostics must expose the override value and whether it matches the current default.
+- On Windows, the default config file is `%LOCALAPPDATA%\smart-search\config.json`. Linux/macOS default to `~/.config/smart-search/config.json`.
+- `SMART_SEARCH_CONFIG_DIR` is an advanced override for CI, containers, sandboxes, or portable installs. The CLI uses it for config and relative logs and skips default-directory selection.
+- The default research evidence root is `evidence` under the active config directory. `SMART_SEARCH_EVIDENCE_DIR` overrides that root; relative values resolve under the active config directory and absolute values are used as-is.
+- Earlier Windows source defaults used `~\.config\smart-search\config.json`, while some installs were already pinned to `%LOCALAPPDATA%\smart-search` through `SMART_SEARCH_CONFIG_DIR`. If the new Windows default file is missing but the old file exists, the active config source is `legacy_windows_home` so upgrades do not silently lose configuration. Diagnostics must expose the override value and whether it matches the current default.
 
 ## Commands
 
@@ -21,10 +21,10 @@
 - `smart-search fetch URL [--format json|markdown|content] [--output PATH]`
 - `smart-search exa-search QUERY [--num-results N] [--search-type neural|keyword|auto] [--include-text] [--include-highlights] [--start-published-date YYYY-MM-DD] [--include-domains DOMAIN...] [--exclude-domains DOMAIN...] [--category NAME] [--format json|markdown|content] [--output PATH]`
 - `smart-search exa-similar URL [--num-results N] [--format json|markdown|content] [--output PATH]`
-- `smart-search zhipu-search QUERY [--count N] [--search-engine NAME] [--search-recency-filter VALUE] [--search-domain-filter DOMAIN] [--content-size medium|high] [--format json|markdown|content] [--output PATH]`
+- `smart-search zhipu-search QUERY [--count N] [--search-engine NAME] [--search-recency-filter VALUE] [--search-domain-filter DOMAIN] [--content-size medium|high] [--format json|markdown|content] [--output PATH]` — **DEPRECATED**: emits a stderr warning on every invocation; the subcommand, the `research_discovery` zhipu branch, and `providers/zhipu.py` will be removed on the schedule in README § "Deprecation notices".
 - `smart-search context7-library NAME [QUERY] [--format json|markdown|content] [--output PATH]`
 - `smart-search context7-docs LIBRARY_ID QUERY [--format json|markdown|content] [--output PATH]`
-- `smart-search research QUERY [--budget quick|standard|deep] [--evidence-dir PATH] [--fallback auto|off] [--format json|markdown|content] [--output PATH]`
+- `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--format json|markdown|content] [--output PATH]`
 - `smart-search map URL [--instructions TEXT] [--max-depth N] [--max-breadth N] [--limit N] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]`
 - `smart-search doctor [--format json|markdown|content] [--output PATH]`
 - `smart-search diagnose openai-compatible [--timeout SECONDS] [--format json|markdown] [--output PATH]`
@@ -71,7 +71,7 @@ Successful search output includes `ok`, `query`, `primary_api_mode`, `content`,
 
 `--format json` is the stable machine-readable contract for agents and scripts. JSON output remains parseable and uses readable non-ASCII text when the terminal encoding supports it.
 
-`--format markdown` is the human-readable report format. `doctor --format markdown` must render a detailed diagnostic report with overall status, active/default/legacy config paths, log path resolution, evidence path resolution, file-logging status, masked config values with sources, minimum profile, capability status, main-search provider checks, provider connectivity checks, model metadata, and full long error/message detail instead of falling back to raw JSON. `diagnose openai-compatible --format markdown` must render a short copy-pasteable troubleshooting report with masked config, quick chat check, real search-shape `stream=false` and `stream=true` checks, a plain-language summary, and a next command. Provider list commands such as `exa-search`, `exa-similar`, `zhipu-search`, `context7-library`, and `map` render result lists or a clear no-results message.
+`--format markdown` is the human-readable report format. `doctor --format markdown` must render a detailed diagnostic report with overall status, active/default/legacy config paths, log path resolution, evidence path resolution, file-logging status, masked config values with sources, minimum profile, capability status, main-search provider checks, provider connectivity checks, model metadata, and full long error/message detail instead of falling back to raw JSON. `diagnose openai-compatible --format markdown` must render a short copy-pasteable troubleshooting report with masked config, quick chat check, real search-shape `stream=false` and `stream=true` checks, a plain-language summary, and a next command. Provider list commands such as `exa-search`, `exa-similar`, `zhipu-search`, `context7-library`, and `map` render result lists or a clear no-results message.
 
 `--format content` prints only the `content` field for content-bearing commands such as `search`, `fetch`, `context7-docs`, and `research`. Commands without a `content` field, including `doctor` and `config`, must print a compact non-empty text summary rather than an empty stdout.
 
@@ -90,17 +90,17 @@ Exa domain filters:
 
 Fetch output includes `ok`, `url`, `provider`, `content`, `provider_attempts`, `fallback_used`, and `elapsed_ms`.
 
-Zhipu Web Search API legacy setup:
-
-- `ZHIPU_API_URL` defaults to `https://open.bigmodel.cn/api`.
-- `ZHIPU_SEARCH_ENGINE` defaults to `search_std`.
-- Official Web Search API service values include `search_std`, `search_pro`, `search_pro_sogou`, and `search_pro_quark`.
-- `smart-search setup --zhipu-api-url URL --zhipu-search-engine ENGINE` saves these values in non-interactive mode.
-- Interactive setup no longer recommends or prompts for Zhipu in the default flow. Use `config set` or non-interactive flags only for explicit manual legacy compatibility.
-- `config set ZHIPU_SEARCH_ENGINE VALUE` must remain free-form so newly added official services do not require a CLI release.
-- `zhipu-search` corresponds to Zhipu Web Search API, not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.
-- `zhipu-search` is deprecated and not used by default routing because quota may be unavailable. Default source discovery uses bilingual `search` through Tavily / Firecrawl when configured.
-- `TAVILY_API_URL` only affects Tavily and does not proxy Zhipu.
+Zhipu Web Search API legacy setup:
+
+- `ZHIPU_API_URL` defaults to `https://open.bigmodel.cn/api`.
+- `ZHIPU_SEARCH_ENGINE` defaults to `search_std`.
+- Official Web Search API service values include `search_std`, `search_pro`, `search_pro_sogou`, and `search_pro_quark`.
+- `smart-search setup --zhipu-api-url URL --zhipu-search-engine ENGINE` saves these values in non-interactive mode.
+- Interactive setup no longer recommends or prompts for Zhipu in the default flow. Use `config set` or non-interactive flags only for explicit manual legacy compatibility.
+- `config set ZHIPU_SEARCH_ENGINE VALUE` must remain free-form so newly added official services do not require a CLI release.
+- `zhipu-search` corresponds to Zhipu Web Search API, not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.
+- `zhipu-search` is deprecated and not used by default routing because quota may be unavailable. Default source discovery uses bilingual `search` through Tavily / Firecrawl when configured.
+- `TAVILY_API_URL` only affects Tavily and does not proxy Zhipu.
 - `TAVILY_TIMEOUT_SECONDS` controls the Tavily `doctor` connectivity timeout. It defaults to `60` so slower pooled/community endpoints are not incorrectly marked unhealthy by the diagnostic check.
 
 Jina Reader setup:
@@ -132,7 +132,7 @@ Map output includes `ok`, `base_url`, `results`, `response_time`, `url`, and `el
 
 Research executor output includes `ok`, `mode=deep_research_execution`, `query_mode=research`, `question`, `budget`, `research_plan`, `routing_decision`, `stage_results`, `discovery_sources`, `final_answer`, `content`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `providers_used`, `fallback_used`, `degraded`, `route_policy_version`, `evidence_dir`, `minimum_profile_ok`, `capability_status`, and `elapsed_ms`. The embedded `research_plan` carries `intent_signals`, `decomposition`, `capability_plan`, `evidence_policy`, `steps`, and `gap_check`. Citations must come only from fetched/read `evidence_items`; discovery sources are candidates until fetched. If evidence cannot close, `research` returns degraded gaps instead of unsupported claims.
 
-Diagnostic output masks keys, reports `config_file` / `config_dir` / `config_dir_source` / `default_config_file` / Windows legacy config metadata / `config_dir_override_value` / `config_dir_override_matches_default` / `log_dir_config_value` / `resolved_log_dir` / `evidence_dir_config_value` / `resolved_evidence_dir` / `file_logging_enabled` / `config_sources` / `primary_api_mode` / `primary_api_mode_source` / provider timeout values / `capability_status` / `minimum_profile_ok`, and includes `main_search_connection_tests` plus connection test objects for Exa, Tavily, Zhipu, Context7, and Firecrawl. `primary_connection_test` remains as a backward-compatible alias for the first configured main provider check. OpenAI-compatible provider health must be validated through `/chat/completions`; `/models` is supplementary metadata and must not be the health gate. Firecrawl currently reports whether `FIRECRAWL_API_KEY` is configured; it is not a live Firecrawl request.
+Diagnostic output masks keys, reports `config_file` / `config_dir` / `config_dir_source` / `default_config_file` / Windows legacy config metadata / `config_dir_override_value` / `config_dir_override_matches_default` / `log_dir_config_value` / `resolved_log_dir` / `evidence_dir_config_value` / `resolved_evidence_dir` / `file_logging_enabled` / `config_sources` / `primary_api_mode` / `primary_api_mode_source` / provider timeout values / `capability_status` / `minimum_profile_ok`, and includes `main_search_connection_tests` plus connection test objects for Exa, Tavily, Zhipu, Context7, and Firecrawl. `primary_connection_test` remains as a backward-compatible alias for the first configured main provider check. OpenAI-compatible provider health must be validated through `/chat/completions`; `/models` is supplementary metadata and must not be the health gate. Firecrawl currently reports whether `FIRECRAWL_API_KEY` is configured; it is not a live Firecrawl request.
 
 When a Windows user reports that different versions seem to use different config paths, diagnose in this order: `config_dir_source`, `config_dir_override_value`, `config_dir_override_matches_default`, then `legacy_windows_config_exists`. A source of `environment` with `config_dir_override_matches_default=true` means the active path is pinned by `SMART_SEARCH_CONFIG_DIR` but is functionally the same as the current default. Do not delete either config file or the user-level override until the upgraded CLI has been verified with `config path` and `doctor` checks.
 
@@ -158,12 +158,12 @@ Deep Research must not require fixed topic recipe ids such as `current_market_re
 - `gap_check`: how the executor verifies that key claims have fetched evidence or downgrades unsupported claims to unverified candidates.
 - `final_answer_policy`: how to cite fetched evidence and list unverified candidates.
 
-Each `steps[]` item must include `id`, `subquestion_id`, `tool`, `purpose`, `command`, and `output_path`. Allowed `tool` values are `search`, `exa-search`, `exa-similar`, `context7-library`, `context7-docs`, `fetch`, and `map`; these map to existing CLI commands only. `doctor` is a `preflight` action, not a `steps[]` item. Use the system-aware evidence root from `resolved_evidence_dir` or an explicit `--evidence-dir` absolute directory for `output_path` values.
+Each `steps[]` item must include `id`, `subquestion_id`, `tool`, `purpose`, `command`, and `output_path`. Allowed `tool` values are `search`, `exa-search`, `exa-similar`, `context7-library`, `context7-docs`, `fetch`, and `map`; these map to existing CLI commands only. `doctor` is a `preflight` action, not a `steps[]` item. Use the system-aware evidence root from `resolved_evidence_dir` or an explicit `--evidence-dir` absolute directory for `output_path` values.
 
 Capability boundaries:
 
-- `search`: broad bilingual discovery and synthesis through `main_search`; use returned `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning` as orchestration signals, not as claim proof.
-- `zhipu-search`: deprecated manual compatibility command. Do not include it in default research plans.
+- `search`: broad bilingual discovery and synthesis through `main_search`; use returned `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning` as orchestration signals, not as claim proof.
+- `zhipu-search`: deprecated manual compatibility command. Do not include it in default research plans.
 - `context7-library` and `context7-docs`: library, SDK, API, framework, and documentation intent. Prefer Context7 before Exa for docs/API questions.
 - `exa-search`: low-noise source discovery for official domains, papers, product pages, known domains, and trusted pages. It is not the default second hop for every high-risk or verification task.
 - `exa-similar`: adjacent-source discovery when a known reliable URL is available.
@@ -175,8 +175,8 @@ Default Deep Research orchestration:
 
 1. Run `smart-search doctor --format json` as preflight when configuration is uncertain.
 2. `research` generates `intent_signals`, `decomposition`, and `capability_plan` internally instead of selecting a fixed topic recipe.
-3. Use planned bilingual `search ... --validation balanced --extra-sources 1..3` steps for Chinese-source and English-source broad discovery.
-4. Add planned `context7-library` plus `context7-docs` for docs/API/library topics, `exa-search` for official/trusted-domain or paper discovery, `exa-similar` for URL-neighbor discovery, or `map` only when the capability boundary matches the intent.
+3. Use planned bilingual `search ... --validation balanced --extra-sources 1..3` steps for Chinese-source and English-source broad discovery.
+4. Add planned `context7-library` plus `context7-docs` for docs/API/library topics, `exa-search` for official/trusted-domain or paper discovery, `exa-similar` for URL-neighbor discovery, or `map` only when the capability boundary matches the intent.
 5. Use `fetch` for key URLs before making claim-level statements.
 6. Run `gap_check`: fetch missing evidence for key claims or downgrade them to unverified candidates.
 
@@ -184,12 +184,12 @@ Default Deep Research orchestration:
 
 When the user wants the CLI to execute the live workflow directly, call:
 
-```powershell
-$Config = smart-search config path --format json | ConvertFrom-Json
-$EvidenceDir = Join-Path $Config.resolved_evidence_dir "YYYYMMDD-HHMM-topic"
-New-Item -ItemType Directory -Force -Path $EvidenceDir | Out-Null
-smart-search research "question" --budget deep --fallback auto --format json --output (Join-Path $EvidenceDir "research.json")
-```
+```powershell
+$Config = smart-search config path --format json | ConvertFrom-Json
+$EvidenceDir = Join-Path $Config.resolved_evidence_dir "YYYYMMDD-HHMM-topic"
+New-Item -ItemType Directory -Force -Path $EvidenceDir | Out-Null
+smart-search research "question" --budget deep --fallback auto --format json --output (Join-Path $EvidenceDir "research.json")
+```
 
 `research --fallback auto` permits same-capability fallback inside selected routes. `research --fallback off` tries only the first selected provider in each capability route and is for debugging or provider comparison. Dynamic routing may reorder providers only inside the same capability. Every attempt must record capability, provider, status, error type, latency, and result count.
 
@@ -197,7 +197,7 @@ Research provider advantage routing:
 
 - Context7 first for library/API/framework docs and docs retrieval.
 - Exa for official domains, papers, product/company pages, date/domain-filtered low-noise discovery, and adjacent-source discovery.
-- Tavily for broad bilingual source discovery and site maps.
+- Tavily for broad bilingual source discovery and site maps.
 - Jina for known public URL, PDF, and arXiv clean extraction; ReaderLM-v2 requires `JINA_API_KEY`.
 - Firecrawl for robust fetch fallback, JS-heavy/dynamic/browser-like extraction, OCR/PDF/structured extraction.
 
@@ -211,7 +211,7 @@ Planner closeout lessons:
 
 Deep Research test coverage should verify trigger phrases, normal search requests that should not trigger Deep Research, required `research_plan` fields, allowed tool whitelist, `fetch_before_claim`, evidence paths, capability boundaries, `intent_signals`, `capability_plan`, `gap_check`, simple current prompts such as `深度搜索一下最近的比特币行情`, docs/API prompts, claim-verification prompts, user-provided URL fetch-first flows, missing-provider failure guidance, research provider advantage routing, same-capability research fallback, and the rule that fixed topic recipe ids are not required schema. When real keys are available, a small live `research` check confirms staged behavior end to end. If an issue is found, fix the affected docs/code/tests and rerun until it passes or is proven to be an external provider blocker.
 
-Setup and config output should include `ok` and `config_file`; `config path` and `doctor` should include `resolved_evidence_dir`. Saved API keys must be masked in command output.
+Setup and config output should include `ok` and `config_file`; `config path` and `doctor` should include `resolved_evidence_dir`. Saved API keys must be masked in command output.
 
 Interactive setup behavior:
 
@@ -264,13 +264,13 @@ Agent timeout handling contract:
 - Legacy `SMART_SEARCH_API_URL`, `SMART_SEARCH_API_KEY`, `SMART_SEARCH_API_MODE`, and `SMART_SEARCH_MODEL` are unsupported config keys. `config set` / `config unset` must return a parameter error for them.
 - Standard minimum profile requires `main_search`, `docs_search`, and fetch capability. Missing required capabilities produce a configuration error.
 - Jina satisfies fetch capability only when `JINA_API_KEY` is configured. Anonymous Jina Reader does not satisfy `standard`.
-- Same-capability fallback is allowed; cross-capability fallback is not. Context7 is not used for unrelated broad web queries, and page extraction providers are not used as docs search providers.
-- `main_search`: OpenAI-compatible Chat Completions.
-- `web_search`: `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured. Zhipu is deprecated from default routing and is not selected automatically for Chinese/current/domestic searches.
-- `docs_search`: explicit keyword-based docs/API/library/framework intent. Context7 is first for library/API/docs intent, then Exa for official-domain, paper, product-page, trusted-site, or low-noise supplemental discovery.
-- Fetch capability: Tavily first, then Jina Reader with `JINA_API_KEY`, then Firecrawl.
-- `search --validation strict` uses the same bilingual web_search policy as balanced mode when source discovery providers are configured. Strict queries without primary, docs, fetch, or explicit source evidence can still fail with `evidence_error`; use `--extra-sources N`, source-first commands such as `exa-search`, or `fetch` when citable evidence is required.
-- `search` calls Tavily and/or Firecrawl for `extra_sources` only when `--extra-sources` is greater than 0.
+- Same-capability fallback is allowed; cross-capability fallback is not. Context7 is not used for unrelated broad web queries, and page extraction providers are not used as docs search providers.
+- `main_search`: OpenAI-compatible Chat Completions.
+- `web_search`: `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured. Zhipu is deprecated from default routing and is not selected automatically for Chinese/current/domestic searches.
+- `docs_search`: explicit keyword-based docs/API/library/framework intent. Context7 is first for library/API/docs intent, then Exa for official-domain, paper, product-page, trusted-site, or low-noise supplemental discovery.
+- Fetch capability: Tavily first, then Jina Reader with `JINA_API_KEY`, then Firecrawl.
+- `search --validation strict` uses the same bilingual web_search policy as balanced mode when source discovery providers are configured. Strict queries without primary, docs, fetch, or explicit source evidence can still fail with `evidence_error`; use `--extra-sources N`, source-first commands such as `exa-search`, or `fetch` when citable evidence is required.
+- `search` calls Tavily and/or Firecrawl for `extra_sources` only when `--extra-sources` is greater than 0.
 - If both Tavily and Firecrawl are configured, `search --extra-sources N` gives about 60% of extra source slots to Tavily and the remainder to Firecrawl.
 - `extra_sources` are retrieved in parallel and are not automatically used by the primary model to verify its answer.
 - `fetch` and known-URL `search "https://..."` use the same fetch fallback chain.
@@ -278,7 +278,7 @@ Agent timeout handling contract:
 - `research` uses capability-first plus provider-advantage routing. Fallback remains same-capability only; low-quality fetches, challenge pages, empty content, auth/rate/timeout/provider errors, and runtime errors are failed attempts that may trigger same-capability fallback.
 - `map` uses Tavily only.
 - `exa-search` and `exa-similar` use Exa only.
-- `zhipu-search` uses Zhipu only and is retained as a deprecated manual compatibility command.
+- `zhipu-search` uses Zhipu only and is retained as a deprecated manual compatibility command.
 - `context7-library` and `context7-docs` use Context7 only.
 - Runtime config priority is environment variables first, then local config file, then defaults.
 - `setup` and `config` read/write the local Smart Search config file and do not call providers.
@@ -286,17 +286,17 @@ Agent timeout handling contract:
 
 ## Routing Heuristics
 
-- Use `exa-search --include-domains` when official documentation domains are known.
-- Use `context7-library` / `context7-docs` for explicit docs/API/SDK/library/framework intent when Context7 is configured.
-- Use the bilingual `search` pair for Chinese, domestic, current, or mixed-language source discovery. Do not use Zhipu unless the user explicitly asks for the deprecated manual route.
+- Use `exa-search --include-domains` when official documentation domains are known.
+- Use `context7-library` / `context7-docs` for explicit docs/API/SDK/library/framework intent when Context7 is configured.
+- Use the bilingual `search` pair for Chinese, domestic, current, or mixed-language source discovery. Do not use Zhipu unless the user explicitly asks for the deprecated manual route.
 - Use `exa-search --start-published-date` for recency-constrained source discovery.
 - Use `exa-similar` when a known good page is available and adjacent sources are needed.
 - Use `search --format content` when a human wants only the generated answer body.
 - Use `fetch --format markdown` or `fetch --format content` for user-supplied URLs or when exact page text matters.
 - Use `map` before fetching many pages from a documentation site.
-- Keep `search --extra-sources` small (`1` to `3`) unless broad coverage is requested.
-- Treat `search --extra-sources N` as explicit candidate discovery; default `extra_sources` is `0`, and candidates still need `fetch` before claim-level citation.
-- For current news or high-risk claims, prefer source discovery plus `fetch`; do not treat broad `search.content` plus `extra_sources` as claim-level verification.
+- Keep `search --extra-sources` small (`1` to `3`) unless broad coverage is requested.
+- Treat `search --extra-sources N` as explicit candidate discovery; default `extra_sources` is `0`, and candidates still need `fetch` before claim-level citation.
+- For current news or high-risk claims, prefer source discovery plus `fetch`; do not treat broad `search.content` plus `extra_sources` as claim-level verification.
 
 ## Maintenance Guardrails
 

package/dist/templates/common/bundled-skills/trellis-cursor2plus-setup/SKILL.md

@@ -20,7 +20,7 @@ Do **not** ask the user to hand-edit slugs (`model-xxxxx`) unless they prefer it
 - User says they use **Cursor++ BYOK** and want per–subagent-type models.
 - After Cursor++ **providers** change: re-list, adjust fallbacks, re-patch.
 
-Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; this skill does not apply.
+Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; this skill does not apply. Tell the user: **`.trellis/local/cursor2plus/` is safe to ignore or delete** unless they use Cursor++ BYOK.
 
 ## Workflow
 
@@ -40,7 +40,7 @@ Native **Cursor API** (no Cursor++): **stop** — frontmatter `model:` works; th
 5. Run:
    ```bash
    python ./.trellis/local/cursor2plus/patch_wpelc8.py --print-map
-   python ./.trellis/local/cursor2plus/patch_wpelc8.py
+   python ./.trellis/local/cursor2plus/patch_wpelc8.py --apply --approve
    ```
 6. Tell user: **Developer: Reload Window** in Cursor (once per patch).
 7. If stderr shows `WARN ... using fallback`, explain that primary was missing from current `providers.json` and fallback was used — suggest updating primary/fallback names, not panicking.

package/dist/templates/common/commands/finish-work.md

@@ -4,6 +4,18 @@ Wrap up the current session: archive the selected task (and any other completed-
 
 Before archive, confirm `verify.md` includes Phase 3.3 **Learning decision** (`update-spec` | `no-update` | `unsure`) and gate-compatible evidence per `.trellis/spec/guides/durable-learning-decision-guide.md`. Run `task.py archive <task> --check` when unsure.
 
+## Evidence pack reference (optional — graceful skip)
+
+When the selected task has `{TASK}/research/retrieval-pack-latest.json` (written by the research-end `stop` hook via `get_context --mode retrieval-pack`, or by an explicit pack run during Phase 3.1):
+
+1. Read the JSON; note top `contextPack.selected` items (`title`, `source`, `reference`, `score`) and `collection` counts.
+2. Ensure `verify.md` includes an `## Evidence pack reference` section citing those ranked sources or documenting explicit gaps.
+3. If the section is missing, add it before proceeding to archive.
+
+If the file does not exist: **skip silently** — no error, no user prompt. Pack absence is normal when the task did not use research/smart-search.
+
+Pack format: `version`, `source` (`retrieval-pack-orchestrator`), `contextPack.selected[]`, `scoredEvidence`, `collection`. Smart-search manifests that feed scoring live under `{TASK}/research/smart-search/<run-id>/` (from `run_smart_search.py`).
+
 ## Step 1: Survey current state
 
 ```bash

package/dist/templates/common/skills/check.md

@@ -70,6 +70,10 @@ Run the project's lint, type-check, and test commands. Fix any failures before p
 - [ ] **`verify.md` lists unresolved retrieval gaps** — external facts still unverified, missing `research/` or `research/smart-search/` evidence, or claims without source/Git/test corroboration
 - [ ] If `{TASK}/research/retrieval-pack-latest.json` exists, top `contextPack.selected` items are cited or gaps are explicitly noted in `verify.md`
 
+**Evidence pack (graceful):** Path `{TASK}/research/retrieval-pack-latest.json`. If absent, skip — no error.
+
+When present, Read the pack and ensure `verify.md` has `## Evidence pack reference` citing `contextPack.selected` (`title`, `source`, `reference`, `score`) or explicit gaps. Empty `selected` with existing `research/` → note stale pack or scoring failure in `verify.md`.
+
 ## Step 5: Cross-Layer Dimensions (if applicable)
 
 Skip this step if your change is confined to a single layer.

package/dist/templates/cursor/agents/trellis-check.md

@@ -3,6 +3,17 @@ name: trellis-check
 description: Trellis quality check agent. Use this exact agent for Trellis task verification, check.jsonl context injection, and self-fixing code review. Do not use generic/default/generalPurpose agents for Trellis checks.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
+
+## Entry points
+
+- **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
+- **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent check` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
+
+## Context source
+
+- **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-check)`.
+- **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
+
 # Check Agent
 
 You are the Check Agent in the Trellis workflow.
@@ -107,6 +118,27 @@ If failed, fix issues and re-run.
 - [ ] **`verify.md` lists unresolved retrieval gaps** (unverified external facts, missing `research/` or `research/smart-search/` evidence, claims without source/Git/test proof)
 - [ ] If `{TASK}/research/retrieval-pack-latest.json` exists (research-end hook), cite top ranked items or document gaps in `verify.md`
 
+**Evidence pack (graceful):** Pack path is `{TASK}/research/retrieval-pack-latest.json`. If missing, skip this block — no error.
+
+When the pack exists:
+
+```bash
+# Optional: confirm path from selected task
+python ./.trellis/scripts/task.py selected --source
+```
+
+Read `{TASK}/research/retrieval-pack-latest.json` and use `contextPack.selected` (top items: `title`, `source`, `reference`, `score`). Add or update `verify.md` with:
+
+```markdown
+## Evidence pack reference
+
+- Pack: `{TASK}/research/retrieval-pack-latest.json` (contextPack.selected=N, artifacts=M, smart-search=K)
+- Cited: <title> — <source> — <reference>
+- Gaps: <any high-score omitted items or unverified external claims>
+```
+
+If `contextPack.selected` is empty but research artifacts exist, document why (budget, failed manifests, or stale pack) instead of silently ignoring the pack.
+
 ---
 
 ## Report Format

package/dist/templates/cursor/agents/trellis-implement.md

@@ -3,6 +3,17 @@ name: trellis-implement
 description: Trellis implementation agent. Use this exact agent for Trellis task implementation, implement.jsonl context injection, and hook-injection tests. Do not use generic/default/generalPurpose agents for Trellis implementation. No git commit allowed.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__exa__web_search_exa, mcp__exa__get_code_context_exa
 ---
+
+## Entry points
+
+- **Agent session:** Open this agent file manually in a new chat — context from this file + your main-session prompt.
+- **Task dispatch:** Run `python ./.trellis/scripts/generate_dispatch_prompt.py --agent implement` → pass stdout as `Task(..., prompt=...)` — context from the Layer 2 prompt.
+
+## Context source
+
+- **Layer 2 prompt = PRIMARY (guaranteed)** — always generate via CLI before `Task(trellis-implement)`.
+- **Hook `additional_context` = best-effort only** — Cursor #158452: not guaranteed to reach the model; optimization / fallback only.
+
 # Implement Agent
 
 You are the Implement Agent in the Trellis workflow.