@warlock.js/ai 4.2.11 → 4.3.0

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: ai-basics
-description: 'Start with @warlock.js/ai — provider-agnostic core for agents / tools / workflows / supervisors. 4-primitive ladder (agent → workflow → supervisor → orchestrator v2). Every primitive returns {data, error, usage, report}. Triggers: `ai.agent`, `ai.tool`, `ai.workflow`, `ai.supervisor`, `ai.systemPrompt`, `ExecuteResult`, `BaseReport`, `AIError`; ''which AI primitive do I use'', ''what is warlock ai'', ''pick an AI skill''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent details — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain`, `llamaindex`, `ai` (Vercel SDK); raw `openai` / `@anthropic-ai/sdk`.'
+description: 'Start with @warlock.js/ai — provider-agnostic core for agents / tools / workflows / supervisors / orchestrators. 4-primitive ladder (agent → workflow → supervisor → orchestrator, all shipped) plus planner, memory, stores, DX helpers, and the optional @warlock.js/ai-panoptic observability sidecar. Every primitive returns {data, error, usage, report}. Triggers: `ai.agent`, `ai.tool`, `ai.workflow`, `ai.supervisor`, `ai.orchestrator`, `ai.planner`, `ai.memory`, `ai.systemPrompt`, `ExecuteResult`, `BaseReport`, `AIError`, `panoptic`; ''which AI primitive do I use'', ''what is warlock ai'', ''pick an AI skill'', ''how do I observe / trace AI runs''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent details — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain`, `llamaindex`, `ai` (Vercel SDK); raw `openai` / `@anthropic-ai/sdk`.'
 ---
 
 # AI foundations
@@ -23,10 +23,12 @@ Provider-agnostic core for building AI primitives in TypeScript. Adapters live i
 ai.agent()        →  single task, stateless                    [shipped]
 ai.workflow()     →  static predefined steps, resumable        [shipped]
 ai.supervisor()   →  multi-agent dynamic routing, resumable    [shipped]
-ai.orchestrator() →  stateful — owns session/history/ctx       (v2)
+ai.orchestrator() →  durable session — state/history/resume    [shipped]
 ```
 
-Each primitive is an escape hatch to the next level of complexity. Users start low, graduate upward only when needed. Every primitive returns the same result envelope — canonical destructure `{ data, error, usage, report }` (the shared `BaseResult` guarantees `usage` + optional `error`; each primitive adds `data` + `report`). Workflows and supervisors expose `.asTool()` so an agent can call them inside its tool loop; compose freely.
+Each primitive is an escape hatch to the next level of complexity. Users start low, graduate upward only when needed. Every primitive returns the same result envelope — canonical destructure `{ data, error, usage, report }` (the shared `BaseResult` guarantees `usage` + optional `error`; each primitive adds `data` + `report`). Workflows, supervisors, and orchestrators expose `.asTool()` so an agent can call them inside its tool loop; raw executables also auto-adapt when dropped into an agent's `tools: []`. Compose freely.
+
+Beyond the ladder: `ai.planner()` (LLM-generated plans), `ai.memory()` (working + semantic + episodic + procedural recall), `ai.batch()` / `ai.fallbackModel()` / `ai.router()` / `ai.fanOut()` (DX helpers), `agent.eval()` (scoring), and the `ai.checkpoint.*` / `ai.snapshot.*` orchestrator stores.
 
 ## Foundations
 
@@ -69,12 +71,18 @@ console.log(text, usage.total, report.duration);
 | `ai.systemPrompt()` / `ai.persona()` / `ai.instruction()` — composable prompts with placeholders | [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) |
 | `ai.workflow({...})` — durable resumable pipelines with steps, routing, retry | [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) |
 | `ai.supervisor({...})` — multi-intent routing, fan-out, evaluate loops | [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) |
+| `ai.orchestrator({...})` — durable stateful sessions, drift, compaction, resume | [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) |
+| `ai.planner({...})` — LLM-generated plans over registered capabilities | [`@warlock.js/ai/run-planner/SKILL.md`](@warlock.js/ai/run-planner/SKILL.md) |
+| `ai.memory({...})` — working + semantic + episodic + procedural recall for agents / sessions | [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md) |
+| `ai.checkpoint.*` / `ai.snapshot.*` — orchestrator session + run stores | [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md) |
+| DX helpers — `batch` / `fallbackModel` / `eval` + matchers / SLO contracts / `fromFile` | [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md) |
 | `sdk.embedder({...})` — text-to-vector for RAG tools, vector ingest | [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) |
-| Agent middleware — `budget` / `guardrail` / `semanticCache` + custom hooks | [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) |
+| Agent + supervisor middleware — `budget` / `guardrail` / `semanticCache` + custom hooks | [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) |
 | Snapshot resume + semantic cache via `@warlock.js/cache` | [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) |
 | Configuring framework logging | [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md) |
-| `AIError` hierarchy, `error.code` / `error.category`, retry patterns | [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) |
-| Choosing a provider adapter (OpenAI / OpenRouter / Anthropic / Bedrock / Ollama) | [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) |
+| `AIError` hierarchy, `error.code` / `error.category`, retry patterns (incl. `ORCHESTRATOR_*` / `PLANNER_*` families) | [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) |
+| Provider adapters + cost truth (pricing / cache + reasoning tokens / capabilities) | [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) |
+| Observability — `panoptic()` subscriber, queryable trace store, OTEL / Langfuse / console / file exporters | [`@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md) |
 
 ## Package layout
 
@@ -85,8 +93,11 @@ console.log(text, usage.total, report.duration);
 @warlock.js/ai-bedrock       — AWS Bedrock adapter (Converse API + Titan embeddings)
 @warlock.js/ai-google        — Google / Gemini adapter (@google/genai + batch embeddings)
 @warlock.js/ai-ollama        — Ollama adapter for local models
