# Smithers Coverage Map

> Generated by `evals/_inventory/build-coverage-md.ts` from a multi-agent sweep of the codebase.
> 380 features across 59 areas · 418 candidate eval tasks · 28 features flagged UNDOCUMENTED.
> Backbone for wave generation: every feature should be reachable by at least one eval.

## Tasks by area

| Area | Features | Tasks | knowledge | authoring | ops | db-query | weak | sota |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| agent-instantiation | 0 | 8 | 0 | 8 | 0 | 0 | 8 | 0 |
| agent-interaction | 3 | 2 | 2 | 0 | 0 | 0 | 2 | 0 |
| agent-lifecycle | 2 | 1 | 0 | 1 | 0 | 0 | 1 | 0 |
| agents | 6 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| agents-runtimes | 19 | 4 | 0 | 4 | 0 | 0 | 4 | 0 |
| approvals | 4 | 2 | 2 | 0 | 0 | 0 | 2 | 0 |
| authoring | 10 | 29 | 0 | 29 | 0 | 0 | 25 | 4 |
| budget-enforcement | 3 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| built-in-tools | 5 | 6 | 0 | 6 | 0 | 0 | 6 | 0 |
| capabilities | 2 | 4 | 1 | 3 | 0 | 0 | 4 | 0 |
| cli | 25 | 20 | 4 | 7 | 9 | 0 | 18 | 2 |
| components-control-flow | 21 | 32 | 19 | 13 | 0 | 0 | 31 | 1 |
| concepts | 2 | 14 | 14 | 0 | 0 | 0 | 14 | 0 |
| configuration | 3 | 4 | 0 | 4 | 0 | 0 | 4 | 0 |
| context-api | 6 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| control-flow | 9 | 2 | 0 | 2 | 0 | 0 | 2 | 0 |
| devtools | 7 | 3 | 3 | 0 | 0 | 0 | 3 | 0 |
| diagnostics | 1 | 1 | 1 | 0 | 0 | 0 | 1 | 0 |
| docs | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| durability-model | 4 | 4 | 4 | 0 | 0 | 0 | 4 | 0 |
| evals | 8 | 12 | 4 | 6 | 0 | 0 | 11 | 1 |
| examples | 8 | 11 | 4 | 7 | 0 | 0 | 10 | 1 |
| gateway | 15 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| gateway-http-api | 0 | 4 | 2 | 2 | 0 | 0 | 4 | 0 |
| human-inbox | 2 | 4 | 0 | 0 | 4 | 0 | 4 | 0 |
| infrastructure | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| integrations | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| knowledge | 0 | 1 | 1 | 0 | 0 | 0 | 1 | 0 |
| mcp | 11 | 11 | 1 | 0 | 10 | 0 | 11 | 0 |
| memory | 16 | 25 | 2 | 23 | 0 | 0 | 23 | 2 |
| monitoring | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| observability | 15 | 5 | 5 | 0 | 0 | 0 | 5 | 0 |
| openapi-tools | 24 | 24 | 0 | 24 | 0 | 0 | 23 | 1 |
| ops | 6 | 24 | 3 | 0 | 21 | 0 | 24 | 0 |
| optimize | 3 | 3 | 0 | 1 | 2 | 0 | 3 | 0 |
| orchestration | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| output-handling | 2 | 2 | 0 | 2 | 0 | 0 | 2 | 0 |
| patterns | 18 | 52 | 31 | 21 | 0 | 0 | 52 | 0 |
| project-setup | 1 | 1 | 1 | 0 | 0 | 0 | 1 | 0 |
| run-control | 3 | 2 | 2 | 0 | 0 | 0 | 2 | 0 |
| runtime-concepts | 4 | 26 | 26 | 0 | 0 | 0 | 26 | 0 |
| runtime-core | 8 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| sandboxing | 10 | 13 | 3 | 10 | 0 | 0 | 13 | 0 |
| scheduling | 4 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| scorers | 14 | 14 | 7 | 6 | 0 | 1 | 14 | 0 |
| sdk-agents | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| security | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| skills | 1 | 2 | 0 | 0 | 2 | 0 | 2 | 0 |
| testing-evaluation | 3 | 2 | 2 | 0 | 0 | 0 | 2 | 0 |
| time-travel | 22 | 16 | 13 | 1 | 2 | 0 | 16 | 0 |
| tool-context | 4 | 3 | 0 | 3 | 0 | 0 | 3 | 0 |
| ui | 2 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| vcs | 16 | 19 | 4 | 15 | 0 | 0 | 17 | 2 |
| workflow-authoring | 3 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| workflow-discovery | 4 | 1 | 1 | 0 | 0 | 0 | 1 | 0 |
| workflow-execution | 2 | 1 | 1 | 0 | 0 | 0 | 1 | 0 |
| workflow-integration | 1 | 2 | 0 | 2 | 0 | 0 | 0 | 2 |
| workflow-monitoring | 3 | 2 | 2 | 0 | 0 | 0 | 2 | 0 |
| workflows | 3 | 0 | 0 | 0 | 0 | 0 | 0 | 0 |

## ⚠️ Features flagged UNDOCUMENTED (28)

Immediate docs-gap candidates — an eval that fails here points straight at a doc to write.

- `smithers chat-create` — Create and start a one-task auto-hijacked chat run with specified agent. _(area: agent-interaction)_
- `smithers alerts (list|ack|resolve|silence)` — List and manage durable alert instances with actions: list, ack, resolve, silence. _(area: monitoring)_
- `smithers snapshots <runId>` — List durability snapshots (workspace checkpoints) for a run. _(area: devtools)_
- `smithers restore <runId> <nodeId>` — Restore a worktree to a durability checkpoint (latest for the node, or --seq). _(area: devtools)_
- `smithers snapshot-hook` — Internal: PostToolUse hook that requests a Tier 1 durability snapshot. _(area: devtools)_
- `smithers revert <workflow>` — Revert the workspace to a previous task attempt's filesystem state. _(area: time-travel)_
- `smithers retry-task <workflow>` — Retry a specific task within a run, optionally skipping dependents with --no-deps. _(area: time-travel)_
- `smithers timetravel <workflow>` — Time-travel to a previous task state by reverting filesystem and DB, optionally resuming. _(area: time-travel)_
- `smithers scores <runId>` — View scorer results for a specific run, optionally filtered by --node. _(area: testing-evaluation)_
- `smithers replay <workflow>` — Fork from a checkpoint and resume execution with input overrides. _(area: time-travel)_
- `smithers tree <runId>` — Print DevTools snapshot as XML tree with optional filtering, watch, and JSON modes. _(area: devtools)_
- `smithers diff <runId> <nodeId>` — Print DiffBundle as unified diff with --stat summary and colorization options. _(area: devtools)_
- `smithers output <runId> <nodeId>` — Print node output row as JSON with optional --pretty schema-ordered rendering. _(area: devtools)_
- `smithers rewind <runId> <frameNo>` — Rewind a run to a previous frame without executing. _(area: time-travel)_
- `smithers fork <workflow>` — Create a branched run from a snapshot checkpoint with optional --run to auto-start. _(area: time-travel)_
- `smithers timeline <runId>` — View execution timeline for a run and its forks with optional --tree recursion. _(area: time-travel)_
- `smithers gui [path]` — Open a directory as a workspace in Smithers GUI macOS app. _(area: ui)_
- `smithers cron start` — Start background scheduler loop in current terminal. _(area: scheduling)_
- `smithers cron add <pattern> <workflowPath>` — Register a new workflow cron schedule with pattern and workflow path. _(area: scheduling)_
- `smithers cron list` — List all registered background cron schedules. _(area: scheduling)_
- `smithers cron rm <cronId>` — Delete an existing cron schedule by ID. _(area: scheduling)_
- `smithers agents capabilities` — Print JSON report of built-in CLI agent capability registries. _(area: agents)_
- `smithers agents doctor` — Validate built-in CLI agent capability registries and command-surface contracts. _(area: agents)_
- `smithers agents add` — Register Smithers agent account via interactive wizard or non-interactive flags. _(area: agents)_
- `smithers agents list` — List all registered Smithers agent accounts with labels and credentials status. _(area: agents)_
- `smithers agents remove <label>` — Remove a registered agent account by label. _(area: agents)_
- `smithers memory list <namespace>` — List all memory facts in a namespace. _(area: memory)_
- `smithersMemoryFacts, smithersMemoryThreads, smithersMemoryMessages` — SQLite schema tables for persistent storage: smithersMemoryFacts, smithersMemoryThreads, smithersMemoryMessages. _(area: memory)_

## Features by area

### agent-instantiation


### agent-interaction

- **ask** (`smithers ask [question]`) — Ask a question about Smithers using installed agent and Smithers MCP server. · _llms.txt_
- **chat-create** (`smithers chat-create`) — Create and start a one-task auto-hijacked chat run with specified agent. · _**UNDOCUMENTED**_
- **hijack** (`smithers hijack <runId>`) — Hand off latest resumable agent session or conversation for a run to interactive terminal. · _llms.txt_

### agent-lifecycle

- **Hijack (interactive resume)** (`-`) — Most CLI agents support native interactive takeover via bunx smithers-orchestrator hijack RUN_ID using vendor-specific resume flags. · _?_
- **Session resumption** (`-`) — Agents persist and resume sessions via native IDs (sessionId, threadId, conversationId) passed through resumeSession or generate() options. · _?_

### agents

- **agents add** (`smithers agents add`) — Register Smithers agent account via interactive wizard or non-interactive flags. · _**UNDOCUMENTED**_
- **agents capabilities** (`smithers agents capabilities`) — Print JSON report of built-in CLI agent capability registries. · _**UNDOCUMENTED**_
- **agents doctor** (`smithers agents doctor`) — Validate built-in CLI agent capability registries and command-surface contracts. · _**UNDOCUMENTED**_
- **agents list** (`smithers agents list`) — List all registered Smithers agent accounts with labels and credentials status. · _**UNDOCUMENTED**_
- **agents remove** (`smithers agents remove <label>`) — Remove a registered agent account by label. · _**UNDOCUMENTED**_
- **usage** (`smithers usage`) — Show rate limit and subscription quota usage for each registered account. · _llms.txt_

### agents-runtimes

