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, 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, workspace remote caching, and cache trust. 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 and authoring rules. Author in a package's docs/ directory; the 48 subdomain sites under apps/docs 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 and its ingest-reference.mjs/generate-llms.mjs steps. Do not hand-edit generated projections.
• Benchmarks or performance claims: read 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 and seeded review. Keep offline deterministic gates and deliberate baseline updates separate from live model measurements and spending.
• Flows: read @smthrs/flow and CLI reference. A file flow at flows/<name>/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.
• Plans: read plan and plan-store. 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. 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, engine, and engine-store. @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 and run-store. 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. 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 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 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. 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. 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 before changing its filesystem or process adapters. Its trusted filesystem boundary invokes an absolute CPython executable (/usr/bin/python3 or SMITHERS_PYTHON3); a relative override fails startup. Bun's host bundle is not the browser adapter.
• Node host: read platform-node before changing containment or process recovery. Confined operations require the smithers-jj-export helper built with Rust 1.98.0; 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 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.