@spendgraph/tools 0.7.0 → 0.8.1

package/dist/search/search.d.ts

@@ -14,6 +14,10 @@ export interface SearchUsage {
     reasoningTokens: number;
     searchQueries: number;
 }
+export interface SearchFailure {
+    source: string;
+    reason: string;
+}
 /** What every searcher hands back, whoever did the searching. */
 export interface Searched {
     answer: string;
@@ -21,6 +25,7 @@ export interface Searched {
     model: string;
     truncated: boolean;
     usage: SearchUsage;
+    failed?: SearchFailure[];
 }
 export interface SearchAsk {
     query: string;
@@ -29,6 +34,7 @@ export interface SearchAsk {
 }
 export type Searcher = ((ask: SearchAsk) => Promise<Searched>) & {
     domains?: readonly string[];
+    source?: string;
 };
 /** What every searcher is configured with; each adds only where its answers come from. */
 export interface SearcherOptions {

package/dist/search/searxng/searxng.js

@@ -1,5 +1,5 @@
-import{checkUrl as S}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as x}from"../search.js";import{textOf as A}from"./text.js";const T="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
+import{checkUrl as x}from"../../builtin/http/allow.js";import{retrying as y}from"../retry.js";import{DEFAULT_MAX_CHARS as N,DEFAULT_MAX_RESULTS as F,NO_TOKENS as A}from"../search.js";import{textOf as T}from"./text.js";const f="searxng",U=["*"],G=2e4,X=6e3,L=4e5,H={quick:5,pro:8,deep:10},I=/https?:\/\/[^\s"'<>)\]]+/,Q=2;function W(t){return!t.url||!t.title?null:{url:t.url,title:t.title,...t.publishedDate?{date:t.publishedDate}:{},snippet:t.content??""}}function q({url:t,title:r,date:i}){return{url:t,title:r,...i?{date:i}:{}}}function K(t,r){return`## ${t.title}
 ${t.url}
-${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,f=t.pageChars??X,b={...H,...t.pages},O=y(t);async function d(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>d(a,s)))]}async function p(n){const s=AbortSignal.timeout(u);let e=S(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=S(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await p(n.url);if(!s.ok)return n.snippet;const e=A((await s.text()).slice(0,L));return e?e.slice(0,f):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await p(n);return s.ok&&A((await s.text()).slice(0,L)).slice(0,f)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:T,truncated:s.length>g,usage:{...x,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await d(n,e),l=s==="deep"?await P(o,e):[o],w=z(l),m=w.slice(0,h),_=m.slice(0,b[s]),k=await Promise.all(_.map(M)),E=_.map(($,j)=>K($,k[j])).join(`
+${r}`}const Y=3,v=t=>t.status>=300&&t.status<400;function R(t,r){if(!r?.length)return!0;const i=new URL(t.url).hostname.toLowerCase();return r.some(u=>{const h=u.toLowerCase().replace(/^\./,"");return i===h||i.endsWith(`.${h}`)})}function z(t){const r=new Set;return t.flatMap(i=>i.hits).filter(i=>!r.has(i.url)&&r.add(i.url))}function tt(t){if(!t.baseUrl?.trim())throw new Error("searxng needs the baseUrl of a SearXNG instance, such as http://localhost:8080.");const r=t.fetch??globalThis.fetch.bind(globalThis),i=t.baseUrl.replace(/\/+$/,""),u=t.timeoutMs??G,h=Math.max(1,t.maxResults??F),g=t.maxChars??N,d=t.pageChars??X,b={...H,...t.pages},O=y(t);async function p(n,s){const e=new URL(`${i}/search`);e.searchParams.set("q",n),e.searchParams.set("format","json"),s&&e.searchParams.set("time_range",s),t.language&&e.searchParams.set("language",t.language),t.engines?.length&&e.searchParams.set("engines",t.engines.join(","));const a=await O(()=>r(e,{signal:AbortSignal.timeout(u),headers:{accept:"application/json"}}));if(!a.ok){const o=a.status===403?" SearXNG refuses the json format unless settings.yml lists it under search.formats and the limiter is off.":"";throw new Error(`SearXNG returned ${a.status}.${o}`)}const c=await a.json();return{hits:(c.results??[]).flatMap(o=>{const l=W(o);return l&&R(l,t.domains)?[l]:[]}),suggestions:c.suggestions??[]}}async function P(n,s){const e=n.suggestions.slice(0,Q);return[n,...await Promise.all(e.map(a=>p(a,s)))]}async function w(n){const s=AbortSignal.timeout(u);let e=x(n,U),a=await r(e,{signal:s,redirect:"manual"});for(let c=0;c<Y&&v(a);c++){const o=a.headers.get("location");if(!o)break;e=x(new URL(o,a.url||e).toString(),U),a=await r(e,{signal:s,redirect:"manual"})}return a}async function M(n){try{const s=await w(n.url);if(!s.ok)return n.snippet;const e=T((await s.text()).slice(0,L));return e?e.slice(0,d):n.snippet}catch{return n.snippet}}async function D(n){if(!R({url:n,snippet:""},t.domains))return null;try{const s=await w(n);return s.ok&&T((await s.text()).slice(0,L)).slice(0,d)||null}catch{return null}}const C=(n,s)=>({answer:s.slice(0,g),results:[{url:n}],model:f,truncated:s.length>g,usage:{...A,searchQueries:0}});return Object.assign(async({query:n,depth:s,recency:e})=>{const a=n.match(I)?.[0],c=a?await D(a):null;if(a&&c)return C(a,c);const o=await p(n,e),l=s==="deep"?await P(o,e):[o],_=z(l),m=_.slice(0,h),E=m.slice(0,b[s]),k=await Promise.all(E.map(M)),S=E.map(($,j)=>K($,k[j])).join(`
 
-`);return{answer:E.slice(0,g),results:m.map(q),model:T,truncated:E.length>g||w.length>m.length,usage:{...x,searchQueries:l.length}}},t.domains?.length?{domains:[...t.domains]}:{})}export{tt as searxng};
+`);return{answer:S.slice(0,g),results:m.map(q),model:f,truncated:S.length>g||_.length>m.length,usage:{...A,searchQueries:l.length}}},{source:f,...t.domains?.length?{domains:[...t.domains]}:{}})}export{tt as searxng};

package/dist/search/sonar/sonar.js

@@ -1 +1 @@
-import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="https://api.perplexity.ai/chat/completions",p=6e4,T=3e5,u=500;function A(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),a=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:p),t=await a(()=>i(f,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,u);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},e.domains?.length?{domains:[...e.domains]}:{})}export{A as sonar};
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as d,DEFAULT_MAX_RESULTS as h}from"../search.js";import{readReply as _}from"./reply.js";const E={quick:"sonar",pro:"sonar-pro",deep:"sonar-deep-research"},f="sonar",p="https://api.perplexity.ai/chat/completions",u=6e4,T=3e5,y=500;function O(e){if(!e.apiKey?.trim())throw new Error("sonar needs a Perplexity apiKey; it will not read one from the process.");const a=e.fetch??globalThis.fetch.bind(globalThis),i=m(e);return Object.assign(async({query:s,depth:o,recency:n})=>{const r=E[o],c=e.timeoutMs??(o==="deep"?T:u),t=await i(()=>a(p,{method:"POST",signal:AbortSignal.timeout(c),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({model:r,messages:[{role:"user",content:s}],...n?{search_recency_filter:n}:{},...e.domains?.length?{search_domain_filter:e.domains}:{}})}));if(!t.ok){const l=(await t.text()).slice(0,y);throw new Error(`Perplexity returned ${t.status} for ${r}: ${l}`)}return _(await t.json(),r,e.maxChars??d,e.maxResults??h)},{source:f,...e.domains?.length?{domains:[...e.domains]}:{}})}export{O as sonar};

package/dist/search/tavily/tavily.js

@@ -1 +1 @@
-import{retrying as l}from"../retry.js";import{DEFAULT_MAX_CHARS as m,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const u="https://api.tavily.com/search",y="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const i=e.fetch??globalThis.fetch.bind(globalThis),r=l(e);return Object.assign(async({query:s,depth:o,recency:t})=>{const{search_depth:c,pages:d}=T[o],a=await r(()=>i(u,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:s,search_depth:c,include_answer:!0,include_raw_content:!0,max_results:Math.min(d,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const h=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${h}`)}return _(await a.json(),y,e.maxChars??m,e.maxResults??n)},e.domains?.length?{domains:[...e.domains]}:{})}export{S as tavily};
+import{retrying as m}from"../retry.js";import{DEFAULT_MAX_CHARS as u,DEFAULT_MAX_RESULTS as n}from"../search.js";import{readReply as _}from"./reply.js";const y="https://api.tavily.com/search",i="tavily-search",g=6e4,p=500,T={quick:{search_depth:"basic",pages:3},pro:{search_depth:"advanced",pages:5},deep:{search_depth:"advanced",pages:10}},E={day:1,week:7,month:30,year:365};function S(e){if(!e.apiKey?.trim())throw new Error("tavily needs an apiKey; it will not read one from the process.");const r=e.fetch??globalThis.fetch.bind(globalThis),s=m(e);return Object.assign(async({query:o,depth:c,recency:t})=>{const{search_depth:d,pages:h}=T[c],a=await s(()=>r(y,{method:"POST",signal:AbortSignal.timeout(e.timeoutMs??g),headers:{authorization:`Bearer ${e.apiKey}`,"content-type":"application/json"},body:JSON.stringify({query:o,search_depth:d,include_answer:!0,include_raw_content:!0,max_results:Math.min(h,e.maxResults??n),...t?{days:E[t]}:{},...e.domains?.length?{include_domains:e.domains}:{}})}));if(!a.ok){const l=(await a.text()).slice(0,p);throw new Error(`Tavily returned ${a.status}: ${l}`)}return _(await a.json(),i,e.maxChars??u,e.maxResults??n)},{source:i,...e.domains?.length?{domains:[...e.domains]}:{}})}export{S as tavily};

