footprintjs 1.0.0 → 2.0.0

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

@@ -18,20 +18,26 @@ npm install footprintjs
 ## Quick Start
 
 ```typescript
-import { flowChart, FlowChartExecutor } from 'footprintjs';
+import { typedFlowChart, createTypedScopeFactory, FlowChartExecutor } from 'footprintjs';
 
-const chart = flowChart('ReceiveOrder', (scope) => {
-    scope.setValue('orderId', 'ORD-123');
-    scope.setValue('amount', 49.99);
+interface OrderState {
+  orderId: string;
+  amount: number;
+  paymentStatus: string;
+}
+
+const chart = typedFlowChart<OrderState>('ReceiveOrder', (scope) => {
+    scope.orderId = 'ORD-123';
+    scope.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');
+    const amount = scope.amount;
+    scope.paymentStatus = amount < 100 ? 'approved' : 'review';
   }, 'process-payment', 'Charge customer and record payment status')
   .setEnableNarrative()
   .build();
 
-const executor = new FlowChartExecutor(chart);
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<OrderState>());
 await executor.run({ input: { orderId: 'ORD-123' } });
 
 console.log(executor.getNarrative());
@@ -47,14 +53,20 @@ console.log(executor.getNarrative());
 
 ## FlowChartBuilder API
 
-Always chain from `flowChart()` or `new FlowChartBuilder()`.
+Always chain from `typedFlowChart<T>()` (recommended) or `flowChart()`.
 
 ### Linear Stages
 
 ```typescript
-import { flowChart } from 'footprintjs';
+import { typedFlowChart } from 'footprintjs';
+
+interface MyState {
+  valueA: string;
+  valueB: number;
+  valueC: boolean;
+}
 
-const chart = flowChart('StageA', fnA, 'stage-a', undefined, 'Description of A')
+const chart = typedFlowChart<MyState>('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();
@@ -67,69 +79,102 @@ const chart = flowChart('StageA', fnA, 'stage-a', undefined, 'Description of A')
 - `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
+### Stage Function Signature (TypedScope)
 
-Every stage receives a `ScopeFacade` that tracks all reads and writes:
+With `typedFlowChart<T>()`, stage functions receive a `TypedScope<T>` proxy. All reads and writes use typed property access:
 
 ```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 }>();
+interface LoanState {
+  creditTier: string;
+  amount: number;
+  customer: { name: string; address: { zip: string } };
+  tags: string[];
+  approved?: boolean;
+}
+
+const myStage = (scope: TypedScope<LoanState>) => {
+  // Typed writes (tracked — appear in narrative)
+  scope.creditTier = 'A';
+  scope.amount = 50000;
+
+  // Deep write (auto-delegates to updateValue)
+  scope.customer.address.zip = '90210';
+
+  // Array copy-on-write
+  scope.tags.push('vip');
+
+  // Optional fields
+  scope.approved = true;
+
+  // $-prefixed escape hatches for non-state operations
+  scope.$debug('checkpoint', { step: 1 });
+  scope.$metric('latency', 42);
+  const args = scope.$getArgs<{ requestId: string }>();
+  const env = scope.$getEnv();
+  scope.$break();  // stop pipeline execution early
 };
 ```
 
-**IMPORTANT:** `getValue`/`setValue` are tracked and produce narrative. `getArgs()` returns frozen readonly input and is NOT tracked.
+**Three access tiers:**
+- **Typed properties** (`scope.amount = 50000`) — mutable shared state, tracked in narrative
+- **`$getArgs()`** — frozen business input from `run({ input })`, NOT tracked
+- **`$getEnv()`** — frozen infrastructure context from `run({ env })`, NOT tracked. Returns `ExecutionEnv { signal?, timeoutMs?, traceId? }`. Auto-inherited by subflows. Closed type.
+
+### Decider Branches with decide() (Single-Choice Conditional)
 
-### Decider Branches (Single-Choice Conditional)
+Use `decide()` for structured decision evidence capture. It auto-records which values led to the decision in the narrative.
 
 ```typescript
-const chart = flowChart('Intake', intakeFn, 'intake')
+import { decide } from 'footprintjs';
+
+interface RiskState {
+  creditScore: number;
+  dti: number;
+  riskTier: string;
+}
+
+const chart = typedFlowChart<RiskState>('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';
+    // decide() captures filter evidence automatically
+    return decide(scope, [
+      { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'low-risk', label: 'Good credit' },
+      { when: (s) => s.creditScore > 600, then: 'medium-risk', label: 'Marginal credit' },
+    ], 'high-risk');
+    // Narrative: "It evaluated Rule 0 'Good credit': creditScore 750 gt 700, and chose low-risk."
   }, 'assess-risk', 'Evaluate risk and route accordingly')
     .addFunctionBranch('high-risk', 'RejectApplication', rejectFn, 'Reject due to high risk')
