@probelabs/visor 0.1.124 → 0.1.126

package/dist/docs/custom-tools.md

@@ -141,14 +141,39 @@ Custom tools are designed to be fully compatible with the Model Context Protocol
 
 ## Using Custom Tools
 
-Once defined, custom tools can be used in any MCP block by setting `transport: custom`:
+### In AI Steps
+
+Use `ai_custom_tools` to expose custom tools to AI providers via an ephemeral MCP server. See [AI Custom Tools](./ai-custom-tools.md) for complete documentation.
+
+```yaml
+steps:
+  ai-review:
+    type: ai
+    prompt: |
+      Use the available tools to analyze the code for issues.
+    ai_custom_tools:
+      - grep-pattern
+      - file-stats
+    ai:
+      provider: anthropic
+      model: claude-3-5-sonnet-20241022
+```
+
+### In MCP Steps
+
+Custom tools can also be used directly in MCP steps by setting `transport: custom`. The MCP provider supports four transport types:
+
+- `stdio` - Spawn an MCP server as a subprocess (default)
+- `sse` - Connect to an MCP server via Server-Sent Events (legacy)
+- `http` - Connect via Streamable HTTP transport
+- `custom` - Execute YAML-defined custom tools directly
 
 ```yaml
 steps:
   my-check:
     type: mcp
-    transport: custom              # Use custom transport
-    method: my-tool                 # Tool name
+    transport: custom              # Use custom transport for YAML-defined tools
+    method: my-tool                 # Tool name (must be defined in tools: section)
     methodArgs:                     # Tool arguments
       param1: "value1"
       param2: 42
@@ -160,17 +185,23 @@ Tools have access to a rich template context through Liquid templates:
 
 ### In `exec` and `stdin`:
 - `{{ args }}` - The arguments passed to the tool
-- `{{ pr }}` - Pull request information (number, title, author, etc.)
+- `{{ input }}` - Alias for `args` (same object)
+- `{{ pr }}` - Pull request information:
+  - `{{ pr.number }}` - PR number
+  - `{{ pr.title }}` - PR title
+  - `{{ pr.author }}` - PR author
+  - `{{ pr.branch }}` - Head branch name
+  - `{{ pr.base }}` - Base branch name
 - `{{ files }}` - List of files in the PR
 - `{{ outputs }}` - Outputs from previous checks
 - `{{ env }}` - Environment variables
 
 ### In `transform` and `transform_js`:
 - All of the above, plus:
-- `{{ output }}` - The raw command output
-- `{{ stdout }}` - Standard output
-- `{{ stderr }}` - Standard error
-- `{{ exitCode }}` - Command exit code
+- `{{ output }}` - The raw command output (or parsed JSON if `parseJson: true`)
+- `{{ stdout }}` - Standard output (raw string)
+- `{{ stderr }}` - Standard error (raw string)
+- `{{ exitCode }}` - Command exit code (number)
 
 ## Examples
 

package/dist/docs/dashboards/README.md

@@ -1,23 +1,37 @@
-Dashboards for Visor Telemetry
-==============================
+# Dashboards for Visor Telemetry
 
 This folder contains example Grafana dashboards to visualize Visor traces and metrics exported via OpenTelemetry (Tempo + Prometheus).
 
-What’s included
-- grafana-visor-overview.json — Run/Check overview: durations, issue counts by severity, recent runs.
-- grafana-visor-diagrams.json — Diagram telemetry (syntax pass rate, average score) if you enable diagram attributes.
-
-Setup
-1) Deploy Grafana + Tempo + Prometheus (or Grafana Cloud).
-2) Configure your OTel Collector to receive OTLP traces/metrics and forward to Tempo/Prometheus.
-3) Enable telemetry in Visor CI:
-   - VISOR_TELEMETRY_ENABLED=true
-   - VISOR_TELEMETRY_SINK=otlp
-   - OTEL_EXPORTER_OTLP_ENDPOINT=https://collector.example.com
-   - OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer <token>
-4) Import the JSON dashboards into Grafana and set the Tempo + Prometheus data sources.
-
-Notes
-- Spans appear in Tempo’s Explore/Trace view (service.name=visor).
-- Metrics are emitted when OTLP metrics exporter is configured; see docs/telemetry-tracing-rfc.md for details.
+## What's Included
+
+- **grafana-visor-overview.json** - Run/Check overview dashboard with:
+  - Check duration histogram (95th percentile)
+  - Issues by severity rate panel
+- **grafana-visor-diagrams.json** - Diagram telemetry dashboard with:
+  - Diagram blocks by origin (content vs issue)
+
+## Setup
+
+1. Deploy Grafana + Tempo + Prometheus (or Grafana Cloud).
+2. Configure your OTel Collector to receive OTLP traces/metrics and forward to Tempo/Prometheus.
+3. Enable telemetry in Visor CI:
+   ```bash
+   export VISOR_TELEMETRY_ENABLED=true
+   export VISOR_TELEMETRY_SINK=otlp
+   export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://collector.example.com/v1/traces
+   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
+   ```
+4. Import the JSON dashboards into Grafana.
+5. Update the data source UIDs in each dashboard to match your Tempo and Prometheus data sources (replace `PROM_DS` with your Prometheus data source UID).
+
+## Notes
+
+- Spans appear in Tempo's Explore/Trace view (service.name=visor).
+- Metrics are emitted when the OTLP metrics exporter is configured.
+- The dashboards use placeholder data source UIDs (`PROM_DS`) that need to be updated after import.
+
+## Related Documentation
+
+- [Telemetry Setup Guide](../telemetry-setup.md) - Complete setup instructions for enabling telemetry
+- [Telemetry RFC](../telemetry-tracing-rfc.md) - Design rationale and architecture details
 

package/dist/docs/debug-visualizer-progress.md

@@ -1,7 +1,10 @@
 # Debug Visualizer Implementation Progress
 
+> **Note**: This is a historical progress tracking document from the debug visualizer RFC implementation.
+> The implementation is largely complete (Milestones 1-5). See [debug-visualizer.md](debug-visualizer.md) for current usage documentation.
+
 **Last Updated**: 2025-10-17
-**Status**: 🟢 **5 of 6 Milestones Complete (83%)**
+**Status**: 5 of 6 Milestones Complete (83%)
 
 ---
 
@@ -111,7 +114,7 @@ From `tests/e2e/state-capture-e2e.test.ts`:
 - 🔄 At least one `state.snapshot` event is present (pending snapshot integration)
 - ✅ All tests pass
 
-**Full Details**: [MILESTONE1-COMPLETE.md](../MILESTONE1-COMPLETE.md)
+**Full Details**: See milestone details below.
 
 ---
 
@@ -158,7 +161,7 @@ From `tests/e2e/state-capture-e2e.test.ts`:
 - ✅ Timeline events are in chronological order
 - ✅ All tests pass (26/26 = 100%)
 
-**Full Details**: [MILESTONE2-COMPLETE.md](../MILESTONE2-COMPLETE.md)
+**Full Details**: See milestone details below.
 
 ---
 
@@ -205,11 +208,10 @@ From `tests/e2e/state-capture-e2e.test.ts`:
 - **Output**: Check results and outputs
 - **Events**: All span events with timestamps and attributes
 
-✅ **Created testing documentation** (`tests/fixtures/traces/README.md`)
-- Manual testing guide
-- Feature checklist
-- Browser compatibility notes
-- Expected behavior documentation
+**Testing with fixtures** (`tests/fixtures/traces/`)
+- `sample-trace.ndjson` - Complete execution trace
+- `error-trace.ndjson` - Error scenario trace
+- `empty-trace.ndjson` - Empty file for error handling
 
 ✅ **Embedded trace reader**
 - Inline implementation of all trace-reader functions
@@ -237,7 +239,7 @@ From `tests/e2e/state-capture-e2e.test.ts`:
 - ✅ Loading spinner
 - ✅ Responsive design
 
-**Full Details**: [MILESTONE3-COMPLETE.md](../MILESTONE3-COMPLETE.md)
+**Full Details**: See milestone details below.
 
 ---
 
@@ -431,20 +433,19 @@ Build completed successfully:
 ### Next Steps
 
 Ready to proceed to Milestone 5 (Time-Travel Debugging) or Milestone 6 (CLI Viewer).
-**Full Details**: [MILESTONE4-INTEGRATION-GUIDE.md](../MILESTONE4-INTEGRATION-GUIDE.md)
 
 ---
 
 ## Overall Progress Summary
 
-**Milestones Completed**: 4 of 6 (67%)
+**Milestones Completed**: 5 of 6 (83%)
 
 ```
 Milestone 1: State Capture Foundation     ████████████████████ 100% ✅
 Milestone 2: Trace File Reader           ████████████████████ 100% ✅
 Milestone 3: Static UI Viewer            ████████████████████ 100% ✅
