agentfootprint 1.23.0 → 2.1.0

package/ai-instructions/claude-code/SKILL.md

@@ -1,596 +1,370 @@
 ---
 name: agentfootprint
-description: Use when building AI agents with agentfootprint — LLM calls, ReAct agents, RAG pipelines, multi-agent flowcharts, swarm orchestration, tools, recorders, providers, adapters, and testing. Also use when someone asks how agentfootprint works or wants to understand the framework.
+description: Use when building Generative AI applications with agentfootprint — LLM calls, ReAct agents, multi-agent compositions (Sequence/Parallel/Conditional/Loop), context engineering (Skill/Steering/Instruction/Fact), memory (4 types × 7 strategies including Causal snapshots), tools, providers, observability, pause/resume, and patterns (Reflexion/ToT/Debate/MapReduce/Swarm). Also use when someone asks how agentfootprint works.
 ---
 
-# agentfootprint — The Explainable Agent Framework
+# agentfootprint — Skill
 
-agentfootprint builds AI agents you can explain, audit, and trust. Every agent is a footprintjs flowchart — every LLM call, tool use, and decision auto-generates a causal trace.
+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 2 primitives + 3 compositions + 1 unifying injection primitive + 1 memory factory.
 
-**Core principle:** Every concept is a flowchart. Collect during traversal, never post-process.
+Built on [footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. Every agent run produces a causal trace through the same DFS traversal, so observability is "free" (no instrumentation, no post-processing).
 
-```bash
-npm install agentfootprint footprintjs
-```
-
----
-
-## 5 Concepts — The Concept Ladder
-
-Each concept builds on footprintjs flowcharts. Each has a builder (`.create()`) and a runner (`.build()`).
-
-### 1. LLMCall — Single LLM Call (No Tools, No Loop)
-
-Flowchart: `SeedScope → CallLLM → ParseResponse → Finalize`
-
-```typescript
-import { LLMCall, mock } from 'agentfootprint';
+## The 6-layer mental model
 
-const caller = LLMCall.create({ provider: mock([{ content: 'Hello!' }]) })
-  .system('You are helpful.')
-  .build();
-
-const result = await caller.run('Hi');
-// result.content === 'Hello!'
-// result.messages — full message history
 ```
-
-**Builder API:**
-- `LLMCall.create({ provider })` — create with an LLM provider
-- `.system(prompt)` — set system prompt
-- `.recorder(rec)` — attach an AgentRecorder
-- `.build()` — returns `LLMCallRunner`
-
-**Runner API:**
-- `runner.run(message, { signal?, timeoutMs? })` — execute
-- `runner.getNarrative()` — causal trace from last run
-- `runner.getSnapshot()` — full memory state
-- `runner.getSpec()` — flowchart spec for visualization
-- `runner.toFlowChart()` — expose for subflow composition
-
-### 2. Agent — ReAct Agent (Tools + Loop)
-
-Flowchart: `SeedScope → PromptAssembly → CallLLM → ParseResponse → HandleResponse → loopTo('call-llm')`
-
-```typescript
-import { Agent, defineTool, mock } from 'agentfootprint';
-
-const searchTool = defineTool({
-  id: 'search',
-  description: 'Search the web',
-  inputSchema: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
-  handler: async (args) => `Results for: ${args.query}`,
-});
-
-const agent = Agent.create({ provider: mock([
-  { content: '', toolCalls: [{ id: 'tc1', name: 'search', args: { query: 'AI' } }] },
-  { content: 'AI is artificial intelligence.' },
-]), name: 'researcher' })
-  .system('You are a research assistant.')
-  .tool(searchTool)
-  .maxIterations(5)
-  .build();
-
-const result = await agent.run('What is AI?');
-// result.content — final answer
-// result.messages — full conversation
-// result.iterations — number of ReAct loops
+2 primitives        : LLMCall · Agent (= ReAct)
+3 compositions+Loop : Sequence · Parallel · Conditional · Loop
+N patterns          : ReAct · Reflexion · ToT · MapReduce · Debate · Swarm  (RECIPES, not classes)
+Context engineering : defineSkill · defineSteering · defineInstruction · defineFact
+Memory              : defineMemory({type, strategy, store}) — 4 types × 7 strategies
+Production features : pause/resume · cost · permissions · observability · events
 ```
 
-**Builder API:**
-- `Agent.create({ provider, name? })` — create with LLM provider
-- `.system(prompt)` — set system prompt
-- `.tool(toolDef)` — register a single tool
-- `.tools(toolDefs)` — register multiple tools
-- `.maxIterations(n)` — set max ReAct loop iterations (default: 10)
-- `.recorder(rec)` — attach an AgentRecorder
-- `.build()` — returns `AgentRunner`
-
-**Runner API:**
-- `runner.run(message, { signal?, timeoutMs? })` — execute
-- `runner.getNarrative()` / `runner.getNarrativeEntries()` — causal trace
-- `runner.getSnapshot()` — full memory state
-- `runner.getSpec()` — flowchart spec
-- `runner.toFlowChart()` — expose for subflow composition
-- `runner.getMessages()` — conversation history
-- `runner.resetConversation()` — clear conversation state
+## Three slots × six flavors
 
-### 3. RAG — Retrieve-Augment-Generate
-
-Flowchart: `SeedScope → Retrieve → AugmentPrompt → CallLLM → ParseResponse → Finalize`
-
-```typescript
-import { RAG, mock, mockRetriever } from 'agentfootprint';
-
-const rag = RAG.create({
-  provider: mock([{ content: 'Based on the documents...' }]),
-  retriever: mockRetriever([
-    { chunks: [{ content: 'AI was invented...', score: 0.95, metadata: {} }] },
-  ]),
-})
-  .system('Answer based on provided context only.')
-  .topK(5)
-  .minScore(0.7)
-  .build();
+Every LLM call has three slots, every "agent feature" is content flowing into one of them:
 
-const result = await rag.run('What is AI?');
-// result.content — generated answer
-// result.chunks — retrieved chunks
-// result.query — the query used for retrieval
-```
+| LLM API field | What goes here |
+|---|---|
+| `system` prompt | Steering · Instruction · Skill body · Fact data · formatted memory |
+| `messages` array | Conversation history · RAG chunks · memory replay · injected instructions |
+| `tools` array | Tool schemas (registered + Skill-attached) |
 
-**Builder API:**
-- `RAG.create({ provider, retriever })` — create with LLM + retriever
-- `.system(prompt)` — set system prompt
-- `.topK(n)` — number of chunks to retrieve
-- `.minScore(score)` — minimum relevance threshold
-- `.recorder(rec)` — attach an AgentRecorder
-- `.build()` — returns `RAGRunner`
+The flavors are intent markers — all reduce to one `Injection` primitive:
 
-### 4. FlowChart — Sequential Multi-Agent Composition
+| Flavor | Trigger | Slots |
+|---|---|---|
+| **Skill** | LLM-activated (`read_skill`) | system-prompt + tools |
+| **Steering** | Always-on | system-prompt |
+| **Instruction** | Predicate (`activeWhen` / `on-tool-return`) | system-prompt or messages |
+| **Fact** | Always-on (data) | system-prompt or messages |
 
-Run agents in order, each feeding into the next. Agents with `toFlowChart()` are mounted as subflows (enables UI drill-down).
+## Public API
 
 ```typescript
-import { FlowChart, Agent, mock, CostRecorder } from 'agentfootprint';
-
-const researcher = Agent.create({ provider: mock([{ content: 'Research findings...' }]), name: 'researcher' })
-  .system('You are a researcher.')
-  .build();
-
-const writer = Agent.create({ provider: mock([{ content: 'Final article...' }]), name: 'writer' })
-  .system('You are a writer.')
-  .build();
-
-const costRecorder = new CostRecorder();
-
-const pipeline = FlowChart.create()
-  .agent('researcher', 'Research', researcher)
-  .agent('writer', 'Write', writer)
-  .recorder(costRecorder)
-  .build();
-
-const result = await pipeline.run('Write about AI');
-// result.content — final output
-// result.agents — per-agent results [{ id, name, content, latencyMs }]
-// result.totalLatencyMs — end-to-end timing
-```
-
-**Builder API:**
-- `FlowChart.create()` — create empty pipeline
-- `.agent(id, name, runner, { inputMapper?, outputMapper? }?)` — add a runner
-- `.recorder(rec)` — attach an AgentRecorder
-- `.build()` — returns `FlowChartRunner`
-
-### 5. Swarm — LLM-Routed Multi-Agent
-
-An orchestrator agent delegates to specialist agents as tools. The LLM decides routing dynamically.
-
-```typescript
-import { Swarm, Agent, mock } from 'agentfootprint';
+import {
+  // Primitives + compositions
+  Agent, LLMCall, defineTool,
+  Sequence, Parallel, Conditional, Loop,
 
-const researcher = Agent.create({ provider: mock([{ content: 'Research done.' }]), name: 'researcher' })
-  .system('You research topics.')
-  .build();
+  // Context engineering — 4 typed factories over one Injection primitive
+  defineSkill, defineSteering, defineInstruction, defineFact,
 
-const writer = Agent.create({ provider: mock([{ content: 'Article written.' }]), name: 'writer' })
-  .system('You write articles.')
-  .build();
+  // Memory — one factory, 4 types × 7 strategies
+  defineMemory,
+  MEMORY_TYPES, MEMORY_STRATEGIES, MEMORY_TIMING, SNAPSHOT_PROJECTIONS,
+  InMemoryStore, mockEmbedder,
 
-const swarm = Swarm.create({ provider: mock([
-  { content: '', toolCalls: [{ id: 'tc1', name: 'research', args: { message: 'AI' } }] },
-  { content: 'Here is the article about AI.' },
-]) })
-  .system('You are a router. Delegate to the right specialist.')
-  .specialist('research', 'Research a topic in depth.', researcher)
-  .specialist('write', 'Write polished content.', writer)
-  .maxIterations(10)
-  .build();
+  // Providers (adapters)
+  anthropic, openai, bedrock, ollama, mock,
 
-const result = await swarm.run('Write about AI');
-// result.content — orchestrator's final response
-// result.agents — which specialists were invoked
-// result.totalLatencyMs
+  // Pause / resume / resilience
+  askHuman, pauseHere, isPaused,
+  withRetry, withFallback, resilientProvider,
+} from 'agentfootprint';
 ```
 
-**Builder API:**
-- `Swarm.create({ provider, name? })` — create with orchestrator LLM
-- `.system(prompt)` — orchestrator system prompt
-- `.specialist(id, description, runner, { inputMapper? }?)` — register specialist
-- `.tool(toolDef)` — register non-agent tool for orchestrator
-- `.maxIterations(n)` — max ReAct iterations
-- `.recorder(rec)` — attach an AgentRecorder
-- `.build()` — returns `SwarmRunner`
-
----
+**Top-level barrel only.** Don't import from stale subpaths
+(`agentfootprint/instructions`, `agentfootprint/observe`,
+`agentfootprint/security`, `agentfootprint/explain` — these are v1).
 
-## Tools — `defineTool()`
+## Hello agent
 
 ```typescript
-import { defineTool } from 'agentfootprint';
-
-const calculator = defineTool({
-  id: 'calculate',
-  description: 'Evaluate a math expression',
-  inputSchema: {
-    type: 'object',
-    properties: { expression: { type: 'string' } },
-    required: ['expression'],
-  },
-  handler: async (args) => {
-    return String(eval(args.expression));
+const weather = defineTool({
+  schema: {
+    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`,
 });
 
