@staticn0va/wigolo 0.6.4 → 0.6.5

package/dist/instructions.d.ts

@@ -14,7 +14,7 @@
  * Parameter schemas (types, enums, required/optional) belong on the JSON
  * Schema, not here. Installation/configuration is for humans, not LLMs.
  */
-export declare const WIGOLO_INSTRUCTIONS = "Wigolo is a local-first web access layer: search the open web, fetch pages, crawl sites, extract structured data, find related content, run multi-step research, and execute agent-driven data gathering. All results land in a local SQLite cache that persists across sessions.\n\n## Host-LLM synthesis pattern (read this first)\n\nWigolo has no internal LLM. It returns *structured evidence* so YOU (the host LLM) write the final answer. Fold structure into your reply:\n\n- `search` `format: \"highlights\"` \u2192 FlashRank-scored passages + `citations`. Quote [N].\n- `research` \u2192 `brief` with `topics`, `highlights`, `key_findings` when sampling unavailable. Use as report scaffold.\n- `find_similar` \u2192 `cold_start` string when local signals are weak. Pass to user verbatim.\n- `extract` `mode: \"structured\"` \u2192 tables + definitions + jsonld + chart_hints + key_value_pairs in one call.\n- `fetch` metadata \u2192 `og_type`, `canonical_url`, `og_image` when present.\n\n## When to use which tool\n\n- `search` -- you need information on a topic but do not have a URL yet. Pass a query string or an array of 3-5 semantically varied keyword forms for broader coverage.\n- `fetch` -- you already have a specific URL to read.\n- `crawl` -- you need multiple pages from the same site (docs, wikis, references).\n- `cache` -- you want to know if the content is already on disk from an earlier read.\n- `extract` -- you need specific data points (tables, metadata, schema-shaped fields) rather than a whole page as markdown.\n- `find_similar` -- you have a URL or concept and want related content from the cache or web. Useful for \"more like this\" discovery.\n- `research` -- you have a complex question that needs multi-step investigation: question decomposition, parallel search, source synthesis into a report. Set `depth` to control thoroughness.\n- `agent` -- you need to gather structured or unstructured data from multiple sources based on a natural-language prompt. Provides full step transparency.\n\n## Routing by intent\n\n| Intent | Tool | Key parameters |\n|--------|------|----------------|\n| Documentation lookup | `search` | `include_domains: [\"react.dev\", \"nextjs.org\"]` -- scope to the project's official site, do not rely on `category: \"docs\"` alone |\n| Error debugging | `search` | exact error string as query, `category: \"code\"` (no domain scoping -- errors appear everywhere) |\n| Library research | `crawl` | seed URL of docs site, `strategy: \"sitemap\"`, then `cache` for later queries |\n| Related content | `find_similar` | `url` of a known good page, or `concept` as free text |\n| Direct quote | `search` | `format: \"highlights\"` returns FlashRank-scored passages with citations; cite [N] in your reply |\n| Direct answer | `search` | `format: \"answer\"` if client supports sampling, else falls back to `highlights` (not plain context) |\n| Comprehensive research | `research` | `depth: \"comprehensive\"`, optional `include_domains` to scope |\n| Data gathering | `agent` | natural-language `prompt`, optional `schema` for structured output |\n| Structured extraction | `extract` | `mode: \"structured\"` (tables + dl + JSON-LD + chart hints + kv pairs), or `mode: \"schema\"` with a JSON Schema |\n| Site inventory | `crawl` | `strategy: \"map\"` for URL-only discovery, no content fetched |\n\n## Rapidly changing content\n\nFor news, prices, status pages, or release notes, bypass the cache with `force_refresh: true`:\n\n  search({ query: \"...\", force_refresh: true })\n  fetch({ url: \"...\", force_refresh: true })\n\nFor docs, tutorials, and reference pages, let the cache work -- much faster.\n\n## Check the cache before going to the network\n\nBefore every `search` or `fetch`, consider a `cache` call. Pages read this session or earlier return instantly with full markdown -- no network. `research` and `agent` check the cache internally.\n\n## Multi-query search strategy\n\nFor broad queries, pass an array of 3-5 semantically varied keyword forms rather than one natural-language question. Example: instead of \"how does React handle state management\", pass `[\"react state management\", \"useState useReducer\", \"react hooks state\", \"react context vs redux\"]`. Sub-queries are deduplicated automatically.\n\n## Pick the right strategy\n\n- For docs sites, prefer `crawl` with `strategy: \"sitemap\"` -- faster and more complete than BFS.\n- For URL discovery only, use `crawl` with `strategy: \"map\"` -- URLs only, no content. Follow with targeted `fetch` calls.\n- For structured data (prices, specs, table rows), use `extract` with `mode: \"schema\"` or `mode: \"tables\"`. Use `fetch` only when you want the whole page as markdown.\n- For multi-source synthesis, use `research` instead of chaining `search` + `fetch` manually.\n- For natural-language data gathering, use `agent` with optional `schema`.\n- `crawl` accepts regex `include_patterns` and `exclude_patterns` to stay inside a section of a large site.\n\n## Scope searches by domain\n\nFor library/framework/SDK queries, **always pass `include_domains`** with official sites. Unscoped queries return generic noise. `category: \"docs\"` alone returns generic portals -- pair with `include_domains` or omit. Skip domain scoping for error strings, broad exploration, and news.\n\n## Performance\n\n- `max_results: 3` for focused lookups; `5` default; `10+` only for broad research.\n- `max_content_chars: 3000` on `search` or `fetch` smart-truncates each result's markdown at a paragraph/heading boundary with a `[... content truncated]` marker. Keeps context compact for AI agents. Prefer this over raw `max_chars` slicing.\n- `fetch` with `section: \"Heading Name\"` returns content under that heading -- cheaper than the whole page.\n- Repeated fetches of the same URL are free (SQLite cache).\n- `research` with `depth: \"quick\"` (~15s) suits most factual questions; reserve `\"comprehensive\"` for deep investigation.\n- `agent` respects `max_pages` (default 10) and `max_time_ms` (default 60s).\n\n## Extras\n\n- Localhost URLs (`localhost:3000`, `127.0.0.1:8080`) work for local dev servers.\n- `use_auth: true` on `fetch`/`crawl` reuses browser session for logged-in pages.\n- `cache` supports FTS5 syntax (`AND`, `OR`, `NOT`, `\"phrase\"`).\n- `research`/`agent` use MCP sampling when supported; fall back to structured data for host-LLM synthesis.";
+export declare const WIGOLO_INSTRUCTIONS = "Wigolo is a local-first web access layer: search the open web, fetch pages, crawl sites, extract structured data, find related content, run multi-step research, and execute agent-driven data gathering. All results land in a local SQLite cache that persists across sessions.\n\n## Host-LLM synthesis pattern (read this first)\n\nWigolo has no internal LLM. It returns *structured evidence* so YOU (the host LLM) write the final answer. Fold structure into your reply:\n\n- `search` `format: \"highlights\"` \u2192 FlashRank-scored passages + `citations`. Quote [N].\n- `research` \u2192 `brief` with `topics`, `highlights`, `key_findings`, `sections` when sampling unavailable. Use `sections.overview.cross_references` for corroborated findings, `sections.gaps` for coverage limits, `sections.comparison` for entity-vs-entity analysis. `query_type` indicates decomposition strategy used.\n- `find_similar` \u2192 `cold_start` string when local signals are weak. Pass to user verbatim.\n- `extract` `mode: \"structured\"` \u2192 tables + definitions + jsonld + chart_hints + key_value_pairs in one call.\n- `fetch` metadata \u2192 `og_type`, `canonical_url`, `og_image` when present.\n\n## When to use which tool\n\n- `search` -- you need information on a topic but do not have a URL yet. Pass a query string or an array of 3-5 semantically varied keyword forms for broader coverage.\n- `fetch` -- you already have a specific URL to read.\n- `crawl` -- you need multiple pages from the same site (docs, wikis, references).\n- `cache` -- you want to know if the content is already on disk from an earlier read.\n- `extract` -- you need specific data points (tables, metadata, schema-shaped fields) rather than a whole page as markdown.\n- `find_similar` -- you have a URL or concept and want related content from the cache or web. Useful for \"more like this\" discovery.\n- `research` -- you have a complex question that needs multi-step investigation: question decomposition, parallel search, source synthesis into a report. Set `depth` to control thoroughness.\n- `agent` -- you need to gather structured or unstructured data from multiple sources based on a natural-language prompt. Provides full step transparency.\n\n## Routing by intent\n\n| Intent | Tool | Key parameters |\n|--------|------|----------------|\n| Documentation lookup | `search` | `include_domains: [\"react.dev\", \"nextjs.org\"]` -- scope to the project's official site, do not rely on `category: \"docs\"` alone |\n| Error debugging | `search` | exact error string as query, `category: \"code\"` (no domain scoping -- errors appear everywhere) |\n| Library research | `crawl` | seed URL of docs site, `strategy: \"sitemap\"`, then `cache` for later queries |\n| Related content | `find_similar` | `url` of a known good page, or `concept` as free text |\n| Direct quote | `search` | `format: \"highlights\"` returns FlashRank-scored passages with citations; cite [N] in your reply |\n| Direct answer | `search` | `format: \"answer\"` if client supports sampling, else falls back to `highlights` (not plain context) |\n| Comprehensive research | `research` | `depth: \"comprehensive\"`, optional `include_domains` to scope |\n| Data gathering | `agent` | natural-language `prompt`, optional `schema` for structured output |\n| Structured extraction | `extract` | `mode: \"structured\"` (tables + dl + JSON-LD + chart hints + kv pairs), or `mode: \"schema\"` with a JSON Schema |\n| Site inventory | `crawl` | `strategy: \"map\"` for URL-only discovery, no content fetched |\n\n## Rapidly changing content\n\nFor news, prices, status pages, or release notes, bypass the cache with `force_refresh: true`:\n\n  search({ query: \"...\", force_refresh: true })\n  fetch({ url: \"...\", force_refresh: true })\n\nFor docs, tutorials, and reference pages, let the cache work -- much faster.\n\n## Check the cache before going to the network\n\nBefore every `search` or `fetch`, consider a `cache` call. Pages read this session or earlier return instantly with full markdown -- no network. `research` and `agent` check the cache internally.\n\n## Multi-query search strategy\n\nFor broad queries, pass an array of 3-5 semantically varied keyword forms rather than one natural-language question. Example: instead of \"how does React handle state management\", pass `[\"react state management\", \"useState useReducer\", \"react hooks state\", \"react context vs redux\"]`. Sub-queries are deduplicated automatically.\n\n## Pick the right strategy\n\n- For docs sites, prefer `crawl` with `strategy: \"sitemap\"` -- faster and more complete than BFS.\n- For URL discovery only, use `crawl` with `strategy: \"map\"` -- URLs only, no content. Follow with targeted `fetch` calls.\n- For structured data (prices, specs, table rows), use `extract` with `mode: \"schema\"` or `mode: \"tables\"`. Use `fetch` only when you want the whole page as markdown.\n- For multi-source synthesis, use `research` instead of chaining `search` + `fetch` manually.\n- For natural-language data gathering, use `agent` with optional `schema`.\n- `crawl` accepts regex `include_patterns` and `exclude_patterns` to stay inside a section of a large site.\n\n## Scope searches by domain\n\nFor library/framework/SDK queries, **always pass `include_domains`** with official sites. Unscoped queries return generic noise. `category: \"docs\"` alone returns generic portals -- pair with `include_domains` or omit. Skip domain scoping for error strings, broad exploration, and news.\n\n## Performance\n\n- `max_results: 3` for focused lookups; `5` default; `10+` only for broad research.\n- `max_content_chars: 3000` on `search` or `fetch` smart-truncates each result's markdown at a paragraph/heading boundary with a `[... content truncated]` marker. Keeps context compact for AI agents. Prefer this over raw `max_chars` slicing.\n- `fetch` with `section: \"Heading Name\"` returns content under that heading -- cheaper than the whole page.\n- Repeated fetches of the same URL are free (SQLite cache).\n- `research` with `depth: \"quick\"` (~15s) suits most factual questions; reserve `\"comprehensive\"` for deep investigation.\n- `agent` respects `max_pages` (default 10) and `max_time_ms` (default 60s).\n\n## Extras\n\n- Localhost URLs (`localhost:3000`, `127.0.0.1:8080`) work for local dev servers.\n- `use_auth: true` on `fetch`/`crawl` reuses browser session for logged-in pages.\n- `cache` supports FTS5 syntax (`AND`, `OR`, `NOT`, `\"phrase\"`).\n- `research`/`agent` use MCP sampling when supported; fall back to structured data for host-LLM synthesis.";
 export declare const TOOL_DESCRIPTIONS: {
     readonly fetch: "Fetch a single URL and return clean markdown. Use when you have a specific URL to read. Automatically detects if JavaScript rendering is needed.\n\nKey parameters:\n- section: extract content under a specific heading (e.g., section: \"API Reference\") -- faster than reading the whole page\n- max_content_chars: smart-truncate markdown at a paragraph/heading boundary with a `[... content truncated]` marker (e.g., 3000 for compact context). Preferred over max_chars for AI agents.\n- use_auth: true to use stored browser session for authenticated/private pages\n- render_js: \"auto\" (default, detects JS need), \"always\" (force browser), \"never\" (HTTP only, fastest)\n- headers: custom HTTP headers if needed\n- force_refresh: true to bypass cache and fetch fresh content from the network\n\nReturns title, markdown, links, images, metadata (og_image, og_type, canonical_url, keywords). Decorative images filtered, relative URLs resolved. Cached locally; repeat fetches are instant. Localhost URLs work.\n\nUse force_refresh: true for frequently changing content. Default serves from cache.";
     readonly search: "Search the web and return full markdown content from top results. Returns extracted page content, not just snippets.\n\nKey parameters:\n- query: string or string[] array (3-5 keyword variants for broader coverage; deduplicated automatically)\n- include_domains/exclude_domains: scope to specific sites. ALWAYS scope library/framework queries.\n- category: \"general\" | \"news\" | \"code\" | \"docs\" | \"papers\" — coarse filter, pair with include_domains.\n- from_date/to_date: ISO YYYY-MM-DD for time-bounded queries\n- max_results: default 5; use 3 for focused, 10+ for research\n- format: \"full\" (default), \"context\", \"highlights\" (FlashRank-scored passages + [N] citations), \"answer\" (sampling synthesis; falls back to highlights), \"stream_answer\"\n- max_highlights: cap highlights count (default 10)\n- max_content_chars: smart-truncate markdown at paragraph boundary (e.g., 3000)\n- force_refresh: true to bypass all caches\n\n\"answer\" falls back to \"highlights\" when sampling unsupported (most clients). Results include title, URL, relevance_score, and full markdown_content. Cache serves previously fetched pages instantly.";
@@ -22,7 +22,7 @@ export declare const TOOL_DESCRIPTIONS: {
     readonly cache: "Search previously fetched content without hitting the network. Use before searching the web -- if relevant content was already fetched or crawled, this returns it instantly.\n\nKey parameters:\n- query: full-text search over cached markdown and titles (supports FTS5 syntax: AND, OR, NOT, \"phrase match\")\n- url_pattern: glob filter on URLs (e.g., \"*example.com*\")\n- since: ISO date -- only results cached after this date\n- stats: true to get cache size, entry count, oldest/newest dates\n- clear: true to delete matching entries\n\nReturns matching cached pages with full markdown content. Cache persists across sessions in local SQLite.";
     readonly extract: "Extract structured data from a URL or raw HTML. Use when you need specific data points, tables, or metadata rather than full page markdown.\n\nKey parameters:\n- mode: \"selector\" (CSS selector -> text), \"tables\" (HTML tables only), \"metadata\" (title/author/date/description/og_* + JSON-LD), \"schema\" (JSON Schema -> heuristic field extraction), \"structured\" (ONE-SHOT: tables + <dl> definitions + JSON-LD + chart hints from SVG/figure + microdata/data-attr/grid key-value pairs)\n- css_selector: required for mode=\"selector\" -- any valid CSS selector\n- schema: for mode=\"schema\", a JSON Schema object describing the fields to extract\n- multiple: true to return array of all matches (mode=\"selector\" only)\n\nPrefer mode=\"structured\" over chaining multiple extract calls — it returns every structured pattern on the page in one response:\n  { tables, definitions, jsonld, chart_hints, key_value_pairs }\n\nchart_hints surfaces SVG titles, aria-labels, and figcaptions — host LLMs use these to describe data visualizations even when the underlying data is rendered by JavaScript.\n\nFor mode=\"tables\", returns array of table objects with headers and row data. For mode=\"schema\", pass { price: \"string\", name: \"string\" } and get structured fields extracted from the page.";
     readonly find_similar: "Find content related to a URL or concept. Use when you have a known-good page or topic and want to discover similar resources from the cache or web.\n\nKey parameters:\n- url: a URL to find content similar to. The page's content and embeddings are used for similarity matching.\n- concept: free-text description of what you want similar content for. Use when you do not have a specific URL.\n- max_results: number of similar items to return (default 5)\n- include_cached: true (default) to search the local cache first, false to skip cache and search the web only\n- threshold: minimum similarity score (0-1, default 0.5) -- higher values return fewer, more relevant results\n\nProvide either url or concept (not both). Results are fused from three signals via 3-way RRF: FTS5 keyword match, sentence-transformer embeddings, and (if local hits are sparse) a live web search. Each result carries `match_signals` with `embedding_rank`, `fts5_rank`, and `fused_score` so you can explain ranking to the user.\n\nThe response may include a `cold_start` string when local signals are weak (empty cache, embeddings unavailable, < 20 cached pages). Pass this verbatim to the user — it explains why results came from web search and how to warm the cache.\n\nReturns results array, method used (\"hybrid\" | \"embedding\" | \"fts5\" | \"search\"), cache_hits, search_hits, embedding_available, and total_time_ms.";
-    readonly research: "Run multi-step research on a complex question. Decomposes the question into sub-queries, searches in parallel, fetches top sources, and synthesizes a report with citations.\n\nKey parameters:\n- question: the research question to investigate\n- depth: \"quick\" (~15s, 2 sub-queries, 5-8 sources), \"standard\" (~40s, 4 sub-queries, 10-15 sources, default), \"comprehensive\" (~80s, 7 sub-queries, 20-25 sources)\n- max_sources: override the default source count for the chosen depth\n- include_domains/exclude_domains: scope research to specific sites\n- schema: optional JSON Schema -- if provided, the report is structured to extract fields matching the schema\n- stream: true to receive progress notifications as each research phase completes\n\nThe pipeline: (1) decompose question into sub-queries, (2) parallel search across sub-queries, (3) fetch and extract top unique sources, (4) synthesize report with citations from all sources, (5) optionally structure report fields if schema is provided.\n\nUses MCP requestSampling for intelligent decomposition and synthesis when available. Without sampling support (the common case), the output includes a `brief` field with:\n  - `topics`: sub-query labels or distilled source-title topics\n  - `highlights`: FlashRank-scored passages with source_index, source_url, relevance_score\n  - `key_findings`: first substantive paragraph per source, ordered by relevance\n  - `per_source_char_cap` / `total_sources_char_cap`: budget hints so you know what was trimmed\n\nThe host LLM (you) should build its final report from the brief rather than re-reading every source — the brief is the structured scaffold this tool produces when it cannot synthesize internally.\n\nReturns report (markdown), citations array, sources with full content, sub_queries used, depth level, total_time_ms, sampling_supported flag, and optional brief.";
+    readonly research: "Run multi-step research on a complex question. Decomposes the question into sub-queries, searches in parallel, fetches top sources, and synthesizes a report with citations.\n\nKey parameters:\n- question: the research question to investigate\n- depth: \"quick\" (~15s, 2 sub-queries, 5-8 sources), \"standard\" (~40s, 4 sub-queries, 10-15 sources, default), \"comprehensive\" (~80s, 7 sub-queries, 20-25 sources)\n- max_sources: override the default source count for the chosen depth\n- include_domains/exclude_domains: scope research to specific sites\n- schema: optional JSON Schema -- if provided, the report is structured to extract fields matching the schema\n- stream: true to receive progress notifications as each research phase completes\n\nThe pipeline: (1) decompose question into sub-queries, (2) parallel search across sub-queries, (3) fetch and extract top unique sources, (4) synthesize report with citations from all sources, (5) optionally structure report fields if schema is provided.\n\nUses MCP requestSampling for intelligent decomposition and synthesis when available. Without sampling support (the common case), the output includes a `brief` with:\n  - `topics`, `highlights` (FlashRank-scored), `key_findings` (per-source, by relevance)\n  - `query_type`: \"comparison\" | \"how-to\" | \"concept\" | \"general\"\n  - `sections.overview`: top findings + cross_references (corroborated by 2+ sources)\n  - `sections.comparison`: entities + comparison_points (comparison queries only)\n  - `sections.gaps`: sub-queries with limited source coverage\n\nBuild your report: overview from key_findings, cross-referenced findings first (most reliable), per-topic sections, comparison table if present, then gaps and sources.\n\nReturns report (markdown), citations array, sources with full content, sub_queries used, depth level, total_time_ms, sampling_supported flag, and optional brief.";
     readonly agent: "Execute a natural-language data gathering task. Plans search queries and URLs from a prompt, executes them in parallel, and synthesizes results. Full step transparency.\n\nKey parameters:\n- prompt: natural-language description of what data to gather (e.g., \"find pricing for the top 5 CRM tools\")\n- urls: optional array of specific URLs to include in the gathering\n- schema: optional JSON Schema -- if provided, extracts structured data matching the schema from each page and merges results\n- max_pages: maximum pages to fetch (default 10)\n- max_time_ms: maximum execution time in milliseconds (default 60000)\n- stream: true to receive progress notifications as each step completes\n\nThe pipeline: (1) plan -- interpret prompt to determine search queries and URLs to visit, (2) execute -- run searches and fetch URLs in parallel within budget, (3) extract -- if schema provided, apply schema extraction to each page and merge, (4) synthesize -- produce natural-language or structured result.\n\nThe steps array in the output provides full transparency into every action taken (plan, search, fetch, extract, synthesize) with timing. This differentiates from black-box alternatives.\n\nUses MCP requestSampling for planning and synthesis. Without sampling support, uses keyword extraction for planning and returns raw content.\n\nReturns result (string or structured object), sources array, pages_fetched count, steps array with action/detail/time_ms, total_time_ms, and sampling_supported flag.";
 };
 export type ToolName = keyof typeof TOOL_DESCRIPTIONS;

package/dist/instructions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,mBAAmB,iwMAkF+E,CAAC;AAEhH,eAAO,MAAM,iBAAiB;;;;;;;;;CAwHpB,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,iBAAiB,CAAC"}
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,eAAO,MAAM,mBAAmB,u8MAkF+E,CAAC;AAEhH,eAAO,MAAM,iBAAiB;;;;;;;;;CAyHpB,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,MAAM,OAAO,iBAAiB,CAAC"}

package/dist/instructions.js

@@ -21,7 +21,7 @@ export const WIGOLO_INSTRUCTIONS = `Wigolo is a local-first web access layer: se
 Wigolo has no internal LLM. It returns *structured evidence* so YOU (the host LLM) write the final answer. Fold structure into your reply:
 
 - \`search\` \`format: "highlights"\` → FlashRank-scored passages + \`citations\`. Quote [N].
-- \`research\` → \`brief\` with \`topics\`, \`highlights\`, \`key_findings\` when sampling unavailable. Use as report scaffold.
+- \`research\` → \`brief\` with \`topics\`, \`highlights\`, \`key_findings\`, \`sections\` when sampling unavailable. Use \`sections.overview.cross_references\` for corroborated findings, \`sections.gaps\` for coverage limits, \`sections.comparison\` for entity-vs-entity analysis. \`query_type\` indicates decomposition strategy used.
 - \`find_similar\` → \`cold_start\` string when local signals are weak. Pass to user verbatim.
 - \`extract\` \`mode: "structured"\` → tables + definitions + jsonld + chart_hints + key_value_pairs in one call.
 - \`fetch\` metadata → \`og_type\`, \`canonical_url\`, \`og_image\` when present.
@@ -184,13 +184,14 @@ Key parameters:
 
 The pipeline: (1) decompose question into sub-queries, (2) parallel search across sub-queries, (3) fetch and extract top unique sources, (4) synthesize report with citations from all sources, (5) optionally structure report fields if schema is provided.
 
-Uses MCP requestSampling for intelligent decomposition and synthesis when available. Without sampling support (the common case), the output includes a \`brief\` field with:
-  - \`topics\`: sub-query labels or distilled source-title topics
-  - \`highlights\`: FlashRank-scored passages with source_index, source_url, relevance_score
-  - \`key_findings\`: first substantive paragraph per source, ordered by relevance
-  - \`per_source_char_cap\` / \`total_sources_char_cap\`: budget hints so you know what was trimmed
+Uses MCP requestSampling for intelligent decomposition and synthesis when available. Without sampling support (the common case), the output includes a \`brief\` with:
+  - \`topics\`, \`highlights\` (FlashRank-scored), \`key_findings\` (per-source, by relevance)
+  - \`query_type\`: "comparison" | "how-to" | "concept" | "general"
+  - \`sections.overview\`: top findings + cross_references (corroborated by 2+ sources)
+  - \`sections.comparison\`: entities + comparison_points (comparison queries only)
+  - \`sections.gaps\`: sub-queries with limited source coverage
 
-The host LLM (you) should build its final report from the brief rather than re-reading every source — the brief is the structured scaffold this tool produces when it cannot synthesize internally.
+Build your report: overview from key_findings, cross-referenced findings first (most reliable), per-topic sections, comparison table if present, then gaps and sources.
 
 Returns report (markdown), citations array, sources with full content, sub_queries used, depth level, total_time_ms, sampling_supported flag, and optional brief.`,
     agent: `Execute a natural-language data gathering task. Plans search queries and URLs from a prompt, executes them in parallel, and synthesizes results. Full step transparency.

package/dist/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+GAkF4E,CAAC;AAEhH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE;;;;;;;;;;;;oFAY2E;IAElF,MAAM,EAAE;;;;;;;;;;;;;uMAa6L;IAErM,KAAK,EAAE;;;;;;;;uLAQ8K;IAErL,KAAK,EAAE;;;;;;;;;0GASiG;IAExG,OAAO,EAAE;;;;;;;;;;;;;4LAaiL;IAE1L,YAAY,EAAE;;;;;;;;;;;;;kJAakI;IAEhJ,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;kKAoBsJ;IAEhK,KAAK,EAAE;;;;;;;;;;;;;;;;sKAgB6J;CAC5J,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;+GAkF4E,CAAC;AAEhH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,KAAK,EAAE;;;;;;;;;;;;oFAY2E;IAElF,MAAM,EAAE;;;;;;;;;;;;;uMAa6L;IAErM,KAAK,EAAE;;;;;;;;uLAQ8K;IAErL,KAAK,EAAE;;;;;;;;;0GASiG;IAExG,OAAO,EAAE;;;;;;;;;;;;;4LAaiL;IAE1L,YAAY,EAAE;;;;;;;;;;;;;kJAakI;IAEhJ,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;kKAqBsJ;IAEhK,KAAK,EAAE;;;;;;;;;;;;;;;;sKAgB6J;CAC5J,CAAC"}

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,KAAK,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AASzJ,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AAmBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBnD"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAKA,KAAK,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,UAAU,GAAG,OAAO,CAAC;AASzJ,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACzD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACxD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC1D;AA+CD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBnD"}

package/dist/logger.js

@@ -1,3 +1,5 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
 import { getConfig } from './config.js';
 const LEVEL_PRIORITY = {
     debug: 0,
@@ -5,6 +7,23 @@ const LEVEL_PRIORITY = {
     warn: 2,
     error: 3,
 };
+let tuiLogPath = null;
+function getTuiLogPath() {
+    if (!tuiLogPath) {
+        const dataDir = getConfig().dataDir;
+        mkdirSync(dataDir, { recursive: true });
+        tuiLogPath = join(dataDir, 'init.log');
+    }
+    return tuiLogPath;
+}
+function appendToLogFile(line) {
+    try {
+        appendFileSync(getTuiLogPath(), line + '\n');
+    }
+    catch {
+        // best effort — don't crash the TUI
+    }
+}
 function writeJson(level, module, msg, data) {
     const line = JSON.stringify({
         ts: new Date().toISOString(),
@@ -13,12 +32,21 @@ function writeJson(level, module, msg, data) {
         module,
         ...(data ? { data } : {}),
     });
+    if (process.env.WIGOLO_TUI_MODE === 'true') {
+        appendToLogFile(line);
+        return;
+    }
     process.stderr.write(line + '\n');
 }
 function writeText(level, module, msg, data) {
     const ts = new Date().toISOString();
     const dataStr = data ? ' ' + Object.entries(data).map(([k, v]) => `${k}=${v}`).join(' ') : '';
-    process.stderr.write(`[${ts}] ${level.toUpperCase().padEnd(5)} [${module}] ${msg}${dataStr}\n`);
+    const line = `[${ts}] ${level.toUpperCase().padEnd(5)} [${module}] ${msg}${dataStr}`;
+    if (process.env.WIGOLO_TUI_MODE === 'true') {
+        appendToLogFile(line);
+        return;
+    }
+    process.stderr.write(line + '\n');
 }
 export function createLogger(module) {
     const config = getConfig();

package/dist/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAKxC,MAAM,cAAc,GAA6B;IAC/C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AASF,SAAS,SAAS,CAAC,KAAe,EAAE,MAAc,EAAE,GAAW,EAAE,IAA8B;IAC7F,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,KAAK;QACL,GAAG;QACH,MAAM;QACN,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1B,CAAC,CAAC;IACH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,SAAS,SAAS,CAAC,KAAe,EAAE,MAAc,EAAE,GAAW,EAAE,IAA8B;IAC7F,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9F,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,KAAK,GAAG,GAAG,OAAO,IAAI,CAAC,CAAC;AAClG,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IACzC,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAC3B,MAAM,WAAW,GAAG,cAAc,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;IAElE,SAAS,GAAG,CAAC,KAAe,EAAE,GAAW,EAAE,IAA8B;QACvE,IAAI,cAAc,CAAC,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;YACzC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,OAAO;QACL,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;QAC7C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,IAAI,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC;QAC3C,KAAK,EAAE,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC;KAC9C,CAAC;AACJ,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"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"}

package/dist/research/brief.d.ts

@@ -1,3 +1,5 @@
-import type { ResearchBrief, ResearchSource } from '../types.js';
-export declare function buildResearchBrief(question: string, sources: ResearchSource[], subQueries: string[], perSourceCharCap: number, totalSourcesCharCap: number): Promise<ResearchBrief>;
+import type { ResearchBrief, ResearchSource, CrossReference } from '../types.js';
+import type { QueryType } from './decompose.js';
+export declare function buildResearchBrief(question: string, sources: ResearchSource[], subQueries: string[], perSourceCharCap: number, totalSourcesCharCap: number, queryType?: QueryType, comparisonEntities?: string[]): Promise<ResearchBrief>;
+export declare function detectCrossReferences(sources: ResearchSource[]): CrossReference[];
 //# sourceMappingURL=brief.d.ts.map

package/dist/research/brief.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brief.d.ts","sourceRoot":"","sources":["../../src/research/brief.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAoB,MAAM,aAAa,CAAC;AAUnF,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,EAAE,MAAM,GAC1B,OAAO,CAAC,aAAa,CAAC,CAyBxB"}
+{"version":3,"file":"brief.d.ts","sourceRoot":"","sources":["../../src/research/brief.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAoB,cAAc,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAYhD,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,cAAc,EAAE,EACzB,UAAU,EAAE,MAAM,EAAE,EACpB,gBAAgB,EAAE,MAAM,EACxB,mBAAmB,EAAE,MAAM,EAC3B,SAAS,GAAE,SAAqB,EAChC,kBAAkB,GAAE,MAAM,EAAO,GAChC,OAAO,CAAC,aAAa,CAAC,CAwCxB;AA6BD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,cAAc,EAAE,CAuCjF"}

package/dist/research/brief.js

@@ -2,10 +2,12 @@ import { extractHighlights } from '../search/highlights.js';
 const MAX_HIGHLIGHTS = 12;
 const MAX_KEY_FINDING_LEN = 280;
 const MAX_TOPICS = 8;
+const MAX_CROSS_REFS = 10;
+const MIN_PHRASE_LEN = 4;
 // Build a host-LLM-friendly structured brief when internal sampling is
 // unavailable. The host model (Claude Code / Cursor / etc.) consumes this
 // shape to produce the final report without needing to re-read raw sources.
-export async function buildResearchBrief(question, sources, subQueries, perSourceCharCap, totalSourcesCharCap) {
+export async function buildResearchBrief(question, sources, subQueries, perSourceCharCap, totalSourcesCharCap, queryType = 'general', comparisonEntities = []) {
     const fetched = sources.filter((s) => s.fetched && s.markdown_content.length > 0);
     // Highlights reuse the FlashRank-or-paragraph scorer so briefs align with
     // whatever format='highlights' produces for single-query searches.
@@ -19,12 +21,26 @@ export async function buildResearchBrief(question, sources, subQueries, perSourc
     const { highlights } = await extractHighlights(question, searchItems, MAX_HIGHLIGHTS);
     const topics = buildTopics(subQueries, fetched);
     const keyFindings = buildKeyFindings(fetched);
+    const crossReferences = detectCrossReferences(fetched);
+    const gaps = detectGaps(subQueries, fetched);
+    const comparison = queryType === 'comparison' && comparisonEntities.length >= 2
+        ? buildComparisonSection(comparisonEntities, fetched)
+        : undefined;
     return {
         topics,
         highlights,
         key_findings: keyFindings,
         per_source_char_cap: perSourceCharCap,
         total_sources_char_cap: totalSourcesCharCap,
+        sections: {
+            overview: {
+                key_findings: keyFindings.slice(0, 5),
+                cross_references: crossReferences,
+            },
+            ...(comparison ? { comparison } : {}),
+            gaps,
+        },
+        query_type: queryType,
     };
 }
 // Prefer sub-queries (planner's view of the topic space) when available;
@@ -53,6 +69,106 @@ function buildKeyFindings(sources) {
     }
     return dedupe(out);
 }
+export function detectCrossReferences(sources) {
+    if (sources.length < 2)
+        return [];
+    // Extract significant phrases from each source's content
+    const phraseMap = new Map();
+    for (let idx = 0; idx < sources.length; idx++) {
+        const content = sources[idx].markdown_content.toLowerCase();
+        const words = content
+            .replace(/[^a-z0-9\s]/g, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length >= MIN_PHRASE_LEN && !STOP_WORDS.has(w));
+        const seenForSource = new Set();
+        for (let i = 0; i < words.length - 2; i++) {
+            const phrase = words.slice(i, i + 3).join(' ');
+            if (seenForSource.has(phrase))
+                continue;
+            seenForSource.add(phrase);
+            if (!phraseMap.has(phrase))
+                phraseMap.set(phrase, new Set());
+            phraseMap.get(phrase).add(idx);
+        }
+    }
+    // Phrases found in 2+ sources are cross-references
+    const candidates = [];
+    for (const [phrase, sourceIndices] of phraseMap) {
+        if (sourceIndices.size >= 2) {
+            candidates.push({
+                finding: phrase,
+                source_indices: [...sourceIndices].sort(),
+                confidence: sourceIndices.size >= 3 ? 'high' : 'medium',
+            });
+        }
+    }
+    // Sort by number of sources (desc), then deduplicate overlapping phrases
+    candidates.sort((a, b) => b.source_indices.length - a.source_indices.length);
+    return deduplicateOverlapping(candidates).slice(0, MAX_CROSS_REFS);
+}
+function deduplicateOverlapping(refs) {
+    const kept = [];
+    const usedWords = new Set();
+    for (const ref of refs) {
+        const words = ref.finding.split(' ');
+        // Skip if most words already covered by a higher-ranked cross-reference
+        const overlapCount = words.filter((w) => usedWords.has(w)).length;
+        if (overlapCount >= words.length - 1 && kept.length > 0)
+            continue;
+        kept.push(ref);
+        for (const w of words)
+            usedWords.add(w);
+    }
+    return kept;
+}
+function detectGaps(subQueries, sources) {
+    if (subQueries.length === 0)
+        return [];
+    const gaps = [];
+    const contentLower = sources.map((s) => s.markdown_content.toLowerCase()).join(' ');
+    for (const query of subQueries) {
+        // Extract significant words from sub-query
+        const words = query.toLowerCase()
+            .replace(/[^a-z0-9\s]/g, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length >= MIN_PHRASE_LEN && !STOP_WORDS.has(w));
+        if (words.length === 0)
+            continue;
+        // Count how many significant words appear in any source
+        const found = words.filter((w) => contentLower.includes(w)).length;
+        const coverage = found / words.length;
+        if (coverage < 0.5) {
+            gaps.push(`Limited coverage for: "${query}"`);
+        }
+    }
+    return gaps;
+}
+function buildComparisonSection(entities, sources) {
+    const comparisonPoints = [];
+    const contentLower = sources.map((s) => s.markdown_content.toLowerCase()).join('\n');
+    // Look for comparison keywords near entity mentions
+    const comparisonTerms = ['faster', 'slower', 'better', 'worse', 'more', 'less',
+        'easier', 'harder', 'simpler', 'complex', 'lightweight', 'heavy',
+        'performance', 'scalability', 'ecosystem', 'community', 'support'];
+    for (const term of comparisonTerms) {
+        if (!contentLower.includes(term))
+            continue;
+        // Check if term appears near any entity
+        const nearEntity = entities.some((e) => {
+            const entityLower = e.toLowerCase();
+            const idx = contentLower.indexOf(entityLower);
+            if (idx === -1)
+                return false;
+            // Check within 200 chars of entity mention
+            const neighborhood = contentLower.slice(Math.max(0, idx - 200), idx + e.length + 200);
+            return neighborhood.includes(term);
+        });
+        if (nearEntity) {
+            comparisonPoints.push(term);
+        }
+    }
+    return { entities, comparison_points: [...new Set(comparisonPoints)] };
+}
 function firstSubstantiveParagraph(markdown) {
     const paragraphs = markdown.split(/\n\n+/).map((p) => p.trim());
     for (const p of paragraphs) {
@@ -76,4 +192,14 @@ function dedupe(list) {
     }
     return out;
 }
+const STOP_WORDS = new Set([
+    'about', 'after', 'also', 'been', 'before', 'being', 'between',
+    'both', 'could', 'does', 'doing', 'done', 'each', 'even', 'every',
+    'from', 'have', 'here', 'into', 'just', 'like', 'made', 'make',
+    'many', 'more', 'most', 'much', 'must', 'need', 'only', 'other',
+    'over', 'same', 'should', 'some', 'such', 'than', 'that', 'their',
+    'them', 'then', 'there', 'these', 'they', 'this', 'those', 'through',
+    'very', 'want', 'well', 'were', 'what', 'when', 'where', 'which',
+    'while', 'will', 'with', 'would', 'your',
+]);
 //# sourceMappingURL=brief.js.map

package/dist/research/brief.js.map

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

package/dist/research/decompose.d.ts

@@ -1,7 +1,14 @@
 import { type SamplingCapableServer } from '../search/sampling.js';
+export type QueryType = 'comparison' | 'how-to' | 'concept' | 'general';
 export interface DecomposeResult {
     subQueries: string[];
     samplingUsed: boolean;
+    queryType: QueryType;
 }
 export declare function decomposeQuestion(question: string, depth: 'quick' | 'standard' | 'comprehensive', server?: SamplingCapableServer): Promise<DecomposeResult>;
+export declare function detectQueryType(question: string): QueryType;
+export declare function extractComparisonEntities(question: string): {
+    entities: string[];
+    context: string;
+};
 //# sourceMappingURL=decompose.d.ts.map

package/dist/research/decompose.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"decompose.d.ts","sourceRoot":"","sources":["../../src/research/decompose.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,uBAAuB,CAAC;AAU/B,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,eAAe,EAC7C,MAAM,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAkB1B"}
+{"version":3,"file":"decompose.d.ts","sourceRoot":"","sources":["../../src/research/decompose.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAG3B,MAAM,uBAAuB,CAAC;AAU/B,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAExE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;CACtB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GAAG,UAAU,GAAG,eAAe,EAC7C,MAAM,CAAC,EAAE,qBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAuC1B;AA8ED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA0B3D;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CA6BnG"}

package/dist/research/decompose.js

@@ -8,11 +8,12 @@ const DEPTH_SUB_QUERY_COUNT = {
 };
 export async function decomposeQuestion(question, depth, server) {
     const targetCount = DEPTH_SUB_QUERY_COUNT[depth] ?? 4;
+    const queryType = detectQueryType(question);
     if (server) {
         try {
             const result = await decomposeWithSampling(question, targetCount, server);
             if (result) {
-                return { subQueries: result, samplingUsed: true };
+                return { subQueries: result, samplingUsed: true, queryType };
             }
         }
         catch (err) {
@@ -21,8 +22,27 @@ export async function decomposeQuestion(question, depth, server) {
             });
         }
     }
+    const templateQueries = decomposeWithTemplate(question, queryType, targetCount);
+    if (templateQueries && templateQueries.length >= targetCount) {
+        return { subQueries: templateQueries, samplingUsed: false, queryType };
+    }
+    // Template produced some queries but not enough — supplement with fallback
+    if (templateQueries && templateQueries.length > 0) {
+        const fallback = decomposeWithFallback(question, targetCount);
+        const merged = [...templateQueries];
+        const seen = new Set(merged.map(q => q.toLowerCase()));
+        for (const q of fallback) {
+            if (merged.length >= targetCount)
+                break;
+            if (!seen.has(q.toLowerCase())) {
+                merged.push(q);
+                seen.add(q.toLowerCase());
+            }
+        }
+        return { subQueries: merged.slice(0, targetCount), samplingUsed: false, queryType };
+    }
     const fallback = decomposeWithFallback(question, targetCount);
-    return { subQueries: fallback, samplingUsed: false };
+    return { subQueries: fallback, samplingUsed: false, queryType };
 }
 async function decomposeWithSampling(question, targetCount, server) {
     try {
@@ -85,6 +105,109 @@ Respond with ONLY valid JSON: {"subQueries": ["query1", "query2", ...]}`;
         return null;
     }
 }
