@blxzer/cursor-trellis 0.2.8 → 0.3.0

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/commands/continue.md

@@ -1,23 +1,23 @@
-# Continue Selected Task
-
-Resume work only when this live session already has a `selected_task`. If no task is selected, show the Task Dashboard and ask for an explicit route.
+# Continue Selected Task
+
+Resume work only when this live session already has a `selected_task`. If no task is selected, show the Task Dashboard and ask for an explicit route.
 
 ---
 
-## Step 1: Load Framework Context
-
-```bash
-{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
-```
-
-Confirms: selected task, Task Dashboard, git state, recent commits.
-
-If the output says `Selected task: none`, do not auto-resume a previous or unique task. Show the dashboard and ask the user to choose one route:
-
-- select a task with `{{PYTHON_CMD}} ./.trellis/scripts/task.py select <task>`
-- create a task
-- inspect details
-- continue without a task for No Task / Micro-Grill work
+## Step 1: Load Framework Context
+
+```bash
+{{PYTHON_CMD}} ./.trellis/scripts/get_context.py
+```
+
+Confirms: selected task, Task Dashboard, git state, recent commits.
+
+If the output says `Selected task: none`, do not auto-resume a previous or unique task. Show the dashboard and ask the user to choose one route:
+
+- select a task with `{{PYTHON_CMD}} ./.trellis/scripts/task.py select <task>`
+- create a task
+- inspect details
+- continue without a task for No Task / Micro-Grill work
 
 ## Step 2: Load the Phase Index
 
@@ -29,12 +29,12 @@ Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
 ## Step 3: Decide Where You Are
 
-When a task is selected, `get_context.py` shows the selected task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
+When a task is selected, `get_context.py` shows the selected task's `status` field. Route by `status` + artifact presence. This command replaces the user needing to remember the Trellis flow; it does not itself approve implementation.
 
-- `status=planning` + no `prd.md` → **1.1** (load `trellis-brainstorm`)
+- `status=planning` + no `prd.md` → **1.1** (load `cstl-brainstorm`)
 - `status=planning` + `prd.md` only → decide whether the task is lightweight or complex. Lightweight can move to **1.4** review; complex returns to **1.1** to add `design.md` + `implement.md`.
 - `status=planning` + complex artifacts complete + sub-agent jsonl not curated (only the seed `_example` row) → **1.3**
-- `status=planning` + required artifacts complete + required jsonl curated or inline mode → execution gate (run `task.py start-execution <task> --check`, report PASS, ask for explicit execution approval, then run `task.py start-execution <task> --approved`)
+- `status=planning` + required artifacts complete + required jsonl curated or inline mode → execution gate (run `task.py start-execution <task> --check`, report PASS, ask for explicit execution approval, then run `task.py start-execution <task> --approved`)
 - `status=in_progress` + implementation not started → **2.1**
 - `status=in_progress` + implementation done, not yet checked → **2.2**
 - `status=in_progress` + check passed → **3.1**

package/dist/templates/common/commands/start.md

@@ -36,14 +36,14 @@ Index files list the specific guideline docs to read when you actually start cod
 ## Step 4: Decide next action
 From Step 1 you know whether a task is selected.
 
-- If `Selected task: none` → show the Task Dashboard; do **not** load `trellis-continue`. For a **small** request without a task, use `trellis-micro-grill` first.
-- If a task **is** selected and you need the next workflow step → use `trellis-continue` instead of repeating Steps 1–3 here.
+- If `Selected task: none` → show the Task Dashboard; do **not** load `cstl-continue`. For a **small** request without a task, use `cstl-micro-grill` first.
+- If a task **is** selected and you need the next workflow step → use `cstl-continue` instead of repeating Steps 1–3 here.
 
 If `Selected task: none`, ask the user to choose: select a task, create a task, inspect details, or continue without a task.
 
 If a task is selected, check the task directory:
 
-- **Selected task status `planning` + no `prd.md`** → Phase 1.1. Load the `trellis-brainstorm` skill.
+- **Selected task status `planning` + no `prd.md`** → Phase 1.1. Load the `cstl-brainstorm` skill.
 - **Selected task status `planning` + `prd.md` exists** → stay in Planning / Execution Gate. Lightweight tasks can be PRD-only; complex tasks need `design.md` + `implement.md`. Run `task.py start-execution <task> --check` and request explicit execution approval before execution.
 - **Selected task status `in_progress`** → Phase 2 step 2.1. Load the step detail:
   ```bash
@@ -57,13 +57,13 @@ If a task is selected, check the task directory:
 
 | User intent | Skill |
 |---|---|
-| Resume **selected** in-progress task | `trellis-continue` |
-| New feature / unclear requirements | `trellis-brainstorm` |
-| Small request, no task yet | `trellis-micro-grill` |
-| About to write code | `trellis-before-dev` |
-| Done coding / quality check | `trellis-check` |
-| Session wrap-up after Phase 3.4 commit | `trellis-finish-work` |
-| Stuck / fixed same bug multiple times | `trellis-break-loop` |
-| Learned something worth capturing | `trellis-update-spec` |
+| Resume **selected** in-progress task | `cstl-continue` |
+| New feature / unclear requirements | `cstl-brainstorm` |
+| Small request, no task yet | `cstl-micro-grill` |
+| About to write code | `cstl-before-dev` |
+| Done coding / quality check | `cstl-check` |
+| Session wrap-up after Phase 3.4 commit | `cstl-finish-work` |
+| Stuck / fixed same bug multiple times | `cstl-break-loop` |
+| Learned something worth capturing | `cstl-update-spec` |
 
 Full rules + anti-rationalization table in `.trellis/workflow.md`.

package/dist/templates/common/index.d.ts

@@ -23,7 +23,7 @@ export interface CommonBundledSkillFile {
     content: string;
 }
 export interface CommonBundledSkill {
-    /** Skill directory name, e.g. "trellis-meta" */
+    /** Skill directory name, e.g. "cstl-meta" */
     name: string;
     /** Files that must be written under the skill directory */
     files: CommonBundledSkillFile[];

package/dist/templates/common/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/common/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAuBH,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAOD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AAuCD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D"}