bare-agent 0.43.0 → 0.44.1

package/src/complexity.js

@@ -89,6 +89,11 @@ const MAX_ASSESS_LEN = 4000;
  * Assess the complexity of a goal/prompt from its text alone (no LLM).
  * @param {string} prompt - The goal to classify.
  * @returns {ComplexityResult}
+ * @when you want a fast, no-LLM read of how hard a goal is (simple/medium/complex/critical) to decide whether to invoke the Planner
+ * @fails never throws — pure text scoring; non-string/blank input scores lowest. Keyword lists are frozen and a critical-safety override always wins.
+ * @example
+ *   const { level, needsPlanning } = assessComplexity(goal);
+ *   if (needsPlanning) await planner.plan(goal);
  */
 function assessComplexity(prompt) {
   if (typeof prompt !== 'string' || !prompt.trim()) {
@@ -169,6 +174,10 @@ function assessComplexity(prompt) {
  * non-string / blank input is `false`.
  * @param {string} prompt - The goal to test.
  * @returns {boolean}
+ * @when you want the durable critical-safety floor alone (security/production/compliance/financial) to gate extra scrutiny, without the full scorer
+ * @fails never throws — deterministic override; non-string/blank input is false. This floor is non-overridable by design.
+ * @example
+ *   if (isCritical(goal)) verdict = await evaluator.evaluate(goal, result, { contract });
  */
 function isCritical(prompt) {
   if (typeof prompt !== 'string' || !prompt.trim()) return false;

package/src/context-units.d.ts

@@ -32,6 +32,10 @@ export function fromUnits(units: Array<Record<string, any>>): Array<Record<strin
  * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
  * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
  * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ * @when you want to adapt a litectx-style neutral-unit assemble(units, ctx) verb into the Loop's assemble(msgs, ctx) context-assembly seam
+ * @fails fail-open — any unexpected return shape sends the original msgs unchanged; a thrown error (incl. HaltError) is left to the Loop's own handling.
+ * @example
+ *   const loop = new Loop({ provider, assemble: unitAssembler(litectx.assemble) });
  */
 export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)): (msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>;
 /**
@@ -67,6 +71,10 @@ export function unitAssembler(assembleUnits: (units: Array<Record<string, any>>,
  *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
  *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
  * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ * @when you want to adapt litectx's trim(units, policy) verb into the Loop's destructive trim(msgs, ctx) seam — harvest-before-evict with an F2 residual .flush
+ * @fails throws if the trim/onHarvest verbs are missing (runtime-checked); the fold is fail-open and a HaltError propagates. `.flush` drains the residual harvest.
+ * @example
+ *   const loop = new Loop({ provider, trim: unitTrimmer({ trim: litectx.trim, onHarvest, policy: { keepLastN: 20 } }) });
  */
 export function unitTrimmer(opts?: {
     trim?: Function;
@@ -93,6 +101,10 @@ export function unitTrimmer(opts?: {
  * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
  * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
  * @returns {string}
+ * @when you need the stable content-address for a transcript unit (the key harvest-before-evict writes under) — a collision-resistant 64-bit id
+ * @fails never throws; normal provider ids round-trip unchanged, and two near-independent hash streams avoid 32-bit birthday collisions.
+ * @example
+ *   const key = harvestKey(unit); // stable id for this turn's harvest
  */
 export function harvestKey(unit: Record<string, any>): string;
 /** chars/4 token estimate over a list of messages (matches poc2 / the Loop's own heuristic). */

package/src/context-units.js

@@ -207,6 +207,10 @@ function fromUnits(units) {
  * error (incl. HaltError) is left to the Loop's own fail-open / HaltError handling — not swallowed here.
  * @param {(units: Array<Record<string, any>>, ctx: any) => (any | Promise<any>)} assembleUnits
  * @returns {(msgs: Array<Record<string, any>>, ctx: any) => Promise<Array<Record<string, any>>>}
+ * @when you want to adapt a litectx-style neutral-unit assemble(units, ctx) verb into the Loop's assemble(msgs, ctx) context-assembly seam
+ * @fails fail-open — any unexpected return shape sends the original msgs unchanged; a thrown error (incl. HaltError) is left to the Loop's own handling.
+ * @example
+ *   const loop = new Loop({ provider, assemble: unitAssembler(litectx.assemble) });
  */
 function unitAssembler(assembleUnits) {
   if (typeof assembleUnits !== 'function') {
@@ -240,6 +244,10 @@ function unitAssembler(assembleUnits) {
  * distinct turns). Normal provider ids (`call_…`) round-trip unchanged through the escape.
  * @param {Record<string, any>} unit - a unit from {@link toUnits} (its `_msgs` backing is read).
  * @returns {string}
+ * @when you need the stable content-address for a transcript unit (the key harvest-before-evict writes under) — a collision-resistant 64-bit id
+ * @fails never throws; normal provider ids round-trip unchanged, and two near-independent hash streams avoid 32-bit birthday collisions.
+ * @example
+ *   const key = harvestKey(unit); // stable id for this turn's harvest
  */
 function harvestKey(unit) {
   const back = (unit && unit._msgs) || [];
@@ -296,6 +304,10 @@ function harvestKey(unit) {
  *   `({ key, content, unit }) => void|Promise` (REQUIRED; the harvest policy point). `policy` — litectx
  *   TrimPolicy: `{ keepLastN }` or `{ maxTokens }` (maxTokens wins). Both verbs are runtime-checked.
  * @returns {((msgs: Array<Record<string, any>>, ctx?: any) => Promise<Array<Record<string, any>>>) & { flush: (msgs: Array<Record<string, any>>, ctx?: any) => Promise<void> }}
+ * @when you want to adapt litectx's trim(units, policy) verb into the Loop's destructive trim(msgs, ctx) seam — harvest-before-evict with an F2 residual .flush
+ * @fails throws if the trim/onHarvest verbs are missing (runtime-checked); the fold is fail-open and a HaltError propagates. `.flush` drains the residual harvest.
+ * @example
+ *   const loop = new Loop({ provider, trim: unitTrimmer({ trim: litectx.trim, onHarvest, policy: { keepLastN: 20 } }) });
  */
 function unitTrimmer(opts) {
   const { trim, onHarvest, policy = {} } = opts || {};

package/src/evaluator.d.ts

@@ -114,7 +114,15 @@ export type EvaluateOptions = {
  * Built flagged-and-deletable per D11 — opt-in by import; calibrate the rubric/prompt from execution traces.
  */
 export class Evaluator {
-    /** @param {EvaluatorOptions} [options] */
+    /**
+     * @param {EvaluatorOptions} [options]
+     * @when you need to judge an output against a goal or contract — deterministically (predicate), by LLM rubric, or with a tool-running critic that exercises the live artifact
+     * @fails never throws for a bad grade — returns a Verdict {status: satisfied|needs_revision|failed}; a provider HaltError propagates clean. Judge tokens forward via onLlmResult.
+     * @example
+     *   const evaluator = new Evaluator({ provider });
+     *   const verdict = await evaluator.evaluate(goal, result, { rubric });
+     *   if (!verdict.pass) revise(verdict.critique);
+     */
     constructor(options?: EvaluatorOptions);
     provider: import("../types").Provider | null;
     prompt: string;

package/src/evaluator.js

@@ -108,7 +108,15 @@ Output your FINAL answer as ONLY this JSON, no markdown, no prose:
  * Built flagged-and-deletable per D11 — opt-in by import; calibrate the rubric/prompt from execution traces.
  */
 class Evaluator {
-  /** @param {EvaluatorOptions} [options] */
+  /**
+   * @param {EvaluatorOptions} [options]
+   * @when you need to judge an output against a goal or contract — deterministically (predicate), by LLM rubric, or with a tool-running critic that exercises the live artifact
+   * @fails never throws for a bad grade — returns a Verdict {status: satisfied|needs_revision|failed}; a provider HaltError propagates clean. Judge tokens forward via onLlmResult.
+   * @example
+   *   const evaluator = new Evaluator({ provider });
+   *   const verdict = await evaluator.evaluate(goal, result, { rubric });
+   *   if (!verdict.pass) revise(verdict.critique);
+   */
   constructor(options = /** @type {EvaluatorOptions} */ ({})) {
     this.provider = options.provider || null;
     this.prompt = options.prompt || GRADER_PROMPT;

package/src/judge-calibration.d.ts

@@ -129,6 +129,11 @@ export function gradeRun(runs: Array<{
  *   a separate admission gate — a leak in any style blocks admission even at a passing clear-case floor.
  * @param {(payload:object)=>any} [opts.onLlmResult] - Budget hook forwarded to each judge call.
  * @returns {Promise<ReturnType<typeof gradeRun> & { reps:number, floor:number, totalCostUsd:number|null, unpricedCalls:number, injectionBattery: { styles: Array<{label:string, usable:number, broke:number, resisted:boolean}>, allResisted:boolean, leaks:number } }>}
+ * @when you are admitting an LLM tier to the judge role and need to grade it against the frozen clear-case battery and resist every injection style before trusting it
+ * @fails never fabricates a pass — a leak in any injection style blocks admission even above the clear-case floor, and the negative control must fail the set. HaltError propagates clean.
+ * @example
+ *   const report = await calibrate({ provider, reps: 5, floor: 7 });
+ *   if (!report.injectionBattery.allResisted) reject('injection leak');
  */
 export function calibrate(opts?: {
     provider: import("../types").Provider;

package/src/judge-calibration.js

@@ -125,6 +125,11 @@ function gradeRun(runs, floor) {
  *   a separate admission gate — a leak in any style blocks admission even at a passing clear-case floor.
  * @param {(payload:object)=>any} [opts.onLlmResult] - Budget hook forwarded to each judge call.
  * @returns {Promise<ReturnType<typeof gradeRun> & { reps:number, floor:number, totalCostUsd:number|null, unpricedCalls:number, injectionBattery: { styles: Array<{label:string, usable:number, broke:number, resisted:boolean}>, allResisted:boolean, leaks:number } }>}
+ * @when you are admitting an LLM tier to the judge role and need to grade it against the frozen clear-case battery and resist every injection style before trusting it
+ * @fails never fabricates a pass — a leak in any injection style blocks admission even above the clear-case floor, and the negative control must fail the set. HaltError propagates clean.
+ * @example
+ *   const report = await calibrate({ provider, reps: 5, floor: 7 });
+ *   if (!report.injectionBattery.allResisted) reject('injection leak');
  */
 async function calibrate(opts = /** @type {any} */ ({})) {
   const provider = opts.provider;

package/src/judge.d.ts

@@ -157,6 +157,11 @@ export type JudgeVerdict = {
  * @throws {ValidationError} on bad inputs (missing request/artifact/provider) — stamped `context.lib='bare-agent'`
  *   at the throw site (contract 4: typed attribution, never sniffed from prose).
  * @throws {HaltError} propagated clean from the provider (a governance halt is not a judge failure).
+ * @when you need a decisive honored/broke verdict on whether one egress artifact honored the verbatim request — a return-time integrity check
+ * @fails throws ValidationError on bad inputs; HaltError propagates clean. Cannot-confirm-honored floors to `broke`; truncation/parse-error are distinct flagged outcomes, never laundered to honored.
+ * @example
+ *   const { verdict, where } = await judge({ request, artifact, provider });
+ *   if (verdict === 'broke') flag(where);
  */
 export function judge(options?: JudgeOptions): Promise<JudgeVerdict>;
 /**

package/src/judge.js

@@ -145,6 +145,11 @@ function normalizeWhere(where) {
  * @throws {ValidationError} on bad inputs (missing request/artifact/provider) — stamped `context.lib='bare-agent'`
  *   at the throw site (contract 4: typed attribution, never sniffed from prose).
  * @throws {HaltError} propagated clean from the provider (a governance halt is not a judge failure).
+ * @when you need a decisive honored/broke verdict on whether one egress artifact honored the verbatim request — a return-time integrity check
+ * @fails throws ValidationError on bad inputs; HaltError propagates clean. Cannot-confirm-honored floors to `broke`; truncation/parse-error are distinct flagged outcomes, never laundered to honored.
+ * @example
+ *   const { verdict, where } = await judge({ request, artifact, provider });
+ *   if (verdict === 'broke') flag(where);
  */
 async function judge(options = /** @type {JudgeOptions} */ ({})) {
   const { request, artifact, provider } = options;

package/src/loop.d.ts

@@ -105,6 +105,12 @@ export class Loop {
      * tool outcomes to `gate.record` (via wireGate) and never kill the loop on error.
      * @param {LoopOptions} options
      * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
+     * @when you are running a model think/act/observe cycle and need round accounting, tool dispatch, spin guards, and a governance chokepoint
+     * @fails returns the last assistant text with an `error` tag on any bound (halt/deny-streak/truncation/provider error); throws only if constructed without a provider. A policy HaltError exits clean.
+     * @example
+     *   const loop = new Loop({ provider, policy });
+     *   const { text, error, metrics } = await loop.run(messages, tools);
+     *   if (error) handle(error);
      */
     constructor(options?: LoopOptions);
     provider: import("../types").Provider;

package/src/loop.js

@@ -273,6 +273,12 @@ class Loop {
    * tool outcomes to `gate.record` (via wireGate) and never kill the loop on error.
    * @param {LoopOptions} options
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
+   * @when you are running a model think/act/observe cycle and need round accounting, tool dispatch, spin guards, and a governance chokepoint
+   * @fails returns the last assistant text with an `error` tag on any bound (halt/deny-streak/truncation/provider error); throws only if constructed without a provider. A policy HaltError exits clean.
+   * @example
+   *   const loop = new Loop({ provider, policy });
+   *   const { text, error, metrics } = await loop.run(messages, tools);
+   *   if (error) handle(error);
    */
   constructor(options = /** @type {LoopOptions} */ ({})) {
     if (!options.provider) throw new Error('[Loop] requires a provider');

package/src/mcp-bridge.d.ts

@@ -92,6 +92,11 @@ export type RpcClient = {
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
  * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @example
+ *   const { tools, close } = await createMCPBridge();
+ *   const loop = new Loop({ provider, tools });
  */
 export function createMCPBridge(opts?: {
     bridgePath?: string | undefined;
@@ -120,6 +125,10 @@ export function createMCPBridge(opts?: {
  * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
  *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
+ * @when you want to find configured MCP servers from the trusted $HOME/IDE config paths (or explicit paths) — discovery without invoking them
+ * @fails honors explicit configPaths verbatim and scans trusted defaults otherwise; returns a Map and never executes a server command.
+ * @example
+ *   const servers = discoverServers();
  */
 export function discoverServers(configPaths?: string[], { includeProjectConfig }?: {
     includeProjectConfig?: boolean;
@@ -142,5 +151,9 @@ export function discoverServers(configPaths?: string[], { includeProjectConfig }
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
+ * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
+ * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
+ * @example
+ *   const metaTools = buildMetaTools(tools);
  */
 export function buildMetaTools(tools: ToolDef[], discoveredAt?: string): ToolDef[];

package/src/mcp-bridge.js

@@ -80,6 +80,10 @@ const TRUSTED_CONFIG_PATHS = [
  * @param {{ includeProjectConfig?: boolean }} [opts] - When no explicit `configPaths` are given,
  *   set `includeProjectConfig: true` to also scan `./.mcp.json`. Default false — see PROJECT_CONFIG_PATH.
  * @returns {Map<string, ServerDef>}
+ * @when you want to find configured MCP servers from the trusted $HOME/IDE config paths (or explicit paths) — discovery without invoking them
+ * @fails honors explicit configPaths verbatim and scans trusted defaults otherwise; returns a Map and never executes a server command.
+ * @example
+ *   const servers = discoverServers();
  */
 function discoverServers(configPaths, { includeProjectConfig = false } = {}) {
   let paths;
@@ -523,6 +527,10 @@ function buildSystemContext(servers, tools, denied) {
  * @param {ToolDef[]} tools - The bulk-loaded, name-prefixed tools array.
  * @param {string} [discoveredAt] - ISO timestamp from .mcp-bridge.json.
  * @returns {ToolDef[]} [mcp_discover, mcp_invoke]
+ * @when you want the two bulk MCP meta-tools (mcp_discover, mcp_invoke) instead of exposing every discovered tool individually — one gate-check per invocation
+ * @fails returns [mcp_discover, mcp_invoke]; a tool name does not travel as action.type (a deliberate v0.9 trade for one gate-check per call).
+ * @example
+ *   const metaTools = buildMetaTools(tools);
  */
 function buildMetaTools(tools, discoveredAt) {
   // Catalog descriptors: same info the LLM would see for bulk-loaded tools,
@@ -637,6 +645,11 @@ function buildMetaTools(tools, discoveredAt) {
  *   of this hook also opts default discovery into the project-cwd `./.mcp.json`,
  *   since each command is then vetted regardless of source.
  * @returns {Promise<{tools: ToolDef[], metaTools?: ToolDef[], servers: string[], systemContext: string, denied: DeniedTool[], errors?: Array<{server: string, error: string}>, close: Function}>}
+ * @when you want to auto-discover MCP servers and expose them as bareagent tools in one call — with a trust hook gating command execution
+ * @fails a trust hook returning false skips a server (its command never runs) and a throw is fail-closed (deny); returns tools plus a close() to shut servers down.
+ * @example
+ *   const { tools, close } = await createMCPBridge();
+ *   const loop = new Loop({ provider, tools });
  */
 async function createMCPBridge(opts = {}) {
   if ('policy' in opts) {

package/src/memory.d.ts

@@ -19,6 +19,11 @@ export class Memory {
     /**
      * @param {{ store?: Store }} [options] - Store backend (must implement store/search/get/delete).
      * @throws {Error} `[Memory] requires options.store` — when options.store is missing.
+     * @when you want thin store-backed memory (store/search/get/delete) an agent can write to and recall from, over any swappable backend
+     * @fails throws if constructed without a store; recall/store metering is opt-in via ctx. All persistence delegates to the backend.
+     * @example
+     *   const memory = new Memory({ store: new JsonFile({ path: './mem.json' }) });
+     *   await memory.store({ text: 'a durable fact' });
      */
     constructor(options?: {
         store?: Store;

package/src/memory.js

@@ -21,6 +21,11 @@ class Memory {
   /**
    * @param {{ store?: Store }} [options] - Store backend (must implement store/search/get/delete).
    * @throws {Error} `[Memory] requires options.store` — when options.store is missing.
+   * @when you want thin store-backed memory (store/search/get/delete) an agent can write to and recall from, over any swappable backend
+   * @fails throws if constructed without a store; recall/store metering is opt-in via ctx. All persistence delegates to the backend.
+   * @example
+   *   const memory = new Memory({ store: new JsonFile({ path: './mem.json' }) });
+   *   await memory.store({ text: 'a durable fact' });
    */
   constructor(options = {}) {
     if (!options.store) throw new Error('[Memory] requires options.store');

package/src/planner.d.ts

@@ -46,6 +46,12 @@ export class Planner {
     /**
      * @param {PlannerOptions} options
      * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
+     * @when you need to turn a goal into an ordered step DAG for an LLM to execute — optionally forcing exactly N independent steps for fan-out
+     * @fails throws if constructed without a provider; a plan call's HaltError (governance cap) propagates clean. Plan-call usage forwards via onLlmResult.
+     * @example
+     *   const planner = new Planner({ provider });
+     *   const steps = await planner.plan('ship the release', { count: 4 });
+     *   await runPlan(steps, ctx);
      */
     constructor(options?: PlannerOptions);
     provider: import("../types").Provider;

package/src/planner.js

@@ -39,6 +39,12 @@ class Planner {
   /**
    * @param {PlannerOptions} options
    * @throws {Error} `[Planner] requires a provider` — when options.provider is missing.
+   * @when you need to turn a goal into an ordered step DAG for an LLM to execute — optionally forcing exactly N independent steps for fan-out
+   * @fails throws if constructed without a provider; a plan call's HaltError (governance cap) propagates clean. Plan-call usage forwards via onLlmResult.
+   * @example
+   *   const planner = new Planner({ provider });
+   *   const steps = await planner.plan('ship the release', { count: 4 });
+   *   await runPlan(steps, ctx);
    */
   constructor(options = /** @type {PlannerOptions} */ ({})) {
     if (!options.provider) throw new Error('[Planner] requires a provider');

package/src/provider-anthropic.d.ts

@@ -62,6 +62,10 @@ export class AnthropicProvider {
     /**
      * @param {AnthropicOptions} [options]
      * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
+     * @when you want Claude models as the Loop's provider — native Messages API with opt-in prompt caching and thinking-block passthrough
+     * @fails throws on a missing apiKey; normalizes stopReason and usage (usage:null when the API omits it); a socket idle/deadline/transport cut rejects with a retryable Timeout/ProviderError.
+     * @example
+     *   const provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-5' });
      */
     constructor(options?: AnthropicOptions);
     apiKey: string;

package/src/provider-anthropic.js

@@ -41,6 +41,10 @@ class AnthropicProvider {
   /**
    * @param {AnthropicOptions} [options]
    * @throws {Error} `[AnthropicProvider] requires apiKey` — when apiKey is missing.
+   * @when you want Claude models as the Loop's provider — native Messages API with opt-in prompt caching and thinking-block passthrough
+   * @fails throws on a missing apiKey; normalizes stopReason and usage (usage:null when the API omits it); a socket idle/deadline/transport cut rejects with a retryable Timeout/ProviderError.
+   * @example
+   *   const provider = new AnthropicProvider({ apiKey, model: 'claude-sonnet-5' });
    */
   constructor(options = {}) {
     if (!options.apiKey) throw new Error('[AnthropicProvider] requires apiKey');

package/src/provider-clipipe.d.ts

@@ -123,6 +123,10 @@ export class CLIPipeProvider {
      * Provider that pipes prompts to a CLI command via stdin and reads stdout.
      * @param {CLIPipeOptions} [options]
      * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+     * @when you want to drive a CLI (e.g. the claude CLI) as the Loop's provider — native MCP tools or a JSON emulation envelope
+     * @fails throws on a missing command; in native mode it owns its own cycle (ownsCycle), so per-round Loop seams are refused at construction rather than left silently dead.
+     * @example
+     *   const provider = new CLIPipeProvider({ command: 'claude' });
      */
     constructor(options?: CLIPipeOptions);
     command: string;

package/src/provider-clipipe.js

@@ -112,6 +112,10 @@ class CLIPipeProvider {
    * Provider that pipes prompts to a CLI command via stdin and reads stdout.
    * @param {CLIPipeOptions} [options]
    * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+   * @when you want to drive a CLI (e.g. the claude CLI) as the Loop's provider — native MCP tools or a JSON emulation envelope
+   * @fails throws on a missing command; in native mode it owns its own cycle (ownsCycle), so per-round Loop seams are refused at construction rather than left silently dead.
+   * @example
+   *   const provider = new CLIPipeProvider({ command: 'claude' });
    */
   constructor(options = {}) {
     if (!options.command) throw new Error('[CLIPipeProvider] requires command');

package/src/provider-fallback.d.ts

@@ -27,6 +27,10 @@ export class FallbackProvider {
      * @param {Provider[]} providers - Ordered list of providers with generate().
      * @param {FallbackOptions} [options={}]
      * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+     * @when you want to try several providers in order, failing over to the next when one errors — resilience across tiers or vendors
+     * @fails throws if given no providers; returns the first provider's success, else propagates the last provider's error.
+     * @example
+     *   const provider = new FallbackProvider([primary, backup]);
      */
     constructor(providers: Provider[], options?: FallbackOptions);
     providers: import("../types").Provider[];

package/src/provider-fallback.js

@@ -17,6 +17,10 @@ class FallbackProvider {
    * @param {Provider[]} providers - Ordered list of providers with generate().
    * @param {FallbackOptions} [options={}]
    * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+   * @when you want to try several providers in order, failing over to the next when one errors — resilience across tiers or vendors
+   * @fails throws if given no providers; returns the first provider's success, else propagates the last provider's error.
+   * @example
+   *   const provider = new FallbackProvider([primary, backup]);
    */
   constructor(providers, options = {}) {
     if (!Array.isArray(providers) || providers.length === 0) {

package/src/provider-gemini.d.ts

@@ -45,7 +45,13 @@ export type GeminiOptions = {
  * cache-read tier populates with no opt-in.
  */
 export class GeminiProvider {
-    /** @param {GeminiOptions} [options] */
+    /**
+     * @param {GeminiOptions} [options]
+     * @when you want Gemini models as the Loop's provider — native generateContent with implicit prompt caching
+     * @fails throws on a missing apiKey; normalizes stopReason (promoting a complete tool call) and usage; a socket idle/deadline/transport cut rejects with a retryable error.
+     * @example
+     *   const provider = new GeminiProvider({ apiKey, model: 'gemini-2.5-pro' });
+     */
     constructor(options?: GeminiOptions);
     apiKey: string | undefined;
     model: string;

package/src/provider-gemini.js

@@ -40,7 +40,13 @@ function isLoopbackHost(hostname) {
  * cache-read tier populates with no opt-in.
  */
 class GeminiProvider {
-  /** @param {GeminiOptions} [options] */
+  /**
+   * @param {GeminiOptions} [options]
+   * @when you want Gemini models as the Loop's provider — native generateContent with implicit prompt caching
+   * @fails throws on a missing apiKey; normalizes stopReason (promoting a complete tool call) and usage; a socket idle/deadline/transport cut rejects with a retryable error.
+   * @example
+   *   const provider = new GeminiProvider({ apiKey, model: 'gemini-2.5-pro' });
+   */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();
     this.model = options.model || 'gemini-2.5-flash';

package/src/provider-ollama.d.ts

@@ -28,6 +28,10 @@ export type OllamaOptions = {
 export class OllamaProvider {
     /**
      * @param {OllamaOptions} [options]
+     * @when you want local models via Ollama as the Loop's provider — no API key, self-hosted
+     * @fails normalizes stopReason (promoting a complete tool call) and usage; a malformed tool-call JSON returns no usable calls with usage metered; a socket idle/deadline cut rejects with a retryable error.
+     * @example
+     *   const provider = new OllamaProvider({ model: 'llama3' });
      */
     constructor(options?: OllamaOptions);
     model: string;

package/src/provider-ollama.js

@@ -27,6 +27,10 @@ const OLLAMA_USAGE_KEYS = ['prompt_eval_count', 'eval_count'];
 class OllamaProvider {
   /**
    * @param {OllamaOptions} [options]
+   * @when you want local models via Ollama as the Loop's provider — no API key, self-hosted
+   * @fails normalizes stopReason (promoting a complete tool call) and usage; a malformed tool-call JSON returns no usable calls with usage metered; a socket idle/deadline cut rejects with a retryable error.
+   * @example
+   *   const provider = new OllamaProvider({ model: 'llama3' });
    */
   constructor(options = {}) {
     this.model = options.model || 'llama3.2';

package/src/provider-openai.d.ts

@@ -68,6 +68,10 @@ export type OpenAIOptions = {
 export class OpenAIProvider {
     /**
      * @param {OpenAIOptions} [options]
+     * @when you want OpenAI or any OpenAI-compatible endpoint as the Loop's provider — tool-calling, toolChoice, and a custom baseUrl
+     * @fails throws on a missing apiKey; a malformed tool-call JSON returns no usable calls with usage still metered (BA-27); a socket idle/deadline/transport cut rejects with a retryable error.
+     * @example
+     *   const provider = new OpenAIProvider({ apiKey, model: 'gpt-5' });
      */
     constructor(options?: OpenAIOptions);
     apiKey: string | undefined;

package/src/provider-openai.js

@@ -76,6 +76,10 @@ function isLoopbackHost(hostname) {
 class OpenAIProvider {
   /**
    * @param {OpenAIOptions} [options]
+   * @when you want OpenAI or any OpenAI-compatible endpoint as the Loop's provider — tool-calling, toolChoice, and a custom baseUrl
+   * @fails throws on a missing apiKey; a malformed tool-call JSON returns no usable calls with usage still metered (BA-27); a socket idle/deadline/transport cut rejects with a retryable error.
+   * @example
+   *   const provider = new OpenAIProvider({ apiKey, model: 'gpt-5' });
    */
   constructor(options = {}) {
     this.apiKey = options.apiKey?.trim();

package/src/recurse-retrieval.d.ts

@@ -99,6 +99,12 @@ export function normalizeCorpus(corpus: unknown): Slice[];
  * @param {{recall: Function}} litectx
  * @param {{kinds?: string[], n?: number}} [opts]
  * @returns {ToolDef}
+ * @category integration
+ * @when you want to give a recurse worker a needle-search handle over litectx (embeddings recall for the relevant few) — for FINDING, never counting
+ * @fails returns matched bodies only and CANNOT count (the completeness guard blocks a "how many" ask before it is offered); a dead window yields nothing, never a fabricated hit.
+ * @example
+ *   const tool = buildSearchTool(litectx, { n: 8 });
+ *   await recurse(task, ctx, { retrieval: 'search', tools: [tool] });
  */
 export function buildSearchTool(litectx: {
     recall: Function;
@@ -114,6 +120,11 @@ export function buildSearchTool(litectx: {
  * OFF to stay exact — deferred; the code-side filter is the embeddings-free path shipped now.)
  * @param {Slice[]} corpus - The validated slice-source.
  * @returns {ToolDef}
+ * @when you want an embeddings-free, exact AND-term filter handle over a slice-source — complete over its slices, for precise lexical matches
+ * @fails only as good as a lexical rule; complete over the slices it is given (no recall cap) but matches nothing outside them.
+ * @example
+ *   const tool = buildExactTool(corpus);
+ *   await recurse(task, ctx, { retrieval: 'exact', tools: [tool] });
  */
 export function buildExactTool(corpus: Slice[]): ToolDef;
 /**
@@ -131,6 +142,11 @@ export function buildExactTool(corpus: Slice[]): ToolDef;
  *   materialized lazily on first call and cached for the tool's lifetime.
  * @param {{provider: Provider, window?: number, passes?: number, ctx?: object, onLlmResult?: Function, policy?: Function}} opts
  * @returns {ToolDef}
+ * @when you need the complete count/"all" path — scan every slice + LLM-judge + code-count — the only retrieval mode that can honestly answer "how many"
+ * @fails a dead window surfaces as `INCOMPLETE — the count is a floor`, never a clean number over a hole; a governance HaltError propagates clean.
+ * @example
+ *   const tool = buildScanTool(corpus, { provider, window: 8 });
+ *   await recurse('how many mention X', ctx, { tools: [tool] });
  */
 export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts: {
     provider: Provider;
@@ -154,6 +170,12 @@ export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts:
  * @param {{enumerate: Function}} litectx
  * @param {{kind?: 'fact'|'episode', pageSize?: number}} [opts]
  * @returns {() => Promise<Slice[]>}
+ * @category integration
+ * @when you want a resident slice-source that paginates a litectx corpus via enumerate — for a corpus ALREADY in litectx, feeding scan/partition
+ * @fails never ingests a fresh corpus (strictly worse than scanning an in-hand array); returns an async source materialized once and cached.
+ * @example
+ *   const corpus = litectxCorpus(litectx, { kind: 'fact' });
+ *   await recurse(task, ctx, { mode: 'partition', corpus });
  */
 export function litectxCorpus(litectx: {
     enumerate: Function;

package/src/recurse-retrieval.js

@@ -188,6 +188,12 @@ function normalizeCorpus(corpus) {
  * @param {{recall: Function}} litectx
  * @param {{kinds?: string[], n?: number}} [opts]
  * @returns {ToolDef}
+ * @category integration
+ * @when you want to give a recurse worker a needle-search handle over litectx (embeddings recall for the relevant few) — for FINDING, never counting
+ * @fails returns matched bodies only and CANNOT count (the completeness guard blocks a "how many" ask before it is offered); a dead window yields nothing, never a fabricated hit.
+ * @example
+ *   const tool = buildSearchTool(litectx, { n: 8 });
+ *   await recurse(task, ctx, { retrieval: 'search', tools: [tool] });
  */
 function buildSearchTool(litectx, opts = {}) {
   const kinds = Array.isArray(opts.kinds) && opts.kinds.length ? opts.kinds : ['fact', 'episode'];
@@ -224,6 +230,11 @@ function buildSearchTool(litectx, opts = {}) {
  * OFF to stay exact — deferred; the code-side filter is the embeddings-free path shipped now.)
  * @param {Slice[]} corpus - The validated slice-source.
  * @returns {ToolDef}
+ * @when you want an embeddings-free, exact AND-term filter handle over a slice-source — complete over its slices, for precise lexical matches
+ * @fails only as good as a lexical rule; complete over the slices it is given (no recall cap) but matches nothing outside them.
+ * @example
+ *   const tool = buildExactTool(corpus);
+ *   await recurse(task, ctx, { retrieval: 'exact', tools: [tool] });
  */
 function buildExactTool(corpus) {
   const slices = normalizeCorpus(corpus);
@@ -269,6 +280,11 @@ function buildExactTool(corpus) {
  *   materialized lazily on first call and cached for the tool's lifetime.
  * @param {{provider: Provider, window?: number, passes?: number, ctx?: object, onLlmResult?: Function, policy?: Function}} opts
  * @returns {ToolDef}
+ * @when you need the complete count/"all" path — scan every slice + LLM-judge + code-count — the only retrieval mode that can honestly answer "how many"
+ * @fails a dead window surfaces as `INCOMPLETE — the count is a floor`, never a clean number over a hole; a governance HaltError propagates clean.
+ * @example
+ *   const tool = buildScanTool(corpus, { provider, window: 8 });
+ *   await recurse('how many mention X', ctx, { tools: [tool] });
  */
 function buildScanTool(corpus, opts) {
   /** @type {Slice[]|null} */
@@ -337,6 +353,12 @@ const ENUM_PAGE = 200;
  * @param {{enumerate: Function}} litectx
  * @param {{kind?: 'fact'|'episode', pageSize?: number}} [opts]
  * @returns {() => Promise<Slice[]>}
+ * @category integration
+ * @when you want a resident slice-source that paginates a litectx corpus via enumerate — for a corpus ALREADY in litectx, feeding scan/partition
+ * @fails never ingests a fresh corpus (strictly worse than scanning an in-hand array); returns an async source materialized once and cached.
+ * @example
+ *   const corpus = litectxCorpus(litectx, { kind: 'fact' });
+ *   await recurse(task, ctx, { mode: 'partition', corpus });
  */
 function litectxCorpus(litectx, opts = {}) {
   const kind = opts.kind === 'episode' ? 'episode' : 'fact'; // enumerate v1 is the memory axis (fact/episode)

package/src/recurse.d.ts

@@ -604,5 +604,11 @@ export type Slice = {
  * @returns {Promise<RecurseResult>} `{ result, verdict, receipts }` on convergence; `{ incomplete, best,
  *   receipts }` on guard exhaustion. NEVER a fabricated success (RC-9).
  * @throws {Error} no provider supplied (on neither `ctx.provider` nor `opts.provider`).
+ * @when a task is too big for one model pass and you want it split, fanned out, verified, and merged — with total cost capped by a gate
+ * @fails returns `{incomplete, best}` on guard exhaustion or a dead worker (never a faked pass); a gate HaltError exits clean. Cost is open by design — run under a budget gate.
+ * @example
+ *   const ctx = wireGate(gate);
+ *   const { result, incomplete } = await recurse('audit 400 logs', ctx, { provider, corpus });
+ *   if (incomplete) retryOrEscalate(result);
  */
 export function recurse(task: string, ctx?: RecurseCtx, opts?: RecurseOptions): Promise<RecurseResult>;

package/src/recurse.js

@@ -395,6 +395,12 @@ function auditSafeCtx(ctx, overrides = {}) {
  * @returns {Promise<RecurseResult>} `{ result, verdict, receipts }` on convergence; `{ incomplete, best,
  *   receipts }` on guard exhaustion. NEVER a fabricated success (RC-9).
  * @throws {Error} no provider supplied (on neither `ctx.provider` nor `opts.provider`).
+ * @when a task is too big for one model pass and you want it split, fanned out, verified, and merged — with total cost capped by a gate
+ * @fails returns `{incomplete, best}` on guard exhaustion or a dead worker (never a faked pass); a gate HaltError exits clean. Cost is open by design — run under a budget gate.
+ * @example
+ *   const ctx = wireGate(gate);
+ *   const { result, incomplete } = await recurse('audit 400 logs', ctx, { provider, corpus });
+ *   if (incomplete) retryOrEscalate(result);
  */
 async function recurse(task, ctx = {}, opts = {}) {
   if (typeof task !== 'string' || task.length === 0) {

package/src/refine.d.ts

@@ -98,5 +98,10 @@ export type RefineOutcome = {
  *
  * @param {RefineOptions} options
  * @returns {Promise<RefineOutcome>}
+ * @when you have a caller-supplied attempt + evaluate pair and want to iterate generate → grade → regenerate until it passes or hits a bound
+ * @fails returns the last outcome on maxIterations or a terminal `failed` verdict (never a faked pass); a HaltError from either callback propagates clean.
+ * @example
+ *   const { result, passed } = await refine({ attempt, evaluate, maxIterations: 3 });
+ *   if (!passed) escalate(result);
  */
 export function refine(options: RefineOptions): Promise<RefineOutcome>;