footprintjs 0.10.1 → 0.10.2

package/AGENTS.md

@@ -0,0 +1,125 @@
+# footprint.js — AI Agent Instructions
+
+> The flowchart pattern for backend code — self-explainable systems that AI can reason about.
+
+## What This Library Does
+
+footprint.js structures backend logic as a graph of named functions with transactional state. Every run auto-generates a causal trace showing what happened and why. An LLM reads the trace and explains decisions accurately — no hallucination.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed detection)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → High-level executor (FlowChartExecutor)
+└── contract/  → I/O schema + OpenAPI generation
+```
+
+Two entry points:
+- `import { ... } from 'footprintjs'` — public API
+- `import { ... } from 'footprintjs/advanced'` — internals
+
+## Quick Start
+
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+
+const chart = flowChart('ReceiveOrder', (scope) => {
+    scope.setValue('orderId', 'ORD-123');
+    scope.setValue('amount', 49.99);
+  }, 'receive-order', undefined, 'Receive the incoming order')
+  .addFunction('ProcessPayment', (scope) => {
+    const amount = scope.getValue('amount');
+    scope.setValue('paymentStatus', amount < 100 ? 'approved' : 'review');
+  }, 'process-payment', 'Charge customer')
+  .setEnableNarrative()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: { orderId: 'ORD-123' } });
+console.log(executor.getNarrative());
+```
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)  // start chain
+  .addFunction(name, fn, id, description?)          // linear stage
+  .addDeciderFunction(name, fn, id, description?)   // single-choice branch
+    .addFunctionBranch(branchId, name, fn)           //   branch option
+    .addSubFlowChartBranch(branchId, subflow)        //   subflow branch
+    .setDefault(branchId)                             //   fallback
+    .end()                                            //   close decider
+  .addSelectorFunction(name, fn, id, description?)  // multi-choice fan-out
+  .addListOfFunction([...], { failFast? })           // parallel fork
+  .addSubFlowChartNext(id, subflow, mount, opts?)   // mount subflow inline
+  .loopTo(stageId)                                   // back-edge loop
+  .setEnableNarrative()                              // enable narrative
+  .setInputSchema(schema)                            // Zod or JSON Schema
+  .build()                                           // compile
+  .toSpec()                                          // JSON structure
+  .toMermaid()                                       // diagram
+```
+
+## Stage Function Signature
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade (per-stage state access)
+
+```typescript
+scope.getValue('key')              // tracked read → appears in narrative
+scope.setValue('key', value)        // tracked write → appears in narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+
+executor.getNarrative()         // string[] — combined flow + data
+executor.getNarrativeEntries()  // CombinedNarrativeEntry[] — structured
+executor.getSnapshot()          // full memory state
+executor.attachFlowRecorder(r)  // plug observer before run()
+executor.setRedactionPolicy({   // PII protection
+  keys: ['ssn'], patterns: [/password/i]
+})
+```
+
+## Two Observer Systems
+
+**Scope Recorder** — fires DURING stage: `onRead`, `onWrite`, `onCommit`, `onStageStart/End`
+**FlowRecorder** — fires AFTER stage: `onStageExecuted`, `onDecision`, `onFork`, `onNext`, `onLoop`, `onError`
+
+8 built-in FlowRecorder strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent.
+
+`CombinedNarrativeRecorder` implements BOTH — auto-attached by `setEnableNarrative()`.
+
+## Anti-Patterns
+
+- Never post-process the tree — use recorders
+- Never use deprecated `CombinedNarrativeBuilder`
+- Don't use `getArgs()` for tracked data — use `getValue()`/`setValue()`
+- Don't manually create `CombinedNarrativeRecorder` — `setEnableNarrative()` handles it
+
+## Build
+
+```bash
+npm install footprintjs
+npm run build    # CJS + ESM dual output
+npm test
+```

package/CLAUDE.md

@@ -0,0 +1,127 @@
+# footprint.js — AI Coding Instructions
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection (narrative, metrics, manifest, identity) happens as side effects of the single DFS traversal pass. Never walk the tree again after execution.
+
+## Architecture — Library of Libraries
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer, EventLog)
+├── schema/    → Validation abstraction (Zod optional, duck-typed detection)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), DeciderList, SelectorFnList)
+├── scope/     → Per-stage facades + recorders + providers (largest module)
+├── engine/    → DFS traversal + narrative + 13 handlers
+├── runner/    → High-level executor (FlowChartExecutor)
+└── contract/  → I/O schema + OpenAPI generation
+```
+
+Dependency DAG: `memory ← scope ← engine ← runner`, `schema ← engine`, `builder (standalone) → engine`, `contract ← schema`
+
+Two entry points:
+- `import { ... } from 'footprintjs'` — public API
+- `import { ... } from 'footprintjs/advanced'` — internals
+
+## Key API
+
+### Builder
+
+```typescript
+import { flowChart, FlowChartBuilder } from 'footprintjs';
+
+// flowChart(name, fn, id, buildTimeExtractor?, description?)
+const chart = flowChart('Stage1', fn1, 'stage-1', undefined, 'Description')
+  .addFunction('Stage2', fn2, 'stage-2', 'Description')
+  .addDeciderFunction('Decide', deciderFn, 'decide', 'Route based on risk')
+    .addFunctionBranch('high', 'Reject', rejectFn)
+    .addFunctionBranch('low', 'Approve', approveFn)
+    .setDefault('high')
+    .end()
+  .setEnableNarrative()
+  .build();
+```
+
+Methods: `start()`, `addFunction()`, `addStreamingFunction()`, `addDeciderFunction()`, `addSelectorFunction()`, `addListOfFunction()`, `addSubFlowChart()`, `addSubFlowChartNext()`, `loopTo()`, `setEnableNarrative()`, `setInputSchema()`, `setOutputSchema()`, `setOutputMapper()`, `build()`, `toSpec()`, `toMermaid()`
+
+### Stage Functions
+
+```typescript
+type PipelineStageFunction = (
+  scope: ScopeFacade,
+  breakPipeline: () => void,
+  streamCallback?: StreamCallback,
+) => Promise<void> | void;
+```
+
+### ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read (appears in narrative)
+scope.setValue('key', value)        // tracked write
+scope.updateValue('key', partial)  // deep merge
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+scope.attachRecorder(recorder)     // plug observer
+```
+
+**IMPORTANT:** `getValue`/`setValue` are tracked. `getArgs()` is NOT tracked and returns frozen input.
+
+### Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: data, timeoutMs: 5000, signal: abortSignal });
+
+executor.getNarrative()         // combined flow + data narrative
+executor.getNarrativeEntries()  // structured entries with type/depth/stageName
+executor.getFlowNarrative()     // flow-only (no data ops)
+executor.getSnapshot()          // full memory state
+executor.attachFlowRecorder(r)  // plug flow observer
+executor.setRedactionPolicy({}) // PII protection
+```
+
+## Two Observer Systems
+
+Both use `{ id, hooks } → dispatcher → error isolation → attach/detach`. Intentionally NOT unified.
+
+**Scope Recorder** (data ops — fires DURING stage execution):
+- `onRead`, `onWrite`, `onCommit`, `onError`, `onStageStart`, `onStageEnd`
+- Built-in: `NarrativeRecorder`, `MetricRecorder`, `DebugRecorder`
+
+**FlowRecorder** (control flow — fires AFTER stage execution):
+- `onStageExecuted`, `onNext`, `onDecision`, `onFork`, `onSelected`, `onSubflowEntry/Exit`, `onLoop`, `onBreak`, `onError`
+- Built-in: 8 strategies (Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest, Silent)
+
+**CombinedNarrativeRecorder** implements BOTH interfaces. Auto-attached by `setEnableNarrative()`.
+
+## Event Ordering
+
+```
+1. Recorder.onStageStart        — stage begins
+2. Recorder.onRead/onWrite      — DURING execution (buffered per-stage)
+3. Recorder.onCommit            — transaction flush
+4. Recorder.onStageEnd          — stage completes
+5. FlowRecorder.onStageExecuted — CombinedNarrativeRecorder flushes buffered ops
+6. FlowRecorder.onNext/onDecision/onFork — control flow continues
+```
+
+## Anti-Patterns
+
+- Never post-process the tree — use recorders
+- Never use deprecated `CombinedNarrativeBuilder` — use `CombinedNarrativeRecorder`
+- Don't extract shared base for Recorder/FlowRecorder — two instances = coincidence
+- Don't use `getArgs()` for tracked data — use `getValue()`/`setValue()`
+- Don't manually create `CombinedNarrativeRecorder` — `setEnableNarrative()` handles it
+
+## Build & Test
+
+```bash
+npm run build    # tsc (CJS) + tsc -p tsconfig.esm.json (ESM)
+npm test         # full suite
+npm run test:unit
+```
+
+Dual output: CommonJS (`dist/`) + ESM (`dist/esm/`) + types (`dist/types/`)

