@warlock.js/ai 4.4.0 → 4.6.0

package/llms-full.txt

@@ -28,7 +28,7 @@ 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, 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.
+Beyond the ladder: `ai.planner()` (LLM-generated plans), `ai.memory()` (working + semantic recall), `ai.batch()` / `ai.fallbackModel()` / `ai.router()` / `ai.fanOut()` (DX helpers), `agent.eval()` (scoring), and the `ai.checkpoint.*` / `ai.snapshot.*` orchestrator stores.
 
 ## Foundations
 
@@ -66,14 +66,14 @@ console.log(text, usage.total, report.duration);
 
 | If the task is about… | Load |
 | --- | --- |
-| `ai.agent({...})` — single-LLM-turn primitive, structured output, streaming, attachments | [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) |
+| `ai.agent({...})` — single-LLM-turn primitive, structured output, streaming, attachments, `spawnSubAgent` | [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) |
 | `ai.tool({...})` — typed validated functions the model can call | [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) |
 | `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.memory({...})` — working + semantic 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) |
@@ -156,8 +156,8 @@ A drop-in `ModelContract` that wraps an ordered list and advances to the next mo
 
 ```ts
 const model = ai.fallbackModel([
-  ai.openai.model({ name: "gpt-4o" }),
-  ai.anthropic.model({ name: "claude-3-5-sonnet" }),
+  openai.model({ name: "gpt-4o" }),
+  anthropic.model({ name: "claude-3-5-sonnet" }),
 ]);
 
 const agent = ai.agent({ model });   // hand it anywhere a model goes
@@ -298,6 +298,144 @@ const concierge = ai.agent({
 - [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — `fallbackModel` wraps these adapters; cost-truth tokens
 
 
+## approve-tool-calls  `@warlock.js/ai/approve-tool-calls/SKILL.md`
+
+---
+name: approve-tool-calls
+description: 'Gate an agent''s tool calls behind a human with `ai.human.approval(options)` (the `tool.before` approval-gate middleware) — ships in @warlock.js/ai core. Triggers: `ai.human.approval`, `humanApproval`, `HumanApprovalOptions`, `ApprovalRequest`, `ApprovalDecision`, `ApprovalHandler`, `InterruptPolicy`, `evaluatePolicy`, `ApprovalRejectedError`, `policy: { type: "allowlist" | "denylist" | "predicate" }`, decision `{ type: "approve" | "reject" | "edit" }`; ''human in the loop'', ''approve a tool call before it runs'', ''ask a human before the agent sends/charges/deletes'', ''pause before a dangerous tool'', ''let an operator edit the tool args'', ''reject a tool call with a reason the model can self-correct from''. Typical import `import { ai } from "@warlock.js/ai"`. Skip: persisting the request and resuming hours later out-of-process — `@warlock.js/ai/durable-resume/SKILL.md`; the agent/middleware/tool primitives themselves — `@warlock.js/ai`.'
+---
+
+# Approve tool calls — the human-in-the-loop gate
+
+`ai.human.approval(options)` returns an `AgentMiddleware` with **one** hook — `tool.before` — that pauses *before a specific tool call* and routes it to a human. The human can **approve** (run the real tool unchanged), **reject** (the model sees a typed error and self-corrects), or **edit** (run the tool with replaced args). Every call the policy doesn't gate passes through untouched.
+
+`ai.human.*` ships natively on the shared `ai` object from `@warlock.js/ai` core — no extra import or registration step. The named `humanApproval` export is the same factory.
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+const support = ai.agent({
+  model: openai.model({ name: "gpt-4o" }),
+  tools: [refundCustomer, lookupOrder],
+  middleware: [
+    ai.human.approval({
+      policy: { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
+      // SSE / CLI handler resolves when the operator rules:
+      handler: async (req) => ui.prompt(req), // → { type: "approve" } | { type: "reject", reason } | { type: "edit", args }
+    }),
+  ],
+});
+
+await support.execute("Refund order #4821"); // pauses at refundCustomer, awaits the operator
+```
+
+## The three decisions
+
+A handler turns an `ApprovalRequest` into an `ApprovalDecision` — a union discriminated by `type` (never `kind`):
+
+| `decision.type` | Effect | What the model sees next |
+|---|---|---|
+| `"approve"` | The real tool runs with the model's original args. | The tool's normal result. |
+| `"reject"` | Short-circuits an `ApprovalRejectedError` carrying `reason`. | `{ error }` on the next trip — it can self-correct. |
+| `"edit"` | The reviewer's `args` replace the model's; the real tool then runs. | The tool's result for the edited args. |
+
+```ts
+type ApprovalDecision =
+  | { type: "approve" }
+  | { type: "reject"; reason: string }
+  | { type: "edit"; args: unknown; reason?: string };
+```
+
+An `edit` still goes through the tool's own Standard-Schema validation — if the replaced args don't fit the schema, the tool surfaces a validation error on `result.error` and the model self-corrects. No special-casing.
+
+## The interrupt policy — which calls need a human
+
+`policy` decides *which* tool calls are gated. It's a union keyed on `type`:
+
+| `policy.type` | Gates a call when… | Tags |
+|---|---|---|
+| `"allowlist"` | the tool name **is** in `tools`. | optional `tags(toolName)` callback |
+| `"denylist"` | the tool name is **not** in `tools` (gate everything else). | optional `tags(toolName)` callback |
+| `"predicate"` | `requiresApproval(ctx)` returns a truthy value. | a returned `string[]` doubles as the tags |
+
+```ts
+// Allowlist — only refunds need sign-off:
+{ type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] }
+
+// Denylist — everything except read-only lookups needs sign-off:
+{ type: "denylist", tools: ["lookupOrder", "searchCatalog"] }
+
+// Predicate — args-aware: only large refunds, tagged for the reviewer UI:
+{
+  type: "predicate",
+  requiresApproval: (ctx) =>
+    ctx.toolName === "refundCustomer" && (ctx.args as { amount: number }).amount > 100
+      ? ["money", "high-value"]
+      : false,
+}
+```
+
+The predicate sees a read-only `PolicyContext` — `toolName`, `toolDescription`, `args` (the model's exact input), `agentName`, `tripIndex`, `sessionId`. Return `false` (or an empty array) to skip approval; `true` or a non-empty `string[]` to require it. The `string[]` becomes `request.context.tags`, surfaced verbatim to the reviewer so a UI can group or prioritize.
+
+Compose with `forTool(names, mw)` from `@warlock.js/ai` for static, name-based scoping and let `policy` be the dynamic, args-aware layer on top.
+
+`evaluatePolicy(policy, context)` is the exported, pure core if you want to reuse the gate decision outside the middleware (it never throws, does no IO, and returns `{ requiresApproval, tags? }`).
+
+## The request a reviewer rules on
+
+For a gated call the middleware builds an `ApprovalRequest` and hands it to your `handler`:
+
+```ts
+interface ApprovalRequest {
+  interruptId: string;          // stable id; durable mode keys the store on it
+  toolName: string;
+  toolDescription?: string;
+  args: unknown;                // the model's exact args
+  context: {
+    agentName: string;
+    tripIndex: number;
+    sessionId?: string;
+    originalInput?: string;     // the run's prompt (used by durable re-run)
+    tags?: string[];            // from the policy match
+  };
+  requestedAt: string;          // ISO-8601
+}
+```
+
+The handler runs in one of two modes that share this one signature:
+
+- **interactive** — return the decision (or a promise of it); the hook `await`s it in-process. The whole agent run stays on the stack — no store needed. This skill.
+- **durable** — persist the request and `throw` to suspend, resuming from another process later. See [`durable-resume/SKILL.md`](@warlock.js/ai/durable-resume/SKILL.md).
+
+## It never throws out of the pipeline
+
+The middleware is a harness, not a detector — every outcome (skip, approve, reject, edit) returns normally. A `reject` does **not** throw out of `execute()`: it short-circuits a failed `ToolInvokeResult` carrying an `ApprovalRejectedError`, so the error rides `result.error` like every other `AIError` and `agent.execute()` still never throws.
+
+```ts
+const result = await support.execute("Refund order #4821");
+
+if (result.error instanceof ApprovalRejectedError) {
+  logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);
+}
+```
+
+Only a *handler bug* — a non-sentinel throw from your handler — propagates, and even then the agent dispatch funnels it onto `result.error` rather than crashing the run. The gate never swallows a bug into a silent approval.
+
+## Edge cases
+
+- **Duplicate middleware name.** Middleware names are validated unique per agent. The default name is `"human-approval"`, so two approval middlewares on one agent need distinct `name`s.
+- **Silent tools.** A `silent`-mode tool's result isn't fed back to the model, but approval still runs (we gate *before* dispatch). A `reject` on a silent tool writes a tool message that's harmless but unread.
+- **Abort during an interactive await.** `ctx.signal` is in scope; honor it in a long-running handler so a cancelled run rejects rather than hanging.
+
+## See also
+
+- [`@warlock.js/ai/durable-resume/SKILL.md`](@warlock.js/ai/durable-resume/SKILL.md) — persist the request, resume out-of-process hours later via `ai.human.resume(...)` and the `InterruptStore`.
+- `@warlock.js/ai` — the `ai.agent(...)`, `AgentMiddleware`, `tool.before`, and `ToolInvokeResult` primitives this gate wraps.
+
+
 ## attach-ai-middleware  `@warlock.js/ai/attach-ai-middleware/SKILL.md`
 
 ---
@@ -307,7 +445,7 @@ description: 'Wire agent middleware — ai.middleware.budget (token / USD caps +
 
 # Middleware — agent-level pipeline
 
-Cross-cutting concerns wrapped around an agent run at three granularities: `execute`, `trip`, `tool`. One middleware = one object. Ships with `budget`, `guardrail`, and `semanticCache` built-ins.
+Cross-cutting concerns wrapped around an agent run at three agent-level granularities (`execute`, `trip`, `tool`), plus a `supervisor` level that wraps a whole supervisor run (see below). One middleware = one object. Ships with `budget`, `guardrail`, and `semanticCache` built-ins.
 
 ## Install order at a glance
 
@@ -705,6 +843,385 @@ Workflow errors surface as `ToolExecutionError` with `cause` pointing at the ori
 - [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — `workflow.asTool()` composition
 
 
+## detect-and-redact-pii  `@warlock.js/ai/detect-and-redact-pii/SKILL.md`
+
+---
+name: detect-and-redact-pii
+description: 'Detect and redact PII (and run model-graded moderation) with @warlock.js/ai-guard detectors — `ai.guardrail.pii(...)` and the optional `ai.guardrail.moderation(...)` peer. Triggers: `ai.guardrail.pii`, `piiDetector`, `PiiDetectorOptions`, `PiiCategory`, `mask`, `{label}`, `dictionary`, `onMatch`, `ai.guardrail.moderation`, `openAiModeration`, `OpenAiModerationOptions`, `blockOn`, `omni-moderation-latest`; ''redact PII from model output'', ''mask SSN / credit card / email / phone / IP'', ''stop PII leaking into a tool call'', ''scrub sensitive data'', ''add OpenAI moderation'', ''block violent / self-harm content''; typical import `import "@warlock.js/ai-guard"` (registers `ai.guardrail.pii` / `.moderation`) or `import { pii, moderation } from "@warlock.js/ai-guard"`. Skip: composing the guard / wiring it into an agent — `@warlock.js/ai-guard/guard-input-output/SKILL.md`; routing a block to a human — `@warlock.js/ai-guard/escalate-block-to-human/SKILL.md`.'
+---
+
+# Detect and redact PII (and moderate)
+
+`ai.guardrail.pii(...)` is a **zero-dependency** detector — regex + exact-string matching, no runtime peer. Pass it into any phase array of `ai.guardrail({ ... })`.
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-guard";
+
+const policy = ai.guardrail({
+  output: [ai.guardrail.pii({ onMatch: "redact", mask: "[REDACTED:{label}]" })],
+});
+```
+
+## Categories — `detect`
+
+Scans for these `PiiCategory` values; `detect` narrows the set (default: all). Each pattern is **linear** (anchored, no nested quantifiers) — safe against catastrophic backtracking.
+
+| Category | Matches |
+|---|---|
+| `ssn` | US Social Security numbers |
+| `email` | email addresses |
+| `phone` | phone numbers |
+| `credit-card` | credit-card numbers |
+| `ipv4` | IPv4 addresses |
+
+```ts
+ai.guardrail.pii({ detect: ["ssn", "credit-card"] }); // scan only these two
+```
+
+Add `dictionary` for extra exact-string terms (internal codenames, customer IDs) treated as PII alongside the built-in regexes:
+
+```ts
+ai.guardrail.pii({ dictionary: ["PROJECT-ORION", "ACME-INTERNAL"] });
+```
+
+## Action — `onMatch`
+
+`onMatch` is `"redact" | "block" | "flag"`, default **`"redact"`**:
+
+- **`redact`** — replace each match with the `mask` and continue (output phase only — see below).
+- **`block`** — reject the trip / tool call with a `GuardrailViolationError`.
+- **`flag`** — allow but record the matches into `ctx.state` for a downstream observer.
+
+## The `mask` template
+
+On `redact`, each match is replaced by `mask`. The `{label}` token is substituted with the matched category, so a redacted SSN becomes `[REDACTED:ssn]`:
+
+```ts
+ai.guardrail.pii({ onMatch: "redact", mask: "[REDACTED:{label}]" });
+// "My SSN is 123-45-6789" -> "My SSN is [REDACTED:ssn]"
+```
+
+Omit `mask` to use the default fixed placeholder.
+
+## Where redaction actually applies
+
+Redaction only rewrites-and-continues where the pipeline seam supports it:
+
+- **Output (`output: [...]`)** — works. `trip.after` returns a replacement `ModelResponse` with the scrubbed `content`. This is the primary PII-redaction use case.
+- **Input (`input: [...]`)** — a `redact` verdict **downgrades to `block`**. The core `trip.before` hook can only short-circuit, not rewrite-and-continue, so the un-redacted prompt can't be threaded back.
+- **Tool (`tool: [...]`)** — a `redact` verdict **downgrades to `block`** (`reason: "tool-arg-redaction-unsupported"`), because silently rewriting tool arguments changes the call's side-effects.
+
+So: **redact on output, block on input/tool.**
+
+```ts
+const policy = ai.guardrail({
+  output: [ai.guardrail.pii({ onMatch: "redact", mask: "[REDACTED:{label}]" })], // scrub the answer
+  tool: [ai.guardrail.pii({ onMatch: "block" })],                                // refuse to leak into tools
+  toolNames: ["send_email"],
+});
+```
+
+## Optional moderation peer — `ai.guardrail.moderation`
+
+For model-graded content (violence, self-harm, hate) beyond regex, the optional `moderation` detector calls OpenAI's moderation endpoint. The `openai` SDK is an **optional lazy peer** — importing `@warlock.js/ai-guard` never forces it to resolve; the detector throws a curated install string on first `check()` when the peer is absent (mirrors ai-panoptic's lazy Langfuse exporter).
+
+```ts
+const policy = ai.guardrail({
+  output: [
+    ai.guardrail.moderation({ blockOn: ["violence", "self-harm"] }),
+  ],
+});
+```
+
+- `blockOn` — categories that escalate to `block`; every other flagged category produces a `flag`. Omit to `flag` on any category.
+- `model` — defaults to `"omni-moderation-latest"`.
+- `apiKey` — defaults to `OPENAI_API_KEY`.
+- `client` — pass a pre-built OpenAI-compatible client to bypass the lazy import entirely (the bring-your-own-client / test escape hatch).
+
+Install the peer only when you use this detector:
+
+```bash
+npm install openai
+```
+
+## See also
+
+- [`@warlock.js/ai-guard/guard-input-output/SKILL.md`](@warlock.js/ai-guard/guard-input-output/SKILL.md) — composing the guard, the verdict model, phases, and `toolNames` scoping.
+- [`@warlock.js/ai-guard/escalate-block-to-human/SKILL.md`](@warlock.js/ai-guard/escalate-block-to-human/SKILL.md) — escalating a hard `block` to a human-review surface.
+
+
+## durable-agent-runs  `@warlock.js/ai/durable-agent-runs/SKILL.md`
+
+---
+name: durable-agent-runs
+description: 'Mid-run crash-resume for agents AND planners — opt in with durable: { store, deleteOnComplete? } on the config, pass a stable runId to execute(), and call agent.resume(runId) / planner.resume(runId) after a crash to continue from the last settled trip / plan node. Reuses the ai.snapshot.{memory,pg,redis} stores; checkpoints per-trip (agent) / per-node (planner); completed trips + nodes never re-run their tools and usage is never double-counted; a drifted definition throws AgentDriftError / PlannerDriftError (bypass with { force: true }). Triggers: `durable`, `agent.resume`, `planner.resume`, `resume(runId)`, `runId`, `AgentSnapshot`, `PlannerSnapshot`, `AgentSnapshotStatus`, `PlannerSnapshotStatus`, `AgentDriftError`, `PlannerDriftError`, `computeAgentSignature`, `agent.signature`, `deleteOnComplete`, `defaultSnapshotStore`, `ai.snapshot.pg`, `ai.snapshot.memory`, `SnapshotStore`, `force: true`; ''resume an agent after a crash'', ''durable agent run'', ''continue a planner from where it crashed'', ''checkpoint agent state'', ''idempotent tool re-run on resume'', ''signature drift on resume''; typical import `import { ai } from "@warlock.js/ai"`. Skip: durable human-in-the-loop approval resume (ai.human.resume of a PendingInterrupt) — `@warlock.js/ai/durable-resume/SKILL.md`; supervisor/workflow iterate-mid-turn snapshot resume + the store contracts themselves — `@warlock.js/ai/manage-ai-stores/SKILL.md`; competing libs `temporal`, `inngest`, `restate`.'
+---
+
+# Durable agent + planner runs — resume from the last checkpoint
+
+Opt-in mid-run crash-resume for the two long-running primitives. Turn it on, give the run a stable `runId`, and after a process crash `resume(runId)` re-hydrates the persisted state and continues from where it stopped — never re-issuing a settled trip's model call or re-invoking a completed node's capability.
+
+> **Not the same as [[durable-resume]].** That skill is `ai.human.resume(interruptId, decision)` — resuming a **gated tool call** hours later after a human rules (a `PendingInterrupt` in an `InterruptStore`). *This* skill is **crash-resume of an in-flight run** (an `AgentSnapshot` / `PlannerSnapshot` in a `SnapshotStore`): the process died mid-run, you restart, and continue the same trip / plan. Different trigger (a crash, not a human), different store, different verb (`agent.resume` / `planner.resume`, not `ai.human.resume`).
+
+## Opt in — `durable` on the config
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const writer = ai.agent({
+  name: "writer",
+  model,
+  tools: [searchTool, draftTool],
+  durable: {
+    store: ai.snapshot.pg({ client: pgPool }), // reuses the ai.snapshot.* stores
+    deleteOnComplete: false,                    // default — keep for the completed-run short-circuit + audit
+  },
+});
+```
+
+`durable` shape (identical on the agent and planner config):
+
+- **`store?`** — a `SnapshotStore`. Falls back to `ai.config({ defaultSnapshotStore })`. When neither resolves, snapshot writes **silently skip** and `resume()` throws.
+- **`deleteOnComplete?`** — drop the snapshot once the run completes successfully. Default `false`.
+
+**Absent `durable` ⇒ zero behavior change** — the loop starts at trip 0 / the first node, never writes a snapshot, and runs byte-for-byte as before.
+
+## Run with a stable `runId`, then resume
+
+The `runId` is the store key. Pass a stable one to `execute()` (or read the generated one off `result.report.runId`) so a later `resume()` can find the snapshot:
+
+```ts
+const result = await writer.execute("research X", { runId: "run-42" });
+
+// ...process crashes mid-run, restarts...
+
+const recovered = await writer.resume("run-42");
+// continues from the next unsettled trip; `recovered.report.status === "completed"`
+```
+
+Planners are the mirror image — `durable` on the config, `runId` on `execute(goal)`, `planner.resume(runId)`:
+
+```ts
+const research = ai.planner({
+  name: "research-assistant",
+  model,
+  capabilities: [{ name: "search", executable: searchAgent }, { name: "write", executable: writerAgent }],
+  durable: { store: ai.snapshot.pg({ client: pgPool }) },
+});
+
+const first = await research.execute("compare A vs B", { runId: "plan-7" });
+// ...crash...
+const done = await research.resume("plan-7");
+```
+
+## Checkpoint granularity
+
+| Primitive | Written | Contains | Resume continues at |
+|---|---|---|---|
+| **agent** | after every settled **trip** (`runTrip` end) | `messages`, `trips`, `toolCalls`, `usage`, resolved `systemPrompt` / `responseSchema`, `signature`, `status` | `trips.length` (the next trip index) |
+| **planner** | after every settled **plan node** (`executeStep` end) | the frozen `plan`, `executedSteps` ledger, `usage`, child `children` reports, `replanCount`, `signature`, `status` | the unfinished frontier (from `executedSteps`) |
+
+The write happens only where the persisted arrays are mutually consistent — for the agent, after every tool a trip requested has been dispatched and its result appended. A crash **mid-trip** loses only that in-flight trip (never checkpointed), which the resume re-issues cleanly. The planner **never re-calls the planning LLM** on resume — the plan is frozen on the first run; re-asking would burn tokens and risk a plan that no longer matches the ledger. Every field on both snapshots is JSON-serializable, so they round-trip through any `ai.snapshot.{memory,pg,redis}` backend verbatim.
+
+## Idempotency — what does and doesn't re-run
+
+```ts
+// Completed run: resume is a no-op that re-returns the stored result.
+const again = await writer.resume("run-42"); // runs nothing when status === "completed"
+```
+
+- **Completed trips / nodes never re-run their tools.** On agent resume, `trips.length` is the starting trip index — earlier trips' model calls are not replayed and their tool dispatches are not re-invoked. On planner resume, a completed node's capability dispatch is skipped (the sequential skip-guard / DAG re-seed derive the completed set from `executedSteps`).
+- **Usage is never double-counted.** The running `usage` total is restored from the snapshot; only the newly-executed trips / nodes add to it.
+- **Caveat — a crash MID-trip re-runs that trip's tools.** The in-flight trip was never checkpointed, so on resume its tools fire again. **Side-effectful tools (charging a card, sending an email) must be idempotent** — the same caller-responsibility boundary the supervisor and workflow primitives document. Guard them with your own dedupe key (e.g. `${runId}:${toolCallId}`).
+
+## Drift — definition changed since the snapshot
+
+Every agent / planner carries a structural `signature` (`agent.signature` — computed at factory time by `computeAgentSignature`), stamped on each snapshot. `resume()` compares the stored signature against the current definition; a mismatch throws before executing anything:
+
+- **agent** covers: model name + provider, sorted tool names, `maxTrips`, whether a default `output` schema is set, `version`. It does **not** cover system-prompt text, middleware, per-event handlers, placeholders, or `modelOptions` — runtime knobs that don't change a resumable run's shape.
+- **planner** covers: name + ordered capability names. A mid-run **re-plan is NOT drift** (the plan changed, not the definition); `replanCount` is persisted so the replan budget survives a resume.
+
+```ts
+import { AgentDriftError } from "@warlock.js/ai";
+
+try {
+  await writer.resume("run-42");
+} catch (error) {
+  if (error instanceof AgentDriftError) {
+    // The definition changed (a tool was added, the model swapped). Either roll the
+    // definition back, or — only when you've verified the change is snapshot-safe:
+    await writer.resume("run-42", { force: true }); // bypasses the drift check
+  }
+}
+```
+
+`{ force: true }` is the escape hatch (mirror `PlannerDriftError` for planners). `resume()` also throws `AgentExecutionError` / `PlannerFailedError` when no store is configured or no snapshot exists for the `runId`.
+
+## Pattern — a boot-drain resume loop
+
+On restart, resume every run the store still has in flight. Snapshots carry a `status` (`"running" | "completed" | "cancelled" | "failed"`), so you only resume the live ones:
+
+```ts
+const store = ai.snapshot.pg({ client: pgPool });
+const runIds = (await store.list?.()) ?? [];
+
+for (const runId of runIds) {
+  const snapshot = await store.load(runId);
+  if (snapshot?.status === "running") {
+    await writer.resume(runId); // completed/failed snapshots short-circuit or re-throw — skip them
+  }
+}
+```
+
+Pair `deleteOnComplete: true` with this loop when you don't need the completed-run audit trail — the store then holds only genuinely-unfinished runs, so the drain never touches settled ones.
+
+## Cost + testing
+
+- **Checkpointing cost is one store write per settled trip / node** — a `JSONB` upsert on `pg`, an in-process `Map` set on `memory`. A failed checkpoint is surfaced via logs, not thrown: it loses resume-ability from that point but never breaks an otherwise-healthy run.
+- **Resume saves the tokens of every settled trip / node** — their model calls are not replayed. A completed-run resume spends nothing (it rebuilds the result from the snapshot). The planning LLM is never re-called on planner resume.
+- **Test with `ai.snapshot.memory()`.** Drive `execute(input, { runId })` against a flaky model that throws once, assert the tool spy was called once, flip the failure off, `resume(runId)`, and assert (a) `status === "completed"`, (b) the tool spy count is unchanged (no re-invoke), and (c) `usage.total` counts each trip's tokens exactly once. Drift is testable by mutating the definition (add a tool) between `execute` and `resume` and asserting `AgentDriftError` — then `{ force: true }` proceeds.
+
+## See also
+
+- [[handle-ai-errors]] — the typed `AgentDriftError` / `PlannerDriftError` / `AgentExecutionError` / `PlannerFailedError` and how `result.error` surfaces a failed run.
+- [[manage-ai-stores]] — the `ai.snapshot.{memory,pg,redis}()` factories, the `SnapshotStore` contract, dev-owned `pg` / `redis` clients, and never-auto-migrated `schema()`.
+- [[persist-ai-data]] — supervisor / workflow snapshot resume (the sibling `iterate`-style durability) and the SnapshotStore migration notes.
+- [[durable-resume]] — the OTHER resume: `ai.human.resume` of a gated tool call (human-in-the-loop), not a crash.
+
+
+## durable-resume  `@warlock.js/ai/durable-resume/SKILL.md`
+
+---
+name: durable-resume
+description: 'Persist a gated tool call and resume it from another process hours later — ships in @warlock.js/ai core: `ai.human.resume(interruptId, decision, options)`, the `InterruptStore` (`ai.human.interrupt.{memory,pg,redis}()`), `PendingInterrupt`, and the `InterruptSuspendedError` suspend sentinel. Triggers: `ai.human.resume`, `resume(interruptId, decision)`, `InterruptStore`, `ai.human.interrupt.memory`, `ai.human.interrupt.pg`, `ai.human.interrupt.redis`, `interruptMemory`, `interruptPg`, `interruptRedis`, `PendingInterrupt`, `InterruptSuspendedError`, `ResumeOptions`, `ResumeResult`, `PgClientLike`, `RedisClientLike`; ''approve hours later from a webhook'', ''persist the approval request and resume in another process'', ''durable human-in-the-loop'', ''store the interrupt in Postgres/Redis'', ''re-run the agent turn once the human approves''. Typical import `import { ai, InterruptSuspendedError } from "@warlock.js/ai"`. Skip: the in-process await gate and the policy/decision shapes — `@warlock.js/ai/approve-tool-calls/SKILL.md`.'
+---
+
+# Durable resume — persist the interrupt, approve from another process
+
+Interactive approval `await`s the operator in-process. **Durable** approval is for when the reviewer rules out-of-band — a Slack button, a webhook, hours later, in a different process. The flow: the handler **persists** the request to an `InterruptStore` and **throws** `InterruptSuspendedError` to suspend the run; the caller surfaces the `interruptId`; later, `ai.human.resume(interruptId, decision, { store })` applies the ruling.
+
+> **v1 durable resume re-runs the turn** with the decision pre-seeded — it does **not** rehydrate an in-flight supervisor mid-call (that's the deferred v2 lift). Re-running is idempotent because the prompt and the seeded decision fully determine the gated call's outcome.
+
+## Process A — suspend and surface the id
+
+```ts
+import { ai, InterruptSuspendedError } from "@warlock.js/ai";
+
+const store = ai.human.interrupt.memory(); // swap for pg / redis in production
+
+const agent = ai.agent({
+  model,
+  tools: [deleteAccount],
+  middleware: [
+    ai.human.approval({
+      policy: { type: "predicate", requiresApproval: (c) => c.toolName === "deleteAccount" },
+      store,
+      handler: async (req) => {
+        // 1. persist the pending interrupt
+        await store.save({
+          interruptId: req.interruptId,
+          request: req,
+          status: "pending",
+          savedAt: new Date().toISOString(),
+        });
+        // 2. notify the reviewer out-of-band
+        await slack.postApproval(req);
+        // 3. suspend the run — the middleware recognizes its OWN sentinel
+        throw new InterruptSuspendedError("Awaiting human approval", {
+          interruptId: req.interruptId,
+        });
+      },
+    }),
+  ],
+});
+
+const result = await agent.execute("Delete account #88");
+
+// execute() never throws — the suspend rides result.error:
+if (result.error instanceof InterruptSuspendedError) {
+  return { status: "awaiting-approval", interruptId: result.error.interruptId };
+}
+```
+
+The middleware catches the **sentinel** (`instanceof InterruptSuspendedError`) and short-circuits a failed `ToolInvokeResult` carrying it, so `error.interruptId` is on `result.error`. Hand that id to the reviewer.
+
+## Process B — resume hours later
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+// Re-run the turn with the decision pre-seeded:
+const outcome = await ai.human.resume(
+  interruptId,
+  { type: "edit", args: { confirm: true } },
+  { store, agent },
+);
+
+if (outcome.type === "applied" && outcome.result) {
+  console.log(outcome.result.text); // the re-run completed with the ruling applied
+}
+```
+
+`ai.human.resume(interruptId, decision, options)` loads the `PendingInterrupt`, validates the decision shape, deletes the record, and — when an `agent` is supplied — re-executes the original prompt with the decision **pre-seeded** so the gated tool call resolves to the ruling instead of pausing again. The prompt comes from `request.context.originalInput`; pass `options.input` to override (e.g. to append the reviewer's note), and `options.executeOptions` to forward history / output schema / signal to the re-run.
+
+### Two resume shapes
+
+| Shape | Pass | Behavior |
+|---|---|---|
+| **re-run** | `{ store, agent }` | Loads, deletes, re-executes the turn; `ResultResult.result` carries the `AgentResult`. |
+| **apply-only** | `{ store }` (no `agent`) | Loads, validates, deletes; returns `{ type: "applied", decision }` for a caller-owned re-drive (custom transport). No turn re-run. |
+
+### Idempotent by construction
+
+```ts
+type ResumeResult =
+  | { type: "applied"; interruptId: string; decision: ApprovalDecision; result?: AgentResult }
+  | { type: "already-resolved"; interruptId: string };
+```
+
+A second resume of an already-resolved (deleted) or never-raised interrupt returns `{ type: "already-resolved" }` — it never double-applies the decision or re-runs the turn. The record is deleted **before** the re-run, so even a re-run that itself raises a fresh interrupt can't collide with the one being resolved. A malformed decision (`reject` with no `reason`, `edit` with no `args`, an unknown `type`) throws a `TypeError` loudly rather than silently mis-driving the re-run.
+
+## The `InterruptStore`
+
+`ai.human.interrupt.{memory,pg,redis}()` build the store. The contract mirrors `@warlock.js/ai`'s `CheckpointStore` / `SnapshotStore` — `save` / `load` / `delete` / optional `list(prefix?)` / `schema()` — so a consumer already running an orchestrator can reuse the **same** pool for the interrupt table.
+
+| Factory | Backing | Deps |
+|---|---|---|
+| `ai.human.interrupt.memory()` | process-local `Map` | none — zero runtime deps |
+| `ai.human.interrupt.pg(options)` | one Postgres row per interrupt, keyed by `interrupt_id` | lazily imports the optional `pg` peer |
+| `ai.human.interrupt.redis(options)` | one namespaced JSON value + a self-maintained id index | lazily imports the optional `redis` peer |
+
+```ts
+// Memory — dev / tests / single-process:
+const store = ai.human.interrupt.memory();
+
+// Postgres — pass a live pool (core never imports pg in that case):
+import { Pool } from "pg";
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const store = ai.human.interrupt.pg({ client: pool });
+// Once, via your migration tool — the framework never auto-migrates:
+// await pool.query(store.schema());
+
+// …or let the store build its own pool (lazily import("pg")):
+const store = ai.human.interrupt.pg({ connectionString: process.env.DATABASE_URL });
+
+// Redis — pass a connected client, or a url:
+const store = ai.human.interrupt.redis({ url: process.env.REDIS_URL });
+```
+
+### Optional peers are lazy
+
+`pg` and `redis` are **optional** peer dependencies — neither is a hard dependency. The driver is imported only inside the store that needs it, and only when you pass a `connectionString` / `url` (passing a live `client` imports nothing). If the driver is absent, a **curated install string** surfaces on first use, never a raw module-resolution stack trace at import — so a memory-only consumer always loads cleanly. `PgClientLike` / `RedisClientLike` are structural interfaces, so any compatible pool/client satisfies them.
+
+`schema()` returns the reference DDL for the Postgres store (run it through your migration tool once) and an empty string for memory / redis, so callers treat `schema()` uniformly across drivers.
+
+## See also
+
+- [`@warlock.js/ai/approve-tool-calls/SKILL.md`](@warlock.js/ai/approve-tool-calls/SKILL.md) — the gate itself: the interrupt policy, the approve / reject / edit decision union, and the interactive (in-process await) handler.
+- `@warlock.js/ai` — the `CheckpointStore` / `SnapshotStore` the `InterruptStore` mirrors, and the `ai.agent(...)` re-run target.
+
+
 ## embed-text  `@warlock.js/ai/embed-text/SKILL.md`
 
 ---
@@ -814,21 +1331,637 @@ No built-in vector store. Bring your own (pgvector / Qdrant / Pinecone / Chroma
 - [`@warlock.js/cascade/search-by-vector/SKILL.md`](@warlock.js/cascade/search-by-vector/SKILL.md) — cascade `similarTo` query method
 
 
-## handle-ai-errors  `@warlock.js/ai/handle-ai-errors/SKILL.md`
+## escalate-block-to-human  `@warlock.js/ai/escalate-block-to-human/SKILL.md`
 
 ---
-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 (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`.'
+name: escalate-block-to-human
+description: 'Route a hard guardrail block to a human-review surface with @warlock.js/ai-guard — the `escalation.onBlock` seam and an `escalate: true` verdict. Triggers: `escalation`, `onBlock`, `GuardrailEscalation`, `GuardrailBlockEvent`, `escalate: true`, `{ type: "block", escalate: true }`, ''escalate a block to a human'', ''human review queue for guardrail'', ''page an operator on a guardrail block'', ''human-in-the-loop guardrail'', ''compose a block with a review surface'', ''custom detector that escalates''; typical import `import "@warlock.js/ai-guard"` then `ai.guardrail({ escalation: { onBlock } })`. Skip: composing the guard / phases / verdict model — `@warlock.js/ai-guard/guard-input-output/SKILL.md`; PII/moderation detectors — `@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md`; durable suspend/resume human-step machinery (deferred) — not in this package.'
 ---
 
-# Typed errors — `AIError` hierarchy
-
-Every error surfaced by `@warlock.js/ai` and every adapter package is an `AIError` subclass with a stable `code`. The base extends platform `Error`; it does NOT extend `HttpError`. Plain `Error` never leaks.
+# Escalate a block to a human
 
-## Two invariants
+A `block` verdict can carry `escalate: true`. When it does, the guard `await`s your `escalation.onBlock(...)` handler **before** throwing the `GuardrailViolationError` — the seam to a human-review queue, an operator page, or any out-of-band approval surface.
 
-1. **`execute()` never throws.** Every `agent.execute()` / `workflow.execute()` resolves with a well-formed result. Failures funnel into `result.error`. Same for `stream.result`.
-2. **Every error is an `AIError`.** Both core and adapter packages funnel everything through `AIError` subclasses. Branch on `error.code` (stable string) or `instanceof`.
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-guard";
+
+const policy = ai.guardrail({
+  output: [ai.guardrail.moderation({ blockOn: ["self-harm"] })],
+  escalation: {
+    async onBlock(event) {
+      await reviewQueue.enqueue({
+        phase: event.phase,   // "input" | "output" | "tool"
+        reason: event.reason, // the detector's human-readable reason
+      });
+    },
+  },
+});
+
+const agent = ai.agent({ model, middleware: [policy] });
+```
+
+## When `onBlock` fires
+
+`onBlock` fires **only** for a verdict of `{ type: "block", escalate: true }` — not for an ordinary `block`, and never for `allow` / `redact` / `flag`. It is **awaited before** the `GuardrailViolationError` is thrown, so your handler runs to completion (enqueue succeeds, the page is sent) before the error surfaces on `result.error`. The run still aborts: escalation is a *signal*, not a recovery — `execute()` returns with `result.error` populated as usual.
+
+## The `GuardrailBlockEvent` payload
+
+`onBlock(event)` receives:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `phase` | `"input" \| "output" \| "tool"` | where the block fired |
+| `reason` | `string` | the detector's human-readable reason |
+| `matches` | `readonly GuardrailMatch[] \| undefined` | what tripped the rule (rule id, span, label), when reported |
+| `ctx` | `MiddlewareTripContext` | the live trip context — `state`, `messages`, `agent`, `model`, `signal` |
+
+`ctx` lets the handler enrich the review item with run context (session id from `ctx.state`, the offending messages, etc.).
+
+## Producing an escalating verdict
+
+The built-in detectors return ordinary `block` verdicts (no `escalate`). To escalate, author a tiny custom `GuardrailDetector` that sets `escalate: true` on its `block`:
+
+```ts
+import type { GuardrailDetector } from "@warlock.js/ai-guard";
+
+const wirePolicy: GuardrailDetector = {
+  name: "wire-transfer",
+  check(text) {
+    if (/wire \$?\d{5,}/i.test(text)) {
+      return {
+        type: "block",
+        reason: "large wire transfer requires human approval",
+        escalate: true, // <- routes through escalation.onBlock
+        matches: [{ rule: "wire-transfer.large", label: "wire" }],
+      };
+    }
+
+    return { type: "allow" };
+  },
+};
+
+const policy = ai.guardrail({
+  tool: [wirePolicy],
+  toolNames: ["initiate_transfer"],
+  escalation: { async onBlock(e) { await approvals.request(e); } },
+});
+```
+
+A `check()` may be sync or async (async = call an external service); the guard awaits either.
+
+## A plain callback by design
+
+`escalation.onBlock` is a **plain callback** — `ai-guard` takes **no** dependency on the deferred durable human-step machinery (suspend/resume). The callback is the decoupling seam: inside it you wire your own review queue, and (where your stack supports it) a `workflow.resume(...)` loop. This package only emits the *signal*; it does not own durable suspension. When the typed human-step handoff ships, `onBlock` upgrades to it without a breaking change here.
+
+## See also
+
+- [`@warlock.js/ai-guard/guard-input-output/SKILL.md`](@warlock.js/ai-guard/guard-input-output/SKILL.md) — composing the guard, the phases, the verdict model, and how a `block` surfaces on `result.error`.
+- [`@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md`](@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md) — the `pii` detector and the optional `moderation` peer that commonly drives an escalation.
+
+
+## eval-datasets-and-ci  `@warlock.js/ai/eval-datasets-and-ci/SKILL.md`
+
+---
+name: eval-datasets-and-ci
+description: 'Datasets + regression-gated eval CI with ai.dataset({...}) feeding agent.eval({cases,baseline,tolerance}). Covers the immutable filterable/shardable dataset (cases / fromFile JSONL), DatasetEntry tags, EvalReport.regression (regressed/added/removed/passed) against a baseline, and the ai.eval reporters toJUnit / toJSON / fromJSON for CI artifacts + committed baselines. Triggers: `ai.dataset`, `DatasetContract`, `DatasetEntry`, `DatasetOptions`, `dataset.filter`, `dataset.shard`, `fromFile`, `agent.eval`, `EvalOptions`, `EvalReport`, `EvalCaseResult`, `EvalRegression`, `baseline`, `tolerance`, `ai.eval.toJUnit`, `ai.eval.toJSON`, `ai.eval.fromJSON`, `diff`, JSONL; ''eval dataset from a JSONL file'', ''shard an eval suite across CI jobs'', ''fail CI on an eval regression'', ''emit a JUnit report'', ''snapshot an eval baseline''; typical import `import { ai } from "@warlock.js/ai"`. Skip: the scorers + LLM-as-judge + Vitest matchers themselves — `@warlock.js/ai/ai-dx-helpers/SKILL.md` (registerAiMatchers / ai.eval.exact|contains|predicate|judge); record/replay of model calls for deterministic tests — `@warlock.js/ai/record-replay-llm/SKILL.md`; competing libs `promptfoo`, `braintrust`.'
+---
+
+# `ai.dataset()` + `agent.eval()` regression CI
+
+Turn a corpus of cases into a regression-gated CI signal. `ai.dataset(...)` wraps cases into an immutable, filterable, shardable collection; `agent.eval({ cases, baseline, tolerance })` runs them, scores them, and diffs against a prior report; the `ai.eval.*` reporters serialize the result for CI ingestion and tomorrow's baseline.
+
+> This skill is the **dataset + CI** layer. The scorers, LLM-as-judge config, and Vitest matchers live in [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md); `agent.eval`'s core scoring loop is in [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md).
+
+## `ai.dataset()` — immutable, filterable, shardable
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const ds = ai.dataset({
+  name: "support",
+  cases: [{ name: "greeting", input: "hi", expected: "Hello" }], // inline entries
+  fromFile: "./eval/support.jsonl",  // JSONL read ONCE, synchronously, at construction
+});
+
+ds.name;   // "support"
+ds.cases;  // DatasetEntry[] (inline first, then file entries appended)
+```
+
+- A `DatasetEntry` is an `EvalCase` plus optional `tags?: string[]` for filtering / sharding.
+- **`fromFile`** reads a JSONL file (one JSON object per line; blank lines skipped) synchronously at construction — mirroring `SystemPrompt.fromFile`. A malformed line throws an **`InvalidRequestError` naming the 1-based line number**; a missing/unreadable path throws too. `cases` and `fromFile` combine (file entries append after inline).
+
+### `filter` / `shard` — derive new datasets
+
+```ts
+const smoke = ds.filter((entry) => entry.tags?.includes("smoke"));
+const shard = ds.shard(0, 4); // first of four parallel CI shards
+```
+
+Both return a **fresh dataset sharing nothing mutable**. `shard(index, total)` is deterministic round-robin by position: every entry lands in exactly one shard, so the union of all `total` shards reproduces the full list with no gaps or overlaps. `shard` validates its args (positive integer `total`, `index` in `[0, total)`) and throws `InvalidRequestError` otherwise.
+
+## `agent.eval({ cases })` — accepts a dataset directly
+
+```ts
+const report = await myAgent.eval({
+  cases: ds,                       // a DatasetContract OR a raw EvalCase[]
+  scorers: [ai.eval.contains()],
+});
+
+expect(report.passed).toBe(true); // true only when EVERY case passed
+```
+
+The runner reads `.cases` off a dataset. Full `EvalReport`: `{ agentName, total, passedCount, failedCount, passRate, meanScore, passed, cases, duration, regression? }`. Each `EvalCaseResult` carries the case, the full `AgentResult`, every scorer's `scores`, the mean `score`, `passed`, and `duration`.
+
+## Regression gating — `baseline` + `tolerance`
+
+```ts
+import { readFile, writeFile } from "node:fs/promises";
+
+const baseline = ai.eval.fromJSON(await readFile("./eval/baseline.json", "utf8"));
+
+const report = await myAgent.eval({
+  cases: ds,
+  scorers: [ai.eval.exact()],
+  baseline,         // a prior EvalReport to diff against
+  tolerance: 0.05,  // max allowed per-case score DROP before it regresses. default 0 (any drop)
+});
+
+if (report.regression && !report.regression.passed) {
+  console.error("Regressed:", report.regression.regressed); // [{ name, before, after }]
+  process.exit(1);
+}
+```
+
+When `baseline` is set the report carries a `regression` block (`EvalRegression`), joining cases by `name`:
+
+- **`regressed`** — `[{ name, before, after }]` for cases whose new score fell more than `tolerance` below baseline.
+- **`added`** / **`removed`** — case names present in only one report. Adding or dropping a case **never fails the gate by itself**.
+- **`passed`** — `true` when `regressed` is empty.
+
+The pure `diff(report, baseline, tolerance)` function (exported as `diff`) is the same logic, decoupled from the runner — depends only on the two reports and the tolerance, mutates neither.
+
+## CI reporters — `ai.eval.toJUnit` / `toJSON` / `fromJSON`
+
+Pure functions over a finished `EvalReport`:
+
+```ts
+// JUnit-XML artifact for CI ingestion — one <testsuite> (the agent), one <testcase> per case,
+// a <failure> on each non-passing case (joined scorer reasons), times in SECONDS.
+await writeFile("./report.junit.xml", ai.eval.toJUnit(report));
+
+// Round-trippable snapshot — today's report becomes tomorrow's baseline.
+await writeFile("./eval/baseline.json", ai.eval.toJSON(report));
+const restored = ai.eval.fromJSON(await readFile("./eval/baseline.json", "utf8"));
+```
+
+`toJSON`/`fromJSON` preserve `result` payloads, per-case `scores`, timings, and any attached `regression` block, so a parsed report drives regression diffing exactly as the in-memory one. `toJUnit` hand-emits XML (no `xml` dependency) and entity-escapes every dynamic value.
+
+## Typical CI shard job
+
+```ts
+const shard = ai.dataset({ name: "support", fromFile: "./eval/support.jsonl" })
+  .shard(Number(process.env.SHARD_INDEX), Number(process.env.SHARD_TOTAL));
+
+const report = await agent.eval({
+  cases: shard,
+  scorers: [ai.eval.contains()],
+  baseline: ai.eval.fromJSON(await readFile("./eval/baseline.json", "utf8")),
+  tolerance: 0.05,
+});
+
+await writeFile(`./out/report-${process.env.SHARD_INDEX}.junit.xml`, ai.eval.toJUnit(report));
+if (report.regression && !report.regression.passed) process.exit(1);
+```
+
+## See also
+
+- [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md) — `ai.eval.{exact,contains,predicate,judge}` scorers + Vitest matchers
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — `agent.eval` scoring loop, `EvalCase` / `EvalJudge`
+- [`@warlock.js/ai/record-replay-llm/SKILL.md`](@warlock.js/ai/record-replay-llm/SKILL.md) — `ai.vcr` for deterministic, offline eval runs
+
+
+## generate-images  `@warlock.js/ai/generate-images/SKILL.md`
+
+---
+name: generate-images
+description: 'Text-to-image via ai.image({ model: sdk.image({ name }), prompt }) — the image-OUTPUT verb (Theme I), returning the uniform never-throws { data, error, usage, report } envelope with cost-truth + panoptic observation. Models come from an adapter''s image() factory: OpenAI gpt-image-* (token-metered) / dall-e-* (per-image), Google imagen-* (per-image). Result images are a discriminated GeneratedImage = { type: "base64" } | { type: "url" }. Triggers: `ai.image`, `sdk.image`, `openai.image`, `google.image`, `ImageModelContract`, `GeneratedImage`, `ImageModelPricing`; ''generate an image'', ''text to image'', ''gpt-image'', ''dall-e'', ''imagen'', ''product thumbnail'', ''image output''; typical import `import { ai } from "@warlock.js/ai"` + `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: image INPUT / vision attachments to a chat agent — `@warlock.js/ai/run-ai-agent/SKILL.md`; embeddings — `@warlock.js/ai/embed-text/SKILL.md`; competing libs raw `openai.images.generate`, `langchain` image tools.'
+---
+
+# Generate images — the image-output verb (`ai.image`)
+
+`ai.image()` is the output counterpart to `ai.agent` for the image modality (the first verb of the output-modality track, Theme I). Prompt-in / images-out, wrapped in the same uniform result contract every executable returns — so it slots into cost dashboards and panoptic traces exactly like an agent run.
+
+This is image **output** (generation). For image/PDF/audio **input** to a chat agent (vision), see [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md).
+
+## Shape
+
+```ts
+// 1. Build an image model from an adapter's image() factory.
+const model = openai.image({ name: "gpt-image-1" });   // ImageModelContract
+
+// 2. Run the verb — never throws; failures land on result.error.
+const { data, error, usage, report } = await ai.image({ model, prompt: "a red bicycle" });
+
+if (error) {
+  console.warn(error.code);          // typed AIError (auth / rate-limit / content-filter / …)
+} else {
+  for (const img of data.images) {   // GeneratedImage[]
+    if (img.type === "base64") save(Buffer.from(img.base64, "base64"), img.mediaType);
+    else download(img.url);
+  }
+}
+```
+
+`ImageModelContract` mirrors `EmbedderContract` — a peer primitive on the SDK adapter, produced by the optional `image?()` factory. An adapter without an image API simply doesn't define `image()`, so `ai.anthropic.image(...)` is a **compile-time** error, not a silent runtime failure.
+
+## The result envelope
+
+```ts
+type ImageResult = {
+  type: "image";
+  data?: { images: GeneratedImage[] };  // undefined on failure
+  error?: AIError;                       // undefined on success — NEVER thrown
+  usage: Usage;                          // tokens (gpt-image) + cost when priced
+  report: ImageReport;                   // type:"image", model, imageCount, lineage
+};
+
+type GeneratedImage =
+  | { type: "base64"; base64: string; mediaType: string; revisedPrompt?: string }
+  | { type: "url"; url: string; mediaType?: string; revisedPrompt?: string };
+```
+
+## Generation options (provider-neutral)
+
+```ts
+await ai.image({
+  model,
+  prompt: "an isometric office desk, soft studio lighting",
+  count: 2,            // n images
+  size: "1024x1024",   // OpenAI WxH (also resolves perImageBySize pricing)
+  quality: "high",     // OpenAI quality tier
+  aspectRatio: "16:9", // Imagen ratio
+  negativePrompt: "blurry, watermark", // Imagen
+  format: "png",       // output container hint
+  signal,              // AbortSignal
+  observe: collector,  // route the report to an Observer (panoptic), like agents
+  sessionId: "checkout-123",
+  options: { background: "transparent" }, // provider-specific passthrough
+});
+```
+
+Each adapter maps the options its API supports and ignores the rest. `options` is the escape hatch for provider-specific knobs (OpenAI `background`, DALL·E `responseFormat: "url"`, Imagen `imageSize` / `personGeneration`).
+
+## OpenAI — gpt-image (token-metered) + DALL·E (per-image)
+
+```ts
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+// gpt-image-1 always returns base64 bytes; priced per TOKEN.
+const gpt = openai.image({ name: "gpt-image-1", pricing: { input: 5, output: 40 } });
+
+// DALL·E 3 — per-image pricing; defaults to base64 (opt into url with options).
+const dalle = openai.image({ name: "dall-e-3", pricing: { perImage: 0.04 } });
+```
+
+A non-image model id (`openai.image({ name: "gpt-4o" })`) throws `InvalidRequestError` **at construction** — fail fast, like the embedder/vision guards.
+
+## Google — Imagen (per-image)
+
+```ts
+import { GoogleSDK } from "@warlock.js/ai-google";
+
+const google = new GoogleSDK({ apiKey: process.env.GEMINI_API_KEY! });
+const imagen = google.image({ name: "imagen-4.0-generate-001", pricing: { perImage: 0.04 } });
+
+const { data } = await ai.image({ model: imagen, prompt: "a watercolor lighthouse at dawn", aspectRatio: "3:4" });
+```
+
+Imagen returns base64 bytes (no hosted URL). When every candidate is safety-filtered, `ai.image` surfaces a typed `ContentFilterError` on `result.error`.
+
+## Cost-truth — one rollup, two metering models
+
+`ai.image` fills `usage.cost` (a `ModelPricing`-shaped USD breakdown) so image spend folds into the **same** `Usage.cost` rollup as text — no second accounting path:
+
+- **Token-metered** (gpt-image-1): `{ input, output }` USD-per-1M-tokens → standard `computeCost` against the returned token usage.
+- **Per-image** (DALL·E, Imagen): `{ perImage }` (or `perImageBySize["1792x1024"]`) × image count → `cost.output`.
+
+Unpriced model → `usage.cost` stays `undefined` (honest "cost unknown", never a false zero). A pre-priced adapter response is honored, not overwritten.
+
+## Pattern — catalog thumbnail in a workflow `run` step
+
+```ts
+ai.step({
+  name: "thumbnail",
+  run: async (ctx) => {
+    const { data, error } = await ai.image({
+      model: openai.image({ name: "gpt-image-1" }),
+      prompt: `product photo, white background: ${ctx.steps.extract.output.title}`,
+      size: "1024x1024",
+    });
+    if (error) throw error; // step retry/backoff handles transient provider faults
+    ctx.state.thumb = data.images[0];
+  },
+});
+```
+
+## Observability
+
+The completed `ImageReport` routes to any registered `Observer` (panoptic, OTel, …) through the shared `observe` seam — pass `observe: true` (global), an `Observer` object (flow-local), or rely on observe-all. Cost + latency attribute to `report.model` for free. See [`@warlock.js/ai/observe-ai-flows/SKILL.md`](@warlock.js/ai/observe-ai-flows/SKILL.md).
+
+## Testing
+
+`MockSDK({ imageResponses, imagePricing }).image({ name })` returns a deterministic `MockImageModel` — no HTTP. Script images/usage/errors and inspect `model.calls`.
+
+```ts
+import { MockSDK } from "@warlock.js/ai";
+
+const mock = MockSDK({ imageResponses: [{}], imagePricing: { perImage: 0.04 } });
+const { data, usage } = await ai.image({ model: mock.image({ name: "mock-image" }), prompt: "x" });
+```
+
+
+## generate-speech  `@warlock.js/ai/generate-speech/SKILL.md`
+
+---
+name: generate-speech
+description: 'Text-to-speech via ai.speech({ model: sdk.speech({ name }), text }) — the audio-OUTPUT verb (Theme I), returning the uniform never-throws { data, error, usage, report } envelope with cost-truth + panoptic observation. Models come from an adapter''s speech() factory: OpenAI tts-1 / tts-1-hd (per-character) or gpt-4o-mini-tts (per-token). Synthesized audio is a discriminated GeneratedAudio = { type: "base64"; base64; mediaType }. Options: voice / format / speed / instructions / signal. Triggers: `ai.speech`, `sdk.speech`, `openai.speech`, `SpeechModelContract`, `GeneratedAudio`, `SpeechModelPricing`, `SpeechOptions`, `MockSpeechModel`; ''text to speech'', ''TTS'', ''synthesize voice'', ''read this aloud'', ''tts-1'', ''gpt-4o-mini-tts'', ''voice narration'', ''audio output'', ''speak this text''; typical import `import { ai } from "@warlock.js/ai"` + `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: speech-to-text / transcribing a voice note — [[transcribe-audio]]; image OUTPUT — [[generate-images]]; competing libs raw `openai.audio.speech.create`, `elevenlabs` SDK.'
+---
+
+# Generate speech — the text-to-speech verb (`ai.speech`)
+
+`ai.speech()` is the audio-output counterpart to `ai.image()` on the output-modality track (Theme I). Text-in / audio-out, wrapped in the same uniform result contract every executable returns — so a synthesized voicemail slots into cost dashboards and panoptic traces exactly like an agent run.
+
+This is audio **output** (TTS). For audio **input** (speech-to-text on a WhatsApp voice note or a meeting recording), see [[transcribe-audio]].
+
+## Shape
+
+```ts
+// 1. Build a speech model from an adapter's speech() factory.
+const model = openai.speech({ name: "tts-1", voice: "alloy" }); // SpeechModelContract
+
+// 2. Run the verb — never throws; failures land on result.error.
+const { data, error, usage, report } = await ai.speech({ model, text: "Your order has shipped." });
+
+if (error) {
+  console.warn(error.code);          // typed AIError (auth / rate-limit / content-filter / …)
+} else {
+  const { base64, mediaType } = data.audio; // GeneratedAudio (always base64 today)
+  await fs.writeFile("ship.mp3", Buffer.from(base64, "base64"));
+}
+```
+
+`SpeechModelContract` mirrors `EmbedderContract` / `ImageModelContract` — a peer primitive produced by the adapter's optional `speech?()` factory. An adapter without a TTS API simply doesn't define `speech()`, so calling it is a **compile-time** error, not a silent runtime failure. A non-TTS model id (`openai.speech({ name: "gpt-4o" })`) throws `InvalidRequestError` **at construction** — fail fast, like the embedder/image guards.
+
+## The result envelope
+
+```ts
+type SpeechResult = {
+  type: "speech";
+  data?: { audio: GeneratedAudio }; // undefined on failure
+  error?: AIError;                  // undefined on success — NEVER thrown
+  usage: Usage;                     // tokens (gpt-4o-mini-tts) + cost when priced
+  report: SpeechReport;             // type:"speech", model, characters, lineage
+};
+
+type GeneratedAudio = {
+  type: "base64";
+  base64: string;    // base64-encoded audio bytes
+  mediaType: string; // IANA type, e.g. "audio/mpeg", "audio/wav"
+};
+```
+
+`GeneratedAudio` is a discriminated union with a single `base64` variant today — the union leaves room for a future hosted-`url` variant without a breaking change, so always branch on `audio.type` rather than assuming `base64`.
+
+## Generation options (provider-neutral)
+
+```ts
+await ai.speech({
+  model,
+  text: "Welcome aboard. Let's get you set up.",
+  voice: "verse",                 // voice id/name; overrides the model's default
+  format: "wav",                  // "mp3" | "opus" | "aac" | "flac" | "wav" | "pcm"
+  speed: 1.25,                    // playback multiplier (OpenAI 0.25–4.0)
+  instructions: "calm, warm",     // tone/delivery steering (gpt-4o-mini-tts only)
+  signal,                         // AbortSignal
+  observe: collector,             // route the report to an Observer (panoptic), like agents
+  sessionId: "onboarding-42",     // group into a session for flat cost/trace queries
+  options: { /* provider passthrough */ },
+});
+```
+
+Each adapter maps the options its API supports and forwards `options` verbatim. On OpenAI the container defaults to `mp3` (→ `audio/mpeg`); `speed` and `instructions` are only sent when set, and the default voice is `alloy` when neither the call nor the model config supplies one.
+
+## OpenAI — tts-1 (per-character) + gpt-4o-mini-tts (per-token)
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+// tts-1 / tts-1-hd — billed per INPUT CHARACTER.
+const classic = openai.speech({ name: "tts-1", voice: "alloy", pricing: { perMillionCharacters: 15 } });
+
+// gpt-4o-mini-tts — billed per TOKEN like a chat model; supports `instructions`.
+const steered = openai.speech({ name: "gpt-4o-mini-tts", pricing: { input: 0.6, output: 12 } });
+
+const { data } = await ai.speech({ model: steered, text: "Read this warmly.", instructions: "gentle" });
+```
+
+## Cost-truth — one rollup, two metering models
+
+`ai.speech` fills `usage.cost` (a USD breakdown) so TTS spend folds into the **same** `Usage.cost` rollup as text — no second accounting path:
+
+- **Per-character** (`tts-1` / `tts-1-hd`): `{ perMillionCharacters }` × `report.characters` → `cost.input`. The Speech API reports no token usage, so `usage` tokens stay `{ 0, 0, 0 }` and spend is priced entirely from the input character count.
+- **Token-metered** (`gpt-4o-mini-tts`): `{ input, output }` USD-per-1M-tokens → standard `computeCost` against the returned token usage.
+
+Per-character wins when both are set. An unpriced model leaves `usage.cost` **`undefined`** (honest "cost unknown", never a false zero); a pre-priced adapter response is honored, not overwritten.
+
+## Pattern — order-confirmation voice line in a workflow `run` step
+
+```ts
+ai.step({
+  name: "voiceLine",
+  run: async (ctx) => {
+    const { data, error } = await ai.speech({
+      model: openai.speech({ name: "tts-1", voice: "alloy" }),
+      text: `Order ${ctx.steps.order.output.id} confirmed. Thank you!`,
+      format: "mp3",
+    });
+    if (error) throw error; // step retry/backoff handles transient provider faults
+    ctx.state.audio = data.audio; // { type:"base64", base64, mediaType:"audio/mpeg" }
+  },
+});
+```
+
+## Observability
+
+The completed `SpeechReport` (with `report.characters` and cost/latency attributed to `report.model`) routes to any registered `Observer` (panoptic, OTel, …) through the shared `observe` seam — pass `observe: true` (global), an `Observer` object (flow-local), or rely on observe-all. See [[observe-ai-flows]]. Provider faults surface as typed `AIError`s on `result.error`; see [[handle-ai-errors]].
+
+## Testing
+
+`MockSpeechModel(name, responses, pricing?)` is a deterministic `SpeechModelContract` double — no HTTP. Script audio/usage/errors and inspect `model.calls`. `MockSDK({ speechResponses, speechPricing }).speech({ name })` wires the same double behind a full adapter.
+
+```ts
+import { MockSpeechModel } from "@warlock.js/ai";
+import { speech } from "@warlock.js/ai";
+
+const model = new MockSpeechModel("tts-1", [{}], { perMillionCharacters: 15 });
+const { data, usage } = await speech({ model, text: "abcdefghij" }); // 10 chars
+// data.audio → { type:"base64", base64:"AAAA", mediaType:"audio/mpeg" }
+// usage.cost.input → (10 * 15) / 1_000_000
+// model.calls[0] records { text, options } for assertions
+```
+
+Scripting `[{ error: new ProviderRateLimitError("slow down") }]` drives the never-throws path — `result.error` is the typed error and `result.data` is `undefined`.
+
+## See also
+
+- [[transcribe-audio]] — the inverse verb (`ai.transcribe`), audio → text
+- [[generate-images]] — the sibling image-output verb (`ai.image`)
+- [[observe-ai-flows]] — routing the `SpeechReport` to panoptic / OTel
+- [[handle-ai-errors]] — the typed `AIError` taxonomy on `result.error`
+
+
+## guard-input-output  `@warlock.js/ai/guard-input-output/SKILL.md`
+
+---
+name: guard-input-output
+description: 'Build the composed guardrail middleware with @warlock.js/ai-guard and wire it into an agent — `ai.guardrail({ input, output, tool, toolNames, escalation })`. Triggers: `ai.guardrail`, `guard`, `GuardOptions`, `GuardrailVerdict`, `GuardrailDetector`, `GuardrailPhase`, `GuardrailMatch`, `GuardrailViolationError`, `ai.guardrail.topic`, `ai.guardrail.injection`, `topicFilter`, `injectionDetector`, `toolNames`, `forTool`; ''add a guardrail to my agent'', ''block prompt injection'', ''filter banned topics'', ''guard agent input and output'', ''stop the model leaking data into a tool call'', ''scope a detector to one tool''; typical import `import "@warlock.js/ai-guard"` (registers `ai.guardrail`) or `import { guard } from "@warlock.js/ai-guard"`. Skip: PII detection/redaction specifically — `@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md`; routing a block to a human — `@warlock.js/ai-guard/escalate-block-to-human/SKILL.md`; the core middleware pipeline / hook contract — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
+---
+
+# Guard agent input, output, and tool args
+
+`ai.guardrail(...)` is a **middleware factory**. It produces one `AgentMiddleware` that runs your detectors at three hook points and maps each verdict onto the agent pipeline's existing throw / return / record mechanics. Importing the package registers the verb (and its attached detector factories) on the shared `ai` namespace:
+
+```ts
+import { ai } from "@warlock.js/ai";
+import "@warlock.js/ai-guard"; // registers ai.guardrail + ai.guardrail.pii/.topic/.injection/.moderation
+
+const policy = ai.guardrail({
+  name: "compliance",
+  input: [ai.guardrail.injection({ onMatch: "block" })],
+  output: [ai.guardrail.topic({ deny: [/medical advice/i, "diagnosis"], onMatch: "block" })],
+});
+
+const agent = ai.agent({ model, middleware: [policy] });
+```
+
+A named-export form is available for callers who prefer not to rely on the augmented namespace:
+
+```ts
+import { guard, topic, injection } from "@warlock.js/ai-guard";
+const policy = guard({ input: [injection({ onMatch: "block" })] });
+```
+
+## The three phases
+
+| Phase | Hook | Inspected text | Set with |
+|---|---|---|---|
+| **input** | `trip.before` | the outbound prompt (`extractUserText(ctx.messages)`) | `input: [...]` |
+| **output** | `trip.after` | `response.content` | `output: [...]` |
+| **tool** | `tool.before` | `JSON.stringify(toolArgs)` | `tool: [...]` |
+
+Each phase array runs its detectors in **registration order**; the first non-`allow` verdict decides the action for that phase (short-circuit). A phase you don't configure is inert — a guard with no detectors is a no-op middleware.
+
+## The verdict model
+
+A detector inspects text and returns a `GuardrailVerdict`, discriminated by `type` (never `kind`):
+
+| `type` | Effect |
+|---|---|
+| `allow` | Pass to the next detector. |
+| `redact` | Rewrite the inspected text and continue — **output phase only** (see limitation below). |
+| `block` | Short-circuit with the existing `GuardrailViolationError`. |
+| `flag` | Pass, but append a `FlagRecord` into `ctx.state` under `<name>.flags` for a downstream observer (panoptic, the caller). |
+
+`agent.execute()` **never throws** — a `block` surfaces on `result.error` as a `GuardrailViolationError`, exactly like every other `AIError`. Branch on it after the run:
+
+```ts
+const result = await agent.execute(userInput);
+
+if (result.error instanceof ai.errors.GuardrailViolationError) {
+  // result.error.phase is "input" | "output" | "tool"
+  // result.error.reason / result.error.guardrail carry the detail
+}
+```
+
+## Built-in detectors
+
+Three zero-dependency detectors ship (a fourth, `moderation`, is an optional `openai` peer — see [`detect-and-redact-pii/SKILL.md`](@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md)):
+
+- **`ai.guardrail.injection(options?)`** — jailbreak / prompt-injection marker phrases. Extra `markers` (string | RegExp); `onMatch` defaults to `"flag"`, callers commonly use `"block"` on input.
+- **`ai.guardrail.topic(options)`** — `deny` (string substring | RegExp) and/or `allow` (allow-list miss triggers `onMatch`). `onMatch` is `"block" | "flag"`, default `"block"`.
+- **`ai.guardrail.pii(options?)`** — PII regex + dictionary (its own skill).
+
+```ts
+const policy = ai.guardrail({
+  input: [
+    ai.guardrail.injection({ onMatch: "block", markers: ["ignore previous instructions"] }),
+    ai.guardrail.topic({ deny: ["competitor-name"], onMatch: "block" }),
+  ],
+});
+```
+
+## Scope tool detectors to specific tools
+
+`tool` detectors fire on **every** tool call by default. Set `toolNames` to scope them — the whole middleware is wrapped with the core `forTool(toolNames, mw)` helper so the `tool` hooks fire only for those names; `input` / `output` (`trip`) hooks are unaffected:
+
+```ts
+const policy = ai.guardrail({
+  tool: [ai.guardrail.pii({ onMatch: "block" })], // stop PII reaching the tool
+  toolNames: ["send_email", "post_webhook"],      // ...only for these tools
+});
+
+const agent = ai.agent({ model, tools: [sendEmail, postWebhook, lookup], middleware: [policy] });
+// `lookup` runs unguarded; `send_email` / `post_webhook` block on PII in their args.
+```
+
+A `block` from `tool.before` aborts that tool dispatch and surfaces on `result.error` with `phase: "tool"` — the agent run itself still never crashes.
+
+## Install order
+
+A guard is a normal `AgentMiddleware`; registration order is execution order (`before` top-down, `after` bottom-up). The canonical order is `[cache, budget, guardrail, observability]`. A `semanticCache` that short-circuits `trip.before` runs *before* the guard — a cached response then skips the **output** detectors, so place the guard before the cache if you don't trust cached contents.
+
+## Input-redaction limitation (v1)
+
+The core `trip.before` hook can only **short-circuit** (return a `ModelResponse`); it cannot rewrite the outbound prompt and continue. So:
+
+- **Input detectors are `block` / `flag` only.** A `redact` verdict on an input detector is treated as a `block` rather than silently passing an un-redacted prompt.
+- **Output redaction works** — `trip.after` returns a replacement `ModelResponse` with the rewritten `content`.
+- **Tool-arg `redact` is also withheld** — it downgrades to a `block` (`reason: "tool-arg-redaction-unsupported"`), because silently rewriting tool arguments changes the call's side-effects unpredictably.
+
+Lifting the input limitation needs a small, non-breaking core affordance and is deferred.
+
+## Failure isolation
+
+A detector's `check()` **rejecting** is an infrastructure fault, not a content violation — it is recorded as a `flag` (`<detector>.error`) into `ctx.state` and the fold **continues** (fail-open). A moderation-API outage degrades to missing annotation, never a failed agent run.
+
+## See also
+
+- [`@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md`](@warlock.js/ai-guard/detect-and-redact-pii/SKILL.md) — the `pii` detector (detect/redact/block), the `mask` template, and the optional `moderation` peer.
+- [`@warlock.js/ai-guard/escalate-block-to-human/SKILL.md`](@warlock.js/ai-guard/escalate-block-to-human/SKILL.md) — routing a `block` to a human-review surface via `escalation.onBlock`.
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — running the agent, the middleware pipeline, and the `GuardrailViolationError` on `result.error`.
+
+
+## handle-ai-errors  `@warlock.js/ai/handle-ai-errors/SKILL.md`
+
+---
+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 (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
+
+Every error surfaced by `@warlock.js/ai` and every adapter package is an `AIError` subclass with a stable `code`. The base extends platform `Error`; it does NOT extend `HttpError`. Plain `Error` never leaks.
+
+## Two invariants
+
+1. **`execute()` never throws.** Every `agent.execute()` / `workflow.execute()` resolves with a well-formed result. Failures funnel into `result.error`. Same for `stream.result`.
+2. **Every error is an `AIError`.** Both core and adapter packages funnel everything through `AIError` subclasses. Branch on `error.code` (stable string) or `instanceof`.
 
 ## Dispatch pattern
 
@@ -1197,109 +2330,397 @@ description: 'Durable orchestrator stores — ai.checkpoint.{memory,pg,redis}()
 ```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
-});
-```
+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`
+
+
+## manage-prompts  `@warlock.js/ai/manage-prompts/SKILL.md`
+
+---
+name: manage-prompts
+description: 'Unified prompt registry — ai.prompts: one process-wide store of named, versioned systemPrompt(...) builders keyed by name@version. Register by giving a prompt a meta.name (auto-registers), resolve by get(name) / resolve(name, versionOrTag, placeholders) / the inline name@selector form, bulk-register with define(name, versions), pin tags with tag(name, tag, version), compare with diff(name, from, to), round-trip with export() / import(snapshot), and quality-check with a unified validate(target, options) (deterministic missing-placeholder check + optional Nova-safe LLM-as-judge with verdict caching). Compose registered prompts into new ones with systemPrompt().merge(name, { fromVersion }) — provenance recorded in meta.composedFrom. ai.prompt is now a thin FACADE over ai.prompts (BREAKING vs the old standalone registry). Triggers: `ai.prompts`, `ai.prompt`, `PromptsManagerContract`, `PromptsManagerEntry`, `SystemPromptContract`, `SystemPromptMeta`, `SystemPromptMergeOptions`, `PromptsValidateOptions`, `PromptValidationResult`, `PromptValidateTarget`, `PromptTemplateVersion`, `PromptDiff`, `ExportedRegistry`, `defaultPromptsManager`, `prompts()`, `promptKey`, `meta`, `name`, `version`, `composedFrom`, `fromVersion`, `register`, `create`, `get`, `has`, `list`, `versions`, `resolve`, `define`, `tag`, `validate`, `diff`, `export`, `import`, `merge`, `judge`, `judgeCache`; ''register a prompt by name'', ''resolve a prompt by name@version or tag'', ''pin a production tag to a prompt version'', ''diff two prompt versions'', ''export / import the prompt registry'', ''validate a prompt for missing placeholders'', ''merge a registered prompt into another''; typical import `import { ai } from "@warlock.js/ai"`. Skip: composing a single prompt from persona + instruction blocks (the builder itself) — `@warlock.js/ai/write-system-prompt/SKILL.md`; runtime loadable skill bodies — `@warlock.js/ai/use-runtime-skills/SKILL.md`; eval scoring of agent outputs — `@warlock.js/ai/eval-datasets-and-ci/SKILL.md`; competing libs `langfuse` (direct), `promptfoo`.'
+---
+
+# `ai.prompts` — the unified prompt registry
+
+`ai.prompts` is ONE process-wide registry of named, versioned `systemPrompt(...)` builders keyed by `name@version`. A `systemPrompt(input, { name })` (or any `.meta({ name })` rename) auto-registers here; `ai.prompts.get(name)` / `.resolve(name)` read them back; `systemPrompt().merge(name)` folds a registered prompt into a new one. There is exactly **one storage shape** behind the whole prompt surface — a `SystemPromptContract` keyed by `name@version` — and `ai.prompt(...)` is now a thin facade over it (see the migration note below).
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+// Register: any named systemPrompt auto-registers in ai.prompts.
+ai.systemPrompt("You are support for {{product}}.", { name: "support" });
+
+// Resolve back — latest version, or a version / pinned tag.
+ai.prompts.get("support");                 // → the SystemPromptContract
+ai.prompts.resolve("support", undefined, { product: "Warlock" }); // → final string
+```
+
+`ai.prompts` is the process-wide default (`defaultPromptsManager()`). For an **isolated** registry (parallel test suites, multi-tenant apps) call the `prompts()` factory — same `PromptsManagerContract`, its own store, no global side effects.
+
+## Identity — `SystemPromptMeta` (`meta.name` / `version` / `description` / `required` / `composedFrom`)
+
+A prompt's identity rides on its `meta`. Read it with the no-argument accessor; update it immutably with the one-argument form:
+
+```ts
+const base = ai.systemPrompt("You are support.", {
+  name: "support",
+  version: "1",
+  description: "Tier-1 support persona.",
+  required: ["product"],
+});
+
+base.meta();                          // → { name: "support", version: "1", description, required }
+const v2 = base.meta({ version: "2" }); // new builder, shallow-merged meta; original untouched
+```
+
+- **`name`** — when present, the prompt auto-registers in `ai.prompts` under `name@version`. Anonymous prompts (no `name`) are never registered.
+- **`version`** — free-form label (`"1"`, `"2025-draft"`). Defaults to the **next integer** for that name when omitted.
+- **`description`** — human-readable purpose (carried through `export`).
+- **`required`** — placeholder keys callers must supply; `validate()` reads them.
+- **`composedFrom`** — deterministic source labels a prompt was merged from (e.g. `["base@2", "global@1"]`). No random suffixes — the same merge always yields the same labels.
+
+## Register / resolve — `register` / `get` / `resolve` / `has` / `list` / `versions`
+
+```ts
+const registry = ai.prompts;              // or prompts() for an isolated one
+
+registry.register(ai.systemPrompt("You are support.", { name: "support" }));
+registry.versions("support");             // ["1"] — version derived as next integer
+
+registry.get("support");                  // latest SystemPromptContract
+registry.get("support@1");                // inline name@selector
+registry.resolve("support", "1", { product: "Warlock" }); // pick version + render in one call
+
+registry.has("support");                  // boolean
+registry.list();                          // every registered name, first-seen order
+```
+
+- **Version selection** — `get(name)` / `resolve(name)` return the **latest** by insertion order; pass a version label, a pinned tag, or fold it into the first arg as `name@selector` (`get("support@1")`, `resolve("support@production")`).
+- **Duplicates** — re-registering the same `name@version` throws `InvalidRequestError` **unless** the content is byte-identical (idempotent re-registration is a no-op).
+- **Unknown name / version / tag** → `InvalidRequestError`.
+- `register()` throws if the prompt has no `meta.name`.
+
+## `create()` — build + register in one entry point
+
+`ai.prompts.create(input?, meta?)` is a documented alias of `ai.systemPrompt(...)` — identical input forms (no arg → empty builder; a string → one instruction; an array of blocks → verbatim). Pass `meta.name` to auto-register, so authoring and lookup read side-by-side:
+
+```ts
+ai.prompts.create("You are support for {{product}}.", { name: "support" });
+ai.prompts.resolve("support", undefined, { product: "Warlock" });
+```
+
+## `define()` — bulk-register many versions
+
+```ts
+ai.prompts.define("agent", [
+  { version: "1", template: "You are v1." },
+  { version: "2", template: [ai.persona("You are Alex."), ai.instruction("Be concise.")] },
+]);
+```
+
+A `PromptTemplateVersion`'s `template` is a raw string (wrapped into one instruction block) or an explicit ordered block list (verbatim). Versions register **oldest-first** in array order; the same duplicate / idempotency rule applies per `name@version`. Returns the manager for chaining.
+
+## `tag()` — pin a moving label to a version
+
+```ts
+ai.prompts.tag("agent", "production", "2");   // pin "production" → version 2
+
+ai.prompts.get("agent", "production");        // resolves through the tag
+ai.prompts.resolve("agent", "production");
+ai.prompts.get("agent@production");           // inline form
+```
+
+Re-pinning an existing tag moves it. An unknown name / version throws `InvalidRequestError`. Tags survive `export` / `import`.
+
+## `validate()` — unified deterministic + optional LLM-judge
+
+```ts
+const report = await ai.prompts.validate("support", {
+  placeholders: { product: "Warlock" }, // values you intend to supply
+  declare: ["language"],                  // extra keys to treat as known
+  judge: judgeModel,                      // optional — turns on the LLM-as-judge pass
+});
+
+report.ok;       // true iff no required placeholder is missing (DETERMINISTIC verdict alone)
+report.missing;  // placeholder keys referenced with no default, unsupplied, undeclared
+report.score;    // 0..1 — present ONLY when a judge ran and produced a usable verdict
+report.issues;   // advisory judge reasons / a degrade note — present only when a judge was supplied
+```
+
+- **Always** runs the deterministic check: every `{{key}}` with no inline default that is neither supplied (`placeholders`), declared (`declare`), nor in the prompt's `meta.required` lands in `missing`; `ok` is `true` iff `missing` is empty.
+- **`judge`** adds a **Nova-safe** LLM-as-judge quality pass — it **never throws** and degrades to an `issues` note (leaving `score` undefined) on failure, so a flaky judge can **never flip `ok`**.
+- **`target`** is a registered name (or `name@selector`), a `SystemPromptContract` instance, or a raw prompt string.
+- **`judgeCache`** (per-call or via the `prompts({ judgeCache })` factory option) memoizes judge verdicts by a content hash of the resolved body + the judge model id — a structural `{ get, set }` subset of `@warlock.js/cache`'s `CacheDriver`, so the cache package stays a strictly **optional** peer.
+
+`systemPrompt().validate(options?)` is the per-builder sugar — `ai.prompts.validate(this, options)` under the hood, same result shape.
+
+## `diff()` — block-level version diff
+
+```ts
+const diff = ai.prompts.diff("agent", "1", "2");
+
+diff.identical;  // true when both versions have identical blocks in identical order
+diff.added;      // blocks in `to` not at the same position in `from`
+diff.removed;    // blocks in `from` not at the same position in `to`
+diff.changed;    // [{ from, to }] — same position, type/text changed
+```
+
+Blocks are matched **positionally**. Unknown name / version → `InvalidRequestError`.
+
+## `export()` / `import()` — portable JSON round-trip
+
+```ts
+const snapshot = ai.prompts.export();   // ExportedRegistry — every name, version, pinned tag, description/required
+otherRegistry.import(snapshot);          // rehydrate (same duplicate / idempotency rule; tags restored)
+```
+
+Each version flattens to `{ type, text }` blocks so the registry round-trips without live builder instances — commit a snapshot, ship it, restore it elsewhere.
+
+## Compose registered prompts — `systemPrompt().merge(name, { fromVersion })`
+
+`merge` folds another prompt's blocks into a new builder (persona **replaces**, instructions **append**) and records `meta.composedFrom`:
+
+```ts
+ai.systemPrompt("Always answer in {{language|English}}.", { name: "global", version: "1" });
+
+const supportPrompt = ai.systemPrompt("You are support for {{product}}.")
+  .merge("global", { fromVersion: "1" });  // fold the registered prompt by name
+
+supportPrompt.meta()?.composedFrom;        // ["…", "global@1"] — deterministic provenance
+```
+
+`merge` accepts three source forms: a pre-built block, another `SystemPromptContract`, or a **registered name** resolved from `ai.prompts` (latest version unless `options.fromVersion` selects another — an unknown name / version throws `InvalidRequestError`).
+
+## `ai.prompt(...)` — now a thin facade (⚠ breaking vs the old registry)
+
+`ai.prompt` has **two** call forms, both backed by the unified manager — there is no longer a separate prompt store:
+
+```ts
+// (a) Resolve a globally-registered prompt from ai.prompts by name.
+ai.systemPrompt("You are support.", { name: "support" });
+const sp = ai.prompt("support");          // → SystemPromptContract (latest)
+const v1 = ai.prompt("support", "1");     // → a specific version / pinned tag
+
+// (b) Build an ISOLATED legacy-shaped registry (PromptRegistryContract).
+const reg = ai.prompt({
+  prompts: [{ name: "summarizer", versions: [{ version: "1", template: "Summarize: {{text}}" }] }],
+});
+const resolved = reg.resolve("summarizer", { placeholders: { text } });
+resolved.toSystemPrompt();                 // drop-in for ai.agent({ systemPrompt })
+```
+
+**⚠ Migration.** Before unification, `ai.prompt(...)` only built a standalone, self-contained registry with its **own private** storage. It now:
+
+1. Adds the **string overload** `ai.prompt(name, versionOrTag?)` → resolves from the shared `ai.prompts` manager. (New capability — `ai.prompt("x")` used to be a type error.)
+2. Backs the **options form** (`ai.prompt({ ... })` → `PromptRegistryContract`) by an internal `PromptsManagerContract`, so its storage shape and validation primitives are now the unified ones. The legacy method surface (`register` / `add` / `versions` / `resolve` / `validate` / `sync` + the `{ score, notes }` report shape) is **unchanged**, and each `ai.prompt({ ... })` call still returns its **own isolated** registry — no shared global state.
+
+If you only ever called `ai.prompt({ ... })` and used the returned registry, **no code change is needed**. The new behavior is additive: prefer `ai.prompts` (the unified manager) for new code; reach for `ai.prompt({ ... })` only when you want the legacy `ResolvedPrompt` / `toSystemPrompt()` ergonomics or the optional Langfuse sync. The legacy facade's reference — `register` / `add` / `resolve(name, { version, placeholders })` / `validate` (`{ score, notes }`) / `sync()` (lazy `langfuse` peer) — is documented inline in `src/prompt/prompt.ts`.
+
+## See also
+
+- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — the `systemPrompt()` / `persona()` / `instruction()` builder, `.meta()`, and `merge()` this registry stores and composes
+- [`@warlock.js/ai/eval-datasets-and-ci/SKILL.md`](@warlock.js/ai/eval-datasets-and-ci/SKILL.md) — the eval `judge` scorer `validate()`'s LLM pass reuses
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — wiring a resolved prompt into an agent, plus the judge-safe agent preset (`ai.agent.judge`)
+
+
+## observe-ai-flows  `@warlock.js/ai/observe-ai-flows/SKILL.md`
+
+---
+name: observe-ai-flows
+description: 'The core Observer seam — a generic, tool-agnostic observability hook every flow routes its completed ExecutionReport through. Covers the per-flow `observe?: boolean | Observer` option on ai.agent / workflow / supervisor / team, the global registry (registerObserver / getObservers / setObserveAll / isObserveAll / clearObservers), resolveObservers / notifyObservers resolution, the opt-in AgentConfig.captureMessages → AgentReport.messages full-history capture, the onConfigApplied dependency-inversion seam, and that @warlock.js/ai-panoptic is the batteries-included Observer. Triggers: `Observer`, `observe`, `registerObserver`, `getObservers`, `setObserveAll`, `isObserveAll`, `clearObservers`, `resolveObservers`, `notifyObservers`, `FlowObserveOption`, `ExecutionReport`, `captureMessages`, `AgentReport.messages`, `CapturedMessage`, `onConfigApplied`, `observeAll`; ''observe an agent run'', ''send finished reports to a collector'', ''capture the full message history'', ''observe every flow by default'', ''wire panoptic / tracing''; typical import `import { ai, registerObserver } from "@warlock.js/ai"`. Skip: structured logging of events — `@warlock.js/ai/log-ai-calls/SKILL.md`; reading the report tree shape (trips / children) — `@warlock.js/ai/run-ai-agent/SKILL.md`; per-call cost / usage rollup — `@warlock.js/ai/handle-ai-errors/SKILL.md`. The batteries-included Observer is the `@warlock.js/ai-panoptic` package.'
+---
+
+# The `Observer` seam — generic, tool-agnostic observability
 
-### Global defaults
+Core defines a structural `Observer` and a tiny registry; it never imports any observability package (panoptic, OTel, Langfuse, …). A flow that resolves to "observed" hands its completed `ExecutionReport` to every registered observer. An observability tool **implements `Observer` and registers itself**, so `observe: true` / observe-all route reports without coupling core to the tool — the dependency inversion that keeps the two sides decoupled.
 
 ```ts
-ai.config({
-  defaultCheckpointStore: ai.checkpoint.memory(),
-  defaultSnapshotStore: ai.snapshot.memory(),
-});
+export interface Observer {
+  collect(report: ExecutionReport): void | Promise<void>;
+}
 ```
 
-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
+`collect` may be sync or async — the flow awaits it. A throw is **swallowed** by the flow (never breaks the run), mirroring the existing `onUsage` / `onComplete` hooks.
 
-| 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 |
+## Per-flow `observe` option
 
-`@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.
+`observe?: boolean | Observer` (`FlowObserveOption`) is accepted on **`ai.agent`, `ai.workflow`, `ai.supervisor`, and `ai.team`** (a team forwards it verbatim to the supervisor it desugars into):
 
 ```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" });
+const collector: Observer = { collect(report) { exporter.send(report); } };
 
-// redis
-ai.checkpoint.redis({ client: redisClient, prefix: "warlock:orchestrator", ttl: 86_400 });
-ai.snapshot.redis({ client: redisClient, prefix: "warlock:snapshot" });
+ai.agent({ model, observe: true });       // → the globally registered observers, even if observe-all is off
+ai.agent({ model, observe: false });      // → opt out entirely, even when observe-all is on
+ai.agent({ model, observe: collector });  // → a flow-LOCAL collector; only this flow's report, only to it
+ai.agent({ model });                      // → undefined: follow the global observe-all flag
 ```
 
-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`.
+Resolution (`resolveObservers(observe)`):
 
-## Schema is NEVER auto-migrated
+- `false` → `[]` (opted out).
+- `true` → the globally registered observers.
+- an `Observer` object → just that one (flow-local; the global observers are skipped).
+- `undefined` → the global observers when observe-all is on, otherwise `[]`.
 
-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:
+`notifyObservers(observe, report)` routes a completed report to each resolved observer, awaiting each `collect` (so async exporters finish before the flow returns) and swallowing any throw. The object form is typed as the structural `Observer` (NOT a panoptic-specific type), so a panoptic flow-local collector — which implements `Observer` — can be passed directly.
+
+## The global registry
 
 ```ts
-const store = ai.checkpoint.pg({ client: pool });
-await pool.query(store.schema());   // once, via your migration tooling
+import {
+  registerObserver, getObservers, setObserveAll, isObserveAll, clearObservers,
+} from "@warlock.js/ai";
+
+registerObserver(collector);  // an observability tool registers ONE collector when its config is applied
+getObservers();               // read-only snapshot of the registered observers (do not mutate)
+
+setObserveAll(true);          // "observe every flow by default" — flows without their own `observe` get observed
+isObserveAll();               // read the flag (default false — opt-in observability)
+
+clearObservers();             // test-only: reset observers + the observe-all flag for spec isolation
 ```
 
-The memory and redis drivers return an empty `schema()` string (no backing table), so callers can treat `schema()` uniformly.
+`observeAll` defaults to `false` (opt-in). A flow that never sets `observe` is observed **only** when observe-all is on; individual flows still opt out with `observe: false`.
 
-## `CheckpointRecord` — the persisted row
+## Full-history capture — `captureMessages` → `AgentReport.messages`
+
+Off by default. When `ai.agent({ captureMessages: true })` is set, the agent normalizes the real assembled turn array onto `AgentReport.messages` as a `CapturedMessage[]`:
 
 ```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
-};
+const { report } = await ai.agent({ model, tools, captureMessages: true }).execute("Go");
+report.messages; // CapturedMessage[] — every role (system/user/assistant/tool), every trip
 ```
 
-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
+A `CapturedMessage` is a JSON-safe projection: `{ role, content, toolCalls?, toolCallId? }` — `content` is always a string (tool results stringified), assistant turns that triggered tools carry `toolCalls`, tool-result turns carry the `toolCallId` they answer. Unlike `trips[].input` (which stubs non-first trips with `"[tool results]"`), this preserves the **real** turn array. Omitted ⇒ the field is **absent** and the report is byte-for-byte as before. Opt-in because messages can be large and sensitive (full prompts, tool inputs/outputs) — and **required for panoptic full-history capture**.
 
-Both stores: `load(...)`, `save(...)`, `delete(...)`, optional `list(...)`, `schema()`.
+## Callback sub-agents nest in the report tree
 
-- **`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.
+The `ExecutionReport` an observer receives reflects **full** lineage: a supervisor / team / orchestrator callback that calls `agent.execute()` directly auto-nests `callback → agent → tool` (via an ambient `RunFrame`), so usage / cost roll up and panoptic renders the sub-agent under its callback instead of as a lone `$0` span. No observer-side change is needed — the tree arrives already nested. A team's root span carries `type: "team"` (a first-class `ReportType`, not `"supervisor"`), so observers can distinguish, group, and label team runs as their own type. See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
 