- **AmpAgent** (`new AmpAgent({...})`) — CLI agent wrapping the Amp CLI in --execute headless mode with thread visibility, MCP config, and dangerouslyAllowAll option. · _?_
- **AnthropicAgent (SDK)** (`new AnthropicAgent({...})`) — AI SDK wrapper for Anthropic Claude models with native structured output support and tool-loop agent semantics. · _?_
- **AntigravityAgent** (`new AntigravityAgent({...})`) — CLI agent wrapping the Google Antigravity CLI (agy binary) with conversation resumption, MCP config, and sandbox mode; replaces GeminiAgent. · _?_
- **Claude permission modes** (`-`) — ClaudeCodeAgent supports permissionMode enum: acceptEdits, bypassPermissions, default, delegate, dontAsk, plan for fine-grained permission control. · _?_
- **ClaudeCodeAgent** (`new ClaudeCodeAgent({...})`) — CLI agent wrapping the Anthropic Claude Code CLI with session persistence, MCP config, tool allow/deny lists, and permission modes. · _?_
- **Codex config overrides** (`-`) — CodexAgent config option enables inline Codex configuration via -c flags or structured key-value pairs. · _?_
- **CodexAgent** (`new CodexAgent({...})`) — CLI agent wrapping the OpenAI Codex CLI with sandbox modes, config overrides, structured JSON output schema, and thread-based resumption. · _?_
- **ForgeAgent** (`new ForgeAgent({...})`) — CLI agent wrapping the Forge CLI supporting 300+ LLM models via provider/model strings and conversation persistence. · _?_
- **GeminiAgent (deprecated)** (`new GeminiAgent({...})`) — Legacy CLI agent wrapping the older Google Gemini CLI; use AntigravityAgent instead for new Google CLI integrations. · _?_
- **HermesAgent (SDK)** (`new HermesAgent({...})`) — OpenAI-compatible local agent wrapper (Nous Research Hermes) using OpenAI SDK with disabled native structured output by default. · _?_
- **Kimi OAuth auto-refresh** (`-`) — KimiAgent automatically refreshes expired OAuth tokens using stored refresh_token; fails fast non-retryable if no token or refresh fails. · _?_
- **KimiAgent** (`new KimiAgent({...})`) — CLI agent wrapping the Moonshot Kimi CLI with automatic OAuth refresh, configurable thinking, agent selection (default/okabe), and auto-isolated KIMI_SHARE_DIR. · _?_
- **OpenAIAgent (SDK)** (`new OpenAIAgent({...})`) — AI SDK wrapper for OpenAI/Azure OpenAI models with configurable baseURL/apiKey and native structured output. · _?_
- **OpenCode nd-JSON events** (`-`) — OpenCodeAgent parses streaming nd-JSON from opencode run with step_start/text/tool_use/step_finish/reasoning/error envelopes. · _?_
- **OpenCode variant/reasoning** (`-`) — OpenCodeAgent variant option controls reasoning effort level (high/medium/low) for different task complexity needs. · _?_
- **OpenCodeAgent** (`new OpenCodeAgent({...})`) — CLI agent wrapping the OpenCode CLI via opencode run --format json with session IDs, file attachments, and reasoning variants. · _?_
- **Pi extension UI requests** (`-`) — PiAgent in RPC mode supports custom UI callbacks via onExtensionUiRequest hook for extension-based interactions. · _?_
- **PiAgent** (`new PiAgent({...})`) — CLI agent wrapping the Pi CLI with three modes (text/json/rpc), extension UI request callbacks, and skills/template support. · _?_
- **VibeAgent** (`new VibeAgent({...})`) — CLI agent wrapping the Mistral Vibe CLI with streaming JSON output, session management, and tool enablement. · _?_

### approvals

- **approve** (`smithers approve <runId>`) — Approve a paused approval gate, auto-detecting pending node if only one exists. · _llms.txt_
- **ask-human** (`smithers ask-human <prompt>`) — Raise a blocking human-approval request from inside a run and wait for decision. · _llms.txt_
- **deny** (`smithers deny <runId>`) — Deny a paused approval gate, rejecting workflow progress. · _llms.txt_
- **human** (`smithers human (inbox|answer|cancel)`) — List pending human requests, answer with --value, or cancel requests. · _llms.txt_

### authoring

- **Approval Component** (`<Approval id output request>`) — JSX component for pausing execution to request human approval with optional feedback. · _docs/llms-full.txt (lines 1016-1070)_
- **Branch Component** (`<Branch if then else>`) — JSX component for conditional execution: if condition then branch1 else branch2. · _docs/llms-full.txt (~1750)_
- **JSX Workflow Authoring API** (`createSmithers(), <Workflow>, <Task>, <Sequence>, <Parallel>, <Branch>, <Loop>`) — Author workflows as JSX trees with Workflow, Task, Sequence, Parallel, Branch, Loop, and control-flow components. · _docs/llms-full.txt (lines 1555-1600)_
- **Loop Component** (`<Loop until maxIterations>`) — JSX component for iterating tasks until a condition is satisfied or max iterations reached. · _docs/llms-full.txt (~1750)_
- **MDX Prompt Templates** (`.smithers/prompts/*.mdx`) — Author prompts as .mdx files with JSX interpolation for variables, enabling dynamic prompt composition. · _docs/llms-full.txt (lines 1595-1600, JSX API section)_
- **Parallel Component** (`<Parallel maxConcurrency>`) — JSX component for concurrent independent task execution with optional concurrency limit. · _docs/llms-full.txt (~1750)_
- **Seeded Reusable Components** (`.smithers/components/*.tsx`) — Pre-built TSX components for common subflows: ValidationLoop, Review, GrillMe, FeatureEnum, ShipTickets. · _.smithers/components/ directory_
- **Sequence Component** (`<Sequence>`) — JSX component for sequential task execution where later tasks depend on earlier outputs. · _docs/llms-full.txt (~1750)_
- **Task Component** (`<Task id output agent>`) — JSX component for declaring a unit of work with agent, output schema, prompt, and dependencies. · _docs/llms-full.txt (lines 2425+)_
- **Workflow Agent Configuration** (`agents.smart, agents.smartTool, agents.cheapFast`) — Assign agents to tasks; agents are configured in .smithers/agents/ (smart, smartTool, cheapFast, etc.) and can be any provider. · _docs/llms-full.txt (lines 399, 2700+)_

### budget-enforcement

- **Aspects Budget Inheritance** (`Aspects nesting`) — Nested Aspects inherit outer budget configs wholesale; a child's config field replaces the parent's entire field (no per-field merge). · _docs/components/aspects.mdx_
- **Aspects Latency SLO** (`Aspects, latencySlo prop`) — Limit wall-clock latency for workflow execution; enforce with fail/warn on breach. · _docs/components/aspects.mdx_
- **Aspects Token Budget** (`Aspects, tokenBudget prop`) — Limit total token usage across a workflow subtree with per-task and global limits; enforce with fail/warn/skip-remaining on breach. · _docs/components/aspects.mdx_

### built-in-tools

- **bash tool** (`bash(cmd, args?, opts?)`) — Built-in Smithers tool to run shell commands with cmd, optional args array, and optional cwd; enforces network/path containment. · _packages/smithers/src/tools/bash.js_
- **edit tool** (`edit(path, patch)`) — Built-in Smithers tool to apply unified diff patches to files; enforces path containment within --root. · _packages/smithers/src/tools/edit.js_
- **grep tool** (`grep(pattern, path?)`) — Built-in Smithers tool to search files with regex patterns using ripgrep (rg); enforces path containment within --root. · _packages/smithers/src/tools/grep.js_
- **read tool** (`read(path)`) — Built-in Smithers tool to read file contents; enforces path containment within --root. · _packages/smithers/src/tools/read.js_
- **write tool** (`write(path, content)`) — Built-in Smithers tool to write or overwrite file contents; enforces path containment within --root. · _packages/smithers/src/tools/write.js_

### capabilities

- **MCP configuration** (`-`) — Model Context Protocol bootstrap modes (project-config, inline-config, allow-list, unsupported) vary by agent with different project/user scope support. · _?_
- **Skill installation modes** (`-`) — Agents support different skill installation: plugin (launch-time), dir (directory), files (file-based), or none; varies by agent. · _?_

### cli

- **Agents-Only Init Flag** (`bunx smithers-orchestrator init --agents-only`) — Only create .smithers/agents/ configuration without touching the workflow pack. · _docs/llms-full.txt (line 1705)_
- **Diff snapshots between frames** (`smithers diff <runId> <nodeId>`) — Compute structured diff of nodes, outputs, loops, and input changes between two snapshots. · _llms-core.txt_
- **Force Init Flag** (`bunx smithers-orchestrator init --force`) — Overwrite existing .smithers/ scaffold files during init. · _docs/llms-full.txt (line 1704)_
- **Fork run from checkpoint** (`smithers fork <workflow> --run-id <runId> --frame <frameNo>`) — Create an independent branched run from a snapshot checkpoint with optional node reset and input overrides. · _llms-core.txt_
- **Global Init Flag** (`bunx smithers-orchestrator init --global`) — Scaffold the workflow pack in ~/.smithers (global) instead of ./.smithers (local). · _docs/llms-full.txt (line 1708)_
- **Init Templates (Starters)** (`bunx smithers-orchestrator init --template <id>`) — Pre-built starter templates for common workflows (idea-to-prd, idea-to-tickets, research, debug, etc.). · _docs/llms-full.txt (lines 550-590)_
- **List durability snapshots** (`smithers snapshots <runId>`) — List workspace checkpoints (durability snapshots) captured during a run's execution. · _llms-core.txt_
- **Replay from checkpoint and resume** (`smithers replay <workflow> --run-id <runId> --frame <frameNo> --restore-vcs`) — Fork from a checkpoint and immediately resume execution, optionally restoring the VCS working copy to match the original attempt. · _llms-core.txt_
- **Restore worktree to checkpoint** (`smithers restore <runId> --node <nodeId>`) — Restore a worktree to a durability checkpoint by running jj restore with the checkpoint's commit ID. · _llms-core.txt_
- **Retry a task within a run** (`smithers retry-task <workflow> --run-id <runId> --node <nodeId>`) — Reset a node to pending state and optionally reset all dependent downstream nodes, then resume the run. · _llms-core.txt_
- **Rewind run to prior frame** (`smithers rewind <runId> --frame <frameNo> --yes`) — Destructively time-travel backwards by reverting VCS state and deleting frames recorded after the target frame. · _llms-core.txt_
- **Smithers Init Command** (`bunx smithers-orchestrator init`) — Scaffold .smithers/ with seeded workflows, prompts, components, agent configs, and optional dependencies. · _docs/llms-full.txt (lines 380-410)_
- **Starter Templates Reference** (`bunx smithers-orchestrator starters`) — 10 canonical starter template IDs with audiences and corresponding seeded workflows (idea-to-prd, idea-to-tickets, launch-checklist, etc.). · _docs/llms-full.txt (lines 575-590)_
- **Starters Browsing Command** (`bunx smithers-orchestrator starters [--audience|--goal|--workflow|--tag]`) — Browse and filter available starter templates by audience, goal, workflow, or tag. · _docs/llms-full.txt (lines 595-610)_
- **Time-travel to prior attempt** (`smithers timetravel <workflow> --run-id <runId> --node <nodeId> --attempt <attemptNo>`) — Revert a specific node to a prior attempt by restoring filesystem state and resetting dependent nodes. · _llms-core.txt_
- **View execution timeline** (`smithers timeline <runId> --tree`) — Display all frames and fork branches for a run, with optional recursive tree view of descendants. · _llms-core.txt_
- **Workflow Create Scaffold Command** (`bunx smithers-orchestrator workflow.create <name>`) — Create a new minimal flat workflow scaffold in .smithers/workflows/ with TypeScript and JSX setup. · _docs/llms-full.txt (~1835)_
- **Workflow Graph Rendering** (`bunx smithers-orchestrator graph <workflow>`) — Render the workflow graph without executing it to verify structure and detect syntax errors. · _docs/llms-full.txt (~1800)_
- **Workflow Inspection Command** (`bunx smithers-orchestrator workflow.inspect <name>`) — Show workflow metadata, input/output schemas, and agent-facing skill documentation. · _docs/llms-full.txt (~1828)_
- **Workflow List Discovery** (`bunx smithers-orchestrator workflow.list`) — List all discovered workflows from local .smithers/workflows/ and global ~/.smithers/workflows/. · _docs/llms-full.txt (~1715)_
- **Workflow Run Command** (`bunx smithers-orchestrator workflow run <name>`) — Execute a discovered workflow by ID with input, concurrency control, resumption, and HTTP serving. · _docs/llms-full.txt (lines ~1720-1770)_
- **Workflow Skills Generation** (`bunx smithers-orchestrator workflow.skills [name] [--output]`) — Generate SKILL.md documentation for discovered workflows for agent use. · _docs/llms-full.txt (~1839)_
- **Workflow Up Command** (`bunx smithers-orchestrator up <workflow>`) — Start or resume a workflow execution with input, run ID, resource limits, and optional HTTP serving. · _docs/llms-full.txt (~1720)_
- **smithers eval CLI command** (`smithers eval`) — Runs an eval suite: `smithers eval <workflow> --cases <file.jsonl> --suite <name> [--concurrency N] [--dry-run]`. · _?_
- **smithers optimize CLI command** (`smithers optimize`) — Runs prompt optimization: baseline eval, GEPA patch generation, optimized eval, score comparison, and artifact output. · _?_

