@blxzer/pactile 0.5.0

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

@@ -0,0 +1,323 @@
+# Smart Search CLI Contract
+
+## Entrypoints
+
+- `smart-search` is the primary CLI.
+- `smart-search --version`, `smart-search --v`, and `smart-search -v` print the installed version and exit with code `0`.
+- `smart-search` should resolve from the user's PATH.
+- This bundled skill is maintained with the `smartsearch` repository.
+- Private API keys should be saved with `smart-search setup` or `smart-search config set`.
+- 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.
+
+## Commands
+
+- `smart-search search QUERY [--platform NAME] [--model ID] [--extra-sources N] [--validation fast|balanced|strict] [--fallback auto|off] [--providers auto|CSV] [--stream|--no-stream] [--timeout SECONDS] [--format json|markdown|content] [--output PATH]`
+- `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 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] [--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]`
+- `smart-search config unset KEY [--format json|markdown|content] [--output PATH]`
+- `smart-search --version`
+
+## Aliases
+
+Top-level aliases must normalize to the same service behavior as their full command:
+
+| Full command | Aliases |
+| --- | --- |
+| `smart-search --version` | `smart-search --v`, `smart-search -v` |
+| `search` | `s` |
+| `fetch` | `f` |
+| `map` | `m` |
+| `exa-search` | `exa`, `x` |
+| `exa-similar` | `xs` |
+| `context7-library` | `c7`, `ctx7` |
+| `context7-docs` | `c7d`, `c7docs`, `ctx7-docs` |
+| `research` | `rs` |
+| `doctor` | `d` |
+| `diagnose` | `diag` |
+| `setup` | `init` |
+| `config` | `cfg` |
+
+Nested aliases:
+
+| Full command | Aliases |
+| --- | --- |
+| `config path` | `cfg p` |
+| `config list` | `cfg ls`, `cfg l` |
+| `config set` | `cfg s` |
+| `config unset` | `cfg rm`, `cfg u` |
+
+## Output Format Expectations
+
+Successful search output includes `ok`, `query`, `primary_api_mode`, `content`, `sources`, `sources_count`, `primary_sources`, `primary_sources_count`, `extra_sources`, `extra_sources_count`, `source_warning`, `routing_decision`, `providers_used`, `provider_attempts`, `fallback_used`, `validation_level`, and `elapsed_ms`. Each source should include at least `url` when available.
+
+`--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`, `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.
+
+Source provenance fields:
+
+- `primary_sources`: sources explicitly extracted from the primary model/provider answer.
+- `extra_sources`: parallel Tavily / Firecrawl candidates from `--extra-sources`; these are not automatic evidence for the generated `content`.
+- `sources`: backward-compatible merged list from `primary_sources + extra_sources`, deduped by URL.
+
+Exa domain filters:
+
+- `--include-domains` and `--exclude-domains` accept comma-separated or whitespace-separated domains.
+- Both `--include-domains docs.python.org,developer.mozilla.org` and `--include-domains docs.python.org developer.mozilla.org` normalize to the same Exa domain list.
+- This normalization is intentional for Windows PowerShell, where an unquoted comma expression can be forwarded through `.ps1` wrappers as a space-separated value.
+- `source_warning`: non-empty when extra source candidates were appended.
+
+Fetch output includes `ok`, `url`, `provider`, `content`, `provider_attempts`, `fallback_used`, and `elapsed_ms`.
+
+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:
+
+- `JINA_READER_API_URL` defaults to `https://r.jina.ai`.
+- `JINA_API_KEY` is required before Jina satisfies `SMART_SEARCH_MINIMUM_PROFILE=standard`.
+- Anonymous Jina Reader calls may be used only as explicit/experimental degraded fetch behavior; they must not make standard setup pass.
+- `JINA_RESPOND_WITH=readerlm-v2` requires `JINA_API_KEY` and should report a configuration error without a network request when the key is missing.
+- Jina Reader is `web_fetch` only, not `web_search`.
+- Jina 401/403, 422, 429, timeout, network errors, and low-quality challenge pages such as `Title: Just a moment...` must be reported as failed provider attempts and allow same-capability fallback.
+
+OpenAI-compatible streaming:
+
+- `OPENAI_COMPATIBLE_STREAM` defaults to `true` and accepts `true`, `1`, or `yes` as true.
+- `search --stream` and `search --no-stream` override `OPENAI_COMPATIBLE_STREAM` for the current invocation.
+- Streaming applies only to OpenAI-compatible `search()` and provider-side `fetch()` calls. `describe_url()` and `rank_sources()` stay non-streaming.
+
+Exa search output includes `ok`, `query`, `search_type`, `results`, `total`, and `elapsed_ms` when successful.
+
+Exa HTTP `400` or `422` failures are returned as `ok=false` with `error_type=parameter_error`; use this to distinguish bad CLI/domain/date/category arguments from upstream network failures.
+
+Exa similar output includes `ok`, `url`, `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, 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.
+
+## Deep Research Skill Contract
+
+Deep Research is an optional capability orchestration workflow for prompts such as `深度搜索`, `深度调研`, `深入搜索`, `deep search`, `deep research`, multi-source verification, cross-checking, serious review, and selection/comparison research. `smart-search research` is the public live executor command for this workflow. It must not change default `smart-search search` behavior. `research` builds the plan internally, then executes the staged workflow and writes JSON/Markdown evidence.
+
+Deep Research must not require fixed topic recipe ids such as `current_market_research`, `product_comparison_research`, `technical_docs_research`, `news_or_policy_research`, `claim_verification_research`, or `url_first_research`. Those phrases may appear as prompt examples, but they are not schema modes or routing enums.
+
+`research` builds an internal `research_plan` before discovery. Its fields are:
+
+- `mode`: always `deep_research`.
+- `query_mode`: always `research`.
+- `question`: the user's research question.
+- `trigger_source`: usually `explicit_cli`.
+- `difficulty`: `standard` or `high`.
+- `intent_signals`: dimensional signals such as `recency_requirement`, `docs_api_intent`, `locale_domain_scope`, `known_url`, `source_authority_need`, `claim_risk`, `cross_validation_need`, and `breadth_depth_budget`.
+- `decomposition`: subquestions for complex research, each with `id`, `question`, `reason`, and `required_capabilities`.
+- `capability_plan`: the selected capability needs and the CLI tools chosen for each need.
+- `evidence_policy`: default `fetch_before_claim`.
+- `preflight`: `doctor` guidance.
+- `steps`: ordered CLI command steps.
+- `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.
+
+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.
+- `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.
+- `search --extra-sources N`: Tavily/Firecrawl horizontal candidate collection for breadth. Treat those candidates as discovery until fetched.
+- `fetch`: page-content evidence. Key claims require fetched page text under `fetch_before_claim`.
+- `map`: site structure exploration before many fetches from one site; not claim evidence by itself.
+
+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.
+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.
+
+`fetch_before_claim` means key claims must be backed by fetched page content. `primary_sources` and `extra_sources` are discovery candidates until fetched. Final answers should include fetched evidence, unverified candidate sources, and key commands used.
+
+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")
+```
+
+`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.
+
+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.
+- 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.
+
+Safe research overrides are `SMART_SEARCH_RESEARCH_PREFERRED_PROVIDERS` and `SMART_SEARCH_RESEARCH_DISABLED_PROVIDERS`. They may reorder or disable providers only inside capabilities the provider already supports; they must not move a provider across capability boundaries.
+
+Planner closeout lessons:
+
+- Budget limits must not break evidence policy. Even `--budget quick` plans must retain at least one `fetch` step when claim-level conclusions are expected, and retained steps must keep valid `subquestion_id` links.
+- `steps[].command` and `steps[].output_path` are one contract. The `--output` path embedded in the executable command must match `output_path`; otherwise the AI agent cannot reliably find saved evidence.
+- Prefer PowerShell-safe quoted commands in generated plans because Windows users often copy planned steps directly from Markdown or JSON output.
+
+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.
+
+Interactive setup behavior:
+
+- Default `smart-search setup` shows a Smart Search ASCII banner, asks for `zh`
+  or `en`, then shows a grouped provider wizard.
+- The grouped wizard should use an arrow-key / Space / Enter selector when the
+  packaged TUI dependencies are available, with a text fallback for non-TTY
+  and tests.
+- Required groups are `main_search`, `docs_search`, and `web_fetch`; `web_search` is optional reinforcement.
+- `--lang zh|en` skips the language question.
+- `--advanced` shows low-level config keys one by one for compatibility with older setup behavior.
+- `--non-interactive` keeps script behavior and only saves values passed as flags.
+- Unchecking a configured provider must not delete existing config values; use
+  `smart-search config unset KEY` for deletion.
+- Interactive output should summarize `minimum_profile_ok`, missing required capabilities, and next-step commands.
+- Beginner filling examples for official-service and relay/pooled-endpoint
+  minimum profiles must appear in the grouped wizard on stderr, not stdout.
+  They must cover `main_search`, `docs_search`, and `web_fetch` so a first-time
+  user can satisfy the minimum profile without understanding provider internals.
+
+Provider endpoint setup:
+
+- `TAVILY_API_URL` defaults to `https://api.tavily.com`.
+- `TAVILY_TIMEOUT_SECONDS` defaults to `60` and applies to Tavily `doctor`
+  connectivity checks.
+- Tavily Hikari / pooled endpoints must use the REST facade base
+  `https://<host>/api/tavily`; `/mcp` is not a REST provider base.
+- Setup normalizes a Hikari root host or `/mcp` URL to
+  `https://<host>/api/tavily`; an existing `/api/tavily` base and official
+  `https://api.tavily.com` remain unchanged.
+- `FIRECRAWL_API_URL` defaults to `https://api.firecrawl.dev/v2`; custom REST
+  bases are saved with scheme normalization and no trailing slash.
+
+Search timeout output uses `ok=false`, `error_type=network_error`, includes the timeout seconds in `error`, keeps `query`, `content`, `sources`, `sources_count`, `primary_sources`, `primary_sources_count`, `extra_sources`, and `extra_sources_count`, and exits with code `4`.
+
+Agent timeout handling contract:
+
+- A `search` result with `ok=false`, `error_type=network_error`, and an `error` message containing `timed out` is retryable at the orchestration layer.
+- Agents should retry up to 3 total attempts with `smart-search search ... --timeout 180 --extra-sources 1 --format json --output PATH`, waiting about 5 seconds between attempts and stopping as soon as the saved JSON has `"ok": true`.
+- Agents must use the CLI `--timeout` option, not a shell-level `timeout` wrapper, so timeout failures remain structured JSON with exit code `4`.
+- `SMART_SEARCH_RETRY_*` settings are not the contract for this path; the visible CLI result is the contract.
+- After repeated timeout failures, agents should switch to source-first fallback: `exa-search` for broad source discovery, `exa-search --include-domains` for likely official domains, then `fetch` key URLs before claim-level conclusions.
+- Final answers assembled through that fallback should explicitly label the evidence mode, for example `source_mode: "fallback"` or equivalent prose.
+
+## Provider Routing
+
+- `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`: 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.
+- `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.
+- `fetch` tries Tavily first, then Jina Reader with `JINA_API_KEY`, then Firecrawl.
+- `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.
+- `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 ...` (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.
+- 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.
+
+## Maintenance Guardrails
+
+- Provider architecture changes must be verified as distributable CLI behavior, not as behavior that only works because one developer machine has a specific wrapper, shell profile, or local config file.
+- Register providers by capability first, then route by intent. Fallback is allowed only within the same capability.
+- Do not use Context7 for broad news or generic web facts; do not use Tavily or Firecrawl as documentation semantic-search replacements.
+- Standard installs must fail closed unless `main_search`, `docs_search`, and fetch capability each have at least one configured provider.
+- After provider-routing changes, run the source-checkout offline test suite. If live keys were used, run a targeted secret scan for exact key substrings before committing.
+
+## Exit Codes
+
+- `0`: success
+- `2`: parameter error
+- `3`: configuration error
+- `4`: network or upstream error
+- `4`: also used for strict insufficient-evidence search failures
+- `5`: runtime or parse error
+
+## Release Lanes
+
+- Stable releases are pushed as `vX.Y.Z` Git tags and publish npm `X.Y.Z` with dist-tag `latest`.
+- Test releases are pushed from `main` and publish `<package.json version>-beta.N` with dist-tag `next`. The beta counter resets per base version, so `0.1.9-beta.1` and `0.1.10-beta.1` are separate sequences.
+- Stable bump commits must use `chore(release): bump version to X.Y.Z`; the branch push is skipped by the npm workflow so the matching `vX.Y.Z` tag is the only publisher for npm `latest`.
+- Stable GitHub release notes should be stored as `.github/releases/vX.Y.Z.md` before tagging. The publish workflow appends npm package, dist-tag, and workflow-run metadata to that body automatically.
+- Historical test builds can be backfilled through GitHub Actions `workflow_dispatch` by supplying an explicit `target_ref`, exact `version`, and a non-`latest` npm tag such as `backfill`.
+- npm versions are immutable. Old `*-dev.*` packages cannot be renamed in place; publish replacement `*-beta.N` packages and optionally deprecate the old names when npm owner credentials are available.
+
+### Release Closeout Lessons
+
+- Always read back npm before and after publishing with `npm view @konbakuyomu/smart-search versions --json` and `npm view @konbakuyomu/smart-search dist-tags --json`. A test release must leave `latest` on the stable version and move only `next` or the explicitly supplied non-`latest` tag.
+- Backfill jobs can publish npm successfully even if GitHub release creation fails because the workflow token cannot access the release API. In that case, leave npm intact and create the missing GitHub prerelease with authenticated local `gh release create ... --prerelease --latest=false`.
+- If concurrent backfill jobs hit npm `E409`, re-dispatch only the affected versions serially after checking whether the version already appeared in the registry.
+- Finish with a diff-style gap check: expected beta version list minus npm versions equals empty, and expected `vX.Y.Z-beta.N` list minus GitHub prereleases equals empty.
+- Local verification after a test release must use an exact install target, such as `mise use -g "npm:@konbakuyomu/smart-search@0.1.10-beta.3" -y --pin`, followed by `mise reshim`, `where.exe smart-search`, `smart-search --version`, and `smart-search doctor --format json`. Also pipe a non-ASCII JSON command such as `smart-search search "深度搜索一下最近的比特币行情" --format json | ConvertFrom-Json` to verify the Windows npm/mise wrapper is emitting UTF-8 JSON, not locale-encoded bytes.
+
+## Tool Policy
+
+Web research through this skill should use `smart-search` CLI. If the CLI is unavailable, report the blocker and recovery steps instead of silently falling back to another web-search route.

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

@@ -0,0 +1,62 @@
+# 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. Do not auto-resume a previous or unique task.
+
+This command is a Cursor `/` escape hatch. It does not implement the Session compiler and does not treat `workflow.md` or `get_context.py --mode phase` as runtime SSOT. Run CLI yourself; do not ask the user to type `python`. Do not open with a “loaded” probe. No selected task → answer directly.
+
+---
+
+## Step 1: Load Kernel / Dashboard
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/get_context.py
+```
+
+Confirms: selected task, Kernel projection (Open / Define / Approve / Execute / Verify / Integrate? / Close), Task Dashboard, git state, recent commits.
+
+If a **compiled session pack** is already in context (SessionStart injected it), use that pack. If `./.pactile/scripts/compile_session_pack.py` exists, you MAY call it to refresh the pack. Do **not** implement or patch the compiler.
+
+Do **not** treat `{{PYTHON_CMD}} ./.pactile/scripts/get_context.py --mode phase` (Phase Index) as runtime SSOT. That extractor is a human overview of `workflow.md`, not Kernel truth.
+
+If the output says `Selected task: none`, stop. Show the dashboard and ask the user to choose one route:
+
+- select a task with `{{PYTHON_CMD}} ./.pactile/scripts/task.py select <task>`
+- create a task (Open Proposal first; no create without consent)
+- inspect details
+- continue without a task for read-only Q&A (Ask if the user is already there; otherwise Agent read-only)
+
+## 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}} ./.pactile/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: Route by Kernel phase
+
+When a task is selected, route by Kernel / Dashboard human phase and persisted `required_controls.rigor` / `topology.kind`. `status` is a projection, not the sole truth. This command does not itself approve Execute.
+
+- **Open** → Intake / Open Proposal only; no product code
+- **Define** → Full: `SwitchMode(plan)` immediately; if the switch fails, one sentence (what happened, where `prd.md` landed) and keep writing artifacts. Lite may stay in Agent. Full follows `required_controls`, not mere file presence. Unlanded Plan is not Execute.
+- **Approve** → run `task.py start-execution <task> --check`, report PASS, ask for explicit Execute approval, then `task.py start-execution <task> --approved`. `--check` is not approval
+- **Execute** → implement under the approved contract in Agent. No product-code edits until this gate. Isolatable units: ask the user to open Multitask and hand worker packs; if they do not, `Task()` plus one sentence — do not block
+- **Verify** → map every AC to evidence in `verify.md`; Debug when runtime-stuck
+- **Integrate?** (parent-child / already integrating) → Parent `integrate-child` path (`merge_limit: 1`), serial, not ordinary Child closeout. `parent_id` alone does **not** make a Child a Parent
+- **Close** → wrap-up via `{{CMD_REF:finish-work}}` when the user is ready; `UpdateGoal` complete or cancel (failure does not block)
+
+Return-to-Define when scope, AC, execution contract, verification strategy, or capability assumptions change.
+
+If this Cursor Task API has no `pactile-implement` / `pactile-check` enum, dispatch workers as `generalPurpose`. Never label that run `true-independent`.
+
+Official `/goal` / CreateGoal is **not** a Pactile Task. Do not restore `pactile-goal`.
+
+---
+
+## Reference
+
+Human overview: `.pactile/workflow.md` (not runtime SSOT). Native mode bindings: `.pactile/framework/cursor-native-modes-guide.md` (on-demand).

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

@@ -0,0 +1,82 @@
+# Finish Work
+
+Wrap up the current session: archive the selected task (and any other completed-but-unarchived tasks the user wants to clean up) and record the session journal. Product-code commits are **not** done here — those belong to Close / Finalize (`vcs-integration`) **before** you invoke this command.
+
+Before archive, confirm `verify.md` includes a **Durable learning decision** (`update-spec` | `no-update` | `unsure`, or a grep-friendly `Durable learning decision:` / `no durable learning` line) and gate-compatible evidence per `.pactile/spec/guides/durable-learning-decision-guide.md`. Run `task.py archive <task> --check` when unsure.
+
+Human lifecycle names: Open / Define / Approve / Execute / Verify / Integrate? / Close. This command is the Close wrap-up hatch, not Execute. On Close, `UpdateGoal` complete or cancel plus one sentence; Goal failure does not block Close. Do not ask the user to type `python`.
+
+## Evidence pack reference (optional — graceful skip)
+
+When the selected task has `{TASK}/research/retrieval-pack-latest.json` (written by the research-end `stop` hook via `get_context --mode retrieval-pack`, or by an explicit pack run during Verify):
+
+1. Read the JSON; note top `contextPack.selected` items (`title`, `source`, `reference`, `score`) and `collection` counts.
+2. Ensure `verify.md` includes an `## Evidence pack reference` section citing those ranked sources or documenting explicit gaps.
+3. If the section is missing, add it before proceeding to archive.
+
+If the file does not exist: **skip silently** — no error, no user prompt. Pack absence is normal when the task did not use research/smart-search.
+
+Pack format: `version`, `source` (`retrieval-pack-orchestrator`), `contextPack.selected[]`, `scoredEvidence`, `collection`. Smart-search manifests that feed scoring live under `{TASK}/research/smart-search/<run-id>/` (from `run_smart_search.py`).
+
+## Step 1: Survey current state
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/get_context.py --mode record
+```
+
+This prints:
+
+- **My active tasks** — review whether any besides the selected one are actually done (code merged, AC met) and should be archived this round.
+- **Git status** — quick visual on what's dirty.
+- **Recent commits** — you'll need their hashes in Step 4 for `--commit`.
+
+If `--mode record` surfaces other completed tasks not tied to the current selection, surface them to the user with a one-shot confirmation: "These N tasks look done — archive them too in this round? [y/N]". Default is no; the selected task is always archived in Step 3 when one exists.
+
+## Step 2: Sanity check — classify dirty paths
+
+Run:
+
+```bash
+git status --porcelain
+```
+
+Filter out paths under `.pactile/workspace/` and `.pactile/tasks/` — those are managed by `add_session.py` and `task.py archive` auto-commits and will appear dirty as part of this skill's own work.
+
+For each remaining dirty path, decide whether it belongs to **the selected task** or to **other parallel work** (e.g., another terminal window editing the same repo). Heuristics:
+
+- Paths referenced in the selected task's `prd.md` / `implement.jsonl` / `check.jsonl` → selected task
+- Paths in code areas matching the selected task's stated scope, or that you remember editing this session → selected task
+- Paths in unrelated areas you have no recollection of touching this session → other parallel work
+
+Then route:
+
+- **Any remaining path looks like selected-task work** — bail out with:
+  > "Working tree has uncommitted code changes from this task: `<list>`. Return to Close / Finalize and commit them before running `{{CMD_REF:finish-work}}`."
+
+  Do NOT run `git commit` here. Do NOT prompt the user to commit. The user goes back to Close / Finalize and the AI drives the batched commit there.
+- **All remaining paths look unrelated** (other parallel-window work) — report them once and continue to Step 3:
+  > "FYI, dirty files outside this task's scope — leaving them for the other window: `<list>`."
+- **Genuinely unsure** — ask the user once: "Are `<list>` this task's work I forgot to commit, or another window's? (commit / ignore)" — then route per their answer.
+
+## Step 3: Archive task(s)
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/task.py archive <task-name>
+```
+
+At minimum: the selected task (if any). Plus any extra tasks the user confirmed in Step 1. Each archive produces a `chore(task): archive ...` commit via the script's auto-commit.
+
+If there is no selected task and the user did not confirm any cleanup archives, skip this step.
+
+## Step 4: Record session journal
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/add_session.py \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary"
+```
+
+Use the work-commit hashes produced in Close / Finalize (visible in Step 1's `Recent commits` list, or via `git log --oneline`) for `--commit`. Do not include the archive commit hashes from Step 3. This produces a `chore: record journal` commit.
+
+Final git log order: `<work commits from Close / Finalize>` → `chore(task): archive ...` (one or more) → `chore: record journal`.

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

@@ -0,0 +1,66 @@
+# Framework Start
+
+Enter or refresh the Pactile Framework Context. This is a dashboard entry surface; it must not select, resume, or start a task by itself.
+
+On **agent-capable Cursor** this command is **not** installed as a `/` slash (SessionStart + `/pactile-continue` cover entry). Keep this template for agent-less platforms only.
+
+---
+
+## Step 1: Framework state
+Identity, git status, selected task, Kernel / Task Dashboard, journal location.
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/get_context.py
+```
+
+If this output includes a line beginning `Pactile update available:`, copy the full line verbatim when summarizing session context. Do not shorten operational command hints.
+
+If a compiled session pack is already in context, use it. Do **not** implement the Session compiler. Do **not** treat `get_context.py --mode phase` Phase Index as runtime SSOT.
+
+## Step 2: Guideline indexes
+Discover packages + spec layers, then read each relevant index file.
+
+```bash
+{{PYTHON_CMD}} ./.pactile/scripts/get_context.py --mode packages
+cat .pactile/spec/guides/index.md
+cat .pactile/spec/<package>/<layer>/index.md   # for each relevant layer
+```
+
+Index files list the specific guideline docs to read when you actually start coding. Human overview: `.pactile/workflow.md` (read on demand; not runtime SSOT).
+
+## Step 3: Decide next action
+From Step 1 you know whether a task is selected. Route by Kernel human phase (Open / Define / Approve / Execute / Verify / Integrate? / Close), not by Phase Index step ids.
+
+- If `Selected task: none` → show the Task Dashboard; do **not** load `pactile-continue`. For read-only Q&A, stay no-task (Ask if the user is already there).
+- If a task **is** selected and you need the next lifecycle step → use `pactile-continue` instead of repeating Steps 1–2 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 Kernel / Dashboard:
+
+- **Open / Define** → stay in definition until AC exists; prefer Plan for Define when useful
+- **Approve** → Execution gate (`task.py start-execution <task> --check`); `--check` is not approval
+- **Execute** → implement under contract
+- **Verify / Close** → evidence then wrap-up (`pactile-finish-work`)
+- **No selected task** → use dashboard routing. Do not auto-select an existing task
+
+Official `/goal` / CreateGoal is not a Pactile Task.
+
+---
+
+## Skill routing (quick reference)
+
+Internal names below are **workflow routing**, not a `/` palette. On Cursor, user slash commands are only Continue / Finish-work / Handoff.
+
+| User intent | Route |
+|---|---|
+| Resume **selected** in-progress task | `pactile-continue` |
+| New feature / unclear requirements | Define / brainstorm discipline (on-demand) |
+| Small request, no task yet | no-task read-only or Open Proposal |
+| About to write code | Execute (after Execute gate) |
+| Done coding / quality check | Verify |
+| Session wrap-up after Close / Finalize commit | `pactile-finish-work` |
+| Stuck / fixed same bug multiple times | Debug → `verify.md`; break-loop when looped |
+| Learned something worth capturing | learning disposition in `verify.md` |
+
+Full human overview in `.pactile/workflow.md`. Native mode bindings: `.pactile/framework/cursor-native-modes-guide.md`.

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

@@ -0,0 +1,68 @@
+/**
+ * Common templates — single source of truth for all platforms.
+ *
+ * These templates contain {{placeholders}} that are resolved per-platform
+ * by resolvePlaceholders() in configurators/shared.ts.
+ *
+ * Directory structure:
+ *   common/
+ *   ├── commands/        # Templates that stay as slash commands
+ *   ├── skills/          # Single-file templates that become auto-triggered skills
+ *   └── bundled-skills/  # Multi-file built-in skills with references/assets
+ */
+export interface CommonTemplate {
+    /** Template name without extension (e.g., "start", "before-dev") */
+    name: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkillFile {
+    /** POSIX path relative to the skill directory, e.g. "references/core.md" */
+    relativePath: string;
+    /** Raw content with {{placeholders}} — must be resolved before writing */
+    content: string;
+}
+export interface CommonBundledSkill {
+    /** Skill directory name, e.g. "pactile-meta" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
+/**
+ * Optional/experimental skill — same shape as bundled skills, but lives under
+ * `optional-skills/` which `getBundledSkillTemplates()` does NOT scan.
+ * Installed only via `pactile init --with-optional <name>` (default off).
+ */
+export interface CommonOptionalSkill {
+    /** Skill directory name, e.g. "chrome-cdp" */
+    name: string;
+    /** Files that must be written under the skill directory */
+    files: CommonBundledSkillFile[];
+}
+/**
+ * Get all command templates (stay as slash commands on all platforms).
+ * Results are cached after first call.
+ */
+export declare function getCommandTemplates(): CommonTemplate[];
+/**
+ * Get all skill templates (become auto-triggered skills on supporting platforms).
+ * Results are cached after first call.
+ */
+export declare function getSkillTemplates(): CommonTemplate[];
+/**
+ * Get all multi-file built-in skills.
+ *
+ * These are copied as complete skill directories so references and assets stay
+ * lazy-loadable instead of being flattened into one oversized SKILL.md.
+ */
+export declare function getBundledSkillTemplates(): CommonBundledSkill[];
+/**
+ * Get all optional/experimental skills (e.g. `optional-skills/chrome-cdp/`).
+ *
+ * Deliberately separate from {@link getBundledSkillTemplates}: `optional-skills/`
+ * is NOT scanned by the bundled pipeline, so default `pactile init` never installs
+ * these. They are installed only through `pactile init --with-optional <name>`.
+ * Results are cached after first call.
+ */
+export declare function getOptionalSkillTemplates(): CommonOptionalSkill[];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,KAAK,EAAE,sBAAsB,EAAE,CAAC;CACjC;AAQD;;;GAGG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,EAAE,CAMtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAMpD;AA2CD;;;;;GAKG;AACH,wBAAgB,wBAAwB,IAAI,kBAAkB,EAAE,CAM/D;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,mBAAmB,EAAE,CAMjE"}