-Milestone 4: Live Streaming Server       ████████████████████ 100% ✅ JUST COMPLETED!
-Milestone 5: Time-Travel Debugging       ░░░░░░░░░░░░░░░░░░░░   0% 📋
+Milestone 4: Live Streaming Server       ████████████████████ 100% ✅
+Milestone 5: Time-Travel Debugging       ████████████████████ 100% ✅
 Milestone 6: Production Ready            ░░░░░░░░░░░░░░░░░░░░   0% 📋
 ```
 

package/dist/docs/debug-visualizer-rfc.md

@@ -399,7 +399,6 @@ cat output/traces/run-*.ndjson | jq '.attributes | select(."visor.check.input.co
 - ✅ `tests/unit/telemetry/state-capture.test.ts` (246 lines)
 - ✅ `tests/e2e/state-capture-e2e.test.ts` (195 lines)
 - ✅ Integration in 3 providers + execution engine
-- ✅ [MILESTONE1-COMPLETE.md](../MILESTONE1-COMPLETE.md) - Full summary
 
 ---
 
@@ -562,8 +561,6 @@ open output/traces/index.html
 - ✅ `src/telemetry/opentelemetry.ts` (updated) - Debug exporter support
 - ✅ `src/debug-visualizer/ui/index.html` (updated) - WebSocket client
 - ✅ `package.json` (updated) - Dependencies and build script
-- ✅ `MILESTONE4-INTEGRATION-GUIDE.md` - Integration documentation
-- ✅ `MILESTONE4-COMPLETE.md` - Completion summary
 
 **Dependencies Installed**:
 - ✅ ws@^8.18.3
@@ -602,14 +599,18 @@ open "output/traces/index.html?trace=run-2025-10-17.ndjson"
 # 7. Arrow keys step forward/backward
 ```
 