### components-control-flow

- **Approval** (`<Approval id="..." output={...} request={...}>`) — Decision node that waits for human approval, produces typed ApprovalDecision output. · _/docs/llms-core.txt (line 2757)_
- **ApprovalGate** (`<ApprovalGate id="..." when={bool} output={...}>`) — Conditional approval gate that only requires approval when 'when' condition is true. · _/docs/llms-core.txt (line 2837)_
- **Aspects** (`<Aspects tokenBudget={{...}} latencySlo={{...}}>`) — Propagates token budget and latency SLO constraints to descendant tasks. · _/docs/llms-core.txt (line 3690)_
- **Branch** (`<Branch if={cond} then={...} else={...}>`) — Conditionally executes one of two branches (then/else) based on a boolean condition. · _/docs/llms-core.txt (line 2660)_
- **ContinueAsNew** (`<ContinueAsNew state={{...}}>`) — Closes current run and starts fresh one with optional carried state. · _/docs/llms-core.txt (line 3598)_
- **HumanTask** (`<HumanTask id="..." output={...} prompt="...">`) — Suspends until human submits JSON matching output schema with max validation retries. · _/docs/llms-core.txt (line 2992)_
- **Loop** (`<Loop until={cond} maxIterations={n}>`) — Repeatedly renders and executes children until condition holds or maxIterations reached. · _/docs/llms-core.txt (line 2705)_
- **MergeQueue** (`<MergeQueue maxConcurrency={n}>`) — Queues child tasks so at most maxConcurrency run; defaults to 1 for single-lane merge queue. · _/docs/llms-core.txt (line 4196)_
- **Parallel** (`<Parallel maxConcurrency={n}>`) — Executes child tasks concurrently with optional maxConcurrency limit. · _/docs/llms-core.txt (line 2622)_
- **Ralph** (`<Ralph> (deprecated)`) — Deprecated alias for Loop component; use Loop instead. · _/packages/components/src/components/RalphProps.ts_
- **Sandbox** (`<Sandbox id="..." workflow={...} provider={...} output={...}>`) — Runs child workflow through injectable provider with isolation, parallelism, or horizontal scale. · _/docs/llms-core.txt (line 3313)_
- **Sequence** (`<Sequence>`) — Executes child tasks top-to-bottom in order. · _/docs/llms-core.txt (line 2578)_
- **Signal** (`<Signal id="..." schema={...}>`) — Typed wrapper around WaitForEvent; signal name equals node id, with typed schema. · _/docs/llms-core.txt (line 3061)_
- **Subflow** (`<Subflow id="..." workflow={...} output={...} mode="childRun"|"inline">`) — Invokes child workflow with own retry, cache, and resume boundary. · _/docs/llms-core.txt (line 3542)_
- **SuperSmithers** (`<SuperSmithers strategy="..." agent={...} targetFiles?>`) — Reads and modifies source code at runtime via markdown strategy doc with agent. · _/docs/llms-core.txt (line 3647)_
- **Task** (`<Task id="..." output={...} agent?>`) — Executes work via agent call, computed function, or static value with schema validation. · _/docs/llms-core.txt (line 2405)_
- **Timer** (`<Timer id="..." duration="..." | until="...">`) — Durably suspends for relative duration (e.g. '30s') or until absolute time. · _/docs/llms-core.txt (line 3170)_
- **TryCatchFinally** (`<TryCatchFinally try={...} catch={...} finally={...}>`) — Workflow-scoped error boundary with catch handlers and guaranteed cleanup via finally. · _/docs/llms-core.txt (line 3267)_
- **WaitForEvent** (`<WaitForEvent id="..." event="..." output={...}>`) — Durably suspends until correlated external event arrives or timeout, with timeout behavior. · _/docs/llms-core.txt (line 3117)_
- **Workflow** (`<Workflow name="..." cache?>`) — Root container that sequences direct children and optionally caches for resume. · _/docs/llms-core.txt (line 2360)_
- **Worktree** (`<Worktree path="..." branch? baseBranch?>`) — Runs child tasks in isolated git worktree at specified path, created and torn down automatically. · _/docs/llms-core.txt (line 3744)_

### concepts

- **AgentCapabilityRegistry** (`AgentCapabilityRegistry type`) — Structured capability metadata for agents including engine name, MCP bootstrap mode, skill installation mode, and built-in tool list. · _?_
- **AgentLike interface** (`AgentLike type`) — Common interface for all agents exposing generate() method, optional tools, and AgentCapabilityRegistry for introspection. · _?_

### configuration

- **BaseCliAgentOptions** (`id, model, systemPrompt, cwd, env, yolo, timeoutMs, idleTimeoutMs, maxOutputBytes, extraArgs`) — Common configuration options shared by all CLI agents including timeouts, environment variables, and system prompts. · _?_
- **Config directory isolation** (`-`) — Agents support configDir option to isolate credentials per invocation (CLAUDE_CONFIG_DIR, CODEX_HOME, KIMI_SHARE_DIR, GEMINI_DIR). · _?_
- **Model selection and fallback** (`-`) — Agents accept model option (e.g., claude-opus-4-8, gpt-5.5, gemini-3.1-pro); pools support fallback chains for automatic model selection. · _?_

### context-api

- **Render Context (ctx)** (`SmithersCtx, ctx parameter`) — The only interface between workflow code and runtime; provides runId, iteration, iterations, input, outputs, auth, task states. · _docs/how-it-works.mdx_
- **Task Dependencies: deps and needs** (`Task deps, needs, dependsOn props`) — deps declares typed render-time upstream outputs; needs maps local names to upstream task ids. Use needs when dep name differs from upstream id. · _docs/components/task.mdx_
- **ctx.latest() for Loop Iteration** (`ctx.latest(table, nodeId)`) — Reads the highest-iteration output of a task, used inside Loop to read the previous iteration's output. · _docs/how-it-works.mdx_
- **ctx.latestArray() for Parsed Arrays** (`ctx.latestArray(value, schema)`) — Parses a JSON string, scalar, or array and keeps entries accepted by a Zod schema, handling null coalescing. · _docs/how-it-works.mdx_
- **ctx.output() and ctx.outputMaybe()** (`ctx.output(table, {nodeId, iteration}), ctx.outputMaybe(table, {nodeId, iteration})`) — Two methods to read upstream task outputs: ctx.output() throws if missing (for guaranteed deps), ctx.outputMaybe() returns undefined (for conditional rendering). · _docs/how-it-works.mdx_
- **ctx.outputs() for All Rows** (`ctx.outputs(table), ctx.outputs.<key>`) — Returns all rows from an output table or accesses rows by schema key as ctx.outputs.keyName. · _docs/how-it-works.mdx_

### control-flow

- **<MergeQueue>** (`<MergeQueue maxConcurrency? id? skipIf?>`) — React component that queues child tasks to run with bounded concurrency (default 1), providing merge-queue serialization. · _?_
- **Approval Denial Policies** (`Approval onDeny prop`) — Three policies for denied approval: fail (abort run), continue (proceed without gated branch), skip (skip gated tasks, continue siblings). · _docs/how-it-works.mdx_
- **Approval Gate vs Decision Node** (`Task needsApproval, Approval component`) — needsApproval on Task is a gate (pause, no decision data). Approval is a decision node (produces typed ApprovalDecision row for branching). · _docs/how-it-works.mdx_
- **Branch Conditional Rendering** (`Branch if, then, else`) — Conditional fork: mounts then when if is true, otherwise else. Unselected branch tasks are absent from the task graph. · _docs/components/branch.mdx_
- **Continue As New State Transition** (`ContinueAsNew state prop, continueAsNew()`) — Close the current run and start a fresh one with optional JSON-serializable carried state. Workflow id is preserved; run id increments. · _docs/components/continue-as-new.mdx_
- **Fork Immutable Session Copy** (`Task fork prop`) — Copy another agent task's final session context into a fresh, independent session and submit a new prompt. Source is never mutated; multiple tasks can safely fork the same source. · _docs/components/task.mdx_
- **Loop Control Flow** (`Loop id, until, maxIterations, onMaxReached`) — Re-run children repeatedly: on each iteration, render, execute, persist outputs; check until condition on next frame; stop when until is true or maxIterations is reached. · _docs/components/loop.mdx_
- **Parallel Concurrency Control** (`Parallel maxConcurrency`) — Run children concurrently with optional maxConcurrency cap. Completes when all children finish unless continueOnFail is set on individual tasks. · _docs/components/parallel.mdx_
- **Saga Compensation Pattern** (`Saga steps prop, compensation`) — Forward steps run sequentially, each with a compensation. On failure of any step, compensations run in reverse from the failed step. · _docs/components/saga.mdx_

