@automatelab/citation-intelligence 0.6.0 → 0.8.0

package/README.md

@@ -36,10 +36,13 @@ The AI citation tracking market is dominated by VC-funded dashboards starting at
 
 ## Tools
 
+**Start with `citation_provenance` or `am_i_cited`.** Single-engine results (`check_citations` with a pinned engine) are directional; multi-engine consensus is the honest signal. A URL cited by 4 of 5 engines is a very different finding than one cited by 1.
+
 | Tool | Purpose |
 |---|---|
-| `check_citations` | URLs cited by Perplexity / Claude / ChatGPT / Gemini / Bing / Brave / Google AI Mode for a query |
-| `am_i_cited` | Presence + rank for a domain across a query cluster |
+| `citation_provenance` | **Recommended first tool.** Fan a query across engines; per-URL cross-engine consensus matrix. Returns `interpretation_note` per engine. |
+| `am_i_cited` | Domain citation check. With `engine=auto` (default): fans across all available LLM engines, returns per-engine breakdown + cross-engine consensus. Pin `engine=` to reduce cost. |
+| `check_citations` | URLs cited by Perplexity / Claude / ChatGPT / Gemini / Google AI Mode for a query; or web rank via bing_serp / brave_serp |
 | `ai_overview` | Google AI Overview presence + cited sources |
 | `cited_for` | Queries the domain has been cited for, from local cache |
 | `predict_citation` | Citation likelihood from public signals - no LLM fired |
@@ -82,6 +85,37 @@ Cache views the client can read or subscribe to (no tool call required):
 - `citation://docs/ai-crawlers` - AI crawlers cheatsheet (markdown)
 - `citation://domain/{domain}/cited-for` - dynamic template: citations for `{domain}`
 