-// Register with agent
-agent.tool(calculator);
-```
-
-**Fields:** `id` (unique), `description` (sent to LLM), `inputSchema` (JSON Schema), `handler` (async function returning string).
-
----
-
-## Recorder System — Observe Without Changing Behavior
-
-All recorders implement the `AgentRecorder` interface with optional hooks:
-`onTurnStart`, `onLLMCall`, `onToolCall`, `onTurnComplete`, `onError`, `clear`.
-
-### Built-in Recorders
-
-```typescript
-import {
-  TokenRecorder,
-  CostRecorder,
-  TurnRecorder,
-  ToolUsageRecorder,
-  QualityRecorder,
-  GuardrailRecorder,
-  CompositeRecorder,
-} from 'agentfootprint';
-
-// Token tracking
-const tokens = new TokenRecorder();
-
-// Cost tracking (needs model pricing)
-const cost = new CostRecorder();
-
-// Turn-by-turn history
-const turns = new TurnRecorder();
-
-// Tool usage statistics
-const toolUsage = new ToolUsageRecorder();
-
-// Quality evaluation (with custom judge)
-const quality = new QualityRecorder(async (content) => ({
-  score: 0.9,
-  dimension: 'relevance',
-}));
-
-// Guardrail checks
-const guardrail = new GuardrailRecorder([
-  async (content) => ({ passed: true, checkName: 'no-pii' }),
-]);
-
-// Compose multiple recorders into one
-const composite = new CompositeRecorder([tokens, cost, turns]);
-```
-
-### Attach to Any Concept
-
-```typescript
-// On builders
-const agent = Agent.create({ provider })
-  .system('...')
-  .recorder(tokens)
-  .recorder(cost)
+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 weather assistant.')
+  .tool(weather)
   .build();
 