-**Success Criteria**:
-- [ ] Timeline scrubber updates graph to show state at selected time
-- [ ] Play button animates execution from start to finish
-- [ ] Can pause at any point and inspect state
-- [ ] Diff view highlights changes between timepoints
-- [ ] State snapshot markers are clickable
-- [ ] Keyboard shortcuts work correctly
-- [ ] Performance: smooth scrubbing with 1000+ spans
+**Success Criteria**: ✅ ALL MET
+- [x] Timeline scrubber updates graph to show state at selected time
+- [x] Play button animates execution from start to finish
+- [x] Can pause at any point and inspect state
+- [x] Diff view highlights changes between timepoints
+- [x] State snapshot markers are clickable
+- [x] Keyboard shortcuts work correctly
+- [x] Performance: smooth scrubbing with 1000+ spans
+
+**Deliverables**:
+- ✅ `src/debug-visualizer/ui/index.html` (updated) - Timeline component, styles, and JavaScript engine
+- ✅ `tests/unit/debug-visualizer/time-travel.test.ts` - 17 comprehensive unit tests
 
 ---
 
@@ -662,10 +663,10 @@ The debug visualizer is complete when:
 2. [x] **Data Layer**: Can parse traces and rebuild execution tree ✅ M2 DONE
 3. [x] **Visualization**: Can see execution graph in browser ✅ M3 DONE
 4. [x] **Real-time**: Can stream live execution ✅ M4 DONE
-5. [ ] **Time-Travel**: Can scrub timeline and see historical state (M5)
+5. [x] **Time-Travel**: Can scrub timeline and see historical state ✅ M5 DONE
 6. [ ] **Production**: Polished UI with docs and tests (M6)
 