-## Boot-drain pattern
+## The config seam — `onConfigApplied`
 
-On startup, resume any session whose last turn was interrupted mid-flight:
+An observability tool reacts to its own augmented config slot without core importing it. Core lets tools attach an opaque slot (e.g. `panoptic?`) via declaration merging on `AIConfig`, then fires registered listeners after each `ai.config(...)` merge:
 
 ```ts
-const sessions = await checkpointStore.list?.(orch.name) ?? [];
-for (const sessionId of sessions) {
-  await orch.resume(sessionId);   // null when nothing in flight — harmless
-}
+import { onConfigApplied, getAIConfig } from "@warlock.js/ai";
+
+onConfigApplied((config) => applyPanopticConfig(config.panoptic)); // react on every config merge
+applyPanopticConfig(getAIConfig().panoptic);                        // catch a pre-set config
 ```
 
-## Distinct from `@warlock.js/cache` snapshot resume
+A misbehaving listener's throw is swallowed (same swallow-on-throw discipline as the observer hooks). This mirrors the `Observer` registry's dependency inversion: a tool flips `setObserveAll(true)` and calls `registerObserver(...)` from inside its `onConfigApplied` listener.
 
-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.
+## The batteries-included Observer
+
+`@warlock.js/ai-panoptic` is the shipped, full-featured `Observer` — install it, configure it via `ai.config({ panoptic })`, and it registers its collector + (optionally) flips observe-all for you. Core stays dependency-free; this skill documents the seam panoptic plugs into.
 
 ## 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`
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — the `AgentReport` / `ExecutionReport` tree (`trips`, `children`) an observer receives
+- [`@warlock.js/ai/log-ai-calls/SKILL.md`](@warlock.js/ai/log-ai-calls/SKILL.md) — event-level structured logging (vs. report-level observation)
+- [`@warlock.js/ai/run-ai-team/SKILL.md`](@warlock.js/ai/run-ai-team/SKILL.md) — a team inherits `observe` through the supervisor it forwards to
 
 
 ## persist-ai-data  `@warlock.js/ai/persist-ai-data/SKILL.md`