-// Or use CompositeRecorder
-const agent = Agent.create({ provider })
-  .recorder(new CompositeRecorder([tokens, cost, turns]))
-  .build();
+const result = await agent.run({ message: 'Weather in SF?' });
 ```
 
-### Read Results After Execution
+For testing, swap `anthropic({...})` for `mock({ reply: 'sunny' })` — same agent, $0.
 
-```typescript
-await agent.run('Hello');
-
-tokens.getStats();      // { totalInput: 50, totalOutput: 30, ... }
-cost.getEntries();      // [{ model, inputTokens, outputTokens, cost }]
-cost.getTotalCost();    // 0.0042
-turns.getEntries();     // [{ message, content, messageCount, ... }]
-toolUsage.getStats();   // { totalCalls: 3, tools: { search: { calls: 2, ... } } }
-```
-
-### Custom Recorder
+## Context engineering
 
 ```typescript
-import type { AgentRecorder } from 'agentfootprint';
-
-const myRecorder: AgentRecorder = {
-  id: 'my-recorder',
-  onLLMCall(event) {
-    console.log(`Model: ${event.model}, tokens: ${event.usage?.totalTokens}`);
-  },
-  onToolCall(event) {
-    console.log(`Tool: ${event.toolName}, latency: ${event.latencyMs}ms`);
-  },
-  clear() { /* reset state */ },
-};
-```
-
----
-
-## Providers & Adapters
-
-### Mock Provider (Testing)
+// Always-on rule (system-prompt)
+const tone = defineSteering({
+  id: 'tone',
+  prompt: 'Be friendly and concise.',
+});
 
-```typescript
-import { mock, mockRetriever } from 'agentfootprint';
+// Predicate-gated
+const urgent = defineInstruction({
+  id: 'urgent',
+  activeWhen: (ctx) => /urgent|asap/i.test(ctx.userMessage),
+  prompt: 'Prioritize the fastest path to resolution.',
+});
 
