scoutline 0.22.0 → 0.24.0

package/skills/scoutline/SKILL.md

@@ -2,20 +2,20 @@
 name: scoutline
 description: |
   Z.AI, MiniMax, Tavily, Exa, Brave, Firecrawl, Parallel AI, Perplexity, Jina AI, You.com,
-  Linkup, and Spider.cloud CLI for: web search (multi-provider, domain/recency/topic
-  filters), reading pages to markdown, evidentiary HTTP fetch with MD5/SHA-256 digests,
-  Wayback archive lookups and snapshot-vs-live diffing, keyless page monitoring,
-  image/video vision analysis, multi-page site crawls, URL-set mapping, deep research
-  with citations, GitHub repo exploration, and raw MCP tool calls. Select per command
-  with --provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|
-  you|linkup|spider>; always-on provider fallback reroutes to the next configured
-  supplier when one is unavailable.
+  Linkup, Spider.cloud, Bocha AI, SearchApi, and Kagi CLI for: web search (multi-provider,
+  domain/recency/topic filters), reading pages to markdown, evidentiary HTTP fetch with
+  MD5/SHA-256 digests, Wayback archive lookups and snapshot-vs-live diffing, keyless page
+  monitoring, image/video vision analysis, multi-page site crawls, URL-set mapping, deep
+  research with citations, GitHub repo exploration, and raw MCP tool calls. Select per
+  command with --provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|
+  jina|you|linkup|spider|bocha|searchapi|kagi>; always-on provider fallback reroutes to
+  the next configured supplier when one is unavailable.
 ---
 
 # Scoutline
 
 Access Z.AI, MiniMax, Tavily, Exa, Brave, Firecrawl, Parallel AI, Perplexity, Jina AI, You.com,
-Linkup, and Spider.cloud capabilities via `scoutline`. The
+Linkup, Spider.cloud, Bocha AI, SearchApi, and Kagi capabilities via `scoutline`. The
 CLI is self-documenting — use `--help` at any level.
 
 ## Setup
@@ -56,6 +56,15 @@ export LINKUP_API_KEY="your-linkup-key"
 
 # OR Spider.cloud (Search, Reader, Crawl, Map)
 export SPIDER_API_KEY="your-spider-key"
