@blxzer/cursor-trellis 0.3.4 → 0.3.6

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

@@ -14,18 +14,17 @@ Use the local `smart-search` command as the default execution layer for web rese
 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 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.
-8. Use `smart-search context7-library` / `context7-docs` first for library, SDK, API, framework, or documentation intent.
-9. Use `smart-search exa-search` for official domains, papers, product pages, trusted sites, and low-noise discovery. Do not treat Exa as the universal second hop for every high-risk or verification task.
-10. Use `smart-search search --extra-sources N` for Tavily/Firecrawl horizontal candidates, and `smart-search fetch` for page text that can support final claims.
-11. Use `smart-search exa-similar` when the user gives a representative URL and wants related pages or neighboring sources.
-12. Use `smart-search fetch` when the user gives a URL or a claim depends on page content.
-13. Use `smart-search map` when a documentation site or domain structure matters.
-14. To change the main-search model, use `smart-search config set OPENAI_COMPATIBLE_MODEL ...`.
-15. For current-news, policy, finance, health, or other high-risk facts, do not answer from broad `search.content` alone. Use the bilingual search pair plus intent-specific sources: Context7 for docs/API, Exa for official/trusted domains or papers, then `fetch` key pages and summarize only what fetched text supports.
-16. Use `smart-search research "question" --format json` when the user wants the CLI to run live Deep Research end to end instead of only planning. It executes plan -> discover -> fetch/read -> gap check -> evidence-only synthesis.
-17. Preserve command lines and source URLs in your answer. Prefer citing fetched pages or `primary_sources`; treat `extra_sources` as follow-up candidates, not verified evidence for generated claims.
+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 via Tavily / Firecrawl when configured.
+7. Use `smart-search context7-library` / `context7-docs` first for library, SDK, API, framework, or documentation intent.
+8. Use `smart-search exa-search` for official domains, papers, product pages, trusted sites, and low-noise discovery. Do not treat Exa as the universal second hop for every high-risk or verification task.
+9. Use `smart-search search --extra-sources N` for Tavily/Firecrawl horizontal candidates, and `smart-search fetch` for page text that can support final claims.
+10. Use `smart-search exa-similar` when the user gives a representative URL and wants related pages or neighboring sources.
+11. Use `smart-search fetch` when the user gives a URL or a claim depends on page content.
+12. Use `smart-search map` when a documentation site or domain structure matters.
+13. To change the main-search model, use `smart-search config set OPENAI_COMPATIBLE_MODEL ...` (or `XAI_MODEL ...` for the xAI route).
+14. For current-news, policy, finance, health, or other high-risk facts, do not answer from broad `search.content` alone. Use the bilingual search pair plus intent-specific sources: Context7 for docs/API, Exa for official/trusted domains or papers, then `fetch` key pages and summarize only what fetched text supports.
+15. Use `smart-search research "question" --format json` when the user wants the CLI to run live Deep Research end to end instead of only planning. It executes plan -> discover -> fetch/read -> gap check -> evidence-only synthesis.
+16. Preserve command lines and source URLs in your answer. Prefer citing fetched pages or `primary_sources`; treat `extra_sources` as follow-up candidates, not verified evidence for generated claims.
 
 ## Deep Research Mode
 