-// Mock LLM responses (consumed in order)
-const provider = mock([
-  { content: 'First response' },
-  { content: '', toolCalls: [{ id: 'tc1', name: 'search', args: { query: 'AI' } }] },
-  { content: 'Final answer' },
-]);
+// Dynamic ReAct — fires AFTER a specific tool returned (recency-weighted slot)
+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',  // higher LLM attention than system-prompt
+});
 
-// Mock retriever
-const retriever = mockRetriever([
-  { chunks: [{ content: 'doc text', score: 0.9, metadata: {} }] },
-]);
-```
+// 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],
+});
 
-### Real Providers
+// Developer-supplied data (not behavior)
+const userProfile = defineFact({
+  id: 'user',
+  data: 'User: Alice (alice@example.com), Plan: Pro.',
+});
 
-```typescript
-import { createProvider, anthropic, openai, bedrock } from 'agentfootprint';
-
-// Anthropic Claude
-const claude = createProvider(anthropic({
-  modelId: 'claude-sonnet-4-20250514',
-  apiKey: process.env.ANTHROPIC_API_KEY,
-}));
-
-// OpenAI
-const gpt = createProvider(openai({
-  modelId: 'gpt-4o',
-  apiKey: process.env.OPENAI_API_KEY,
-}));
-
-// AWS Bedrock
-const bedrockLLM = createProvider(bedrock({
-  modelId: 'anthropic.claude-3-sonnet',
-  region: 'us-east-1',
-}));
+agent
+  .steering(tone)
+  .instruction(urgent)
+  .instruction(afterRedact)
+  .skill(billing)
+  .fact(userProfile);
 ```
 
-### Protocol Adapters
-
-```typescript
-import { mcpToolProvider, a2aRunner } from 'agentfootprint';
-
-// MCP — connect to external tool servers
-const mcpTools = mcpToolProvider({ client: mcpClient });
-
-// A2A — call remote agents
-const remoteAgent = a2aRunner({ client: a2aClient, agentId: 'remote-1' });
-```
+Every flavor emits the same `agentfootprint.context.injected` event with `source` discriminating which factory produced it.
 
----
+## Memory
 
-## Prompt Providers
+`defineMemory({ type, strategy, store })` — ONE factory, dispatches `type × strategy.kind` onto the right pipeline. Multiple memories layer cleanly via per-id scope keys.
 
 ```typescript