@@ -1646,91 +3067,355 @@ type ModelPricing = {
 };
 ```
 
-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):
+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, 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
+});
+```
+
+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
+
+OpenAI ships the first embedder:
+
+```ts
+const embedder = openai.embedder({ name: "text-embedding-3-small" });
+const { vector } = await embedder.embed("Hello, world.");
+```
+
+See [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md).
+
+## Multi-provider apps
+
+Pattern: one SDK instance per provider, mix at the call site:
+
+```ts
+const openai     = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const openrouter = new OpenAISDK({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  baseURL: "https://openrouter.ai/api/v1",
+  provider: "openrouter",
+});
+
+const fastAgent  = ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) });
+const claudeAgent = ai.agent({ model: openrouter.model({ name: "anthropic/claude-3.5-sonnet" }) });
+```
+
+Reports label per-agent provider correctly. Pricing applies per SDK instance.
+
+## When the adapter changes
+
+If you switch providers mid-project (e.g. OpenAI → Anthropic):
+
+1. The agent factory call signature stays the same — `ai.agent({ model: <newSdk>.model({...}) })`.
+2. Capabilities matter — if the new model doesn't support `structuredOutput` natively, fall back to the soft "respond in JSON only" instruction (framework handles it).
+3. Errors stay typed — `ProviderAuthError`, `ContextLengthExceededError`, etc. are adapter-agnostic.
+4. Pricing matrix needs updating per the new provider's rates.
+
+## See also
+
+- [`@warlock.js/ai-openai/setup-openai/SKILL.md`](@warlock.js/ai-openai/setup-openai/SKILL.md) — full OpenAI adapter docs
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — model passed into `ai.agent({...})`
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — embedder primitive on the SDK
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — adapter error categorization
+
+
+## rag-loaders-and-stores  `@warlock.js/ai/rag-loaders-and-stores/SKILL.md`
+
+---
+name: rag-loaders-and-stores
+description: 'Turn any source into a RagDocument and index it in a production vector store — the document loaders ai.rag.loadText / loadHtml / loadWeb (SSRF-safe via guardedFetch) / loadPdf (lazy pdf-parse peer), plus the swappable stores ai.rag.pgVectorStore({client}) (pgvector + ensureSchema DDL + hnsw/ivfflat index) and ai.rag.cacheVectorStore(driver), both satisfying VectorStoreContract (upsert / query / removeNamespace). Loaders return the exact RagDocument[] that kb.index() consumes — no adapter. Triggers: `ai.rag.loadText`, `ai.rag.loadHtml`, `ai.rag.loadWeb`, `ai.rag.loadPdf`, `loadText`, `loadHtml`, `loadWeb`, `loadPdf`, `ai.rag.pgVectorStore`, `ai.rag.cacheVectorStore`, `pgVectorStore`, `cacheVectorStore`, `VectorStore`, `PgVectorStoreOptions`, `PgVectorStoreInstance`, `ensureSchema`, `schema()`, `RagLoaderResult`, `LoadWebOptions`, `LoadPdfOptions`, `perPage`, `OutboundPolicy`, `guardedFetch`, `hnsw`, `ivfflat`, `pgvector`, `dimensions`, `PgClientLike`, `PDF_PARSE_INSTALL_INSTRUCTIONS`; ''load a website into a knowledge base'', ''index a PDF for RAG'', ''strip HTML to text for embedding'', ''pgvector store for RAG'', ''SSRF-safe document fetch'', ''one document per PDF page'', ''swap the vector store''; typical import `import { ai } from "@warlock.js/ai"`. Skip: the chunk → embed → retrieve → rerank → cite pipeline that consumes these — `@warlock.js/ai/run-ai-rag/SKILL.md`; the raw embedder primitive — `@warlock.js/ai/embed-text/SKILL.md`; cache similarity internals — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `langchain` loaders, `llamaindex` readers.'
+---
+
+# RAG loaders + vector stores — source → `RagDocument` → durable store
+
+Two feature groups that bracket `ai.rag()`: **loaders** turn a source (string, raw HTML, a URL, or PDF bytes) into the exact `RagDocument[]` shape `kb.index()` consumes, and **stores** are the swappable backends that hold the embeddings. Both live on the `ai.rag.*` namespace — present the moment `@warlock.js/ai` is imported, no side-effect import, no module augmentation.
+
+## Contract — what each side produces / satisfies
+
+Every loader returns `RagLoaderResult` — a plain `RagDocument[]` — so a load feeds `index()` with no adapter and callers never branch on arity (one page ⇒ 1 doc, a per-page PDF ⇒ N docs):
+
+```ts
+type RagLoaderResult = RagDocument[];
+type RagDocument = { id: string; text: string; metadata?: Record<string, unknown>; tags?: string[] };
+```
+
+Every store satisfies the three-method `VectorStore` contract (a thin narrowing of the cache `similar()` surface — NOT a new engine):
+
+```ts
+interface VectorStore {
+  upsert(key: string, value: unknown, vector: number[], tags?: string[]): Promise<void>;
+  query<T>(vector: number[], options: { topK: number; threshold?: number; tags?: string[] }): Promise<{ key: string; value: T; score: number }[]>;
+  removeNamespace(namespace: string): Promise<void>;
+}
+```
+
+## Loaders
+
+| Loader | Input | Deps | Emits |
+|---|---|---|---|
+| `ai.rag.loadText(input, opts?)` | `string` \| `{ id, text }` \| array of either | none | one doc per non-empty item |
+| `ai.rag.loadHtml(html, opts?)` | raw HTML string | none (regex strip) | one doc, `metadata.title` from `<title>` |
+| `ai.rag.loadWeb(url, opts?)` | absolute URL | none (uses core `guardedFetch`) | one doc, SSRF-safe fetch |
+| `ai.rag.loadPdf(bytes, opts?)` | `Buffer` \| `ArrayBuffer` \| `Uint8Array` | lazy `pdf-parse` peer | one doc, or one per page with `perPage: true` |
+
+Shared options (`RagLoaderOptions`): `id` (source id — falls back to the URL for web, `"document"` otherwise), `metadata` (merged **over** the loader-derived keys, so an explicit `metadata.title` always wins), and `tags` (applied to every chunk for `retrieve({ tags })` filtering). Loader-derived keys: `source`, `loader` (`"text" | "html" | "web" | "pdf"`), plus `title` / `page` / `pageCount` / `contentType` where determinable. Empty / whitespace-only / all-markup inputs emit **no** document — never a no-op record for `index()` to skip.
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+// Bare string, or many records → many distinctly-identified docs:
+await kb.index(ai.rag.loadText([
+  { id: "faq-billing", text: "…", metadata: { section: "billing" } },
+  { id: "faq-shipping", text: "…" },
+]));
+
+// Raw HTML → readable text (scripts/styles dropped, entities decoded):
+await kb.index(ai.rag.loadHtml(rawHtml, { id: "landing", tags: ["marketing"] }));
+```
+
+### `loadWeb` is SSRF-safe — never a raw `fetch`
+
+Every request goes through core's `guardedFetch` under an `OutboundPolicy`. The strict defaults (https-only, private-IP-deny on, 10s timeout, 5 MiB cap) apply even when you pass no `policy`, so an untuned call is already hardened. Tighten it per call:
+
+```ts
+await kb.index(await ai.rag.loadWeb("https://docs.example.com/guide", {
+  policy: { hostAllowlist: ["docs.example.com"], maxBytes: 2_000_000, timeoutMs: 5_000 },
+  tags: ["docs"],
+}));
+```
+
+HTML responses run through the same tag-strip pass as `loadHtml`; non-HTML text (`text/plain`, markdown) is used verbatim. `metadata.source` is the resolved URL, `metadata.contentType` the server-reported type. A non-OK response, a policy block, a timeout, or an over-cap body throws `OutboundPolicyError`.
+
+### `loadPdf` — lazy optional peer, page-precise citations
+
+`pdf-parse` is an **optional** peer, dynamic-imported on the FIRST `loadPdf` call — importing `@warlock.js/ai` never forces it. When it is absent, the curated `PDF_PARSE_INSTALL_INSTRUCTIONS` string is thrown as a plain `Error` (a missing infra peer, not a content problem), never a raw module-resolution stack trace.
+
+```ts
+import { readFile } from "node:fs/promises";
+
+// Whole PDF → one doc carrying metadata.pageCount:
+await kb.index(await ai.rag.loadPdf(await readFile("manual.pdf"), { id: "manual" }));
+
+// One doc per page → citations stay page-precise (id suffixed `#p<n>`, metadata.page set):
+await kb.index(await ai.rag.loadPdf(bytes, { id: "manual", perPage: true }));
+```
+
+An image-only / scanned page has no text layer and is dropped, so a fully-scanned PDF yields zero docs (nothing to embed).
+
+## Stores
+
+### `ai.rag.cacheVectorStore(driver)` — adapt any `@warlock.js/cache` driver
+
+The cache driver **is** the vector store — `upsert → set({ vector, tags })`, `query → similar()`, `removeNamespace → removeNamespace()`. A driver without similarity support throws `CacheUnsupportedError` unchanged (pointing you at the `pg` / `redis` cache drivers).
+
+```ts
+import { MemoryCacheDriver } from "@warlock.js/cache";
+
+const store = ai.rag.cacheVectorStore(new MemoryCacheDriver()); // dev / tests
+```
+
+### `ai.rag.pgVectorStore(options)` — production pgvector
+
+One durable row per chunk keyed by the pipeline's dotted key, the chunk payload in a `JSONB` `value` column, the embedding in a pgvector `vector` column. Pass a live pool (`{ client }` — `@warlock.js/ai` imports **nothing**) or a `{ connectionString }` and let the store lazily `import("pg")` (the optional peer; curated install string on first use if absent). Exactly one of the two is required.
+
+```ts
+type PgVectorStoreOptions = {
+  client?: PgClientLike;               // a pg.Pool / pg.Client — only `query` is ever called
+  connectionString?: string;           // else the store builds its own Pool lazily
+  table?: string;                      // default "warlock_ai_rag_vectors"; must be a safe identifier
+  dimensions?: number;                 // vector(N) width in the DDL, default 1536
+  index?: "hnsw" | "ivfflat" | "none"; // ANN strategy, default "hnsw"
+  ivfflatLists?: number;               // ivfflat only, default 100
+};
+```
+
+`schema()` (alias `ensureSchema()`) returns the reference migration DDL — `CREATE EXTENSION vector`, the table, a GIN index on `tags`, and the chosen ANN index (`USING hnsw (embedding vector_cosine_ops)`). It **only returns the string**; the framework never auto-migrates — you run it once through your own tool. Index and query MUST use the same embedding model: the `vector(N)` width is fixed at table-creation time from `dimensions`.
+
+```ts
+import { Pool } from "pg";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536, index: "hnsw" });
+
+// Once, via your migration tooling — never auto-run:
+await pool.query(store.ensureSchema());
+```
+
+`query()` runs the cosine floor (`threshold`) and `tags` overlap filter **in SQL** (a below-floor row never crosses the wire), orders by `embedding <=> $vec`, caps at `topK`, and maps the pgvector distance back to a `[0,1]` cosine-similarity `score` — the same scale the cache store emits. `removeNamespace()` is a prefix DELETE that escapes `_` / `%` so dropping `ai.rag.docs` never also catches `ai.rag.docs2`.
+
+## Pattern — a knowledge base from a website, backed by pgvector
+
+```ts
+import { Pool } from "pg";
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });
+await pool.query(store.ensureSchema()); // once at boot / migration
+
+const kb = ai.rag({
+  name: "docs",
+  embedder: openai.embedder({ name: "text-embedding-3-small" }), // 1536 dims — matches the DDL
+  store,
+});
+
+// Crawl a few pages (SSRF-safe) + a spec PDF into the same namespace:
+for (const url of ["https://docs.example.com/intro", "https://docs.example.com/config"]) {
+  await kb.index(await ai.rag.loadWeb(url, { policy: { hostAllowlist: ["docs.example.com"] }, tags: ["docs"] }));
+}
+await kb.index(await ai.rag.loadPdf(await readFile("spec.pdf"), { id: "spec", perPage: true, tags: ["spec"] }));
+
+// Now retrieve — every hit's citation traces back to its source URL / page:
+const { chunks } = await kb.retrieve("how do I configure caching?", { topK: 4, tags: ["docs"] });
+```
+
+The `embedder`'s `dimensions` MUST equal the store's `dimensions` — a mismatch is a runtime insert failure at the pgvector column, not a type error.
+
+## Cost + testing
+
+- **Loaders are cheap.** `loadText` / `loadHtml` are zero-dependency string passes; `loadWeb` costs one guarded HTTP round-trip; `loadPdf` costs the `pdf-parse` parse. **None embed** — embedding cost lands entirely in `kb.index()` (batched, 96 texts per `embedMany` call). The token spend is per chunk, so `perPage` PDFs and finer chunking mean more, smaller vectors.
+- **`pgVectorStore` construction is synchronous and does no I/O** — the `pg` import + pool build are deferred to first `query`/`upsert`. Table-name validation (`/^[A-Za-z_][A-Za-z0-9_]*$/`) throws at construction, so a `table: "bad; DROP TABLE x"` fails fast.
+- **Unit-test loaders with fixtures** (a stubbed `policy.fetch` for `loadWeb`, `vi.mock("pdf-parse")` for `loadPdf` — the literal specifier is mockable). Test stores against a `FakePgClient` implementing `{ query }`, or `cacheVectorStore(new MemoryCacheDriver())` for a real end-to-end index/retrieve with no external service.
+
+## See also
+
+- [[run-ai-rag]] — the chunk → embed → retrieve → rerank → cite pipeline that **consumes** these loaders and stores (`ai.rag({ embedder, store })`, `index()` / `retrieve()`).
+- [[embed-text]] — the `sdk.embedder` primitive whose `dimensions` must match the store's `vector(N)` width.
+- [`@warlock.js/cache/use-cache-similarity/SKILL.md`](@warlock.js/cache/use-cache-similarity/SKILL.md) — the cache driver `cacheVectorStore` adapts.
+
+
+## record-replay-llm  `@warlock.js/ai/record-replay-llm/SKILL.md`
+
+---
+name: record-replay-llm
+description: 'Deterministic, offline LLM tests with ai.vcr(model,{path,mode}) — a record/replay decorator over ANY ModelContract that intercepts only complete()/stream(), delegates name/provider/capabilities/pricing to the inner model, and hashes each request against a JSON cassette on disk. Covers the three modes (record / replay / auto), the cassette format, save(), VcrCassetteMissError, streaming round-trip, hashOptions, and composing below fallbackModel. Triggers: `ai.vcr`, `vcr`, `VcrModel`, `VcrOptions`, `VcrMode`, `Cassette`, `CassetteEntry`, `VcrCassetteMissError`, `hashRequest`, `DEFAULT_HASH_OPTIONS`, `mode`, `path`, `hashOptions`, `save`, `cassette`, record, replay, cassette; ''record LLM responses for tests'', ''replay model calls offline in CI'', ''deterministic agent test without hitting the provider'', ''cassette for model calls''; typical import `import { ai } from "@warlock.js/ai"`. Skip: eval scoring + regression gating — `@warlock.js/ai/eval-datasets-and-ci/SKILL.md`; the Vitest matchers + mockRouter — `@warlock.js/ai/ai-dx-helpers/SKILL.md`; choosing a provider adapter — `@warlock.js/ai/pick-ai-provider/SKILL.md`; competing libs `nock`, `polly.js`.'
+---
+
+# `ai.vcr()` — record / replay any model
+
+`ai.vcr(model, { path, mode })` wraps any `ModelContract` in a record/replay decorator backed by a JSON cassette on disk. It intercepts only `complete()` / `stream()` — the single seam every agent trip funnels through — and delegates `name`, `provider`, `capabilities`, and `pricing` to the inner model untouched, so cost accounting and capability detection are unchanged. Depends only on `ModelContract`, so it works with **any** adapter.
+
+## Shape
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+const live = openai.model({ name: "gpt-4o-mini" });
 
-```ts
-const { usage } = await ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) }).execute("hi");
+const model = ai.vcr(live, {
+  path: "./cassettes/support.json",  // cassette file (JSON); read on construct, written on save()
+  mode: "auto",                      // "record" | "replay" | "auto" (default)
+});
 