@@ -101,7 +100,6 @@ Allowed `steps[].tool` values are `search`, `exa-search`, `exa-similar`, `contex
 Capability boundaries:
 
 - `search`: broad bilingual discovery and synthesis through `main_search`; inspect `routing_decision`, `provider_attempts`, `fallback_used`, and `source_warning`. Do not treat broad answers as proof for high-risk claims.
-- `zhipu-search`: deprecated manual compatibility command. Do not include it in default plans or workflows unless the user explicitly requests Zhipu.
 - `context7-library` / `context7-docs`: library, SDK, API, framework, and documentation intent. Prefer Context7 before Exa for docs/API questions.
 - `exa-search`: low-noise discovery for official domains, papers, product pages, known domains, and trusted pages. Use it when that boundary fits; it is not the default second hop for every verification task.
 - `exa-similar`: adjacent-source discovery when a known reliable URL is available.
@@ -122,9 +120,10 @@ 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] [--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.
+- `smart-search research QUERY [--budget quick|standard|deep] [--locale-scope cn|en|both] [--evidence-dir PATH] [--fallback auto|off] [--dry-run] [--progress] [--timeout SECONDS] [--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. Docs/API intent is precision-first (weak language/product tokens alone do not trigger). If docs discovery yields no HTTP evidence, the executor fail-opens to `web_discovery` (`stage_results` may include `fail_open_web_after_docs`). Default `--timeout` is 600 seconds for the full research run.
 - 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`.
+- Research output includes `final_answer`, `citations`, `evidence_items`, `gap_check`, `provider_attempts`, `fallback_used`, `degraded`, `route_policy_version`, `output_schema_version`, and `evidence_dir`.
+- Contract fields for agents: always read `output_schema_version` (currently `1`), `route_policy_version`, `minimum_profile_ok`, and `cache_hit` on attempts/stages. Treat `cache_hit: true` as possibly stale only if the local config model/endpoint changed without process restart — keys include model identity, but process-local TTL still applies. Prefer `doctor --format json` when `minimum_profile_ok` is false (fail-closed).
 - The synthesis is evidence-only. It may cite fetched/read evidence, but it must not cite unfetched discovery candidates as proof.
 - If providers are exhausted or evidence cannot close, return the degraded gaps rather than inventing missing claims.
 
@@ -151,7 +150,7 @@ smart-search research "https://example.com/source" --format json
 
 ## Provider Routing
 
-- `search` builds `main_search` from `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY`, which registers OpenAI-compatible Chat Completions.
+- `search` builds `main_search` from `XAI_API_KEY` (xAI Responses with server-side `web_search`/`x_search` tools) and/or `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY` (Chat Completions). One is enough; when both are configured, `SMART_SEARCH_MAIN_SEARCH_ROUTE` (ordered CSV of `xai-responses,openai-compatible`) sets priority, and a single entry disables cross-route fallback.
 - `search` is the default first hop for broad exploration, current synthesis, and routing metadata.
 - OpenAI-compatible relays/gateways use Chat Completions `/chat/completions` through `OPENAI_COMPATIBLE_*`.
 - `OPENAI_COMPATIBLE_STREAM=true` or `search --stream` sets `stream=true` only for OpenAI-compatible `search` and provider-side `fetch`; it is a relay compatibility switch and does not affect URL description or source ranking.
@@ -160,7 +159,7 @@ smart-search research "https://example.com/source" --format json
 - Jina Reader is `web_fetch` only, not a general search provider. `JINA_API_KEY` is required before Jina satisfies the standard minimum profile; anonymous `r.jina.ai` is explicit/experimental fetch behavior.
 - `search` exposes `--validation fast|balanced|strict`, `--fallback auto|off`, and `--providers auto|CSV`. Default validation is `balanced`; fallback only happens within the same capability.
 - `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` runs bilingual web_search source discovery through Tavily / Firecrawl when configured. Zhipu is deprecated from default routing and is not the first hop for Chinese/current/domestic searches.
+- `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured.
 - Docs/API/library routing stays explicit keyword intent-based and should prefer Context7 first. Exa is for official-domain or low-noise supplemental discovery, not the default docs answer route.
 - `search` calls Tavily and/or Firecrawl for `extra_sources` only when `--extra-sources N` is greater than 0.
 - With both Tavily and Firecrawl configured, `search --extra-sources N` splits extra sources between them, with Tavily receiving about 60% and Firecrawl the rest.
@@ -170,11 +169,8 @@ smart-search research "https://example.com/source" --format json
 - `map` currently uses Tavily only.
 - `exa-search` and `exa-similar` use Exa only.
 - `context7-library` and `context7-docs` use Context7 only.
-- `zhipu-search` uses Zhipu only and is retained as a deprecated manual compatibility command.
-- `zhipu-search` corresponds to the official Zhipu Web Search API route, using `ZHIPU_API_URL` plus `ZHIPU_SEARCH_ENGINE`; it is not Zhipu Chat Completions `tools=[web_search]`, not Search Agent, and not the MCP Server.
-- `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`; keep custom values possible because official services may change.
-- `TAVILY_API_URL` only affects Tavily REST calls and does not proxy Zhipu. Zhipu defaults to `https://open.bigmodel.cn/api` unless `ZHIPU_API_URL` is set.
-- `doctor` tests configured main-search providers, Exa, Tavily, Jina, Zhipu Web Search API, and Context7 connectivity. Firecrawl status currently means the key is configured, not that a live Firecrawl request succeeded.
+- `TAVILY_API_URL` only affects Tavily REST calls.
+- `doctor` tests configured main-search providers, Exa, Tavily, Jina, and Context7 connectivity. Firecrawl status currently means the key is configured, not that a live Firecrawl request succeeded.
 
 ## Evidence Files
 
@@ -270,13 +266,11 @@ Use this when the user wants work that can be inspected, resumed, or audited.
 - Use `smart-search doctor --format json` for agent/script parsing and `smart-search doctor --format markdown` when a human wants a detailed diagnostic report.
 - If `smart-search doctor --format json` returns `ok: false`, follow the `error` field's guidance (`smart-search setup` or `smart-search config set KEY VALUE`); do not silently fall back to native web search.
 - Use `smart-search diagnose openai-compatible --format markdown` when `doctor` succeeds but OpenAI-compatible `search` appears to hang, returns a timeout, or differs between `--stream` and `--no-stream`. It is the beginner-facing one-command report for upstream/relay compatibility.
-- Interactive `smart-search setup` is a language-selecting grouped wizard with arrow-key / Space / Enter provider selection. It guides users through required `main_search`, `docs_search`, and fetch capability. Zhipu is no longer recommended or prompted in the default setup flow.
+- Interactive `smart-search setup` is a language-selecting grouped wizard with arrow-key / Space / Enter provider selection. It guides users through required `main_search`, `docs_search`, and fetch capability.
 - The setup wizard prints beginner filling examples for official-service and relay/pooled-endpoint minimum profiles. Keep that guidance on stderr so stdout remains parseable JSON/Markdown/content output.
 - Use `smart-search setup --lang en` for an English wizard and `smart-search setup --advanced` only when low-level config keys must be shown one by one.
-- Use `smart-search config set ZHIPU_API_KEY ...` only for explicit legacy Zhipu compatibility. Do not set it up for default workflows.
 - Use `smart-search setup --non-interactive --jina-key "key"` to let Jina satisfy `web_fetch`; `JINA_RESPOND_WITH=readerlm-v2` also requires `JINA_API_KEY`.
 - Use `smart-search setup --non-interactive --openai-compatible-stream true` only when an OpenAI-compatible relay benefits from SSE streaming for long requests. Default is true.
-- Interactive setup does not ask for Zhipu by default.
 - Use `TAVILY_API_URL=https://<host>/api/tavily` for Tavily Hikari / pooled endpoints. Root host and `/mcp` inputs are normalized by setup; `/mcp` itself is not the REST base Smart Search should call.
 - `TAVILY_TIMEOUT_SECONDS` controls the Tavily `doctor` connectivity timeout and defaults to `30`. Raise it for slower pooled/community Tavily endpoints before judging the provider unhealthy.
 - Use `FIRECRAWL_API_URL` only for a Firecrawl-compatible REST base. Official default is `https://api.firecrawl.dev/v2`.
@@ -311,11 +305,11 @@ smart-search config set OPENAI_COMPATIBLE_API_URL "https://api.openai.com/v1" --
 smart-search config set OPENAI_COMPATIBLE_API_KEY "key" --format json
 smart-search config set OPENAI_COMPATIBLE_MODEL "model-id" --format json
 smart-search config set OPENAI_COMPATIBLE_STREAM "true" --format json
+smart-search config set XAI_API_KEY "key" --format json
+smart-search config set XAI_MODEL "grok-4.5" --format json
+smart-search config set SMART_SEARCH_MAIN_SEARCH_ROUTE "xai-responses,openai-compatible" --format json
 smart-search config set EXA_API_KEY "key" --format json
 smart-search config set CONTEXT7_API_KEY "key" --format json
-smart-search config set ZHIPU_API_KEY "key" --format json
-smart-search config set ZHIPU_API_URL "https://open.bigmodel.cn/api" --format json
-smart-search config set ZHIPU_SEARCH_ENGINE "search_pro" --format json
 smart-search config set TAVILY_API_URL "https://api.tavily.com" --format json
 smart-search config set TAVILY_TIMEOUT_SECONDS "45" --format json
 smart-search config set FIRECRAWL_API_URL "https://api.firecrawl.dev/v2" --format json
@@ -344,6 +338,18 @@ smart-search d --format markdown
 
 When `smart-search search` returns `ok: false` with `error_type: "network_error"` and an error message containing `timed out`, treat it as a retryable CLI-level timeout, not as a terminal research failure.
 
+### Error contract (U1/U2)
+
+Failed JSON payloads expose a stable triple for Agent/JSON consumers:
+
+| Field | Meaning |
+| --- | --- |
+| `error_type` | Category enum string: `config_error`, `parameter_error`, `network_error`, `evidence_error`, `auth_error`, `rate_limited`, `timeout`, `parse_error`, `quality_error`, `runtime_error` |
+| `error_code` | Stable `SCREAMING_SNAKE` code (defaults from `error_type`, e.g. `CONFIG_ERROR`; specific codes such as `MISSING_API_KEY`, `SEARCH_TIMEOUT` when applicable) |
+| `error` | Default **English** human message (no locale framework; Chinese remains only in interactive setup prompts via existing `_t`) |
+
+CLI exit codes stay mapped from `error_type` only: `parameter_error→2`, `config_error→3`, `network_error`/`evidence_error→4`, other→`5`.
+
 1. Retry up to 3 total attempts with `--timeout 180`, waiting about 5 seconds between attempts.
 2. Use `--format json` and `--output PATH` for each attempt; after each attempt, inspect the saved JSON and stop on the first `"ok": true`.
 3. Use `--extra-sources 1` during retry attempts to keep Tavily/Firecrawl overhead small.
@@ -380,7 +386,7 @@ smart-search fetch "https://example.com/source" --format markdown --output fetch
 - Do not use legacy MCP tool names in prompts, notes, or generated instructions for this workflow.
 - Treat key rotation as a hard safety gate when previous key values were pasted into chat or logs.
 - For provider architecture maintenance, verify the distributable contract rather than the current developer machine's wrappers or local config. Keep fallback same-capability only.
-- `main_search` is OpenAI-compatible Chat Completions configured through `OPENAI_COMPATIBLE_*`. Do not fabricate a second `main_search` provider or reuse another capability's URL/key as a `main_search` fallback.
+- `main_search` is a user choice between xAI Responses (`XAI_*`) and OpenAI-compatible Chat Completions (`OPENAI_COMPATIBLE_*`). Never send xAI server tools (`web_search`, `x_search`) or xAI-only parameters into the OpenAI-compatible route, and never point the xAI route at `/chat/completions`. Do not fabricate additional `main_search` providers or reuse another capability's URL/key as a `main_search` fallback.
 
 ## Supporting Reference
 

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

@@ -21,14 +21,13 @@
 - `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]` — **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] [--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]`
-- `smart-search setup [--lang zh|en] [--advanced] [--non-interactive] [--openai-compatible-api-url URL] [--openai-compatible-api-key KEY] [--openai-compatible-model ID] [--openai-compatible-stream true|false] [--validation-level fast|balanced|strict] [--fallback-mode auto|off] [--minimum-profile standard|off] [--exa-key KEY] [--context7-key KEY] [--zhipu-key KEY] [--zhipu-api-url URL] [--zhipu-search-engine ENGINE] [--jina-key KEY] [--jina-reader-api-url URL] [--jina-respond-with MODE] [--jina-timeout SECONDS] [--tavily-api-url URL] [--tavily-key KEY] [--firecrawl-api-url URL] [--firecrawl-key KEY] [--format json|markdown|content] [--output PATH]`
+- `smart-search setup [--lang zh|en] [--advanced] [--non-interactive] [--openai-compatible-api-url URL] [--openai-compatible-api-key KEY] [--openai-compatible-model ID] [--openai-compatible-stream true|false] [--validation-level fast|balanced|strict] [--fallback-mode auto|off] [--minimum-profile standard|off] [--exa-key KEY] [--context7-key KEY] [--jina-key KEY] [--jina-reader-api-url URL] [--jina-respond-with MODE] [--jina-timeout SECONDS] [--tavily-api-url URL] [--tavily-key KEY] [--firecrawl-api-url URL] [--firecrawl-key KEY] [--format json|markdown|content] [--output PATH]`
 - `smart-search config path [--format json|markdown|content] [--output PATH]`
 - `smart-search config list [--format json|markdown|content] [--output PATH]`
 - `smart-search config set KEY VALUE [--format json|markdown|content] [--output PATH]`
@@ -47,7 +46,6 @@ Top-level aliases must normalize to the same service behavior as their full comm
 | `map` | `m` |
 | `exa-search` | `exa`, `x` |
 | `exa-similar` | `xs` |
-| `zhipu-search` | `z`, `zp` |
 | `context7-library` | `c7`, `ctx7` |
 | `context7-docs` | `c7d`, `c7docs`, `ctx7-docs` |
 | `research` | `rs` |
@@ -71,7 +69,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`, `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 +88,9 @@ 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.
+Tavily setup notes:
+
+- `TAVILY_API_URL` only affects Tavily.
 - `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:
@@ -124,15 +114,13 @@ Exa HTTP `400` or `422` failures are returned as `ok=false` with `error_type=par
 
 Exa similar output includes `ok`, `url`, `results`, `total`, and `elapsed_ms` when successful.
 
-Zhipu search output includes `ok`, `query`, `provider`, `search_engine`, `results`, `total`, and `elapsed_ms` when successful.
-
 Context7 library output includes `ok`, `query`, `provider`, `results`, `total`, and `elapsed_ms` when successful. Context7 docs output includes `ok`, `library_id`, `query`, `provider`, `results`, `total`, `content`, and `elapsed_ms` when successful.
 
 Map output includes `ok`, `base_url`, `results`, `response_time`, `url`, and `elapsed_ms` when successful.
 
 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, 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. xAI Responses health is validated through `/responses` (a lightweight probe in `doctor`; `diagnose xai` adds a search-shape probe with server-side tools). 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.
 
@@ -163,7 +151,6 @@ Each `steps[]` item must include `id`, `subquestion_id`, `tool`, `purpose`, `com
 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.
 - `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.
@@ -258,15 +245,15 @@ Agent timeout handling contract:
 
 ## Provider Routing
 
-- `search` builds `main_search` from `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY`, which registers OpenAI-compatible Chat Completions.
+- `search` builds `main_search` from `XAI_API_KEY` (xAI Responses with server-side `web_search`/`x_search` tools) and/or `OPENAI_COMPATIBLE_API_URL` + `OPENAI_COMPATIBLE_API_KEY` (Chat Completions). One is enough; when both are configured, `SMART_SEARCH_MAIN_SEARCH_ROUTE` (ordered CSV of `xai-responses,openai-compatible`) sets priority, and a single entry disables cross-route fallback.
 - OpenAI-compatible relays/gateways use Chat Completions `/chat/completions` through `OPENAI_COMPATIBLE_*`.
 - `OPENAI_COMPATIBLE_STREAM` and `search --stream/--no-stream` affect only the OpenAI-compatible Chat Completions transport for search/fetch. They do not change provider-internal ranking/URL description tasks.
 - 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.
+- `main_search`: xAI Responses (`XAI_*`) or OpenAI-compatible Chat Completions (`OPENAI_COMPATIBLE_*`), ordered by `SMART_SEARCH_MAIN_SEARCH_ROUTE` when both are configured (default `xai-responses -> openai-compatible`).
+- `web_search`: `search` runs bilingual web_search source discovery through Tavily / Firecrawl when configured.
 - `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.