-### Current Status: 🟢 Milestone 4 of 6 Complete (67%)
+### Current Status: 🟢 Milestone 5 of 6 Complete (83%)
 
 ## Open Questions
 

package/dist/docs/debug-visualizer.md

@@ -5,9 +5,10 @@ The Debug Visualizer is a lightweight HTTP server that streams OpenTelemetry spa
 ## Quick Start
 
 - Start the CLI with the debug server:
-  - `node dist/index.js --config <path/to/.visor.yaml> --mode cli --output json --debug-server --debug-port 3456`
+  - `visor --config <path/to/.visor.yaml> --output json --debug-server --debug-port 3456`
+  - Or using the development build: `node dist/cli-main.js --config <path/to/.visor.yaml> --output json --debug-server --debug-port 3456`
   - The server starts at `http://localhost:3456`. In headless CI, set `VISOR_NOBROWSER=true` to skip auto‑open.
-- Click “Start Execution” in the UI or POST `POST /api/start` (see below) to begin.
+- Click "Start Execution" in the UI or POST `/api/start` (see below) to begin.
 
 ## Control Endpoints
 
@@ -56,6 +57,23 @@ The Debug Visualizer is a lightweight HTTP server that streams OpenTelemetry spa
 }
 ```
 
+### Config shape (`GET /api/config`)
+```json
+{
+  "config": { /* loaded configuration object */ },
+  "timestamp": "2025-01-01T00:00:00.000Z"
+}
+```
+
+### Results shape (`GET /api/results`)
+```json
+{
+  "results": { /* check results by check name */ },
+  "timestamp": "2025-01-01T00:00:00.000Z",
+  "executionState": "stopped"
+}
+```
+
 ## Pause/Stop Semantics
 
 The engine checks a “pause gate” at key scheduling points:
@@ -81,14 +99,14 @@ Effects:
 ## CLI Examples
 
 - Start server headless on port 40000 and begin automatically from script:
-  - `VISOR_NOBROWSER=true node dist/index.js --config .visor.yaml --mode cli --output json --debug-server --debug-port 40000`
+  - `VISOR_NOBROWSER=true visor --config .visor.yaml --output json --debug-server --debug-port 40000`
   - Then: `curl -sSf -X POST http://localhost:40000/api/start`.
 - Pause/Resume/Stop from a terminal:
   - `curl -sSf -X POST http://localhost:40000/api/pause`
   - `curl -sSf -X POST http://localhost:40000/api/resume`
   - `curl -sSf -X POST http://localhost:40000/api/stop`
 - Inspect spans/status:
-  - `curl -sSf http://localhost:40000/api/status | jq`  
+  - `curl -sSf http://localhost:40000/api/status | jq`
   - `curl -sSf http://localhost:40000/api/spans | jq '.total'`
 
 ## Spans & State Capture