-usage.cost;          // { input, output, cachedInput?, cachedOutput? }  — USD per channel
-// single scalar total: sum the populated fields, treating undefined as 0.
-```
+const agent = ai.agent({ model, systemPrompt: "..." });
+const result = await agent.execute("hi");
 
-`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.
+await model.save(); // first run records; later runs replay deterministically
+```
 
-### Token channels (`Usage`) — what each adapter reports
+The returned `VcrModel` is a `ModelContract` plus `save(): Promise<void>` and a readonly `cassette` (exposed for assertions).
 
-Beyond `input` / `output` / `total`, `Usage` carries optional sub-channels (undefined when the provider doesn't meter them):
+## Modes — `VcrMode`
 
-| 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 |
+- **`record`** — always calls the inner model and appends a cassette entry. Never replays (the in-memory cassette starts empty, so a record run never accidentally replays a stale entry). Use to (re)capture a fresh cassette.
+- **`replay`** — never calls the inner model. A cassette hit returns the stored response / re-yields its chunks / re-throws its error; a **miss throws `VcrCassetteMissError`** — never a silent live call. Use in CI for deterministic, offline tests.
+- **`auto`** (default) — replay on a hit, record on a miss. The friendliest mode for local dev: records once, replays thereafter.
 
-### Driving cache + reasoning per call
+## Request hashing — `hashOptions`
 
-`ModelCallOptions` exposes vendor-neutral controls the agent forwards only when `capabilities` allows:
+On each call VCR computes a stable hash over `{ messages, picked options }` and looks for a matching `CassetteEntry`. The hashed option fields default to:
 
 ```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
