# Smithers


> Smithers instruments and automates a code repository so changes get cheaper, faster, and smarter. Agents plan, run, and review changes through flows declared beside the code.


## Start here

- [Welcome to Smithers](https://smithers.sh/docs/): Smithers instruments and automates a code repository so changes get cheaper, faster, and smarter. Agents plan, run, and review changes through flows declared beside the code.
- [Quickstart](https://smithers.sh/docs/quickstart/): Open Smithers, explore a repository, find a flow, and make your first contribution through the app.
- [Pricing](https://smithers.sh/docs/pricing/): The hosted Smithers alpha is free for selected public repositories. Compare hosted access with running the open-source tools yourself.
- [CLI and libraries](https://smithers.sh/docs/developers/): Use Smithers from your terminal, define flows beside your code, and build on the TypeScript libraries.
- [Installation](https://smithers.sh/docs/installation/): Install the Smithers CLI or library, keep Effect pinned, and verify the install.
- [CLI quickstart](https://smithers.sh/docs/cli-quickstart/): Install the CLI, scaffold a flow, choose its model, and run it in your project.

## Use the app

- [The interface](https://smithers.sh/docs/app/): Find your way around the Smithers app: repositories, chat, cards, and the six main areas.
- [Open a repository](https://smithers.sh/docs/app/repositories/): Open an available repository and choose whether to explore, contribute, or maintain it.
- [Talk to Smithers](https://smithers.sh/docs/app/chat/): Describe a task, inspect the cards in the conversation, and steer work while it runs.
- [Search the app](https://smithers.sh/docs/app/search/): Use the command palette to find files, flows, notes, and other project information.
- [Read and edit the Wiki](https://smithers.sh/docs/app/wiki/): Open project notes, follow their sources, and understand the difference between notes and a generated repository wiki.
- [Inspect the Dispatcher](https://smithers.sh/docs/app/dispatcher/): Read automation rules and distinguish declared events from triggers registered on a running box.
- [Run a flow](https://smithers.sh/docs/app/flows/): Choose a repository flow in the app, supply its inputs, and inspect the run that starts.
- [Inspect and steer a run](https://smithers.sh/docs/app/runs/): Follow a flow's status, inspect its execution trace, send a correction, and stop or resume work.
- [Work in a box](https://smithers.sh/docs/app/boxes/): Open a cloud box, inspect its files and terminal, and use its services and snapshots.
- [Review an approval](https://smithers.sh/docs/app/approvals/): Inspect a requested action and approve or deny it from the Smithers conversation.
- [Review a change](https://smithers.sh/docs/app/changes/): Inspect a Change's diff, checks, reviews, and revisions before landing it.
- [Repository secrets](https://smithers.sh/docs/app/secrets/): Inspect the scope and metadata of secrets available to a repository's sessions.
- [Explore History](https://smithers.sh/docs/app/history/): Read the repository's mythical history and distinguish it from run history and Change revisions.
- [Account and access](https://smithers.sh/docs/app/account/): Sign in with GitHub, check your alpha access, and understand what the Account card shows.
- [Troubleshoot the app](https://smithers.sh/docs/app/troubleshooting/): Resolve sign-in, access, box, search, and run problems in the Smithers app.

## Tutorials

- [Run a target and hit the cache](https://smithers.sh/docs/tutorials/first-target/): Declare a file input and a test target, run it twice, then change the input to see the target execute again.
- [Build your first durable flow](https://smithers.sh/docs/tutorials/first-flow/): Declare an action and a flow, attach an implementation, and run the flow in memory and durably over SQLite.
- [Crash and resume a run](https://smithers.sh/docs/tutorials/crash-and-resume/): Suspend a durable run at a wait, drop the engine, and resume from durable state without re-executing recorded steps.
- [Retry a flaky action](https://smithers.sh/docs/tutorials/retry-policy/): Declare a retry policy, inspect its backoff ladder, and retry an action that fails twice before it succeeds.
- [Add a human approval](https://smithers.sh/docs/tutorials/human-approval/): Park a durable run on a HumanTask question, refuse an answer within the attempt budget, and answer it to completion.
- [Fork and rewind a run](https://smithers.sh/docs/tutorials/time-travel/): Fork a finished run at a journal frame, drive the copy to a different outcome, and rewind a run to an earlier frame.
- [Build your first agent flow](https://smithers.sh/docs/tutorials/first-agent-flow/): Author a markdown agent flow, run it with smthrs up, then give a model-backed step real tools and a sandbox.
- [Pass typed outputs between agent steps](https://smithers.sh/docs/tutorials/agent-outputs/): Declare output schemas on model-backed steps, chain one step's typed output into the next, and read the recorded outputs back.
- [Remember facts across runs](https://smithers.sh/docs/tutorials/memory/): Record facts in one run, recall them in a later run under one memory policy, and inspect the namespace with the CLI.

## How-to guides

- [Guides](https://smithers.sh/docs/guides/): Choose a task: author a flow, run it, connect an agent, or operate persistent runs.
- [Run selected and affected targets](https://smithers.sh/docs/guides/build-targets/): Choose target kinds and labels, preview work, and run only the targets affected by a change.
- [Write a markdown flow](https://smithers.sh/docs/guides/markdown-flows/): Scaffold a flow.mdx with smthrs init, write its frontmatter and prose instructions, and run it with smthrs flow start.
- [Share target results between machines](https://smithers.sh/docs/guides/remote-cache/): Configure a remote target cache, separate read and write credentials, and verify reuse from a second checkout.
- [Write a module flow](https://smithers.sh/docs/guides/module-flows/): Define typed actions and a flow in TypeScript, provide their implementations, and execute the program.
- [Organize flows in a project](https://smithers.sh/docs/guides/flow-discovery/): Lay out flows/ sources and .flows/ state, control how flow ids are derived, and resolve which project root a command acts on.
- [Plan, approve, and run a flow](https://smithers.sh/docs/guides/plan-approve-run/): Inspect a flow's plan, approve its exact payload, launch it, and resume a run waiting for approval.
- [Cancel, signal, and steer a run](https://smithers.sh/docs/guides/steering/): Pick the right verb to intervene in a live run: cancel to stop it, signal to complete a named wait, steer to message the agent.
- [Inspect runs](https://smithers.sh/docs/guides/inspecting-runs/): Find a run, read its diagnosis, follow events, and retrieve recorded outputs with the runs commands.
- [Configure model seats and providers](https://smithers.sh/docs/guides/model-seats/): Set the provider keys a flow's model seat resolves from, choose how OpenAI seats authenticate, and change the seat a flow runs on.
- [Set quotas, budgets, and corrections for agents](https://smithers.sh/docs/guides/agent-policies/): Bound what an agent run spends, park runs through provider quota windows, and give schema-enforced steps a correction budget.
- [Give a flow tools](https://smithers.sh/docs/guides/tools/): Call the std tool library from a module flow, attach external MCP servers with --mcp-config or SMITHERS_MCP_CONFIG, and grant the capabilities the tools declare.
- [Drive Smithers from your agent](https://smithers.sh/docs/guides/mcp-setup/): Connect an MCP client to Smithers, discover its tools, and verify access to the intended project.
- [Declare and grant capabilities](https://smithers.sh/docs/guides/capabilities/): Declare the host authority a flow needs in its frontmatter, grant it with smthrs approvals approve --scope, and read the typed denial when a run exceeds its grant.
- [Run work in a sandbox](https://smithers.sh/docs/guides/sandboxes/): Compose a sandbox provider to place one action's host services, or a whole child flow, on a provisioned machine.
- [Wait durably: sleep, poll, deferreds, queues](https://smithers.sh/docs/guides/durable-waits/): Pick the durable wait primitive that matches what you are waiting for, and compose it so the wait survives a process restart.
- [Compose child flows](https://smithers.sh/docs/guides/child-flows/): Split work across durable runs with .child, join the results, cancel a parent and reach its children, and detach children that outlive the parent.
- [Undo work with compensation](https://smithers.sh/docs/guides/compensation/): Declare how a failed run undoes the work it already did: flow-scope rollbacks, compensable actions with Jj pre-images, and rewind-time handlers.
- [Share results with artifacts and the step cache](https://smithers.sh/docs/guides/artifacts-cache/): Store step bytes in the content-addressed artifact store, cache sealed step results, and share both between two engines over the HTTP tiers.
- [Operate the control plane](https://smithers.sh/docs/guides/control-plane/): Serve this project's control plane over HTTP and WebSocket, bind it safely, and point clients at it.
- [Run a read-only follower](https://smithers.sh/docs/guides/sync-followers/): Follow a run's journal from a second process over the sync protocol and build a read model from the entries.
- [Export traces, logs, and metrics](https://smithers.sh/docs/guides/observability/): Attach the OTLP exporter to a durable run, forward logs into the journal, and read the same run three ways.
- [Back up, gc, and retain run state](https://smithers.sh/docs/guides/retention/): Back up the .flows directory safely, delete terminal runs with smthrs gc, and sweep unreferenced artifacts.
- [Operate the memory store](https://smithers.sh/docs/guides/memory-ops/): Inspect, seed, and prune namespaced facts with the smthrs memory command, and run memory maintenance.
- [Run flows in CI](https://smithers.sh/docs/guides/ci/): Launch a flow from CI, handle its exit status, and keep evidence when the run fails or waits.
- [Test your flows](https://smithers.sh/docs/guides/testing-flows/): Run flows on the in-memory engine under vitest, assert on recorded results and journal entries, and replay recorded model responses instead of calling a provider.
- [Review pull requests with the Smithers action](https://smithers.sh/docs/guides/pr-review-action/): Add the Smithers review GitHub Action to a repository, trigger agent reviews with a PR comment, and run the same review from a terminal.
- [Run CI on Smithers Cloud](https://smithers.sh/docs/guides/cloud-ci/): What runs your PACKAGE.ts checks today, and the planned Smithers Cloud CI that would run them from repository events.
- [Define triggers](https://smithers.sh/docs/guides/triggers/): Register a durable cron trigger that starts a flow, host the scheduler, fire an occurrence by hand, and read the fire ledger. Repository-event triggers are planned.

## Concepts

- [How target caching works](https://smithers.sh/docs/concepts/target-caching/): What target keys include, how output restoration works, and how to diagnose unexpected hits or misses.
- [Durable execution](https://smithers.sh/docs/concepts/durable-execution/): What a run records, what resume reuses, and which work can execute again after a crash.
- [Flows, actions, and plans](https://smithers.sh/docs/concepts/flows-actions-plans/): How action declarations, flow bodies, and approved plans fit together.
- [Content addressing](https://smithers.sh/docs/concepts/content-addressing/): How declared inputs determine step keys, which changes invalidate results, and where the identity contract stops.
- [Execution IDs and ownership](https://smithers.sh/docs/concepts/ownership/): Choose which invocations share a run, and understand how the engine prevents stale owners from writing it.
- [Retries and interruption](https://smithers.sh/docs/concepts/retries/): Choose between retrying a typed action failure, recovering an infrastructure interruption, and cancelling a run.
- [Capabilities and the host kernel](https://smithers.sh/docs/concepts/kernel/): A closed host surface, a closed capability vocabulary over it, and a grant check on every call, so no flow reaches the host ambiently.
- [Time travel](https://smithers.sh/docs/concepts/time-travel/): Replay, fork, rewind, compensation, and recovery as protocols over the journal a run wrote.
- [Sync and read-only followers](https://smithers.sh/docs/concepts/sync/): Replicate committed journal entries into a dashboard or audit view using durable cursors.
- [The agent runtime](https://smithers.sh/docs/concepts/agent-runtime/): How @smthrs/agent runs a model-driven cell loop as durable work on the engine.
- [Memory](https://smithers.sh/docs/concepts/memory/): Retain facts, conversation history, and reviewed notes across runs, then recall them under an explicit policy.
- [Why Effect](https://smithers.sh/docs/concepts/why-effect/): Why flows are Effect programs, why implementations attach as layers, and why the Effect version is pinned.

## Reference

- [Library API](https://smithers.sh/docs/reference/api/): One page per @smthrs package: what it exports, with the types and defaults stitched from the api.md colocated with its source.
- [Targets](https://smithers.sh/docs/reference/targets/): One page per @smthrs/targets rule: attributes, verbs, cache behavior, and channels from Target.make.
- [RC support matrix](https://smithers.sh/docs/reference/support-matrix/): Runtime, platform, storage, hosting, and evidence limits for Smithers 1.0.0-rc.0.
- [smthrs flow](https://smithers.sh/docs/reference/cli/flow/): Discover flows, inspect plans, and launch durable executions.
- [smthrs runs](https://smithers.sh/docs/reference/cli/runs/): Inspect, resume, cancel, and read historical frames of durable executions.
- [smthrs approvals](https://smithers.sh/docs/reference/cli/approvals/): List in-run approval requests and submit decisions against exact payloads.
- [@smthrs/flow](https://smithers.sh/docs/reference/api/flow/): What @smthrs/flow exports: the flow, action, runtime-port, and durable-primitive namespaces, with types and defaults from source.
- [Export reference](https://smithers.sh/docs/reference/api/engine/): Every export of @smthrs/engine one at a time: FlowEngine, FlowProxy, and FlowProxyServer, each with its full type, its defaults, and its field tables.
- [Smithers API cheat sheet](https://smithers.sh/docs/reference/api/cheat-sheet/): The complete top-level Smithers API used in WORKSPACE.ts and PACKAGE.ts, shown through examples.
- [@smthrs/targets](https://smithers.sh/docs/reference/api/targets/): What @smthrs/targets exports: the Smithers namespace of workspace declarations, catalog rules, macros, actions, and errors, with types from source.
- [Agent.Diff](https://smithers.sh/docs/reference/targets/agent-diff/): Declares an agent that produces a bounded, gate-checked candidate diff inside a declared write-set, executed by the run verb.
- [Filegroup](https://smithers.sh/docs/reference/targets/filegroup/): Names a set of files under one label so other targets depend on the set instead of repeating its globs.
- [@smthrs/agent](https://smithers.sh/docs/reference/api/agent/): The Smithers agent: the production agent loop composed on the durable engine, plus the two adapters that run it, AgentSession for control-plane runs and AgentAction for typed workflow steps
- [@smthrs/artifacts](https://smithers.sh/docs/reference/api/artifacts/): Effect service for the Smithers content-addressed artifact store, local and remote
- [@smthrs/build](https://smithers.sh/docs/reference/api/build/): Bazel-style TypeScript workflow orchestration with explicit pnpm installation
- [@smthrs/build-cli](https://smithers.sh/docs/reference/api/build-cli/): Executes PACKAGE.ts target graphs with content-addressed caching
- [@smthrs/canonical](https://smithers.sh/docs/reference/api/canonical/): RFC 8785 canonical JSON as an Effect Schema
- [@smthrs/capability](https://smithers.sh/docs/reference/api/capability/): Capability values and permission failures: the leaf vocabulary of the Smithers permission kernel
- [@smthrs/chain](https://smithers.sh/docs/reference/api/chain/): The Agent Chain spine: an append-only journal, keyed replayable calls, and the trampoline that runs model-authored flow scripts
- [@smthrs/cli](https://smithers.sh/docs/reference/api/cli/): Node command-line interface for Smithers control
- [@smthrs/control](https://smithers.sh/docs/reference/api/control/): Control services and RPC projections for flows
- [@smthrs/core](https://smithers.sh/docs/reference/api/core/): Flow and Node builders: the pure plan-time data model of the Smithers harness
- [@smthrs/create-app](https://smithers.sh/docs/reference/api/create-app/): Declare a Smithers app in one PACKAGE.ts: file-routed flows, panes, and Cloudflare targets
- [@smthrs/crypto](https://smithers.sh/docs/reference/api/crypto/): Strict SHA-256 hashing with injected and synchronous Effect entry points
- [@smthrs/database](https://smithers.sh/docs/reference/api/database/): A driver-neutral SQL contract with a bounded write-retry seam, plus the composed migration ladder
- [@smthrs/engine-store](https://smithers.sh/docs/reference/api/engine-store/): Effect services for durable engine action persistence and replay boundaries
- [@smthrs/errors](https://smithers.sh/docs/reference/api/errors/): SmithersError and the error codes the integration adapters raise
- [@smthrs/evals](https://smithers.sh/docs/reference/api/evals/): Fixed-suite evaluation, baselines, regression reports, and score gates for flows
- [@smthrs/flows](https://smithers.sh/docs/reference/api/flows/): Barrel package re-exporting the whole @smthrs durable flow engine
- [@smthrs/fs](https://smithers.sh/docs/reference/api/fs/): Private metadata routing and schema-checked command projections for Smithers flows
- [@smthrs/gateway](https://smithers.sh/docs/reference/api/gateway/): Effect workspace gateway contracts, projections, and supervision ports for flows
- [@smthrs/harness](https://smithers.sh/docs/reference/api/harness/): The Smithers built-in agent loop: a cell-first controller whose model turns produce JavaScript cells that run in a persistent realm and reach the world only through durable flow calls
- [@smthrs/integrations](https://smithers.sh/docs/reference/api/integrations/): GitHub, Linear, and Telegram adapters over the Smithers control plane
- [@smthrs/jj](https://smithers.sh/docs/reference/api/jj/): Jujutsu version control as a portable Effect host service
- [@smthrs/journal](https://smithers.sh/docs/reference/api/journal/): Effect services for the Smithers event journal: the immutable run history and the owner fence on its durable channel
- [@smthrs/kernel](https://smithers.sh/docs/reference/api/kernel/): Capability kernel: effect tiers, monotone capability sets, grant store, and permission-decorating layers over the Host services
- [@smthrs/keys](https://smithers.sh/docs/reference/api/keys/): Canonical flow-key derivation and stored-key validation
- [@smthrs/mcp](https://smithers.sh/docs/reference/api/mcp/): Model Context Protocol client and flow adapter: projects a remote MCP server's tools as ordinary FlowBinding.Source entries
- [@smthrs/memory](https://smithers.sh/docs/reference/api/memory/): Effect services for durable cross-run facts, history, notes, recall, and maintenance
- [@smthrs/migrate](https://smithers.sh/docs/reference/api/migrate/): Upgrades Smithers 0.x projects to Smithers 1.0 flows and writes an auditable migration report
- [@smthrs/model](https://smithers.sh/docs/reference/api/model/): Schema-first Effect model protocols, routes, and streaming events for flows
- [@smthrs/notifications](https://smithers.sh/docs/reference/api/notifications/): Durable notification queue, admission policy, and journal projection for flows
- [@smthrs/observability](https://smithers.sh/docs/reference/api/observability/): Observability for flows: default OTLP export wiring plus Effect-native logger, metric, and OpenTelemetry SDK layers
- [@smthrs/patterns](https://smithers.sh/docs/reference/api/patterns/): Higher-order flow patterns and decorators for flows. It composes @smthrs/core alone and imports no Node built-ins.
- [@smthrs/plan](https://smithers.sh/docs/reference/api/plan/): The persisted flows plan: a keyed action graph, its append-only store, and its diff
- [@smthrs/platform-browser](https://smithers.sh/docs/reference/api/platform-browser/): Browser implementations of Effect platform services backed by ZenFS and just-bash
- [@smthrs/platform-bun](https://smithers.sh/docs/reference/api/platform-bun/): Bun Host bundle for flows: Effect's Bun platform services composed into the closed Host surface
- [@smthrs/platform-node](https://smithers.sh/docs/reference/api/platform-node/): Node.js Host bundle for flows: Effect's Node platform services composed into the closed Host surface
- [@smthrs/plugin](https://smithers.sh/docs/reference/api/plugin/): Vite-style typed plugin kernel for flows: hooks, resolution, and config execution
- [@smthrs/registry](https://smithers.sh/docs/reference/api/registry/): Portable flow descriptor discovery and progressive-disclosure registry services
- [@smthrs/run-store](https://smithers.sh/docs/reference/api/run-store/): Effect services for flows run state, attempts, and ownership arbitration
- [@smthrs/sandbox](https://smithers.sh/docs/reference/api/sandbox/): Provisioned machines, provider-neutral remote process execution, conformance, and sandbox liveness for flows
- [@smthrs/scorers](https://smithers.sh/docs/reference/api/scorers/): Flow-native scoring, durable observations, and asynchronous score runners for flows
- [@smthrs/std](https://smithers.sh/docs/reference/api/std/): The flows standard tool library: filesystem, search, HTTP, web-search, shell, and language-server flows
- [@smthrs/step-cache](https://smithers.sh/docs/reference/api/step-cache/): Effect service for the flows content-addressed step result cache
- [@smthrs/sync](https://smithers.sh/docs/reference/api/sync/): Workspace read-path sync protocol, server, and client for flows
- [@smthrs/testing](https://smithers.sh/docs/reference/api/testing/): Testing and conformance library for flows
- [@smthrs/time-travel](https://smithers.sh/docs/reference/api/time-travel/): Durable replay, fork, and rewind primitives for flows
- [@smthrs/triggers](https://smithers.sh/docs/reference/api/triggers/): Durable cron triggers and channel contracts for flows
- [Environment variables](https://smithers.sh/docs/reference/environment-variables/): Control-plane connection settings, target-cache credentials, presentation settings, and provider keys.
- [Exit codes and error codes](https://smithers.sh/docs/reference/errors/): The process exit codes of the smthrs CLI and every stable structured refusal code the named packages raise.
- [flow.mdx frontmatter](https://smithers.sh/docs/reference/flow-mdx/): The YAML frontmatter keys a markdown flow accepts, and how the body below them maps to agent instructions.
- [Glossary](https://smithers.sh/docs/reference/glossary/): The Smithers vocabulary in one sentence per term, with a link to the concept page that develops each one.
- [HTTP and RPC endpoints](https://smithers.sh/docs/reference/http-api/): The routes smthrs serve mounts, their protocols, their authentication rules, and the RPC groups each one serves.
- [llms.txt](https://smithers.sh/docs/reference/llms-txt/): Agent-facing entry points: the curated llms.txt index and the full-prose llms-full.txt, regenerated from the docs tree.
- [MCP tools](https://smithers.sh/docs/reference/mcp-tools/): Discover and call the Smithers command tree through its stdio MCP server.
- [Project layout](https://smithers.sh/docs/reference/project-layout/): The files of a Smithers project: flows/ sources, .flows/ run state, and the root resolution rules.
- [Smithers Cloud CI](https://smithers.sh/docs/reference/cloud-ci/): The planned Smithers Cloud CI service: activation, execution, caching, and required results. Not shipped; recorded so the design is visible.
- [smthrs approve](https://smithers.sh/docs/reference/cli/approve/): Approve the complete serialized approval payload
- [smthrs bug](https://smithers.sh/docs/reference/cli/bug/): Report a bug with a run digest attached
- [smthrs cancel](https://smithers.sh/docs/reference/cli/cancel/): Cancel a durable run
- [smthrs claude](https://smithers.sh/docs/reference/cli/claude/): Claude Code plugin mirror protocol
- [smthrs deny](https://smithers.sh/docs/reference/cli/deny/): Deny the complete serialized approval payload
- [smthrs doctor](https://smithers.sh/docs/reference/cli/doctor/): Report registry, database, runtime, and provider readiness
- [smthrs down](https://smithers.sh/docs/reference/cli/down/): Cancel every non-terminal run
- [smthrs gc](https://smithers.sh/docs/reference/cli/gc/): Delete terminal runs older than a threshold, with the rows they own
- [smthrs init](https://smithers.sh/docs/reference/cli/init/): Initialize target declarations and a starter durable flow while preserving existing files.
- [smthrs logs](https://smithers.sh/docs/reference/cli/logs/): Read run events; --follow streams future events
- [smthrs ls](https://smithers.sh/docs/reference/cli/ls/): List the flows discovered under this project
- [smthrs mcp](https://smithers.sh/docs/reference/cli/mcp/): Register the generated Smithers command surface with an MCP client.
- [smthrs memory](https://smithers.sh/docs/reference/cli/memory/): Persistent facts, notes, recall, and conversation history in the control database.
- [smthrs migrate](https://smithers.sh/docs/reference/cli/migrate/): Convert a Smithers 0.x project to the 1.0 authoring model
- [smthrs output](https://smithers.sh/docs/reference/cli/output/): Print one registered node output
- [smthrs plan](https://smithers.sh/docs/reference/cli/plan/): Render a flow plan and its complete approval payload
- [smthrs ps](https://smithers.sh/docs/reference/cli/ps/): List durable runs
- [smthrs run](https://smithers.sh/docs/reference/cli/run/): Execute run-kind targets from the workspace graph.
- [smthrs serve](https://smithers.sh/docs/reference/cli/serve/): Host the control server and durable trigger scheduler for this project.
- [smthrs signal](https://smithers.sh/docs/reference/cli/signal/): Deliver a durable JSON signal to a run
- [smthrs status](https://smithers.sh/docs/reference/cli/status/): Show the diagnosis card for one run, or the run listing
- [smthrs steer](https://smithers.sh/docs/reference/cli/steer/): Send a durable, attributed steering message to a run
- [smthrs suggest](https://smithers.sh/docs/reference/cli/suggest/): Read the project, stream the ways Smithers can help, and implement the one you pick
- [smthrs up](https://smithers.sh/docs/reference/cli/up/): Plan, approve, and run one flow; -d launches it detached
- [smthrs update](https://smithers.sh/docs/reference/cli/update/): Check npm for a newer @smthrs/cli
- [Subpackages](https://smithers.sh/docs/reference/subpackages/): Smithers ships as many small packages rather than one. What each one is, a minimal example of using it, and where its documentation lives.
- [The smthrs command](https://smithers.sh/docs/reference/cli/): Target execution, durable flows, run control, and operator commands in one CLI.
- [Triggers](https://smithers.sh/docs/reference/triggers/): The shipped trigger declaration, its CLI verbs, scheduler behavior, and fire ledger, followed by the planned repository-event selector API marked as unshipped.

## Troubleshooting

- [Troubleshooting](https://smithers.sh/docs/troubleshooting/): Find your symptom verbatim; each entry names the cause, the fix, and how to verify the fix.
- [A run is stuck](https://smithers.sh/docs/troubleshooting/stuck-run/): Distinguish a missing executor, a dead owner, and a durable wait before trying to resume a run.
- [Exit code 3: waiting-approval](https://smithers.sh/docs/troubleshooting/waiting-approval/): Find the pending request, approve its exact payload, and resume the existing run.
- [Fix provider readiness](https://smithers.sh/docs/troubleshooting/doctor-provider/): Resolve missing credentials and model-seat mismatches before starting an agent flow.
- [unsupported_database](https://smithers.sh/docs/troubleshooting/unsupported-database/): The CLI refuses database backends other than local SQLite in 1.0.0-rc.0.

## Migration

- [Compatibility policy](https://smithers.sh/docs/migration/compatibility/): The frozen Smithers 1.0.0-rc.0 compatibility policy: what rc.0 does not provide, what it preserves, and what flows require to run.
- [Upgrade from 0.x to 1.0](https://smithers.sh/docs/migration/1.0/): Migrate a Smithers 0.x JSX project to the 1.0 authoring model with smthrs migrate, and look up every removed 0.x command and flag.

## Optional

- [Define and run](https://smithers.sh/docs/examples/01-define-and-run/): Define a typed flow and run it on the in-memory engine.
- [Examples](https://smithers.sh/docs/examples/): Tested, runnable programs in examples/src, grouped by task.
- [Run durably](https://smithers.sh/docs/examples/02-run-durably/): Run a flow on the durable engine and read its journal.
- [Crash and resume](https://smithers.sh/docs/examples/03-crash-and-resume/): Suspend a run and resume it through a fresh engine over the same SQLite file.
- [Retry policy](https://smithers.sh/docs/examples/04-retry-policy/): Inspect a retry policy and retry an action that fails before succeeding.
- [Time travel fork](https://smithers.sh/docs/examples/05-time-travel-fork/): Fork a finished run at a journal frame and drive the child.
- [Time travel rewind](https://smithers.sh/docs/examples/06-time-travel-rewind/): Inspect a run at a frame, then rewind its persistent state.
- [Sync follower](https://smithers.sh/docs/examples/07-sync-follower/): Follow a run's journal from a second process's point of view.
- [Host adapters](https://smithers.sh/docs/examples/08-host-adapters/): Run the same host program against two adapters.
- [Browser use](https://smithers.sh/docs/examples/09-browser-use/): Use the library from a browser bundle.
- [Telemetry export](https://smithers.sh/docs/examples/10-telemetry-export/): Add the one telemetry layer to a durable run and read the granular trace data back three ways.
- [Agent step](https://smithers.sh/docs/examples/11-agent-step/): Pass typed output from a research action into a writing action.
- [Agent live smoke](https://smithers.sh/docs/examples/12-agent-live-smoke/): Run a model-backed action against a live OpenAI provider.
- [Agent live smoke local](https://smithers.sh/docs/examples/13-agent-live-smoke-local/): Run a model-backed action against a local Ollama endpoint.
- [Agent live smoke gemini](https://smithers.sh/docs/examples/14-agent-live-smoke-gemini/): Run a model-backed action against Gemini's OpenAI-compatible endpoint.
- [Model layer smoke](https://smithers.sh/docs/examples/15-model-layer-smoke/): Stream a response directly through the model package.
- [Fan out fan in](https://smithers.sh/docs/examples/16-fan-out-fan-in/): Run checks in batches of two and join their verdicts into a report.
- [Review loop](https://smithers.sh/docs/examples/17-review-loop/): Draft, review, and revise until approval or the round limit.
- [Approval and signal](https://smithers.sh/docs/examples/18-approval-and-signal/): Compare plan approval, an in-run approval, and a signal wait.
- [Cancel and child cleanup](https://smithers.sh/docs/examples/19-cancel-and-child-cleanup/): Cancel a run and observe attached child and process cleanup.
- [Child flows](https://smithers.sh/docs/examples/20-child-flows/): Run two child flows, join their results, and resume the parent without duplicating the children.
- [Cache and compensation](https://smithers.sh/docs/examples/21-cache-and-compensation/): Apply a cache lifetime and restore workspace state before retrying a compensable action.
- [Mcp server](https://smithers.sh/docs/examples/22-mcp-server/): The MCP server 22-mcp-tools.ts connects to.
- [Mcp tools](https://smithers.sh/docs/examples/22-mcp-tools/): Give an agent tools supplied by a separate MCP server process.
- [Control plane and gateway](https://smithers.sh/docs/examples/24-control-plane-and-gateway/): Plan, approve, launch, and watch a flow through a loopback control server.
- [Agent tools in sandbox](https://smithers.sh/docs/examples/25-agent-tools-in-sandbox/): Run a scripted agent with filesystem tools inside a bounded QuickJS cell loop.
- [Memory recall](https://smithers.sh/docs/examples/26-memory-recall/): Store facts in one run and recall them in a later execution.
- [Failure control](https://smithers.sh/docs/examples/30-failure-control/): Failure control: what runs, what unwinds, and what the plan shows first.
- [Bounded loops](https://smithers.sh/docs/examples/31-bounded-loops/): Repair a configuration and refine a summary with bounded loop patterns.
- [Intervene](https://smithers.sh/docs/examples/32-intervene/): Intervene on a real workspace: read a file, propose an edit, gate the write behind an approval, and report what happened.
- [Delegation trellis](https://smithers.sh/docs/examples/33-delegation-trellis/): Execute a model-authored plan across durable flow rounds.
- [Human task](https://smithers.sh/docs/examples/34-human-task/): Reject an invalid human answer and ask again after an engine restart.
- [Poll](https://smithers.sh/docs/examples/34-poll/): Resume a poll after stopping the engine during its durable timer.
- [Remote cache](https://smithers.sh/docs/examples/35-remote-cache/): Share a sealed step result between engines with separate databases.
- [Detached children](https://smithers.sh/docs/examples/36-detached-children/): Let a child outlive its parent and collect its output after a restart.
- [Host containment](https://smithers.sh/docs/examples/37-host-containment/): Recover process cleanup after a host is killed with SIGKILL.
- [Monitor and alert](https://smithers.sh/docs/examples/38-monitor-and-alert/): Observe parked runs and test delayed alert delivery.
- [Agent policies](https://smithers.sh/docs/examples/39-agent-policies/): Resume a model-backed action after a rate limit and an invalid structured answer.
- [Sandbox placement](https://smithers.sh/docs/examples/40-sandbox-placement/): Place an action's host operations in a provisioned session.
- [Sandboxed flow](https://smithers.sh/docs/examples/41-sandboxed-flow/): Run a child flow's code inside a provisioned environment as one parent action.