+
+# OR Bocha AI (Search)
+export BOCHA_API_KEY="your-bocha-key"
+
+# OR SearchApi (Search, Quota)
+export SEARCHAPI_API_KEY="your-searchapi-key"
+
+# OR Kagi (Search)
+export KAGI_API_KEY="your-kagi-key"
 ```
 
 Get a Z.AI key at: https://z.ai/manage-apikey/apikey-list
@@ -70,6 +79,9 @@ Get a Jina AI key at: https://jina.ai
 Get a You.com key at: https://you.com/api
 Get a Linkup key at: https://app.linkup.so
 Get a Spider.cloud key at: https://spider.cloud
+Get a Bocha AI key at: https://open.bochaai.com
+Get a SearchApi key at: https://www.searchapi.io
+Get a Kagi key at: https://kagi.com/settings/api
 
 ### Interactive onboarding (`scoutline init`)
 
@@ -101,7 +113,7 @@ or env vars; API keys never belong in command arguments.
 
 Shared commands (`search`, `vision analyze`, `quota`, `doctor`),
 **`repo`**, **`read`**, **`crawl`**, **`map`**, and **`research`**
-accept the global `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider>` flag. Precedence
+accept the global `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider|bocha|searchapi|kagi>` flag. Precedence
 is the flag, then the `SCOUTLINE_PROVIDER` environment variable, then
 the default `zai`. Provider selection is never inferred from
 credentials. Unknown values fail fast with `VALIDATION_ERROR`.
@@ -110,12 +122,13 @@ credentials. Unknown values fail fast with `VALIDATION_ERROR`.
 remain Z.AI-only.
 
 Capability coverage at launch (generated from the production registry
-in registry order `[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider]`):
+in registry order `[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider, bocha, searchapi, kagi]`):
 
 - `search` — Z.AI, MiniMax, Tavily, Exa, Brave, Firecrawl, Parallel AI,
-  Perplexity, Jina AI, You.com, Linkup, and Spider.cloud. The only search
-  control honored by every Provider
-  is `--topic <general|news|finance>`.
+  Perplexity, Jina AI, You.com, Linkup, Spider.cloud, Bocha AI, SearchApi,
+  and Kagi. The only search control honored by every Provider
+  is `--topic <general|news|finance>` (Firecrawl rejects the `finance`
+  value, so option-level fallback retries it on the next candidate).
   Brave is the only Provider that accepts `--type video`; every other
   Provider rejects `controls.type` as `UnsupportedOptionError` so
   option-level fallback continues to Brave.
@@ -123,15 +136,25 @@ in registry order `[zai, minimax, tavily, exa, brave, firecrawl, parallel, perpl
   (`ui-artifact`, `extract-text`, `diagnose-error`, `diagram`, `chart`)
   follow the same registry and are mediated by MiniMax's compiled
   conformance registry.
+- `vision.extract-text` on Z.AI routes to the GLM-OCR specialist
+  (`layout_parsing`, PAYG balance-gated): verbatim markdown extraction,
+  PDF input accepted (≤50 MB; images ≤10 MB), content-hash cached for
+  24 h (disable for a run with `SCOUTLINE_CACHE=0`). On exhaustion (error 1113) it prints one
+  stderr notice and falls back to the plan-covered vision model with
+  identical invocation semantics. `--language` and a custom `[prompt]`
+  are warn-and-strip on the OCR arm (stderr notice) and honored
+  verbatim on the fallback arm and on MiniMax.
 - `quota` — Z.AI, MiniMax, Tavily, Firecrawl (credits), Brave
   (rate-limit window), Jina AI (rate-limit telemetry), Linkup and
-  Spider.cloud (credit balance, limit unknown). Exa, Parallel AI,
-  Perplexity, and You.com do not advertise quota.
+  Spider.cloud (credit balance, limit unknown), and SearchApi (credits).
+  Exa, Parallel AI, Perplexity, You.com, Bocha AI, and Kagi do not
+  advertise quota.
 - `diagnostics` — every built-in Provider (Z.AI, MiniMax, Tavily, Exa,
   Brave, Firecrawl, Parallel AI, Perplexity, Jina AI, You.com, Linkup,
-  Spider.cloud).
+  Spider.cloud, Bocha AI, SearchApi, and Kagi).
 - `read` — Z.AI, Tavily, Exa, Firecrawl, Parallel AI, Jina AI, You.com,