-});
+["temperature", "maxTokens", "responseSchema", "tools", "reasoning"]
 ```
 
-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.
+(`DEFAULT_HASH_OPTIONS`). `signal` and unknown provider keys are **always excluded**, so an otherwise-identical logical call still matches. `tools` are hashed by name + description + input-schema shape, not object identity. Override `hashOptions` to widen / narrow what counts as "the same request". `hashRequest(messages, options, hashOptions)` is exported for direct use.
 
-## Embeddings
+## Cassette format
 
-OpenAI ships the first embedder:
+A `Cassette` is `{ version: 1, model, provider, entries: CassetteEntry[] }`. Each `CassetteEntry` is `{ requestHash, request: { messages, options? }, ... }` where **exactly one** of `response` / `chunks` / `error` is populated — mirroring the three outcomes of a model call (non-streaming reply, streamed chunk list, or a thrown provider error). The full `request` is stored verbatim for human readability and so the cassette can be re-hashed if the hashing format ever changes.
+
+## Streaming round-trip
 
 ```ts
-const embedder = openai.embedder({ name: "text-embedding-3-small" });
-const { vector } = await embedder.embed("Hello, world.");
+for await (const chunk of model.stream(messages)) {
+  // record mode: buffers each chunk into entry.chunks[] while re-emitting
+  // replay mode: re-yields the stored chunks in order (delta / tool-call / done sequence)
+}
+await model.save();
 ```
 
-See [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md).
-
-## Multi-provider apps
+Recorded chunks reproduce the exact `delta` / `tool-call` / `done` sequence on replay; a recorded error is re-thrown.
 
-Pattern: one SDK instance per provider, mix at the call site:
+## `VcrCassetteMissError`
 
 ```ts
