--- name: smithers-maintenance description: Work on Smithers workspace graph, generated documentation, benchmark or eval evidence, or durable flow authoring in this repository. --- # Smithers maintenance Use the owning source and current docs on the revision being changed. The installed `smthrs --help` and `--schema` decide CLI syntax when they differ from a checked-in example. The 1.0 CLI separates target graph commands (`smthrs targets`, `show target`, `build|test|lint|docs|review|ci`) from durable flow commands (`smthrs flow list|plan|start`, `smthrs runs ...`). A flow start receipt does not prove completion; inspect its run and action receipts. - **Graph or root files:** read [CONTRIBUTING.md](../../../CONTRIBUTING.md), especially root-file and target-index generation. `PACKAGE.ts` declares targets; generated companions and the whole declaration-set index have explicit checks. Use `pnpm run target-index` when that contract calls for regeneration. - **Build/install/cache:** read [build](../../../packages/smithers/build/README.md), [workspace remote caching](../../../packages/smithers/build/docs/workspace/smithers-cloud-cache.md), and [cache trust](../../../packages/smithers/build/infra/CACHE-TRUST.md). The install flow currently supports pnpm only; Bun can still run target tools. Install actions use expected filesystem boundaries and do not enter the shared engine cache. The target `/ac` cache differs from engine step-cache/artifacts; hosted and self-hosted cache implementations need matching route, bound, and credential behavior. - **Documentation:** read [apps/docs/README.md](../../../apps/docs/README.md) and [authoring rules](../../../apps/docs/shared/AUTHORING.md). Author in a package's `docs/` directory; the subdomain sites listed in `apps/docs/shared/manifest.mjs` are generated/staged copies, separate from the main `apps/site` pipeline. Use `pnpm run docs:sync` and `pnpm run docs:check` for that fleet. For targets reference pages on the main site, follow [targets documentation contribution rules](../../../packages/smithers/build/targets/README.md#contributing-to-the-documentation) and its `ingest-reference.mjs`/`generate-llms.mjs` steps. TUI docs are authored on the main site (TUI tabs in `docs/learn/`, reference in `docs/tui/`); recording scripts live in `apps/tui/docs/recordings/`, and `apps/tui-docs` records them and hosts the playground; see [its README](../../../apps/tui-docs/README.md). Do not hand-edit generated projections. - **Benchmarks or performance claims:** read [scripts/bench/README.md](../../../scripts/bench/README.md). Distinguish the deterministic PR gate from scheduled observed timings, review candidate baselines, and retain methods and limitations with any claim. - **Evals:** read the owning suite's README, including [agent](../../../evals/agent/README.md) and [seeded review](../../../evals/review-seeded-bugs/README.md). Keep offline deterministic gates and deliberate baseline updates separate from live model measurements and spending. - **Flows:** read [@smthrs/flow](../../../packages/smithers/flows/flow/README.md) and [CLI reference](../../../packages/smithers/docs/reference/cli/README.md). A file flow at `flows//flow.ts` default-exports a tagged `Flow.make` from `@smthrs/flow`. Use stable `Node.capture` callbacks for canonical persisted composition and matching `implementationVersion` declarations/registrations for sealed idempotent actions. New authoring uses Effect Schema, not retired JSX/Zod task examples. A decision inside a flow (classify, filter, rank, route, yes/no over items) asks Jev through `Classifier.make` and the host `Evaluator`, as one request with one question per item, never through an LLM seat; see [jev-check](../../../flows/coding/jev-check.ts). - **Plans:** read [plan](../../../packages/smithers/flows/plan/README.md) and [plan-store](../../../packages/smithers/flows/plan-store/README.md). Node payloads are persisted as plaintext in `node_json` and approval cards without redaction; keep credentials out and resolve them at dispatch. Persisted plans are verified on write and read, and append uses an immutable-history compare-and-swap over the approved base and running prefix. - **Generated or untrusted flow declarations:** read [core planning rules](../../../packages/smithers/flows/core/README.md). `Graph.build` executes bodies and planning callbacks with the caller's process authority; capability/effect metadata does not sandbox that code. Translate validated data into nodes with trusted code, or plan untrusted code in an externally isolated process. - **Runtime or persistence:** read [flows runtime](../../../packages/smithers/flows/README.md), [engine](../../../packages/smithers/flows/engine/README.md), and [engine-store](../../../packages/smithers/flows/engine-store/README.md). `@smthrs/flow` declares behavior, the engine makes decisions, and the storage seam changes where state lives. Node and Bun use distinct native host/SQL adapters over the same SQLite migrations, journal, stores, cache, and recovery. Run migrations before SQL-backed services and use one writer for journal/state transitions; demonstrate cross-runtime recovery and cancellation. Browser bundling alone does not establish durable browser execution. - **Journal and ownership fencing:** read [journal](../../../packages/smithers/flows/journal/README.md) and [run-store](../../../packages/smithers/flows/run-store/README.md). Fenced durable emissions require a `flows_runs` owner row and run-store migrations; journal migrations alone are insufficient. `emitDurableUnfenced` is only for genuinely ownerless admission or repair, never a bypass for `fence_lost`. An expired lease alone does not authorize takeover; `LivenessEvidence` must be current, and an unknown probe counts as alive. - **Step cache migrations:** read [step-cache](../../../packages/smithers/flows/step-cache/README.md). The earlier 1.0 RC migration 2002 identity is accepted explicitly; preserve its ledger and cached results during upgrade. An unknown migration identity remains a failure, not a reason to delete a runtime database. - **Time travel:** read [time-travel](../../../packages/smithers/flows/time-travel/README.md) before changing fork, rewind, or their receipts. A fork may re-execute actions keyed by the child run ID; rewind archives future waits and refuses crossed irreversible effects or live descendants. Test recovery after an interrupted mutation. - **Sync:** read [sync](../../../packages/smithers/flows/sync/README.md) before changing cursors, subscriptions, or gateway mounts. Persist applied cursor progress with consumer state; change feeds are hints and a re-list is authoritative. Preserve rewind generation handling: `lineage_changed` requires rebuilding the projection. Branch RPC code is not currently mounted by the gateway. - **Artifacts:** read [artifact storage](../../../packages/smithers/flows/artifacts/README.md). Its filesystem backend needs trusted host filesystem semantics; kernel-guarded filesystem access cannot substitute for them. Treat deletion as explicit and keep engine-store responsible for liveness/reachability. - **Browser host:** read [platform-browser](../../../packages/smithers/flows/platform-browser/README.md). Its bash, filesystem, and jj views must share one volume; the tab uses the memory engine, and reload durability depends on the mount's `sync()`. Do not infer browser durability from a successful build or import. - **Bun host:** read [platform-bun](../../../packages/smithers/flows/platform-bun/README.md) before changing its filesystem or process adapters. Its trusted filesystem boundary runs the native `smithers-jj-export` helper (build with `cargo build --locked --release -p smithers-ffi --bin smithers-jj-export` or set an absolute `SMITHERS_WORKSPACE_JJ_EXPORT_BINARY`); `PATH` is never searched. Bun's host bundle is not the browser adapter. - **Node host:** read [platform-node](../../../packages/smithers/flows/platform-node/README.md) before changing containment or process recovery. Confined operations require the `smithers-jj-export` helper built with the Rust toolchain `rust-toolchain.toml` pins; a missing helper refuses them. `ProcessLedger.layerMemory` cannot recover escaped children after a host crash, and permission checks belong around the host service bundle. For TUI changes, read [apps/tui/AGENTS.md](../../../apps/tui/AGENTS.md) and its linked README. For app/server work, use their scoped `AGENTS.md` files. Treat issue state and wiki freshness as separate receipts from code status.