### devtools

- **diff** (`smithers diff <runId> <nodeId>`) — Print DiffBundle as unified diff with --stat summary and colorization options. · _**UNDOCUMENTED**_
- **graph** (`smithers graph <workflow>`) — Render the workflow graph without executing it, with optional --input and --compact. · _llms.txt_
- **output** (`smithers output <runId> <nodeId>`) — Print node output row as JSON with optional --pretty schema-ordered rendering. · _**UNDOCUMENTED**_
- **restore** (`smithers restore <runId> <nodeId>`) — Restore a worktree to a durability checkpoint (latest for the node, or --seq). · _**UNDOCUMENTED**_
- **snapshot-hook** (`smithers snapshot-hook`) — Internal: PostToolUse hook that requests a Tier 1 durability snapshot. · _**UNDOCUMENTED**_
- **snapshots** (`smithers snapshots <runId>`) — List durability snapshots (workspace checkpoints) for a run. · _**UNDOCUMENTED**_
- **tree** (`smithers tree <runId>`) — Print DevTools snapshot as XML tree with optional filtering, watch, and JSON modes. · _**UNDOCUMENTED**_

### diagnostics

- **Agent capability diagnostics** (`getCliAgentCapabilityDoctorReport, formatCliAgentCapabilityDoctorReport`) — Diagnostic functions to check agent CLI availability, MCP support, skill registration, and tool surface compliance. · _?_

### docs

- **docs** (`smithers docs`) — Print llms.txt (concise docs index for LLMs) for this CLI version. · _llms.txt_
- **docs-full** (`smithers docs-full`) — Print llms-full.txt (full docs bundle for LLMs) for this CLI version. · _llms.txt_

### durability-model

- **Crash-Resume Durability Contract** (`resume: true, --resume flag`) — A completed task is never re-executed. Resume loads persisted state, validates workflow source hash and VCS revision, abandons stale in-progress attempts (>15 min without heartbeat), and continues. · _docs/how-it-works.mdx_
- **Heartbeat Timeout Recovery** (`heartbeatTimedOut(), heartbeatTimeoutMs prop`) — In-progress tasks without a heartbeat for >15 minutes are abandoned on resume as stale and re-executed as a fresh attempt. · _docs/how-it-works.mdx_
- **Hot Reload Mode** (`hot: true, up --hot`) — Edit workflow code during a running execution; changes apply only to newly scheduled tasks while in-flight tasks finish on their original code. · _docs/how-it-works.mdx_
- **Stable Task ID Requirement** (`id prop on Task, Loop, Branch`) — Task IDs must be stable and data-derived across renders. Changing an ID makes it look like a new task; a disappeared ID drops the old task from the plan. · _docs/how-it-works.mdx_

### evals

- **Build and write eval report** (`-`) — Internal helper of the `smithers eval` command (apps/cli/src/eval-suite.js). Constructs and writes a JSON report summarizing eval results with per-case status, assertions, and timing. Not a published export; author-facing surface is the `smithers eval` CLI and the report file at .smithers/evals/<suiteId>.json. · _?_
- **Build eval execution plan** (`-`) — Internal helper of the `smithers eval` command (apps/cli/src/eval-suite.js). Transforms loaded cases into a planned execution with stable run IDs and suite/case metadata. Not a published export. · _?_
- **Eval case metadata for optimization hints** (`-`) — Per-case metadata object supporting promptPatches (explicit patches) and optimizationHints (guidance for GEPA). · _?_
- **Eval cases JSONL format** (`-`) — Line-delimited JSON format for eval cases, each with id, input, expected (status/output/outputContains), annotations, metadata. · _?_
- **Evaluate case result assertions** (`-`) — Internal helper of the `smithers eval` command (apps/cli/src/eval-suite.js). Checks run result against expected assertions (status, output, outputContains, errorContains) and returns pass/fail per assertion. Not a published export. · _?_
- **Generate stable eval run IDs** (`-`) — Creates deterministic run IDs from suite and case IDs, capping at 64 characters with hash suffix for long names. · _?_
- **Load eval cases from JSONL/JSON** (`-`) — Loads and normalizes eval cases from JSONL or JSON files, with per-case input, expected assertions, and metadata. · _?_
- **eval-writer skill for bootstrapping suites** (`-`) — Workflow skill that turns plain-English acceptance criteria into executable JSONL eval fixtures with cases and rubrics. · _?_

### examples

- **Debate/Panel Pattern** (`examples/debate.jsx, examples/panel.jsx`) — Multiple agents argue positions in parallel, a judge synthesizes the verdict. · _examples/debate.jsx_
- **Example Kit Utilities** (`examples/_example-kit.js`) — Helper functions and utilities for writing example workflows: createExampleSmithers, latest, unique, countBy, etc. · _examples/_example-kit.js_
- **Example Workflow Patterns** (`examples/*.jsx`) — 100 documented example workflows demonstrating patterns: fan-out-fan-in, loops, debates, panels, triage, migrations, PR lifecycles, and more. · _examples/ directory + docs/llms-full.txt (lines 203-225)_
- **Fan-Out-Fan-In Pattern** (`examples/fan-out-fan-in.jsx`) — Split work into N parallel items, process each independently, merge results. · _examples/fan-out-fan-in.jsx_
- **Loop/Coverage Pattern** (`examples/coverage-loop.jsx`) — Iterate until convergence: measure → improve → repeat with measurable progress. · _examples/coverage-loop.jsx_
- **Review Loop Pattern** (`examples/review-cycle.jsx, examples/code-review-loop.jsx`) — Agent implements, reviewer critiques, implementer fixes, repeat until approved. · _examples/review-cycle.jsx_
- **Triage/Classifier Pattern** (`examples/triage.jsx, examples/classifier-switchboard.jsx`) — Classify/categorize items, route each to handler by classification. · _examples/triage.jsx_
- **Waterfall/Sequence Pattern** (`examples/waterfall.jsx`) — Sequential phases where each phase receives and builds on previous phase output. · _examples/waterfall.jsx_

### gateway

- **Custom UI pattern (vanilla/React)** (`gateway.register(key, workflow, { ui: { entry, title } }), createGatewayReactRoot`) — Mount custom UIs per workflow via .ui/<key>.tsx or vanilla JS entry points; UIs bootstrap with gateway boot config. · _?_
- **DevTools snapshot/delta stream** (`streamDevTools, DevToolsSnapshot, DevToolsDelta, DevToolsEvent, DevToolsNode`) — Versioned (v1) WebSocket stream of workflow tree snapshots and incremental deltas for inspector/debugger consumption. · _?_
- **Gateway RPC error codes** (`InvalidRequest, InvalidInput, Unauthorized, Forbidden, RunNotFound, RUN_NOT_ACTIVE, CronNotFound, NodeNotFound, FrameOutOfRange, SeqOutOfRange, Busy, AlreadyDecided, RateLimited, PayloadTooLarge, BackpressureDisconnect, UnsupportedSandbox, VcsError, RewindFailed, Internal`) — 21 stable error codes with HTTP status mappings and optional requiredScope/refresh hints for auth token expiry handling. · _?_
- **Gateway RPC methods** (`launchRun, resumeRun, cancelRun, hijackRun, rewindRun, submitApproval, submitSignal, getRun, listRuns, listWorkflows, listApprovals, streamRunEvents, streamDevTools, getNodeOutput, getNodeDiff, cronList, cronCreate, cronDelete, cronRun`) — 19 typed RPC methods over HTTP+WebSocket for run lifecycle, approvals, signals, cron, and devtools, with stable error codes and auth scopes. · _?_
- **Gateway React hooks** (`useGatewayRun, useGatewayRuns, useGatewayRpc, useGatewayRunEvents, useGatewayApprovals, useGatewayActions, useGatewayExtensionStream, useGatewayExtensionResource, useGatewayExtensionAction, createGatewayReactRoot, SmithersGatewayProvider`) — React 19 hooks for live-data subscriptions over gateway collections with stale-data guards, optimistic mutations, and WebSocket reconnect handling. · _?_
- **Gateway UI boot configuration** (`GatewayUiBootConfig, __SMITHERS_GATEWAY_UI__`) — Global config passed to custom UIs at boot time: base URL, auth token, run ID, and protocol version via window.__SMITHERS_GATEWAY_UI__. · _?_
- **Gateway WebSocket protocol** (`req, res, event, connect.challenge, hello, tick, run.completed, approval.requested, devtools.event`) — Frame-based protocol: request/response with correlation IDs, server-pushed events, handshake with auth challenge, and heartbeat. · _?_
- **Gateway auth scopes and tokens** (`run:read, run:write, run:admin, approval:submit, signal:submit, cron:read, cron:write, observability:read, *, methodName`) — Granular auth scopes for gateway RPC methods; tokens grant scopes and caller identity (userId, role) for ownership and audit. · _?_
- **Gateway client SDK (TypeScript/JavaScript)** (`SmithersGatewayClient, SmithersGatewayConnection`) — Browser-first SDK for programmatic gateway RPC calls, event streaming with resilient reconnection/backoff, and WebSocket multiplexing. · _?_
- **Gateway exponential backoff** (`gatewayBackoffDelay, GatewayBackoffOptions, attempt, maxDelayMs, jitterFraction`) — Configurable exponential backoff with jitter for stream reconnection and RPC retry. · _?_
- **Gateway extension RPC/stream system** (`extensionMethodName, extensionStreamMethodName, GATEWAY_EXTENSION_METHOD_PREFIX, GatewayExtensionEnvelope`) — Third-party RPC methods and streams over the gateway namespace/key pattern with backpressure, bounded frame windows, and reconnect resume. · _?_
- **Node output and diff fetching** (`getNodeOutput, getNodeDiff, NodeOutputResponse, OutputSchemaDescriptor, iteration`) — Fetch task output payload with schema descriptor or node-level diff bundle (VCS, file-level changes). · _?_
- **Rewind run (time travel)** (`rewindRun, frameNo, confirm:true, JumpResult, TimeTravelJumped, _smithers_time_travel_audit`) — Destructive frame rewind with VCS sandbox rollback, audit trail, owner/admin authorization, and 10-rewind-per-hour quota. · _?_
- **Run events resilient stream** (`streamRunEvents, streamRunEventsResilient, GatewayEventFrame, run.heartbeat, run.gap_resync`) — WebSocket stream with gap-resync semantics, bounded replay, per-run sequence numbers, and heartbeat keep-alives. · _?_
- **Smithers TanStack DB collections** (`createSmithersCollections, WorkspaceMode, SmithersCollectionsProvider, useGatewayRunEvents`) — Current collection surface for Gateway UIs: createSmithersCollections over WorkspaceMode, /v1/api reads plus SSE invalidation in local mode, and electric-proxy multiplayer shapes. · _docs/guides/sync.mdx_