-const openai     = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
-const openrouter = new OpenAISDK({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  baseURL: "https://openrouter.ai/api/v1",
-  provider: "openrouter",
-});
+import { VcrCassetteMissError } from "@warlock.js/ai";
 
-const fastAgent  = ai.agent({ model: openai.model({ name: "gpt-4o-mini" }) });
-const claudeAgent = ai.agent({ model: openrouter.model({ name: "anthropic/claude-3.5-sonnet" }) });
+try {
+  await vcrModel.complete(messages);
+} catch (error) {
+  if (error instanceof VcrCassetteMissError) {
+    console.error("Re-record the cassette:", error.path, error.requestHash);
+  }
+}
 ```
 
-Reports label per-agent provider correctly. Pricing applies per SDK instance.
+Thrown only in `replay` mode on a miss (code `"VCR_CASSETTE_MISS"`). It carries the looked-up `requestHash` and the cassette `path` so a failing CI run names exactly which call was not recorded. Extends `AIError` directly (not `ProviderError`) — a miss is a harness/config failure, not a provider failure. **The whole point:** `replay` never falls back to a live call, which would silently re-introduce non-determinism into a test that asked for the opposite. Re-record by running once in `record` / `auto`.
 
-## When the adapter changes
+## `save()` — flush new entries
 
-If you switch providers mid-project (e.g. OpenAI → Anthropic):
+`save()` writes newly recorded entries to `path`. It is a **no-op when nothing was recorded** (pure replay, or a record/auto run that only hit cached entries), so calling it unconditionally is safe.
 
-1. The agent factory call signature stays the same — `ai.agent({ model: <newSdk>.model({...}) })`.
-2. Capabilities matter — if the new model doesn't support `structuredOutput` natively, fall back to the soft "respond in JSON only" instruction (framework handles it).
-3. Errors stay typed — `ProviderAuthError`, `ContextLengthExceededError`, etc. are adapter-agnostic.
-4. Pricing matrix needs updating per the new provider's rates.
+## Composition
+
+VCR composes **below** `ai.fallbackModel` and works with any adapter. Wrap the live model in `vcr(...)`, then pass it anywhere a `ModelContract` is accepted (agent, planner, reranker, judge).
 
 ## See also
 
-- [`@warlock.js/ai-openai/setup-openai/SKILL.md`](@warlock.js/ai-openai/setup-openai/SKILL.md) — full OpenAI adapter docs
-- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — model passed into `ai.agent({...})`
-- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — embedder primitive on the SDK
-- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — adapter error categorization
+- [`@warlock.js/ai/eval-datasets-and-ci/SKILL.md`](@warlock.js/ai/eval-datasets-and-ci/SKILL.md) — pair a cassette with a dataset for fully offline eval CI
+- [`@warlock.js/ai/ai-dx-helpers/SKILL.md`](@warlock.js/ai/ai-dx-helpers/SKILL.md) — `ai.mockRouter` + Vitest matchers for the rest of the test surface
+- [`@warlock.js/ai/pick-ai-provider/SKILL.md`](@warlock.js/ai/pick-ai-provider/SKILL.md) — the adapters whose models VCR wraps
 
 
 ## run-ai-agent  `@warlock.js/ai/run-ai-agent/SKILL.md`
 
 ---
 name: run-ai-agent
-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`.'
+description: 'Build agents with ai.agent({...}) — the single-LLM-turn primitive. Covers execute / stream, attachments, structured output, placeholders, events, agent.eval scoring, the judge-safe preset for resilient LLM-as-judge / verdict classifiers (ai.agent.judge / judge: true — lenient JSON parse + repair + never-throw, for Nova-class models), and auto-adapting raw executables in tools:[]. Triggers: `ai.agent`, `ai.agent.judge`, `agent.execute`, `agent.stream`, `agent.eval`, `AgentResult`, `AgentReport`, `AgentToolEntry`, `JudgeConfig`, `JudgeAgentConfig`, `judge`, `repairAttempts`, `streamingToolGuard`, `attachments`, `repair`, `maxTrips`, `sessionId`, `spawnSubAgent`, `SpawnSubAgentSpec`; ''run an agent'', ''stream an agent response'', ''structured output schema'', ''pass image to agent'', ''evaluate an agent'', ''LLM-as-judge that survives malformed JSON'', ''grade with a Nova model without crashing'', ''put a supervisor in tools'', ''cancel an agent run'', ''spawn a one-shot sub-agent with a per-task budget''; 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
@@ -1913,6 +3598,31 @@ await myAgent.execute(input, {
 
 Disabled by default. Each repair attempt counts against `maxTrips`.
 
+## `judge` preset — resilient LLM-as-judge / verdict classifiers
+
+For graders and verdict classifiers running on models that emit **corrupted** structured output — notably the Amazon Nova family, which wraps verdicts in fenced ` ```json ` blocks, prepends prose, or trails commentary — set `judge: true` (or a `JudgeConfig`). It turns on three behaviors at once:
+
+```ts
+const grader = ai.agent.judge({
+  model: nova.model({ name: "amazon.nova-pro-v1:0" }),
+  systemPrompt: "Grade the answer. Respond with JSON only.",
+  output: verdictSchema,
+});
+
+const result = await grader.execute(prompt);
+if (result.error) {
+  // graceful default — the judge couldn't produce a clean verdict
+}
+```
+
+1. **Repair** — a couple of re-ask attempts by default (`repairAttempts`, defaults to `2`; bounded by `maxTrips`) when the verdict fails to parse / validate. The caller's per-call `options.repair` still wins.
+2. **Lenient verdict parsing** — extracts the first balanced JSON object / array (tolerating fenced blocks + surrounding prose) instead of the strict parser.
+3. **Never throws on a parse miss** — even an unparseable verdict yields a well-formed result (`result.error` populated, `result.data` undefined), so a flaky judge degrades instead of crashing the flow.
+
+`ai.agent.judge(config, judge?)` is sugar for `ai.agent({ ...config, judge })`; the bare `ai.agent({ judge: true })` option does the same. `judge: {}` ≡ `judge: true` (every field falls back to its resilient default); `judge: { repairAttempts: 0 }` keeps the lenient parser + never-throw guarantee but disables repair.
+
+**Trade-off — resilience over strictness.** The lenient parse can recover JSON the strict parser would (correctly) reject — leave `judge` **off** for normal structured output, where a hard parse failure is a useful signal. Off by default; omitting it parses strictly and never auto-enables repair, byte-for-byte as before. (This is the same Nova-safe judge the unified prompt `validate()` uses — see [`@warlock.js/ai/manage-prompts/SKILL.md`](@warlock.js/ai/manage-prompts/SKILL.md).)
+
 ## Pattern — image attachments
 
 ```ts
@@ -1930,102 +3640,374 @@ attachments: [
 ];
 ```
 
-Model must declare `capabilities.vision`. OpenAI adapter auto-infers from name; override with `openai.model({ name, vision: true })`.
+Model must declare `capabilities.vision`. OpenAI adapter auto-infers from name; override with `openai.model({ name, vision: true })`.
+
+## Pattern — streaming
+
+```ts
+const stream = myAgent.stream(input);
+
+for await (const event of stream) {
+  if (event.type === "agent.trip.streaming") {
+    process.stdout.write(event.delta);
+  }
+}
+
+const result = await stream.result;
+```
+
+Or use `.on({ "agent.trip.streaming": ..., "agent.completed": ..., "agent.error": ... })` alongside iteration.
+
+## Pattern — cancellation
+
+```ts
+const ctrl = new AbortController();
+const resultPromise = myAgent.execute(input, { signal: ctrl.signal });
+
+setTimeout(() => ctrl.abort("too slow"), 30_000);
+
+const { error, report } = await resultPromise;
+if (report.status === "cancelled") {
+  // error is an AgentCancelledError (code "AGENT_CANCELLED",
+  // category "cancelled") carrying `cancelledAt` + `reason`
+}
+```
+
+Between-trip abort is guaranteed. Mid-trip best-effort.
+
+## Events — dot-notation + 3-tier subscription
+
+- `agent.starting`, `agent.trip.started`, `agent.trip.streaming`, `agent.trip.completed`
+- `agent.tool.calling`, `agent.tool.called`, `agent.tool.failed`
+- `agent.completed`, `agent.error`
+
+Three subscription tiers — fire in order **factory → instance → per-call**:
+
+```ts
+ai.agent({ model, on: { "agent.starting": () => metrics.inc("agent.runs") } });
+
+const unsubscribe = myAgent.on("agent.error", ({ error }) => logger.error(error));
+
+await myAgent.execute("go", {
+  on: { "agent.trip.completed": ({ trip }) => console.log(trip.duration) },
+});
+```
+
+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).
+
+## `ai.spawnSubAgent()` — one-shot delegation with a budget
+
+`ai.spawnSubAgent(spec)` is a thin wrapper over this same `ai.agent()`: it builds a fresh agent from the spec, optionally attaches a `budget` middleware, runs the `task` once, and returns the `AgentResult`. Not a sandbox or a separate runtime — a spawn is an ordinary new agent (empty conversation, its own tools/prompt). It is a **general** primitive: usable inside a tool, a workflow or planner step, a supervisor intent, or hand-rolled orchestration — it is NOT planner-specific (the planner engine never calls it).
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const result = await ai.spawnSubAgent({
+  name: "extract-entities",
+  model,
+  task: "Pull every company name from this article: ...",
+  budget: { maxCostUSD: 0.05 },   // per-task spend cap — aborts when crossed
+  output: companiesSchema,
+});
+```
+
+The one field a bare agent config doesn't surface ergonomically is `budget` (`BudgetOptions` — `maxTokens` / `maxCostUSD`), equivalent to `ai.agent({ middleware: [ai.middleware.budget(...)] })` but promoted to a first-class spec field so a delegated subtask can't overrun its cap (distinct from `maxTrips`, which caps round-trips, not spend). The surface is **narrower** than `agent.execute()`: one-shot, with no `history`, `placeholders`, per-call events, or `repair`. The spawned `report` slots under the caller's `report.children[]`, so cost and traces roll up uniformly. Reach for it when you want a named single-use delegation with a hard spend cap; otherwise just build an `ai.agent()` and call it.
+
+## 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)
+- Multi-agent routing with iteration → [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md)
+
+## See also
+
+- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — tool wiring + schema validation
+- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — persona / instruction builders
+- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `AIError` hierarchy
+
+
+## run-ai-rag  `@warlock.js/ai/run-ai-rag/SKILL.md`
+
+---
+name: run-ai-rag
+description: 'Retrieval-augmented generation with ai.rag({...}) — a chunk → embed → vector-store → retrieve → rerank → cite pipeline that reuses ai.embedder + a @warlock.js/cache CacheDriver. Covers index() / retrieve() / clear() / asTool(), chunking strategies (recursive | markdown | sentence | fixed), Citation / RetrievedChunk provenance, and the opt-in rerankers ai.rag.keywordReranker / ai.rag.llmReranker. Triggers: `ai.rag`, `rag.index`, `rag.retrieve`, `rag.clear`, `rag.asTool`, `RagConfig`, `RagDocument`, `RetrieveOptions`, `RetrieveResult`, `RetrievedChunk`, `Citation`, `ChunkOptions`, `ChunkType`, `ai.rag.keywordReranker`, `ai.rag.llmReranker`, `cacheVectorStore`, `VectorStore`, `topK`, `threshold`, `candidates`; ''build a knowledge base'', ''retrieve relevant chunks for a query'', ''cite the source of an answer'', ''chunk markdown for embedding'', ''rerank retrieval results'', ''expose retrieval as a tool''; typical import `import { ai } from "@warlock.js/ai"`. Skip: raw single-string embedding — `@warlock.js/ai/embed-text/SKILL.md`; exact + vector LLM-response cache — `@warlock.js/ai/attach-ai-middleware/SKILL.md` (ai.middleware.semanticCache); tool wiring — `@warlock.js/ai/define-ai-tool/SKILL.md`; competing libs `langchain`, `llamaindex`.'
+---
+
+# `ai.rag()` — chunk → embed → retrieve → rerank → cite
+
+A self-contained retrieval pipeline. It reuses the embedder you already have (`provider.embedder(...)`), a `@warlock.js/cache` vector-capable `CacheDriver` as the store, and the composite-as-tool engine for `asTool()`. Zero new dependencies. `ai.rag` is a native core verb — present the moment `@warlock.js/ai` is imported (no module augmentation, no side-effect import).
+
+## Factory 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 kb = ai.rag({
+  name: "docs",                                            // default "rag"
+  embedder: openai.embedder({ name: "text-embedding-3-small" }), // REQUIRED
+  store: new MemoryCacheDriver(),                          // or ai.config({ defaultStore })
+  namespace: "ai.rag.docs",                                // default `ai.rag.<name>`
+  chunk: { type: "markdown", size: 800, overlap: 120 },    // index() defaults
+  reranker: ai.rag.keywordReranker(),                      // OFF by default (cosine-only)
+  retrieve: { topK: 4, threshold: 0.5 },                   // default retrieval knobs
+});
+```
+
+Resolution is **loud at construction** (mirrors `ai.memory`):
+
+- `embedder` is **required** — a provider with no embedder must be caught here, not at first `index()`.
+- `store` falls back to `ai.config({ defaultStore })`; if neither resolves, the factory throws.
+
+## Surface — `Rag`
+
+```ts
+interface Rag {
+  readonly name: string;
+  index(docs: RagDocument[], chunk?: ChunkOptions): Promise<{ chunks: number }>;
+  retrieve(query: string, options?: RetrieveOptions): Promise<RetrieveResult>;
+  clear(): Promise<void>;
+  asTool(options?: RagAsToolOptions): ToolContract<{ query: string }, RetrieveResult>;
+}
+```
+
+## `index()` — chunk, embed (batched), store
+
+```ts
+await kb.index([
+  { id: "guide", text: longMarkdown, metadata: { url: "/guide" }, tags: ["frontend"] },
+  { id: "faq", text: faqText },
+]);
+```
+
+A `RagDocument` is `{ id, text, metadata?, tags? }` — **you** load + parse documents to text (loaders are out of scope for v1). Each doc is split into chunks, embedded in sub-batches of 96 texts per `embedMany()` call (so one giant doc never blows the provider's per-request cap), and upserted. Returns the chunk count written. Empty / whitespace-only documents yield zero chunks — nothing is embedded. The per-call `chunk` arg overrides `config.chunk` for that index.
+
+## Chunking — `ChunkOptions`
+
+All sizing is in **characters** (tokenizer-free; the embedder owns token counting). `chunk(text, options)` is also exported standalone.
+
+```ts
+type ChunkType = "recursive" | "sentence" | "fixed" | "markdown";
+
+{
+  type?: ChunkType,          // default "recursive"
+  size?: number,             // target chars per chunk, default 1000
+  overlap?: number,          // chars carried between adjacent chunks, default 200
+  separators?: string[],     // recursive only; default ["\n\n", "\n", ". ", " ", ""]
+}
+```
+
+- **`recursive`** (default) — separator-aware greedy packing, largest unit first.
+- **`markdown`** — heading/section-aware, then recursive within each section.
+- **`sentence`** — packs whole sentences up to `size`.
+- **`fixed`** — back-to-back character windows.
+
+Every chunk records its exact `[start, end)` span in the original text, so a `Citation.span` is precise.
+
+## `retrieve()` — embed query, fetch, rerank, slice, cite
+
+```ts
+const { query, chunks } = await kb.retrieve("how do I configure caching?", {
+  topK: 4,          // returned AFTER reranking. default 5
+  threshold: 0.5,   // cosine floor at the store stage. default 0.5
+  candidates: 16,   // pool fetched before rerank. default topK * 4 (clamped >= topK)
+  tags: ["frontend"], // restrict to chunks whose source had one of these tags
+});
+
+for (const hit of chunks) {
+  console.log(hit.score, hit.text);
+  console.log(hit.citation.sourceId, hit.citation.chunkIndex, hit.citation.span);
+}
+```
+
+`retrieve()` is **return-only** — it never auto-injects into a prompt. The caller formats the cited chunks (or uses `asTool()` for the agent loop). A `RetrievedChunk` carries `{ text, score, citation }`; the `Citation` is `{ sourceId, chunkIndex, span, score, metadata? }`. The reranker is **OFF by default** (cosine ranking only) unless `config.reranker` is set.
+
+## Rerankers — opt-in, on `ai.rag.*`
+
+Both are exposed as namespaced helpers on the factory (`ai.rag.keywordReranker`, `ai.rag.llmReranker`).
+
+```ts
+// Zero-dependency lexical reranker (BM25-lite keyword overlap).
+ai.rag.keywordReranker({ weight: 0.5 }); // weight in [0,1]; 1 = pure keyword, 0 = keep cosine
+
+// Model-backed reranker — one or more model calls per retrieval.
+ai.rag.llmReranker({ model: openai.model({ name: "gpt-4o-mini" }), batchSize: 10 });
+```
+
+- **`keywordReranker`** — blends lexical query-term overlap with the original cosine score by `weight`; ties keep the incoming cosine order. Costs nothing beyond string splits. Reach for it when embedding-only ranking buries a keyword-rich chunk.
+- **`llmReranker`** — asks an LLM to grade each over-fetched candidate `0..1` and sorts by that. Candidates the model fails to score keep their cosine score, so a garbled reply degrades gracefully. Opt in only when precision beats latency/cost. Both implement the `RagReranker` contract, so you can write your own.
+
+## `asTool()` — drop retrieval into an agent's `tools: []`
+
+```ts
+const agent = ai.agent({
+  model: openai.model({ name: "gpt-4o" }),
+  tools: [kb.asTool({ name: "search_docs", retrieve: { topK: 6 } })],
+});
+```
+
+Input is `{ query: string }`; output is the `RetrieveResult`. Default tool name is `retrieve_<rag.name>`; `description` and a per-tool `retrieve` override are optional. Built via the same composite-as-tool engine every other primitive uses.
+
+## `clear()`
+
+```ts
+await kb.clear(); // drops every entry written under this rag's namespace
+```
+
+## Advanced
+
+- `cacheVectorStore(driver)` + the `VectorStore` contract are exported for swapping in a custom store.
+- A stored chunk's namespaced key is `${namespace}.${sourceId}.${chunkIndex}`.
+
+## See also
+
+- [`@warlock.js/ai/embed-text/SKILL.md`](@warlock.js/ai/embed-text/SKILL.md) — the `sdk.embedder` primitive this consumes
+- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — what `asTool()` produces
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — wiring the retrieval tool into an agent
+
+
+## run-ai-team  `@warlock.js/ai/run-ai-team/SKILL.md`
+
+---
+name: run-ai-team
+description: 'Manager-led multi-agent teams with ai.team({...}) — transparent sugar over ai.supervisor that maps a manager → route/router, members → intents, and a gate → evaluate, returning a REAL SupervisorContract (no new loop, no new contract). Covers the built-in gate strings "quality" (review-then-fix) and "verify" (test-then-fix), a custom gate function, role mapping (roles / gateKey), and the verbatim supervisor pass-throughs (goal / output / state / maxIterations / snapshotStore / on / observe). Triggers: `ai.team`, `TeamConfig`, `TeamGate`, `TeamGateFn`, `TeamMemberValue`, `manager`, `members`, `gate`, `roles`, `gateKey`, `buildQualityGate`, `buildVerifyGate`, `SupervisorContract`, `ReportType`; ''build a team of agents'', ''manager that delegates to members'', ''review then fix loop'', ''test then fix loop'', ''quality gate for a multi-agent run'', ''report type team''; typical import `import { ai } from "@warlock.js/ai"`. Skip: routing one input to a fixed roster directly — `@warlock.js/ai/run-supervisor/SKILL.md` (team is sugar over it); durable cross-turn sessions — `@warlock.js/ai/run-orchestrator/SKILL.md`; LLM-generated plans — `@warlock.js/ai/run-planner/SKILL.md`; competing libs `crewai`, `autogen`.'
+---
+
+# `ai.team()` — manager + members + a quality gate
+
+`ai.team(config)` is **thin, transparent sugar over `ai.supervisor`**. It builds a `SupervisorConfig` from the team-shaped config, calls `supervisor(...)`, and returns the **unchanged** `SupervisorContract<TOutput>` — the exact object `ai.supervisor` returns. So `ctx.intents.<member>.execute()`, `.asTool()`, `.resume()`, snapshots, and events all stay intact. `team()` owns no loop of its own.
+
+The mapping:
+
+| team field | becomes supervisor field |
+| --- | --- |
+| `manager` | `route` (deterministic `{ route }`) XOR `router` (an agent / `RouterEntry`) |
+| `members` | `intents` |
+| `gate` | `evaluate` |
 
-## Pattern — streaming
+Everything else passes through 1:1 — the sole exception is the report/result `type`, which is stamped `"team"` (see [Pass-throughs](#pass-throughs-verbatim-supervisor-semantics)).
+
+## Shape
 
 ```ts