+    .addFunctionBranch('medium-risk', 'ManualReview', reviewFn, 'Send to manual review')
     .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.
+The `decide()` function accepts two `when` formats:
+- **Filter format:** `{ creditScore: { gt: 700 } }` — declarative, auto-captures evidence
+- **Function format:** `(s) => s.creditScore > 600` — arbitrary logic with optional `label`
+
+The decider function **returns a branch ID string**. The engine matches it to a child and executes that branch. The decision and its evidence are recorded in the narrative.
+
+### Selector Branches with select() (Multi-Choice Fan-Out)
 
-### Selector Branches (Multi-Choice Fan-Out)
+Use `select()` for structured multi-choice evidence capture:
 
 ```typescript
-const chart = flowChart('Intake', intakeFn, 'intake')
+import { select } from 'footprintjs';
+
+interface CheckState {
+  needsCredit: boolean;
+  needsIdentity: boolean;
+}
+
+const chart = typedFlowChart<CheckState>('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;
+    return select(scope, [
+      { when: { needsCredit: { eq: true } }, then: 'credit-check', label: 'Credit required' },
+      { when: { needsIdentity: { eq: true } }, then: 'identity-check', label: 'Identity required' },
+    ]);
+    // Returns array of matching branch IDs
   }, 'select-checks')
     .addFunctionBranch('credit-check', 'CreditCheck', creditFn)
     .addFunctionBranch('identity-check', 'IdentityCheck', identityFn)
@@ -151,13 +196,13 @@ builder.addListOfFunction([
 
 ```typescript
 // Build a reusable sub-pipeline
-const creditSubflow = flowChart('PullReport', pullReportFn, 'pull-report')
+const creditSubflow = typedFlowChart<CreditState>('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') }),
+  inputMapper: (parentScope) => ({ ssn: parentScope.ssn }),
   outputMapper: (subOut, parentScope) => ({ creditScore: subOut.score }),
 });
 
@@ -171,11 +216,15 @@ builder.addDeciderFunction('Route', routerFn, 'route')
 ### Loops
 
 ```typescript
+interface RetryState {
+  attempts: number;
+  paymentResult?: string;
+}
+
 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
+    scope.attempts = (scope.attempts ?? 0) + 1;
+    if (scope.attempts >= 3) return; // exit loop by not looping
   }, 'retry-payment')
   .loopTo('retry-payment'); // back-edge to this stage's ID
 ```
@@ -206,30 +255,36 @@ const mermaid = builder.toMermaid(); // Mermaid diagram string
 ## FlowChartExecutor API
 
 ```typescript
-import { FlowChartExecutor } from 'footprintjs';
+import { FlowChartExecutor, createTypedScopeFactory } from 'footprintjs';
 
-const executor = new FlowChartExecutor(chart);
+interface AppState {
+  applicantName: string;
+  income: number;
+  riskTier?: string;
+  decision?: string;
+}
 
-// Run with input
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<AppState>());
+
+// Run with input and optional execution environment
 const result = await executor.run({
   input: { applicantName: 'Bob', income: 42000 },
-  timeoutMs: 5000,    // optional auto-abort
-  signal: controller.signal, // optional AbortSignal
+  env: { traceId: 'req-123', timeoutMs: 5000 },
 });
 
 // Get narrative (combined flow + data operations)
 const narrative: string[] = executor.getNarrative();
 // ["Stage 1: The process began with ReceiveApplication.",
-//  "  Step 1: Write app = {applicantName, income, ...}",
+//  "  Step 1: Write applicantName = \"Bob\"",
 //  "Stage 2: Next, it moved on to AssessRisk.",
-//  "  Step 1: Read app = ...",
+//  "  Step 1: Read income = 42000",
 //  "  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: 'step', text: 'Write applicantName = ...', depth: 1, stageName: 'ReceiveApplication', stepNumber: 1 },
 //  { type: 'condition', text: '...', depth: 0 }]
 
 // Full memory snapshot
@@ -248,18 +303,20 @@ const flowOnly: string[] = executor.getFlowNarrative();
 
 ### Scope Recorders (data operations)
 
-Attached to `ScopeFacade`, fire during `getValue()`/`setValue()`:
+Fire during typed property access (reads/writes). Attach via `executor.attachRecorder()`:
 
 ```typescript