+@warlock.js/ai-panoptic      — observability sidecar: panoptic() subscriber → collector → queryable trace store + console / file / OTEL / Langfuse exporters
 ```
 
+The observability sidecar is OPTIONAL and lives in its own package — it subscribes to the report tree every primitive already emits, so you wire `panoptic(...)` once and never touch primitive code. Load [`@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md`](@warlock.js/ai-panoptic/observe-with-panoptic/SKILL.md) for collecting / querying traces and [`@warlock.js/ai-panoptic/export-traces/SKILL.md`](@warlock.js/ai-panoptic/export-traces/SKILL.md) for OTEL / Langfuse / console / file exporters.
+
 Runtime deps: `@warlock.js/cache` (persistence), `@warlock.js/logger` (logging), `@warlock.js/seal` (recommended schema lib).
 
 ## When NOT to use this skill
@@ -103,11 +114,195 @@ Runtime deps: `@warlock.js/cache` (persistence), `@warlock.js/logger` (logging),
 - `domains/ai/conventions/errors.md` — framework-vs-consumer-app error split
 
 
+## ai-dx-helpers  `@warlock.js/ai/ai-dx-helpers/SKILL.md`
+
+---
+name: ai-dx-helpers
+description: 'Developer-experience helpers across @warlock.js/ai — ai.batch (fan-out an executable over a dataset w/ concurrency + per-item retry), ai.fallbackModel (ordered model failover), agent.eval + ai.eval scorers + Vitest matchers (registerAiMatchers / toRouteTo / toConverge / toPassStep / toOutputShape) + ai.mockRouter, SLO/cost budget contracts (ai.middleware.budget({contract}) + readBudgetFallbackSignal), supervisor-level middleware, ai.systemPrompt.fromFile, and auto-adapt executables in tools:[]. Triggers: `ai.batch`, `BatchResult`, `ai.fallbackModel`, `FallbackModelContract`, `agent.eval`, `ai.eval`, `EvalReport`, `EvalScorer`, `ai.eval.judge`, `registerAiMatchers`, `toRouteTo`, `toConverge`, `toPassStep`, `toOutputShape`, `ai.mockRouter`, `MockSDK`, `mockAgent`, `budget({contract})`, `BudgetContract`, `maxLatencyMs`, `onViolation`, `readBudgetFallbackSignal`, `supervisor middleware`, `systemPrompt.fromFile`; ''run an agent over a list'', ''fail over to a backup model'', ''evaluate / score an agent'', ''SLO budget'', ''test a supervisor without an LLM'', ''prompt from a file''; typical import `import { ai } from "@warlock.js/ai"`. Skip: core agent lifecycle — `@warlock.js/ai/run-ai-agent/SKILL.md`; the budget/guardrail/semanticCache basics — `@warlock.js/ai/attach-ai-middleware/SKILL.md`; competing libs `promptfoo`, `langsmith`.'
+---
+
+# DX helpers — batch, fallback, eval, SLO, supervisor middleware
+
+A grab-bag of additive 4.3.0 helpers. Each is independent — load the section you need.
+
+## `ai.batch(executable, items, options?)` — fan-out a dataset
+
+Runs the SAME executable (agent / workflow / supervisor / tool — anything `ExecutableContract`) N times, once per item, with bounded concurrency and per-item retry. Aggregates into the unified `ExecuteResult` envelope so a batch slots into cost dashboards exactly like a single run.
+
+```ts
+const result = await ai.batch(summarizer, articles, {
+  concurrency: 4,                                   // default = items.length (all at once); <=0 → serial
+  retry: { attempts: 3, backoff: "exponential" },   // workflow RetryConfig, applied per item
+  onItem: (item) => log.info("batch", "item", "settled", { index: item.index }),
+  signal: AbortSignal.timeout(120_000),
+  sessionId: "ingest-2026-06-19",                   // lineage onto every child report
+  name: "summarize-articles",
+});
+
+console.log(`${result.report.succeeded}/${result.report.total} ok`);
+console.log(`${result.usage.total} tokens total`);
+
+for (const item of result.items) {
+  if (item.status === "completed") console.log(item.index, item.result?.data);
+  else console.warn(item.index, item.error?.code, "after", item.attempts, "attempts");
+}
+```
+
+**Isolation.** Items are independent — one item's failure (after its retries) never cancels a sibling, and **the batch never rejects as a whole** (`result.error` stays undefined). Failures live on each `BatchItemResult` (`status: "completed" | "failed" | "cancelled"`, `error`, `attempts`). `result.data` is the positional array of successful items' `.data` with `undefined` in failed/cancelled slots. Usage rolls up bottom-up (batch has zero own cost); each item's report attaches under `report.children[]` in original order. An `onItem` throw is swallowed — a progress hook never breaks the batch.
+
+## `ai.fallbackModel(models, options?)` — ordered model failover
+
+A drop-in `ModelContract` that wraps an ordered list and advances to the next model only on a **transient** provider error.
+
+```ts
+const model = ai.fallbackModel([
+  ai.openai.model({ name: "gpt-4o" }),
+  ai.anthropic.model({ name: "claude-3-5-sonnet" }),
+]);
+
+const agent = ai.agent({ model });   // hand it anywhere a model goes
+
+// custom retry predicate or code list:
+ai.fallbackModel([primary, backup], { retryOn: ["PROVIDER_RATE_LIMIT", "PROVIDER_TIMEOUT"] });
+ai.fallbackModel([primary, backup], { retryOn: (error) => error instanceof ProviderError });
+```
+
+Default retryable codes: `PROVIDER_RATE_LIMIT`, `PROVIDER_TIMEOUT`, `PROVIDER_ERROR`. Auth / invalid-request / context-length / content-filter re-throw immediately (they'd fail identically downstream — retrying only burns budget). Identity/capabilities/pricing front the primary model. Usage aggregates across attempted models. Inspect `model.lastAttempts` for the failed models of the most recent call.
+
+**Streaming caveat:** `stream()` can only fail over while no chunk has been emitted yet — once the first `delta` / `tool-call` reaches the consumer, a mid-stream failure propagates instead of restarting. It advances *instantly* (no backoff) — pair with a backoff middleware if you want delay.
+
+## `agent.eval(options)` + `ai.eval.*` scorers — evaluate an agent
+
+Run a suite of cases through `agent.execute()` and score each.
+
+```ts
+const report = await myAgent.eval({
+  cases: [
+    { name: "capital", input: "Capital of Egypt?", expected: "Cairo" },
+    { name: "tone", input: "Comfort an upset user." },          // judge-scored
+  ],
+  scorers: [ai.eval.contains()],                                 // default scorers for cases w/o their own
+  judge: { agent: judgeAgent, rubric: "Score 1.0 only if empathetic." },  // LLM-as-judge fallback
+  passThreshold: 0.5,                                            // default
+  onFailure: (caseResult) => snapshot(caseResult),
+});
+
+expect(report.passed).toBe(true);   // true only when EVERY case passed
+report.passRate; report.meanScore; report.cases;   // drill-down
+```
+
+Built-in scorers on `ai.eval.*`: `exact()` (trimmed, case-insensitive; structured compared by canonical JSON), `contains()` (substring), `predicate(fn)` (arbitrary boolean assertion), `judge(config)` (LLM-as-judge). Scorer precedence per case: the case's own `scorers` → suite `scorers` → synthesized judge. A case with NONE throws at author time. A case passes only when the agent did not error AND every scorer passed.
+
+## Vitest matchers + `ai.mockRouter` — test report trees
+
+```ts
+import { registerAiMatchers } from "@warlock.js/ai";
+registerAiMatchers();   // once per test file (idempotent)
+
+expect(await supervisor.execute(input)).toRouteTo("critic");        // dispatched the named intent
+expect(await supervisor.execute(input)).toConverge();               // terminated cleanly on own decision
+expect(await workflow.execute(input)).toPassStep("draft");          // named step completed
+expect(await agent.execute(input, { output: schema })).toOutputShape(schema);  // data validates
+```
+
+The pure verdict functions (`matchConverge`, `matchOutputShape`, `matchPassStep`, `matchRouteTo`) and `AiMatchers` ship eagerly with no `vitest` coupling; only `registerAiMatchers` lazily imports `vitest` (a devDependency), so importing `@warlock.js/ai` in production never pulls in `vitest`.
+
+`ai.mockRouter(decisions, options?)` builds a deterministic `route` callback that replays a canned sequence — one decision per supervisor iteration — for testing supervisors without an LLM router:
+
+```ts
+import { END } from "@warlock.js/ai";
+
+ai.supervisor({
+  name: "draft-then-review",
+  intents: { writer, critic },
+  route: ai.mockRouter(["writer", "critic", END]),
+});
+
+// branch on state, repeat the last decision until done:
+ai.mockRouter(["research", (ctx) => (ctx.state.summary ? END : "research")], { onExhausted: "repeat" });
+```
+
+A decision is a literal `Next` (intent name / fan-out array / `END`) or a predicate over the live `RouteContext`. On exhaustion: `"end"` (default — terminate), `"throw"` (test failure), `"repeat"` (replay last). For a scripted LLM, use `MockSDK` (script the model output) and `mockAgent({ name, responses })` for fixed-response capabilities.
+
+## SLO / cost budget contracts — `ai.middleware.budget({ contract })`
+
+On top of the legacy `maxTokens` / `maxCostUSD` caps, declare a run-level SLO as data, with one global reaction:
+
+```ts
+const guard = ai.middleware.budget({
+  pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+  contract: {
+    maxCostUSD: 0.05,
+    maxLatencyMs: 8_000,        // wall-clock from first execute.before to each trip.after
+    maxTokens: 40_000,
+    onViolation: "fallback",    // "abort" (default) hard-stops; "fallback" records a signal + continues
+    fallback: (violation) => routeToCheaperModel(violation.dimension),
+  },
+});
+```
+
+Every clause is optional (a contract with no caps is inert). `onViolation: "abort"` throws `BudgetExceededError` at the next trip boundary; `"fallback"` does NOT abort — it records a typed `BudgetContractViolation` and fires `fallback`, letting the run continue (the middleware can't itself swap models). A latency breach has no `BudgetUnit` — its numbers surface via the error's `context.dimension`. `maxCostUSD` still needs a `pricing` entry for the running model or it degrades silently.
+
+Read a recorded fallback signal in an outer middleware's `execute.after`:
+
+```ts
+import { readBudgetFallbackSignal } from "@warlock.js/ai";
+
+const signal = readBudgetFallbackSignal(ctx.state);   // pass the middleware name as 2nd arg if non-default
+if (signal?.dimension === "cost") await rerunOnCheaperModel();
+```
+
+## Supervisor-level middleware
+
+The `middleware: AgentMiddleware[]` array on `ai.supervisor({...})` fires each middleware's optional `supervisor` hook map (`before` / `after` / `onError`) ONCE around the entire `execute()` / `stream()` / `resume()` run — the supervisor-level peer of an agent's `execute`-level middleware.
+
+```ts
+ai.supervisor({ name: "support", router, intents, middleware: [auditTrail] });
+```
+
+Same onion semantics as the agent pipeline: `before` runs top-down (return a `SupervisorResult` to short-circuit, throw to abort), `after` / `onError` run bottom-up. A middleware without a `supervisor` hook map is skipped — so the same builtin objects (budget, guardrail, …) can be registered on agents AND on the supervisor, each declaring whichever level applies. Each needs a unique `name` (its `ctx.state` namespace).
+
+## `ai.systemPrompt.fromFile(path)`
+
+Build a system prompt by reading a file **once, synchronously, at construction** — the file's UTF-8 contents seed one instruction block, so placeholders inside resolve at `resolve()` time and the result forks with further `.persona()` / `.instruction()` calls.
+
+```ts
+const prompt = ai.systemPrompt.fromFile("./prompts/support-agent.md");
+const localized = prompt.instruction("Respond in {{language|English}}.");
+localized.resolve({ language: "Arabic" });
+```
+
+One-shot by design (never re-read on `resolve()`). Throws `InvalidRequestError` when the file can't be read — a typo in the path fails loudly at construction instead of producing an empty prompt. `SystemPrompt.fromFile(path)` and `ai.systemPrompt.fromFile(path)` are identical.
+
+## Auto-adapt executables in `tools: []`
+
+An agent's `tools` array accepts a raw executable primitive (`AgentContract` / `WorkflowInstance` / `SupervisorContract` / orchestrator) directly — it is auto-adapted into a `ToolContract` at factory time. The tool manifest is derived from the executable's `name` + `description` + (optional) `inputSchema`; dispatch flows through its `execute()`.
+
+```ts
+const support = ai.supervisor({ name: "support", inputSchema: v.object({ message: v.string() }), router, intents });
+
+const concierge = ai.agent({
+  model,
+  tools: [support, billingWorkflow, lookupTool],   // no .asTool() needed
+});
+```
+
+`.asTool()` still works and takes precedence when you need a custom name / schema per use. For a supervisor/orchestrator, declaring `inputSchema` on the config is what lets it drop straight into `tools: []`.
+
+## See also
+
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — `agent.eval`, `tools: []`, the agent the helpers wrap
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — `ai.router` / `ai.fanOut` / supervisor `middleware` / `mockRouter`
+- [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — budget / guardrail / semanticCache basics
+- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — `systemPrompt.fromFile` in context
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — `fallbackModel` wraps these adapters; cost-truth tokens
+
+
 ## attach-ai-middleware  `@warlock.js/ai/attach-ai-middleware/SKILL.md`
 
 ---
 name: attach-ai-middleware
-description: 'Wire agent middleware — ai.middleware.budget (token / USD caps), ai.middleware.guardrail (pre / post content checks), ai.middleware.semanticCache (exact + vector cache), plus authoring custom hooks (execute / trip / tool). Triggers: `ai.middleware.budget`, `ai.middleware.guardrail`, `ai.middleware.semanticCache`, `ai.middleware.compose`, `ai.middleware.forTool`, `AgentMiddleware`, `BudgetExceededError`, `GuardrailViolationError`; ''cap token cost'', ''block pii in prompts'', ''semantic cache before LLM'', ''write custom hook''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent lifecycle — `@warlock.js/ai/run-ai-agent/SKILL.md`; cache drivers — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `langchain` callbacks.'
+description: 'Wire agent middleware — ai.middleware.budget (token / USD caps + SLO/cost contract w/ maxLatencyMs + onViolation fallback), ai.middleware.guardrail (pre / post content checks), ai.middleware.semanticCache (exact + vector cache), supervisor-level middleware, plus authoring custom hooks (execute / trip / tool). Triggers: `ai.middleware.budget`, `ai.middleware.guardrail`, `ai.middleware.semanticCache`, `ai.middleware.compose`, `ai.middleware.forTool`, `AgentMiddleware`, `BudgetExceededError`, `GuardrailViolationError`, `BudgetContract`, `maxLatencyMs`, `onViolation`, `readBudgetFallbackSignal`, `supervisor middleware`; ''cap token cost'', ''SLO budget'', ''block pii in prompts'', ''semantic cache before LLM'', ''supervisor-level middleware'', ''write custom hook''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent lifecycle — `@warlock.js/ai/run-ai-agent/SKILL.md`; cache drivers — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `langchain` callbacks.'
 ---
 
 # Middleware — agent-level pipeline
@@ -160,6 +355,25 @@ Breach → `BudgetExceededError` on `result.error`. Inspect `error.unit` (`"toke
 
 USD only fires when both `maxCostUSD` AND a matching `pricing[modelName]` entry exist.
 
+### SLO / cost contract — `budget({ contract })`
+
+On top of the legacy caps, declare a run-level SLO as data with one global reaction. Adds a wall-clock `maxLatencyMs` dimension:
+
+```ts
+ai.middleware.budget({
+  pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+  contract: {
+    maxTokens: 40_000,
+    maxCostUSD: 0.05,
+    maxLatencyMs: 8_000,        // wall-clock, first execute.before → each trip.after
+    onViolation: "fallback",    // "abort" (default) throws; "fallback" records a signal + continues
+    fallback: (violation) => routeToCheaperModel(violation.dimension),
+  },
+});
+```
+
+Every clause optional (no caps = inert). `"fallback"` can't itself swap models — it records a typed `BudgetContractViolation` and fires `fallback`; an outer layer reads it via `readBudgetFallbackSignal(ctx.state)` and degrades the next run. A latency breach has no `BudgetUnit` — read its numbers from the thrown error's `context.dimension`. Full coverage in [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md).
+
 ## `ai.middleware.guardrail(options)`
 
 Pre / post content checks.