### gateway-http-api


### human-inbox

- **Ask Human Blocking Request** (`smithers ask-human <prompt>`) — Raise a blocking human-approval request from inside a running workflow and wait for the decision. · _apps/cli/src/index.js: lines 4326-4459; docs/llms-observability.txt: ask_human tool_
- **Human Request Inbox Management** (`smithers human inbox|answer|cancel`) — List, answer, and cancel durable human requests via smithers human inbox|answer|cancel. · _apps/cli/src/index.js: lines 4189-4321_

### infrastructure

- **gateway** (`smithers gateway`) — Serve the multi-run Gateway RPC/WS control plane for workspace workflows (not tied to one run). · _llms.txt_
- **observability** (`smithers observability`) — Start local observability stack (Grafana, Prometheus, Tempo, OTLP) via Docker Compose. · _llms-observability.txt_

### integrations

- **Smithers as MCP Client** (`createMcpToolset`) — Use Smithers as a client to external MCP servers via createMcpToolset for SDK agents. · _docs/llms-integrations.txt: MCP Toolset section_

### knowledge


### mcp

- **MCP Ask Human Tool** (`ask_human`) — Block current run and ask human to make decision, wait for answer via MCP ask_human tool. · _docs/llms-observability.txt: ask_human tool reference_
- **MCP Explain Run Tool** (`explain_run`) — Return structured diagnosis explaining why a run is blocked, waiting, or stale via MCP explain_run. · _docs/llms-observability.txt: explain_run tool reference_
- **MCP Get Node Detail Tool** (`get_node_detail`) — Get enriched detail for a single node including attempts, tool calls, token usage, and scorer results. · _docs/llms-observability.txt: get_node_detail tool reference_
- **MCP List Pending Approvals Tool** (`list_pending_approvals`) — List human approvals waiting for decision, optionally filtered by run, workflow, or node. · _docs/llms-observability.txt: list_pending_approvals tool reference_
- **MCP List Workflows Tool** (`list_workflows`) — Discover and list all Smithers workflows available in working directory via MCP list_workflows tool. · _docs/llms-observability.txt: list_workflows tool reference_
- **MCP Resolve Approval Tool** (`resolve_approval`) — Approve or deny a pending human approval gate via MCP resolve_approval tool. · _docs/llms-observability.txt: resolve_approval tool reference_
- **MCP Revert Attempt Tool** (`revert_attempt`) — Revert workspace and frame history back to a specific attempt state (destructive) via MCP revert_attempt. · _docs/llms-observability.txt: revert_attempt tool reference_
- **MCP Run Workflow Tool** (`run_workflow`) — Start or resume a discovered workflow via MCP run_workflow tool with input, runId, and run options. · _docs/llms-observability.txt: run_workflow tool reference_
- **MCP Semantic Tools** (`semantic-surface`) — Stable structured tool set for MCP clients including list_workflows, run_workflow, watch_run, resolve_approval, ask_human, and more. · _docs/llms-observability.txt: Tool Reference section_
- **MCP Server via CLI** (`--mcp`) — Start Smithers as a Model Context Protocol stdio server with --mcp flag for AI agent control. · _docs/llms-observability.txt: MCP Server section_
- **MCP Watch Run Tool** (`watch_run`) — Poll a run at fixed interval until terminal state with timeout support via MCP watch_run tool. · _docs/llms-observability.txt: watch_run tool reference_

### memory

- **Fact storage (working memory)** (`store.setFact(ns, key, value, ttlMs?)`) — Namespace-scoped JSON fact storage with optional TTL, supporting get/set/delete/list operations across workflow, agent, user, and global scopes. · _llms-memory.txt_
- **Memory CLI listing** (`bunx smithers-orchestrator memory list`) — CLI command to inspect facts in a namespace for debugging and observability. · _llms-memory.txt_
- **Memory metrics** (`memoryFactReads, memoryFactWrites, memoryRecallQueries, memoryMessageSaves, memoryRecallDuration`) — Observability metrics: memoryFactReads, memoryFactWrites, memoryRecallQueries, memoryMessageSaves, memoryRecallDuration. · _llms-memory.txt_
- **Memory namespaces** (`MemoryNamespace { kind, id }`) — Four namespace kinds (workflow, agent, user, global) provide isolated scopes for facts and threads, matching lifetime semantics. · _llms-memory.txt_
- **Memory schema (Drizzle tables)** (`smithersMemoryFacts, smithersMemoryThreads, smithersMemoryMessages`) — SQLite schema tables for persistent storage: smithersMemoryFacts, smithersMemoryThreads, smithersMemoryMessages. · _**UNDOCUMENTED**_
- **Memory service (Effect)** (`MemoryService, createMemoryLayer(config)`) — Effect-ts service layer providing memory operations as effects: getFact, setFact, listFacts, createThread, saveMessage, countMessages. · _llms-memory.txt_
- **Memory store direct API** (`createMemoryStore(db)`) — Synchronous memory store with methods for fact, thread, and message operations: getFact, setFact, deleteFact, listFacts, createThread, saveMessage, listMessages, deleteExpiredFacts. · _llms-memory.txt_
- **Message history (threads)** (`store.createThread(ns, title?)`) — Ordered message threads per namespace supporting saveMessage, listMessages, countMessages, and thread lifecycle operations. · _llms-memory.txt_
- **Namespace string parsing** (`parseNamespace(str), namespaceToString(ns)`) — Utility functions to convert between MemoryNamespace objects and string representations with encoding (kind:id format). · _llms-memory.txt_
- **Summarizer processor** (`Summarizer(agent)`) — Memory maintenance processor that compresses old messages into summaries using an LLM agent, operates at thread level. · _llms-memory.txt_
- **TTL garbage collector processor** (`TtlGarbageCollector()`) — Memory maintenance processor that deletes facts past their TTL expiration, run periodically to clean up ephemeral working memory. · _llms-memory.txt_
- **Task memory persist metadata** (`memory={{ remember: { namespace, key } }}`) — Optional task metadata to persist task output as a fact: namespace and key fields store result in working memory across runs. · _llms-memory.txt_
- **Task memory recall metadata** (`memory={{ recall: { namespace, topK, query } }}`) — Optional task metadata for semantic recall: namespace, topK, and query fields to inject relevant past facts into prompts. · _llms-memory.txt_
- **Task message history metadata** (`memory={{ threadId }}`) — Optional task metadata to append agent conversation messages to a named thread for cross-run history. · _llms-memory.txt_
- **Token limiter processor** (`TokenLimiter(maxTokens)`) — Memory maintenance processor that trims message history to stay under token budget, operates at thread level. · _llms-memory.txt_
- **memory list** (`smithers memory list <namespace>`) — List all memory facts in a namespace. · _**UNDOCUMENTED**_

### monitoring

- **alerts** (`smithers alerts (list|ack|resolve|silence)`) — List and manage durable alert instances with actions: list, ack, resolve, silence. · _**UNDOCUMENTED**_

### observability

- **Correlation context (distributed tracing)** (`CorrelationContext, correlationContextFiberRef, withCorrelationContext, withCurrentCorrelationContext, getCurrentCorrelationContext`) — Fiber-local correlation context for tracing: userId, runId, traceId propagation across Effect tasks. · _?_
- **Gateway server (multi-workflow)** (`Gateway, gateway.register(), gateway.listen(), GatewayOptions, GatewayAuthConfig`) — Multi-workflow headless control plane with WebSocket RPC, event subscriptions, UI mounting, cron scheduling, and auth. · _?_
- **HTTP server (REST multi-workflow)** (`startServer, ServerOptions, /v1/runs, /v1/approvals, /metrics, /events`) — Node.js http-based multi-workflow REST server with bearer auth, SSE events, approval submission, and Prometheus metrics. · _?_
- **Metric definitions catalog** (`SmithersMetricDefinition, smithersMetricCatalog, toPrometheusMetricName`) — Typed metric registry: counter/gauge/histogram with unit, labels, boundaries; label cardinality safeguards and overflow protection. · _?_
- **Serve mode (single-workflow HTTP server)** (`createServeApp, bunx smithers-orchestrator up --serve, --port, --host, --auth-token, --metrics`) — Hono-based HTTP server for a single workflow: REST routes, SSE events, approvals, metrics, and health endpoint. · _?_
- **Smithers metrics system (Prometheus/OTLP)** (`renderPrometheusMetrics, prometheusContentType, smithersMetrics, MetricsService, MetricsServiceLive`) — In-process metrics registry with 100+ Prometheus counters/gauges/histograms for runs, nodes, timers, tokens, sandbox, DB, and networking. · _?_
- **Smithers observability service layer** (`SmithersObservability, createSmithersObservabilityLayer, createSmithersOtelLayer, resolveSmithersObservabilityOptions`) — Effect-based service for OpenTelemetry integration: span context, tracing, logging format (json/pretty/logfmt), and log-level configuration. · _?_
- **SmithersEvent Union Type** (`SmithersEvent, event.type`) — Tagged union of all runtime events: SupervisorStarted, RunStarted, NodePending, NodeStarted, TaskHeartbeat, TaskHeartbeatTimeout, NodeFinished, NodeFailed, ApprovalRequested, etc. · _apps/observability/src/SmithersEvent.ts_
- **Structured logging API** (`logDebug, logInfo, logWarning, logError, SmithersEvent, SmithersLogFormat`) — Structured event logging with configurable format (JSON, pretty, logfmt, string) and log level filtering. · _?_
- **chat** (`smithers chat [runId]`) — Show agent chat output for the latest run or a specific run with --follow option. · _llms.txt_
- **events** (`smithers events <runId>`) — Query run event history with --node filter, --type, --since, --limit, --group-by, and --watch. · _llms.txt_
- **inspect** (`smithers inspect <runId>`) — Output detailed run state including steps, agents, approvals, and outputs with optional --watch. · _llms.txt_
- **logs** (`smithers logs <runId>`) — Tail the event log of a specific run with --follow and --tail options. · _llms.txt_
- **node** (`smithers node <nodeId>`) — Show enriched node details for debugging retries, tool calls, and output with watch support. · _llms.txt_
- **why** (`smithers why <runId>`) — Explain why a run is currently blocked, paused, or waiting with actionable next steps. · _llms.txt_

### openapi-tools