@@ -109,6 +127,13 @@ You can parse NDJSON via the built‑in trace reader (`src/debug-visualizer/trac
 
 ## Troubleshooting
 
-- Server started but CLI doesn’t proceed: send `POST /api/start` or set a start timeout with `VISOR_DEBUG_START_TIMEOUT_MS`.
+- Server started but CLI doesn't proceed: send `POST /api/start` or set a start timeout with `VISOR_DEBUG_START_TIMEOUT_MS`.
 - No spans in file: confirm `VISOR_TELEMETRY_ENABLED=true` and `VISOR_TELEMETRY_SINK=file`. Check `VISOR_TRACE_DIR` exists.
 - Duplicate OpenTelemetry context warning: benign; initialization is guarded, but concurrent runs can still log a warning.
+
+## Related Documentation
+
+- [Debugging Guide](./debugging.md) — Comprehensive debugging techniques and tools
+- [Telemetry Setup](./telemetry-setup.md) — Configuring OpenTelemetry tracing and metrics
+- [Engine Pause/Resume RFC](./engine-pause-resume-rfc.md) — Design rationale for pause/resume semantics
+- [Debug Visualizer RFC](./debug-visualizer-rfc.md) — Original design specification

package/dist/docs/debugging.md

@@ -10,6 +10,8 @@ This guide provides comprehensive debugging techniques and tools to help trouble
 - [Common Debugging Patterns](#common-debugging-patterns)
 - [Author Permission Functions](#author-permission-functions)
 - [Troubleshooting Tips](#troubleshooting-tips)
+- [Tracing with OpenTelemetry](#tracing-with-opentelemetry)
+- [Debug Visualizer](#debug-visualizer)
 
 ## Debug Mode
 
@@ -423,19 +425,24 @@ steps:
 Set these environment variables for additional debug output:
 
 ```bash
-# Show all debug output
+# Enable verbose debug output (used in diff processing and other internals)
 export DEBUG=1
+# or
+export VERBOSE=1
 
-# Show Liquid template rendering
-export DEBUG_TEMPLATES=1
+# Enable telemetry and tracing
+export VISOR_TELEMETRY_ENABLED=true
+export VISOR_TELEMETRY_SINK=file  # or otlp, console
 
-# Show command execution details
-export DEBUG_COMMANDS=1
+# Set trace output directory
+export VISOR_TRACE_DIR=output/traces
 
-# Show dependency resolution
-export DEBUG_DEPS=1
+# For headless/CI environments (skip auto-opening browser)
+export VISOR_NOBROWSER=true
 ```
 
+See [Telemetry Setup](./telemetry-setup.md) for detailed configuration of tracing and metrics.
+
 ## Common Issues and Solutions
 
 ### Issue: "outputs is undefined"
@@ -628,9 +635,67 @@ steps:
       outputs["security-scan"].criticalIssues === 0
 ```
 
+## Tracing with OpenTelemetry
+
+Visor supports OpenTelemetry tracing for deep execution visibility. Enable tracing to see:
+
+- **Root span**: `visor.run` - one per CLI/Slack execution
+- **State spans**: `engine.state.*` with `wave`, `wave_kind`, `session_id` attributes
+- **Check spans**: `visor.check.<checkId>` with `visor.check.id`, `visor.check.type`, `visor.foreach.index` (for map fanout)
+- **Routing decisions**: `visor.routing` events with `trigger`, `action`, `source`, `target`, `scope`, `goto_event`
+- **Wave visibility**: `engine.state.level_dispatch` includes `level_size` and `level_checks_preview`
+
+### Quick Start with Jaeger
+
+```bash
+# Start Jaeger locally
+docker run -d --name jaeger \
+  -p 16686:16686 \
+  -p 4318:4318 \
+  jaegertracing/all-in-one:latest
+
+# Run Visor with tracing enabled
+VISOR_TELEMETRY_ENABLED=true \
+VISOR_TELEMETRY_SINK=otlp \
+OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces \
+visor --config .visor.yaml
+
+# View traces at http://localhost:16686
+```
+
+For complete tracing setup and configuration, see [Telemetry Setup](./telemetry-setup.md).
+
+## Debug Visualizer
+
+Visor includes a built-in debug visualizer - a lightweight HTTP server that streams OpenTelemetry spans during execution and provides control endpoints for pause/resume/stop.
+
+### Starting the Debug Visualizer
+
+```bash
+# Start with debug server
+visor --config .visor.yaml --debug-server --debug-port 3456
+
+# For CI/headless environments
+VISOR_NOBROWSER=true visor --config .visor.yaml --debug-server --debug-port 3456
+```
+
+### Control Endpoints
+
+- `GET /api/status` - Execution state and readiness
+- `GET /api/spans` - Current in-memory spans (live view)
+- `POST /api/start` - Begin execution
+- `POST /api/pause` - Pause scheduling (in-flight work continues)
+- `POST /api/resume` - Resume scheduling
+- `POST /api/stop` - Stop scheduling new work
+- `POST /api/reset` - Clear spans and return to idle
+
+For complete debug visualizer documentation, see [Debug Visualizer](./debug-visualizer.md).
+
 ## Further Reading
 
 - [Liquid Templates Guide](./liquid-templates.md) - Template syntax and variables
 - [Command Provider Documentation](./command-provider.md) - Command execution and transforms
 - [Configuration Reference](./configuration.md) - Full configuration options
-- [GitHub Actions Integration](./github-actions.md) - CI/CD debugging
+- [Telemetry Setup](./telemetry-setup.md) - OpenTelemetry tracing and metrics
+- [Debug Visualizer](./debug-visualizer.md) - Live execution visualization
+- [Output History](./output-history.md) - Tracking outputs across loop iterations

package/dist/docs/default-output-schema.md

@@ -1,28 +1,32 @@
 # Default Output Schema and Timestamps
 
-Visor normalizes check outputs to make prompts and history handling predictable. There are exactly two modes:
+Visor adds timestamps to check outputs to make history handling predictable.
 
-1) Checks with a schema (e.g., `schema: {...}` on the check)
-- The provider's output shape is respected.
-- If the final output is an Object (map), Visor injects a `ts` field (milliseconds since epoch) if it is missing.
-- If the final output is a primitive or an array, it is passed through unchanged (no wrapping, no `ts`).
+## Timestamp Injection
 
