agentfootprint 2.1.0 → 2.3.0

package/AGENTS.md

@@ -32,8 +32,87 @@ The flavors are how you *mark intent* — but they all reduce to one `Injection`
 | **Instruction** | Predicate (`activeWhen` / `on-tool-return`) | system-prompt or messages |
 | **Fact** | Always-on (data) | system-prompt or messages |
 
+## Mock-first development (RECOMMENDED workflow)
+
+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.
+
+```typescript
+import { Agent, mock, InMemoryStore, mockEmbedder, defineTool } from 'agentfootprint';
+
+// 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({
+  schema: { name: 'lookup', description: '...', inputSchema: {} },
+  execute: async () => 'mock data',
+});
+
+const agent = Agent.create({ provider, model: 'mock' }).tool(lookup).build();
+await agent.run({ message: 'How long does a refund take?' });
+```
+
+| Boundary | Mock for development | Production swap |
+|---|---|---|
+| LLM provider | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
+| Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder factory |
+| Memory store | `InMemoryStore` | `RedisStore` (`agentfootprint/memory-redis`) · `AgentCoreStore` (`agentfootprint/memory-agentcore`) · 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:
+
+```typescript
+import { RedisStore } from 'agentfootprint/memory-redis';
+import { AgentCoreStore } from 'agentfootprint/memory-agentcore';
+```
+
+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:**
+
+```typescript
+const provider = mock({
+  replies: [
+    { toolCalls: [{ id: '1', name: 'lookup', args: { topic: 'refunds' } }] },
+    { content: 'Refunds take 3 business days.' },
+  ],
+});
+```
+
+Each `complete()` consumes one reply in order. Exhaustion throws loud — misnumbered scripts fail tests instead of silently looping.
+
 ## Public API
 
+### MCP — `mcpClient` (connect to MCP servers, register their tools)
+
+```typescript
+import { Agent, mcpClient } from 'agentfootprint';
+
+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
+  .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.
+
+`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.
+
 ### RAG — `defineRAG` (one factory, one helper)
 
 ```typescript
@@ -387,6 +466,7 @@ Recorders (auto-attached when relevant builder method is called):
 | Cross-run "why?" replay | `defineMemory({ type: CAUSAL, strategy: TOP_K })` ⭐ |
 | Long conversation overflows context | `defineMemory({ type: EPISODIC, strategy: SUMMARIZE })` |
 | 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
 

package/CLAUDE.md

@@ -32,8 +32,87 @@ The flavors are how you *mark intent* — but they all reduce to one `Injection`
 | **Instruction** | Predicate (`activeWhen` / `on-tool-return`) | system-prompt or messages |
 | **Fact** | Always-on (data) | system-prompt or messages |
 
+## Mock-first development (RECOMMENDED workflow)
+
+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.
+
+```typescript
+import { Agent, mock, InMemoryStore, mockEmbedder, defineTool } from 'agentfootprint';
+
+// 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({
+  schema: { name: 'lookup', description: '...', inputSchema: {} },
+  execute: async () => 'mock data',
+});
+
+const agent = Agent.create({ provider, model: 'mock' }).tool(lookup).build();
+await agent.run({ message: 'How long does a refund take?' });
+```
+
+| Boundary | Mock for development | Production swap |
+|---|---|---|
+| LLM provider | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
+| Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder factory |
+| Memory store | `InMemoryStore` | `RedisStore` (`agentfootprint/memory-redis`) · `AgentCoreStore` (`agentfootprint/memory-agentcore`) · 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:
+
+```typescript
+import { RedisStore } from 'agentfootprint/memory-redis';
+import { AgentCoreStore } from 'agentfootprint/memory-agentcore';
+```
+
+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:**
+
+```typescript
+const provider = mock({
+  replies: [
+    { toolCalls: [{ id: '1', name: 'lookup', args: { topic: 'refunds' } }] },
+    { content: 'Refunds take 3 business days.' },
+  ],
+});
+```
+
+Each `complete()` consumes one reply in order. Exhaustion throws loud — misnumbered scripts fail tests instead of silently looping.
+
 ## Public API
 
+### MCP — `mcpClient` (connect to MCP servers, register their tools)
+
+```typescript
+import { Agent, mcpClient } from 'agentfootprint';
+
+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
+  .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.
+
+`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.
+
 ### RAG — `defineRAG` (one factory, one helper)
 
 ```typescript
