agentfootprint 9.114.2 → 9.115.1

package/AGENTS.md

@@ -1,602 +1,288 @@
 # agentfootprint — Agent Instructions (OpenAI Codex)
 
-This is the **agentfootprint** library — a framework for building Generative AI applications where context engineering is buildable at the control-flow level. Built on [footprintjs](https://github.com/footprintjs/footPrint) (the flowchart pattern for backend code).
+> GENERATED from `ai-instructions/claude-code/SKILL.md` by `npm run docs:regen` — edit that file.
+> Search [CAPABILITIES.md](https://github.com/footprintjs/agentfootprint/blob/main/CAPABILITIES.md) before building
+> anything — it may already ship. Contributing to agentfootprint itself? Read its
+> [CLAUDE.md](https://github.com/footprintjs/agentfootprint/blob/main/CLAUDE.md) (the definition of done).
 
-## Core Thesis
+agentfootprint structures AI agents as composable flowcharts, so every injection, read, write, decision and tool call becomes connected evidence as the run happens. Every concept takes an `LLMProvider` — swap `mock({...})` for `anthropic({...})` with zero code changes.
 
-**Building Generative AI applications is mostly *context engineering*** — deciding what content lands in which slot of the LLM call, when, and why. agentfootprint exposes this discipline through:
+**Core principles:**
+- Adapter-swap testing ($0 test runs, deterministic assertions)
+- The ladder: `mock` → `ollama` (free, local, real model) → a paid provider
+- Declare context (facts, steering, skills); the framework decides WHEN it fires and WHICH slot it lands in
+- Collect during traversal, never post-process (inherited from footprintjs)
 
-- **2 primitives** — `LLMCall`, `Agent` (= ReAct loop)
-- **3 compositions + Loop** — `Sequence` · `Parallel` · `Conditional` · `Loop`
-- **1 unifying injection primitive** — `Injection` with 4 typed sugar factories
-- **1 memory factory** — `defineMemory({ type, strategy, store })`
-
-Every named pattern (Reflexion, ToT, Swarm, ...) is a recipe over these. **Don't ship new classes per paper.**
+```bash
+npm install agentfootprint footprintjs
+```
 
-## The Mental Model — Three Slots, Six Flavors
+## Read this first — what does NOT exist
 
-Every LLM call has three slots. Every "agent feature" is content flowing into one of them:
+These are not hypothetical. A capable author, working from a correct mental model of
+this library, invented all four in one document. Treat them as the things you are
+most likely to get wrong here.
 
-| LLM API field | What goes here |
+| You will reach for | The reality |
 |---|---|
-| `system` prompt | Steering · Instruction text · Skill body · Fact data · formatted memory |
-| `messages` array | The conversation — user turns, assistant turns, tool results. Assembled from the conversation itself, never injected into |
-| `tools` array | Tool schemas (registered + Skill-attached) |
+| `startRun(...)` | **No such function.** The door is `agent.run(input, options?)`, where `AgentInput = { message: string; identity?; continueFrom? }` and `AgentOutput = string`. `run()` returns `AgentOutput \| RunnerPauseOutcome` — a run paused for a human returns a checkpoint; discriminate with `isPaused(result)`. |
+| `RunStep` as skill/route history | **`RunStep` is real and it is something else** — the footprintjs flowchart TOPOLOGY slider, exported from `agentfootprint/observe`. Its `kind` is `'sequential' \| 'fork' \| 'merge' \| 'decide' \| 'iteration' \| 'iteration-exit' \| 'react'`. Nothing in it concerns skills. Importing it succeeds, which is exactly why it is dangerous. For route history use `routeRecorder()` from the same door. |
+| the LLM classifier as routing "tier 3" | **It is a tier-2 strategy.** Tier 1 = declared start rules. Tier 2 = the configured scorer — `llmClassifier(provider)` OR `keywordScorer()` OR `embeddingScorer(e)` OR the entry scorer; near-ties fall through rather than argmax. Tier 3 = a menu the model resolves in-band through `read_skill`'s own description, reached only when tier 2 was NOT decisive. |
+| a skill's tools being gated to that skill automatically | **They are not, by default.** `defineSkill({ tools })` puts them in the agent's static tool list at build time — visible from iteration 1 whether the skill ever activates or not. Ask for the gate: `.toolsFromActiveSkill()` (agent-wide), `skillGraph({ scopeTools: true })` (graph-wide), or `autoActivate: 'currentSkill'` (per skill). `.tree()` leaves are the one shape scoped by default. |
+
+Two more absences: there is **no runtime force-stop governor** (`routeRecorder().getTrips()`
+only *labels* a spinning run; `maxIterations` is the hard stop), and there is **no
+automatic re-delivery of an ageing skill body** (`refreshPolicy` is stored and never
+read on any version — use `surfaceMode: 'both'`).
 
-The flavors are how you *mark intent* — but they all reduce to one `Injection` primitive:
+## Subpath map — 17 doors
 
-| Flavor | Trigger | Slots |
-|---|---|---|
-| **Skill** | LLM-activated (`read_skill`) | system-prompt + tools |
-| **Steering** | Always-on | system-prompt |
-| **Instruction** | Predicate (`activeWhen` / `on-tool-return`) | system-prompt |
-| **Fact** | Always-on (data) | system-prompt |
+`agentfootprint` (main barrel: `Agent`, `LLMCall`, `defineTool`, control flow, patterns, `defineRAG`, pause/resume) · `/providers` (`mock`, `anthropic`, `openai`, `bedrock`, `ollama`, `mcpClient`, embedders — every provider, so bundlers never walk the vendor SDKs from the main barrel) · `/context` (`defineSkill`, `defineFact`, `defineSteering`, `defineInstruction`, `skillGraph`, `skillsFromDir`, the scorers) · `/memory` (`defineMemory`, `InMemoryStore`, `mockEmbedder`, the stores) · `/rag` (stores + loaders; `defineRAG` itself is on the main barrel) · `/observe` (recorders, tracing, `RunStep`) · `/resilience` (provider decorators) · `/reliability` (the rules-based fail-fast gate) · `/cache` (prefix-cache strategies; importing it registers them) · `/security` · `/hosting` · `/events` · `/skill-graph` (the routing layer with no framework attached, for a host that is not this agent) · `/recipes` (`defineAgentRecipe` — one named, versioned agent setup, applied with `.recipe()`) · `/maps` (`Claim<T>` and the map-engagement vocabulary behind `.maps()`) · `/classify` (the calibrated-classifier port: `Classifier`, `mockClassifier`) · `/ontology` (`defineOntology` — a declared map of the domain, mounted with `.ontology()`). `package.json` `exports` is the complete list; a path not on it does not resolve.
 
-## Mock-first development (RECOMMENDED workflow)
+## Core Concepts
 
-Build the entire app — agent, context engineering, tools, memory, RAG, MCP — against in-memory mocks first. Validate logic and patterns end-to-end with $0 API cost. Swap real infrastructure in, one boundary at a time, only after the flow is right.
+### LLMCall — a single LLM call, no tools
 
 ```typescript
-import { Agent, defineTool } from 'agentfootprint';
+import { LLMCall } from 'agentfootprint';
 import { mock } from 'agentfootprint/providers';
-import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
-
-// Mock LLM provider — no API key, deterministic reply.
-const provider = mock({ reply: 'Refunds take 3 business days.' });
 
-// Inline-mocked tool — no real backend yet.
-const lookup = defineTool({
-  name: 'lookup',
-  description: '...',
-  inputSchema: { type: 'object', properties: {} },
-  execute: async () => 'mock data',
-});
-
-const agent = Agent.create({ provider, model: 'mock' }).tool(lookup).build();
-await agent.run({ message: 'How long does a refund take?' });
+const caller = LLMCall.create({ provider: mock({ reply: 'Hello!' }), model: 'mock' }).system('You are helpful.').build();
+const result = await caller.run({ message: 'Hi' });
 ```
 
-| Boundary | Mock for development | Production swap |
-|---|---|---|
-| LLM provider | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `ollama('<model>')` — a real model, still $0 and no key · then `anthropic()` · `openai()` · `bedrock()` |
-| Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder factory |
-| Memory store | `InMemoryStore` | `RedisStore` (`agentfootprint/memory`) · `AgentCoreStore` (`agentfootprint/memory`) · DynamoDB / Postgres / Pinecone (planned) |
-| MCP server | `mockMcpClient({ tools })` — in-memory, no SDK | `mcpClient({ transport })` to a real server |
-| Tool execute | inline `async () => '...'` closure | real implementation |
-
-When generating starter code for users, **default to the mock surface** unless they explicitly say they have a key / endpoint / store ready. Show real-provider code as the "swap" step, not the first step.
-
-**Subpath imports** for memory adapters keep the main barrel small + tree-shaking clean:
+### Agent — a ReAct agent with tools
 
 ```typescript
-import { RedisStore } from 'agentfootprint/memory';
-import { AgentCoreStore } from 'agentfootprint/memory';
-```
-
-Both lazy-require their SDK (`ioredis` / `@aws-sdk/client-bedrock-agent-runtime`) and accept `_client` for test injection.
-
-**Multi-turn mock for tool-using ReAct:**
+import { Agent, defineTool } from 'agentfootprint';
+import { mock } from 'agentfootprint/providers';
 
-```typescript
-const provider = mock({
-  replies: [
-    { toolCalls: [{ id: '1', name: 'lookup', args: { topic: 'refunds' } }] },
-    { content: 'Refunds take 3 business days.' },
-  ],
+const weather = defineTool({
+  name: 'weather',
+  description: 'Get current weather for a city.',
+  inputSchema: { type: 'object', properties: { city: { type: 'string' } }, required: ['city'] },
+  execute: async ({ city }: { city: string }) => `${city}: 72°F, sunny`,
 });
-```
 
-Each `complete()` consumes one reply in order. Exhaustion throws loud — misnumbered scripts fail tests instead of silently looping.
+const agent = Agent.create({ provider: mock({ reply: 'It is 72°F.' }), model: 'mock' })
+  .system('You answer weather questions using the weather tool.')
+  .tool(weather)
+  .maxIterations(5)
+  .build();
 
-## Public API
+const result = await agent.run({ message: 'Weather in Paris?' });
+```
 
-### MCP — `mcpClient` (connect to MCP servers, register their tools)
+### Context — facts, steering, skills, and declared routing
 
 ```typescript
-import { Agent, mcpClient } from 'agentfootprint';
+import { defineFact, defineSteering, defineSkill, skillGraph } from 'agentfootprint/context';
 
-const slack = await mcpClient({
-  name: 'slack',
-  transport: { transport: 'stdio', command: 'npx', args: ['@example/slack-mcp'] },
-});
-
-const agent = Agent.create({ provider })
-  .tools(await slack.tools())  // pull ALL tools from the server in one call
+Agent.create({ provider, model })
+  .fact(defineFact({ id: 'user-profile', data: 'Plan: Pro · Customer since 2022' }))
+  .steering(defineSteering({ id: 'policy', prompt: 'Never promise a refund before checking.' }))
+  .skill(defineSkill({ id: 'refunds', description: 'Refund procedure.', body: '…', tools: [issueRefund] }))
   .build();
-
-await agent.run({ message: '...' });
-await slack.close();
 ```
 
-Transports: `stdio` (local subprocess), `http` (Streamable HTTP). The
-`@modelcontextprotocol/sdk` peer-dep is lazy-required — zero runtime
-cost when MCP isn't used. Friendly install hint if missing.
-
-**In a BROWSER** the Node `require` loader does not exist, so supply what it
-would have found. Give the two SDK modules as `sdk` (the library still builds
-the transport, so headers / your own `fetch` / gateway vending / throttle retry
-all keep working), or a client you connected yourself as `connection`:
+`defineSkill` bodies load on demand — the model opens one with `read_skill`, or a `skillGraph()` routes to it:
 
 ```typescript
-import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+const graph = skillGraph()
+  .entry(triage, { when: (c) => /order/.test(c.userMessage) })   // where the turn STARTS
+  .route(triage, refunds, { onToolReturn: 'lookup_order' })      // a declared handoff
+  .build();
 
-const sidecar = await mcpClient({
-  name: 'sidecar',
-  sdk: { Client, StreamableHTTPClientTransport },
-  transport: { transport: 'http', url: '/py/mcp' },   // relative resolves against the page
-});
+Agent.create({ provider, model }).skillGraph(graph).build();
+graph.toMermaid();   // declared === drawn
 ```
 
-`stdio` spawns a subprocess and is refused in words there. On the `connection`
-arm the library builds no transport, so `retryOnThrottle` / `clientInfo` are
-REFUSED rather than ignored — wrap your own fetch with `retryingFetch` instead.
+`.entry()` and `.route()` take the skill OBJECTS, not their ids. The object form is
+the other door — `skillGraph({ skills, start, steps })` returns a finished graph with
+nothing to chain.
+
+A skill is active exactly while the cursor is on it — one skill's turn at a time. An `.entry(x)` with **no** `when` is the persistent base (`always`), on beside whatever the cursor is on.
+
+**The cursor is a program counter, not a per-turn classifier.** Nine causes move it (or
+decline to), reported as `cursorMove.by` on `agentfootprint.context.evaluated` and as
+`outcome` on `routeRecorder().getHops()`:
+
+`'entry'` (cold start) · `'route'` (a declared `from`-gated edge fired) · `'tool-proposal'`
+(a TOOL RESULT proposed a transition and the graph accepted it) · `'model-pick'` (a
+gate-accepted `read_skill`) · `'intent'` (the tier-2 scorer was decisive) · `'continuity'`
+(the cursor inherited from the previous turn held) · `'decider'` (an out-of-band menu
+resolver) · `'stay'` (nothing fired — sticky, and a recorded decision, not an absence) ·
+`'none'` (no cursor at all: nothing to enter, or a `tree()`, which has no cursor).
+`routeRecorder`'s `RouteOutcome` is those eight minus `'none'` (no cursor, no hop) plus
+`'rejected'` — nine values. Precedence when several want it at once:
+**declared edge > accepted tool proposal > model pick > stay.** A suppressed pick emits
+`agentfootprint.skill.reroute_superseded`; a parallel batch matching different targets
+emits `agentfootprint.skill.route_conflict`.
+
+**The cursor is per RUN by default.** A second `run()` starts cold at the entry.
+`.skillGraph(graph, { continuity: 'conversation' })` makes it span the conversation.
+
+**`read_skill` has a three-way design, not one list.** Per iteration a skill is
+*reachable* (named under "Reachable from here"), *refusable* (named under "Not reachable
+from here" — a graph refusal is about WHERE THE CURSOR IS, so naming it lets the model
+route in one step), or *hidden* (absent entirely — a hidden skill is about WHO IS ASKING,
+and naming it would leak the shape of somebody else's permissions; needs a
+`PermissionChecker` governing `skill_read`). **The enum stays the full catalog in every
+case** — narrowing it would turn a policy refusal into a generic schema error the model
+never reads.
+
+A refused pick gets one teaching sentence back and moves nothing:
+
+```text
+read_skill("audit-log") is not reachable from here. Reachable skills: billing. Pick one of these, or finish.
+```
 
-`agent.tools(arr)` is the bulk-register companion to `agent.tool(t)`.
-Pair with `await client.tools()` to register everything an MCP server
-exposes in one builder call. Tool-name uniqueness is still validated
-at `.build()` across MCP servers + manual `.tool()` calls.
+**The authority rule.** A tool result is written into the conversation once and then only
+ages; the system prompt is rebuilt from nothing every iteration (`reactMode: 'dynamic'`,
+the default, re-runs the InjectionEngine and all three slots). So standing instructions
+belong in the recomposed surface. `reactMode: 'classic'` caches system-prompt and tools
+after turn 1 — do **not** use it with skills.
 
-### RAG — `defineRAG` (one factory, one helper)
+### RAG — retrieve, augment, generate
 
 ```typescript
-import {
-  defineRAG, indexDocuments,
-  InMemoryStore, mockEmbedder,
-} from 'agentfootprint';
-
-const embedder = mockEmbedder();
-const store = new InMemoryStore();
-
-// Seed the corpus once at startup
-await indexDocuments(store, embedder, [
-  { id: 'doc1', content: 'Refunds are processed within 3 business days.' },
-  { id: 'doc2', content: 'Pro plan costs $20/month.' },
-]);
-
-// Define the retriever
-const docs = defineRAG({
-  id: 'product-docs',
-  store, embedder,
-  topK: 3,
-  threshold: 0.7,        // STRICT — nothing is injected when nothing matches
-});
-// Retrieved chunks land in the SYSTEM-PROMPT slot, as one system message
-// of citable `<source id=… doc=… score=…>` blocks.
-// `asRole` was removed in 7.20.0 — it was never read, and passing it throws.
-
-// Wire to agent — `.rag()` is an alias for `.memory()`, same plumbing
-agent.rag(docs);
+import { defineRAG } from 'agentfootprint';                    // wiring lives on the main barrel
+import { InMemoryStore, mockEmbedder } from 'agentfootprint/memory';
 
-// No identity argument anywhere: a corpus lives in its own namespace
-// (`corpus`, default `{ conversationId: '_global' }`) — the same one
-// indexDocuments writes to.
-await agent.run({ message: 'How long do refunds take?' });
+Agent.create({ provider, model })
+  .rag(defineRAG({ id: 'docs', store: new InMemoryStore(), embedder: mockEmbedder(), topK: 5 }))
+  .build();
 ```
 
-**Building the index** (8.10.0) is `agentfootprint/rag`: `indexFolder('./docs', { to: store, embedder })`, or the `loadDocuments` → `splitDocuments` → `indexCorpus` pieces, or `npx agentfootprint-index ./docs --to ./corpus.db`. Loaders for text/Markdown/HTML (zero-dep) and PDF (lazy `unpdf`, per-page text so citations can name a page). Re-running embeds only what changed. `defineRAG` stays on the MAIN barrel — it is run-time wiring; that door is index time.
-
-`defineRAG` runs on `defineMemory({ type: SEMANTIC, strategy: TOP_K })`. Same machinery, three deliberate differences: a corpus is **read-only** (it never stores the conversation), it reads under its **own namespace** rather than the run's identity, and its chunks render as **citable `<source>` blocks**. For conversation memory alongside a corpus, register both — `.rag(defineRAG(...))` and `.memory(defineMemory(...))`, each with its own store.
-
-**Why did the agent read this passage?** `agentfootprint.memory.retrieved` carries every candidate with its score — including the ones that were rejected and why. `agentfootprint.memory.attached` fires per chunk that reached the prompt. `agentfootprint.context.injected` reports `source: 'rag'` with that chunk's `retrievalScore` / `rankPosition` / `threshold`. The whole record is on root state as `retrievalEvidence_<id>`, where a backward slice can reach it.
-
-### Agent (ReAct primitive)
+### Control flow + patterns — compose runners
 
 ```typescript
-import { Agent, defineTool } from 'agentfootprint';
-import { anthropic } from 'agentfootprint/providers';
-
-const agent = Agent.create({
-  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
-  model: 'claude-sonnet-4-5-20250929',
-  maxIterations: 10,
-})
-  .system('You are a helpful assistant.')
-  .tool(weatherTool)
-  .build();
+import { Sequence, Parallel, Loop, Conditional, workflow, graph } from 'agentfootprint';
+import { swarm, debate, reflection, selfConsistency, mapReduce, tot } from 'agentfootprint';  // patterns
 
-const result = await agent.run({ message: 'Weather in SF?' });
-```
+const pipeline = Sequence.create().step('research', researchAgent).step('write', writerAgent).build();
 
-Builder methods:
-- `.system(prompt)` — base system prompt
-- `.tool(definedTool)` — register a tool
-- `.steering(injection)` · `.instruction(injection)` · `.skill(injection)` · `.fact(injection)` — context-engineering injections
-- `.memory(definition)` — register a memory (returned by `defineMemory()`)
-- `.build()` → `Agent` — runner with `.run({ message, identity? })`
+const desk = swarm({
+  agents: [{ id: 'research', runner: researchAgent }, { id: 'write', runner: writerAgent }],
+  route: ({ message }) => (/write/.test(message) ? 'write' : 'research'),
+});
+```
 
-### LLMCall (one-shot primitive)
+## Providers
 
 ```typescript
-import { LLMCall } from 'agentfootprint';
-import { anthropic } from 'agentfootprint/providers';
-
-const call = LLMCall.create({ provider: anthropic(...), model: 'claude-sonnet-4-5-20250929' })
-  .system('You are a terse assistant.')
-  .build();
+import { mock, anthropic, openai, bedrock, ollama } from 'agentfootprint/providers';
 
-const answer = await call.run({ message: 'Summarize: ...' });
+const provider = process.env.NODE_ENV === 'production'
+  ? anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! })
+  : ollama('llama3.2');            // free local model; or mock({...}) for determinism
 ```
 
-### Tools
+`mock` takes `{ reply }` (one fixed answer), `{ replies: [...] }` (consumed in order — exhaustion throws loud), or `{ respond: (req) => … }` (build the answer from the request, including `toolCalls`).
+
+## Tools
 
 ```typescript
 import { defineTool } from 'agentfootprint';
 
-const weather = defineTool({
-  name: 'weather',
-  description: 'Current weather for a city.',
-  inputSchema: {
-    type: 'object',
-    properties: { city: { type: 'string' } },
-    required: ['city'],
-  },
-  execute: async (args) => `${(args as { city: string }).city}: 72°F`,
+const calculator = defineTool({
+  name: 'calculator',                                  // `name`, not `id`
+  description: 'Perform arithmetic',
+  inputSchema: { type: 'object', properties: { expression: { type: 'string' } } },
+  execute: async ({ expression }: { expression: string }) => String(evaluate(expression)),
 });
 ```
 
-Tool-name uniqueness is validated at `agent.build()` time across `.tool()` registrations AND every Skill's `inject.tools[]`.
-
-A long-running tool can say where it is, mid-call, with `ctx.progress(payload)` —
-each call files one `agentfootprint.stream.tool_progress` event between that
-call's `tool_start` and `tool_end`, so a forty-second walk reads as "hop 3 of 12"
-instead of silence:
+### A long tool that says where it is
 
 ```typescript
 execute: async (args, ctx) => {
   for (const [i, hop] of hops.entries()) {
     await visit(hop);
-    ctx.progress({ done: i + 1, total: hops.length });   // telemetry, never the model's to read
+    ctx.progress({ done: i + 1, total: hops.length });   // → stream.tool_progress
   }
   return summarize(hops);
 },
 ```
 
-The framework stamps `toolCallId` / `toolName` / `iteration`; `payload` is yours,
-forwarded verbatim (it must survive `structuredClone`). Always present, never
-throws, never blocks — with nothing listening it is a no-op, and a tool that
-never calls it emits exactly what it emitted before.
-
-### Context Engineering — 4 typed factories
-
-All four return an `Injection` evaluated by the same engine; all emit the same `agentfootprint.context.injected` event with `source` discriminating the flavor.
-
-```typescript
-import {
-  defineSkill, defineSteering, defineInstruction, defineFact,
-} from 'agentfootprint';
-
-// Always-on rule (system-prompt)
-const tone = defineSteering({
-  id: 'tone',
-  prompt: 'Be friendly and concise.',
-});
-
-// Predicate-gated
-const urgent = defineInstruction({
-  id: 'urgent',
-  activeWhen: (ctx) => /urgent|asap/i.test(ctx.userMessage),
-  prompt: 'Prioritize the fastest path to resolution.',
-});
-
-// Dynamic ReAct — fires AFTER a specific tool returned (system slot, that turn only)
-const afterRedact = defineInstruction({
-  id: 'after-redact',
-  activeWhen: (ctx) => ctx.lastToolResult?.toolName === 'redact_pii',
-  prompt: 'Use the redacted text only. Do not paraphrase the original.',
-});
-// `slot: 'messages'` DELIVERS since 7.21.0 — it appends to `scope.history`, so the
-// window strategies, the trace and the wire all see it. It requires a `role` (no
-// default), and both wire rules can refuse: a role the provider does not carry
-// inside `messages` throws at RUN START naming the provider (Anthropic-family
-// drops 'system' there, OpenAI-family carries it), and a role that would repeat
-// the turn at the end of the window is DEFERRED to the next boundary with a
-// reason on `messagesDelivery.deferred`. Practical consequence: inside a
-// tool-using loop `role: 'user'` typically never delivers (the window ends on
-// the user's turn, or on tool results, which count as one) — use 'assistant', or
-// return the words from the tool itself.
-
-// LLM-activated body + tools (auto-attaches `read_skill` activation tool)
-const billing = defineSkill({
-  id: 'billing',
-  description: 'Use for refunds, subscriptions, invoices.',
-  body: 'Confirm identity before processing refunds.',
-  tools: [refundTool],
-});
-// A declarative `skillGraph()` is fully shipped (lib/injection-engine/skillGraph.ts):
-// fluent builder — .entry(skill,{when?}) .route(from,to,{when|onToolReturn}) .tree(decide(...))
-// .build() + toMermaid() — or the config form skillGraph({skills, start, steps} | {skills, tree}).
-// The v2 hardening ALL shipped versions ago: from-gating via currentSkillId, the scoped
-// read_skill gate (toolCalls.ts), per-matcher try/catch, entry scorers (entryBy/entryByRelevance/
-// entryByRead), governors + routeRecorder, and build-time validation (graph.checkup()).
-// Since 8.3.0 an accepted read_skill pick really activates (and can move the cursor);
-// since 8.4.0 invalid combinations refuse at build() with teaching messages, and skills the
-// graph doesn't route ("open skills": llm-activated + no incoming edge) activate via read_skill
-// without moving the cursor — so .selfExplain() works alongside a graph.
-// Spec: docs/design/skill-graph-spec.md; guide: docs/skill-graph-guide.md.
-
-// Developer-supplied data (not behavior)
-const userProfile = defineFact({
-  id: 'user',
-  data: 'User: Alice (alice@example.com), Plan: Pro.',
-});
-
-agent
-  .steering(tone)
-  .instruction(urgent)
-  .instruction(afterRedact)
-  .skill(billing)
-  .fact(userProfile);
-```
-
-### Memory — `defineMemory({ type, strategy, store })`
+`ctx.progress` is always present, never throws, never blocks, and never reaches
+the model — the framework stamps `toolCallId` / `toolName` / `iteration`, you own
+`payload`. `agent.on('agentfootprint.stream.*')` and `toSSE(agent)` carry it with
+no extra wiring.
 
-ONE factory dispatches `type × strategy.kind` onto the right pipeline. Multiple memories layer cleanly via per-id scope keys (`memoryInjection_${id}`).
+### When a tool finds nothing, and what a clean result does not cover
 
 ```typescript
-import {
-  defineMemory,
-  MEMORY_TYPES, MEMORY_STRATEGIES, SNAPSHOT_PROJECTIONS,
-  InMemoryStore, mockEmbedder,
-} from 'agentfootprint';
-
-// Short-term sliding window — the 90% case
-const shortTerm = defineMemory({
-  id: 'short-term',
-  type: MEMORY_TYPES.EPISODIC,
-  strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
-  store: new InMemoryStore(),
-});
-
-// Semantic recall — vector retrieval with strict threshold
-const facts = defineMemory({
-  id: 'facts',
-  type: MEMORY_TYPES.SEMANTIC,
-  strategy: {
-    kind: MEMORY_STRATEGIES.TOP_K,
-    topK: 3,
-    threshold: 0.7,                 // STRICT — empty when no match
-    embedder: mockEmbedder(),       // swap for openaiEmbedder() in prod
-  },
-  store: new InMemoryStore(),
-});
-
-// Causal — UNIQUE TO AGENTFOOTPRINT. Persists run snapshots so cross-run
-// "why was X rejected?" follow-ups answer from the STORED run: decisions
-// (footprintjs decide()/select() evidence + route/skill-graph provenance),
-// tool calls (args + result previews), iterations, duration, token usage —
-// harvested automatically by causalEvidenceRecorder when a CAUSAL memory is
-// mounted. (commitLog/narrative capture: not yet — see SnapshotEntry.)
-const causal = defineMemory({
-  id: 'causal',
-  type: MEMORY_TYPES.CAUSAL,
-  strategy: {
-    kind: MEMORY_STRATEGIES.TOP_K,
-    topK: 1,
-    threshold: 0.7,
-    embedder: mockEmbedder(),
-  },
-  store: new InMemoryStore(),
-  projection: SNAPSHOT_PROJECTIONS.DECISIONS,
-});
+import { absent, coverage, defineTool } from 'agentfootprint';
 
-agent.memory(shortTerm).memory(facts).memory(causal);
+// "I looked and there is nothing" — never readable as "I could not look".
+execute: ({ port }) => rows.length ? rows : absent({
+  what: `FLOGI entries on ${port}`,
+  checked: ['shq-fab-a: the live fcns database', 'window: the last 24h'],
+  notChecked: [{ what: 'the archived history', why: 'older than the 24h window' }],
+  cannotCover: [{ what: 'the peer fabric', why: 'this collector is scoped to one fabric' }],
+  tryInstead: 'Ask for a different interface, or query the peer fabric by name.',
+}),
 
-// Multi-tenant identity is plumbed through agent.run:
-await agent.run({
-  message: '...',
-  identity: { tenant: 'acme', principal: 'alice', conversationId: 'thread-42' },
-});
+// A verdict WITH its boundary — what "fine" does and does not rule out.
+execute: async () => coverage(await checkReplication(), {
+  checked: ['SRDF pair state on all 4 arrays'],
+  cannotCover: [{ what: 'host-side multipathing', why: 'no collector on the ESX hosts' }],
+}),
 ```
 
-The 4 memory **types**:
-- `EPISODIC` — raw conversation messages
-- `SEMANTIC` — extracted structured facts
-- `NARRATIVE` — beats / summaries of prior runs
-- `CAUSAL` — footprintjs decision-evidence snapshots ⭐
-
-The 7 **strategies**:
-- `WINDOW` (rule, last N) · `BUDGET` (decider, fit-to-tokens) · `SUMMARIZE` (one LLM call folds the older entries; the summary is stored, so a span is paid for once — needs `llm` + `model`)
-- `TOP_K` (score-threshold) · `EXTRACT` (LLM distills on write)
-- `DECAY` (recency-weighted, planned) · `HYBRID` (compose multiple)
+An absence gets the delivered status `'absent'` (route it with
+`onToolStatus: 'absent'`), files `agentfootprint.tools.absent`, and grounds only
+its COVERAGE in the evidence gate — so an id the model invented does not become
+grounded by one lookup that found nothing. It is never an error: nothing retries
+it, nothing refuses it, no `error: true`. A ledger files
+`agentfootprint.tools.coverage_declared`; add `.limitsTravelWithTheAnswer()` on
+the agent and the framework APPENDS the run's limits to the final answer, so the
+model cannot drop what it never wrote.
 
-### Compositions — Multi-Agent via Control Flow
-
-There is **no** `MultiAgentSystem` class. Multi-agent = compositions of single Agents through the same control flow that connects any flowchart stages:
+## Observing a run
 
 ```typescript
-import { Sequence, Parallel, Conditional, Loop } from 'agentfootprint';
-
-// Output flows downstream — every step needs an id + a runner
-const pipeline = Sequence.create()
-  .step('research', researcher)   // each runner is an Agent / LLMCall / composition
-  .step('write', writer)
-  .step('edit', editor)
-  .build();
-
-// Multi-perspective with LLM merge — branches need ids; rank via mergeWithLLM
-const tot = Parallel.create()
-  .branch('a', thoughtAgent)
-  .branch('b', thoughtAgent)
-  .branch('c', thoughtAgent)
-  .mergeWithLLM({ provider, model: 'mock', prompt: 'Pick the best answer.' })
-  .build();
-// (or .mergeWithFn((results) => ...) to merge in code)
+import { costRecorder, routeRecorder } from 'agentfootprint/observe';
 
-// Predicate-based routing — .when(id, predicate, runner); .otherwise is mandatory
-const triage = Conditional.create()
-  .when('billing', (input) => /refund|invoice/i.test(input.message), billingAgent)
-  .when('tech', (input) => /error|bug/i.test(input.message), techAgent)
-  .otherwise('general', generalAgent)
+const agent = Agent.create({ provider, model })
+  .watch(routeRecorder({ id: 'routes' }))              // recorders are factories, not classes
   .build();
 
-// Iterate with a REQUIRED budget — .repeat(body) + .times(n) / .forAtMost(ms) / .until(guard)
-const refine = Loop.create()
-  .repeat(critiqueAgent)
-  .until(({ iteration, latestOutput }) => latestOutput.includes('DONE'))
-  .times(5)
-  .build();
+agent.on('agentfootprint.context.evaluated', (e) => console.log(e.payload.activeIds));
 ```
 
-### Named patterns — recipes ship as runnable examples
-
-```
-ReAct            = Agent (default loop)
-Reflexion        = Sequence(Agent, critique-LLM, Agent)
-Tree-of-Thoughts = Parallel(Agent × N) + rank
-Self-Consistency = Parallel(Agent × N) + majority-vote
-Debate           = Loop(Agent × 2 + judge)
-Map-Reduce       = Parallel(Agent × N) + merge
-Swarm            = Agent whose tools are other Agents
-```
-
-Browse [`examples/patterns/`](examples/patterns/) — every pattern is a runnable end-to-end test.
-
-### Providers
+**121 typed events across 27 domains.** Two subscription shapes and no third:
+`'*'` (every event) and `'agentfootprint.<domain>.*'` (one domain). **`'agentfootprint.*'`
+is not a pattern** — TypeScript rejects it, and at runtime it would match nothing.
 
 ```typescript
-import { mock, anthropic, openai, bedrock, ollama } from 'agentfootprint/providers';
-
-// The ladder: shape the logic on the mock → check it against a REAL model for
-// free → pay only in production. One argument changes; the agent does not.
-const provider = process.env.NODE_ENV === 'production'
-  ? anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! })
-  : ollama('llama3.2');   // or mock({ reply: 'test response' }) for determinism
+agent.on('*', (e) => log(e));
+agent.on('agentfootprint.stream.*', (e) => log(e));           // tool_start, tool_end, deltas
+agent.on('agentfootprint.agent.turn_end', (e) =>
+  console.log(`${e.payload.iterationCount} iterations`));
 ```
 
-Every provider implements the same `LLMProvider` interface. `mock`,
-`browserAnthropic`, `browserOpenai`, and `createProvider` ship on the main
-barrel; `anthropic` · `openai` · `bedrock` · `ollama` live ONLY at
-`agentfootprint/providers` so bundlers never walk the vendor-SDK requires.
-Browser variants exist for client-side use.
-
-`ollama('<model>')` is the middle rung and needs NO vendor SDK — it talks
-Ollama's native API over `fetch`. Install Ollama, `ollama pull llama3.2`, done.
-When it can't work it says so in words that contain the fix (`ollama serve`,
-`ollama pull <model>`), never a raw connection error. `OLLAMA_MODEL=<model>`
-makes `providerFromEnv()` pick it, ahead of the cloud credentials.
-
-### Pause / Resume (Human-in-the-Loop)
+## Human in the loop
 
 ```typescript
-import { askHuman, pauseHere, isPaused } from 'agentfootprint';
-
-const approveTool = defineTool({
-  name: 'approve',
-  description: 'Ask a human.',
-  inputSchema: { type: 'object', properties: { amount: { type: 'number' } } },
-  // askHuman() / pauseHere() throw a PauseRequest — CALL them inside
-  // execute, don't pass them as the execute function.
-  execute: async (args) =>
-    askHuman({ question: `Approve $${(args as { amount: number }).amount}?` }),
-});
+import { askHuman, isPaused, checkInApproved } from 'agentfootprint';
 
 const result = await agent.run({ message: 'Refund $500?' });
 if (isPaused(result)) {
-  const checkpoint = result.checkpoint;          // JSON-serializable
-  // Persist to Redis/DB; later, on possibly different server:
-  const final = await agent.resume(checkpoint, { approved: true });
+  const final = await agent.resume(result.checkpoint, checkInApproved({ by: 'maya' }));
 }
 ```
 
-### Resilience
+## Resilience
 
 ```typescript
-import { withRetry, withFallback, fallbackProvider, withCircuitBreaker } from 'agentfootprint/resilience';
-import { anthropic, openai, ollama } from 'agentfootprint/providers';
+import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint/resilience';
 
 const reliable = withRetry(provider, { maxAttempts: 3 });
-const resilient = withFallback(primary, fallback);
-const chain = fallbackProvider(anthropic({...}), openai({...}), ollama('llama3.2'));
-const guarded = withCircuitBreaker(provider);
+const resilient = withFallback(primary, backup);
 ```
 
-Resilience decorators live on the `agentfootprint/resilience` subpath
-(not the main barrel). Each preserves the `LLMProvider` interface and
-stacks freely.
-
-### Result primitives — an absence that names itself, a limit that travels
-
-```typescript
-import { absent, coverage } from 'agentfootprint';
-
-// A tool that found nothing, in a shape no model can read as "I could not look".
-return absent({
-  what: `FLOGI entries on ${port}`,
-  checked: [`${sw}: the live fcns database`, 'window: the last 24h'],
-  cannotCover: [{ what: 'the peer fabric', why: 'this collector is scoped to one fabric' }],
-  tryInstead: 'Ask for a different interface, or query the peer fabric by name.',
-});
-
-// A verdict with its own boundary attached.
-return coverage(verdict, {
-  checked: ['SRDF pair state on all 4 arrays'],
-  notChecked: [{ what: 'NDM migration sessions', why: 'the API timed out' }],
-  cannotCover: [{ what: 'host-side multipathing', why: 'no collector on the ESX hosts' }],
-});
-```
-
-An absence carries the delivered status `'absent'` (routable by `onToolStatus`),
-files `agentfootprint.tools.absent`, and grounds only its coverage in the
-evidence gate. It is never an error — nothing retries or refuses it. A ledger
-files `agentfootprint.tools.coverage_declared`; with
-`.limitsTravelWithTheAnswer()` the framework appends the run's declared limits
-to the final answer, which is how a limit survives a model that would rather not
-mention it.
-
-### Observability — 120 typed events across 27 domains
-
-```typescript
-agent.on('agentfootprint.context.injected', (e) =>
-  console.log(`[${e.payload.source}] landed in ${e.payload.slot}`));
-agent.on('agentfootprint.stream.tool_start', (e) =>
-  console.log(`→ ${e.payload.toolName}(${JSON.stringify(e.payload.args)})`));
-agent.on('agentfootprint.agent.turn_end', (e) =>
-  console.log(`[${e.payload.iterationCount} iter, ${e.payload.totalInputTokens}+${e.payload.totalOutputTokens} tokens]`));
-```
-
-Wildcards: `.on('*', ...)` for every event, or `.on('agentfootprint.<domain>.*', ...)` per-domain (`agent`, `stream`, `context`, `tools`, `memory`, `cost`, `error`, …). `'agentfootprint.*'` is NOT a valid pattern — the dispatcher accepts `'*'` or `'agentfootprint.<DOMAIN>.*'` only. All events typed via `AgentfootprintEventMap`.
-
-Recorders (auto-attached when relevant builder method is called):
-- `ContextRecorder` — `context.evaluated` / `context.injected` / `context.slot_composed`
-- `streamRecorder` — `stream.llm_start` / `stream.llm_end` / `stream.token` / `stream.tool_start` / `stream.tool_end`
-- `agentRecorder` — `agent.turn_start` / `agent.turn_end` / `agent.iteration_start` / `agent.iteration_end` / `agent.route_decided`
-- `costRecorder` — `cost.tick` / `cost.limit_hit` (when `pricingTable` supplied)
-- `permissionRecorder` — `permission.check` (when `permissionChecker` supplied)
-- `evalRecorder` · `memoryRecorder` · `skillRecorder`
-
-**Observer delivery tier (RFC-001 Block 10):** `Agent.create({ observerDelivery:
-'deferred' })` routes the bridge recorders above + consumer `.watch()` /
-`agent.attach()` recorders through footprintjs's bounded capture queue —
-capture inline (≈ µs), deliver one beat behind, drain synchronously at run
-resolve / reject / pause. Default `'inline'` = byte-identical attach path, no
-queue allocated. `agent.on()` listeners receive deep-equal typed events either
-way (parity-tested). EXCEPTION kept inline: the causal-evidence recorder — the
-memory write stage reads `collect()` MID-run. A recorder's own `delivery`
-field beats the agent default (per-recorder override). Dials via
-`observerDeliveryOptions` (throws without `'deferred'`); shutdown via
-`agent.drainObservers({ timeoutMs })`; stats on
-`getLastSnapshot()?.observerStats`. CONTRACT: typed event payloads must be
-detached plain data — never pass a TypedScope read (e.g. `scope.history`, a
-live deep-Proxy) into `typedEmit`; use the plain local value (`typedEmit`
-dev-warns on unclonable payloads). Bench:
-`examples/features/21-deferred-observers.ts`.
-
-### Self-explain — `.selfExplain()` (the agent answers "why?" about its own last run)
-
-One builder call mounts ONE skill that, when the user asks a why-question, unlocks the 5 trace tools (`run_overview` / `trace_node` / `who_wrote` / `get_value` / `trace_slice`) for that iteration ONLY — bound LATE to the agent's PREVIOUS COMPLETED run (captured at `onRunEnd`/`onRunFailed`, so it can never serve an in-flight run; a failed run still explains "why did you fail?"). `delegate: { provider, model }` runs the trace-walk on a cheaper model via one `explain_run` tool. Requires `reactMode: 'dynamic'`/`'dynamic-grouped'` (classic caches the tools slot → throws at build); reserved tool-name clash also throws. Differs from **Causal memory**: `.selfExplain()` = THIS conversation's last run, in-memory, drill-by-id; Causal = any past run, persisted, recalled by similarity — reach for selfExplain on same-conversation follow-ups, Causal for cross-session. Note: Causal *similarity* recall needs a store with `search()` (only `InMemoryStore` today; Redis/AgentCore lack it). Full guide: docs `debug/self-explain`.
-
-## Anti-Patterns — Don't
-
-- ❌ **Don't ship a `ReflexionAgent` class.** Compose `Sequence(Agent, critique-LLM, Agent)`.
-- ❌ **Don't use `agent.run('string')`** — use `agent.run({ message: '...', identity? })`.
-- ❌ **Don't import from non-existent subpaths** like `'agentfootprint/instructions'` — the injection factories live on the main barrel (or `'agentfootprint/context'`). NOTE: `'agentfootprint/observe'`, `'agentfootprint/security'`, `'agentfootprint/resilience'`, `'agentfootprint/providers'`, `'agentfootprint/memory'`, `'agentfootprint/providers'`, `'agentfootprint/observe'` ARE real subpaths — some surfaces (vendor providers, resilience decorators) live ONLY there, not on the main barrel.
-- ❌ **Don't use `.memoryPipeline(pipeline)`** — that's the v1 API. Use `.memory(defineMemory({...}))`.
-- ❌ **Don't fall back when TopK threshold returns nothing.** Strict semantics: garbage past context > none is wrong.
-- ❌ **Don't store closures or class instances in scope** — TransactionBuffer can't clone functions. Memory-store entries serialize to JSON.
-- ❌ **Don't add new event types per feature.** Route through `agentfootprint.context.injected` with a new `source` value.
-- ❌ **Don't reach into `getArgs()` / `getEnv()` from injection content.** Predicates run with the engine's `InjectionContext` only.
-
 ## Decision Tree — Pick the Right Tool
 
 | Goal | Use |
@@ -620,43 +306,34 @@ One builder call mounts ONE skill that, when the user asks a why-question, unloc
 | Retrieve from a document corpus | `defineRAG({ store, embedder, topK, threshold })` |
 | Use tools from an external MCP server | `mcpClient({ transport, ... })` + `agent.tools(await c.tools())` |
 
-## Build & Test
+## Anti-Patterns
 
-```bash
-npm install agentfootprint footprintjs   # footprintjs ^6 is a peer dependency
-npm test                           # vitest run
-npm run example examples/...       # run a single example end-to-end
-npm run test:examples              # typecheck + run every example
-```
+- Don't use `id`/`handler` on `defineTool` — it's `name`/`execute`
+- Don't call `mock([...])` with an array — it's `mock({ replies: [...] })`
+- Don't import any provider (`mock` included) from the main barrel — they live on `agentfootprint/providers`
+- Don't `new` a recorder — they're lowercase factories attached via `.watch()`
+- Don't write `.entry(x, { when: () => true })` for an always-on skill — omit `when`, or use `.steering()`
+- Don't post-process execution — use recorders
 
-## Package layout
+## Checking your own wiring
 
-```
-src/
-├── core/         — Agent, LLMCall, builder methods, pause/resume
-├── core-flow/    — Sequence, Parallel, Conditional, Loop
-├── patterns/     — Reflexion, SelfConsistency, ToT, Debate, MapReduce, Swarm
-├── lib/
-│   └── injection-engine/  — Injection primitive + 4 factories + engine subflow
-├── memory/       — defineMemory + 4 types × 7 strategies + InMemoryStore + Causal
-├── adapters/llm/ — Anthropic, OpenAI, Bedrock, Ollama, Browser variants, Mock
-├── recorders/    — context, stream, agent, cost, skill, permission, eval, memory
-├── resilience/   — withRetry, withFallback, fallbackProvider, withCircuitBreaker
-└── stream.ts     — SSE formatter
-
-examples/        — runnable end-to-end tests organized by DNA layer
-  ├── core/                — primitives
-  ├── core-flow/           — compositions
-  ├── patterns/            — canonical recipes
-  ├── context-engineering/ — InjectionEngine flavors
-  ├── memory/              — 7 strategies
-  └── features/            — pause/cost/permissions/observability/events
+```bash
+npx agentfootprint-lint-tools tools.json   # confusable tool catalog — the CI gate
+npx agentfootprint-index ./docs --to ./corpus.db   # build a RAG corpus at boot time
 ```
 
-## Roadmap (informs what to defer)
+```typescript
+const report = graph.checkup({ knownTools: ['lookup_order'] });   // unreachable skills, unknown edges, dead entries
+if (!report.ok) throw new Error(formatCheckup(report));
+```
 
-- **v3.1 (current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + providers + RAG (`defineRAG`) + MCP (`mcpClient`) + Redis/AgentCore memory adapters + resilience (retry / fallback / circuit breaker) + Permission policy + observability subsystem
-- **Shipped since v2.0** — RAG flavor · Redis memory adapter · MCP integration · CircuitBreaker · governance (PermissionPolicy)
-- **Planned** — Causal training-data exports (SFT / DPO / process-RL) · DynamoDB / Postgres / Pinecone adapters · Deep Agents · A2A protocol · Lens UI integration
+## Going deeper
 
-When in doubt — read [`examples/`](examples/), every file is a runnable spec.
+The full architecture of the skill graph — the three surfaces, the authority rule, the
+nine cursor causes, the three-way `read_skill`, and a worked refusal taken from a real
+run — is published as **Skill graph architecture**:
+<https://agentfootprint.dev/docs/build/skill-graph-architecture/>.
+Every capability claim there carries a status — `shipped` / `opt-in` /
+`application-provided` / `planned` — and every code block is type-checked against the
+shipped types at build. Read it rather than this file when the question is "how does
+routing actually work"; read this file for what to reach for and what does not exist.