package/dist/tool/tool.d.ts

@@ -9,6 +9,10 @@ export interface ToolSpec<T extends readonly ArgSpec[]> {
     trust?: Trust;
     costOf?(value: unknown): number | undefined;
     needs?: readonly string[];
+    wants?: {
+        name: string;
+        description: string;
+    };
     run(args: ArgsOf<T>): Promise<unknown> | unknown;
 }
 /**

package/dist/tool/tool.js

@@ -1 +1 @@
-const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"],a=["own","external"];function s(n,t){if(!t.options?.length)throw new Error(`Tool "${n}" argument "${t.name}" is an enum with no options, so nothing can satisfy it.`);const e=new Set;for(const o of t.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${t.name}" has a blank option, which the model can pick and you cannot act on.`);if(e.has(o))throw new Error(`Tool "${n}" argument "${t.name}" lists "${o}" twice.`);e.add(o)}}function f(n,t){if(t){for(const e of t)if(!e.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function h(n,t){const e=new Set;for(const o of t){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(e.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);e.add(o.name),o.type==="enum"&&s(n,o)}}function d(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(h(n.name,n.args),f(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);if(n.trust!==void 0&&!a.includes(n.trust))throw new Error(`Tool "${n.name}" declares trust "${n.trust}", which is not one of ${a.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(t=>({...t,options:t.options?[...t.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},...n.trust?{trust:n.trust}:{},...n.costOf?{costOf:n.costOf}:{},...n.needs?.length?{needs:[...n.needs]}:{},run:n.run}}export{d as tool};
+const r=/^[A-Za-z_][A-Za-z0-9_]*$/,i=["readonly","idempotent","destructive"],a=["own","external"];function s(n,t){if(!t.options?.length)throw new Error(`Tool "${n}" argument "${t.name}" is an enum with no options, so nothing can satisfy it.`);const e=new Set;for(const o of t.options){if(!o.trim())throw new Error(`Tool "${n}" argument "${t.name}" has a blank option, which the model can pick and you cannot act on.`);if(e.has(o))throw new Error(`Tool "${n}" argument "${t.name}" lists "${o}" twice.`);e.add(o)}}function f(n,t){if(t){for(const e of t)if(!e.trim())throw new Error(`Tool "${n}" has a blank alias, which matches every query or none.`)}}function h(n,t){const e=new Set;for(const o of t){if(!r.test(o.name))throw new Error(`Tool "${n}" argument "${o.name}" is not a usable name.`);if(e.has(o.name))throw new Error(`Tool "${n}" declares "${o.name}" twice.`);e.add(o.name),o.type==="enum"&&s(n,o)}}function d(n){if(!r.test(n.name))throw new Error(`Tool name "${n.name}" must be letters, digits and underscores, starting with a letter.`);if(!n.description.trim())throw new Error(`Tool "${n.name}" has no description. It is the only thing the model reads to decide whether to call it.`);if(h(n.name,n.args),f(n.name,n.aliases),n.effect!==void 0&&!i.includes(n.effect))throw new Error(`Tool "${n.name}" declares effect "${n.effect}", which is not one of ${i.join(", ")}.`);if(n.trust!==void 0&&!a.includes(n.trust))throw new Error(`Tool "${n.name}" declares trust "${n.trust}", which is not one of ${a.join(", ")}.`);return{name:n.name,description:n.description,args:n.args.map(t=>({...t,options:t.options?[...t.options]:void 0})),...n.aliases?.length?{aliases:[...n.aliases]}:{},pinned:n.pinned,...n.effect?{effect:n.effect}:{},...n.trust?{trust:n.trust}:{},...n.costOf?{costOf:n.costOf}:{},...n.needs?.length?{needs:[...n.needs]}:{},...n.wants?{wants:{...n.wants}}:{},run:n.run}}export{d as tool};

package/dist/types/tool.d.ts

@@ -106,6 +106,19 @@ export interface Tool<Args = Record<string, unknown>> {
      * where the words a caller actually types are declared.
      */
     aliases?: string[];