-import { MetricRecorder, DebugRecorder, NarrativeRecorder } from 'footprintjs';
+import { MetricRecorder, DebugRecorder } 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);
+// Attach to executor (one-liner, no custom scopeFactory needed)
+executor.attachRecorder(metrics);
+executor.attachRecorder(debug);
+
+await executor.run({ input: data });
 
 // After execution
 metrics.getSummary(); // { totalReads: 12, totalWrites: 8, stages: {...} }
@@ -299,6 +356,10 @@ const myRecorder: FlowRecorder = {
   },
   onDecision(event: FlowDecisionEvent) {
     console.log(`Decision at ${event.stageName}: chose ${event.chosen}`);
+    // event.evidence available when using decide()
+    if (event.evidence) {
+      console.log(`Evidence: ${JSON.stringify(event.evidence)}`);
+    }
   },
   clear() {
     // Reset state before each run
@@ -370,15 +431,16 @@ 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)
+2. Recorder.onRead              — each typed property read (DURING execution)
+3. Recorder.onWrite             — each typed property write (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.onDecision   — if this was a decider (carries evidence from decide())
    OR FlowRecorder.onFork       — if children execute in parallel
+   OR FlowRecorder.onSelected   — if this was a selector (carries evidence from select())
 ```
 
 **This ordering is what makes inline collection work.** Scope events buffer during execution, flow events trigger the flush.
@@ -388,10 +450,13 @@ When a stage executes, events fire in this exact order:
 ## 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.
+2. **Don't use `getValue()`/`setValue()` in TypedScope stages.** Use typed property access (`scope.amount = 50000`). The old ScopeFacade API is internal only.
+3. **Don't use `$`-prefixed state keys** (e.g., `$break` as a property name) — they collide with TypedScope's `$`-prefixed escape hatches (`$getArgs`, `$getEnv`, `$break`, `$debug`, `$metric`).
+4. **Never use `CombinedNarrativeBuilder`** — it's deprecated. Use `CombinedNarrativeRecorder` (auto-attached by `setEnableNarrative()`).
+5. **Don't extract a shared base class** for Recorder and FlowRecorder. They look similar but serve different layers. Two instances = coincidence.
+6. **Don't call `$getArgs()` for tracked data.** `$getArgs()` returns frozen readonly input. Use typed scope properties for state that should appear in the narrative.
+7. **Don't put infrastructure data in `$getArgs()`.** Use `$getEnv()` via `run({ env })` for signals, timeouts, and trace IDs.
+8. **Don't create scope recorders manually** unless building a custom recorder. `setEnableNarrative()` handles everything.
 
 ---
 
@@ -401,13 +466,17 @@ When a stage executes, events fire in this exact order:
 src/lib/
 ├── memory/    → SharedMemory, StageContext, TransactionBuffer, EventLog (foundation)
 ├── schema/    → detectSchema, validate, InputValidationError (foundation)
-├── builder/   → FlowChartBuilder, flowChart(), DeciderList, SelectorFnList (standalone)
+├── builder/   → FlowChartBuilder, flowChart(), typedFlowChart(), DeciderList, SelectorFnList (standalone)
 ├── scope/     → ScopeFacade, recorders/, providers/, protection/ (depends: memory)
-├── engine/    → FlowchartTraverser, handlers/, narrative/ (depends: memory, scope, builder)
+├── reactive/  → TypedScope<T> deep Proxy, typed property access, $-methods, cycle-safe (depends: scope)
+├── decide/    → decide()/select() decision evidence capture, filter + function when formats (depends: scope)
+├── engine/    → FlowchartTraverser, handlers/, narrative/ (depends: memory, scope, reactive, builder)
 ├── runner/    → FlowChartExecutor, ExecutionRuntime (depends: engine, scope, schema)
 └── contract/  → defineContract, generateOpenAPI (depends: schema)
 ```
 
+Dependency DAG: `memory <- scope <- reactive <- engine <- runner`, `schema <- engine`, `builder (standalone) -> engine`, `contract <- schema`, `decide -> scope`
+
 Two entry points:
 - `import { ... } from 'footprintjs'` — public API
 - `import { ... } from 'footprintjs/advanced'` — internals (memory, traverser, handlers)
@@ -416,21 +485,50 @@ Two entry points:
 
 ## Common Patterns
 
-### Pipeline with decision + narrative
+### Pipeline with decide() + narrative
 
 ```typescript
-const chart = flowChart('Receive', receiveFn, 'receive')
-  .addFunction('Analyze', analyzeFn, 'analyze')
-  .addDeciderFunction('Decide', decideFn, 'decide')
-    .addFunctionBranch('approve', 'Approve', approveFn)
-    .addFunctionBranch('reject', 'Reject', rejectFn)
+import { typedFlowChart, createTypedScopeFactory, FlowChartExecutor, decide } from 'footprintjs';
+
+interface LoanState {
+  applicantName: string;
+  income: number;
+  creditScore: number;
+  dti: number;
+  decision?: string;
+  reason?: string;
+}
+
+const chart = typedFlowChart<LoanState>('Receive', (scope) => {
+    const args = scope.$getArgs<{ applicantName: string; income: number }>();
+    scope.applicantName = args.applicantName;
+    scope.income = args.income;
+  }, 'receive')
+  .addFunction('Analyze', (scope) => {
+    scope.creditScore = 750;  // from credit bureau
+    scope.dti = 0.35;         // computed
+  }, 'analyze')
+  .addDeciderFunction('Decide', (scope) => {
+    return decide(scope, [
+      { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approve', label: 'Good credit' },
+      { when: (s) => s.creditScore > 600, then: 'approve', label: 'Marginal but acceptable' },
+    ], 'reject');
+  }, 'decide')
+    .addFunctionBranch('approve', 'Approve', (scope) => {
+      scope.decision = 'approved';
+      scope.reason = 'Meets credit criteria';
+    })
+    .addFunctionBranch('reject', 'Reject', (scope) => {
+      scope.decision = 'rejected';
+      scope.reason = 'Does not meet credit criteria';
+    })
     .setDefault('reject')
     .end()
   .setEnableNarrative()
   .build();
 
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input: data });
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<LoanState>());
+await executor.run({ input: { applicantName: 'Bob', income: 42000 } });
 const trace = executor.getNarrative();
 // Feed trace to LLM for grounded explanations
 ```
@@ -438,14 +536,25 @@ const trace = executor.getNarrative();
 ### Subflow with input/output mapping
 
 ```typescript
-const subflow = flowChart('SubStart', subStartFn, 'sub-start')
+interface SubState {
+  ssn: string;
+  score: number;
+}
+
+interface MainState {
+  ssn: string;
+  parentKey: string;
+  creditScore?: number;
+}
+
+const subflow = typedFlowChart<SubState>('SubStart', subStartFn, 'sub-start')
   .addFunction('SubProcess', subProcessFn, 'sub-process')
   .build();
 
-const main = flowChart('Main', mainFn, 'main')
+const main = typedFlowChart<MainState>('Main', mainFn, 'main')
   .addSubFlowChartNext('my-subflow', subflow, 'SubflowMount', {
-    inputMapper: (scope) => ({ key: scope.getValue('parentKey') }),
-    outputMapper: (subOut) => ({ result: subOut.processed }),
+    inputMapper: (scope) => ({ ssn: scope.ssn }),
+    outputMapper: (subOut) => ({ creditScore: subOut.score }),
   })
   .build();
 ```
@@ -453,8 +562,12 @@ const main = flowChart('Main', mainFn, 'main')
 ### Attach multiple recorders
 
 ```typescript
-import { ManifestFlowRecorder, MilestoneNarrativeFlowRecorder } from 'footprintjs';
+import { ManifestFlowRecorder, MilestoneNarrativeFlowRecorder, MetricRecorder } from 'footprintjs';
+
+// Scope recorder (data ops) — via executor.attachRecorder()
+executor.attachRecorder(new MetricRecorder());
 
+// Flow recorders (control flow) — via executor.attachFlowRecorder()
 executor.attachFlowRecorder(new ManifestFlowRecorder());
 executor.attachFlowRecorder(new MilestoneNarrativeFlowRecorder());
 

package/ai-instructions/clinerules

@@ -1,4 +1,4 @@
-# footprint.js — Cline Rules
+# footprint.js
 
 This is the footprint.js library — the flowchart pattern for backend code. Self-explainable systems that AI can reason about.
 
@@ -12,8 +12,10 @@ This is the footprint.js library — the flowchart pattern for backend code. Sel
 src/lib/
 ├── memory/    → Transactional state (SharedMemory, StageContext, TransactionBuffer)
 ├── schema/    → Validation (Zod optional, duck-typed)
-├── builder/   → Fluent DSL (FlowChartBuilder, flowChart())
+├── builder/   → Fluent DSL (FlowChartBuilder, flowChart(), typedFlowChart())
 ├── scope/     → Per-stage facades + recorders + providers
+├── reactive/  → TypedScope<T> deep Proxy (typed property access, $-methods)
+├── decide/    → decide()/select() decision evidence capture
 ├── engine/    → DFS traversal + narrative + handlers
 ├── runner/    → FlowChartExecutor
 └── contract/  → I/O schema + OpenAPI
@@ -21,46 +23,82 @@ src/lib/
 
 Entry points: `footprintjs` (public) and `footprintjs/advanced` (internals).
 
-## Builder API
+## Key API — TypedScope (Recommended)
 
 ```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)