- **API key authentication** (`auth: { type: 'apiKey', name, value, in }`) — Pass auth option { type: 'apiKey', name, value, in: 'header'|'query' } to add API key as header or query parameter to all tool requests. · _docs/llms-openapi.txt_
- **Base URL override** (`baseUrl: string`) — Pass baseUrl option to override the spec's default server URL for all tool requests. · _docs/llms-openapi.txt_
- **Basic authentication** (`auth: { type: 'basic', username, password }`) — Pass auth option { type: 'basic', username, password } to add Authorization: Basic header (base64 encoded) to all tool requests. · _docs/llms-openapi.txt_
- **Bearer token authentication** (`auth: { type: 'bearer', token }`) — Pass auth option { type: 'bearer', token: string } to add Authorization: Bearer header to all tool requests. · _docs/llms-openapi.txt_
- **Build combined operation schema** (`buildOperationSchema(parameters, requestBody, spec)`) — Exported buildOperationSchema(parameters, requestBody, spec) combines path/query/header parameters and request body into a single Zod schema for an operation. · _docs/llms-openapi.txt_
- **Custom request headers** (`headers: Record<string, string>`) — Pass headers option as Record<string, string> to add custom headers merged into every tool request. · _docs/llms-openapi.txt_
- **Extract operations from spec** (`extractOperations(spec)`) — Exported extractOperations(spec) parses an OpenAPI spec and returns ParsedOperation[] with operationId, method, path, parameters, and requestBody. · _docs/llms-openapi.txt_
- **JSON Schema to Zod conversion** (`jsonSchemaToZod(schema, spec, visited?)`) — Exported jsonSchemaToZod(schema, spec) converts OpenAPI JSON Schema objects to Zod schemas, supporting allOf/anyOf/oneOf, nullable fields, defaults, and constraints. · _docs/llms-openapi.txt_
- **Load spec from URL** (`createOpenApiTools('https://api.example.com/openapi.json')`) — Pass a URL (http:// or https://) to createOpenApiTools/loadSpecEffect to fetch and parse a remote OpenAPI spec. · _docs/llms-openapi.txt_
- **Load spec from local file** (`createOpenApiTools('./path/to/spec.yaml')`) — Pass a local file path (string) to createOpenApiTools/loadSpec functions to read and parse a YAML or JSON OpenAPI spec. · _docs/llms-openapi.txt_
- **Load spec from object** (`createOpenApiTools(specObject)`) — Pass a parsed OpenAPI spec object directly to createOpenApiTools; skips parsing and uses it immediately. · _docs/llms-openapi.txt_
- **Load spec from raw text** (`createOpenApiTools(jsonString)`) — Pass a raw JSON or YAML text string to createOpenApiTools/loadSpec functions; auto-detects format and parses without filesystem access. · _docs/llms-openapi.txt_
- **Load spec synchronously** (`loadSpecSync(input)`) — Exported loadSpecSync(input) synchronously loads a spec from a local file path or object; does not fetch URLs. · _docs/llms-openapi.txt_
- **Load spec with Effect** (`loadSpecEffect(input)`) — Exported loadSpecEffect(input) returns Effect.Effect<OpenApiSpec> that loads a spec from file, URL, or text with async/error handling. · _docs/llms-openapi.txt_
- **OpenAPI tool metrics** (`openApiToolCallsTotal | openApiToolCallErrorsTotal | openApiToolDuration`) — Exported Effect metrics: openApiToolCallsTotal (counter), openApiToolCallErrorsTotal (counter), openApiToolDuration (histogram) for observability. · _docs/llms-openapi.txt_
- **Operation filtering (include/exclude)** (`include: string[] | exclude: string[]`) — Pass include/exclude arrays of operationIds to allowlist or blocklist specific operations; exclude wins if both are set. · _docs/llms-openapi.txt_
- **Path containment enforcement** (`resolveToolPath(rootDir, inputPath)`) — All file-accessing tools enforce --root containment: paths are validated against rootDir, symlink targets are checked, and escape attempts throw TOOL_PATH_ESCAPE error. · _packages/sandbox/src/sandboxPath.js_
- **Tool name prefix** (`namePrefix: string`) — Pass namePrefix option to prepend a prefix to generated tool names without changing the operationIds used for filtering. · _docs/llms-openapi.txt_
- **createOpenApiTool (async)** (`createOpenApiTool(input, operationId, options?)`) — Async function to create a single AI SDK tool for a specific operationId from an OpenAPI spec. · _docs/llms-openapi.txt_
- **createOpenApiToolSync (sync)** (`createOpenApiToolSync(input, operationId, options?)`) — Synchronous variant to create a single tool for a specific operationId (local files and objects only). · _docs/llms-openapi.txt_
- **createOpenApiTools (async)** (`createOpenApiTools(input, options?)`) — Async function that parses an OpenAPI spec and returns a record of AI SDK tools keyed by operationId. · _docs/llms-openapi.txt_
- **createOpenApiToolsSync (sync)** (`createOpenApiToolsSync(input, options?)`) — Synchronous variant of createOpenApiTools that works with local files and spec objects (not URLs). · _docs/llms-openapi.txt_
- **listOperations** (`listOperations(input)`) — List all operationIds and their metadata (method, path, summary) from an OpenAPI spec without creating tools. · _docs/llms-openapi.txt_
- **smithers openapi list CLI command** (`smithers openapi list <spec-path>`) — CLI command to preview tools that would be generated from an OpenAPI spec, listing each operationId with method, path, and summary. · _apps/cli/src/index.js_

### ops

- **Cron Schedule Management** (`smithers cron add|list|rm|start`) — Register, list, and manage background cron schedules for workflow automation via smithers cron commands. · _apps/cli/src/index.js: lines 2265-2328_
- **Gateway Cron RPC Methods** (`cronList|cronCreate|cronDelete|cronRun`) — RPC methods cronList, cronCreate, cronDelete, cronRun for programmatic cron management via Gateway. · _docs/llms-observability.txt: Gateway RPC methods section_
- **Hijack Agent Session** (`smithers hijack <run-id>`) — Hand off the latest resumable agent session or conversation for a run to native CLI. · _apps/cli/src/index.js: lines 3824-3972; docs/llms-integrations.txt: Hijack handoff section_
- **Native Agent Hijack Engines** (`claude-code|codex|agy|gemini|pi|kimi|forge|amp`) — Support for hijacking sessions across multiple agent CLIs: Claude Code, Codex, Antigravity, Gemini, Pi, Kimi, Forge, Amp. · _apps/cli/src/hijack.js; docs/llms-integrations.txt: Hijack handoff table_
- **Signal Delivery to Runs** (`smithers signal <run-id> <signal-name>`) — Deliver a durable named signal to a run waiting on Signal or WaitForEvent components. · _apps/cli/src/index.js: lines 4651-4712; docs/llms-observability.txt: submitSignal RPC_
- **Supervisor Watch Loop** (`smithers supervise`) — Watch for stale running runs and auto-resume them in background with configurable thresholds. · _apps/cli/src/index.js: lines 3170-3219_

### optimize

- **GEPA optimizer provider selection** (`-`) — Choose optimizer: heuristic, cerebras, openai, anthropic, gemini, or openai-compatible with provider-specific config. · _?_
- **Heuristic GEPA optimizer** (`-`) — Uses metadata.promptPatches or metadata.optimizationHints from cases to generate prompt patches without calling an LLM. · _?_
- **Optimize command with thresholds** (`-`) — Optimize with --minImprovement, --provider, --model, --artifact, --reportDir, and concurrency options. · _?_

### orchestration

- **Agent fallback pools** (`-`) — Named agent pools in .smithers/agents.ts that define fallback chains (e.g. cheapFast, smart, smartTool) for automatic agent selection and failover. · _?_
- **Fallback chains** (`-`) — When a task specifies a pool of agents, Smithers automatically retries with the next agent if the current agent fails, enabling graceful degradation. · _?_

### output-handling

- **Output format selection** (`-`) — CLI agents support multiple output formats (text, json, stream-json) to control how progress and results are streamed and parsed. · _?_
- **Structured output (JSON schema)** (`-`) — CLI agents support outputSchema parameter; SDK agents support via native structured-output APIs (AnthropicAgent, OpenAIAgent) or Zod schema output. · _?_

### patterns

- **CheckSuite** (`<CheckSuite>`) — Parallel checks with auto-aggregated pass/fail verdict. · _docs/components/check-suite.mdx_
- **ClassifyAndRoute** (`<ClassifyAndRoute>`) — Classify items into categories, then route each to a category-specific agent in parallel. · _docs/components/classify-and-route.mdx_
- **ContentPipeline** (`<ContentPipeline>`) — Typed waterfall of refinement stages, each depending on the previous. · _docs/components/content-pipeline.mdx_
- **Debate** (`<Debate>`) — Adversarial multi-round debate between proposer and opponent, then judge verdict. · _docs/components/debate.mdx_
- **DecisionTable** (`<DecisionTable>`) — Flat rule table that replaces nested Branch trees with declarative routing. · _docs/components/decision-table.mdx_
- **DriftDetector** (`<DriftDetector>`) — Capture state, compare against a baseline, and alert on meaningful drift. · _docs/components/drift-detector.mdx_
- **EscalationChain** (`<EscalationChain>`) — Sequential agent escalation with optional human fallback. · _docs/components/escalation-chain.mdx_
- **GatherAndSynthesize** (`<GatherAndSynthesize>`) — Parallel gather from multiple sources, then synthesize into a unified result. · _docs/components/gather-and-synthesize.mdx_
- **Kanban** (`<Kanban>`) — Process items through ordered columns with a pluggable ticket source. · _docs/components/kanban.mdx_
- **LoopUntilScored** (`<LoopUntilScored>`) — Re-run children until the latest output's score crosses a threshold, or maxIterations is hit. · _docs/components/loop-until-scored.mdx_
- **Optimizer** (`<Optimizer>`) — Generate, evaluate, and improve in a loop until a target score is reached. · _docs/components/optimizer.mdx_
- **Panel** (`<Panel>`) — Parallel specialist agents review the same input; a moderator synthesizes results. · _docs/components/panel.mdx_
- **Poller** (`<Poller>`) — Poll an external condition with configurable backoff until satisfied or timed out. · _docs/components/poller.mdx_
- **ReviewLoop** (`<ReviewLoop>`) — Produce, review, and fix in a loop until the reviewer approves. · _docs/components/review-loop.mdx_
- **Runbook** (`<Runbook>`) — Sequential steps with risk classification; safe auto-runs, risky/critical gate on approval. · _docs/components/runbook.mdx_
- **Saga** (`<Saga>`) — Forward steps with compensations run in reverse on failure. · _docs/components/saga.mdx_
- **ScanFixVerify** (`<ScanFixVerify>`) — Scan for problems, fix in parallel, verify, then report in a retry loop. · _docs/components/scan-fix-verify.mdx_
- **Supervisor** (`<Supervisor>`) — Boss plans, workers run in parallel, boss reviews and re-delegates failures. · _docs/components/supervisor.mdx_

### project-setup

- **init** (`smithers init`) — Install the local Smithers workflow pack into .smithers/ directory. · _llms.txt_

### run-control

- **cancel** (`smithers cancel <runId>`) — Safely halt agents and terminate a run. · _llms.txt_
- **down** (`smithers down`) — Cancel all active runs. Like 'docker compose down' for workflows. · _llms.txt_
- **signal** (`smithers signal <runId> <signalName>`) — Deliver a durable signal to a run waiting on <Signal> or <WaitForEvent>. · _llms.txt_

### runtime-concepts

- **Agent Output Validation Retries** (`retries prop, validation failure`) — Agent output validation failures trigger retry attempts; agents self-correct on schema drift without consuming manual retry budget. · _docs/how-it-works.mdx_
- **Idempotency Key for Side-Effect Tools** (`ctx.idempotencyKey, defineTool sideEffect`) — Mark tools with sideEffect: true and use ctx.idempotencyKey so retries don't double-fire the same operation. · _docs/how-it-works.mdx_
- **Input Immutability** (`ctx.input`) — ctx.input is immutable and persisted at first run. Resuming with different --input is an error. · _docs/how-it-works.mdx_
- **Task Caching with Auto-Invalidation** (`Task cache prop, cache.by, cache.version`) — Per-task caching with cache key = cache.by(ctx) + cache.version + schema signature (SHA-256). Schema changes auto-invalidate; use for pure work only. · _docs/how-it-works.mdx_

### runtime-core

- **EngineDecision Union Type** (`EngineDecision, _tag property`) — Tagged union of scheduler decisions: Execute (run tasks), ReRender (render with new context), Wait (pause for event), ContinueAsNew (close and restart), Finished, Failed. · _packages/scheduler/src/index.d.ts_
- **Frame as Unit of Progress** (`GraphSnapshot, frameNo`) — Every frame is a snapshot of (state → plan); frames are the unit for time travel, observability, hot reload, and resume. · _docs/how-it-works.mdx_
- **Graph Snapshot Extraction** (`GraphSnapshot, TaskDescriptor`) — Runtime walks the rendered JSX tree to produce a GraphSnapshot: flat list of TaskDescriptors capturing node id, dependencies, output schema, agent, retries, timeouts. · _docs/how-it-works.mdx_
- **Pure Function Render Model** (`WorkflowDefinition.build(ctx)`) — Render function is a pure function of ctx (which reads SQLite). Plan is derived from persisted state; no mutation, no refs, no useState for durable values. · _docs/how-it-works.mdx_
- **Render-Execute-Persist Loop** (`WorkflowDriver.run(), EngineDecision`) — The fundamental cycle that powers Smithers: render the workflow tree, extract ready tasks, execute them, persist outputs to SQLite, and re-render against the new state. · _docs/how-it-works.mdx_
- **Scheduler Service** (`Scheduler, schedule(), ScheduleResult`) — Computes the ready set from the plan: tasks whose dependencies completed, whose enclosing sequence reached them, whose enclosing branch resolved them, and which fit within maxConcurrency. · _packages/scheduler/src/index.d.ts_
- **Task State Machine** (`TaskState type, getTaskStates()`) — Task states: pending, waiting-approval, waiting-event, waiting-timer, in-progress, finished, failed, cancelled, skipped. Transitions driven by task completion, approval, timeout, or scheduler decisions. · _packages/scheduler/src/TaskState.ts_
- **Workflow Session Service** (`WorkflowSession, makeWorkflowSession()`) — Effect-based service that orchestrates task lifecycle: submitGraph, taskCompleted, taskFailed, approvalResolved, eventReceived, signalReceived, hotReloaded, etc. · _packages/scheduler/src/index.d.ts_

### sandboxing

- **<Sandbox>** (`<Sandbox id={string} provider? runtime? workflow? input? output>`) — React component that executes a child workflow through an injectable sandbox provider with optional networking, volume mounts, custom images, and egress config. · _?_
- **Freestyle Sandbox Adapter** (`createFreestyleSandboxProvider`) — Pluggable provider adapter that creates Freestyle VMs, writes request/setup files, execs commands, reads result JSON, enabling real VMs as sandboxes. · _?_
- **Sandbox Diff Review** (`reviewDiffs, autoAcceptDiffs`) — Human-in-the-loop review and auto-acceptance of file changes produced by sandbox execution. · _?_
- **Sandbox Egress Config** (`egress: SandboxEgressConfig`) — HTTP/HTTPS proxy, CA certificates, and secret bindings for sandbox outbound connections. · _?_
- **Sandbox Network** (`allowNetwork: boolean`) — Network access control for sandboxes via allowNetwork prop; denied by default, enabled per-sandbox. · _?_
- **Sandbox Volume Mounts** (`volumes: SandboxVolumeMount[]`) — Host directory binding into sandbox containers via volumes prop with {host, container, readonly?} specifications. · _?_
- **Sandbox Workspace Spec** (`workspace: SandboxWorkspaceSpec`) — jj workspace configuration inside a sandbox with name, snapshot restoration, idle timeout, and persistence mode. · _?_
- **SandboxProvider** (`SandboxProvider, registerSandboxProvider, resolveSandboxProvider`) — Pluggable interface for sandbox execution: {id, run(request), cleanup?(request)} for local/remote VM/Docker/Freestyle implementations. · _?_
- **SandboxProvider Interface** (`SandboxProvider`) — Contract for sandbox implementations: {id, run(request), cleanup?(request)} where run receives request with rootDir/workflow/input and returns {bundlePath} or {status, output, diffBundle, patches}. · _?_
- **SandboxRuntime** (`runtime: 'bubblewrap' | 'docker' | 'codeplane'`) — Process isolation runtime for sandboxes: bubblewrap (Linux), docker (OCI containers), or codeplane (cloud VMs). · _?_

### scheduling

- **cron add** (`smithers cron add <pattern> <workflowPath>`) — Register a new workflow cron schedule with pattern and workflow path. · _**UNDOCUMENTED**_
- **cron list** (`smithers cron list`) — List all registered background cron schedules. · _**UNDOCUMENTED**_
- **cron rm** (`smithers cron rm <cronId>`) — Delete an existing cron schedule by ID. · _**UNDOCUMENTED**_
- **cron start** (`smithers cron start`) — Start background scheduler loop in current terminal. · _**UNDOCUMENTED**_

### scorers

- **Aggregate scorer statistics** (`-`) — Computes aggregate statistics (count, mean, min, max, p50, stddev) for scorer results across runs. · _?_
- **Attach scorers to Task in JSX** (`-`) — Use the scorers={} prop on Task to bind multiple named scorers with individual sampling configs. · _?_
- **Faithfulness scorer (builtin)** (`-`) — LLM-based scorer that checks output is faithful to provided context without hallucinations. · _?_
- **Filter options for aggregateScores** (`-`) — Options to filter aggregate statistics by runId, nodeId, or scorerId. · _?_
- **Latency scorer (builtin)** (`-`) — Scores execution time with linear interpolation between a target and maximum latency threshold. · _?_
- **Named scorer binding with sampling** (`-`) — Maps a named key to a Scorer and optional SamplingConfig, used in Task scorers prop. · _?_
- **Relevancy scorer (builtin)** (`-`) — LLM-based scorer that evaluates whether output addresses and is relevant to the input prompt. · _?_
- **Schema adherence scorer (builtin)** (`-`) — Validates task output against Zod schema, returning 1.0 if valid or 0.0 with validation errors. · _?_
- **Scorer event metrics** (`-`) — Observable metrics: scorersStarted, scorersFinished, scorersFailed, scorerDuration for monitoring scorer execution. · _?_
- **Scorer execution context type** (`-`) — Runtime context passed to scorer functions: runId, nodeId, iteration, attempt, input, output, latencyMs, outputSchema. · _?_
- **Scorer sampling configuration** (`-`) — Controls how often a scorer runs: 'all', 'ratio', or 'none' types to optimize expensive evaluations. · _?_
- **Toxicity scorer (builtin)** (`-`) — LLM-based scorer that detects toxic, harmful, offensive, or inappropriate content in output. · _?_
- **createScorer factory** (`-`) — Creates a custom scorer from a configuration object with id, name, description, and score function. · _?_
- **llmJudge factory** (`-`) — Creates an LLM-as-judge scorer that delegates evaluation to an AI agent and parses JSON responses. · _?_

### sdk-agents

- **anthropic provider import** (`import { anthropic } from '@ai-sdk/anthropic'`) — SDK provider for AnthropicAgent allowing direct model references like anthropic('claude-opus-4'). · _?_
- **openai provider import** (`import { openai } from '@ai-sdk/openai'`) — SDK provider for OpenAIAgent supporting model strings and createOpenAI() factory for custom baseURL/apiKey. · _?_

### security

- **Permission and approval modes** (`-`) — Agent-specific permission handling: yolo (skip all), permissionMode flags (bypassPermissions, plan, etc.), dangerouslySkipPermissions, approvalMode, dangerouslyAllowAll. · _?_
- **Yolo mode** (`-`) — yolo: true (default) auto-approves all tool calls, mapping to vendor-specific skip-permissions flags; disable for tighter control. · _?_

### skills

- **Workflow Skills Generation** (`smithers workflow skills`) — Generate agent-facing skill documentation files for local workflows via smithers workflow skills. · _apps/cli/src/index.js: lines 2126-2168_

### testing-evaluation

- **eval** (`smithers eval <workflow>`) — Run a workflow over a JSON/JSONL eval suite and write regression report. · _llms.txt_
- **optimize** (`smithers optimize <workflow>`) — Run GEPA prompt optimization over an eval suite and write optimized prompt artifact. · _llms.txt_
- **scores** (`smithers scores <runId>`) — View scorer results for a specific run, optionally filtered by --node. · _**UNDOCUMENTED**_

### time-travel

- **Branch metadata record** (`BranchInfo type`) — Records parentRunId, parentFrameNo, branch label, and fork description for a forked run. · _/packages/time-travel/src/BranchInfo.ts_
- **Capture workflow snapshot** (`captureSnapshot(adapter, runId, frameNo, snapshotData)`) — Capture durable snapshot of nodes, outputs, inputs, and loops at each execution frame for time-travel. · _/packages/time-travel/src/snapshot/index.js_
- **Fork operation with branch metadata** (`forkRun(adapter, ForkParams)`) — Programmatic fork: creates child run from snapshot with branch label, input overrides, and node resets. · _/packages/time-travel/src/fork/index.js_
- **Full time-travel with reset** (`timeTravel(adapter, TimeTravelOptions)`) — High-level time-travel: revert attempt, reset nodes, and optionally restore VCS to specific revision. · _/packages/time-travel/src/timetravel.js_
- **Jump to frame (rewind)** (`jumpToFrame(input: JumpToFrameInput)`) — Core rewind mechanism: validates runId/frameNo, acquires lock, reverts VCS sandboxes, deletes future frames and attempts. · _/packages/time-travel/src/jumpToFrame.js_
- **Load snapshot by frame** (`loadSnapshot(adapter, runId, frameNo), loadLatestSnapshot(adapter, runId)`) — Retrieve a serialized snapshot for a specific frame or the latest frame of a run. · _/packages/time-travel/src/snapshot/index.js_
- **Replay operation with VCS restore** (`replayFromCheckpoint(adapter, ReplayParams)`) — Programmatic replay: fork a snapshot and optionally restore VCS working copy to original revision. · _/packages/time-travel/src/replay.js_
- **Retry task operation** (`retryTask(adapter, RetryTaskOptions)`) — Reset node and dependents to pending, cancel in-flight attempts, clear outputs, and resume run. · _/packages/time-travel/src/retry-task.js_
- **Revert to node attempt** (`revertToAttempt(adapter, RevertOptions)`) — Restore workspace to a specific node attempt's filesystem state via jj and discard frames after it. · _/packages/time-travel/src/revert.js_
- **Rewind audit trail** (`writeRewindAuditRow, listRewindAuditRows, updateRewindAuditRow`) — Persistent audit log of all rewind operations with status (success/failed/partial/in_progress). · _/packages/time-travel/src/rewindAudit.js_
- **Rewind concurrency lock** (`acquireRewindLock(runId), hasRewindLock(runId)`) — Mutual exclusion lock preventing concurrent rewinds on the same run. · _/packages/time-travel/src/rewindLock.js_
- **Rewind rate limiter** (`evaluateRewindRateLimit(runId, windowMs, maxPerWindow)`) — Rate limit enforcement: default 10 rewinds per hour per caller, configurable window. · _/packages/time-travel/src/rewindRateLimit.js_
- **Structured snapshot diff** (`diffSnapshots(a, b), SnapshotDiff type`) — SnapshotDiff captures added/removed/changed nodes, outputs, loops, input changes, and VCS pointer changes. · _/packages/time-travel/src/diff.js_
- **Timeline frames and tree** (`buildTimeline(adapter, runId), buildTimelineTree(adapter, runId)`) — BuildTimeline returns flat list of frames with fork points; buildTimelineTree returns recursive tree of run and descendants. · _/packages/time-travel/src/timeline/index.js_
- **VCS-tagged snapshot** (`tagSnapshotVcs(adapter, runId, frameNo, vcsPointer)`) — Tag a snapshot with its VCS revision and enable reverting to that exact version. · _/packages/time-travel/src/vcs-version/index.js_
- **fork** (`smithers fork <workflow>`) — Create a branched run from a snapshot checkpoint with optional --run to auto-start. · _**UNDOCUMENTED**_
- **replay** (`smithers replay <workflow>`) — Fork from a checkpoint and resume execution with input overrides. · _**UNDOCUMENTED**_
- **retry-task** (`smithers retry-task <workflow>`) — Retry a specific task within a run, optionally skipping dependents with --no-deps. · _**UNDOCUMENTED**_
- **revert** (`smithers revert <workflow>`) — Revert the workspace to a previous task attempt's filesystem state. · _**UNDOCUMENTED**_
- **rewind** (`smithers rewind <runId> <frameNo>`) — Rewind a run to a previous frame without executing. · _**UNDOCUMENTED**_
- **timeline** (`smithers timeline <runId>`) — View execution timeline for a run and its forks with optional --tree recursion. · _**UNDOCUMENTED**_
- **timetravel** (`smithers timetravel <workflow>`) — Time-travel to a previous task state by reverting filesystem and DB, optionally resuming. · _**UNDOCUMENTED**_

### tool-context

- **getToolContext()** (`getToolContext()`) — Get the ambient AsyncLocalStorage-based tool execution context (run/node/cwd/auth/limits) set by runWithToolContext(). · _packages/tool-context/src/toolContext.js_
- **getToolIdempotencyKey()** (`getToolIdempotencyKey(ctx?)`) — Generate or return an idempotency key for tool requests from context: 'smithers:<runId>:<nodeId>:<iteration>' or custom idempotencyKey field. · _packages/tool-context/src/toolContext.js_
- **nextToolSeq()** (`nextToolSeq(ctx)`) — Increment and return a sequence counter in the tool context for ordering or versioning tool calls within a run/node. · _packages/tool-context/src/toolContext.js_
- **runWithToolContext()** (`runWithToolContext(ctx, fn)`) — Set the ambient tool execution context via AsyncLocalStorage so tool execute() functions can access run/node/idempotency context across awaits. · _packages/tool-context/src/toolContext.js_

### ui

- **gui** (`smithers gui [path]`) — Open a directory as a workspace in Smithers GUI macOS app. · _**UNDOCUMENTED**_
- **ui** (`smithers ui [runId]`) — Open custom UI for a workflow run in browser, auto-starting Gateway if needed. · _llms.txt_

### vcs

- **<Worktree>** (`<Worktree path={string} branch? baseBranch? id? skipIf?>`) — React component that runs a subtree in an isolated git or jj worktree rooted at a filesystem path. · _?_
- **Binary Resolution** (`resolveJjBinary, resolveGitBinary, ResolvedBinary`) — Executable discovery for jj and git: env override (SMITHERS_JJ_PATH/SMITHERS_GIT_PATH), bundled packages, then PATH. · _?_
- **Jj Pointer** (`getJjPointer, revertToJjPointer`) — A jj change_id that identifies a stable point in worktree history for durable restore and cache invalidation. · _?_
- **Supervisor Per-Agent Worktrees** (`useWorktrees: boolean`) — When useWorktrees={true}, Supervisor places each worker in .worktrees/{prefix}-worker-{type} on branch worker/{prefix}-worker-{type} for isolated parallel work. · _?_
- **Worktree + MergeQueue Pattern** (`<Worktree><Task/><MergeQueue><Task/></MergeQueue></Worktree>`) — Fan-out work across multiple isolated worktrees, each with sequential build/test/apply steps in MergeQueue, enabling per-worktree parallelism with bounded merges. · _?_
- **Worktree Path Access** (`ctx.worktreePath, ctx.resolveWorktreePath`) — Read the resolved absolute worktree path in a task using ctx.worktreePath(taskId) or ctx.resolveWorktreePath(pathProp). · _?_
- **captureWorkspaceSnapshot()** (`captureWorkspaceSnapshot(cwd?)`) — Capture a worktree's current state as {commitId, changeId, operationId} for time-travel and durability. · _?_
- **findVcsRoot()** (`findVcsRoot(startDir)`) — Detect the nearest .jj or .git directory, preferring jj for colocated repos, returning {type, root} or null. · _?_
- **isJjRepo()** (`isJjRepo(cwd?)`) — Detect whether a directory is a readable jj repository via 'jj --version' execution. · _?_
- **jj Snapshot Behavior** (`jj diff --from <baseBranch> --to @`) — jj continuously snapshots working-copy edits onto its bookmark; dirty-state detection via git status appears clean; instead use jj diff or git diff against baseBranch. · _?_
- **revertToJjPointer()** (`revertToJjPointer(pointer, cwd?)`) — Restore a worktree's working copy to a previously recorded jj change_id using 'jj restore --from <pointer>'. · _?_
- **runJj()** (`runJj(args, opts?)`) — Execute an arbitrary jj command and capture {code, stdout, stderr}; safe to call when jj is missing. · _?_
- **vcsToolingStatus()** (`vcsToolingStatus(): VcsToolingStatus`) — Synchronous best-effort probe for usable jj and/or git executables, returning {jj, git, ok}. · _?_
- **workspaceAdd()** (`workspaceAdd(name, path, opts?)`) — Create a new jj workspace at a filesystem path with a friendly name, optionally at a specific revision. · _?_
- **workspaceClose()** (`workspaceClose(name, opts?)`) — Close a jj workspace by name, cleaning up associated metadata and directories. · _?_
- **workspaceList()** (`workspaceList(cwd?)`) — List existing jj workspaces in a repo with structured output, falling back to parsing if -T template is unavailable. · _?_

### workflow-authoring

- **workflow create** (`smithers workflow create <name>`) — Create a new workflow scaffold in .smithers/workflows or globally with --global. · _llms.txt_
- **workflow inspect** (`smithers workflow inspect <name>`) — Show workflow metadata, input schema, and agent-facing skill preview. · _llms.txt_
- **workflow skills** (`smithers workflow skills [name]`) — Generate agent-facing skill docs for local workflows and write .md files. · _llms.txt_

### workflow-discovery

- **starters** (`smithers starters [id]`) — Show plain-English starter workflows with copy-paste commands. · _llms.txt_
- **workflow doctor** (`smithers workflow doctor [name]`) — Inspect workflow discovery, preload files, VCS status, and detected agents. · _llms.txt_
- **workflow list** (`smithers workflow list`) — List all discovered local workflows in the current project. · _llms.txt_
- **workflow path** (`smithers workflow path <name>`) — Resolve a workflow ID to its entry file path. · _llms.txt_

### workflow-execution

- **up** (`smithers up [workflow]`) — Start a workflow execution with optional detached mode (-d), resumable run ID, and input. · _llms.txt_
- **workflow run** (`smithers workflow run <name>`) — Execute a discovered workflow by ID with optional input, detached mode, and concurrency controls. · _llms.txt_

### workflow-integration

- **Task agent routing** (`-`) — Workflows route tasks to named agent pools from agents.ts for automatic model selection, fallback, and per-task optimization. · _?_

### workflow-monitoring

- **monitor** (`smithers monitor [runId]`) — Open the Smithers Monitor, the gateway-served live web UI over every run in the workspace (pure observation: launches no run, workflow, or agents). · _llms.txt_
- **ps** (`smithers ps`) — List active, paused, and recently completed runs with optional --watch polling. · _llms.txt_
- **supervise** (`smithers supervise`) — Watch for stale running runs and auto-resume them at configurable intervals. · _llms.txt_

### workflows

- **Create Skill (Seeded Workflow)** (`.smithers/workflows/create-skill.tsx`) — Guided agent-driven skill authoring: clarify capability → design doc structure → scaffold SKILL.md → verify → document. · _.smithers/workflows/create-skill.tsx_
- **Create Workflow (Seeded Workflow)** (`.smithers/workflows/create-workflow.tsx`) — Guided agent-driven workflow authoring: clarify intent → provision docs/skills → design → approve → scaffold → verify → document. · _.smithers/workflows/create-workflow.tsx (entire file)_
- **Seeded Workflow Pack** (`.smithers/workflows/*.tsx`) — 61 pre-built workflow templates covering research, planning, review, approval, monitoring, and multi-agent patterns. · _.smithers/workflows/ directory_