+    /**
+     * A second, differently-shaped input the tool would rather be given, named.
+     *
+     * A stage hands every tool the one question it wrote. That suits a search
+     * engine and defeats a catalogue that matches on a title: measured against
+     * OpenAlex, a 280-character sub-question found nothing where the same ask as
+     * an 80-character phrase found ten papers. Declaring it here is what lets the
+     * stage be told to write one, without the stored wording naming any tool.
+     */
+    wants?: {
+        name: string;
+        description: string;
+    };
     /**
      * Offered whatever selection decides — an escalation path, a refusal, where
      * losing a similarity search is not an acceptable outcome.

package/docs/bogus.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Bogus tools — spendgraph docs",
+  title: "Bogus tools: spendgraph docs",
   description:
     "Twelve tools that answer the same way every time, built so the answer cannot be known without calling. Nothing reaches the network, so the noise in a run is the model's own.",
 };
@@ -22,13 +22,13 @@ Its own subpath, so nothing here reaches a production bundle by accident.
 
 ## For testing a pipeline, not a provider
 
-Nothing here touches the network. No key, no rate limit, no flake, no bill — so whatever noise a run shows is the **model's own**, not the weather between you and a provider. Run the same question a hundred times and the tools are the one thing that did not move.
+Nothing here touches the network. No key, no rate limit, no flake, no bill, so whatever noise a run shows is the **model's own**, not the weather between you and a provider. Run the same question a hundred times and the tools are the one thing that did not move.
 
 ## Every answer is unknowable without the call
 
 This is the part that makes them worth more than stubs. The Bogus League's clubs exist nowhere else. The dictionary's definitions are its own. The gold rate is not the market rate, and the prayer times match no published table. Each description says so.
 
-A model that answers from memory is therefore **caught**, not merely unhelpful — there is no training data to be accidentally right from.
+A model that answers from memory is therefore **caught**, not merely unhelpful: there is no training data to be accidentally right from.
 
 ## The receipt
 
@@ -44,13 +44,13 @@ import { receipt } from "@spendgraph/tools/bogus";
 receipt("my_notes", "wifi");   // "bogus-my_notes-9e01b3"
 ```
 
-Grep an answer for `bogus-` and you know which tools actually reached it. The model cannot invent a receipt it never saw, so provenance is **observed rather than claimed** — which is a different and stronger thing than reading the step log, since the log records what your code ran and the receipt records what the answer was actually built from.
+Grep an answer for `bogus-` and you know which tools actually reached it. The model cannot invent a receipt it never saw, so provenance is **observed rather than claimed**, which is a different and stronger thing than reading the step log, since the log records what your code ran and the receipt records what the answer was actually built from.
 
 ## The twelve
 
 | | | |
 | --- | --- | --- |
-| `my_notes` | the user's own notes — passwords, plans, things written down | `readonly` |
+| `my_notes` | the user's own notes: passwords, plans, things written down | `readonly` |
 | `my_calendar` | what is on for a given day | `readonly` |
 | `my_recipes` | only what they saved themselves, not a cookbook | `readonly` |
 | `dictionary` | definitions that are its own and not the ones in general use | `readonly` |
@@ -64,12 +64,12 @@ Grep an answer for `bogus-` and you know which tools actually reached it. The mo
 | `ask_mum` | always answers, rarely the question asked, forty-one minutes | `destructive` |
 
 <Callout tone="trap" title="They are fixtures, not fakes of anything real">
-  Every answer is unknowable without the call — that is what makes them useful for testing a loop and useless for testing a provider. Ship one by accident and the model will happily tell a customer what the gold price is.
+  Every answer is unknowable without the call: that is what makes them useful for testing a loop and useless for testing a provider. Ship one by accident and the model will happily tell a customer what the gold price is.
 </Callout>
 
 ## All three effects, on purpose
 
-Eight `readonly`, one `idempotent`, three `destructive`. That spread is why this is the fixture for a gate: you can assert a policy refuses `order_pizza`, retries `feed_cat`, and waves `my_notes` through — without a bus that can spend real money.
+Eight `readonly`, one `idempotent`, three `destructive`. That spread is why this is the fixture for a gate: you can assert a policy refuses `order_pizza`, retries `feed_cat`, and waves `my_notes` through, without a bus that can spend real money.
 
 ```ts
 const bus = toolbus(bogusTools());
@@ -82,4 +82,4 @@ bus.unannotated();     // []
 
 ## What they are not
 
-They are not a benchmark. A model doing well on the Bogus League says it can follow a description and call a tool, not that it is good — the questions were written to be answerable only one way. Use them to prove the wiring, then measure quality on real work.
+They are not a benchmark. A model doing well on the Bogus League says it can follow a description and call a tool, not that it is good: the questions were written to be answerable only one way. Use them to prove the wiring, then measure quality on real work.

package/docs/builtins.mdx

@@ -1,12 +1,12 @@
 export const meta = {
-  title: "Builtins — spendgraph docs",
+  title: "Builtins: spendgraph docs",
   description:
-    "Twenty-one factories, none registered for you — this package's own advice is that more tools makes a model worse at picking, so they are opt-in one at a time.",
+    "Twenty-one factories, none registered for you: this package's own advice is that more tools makes a model worse at picking, so they are opt-in one at a time.",
 };
 
 # Builtins
 
-Twenty-one, each a factory, **none registered for you** — this package's own advice is that more tools in front of a model makes it worse at picking, so they are opt-in one at a time. Six need a key, one needs a sandbox; the rest are local code.
+Twenty-one, each a factory, **none registered for you**: this package's own advice is that more tools in front of a model makes it worse at picking, so they are opt-in one at a time. Six need a key, one needs a sandbox; the rest are local code.
 
 ```ts
 import { calculate, currentTime, escalate, finish, think, httpRequest } from "@spendgraph/tools";
@@ -34,13 +34,12 @@ const bus = toolbus([
 | `dates()` | the same, asked in words, for a caller that can only send a question | local |
 | `jsonQuery()` | one value out of a JSON document, by path | local |
 | `httpRequest()` | a GET or POST to hosts you named | local |
-| `extract()` | the text of a file at a URL — pdf, docx, a page, md, txt | local |
+| `extract()` | the text of a file at a URL: pdf, docx, a page, md, txt | local |
 | `codeExec()` | a short program, run wherever you say | sandbox |
-| `writeDocument()` | a document agent that returns a rendered file | key |
 | `publish()` | content out as a file at a public URL, through the app | key |
 | `webSearch()` | a searched answer with its sources, from a searcher you pick | local or key |
 | `wikidata()` | what Wikidata records about a thing, as text with every id named | local |
-| `openalex()` | papers on a topic, as text with a DOI and a PDF where one is open | local |
+| `paperSearch()` | published papers on a topic, as text with a DOI and a PDF where one is open, from a paper searcher you pick | local or key |
 | `recall()` | what your memory holds about something, one note per row | key |
 | `deepRecall()` | the same, walked across linked notes, with the evidence | key |
 | `remember()` | one thing filed under a `type:name` context | key |
@@ -95,12 +94,12 @@ const bus = toolbus(memories({ client: store }).tools);
 ```
 
 <Callout tone="trap" title="None of them are registered for you">
-  Importing a builtin does nothing until it is in a bus. That is deliberate — a package that silently added `http_request` to every agent would be a package that widened your blast radius on `npm update` — but it does mean a tool you "added" and never see called is usually a tool you never put in the bus.
+  Importing a builtin does nothing until it is in a bus. That is deliberate, a package that silently added `http_request` to every agent would be a package that widened your blast radius on `npm update`, but it does mean a tool you "added" and never see called is usually a tool you never put in the bus.
 </Callout>
 
 ## A few worth reading about
 
-**`calculate`** parses the expression — numbers, `+ - * / % ^`, brackets, and `sqrt abs round floor ceil ln log` — and refuses everything else. `eval` on model output is arbitrary code execution with extra steps.
+**`calculate`** parses the expression, numbers, `+ - * / % ^`, brackets, and `sqrt abs round floor ceil ln log`, and refuses everything else. `eval` on model output is arbitrary code execution with extra steps.
 
 It answers with the digits a double actually carries, so `0.1 + 0.2` is `0.3` and not `0.30000000000000004`. A whole number past 2^53 is refused rather than silently rounded, because the answer would then be confidently wrong about a figure the model can see in its own request.
 
@@ -108,13 +107,13 @@ It answers with the digits a double actually carries, so `0.1 + 0.2` is `0.3` an
 
 **`finish`** gives a loop a real stop condition. Without it a run ends when the model goes quiet, which is indistinguishable from it losing the thread. Read the result with `isFinished(result)` and `answerOf(result)`.
 
-**`decline`** is the other real ending, and the one usually left to prose. A model that cannot answer will otherwise write an apology, which reads as an answer to everything downstream — it is scored, it is stored, and the rate of it is invisible. The tool takes a fixed `because` — `unknowable`, `not_covered`, `out_of_scope`, `unsafe` — so the rate of each is countable, and the two commonest want opposite fixes: one is the world, the other is your records. `isDeclined(result)` and `declinedFor(result)` read it back, and a loop that ends this way reports `stoppedBy: "declined"` with `declinedBecause` beside it.
+**`decline`** is the other real ending, and the one usually left to prose. A model that cannot answer will otherwise write an apology, which reads as an answer to everything downstream, it is scored, it is stored, and the rate of it is invisible. The tool takes a fixed `because`, `unknowable`, `not_covered`, `out_of_scope`, `unsafe`, so the rate of each is countable, and the two commonest want opposite fixes: one is the world, the other is your records. `isDeclined(result)` and `declinedFor(result)` read it back, and a loop that ends this way reports `stoppedBy: "declined"` with `declinedBecause` beside it.
 
 **`current_time`** is the clock a model does not have. Asked for today's date it will otherwise produce its training cutoff, confidently. A wrong IANA zone throws rather than falling back, because a confidently wrong time is the failure this exists to stop.
 
-**`dateMath`** is what `current_time` leads to. Calendar months clamp rather than overflow — a month after 31 January is 28 February, not 3 March, which is what `setMonth` gives and what every billing system disagrees with. `difference` counts boundaries crossed rather than dividing elapsed milliseconds, because a month is not 30 days. `dates()` is the same tool taking one `question` in one of three forms — `days from 2026-03-01 to 2026-09-09`, `30 days after 2026-03-01`, `2 months before 2026-03-01` — for a pipeline that hands every tool a question and nothing else.
+**`dateMath`** is what `current_time` leads to. Calendar months clamp rather than overflow, a month after 31 January is 28 February, not 3 March, which is what `setMonth` gives and what every billing system disagrees with. `difference` counts boundaries crossed rather than dividing elapsed milliseconds, because a month is not 30 days. `dates()` is the same tool taking one `question` in one of three forms, `days from 2026-03-01 to 2026-09-09`, `30 days after 2026-03-01`, `2 months before 2026-03-01`, for a pipeline that hands every tool a question and nothing else.
 
-**`jsonQuery`** reads one value by path — `invoices[0].total`, or `invoices[*].total` for every element. A path that matches nothing comes back `found: false` rather than `null`, which a model would otherwise read as the answer.
+**`jsonQuery`** reads one value by path: `invoices[0].total`, or `invoices[*].total` for every element. A path that matches nothing comes back `found: false` rather than `null`, which a model would otherwise read as the answer.
 
 **`webSearch`** takes a searcher, and ships two. `sonar` is Perplexity, which searches, reads and writes the answer itself, for a key. `searxng` is a [SearXNG](https://docs.searxng.org) you run, which costs nothing and needs no key: it searches, then reads the first hits as text, five on `quick`, eight on `pro`, ten on `deep`. Handed a query that names a link, it reads that page instead.
 
@@ -126,9 +125,68 @@ webSearch({ search: sonar({ apiKey, domains: ["gov.uk"] }), maxDepth: "pro" });
 webSearch({ search: searxng({ baseUrl: "http://localhost:8080", language: "en" }), maxDepth: "deep" });
 ```
 
-Both hand back the same shape — `answer`, `results`, `model`, `truncated`, `usage` — so whatever reads one reads the other; only where the answer came from and what it cost differ. The model chooses `query`, `depth` and `recency`; `domains`, engines and language are pinned on the searcher, so it cannot widen them. Pages the SearXNG searcher reads go through the same guard as `httpRequest`, so a private address is refused even when an engine offered it. A stock SearXNG answers the json format with a 403 until `settings.yml` lists it under `search.formats` and the limiter is off, and the error says so. `examples/search` runs both searchers directly.
+Both hand back the same shape, `answer`, `results`, `model`, `truncated`, `usage`, so whatever reads one reads the other; only where the answer came from and what it cost differ. `everySearch([sonar, tavily, searxng])` is that shape used on itself: one searcher over several, asked at the same time. The model chooses `query`, `depth` and `recency`; `domains`, engines and language are pinned on the searcher, so it cannot widen them. Pages the SearXNG searcher reads go through the same guard as `httpRequest`, so a private address is refused even when an engine offered it. A stock SearXNG answers the json format with a 403 until `settings.yml` lists it under `search.formats` and the limiter is off, and the error says so. `examples/search` runs both searchers directly.
 
-**`codeExec`** runs a short program and hands back what it printed — for work an arithmetic expression cannot state: sorting, filtering, joining, parsing. It takes a **required** `sandbox` and has no default, because a default would mean running model-written code in the process that called it. That is what `calculate` exists to avoid, and shipping one here would undo it.
+**`paperSearch`** is `webSearch` for the literature, and ships three searchers. `openAlexPapers` is [OpenAlex](https://openalex.org), free and keyless. `semanticScholar` is the [Semantic Scholar](https://www.semanticscholar.org/product/api) graph, and carries the `tldr` as each paper's takeaway. `consensus` is [Consensus](https://consensus.app), which needs a key and is the only one that says how a study was run, `rct`, `meta-analysis`, with its sample size and a one-line finding.
+
+Keys, and what each is worth:
+
+| | |
+| --- | --- |
+| `openAlexPapers` | optional, free, from [OpenAlex authentication](https://help.openalex.org/api/authentication/): sent as a bearer token, never in the url. Basic use is keyless; a key is ten times the daily budget, and heavier use is pay as you go |
+| `semanticScholar` | optional, free, from [the API key form](https://www.semanticscholar.org/product/api#api-key-form): emailed after review, so not the same day. Keyless is 1000 req/s *shared with every unauthenticated caller on the internet*, which in practice means routine 429s; a key is 1 req/s that is yours |
+| `consensus` | required, from a [Consensus](https://consensus.app) account |
+
+A 429 from the keyless Semantic Scholar pool is not a failure to design around: under `everyPaper` it is one source that did not answer while the others did.
+
+**What a search cost** rides back with it. OpenAlex prices every call in its own envelope, `meta.cost_usd`, and that becomes `costMicroUsd` on the `PapersFound`, in micro-USD like every other price here. A source that does not price its own calls takes `costMicroUsd` as an option instead, which is what your plan charges per search:
+
+```ts
+everyPaper([openAlexPapers({ apiKey }), consensus({ apiKey, costMicroUsd: 2500 })]);
+```
+
+`everyPaper` sums what the sources that answered reported, and bills nothing for one that failed. `paper_search` declares `costOf`, so the number lands on the result as `costMicros` and `spentOn([...results])` adds a run up. Only sources that said are counted: a search with no price is unmeasured, not free, and those are different claims.
+
+The tool returns `{ answer, results, costMicroUsd }` rather than a bare string. The model still reads only `answer`, `render()` has always unwrapped that shape, while `results` become the result's `sources`, one per paper, preferring an open PDF, then the source's own page, then `https://doi.org/…`.
+
+```ts
+import { paperSearch } from "@spendgraph/tools";
+import { consensus, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
+
+paperSearch({ papers: openAlexPapers({ apiKey }) });
+paperSearch({ papers: semanticScholar({ apiKey, fieldsOfStudy: ["Medicine"] }), maxResults: 5 });
+paperSearch({ papers: consensus({ apiKey, studyTypes: ["rct"], excludePreprints: true }) });
+```
+
+All three hand back the same `Paper`, title, year, authors, venue, citations, DOI, an open PDF, a study type and sample size where the source knows them, a takeaway, and the abstract, so whatever reads one reads the others. The model chooses `query`, `year_min`, `year_max`, `min_citations` and `open_access`; the study filters, fields of study and journals are pinned on the searcher, so it cannot widen them. `openalex()` is the preset for the keyless case, and is `paperSearch({ papers: openAlexPapers(opts) })` with nothing added.
+
+**Two or three sources at once** is `everySearch` in `@spendgraph/tools/search` and `everyPaper` in `@spendgraph/tools/papers`. Each takes a list, returns one searcher of the same type, and asks all of them at the same time.
+
+```ts
+import { paperSearch, webSearch } from "@spendgraph/tools";
+import { consensus, everyPaper, openAlexPapers, semanticScholar } from "@spendgraph/tools/papers";
+import { everySearch, searxng, sonar } from "@spendgraph/tools/search";
+
+paperSearch({ papers: everyPaper([consensus({ apiKey }), semanticScholar(), openAlexPapers()]) });
+webSearch({ search: everySearch([sonar({ apiKey }), searxng({ baseUrl })]) });
+```
+
+One tool, not three. `busgroup` is the other way to hold several providers, a bus each, `namespace: true`, and the model sees `consensus__paper_search` beside `s2__paper_search`, and it is the right shape when the buses do *different* things, because a name there has to say which one runs. These do the same thing: same ask in, same shape out. Interchangeable by construction is a fan-out, not a routing decision the model has any basis to make, and three namespaced copies spend three shortlist slots on one capability.
+
+What the merge does with what comes back:
+
+| | |
+| --- | --- |
+| order | round-robin: first from each source, then second from each, so no one corpus owns the top |
+| the same paper twice | folded on DOI, else on the title with punctuation and case removed |
+| a fold | fills gaps rather than dropping one: Consensus' `studyType` survives alongside Semantic Scholar's abstract, and the higher citation count wins |
+| a source that fails | named in `failed`, and the rest still answer; `paper_search` prints `openalex did not answer: …` under the list |
+| every source failing | the call fails, quoting what each one said |
+| the bill | three providers per call, not one, a fan-out costs what its parts cost |
+
+`everySearch` puts each answer under `# via <model>` so a quote stays attributable: `via` because a page's own text routinely carries an `#` heading of its own, and the marker has to be the one line that cannot be mistaken for content, unions the links, and sums all five token lines. It keeps `domains` only when *every* searcher is pinned, since one unpinned searcher means the answer is no longer restricted.
+
+**`codeExec`** runs a short program and hands back what it printed, for work an arithmetic expression cannot state: sorting, filtering, joining, parsing. It takes a **required** `sandbox` and has no default, because a default would mean running model-written code in the process that called it. That is what `calculate` exists to avoid, and shipping one here would undo it.
 
 Its `effect` is left unset on purpose: `readonly` would be a lie about arbitrary code and `destructive` a lie about sorting a list.
 
@@ -149,8 +207,11 @@ const sandbox: Sandbox = {
 codeExec({ sandbox, language: "python", timeoutMs: 10_000 });
 ```
 
-Anything satisfying `execute` works — a hosted sandbox, a container, a WASM runtime. A failed run comes back with `ok: false` rather than throwing, so the model reads `stderr` and corrects its own code instead of getting an opaque tool failure.
+Anything satisfying `execute` works, a hosted sandbox, a container, a WASM runtime. A failed run comes back with `ok: false` rather than throwing, so the model reads `stderr` and corrects its own code instead of getting an opaque tool failure.
 
-**`writeDocument`** commissions a document from an agent and hands back a rendered file. It takes a `MoaClient` — `create`, `get`, and optionally `cancel` — so the queue it talks to is yours. Long jobs are the normal case, which is why there are two errors rather than one: `MoaTimeoutError` when the wait ran out with work still going, and `MoaAbortedError` when something cancelled it. `DEFAULT_DESIGN`, `mergeDesign` and `renderDesign` are how the house style reaches the agent without being retyped per call.
+Commissioning a document agent used to live here as `writeDocument`. It now lives in
+`@spendgraph/vigil/agents` as `moaAgent()`, because the work takes minutes and a tool has to
+return now: a run parks on the agent and picks itself back up, rather than holding a process
+open for ten minutes.
 
 **`httpRequest`** takes a **required** allowlist and has no default. It is https only, refuses private, loopback, link-local and `.internal`/`.local` hosts **even if you list them**, and sets headers itself so a credential is never something the model can redirect. If the guard feels heavy, that is the correct amount of heavy: this is the one builtin that can exfiltrate. `allow: ["*"]` opens it to every public host, for the one case where the tool is a reader of the open web rather than a client of your own APIs; the private-address and https refusals still hold.

package/docs/bus.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "The bus — spendgraph docs",
+  title: "The bus: spendgraph docs",
   description:
     "toolbus holds them, picks the few worth sending, converts them per provider, and runs them without throwing. Selection is never applied for you, because hiding it would hide a cache invalidation.",
 };
@@ -20,7 +20,7 @@ toolbus([lookup, lookup]);   // Error: Two tools are called "lookup_contract".
 
 Registering the second under the same key would leave `invoke` a coin flip. It fails at import instead.
 
-The bus also warns — once, however many pairs — when two tools describe themselves almost identically. Nothing fails at runtime when they do; the model just picks wrong more often, which is exactly why it is worth saying out loud. Switch it off with `{ warnOnOverlap: false }` once a catalogue is large enough that the warning is noise rather than news.
+The bus also warns, once, however many pairs, when two tools describe themselves almost identically. Nothing fails at runtime when they do; the model just picks wrong more often, which is exactly why it is worth saying out loud. Switch it off with `{ warnOnOverlap: false }` once a catalogue is large enough that the warning is noise rather than news.
 
 ## Selection is never applied for you
 
@@ -31,7 +31,7 @@ bus.anthropic(bus.select(query))    // the shortlist
 
 The provider adapters send **everything** unless you narrow them, and that is deliberate. The `tools` array sits ahead of the messages in the cached prefix, so a list that changes every turn invalidates the system prompt along with it. Hiding a `select()` call inside `anthropic()` would hide that cost, so the shorter call is the expensive one on purpose.
 
-In practice you want [`trace()`](/docs/tools/turns), which selects once and records what it offered.
+In practice you want [`trace()`](/spendgraph/tools/turns), which selects once and records what it offered.
 
 ## What it answers
 
@@ -59,16 +59,16 @@ result.status;   // "completed" | "failed"
 ```
 
 <Callout tone="trap" title="`invoke` never throws, so `status` is the only thing that says it failed">
-  A tool that throws comes back as a failed result the model reads and can act on, which is the point — but code that only looks at `output` sees an empty string and carries on. Check `status === "failed"` before believing a result.
+  A tool that throws comes back as a failed result the model reads and can act on, which is the point, but code that only looks at `output` sees an empty string and carries on. Check `status === "failed"` before believing a result.
 </Callout>
 
 ## Gating on effect
 
-`destructive()` lists only the tools that **said** they are. Pair it with `unannotated()` before treating the rest as safe — see [Effects](/docs/tools/effects).
+`destructive()` lists only the tools that **said** they are. Pair it with `unannotated()` before treating the rest as safe. See [Effects](/spendgraph/tools/effects).
 
 ## Usage is the tiebreaker
 
-`usage()` counts what has actually run, and selection falls back on it when a query singles nothing out. A call that never reached the tool — a bad name, arguments that did not validate — is not counted, because it was not a use.
+`usage()` counts what has actually run, and selection falls back on it when a query singles nothing out. A call that never reached the tool, a bad name, arguments that did not validate, is not counted, because it was not a use.
 
 ## Nesting: one bus of buses
 
@@ -83,7 +83,7 @@ const bus = busgroup([
 ]);
 ```
 
-**It returns a bus.** Everything above works on it unchanged, a member's `bus` may itself be a group, and the model still sees a flat list of tools — grouping is a selection-time concern, never a wire-format one.
+**It returns a bus.** Everything above works on it unchanged, a member's `bus` may itself be a group, and the model still sees a flat list of tools: grouping is a selection-time concern, never a wire-format one.
 
 Routing runs in three steps. A query that clearly names a domain consults only that domain. A query that names none consults every member and re-ranks the merged offers, so nesting is never worse than flat. A query that matches nothing anywhere spreads across members rather than letting array order decide.
 

package/docs/declaring.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Declaring a tool — spendgraph docs",
+  title: "Declaring a tool: spendgraph docs",
   description:
     "Write `as const` and the handler types itself. Every check `tool` makes is something a provider either rejects opaquely or accepts and behaves oddly about.",
 };
@@ -21,7 +21,7 @@ const lookup = tool({
 
 ## Write `as const` and the handler types itself
 
-`ref` arrives a string, `limit` a number, `mode` narrowed to its two options, and the optional ones optional. Rename an argument and the handler stops compiling — rather than being handed `undefined` halfway through an agent loop.
+`ref` arrives a string, `limit` a number, `mode` narrowed to its two options, and the optional ones optional. Rename an argument and the handler stops compiling: rather than being handed `undefined` halfway through an agent loop.
 
 Without `as const`, inference falls back to nothing **silently**. That is the failure the package's own typecheck test exists to catch.
 
@@ -32,11 +32,11 @@ Arguments are validated, then filled in and coerced, before `run` sees them:
 - a **declared default** applies when the argument is absent;
 - a value arrives at the **type its declaration promises**.
 
-Providers hand tool arguments over as JSON a model wrote, so `"limit": "7"` is ordinary. It validates — the checker reads it through the same coercion — and it reaches `run` as the number `7`. `"loud": "false"` reaches it as `false`, not as a non-empty string that would make `if (args.loud)` run the branch the model asked it not to.
+Providers hand tool arguments over as JSON a model wrote, so `"limit": "7"` is ordinary. It validates, the checker reads it through the same coercion, and it reaches `run` as the number `7`. `"loud": "false"` reaches it as `false`, not as a non-empty string that would make `if (args.loud)` run the branch the model asked it not to.
 
 ## `aliases` are matched, never sent
 
-The description is what the model reads. `aliases` are what [selection](/docs/tools/selecting) matches on, and they never leave the process:
+The description is what the model reads. `aliases` are what [selection](/spendgraph/tools/selecting) matches on, and they never leave the process:
 
 ```ts
 tool({
@@ -68,7 +68,7 @@ Every check `tool` makes is something a provider either rejects opaquely or acce
 They fire at import, not on the first loop in production.
 
 <Callout tone="trap" title="Without `as const`, inference gives up quietly">
-  Drop it and the handler's argument type falls back to `Record<string, unknown>` — no error, no red squiggle, just every field typed `unknown` from then on. It is checked by a typecheck test in the package for exactly that reason.
+  Drop it and the handler's argument type falls back to `Record<string, unknown>`, no error, no red squiggle, just every field typed `unknown` from then on. It is checked by a typecheck test in the package for exactly that reason.
 </Callout>
 
 ## What a result carries
@@ -80,6 +80,6 @@ result.error;      // why, when it failed
 result.latencyMs;
 ```
 
-A tool whose **return value** cannot be serialised — a circular object, a `BigInt` — is still a tool that **ran**. It comes back completed, carrying `[not recordable: …]`, rather than failed: reporting a completed action as a failure invites the agent to do it again.
+A tool whose **return value** cannot be serialised, a circular object, a `BigInt`, is still a tool that **ran**. It comes back completed, carrying `[not recordable: …]`, rather than failed: reporting a completed action as a failure invites the agent to do it again.
 
 A thrown string keeps its message. Anything can be thrown, and reading only `Error.message` discards the one thing the tool said about itself.

package/docs/effects.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Effects — spendgraph docs",
+  title: "Effects: spendgraph docs",
   description:
     "Three values, not a taxonomy. There is no default, and unset is not readonly: a default would quietly label every tool written before this existed as safe.",
 };
@@ -20,7 +20,7 @@ Without it, `issue_refund` and `lookup_clause` are the same thing to a bus: two
 | `idempotent` | has an effect, but twice is the same as once |
 | `destructive` | neither, so never retry it on its own |
 
-Three values, not a taxonomy — anything finer does not get filled in accurately.
+Three values, not a taxonomy: anything finer does not get filled in accurately.
 
 ## There is no default, and unset is not `readonly`
 
@@ -32,18 +32,18 @@ bus.destructive()              // ["issue_refund"]
 bus.unannotated()              // ["send_email"]
 ```
 
-`destructive()` returns only the tools that said so, so a gate built on it alone lets an unlabelled one through. **`unannotated()` is how you find those** — assert it is empty in a test and a new tool cannot join the bus unlabelled.
+`destructive()` returns only the tools that said so, so a gate built on it alone lets an unlabelled one through. **`unannotated()` is how you find those**: assert it is empty in a test and a new tool cannot join the bus unlabelled.
 
 <Callout tone="trap" title="`readonly` is not the same as safe">
-  Effect says what a call does outside the process; `trust` says whether what it returns was written by somebody outside. A web fetch is `readonly` and is also how an injected instruction arrives. A guard that wants "no destructive call after untrusted content came in" has to gate on `trust: "external"` — the alternative is gating on the tool's *name*, which a rename turns off silently, and in the permissive direction.
+  Effect says what a call does outside the process; `trust` says whether what it returns was written by somebody outside. A web fetch is `readonly` and is also how an injected instruction arrives. A guard that wants "no destructive call after untrusted content came in" has to gate on `trust: "external"`: the alternative is gating on the tool's *name*, which a rename turns off silently, and in the permissive direction.
 </Callout>
 
 ## It survives selection
 
 The effect rides along on `declarations()` and survives `select()`, which is where a gate reads it. Every provider shape drops it: no API has a field for it, and an unknown key is either rejected or ignored.
 
-A turn answers about the tools **it** was offered — `effectOf` is `undefined` both for a tool that never said and for one this turn never saw. A gate reading it decides what unknown means for it.
+A turn answers about the tools **it** was offered: `effectOf` is `undefined` both for a tool that never said and for one this turn never saw. A gate reading it decides what unknown means for it.
 
 ## Three builtins leave it unset on purpose
 
-`http_request` is a GET or a POST depending on an argument, and one label cannot be true of both. `escalate` runs your `onEscalate`, and paging someone twice is not the same as paging them once. `code_exec` runs whatever the model wrote, which is neither safe nor known — and `undefined` says exactly that, where either label would lie.
+`http_request` is a GET or a POST depending on an argument, and one label cannot be true of both. `escalate` runs your `onEscalate`, and paging someone twice is not the same as paging them once. `code_exec` runs whatever the model wrote, which is neither safe nor known, and `undefined` says exactly that, where either label would lie.

package/docs/overview.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Tools — spendgraph docs",
+  title: "Tools: spendgraph docs",
   description:
     "Declare a tool once, offer the right few, and record what was called. A description and a function in one object, so a rename cannot become a runtime failure.",
 };
@@ -8,12 +8,14 @@ export const meta = {
 
 Fifty tools is 7,500 tokens spent before the user has typed anything, and a model given fifty picks worse than a model given five.
 
-Declare a tool once, offer the right few, and record what was called — because a model that says it checked the ledger and did not is a claim only the steps can disprove.
+Declare a tool once, offer the right few, and record what was called: because a model that says it checked the ledger and did not is a claim only the steps can disprove.
 
 ```sh
 npm install @spendgraph/tools
 ```
 
+<ToolShortlist />
+
 Two things to learn, and twenty-two builtins you can ignore until you want one.
 
 ```ts
@@ -44,7 +46,7 @@ turn.record();   // { offeredTools, steps }
 
 ## Why one object
 
-A description the model reads and a function you wrote, in **one object**. Splitting them — a schema here, a handler there, matched by string — is how a rename becomes a runtime failure mid-loop.
+A description the model reads and a function you wrote, in **one object**. Splitting them, a schema here, a handler there, matched by string, is how a rename becomes a runtime failure mid-loop.
 
 The description is the biggest lever on whether the model calls it correctly, and worth iterating on more than the code is.
 
@@ -59,18 +61,18 @@ await prompt.call(values, ({ messages, turn }) => llm.call(messages, { tools: tu
 ```
 
 <Callout tone="trap" title="Declaring a tool is not offering it">
-  `toolbus()` holds everything your app can do; what the model sees each turn is a shortlist. Selection is never applied for you — hand the model the whole bus and you are paying for every description on every turn, and making it worse at choosing.
+  `toolbus()` holds everything your app can do; what the model sees each turn is a shortlist. Selection is never applied for you: hand the model the whole bus and you are paying for every description on every turn, and making it worse at choosing.
 </Callout>
 
 ## Where to go next
 
 | | |
 | --- | --- |
-| [Declaring a tool](/docs/tools/declaring) | args, `as const`, and what is checked at import |
-| [A stored tool](/docs/tools/stored) | wording in the dashboard, handler in code |
-| [Effects](/docs/tools/effects) | what running one does to the world outside |
-| [The bus](/docs/tools/bus) | holds, picks, converts, runs — and nests |
-| [Selecting](/docs/tools/selecting) | the shortlist, and why it is a shortlist |
-| [A turn](/docs/tools/turns) | offered, called, and what the rollout keeps |
-| [Builtins](/docs/tools/builtins) | thirteen factories, none registered for you |
-| [Bogus tools](/docs/tools/bogus) | twelve mocks for testing the pipeline, not the provider |
+| [Declaring a tool](/spendgraph/tools/declaring) | args, `as const`, and what is checked at import |
+| [A stored tool](/spendgraph/tools/stored) | wording in the dashboard, handler in code |
+| [Effects](/spendgraph/tools/effects) | what running one does to the world outside |
+| [The bus](/spendgraph/tools/bus) | holds, picks, converts, runs, and nests |
+| [Selecting](/spendgraph/tools/selecting) | the shortlist, and why it is a shortlist |
+| [A turn](/spendgraph/tools/turns) | offered, called, and what the rollout keeps |
+| [Builtins](/spendgraph/tools/builtins) | thirteen factories, none registered for you |
+| [Bogus tools](/spendgraph/tools/bogus) | twelve mocks for testing the pipeline, not the provider |

package/docs/selecting.mdx

@@ -1,5 +1,5 @@
 export const meta = {
-  title: "Selecting tools — spendgraph docs",
+  title: "Selecting tools: spendgraph docs",
   description:
     "Fifty tools is 7.5k tokens before the user has said anything. `limit` is an accuracy budget, not a token one, and selection is keyword and usage on purpose.",
 };
@@ -22,23 +22,23 @@ Holding tools in one place is what makes selection possible. Fifty tools at roug
 
 ## `limit` is an accuracy budget
 
-More tools in front of a model makes it worse at picking the right one **regardless of context length**. Measured shortlists cluster around five to eight. Pinned tools count against it — what is in front of the model is what costs accuracy, whoever put it there.
+More tools in front of a model makes it worse at picking the right one **regardless of context length**. Measured shortlists cluster around five to eight. Pinned tools count against it: what is in front of the model is what costs accuracy, whoever put it there.
 
-A limit that is `NaN` is refused rather than clamped: `Math.max(1, NaN)` is `NaN`, and every length compares false against it, so the model would be offered **nothing** — the one outcome selection exists to avoid.
+A limit that is `NaN` is refused rather than clamped: `Math.max(1, NaN)` is `NaN`, and every length compares false against it, so the model would be offered **nothing**, the one outcome selection exists to avoid.
 
 ## Keyword and usage, deliberately
 
 No embedding provider, no extra call, no latency. It is also the baseline that says what embeddings would buy.
 
-Relevance comes before usage: at a shortlist of six, three previously-used tools take half the slots and push out the tool the query needs. Usage earns its place as the tiebreaker among equal matches, and as the fallback when nothing matches — the case where an agent would otherwise be handed nothing.
+Relevance comes before usage: at a shortlist of six, three previously-used tools take half the slots and push out the tool the query needs. Usage earns its place as the tiebreaker among equal matches, and as the fallback when nothing matches, the case where an agent would otherwise be handed nothing.
 
-Words are found in **any script**. A query with no ASCII letters used to produce no terms at all, so every request fell through to "the first six declared" — the same six for a Japanese question as for a Russian one.
+Words are found in **any script**. A query with no ASCII letters used to produce no terms at all, so every request fell through to "the first six declared", the same six for a Japanese question as for a Russian one.
 
 ## How a tool scores
 
 Whole words, never substrings. A term matching inside a longer word is noise, not signal: `me` sits inside `statement`, and at a few hundred tools that alone puts half the catalogue in every shortlist.
 
-Where the word appears decides its weight — **name beats alias beats description**. A tool named `refund` is a stronger answer to a question about refunds than one that merely mentions the word in a paragraph.
+Where the word appears decides its weight: **name beats alias beats description**. A tool named `refund` is a stronger answer to a question about refunds than one that merely mentions the word in a paragraph.
 
 Then each term is weighted by how **rare** it is across the bus. A word one tool in two thousand uses says far more than one four hundred of them share, and without that every term counts the same and common vocabulary decides the shortlist.
 
@@ -56,15 +56,15 @@ tool({
 });
 ```
 
-They are matched, never sent — every provider shape drops them, exactly as it drops `effect`. Unlike an embedding, a bad match is fixed by editing one line.
+They are matched, never sent: every provider shape drops them, exactly as it drops `effect`. Unlike an embedding, a bad match is fixed by editing one line.
 
 <Callout tone="trap" title="Pinned tools spend the budget too">
-  `limit` counts pinned tools, so a shortlist of 5 with `finish` and `escalate` pinned leaves three slots for the query. A tool that needs a partner is dropped rather than offered alone — an agent told to prefer `recall` and handed only `deep_recall` will reach for the one it does not have.
+  `limit` counts pinned tools, so a shortlist of 5 with `finish` and `escalate` pinned leaves three slots for the query. A tool that needs a partner is dropped rather than offered alone, an agent told to prefer `recall` and handed only `deep_recall` will reach for the one it does not have.
 </Callout>
 
 ## Past a few hundred tools
 
-Ranking, not speed, is what gives out first: selection stays near a millisecond at two thousand tools, but a coincidental match in an unrelated domain starts taking slots. [`busgroup`](/docs/tools/bus) gives each domain its own bus and routes between them.
+Ranking, not speed, is what gives out first: selection stays near a millisecond at two thousand tools, but a coincidental match in an unrelated domain starts taking slots. [`busgroup`](/spendgraph/tools/bus) gives each domain its own bus and routes between them.
 
 ## `missing` catches a silent failure
 
@@ -76,4 +76,4 @@ bus.missing(["refund", "escalate"]);   // the names this bus does not have
 
 ## Two tools that describe themselves the same way
 
-Two near-identical descriptions are worse than one tool: the model cannot tell them apart and picks wrong more often, with nothing failing. The bus says so at construction, once, however many pairs there are — a line each buries whatever else the process said at startup and teaches people to switch the check off.
+Two near-identical descriptions are worse than one tool: the model cannot tell them apart and picks wrong more often, with nothing failing. The bus says so at construction, once, however many pairs there are, a line each buries whatever else the process said at startup and teaches people to switch the check off.