-  Linkup, and Spider.cloud (MiniMax, Brave, and Perplexity do not
+  Linkup, and Spider.cloud (MiniMax, Brave, Perplexity, Bocha AI,
+  SearchApi, and Kagi do not
   advertise it; Tavily/Exa/Firecrawl/Parallel reject Z.AI-only reader
   options: `--with-links`, `--no-gfm`, `--keep-img-data-url`,
   `--with-images-summary`; Jina maps them natively; You.com mirrors the
@@ -156,17 +179,19 @@ Vision by Z.AI and MiniMax only. **Provider
 fallback is always-on by default**
 (0.11.0+): selecting a non-supplier emits a stderr notice and silently
 reroutes to the next eligible configured Provider in registry order
-`[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider]`. Pass
+`[zai, minimax, tavily, exa, brave, firecrawl, parallel, perplexity, jina, you, linkup, spider, bocha, searchapi, kagi]`. Pass
 `--no-fallback` (or set `SCOUTLINE_NO_FALLBACK=1`) to restore the
 previous strict `UNSUPPORTED_CAPABILITY` behavior — the preflight
 still runs capability metadata → configuration → adapter handle in
 order on the effective Provider only.
 
-### Search fan-out (multi-provider search, ADR-0004)
+### Search fan-out (multi-provider search, ADR-0012)
 
 `search` alone can run one query across several providers in parallel
-and merge the results (dedupe by canonical URL identity, occurrence
-ranking, additive `mergedFrom` provenance per result; arms are pinned —
+and merge the results (dedupe by canonical URL identity with
+near-duplicate title clustering, fusion ranking — `rrf` by default,
+`config set fusion occurrence` restores the legacy ordering — and
+additive `mergedFrom` provenance per result; arms are pinned —
 no per-arm fallback, and an arm that rejects a control drops with a
 stderr notice instead of failing the invocation). Activation tiers:
 
@@ -184,6 +209,17 @@ stderr notice instead of failing the invocation). Activation tiers:
 billable calls.** Use it when recall across providers matters more than
 spend; use a single `--provider` pin when it does not.
 
+### Fusion ranking (merged search)
+
+Merged lists (fan-out and `--merge`) rank by `fusion` (config key;
+`SCOUTLINE_FUSION` env wins; no `--fusion` flag): `rrf` (default) scores
+Σ 1/(60 + rank) over every arm × sub-query occurrence and emits a fixed
+3-decimal `fusionScore` on every row; `occurrence` restores the legacy
+ordering byte-for-byte. Near-dup clustering (3-word title shingles,
+Jaccard ≥ 0.8, ≥ 4 shingles) runs in both modes — absorbed urls travel
+verbatim on the representative's `clusterUrls`; `www`/apex hosts
+collapse to one identity.
+
 ### Local context (`--context` / `--context-stdin`)
 
 `research` and `search` accept a local notes file (markdown headings +
@@ -246,27 +282,29 @@ scoutline search "x" --no-journal                           # skip this one call
 
 ## Capability Matrix
 
-| Capability | Z.AI | MiniMax | Tavily | Exa | Brave | Firecrawl | Parallel | Perplexity | Jina AI | You.com | Linkup | Spider.cloud | arXiv | OpenAlex | Crossref | PubMed | Europe PMC | Command |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| Search | Yes | Yes (no domain/recency/content-size/location) | Yes (no location) | Yes (no location) | Yes (web/news/video; `--content-size high` → LLM Context) | Yes (no location; `--content-size high` = markdown, +1 credit/result) | Yes (domain, recency, location, content-size via `advanced_settings`; topic via keyword) | Yes (domain, recency, content-size; topic via keyword) | Yes (domain, location; rejects recency/content-size; topic via keyword) | Yes | Yes | Yes | No | No | No | No | No | `scoutline search` |
-| General single-image interpretation | Yes | Yes (JPG/JPEG/PNG/WebP ≤50 MiB) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision analyze` |
-| Specialized Vision (UI-to-code, OCR, error diagnosis, diagram) | Yes | Available (live-attested; conformance-gated) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision ui-to-code`, `vision extract-text`, `vision diagnose-error`, `vision diagram` |
-| Specialized Vision (chart) | Yes | Pending (implemented; fixture image defect blocks live conformance) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision chart` |
-| Two-image diff, video | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision diff`, `vision video` |
-| Quota (normalized) | Yes | Yes | Yes | **No** (deferred) | Yes (rate-limit window, not spend) | Yes (credits) | **No** | **No** | Yes (rate-limit telemetry, not spend) | **No** | Yes (credit balance, not spend) | Yes (credit balance, not spend) | No | No | No | No | No | `scoutline quota [--all-providers]` |
-| Diagnostics | Yes | Yes | Yes | Yes | Yes | Yes (single-scrape probe) | Yes | Yes | Yes | Yes | Yes | Yes | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | `scoutline doctor [--no-tools] [--available]`; every row carries `availability` (`ok`/`exhausted`/`error`/`unconfigured`), rows sort healthy-first, and `availableProviders` lists the `ok` providers in registry order |
-| Reader | Yes | **No** (UNSUPPORTED_CAPABILITY) | Yes (rejects Z.AI-only options) | Yes (rejects Z.AI-only options) | **No** (UNSUPPORTED_CAPABILITY) | Yes (returns page titles) | Yes | **No** (UNSUPPORTED_CAPABILITY) | Yes | Yes (rejects Z.AI-only options plus `--format text`) | Yes (renders JavaScript; rejects `--format text` and `--no-images`) | Yes (rejects Z.AI-only options) | No | No | No | No | No | `scoutline read` |
-| Repository exploration (search/read/tree/brief) | Yes | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | No | No | No | No | No | `scoutline repo ...` |
-| Crawl | **No** | **No** | Yes | **No** | **No** | Yes (async; resumable after Ctrl-C) | **No** | **No** | **No** | **No** | **No** | Yes (sync) | No | No | No | No | No | `scoutline crawl` |
-| Map | **No** | **No** | Yes | **No** | **No** | Yes | **No** | **No** | **No** | **No** | **No** | Yes | No | No | No | No | No | `scoutline map` |
-| Research (4-250 credits) | **No** | **No** | Yes | Yes | **No** | **No** (`/deep-research` deprecated) | Yes | Yes | Yes | Yes | Yes | **No** | No | No | No | No | No | `scoutline research` |
-| Science (scholarly search/get) | No | No | No | No | No | No | No | No | No | No | No | No | Yes | Yes | Yes | Yes | Yes | `scoutline science search <query>` / `scoutline science get <identifier>`; keyless — no API key required; controls `--author`/`--year`/`--venue`/`--type` consumed only where the supplier wire supports them |
-| Raw tools | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline tools`, `tool`, `call` |
-| Code Mode | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline code ...` |
+| Capability | Z.AI | MiniMax | Tavily | Exa | Brave | Firecrawl | Parallel | Perplexity | Jina AI | You.com | Linkup | Spider.cloud | Bocha AI | SearchApi | Kagi | arXiv | OpenAlex | Crossref | PubMed | Europe PMC | Command |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| Search | Yes | Yes (no domain/recency/content-size/location) | Yes (no location) | Yes (no location) | Yes (web/news/video; `--content-size high` → LLM Context) | Yes (no location; `--content-size high` = markdown, +1 credit/result) | Yes (domain, recency, location, content-size via `advanced_settings`; topic via keyword) | Yes (domain, recency, content-size; topic via keyword) | Yes (domain, location; rejects recency/content-size; topic via keyword) | Yes | Yes | Yes | Yes (no location/type; domain via `site:` prefix) | Yes (no content-size/type; domain via `site:` prefix) | Yes (no location/recency/content-size/type; domain via `site:` prefix; `--topic news` → `/api/v0/enrich/news`) | No | No | No | No | No | `scoutline search` |
+| General single-image interpretation | Yes | Yes (JPG/JPEG/PNG/WebP ≤50 MiB) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision analyze` |
+| Specialized Vision (UI-to-code, OCR, error diagnosis, diagram) | Yes (extract-text = glm-ocr engine with exhaustion fallback; PDF ≤50 MB accepted) | Available (live-attested; conformance-gated) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision ui-to-code`, `vision extract-text`, `vision diagnose-error`, `vision diagram` |
+| Specialized Vision (chart) | Yes | Pending (implemented; fixture image defect blocks live conformance) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision chart` |
+| Two-image diff, video | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline vision diff`, `vision video` |
+| Quota (normalized) | Yes | Yes | Yes | **No** (deferred) | Yes (rate-limit window, not spend) | Yes (credits) | **No** | **No** | Yes (rate-limit telemetry, not spend) | **No** | Yes (credit balance, not spend) | Yes (credit balance, not spend) | No | Yes | No | No | No | No | No | No | `scoutline quota [--all-providers]` |
+| Diagnostics | Yes | Yes | Yes | Yes | Yes | Yes (single-scrape probe) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | Yes (keyless probe) | `scoutline doctor [--no-tools] [--available]`; every row carries `availability` (`ok`/`exhausted`/`error`/`unconfigured`), rows sort healthy-first, and `availableProviders` lists the `ok` providers in registry order |
+| Reader | Yes | **No** (UNSUPPORTED_CAPABILITY) | Yes (rejects Z.AI-only options) | Yes (rejects Z.AI-only options) | **No** (UNSUPPORTED_CAPABILITY) | Yes (returns page titles) | Yes | **No** (UNSUPPORTED_CAPABILITY) | Yes | Yes (rejects Z.AI-only options plus `--format text`) | Yes (renders JavaScript; rejects `--format text` and `--no-images`) | Yes (rejects Z.AI-only options) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | No | No | No | No | No | `scoutline read` |
+| Repository exploration (search/read/tree/brief) | Yes | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | **No** (UNSUPPORTED_CAPABILITY) | No | No | No | No | No | `scoutline repo ...` |
+| Crawl | **No** | **No** | Yes | **No** | **No** | Yes (async; resumable after Ctrl-C) | **No** | **No** | **No** | **No** | **No** | Yes (sync) | **No** | **No** | **No** | No | No | No | No | No | `scoutline crawl` |
+| Map | **No** | **No** | Yes | **No** | **No** | Yes | **No** | **No** | **No** | **No** | **No** | Yes | **No** | **No** | **No** | No | No | No | No | No | `scoutline map` |
+| Research (4-250 credits) | **No** | **No** | Yes | Yes | **No** | **No** (`/deep-research` deprecated) | Yes | Yes | Yes | Yes | Yes | **No** | **No** | **No** | **No** | No | No | No | No | No | `scoutline research` |
+| Science (scholarly search/get) | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | Yes | Yes | Yes | Yes | Yes | `scoutline science search <query>` / `scoutline science get <identifier>`; keyless — no API key required; controls `--author`/`--year`/`--venue`/`--type` consumed only where the supplier wire supports them |
+| Raw tools | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline tools`, `tool`, `call` |
+| Code Mode | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | No | `scoutline code ...` |
 
 Vision results are never cached. Z.AI image limits are JPG/JPEG/PNG ≤5 MiB.
-Search result count is applied locally after normalization and is never sent
-to the active Provider.
+Search result count is applied locally after normalization; for every
+Provider except Bocha it is never sent to the active Provider. Bocha's
+wire request carries a native count parameter, so its Adapter forwards
+the requested count (default 10) and partitions its cache entries by it.
 
 ## Science
 
@@ -325,6 +363,67 @@ per-op `output` writes captured stdout (temp + rename); `vision batch` adds
 per-input files plus `out/summary.json` (`--out` required for more than one
 input).
 
+## Investigation (`investigate`, ADR-0013)
+
+A local, transparent, cache-resumable pipeline: plans sub-queries, fans
+out search, merges by Fusion, reads the top sources, and extracts
+deterministic passages into an EvidencePack. No provider-side job runs —
+distinct from Research, an opaque billed provider job. Agent-synthesis is
+the default: the pack is data, not prose (text output modes fall back to
+JSON), and the calling agent writes the brief. `--synthesize` is the
+additive-only escape hatch: an optional `brief` attaches to the pack
+through Z.AI chat (Z.AI-only; it ignores `--provider`), never replaces
+it — absent by default.
+
+```bash
+scoutline investigate "rust async runtime benchmarks"
+scoutline investigate "rust async | rust tokio"    # explicit pipes split sub-queries
+scoutline investigate "topic" --provider tavily,exa --sources 8
+scoutline investigate "topic" --synthesize         # attach a Z.AI brief (additive)
+```
+
+Sub-query planning precedence: explicit pipes (the `--merge` grammar,
+escape a literal pipe with `\|`) > `--context <path>` (local notes file,
+never leaves the machine) > deterministic templates of the question
+(original, key terms, overview/evidence/criticism; deduped, capped 5).
+Cost is pinned before any billable work: N sub-queries × M arms
+billable searches + up to K reads (default `--sources` 5).
+
+Sources surfaced but unread land in `coverage.unread` with a reason code
+(`no-reader-supplier`, `reader-failed:<code>`) — never silently dropped.
+`--max-chars` is the output budget: passages trim first, late sources
+drop; the full untrimmed pack is saved and recoverable via
+`scoutline history show <ref>` (the `compaction {budget, ref}` stamp
+names it). `--depth`, `--arms`, and `--budget-tokens` are rejected
+with `VALIDATION_ERROR` by design (no depth axis; the arm set IS the
+provider pin; `--max-chars` is the budget).
+
+### Claim verification (`investigate --verify`, ADR-0013 follow-up)
+
+`--verify` turns the positional into a STATEMENT: sentence-claims
+(the extract grammar's terminators; `|` is literal text) capped at 8
+— a 9th sentence fails loud with VALIDATION_ERROR naming the cap,
+never silent truncation. Each claim is searched verbatim (no
+per-claim controls; `--context` + `--verify` is a mode-conflict
+VALIDATION_ERROR — verify owns planning), then deterministically
+matched to the extracted passages. The pack gains an additive
+`verify` block: per claim, a verdict, evidence pointers
+`{sourceIndex, passageIndex}`, and a negation-cue count.
+
+```bash
+scoutline investigate "X is fast. Y lags." --verify
+scoutline investigate "claim one. claim two." --verify --max-chars 4000
+```
+
+Verdicts: `corroborated` (matching passages, zero cues) /
+`contradicted` (a term-matching passage carries a negation cue from
+a fixed, versioned cue list) / `unresolved` (no matching passages).
+**Hint-grade disclosure**: `contradicted` is a cue heuristic, NOT
+semantic contradiction — semantic judgment stays with you; the
+per-claim `negationCues` count exists for exactly that re-judgment.
+`--max-chars` never cuts claim text or verdicts (evidence pointers
+drop last, whole); cost notices state "N claims × M arms".
+
 ## Commands
 
 | Command | Purpose | Help |
@@ -340,6 +439,7 @@ input).
 | crawl | Multi-page website traversal (Tavily, Firecrawl, or Spider.cloud) | `--help` for depth/breadth/filters |
 | map | URL-set discovery without fetching pages (Tavily, Firecrawl, or Spider.cloud) | `--help` for depth/breadth/filters |
 | research | Deep research with citations (seven providers; 4-250 credits) | `--help` for model/citation/timeout and local context |
+| investigate | Local investigation pipeline returning an EvidencePack (ADR-0013); `--verify` adds claim verdicts (cue-heuristic, hint-grade) | `--help` for planner tiers, controls, and cost |
 | repo | GitHub code search and reading (Z.AI) | `--help` for tree/search/read/brief |
 | quota | Provider-normalized plan usage dashboard | `--help` for `--all-providers` |
 | tools | List available MCP tools (Z.AI) | |
@@ -445,6 +545,19 @@ scoutline --provider spider crawl https://docs.example.com --depth 2
 scoutline --provider spider map https://docs.example.com
 scoutline --provider spider quota   # credit balance
 
+# Bocha AI (Search)
+scoutline --provider bocha search "AI policy news" --topic news
+scoutline doctor --provider bocha
+
+# SearchApi (Search, Quota)
+scoutline --provider searchapi search "AI policy news" --topic news
+scoutline --provider searchapi quota
+scoutline doctor --provider searchapi
+
+# Kagi (Search)
+scoutline --provider kagi search "AI policy news" --topic news
+scoutline doctor --provider kagi
+
 # All-Provider quota
 scoutline quota --all-providers
 
@@ -477,6 +590,9 @@ scoutline config get routing
 | You.com | Search/reader/research; no quota endpoint. |
 | Linkup | Research priced by reasoning depth ($0.25-$2.50/query); quota reports the prepaid USD balance. |
 | Spider.cloud | Crawl/map (sync) plus search/reader; credit-based. |
+| Bocha AI | Web search with `--domain` as a `site:` prefix, `--recency` freshness, and `--content-size high` summaries; search + diagnostics only. Key: `BOCHA_API_KEY` — https://open.bochaai.com. |
+| SearchApi | Exact Google-SERP search (`--topic news` routes to the google_news engine) plus credit quota via `quota`; search + quota + diagnostics only. Key: `SEARCHAPI_API_KEY` — https://www.searchapi.io. |
+| Kagi | Search (and `--topic news` via the enrich/news endpoint) with a diagnostics probe; no reader/research/crawl/map/vision/quota. Key: `KAGI_API_KEY` — https://kagi.com/settings/api. |
 | arXiv, OpenAlex, Crossref, PubMed, Europe PMC | `scoutline science search` / `science get` only — keyless scholarly lookups (five suppliers, DOI-deduped merge; `--provider` pins one). |
 
 ## Repository Exploration
@@ -584,10 +700,12 @@ legacy-key construction — ambient `process.env` is never reread.
 ## Reader
 
 `scoutline read` participates in Provider selection. Z.AI, Tavily, Exa,
-and Firecrawl advertise `reader`; Z.AI supplies it through the Z.AI
+Firecrawl, Parallel AI, Jina AI, You.com, Linkup, and Spider.cloud
+advertise `reader`; Z.AI supplies it through the Z.AI
 Reader Adapter, Tavily through the Tavily `/extract` endpoint, Exa
-through `/contents`, and Firecrawl through `/v2/scrape`. MiniMax and
-Brave do not, so by default (0.11.0+) selecting either emits a stderr
+through `/contents`, and Firecrawl through `/v2/scrape`. MiniMax,
+Brave, Perplexity, Bocha AI, SearchApi, and Kagi do not, so by default
+(0.11.0+) selecting any of them emits a stderr
 notice and Provider fallback auto-reroutes to the next eligible
 configured supplier; under `--no-fallback` (or
 `SCOUTLINE_NO_FALLBACK=1`) the preflight surfaces
@@ -718,7 +836,7 @@ additive optional fields to both schemas
 { source: "snapshot" | "live", observedAt, authoritative }`, the
 `providers` union may include a `{ status: "none", reason:
 "no-capability" }` row for a configured provider without quota (Exa,
-Parallel, Perplexity, You.com),
+Parallel, Perplexity, You.com, Bocha AI, and Kagi),
 and each `doctor` provider entry may carry `quota: { source:
 "snapshot" | "none", observedAt?, authoritative }` plus `verification:
 { status, checkedAt, reason? }`. Each `quota` requests category may

package/skills/scoutline/references/advanced.md

@@ -8,9 +8,9 @@ gate.
 
 Shared commands (`search`, `vision analyze`, `quota`, `doctor`),
 **`repo`**, **`read`**, **`crawl`**, **`map`**, and **`research`** accept
-the global `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider>` flag. Precedence:
+the global `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider|bocha|searchapi|kagi>` flag. Precedence:
 
-1. `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider>` on the command line
+1. `--provider <zai|minimax|tavily|exa|brave|firecrawl|parallel|perplexity|jina|you|linkup|spider|bocha|searchapi|kagi>` on the command line
 2. `SCOUTLINE_PROVIDER` environment variable
 3. Default `zai`
 
@@ -19,11 +19,12 @@ invocation. Provider selection is never inferred from credentials.
 
 `tools`, `tool`, `call`, and `code` accept the flag but ignore it; they
 remain Z.AI-only and do not validate the supplied value. `repo` and `read`
-participate in selection: Z.AI, Tavily, Exa, Firecrawl, Parallel, and
-Jina supply `reader`; only Z.AI supplies `repository-exploration`.
-`crawl` and `map` participate in selection and are supplied by Tavily
-and Firecrawl. `research` is supplied by Tavily, Exa, Parallel,
-Perplexity, and Jina. By default (0.11.0+) Provider
+participate in selection: Z.AI, Tavily, Exa, Firecrawl, Parallel, Jina,
+You.com, Linkup, and Spider.cloud supply `reader`; only Z.AI supplies
+`repository-exploration`. `crawl` and `map` participate in selection and
+are supplied by Tavily, Firecrawl, and Spider.cloud. `research` is
+supplied by Tavily, Exa, Parallel, Perplexity, Jina, You.com, and
+Linkup. By default (0.11.0+) Provider
 fallback is always-on: selecting a non-supplier emits a stderr notice
 and silently reroutes to the next eligible configured supplier in
 registry order. Under `--no-fallback` (or `SCOUTLINE_NO_FALLBACK=1`)
@@ -342,9 +343,10 @@ each advertised capability, exactly which built-in Providers supply it.
 `sharedCapabilities` and `zaiOnlyCapabilities` are gone; their two-array
 derivation silently hid capabilities supplied by a subset of providers.
 The matrix replaces them. `repository-exploration` is reported under
-Z.AI alone; `reader` under Z.AI, Tavily, Exa, Firecrawl, Parallel, and
-Jina; `crawl` and `map` under Tavily and Firecrawl; `research` under
-Tavily, Exa, Parallel, Perplexity, and Jina. Doctor help derives its
+Z.AI alone; `reader` under Z.AI, Tavily, Exa, Firecrawl, Parallel, Jina,
+You.com, Linkup, and Spider.cloud; `crawl` and `map` under Tavily,
+Firecrawl, and Spider.cloud; `research` under Tavily, Exa, Parallel,
+Perplexity, Jina, You.com, and Linkup. Doctor help derives its
 unsupported lists from the same descriptor metadata for every other
 Provider.