+import { typedFlowChart, createTypedScopeFactory, FlowChartExecutor, decide } from 'footprintjs';
+
+interface State {
+  creditScore: number;
+  riskTier: string;
+  decision?: string;
+}
+
+const chart = typedFlowChart<State>('Intake', async (scope) => {
+  scope.creditScore = 750;          // typed write (no setValue needed)
+  scope.riskTier = 'low';           // typed write
+}, 'intake')
   .setEnableNarrative()
-  .build() / .toSpec() / .toMermaid()
+  .addDeciderFunction('Route', (scope) => {
+    return decide(scope, [
+      { when: { riskTier: { eq: 'low' } }, then: 'approved', label: 'Low risk' },
+    ], 'rejected');
+  }, 'route', 'Route based on risk')
+    .addFunctionBranch('approved', 'Approve', async (scope) => {
+      scope.decision = 'Approved';
+    })
+    .addFunctionBranch('rejected', 'Reject', async (scope) => {
+      scope.decision = 'Rejected';
+    })
+    .setDefault('rejected')
+    .end()
+  .build();
+
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<State>());
+await executor.run();
+executor.getNarrative();  // causal trace with decision evidence
 ```
 
-## Stage Functions
+### TypedScope $-methods (escape hatches)
 
 ```typescript
-(scope: ScopeFacade, breakPipeline: () => void, streamCallback?: StreamCallback) => void | Promise<void>
+scope.$getArgs<T>()        // frozen readonly input
+scope.$getEnv()            // execution environment (signal, timeoutMs, traceId)
+scope.$break()             // stop pipeline
+scope.$debug(key, value)   // debug info
+scope.$metric(name, value) // metrics
 ```
 
-## ScopeFacade
+### decide() / select()
 
 ```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)