-const stream = myAgent.stream(input);
+import { ai } from "@warlock.js/ai";
+import { v } from "@warlock.js/seal";
 
-for await (const event of stream) {
-  if (event.type === "agent.trip.streaming") {
-    process.stdout.write(event.delta);
-  }
-}
+const codeTeam = ai.team({
+  name: "code-team",
+  goal: "Ship a tested module that passes review.",
+  manager: techLeadRouter,                 // an agent / RouterEntry → router; or { route } → deterministic
+  members: { builder, reviewer, fixer },   // role-name → agent | workflow
+  gate: "quality",                         // "quality" | "verify" | (ctx) => EvaluateResult
+  output: v.object({ code: v.string() }),
+  maxIterations: 6,                        // default 10 (supervisor's)
+});
 
-const result = await stream.result;
+const { data, report } = await codeTeam.execute("Build a debounce<T> utility.");
 ```
 
-Or use `.on({ "agent.trip.streaming": ..., "agent.completed": ..., "agent.error": ... })` alongside iteration.
+A `member` is an `AgentContract` or a `WorkflowInstance` (the `TeamMemberValue` union — the autocomplete-friendly common case; callback / full-entry intent shapes still work when forwarded). The keys are both the role names the manager routes to AND the keys `ctx.intents.<role>` exposes (the supervisor escape hatch is preserved).
 
-## Pattern — cancellation
+## The manager — `route` XOR `router`
 
 ```ts
-const ctrl = new AbortController();
-const resultPromise = myAgent.execute(input, { signal: ctrl.signal });
-
-setTimeout(() => ctrl.abort("too slow"), 30_000);
+// LLM-driven manager: an agent (or RouterEntry) → becomes SupervisorConfig.router
+manager: techLeadRouter
 
-const { error, report } = await resultPromise;
-if (report.status === "cancelled") {
-  // error is an AgentCancelledError (code "AGENT_CANCELLED",
-  // category "cancelled") carrying `cancelledAt` + `reason`
-}
+// Deterministic manager: { route } → becomes SupervisorConfig.route
+manager: { route: (ctx) => (ctx.iteration === 0 ? "builder" : "reviewer") }
 ```
 
-Between-trip abort is guaranteed. Mid-trip best-effort.
-
-## Events — dot-notation + 3-tier subscription
+Exactly one form is forwarded — mutually exclusive, mirroring the supervisor's own `router` XOR `route` rule. A malformed manager surfaces the existing `SupervisorFailedError` downstream.
 
-- `agent.starting`, `agent.trip.started`, `agent.trip.streaming`, `agent.trip.completed`
-- `agent.tool.calling`, `agent.tool.called`, `agent.tool.failed`
-- `agent.completed`, `agent.error`
+## Gates — `"quality"` | `"verify"` | a function
 
-Three subscription tiers — fire in order **factory → instance → per-call**:
+A `gate` string selects a pre-built `evaluate` strategy; both desugar to a concrete `evaluate` callback that leans entirely on the already-shipped `EvaluateResult` semantics (`satisfied` terminates, `reassignTo` re-dispatches the fixer, `feedback` threads forward) — **no new termination or loop code**.
 
-```ts
-ai.agent({ model, on: { "agent.starting": () => metrics.inc("agent.runs") } });
+### `gate: "quality"` — review-then-fix
 
-const unsubscribe = myAgent.on("agent.error", ({ error }) => logger.error(error));
+After each iteration's members settle and merge into supervisor `state`, the gate reads `state.approved` (the `gateKey`, default `"approved"`). If truthy → `{ satisfied: true }`; otherwise → `{ reassignTo: "fixer", feedback: String(state.notes ?? "") }`. The reviewer's feedback (`state.notes`) threads into the next iteration.
 
-await myAgent.execute("go", {
-  on: { "agent.trip.completed": ({ trip }) => console.log(trip.duration) },
-});
-```
+### `gate: "verify"` — test-then-fix
 
-Every event payload carries `runId` and `rootRunId`. Same identity fields ride on stream events.
+Identical shape but keyed on the tester's pass/fail slice `state.passed` (default `gateKey`) rather than a subjective score. On failure it re-dispatches the fixer; there is no feedback channel for a pass/fail signal, so none is threaded.
 
-## `tools: []` — auto-adapt executables
+> The named member whose `output` schema writes the gate slice must produce a boolean into `gateKey`.
 
-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()`.
+### A custom gate (full escape hatch)
 
 ```ts
-const concierge = ai.agent({
-  model,
-  tools: [billingWorkflow, supportSupervisor, lookupTool],  // no .asTool() needed
-});
+gate: (ctx) => {
+  if (ctx.state.score >= 0.9) return { satisfied: true };
+  return { reassignTo: "fixer", feedback: ctx.state.review };
+}
 ```
 
-`.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).
+Supplying a `TeamGateFn` instead of a string opts out of the sugar entirely while keeping the rest of `team()`'s wiring — it forwards straight to `SupervisorConfig.evaluate` with zero wrapping.
 
-## `agent.eval(options)` — score the agent against a suite
+## Role mapping — `roles` + `gateKey`
+
+The string gates default to canonical role names. Override when your `members` keys differ:
 
 ```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
+ai.team({
+  name: "qa-team",
+  manager,
+  members: { author, critic, patcher },
+  gate: "quality",
+  roles: { reviewer: "critic", fixer: "patcher" }, // map gate roles → your member keys
+  gateKey: "ok",                                    // state slice the gate reads
 });
-
-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).
+**Construction-time validation:** when the gate is a string, the resolved `fixer` (and, for `"quality"`, the `reviewer`) role is checked against `members`. A missing role throws an authoring-style `SupervisorFailedError` (`context: { authoring: true }`) immediately — rather than silently starving until `maxIterations`.
 
-## When NOT to use this primitive
+## Pass-throughs (verbatim supervisor semantics)
 
-- Multi-step pipeline with a fixed shape → [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md)
-- Multi-agent routing with iteration → [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md)
+`goal`, `output`, `state`, `maxIterations`, `snapshotStore`, `on`, `observe`, and `version` are forwarded unchanged. Because the returned object IS a supervisor, observability rides the same generic `Observer` seam every other flow uses (see `observe-ai-flows`), and snapshot resume works exactly as on a bare supervisor.
+
+The one behavioural difference from a bare supervisor: a team stamps **`type: "team"`** on both its report (a first-class `ReportType`, was `"supervisor"`) and its result, so Panoptic and any `Observer` can distinguish, group, filter, and label team runs as their own type rather than folding them into plain supervisor runs. Everything else passes through 1:1.
+
+A member callback that calls `agent.execute()` **directly** still nests `member → agent → tool` under the member span with usage rolled up — the same ambient-`RunFrame` auto-nesting as a bare supervisor. See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
 
 ## See also
 
-- [`@warlock.js/ai/define-ai-tool/SKILL.md`](@warlock.js/ai/define-ai-tool/SKILL.md) — tool wiring + schema validation
-- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — persona / instruction builders
-- [`@warlock.js/ai/handle-ai-errors/SKILL.md`](@warlock.js/ai/handle-ai-errors/SKILL.md) — `AIError` hierarchy
+- [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md) — the primitive team desugars into (intents, route/router, evaluate, ctx.intents)
+- [`@warlock.js/ai/run-orchestrator/SKILL.md`](@warlock.js/ai/run-orchestrator/SKILL.md) — wrap a team in durable cross-turn session state
+- [`@warlock.js/ai/observe-ai-flows/SKILL.md`](@warlock.js/ai/observe-ai-flows/SKILL.md) — the `observe` seam a team inherits
 
 
 ## run-ai-workflow  `@warlock.js/ai/run-ai-workflow/SKILL.md`
@@ -2346,7 +4328,7 @@ await supportBot.execute(input, {
   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
+  on: { "orchestrator.turn.awaiting-input": (e) => log(e) },  // tier-3 per-call handlers
   force: false,               // bypass drift check for this call
 });
 ```
@@ -2361,7 +4343,7 @@ await supportBot.execute(input, {
 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`.