-2) Checks without a schema
-- Visor uses a default schema: `{ text: string, ts: number }`.
-- If the provider returned a primitive (string/number/boolean), it is wrapped into `{ text, ts }`.
-- If it returned an Object, Visor injects `ts` if it is missing.
-- If it returned an array, it is passed through unchanged.
+When a check completes successfully:
+- If the output is a plain **Object** (not an array, not null), Visor injects a `ts` field (milliseconds since epoch) if it is missing.
+- If the output is a **primitive** (string, number, boolean), **array**, or **null**, it is passed through unchanged (no wrapping, no `ts`).
 
-This normalization happens after the provider returns and before outputs are recorded into `outputs` and `outputs_history`.
+This injection happens after the provider returns and before outputs are recorded into `outputs` and `outputs_history`.
 
-Why this exists
-- Prompts and templates can reliably access `.text` and `.ts` for no‑schema checks (e.g., human‑input), and can still trust custom shapes for schema’d checks.
-- `ts` allows you to sort/merge histories across steps without bespoke engines or roles.
+## Provider-Specific Defaults
 
-Practical tips
-- Human input defaults to `{ text, ts }`. In Liquid, read `outputs_history.ask[i].text` safely with a fallback: `{% if u.text %}{{ u.text }}{% else %}{{ u }}{% endif %}` for legacy mocks.
-- For schema’d AI checks, add `ts` to your schema if you want it persisted by validators; otherwise Visor will add it at runtime (not validated).
-- Arrays are passed through untouched; if you need timestamps per item, include them in your own schema.
+Some providers return structured output by default:
+- **human-input**: Returns `{ text: string, ts: number }` directly from the provider (not via central normalization).
+- **Other providers**: Return whatever their implementation produces; Visor only adds `ts` to objects.
 
-Related
-- See `docs/human-input-provider.md` for default output shape of human input.
+## Why Timestamps Exist
+
+- `ts` allows you to sort/merge histories across steps without custom logic.
+- Providers that need structured output (like human-input) implement it directly.
+
+## Practical Tips
+
+- Human input always returns `{ text, ts }`. In Liquid, access via `outputs['my-check'].text`.
+- For AI checks with custom schemas, add `ts` to your schema if you want it persisted by validators; otherwise Visor adds it at runtime (not validated).
+- Arrays are passed through untouched; if you need timestamps per item, include them in your schema.
+
+## Related
+
+- See [Human Input Provider](./human-input-provider.md) for the default output shape of human input.

package/dist/docs/dependencies.md

@@ -117,7 +117,7 @@ steps:
 ```
 
 ```yaml
-checks:
+steps:
   parse-issue:   { type: noop }
   parse-comment: { type: noop }
   triage:        { type: noop, depends_on: ["parse-issue|parse-comment"] }
@@ -132,6 +132,56 @@ Rules:
 
 Tip: When targeting a leaf in ad‑hoc runs (e.g., `visor --check final`), include one member of each pipe group explicitly (e.g., `--check a --check final`) to make intent unambiguous. In normal runs Visor computes the plan automatically from your config.
 