@@ -387,6 +466,7 @@ Recorders (auto-attached when relevant builder method is called):
 | Cross-run "why?" replay | `defineMemory({ type: CAUSAL, strategy: TOP_K })` ⭐ |
 | Long conversation overflows context | `defineMemory({ type: EPISODIC, strategy: SUMMARIZE })` |
 | 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
 

package/README.md

@@ -233,6 +233,55 @@ Every `.steering` / `.instruction` / `.memory` / `.tool` call adds an injection
 
 ---
 
+## Build with mocks first — swap real infra later
+
+Generative AI app development is expensive when every iteration hits a paid API. agentfootprint is designed so you can **build the entire app — agent, context engineering, tool chains, memory, RAG — against in-memory mocks**, prove the logic and patterns end-to-end with zero API cost, then swap real infrastructure in piece by piece.
+
+```typescript
+import {
+  Agent, defineTool, defineSteering, defineMemory,
+  MEMORY_TYPES, MEMORY_STRATEGIES,
+  mock, InMemoryStore,        // ← the mock surfaces
+} from 'agentfootprint';
+
+const agent = Agent.create({
+  provider: mock({ reply: 'Refunds take 3 business days.' }),  // ← no API key
+  model: 'mock',
+})
+  .steering(defineSteering({ id: 'tone', prompt: 'Be friendly.' }))
+  .tool(defineTool({
+    schema: { name: 'lookup', description: '...', inputSchema: {} },
+    execute: async () => 'mock data',                          // ← inline mock
+  }))
+  .memory(defineMemory({
+    id: 'short-term',
+    type: MEMORY_TYPES.EPISODIC,
+    strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+    store: new InMemoryStore(),                                // ← ephemeral
+  }))
+  .build();
+
+await agent.run({ message: 'How long does a refund take?' });
+```
+
+The whole flow runs offline. Iterate on context engineering, narrative, control-flow patterns, error handling, multi-agent compositions — **without** spending a cent.
+
+When the logic is right, swap one boundary at a time:
+
+| Boundary | Mock for development | Production swap |
+|---|---|---|
+| **LLM provider** | `mock({ reply })` · `mock({ replies })` for scripted ReAct | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
+| **Embedder** | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder (factories on roadmap) |
+| **Memory store** | `InMemoryStore` | `RedisStore` (`agentfootprint/memory-redis`) · `AgentCoreStore` (`agentfootprint/memory-agentcore`) · DynamoDB / Postgres / Pinecone (planned) |
+| **MCP server** | `mockMcpClient({ tools })` — in-memory, no SDK | `mcpClient({ transport })` to a real server |
+| **Tool execution** | `defineTool({ execute: async () => '...' })` | Same `defineTool`, real implementation |
+
+Each swap is one line. The flowchart, narrative, recorders, and tests don't change. Ship the patterns first; pay for tokens last.
+
+> Why this matters: it's the difference between *learning context engineering by trying things* and *learning by burning your API budget*. The library treats $0 development as a first-class workflow, not an afterthought.
+
+---
+
 ## Memory — one factory, four types, seven strategies
 
 `defineMemory({ type, strategy, store })` — one factory dispatches `type × strategy.kind` onto the right pipeline.
@@ -291,7 +340,8 @@ The same snapshot data shape becomes RL/SFT/DPO training data in v2.1+.
 
 | Release | Focus |
 |---|---|
-| v2.1 | RAG flavor (`defineRAG`) · Redis memory store adapter · MCP integration · CircuitBreaker as a first-class primitive · 3-tier structured-output fallback |
+| ~~v2.1~~ ✓ | RAG flavor (`defineRAG`) — shipped in 2.1.0 |
+| v2.2 | MCP integration (`mcpClient`) ✓ · Redis memory store adapter · CircuitBreaker primitive · 3-tier structured-output fallback |
 | v2.2 | Governance subsystem (`Policy`, `BudgetTracker`, role-based access) · DynamoDB / Postgres / Pinecone store adapters |
 | v2.3 | Causal training-data exports — `causalMemory.exportForTraining({ format: 'sft' \| 'dpo' \| 'process' })` for HuggingFace / OpenAI / Anthropic batch fine-tune |
 | v2.4+ | Deep Agents (planning-before-execution) · A2A protocol · Lens UI deep-link |