@@ -278,17 +265,16 @@ 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.
 - `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.
-- Use `config set OPENAI_COMPATIBLE_MODEL ...` to change the main-search model.
+- Use `config set OPENAI_COMPATIBLE_MODEL ...` (or `XAI_MODEL ...` for the xAI route) to change the main-search model; use `config set SMART_SEARCH_MAIN_SEARCH_ROUTE ...` to change route priority.
 
 ## 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 the bilingual `search` pair for Chinese, domestic, current, or mixed-language source discovery.
 - 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.

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

@@ -19,7 +19,19 @@ If the output says `Selected task: none`, do not auto-resume a previous or uniqu
 - inspect details
 - continue without a task for No Task / Micro-Grill work
 
-## Step 2: Load the Phase Index
+## Step 2: Search Session Memory
+
+**Skip this step** if Step 1 reported `Selected task: none`.
+
+When a task is selected, search past session memory so resume work can reuse journal context instead of re-asking the user:
+
+```bash
+{{PYTHON_CMD}} ./.cstl/scripts/search_memory.py --query "<task topic or title>" --json
+```
+
+Use the selected task's title or topic as the query. From the JSON results, summarize **1–3** most relevant hits for the user (title, summary, and next steps when present). Carry that context into the rest of the continue flow.
+
+## Step 3: Load the Phase Index
 
 ```bash
 {{PYTHON_CMD}} ./.cstl/scripts/get_context.py --mode phase