+export function detectQueryType(question) {
+    const q = question.trim().toLowerCase();
+    // Comparison: "X vs Y", "X versus Y", "compare X and Y", "X or Y for Z"
+    if (/\bvs\.?\s/i.test(q) || /\bversus\b/i.test(q) || /^compare\b/i.test(q)) {
+        return 'comparison';
+    }
+    if (/\b(?:difference|differences)\s+between\b/i.test(q)) {
+        return 'comparison';
+    }
+    // "X or Y for Z" pattern (choice between alternatives)
+    if (/\b\w+\s+or\s+\w+\s+for\b/i.test(q)) {
+        return 'comparison';
+    }
+    // How-to: "how to ...", "how do I ...", "how can I ...", "steps to ..."
+    if (/^how\s+(?:to|do|does|can|should)\b/i.test(q) || /^steps\s+to\b/i.test(q)) {
+        return 'how-to';
+    }
+    // Concept: "what is ...", "explain ...", "overview of ..."
+    if (/^(?:what\s+(?:is|are)|explain|overview\s+of|describe)\b/i.test(q)) {
+        return 'concept';
+    }
+    return 'general';
+}
+export function extractComparisonEntities(question) {
+    // Strip common question prefixes so "how does X vs Y" still matches
+    const cleaned = question
+        .replace(/[?!.]/g, '')
+        .replace(/^(?:how\s+(?:does|do|is|are|about)|what\s+(?:is|are)\s+(?:the\s+)?(?:difference|differences)\s+(?:between)?|should\s+I\s+(?:use|choose)|which\s+is\s+better)\s*/i, '')
+        .trim();
+    // "X vs Y vs Z for/in/with context"
+    const vsMatch = cleaned.match(/^(.+?)\s+(?:vs\.?|versus)\s+(.+?)(?:\s+(?:vs\.?|versus)\s+(.+?))?(?:\s+(?:for|in|with|when)\s+(.+))?$/i);
+    if (vsMatch) {
+        const entities = [vsMatch[1], vsMatch[2], vsMatch[3]].filter(Boolean).map(e => e.trim());
+        return { entities, context: vsMatch[4]?.trim() || '' };
+    }
+    // "compare X and Y for context" / "compare X, Y, and Z"
+    const compareMatch = cleaned.match(/^compare\s+(.+?)(?:\s+(?:for|in|with|when)\s+(.+))?$/i);
+    if (compareMatch) {
+        const entityPart = compareMatch[1];
+        const entities = entityPart.split(/(?:,\s*|\s+and\s+)/).map(e => e.trim()).filter(Boolean);
+        return { entities, context: compareMatch[2]?.trim() || '' };
+    }
+    // "differences between X and Y"
+    const diffMatch = cleaned.match(/differences?\s+between\s+(.+?)\s+and\s+(.+?)(?:\s+(?:for|in|with)\s+(.+))?$/i);
+    if (diffMatch) {
+        return { entities: [diffMatch[1].trim(), diffMatch[2].trim()], context: diffMatch[3]?.trim() || '' };
+    }
+    return { entities: [], context: '' };
+}
+function decomposeWithTemplate(question, queryType, targetCount) {
+    if (queryType === 'comparison') {
+        const { entities, context } = extractComparisonEntities(question);
+        if (entities.length < 2)
+            return null;
+        const queries = [];
+        // Per-entity queries
+        for (const entity of entities) {
+            queries.push(`${entity} ${context} features performance`.trim());
+        }
+        // Cross-comparison queries
+        for (let i = 0; i < entities.length; i++) {
+            for (let j = i + 1; j < entities.length; j++) {
+                queries.push(`${entities[i]} vs ${entities[j]} ${context} comparison`.trim());
+            }
+        }
+        // Ecosystem/adoption query
+        queries.push(`${entities.join(' vs ')} which to choose ${context}`.trim());
+        return [...new Set(queries)].slice(0, targetCount);
+    }
+    if (queryType === 'how-to') {
+        const cleaned = question.replace(/[?!.]/g, '').trim();
+        const task = cleaned.replace(/^(?:how\s+(?:to|do\s+I|does\s+one|can\s+I|should\s+I)|steps\s+to)\s+/i, '').trim();
+        if (task.length < 5)
+            return null;
+        const queries = [
+            `${task} tutorial guide`,
+            `${task} best practices`,
+            `${task} common mistakes pitfalls`,
+            `${task} examples production`,
+            `${task} step by step`,
+            `${task} tools libraries`,
+            `${task} troubleshooting`,
+        ];
+        return [...new Set(queries)].slice(0, targetCount);
+    }
+    if (queryType === 'concept') {
+        const cleaned = question.replace(/[?!.]/g, '').trim();
+        const concept = cleaned.replace(/^(?:what\s+(?:is|are)|explain|overview\s+of|describe)\s+/i, '').trim();
+        if (concept.length < 3)
+            return null;
+        const queries = [
+            `${concept} definition overview`,
+            `${concept} how it works architecture`,
+            `${concept} use cases applications`,
+            `${concept} alternatives comparison`,
+            `${concept} advantages disadvantages`,
+            `${concept} examples real world`,
+            `${concept} best practices`,
+        ];
+        return [...new Set(queries)].slice(0, targetCount);
+    }
+    return null;
+}
 function decomposeWithFallback(question, targetCount) {
     const cleaned = question.trim();
     if (!cleaned) {
@@ -146,6 +269,7 @@ function extractNounPhrases(text) {
         'this', 'that', 'these', 'those', 'i', 'me', 'my', 'we', 'our',
         'you', 'your', 'he', 'him', 'his', 'she', 'her', 'it', 'its',
         'they', 'them', 'their',
+        'vs', 'versus', 'compare', 'compared', 'comparison',
     ]);
     const words = text.replace(/[?!.,;:'"()\[\]{}]/g, ' ').split(/\s+/).filter(Boolean);
     const contentWords = words.filter((w) => !stopWords.has(w.toLowerCase()));