package/README.md

@@ -537,6 +537,54 @@ src/lib/
 
 ---
 
+## AI Coding Tool Support
+
+FootPrint ships with built-in instructions for every major AI coding assistant. Your AI tool understands the library's API, patterns, and anti-patterns out of the box.
+
+### Quick setup
+
+```bash
+# After installing footprintjs, run:
+npx footprintjs-setup
+```
+
+This interactive installer copies the right instruction files for your tool(s):
+
+| Tool | What gets installed | Format |
+|------|-------------------|--------|
+| **[Claude Code](https://claude.com/claude-code)** | `.claude/skills/footprint/SKILL.md` + `CLAUDE.md` | Interactive skill + project rules |
+| **[OpenAI Codex](https://openai.com/index/codex/)** | `AGENTS.md` | Agent instructions |
+| **[GitHub Copilot](https://github.com/features/copilot)** | `.github/copilot-instructions.md` | Custom instructions |
+| **[Cursor](https://cursor.com)** | `.cursor/rules/footprint.md` | Project rules |
+| **[Windsurf](https://windsurf.com)** | `.windsurfrules` | Project rules |
+| **[Cline](https://github.com/cline/cline)** | `.clinerules` | Project rules |
+| **[Kiro](https://kiro.dev)** | `.kiro/rules/footprint.md` | Project rules |
+
+Or install manually:
+
+```bash
+# Claude Code skill
+mkdir -p .claude/skills/footprint
+cp node_modules/footprintjs/ai-instructions/claude-code/SKILL.md .claude/skills/footprint/
+
+# Cursor rules
+mkdir -p .cursor/rules
+cp node_modules/footprintjs/ai-instructions/cursor/footprint.md .cursor/rules/
+
+# Any other tool — files are in node_modules/footprintjs/ai-instructions/
+```
+
+Every file teaches the AI assistant:
+- The **Builder**, **Executor**, and **ScopeFacade** APIs
+- The **recorder system** (scope + flow, two observer layers)
+- The **core principle**: collect during traversal, never post-process
+- **Anti-patterns** to avoid (deprecated APIs, wrong state access patterns)
+- **Event ordering** that makes inline narrative collection work
+
+This means any AI coding tool can help you build flowchart pipelines correctly from day one.
+
+---
+
 ## License
 
 [MIT](./LICENSE) © [Sanjay Krishna Anbalagan](https://github.com/sanjay1909)

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

@@ -0,0 +1,465 @@
+---
+name: footprint
+description: Use when building flowchart pipelines with footprintjs — stage functions, decider branches, selectors, subflows, loops, narrative traces, recorders, redaction, contracts, and LLM-ready output. Also use when someone asks how footprint.js works or wants to understand the library.
+---
+
+# footprint.js — The Flowchart Pattern for Backend Code
+
+footprint.js structures backend logic as a graph of named functions with transactional state. The code becomes self-explainable: every run auto-generates a causal trace of what happened and why.
+
+**Core principle:** All data collection happens during the single DFS traversal pass — never post-process or walk the tree again.
+
+```bash
+npm install footprintjs
+```
+
+---
+
+## Quick Start
+
+```typescript
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+
+const chart = flowChart('ReceiveOrder', (scope) => {
+    scope.setValue('orderId', 'ORD-123');
+    scope.setValue('amount', 49.99);
+  }, 'receive-order', undefined, 'Receive and validate the incoming order')
+  .addFunction('ProcessPayment', (scope) => {
+    const amount = scope.getValue('amount');
+    scope.setValue('paymentStatus', amount < 100 ? 'approved' : 'review');
+  }, 'process-payment', 'Charge customer and record payment status')
+  .setEnableNarrative()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: { orderId: 'ORD-123' } });
+
+console.log(executor.getNarrative());
+// Stage 1: The process began with ReceiveOrder.
+//   Step 1: Write orderId = "ORD-123"
+//   Step 2: Write amount = 49.99
+// Stage 2: Next, it moved on to ProcessPayment.
+//   Step 1: Read amount = 49.99
+//   Step 2: Write paymentStatus = "approved"
+```
+
+---
+
+## FlowChartBuilder API
+
+Always chain from `flowChart()` or `new FlowChartBuilder()`.
+
+### Linear Stages
+
+```typescript
+import { flowChart } from 'footprintjs';
+
+const chart = flowChart('StageA', fnA, 'stage-a', undefined, 'Description of A')
+  .addFunction('StageB', fnB, 'stage-b', 'Description of B')
+  .addFunction('StageC', fnC, 'stage-c', 'Description of C')
+  .build();
+```
+
+**Parameters:** `(name: string, fn: PipelineStageFunction, id: string, description?: string)`
+
+- `name` — human-readable label (used in narrative)
+- `fn` — the stage function
+- `id` — stable identifier (used for branching, visualization, loop targets)
+- `description` — optional, appears in narrative and auto-generated tool descriptions
+
+### Stage Function Signature
+
+```typescript
+type PipelineStageFunction = (
+  scope: ScopeFacade,       // read/write transactional state
+  breakPipeline: () => void, // call to stop execution early
+  streamCallback?: StreamCallback, // for streaming stages
+) => Promise<void> | void;
+```
+
+### ScopeFacade — State Access
+
+Every stage receives a `ScopeFacade` that tracks all reads and writes:
+
+```typescript
+const myStage = (scope: ScopeFacade) => {
+  // Read (tracked — appears in narrative)
+  const name = scope.getValue('applicantName') as string;
+
+  // Write (tracked — appears in narrative)
+  scope.setValue('greeting', `Hello, ${name}!`);
+
+  // Update (deep merge for objects)
+  scope.updateValue('profile', { verified: true });
+
+  // Delete
+  scope.deleteValue('tempData');
+
+  // Readonly input (frozen, not tracked in narrative)
+  const config = scope.getArgs<{ maxRetries: number }>();
+};
+```
+
+**IMPORTANT:** `getValue`/`setValue` are tracked and produce narrative. `getArgs()` returns frozen readonly input and is NOT tracked.
+
+### Decider Branches (Single-Choice Conditional)
+
+```typescript
+const chart = flowChart('Intake', intakeFn, 'intake')
+  .addDeciderFunction('AssessRisk', (scope) => {
+    const score = scope.getValue('riskScore') as number;
+    // Return the branch ID to take
+    return score > 70 ? 'high-risk' : 'low-risk';
+  }, 'assess-risk', 'Evaluate risk and route accordingly')
+    .addFunctionBranch('high-risk', 'RejectApplication', rejectFn, 'Reject due to high risk')
+    .addFunctionBranch('low-risk', 'ApproveApplication', approveFn, 'Approve the application')
+    .setDefault('high-risk') // fallback if branch ID doesn't match
+    .end()
+  .build();
+```
+
+The decider function **returns a branch ID string**. The engine matches it to a child and executes that branch. The decision is recorded in the narrative.
+
+### Selector Branches (Multi-Choice Fan-Out)
+
+```typescript
+const chart = flowChart('Intake', intakeFn, 'intake')
+  .addSelectorFunction('SelectChecks', (scope) => {
+    const checks = [];
+    if (scope.getValue('needsCredit')) checks.push('credit-check');
+    if (scope.getValue('needsIdentity')) checks.push('identity-check');
+    // Return array of branch IDs to execute in parallel
+    return checks;
+  }, 'select-checks')
+    .addFunctionBranch('credit-check', 'CreditCheck', creditFn)
+    .addFunctionBranch('identity-check', 'IdentityCheck', identityFn)
+    .end()
+  .build();
+```
+
+### Parallel Execution (Fork)
+
+```typescript
+builder.addListOfFunction([
+  { id: 'check-a', name: 'CheckA', fn: checkAFn },
+  { id: 'check-b', name: 'CheckB', fn: checkBFn },
+  { id: 'check-c', name: 'CheckC', fn: checkCFn },
+], { failFast: true }); // reject on first error
+```
+
+### Subflows (Nested Flowcharts)
+
+```typescript
+// Build a reusable sub-pipeline
+const creditSubflow = flowChart('PullReport', pullReportFn, 'pull-report')
+  .addFunction('ScoreReport', scoreReportFn, 'score-report')
+  .build();
+
+// Mount as linear continuation
+builder.addSubFlowChartNext('credit-sub', creditSubflow, 'CreditCheck', {
+  inputMapper: (parentScope) => ({ ssn: parentScope.getValue('ssn') }),
+  outputMapper: (subOut, parentScope) => ({ creditScore: subOut.score }),
+});
+
+// Mount as decider branch
+builder.addDeciderFunction('Route', routerFn, 'route')
+  .addSubFlowChartBranch('detailed', creditSubflow, 'DetailedCheck')
+  .addFunctionBranch('simple', 'SimpleCheck', simpleFn)
+  .end();
+```
+
+### Loops
+
+```typescript
+builder
+  .addFunction('RetryPayment', async (scope) => {
+    const attempts = (scope.getValue('attempts') as number ?? 0) + 1;
+    scope.setValue('attempts', attempts);
+    if (attempts >= 3) return; // exit loop by not looping
+  }, 'retry-payment')
+  .loopTo('retry-payment'); // back-edge to this stage's ID
+```
+
+### Configuration
+
+```typescript
+builder
+  .setEnableNarrative()              // enable narrative recording
+  .setInputSchema(zodSchema)         // validate input (Zod or JSON Schema)
+  .setOutputSchema(outputZodSchema)  // declare output shape
+  .setOutputMapper((state) => ({     // map final state to response
+    decision: state.decision,
+    reason: state.reason,
+  }));
+```
+
+### Output
+
+```typescript
+const chart = builder.build();      // FlowChart object (for executor)
+const spec = builder.toSpec();       // JSON-safe structure (for visualization)
+const mermaid = builder.toMermaid(); // Mermaid diagram string
+```
+
+---
+
+## FlowChartExecutor API
+
+```typescript
+import { FlowChartExecutor } from 'footprintjs';
+
+const executor = new FlowChartExecutor(chart);
+
+// Run with input
+const result = await executor.run({
+  input: { applicantName: 'Bob', income: 42000 },
+  timeoutMs: 5000,    // optional auto-abort
+  signal: controller.signal, // optional AbortSignal
+});
+
+// Get narrative (combined flow + data operations)
+const narrative: string[] = executor.getNarrative();
+// ["Stage 1: The process began with ReceiveApplication.",
+//  "  Step 1: Write app = {applicantName, income, ...}",
+//  "Stage 2: Next, it moved on to AssessRisk.",
+//  "  Step 1: Read app = ...",
+//  "  Step 2: Write riskTier = \"high\"",
+//  "[Condition]: A decision was made, path taken was RejectApplication."]
+
+// Structured entries (for programmatic access)
+const entries: CombinedNarrativeEntry[] = executor.getNarrativeEntries();
+// [{ type: 'stage', text: '...', depth: 0, stageName: 'ReceiveApplication' },
+//  { type: 'step', text: 'Write app = ...', depth: 1, stageName: 'ReceiveApplication', stepNumber: 1 },
+//  { type: 'condition', text: '...', depth: 0 }]
+
+// Full memory snapshot
+const snapshot = executor.getSnapshot();
+// { sharedState: { ... }, commitLog: [...], subflowResults: Map }
+
+// Flow-only narrative (no data operations)
+const flowOnly: string[] = executor.getFlowNarrative();
+```
+
+---
+
+## Recorder System — Collect During Traversal
+
+**The core innovation.** Two observer layers fire during the single DFS pass:
+
+### Scope Recorders (data operations)
+
+Attached to `ScopeFacade`, fire during `getValue()`/`setValue()`:
+
+```typescript
+import { MetricRecorder, DebugRecorder, NarrativeRecorder } from 'footprintjs';
+
+// Built-in recorders
+const metrics = new MetricRecorder();
+const debug = new DebugRecorder('verbose'); // or 'minimal'
+
+// Attach to scope (usually via scope factory)
+scope.attachRecorder(metrics);
+scope.attachRecorder(debug);
+
+// After execution
+metrics.getSummary(); // { totalReads: 12, totalWrites: 8, stages: {...} }
+debug.getEntries();   // [{ type: 'read', key: 'app', value: {...}, stage: 'Intake' }, ...]
+```
+
+### FlowRecorders (control flow events)
+
+Attached to executor, fire after each stage/decision/fork:
+
+```typescript
+import { NarrativeFlowRecorder, AdaptiveNarrativeFlowRecorder } from 'footprintjs';
+
+// Attach before run()
+executor.attachFlowRecorder(new NarrativeFlowRecorder());
+
+// 8 built-in strategies:
+// NarrativeFlowRecorder      — all events as sentences (default)
+// AdaptiveNarrativeFlowRecorder — full detail then sampling for loops
+// WindowedNarrativeFlowRecorder — keep last N iterations only
+// RLENarrativeFlowRecorder    — run-length encode repeated loops
+// MilestoneNarrativeFlowRecorder — only decisions, errors, subflows
+// ProgressiveNarrativeFlowRecorder — progress markers for streaming UIs
+// SeparateNarrativeFlowRecorder — dual channels (main + loop detail)
+// ManifestFlowRecorder        — subflow tree + spec catalog for LLM exploration
+```
+
+### Custom FlowRecorder
+
+```typescript
+import type { FlowRecorder, FlowStageEvent, FlowDecisionEvent } from 'footprintjs';
+
+const myRecorder: FlowRecorder = {
+  id: 'my-recorder',
+  onStageExecuted(event: FlowStageEvent) {
+    console.log(`Executed: ${event.stageName}`);
+  },
+  onDecision(event: FlowDecisionEvent) {
+    console.log(`Decision at ${event.stageName}: chose ${event.chosen}`);
+  },
+  clear() {
+    // Reset state before each run
+  },
+};
+
+executor.attachFlowRecorder(myRecorder);
+```
+
+### CombinedNarrativeRecorder (the inline dual-channel recorder)
+
+This is what powers `getNarrative()` and `getNarrativeEntries()`. It implements BOTH `Recorder` (scope) and `FlowRecorder` (engine) interfaces. It buffers scope ops per-stage, then flushes when the flow event arrives — producing merged entries in a single pass.
+
+**You don't need to create this manually.** Calling `.setEnableNarrative()` on the builder auto-attaches it.
+
+---
+
+## Redaction (PII Protection)
+
+```typescript
+executor.setRedactionPolicy({
+  keys: ['ssn', 'creditCardNumber'],           // exact key names
+  patterns: [/password/i, /^secret.*/],        // regex patterns
+  fields: { applicant: ['ssn', 'address.zip'] }, // nested field paths
+});
+
+await executor.run({ input: { ... } });
+
+// Narrative shows: Write ssn = [REDACTED]
+// Recorders receive scrubbed values
+const report = executor.getRedactionReport();
+// { redactedKeys: ['ssn'], patternsMatched: [...] } — never contains actual values
+```
+
+---
+
+## Contracts & OpenAPI
+
+```typescript
+import { defineContract, generateOpenAPI } from 'footprintjs';
+import { z } from 'zod';
+
+const contract = defineContract(chart, {
+  inputSchema: z.object({
+    applicantName: z.string(),
+    income: z.number(),
+  }),
+  outputSchema: z.object({
+    decision: z.enum(['approved', 'rejected']),
+    reason: z.string(),
+  }),
+  outputMapper: (state) => ({
+    decision: state.decision,
+    reason: state.reason,
+  }),
+});
+
+const openApiSpec = generateOpenAPI(contract, {
+  title: 'Loan Underwriting API',
+  version: '1.0.0',
+});
+```
+
+---
+
+## Event Ordering (Critical for Understanding)
+
+When a stage executes, events fire in this exact order:
+
+```
+1. Recorder.onStageStart        — stage begins
+2. Recorder.onRead              — each getValue() call (DURING execution)
+3. Recorder.onWrite             — each setValue() call (DURING execution)
+4. Recorder.onCommit            — transaction buffer flushes to shared memory
+5. Recorder.onStageEnd          — stage completes
+6. FlowRecorder.onStageExecuted — control flow records the stage
+   (CombinedNarrativeRecorder flushes buffered ops here)
+7. FlowRecorder.onNext          — moving to next stage
+   OR FlowRecorder.onDecision   — if this was a decider
+   OR FlowRecorder.onFork       — if children execute in parallel
+```
+
+**This ordering is what makes inline collection work.** Scope events buffer during execution, flow events trigger the flush.
+
+---
+
+## Anti-Patterns to Avoid
+
+1. **Never post-process the tree.** Don't walk the spec after execution to collect data. Use recorders.
+2. **Never use `CombinedNarrativeBuilder`** — it's deprecated. Use `CombinedNarrativeRecorder` (auto-attached by `setEnableNarrative()`).
+3. **Don't extract a shared base class** for Recorder and FlowRecorder. They look similar but serve different layers. Two instances = coincidence.
+4. **Don't call `getArgs()` for tracked data.** `getArgs()` returns frozen readonly input. Use `getValue()`/`setValue()` for state that should appear in the narrative.
+5. **Don't create scope recorders manually** unless building a custom recorder. `setEnableNarrative()` handles everything.
+
+---
+
+## Library Structure (for contributors)
+
+```
+src/lib/
+├── memory/    → SharedMemory, StageContext, TransactionBuffer, EventLog (foundation)
+├── schema/    → detectSchema, validate, InputValidationError (foundation)
+├── builder/   → FlowChartBuilder, flowChart(), DeciderList, SelectorFnList (standalone)
+├── scope/     → ScopeFacade, recorders/, providers/, protection/ (depends: memory)
+├── engine/    → FlowchartTraverser, handlers/, narrative/ (depends: memory, scope, builder)
+├── runner/    → FlowChartExecutor, ExecutionRuntime (depends: engine, scope, schema)
+└── contract/  → defineContract, generateOpenAPI (depends: schema)
+```
+
+Two entry points:
+- `import { ... } from 'footprintjs'` — public API
+- `import { ... } from 'footprintjs/advanced'` — internals (memory, traverser, handlers)
+
+---
+
+## Common Patterns
+
+### Pipeline with decision + narrative
+
+```typescript
+const chart = flowChart('Receive', receiveFn, 'receive')
+  .addFunction('Analyze', analyzeFn, 'analyze')
+  .addDeciderFunction('Decide', decideFn, 'decide')
+    .addFunctionBranch('approve', 'Approve', approveFn)
+    .addFunctionBranch('reject', 'Reject', rejectFn)
+    .setDefault('reject')
+    .end()
+  .setEnableNarrative()
+  .build();
+
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input: data });
+const trace = executor.getNarrative();
+// Feed trace to LLM for grounded explanations
+```
+
+### Subflow with input/output mapping
+
+```typescript
+const subflow = flowChart('SubStart', subStartFn, 'sub-start')
+  .addFunction('SubProcess', subProcessFn, 'sub-process')
+  .build();
+
+const main = flowChart('Main', mainFn, 'main')
+  .addSubFlowChartNext('my-subflow', subflow, 'SubflowMount', {
+    inputMapper: (scope) => ({ key: scope.getValue('parentKey') }),
+    outputMapper: (subOut) => ({ result: subOut.processed }),
+  })
+  .build();
+```
+
+### Attach multiple recorders
+
+```typescript
+import { ManifestFlowRecorder, MilestoneNarrativeFlowRecorder } from 'footprintjs';
+
+executor.attachFlowRecorder(new ManifestFlowRecorder());
+executor.attachFlowRecorder(new MilestoneNarrativeFlowRecorder());
+
+await executor.run({ input: data });
+
+const manifest = executor.getSubflowManifest(); // subflow catalog
+const milestones = executor.getFlowNarrative();  // key events only
+```

package/ai-instructions/clinerules

@@ -0,0 +1,79 @@
+# footprint.js — Cline Rules
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
+```
+
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)
+  .addFunction(name, fn, id, description?)
+  .addDeciderFunction(name, fn, id, description?)
+    .addFunctionBranch(branchId, name, fn) / .setDefault(id) / .end()
+  .addSelectorFunction(name, fn, id, description?)
+  .addListOfFunction([...], { failFast? })
+  .addSubFlowChartNext(id, subflow, mount, { inputMapper?, outputMapper? })
+  .loopTo(stageId)
+  .setEnableNarrative()
+  .build() / .toSpec() / .toMermaid()
+```
+
+## Stage Functions
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read → narrative
+scope.setValue('key', value)        // tracked write → narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+executor.getNarrative()            // combined flow + data
+executor.getNarrativeEntries()     // structured entries
+executor.getSnapshot()             // memory state
+executor.attachFlowRecorder(r)     // plug flow observer
+executor.setRedactionPolicy({ keys, patterns, fields })
+```
+
+## Observer Systems
+
+- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
+- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
+- 8 strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest
+- `CombinedNarrativeRecorder` implements both — auto-attached by `setEnableNarrative()`
+
+## Rules
+
+- Never post-process the tree — use recorders
+- `getValue()`/`setValue()` for tracked state; `getArgs()` for frozen input
+- Don't use deprecated `CombinedNarrativeBuilder`
+- `setEnableNarrative()` is all you need

package/ai-instructions/copilot-instructions.md

@@ -0,0 +1,86 @@
+# footprint.js — Copilot Instructions
+
+This is the footprint.js library — the flowchart pattern for backend code.
+
+## What It Does
+
+Structures backend logic as a graph of named functions with transactional state. Every run auto-generates a causal trace of what happened and why. LLMs read the trace for grounded explanations — no hallucination.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
+```
+
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
+
+## Key API
+
+### Builder Chain
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)
+  .addFunction(name, fn, id, description?)
+  .addDeciderFunction(name, fn, id, description?)
+    .addFunctionBranch(branchId, name, fn) / .setDefault(id) / .end()
+  .addSelectorFunction(name, fn, id, description?)
+  .addListOfFunction([...], { failFast? })
+  .addSubFlowChartNext(id, subflow, mount, { inputMapper?, outputMapper? })
+  .loopTo(stageId)
+  .setEnableNarrative()
+  .setInputSchema(schema) / .setOutputSchema(schema) / .setOutputMapper(fn)
+  .build() / .toSpec() / .toMermaid()
+```
+
+### Stage Functions
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+### ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read
+scope.setValue('key', value)        // tracked write
+scope.updateValue('key', partial)  // deep merge
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+### Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+executor.getNarrative()            // string[]
+executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
+executor.getSnapshot()             // memory state
+executor.attachFlowRecorder(r)     // plug observer
+executor.setRedactionPolicy({ keys, patterns, fields })
+```
+
+## Observer Systems
+
+- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
+- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
+- 8 built-in FlowRecorder strategies (Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest)
+- `setEnableNarrative()` auto-attaches `CombinedNarrativeRecorder` (implements both)
+
+## Rules
+
+- Never post-process the tree — use recorders
+- `getValue()`/`setValue()` for tracked state; `getArgs()` for frozen readonly input
+- Don't use deprecated `CombinedNarrativeBuilder`
+- `setEnableNarrative()` is all you need for narrative setup

package/ai-instructions/cursor/footprint.md

@@ -0,0 +1,80 @@
+# footprint.js — Cursor Rules
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
+```
+
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)
+  .addFunction(name, fn, id, description?)
+  .addDeciderFunction(name, fn, id, description?)
+    .addFunctionBranch(branchId, name, fn) / .setDefault(id) / .end()
+  .addSelectorFunction(name, fn, id, description?)
+  .addListOfFunction([...], { failFast? })
+  .addSubFlowChartNext(id, subflow, mount, { inputMapper?, outputMapper? })
+  .loopTo(stageId)
+  .setEnableNarrative()
+  .build() / .toSpec() / .toMermaid()
+```
+
+## Stage Function Signature
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read → narrative
+scope.setValue('key', value)        // tracked write → narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+executor.getNarrative()            // combined flow + data
+executor.getNarrativeEntries()     // structured entries
+executor.getSnapshot()             // memory state
+executor.attachFlowRecorder(r)     // plug flow observer
+executor.setRedactionPolicy({ keys, patterns, fields })
+```
+
+## Two Observer Systems (intentionally separate)
+
+- **Scope Recorder**: `onRead`, `onWrite`, `onCommit`, `onStageStart/End` — fires DURING execution
+- **FlowRecorder**: `onStageExecuted`, `onDecision`, `onFork`, `onNext`, `onLoop` — fires AFTER stage
+- 8 strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest
+- `CombinedNarrativeRecorder` implements both — auto-attached by `setEnableNarrative()`
+
+## Rules
+
+- Never post-process the tree — use recorders
+- `getValue()`/`setValue()` for tracked state; `getArgs()` for frozen readonly input
+- Don't use deprecated `CombinedNarrativeBuilder` — use `CombinedNarrativeRecorder`
+- Don't extract shared base for Recorder/FlowRecorder — coincidence, not pattern
+- `setEnableNarrative()` is all you need

package/ai-instructions/kiro/footprint.md

@@ -0,0 +1,79 @@
+# footprint.js — Kiro Rules
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
+```
+
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)
+  .addFunction(name, fn, id, description?)
+  .addDeciderFunction(name, fn, id, description?)
+    .addFunctionBranch(branchId, name, fn) / .setDefault(id) / .end()
+  .addSelectorFunction(name, fn, id, description?)
+  .addListOfFunction([...], { failFast? })
+  .addSubFlowChartNext(id, subflow, mount, { inputMapper?, outputMapper? })
+  .loopTo(stageId)
+  .setEnableNarrative()
+  .build() / .toSpec() / .toMermaid()
+```
+
+## Stage Functions
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read → narrative
+scope.setValue('key', value)        // tracked write → narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+executor.getNarrative()            // combined flow + data
+executor.getNarrativeEntries()     // structured entries
+executor.getSnapshot()             // memory state
+executor.attachFlowRecorder(r)     // plug flow observer
+executor.setRedactionPolicy({ keys, patterns, fields })
+```
+
+## Observer Systems
+
+- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
+- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
+- 8 strategies: Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest
+- `CombinedNarrativeRecorder` implements both — auto-attached by `setEnableNarrative()`
+
+## Rules
+
+- Never post-process the tree — use recorders
+- `getValue()`/`setValue()` for tracked state; `getArgs()` for frozen input
+- Don't use deprecated `CombinedNarrativeBuilder`
+- `setEnableNarrative()` is all you need

package/ai-instructions/setup.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# footprint.js — AI coding tool setup
+# Installs instruction files for your preferred AI coding assistant.
+#
+# Usage:
+#   npx footprintjs-setup          (after npm install footprintjs)
+#   bash node_modules/footprintjs/ai-instructions/setup.sh
+
+set -euo pipefail
+
+PKG_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(pwd)"
+
+echo ""
+echo "  footprint.js — AI Coding Tool Setup"
+echo "  ──────────────────────────────────────"
+echo ""
+echo "  This will copy instruction files so your AI coding"
+echo "  assistant understands the footprint.js API."
+echo ""
+
+install_claude_code() {
+  mkdir -p "$PROJECT_DIR/.claude/skills/footprint"
+  cp "$PKG_DIR/claude-code/SKILL.md" "$PROJECT_DIR/.claude/skills/footprint/SKILL.md"
+  # Also copy CLAUDE.md to project root if not present
+  if [ ! -f "$PROJECT_DIR/CLAUDE.md" ]; then
+    cp "$PKG_DIR/../CLAUDE.md" "$PROJECT_DIR/CLAUDE.md" 2>/dev/null || true
+  fi
+  echo "  [ok] Claude Code — .claude/skills/footprint/SKILL.md"
+}
+
+install_codex() {
+  if [ ! -f "$PROJECT_DIR/AGENTS.md" ]; then
+    cp "$PKG_DIR/../AGENTS.md" "$PROJECT_DIR/AGENTS.md" 2>/dev/null || true
+    echo "  [ok] OpenAI Codex — AGENTS.md"
+  else
+    echo "  [skip] AGENTS.md already exists"
+  fi
+}
+
+install_copilot() {
+  mkdir -p "$PROJECT_DIR/.github"
+  if [ ! -f "$PROJECT_DIR/.github/copilot-instructions.md" ]; then
+    cp "$PKG_DIR/copilot-instructions.md" "$PROJECT_DIR/.github/copilot-instructions.md"
+    echo "  [ok] GitHub Copilot — .github/copilot-instructions.md"
+  else
+    echo "  [skip] .github/copilot-instructions.md already exists"
+  fi
+}
+
+install_cursor() {
+  mkdir -p "$PROJECT_DIR/.cursor/rules"
+  cp "$PKG_DIR/cursor/footprint.md" "$PROJECT_DIR/.cursor/rules/footprint.md"
+  echo "  [ok] Cursor — .cursor/rules/footprint.md"
+}
+
+install_windsurf() {
+  if [ ! -f "$PROJECT_DIR/.windsurfrules" ]; then
+    cp "$PKG_DIR/windsurfrules" "$PROJECT_DIR/.windsurfrules"
+    echo "  [ok] Windsurf — .windsurfrules"
+  else
+    # Append footprint rules to existing file
+    echo "" >> "$PROJECT_DIR/.windsurfrules"
+    cat "$PKG_DIR/windsurfrules" >> "$PROJECT_DIR/.windsurfrules"
+    echo "  [ok] Windsurf — appended to .windsurfrules"
+  fi
+}
+
+install_cline() {
+  if [ ! -f "$PROJECT_DIR/.clinerules" ]; then
+    cp "$PKG_DIR/clinerules" "$PROJECT_DIR/.clinerules"
+    echo "  [ok] Cline — .clinerules"
+  else
+    echo "" >> "$PROJECT_DIR/.clinerules"
+    cat "$PKG_DIR/clinerules" >> "$PROJECT_DIR/.clinerules"
+    echo "  [ok] Cline — appended to .clinerules"
+  fi
+}
+
+install_kiro() {
+  mkdir -p "$PROJECT_DIR/.kiro/rules"
+  cp "$PKG_DIR/kiro/footprint.md" "$PROJECT_DIR/.kiro/rules/footprint.md"
+  echo "  [ok] Kiro — .kiro/rules/footprint.md"
+}
+
+install_all() {
+  install_claude_code
+  install_codex
+  install_copilot
+  install_cursor
+  install_windsurf
+  install_cline
+  install_kiro
+}
+
+# Interactive menu
+echo "  Which tool(s) do you use?"
+echo ""
+echo "    1) Claude Code"
+echo "    2) OpenAI Codex"
+echo "    3) GitHub Copilot"
+echo "    4) Cursor"
+echo "    5) Windsurf"
+echo "    6) Cline"
+echo "    7) Kiro"
+echo "    a) All of the above"
+echo "    q) Quit"
+echo ""
+read -rp "  Choose (e.g. 1,4 or a): " choice
+
+echo ""
+
+if [[ "$choice" == "q" ]]; then
+  echo "  Cancelled."
+  exit 0
+fi
+
+if [[ "$choice" == "a" || "$choice" == "A" ]]; then
+  install_all
+else
+  IFS=',' read -ra selections <<< "$choice"
+  for sel in "${selections[@]}"; do
+    sel="$(echo "$sel" | tr -d ' ')"
+    case "$sel" in
+      1) install_claude_code ;;
+      2) install_codex ;;
+      3) install_copilot ;;
+      4) install_cursor ;;
+      5) install_windsurf ;;
+      6) install_cline ;;
+      7) install_kiro ;;
+      *) echo "  [?] Unknown option: $sel" ;;
+    esac
+  done
+fi
+
+echo ""
+echo "  Done! Your AI assistant now knows the footprint.js API."
+echo "  Add the generated files to .gitignore if you don't want them in version control."
+echo ""