@@ -27,7 +39,7 @@ If the output says `Selected task: none`, do not auto-resume a previous or uniqu
 
 Shows the Phase Index (Plan / Execute / Finish) with routing + skill mapping.
 
-## Step 3: Decide Where You Are
+## Step 4: 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.
 
@@ -46,7 +58,7 @@ Phase rules (full detail in `.cstl/workflow.md`):
 2. `[once]` steps are already done if the required output exists. `prd.md` alone can be enough only for lightweight tasks; complex tasks also need `design.md` and `implement.md`.
 3. You may go back to an earlier phase if discoveries require it
 
-## Step 4: Load the Specific Step
+## Step 5: Load the Specific Step
 
 Once you know which step to resume at:
 

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

@@ -45,11 +45,14 @@ Run the project's lint, type-check, and test commands. Fix any failures before p
 - [ ] No debug logging left in?
 - [ ] No suppressed warnings or type-safety bypasses?
 
-### Test Coverage
+### Test Coverage (verification strength — not TDD)
 
-- [ ] New function → unit test added?
-- [ ] Bug fix → regression test added?
-- [ ] Changed behavior → existing tests updated?
+Follow `.cstl/spec/guides/verification-strength-guide.md` for **graded** validation depth by closeout profile. cstl does **not** mandate red-green TDD or per-function unit tests.
+
+- [ ] **Lite:** focused validation on touched behavior recorded in `verify.md` (`Validation:` line + result)
+- [ ] **Full:** above + `Check evidence:` + `Reviewed change-set:` when contract requires code-review gate
+- [ ] New function / bug fix → add or update tests **when the project's norms and task scope require it** — not as automatic TDD ceremony
+- [ ] `python ./.cstl/scripts/task.py validate <task>` passing JSONL schema **≠** task acceptance; substantive `verify.md` signals still required
 
 ### Durable Learning (Phase 3.3)
 

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

@@ -48,6 +48,7 @@ Look for the `<!-- cstl-hook-injected -->` marker in your input above.
 
 Before checking, read:
 - `.cstl/spec/` - Development guidelines
+- `.cstl/spec/guides/verification-strength-guide.md` - Graded verify depth (Lite/Full/Parent; not TDD)
 - Task `prd.md` - Requirements document
 - Task `design.md` - Technical design (if exists)
 - Task `implement.md` - Execution plan (if exists)

package/dist/templates/cursor/fixtures/expected-rules.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"expected-rules.d.ts","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EAyBvC,CAAC"}
+{"version":3,"file":"expected-rules.d.ts","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,eAAO,MAAM,aAAa,EAAE,YAAY,EA8BvC,CAAC"}

package/dist/templates/cursor/fixtures/expected-rules.js

@@ -19,7 +19,7 @@ export const expectedRules = [
     },
     {
         filename: "retrieval-routing.mdc",
-        requiredSections: ["Native", "BYOK", "codegraph", "smart-search"],
+        requiredSections: ["Prefer", "Adapt", "Own", "Native", "BYOK", "codegraph", "smart-search"],
         minBytes: 600,
     },
     {
@@ -27,5 +27,10 @@ export const expectedRules = [
         requiredSections: ["rename_chat", "select", "start-execution", "skip silently"],
         minBytes: 300,
     },
+    {
+        filename: "cstl-cursor-modes.mdc",
+        requiredSections: ["Prefer Cursor native modes", "Quick routing", "Hard boundaries", "Rollback"],
+        minBytes: 400,
+    },
 ];
 //# sourceMappingURL=expected-rules.js.map

package/dist/templates/cursor/fixtures/expected-rules.js.map