package/README.proposed.md

@@ -0,0 +1,258 @@
+<p align="center">
+  <h1 align="center">agentfootprint</h1>
+  <p align="center">
+    <strong>Build agents whose every decision, tool call, and memory write is a typed event<br>you can replay and audit — same day, or six months later.</strong>
+  </p>
+</p>
+
+<p align="center">
+  <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
+  <a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
+</p>
+
+<br>
+
+<!-- ┌────────────────────────────────────────────────────────────────┐
+     │  📹  30-second demo video goes here.                            │
+     │      Embed: GitHub-hosted MP4 or Loom thumbnail.                │
+     │      Content: paste a trace into the viewer → drag the          │
+     │      time-travel slider → every step is there.                  │
+     │      This is the single most important asset on this page.      │
+     └────────────────────────────────────────────────────────────────┘ -->
+
+> **Try it without installing anything →** [Open the live trace viewer](https://footprintjs.github.io/agent-playground/#/viewer), paste the [sample trace](./examples/sample-trace.json), drag the slider. You'll see what your agent did, not what it logged.
+
+---
+
+## In 30 seconds
+
+```bash
+npm install agentfootprint footprintjs
+```
+
+```typescript
+import { Agent, defineTool, mock } from 'agentfootprint';
+
+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`,
+});
+
+const agent = Agent.create({
+  provider: mock({ reply: 'Paris is 72°F and sunny.' }),  // ← no API key
+  model: 'mock',
+})
+  .system('You answer weather questions using the weather tool.')
+  .tool(weather)
+  .build();
+
+const result = await agent.run({ message: 'Weather in Paris?' });
+console.log(result);  // → "Paris is 72°F and sunny."
+```
+
+That runs offline, deterministically, in <100ms, with no API key. Swap `mock(...)` for `anthropic(...)` / `openai(...)` / `bedrock(...)` / `ollama(...)` for production. Nothing else changes.
+
+---
+
+## The model in your head
+
+Every LLM call has three slots. **Every "agent feature" — Skill, Steering doc, Instruction, Fact, Memory replay, RAG chunk — is content flowing into one of them, under one of four triggers.**
+
+```
+                       ┌─────────────────────────────────────┐
+                       │                                     │
+                       │    Your LLM call has 3 slots:       │
+                       │                                     │
+                       │    system    messages    tools      │
+                       │       ▲          ▲          ▲       │
+                       └───────┼──────────┼──────────┼───────┘
+                               │          │          │
+                               │   one    │   one    │
+                               │ Injection│ Injection│
+                               │  fires…  │  fires…  │
+                               │          │          │
+                ┌──────────────┴────┐  ┌──┴───┐  ┌──┴────┐
+                │ defineSkill        │  │ ...  │  │ ...   │
+                │ defineSteering     │  │      │  │       │
+                │ defineInstruction  │  │      │  │       │
+                │ defineFact         │  │      │  │       │
+                │ defineMemory(read) │  │      │  │       │
+                │ defineRAG (v2.1)   │  │      │  │       │
+                │   …your next idea  │  │      │  │       │
+                └────────────────────┘  └──────┘  └───────┘
+                          ▲
+                   …under one of:
+                  always · rule · on-tool-return · llm-activated
+```
+
+**There's no fourth slot.** There won't be. Every named pattern in the agent literature — Reflexion, Tree-of-Thoughts, Skills, RAG, Constitutional AI — reduces to *which slot* + *which trigger*. You learn one model; the field's growth lands as new factories on the same primitive.
+
+---
+
+## What you can build
+
+Three example shapes, all runnable end-to-end with `npm run example examples/<file>.ts`.
+
+### Customer support agent (with skills, memory, and audit trail)
+
+A support agent that activates a "billing" skill when needed, remembers the customer across sessions, and produces an audit-grade trace.
+
+```typescript
+const agent = Agent.create({ provider: anthropic(...), model: 'claude-sonnet-4-5-20250929' })
+  .system('You are a friendly support assistant.')
+  .skill(billingSkill)        // LLM activates with read_skill('billing')
+  .steering(toneGuidelines)   // always-on
+  .memory(conversationMemory) // remembers across .run() calls
+  .build();
+```
+
+→ [`examples/context-engineering/06-mixed-flavors.ts`](examples/context-engineering/06-mixed-flavors.ts)
+
+### Research pipeline (multi-agent, fan-out + merge)
+
+Three perspectives explore in parallel; an LLM merges their findings.
+
+```typescript
+const research = Parallel.create()
+  .branch(optimist).branch(skeptic).branch(historian)
+  .merge(synthesizer)
+  .build();
+
+await research.run({ message: 'Should we adopt microservices?' });
+```
+
+→ [`examples/patterns/05-tot.ts`](examples/patterns/05-tot.ts) (Tree-of-Thoughts) · [`examples/patterns/01-self-consistency.ts`](examples/patterns/01-self-consistency.ts)
+
+### Streaming chat agent (token-by-token to a browser)
+
+<!-- ┌────────────────────────────────────────────────────────────────┐
+     │  📹  Streaming demo clip here.                                  │
+     │      A short loop: user types → token-by-token streaming →     │
+     │      tool call appears mid-stream → final answer.              │
+     │      Demonstrates `provider.stream()` + SSE bridge.            │
+     └────────────────────────────────────────────────────────────────┘ -->
+
+```typescript
+agent.on('agentfootprint.stream.token', (e) => res.write(e.payload.content));
+agent.on('agentfootprint.stream.tool_start', (e) => res.write(`\n→ calling ${e.payload.toolName}...\n`));
+await agent.run({ message: userInput });
+```
+
+→ [`docs-site/guides/streaming/`](docs-site/src/content/docs/guides/streaming.mdx)
+
+---
+
+## The differentiator
+
+Agent frameworks are a crowded shelf. Two things in here are not on the rest of that shelf.
+
+### 1. Causal memory — replay *why*, not just *what*
+
+Other libraries' memory remembers what was said. **agentfootprint's `defineMemory({ type: CAUSAL })` remembers the decision evidence** — every `decide()` and `select()` value the agent's flowchart captured during the run. New questions cosine-match against past queries, inject the prior decision evidence, and the LLM answers from *exact past facts* — not reconstruction.
+
+```typescript
+const causal = defineMemory({
+  id: 'causal',
+  type: MEMORY_TYPES.CAUSAL,
+  strategy: { kind: MEMORY_STRATEGIES.TOP_K, topK: 1, threshold: 0.7, embedder },
+  store,
+  projection: SNAPSHOT_PROJECTIONS.DECISIONS,  // inject "why" only, not "what"
+});
+
+// Monday: agent decides loan #42 should be rejected (creditScore=580, threshold=600)
+// Friday: user asks "Why was my application rejected?"
+// → Causal memory loads the exact decision evidence from Monday.
+// → LLM answers from the SOURCE, not from memory of memory.
+```
+
+→ [`examples/memory/06-causal-snapshot.ts`](examples/memory/06-causal-snapshot.ts) — runs end-to-end with mock embedder, ~50 lines.
+
+The same snapshot data shape becomes RL/SFT/DPO training data in v2.3+. Every successful production run becomes a labeled trajectory.
+
+### 2. Trace export → trace replay
+
+Every run exports as one JSON blob. Paste it into the viewer six months later, on a different machine. Every decision, every tool call, every memory write is on a draggable time-travel slider. **No log parsing. No reconstruction. The trace IS the evidence.**
+
+```typescript
+const trace = exportTrace(agent);                       // serialize
+fs.writeFileSync('incident-2026-04-29.json', trace);    // archive
+
+// Later — different team, different machine
+<TraceViewer trace={JSON.parse(fs.readFileSync('incident-2026-04-29.json'))} />
+```
+
+That round-trip is the difference between "we shipped an agent and hope it's working" and "we can audit any production decision after the fact."
+
+---
+
+## Mocks first, prod second
+
+Generative AI development is expensive when every iteration hits a paid API. agentfootprint is designed so you build the entire app — agent, context engineering, memory, RAG — against in-memory mocks, prove the logic end-to-end with **zero API cost**, then swap real infrastructure in one boundary at a time.
+
+| Boundary | Dev (mock) | Prod (swap one line) |
+|---|---|---|
+| LLM provider | `mock({ reply })` | `anthropic()` · `openai()` · `bedrock()` · `ollama()` |
+| Embedder | `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder |
+| Memory store | `InMemoryStore` | Redis · DynamoDB · Postgres · Pinecone |
+| MCP server | `mcpClient({ _client })` | `mcpClient({ transport })` |
+| Tool execution | inline closure | real implementation |
+
+The flowchart, recorders, narrative, and tests don't change between dev and prod. **Ship the patterns first; pay for tokens last.**
+
+---
+
+## Pick your starting door
+
+| If you are... | Start here |
+|---|---|
+| 🎓 **New to agents** — never built one before | [5-minute Quick Start](https://footprintjs.github.io/agentfootprint/getting-started/quick-start/) → first agent runs offline |
+| 🛠️ **A LangChain / CrewAI / LangGraph user** | [Migration sketch](https://footprintjs.github.io/agentfootprint/getting-started/vs/) — same patterns, fewer classes |
+| 🏗️ **Architecting an enterprise rollout** | [Production guide](https://footprintjs.github.io/agentfootprint/guides/deployment/) — multi-tenant identity, audit trails, redaction, OTel |
+| 🔬 **Researcher / extending the framework** | [Extension guide](https://footprintjs.github.io/agentfootprint/contributing/extension-guide/) — add a new flavor in 50 lines |
+
+Every code snippet on the docs site is a real, runnable file in [`examples/`](examples/) — every example is also an end-to-end test in CI. There is no docs-only code in this repo.
+
+---
+
+## What ships today (v2.0)
+
+- **2 primitives** — `LLMCall`, `Agent` (the ReAct loop)
+- **4 compositions** — `Sequence`, `Parallel`, `Conditional`, `Loop`
+- **6 LLM providers** — Anthropic · OpenAI · Bedrock · Ollama · Browser-Anthropic · Browser-OpenAI · Mock
+- **One Injection primitive** — `defineSkill` / `defineSteering` / `defineInstruction` / `defineFact` (one engine, four typed factories, all reduce to `{ trigger, slot }`)
+- **One Memory factory** — `defineMemory({ type, strategy, store })` — 4 types × 7 strategies including **Causal**
+- **47 typed observability events** across 13 domains — context · stream · agent · cost · skill · permission · eval · memory · …
+- **Pause / resume** — JSON-serializable checkpoints; pause via `askHuman`/`pauseHere`, resume hours later on a different server
+- **Resilience** — `withRetry`, `withFallback`, `resilientProvider`
+- **AI-coding-tool support** — bundled instructions for Claude Code · Cursor · Windsurf · Cline · Kiro · Copilot
+- **33 runnable examples** organized by DNA layer (core · core-flow · patterns · context-engineering · memory · features)
+
+## What's next (clearly marked roadmap)
+
+| Release | Focus |
+|---|---|
+| v2.1 ✓ | RAG flavor (`defineRAG`) — *shipped* |
+| v2.2 | MCP integration (`mcpClient`) ✓ · Redis adapter · CircuitBreaker · 3-tier output fallback |
+| v2.3 | Governance (`Policy`, `BudgetTracker`) · DynamoDB / Postgres / Pinecone adapters |
+| v2.4 | Causal training-data exports — `causalMemory.exportForTraining({ format: 'sft' \| 'dpo' \| 'process' })` |
+| v2.5+ | Deep Agents (planning-before-execution) · A2A protocol · Lens UI deep-link |
+
+Roadmap items are *not* claims about the current API. If a feature isn't in `npm install agentfootprint` today, it's listed here, not in the documentation.
+
+---
+
+## Built on
+
+[footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. The decision-evidence capture, narrative recording, and time-travel checkpointing this library uses are footprintjs primitives. You don't need to learn footprintjs to use agentfootprint, but if you want to build your own primitives at this depth, [start there](https://footprintjs.github.io/footPrint/).
+
+## License
+
+[MIT](./LICENSE) © [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)

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

@@ -68,7 +68,21 @@ import {
 (`agentfootprint/instructions`, `agentfootprint/observe`,
 `agentfootprint/security`, `agentfootprint/explain` — these are v1).
 
-## Hello agent
+## Mock-first development (RECOMMENDED)
+
+Build the entire agent + context engineering + tools + memory + RAG + MCP with in-memory mocks first. Validate logic and patterns end-to-end with $0 API cost. Swap real infrastructure in one boundary at a time after the flow is right.
+
+| Mock | Production swap |
+|---|---|
+| `mock({ reply })` · `mock({ replies })` for scripted multi-turn | `anthropic()` / `openai()` / `bedrock()` / `ollama()` |
+| `InMemoryStore` | `RedisStore` (`agentfootprint/memory-redis`) · `AgentCoreStore` (`agentfootprint/memory-agentcore`) · Dynamo · Postgres · Pinecone (planned) |
+| `mockEmbedder()` | OpenAI / Cohere / Bedrock embedder factory |
+| `mockMcpClient({ tools })` — in-memory, no SDK | `mcpClient({ transport })` real server |
+| inline `defineTool({ execute: async () => '...' })` | real implementation |
+
+When generating starter code, default to the mock surface unless the user explicitly says they have a key / endpoint / store ready.
+
+## Hello agent — mock-first
 
 ```typescript
 const weather = defineTool({
@@ -81,12 +95,12 @@ const weather = defineTool({
       required: ['city'],
     },
   },
-  execute: async (args) => `${(args as { city: string }).city}: 72°F`,
+  execute: async (args) => `${(args as { city: string }).city}: 72°F`,  // mock data
 });
 
 const agent = Agent.create({
-  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
-  model: 'claude-sonnet-4-5-20250929',
+  provider: mock({ reply: 'San Francisco: 72°F, sunny.' }),  // ← no API key
+  model: 'mock',
   maxIterations: 10,
 })
   .system('You are a helpful weather assistant.')
@@ -96,7 +110,12 @@ const agent = Agent.create({
 const result = await agent.run({ message: 'Weather in SF?' });
 ```
 
-For testing, swap `anthropic({...})` for `mock({ reply: 'sunny' })` — same agent, $0.
+When the logic is right, swap to a real provider — one line:
+
+```typescript
+provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+model: 'claude-sonnet-4-5-20250929',
+```
 
 ## Context engineering
 
@@ -210,6 +229,38 @@ The 7 **strategies**:
 - `TOP_K` (score-threshold) · `EXTRACT` (LLM distills on write)
 - `DECAY` (recency-weighted, planned) · `HYBRID` (compose multiple)
 
+## MCP — `mcpClient` (connect to external MCP servers)
+
+```typescript
+import { Agent, mcpClient } from 'agentfootprint';
+
+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 server in one call
+  .build();
+
+await agent.run({ message: '...' });
+await slack.close();
+```
+
+Transports:
+- `{ transport: 'stdio', command, args, env?, cwd? }` — local subprocess
+- `{ transport: 'http', url, headers? }` — remote Streamable HTTP
+
+The `@modelcontextprotocol/sdk` peer-dep is **lazy-required** — zero
+runtime cost when MCP isn't used. Friendly install hint if missing.
+
+`agent.tools(arr)` is the bulk-register companion to `agent.tool(t)`.
+Tool-name uniqueness is validated at `.build()` across MCP servers +
+manual `.tool()` calls — duplicates throw early.
+
+Server-side support (exposing your agent as an MCP tool to other LLMs)
+is a separate concern, not yet shipped.
+
 ## RAG — `defineRAG` + `indexDocuments`
 
 ```typescript