+// Filter syntax — captures operators + thresholds
+decide(scope, [
+  { when: { creditScore: { gt: 700 }, dti: { lt: 0.43 } }, then: 'approved', label: 'Good credit' },
+], 'rejected');
+
+// Function syntax — captures which keys were read
+decide(scope, [
+  { when: (s) => s.creditScore > 700, then: 'approved' },
+], 'rejected');
+
+// select() — all matching branches (not first-match)
+select(scope, [
+  { when: { glucose: { gt: 100 } }, then: 'diabetes' },
+  { when: { bmi: { gt: 30 } }, then: 'obesity' },
+]);
 ```
 
-## Executor
+### Executor
 
 ```typescript
-const executor = new FlowChartExecutor(chart);
-await executor.run({ input, timeoutMs?, signal? });
-executor.getNarrative()            // combined flow + data
-executor.getNarrativeEntries()     // structured entries
+const executor = new FlowChartExecutor(chart, createTypedScopeFactory<State>());
+await executor.run({ input, env: { traceId: 'req-123' } });
+executor.getNarrative()            // string[]
+executor.getNarrativeEntries()     // CombinedNarrativeEntry[]
 executor.getSnapshot()             // memory state
-executor.attachFlowRecorder(r)     // plug flow observer
+executor.attachRecorder(recorder)  // scope observer
+executor.attachFlowRecorder(r)     // flow observer
 executor.setRedactionPolicy({ keys, patterns, fields })
 ```
 
@@ -68,12 +106,14 @@ executor.setRedactionPolicy({ keys, patterns, fields })
 
 - **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()`
+- 8 built-in FlowRecorder strategies
+- `setEnableNarrative()` auto-attaches `CombinedNarrativeRecorder`
 
 ## Rules
 
+- Use `typedFlowChart<T>()` + `createTypedScopeFactory<T>()` (not flowChart + ScopeFacade)
+- Use `decide()` / `select()` in decider/selector functions
+- Use typed property access (not getValue/setValue)
+- Use `$getArgs()` for input, `$getEnv()` for environment
 - 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
+- `setEnableNarrative()` is all you need for narrative setup