-import { staticPrompt, templatePrompt, skillBasedPrompt, compositePrompt } from 'agentfootprint';
-
-// Static string
-const p1 = staticPrompt('You are helpful.');
-
-// Template with variables
-const p2 = templatePrompt('You are a {role} assistant.');
-
-// Skill-based (select instructions by context)
-const p3 = skillBasedPrompt({
-  skills: [
-    { id: 'search', instruction: 'Use search tool for factual queries.' },
-    { id: 'math', instruction: 'Use calculator for math questions.' },
-  ],
-  selector: (ctx) => ctx.message.includes('calculate') ? ['math'] : ['search'],
+// 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(),
 });
 
-// Compose providers
-const p4 = compositePrompt({ providers: [p1, p3] });
-```
-
----
+// 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(),
+});
 
-## Tool Providers
+// Causal — UNIQUE TO AGENTFOOTPRINT.
+// Persists footprintjs decision-evidence snapshots so cross-run
+// "why was X rejected?" follow-ups answer from EXACT past facts
+// (zero hallucination). Same data shape feeds SFT/DPO training-data
+// exports in v2.1+.
+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,
+});
 
-```typescript
-import { agentAsTool, compositeTools, defineTool } from 'agentfootprint';
+agent.memory(shortTerm).memory(facts).memory(causal);
 