@@ -278,11 +492,21 @@ const scoped = ai.middleware.forTool(["paid_api", "expensive_db"], toolRateLimit
 - **`name` must be unique** across an agent's middleware array.
 - **Middleware state does NOT cross `agent.execute()` boundaries.** One execute → one fresh `ctx.state`.
 
-## Workflow + middleware — what works today (v1)
+## Supervisor-level middleware
+
+`ai.supervisor({ middleware: [...] })` fires each middleware's optional `supervisor` hook map (`before` / `after` / `onError`) ONCE around the whole `execute()` / `stream()` / `resume()` run — the supervisor-level peer of an agent's `execute`-level middleware:
+
+```ts
+ai.supervisor({ name: "support", router, intents, middleware: [auditTrail] });
+```
+
+Same onion semantics: `before` top-down (return a `SupervisorResult` to short-circuit, throw to abort), `after` / `onError` bottom-up. A middleware WITHOUT a `supervisor` hook map is skipped — so the SAME builtin objects (budget, guardrail, …) can be registered on agents AND on the supervisor, each declaring whichever level applies. Each needs a unique `name`. See [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md).
+
+## Workflow + middleware — what works today
 
 - Inside a workflow step with `agent: myAgent` — the agent's own middleware fires normally.
 - `workflow.asTool()` called from an agent — the calling agent's `tool`-level middleware wraps the workflow.
-- Step-level / workflow-level / supervisor-level middleware does NOT exist yet.
+- Step-level / workflow-level middleware does NOT exist yet (supervisor-level DOES — see above).
 
 ## See also
 
@@ -594,7 +818,7 @@ No built-in vector store. Bring your own (pgvector / Qdrant / Pinecone / Chroma
 
 ---
 name: handle-ai-errors
-description: 'Typed AIError hierarchy with stable code strings + coarse category for retry-policy dispatch. execute() never throws — errors surface via result.error. Triggers: `AIError`, `ProviderRateLimitError`, `ProviderAuthError`, `ContextLengthExceededError`, `ContentFilterError`, `SchemaValidationError`, `ToolExecutionError`, `WorkflowDriftError`, `BudgetExceededError`, `GuardrailViolationError`, `error.code`, `error.category`; ''handle ai error'', ''retry on rate limit'', ''branch on error code'', ''build fallback ladder''; typical import `import { AIError } from "@warlock.js/ai"`. Skip: log surfacing — `@warlock.js/ai/log-ai-calls/SKILL.md`; native `try / catch` on raw `openai`.'
+description: 'Typed AIError hierarchy with stable code strings + coarse category for retry-policy dispatch. execute() never throws — errors surface via result.error (the sole exception: OrchestratorConfigError throws at construction). Triggers: `AIError`, `ProviderRateLimitError`, `ProviderAuthError`, `ContextLengthExceededError`, `ContentFilterError`, `SchemaValidationError`, `ToolExecutionError`, `WorkflowDriftError`, `SupervisorDriftError`, `SupervisorFailedError`, `SupervisorRoutingError`, `OrchestratorFailedError`, `OrchestratorDriftError`, `OrchestratorConfigError`, `OrchestratorCancelledError`, `PlannerFailedError`, `PlannerPlanInvalidError`, `PlannerCancelledError`, `BudgetExceededError`, `GuardrailViolationError`, `error.code`, `error.category`; ''handle ai error'', ''retry on rate limit'', ''branch on error code'', ''ORCHESTRATOR_DRIFT'', ''PLANNER_PLAN_INVALID'', ''build fallback ladder''; typical import `import { AIError } from "@warlock.js/ai"`. Skip: log surfacing — `@warlock.js/ai/log-ai-calls/SKILL.md`; native `try / catch` on raw `openai`.'
 ---
 
 # Typed errors — `AIError` hierarchy
@@ -685,9 +909,16 @@ AIError  (base — code, category, message, cause?, context?)
 │   └── RoutingError             WORKFLOW_INVALID_GOTO      { stepName, targetName }
 ├── SupervisorFailedError        SUPERVISOR_FAILED  (base + authoring/runtime)
 │   ├── MaxIterationsError       SUPERVISOR_MAX_ITERATIONS  { maxIterations }
-│   ├── SupervisorRoutingError   SUPERVISOR_INVALID_ROUTE
+│   ├── SupervisorRoutingError   SUPERVISOR_INVALID_ROUTE   { returned, availableKeys }
 │   ├── SupervisorCancelledError SUPERVISOR_CANCELLED       { cancelledAt, reason }
 │   └── SupervisorDriftError     SUPERVISOR_DRIFT           { savedSignature, currentSignature, runId }
+├── OrchestratorFailedError      ORCHESTRATOR_FAILED  (base — durable-session turn)
+│   ├── OrchestratorConfigError    ORCHESTRATOR_CONFIG     authoring-time, THROWS  (validation) — bad ai.orchestrator(config)
+│   ├── OrchestratorDriftError     ORCHESTRATOR_DRIFT      { savedSignature, currentSignature, sessionId } (drift) — checkpoint ≠ definition
+│   └── OrchestratorCancelledError ORCHESTRATOR_CANCELLED  { cancelledAt, sessionId, reason } (cancelled) — mid-turn abort
+├── PlannerFailedError           PLANNER_FAILED  (base — plan generation/execution)
+│   ├── PlannerPlanInvalidError    PLANNER_PLAN_INVALID    (schema) — LLM plan unparseable or names an unregistered capability
+│   └── PlannerCancelledError      PLANNER_CANCELLED       { cancelledAt, reason } (cancelled) — mid-plan abort
 ├── ProviderError                PROVIDER_ERROR  (base + catch-all)
 │   ├── ProviderRateLimitError   PROVIDER_RATE_LIMIT        { retryAfter? } — transient
 │   ├── QuotaExceededError       PROVIDER_QUOTA_EXCEEDED    — NOT retryable (billing cap)
@@ -700,7 +931,9 @@ AIError  (base — code, category, message, cause?, context?)
 └── GuardrailViolationError      GUARDRAIL_VIOLATION        { phase, reason } — from ai.middleware.guardrail
 ```
 
-> `SupervisorFailedError` doubles as the base for the supervisor family **and** the authoring-time error for bad config (e.g. `route` + `router` both set). It carries extra `SUPERVISOR_INTENT_*` / `SUPERVISOR_DISPATCH_CYCLE` codes for specific intent-validation failures.
+> `SupervisorFailedError` doubles as the base for the supervisor family **and** the authoring-time error for bad config (e.g. `route` + `router` both set). It carries extra `SUPERVISOR_INTENT_*` / `SUPERVISOR_DISPATCH_CYCLE` codes for specific intent-validation failures (`SUPERVISOR_INTENT_DESCRIPTION_REQUIRED`, `SUPERVISOR_INTENT_MIXED_DISPATCH`, `SUPERVISOR_INTENT_STREAM_AND_OUTPUT`, `SUPERVISOR_INTENT_STREAM_TO_REQUIRED`, `SUPERVISOR_INTENT_STREAM_ON_WORKFLOW`, `SUPERVISOR_DISPATCH_CYCLE`).
+
+> **Orchestrator + planner families** anchor on `OrchestratorFailedError` / `PlannerFailedError` (the `ORCHESTRATOR_*` / `PLANNER_*` code families). Both follow the never-throw rule: `orchestrator.execute()` / `resume()` / `command()` and `planner.execute()` surface failures on `result.error` with `report.status` `"failed"` / `"cancelled"`. The **one exception** is `OrchestratorConfigError` (`ORCHESTRATOR_CONFIG`) — an authoring-time misconfiguration (`iterate: true` with no resolvable `snapshotStore`, no `checkpointStore`, both `route` and `router` set, `initialAgent` absent from `intents`) that **throws synchronously at construction** so a bad definition fails fast at boot. Child-execution errors (agent / tool / provider / supervisor / workflow) flow through both primitives **unchanged** — captured on the step / turn report and surfaced on `result.error` directly, never re-wrapped into a `PLANNER_*` / `ORCHESTRATOR_*` code. On an `iterate: true` mid-turn cancel the underlying `SupervisorCancelledError` rides on `OrchestratorCancelledError.cause`.
 
 ## Error fields
 
@@ -725,9 +958,11 @@ Typed fields (`retryAfter`, `toolName`, `issues`, `stepName`, …) are first-cla
 | `ContentFilterError` | Usually **no** — the prompt itself is the issue |
 | `SchemaValidationError` | Use agent `repair: { maxAttempts }` instead |
 | `ToolExecutionError` | Depends on `cause` |
-| `WorkflowDriftError` | **No** — manual migration or `force: true` |
-| `WorkflowCancelledError` | **No** — caller-driven cancel |
-| `MaxStepsExceededError` / `RoutingError` | **No** — programmer error |
+| `WorkflowDriftError` / `SupervisorDriftError` / `OrchestratorDriftError` | **No** — manual migration or `force: true` |
+| `WorkflowCancelledError` / `SupervisorCancelledError` / `OrchestratorCancelledError` / `PlannerCancelledError` | **No** — caller-driven cancel |
+| `MaxStepsExceededError` / `RoutingError` / `SupervisorRoutingError` | **No** — programmer error |
+| `OrchestratorConfigError` | **No** — authoring-time config bug; thrown at construction |
+| `PlannerPlanInvalidError` | **No** — bad LLM plan / unregistered capability; re-prompt or fix the capability roster |
 | `BudgetExceededError` | **No** — raise the cap, split the workload |
 | `GuardrailViolationError` (`phase: "input"`) | **No** — block / sanitize at product layer |
 | `GuardrailViolationError` (`phase: "output"`) | Sometimes — re-prompt with adjusted system message |
@@ -783,6 +1018,9 @@ async function runWithFallbacks(input: string) {
 
 - [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — `AgentResult.error`
 - [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `WorkflowError` subclasses
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — `SupervisorFailedError` family + intent-validation codes
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — `OrchestratorFailedError` family + `ORCHESTRATOR_CONFIG` boot-time throw
+- [`@warlock.js/ai/run-planner/SKILL.md`](@warlock.js/ai/run-planner/SKILL.md) — `PlannerFailedError` family + `PLANNER_PLAN_INVALID`
 - [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — `ToolExecutionError` wrapping
 - [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md) — error logging
 - `domains/ai/conventions/errors.md` — framework vs app error convention
@@ -933,11 +1171,142 @@ See [`@warlock.js/logger/test-logging-code/SKILL.md`](@warlock.js/logger/test-lo
 - [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — what lands on the `error` channel
 
 
+## manage-ai-stores  `@warlock.js/ai/manage-ai-stores/SKILL.md`
+
+---
+name: manage-ai-stores
+description: 'Durable orchestrator stores — ai.checkpoint.{memory,pg,redis}() for cross-turn SESSION STATE and ai.snapshot.{memory,pg,redis}() for in-flight SUPERVISOR/WORKFLOW run state. Two distinct contracts (CheckpointStore vs SnapshotStore), dev-owned pg/redis clients (no peer dep), never-auto-migrated schema(), global defaults via ai.config({defaultCheckpointStore, defaultSnapshotStore}). Triggers: `ai.checkpoint`, `ai.snapshot`, `checkpointStore`, `snapshotStore`, `CheckpointStore`, `SnapshotStore`, `CheckpointRecord`, `checkpoint.pg`, `checkpoint.redis`, `snapshot.pg`, `snapshot.redis`, `store.schema()`, `keepSnapshots`, `defaultCheckpointStore`, `defaultSnapshotStore`, `PgClientLike`, `RedisClientLike`; ''persist orchestrator sessions'', ''wire a pg checkpoint store'', ''run the store DDL'', ''checkpoint vs snapshot''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator lifecycle — `@warlock.js/ai/run-orchestrator/SKILL.md`; cache-backed snapshot resume / semanticCache store — `@warlock.js/ai/persist-ai-data/SKILL.md`; competing libs `temporal`, `inngest`.'
+---
+
+# Orchestrator stores — checkpoint vs snapshot
+
+`ai.orchestrator()` persists through **two distinct stores** with two distinct contracts. Confusing them is the #1 wiring mistake.
+
+| Store | Contract | Persists | Keyed by | Factories |
+|---|---|---|---|---|
+| **checkpoint** | `CheckpointStore` | cross-turn SESSION STATE (one append-only row per settled turn) | `(orchestrator_name, session_id, turn_index)` | `ai.checkpoint.{memory,pg,redis}()` |
+| **snapshot** | `SnapshotStore` | in-flight internal SUPERVISOR run state (for `iterate: true` mid-turn resume) | `runId` | `ai.snapshot.{memory,pg,redis}()` |
+
+- A **checkpoint** is what lets `execute()` rehydrate a session across calls — state, `turn_index`, drift `signature`, `version`, `last_route`, compaction progress, lock metadata.
+- A **snapshot** is what lets a crashed mid-turn `iterate: true` turn resume — it round-trips the existing `SupervisorSnapshot` envelope (the same shape the supervisor's own `snapshotStore` uses).
+
+`iterate: false` orchestrators need only a `checkpointStore`. `iterate: true` needs **both**.
+
+## Wiring
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const orch = ai.orchestrator({
+  name: "support",
+  intents,
+  route,
+  iterate: true,
+  checkpointStore: ai.checkpoint.pg({ client: pgPool }),
+  snapshotStore: ai.snapshot.pg({ client: pgPool }),  // a single pg.Pool backs both
+});
+```
+
+### Global defaults
+
+```ts
+ai.config({
+  defaultCheckpointStore: ai.checkpoint.memory(),
+  defaultSnapshotStore: ai.snapshot.memory(),
+});
+```
+
+Resolution: explicit `checkpointStore` / `snapshotStore` on the config wins, else the matching `ai.config({ default… })`, else undefined. `iterate: true` with no snapshot store resolvable throws `OrchestratorConfigError` at construction.
+
+## The three drivers
+
+| Driver | Client | Durable | Cross-process | Fits |
+|---|---|---|---|---|
+| `memory()` | none | ❌ | ❌ | dev / tests / single-process; no resume across restarts |
+| `pg({ client, table?, ttl? })` | dev-supplied `pg.Pool`/`Client` | ✅ | ✅ | production with Postgres |
+| `redis({ client, prefix?, ttl? })` | dev-supplied `redis` client | ✅ | ✅ | production with Redis |
+
+`@warlock.js/ai` takes **NO peer dependency** on `pg` or `redis` — you install the client, build it, and pass it in via `{ client }` (anything matching `PgClientLike` / `RedisClientLike`). The store never opens or closes the connection. A single `pg.Pool` can back the cache, the checkpoint store, and the snapshot store at once.
+
+```ts
+import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+ai.checkpoint.pg({ client: pool, table: "warlock_orchestrator_sessions", ttl: 86_400 });
+ai.snapshot.pg({ client: pool, table: "warlock_supervisor_snapshots" });
+
+// redis
+ai.checkpoint.redis({ client: redisClient, prefix: "warlock:orchestrator", ttl: 86_400 });
+ai.snapshot.redis({ client: redisClient, prefix: "warlock:snapshot" });
+```
+
+Table / prefix names must be safe SQL identifiers (`[A-Za-z_][A-Za-z0-9_]*`) — interpolated into DDL/DML, so anything outside that subset is rejected. Defaults: pg checkpoint table `warlock_orchestrator_sessions`, pg snapshot table `warlock_supervisor_snapshots`, redis prefix `warlock:orchestrator`.
+
+## Schema is NEVER auto-migrated
+
+The framework never creates or alters tables. Each pg store exposes `schema()` returning the reference DDL — run it through YOUR migration tool once before use:
+
+```ts
+const store = ai.checkpoint.pg({ client: pool });
+await pool.query(store.schema());   // once, via your migration tooling
+```
+
+The memory and redis drivers return an empty `schema()` string (no backing table), so callers can treat `schema()` uniformly.
+
+## `CheckpointRecord` — the persisted row
+
+```ts
+type CheckpointRecord = {
+  orchestrator_name: string;          // PK segment 1
+  session_id: string;                 // PK segment 2
+  turn_index: number;                 // PK segment 3 — highest is live
+  state: unknown;                     // post-merge session accumulator (TState)
+  last_route: string | string[] | null;
+  signature: string;                  // drift fingerprint at write time
+  version: string | null;             // config.version tag — metadata only
+  summarized_through: number | null;  // exclusive turn index compaction reached
+  lock_acquired_at: string | null;    // compaction lock metadata
+  lock_expires_at: string | null;
+  saved_at: string;                   // ISO write timestamp
+};
+```
+
+Append-only from v1 — `save()` never overwrites a prior `turn_index`. `load(name, sessionId)` returns the latest row (highest `turn_index`), or `undefined` for a session the store has never seen.
+
+## Store contract methods
+
+Both stores: `load(...)`, `save(...)`, `delete(...)`, optional `list(...)`, `schema()`.
+
+- **`list(orchestratorName, prefix?)`** (checkpoint) / **`list(prefix?)`** (snapshot) — enumerate session/run ids for the production boot-drain loop. Optional: stores that can't enumerate omit it.
+- The orchestrator's **`keepSnapshots`** retention policy lives on the orchestrator config, NOT the store — the orchestrator calls the pg store's `prune()` after a successful `save` when `keepSnapshots` is a finite number; `"all"` skips pruning.
+
+## Boot-drain pattern
+
+On startup, resume any session whose last turn was interrupted mid-flight:
+
+```ts
+const sessions = await checkpointStore.list?.(orch.name) ?? [];
+for (const sessionId of sessions) {
+  await orch.resume(sessionId);   // null when nothing in flight — harmless
+}
+```
+
+## Distinct from `@warlock.js/cache` snapshot resume
+
+A bare `ai.supervisor()` / `ai.workflow()` uses a `snapshotStore` for `resume(runId)`. That `SnapshotStore` was promoted from the historical `@warlock.js/cache` `CacheDriver` path. ⚠ The CacheDriver overload is deprecated for one minor — new code wires `ai.snapshot.*` stores. See [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) for the supervisor/workflow side and the cache-backed semantic cache.
+
+## See also
+
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — the consumer of these stores
+- [`@warlock.js/ai/persist-ai-data/SKILL.md`](@warlock.js/ai/persist-ai-data/SKILL.md) — supervisor/workflow snapshot resume + the SnapshotStore migration
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `OrchestratorDriftError` / `OrchestratorConfigError`
+
+
 ## persist-ai-data  `@warlock.js/ai/persist-ai-data/SKILL.md`
 
 ---
 name: persist-ai-data
-description: 'Persistence delegated to @warlock.js/cache — workflow + supervisor snapshot resume via snapshotStore, semantic cache via vector-capable CacheDriver, global default via ai.config({defaultStore}). Covers drift detection + three recovery paths. Triggers: `ai.config`, `defaultStore`, `snapshotStore`, `wf.resume`, `supervisor.resume`, `WorkflowSnapshot`, `SupervisorSnapshot`, `WorkflowDriftError`, `SupervisorDriftError`, `force: true`; ''resume a workflow run'', ''configure snapshot store'', ''handle signature drift'', ''wire pg vector cache''; typical import `import { ai } from "@warlock.js/ai"`. Skip: cache driver catalog — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `temporal`, `inngest`.'
+description: 'Persistence delegated to @warlock.js/cache — workflow + supervisor snapshot resume via snapshotStore (4.3.0: now a SnapshotStore from ai.snapshot.*, ⚠ moved off raw CacheDriver), semantic cache + memory via vector-capable CacheDriver, global defaults via ai.config({defaultStore}) + ai.config({defaultSnapshotStore}). Covers drift detection + three recovery paths. Triggers: `ai.config`, `defaultStore`, `defaultSnapshotStore`, `snapshotStore`, `ai.snapshot`, `wf.resume`, `supervisor.resume`, `WorkflowSnapshot`, `SupervisorSnapshot`, `WorkflowDriftError`, `SupervisorDriftError`, `force: true`; ''resume a workflow run'', ''configure snapshot store'', ''handle signature drift'', ''wire pg vector cache''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator checkpoint/snapshot store factories — `@warlock.js/ai/manage-ai-stores/SKILL.md`; cache driver catalog — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `temporal`, `inngest`.'
 ---
 
 # Persistence — `@warlock.js/cache` everywhere
@@ -960,15 +1329,19 @@ description: 'Persistence delegated to @warlock.js/cache — workflow + supervis
 └──────────────┘         └────────────────────┘         └──────────────────┘
 ```
 
-## Resolution order
+## Resolution order — two separate defaults
 
 ```
-options.store ?? ai.config({ defaultStore }) ?? undefined
+// semantic cache + memory (CacheDriver):
+options.store         ?? ai.config({ defaultStore })         ?? undefined
+
+// supervisor / workflow / orchestrator snapshots (SnapshotStore):
+options.snapshotStore ?? ai.config({ defaultSnapshotStore }) ?? undefined
 ```
 
-When neither is set:
+`defaultStore` (a `CacheDriver`) and `defaultSnapshotStore` (a `SnapshotStore`) are independent — set whichever the consumer needs. When the relevant one is unset:
 - **Snapshot consumers** silently skip writes and throw on `resume()`.
-- **Semantic cache** throws at construction.
+- **Semantic cache / memory** throws at construction.
 
 ## `ai.config({ defaultStore })` — set once at boot
 
@@ -997,26 +1370,32 @@ Brute-force memory drivers carry an `O(N)` similarity scan — fine up to a few
 
 ## Snapshot resume — workflow + supervisor
 
-### Wiring
+> ⚠ **BREAKING (4.3.0): supervisor + workflow snapshot persistence moved `CacheDriver` → `SnapshotStore`.** A `snapshotStore` is now a `SnapshotStore` built with `ai.snapshot.{memory,pg,redis}()`, not a raw `cache.driver(...)`. The framework still ships a deprecated `CacheDriver` overload for ONE minor so existing wiring keeps working, but new code uses the dedicated store factories. The `defaultSnapshotStore` resolution is via `ai.config({ defaultSnapshotStore })` (a `SnapshotStore`), separate from `defaultStore` (a `CacheDriver`, still used for `semanticCache` + memory). See [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md).
+
+### Wiring (new)
 
 ```ts
-ai.config({ defaultStore: cache.driver("redis", { client }) });
+import { ai } from "@warlock.js/ai";
+
+ai.config({ defaultSnapshotStore: ai.snapshot.redis({ client }) });
 
 const wf = ai.workflow({
   name: "ticket-processor",
   steps: [...],
-  // snapshotStore optional — falls back to defaultStore
+  // snapshotStore optional — falls back to ai.config({ defaultSnapshotStore })
 });
 
 const sup = ai.supervisor({
   name: "support-team",
   router: routerAgent,
   intents: { triage, billing, resolver },
-  // explicit override when this primitive needs a different driver
-  snapshotStore: cache.driver("pg", { client: pgPool, table: "support_runs" }),
+  // explicit override when this primitive needs a different store
+  snapshotStore: ai.snapshot.pg({ client: pgPool, table: "support_runs" }),
 });
 ```
 
+The `SnapshotStore` is generic over its snapshot shape — it defaults to `SupervisorSnapshot`, and the workflow engine parameterizes it with `WorkflowSnapshot`; the only structural requirement is a `runId` string. `ai.snapshot.memory()` for dev/tests, `ai.snapshot.{pg,redis}()` for production (dev-owned client, never-auto-migrated `schema()`).
+
 ### Snapshot shapes
 
 ```ts
@@ -1137,6 +1516,7 @@ The driver must support `similar()`. Without similarity → `CacheUnsupportedErr
 
 ## See also
 
+- [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md) — `ai.snapshot.*` + `ai.checkpoint.*` store factories, schema(), drivers
 - [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `snapshotStore` + `resume()`
 - [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — same on supervisor
 - [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — `semanticCache` middleware
@@ -1148,7 +1528,7 @@ The driver must support `similar()`. Without similarity → `CacheUnsupportedErr
 
 ---
 name: pick-ai-provider
-description: 'Choose an AI provider adapter — @warlock.js/ai-openai (shipped, also handles OpenRouter / Azure via baseURL), @warlock.js/ai-anthropic, @warlock.js/ai-bedrock, @warlock.js/ai-google, @warlock.js/ai-ollama. Triggers: `OpenAISDK`, `SDKAdapterContract`, `ModelContract`, `sdk.model`, `sdk.embedder`, `capabilities.vision`, `capabilities.structuredOutput`, `pricing`, `baseURL`, `provider: "openrouter"`; ''pick a provider'', ''openai vs openrouter'', ''does this model support vision'', ''configure pricing''; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent factory — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs raw `openai`, `@anthropic-ai/sdk`, `@aws-sdk/client-bedrock-runtime`.'
+description: 'Choose an AI provider adapter — @warlock.js/ai-openai (shipped, also handles OpenRouter / Azure via baseURL), @warlock.js/ai-anthropic, @warlock.js/ai-bedrock, @warlock.js/ai-google, @warlock.js/ai-ollama — plus cost truth: ModelPricing (per-1M tokens), Usage cost breakdown, the cachedTokens / cacheWriteTokens / reasoningTokens channels, and capability flags. Triggers: `OpenAISDK`, `SDKAdapterContract`, `ModelContract`, `ModelPricing`, `ModelCapabilities`, `sdk.model`, `sdk.embedder`, `capabilities.vision`, `capabilities.structuredOutput`, `capabilities.reasoning`, `capabilities.promptCaching`, `pricing`, `Usage.cost`, `cachedTokens`, `cacheWriteTokens`, `reasoningTokens`, `reasoning.effort`, `cacheControl`, `baseURL`, `provider: "openrouter"`; ''pick a provider'', ''openai vs openrouter'', ''does this model support vision/reasoning'', ''configure pricing'', ''how much did reasoning cost'', ''prompt cache tokens''; typical import `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: agent factory — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs raw `openai`, `@anthropic-ai/sdk`, `@aws-sdk/client-bedrock-runtime`.'
 ---
 
 # Pick an AI provider adapter
@@ -1192,16 +1572,20 @@ Adapters are classes — `new OpenAISDK({ apiKey })`, `new AnthropicSDK({ apiKey
 - `count(text, model?)` — provider-appropriate token count.
 - `embedder({ name })` — text-to-vector. Optional; check `typeof sdk.embedder === "function"` before calling.
 
-The `ModelContract.capabilities` field declares what the model supports — two flags today, both optional (absent = treat as `false`):
+The `ModelContract.capabilities` field declares what the model supports — all flags optional (absent = treat as `false`):
 
 ```ts
 type ModelCapabilities = {
   structuredOutput?: boolean;   // native response_format: json_schema support?
   vision?: boolean;             // can accept image attachments?
+  reasoning?: boolean;          // forwards ModelCallOptions.reasoning (effort / thinking budget)?
+  promptCaching?: boolean;      // honors cacheControl breakpoints + reports cache token channels?
+  audio?: boolean;              // can accept audio ContentPart input?
+  pdf?: boolean;                // can accept PDF / document ContentPart input?
 };
 ```
 
-The framework reads `capabilities` to fail loud upfront — e.g. passing `attachments: [...]` to a non-vision model throws at the boundary instead of failing mid-trip.
+The framework reads `capabilities` to fail loud upfront — e.g. passing `attachments: [...]` to a non-vision model throws at the boundary instead of failing mid-trip; reasoning / cacheControl options are silently skipped when the adapter doesn't declare support, rather than sent as unsupported params.
 
 ## OpenAI adapter — usage
 
@@ -1248,23 +1632,53 @@ const customModel = openai.model({
 });
 ```
 
-## Pricing — per-channel cost breakdown
+## Cost truth — pricing + token channels
 
-Configure `pricing` on the model (or via the SDK registry) and every report carries `Usage.cost`:
+`ModelPricing` is **USD per 1,000,000 tokens** (the industry-standard unit), declared at two optional sites — `SDK.pricing` (registry keyed by model name) and `model({ pricing })` (per-model override, wins). Resolution: per-model > SDK registry > undefined (no cost computed).
 
 ```ts
-const openai = new OpenAISDK({
-  apiKey,
-  pricing: { "gpt-4o-mini": { input: 0.15, output: 0.6, cachedInput: 0.075 } },
-});
+type ModelPricing = {
+  input: number;            // required — USD / 1M input tokens
+  output: number;           // required — USD / 1M output tokens
+  cachedInput?: number;     // prompt-cache READ rate; falls back to `input`
+  cachedOutput?: number;    // cache-WRITE rate (Anthropic premium); falls back to `output`
+  reasoning?: number;       // reasoning/thinking-token rate; falls back to `output`
+};
+```
+
+Configure it and every report carries `Usage.cost` — a per-channel breakdown captured at emit time as a historical fact (stored reports stay accurate after the upstream table changes):
 
+```ts
 const { usage } = await ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) }).execute("hi");
 
-usage.cost;
-// { input: 0.0000045, output: 0.000192, cachedInput: 0.000009 }  — USD breakdown
+usage.cost;          // { input, output, cachedInput?, cachedOutput? }  — USD per channel
+// single scalar total: sum the populated fields, treating undefined as 0.
+```
+
+`usage.cost` is `undefined` when no pricing is available — honest absence over false zero. Aggregators merge only defined fields, so one unpriced child never erases a priced sibling's cost.
+
+### Token channels (`Usage`) — what each adapter reports
+
+Beyond `input` / `output` / `total`, `Usage` carries optional sub-channels (undefined when the provider doesn't meter them):
+
+| Channel | Meaning | Provider source |
+|---|---|---|
+| `cachedTokens` | subset of `input` served from prompt cache (READ hit) | OpenAI `prompt_tokens_details.cached_tokens`, Anthropic `cache_read_input_tokens` |
+| `cacheWriteTokens` | input tokens WRITTEN to the cache this call | Anthropic `cache_creation_input_tokens` (OpenAI does not write-bill) |
+| `reasoningTokens` | subset of `output` for internal reasoning/thinking | OpenAI `completion_tokens_details.reasoning_tokens`, Anthropic extended-thinking |
+
+### Driving cache + reasoning per call
+
+`ModelCallOptions` exposes vendor-neutral controls the agent forwards only when `capabilities` allows:
+
+```ts
+await model.complete(messages, {
+  reasoning: { effort: "high", maxTokens: 8_000 },  // effort → OpenAI reasoning_effort; maxTokens → Anthropic thinking budget
+  cacheControl: { breakpoints: 1 },                 // WRITE breakpoint → Anthropic cache_control markers
+});
 ```
 
-Shape mirrors `ModelPricing` — `{ input, output, cachedInput?, cachedOutput? }`. Per-model `pricing` wins over the SDK-level registry. `undefined` when no pricing configured — honest absence over false zero.
+Read-side cache accounting (`Usage.cachedTokens`) works WITHOUT `cacheControl` — it only controls WRITE placement. Adapters whose `capabilities.reasoning` / `.promptCaching` is absent ignore these rather than forwarding unsupported params.
 
 ## Embeddings
 
@@ -1316,7 +1730,7 @@ If you switch providers mid-project (e.g. OpenAI → Anthropic):
 
 ---
 name: run-ai-agent
-description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events. Triggers: `ai.agent`, `agent.execute`, `agent.stream`, `AgentResult`, `AgentReport`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''cancel an agent run''; typical import `import { ai } from "@warlock.js/ai"`. Skip: tool definition — `@warlock.js/ai/define-ai-tool/SKILL.md`; workflows — `@warlock.js/ai/run-ai-workflow/SKILL.md`; competing libs `langchain`, `ai` (Vercel), raw `openai`.'
+description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events, agent.eval scoring, and auto-adapting raw executables in tools:[]. Triggers: `ai.agent`, `agent.execute`, `agent.stream`, `agent.eval`, `AgentResult`, `AgentReport`, `AgentToolEntry`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''evaluate an agent'', ''put a supervisor in tools'', ''cancel an agent run''; typical import `import { ai } from "@warlock.js/ai"`. Skip: tool definition — `@warlock.js/ai/define-ai-tool/SKILL.md`; workflows — `@warlock.js/ai/run-ai-workflow/SKILL.md`; eval matchers / batch / fallback detail — `@warlock.js/ai/ai-dx-helpers/SKILL.md`; competing libs `langchain`, `ai` (Vercel), raw `openai`.'
 ---
 
 # `ai.agent()` — single-turn primitive
@@ -1335,7 +1749,7 @@ ai.agent({
   name?: string,                              // optional — anonymous gets a fingerprint
   model: openai.model({ name: "gpt-4o-mini" }),
   systemPrompt?: string | SystemPromptContract,
-  tools?: ToolContract<any, any>[],
+  tools?: AgentToolEntry<any, any>[],          // ToolContract OR a raw executable (auto-adapted)
   placeholders?: Record<string, unknown>,
   maxTrips?: number,                           // default 10
   modelOptions?: ModelCallOptions,
@@ -1571,6 +1985,37 @@ await myAgent.execute("go", {
 
 Every event payload carries `runId` and `rootRunId`. Same identity fields ride on stream events.
 
+## `tools: []` — auto-adapt executables
+
+Each `tools` entry is either a built `ToolContract` (from `ai.tool(...)` or an explicit `.asTool(...)`) OR a **raw executable primitive** (`AgentContract` / `WorkflowInstance` / `SupervisorContract` / orchestrator) — auto-adapted into a `ToolContract` at factory time. The manifest is derived from the executable's `name` + `description` + (optional) `inputSchema`; dispatch flows through its `execute()`.
+
+```ts
+const concierge = ai.agent({
+  model,
+  tools: [billingWorkflow, supportSupervisor, lookupTool],  // no .asTool() needed
+});
+```
+
+`.asTool()` still works and takes precedence when you need a custom name / schema per use. A supervisor/orchestrator needs `inputSchema` on its config to drop straight into `tools: []`. See [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md).
+
+## `agent.eval(options)` — score the agent against a suite
+
+```ts
+const report = await myAgent.eval({
+  cases: [
+    { name: "capital", input: "Capital of Egypt?", expected: "Cairo" },
+    { name: "tone", input: "Comfort an upset user." },          // judge-scored
+  ],
+  scorers: [ai.eval.contains()],                                 // default for cases w/o their own
+  judge: { agent: judgeAgent, rubric: "Score 1.0 only if empathetic." },  // LLM-as-judge fallback
+  passThreshold: 0.5,                                            // default
+});
+
+expect(report.passed).toBe(true);   // true only when EVERY case passed
+```
+
+Each case runs through `execute(input)`; scorer precedence is per-case `scorers` → suite `scorers` → synthesized `judge` (throws at author time if a case resolves none). Built-in scorers on `ai.eval.*`: `exact()`, `contains()`, `predicate(fn)`, `judge(config)`. Full coverage — plus the Vitest matchers (`registerAiMatchers` / `toRouteTo` / `toConverge` / `toPassStep` / `toOutputShape`) — in [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md).
+
 ## When NOT to use this primitive
 
 - Multi-step pipeline with a fixed shape → [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md)
@@ -1845,11 +2290,285 @@ Every payload carries `runId` and `rootRunId`.
 - [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `WorkflowError` subclasses
 
 
+## run-orchestrator  `@warlock.js/ai/run-orchestrator/SKILL.md`
+
+---
+name: run-orchestrator
+description: 'Durable stateful sessions with ai.orchestrator({...}) — the capstone of the 4-primitive ladder. Wraps a supervisor with cross-turn session state (checkpointStore), per-turn windowing, drift detection, post-turn compaction, mid-turn resume (iterate: true + snapshotStore), per-turn memory, typed commands, asTool, and a 3-tier event model. Triggers: `ai.orchestrator`, `orchestrator.execute`, `orchestrator.resume`, `orchestrator.command`, `orchestrator.stream`, `OrchestratorConfig`, `OrchestratorResult`, `OrchestratorReport`, `OrchestratorContract`, `CheckpointStore`, `OrchestratorDriftError`, `sessionId`, `iterate`, `historyWindow`, `summarize`, `keepSnapshots`, `awaiting-input`, `turns[]`, `TurnSnapshot`, `CompactionResult`, `initialAgent`, `checkpointStore`; ''multi-turn conversation that persists'', ''durable session across calls'', ''resume an interrupted turn'', ''compact session history'', ''per-session memory''; typical import `import { ai } from "@warlock.js/ai"`. Skip: a single routing turn with no session — `@warlock.js/ai/run-supervisor/SKILL.md`; a fixed pipeline — `@warlock.js/ai/run-ai-workflow/SKILL.md`; the store factories themselves — `@warlock.js/ai/manage-ai-stores/SKILL.md`; competing libs `langgraph`, `crewai`.'
+---
+
+# `ai.orchestrator()` — durable stateful sessions
+
+The capstone of the 4-primitive ladder. An orchestrator is a **session-state manager wrapped around a supervisor**: each `execute` / `stream` call is ONE turn against a named `sessionId`, with the session's accumulated state, drift signature, and compaction progress persisted in a `CheckpointStore` between calls. The "what runs" fields (`intents`, `route` / `router`, `evaluate`, `state`, `output`, `initialAgent`, `maxIterations`) are the supervisor's surface spread directly — the orchestrator builds the supervisor lazily per turn and delegates to it. You never see the supervisor object.
+
+## When to reach for it
+
+- **`supervisor`** — routes one input to a specialist each turn; stateless between runs unless you wire `snapshotStore`. No cross-turn session memory.
+- **`orchestrator`** — when the **session** matters: a long-running conversation where each turn must rehydrate the prior turn's state, history must be windowed/compacted, and an interrupted turn must resume after a crash.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { END } from "@warlock.js/ai";
+
+type SessionState = { category?: string; order?: { id: string }; reply?: string };
+
+const supportBot = ai.orchestrator<SessionState>({
+  name: "refund-support",
+  intents: { classify, lookup, process, compose },
+  route: (ctx) => (ctx.iteration === 0 ? "classify" : END),
+  iterate: true,                                  // delegate each turn to a real supervisor
+  historyWindow: { router: 5, agents: 20 },
+  summarize: { afterTurns: 20, keep: 6 },         // auto-compaction policy
+  keepSnapshots: 100,                             // turns retained per session
+  checkpointStore: ai.checkpoint.pg({ client: pg }),
+  snapshotStore: ai.snapshot.pg({ client: pg }),  // required when iterate: true
+});
+
+const result = await supportBot.execute(message, { sessionId: "sess_42", history });
+
+if (result.report.status === "awaiting-input") {
+  // session continues — wait for the next user turn
+}
+```
+
+`route` XOR `router` is required (mutually exclusive). `initialAgent`, when set, must be a key in `intents` and dispatches on turn 0, skipping the first route/router call. All config-shape errors throw `OrchestratorConfigError` at construction (author-time), not on the first turn.
+
+## The session is owned by `sessionId` — passed per call
+
+There is no stateful session object and no implicit "current session" — every method names the session it acts on via `options.sessionId`. `history` is **required** on every `execute` call: the framework never persists raw messages (it owns session *state*, not the message log — that is the dev's store). `state` is a partial seed/patch shallow-merged into the loaded session state; `context` is the request-scoped bag, frozen at intake.
+
+```ts
+await supportBot.execute(input, {
+  sessionId: "sess_42",       // required — names the session
+  history: priorMessages,     // required — the dev re-supplies prior turns each call
+  state: { tier: "gold" },    // partial patch shallow-merged into loaded state
+  context: { userId, db },    // request-scoped, never persisted
+  signal: AbortSignal.timeout(60_000),
+  on: { "orchestrator.turn.completed": (e) => log(e) },  // tier-3 per-call handlers
+  force: false,               // bypass drift check for this call
+});
+```
+
+## The turn lifecycle (what each turn does)
+
+1. **load** — read the latest checkpoint for `(name, sessionId)`; seed empty on first call (`orchestrator.session.loaded`).
+2. **drift check** — compare the loaded checkpoint's `signature` to the current definition (`orchestrator.drift.checked`). Mismatch throws `OrchestratorDriftError` unless `force: true`.
+3. **lock wait** — wait on the compaction lock if held (`orchestrator.lock.waiting`).
+4. **window** — slice history per `historyWindow.{router,agents}` (`orchestrator.history.windowed`).
+5. **dispatch** — `route`/`router` (or `initialAgent` on turn 0) picks the intent(s); the supervisor runs the turn (`orchestrator.turn.routed`, `orchestrator.turn.streaming`).
+6. **persist** — append a checkpoint row for the settled turn, then prune to `keepSnapshots` (`orchestrator.checkpoint.persisted`).
+7. **compaction** — fire the post-turn compaction trigger if configured (`orchestrator.compaction.suggested` / `.applied`).
+
+Terminal events: `orchestrator.turn.completed` / `.failed` / `.cancelled`, plus the non-terminal `orchestrator.turn.awaiting-input`.
+
+## `OrchestratorResult` — read the report
+
+```ts
+const result = await supportBot.execute(message, { sessionId, history });
+
+result.sessionId;                 // echoes the session this turn acted on
+result.turnIndex;                 // zero-indexed turn number
+result.data;                      // validated against `output`, if set
+result.error;                     // typed AIError — execute() never throws on runtime failure
+result.report.type;               // "orchestrator"
+result.report.status;             // ReportStatus | "awaiting-input"
+result.report.turns;              // TurnSnapshot[] — current turn + prior, bounded by keepSnapshots
+result.compaction;                // CompactionResult when a turn compacted (and no onCompact ran)
+```
+
+`report.children[]` carries ONLY the current turn's dispatched primitive reports. Full session history lives on `report.turns[]` — a `children[]` walker will NOT reach prior turns (intentional). Child `supervisor.*` / `agent.*` events bubble up unmodified under their own identity.
+
+**`awaiting-input` is the only non-terminal status across the unified result tree.** Code branching on `status === "completed"` MUST explicitly handle `"awaiting-input"` as a session-continues path, not a failure.
+
+## `iterate` — single dispatch vs. internal supervisor
+
+- **`iterate: false`** (default) — one dispatch per turn. No `snapshotStore` needed.
+- **`iterate: true`** — each turn delegates to a real internal supervisor that loops to `maxIterations` (default 10). **Requires** a `snapshotStore` (explicit or `ai.config({ defaultSnapshotStore })`) so a crashed mid-turn iteration can resume. Construction throws if you set `iterate: true` without one.
+
+## `resume()` — drain an interrupted turn
+
+```ts
+const result = await supportBot.resume("sess_42", { context: { db }, force: false });
+```
+
+Resume continues an interrupted `iterate: true` turn from its persisted supervisor snapshot. Returns `null` when there is nothing in flight for the session (a no-op for `iterate: false` orchestrators). It re-supplies request-scoped `context` (NOT persisted) and rehydrates state from the checkpoint — there is no `history` field, since it continues an in-flight turn rather than opening a fresh one. Runs the same drift check as `execute()`; throws `OrchestratorDriftError` on mismatch unless `{ force: true }`. Use the boot-drain pattern: enumerate sessions via `checkpointStore.list(name)` and `resume()` each on startup.
+
+## Compaction — `summarize`
+
+Bounds session history growth. Two forms:
+
+```ts
+// Object policy — count-based auto-fire after `afterTurns`, keep the most recent `keep`.
+summarize: {
+  afterTurns: 20,
+  keep: 6,
+  summarizer: cheapModel,                  // defaults to the orchestrator's own model
+  onCompact: async (compaction, ctx) => {  // apply to the dev's message store
+    await messages.applyCompaction(ctx.sessionId, compaction);
+  },
+  lock: { maxWait: 5_000 },
+}
+
+// Callback form — full control; NEVER auto-fires, driven only by command("compact").
+summarize: (history) => ({ summary, replacesFromIndex, replacesToIndex }),
+```
+
+A `CompactionResult` is `{ summary: Message, replacesFromIndex, replacesToIndex }` — the replacement summary plus the inclusive index range it replaces in the dev's history array. When `onCompact` is supplied the orchestrator applies it for you and does NOT surface `result.compaction`; otherwise it surfaces `result.compaction` for you to apply manually.
+
+## `command()` — typed built-ins
+
+```ts
+const compaction = await supportBot.command("compact", { sessionId, history });
+// → { summary, replacesFromIndex, replacesToIndex }
+```
+
+v1 ships exactly one built-in command, `compact` (manual compaction outside the auto-trigger; reuses the same compaction code path). User commands attach via module augmentation of `OrchestratorCommands` — declaring extra keys in your own `.d.ts` widens the typed `command<K>` surface without a framework release.
+
+## Per-turn memory — `memory`
+
+Wire an `ai.memory()` store so each turn recalls relevant memories before routing and remembers the settled outcome after:
+
+```ts
+ai.orchestrator({
+  name: "support",
+  intents,
+  route,
+  memory: mem,                                  // bare MemoryContract — recall + remember w/ defaults
+  // or finer control:
+  memory: {
+    store: mem,
+    recall: { k: 5, threshold: 0.7, tier: "semantic" },  // k: 0 = write-only memory
+    remember: true,                             // false = read-only (recall, never write)
+    rememberTier: "semantic",
+    injectKey: "memories",                      // ctx.context[injectKey] holds RecalledMemory[]
+  },
+});
+```
+
+Recalled memories land in the per-turn `context` bag under `injectKey` (default `"memories"`) — every route / router / evaluate / dispatch callback reads them at `ctx.context.memories`. Memory never mutates the prompt itself; surfacing it stays explicit. Cancelled / failed turns never remember (they revert), regardless of `remember`. See [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md).
+
+## `asTool()` — orchestrator as a tool
+
+```ts
+const supportTool = supportBot.asTool({
+  name: "handle_refund",
+  description: "Handle a refund conversation end-to-end.",
+  inputSchema: v.object({ message: v.string() }),
+  sessionScope: "fresh",   // default — each call gets a brand-new sessionId
+});
+
+const concierge = ai.agent({ model, tools: [supportTool] });
+```
+
+The tool boundary is **opaque**: the parent's `signal` / `context` / events do NOT auto-forward — anything the wrapped orchestrator needs must ride on the `inputSchema` payload. `sessionScope`:
+- **`"fresh"`** (default) — each invocation gets a generated `sessionId` and empty history; no continuity across calls.
+- **`"shared"`** — the parent threads `sessionId` (and optionally `history`) through the validated payload; the orchestrator participates in that session. A missing/blank `sessionId` throws.
+
+## Drift detection
+
+The orchestrator signature fingerprints: name + intents map + route/router presence + evaluate presence + initialAgent + maxIterations + iterate flag + historyWindow shape. It does NOT aggregate the internal supervisor's signature — internal-supervisor drift surfaces only on `iterate: true` resume via the supervisor's own drift check. On mismatch, `OrchestratorDriftError` (`code: "ORCHESTRATOR_DRIFT"`, `category: "drift"`) is thrown synchronously — nothing dispatches. Recover by discarding the session, migrating the persisted checkpoint, or passing `{ force: true }`.
+
+## 3-tier events
+
+Handlers fire definition → instance → per-call, in that order, on every emission:
+
+```ts
+const orch = ai.orchestrator({ ..., on: { "orchestrator.turn.failed": tier1 } });   // tier 1 — definition
+const off = orch.on("orchestrator.turn.completed", tier2);                          // tier 2 — instance
+await orch.execute(input, { sessionId, history, on: { "orchestrator.drift.checked": tier3 } }); // tier 3 — per-call
+```
+
+## Stores
+
+`checkpointStore` (cross-turn session state) and `snapshotStore` (internal-supervisor run state for `iterate: true`) are distinct contracts with distinct factories. See [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — the engine each turn delegates to
+- [`@warlock.js/ai/manage-ai-stores/SKILL.md`](@warlock.js/ai/manage-ai-stores/SKILL.md) — `ai.checkpoint.*` / `ai.snapshot.*`
+- [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md) — the `memory` field
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `OrchestratorDriftError` / `OrchestratorConfigError`
+
+
+## run-planner  `@warlock.js/ai/run-planner/SKILL.md`
+
+---
+name: run-planner
+description: 'Goal-driven planning with ai.planner({...}) — an LLM GENERATES an ordered execution plan over your registered capabilities (agents / workflows / supervisors / tools), then the planner EXECUTES that plan step-by-step, threading each step output into the next, and returns the unified {data, report, usage, error} envelope with report.type "planner". A plan step may delegate via ai.spawnSubAgent({...}) — a GENERAL one-shot-agent helper (a fresh agent + optional per-task budget), covered fully in `@warlock.js/ai/run-ai-agent/SKILL.md`; it is not planner-specific and the planner engine does not require it. Triggers: `ai.planner`, `planner.execute`, `spawnSubAgent`, `PlannerConfig`, `PlannerCapability`, `PlannerResult`, `PlannerReport`, `PlannerPlan`, `PlannerStep`, `maxSteps`, `report.plan`, `report.executedSteps`; ''let the model plan the steps'', ''dynamic plan from a goal'', ''decompose a goal into capability calls'', ''spawn a sub-agent for a subtask''; typical import `import { ai } from "@warlock.js/ai"`. Skip: a FIXED known pipeline — `@warlock.js/ai/run-ai-workflow/SKILL.md`; routing one input to a specialist each turn — `@warlock.js/ai/run-supervisor/SKILL.md`; a single model + tools call — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
+---
+
+# `ai.planner()` — LLM-generated, then executed, plans
+
+A planner turns a free-form **goal** into an ordered **plan** the LLM writes itself (referencing only the capabilities you registered), then runs that plan one step at a time through each capability's own `execute()`. Use it when you do NOT know the steps up front — the model decides the sequence.
+
+## When to reach for it
+
+- **`agent`** — one model + tools, single task. No multi-step decomposition.
+- **`workflow`** — a FIXED pipeline you author by hand (`steps: [...]`). The steps are known at design time.
+- **`supervisor`** — routes one input to the right specialist each turn; loops on a quality verdict.
+- **`planner`** — the steps are NOT known in advance. The LLM generates the ordered plan from the goal, then the planner executes it. Bounded v1: strictly sequential, no DAG scheduling, no mid-plan re-planning.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const research = ai.planner({
+  name: "research-assistant",
+  model: ai.openai.model({ name: "gpt-4o" }), // the plan-GENERATION brain
+  capabilities: [
+    { name: "search", description: "Search the web for sources", executable: searchAgent },
+    { name: "summarize", description: "Summarize text into bullet points", executable: summarizer },
+    { name: "write", description: "Draft a final report", executable: writerAgent },
+  ],
+  maxSteps: 6, // hard cap; steps beyond it are recorded as "skipped"
+});
+
+const { data, report, usage, error } = await research.execute("Compare React vs Vue in 2026");
+
+console.log(report.plan?.summary);          // the LLM's one-line strategy
+for (const step of report.executedSteps) {  // forensic, in execution order
+  console.log(step.step.capability, step.status);
+}
+```
+
+- `model` builds an internal planning agent with a generated plan-prompt baked on. **Mutually exclusive** with `planner`.
+- `planner` lets you bring your own fully-configured planning agent (custom prompt, middleware). The planner injects the plan schema as that agent's per-call `output`.
+- A `capability` is `{ name, description, executable }`. The `name` is what the LLM references per step; the `description` is what it reads to pick. `executable` is any `ExecutableContract` (agent / workflow / supervisor / tool).
+
+## Execution model (bounded v1)
+
+1. **Generate** — the planning agent is asked for a `{ steps, summary? }` plan via a generated schema whose `capability` field is an `enum` of your capability names.
+2. **Execute** — steps run **strictly in array order**. Each completed step's output is threaded into the next step's input as "Context from earlier steps". `dependsOn` on a step is advisory metadata only — recorded, not scheduled on.
+3. **Finalize** — when `output` is set (factory or per-call), the LAST completed step's structured output is validated into `result.data`. A capability that should feed typed output to the planner's `output` should declare its own `output` schema (the planner reads `data`, falling back to an agent's raw `text`).
+
+`report.type === "planner"`; `report.children[]` carries every dispatched capability report (plus the planning trip), with usage rolled up. Lazy capability loading is **deferred** — every capability is fully constructed up front.
+
+## Failure + cancellation
+
+`execute()` never throws — failures surface on `result.error`:
+
+- **`PlannerPlanInvalidError`** (`PLANNER_PLAN_INVALID`, category `schema`) — empty plan or a step naming an unknown capability; also a final-output validation failure.
+- **`PlannerCancelledError`** (`PLANNER_CANCELLED`, category `cancelled`) — the `AbortSignal` fired. `report.status === "cancelled"`, `report.cancelledAt` set; remaining steps are `skipped`.
+- A child capability's own error (agent / tool / provider) flows through unchanged on the failing step's snapshot and as `result.error`. The planner stops at the first failed step and marks the rest `skipped`.
+- **`PlannerFailedError`** is the base for the `PLANNER_*` family.
+
+## Delegating a step with `ai.spawnSubAgent()`
+
+A plan step can hand a bounded subtask to a fresh single-use agent with a hard spend cap via `ai.spawnSubAgent({...})`. It is **not** a planner feature — it's a general one-shot-agent helper (a fresh `ai.agent()` + an optional per-task `budget`, run once) that works identically inside a tool, a workflow step, a supervisor intent, or hand-rolled orchestration. The planner engine never calls it; it's simply a primitive a capability *you* write can reach for. Full coverage: [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md).
+
+## Testing
+
+Use `MockSDK` for the planning model — script the plan as a JSON string matching `{ steps, summary? }`. Capabilities can be `mockAgent({ name, responses })`. See `src/planner/planner.spec.ts`.
+
+
 ## run-supervisor  `@warlock.js/ai/run-supervisor/SKILL.md`
 
 ---
 name: run-supervisor
-description: 'Multi-intent routing with ai.supervisor({...}) — classifier (iter-0 dispatch), router agent OR route callback, intents as agents / workflows / callbacks, fan-out, evaluate quality loop, ack receptionist. Triggers: `ai.supervisor`, `supervisor.execute`, `supervisor.resume`, `intents`, `router`, `route`, `classifier`, `evaluate`, `ack`, `artifactsSchema`, `END`, `ctx.intents.X.execute`; ''route one input across specialists'', ''multi-intent dispatch'', ''fan-out then evaluate'', ''classifier then router''; typical import `import { ai } from "@warlock.js/ai"`. Skip: fixed pipelines — `@warlock.js/ai/run-ai-workflow/SKILL.md`; single agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
+description: 'Multi-intent routing with ai.supervisor({...}) — classifier (iter-0 dispatch), router agent OR route callback, intents as agents / workflows / callbacks, fan-out, evaluate quality loop, ack receptionist, supervisor-level middleware. Triggers: `ai.supervisor`, `ai.router`, `ai.fanOut`, `supervisor.execute`, `supervisor.resume`, `intents`, `router`, `route`, `classifier`, `evaluate`, `ack`, `artifactsSchema`, `middleware`, `END`, `ctx.intents.X.execute`; ''route one input across specialists'', ''multi-intent dispatch'', ''fan-out then evaluate'', ''classifier then router'', ''supervisor middleware'', ''self-consistency / voting''; typical import `import { ai } from "@warlock.js/ai"`. Skip: durable multi-turn sessions — `@warlock.js/ai/run-orchestrator/SKILL.md`; fixed pipelines — `@warlock.js/ai/run-ai-workflow/SKILL.md`; single agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langgraph`, `crewai`.'
 ---
 
 # `ai.supervisor()` — multi-intent routing
@@ -1861,7 +2580,7 @@ A supervisor takes one input, picks which intent(s) handle it, runs them, option
 - **`agent`** — one model + tools, single task. Doesn't fit when the right specialist depends on the input.
 - **`workflow`** — fixed step order. Doesn't fit when routing decisions need an LLM or vary per request.
 - **`supervisor`** — when the right specialist is decided per-call and you may iterate to a goal.
-- **`orchestrator` (v2)** — when the *session* matters: long-running conversations.
+- **`orchestrator`** — when the *session* matters: long-running conversations with durable cross-turn state, history windowing/compaction, and mid-turn resume. See [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md).
 
 ## Three dispatch surfaces
 
@@ -1922,6 +2641,41 @@ The router agent's output MUST include `next: string | string[] | typeof END`; `
 
 `evaluate` pairs with both `router` AND `route` — state-driven termination is useful in either dispatch mode.
 
+#### `ai.router()` — skip the boilerplate
+
+`ai.router({ model, intents })` builds the routing agent for you: it generates the `{ next, reasoning }` output schema (with the intent names + `END` baked in as a JSON-Schema `enum`) and auto-writes the routing system prompt listing every intent + description. Pass the **same** `intents` object you pass to `ai.supervisor()`.
+
+```ts
+const intents = { billing, shipping, returns, escalate };
+
+const supportBot = ai.supervisor({
+  router: ai.router({
+    model,
+    intents,
+    systemPrompt: "You coordinate a customer-support team.", // optional framing on top
+  }),
+  intents,
+});
+```
+
+The result is a plain `AgentContract` — usable standalone or as `router`. Hand-writing the agent (above) still works; `ai.router()` is the shortcut.
+
+#### `ai.fanOut()` — voting / self-consistency
+
+`ai.fanOut(unit, n)` spreads one agent/workflow into `n` distinctly-keyed intent entries (`writer1..writerN`) so the supervisor can dispatch them in parallel and a downstream intent can pick the best/majority answer. Spread it into `intents`:
+
+```ts
+ai.supervisor({
+  intents: {
+    ...ai.fanOut(writer, 3),                                   // writer1, writer2, writer3
+    vote: { run: pickMajority, description: "Choose the majority answer." },
+  },
+  route: (ctx) => (ctx.iteration === 0 ? ["writer1", "writer2", "writer3"] : "vote"),
+});
+```
+
+Each key references the same underlying unit; the description defaults to the unit's. Override the key base with `{ keyPrefix }` and the per-entry text with `{ description }`.
+
 ## The `intents` map — five accepted shapes
 
 ```ts
@@ -2095,6 +2849,16 @@ await supportBot.execute(message, {
 
 `history` precedence: per-call → factory `config.history`. Slice with `historyWindow.{router,agents,ack}` (default ack = 0, router/agents = unbounded) or per-entry `history(ctx)` override.
 
+## Supervisor-level middleware
+
+`middleware: AgentMiddleware[]` fires each middleware's optional `supervisor` hook map (`before` / `after` / `onError`) ONCE around the whole `execute()` / `stream()` / `resume()` run:
+
+```ts
+ai.supervisor({ name: "support", router, intents, middleware: [auditTrail] });
+```
+
+Same onion semantics as the agent pipeline: `before` top-down (return a `SupervisorResult` to short-circuit, throw to abort), `after` / `onError` bottom-up. A middleware without a `supervisor` hook map is skipped — the SAME builtin objects (budget, guardrail, …) can be registered on agents AND here, each declaring whichever level applies. Each needs a unique `name`. See [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md).
+
 ## Iteration model
 
 1. Router/route picks `next` (or `END`).
@@ -2158,11 +2922,139 @@ const escalationAgent = ai.agent({ model, tools: [supportTool] });
 - [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — tool artifacts side-channel
 
 
+## use-ai-memory  `@warlock.js/ai/use-ai-memory/SKILL.md`
+
+---
+name: use-ai-memory
+description: 'Agent memory with ai.memory({...}) — a provider-neutral store with FOUR tiers: WORKING (in-run scratch, recalled by recency), SEMANTIC (durable facts by cosine similarity over a @warlock.js/cache vector driver via .similar()), EPISODIC (durable events, similarity blended with recency), and PROCEDURAL (durable how-tos, similarity blended with reinforcement). remember() / recall() / clear(); wire it into ai.orchestrator({ memory }). Triggers: `ai.memory`, `memory.remember`, `memory.recall`, `memory.clear`, `MemoryContract`, `MemoryConfig`, `MemoryItem`, `RecalledMemory`, `MemoryTier`, `SemanticMemoryConfig`, `EpisodicMemoryConfig`, `ProceduralMemoryConfig`, `working`, `semantic`, `episodic`, `procedural`, `defaultTier`, `threshold`, `recencyWeight`, `halfLifeMs`, `reinforcementWeight`, `injectKey`; ''give the agent memory'', ''remember user preferences'', ''semantic recall'', ''per-session working memory'', ''episodic / event memory'', ''procedural / how-to memory'', ''recency-weighted recall'', ''reinforce a procedure''; typical import `import { ai } from "@warlock.js/ai"`. Skip: orchestrator wiring of the memory — `@warlock.js/ai/run-orchestrator/SKILL.md`; the vector cache driver itself — `@warlock.js/cache/cache-basics/SKILL.md`; embeddings primitive — `@warlock.js/ai/embed-text/SKILL.md`; competing libs `mem0`, `langchain` memory.'
+---
+
+# `ai.memory()` — agent memory store
+
+A single provider-neutral store that holds and retrieves what an agent / orchestrator should remember across turns. Four tiers ship in 4.3.0:
+
+- **working** — in-run scratch threaded across turns of one session. Volatile, unscored, recalled in insertion order (recency). On by default.
+- **semantic** — durable *facts* stored as embeddings in a `@warlock.js/cache` driver, retrieved by cosine similarity via the driver's native `.similar()` — the same delegation the `semanticCache` middleware uses. Activates only when you pass `semantic` config.
+- **episodic** — durable *events*: a timestamped log retrieved by similarity **blended with recency** (recent episodes rank higher). Embedder-backed like semantic; tune with `recencyWeight` + `halfLifeMs`.
+- **procedural** — durable *how-tos*: learned procedures retrieved by similarity **blended with reinforcement** — re-remembering a procedure increments its use count so well-worn procedures rank higher. Tune with `reinforcementWeight`.
+
+> **Still deferred** — decay / forgetting (TTL falloff, eviction). The four tiers above are the full 4.3.0 surface; the `MemoryTier` union widened from `"working" | "semantic"` to add `"episodic" | "procedural"` (a non-breaking change).
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { MemoryCacheDriver } from "@warlock.js/cache";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+const store = new MemoryCacheDriver();
+store.setOptions({});
+
+const mem = ai.memory({
+  semantic: {
+    embedder: openai.embedder({ name: "text-embedding-3-small" }),
+    store,                                  // vector-capable CacheDriver
+    namespace: "ai.memory",                 // key prefix; default "ai.memory"
+  },
+  defaultTier: "semantic",                  // tier a remember() item lands in without its own `tier`
+  k: 5,                                     // default recall count
+  threshold: 0.7,                           // default semantic similarity floor [0,1]
+});
+
+await mem.remember({ text: "User prefers concise answers." });
+const hits = await mem.recall("how should I respond?", { k: 3 });
+```
+
+## Configuration rules (loud at construction)
+
+- **At least one tier must be enabled** — `working` defaults to `true`; `semantic` / `episodic` / `procedural` each activate only when you pass their config. Enabling neither throws (`a memory with no tiers can't store or recall`).
+- **A vector tier with no store throws now** — pass the tier's `store`, or set `ai.config({ defaultStore })` at boot. Applies to `semantic`, `episodic`, and `procedural`. Resolution happens once at construction, not silently on first use (the same loud-now contract `semanticCache` follows).
+- **`defaultTier` must reference an enabled tier** — defaults to `"working"`.
+- Set `working: false` for a durable-only memory (then set `defaultTier` to an enabled vector tier).
+
+## Episodic & procedural tiers
+
+Both are durable, embedder-backed tiers wired like `semantic` (`{ embedder, store? }`), but they re-rank by *time* and *use*:
+
+```ts
+const mem = ai.memory({
+  episodic:   { embedder, store, recencyWeight: 0.3, halfLifeMs: 7 * 24 * 60 * 60 * 1000 },
+  procedural: { embedder, store, reinforcementWeight: 0.3 },
+  defaultTier: "episodic",
+});
+
+await mem.remember({ text: "Refunded order 5821 after a cracked-item complaint.", tier: "episodic" });
+await mem.remember({ id: "esc", text: "Escalate refunds over $500 to a human.", tier: "procedural" });
+await mem.remember({ id: "esc", text: "Escalate refunds over $500 to a human.", tier: "procedural" }); // reinforce → uses 1→2
+```
+
+- **episodic** — stamps each entry with the remember time and decays its recency on an exponential half-life; at equal similarity a recent episode wins. `recencyWeight: 0` → pure similarity. The similarity `threshold` still gates relevance (recency never surfaces an irrelevant-but-recent episode). `now` is injectable for deterministic tests.
+- **procedural** — keeps a per-procedure use count; re-remembering (same `id`, or same text → same derived id) **reinforces** it with diminishing returns. Recall is side-effect-free.
+- Each vector tier defaults to its own namespace (`ai.memory.semantic` / `.episodic` / `.procedural`) so they don't collide on a shared driver; override with `namespace`.
+
+## The three methods
+
+### `remember(items)`
+
+```ts
+await mem.remember({ text: "User is on the Enterprise plan.", tier: "semantic", metadata: { source: "crm" } });
+await mem.remember([{ text: "a" }, { text: "b", tier: "working" }]);   // batch
+```
+
+A `MemoryItem` is `{ text, tier?, id?, metadata? }`. `text` is the only required field — it's what gets embedded (semantic) and surfaced back on recall. `tier` defaults to the factory `defaultTier`. Semantic items are embedded + indexed; working items append to the in-run buffer. **Re-remembering an item whose id (explicit or text-derived) already exists overwrites in place rather than duplicating.** `metadata` is an opaque bag round-tripped verbatim onto the recalled memory.
+
+### `recall(query, options?)`
+
+```ts
+const hits = await mem.recall("which plan is the user on?", {
+  k: 5,              // cap result count (defaults to factory k)
+  threshold: 0.75,   // raise the semantic floor for this call
+  tier: "semantic",  // restrict to one tier; omit to query every enabled tier
+});
+
+for (const hit of hits) {
+  hit.id; hit.text; hit.tier; hit.score; hit.metadata;
+}
+```
+
+Returns `RecalledMemory[]` scored and ordered by descending relevance. By default queries every enabled tier and merges. `score` is in `[0,1]` for **every** tier — cosine similarity (semantic), a recency proxy (working, most-recent = 1), similarity×recency (episodic), or similarity×reinforcement (procedural) — so a mixed recall set sorts on one field without special-casing the tier. Returns `[]` when nothing clears the threshold — never throws on "no hits".
+
+**Memory never mutates the prompt.** `recall()` hands you scored entries; surfacing the recalled text (system prefix, a synthesized "what you remember" block, …) is YOUR call so the injection point stays explicit.
+
+### `clear(tier?)`
+
+```ts
+await mem.clear();            // every tier
+await mem.clear("working");   // just working — e.g. at session end, keeping durable recall
+```
+
+## Wiring into an orchestrator
+
+Pass the store as `ai.orchestrator({ memory })` to recall before each turn's dispatch and remember the settled outcome after. Recalled memories land in `ctx.context[injectKey]` (default `"memories"`). See [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) for the per-turn `memory` field, `recall.k: 0` (write-only), `remember: false` (read-only), and `rememberTier`.
+
+## Picking a vector driver
+
+The semantic tier delegates similarity entirely to the `CacheDriver`:
+- **Dev / tests** — `new MemoryCacheDriver()` (zero config, O(N) scan; fine up to a few thousand entries).
+- **Production** — a driver with a real ANN index: `pg` with pgvector, `redis` with RediSearch.
+
+Drivers without similarity support throw `CacheUnsupportedError` from `set({ vector })` / `similar()`. See [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md).
+
+## See also
+
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — the `memory` field on a session
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — the embedder the semantic tier needs
+- [`@warlock.js/ai/attach-ai-middleware/SKILL.md`](@warlock.js/ai/attach-ai-middleware/SKILL.md) — `semanticCache`, the sibling `.similar()` consumer
+- [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — vector driver catalog
+
+
 ## write-system-prompt  `@warlock.js/ai/write-system-prompt/SKILL.md`
 
 ---
 name: write-system-prompt
-description: 'Compose system prompts via ai.systemPrompt() / ai.persona() / ai.instruction() — immutable builders with {{placeholder}} substitution. Triggers: `ai.systemPrompt`, `ai.persona`, `ai.instruction`, `SystemPromptBlockContract`, `PersonaContract`, `InstructionContract`, `placeholders`, `{{placeholder|default}}`; ''write a system prompt'', ''compose persona + instructions'', ''per-call prompt override'', ''mustache placeholder''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent factory wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain` `PromptTemplate`, raw f-strings.'
+description: 'Compose system prompts via ai.systemPrompt() / ai.persona() / ai.instruction() — immutable builders with {{placeholder}} substitution, plus ai.systemPrompt.fromFile(path) to seed from a file read once at construction. Triggers: `ai.systemPrompt`, `ai.systemPrompt.fromFile`, `ai.persona`, `ai.instruction`, `SystemPromptBlockContract`, `PersonaContract`, `InstructionContract`, `placeholders`, `{{placeholder|default}}`, `InvalidRequestError`; ''write a system prompt'', ''compose persona + instructions'', ''prompt from a file'', ''per-call prompt override'', ''mustache placeholder''; typical import `import { ai } from "@warlock.js/ai"`. Skip: agent factory wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain` `PromptTemplate`, raw f-strings.'
 ---
 
 # System prompts — immutable builders
@@ -2177,6 +3069,7 @@ import { ai } from "@warlock.js/ai";
 ai.systemPrompt();                  // empty — chain .persona(), .instruction() onto it
 ai.systemPrompt("literal text");    // one-shot string form
 ai.systemPrompt([block1, block2]);  // array form — blocks render in declaration order
+ai.systemPrompt.fromFile(path);     // seed from a file read once at construction
 
 ai.persona(text);                   // PersonaContract block
 ai.instruction(text);               // InstructionContract block
@@ -2213,6 +3106,18 @@ ai.systemPrompt([
 ]);
 ```
 
+### From a file — `ai.systemPrompt.fromFile(path)`
+
+Read a prompt template from disk ONCE, synchronously, at construction. The file's UTF-8 contents seed one instruction block — so `{{placeholders}}` inside the file resolve at `resolve()` time and the result forks with further `.persona()` / `.instruction()` calls:
+
+```ts
+const prompt = ai.systemPrompt.fromFile("./prompts/support-agent.md");
+const localized = prompt.instruction("Respond in {{language|English}}.");
+localized.resolve({ language: "Arabic" });
+```
+
+One-shot by design (never re-read on `resolve()`). Throws `InvalidRequestError` when the file can't be read — a path typo fails loudly at construction instead of silently producing an empty prompt. `ai.systemPrompt.fromFile(path)` === `SystemPrompt.fromFile(path)`.
+
 ## Block ordering
 
 `SystemPrompt` stores `blocks: readonly SystemPromptBlockContract[]` — not separate persona + instructions fields. Rendering honors insertion order.