+A clean turn ends with `orchestrator.turn.awaiting-input` (the session stays open for the next user turn); `orchestrator.turn.failed` and `orchestrator.turn.cancelled` end error / cancelled turns. (`orchestrator.turn.completed` is defined on the event map, but the v1 lifecycle maps a clean completion to `awaiting-input`, so it isn't emitted on the normal path — subscribe to `awaiting-input` for "turn done".)
 
 ## `OrchestratorResult` — read the report
 
@@ -2380,6 +4362,8 @@ result.compaction;                // CompactionResult when a turn compacted (and
 
 `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.
 
+A turn callback that calls `agent.execute()` **directly** (not via `ctx.run` / `ctx.intents`) still nests `callback → agent → tool` inside the turn's report tree, with usage rolled up and the session's `sessionId` stamped onto the captured subtree — an ambient `RunFrame` handles the self-attach. See [`@warlock.js/ai/run-supervisor/SKILL.md`](@warlock.js/ai/run-supervisor/SKILL.md).
+
 **`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
@@ -2496,7 +4480,7 @@ await orch.execute(input, { sessionId, history, on: { "orchestrator.drift.checke
 
 ---
 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`.'
+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 it, threading each step output into the next, and returns the unified {data, report, usage, error} envelope with report.type "planner". Supports DAG scheduling (dag:true + maxConcurrency off dependsOn), adaptive re-planning (replan:{maxReplans} + the onStep continue/abort/replan directive), and plan-only / approval (mode:"plan-only" → status "awaiting-approval" → approvedPlan). A plan step may delegate via ai.spawnSubAgent({...}) — a GENERAL one-shot-agent helper covered in `@warlock.js/ai/run-ai-agent/SKILL.md`; it is not planner-specific. Triggers: `ai.planner`, `planner.execute`, `spawnSubAgent`, `PlannerConfig`, `PlannerCapability`, `PlannerResult`, `PlannerReport`, `PlannerPlan`, `PlannerStep`, `PlannerStepDirective`, `PlannerPlanInvalidError`, `maxSteps`, `dag`, `maxConcurrency`, `dependsOn`, `replan`, `onStep`, `mode`, `approvedPlan`, `awaiting-approval`, `report.plan`, `report.executedSteps`; ''let the model plan the steps'', ''dynamic plan from a goal'', ''run independent steps in parallel'', ''re-plan when a step fails'', ''generate a plan for approval before running it''; 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
@@ -2508,16 +4492,19 @@ A planner turns a free-form **goal** into an ordered **plan** the LLM writes its
 - **`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.
+- **`planner`** — the steps are NOT known in advance. The LLM generates the ordered plan from the goal, then the planner executes it. Sequential by default; opt into **DAG** scheduling, **adaptive re-planning**, and **plan-only / approval** as needed (below).
 
 ## Shape
 
 ```ts
 import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
 
 const research = ai.planner({
   name: "research-assistant",
-  model: ai.openai.model({ name: "gpt-4o" }), // the plan-GENERATION brain
+  model: 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 },
@@ -2538,19 +4525,81 @@ for (const step of report.executedSteps) {  // forensic, in execution order
 - `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)
+## Execution model
 
-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.
+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. Each `PlannerStep` is `{ capability, input, id?, reason?, dependsOn? }`.
+2. **Execute** — by default steps run **strictly in array order**; each completed step's output is threaded into the next step's input as "Context from earlier steps". (Set `dag: true` to schedule on `dependsOn` instead — below.)
 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.
+`report.type === "planner"`; `report.children[]` carries every dispatched capability report (plus the planning trip), with usage rolled up. `report.executedSteps` is the authoritative per-step record (`PlannerStepSnapshot[]`). Lazy capability loading is **deferred** — every capability is fully constructed up front.
+
+## DAG scheduling — `dag: true` + `maxConcurrency`
+
+Run independent steps in parallel instead of array-order:
+
+```ts
+const research = ai.planner({
+  name: "research",
+  model,
+  capabilities,
+  dag: true,            // build a DAG from each step's `id` / `dependsOn`
+  maxConcurrency: 4,    // max steps in flight at once. default 4
+});
+```
+
+With `dag: true` the planner builds a DAG from step `id` / `dependsOn`, runs each **ready level concurrently** (up to `maxConcurrency`), and feeds each step **only its dependencies' outputs** (not the whole prior transcript). A **cycle** or a `dependsOn` naming an unknown step raises a typed `PlannerPlanInvalidError` **before any step runs**. Default `false` ⇒ the strict array-order loop, byte-for-byte unchanged (where `dependsOn` is advisory-only metadata).
+
+## Adaptive re-planning — `replan: { maxReplans }` + `onStep`
+
+When set, a **failed step** (or a `replan` verdict from the `onStep` hook) **revises the REMAINING plan** instead of aborting — re-asking the planning agent for a fresh plan seeded with the executed-step digest plus the feedback. Bounded by `maxReplans`; on exhaustion the run ends with the last failure.
+
+```ts
+const planner = ai.planner({
+  name: "adaptive",
+  model,
+  capabilities,
+  replan: { maxReplans: 2 },
+});
+
+await planner.execute(goal, {
+  onStep: (snapshot, plan) => {
+    // fired after EACH step settles (both the sequential and the DAG path)
+    if (snapshot.status === "completed" && looksWrong(snapshot.output)) {
+      return { type: "replan", feedback: "The summary missed the pricing section." };
+    }
+    // return nothing / { type: "continue" } to proceed; { type: "abort" } to stop
+  },
+});
+```
+
+The `onStep` directive (`PlannerStepDirective`):
+
+- `{ type: "continue" }` (or returning nothing) — proceed.
+- `{ type: "abort" }` — stop; remaining steps recorded `skipped` (exactly as a failure aborts).
+- `{ type: "replan"; feedback }` — re-plan the remainder, seeded with the digest + `feedback`. **A `replan` directive with no `replan` config is treated as `continue`** (no-op). Default off ⇒ a failure aborts exactly as before.
+
+## Plan-only / approval — `mode: "plan-only"` + `approvedPlan`
+
+Generate (and validate) a plan, return it for human sign-off, then execute the approved plan in a follow-up call:
+
+```ts
+// 1. Generate WITHOUT executing.
+const draft = await planner.execute(goal, { mode: "plan-only" });
+// draft.report.status === "awaiting-approval"; draft.plan carries the generated PlannerPlan.
+
+// 2. (human reviews draft.plan) ... then execute it verbatim.
+const final = await planner.execute(goal, { approvedPlan: draft.plan! });
+```
+
+- `mode: "plan-only"` generates + validates the plan and returns **without executing** — `report.status === "awaiting-approval"` (a planner-specific NON-terminal status) and `result.plan` carries the generated plan.
+- `approvedPlan` executes that exact plan, **skipping plan generation entirely**. It is still validated against the **live** capabilities, so a stale plan naming a capability the planner no longer has surfaces a `PlannerPlanInvalidError`.
+- `mode: "plan-only"` **with** `approvedPlan` is contradictory — `approvedPlan` wins (the plan executes).
 
 ## 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.
+- **`PlannerPlanInvalidError`** (`PLANNER_PLAN_INVALID`, category `schema`) — empty plan, a step naming an unknown capability, a DAG cycle, a `dependsOn` naming an unknown step, a stale `approvedPlan`, or 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.
@@ -2568,7 +4617,7 @@ Use `MockSDK` for the planning model — script the plan as a JSON string matchi
 
 ---
 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, 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`.'
+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. A callback that calls agent.execute() directly auto-nests agent → tool under the callback span (ambient RunFrame) with usage / cost rolled up — same for team members and orchestrator turns. Triggers: `ai.supervisor`, `ai.router`, `ai.fanOut`, `supervisor.execute`, `supervisor.resume`, `intents`, `router`, `route`, `classifier`, `evaluate`, `ack`, `artifactsSchema`, `middleware`, `END`, `ctx.intents.X.execute`, `ctx.run`, `RunFrame`, `callback span`, `children`, `parentRunId`, `rootRunId`, `trace nesting`, `sub-agent`; ''route one input across specialists'', ''multi-intent dispatch'', ''fan-out then evaluate'', ''classifier then router'', ''supervisor middleware'', ''self-consistency / voting'', ''why is my callback agent not nested / cost is $0'', ''nest a sub-agent under a callback''; 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
@@ -2835,6 +4884,25 @@ intents: {
 
 Cycle protection: per-branch call stack. Re-entry on same intent → `SUPERVISOR_DISPATCH_CYCLE`.
 
+### Sub-agent trace nesting — `agent.execute()` inside a callback auto-nests
+
+A callback that calls `agent.execute()` (or `team` member / `orchestrator` turn callback) **directly** — not through `ctx.run(agent)` / `ctx.intents.X.execute()` — still nests under its enclosing span. An ambient async-local `RunFrame` lets the agent self-attach to the callback's `children[]`, so the report tree is `callback → agent → tool` with usage / cost **rolled up** (no `$0` lone callback span, no manual id threading):
+
+```ts
+ai.supervisor({
+  intents: {
+    delegate: async (ctx) => {
+      const result = await worker.execute(String(ctx.input)); // direct call — still nested
+      return { reply: result.text };
+    },
+  },
+  route: (ctx) => (ctx.iteration === 0 ? "delegate" : END),
+});
+// report → callback("delegate") → agent("worker") → tool("echo"); usage flows up to the root.
+```
+
+Same behavior across `ai.supervisor`, `ai.team` (member callbacks), and `ai.orchestrator` (turn callbacks) — and `sessionId` propagates onto the captured subtree. `ctx.run(agent)` is captured **exactly once** (the explicit path does not double-count via the ambient frame), and a standalone `agent.execute()` **outside** any callback keeps its own self-root (no frame leakage). This is what an `Observer` / panoptic sees — see [`@warlock.js/ai/observe-ai-flows/SKILL.md`](@warlock.js/ai/observe-ai-flows/SKILL.md).
+
 ## Per-call options
 
 ```ts
@@ -2922,6 +4990,167 @@ 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
 
 
+## transcribe-audio  `@warlock.js/ai/transcribe-audio/SKILL.md`
+
+---
+name: transcribe-audio
+description: 'Speech-to-text via ai.transcribe({ model: sdk.transcribe({ name }), audio }) — the audio-INPUT verb (Theme I), returning the uniform never-throws { data, error, usage, report } envelope with cost-truth + panoptic observation. Feed it an AudioInput = { base64; mediaType; filename? } — build one with ai.audioFromFile(path) (reads disk, infers media type incl. WhatsApp .ogg/.opus) or ai.audioFromBuffer(bytes, mediaType). Models: OpenAI whisper-1 (verbose_json, per-minute, segments + durationSeconds) or gpt-4o-transcribe (json, per-token). Triggers: `ai.transcribe`, `ai.audioFromFile`, `ai.audioFromBuffer`, `sdk.transcribe`, `openai.transcribe`, `TranscriptionModelContract`, `AudioInput`, `TranscriptionSegment`, `MockTranscriptionModel`; ''speech to text'', ''transcribe audio'', ''voice note to text'', ''WhatsApp voice message'', ''whisper'', ''gpt-4o-transcribe'', ''subtitle segments'', ''audio input''; typical import `import { ai } from "@warlock.js/ai"` + `import { OpenAISDK } from "@warlock.js/ai-openai"`. Skip: text-to-speech / synthesizing a voice — [[generate-speech]]; competing libs raw `openai.audio.transcriptions.create`, `whisper.cpp`.'
+---
+
+# Transcribe audio — the speech-to-text verb (`ai.transcribe`)
+
+`ai.transcribe()` is the inverse of `ai.speech()` on the modality track (Theme I). Audio-in / text-out, wrapped in the same uniform result contract every executable returns — so transcribing a support voicemail slots into cost dashboards and panoptic traces exactly like an agent run.
+
+**Extracting text from an audio file NEEDS AI** — that is the `ai.transcribe` step. The file handling (`ai.audioFromFile` / `ai.audioFromBuffer`) is pure, non-AI **utility** that just packages bytes into an `AudioInput`; it does no I/O to a provider on its own.
+
+This is audio **input** (STT). For audio **output** (synthesizing a voice line), see [[generate-speech]].
+
+## Shape — WhatsApp voice note → text, end to end
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { OpenAISDK } from "@warlock.js/ai-openai";
+
+const openai = new OpenAISDK({ apiKey: process.env.OPENAI_API_KEY! });
+
+// audioFromFile reads the file + infers the media type from the extension.
+// .ogg / .opus (Android WhatsApp) and .m4a (iOS) are recognized out of the box.
+const audio = await ai.audioFromFile("./voice-note.ogg");
+
+const { data, error } = await ai.transcribe({
+  model: openai.transcribe({ name: "whisper-1" }),
+  audio,
+  language: "en", // BCP-47 hint — improves accuracy + latency
+});
+
+if (error) console.warn(error.code); // typed AIError
+else console.log(data.text);         // the transcript
+```
+
+`TranscriptionModelContract` mirrors `SpeechModelContract` — a peer primitive produced by the adapter's optional `transcribe?()` factory. A non-STT model id (`openai.transcribe({ name: "gpt-4o" })`) throws `InvalidRequestError` **at construction** — fail fast, like the speech/embedder guards.
+
+## The `AudioInput` shape + the two builders
+
+```ts
+type AudioInput = {
+  base64: string;    // base64-encoded audio bytes
+  mediaType: string; // IANA type, e.g. "audio/ogg", "audio/mpeg"
+  filename?: string; // helps providers infer the codec from the extension
+};
+
+// From a file on disk — reads + infers media type (override for extensionless files).
+const fromDisk = await ai.audioFromFile("./meeting.m4a");
+const forced   = await ai.audioFromFile("./blob", { mediaType: "audio/ogg" });
+
+// From bytes you already hold (an upload buffer, a downloaded blob) — no I/O, no AI.
+const fromBytes = ai.audioFromBuffer(uploadBuffer, "audio/ogg", "note.ogg");
+```
+
+Keeping `AudioInput` as inlined base64 + explicit media type makes the verb provider-neutral and serializable — there is no `fs` coupling in core, so the same request can cross a queue or an RPC boundary.
+
+## The result envelope
+
+```ts
+type TranscriptionResult = {
+  type: "transcription";
+  data?: {
+    text: string;                    // full transcript
+    segments?: TranscriptionSegment[]; // timestamped, in verbose mode
+  };                                 // undefined on failure
+  error?: AIError;                   // undefined on success — NEVER thrown
+  usage: Usage;                      // tokens (gpt-4o-transcribe) + cost when priced
+  report: TranscriptionReport;       // type:"transcription", model, durationSeconds, lineage
+};
+
+type TranscriptionSegment = { text: string; start?: number; end?: number };
+```
+
+`segments` and `report.durationSeconds` appear only when the provider returns them (whisper's `verbose_json` mode). Use segments to build subtitles or to jump-to-timestamp in a player.
+
+## Transcribe options (provider-neutral)
+
+```ts
+await ai.transcribe({
+  model,
+  audio,
+  language: "en",              // BCP-47 hint
+  prompt: "Names: Acme, Zoë",  // priming — spelling / style hints
+  format: "verbose_json",      // response-format override (segments + duration)
+  signal,                      // AbortSignal
+  observe: collector,          // route the report to an Observer (panoptic)
+  sessionId: "ticket-88",      // group into a session for flat cost/trace queries
+  options: { /* provider passthrough */ },
+});
+```
+
+## OpenAI — whisper-1 (per-minute) + gpt-4o-transcribe (per-token)
+
+```ts
+// whisper-1 — defaults to verbose_json → segments + duration; billed PER MINUTE.
+const whisper = openai.transcribe({ name: "whisper-1", pricing: { perMinute: 0.006 } });
+
+// gpt-4o-transcribe — defaults to json; billed PER TOKEN like a chat model.
+const gpt = openai.transcribe({ name: "gpt-4o-transcribe", pricing: { input: 2.5, output: 10 } });
+
+const { data, usage } = await ai.transcribe({ model: whisper, audio });
+// data.segments → [{ text, start, end }, …]; usage.cost from report.durationSeconds
+```
+
+The adapter wraps the base64 bytes in an uploadable via the SDK's `toFile`, using `audio.filename` (or `"audio"`) and `audio.mediaType` so the codec is declared correctly.
+
+## Cost-truth — one rollup, two metering models
+
+`ai.transcribe` fills `usage.cost` so STT spend folds into the **same** `Usage.cost` rollup as text:
+
+- **Per-minute** (`whisper-1`): `{ perMinute }` × `(durationSeconds / 60)` → `cost.input`. If the provider didn't report a duration, cost stays **`undefined`** (no guessing).
+- **Token-metered** (`gpt-4o-transcribe`): `{ input, output }` USD-per-1M-tokens → standard `computeCost` against the returned token usage.
+
+Per-minute wins when both are set; an unpriced model leaves `usage.cost` **`undefined`** (honest "cost unknown", never a false zero).
+
+## Pattern — inbound voice-message webhook
+
+```ts
+const stt = openai.transcribe({ name: "whisper-1" });
+
+async function onVoiceMessage(buffer: Buffer, mediaType: string) {
+  const audio = ai.audioFromBuffer(buffer, mediaType, "inbound.ogg");
+  const { data, error } = await ai.transcribe({ model: stt, audio, sessionId: "inbox" });
+
+  if (error) return replyWith("Sorry, I couldn't understand that audio.");
+  return routeToAgent(data.text); // hand the transcript to an ai.agent for a reply
+}
+```
+
+## Observability
+
+The completed `TranscriptionReport` (with `report.durationSeconds` and cost/latency attributed to `report.model`) routes to any registered `Observer` (panoptic, OTel, …) through the shared `observe` seam — `observe: true` (global), an `Observer` (flow-local), or observe-all. See [[observe-ai-flows]]. Provider faults surface as typed `AIError`s on `result.error`; see [[handle-ai-errors]].
+
+## Testing
+
+`MockTranscriptionModel(name, responses, pricing?)` is a deterministic `TranscriptionModelContract` double — no HTTP. Script text/segments/duration/usage/errors and inspect `model.calls`. `MockSDK({ transcriptionResponses, transcriptionPricing }).transcribe({ name })` wires the same double behind a full adapter.
+
+```ts
+import { MockTranscriptionModel, transcribe } from "@warlock.js/ai";
+
+const AUDIO = { base64: "QUJD", mediaType: "audio/mpeg", filename: "clip.mp3" };
+
+const model = new MockTranscriptionModel("whisper-1", [{ durationSeconds: 120 }], { perMinute: 0.006 });
+const { data, usage, report } = await transcribe({ model, audio: AUDIO });
+// data.text → "mock transcript"
+// usage.cost.input → (120 / 60) * 0.006   report.durationSeconds → 120
+// model.calls[0] records { audio, options } for assertions
+```
+
+Scripting `[{ error: new ProviderRateLimitError("slow down") }]` drives the never-throws path — `result.error` is the typed error and `result.data` is `undefined`.
+
+## See also
+
+- [[generate-speech]] — the inverse verb (`ai.speech`), text → audio
+- [[generate-images]] — the sibling image-output verb (`ai.image`)
+- [[observe-ai-flows]] — routing the `TranscriptionReport` to panoptic / OTel
+- [[handle-ai-errors]] — the typed `AIError` taxonomy on `result.error`
+
+
 ## use-ai-memory  `@warlock.js/ai/use-ai-memory/SKILL.md`
 
 ---
@@ -3050,11 +5279,121 @@ Drivers without similarity support throw `CacheUnsupportedError` from `set({ vec
 - [`@warlock.js/cache/cache-basics/SKILL.md`](@warlock.js/cache/cache-basics/SKILL.md) — vector driver catalog
 
 
+## use-runtime-skills  `@warlock.js/ai/use-runtime-skills/SKILL.md`
+
+---
+name: use-runtime-skills
+description: 'Progressive-disclosure agent skills with ai.skills({...}) and the first-class `skills` option on ai.agent — an always-injected cheap metadata catalog plus an on-demand loadSkill tool, backed by directory / url / store sources. Covers inject ("all" | {select:"semantic",topK,embedder}), maxLoadsPerRun, scope tags, the MockSkillsStore, semantic preload, and the inert-by-default Phase-2 self-authoring (saveSkill + default-DENY review gate → promote). Triggers: `ai.skills`, `SkillsConfig`, `SkillsContract`, `SkillSource`, `SkillInjectMode`, `SkillRecord`, `SkillCatalogEntry`, `loadSkill`, `loadSkillTool`, `saveSkill`, `saveSkillTool`, `SkillReviewGate`, `runReviewGate`, `MockSkillsStore`, `proceduralSkillStore`, `maxLoadsPerRun`, `inject`, `scope`, `review`, the agent `skills:` option; ''give an agent loadable skills'', ''progressive disclosure of instructions'', ''catalog of skills the model pulls on demand'', ''semantic preload of skill bodies'', ''let an agent author and review a skill''; typical import `import { ai } from "@warlock.js/ai"`. Skip: composing static system prompts — `@warlock.js/ai/write-system-prompt/SKILL.md`; durable agent memory tiers — `@warlock.js/ai/use-ai-memory/SKILL.md`; defining callable tools — `@warlock.js/ai/define-ai-tool/SKILL.md`.'
+---
+
+# `ai.skills()` — runtime skills with progressive disclosure
+
+A **skill is text injected into an agent's context — it never runs code.** `ai.skills(config)` builds a `SkillsContract`: the mechanism behind the first-class `skills` agent option. The agent always injects a cheap **metadata catalog** (one line per in-scope skill) and registers a `loadSkill` tool so the model pulls a skill's full **body** only when it needs it (progressive disclosure). Bodies are withheld until loaded — keeping context lean.
+
+## The first-class agent option (the supported way)
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const agent = ai.agent({
+  model: openai.model({ name: "gpt-4o" }),
+  systemPrompt: "You are a build assistant.",
+  skills: {                                   // a SkillsConfig OR an ai.skills(...) instance
+    name: "build-skills",
+    sources: [{ type: "directory", path: "./agent-skills" }],
+  },
+});
+```
+
+When `skills` is set the agent owns the runtime flow at execute time: it **prepends the always-injected catalog** (and, under `inject`, the preloaded bodies) in front of your system prompt, auto-registers `loadSkill` (plus `saveSkill` only when a `review` gate is configured), and threads the run id so `maxLoadsPerRun` is enforced per execution. **Omitted ⇒ no skills behavior; the agent runs byte-for-byte as today.** The option accepts a raw `SkillsConfig` (the agent passes it to `skills()` for you) or a pre-built `SkillsContract`.
+
+## Factory config — `SkillsConfig`
+
+```ts
+const lib = ai.skills({
+  name: "build-skills",                        // surfaced in analytics + the catalog block
+  sources: [{ type: "directory", path: "./agent-skills" }], // >= 1; later source wins on name clash
+  inject: { select: "semantic", topK: 2, embedder },        // body-injection policy (see below)
+  maxLoadsPerRun: 4,                           // cap on loadSkill calls per run. default 5
+  scope: { tags: ["frontend"] },               // only skills whose tags intersect are catalogued
+  review: { approve, store },                  // Phase 2 — absent ⇒ saveSkill is NOT exposed
+  analytics: (event) => track(event),          // optional efficacy sink (errors swallowed)
+});
+```
+
+### Sources — `SkillSource` (discriminated by `type`, never `kind`)
+
+- `{ type: "directory", path }` — reads `path/<folder>/SKILL.md` off disk (lazy `node:fs/promises`).
+- `{ type: "url", url, headers? }` — `fetch()`es a JSON manifest of skills.
+- `{ type: "store", store }` — any `SkillsStoreContract`, e.g. `MockSkillsStore`.
+
+Sources merge in order; a later source wins on a name collision.
+
+### Injection — `inject` (`SkillInjectMode`)
+
+The metadata catalog is **always** injected (it's cheap). `inject` controls whether any **bodies** are auto-injected up front:
+
+- **omitted** (default) — inject NO bodies; the model pulls them via `loadSkill`. Pure progressive disclosure.
+- `"all"` — inject every body up front (small libraries only).
+- `{ select: "semantic", topK, embedder?, threshold? }` — embed the run input, rank the catalog by cosine similarity, inject the top-`topK` bodies. Needs an embedder (passed here, or lazily auto-resolved).
+
+## `SkillsContract` surface
+
+```ts
+interface SkillsContract {
+  readonly name: string;
+  catalog(scopeInput?: string): Promise<SkillCatalogEntry[]>;  // cheap metadata, body omitted
+  catalogPrompt(scopeInput?: string): Promise<string>;          // catalog rendered as a system block
+  preload(input: string): Promise<SkillRecord[]>;               // bodies per `inject`; [] when omitted
+  tools(runId?: string): AgentToolEntry<any, any>[];            // loadSkill always; saveSkill iff review
+}
+```
+
+A `SkillCatalogEntry` is `Pick<SkillRecord, "name"|"description"|"version"|"tags"|"type">` — the **structural omission of `body`** is the type-level guarantee the catalog never carries skill bodies. A `SkillRecord` adds the full `body` plus `type: "authored" | "promoted" | "candidate"`.
+
+## `maxLoadsPerRun` — a budget, not a throw
+
+`loadSkill` calls are capped per run (default 5). Exhaustion is an **error RESULT the model self-corrects from**, never a throw — the tool returns `{ error }` and the loop continues. `runId` scopes both the budget and analytics correlation.
+
+## Stores
+
+```ts
+import { ai, MockSkillsStore } from "@warlock.js/ai";
+
+const store = new MockSkillsStore([
+  { name: "scaffold", description: "Scaffold a form", version: 1, body: "...", type: "authored" },
+]);
+const lib = ai.skills({ name: "build", sources: [{ type: "store", store }] });
+```
+
+`MockSkillsStore` is an in-memory `SkillsStoreContract` that ships with the package (construct via `new` — it is a concrete test/utility store, not a factory-fronted primitive). It holds the latest record per name, filters out `candidate`s from `list()` / `load()`, and exposes `saveCandidate` / `promote`. `proceduralSkillStore` is also exported (unifies proven procedural memories with named skills).
+
+## Phase 2 — self-authoring (inert by default)
+
+Self-authoring is **gated and OFF unless a `review` gate is wired**:
+
+- Without `review`, the `saveSkill` tool is **never registered** — a candidate can never be written, let alone injected.
+- With `review: { approve, store }`, `saveSkill` writes an **INERT** `type: "candidate"` (`version: 0`), filtered out of every catalog/load until promoted.
+- The `SkillReviewGate.approve(candidate)` is **default-DENY**: only `{ approve: true }` promotes the candidate to a new audited version (`promote` → `type: "promoted"`, `version + 1`). Anything else — `{ approve: false }`, a malformed result, or a **throw** (fail-closed) — keeps it inert. `runReviewGate(candidate, gate, emit?)` runs this and never throws (a throwing gate is a denial), emitting `promoted` / `denied` analytics events.
+
+The three interchangeable approve shapes — a policy fn, a validator agent, a human callback — all reduce to one `Promise<{ approve: boolean; reason? }>`.
+
+## Analytics
+
+The optional `analytics` sink fires `catalogued` / `loaded` / `used` / `saved` / `promoted` / `denied` events `{ type, skill, version, runId?, outcome? }`. Errors from the sink are swallowed (mirroring the agent's `onUsage` / `onComplete`), so analytics never crash a run.
+
+## See also
+
+- [`@warlock.js/ai/write-system-prompt/SKILL.md`](@warlock.js/ai/write-system-prompt/SKILL.md) — static persona / instruction blocks (vs. dynamic loaded skills)
+- [`@warlock.js/ai/use-ai-memory/SKILL.md`](@warlock.js/ai/use-ai-memory/SKILL.md) — the procedural memory tier `proceduralSkillStore` unifies with
+- [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — the agent the `skills` option attaches to
+
+
 ## 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, 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.'
+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. Carry identity with .meta({ name, version, description, required }) (a name auto-registers in ai.prompts) and compose with merge(...blocks) / merge(contract) / merge(name, { fromVersion }) (provenance in meta.composedFrom). Triggers: `ai.systemPrompt`, `ai.systemPrompt.fromFile`, `ai.persona`, `ai.instruction`, `SystemPromptBlockContract`, `SystemPromptContract`, `SystemPromptMeta`, `SystemPromptMergeOptions`, `PersonaContract`, `InstructionContract`, `meta`, `merge`, `composedFrom`, `fromVersion`, `placeholders`, `{{placeholder|default}}`, `InvalidRequestError`; ''write a system prompt'', ''compose persona + instructions'', ''prompt from a file'', ''name and version a prompt'', ''merge prompts together'', ''per-call prompt override'', ''mustache placeholder''; typical import `import { ai } from "@warlock.js/ai"`. Skip: the named/versioned prompt registry (register / resolve / tag / diff / export / validate) — `@warlock.js/ai/manage-prompts/SKILL.md`; agent factory wiring — `@warlock.js/ai/run-ai-agent/SKILL.md`; competing libs `langchain` `PromptTemplate`, raw f-strings.'
 ---
 
 # System prompts — immutable builders
@@ -3161,6 +5500,34 @@ ai.agent({ model, systemPrompt: prompt, placeholders: { language: "Arabic" } });
 
 Substitution works on the **rendered** concatenation of every block, so `{{key}}` inside a persona and inside an instruction both resolve against the same placeholder bag.
 
+## Identity + composition — `.meta()` and `merge()`
+
+A prompt carries optional `SystemPromptMeta` — `{ name?, version?, description?, required?, composedFrom? }`. Read it with the no-argument accessor; update it immutably with the one-argument form. **Giving a prompt a `name` auto-registers it in the `ai.prompts` registry** (keyed by `name@version`):
+
+```ts
+const base = ai.systemPrompt("You are support.", { name: "support", version: "1" });
+base.meta();                       // → { name: "support", version: "1" }
+const v2 = base.meta({ version: "2" }); // new builder; original untouched; re-registers under support@2
+```
+
+`merge(...)` folds blocks from another source into a **new** builder — a persona **replaces**, instructions **append**:
+
+```ts
+// (a) N pre-built blocks in one call
+const p = ai.systemPrompt().merge(ai.persona("You are Alex."), ai.instruction("Be concise."));
+
+// (b) another prompt contract — its blocks fold in; meta.composedFrom records provenance
+const merged = ai.systemPrompt("Be terse.").merge(otherPrompt);
+merged.meta()?.composedFrom;       // deterministic source labels, e.g. ["base@2"]
+
+// (c) a registered prompt resolved from ai.prompts by name (latest, or a pinned fromVersion)
+const composed = ai.systemPrompt("You are support.").merge("global", { fromVersion: "1" });
+```
+
+The name / contract / registry-name forms are the registry's composition surface — full coverage (register / resolve / version / tag / diff / validate) in [`@warlock.js/ai/manage-prompts/SKILL.md`](@warlock.js/ai/manage-prompts/SKILL.md).
+
+`.validate(options?)` is per-builder sugar over `ai.prompts.validate(this, options)` — the deterministic missing-placeholder check plus an optional Nova-safe LLM-judge.
+
 ## Per-call overrides
 
 Replace the agent's system prompt for a single run:
@@ -3192,6 +5559,7 @@ Three distinct prompts, one common foundation. Base is immutable — safe to sha
 
 ## See also
 
+- [`@warlock.js/ai/manage-prompts/SKILL.md`](@warlock.js/ai/manage-prompts/SKILL.md) — the `ai.prompts` registry these named prompts auto-register into (resolve / version / tag / diff / export / validate)
 - [`@warlock.js/ai/run-ai-agent/SKILL.md`](@warlock.js/ai/run-ai-agent/SKILL.md) — `systemPrompt` on factory + per-call override
 - [`@warlock.js/ai/run-ai-workflow/SKILL.md`](@warlock.js/ai/run-ai-workflow/SKILL.md) — per-step agent references inherit their own system prompt