-// Wrap an agent as a tool (for Swarm pattern)
-const agentTool = agentAsTool({
-  id: 'researcher',
-  description: 'Research a topic',
-  runner: researchAgent,
+// Multi-tenant identity — plumbs through agent.run:
+await agent.run({
+  message: '...',
+  identity: { tenant: 'acme', principal: 'alice', conversationId: 'thread-42' },
 });
-
-// Combine tool sets
-const allTools = compositeTools([staticTools, mcpTools]);
 ```
 
----
+The 4 **types**:
+- `EPISODIC` — raw conversation messages
+- `SEMANTIC` — extracted structured facts
+- `NARRATIVE` — beats / summaries of prior runs
+- `CAUSAL` — footprintjs decision-evidence snapshots ⭐
 
-## Compositions (Resilience)
+The 7 **strategies**:
+- `WINDOW` (rule, last N) · `BUDGET` (decider, fit-to-tokens) · `SUMMARIZE` (LLM compresses older)
+- `TOP_K` (score-threshold) · `EXTRACT` (LLM distills on write)
+- `DECAY` (recency-weighted, planned) · `HYBRID` (compose multiple)
+
+## RAG — `defineRAG` + `indexDocuments`
 
 ```typescript
-import { withRetry, withFallback, withCircuitBreaker } from 'agentfootprint';
+import { defineRAG, indexDocuments, InMemoryStore, mockEmbedder } from 'agentfootprint';
 
-// Retry with exponential backoff
-const resilient = withRetry(agent, { maxRetries: 3, delayMs: 1000 });
+const store = new InMemoryStore();
+const embedder = mockEmbedder();
 
-// Fallback to cheaper model
-const withFb = withFallback(primaryAgent, fallbackAgent);
+// Seed corpus once at startup
+await indexDocuments(store, embedder, [
+  { id: 'doc1', content: 'Refunds processed in 3 business days.' },
+  { id: 'doc2', content: 'Pro plan: $20/month.' },
+]);
 
-// Circuit breaker
-const breaker = withCircuitBreaker(agent, {
-  failureThreshold: 5,
-  resetTimeMs: 30000,
+// Define retriever
+const docs = defineRAG({
+  id: 'product-docs',
+  store, embedder,
+  topK: 3,
+  threshold: 0.7,        // STRICT — no fallback when nothing matches
+  asRole: 'user',        // chunks land as user-role context
 });
-```
-
----
 
-## Streaming
-
-```typescript
-import { StreamEmitter, SSEFormatter } from 'agentfootprint';
-
-const emitter = new StreamEmitter();
-emitter.on('chunk', (chunk) => process.stdout.write(chunk.text));
-
-const formatter = new SSEFormatter();
-// Convert stream events to SSE format for HTTP responses
+// Wire — `.rag()` is alias for `.memory()`, same plumbing
+agent.rag(docs);
 ```
 
----
+`defineRAG` is sugar over `defineMemory({ type: SEMANTIC, strategy: TOP_K })` with RAG-friendly defaults. Distinction is intent: RAG = document corpus retrieval; `defineMemory` = conversation/run-state memory.
 
-## Testing Patterns
+## Multi-agent via control flow
 
-Every concept uses `mock([...])` for deterministic testing — no API keys needed.
+There is **no** `MultiAgentSystem` class. Multi-agent = compositions of single Agents through the same control flow that connects any flowchart stages:
 
 ```typescript
-import { Agent, defineTool, mock, TokenRecorder, CostRecorder } from 'agentfootprint';
-
-// 1. Define tools
-const searchTool = defineTool({
-  id: 'search',
-  description: 'Search',
-  inputSchema: { type: 'object', properties: { q: { type: 'string' } }, required: ['q'] },
-  handler: async (args) => `Found: ${args.q}`,
-});
-
-// 2. Mock provider with scripted responses
-const provider = mock([
-  { content: '', toolCalls: [{ id: 'tc1', name: 'search', args: { q: 'test' } }] },
-  { content: 'The answer is 42.' },
-]);
-
-// 3. Build with recorders
-const tokens = new TokenRecorder();
-const cost = new CostRecorder();
+// Output flows downstream
+const pipeline = Sequence.create()
+  .step(researcher)
+  .step(writer)
+  .step(editor)
+  .build();
 
-const agent = Agent.create({ provider, name: 'test-agent' })
-  .system('You are helpful.')
-  .tool(searchTool)
-  .recorder(tokens)
-  .recorder(cost)
+// Multi-perspective with merge
+const tot = Parallel.create()
+  .branch(thoughtAgent)
+  .branch(thoughtAgent)
+  .branch(thoughtAgent)
+  .merge(rankerLLM)
   .build();
 
-// 4. Run and assert
-const result = await agent.run('What is the answer?');
-expect(result.content).toBe('The answer is 42.');
-expect(result.iterations).toBe(2);
+// Predicate-based routing
+const triage = Conditional.create()
+  .when((ctx) => ctx.intent === 'billing', billingAgent)
+  .when((ctx) => ctx.intent === 'tech', techAgent)
+  .otherwise(generalAgent)
+  .build();
 
-// 5. Inspect narrative (causal trace)
-const narrative = agent.getNarrative();
-// Verify the execution path
-expect(narrative.some(line => line.includes('CallLLM'))).toBe(true);
+// Iterate with budget
+const refine = Loop.create()
+  .body(critiqueAgent)
+  .untilGuard((ctx) => ctx.qualityScore > 0.9)
+  .maxIterations(5)
+  .build();
 ```
 
----
-
-## Architecture
+## Named patterns — recipes ship as runnable examples
 
 ```
-src/
-├── types/        → Content blocks, messages, LLM types, tool types, agent types
-├── models/       → Model configs (anthropic, openai, ollama, bedrock)
-├── adapters/     → Mock, Anthropic, OpenAI, Bedrock, MCP, A2A, createProvider
-├── tools/        → ToolRegistry, defineTool
-├── memory/       → Message helpers (appendMessage, lastMessage, lastAssistantMessage)
-├── scope/        → AgentScope (typed paths into footprintjs ScopeFacade)
-├── stages/       → Reusable stage functions (seedScope, callLLM, parseResponse, etc.)
-├── core/         → AgentRecorder, PromptProvider, ToolProvider, AgentLoopConfig
-├── concepts/     → LLMCall, Agent, RAG, FlowChart, Swarm (builders + runners)
-├── recorders/    → Scope-level + AgentRecorder implementations
-│   └── v2/       → TokenRecorder, CostRecorder, TurnRecorder, ToolUsageRecorder, etc.
-├── providers/    → Prompt providers, tool providers (agentAsTool, compositeTools)
-├── compositions/ → withRetry, withFallback, withCircuitBreaker
-├── streaming/    → StreamEmitter, SSEFormatter
-└── executor/     → agentLoop (low-level loop runner)
+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
 ```
 
-Single entry point: `import { ... } from 'agentfootprint'`
+Browse [`examples/patterns/`](examples/patterns/) — every pattern is a runnable end-to-end test.
 
----
-
-## Anti-Patterns to Avoid
-
-1. **Never post-process the flowchart** — use recorders to collect data during traversal.
-3. **Never build agents without `mock()`** in tests — no API keys in test suites.
-4. **Don't skip `.recorder(rec)`** — always attach recorders to observe execution.
-5. **Don't use raw footprintjs stages** for agent logic — use concept builders (`Agent.create()`, `LLMCall.create()`, etc.).
-6. **Don't create flat stages for multi-agent** — use `FlowChart.create().agent(...)` or `Swarm.create().specialist(...)` so the UI gets drill-down.
-7. **Don't manually call `agentLoop()`** unless building a custom concept — use the 5 concept builders.
-8. **Don't mix `mock()` and real providers** in the same builder — pick one.
-
----
+## Pause / resume (HITL)
 
-## Concept Ladder Summary
-
-| Concept | Pattern | Tools | Loop | Multi-Agent |
-|---------|---------|-------|------|-------------|
-| `LLMCall` | Single call | No | No | No |
-| `Agent` | ReAct | Yes | Yes | No |
-| `RAG` | Retrieve + Generate | No | No | No |
-| `FlowChart` | Sequential pipeline | Via agents | Via agents | Yes |
-| `Swarm` | LLM-routed handoff | Yes + agents | Yes | Yes |
+```typescript
+import { askHuman, pauseHere, isPaused } from 'agentfootprint';
 
----
+const approveTool = defineTool({
+  schema: { name: 'approve', description: 'Ask a human.', inputSchema: { ... } },
+  execute: askHuman({ severity: 'high' }),
+});
 
-## Common Patterns
+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 });
+}
+```
 
-### Agent with tools and cost tracking
+## Observability — 47 typed events × 13 domains
 
 ```typescript
-const cost = new CostRecorder();
-const agent = Agent.create({ provider: createProvider(anthropic({ modelId: 'claude-sonnet-4-20250514' })) })
-  .system('You are a helpful assistant.')
-  .tool(searchTool)
-  .tool(calculatorTool)
-  .recorder(cost)
-  .build();
-
-await agent.run('Calculate 2+2 and search for AI');
-console.log(`Total cost: $${cost.getTotalCost()}`);
+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, tokens=${e.payload.totalInputTokens}+${e.payload.totalOutputTokens}]`));
+
+// Wildcards work
+agent.on('agentfootprint.*', (e) => log(e));
 ```
 