+## What this actually measures
+
+Every response includes a `surface` field that tells you exactly how the data was collected. Understanding this is important before drawing conclusions.
+
+| Surface | Engines | What it means |
+|---|---|---|
+| `consumer_scrape` | `perplexity`, `google_ai_mode` | Proxied through a real consumer-facing AI search product. Closest to what your users see. |
+| `api_proxy` | `claude`, `openai`, `gemini` | API call to a search-enabled LLM. **May differ from consumer product behavior** — different model versions, no UI-level ranking logic, no personalization. Use as a directional proxy, not as ground truth. |
+| `web_rank` | `bing_serp`, `brave_serp` | Traditional web search rank (not LLM citation). Measures whether a URL appears in SERP results, not whether an LLM cites it. |
+| `static_signal` | `predict_citation`, `wikipedia_mentions` | Offline signal computed from public data. No live LLM query. |
+
+### Per-engine notes
+
+**`perplexity` (consumer_scrape)** — Sonar Pro via the Perplexity API with a consumer-equivalent system prompt. Reasonably close to Perplexity.ai. Citations come from `search_results` in the response; the `citations` fallback contains URL-only entries without title.
+
+**`claude` (api_proxy)** — Claude Sonnet via the Anthropic Messages API with `web_search` tool enabled. The consumer Claude.ai product uses different routing and ranking logic. Citation behavior can differ, especially for recent/time-sensitive queries.
+
+**`openai` (api_proxy)** — `gpt-4o-search-preview` via the OpenAI Responses API. This is the model OpenAI ships to mirror SearchGPT behavior — closer to consumer than `gpt-4o-mini`, but still API-tier.
+
+**`gemini` (api_proxy)** — Gemini 2.5 Pro via the Generative Language API with `google_search` grounding. Consumer Gemini uses the same grounding index but different re-ranking. Results are directional.
+
+**`google_ai_mode` (consumer_scrape)** — Google AI Mode results via SerpAPI. Closest to what users see in Google Search. Requires `SERPAPI_KEY`.
+
+**`bing_serp` / `brave_serp` (web_rank)** — Traditional SERP rank. Does NOT measure LLM citations. Use `check_citations` with these engines to compare organic web rank against LLM citation rank. `am_i_cited` refuses these engines — it only measures LLM behavior.
+
+The proxy nature of `api_proxy` engines is a feature, not a bug: it lets you run citation checks without consuming expensive consumer-product quota. Just don't report API-proxy numbers as "ChatGPT cites you" without the caveat.
+
+Every tool response includes an `interpretation_note` field that summarizes the fidelity in one sentence. Full per-engine fidelity ratings: [docs/surface-fidelity.md](docs/surface-fidelity.md).
+
+---
+
 ## Quick start
 
 ```bash
@@ -133,12 +167,13 @@ Set only the keys you have. Any MCP client that supports stdio transport works -
 
 | Var | Purpose | Free tier? |
 |---|---|---|
-| `PERPLEXITY_API_KEY` | check_citations (Perplexity) | Yes |
-| `SERPAPI_KEY` | ai_overview | 100/month free |
-| `BING_API_KEY` | check_citations (Bing) | Yes |
-| `ANTHROPIC_API_KEY` | check_citations (Claude) | Paid only |
-| `OPENAI_API_KEY` | check_citations (ChatGPT) | Paid only |
-| `GEMINI_API_KEY` | check_citations (Gemini) | Yes |
+| `PERPLEXITY_API_KEY` | check_citations (perplexity — consumer_scrape) | Yes |
+| `SERPAPI_KEY` | ai_overview + check_citations (google_ai_mode — consumer_scrape) | 100/month free |
+| `ANTHROPIC_API_KEY` | check_citations (claude — api_proxy) | Paid only |
+| `OPENAI_API_KEY` | check_citations (openai — api_proxy) | Paid only |
+| `GEMINI_API_KEY` | check_citations (gemini — api_proxy) | Yes |
+| `BING_API_KEY` | check_citations (bing_serp — web_rank) | Yes |
+| `BRAVE_API_KEY` | check_citations (brave_serp — web_rank) | Yes (2000/month) |
 | `CITATION_CACHE_TTL_DAYS` | Cache TTL for citation_check entries (default 7) | n/a |
 | `CITATION_AI_OVERVIEW_TTL_DAYS` | Cache TTL for ai_overview entries (default 1) | n/a |
 | `CITATION_CONFIG_DIR` | Override config dir (default `~/.config/citation-intelligence`) | n/a |

package/dist/adapters/anthropic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAa3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAsDxB"}
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAa3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAwDxB"}

package/dist/adapters/anthropic.js

@@ -10,10 +10,12 @@ export async function claudeSearch(query, maxResults) {
             message: "Set ANTHROPIC_API_KEY to use the Claude engine. Get a key at https://console.anthropic.com.",
         });
     }
+    // System prompt approximates Claude.ai consumer behavior: search-first with citation list.
     const body = JSON.stringify({
-        model: "claude-sonnet-4-6",
+        model: "claude-sonnet-4-7",
         max_tokens: 1024,
-        tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
+        system: "You are a search assistant. Answer with inline citations. List each source URL you used.",
+        tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 5 }],
         messages: [{ role: "user", content: query }],
     });
     const res = await fetchJson("https://api.anthropic.com/v1/messages", {

package/dist/adapters/anthropic.js.map

@@ -1 +1 @@
-{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAc5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,mBAAmB;YAC5B,OAAO,EACL,6FAA6F;SAChG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,mBAAmB;QAC1B,UAAU,EAAE,IAAI;QAChB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACzE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC7C,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,uCAAuC,EACvC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,WAAW,EAAE,GAAG;YAChB,mBAAmB,EAAE,YAAY;YACjC,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;YACnD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,CAAC,CAAC,GAAG;oBACV,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}
+{"version":3,"file":"anthropic.js","sourceRoot":"","sources":["../../src/adapters/anthropic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAc5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACxC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,mBAAmB;YAC5B,OAAO,EACL,6FAA6F;SAChG,CAAC,CAAC;IACL,CAAC;IAED,2FAA2F;IAC3F,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,mBAAmB;QAC1B,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,0FAA0F;QAClG,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;QACzE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KAC7C,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,uCAAuC,EACvC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,WAAW,EAAE,GAAG;YAChB,mBAAmB,EAAE,YAAY;YACjC,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,KAAK,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACtC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,wBAAwB,EAAE,CAAC;YACnD,KAAK,MAAM,CAAC,IAAI,KAAK,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACpC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;oBAAE,SAAS;gBACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;gBAChB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,CAAC,CAAC,GAAG;oBACV,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/bing.js

@@ -5,7 +5,7 @@ export async function bingSearch(query, maxResults) {
     if (!key) {
         throw new ToolFetchError({
             type: "missing_key",
-            engine: "bing",
+            engine: "bing_serp",
             env_var: "BING_API_KEY",
             message: "Set BING_API_KEY to use the Bing engine. Free tier at https://www.microsoft.com/en-us/bing/apis/bing-web-search-api.",
         });

package/dist/adapters/bing.js.map

@@ -1 +1 @@
-{"version":3,"file":"bing.js","sourceRoot":"","sources":["../../src/adapters/bing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAS5D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,cAAc;YACvB,OAAO,EACL,sHAAsH;SACzH,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,8CAA8C,MAAM,CAAC,QAAQ,EAAE,EAAE,EACjE,EAAE,OAAO,EAAE,EAAE,2BAA2B,EAAE,GAAG,EAAE,EAAE,CAClD,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,SAAS;QACrB,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,IAAI;YACb,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,IAAI,EAAE;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;IAC5C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"bing.js","sourceRoot":"","sources":["../../src/adapters/bing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAS5D,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,cAAc,CAAC,CAAC;IACnC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,WAAW;YACnB,OAAO,EAAE,cAAc;YACvB,OAAO,EACL,sHAAsH;SACzH,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC5E,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,8CAA8C,MAAM,CAAC,QAAQ,EAAE,EAAE,EACjE,EAAE,OAAO,EAAE,EAAE,2BAA2B,EAAE,GAAG,EAAE,EAAE,CAClD,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QAC1C,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,SAAS;QACrB,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,IAAI;YACb,OAAO,EAAE,CAAC,CAAC,OAAO;YAClB,IAAI,EAAE,IAAI,EAAE;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;IAC5C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/adapters/brave.js

@@ -5,7 +5,7 @@ export async function braveSearch(query, maxResults) {
     if (!key) {
         throw new ToolFetchError({
             type: "missing_key",
-            engine: "brave",
+            engine: "brave_serp",
             env_var: "BRAVE_API_KEY",
             message: "Set BRAVE_API_KEY to use the Brave engine. Free tier at https://api.search.brave.com (2000 queries/month).",
         });

package/dist/adapters/brave.js.map

@@ -1 +1 @@
-{"version":3,"file":"brave.js","sourceRoot":"","sources":["../../src/adapters/brave.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAa5D,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,OAAO;YACf,OAAO,EAAE,eAAe;YACxB,OAAO,EACL,4GAA4G;SAC/G,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,kDAAkD,MAAM,CAAC,QAAQ,EAAE,EAAE,EACrE;QACE,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;YAC1B,sBAAsB,EAAE,GAAG;SAC5B;KACF,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,SAAS;QACrB,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,WAAW;YACtB,IAAI,EAAE,IAAI,EAAE;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;IAC5C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}
+{"version":3,"file":"brave.js","sourceRoot":"","sources":["../../src/adapters/brave.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAa5D,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;IACpC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,eAAe;YACxB,OAAO,EACL,4GAA4G;SAC/G,CAAC,CAAC;IACL,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC;IAC1F,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,kDAAkD,MAAM,CAAC,QAAQ,EAAE,EAAE,EACrE;QACE,OAAO,EAAE;YACP,MAAM,EAAE,kBAAkB;YAC1B,sBAAsB,EAAE,GAAG;SAC5B;KACF,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC;QACvC,IAAI,CAAC,CAAC,CAAC,GAAG;YAAE,SAAS;QACrB,SAAS,CAAC,IAAI,CAAC;YACb,GAAG,EAAE,CAAC,CAAC,GAAG;YACV,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,OAAO,EAAE,CAAC,CAAC,WAAW;YACtB,IAAI,EAAE,IAAI,EAAE;SACb,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;YAAE,MAAM;IAC5C,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,CAAC;AACvB,CAAC"}

package/dist/adapters/gemini.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAW3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CA+CxB"}
+{"version":3,"file":"gemini.d.ts","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAW3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAmDxB"}

package/dist/adapters/gemini.js

@@ -10,11 +10,15 @@ export async function geminiSearch(query, maxResults) {
             message: "Set GEMINI_API_KEY to use the Gemini engine. Get a key at https://aistudio.google.com/apikey.",
         });
     }
+    // System prompt approximates Gemini consumer app behavior: search-first with source attribution.
     const body = JSON.stringify({
+        system_instruction: {
+            parts: [{ text: "You are a search assistant. Answer with inline citations. List each source URL you used." }],
+        },
         contents: [{ parts: [{ text: query }] }],
         tools: [{ google_search: {} }],
     });
-    const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash:generateContent?key=${encodeURIComponent(key)}`;
+    const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent?key=${encodeURIComponent(key)}`;
     const res = await fetchJson(url, {
         method: "POST",
         headers: { "content-type": "application/json" },

package/dist/adapters/gemini.js.map

@@ -1 +1 @@
-{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAY5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,+FAA+F;SAClG,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACxC,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,gGAAgG,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;IAEtI,MAAM,GAAG,GAAG,MAAM,SAAS,CAAiB,GAAG,EAAE;QAC/C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI;KACL,CAAC,CAAC;IAEH,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,iBAAiB,EAAE,eAAe,IAAI,EAAE,EAAE,CAAC;YAClE,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;YACzB,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAChC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC;gBACN,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK;gBACvB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}
+{"version":3,"file":"gemini.js","sourceRoot":"","sources":["../../src/adapters/gemini.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAY5D,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,+FAA+F;SAClG,CAAC,CAAC;IACL,CAAC;IAED,iGAAiG;IACjG,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,kBAAkB,EAAE;YAClB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,0FAA0F,EAAE,CAAC;SAC9G;QACD,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QACxC,KAAK,EAAE,CAAC,EAAE,aAAa,EAAE,EAAE,EAAE,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,8FAA8F,kBAAkB,CAAC,GAAG,CAAC,EAAE,CAAC;IAEpI,MAAM,GAAG,GAAG,MAAM,SAAS,CAAiB,GAAG,EAAE;QAC/C,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI;KACL,CAAC,CAAC;IAEH,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,GAAG,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,iBAAiB,EAAE,eAAe,IAAI,EAAE,EAAE,CAAC;YAClE,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,EAAE,GAAG,CAAC;YACzB,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAChC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC;gBACN,KAAK,EAAE,KAAK,CAAC,GAAG,EAAE,KAAK;gBACvB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/openai.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAmB3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAqDxB"}
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAmB3D,wBAAsB,YAAY,CAChC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAuDxB"}

package/dist/adapters/openai.js

@@ -1,7 +1,7 @@
 import { envKey } from "../lib/config.js";
 import { fetchJson, ToolFetchError } from "../lib/fetch.js";
 import { log } from "../lib/log.js";
-const OPENAI_MODEL = "gpt-4o-mini";
+const OPENAI_MODEL = "gpt-4o-search-preview";
 export async function openaiSearch(query, maxResults) {
     const key = envKey("OPENAI_API_KEY");
     if (!key) {
@@ -13,9 +13,11 @@ export async function openaiSearch(query, maxResults) {
         });
     }
     log.debug("openai web_search", { model: OPENAI_MODEL });
+    // System prompt approximates ChatGPT consumer behavior: answer with inline citations.
     const body = JSON.stringify({
         model: OPENAI_MODEL,
         tools: [{ type: "web_search_preview" }],
+        system: "You are a search assistant. Answer with inline citations. List each source URL you used.",
         input: query,
     });
     const res = await fetchJson("https://api.openai.com/v1/responses", {

package/dist/adapters/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGpC,MAAM,YAAY,GAAG,aAAa,CAAC;AAiBnC,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,yFAAyF;SAC5F,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,YAAY;QACnB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QACvC,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,qCAAqC,EACrC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/D,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;oBAC9D,SAAS;gBACX,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/adapters/openai.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,GAAG,EAAE,MAAM,eAAe,CAAC;AAGpC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAiB7C,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;IACrC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,QAAQ;YAChB,OAAO,EAAE,gBAAgB;YACzB,OAAO,EACL,yFAAyF;SAC5F,CAAC,CAAC;IACL,CAAC;IAED,GAAG,CAAC,KAAK,CAAC,mBAAmB,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC,CAAC;IACxD,sFAAsF;IACtF,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,YAAY;QACnB,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,CAAC;QACvC,MAAM,EAAE,0FAA0F;QAClG,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,qCAAqC,EACrC;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,SAAS,GAAa,EAAE,CAAC;IAE/B,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;QACnC,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;YAClC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,IAAI,CAAC,CAAC,IAAI;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/D,KAAK,MAAM,GAAG,IAAI,CAAC,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,GAAG,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;oBAC9D,SAAS;gBACX,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBAClB,SAAS,CAAC,IAAI,CAAC;oBACb,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,KAAK,EAAE,GAAG,CAAC,KAAK;oBAChB,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;iBAC3B,CAAC,CAAC;gBACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;oBAAE,MAAM;YAC5C,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,SAAS,EAAE,CAAC;AACtE,CAAC"}

package/dist/adapters/perplexity.d.ts

@@ -1,3 +1,4 @@
 import type { AdapterResult } from "../types.js";
-export declare function perplexitySearch(query: string, maxResults: number): Promise<AdapterResult>;
+export declare const PERPLEXITY_MODEL_DEFAULT = "sonar-pro";
+export declare function perplexitySearch(query: string, maxResults: number, model?: string): Promise<AdapterResult>;
 //# sourceMappingURL=perplexity.d.ts.map

package/dist/adapters/perplexity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"perplexity.d.ts","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAU3D,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAwDxB"}
+{"version":3,"file":"perplexity.d.ts","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAY,MAAM,aAAa,CAAC;AAU3D,eAAO,MAAM,wBAAwB,cAAc,CAAC;AAEpD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,MAAM,EAClB,KAAK,GAAE,MAAiC,GACvC,OAAO,CAAC,aAAa,CAAC,CA0DxB"}

package/dist/adapters/perplexity.js

@@ -1,6 +1,7 @@
 import { envKey } from "../lib/config.js";
 import { fetchJson, ToolFetchError } from "../lib/fetch.js";
-export async function perplexitySearch(query, maxResults) {
+export const PERPLEXITY_MODEL_DEFAULT = "sonar-pro";
+export async function perplexitySearch(query, maxResults, model = PERPLEXITY_MODEL_DEFAULT) {
     const key = envKey("PERPLEXITY_API_KEY");
     if (!key) {
         throw new ToolFetchError({
@@ -10,8 +11,10 @@ export async function perplexitySearch(query, maxResults) {
             message: "Set PERPLEXITY_API_KEY to use the Perplexity engine. Sign up at https://www.perplexity.ai/settings/api",
         });
     }
+    // System prompt approximates Perplexity.ai consumer behavior: search-first with citations.
     const body = JSON.stringify({
-        model: "sonar",
+        model,
+        system: "You are a search assistant. Answer with inline citations. List each source URL you used.",
         messages: [{ role: "user", content: query }],
         return_citations: true,
     });

package/dist/adapters/perplexity.js.map

@@ -1 +1 @@
-{"version":3,"file":"perplexity.js","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAW5D,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAa,EACb,UAAkB;IAElB,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,oBAAoB;YAC7B,OAAO,EACL,wGAAwG;SAC3G,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK,EAAE,OAAO;QACd,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,4CAA4C,EAC5C;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS;YACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChB,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,UAAU,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC;YACpD,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC"}
+{"version":3,"file":"perplexity.js","sourceRoot":"","sources":["../../src/adapters/perplexity.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAW5D,MAAM,CAAC,MAAM,wBAAwB,GAAG,WAAW,CAAC;AAEpD,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAa,EACb,UAAkB,EAClB,QAAgB,wBAAwB;IAExC,MAAM,GAAG,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;IACzC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,cAAc,CAAC;YACvB,IAAI,EAAE,aAAa;YACnB,MAAM,EAAE,YAAY;YACpB,OAAO,EAAE,oBAAoB;YAC7B,OAAO,EACL,wGAAwG;SAC3G,CAAC,CAAC;IACL,CAAC;IAED,2FAA2F;IAC3F,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC;QAC1B,KAAK;QACL,MAAM,EAAE,0FAA0F;QAClG,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC5C,gBAAgB,EAAE,IAAI;KACvB,CAAC,CAAC;IAEH,MAAM,GAAG,GAAG,MAAM,SAAS,CACzB,4CAA4C,EAC5C;QACE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE;YACP,aAAa,EAAE,UAAU,GAAG,EAAE;YAC9B,cAAc,EAAE,kBAAkB;SACnC;QACD,IAAI;KACL,CACF,CAAC;IAEF,MAAM,SAAS,GAAe,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,cAAc,EAAE,CAAC;YACnC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;gBAAE,SAAS;YACxC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;YAChB,SAAS,CAAC,IAAI,CAAC;gBACb,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,KAAK,EAAE,CAAC,CAAC,KAAK;gBACd,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC;aAC3B,CAAC,CAAC;YACH,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IACD,IAAI,SAAS,CAAC,MAAM,GAAG,UAAU,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;QACnD,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,SAAS,EAAE,CAAC;YAChC,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAS;YACpC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,SAAS,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC;YACpD,IAAI,SAAS,CAAC,MAAM,IAAI,UAAU;gBAAE,MAAM;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,UAAU,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,CAAC;AACnC,CAAC"}

package/dist/index.js

@@ -26,13 +26,15 @@ import { citationEvidence, citationEvidenceInputSchema } from "./tools/citation-
 import { crawlerAccessAudit, crawlerAccessAuditInputSchema } from "./tools/crawler-access-audit.js";
 import { sitemapCitationMap, sitemapCitationMapInputSchema } from "./tools/sitemap-citation-map.js";
 import { canonicalCompetitorSet, canonicalCompetitorSetInputSchema } from "./tools/canonical-competitor-set.js";
+import { structuredDataRepair, structuredDataRepairInputSchema } from "./tools/structured-data-repair.js";
 import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
 import { ToolFetchError } from "./lib/fetch.js";
 import { log } from "./lib/log.js";
+import { checkCitationsOutputShape, amICitedOutputShape, aiOverviewOutputShape, citedForOutputShape, predictCitationOutputShape, trackQueriesOutputShape, runPanelOutputShape, citationTrendOutputShape, compareDomainsOutputShape, wikipediaMentionsOutputShape, auditSitemapOutputShape, competeForQueryOutputShape, citationFreshnessScoreOutputShape, citedForDiffOutputShape, gscCitationGapOutputShape, schemaAuditOutputShape, llmsTxtGeneratorOutputShape, answerBoxPositionOutputShape, citationProvenanceOutputShape, citationEvidenceOutputShape, crawlerAccessAuditOutputShape, sitemapCitationMapOutputShape, canonicalCompetitorSetOutputShape, structuredDataRepairOutputShape, } from "./output-schemas.js";
 const server = new McpServer({
     name: "@automatelab/citation-intelligence",
-    version: "0.6.0",
+    version: "0.7.0",
 });
 function toolError(err) {
     return {
@@ -59,101 +61,297 @@ function wrapHandler(handler) {
 server.registerTool("check_citations", {
     description: "Return URLs cited by an AI engine (Perplexity, Claude, ChatGPT, Gemini, or Bing) for a query. Use this when an agent or user wants to see what sources an AI search engine grounds answers on. Requires at least one engine API key; auto-picks the first available.",
     inputSchema: checkCitationsInputSchema,
+    outputSchema: checkCitationsOutputShape,
+    annotations: {
+        title: "Check AI engine citations",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => checkCitations(args)));
 server.registerTool("am_i_cited", {
     description: "Check whether a domain is cited by an AI engine across a cluster of queries. Returns per-query presence, rank, and a citation-rate summary. Use to measure visibility for a brand, product, or content site in AI search.",
     inputSchema: amICitedInputSchema,
+    outputSchema: amICitedOutputShape,
+    annotations: {
+        title: "Check domain citation presence",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => amICited(args)));
 server.registerTool("ai_overview", {
     description: "Check whether Google shows an AI Overview for a query, and which URLs it cites. Uses SerpAPI (free tier: 100/month). Set SERPAPI_KEY.",
     inputSchema: aiOverviewInputSchema,
+    outputSchema: aiOverviewOutputShape,
+    annotations: {
+        title: "Check Google AI Overview presence",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => aiOverview(args)));
 server.registerTool("cited_for", {
     description: "List queries that the given domain has been cited for, served from the local cache. Build up a corpus by calling check_citations or am_i_cited first; cited_for queries it without spending API budget.",
     inputSchema: citedForInputSchema,
+    outputSchema: citedForOutputShape,
+    annotations: {
+        title: "List cached queries domain was cited for",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 }, (args) => wrapHandler(() => citedFor(args)));
 server.registerTool("predict_citation", {
     description: "Score citation likelihood for a URL from public signals (Wikipedia link presence, schema.org markup, /llms.txt, GitHub and Reddit references, canonical hygiene, HTTPS). No LLM fired - all heuristic. Returns 0-100 score, grade, signal breakdown, and ranked fixes.",
     inputSchema: predictCitationInputSchema,
+    outputSchema: predictCitationOutputShape,
+    annotations: {
+        title: "Predict citation likelihood for a URL",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => predictCitation(args)));
 server.registerTool("track_queries", {
     description: "Save, load, or list named query panels. A panel is a persisted set of queries you want to monitor over time (e.g. editorial-watchlist). Use action=save with queries[] to create, action=load to read, action=list to enumerate. Panels live under <config>/panels/<name>.json.",
     inputSchema: trackQueriesInputSchema,
+    outputSchema: trackQueriesOutputShape,
+    annotations: {
+        title: "Save or load a query panel",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 }, (args) => wrapHandler(() => trackQueries(args)));
 server.registerTool("run_panel", {
     description: "Run a saved panel through am_i_cited and append a timestamped snapshot. Snapshots live under <config>/snapshots/<panel>/<iso>.json. Feeds citation_trend.",
     inputSchema: runPanelInputSchema,
+    outputSchema: runPanelOutputShape,
+    annotations: {
+        title: "Run panel and save snapshot",
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => runPanel(args)));
 server.registerTool("citation_trend", {
     description: "Report citation rate over time for a panel from stored snapshots. Returns the series of citation_rate per snapshot plus per-query deltas (gained/lost/unchanged) between first and last snapshot.",
     inputSchema: citationTrendInputSchema,
+    outputSchema: citationTrendOutputShape,
+    annotations: {
+        title: "Report citation trend over time",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 }, (args) => wrapHandler(() => citationTrend(args)));
 server.registerTool("compare_domains", {
     description: "Run predict_citation on 2-10 URLs and return a side-by-side signal table plus a list of signals where the URLs diverge. Use to compare your URL to top-cited competitors for the same query.",
     inputSchema: compareDomainsInputSchema,
+    outputSchema: compareDomainsOutputShape,
+    annotations: {
+        title: "Compare citation signals across URLs",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => compareDomains(args)));
 server.registerTool("wikipedia_mentions", {
     description: "List Wikipedia articles that reference the given domain. Wikipedia citation is the highest-lift signal for LLM training corpora. Zero keys required.",
     inputSchema: wikipediaMentionsInputSchema,
+    outputSchema: wikipediaMentionsOutputShape,
+    annotations: {
+        title: "Find Wikipedia articles citing a domain",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => wikipediaMentions(args)));
 server.registerTool("audit_sitemap", {
     description: "Fetch a sitemap.xml (or sitemap index) and run predict_citation on every URL. Returns results sorted worst-score-first. Surfaces systemic issues across a whole site in one pass. Zero engine keys needed.",
     inputSchema: auditSitemapInputSchema,
+    outputSchema: auditSitemapOutputShape,
+    annotations: {
+        title: "Audit all URLs in a sitemap",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => auditSitemap(args)));
 server.registerTool("compete_for_query", {
     description: "End-to-end competitive snapshot for a single query. Calls check_citations to get the cited URLs, then runs compare_domains on your_url vs the top cited competitors. Returns your score, the average competitor score, and the gap.",
     inputSchema: competeForQueryInputSchema,
+    outputSchema: competeForQueryOutputShape,
+    annotations: {
+        title: "Competitive citation snapshot for a query",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => competeForQuery(args)));
 server.registerTool("citation_freshness_score", {
     description: "Score how recent the pages cited for a query are. Calls check_citations, then collects dateModified for each cited URL, returns a 0-100 recency_score (halflife=365d) plus per-URL freshness bucket (fresh/current/stale/ancient/unknown). Surfaces queries where AI cites old content - opportunity to ship fresher.",
     inputSchema: citationFreshnessScoreInputSchema,
+    outputSchema: citationFreshnessScoreOutputShape,
+    annotations: {
+        title: "Score freshness of AI-cited pages",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => citationFreshnessScore(args)));
 server.registerTool("cited_for_diff", {
     description: "Diff cited_for between two time windows for a domain. Returns queries gained (cited now, not before baseline_until) and queries lost (cited before, not since current_since). Cache-only, no API spend. Use to track citation drift over time after publishing or migrating content.",
     inputSchema: citedForDiffInputSchema,
+    outputSchema: citedForDiffOutputShape,
+    annotations: {
+        title: "Diff citation changes between time windows",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 }, (args) => wrapHandler(() => citedForDiff(args)));
 server.registerTool("gsc_citation_gap", {
     description: "Join Google Search Console performance with am_i_cited per query. Surfaces queries where the domain ranks well in Google but is not cited in AI - the closest editorial wins. Requires GCP service account creds (credentials_path or GOOGLE_APPLICATION_CREDENTIALS env).",
     inputSchema: gscCitationGapInputSchema,
+    outputSchema: gscCitationGapOutputShape,
+    annotations: {
+        title: "Find GSC queries not cited by AI",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => gscCitationGap(args)));
 server.registerTool("schema_audit", {
     description: "Deep schema.org validation for a URL. Parses every JSON-LD block and microdata node, checks required fields per @type (Article needs headline+author+datePublished, FAQPage needs mainEntity, HowTo needs step, etc.), and flags missing fields and malformed JSON-LD. Returns issues list and a valid/invalid verdict. Use to fix structured-data bugs that predict_citation flags but can't explain.",
     inputSchema: schemaAuditInputSchema,
+    outputSchema: schemaAuditOutputShape,
+    annotations: {
+        title: "Audit schema.org structured data",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => schemaAudit(args)));
 server.registerTool("llms_txt_generator", {
     description: "Generate an llms.txt file (https://llmstxt.org spec) from a sitemap. Parses sitemap.xml + nested indexes, groups URLs by top-level path, and emits a Markdown document with H1+description+sectioned link lists. Set fetch_titles=true to pull <title> per URL (slower, richer output).",
     inputSchema: llmsTxtGeneratorInputSchema,
+    outputSchema: llmsTxtGeneratorOutputShape,
+    annotations: {
+        title: "Generate llms.txt from sitemap",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => llmsTxtGenerator(args)));
 server.registerTool("answer_box_position", {
     description: "Locate where each cited URL appears in the AI's raw answer text. Calls check_citations, finds the first mention of each citation's URL (or hostname) in raw_answer, and bins by char position into early/middle/late thirds. Surfaces whether your URL is cited up-front or buried near the end. Returns 'unknown' for engines without raw_answer (Bing, Brave).",
     inputSchema: answerBoxPositionInputSchema,
+    outputSchema: answerBoxPositionOutputShape,
+    annotations: {
+        title: "Locate citation positions in AI answer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => answerBoxPosition(args)));
 server.registerTool("citation_provenance", {
     description: "Fan a query out across multiple AI engines and report per-URL cross-engine consensus. Returns each unique cited URL with the list of engines that cited it, plus a consensus_urls list (URLs cited by ALL engines). High engine_count = strong cross-engine citation signal; engine_count=1 = engine-specific.",
     inputSchema: citationProvenanceInputSchema,
+    outputSchema: citationProvenanceOutputShape,
+    annotations: {
+        title: "Cross-engine citation provenance",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => citationProvenance(args)));
 server.registerTool("citation_evidence", {
     description: "Extract the cited snippet from the AI engine's raw answer for each citation. Calls check_citations, then for each returned URL finds the first mention in raw_answer and returns a context window plus the nearest quoted span or containing sentence. Use to see *why* an engine cited a URL, not just *that* it did. Returns 'not found' for engines without raw_answer (Bing, Brave).",
     inputSchema: citationEvidenceInputSchema,
+    outputSchema: citationEvidenceOutputShape,
+    annotations: {
+        title: "Extract citation evidence from AI answer",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => citationEvidence(args)));
 server.registerTool("crawler_access_audit", {
     description: "Verify that major AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, CCBot, Google-Extended, Applebot-Extended, Bytespider, Meta-ExternalAgent, plus real-time fetch UAs) can fetch a URL. Parses robots.txt and does a live GET with each bot's User-Agent. Surfaces robots.txt blocks AND UA-based gating that breaks AI citation.",
     inputSchema: crawlerAccessAuditInputSchema,
+    outputSchema: crawlerAccessAuditOutputShape,
+    annotations: {
+        title: "Audit AI crawler access to a URL",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => crawlerAccessAudit(args)));
 server.registerTool("sitemap_citation_map", {
     description: "Cross-reference a sitemap with the citation cache. For each sitemap URL, reports whether it appears in cached citations (and how many queries/engines cited it). Inverse of audit_sitemap: not 'how citable is each URL', but 'has each URL actually been cited yet'. Cache must be primed via check_citations or run_panel first.",
     inputSchema: sitemapCitationMapInputSchema,
+    outputSchema: sitemapCitationMapOutputShape,
+    annotations: {
+        title: "Map sitemap URLs against citation cache",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
 }, (args) => wrapHandler(() => sitemapCitationMap(args)));
 server.registerTool("canonical_competitor_set", {
     description: "Fan a query across engines and aggregate citations by registered domain (not URL). Returns top competitor domains ranked by cross-engine consensus, with per-engine breakdown and top URLs per domain. Use to identify the canonical competitor set for a query - the domains every engine treats as authoritative.",
     inputSchema: canonicalCompetitorSetInputSchema,
+    outputSchema: canonicalCompetitorSetOutputShape,
+    annotations: {
+        title: "Identify canonical competitor domains for a query",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
 }, (args) => wrapHandler(() => canonicalCompetitorSet(args)));
+server.registerTool("structured_data_repair", {
+    description: "Suggest missing JSON-LD additions for a URL. Fetches the page, detects existing schema types, and returns ready-to-paste templates for types that are missing but signalled by page content (BlogPosting from og:type=article or bylines, FAQPage from Q&A pairs, HowTo from numbered steps, BreadcrumbList from nested paths, Organization on homepages). Templates are pre-filled from page metadata where possible; fields marked FILL: require manual completion.",
+    inputSchema: structuredDataRepairInputSchema,
+    outputSchema: structuredDataRepairOutputShape,
+    annotations: {
+        title: "Suggest missing JSON-LD for a URL",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true,
+    },
+}, (args) => wrapHandler(() => structuredDataRepair(args)));
 registerPrompts(server);
 registerResources(server);
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log.info("server ready on stdio", {
-    version: "0.6.0",
+    version: "0.7.0",
     log_level: log.level(),
     tools: [
         "check_citations",
@@ -179,6 +377,7 @@ log.info("server ready on stdio", {
         "crawler_access_audit",
         "sitemap_citation_map",
         "canonical_competitor_set",
+        "structured_data_repair",
     ],
     prompts: [
         "audit_citation_readiness",