package/ai-instructions/windsurfrules

@@ -0,0 +1,79 @@
+# footprint.js — Windsurf Rules
+
+This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
+
+## Core Principle
+
+**Collect during traversal, never post-process.** All data collection happens as side effects of the single DFS traversal. Never walk the tree after execution.
+
+## Architecture
+
+```
+src/lib/
+├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
+├── schema/    → Validation (Zod optional, duck-typed)
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── scope/     → Per-stage facades + recorders + providers
+├── engine/    → DFS traversal + narrative + handlers
+├── runner/    → FlowChartExecutor
+└── contract/  → I/O schema + OpenAPI
+```
+
+Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
+
+## Builder API
+
+```typescript
+flowChart(name, fn, id, extractor?, description?)
+  .addFunction(name, fn, id, description?)
+  .addDeciderFunction(name, fn, id, description?)
+    .addFunctionBranch(branchId, name, fn) / .setDefault(id) / .end()
+  .addSelectorFunction(name, fn, id, description?)
+  .addListOfFunction([...], { failFast? })
+  .addSubFlowChartNext(id, subflow, mount, { inputMapper?, outputMapper? })
+  .loopTo(stageId)
+  .setEnableNarrative()
+  .build() / .toSpec() / .toMermaid()
+```
+
+## Stage Functions
+
+```typescript
+(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+```
+
+## ScopeFacade
+
+```typescript
+scope.getValue('key')              // tracked read → narrative
+scope.setValue('key', value)        // tracked write → narrative
+scope.updateValue('key', partial)  // deep merge (tracked)
+scope.deleteValue('key')           // tracked delete
+scope.getArgs<T>()                 // frozen readonly input (NOT tracked)
+```
+
+## Executor
+
+```typescript
+const executor = new FlowChartExecutor(chart);
+await executor.run({ input, timeoutMs?, signal? });
+executor.getNarrative()            // combined flow + data
+executor.getNarrativeEntries()     // structured entries
+executor.getSnapshot()             // memory state
+executor.attachFlowRecorder(r)     // plug flow observer
+executor.setRedactionPolicy({ keys, patterns, fields })
+```
+
+## Observer Systems
+
+- **Scope Recorder**: fires DURING stage (`onRead`, `onWrite`, `onCommit`)
+- **FlowRecorder**: fires AFTER stage (`onStageExecuted`, `onDecision`, `onFork`, `onLoop`)
+- 8 built-in strategies (Narrative, Adaptive, Windowed, RLE, Milestone, Progressive, Separate, Manifest)
+- `CombinedNarrativeRecorder` implements both — auto-attached by `setEnableNarrative()`
+
+## Rules
+
+- Never post-process the tree — use recorders
+- `getValue()`/`setValue()` for tracked state; `getArgs()` for frozen input
+- Don't use deprecated `CombinedNarrativeBuilder`
+- `setEnableNarrative()` is all you need for narrative

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Turn your whiteboard flowchart into running code — with automatic causal traces for LLM reasoning",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -49,7 +49,10 @@
     "dist/**/*",
     "!dist/test",
     "!dist/types/test",
-    "!dist/esm/types/test"
+    "!dist/esm/types/test",
+    "ai-instructions/**/*",
+    "CLAUDE.md",
+    "AGENTS.md"
   ],
   "main": "dist/index.js",
   "module": "dist/esm/index.js",
@@ -72,6 +75,9 @@
       "prettier --config .prettierrc.js --write"
     ]
   },
+  "bin": {
+    "footprintjs-setup": "ai-instructions/setup.sh"
+  },
   "sideEffects": false,
   "dependencies": {
     "lodash.get": "^4.4.2",