+### AI Session Reuse
+
+For AI checks that depend on other AI checks, you can reuse the parent's conversation session to maintain context:
+
+```yaml
+steps:
+  initial-analysis:
+    type: ai
+    prompt: "Analyze this code for issues..."
+
+  follow-up:
+    type: ai
+    depends_on: [initial-analysis]
+    reuse_ai_session: true  # Reuses session from first dependency
+    prompt: "Based on your analysis, suggest fixes..."
+```
+
+Options:
+- `reuse_ai_session: true` - Reuse session from first dependency
+- `reuse_ai_session: "step-name"` - Reuse session from specific step
+- `session_mode: 'clone'` - Copy conversation history (default)
+- `session_mode: 'append'` - Share conversation history (modifications visible to both)
+
+When using ANY-OF dependencies (`depends_on: ["a|b"]`), the session is taken from whichever dependency completes first.
+
+### Fanout Control
+
+When a step is triggered via routing (`on_success.run`, `on_fail.run`) from a forEach scope, you can control how it schedules:
+
+```yaml
+steps:
+  process-items:
+    type: command
+    forEach: true
+    exec: echo '["a","b","c"]'
+
+  validate-item:
+    depends_on: [process-items]
+    fanout: map  # Run once per forEach item (fan-out)
+
+  aggregate-results:
+    depends_on: [process-items]
+    fanout: reduce  # Run once at parent scope (aggregation)
+    # Alias: reduce: true
+```
+
+- `fanout: 'map'` - Schedule once per forEach item (fan-out behavior)
+- `fanout: 'reduce'` - Schedule a single run at parent scope (aggregation)
+- `reduce: true` - Alias for `fanout: 'reduce'`
+
 ### Error Handling
 
 - Cycle detection and missing dependency validation
@@ -145,7 +195,7 @@ When a check has `forEach: true`, it outputs an array and all its dependent chec
 ### Basic Flow
 
 ```yaml
-checks:
+steps:
   extract-items:
     type: ai
     forEach: true
@@ -167,7 +217,7 @@ checks:
 The `on_finish` hook runs **once** after all dependent checks complete all their iterations, making it perfect for aggregating results and making routing decisions:
 
 ```yaml
-checks:
+steps:
   extract-facts:
     type: ai
     forEach: true
@@ -214,33 +264,37 @@ checks:
 
 ### Accessing forEach Results
 
-Inside `on_finish` hooks, you have access to all iteration results via `outputs.history`:
+Inside `on_finish` hooks, you have access to all iteration results. The context provides these variables:
 
 ```javascript
 // In on_finish.goto_js or on_finish.run_js
-{
-  outputs: {
-    'extract-facts': [...],  // The forEach array
-    'validate-fact': [...],  // Latest results (for compatibility)
-  },
-  outputs.history: {
-    'validate-fact': [[...], ...], // ALL results from ALL iterations
-  },
-  forEach: {
-    total: 3,       // Total forEach items
-    successful: 3,  // Number of successful iterations
-    failed: 0,      // Number of failed iterations
-    items: [...]    // The forEach items array
-  }
-}
+// Available variables:
+outputs['extract-facts']           // The forEach array (latest value)
+outputs['validate-fact']           // Latest result from validate-fact
+outputs.history['validate-fact']   // ALL results from ALL iterations (array)
+outputs_history['validate-fact']   // Alias for outputs.history
+outputs_raw['extract-facts']       // Aggregate value (full array)
+
+// forEach metadata
+forEach.total        // Total forEach items
+forEach.successful   // Number of successful iterations
+forEach.failed       // Number of failed iterations
+forEach.items        // The forEach items array
+
+// Memory access
+memory.get('key', 'namespace')
+memory.set('key', value, 'namespace')
+memory.increment('key', amount, 'namespace')
 ```
 
+Note: `outputs.history` and `outputs_history` are aliases - both provide access to the full history array for each check.
+
 ### Complete Example: Multi-Dependent Aggregation
 
 The real power of `on_finish` is aggregating results from **multiple** dependent checks:
 
 ```yaml
-checks:
+steps:
   # Step 1: Extract claims from AI response
   extract-claims:
     type: ai
@@ -340,7 +394,7 @@ This is the **only way** to aggregate across multiple dependent checks in a forE
 **Example showing the difference:**
 
 ```yaml
-checks:
+steps:
   extract-items:
     type: command
     forEach: true