@@ -1 +1 @@
-{"version":3,"file":"expected-rules.js","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C;QACE,QAAQ,EAAE,iBAAiB;QAC3B,gBAAgB,EAAE;YAChB,eAAe;YACf,qBAAqB;YACrB,cAAc;SACf;QACD,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,4BAA4B;QACtC,gBAAgB,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,CAAC;QAChE,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,uBAAuB;QACjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC;QACjE,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,yBAAyB;QACnC,gBAAgB,EAAE,CAAC,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,eAAe,CAAC;QAC/E,QAAQ,EAAE,GAAG;KACd;CACF,CAAC"}
+{"version":3,"file":"expected-rules.js","sourceRoot":"","sources":["../../../../src/templates/cursor/fixtures/expected-rules.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,CAAC,MAAM,aAAa,GAAmB;IAC3C;QACE,QAAQ,EAAE,iBAAiB;QAC3B,gBAAgB,EAAE;YAChB,eAAe;YACf,qBAAqB;YACrB,cAAc;SACf;QACD,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,4BAA4B;QACtC,gBAAgB,EAAE,CAAC,SAAS,EAAE,0BAA0B,EAAE,KAAK,CAAC;QAChE,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,uBAAuB;QACjC,gBAAgB,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC;QAC3F,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,yBAAyB;QACnC,gBAAgB,EAAE,CAAC,aAAa,EAAE,QAAQ,EAAE,iBAAiB,EAAE,eAAe,CAAC;QAC/E,QAAQ,EAAE,GAAG;KACd;IACD;QACE,QAAQ,EAAE,uBAAuB;QACjC,gBAAgB,EAAE,CAAC,4BAA4B,EAAE,eAAe,EAAE,iBAAiB,EAAE,UAAU,CAAC;QAChG,QAAQ,EAAE,GAAG;KACd;CACF,CAAC"}

package/dist/templates/cursor/rules/cstl-cursor-modes.mdc

@@ -0,0 +1,32 @@
+---
+description: "Prefer Cursor native modes — task-driven; quiet cstl spine fallback"
+alwaysApply: true
+---
+
+# Prefer Cursor native modes (P1 — orchestrate, don't replace)
+
+cstl **prefers** Cursor native modes and maps them to Trellis Triage/phases. **Do not** replace Cursor UI or invent a parallel Plan/Ask/Debug product. Full table: `.cstl/spec/guides/cursor-native-modes-guide.md` · evidence: `{TASK}/research/modes-callability-matrix.md`.
+
+## Quick routing
+
+| Situation | Prefer | Trellis anchor |
+| --- | --- | --- |
+| Read-only explain / lookup | **Ask** when reachable; else No Task in Agent | `[Triage: No Task]` — no durable edits |
+| Scope / design before code | **Try `SwitchMode(plan)`**; if poor, write artifacts in Agent | Phase 1 → `prd.md` / `design.md` / `implement.md`; `--check` |
+| Approved build / verify | **Agent**; `SwitchMode(agent)` after Plan | Phase 2–3; `execution_mode` |
+| Runtime / repeat failure | **Debug** when reachable; else verify + break-loop | Evidence → `verify.md` |
+| Independent Parent children (post-approval) | **Multitask** / `Task` parallel when useful | Explicit `.cstl/tasks/<dir>` per worker; Parent integrates |
+
+## Quiet fallback
+
+When native cannot be task-driven well: continue on the **cstl spine** (Triage / Phase / artifacts / gates). Do **not** add user-facing “本版本不适配某 mode” copy. Do **not** center guidance on “please open the mode picker.”
+
+## Hard boundaries
+
+- Plan default save = **home dir** until Save to workspace → map into task files.
+- Multitask/subagents: **never** rely on `selected_task`; worktrees + Parent review.
+- Agent `SwitchMode`: **`plan` / `agent` only** (Ask/Debug not in the tool enum).
+
+## Rollback
+
+Delete this file + `cursor-native-modes-guide.md` (see guide Rollback).

package/dist/templates/cursor/rules/cstl-triage.mdc

@@ -1,5 +1,5 @@
 ---
-description: "Trellis Request Triage — mandatory classification before any work (Cursor sessionStart additional_context is broken; this rule is the reliable injection channel)"
+description: "Trellis Request Triage — mandatory classification before any work (Cursor: alwaysApply rule is the per-turn reliable channel; sessionStart is session-level only)"
 alwaysApply: true
 ---
 
@@ -33,6 +33,4 @@ If the user declines a task for a simple request, skip Trellis for this session.
 
 ## Why this rule exists
 
-Cursor's `sessionStart` hook has a confirmed bug (#158452): `additional_context` is never injected into the agent's system context. The Triage rules in `.cstl/workflow.md` therefore never reach you via that channel. This `.cursor/rules` file is the reliable workaround — Cursor prepends rules to your context before every prompt, independent of the broken sessionStart path.
-
-Full decision-tree details, trigger-signal keywords, and the Task Ladder table: see `.cstl/workflow.md` → `### Request Triage`.
+Request Triage must be visible **on every turn**, not only at session start. `.cursor/rules` with `alwaysApply: true` is the reliable per-turn channel on Cursor. `sessionStart` `additional_context` delivers session-level orientation (dashboard, workflow summary) once per session — useful but insufficient for a per-turn hard gate. The full decision tree also lives in `.cstl/workflow.md` for on-demand loading via `get_context.py` / `cstl-continue`.

package/dist/templates/cursor/rules/retrieval-routing.mdc

@@ -5,7 +5,23 @@ alwaysApply: true
 
 # Codebase retrieval routing (Cursor)
 
-Before answering **code-location / architecture / caller-chain / config-schema** questions in this repo, use the retrieval layer deliberately. On Cursor, **`.cursor/rules` is the reliable policy channel**; **per-query `## 代码库检索计划` blocks** are injected by the **`beforeSubmitPrompt`** hook (`.cursor/hooks/inject-retrieval-plan.py`) when the user message looks like a codebase question. Do **not** depend on `sessionStart` hook `additional_context` (#158452) or end-of-turn retrieval-pack hooks for plans.
+Before answering **code-location / architecture / caller-chain / config-schema** questions in this repo, use the retrieval layer deliberately. On Cursor, **`.cursor/rules` is the reliable per-turn policy channel**; the **`beforeSubmitPrompt`** hook (`.cursor/hooks/inject-retrieval-plan.py`) runs **telemetry-only** — it does **not** inject `## 代码库检索计划` blocks. Generate a plan via `route_codebase_retrieval.py --instructions` when needed, or follow the default tool order below. Do **not** depend on end-of-turn retrieval-pack hooks for plans.
+
+## Prefer / Adapt / Own (code intelligence)
+
+**Three surfaces (do not conflate):** (1) **IDE Editor** — full extension LSP; (2) **Agents Window (Glass)** — staff-reported partial LSP vs Editor ([forum](https://forum.cursor.com/t/cursor-agents-window-lsp-not-working-with-typescript/156772)); (3) **Agent autonomous tools** — [official list](https://cursor.com/docs/agent/overview.md) is search/read/edit/shell/web — **no** `GO_TO_DEFINITION` / raw LSP tool. Trellis routes **Agent tool table** only. See `retrieval-daily-guide.md` § Prefer/Adapt/Own evidence (2026-08-05 smart-search + Native probe).
+
+| Need | **Prefer** (Cursor native, Agent-reachable) | **Adapt** (route by intent / `cursorEnv`) | **Own** (codegraph / MCP) |
+| --- | --- | --- | --- |
+| Exact literal / path | **Grep** | — | — |
+| Named-symbol definition (known identifier) | **Grep → Read** | Path hints from semantic when file unknown | codegraph when cross-package trap, overload ambiguity, or blast context needed |
+| Agent-session diagnostics | **ReadLints** (when in tool table) | — | — |
+| Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search (index embeddings; ≠ LSP) | **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. | — |
+| Caller chain / blast radius | Grep for imports/callbacks (gap-fill) | — | **codegraph_callers** / **codegraph_explore** |
+| Cross-package trap / extension symbol | Grep scoped by package or `extensions/` | — | **codegraph_search** / **codegraph_explore** |
+| Raw LSP / GO_TO_DEFINITION **as Agent tool** | **Not in Agent tool table** (official docs + Native probe 2026-08-05) | IDE Editor has LSP; Agents Window may lack parity — human UI, not Agent routing | codegraph when Grep+Read insufficient |
+
+**Rollback:** revert this rule + `retrieval-daily-guide.md` Prefer rows to the pre-P1 codegraph-first definition wording; keep codegraph MCP enabled.
 
 ## When a retrieval plan block is present
 
@@ -13,7 +29,7 @@ If the user message or Trellis context contains a block starting with `## 代码
 
 1. Execute steps **in order** before stating file paths or behavior claims.
 2. Treat each step as mandatory tooling (not suggestions).
-3. Finish with **Read** verification on cited sources (definition jumps use **codegraph_node**, not LSP).
+3. Finish with **Read** verification on cited sources (definition jumps: **Grep → Read** first; **codegraph** when the plan lists structural/trap routes or Grep is ambiguous).
 
 Generate a fresh plan when needed:
 
@@ -32,12 +48,13 @@ python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --json
 | Need | Tool (Cursor) |
 | --- | --- |
 | Exact string / path | **Grep** (Instant Grep) |
-| Who calls / blast radius | **codegraph_callers** → Grep for imports/callbacks |
+| Named-symbol definition | **Grep** → **Read** (Prefer native); **codegraph_explore** / **codegraph_search** when trap, overload, or blast context needed |
+| IDE diagnostics | **ReadLints** on touched or cited files |
+| Who calls / blast radius | **codegraph_callers** / **codegraph_explore** → Grep for imports/callbacks |
 | Same name across packages (trap) | **codegraph_search** / **codegraph_explore** → Grep |
 | Extension symbols | **codegraph_search** under `extensions/` |
 | Conceptual / how does X work | **Native:** built-in `@codebase` / semantic search. **BYOK:** **fast_context_search** (fast-context MCP). Plans show `cursorEnv`. |
 | Policy / architecture / boundaries / storage rules | **Grep** on `AGENTS.md`, `**/AGENTS.md`, `.cstl/spec/**`, `README.md` (router `policy-docs-rg`) before implementation modules |
-| Definition jump | **codegraph_node** / **codegraph_search**, then **Read** (Agent does not expose GO_TO_DEFINITION / LSP) |
 | Wide cross-cutting explore | **Native:** DEEP_SEARCH or Explore subagent. **BYOK:** **Task explore** subagent, then Grep/codegraph/Read |
 
 ## Semantic on Cursor (`platform-semantic`)
@@ -50,10 +67,12 @@ python ./.cstl/scripts/route_codebase_retrieval.py "<question>" --json
 
 When the plan block includes **结果层排序**, apply it **after** collecting path candidates and **before** stating Top-1 / Top-5: caller concrete sites over assembly files; trap demotion; env scripts/e2e/bench over generic `src/auth`/`paths`. Offline reorder: `rank_retrieval_candidates.py`.
 
-## codegraph-only value
+## codegraph-only value (Own layer)
+
+Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, **impact/blast radius**, and **definition/reference when native Grep+Read is ambiguous** — not for pure literal search (Grep), simple single-package definition jump (Grep+Read), BYOK concept Primary (use fast-context), Agent diagnostics (ReadLints), or **replacing IDE Editor LSP** (human surface).
 
-Use codegraph for **call chains**, **cross-package trap disambiguation**, **extension symbol resolution**, **impact**, and **definition/reference** (replaces unavailable Agent LSP) — not for pure literal search (Grep) or BYOK concept Primary (use fast-context).
+**Re-probe gate:** Before elevating raw LSP to Prefer, verify Agent tool table + `retrieval-daily-guide.md` evidence notes; if external docs add LSP tools but Native probe fails, **keep fallback** and document the gap.
 
 ## External facts
 
-Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md`.
+Web/current events: **smart-search** first per `.cstl/spec/guides/retrieval-daily-guide.md` (see **External-knowledge gate** for search-or-not).

package/dist/templates/markdown/agents.md

@@ -23,6 +23,8 @@ Only a handful of Trellis entry points are meant for **manual `/` invocation**.
 
 For **any external / current / web fact**, run **`python ./.cstl/scripts/run_smart_search.py "<question>" --intent deep-research --json`** first. That script is the **only** Trellis web-research evidence entrypoint (it shells out to the `smart-search` CLI). Do not guess paths under package source trees or sibling repos. Platform built-in web tools (Cursor `WebSearch` / `WebFetch`, or native web tools elsewhere) are **downgrade-only fallbacks**, used solely when smart-search is unavailable (`doctor` not ok, status `not_configured` / `failed`, or search timeout). Do not reach for built-in web search while smart-search is healthy. On Cursor, `smart-search-cli` is an **internal workflow skill name** only (not shipped under `.cursor/skills/`); follow `.cstl/spec/guides/retrieval-daily-guide.md` and `.cursor/rules/retrieval-routing.mdc` for the executable contract.
 
+**External-knowledge gate:** If the answer would be wrong because the **world or a third-party API moved** and that matters → use smart-search (cheap `docs` / `broad-search` when enough; `deep-research` when multi-source). If truth lives only in this workspace → do not default to web. When unsure, prefer a cheap probe over guessing. See retrieval-daily-guide § External-knowledge gate.
+
 Managed by cursor-trellis. Edits outside this block are preserved; edits inside may be overwritten by a future `cstl update`.
 
 <!-- CSTL:END -->

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

@@ -30,4 +30,7 @@ export declare const guidesCursorSemanticComplianceContent: string;
 export declare const guidesCursorSubagentPolicyContent: string;
 export declare const guidesExecutionStrategyContent: string;
 export declare const guidesCursorContextInjectionGuideContent: string;
+export declare const guidesCursorNativeModesGuideContent: string;
+export declare const guidesVerificationStrengthGuideContent: string;
+export declare const guidesInjectionBudgetGuideContent: string;
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,eAAO,MAAM,eAAe,EAAE,MAAuC,CAAC;AAGtE,eAAO,MAAM,qBAAqB,EAAE,MACK,CAAC;AAG1C,eAAO,MAAM,yBAAyB,QAAwB,CAAC;AAG/D,eAAO,MAAM,wBAAwB,EAAE,MACH,CAAC;AAQrC,eAAO,MAAM,mBAAmB,EAAE,MAEjC,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,+BAA+B,EAAE,MAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,EAAE,MAEzC,CAAC;AAGF,eAAO,MAAM,oBAAoB,EAAE,MAElC,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,yBAAyB,EAAE,MAEvC,CAAC;AACF,eAAO,MAAM,6BAA6B,EAAE,MAE3C,CAAC;AACF,eAAO,MAAM,kCAAkC,EAAE,MAEhD,CAAC;AACF,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAEhC,CAAC;AACF,eAAO,MAAM,oCAAoC,EAAE,MAElD,CAAC;AACF,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,yCAAyC,EAAE,MACiB,CAAC;AAC1E,eAAO,MAAM,gCAAgC,EAAE,MAE9C,CAAC;AACF,eAAO,MAAM,qCAAqC,EAAE,MAEnD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC;AACF,eAAO,MAAM,8BAA8B,EAAE,MAE5C,CAAC;AACF,eAAO,MAAM,wCAAwC,EAAE,MACiB,CAAC;AACzE,eAAO,MAAM,mCAAmC,EAAE,MAEjD,CAAC;AACF,eAAO,MAAM,sCAAsC,EAAE,MAEpD,CAAC;AACF,eAAO,MAAM,iCAAiC,EAAE,MAE/C,CAAC"}

package/dist/templates/markdown/index.js

@@ -55,4 +55,7 @@ export const guidesCursorSemanticComplianceContent = readLocalTemplate("spec/gui
 export const guidesCursorSubagentPolicyContent = readLocalTemplate("spec/guides/cursor-subagent-policy.md.txt");
 export const guidesExecutionStrategyContent = readLocalTemplate("spec/guides/execution-strategy.md.txt");
 export const guidesCursorContextInjectionGuideContent = readLocalTemplate("spec/guides/cursor-context-injection-guide.md.txt");
+export const guidesCursorNativeModesGuideContent = readLocalTemplate("spec/guides/cursor-native-modes-guide.md.txt");
+export const guidesVerificationStrengthGuideContent = readLocalTemplate("spec/guides/verification-strength-guide.md.txt");
+export const guidesInjectionBudgetGuideContent = readLocalTemplate("spec/guides/injection-budget-guide.md.txt");
 //# sourceMappingURL=index.js.map

package/dist/templates/markdown/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/markdown/index.ts"],"names":[],"mappings":"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"}