-### Multi-agent pipeline with narrative
-
-```typescript
-const pipeline = FlowChart.create()
-  .agent('planner', 'Plan', plannerAgent)
-  .agent('executor', 'Execute', executorAgent)
-  .agent('reviewer', 'Review', reviewerAgent)
-  .build();
+## 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 stale subpaths** (`agentfootprint/instructions`, `agentfootprint/observe`, `agentfootprint/security`). Top-level barrel covers everything: `from 'agentfootprint'`.
+- ❌ **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 for `agentObservability()`** — it's a v1 name. Use the recorder factories: `agentRecorder({...})`, `costRecorder({...})`, etc.
+
+## Decision tree — pick the right tool
+
+| Goal | Use |
+|---|---|
+| One-shot LLM call (summarization, classification) | `LLMCall` |
+| Loop with tools (research, code, anything iterative) | `Agent` |
+| Two LLM calls in series with output flowing | `Sequence` |
+| Multiple critics, merge with LLM | `Parallel` |
+| Route to specialist by intent | `Conditional` |
+| Iterate until quality bar | `Loop` |
+| Output format / persona / safety policy | `defineSteering` |
+| Rule that fires when predicate matches | `defineInstruction` |
+| LLM activates a body of expertise + its tools | `defineSkill` |
+| Inject user profile / current time / env data | `defineFact` |
+| Remember last N turns of conversation | `defineMemory({ type: EPISODIC, strategy: WINDOW })` |
+| Semantic recall via embeddings | `defineMemory({ type: SEMANTIC, strategy: TOP_K })` |
+| Cross-run "why?" replay | `defineMemory({ type: CAUSAL, strategy: TOP_K })` ⭐ |
+| Long conversation overflows context | `defineMemory({ type: EPISODIC, strategy: SUMMARIZE })` |
+
+## Build & test
 
-const result = await pipeline.run('Build a website');
-console.log(pipeline.getNarrative()); // Full causal trace across all agents
+```bash
+npm install agentfootprint footprintjs
+npm test                           # vitest run — 1100+ tests
+npm run example examples/...       # run a single example end-to-end
+npm run examples:run-all           # run every example (33 of them)
 ```
 
-### Swarm with specialist routing
+## Roadmap (informs what to defer)
 
-```typescript
-const swarm = Swarm.create({ provider })
-  .system('Route to the best specialist for the task.')
-  .specialist('coder', 'Write and debug code.', coderAgent)
-  .specialist('writer', 'Write documentation and articles.', writerAgent)
-  .specialist('analyst', 'Analyze data and produce reports.', analystAgent)
-  .build();
+- **v2.0 (current)** — primitives + compositions + InjectionEngine + Memory (incl. Causal) + 6 providers + 33 examples
+- **v2.1** — RAG flavor (`defineRAG`) · Redis memory adapter · MCP integration · CircuitBreaker · 3-tier output fallback
+- **v2.2** — Governance (Policy + BudgetTracker) · DynamoDB / Postgres / Pinecone adapters
+- **v2.3** — Causal training-data exports (`exportForTraining({ format: 'sft' | 'dpo' | 'process' })`)
+- **v2.4+** — Deep Agents · A2A protocol · Lens UI integration
 
-await swarm.run('Write unit tests for the auth module');
-```
+When in doubt — read [`examples/`](examples/), every file is a runnable spec.