@michaelrwalker/stagehand 0.5.3 → 0.6.0

package/skills/observability/reporting-progress/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: 'reporting-progress'
+description: >
+  Covers the handler UI surface — `status(text)` vs `note(text)`, `progress({ total, label })` and its `ProgressHandle` (`update`/`increment`/`setTotal`/`setLabel`/`done`), `task(label)`/`tasks([...] as const)` and `TaskHandle`/`TaskListHandle`, and the `log`/`info`/`warn`/`error`/`success` severity lines. Load this for "show a progress bar," "put a row count on the finished step line," "run a typed checklist inside a step," or any handler-level UI call that isn't about where the output physically renders.
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/handler-surface.md'
+  - 'miaklwalker/stagehand:src/context.ts'
+  - 'miaklwalker/stagehand:src/script.ts'
+---
+
+# Stagehand — Reporting Progress From a Step
+
+Every handler receives `status`, `note`, `progress`, `task`, `tasks`, and the five log methods as part of its single context object. `rollback` gets a smaller subset — `log` (no `info`/`warn`/`error`/`success`), `status`, `note`, and `progress`, but not `task`/`tasks`.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+const result = await new Script({ name: "sync" })
+  .addStep({
+    name: "fetch records",
+    handler: async ({ status, note, progress, log }) => {
+      status("connecting");
+      log("opened connection");
+
+      const total = 428;
+      const bar = progress({ total, label: "fetching" });
+      const rows: number[] = [];
+      for (let i = 0; i < total; i++) {
+        rows.push(i);
+        bar.update(i + 1);
+      }
+      bar.done();
+
+      note(`${rows.length} rows found`);
+      return { rows };
+    },
+  })
+  .run({});
+```
+
+## Core Patterns
+
+### `status` for scratch space, `note` for what should survive on the finished line
+
+```ts
+.addStep({
+  name: "query database",
+  handler: async ({ status, note }) => {
+    status("scanning");            // ⠸ query database  › scanning
+    const rows = await db.all(sql);
+    note(`${rows.length} rows found`);
+    return { rows };
+  },
+})
+// ✔ query database (400 rows found)                                    1.2s
+```
+
+`status` is wiped the instant the step settles; `note` is written into the step's title and stays. Calling either again replaces the previous text — neither is cumulative — and `note("")` removes the annotation entirely.
+
+### A progress bar with a mid-flight relabel
+
+```ts
+handler: async ({ progress }) => {
+  const bar = progress({ total: 428, label: "resolving" });
+  for (let i = 0; i <= 428; i += 17) {
+    bar.update(i, i < 200 ? "resolving" : "linking");
+    await doWork();
+  }
+  bar.done();
+  return { packages: 428 };
+}
+```
+
+`progress` returns a `ProgressHandle` with `update(value, label?)`, `increment(by = 1)`, `setTotal(total)`, `setLabel(label)`, `done()`, and readonly `.value`/`.total`; every value it accepts is clamped to `[0, total]`.
+
+### A typed checklist with `tasks()`
+
+```ts
+handler: async ({ tasks }) => {
+  const list = tasks(["typecheck", "transform", "minify", "write manifest"] as const);
+
+  for (const key of ["typecheck", "transform", "minify", "write manifest"] as const) {
+    const item = list.get(key);
+    item.start();
+    await run(key);
+    item.succeed();
+  }
+}
+
+async function run(step: string) {}
+```
+
+`tasks(labels)` takes the label list as a `const` tuple, so `list.get(key)` is typed to exactly those labels — a single ad hoc item can also be created with `task(label)`, returning one `TaskHandle` (`start`/`label`/`succeed`/`fail`/`skip`, each taking an optional replacement text).
+
+### Severity-tagged lines with `log`/`info`/`warn`/`error`/`success`
+
+```ts
+handler: async ({ log, info, warn, error, success }) => {
+  log("starting migration");
+  info("using batch size 500");
+  warn("retrying batch 3");
+  error("batch 7 failed, continuing");
+  success("migration complete");
+  return {};
+}
+```
+
+All five just differ in icon/style; where the line lands is controlled by the script's `logPlacement` option, covered in the log-placement-and-rendering skill.
+
+## Common Mistakes
+
+### HIGH Using status() for a value meant to persist on the finished step line
+
+Wrong:
+```ts
+handler: async ({ status }) => {
+  const rows = await db.all(sql);
+  status(`${rows.length} rows found`);  // gone the moment this step finishes
+  return { rows };
+}
+```
+
+Correct:
+```ts
+handler: async ({ status, note }) => {
+  status("scanning");
+  const rows = await db.all(sql);
+  note(`${rows.length} rows found`);  // stays on the finished line
+  return { rows };
+}
+```
+
+`status` is scratch space for a step in flight — it is deleted (`delete item.state.statusText`) the instant the step settles, whether it succeeds or fails; only `note` survives onto the finished line.
+
+Source: docs/guides/handler-surface.md; src/script.ts (delete item.state.statusText on success/failure)
+
+### LOW Calling note() repeatedly expecting it to append, like a log
+
+Wrong:
+```ts
+note("400 rows");
+note("2 skipped");  // "400 rows" is gone — the title now reads "2 skipped"
+```
+
+Correct:
+```ts
+note(`${rowCount} rows, ${skipped} skipped`);
+```
+
+`note` replaces whatever it previously set rather than accumulating; `note("")` clears it.
+
+Source: docs/guides/handler-surface.md
+
+### LOW Passing a plain string[] (not `as const`) to tasks()
+
+Wrong:
+```ts
+const labels = ["typecheck", "transform", "minify"];
+const list = tasks(labels);
+list.get("tpyecheck");  // typo compiles — labels was string[], not a literal tuple
+```
+
+Correct:
+```ts
+const list = tasks(["typecheck", "transform", "minify"] as const);
+list.get("tpyecheck");  // compile error
+```
+
+`tasks(labels)` needs the label list as a const tuple for `list.get(key)` to be typed to exactly those labels; a widened `string[]` makes `get()` accept any string, including a typo, with no compile error.
+
+Source: docs/guides/handler-surface.md
+
+### LOW Passing a value outside [0, total] to progress and expecting an error or warning
+
+Wrong:
+```ts
+const bar = progress({ total: 100 });
+bar.update(bytesUploaded);  // bytesUploaded is actually in KB — silently clamps to 100
+```
+
+Correct:
+```ts
+const bar = progress({ total: totalBytes });
+bar.update(bytesUploaded);  // units matched to `total`
+```
+
+`update`/`increment`/`setTotal` all clamp silently to the valid range rather than throwing, so an off-by-one or unit mismatch in the caller's own math shows up only as a bar stuck at 0% or 100% with no diagnostic.
+
+Source: src/context.ts createProgress() (clamp(...))
+
+### HIGH Tension: Rich live observability vs. complete log record
+
+`logPlacement` "step"/"bottom" produce the most pleasant live-TTY experience by capping what they retain, while "scrollback" is the only placement that is both complete and the default, and one choice applies to the whole script. Agents optimizing for this skill's goal (a beautifully-nested live view of status/note/progress/tasks next to the step they belong to) tend to leave `logPlacement` at "step" or "bottom" for a script that also needs a guaranteed-complete CI/audit trail, because they don't account for those two placements silently discarding older lines beyond a handful.
+
+See also: skills/observability/log-placement-and-rendering/SKILL.md § Common Mistakes
+
+See also: skills/observability/log-placement-and-rendering/SKILL.md — where status/note/log actually render depends entirely on logPlacement and which renderer is active; the two skills describe one mechanism from two ends.

package/skills/reuse/reusable-routines-and-mounts/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: 'reusable-routines-and-mounts'
+description: >
+  Covers routineFor<In, Ctx>() for declaring a mountable group of phases, and Script.use(routine | script, { as?, input? })
+  for splicing it into a host with optional renaming and per-mount input mapping. Load this for "share a fetch-and-normalize
+  pipeline across scripts," "mount the same routine twice for two tenants," or "feed a mounted fragment its own input."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
+  - 'miaklwalker/stagehand:docs/guides/caching.md'
+  - 'miaklwalker/stagehand:docs/reference/errors.md'
+  - 'miaklwalker/stagehand:docs/reference/script.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:test/routine.test.ts'
+---
+
+# Stagehand — Reusable Routines and Mounts
+
+`routineFor` declares a group of phases away from any particular script; `use()` splices that routine (or a plain `Script`) into a host, in order, merging everything it produces into the host's typed context.
+
+## Setup
+
+```ts
+// routines/channel.ts
+import { routineFor } from "@michaelrwalker/stagehand";
+
+export const fetchChannel = routineFor<{ channel: string }>()("fetch channel", (script) =>
+  script
+    .addPhase("Fetch")
+    .addStep({ name: "authenticate", handler: ({ input }) => ({ token: `t_${input.channel}` }) })
+    .addStep({ name: "pull orders", handler: ({ ctx }) => ({ orders: [{ id: `${ctx.token}_o1`, total: 10 }] }) })
+    .addPhase("Normalize")
+    .addStep({ name: "dedupe", handler: ({ ctx }) => ({ orderCount: ctx.orders.length }) }),
+);
+```
+
+```ts
+// somewhere-else.ts
+import { Script } from "@michaelrwalker/stagehand";
+import { fetchChannel } from "./routines/channel";
+
+const report = await new Script<{ channel: string }>({ name: "report" })
+  .use(fetchChannel)
+  .addPhase("Report")
+  .addStep({ name: "aggregate", handler: ({ ctx }) => ({ total: ctx.orderCount }) })
+  .run({ channel: "amazon" });
+```
+
+`routineFor<In, Ctx>()` takes the **minimum** the fragment needs: the input it reads (`In`) and the context it expects to already exist (`Ctx`). Both are checked at the `use()` call site — a host missing `channel` on its input, or missing an upstream key the routine needs in `ctx`, is a compile error there, not an `undefined` at run time.
+
+## Core Patterns
+
+### Mount the same routine twice for two tenants
+
+```ts
+new Script<{ since: string; amazonKey: string; shopifyKey: string }>({ name: "all channels" })
+  .use(fetchChannel, {
+    as: "Amazon",
+    input: ({ input }) => ({ channel: "amazon" }),
+  })
+  .use(fetchChannel, {
+    as: "Shopify",
+    input: ({ input }) => ({ channel: "shopify" }),
+  });
+```
+
+`as` prefixes every phase name the mount brings in (`"Amazon / Fetch"`, `"Amazon / Normalize"`), keeping them unique so a second mount of the same routine doesn't collide.
+
+### Mount a plain `Script`, still runnable on its own
+
+```ts
+const pipeline = new Script<{ channel: string }>({ name: "pull" })
+  .addPhase("Fetch")
+  .addStep({ name: "pull", handler: ({ input }) => ({ rows: [input.channel] }) });
+
+await pipeline.run({ channel: "etsy" }); // runs standalone today
+
+const mounted = await new Script<{ channel: string }>({ name: "report" })
+  .use(pipeline) // mounts into something bigger tomorrow
+  .addPhase("Report")
+  .addStep({ name: "count", handler: ({ ctx }) => ({ n: ctx.rows.length }) })
+  .run({ channel: "etsy" });
+```
+
+`use()` accepts anything built with `routineFor` or an ordinary `Script` — the same module works alone or spliced into a host.
+
+### Give a mount its own input, decoupled from the host's shape
+
+```ts
+export const pullChannel = routineFor<{ channel: string; apiKey: string }>()("pull channel", (script) =>
+  script.addPhase("Fetch").addStep({
+    name: "pull",
+    handler: ({ input }) => ({ pulled: `${input.channel}:${input.apiKey}` }),
+  }),
+);
+
+const result = await new Script<{ region: string }>({ name: "t" })
+  .use(pullChannel, {
+    input: ({ input }) => ({ channel: input.region, apiKey: "k" }),
+  })
+  .run({ region: "eu" });
+```
+
+`input` takes a fixed value or an `{ input, ctx } => SubIn` mapper, may be async, and is resolved once per mount at the moment the mount is reached — the host no longer has to match the routine's input shape, only produce it.
+
+## Common Mistakes
+
+### HIGH Chaining addStep() directly after use() without a new phase
+
+Wrong:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel)
+  .addStep({ name: "sneaky", handler: () => ({}) });
+// StepDefinitionError: Cannot add a step after use()
+```
+
+Correct:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel)
+  .addPhase("Report")
+  .addStep({ name: "summarize", handler: ({ ctx }) => ({}) });
+```
+
+A routine owns whole phases, so the last phase spliced in by `use()` belongs to the fragment — a bare `addStep` right after it throws `StepDefinitionError` at build time even though the fluent chain reads naturally.
+
+Source: src/script.ts currentPhase() StepDefinitionError; docs/guides/reusable-scripts.md
+
+### MEDIUM Assuming a mounted routine's when() sees the host's own input
+
+Wrong:
+```ts
+// inside routines/channel.ts, built with routineFor<{ channel: string }>()
+.addStep({ name: "gate", when: ({ input }) => input.hostOnlyFlag, handler: async () => {} })
+// TypeScript already blocks referencing hostOnlyFlag if routineFor's In doesn't include it —
+// but this is exactly the trap when In is loosely typed or the mapper over-forwards fields
+```
+
+Correct:
+```ts
+export const pullChannel = routineFor<{ channel: string; since: string }>()(
+  "pull channel",
+  (script) => script.addStep({
+    name: "gate",
+    when: ({ input }) => input.channel === "amazon",
+    handler: async () => {},
+  }),
+);
+```
+
+A mount's input is resolved once, when the mount is reached, from either a fixed value or an `{ input, ctx } => SubIn` mapper — every `when` inside that fragment (phase- or step-level) is evaluated against the mount's resolved input, never the host's own.
+
+Source: docs/guides/reusable-scripts.md ("Giving a mount its own input"); src/script.ts use()/run() mount input resolution
+
+### HIGH Mounting the same routine twice without as
+
+Wrong:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel)
+  .use(pullChannel); // DuplicateNameError: "Fetch" already defined
+```
+
+Correct:
+```ts
+new Script({ name: "t" })
+  .use(pullChannel, { as: "Amazon", input: ({ input }) => ({ ...input, channel: "amazon" }) })
+  .use(pullChannel, { as: "Shopify", input: ({ input }) => ({ ...input, channel: "shopify" }) });
+```
+
+Phase names must stay unique across the whole script; mounting the same routine a second time without a distinguishing `as` prefix throws `DuplicateNameError` at build time.
+
+Source: docs/guides/reusable-scripts.md; docs/reference/errors.md (DuplicateNameError)
+
+### MEDIUM Giving a routine its own ScriptOptions and expecting them to hold once mounted
+
+Wrong:
+```ts
+// routines/import.ts
+const pipeline = new Script({ name: "import", rollback: "none" })
+  .addPhase("Fetch")
+  .addStep({ name: "pull", handler, rollback: undoPull });
+// mounted into a host with rollback: "all" — the host's "all" wins; "pull"'s rollback CAN fire
+```
+
+Correct:
+```ts
+// a mountable fragment's own ScriptOptions are dead weight once mounted — fine to leave them off,
+// and expect whichever script mounts it to own rollback/logPlacement/silent for the whole run
+```
+
+A mounted `Script`'s own `ScriptOptions` are ignored in favor of the host's; only its phases and steps come across. This is by design, not a bug — a standalone `Script` is meant to be runnable on its own today and mountable into something bigger tomorrow, and the host has to govern the whole run.
+
+Source: docs/guides/reusable-scripts.md ("A mounted Script's own ScriptOptions... are ignored in favor of the host's")
+
+### LOW Renaming a mount with as and forgetting to update cache calls
+
+Wrong:
+```ts
+.use(pullChannel, { as: "Amazon" })
+// elsewhere: cache.clear("Fetch")  — now a compile error, slot is "Amazon / Fetch"
+```
+
+Correct:
+```ts
+.use(pullChannel, { as: "Amazon" })
+// elsewhere: cache.clear("Amazon / Fetch")
+```
+
+`as` renames a mounted fragment's cache slots along with its phases, so every `context.cache` call written against the unprefixed name goes red at compile time and needs the `"As / PhaseName"` form instead.
+
+Source: docs/guides/reusable-scripts.md ("Mounting twice"); docs/guides/caching.md ("Reaching the cache from a step")
+
+### MEDIUM Assuming a mount's input mapper re-evaluates per step
+
+Wrong:
+```ts
+.use(pullChannel, { input: ({ input }) => ({ apiKey: getFreshToken() }) })
+// assumed: getFreshToken() called again for each step in the fragment — it is called exactly once
+```
+
+Correct:
+```ts
+// if freshness matters per step, resolve it inside the fragment's own step handlers
+// instead of the mount mapper
+```
+
+Input is resolved once per mount, at the moment the mount is reached in execution order, and every phase/step of that fragment — including `when` and `rollback` — sees that single resolved value, not a fresh evaluation each time.
+
+Source: docs/guides/reusable-scripts.md ("resolved once per mount, at the moment the mount is reached")
+
+### HIGH Tension: Routine authoring instincts vs. host-controlled ScriptOptions
+
+A routine is built as an ordinary `Script`, which makes it natural to set `rollback`/`logPlacement`/`silent` on it as if authoring a standalone safety policy — but every one of those is discarded the moment it is mounted. Agents optimizing for a reusable, "always non-destructive" fragment tend to bake `rollback: "none"` into the sub-script because they don't account for the host's `ScriptOptions` overriding it entirely; that requirement has to be documented for whoever mounts the routine instead.
+
+See also: skills/compensation-safety/adding-rollbacks/SKILL.md § Common Mistakes
+See also: skills/observability/log-placement-and-rendering/SKILL.md § Common Mistakes
+
+See also: skills/building-scripts/structuring-phases-and-steps/SKILL.md — a routine owns whole phases; addStep directly after use() is refused, which only makes sense once phase ownership is understood.

package/skills/reuse/splitting-steps-across-files/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: 'splitting-steps-across-files'
+description: >
+  stepFor<In, Ctx>() binds the input and context a step declared outside any script expects, so the step can be exported from its own module and passed to addStep; WithStepFor<Step, Rest> computes a chain's Ctx from an earlier step's output instead of restating it by hand. Load this for "move a step into its own module," "share a step across two scripts," or "build a reusable steps file for a recurring workflow."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.5.3'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/splitting-steps.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:test/with-step-for.test.ts'
+---
+
+# Stagehand — Splitting Steps Across Files
+
+A step defined inline with `addStep` infers its `In` and `Ctx` from the script it's attached to. A step declared in its own module has no script to infer from, so `stepFor<In, Ctx>()` supplies that binding explicitly while keeping full inference on the handler's return type.
+
+## Setup
+
+```ts
+// steps/tenancy.ts
+import { stepFor } from "@michaelrwalker/stagehand";
+
+interface Input {
+  accountId: string;
+}
+
+export const loadAccount = stepFor<Input>()({
+  name: "load account",
+  handler: async ({ input }) => ({ account: await fetchAccount(input.accountId) }),
+});
+
+export const createTenant = stepFor<Input, { account: Account }>()({
+  name: "create tenant",
+  handler: async ({ ctx }) => ({ tenantId: await api.create(ctx.account) }),
+  rollbackKeys: ["tenantId"],
+  rollback: async ({ ctx }) => api.destroy(ctx.tenantId),
+});
+```
+
+```ts
+// scripts/signup.ts
+import { Script } from "@michaelrwalker/stagehand";
+import { loadAccount, createTenant } from "../steps/tenancy.js";
+
+const signup = new Script<{ accountId: string }>({ name: "signup" })
+  .addPhase("Account")
+  .addStep(loadAccount)
+  .addPhase("Provision")
+  .addStep(createTenant);
+```
+
+## Core Patterns
+
+### Chaining `stepFor` steps with `WithStepFor` instead of restating `Ctx`
+
+```ts
+import { stepFor, type WithStepFor } from "@michaelrwalker/stagehand";
+
+interface Input {
+  channel: string;
+}
+
+export const logIntoDb = stepFor<Input>()({
+  name: "log into db",
+  handler: async () => ({ conn: await connect() }),
+});
+
+export const loadRules = stepFor<
+  Input,
+  WithStepFor<typeof logIntoDb, { conditions: Array<{ name: string }> }>
+>()({
+  name: "load rules",
+  // ctx.conn comes from logIntoDb's output, ctx.conditions from Rest
+  handler: ({ ctx }) => ({ rules: ctx.conn.query(ctx.conditions) }),
+});
+```
+
+`WithStepFor<Step, Rest>` merges `Step`'s output over `Rest` (which defaults to `{}`), so the second step's `Ctx` doesn't have to be hand-typed against the first step's return shape.
+
+### Nesting `WithStepFor` for a chain three or more steps deep
+
+```ts
+type Ctx = WithStepFor<typeof third, WithStepFor<typeof second, WithStepFor<typeof first, { seed: boolean }>>>;
+```
+
+Read inside out: start with `{ seed: boolean }`, add what `first` returns, then `second`, then `third` — the same order the steps actually run in, and on a name collision the outermost (`third`) wins, matching how a later step's return shadows an earlier key at runtime.
+
+### A shared step library reused across two unrelated scripts
+
+```ts
+// steps/crm.ts — written once, small and generic
+import { stepFor } from "@michaelrwalker/stagehand";
+
+export const fetchContacts = stepFor<{ emails: string[] }>()({
+  name: "fetch contacts",
+  handler: async ({ input }) => ({ contacts: await crm.fetch(input.emails) }),
+});
+
+export const dedupeContacts = stepFor<{ emails: string[] }, { contacts: Contact[] }>()({
+  name: "dedupe contacts",
+  handler: ({ ctx }) => ({ contacts: dedupe(ctx.contacts) }),
+});
+```
+
+```ts
+// scripts/sync-a.ts
+import { Script } from "@michaelrwalker/stagehand";
+import { fetchContacts, dedupeContacts } from "../steps/crm.js";
+
+new Script<{ emails: string[] }>({ name: "sync-a" })
+  .addPhase("Contacts")
+  .addStep(fetchContacts)
+  .addStep(dedupeContacts);
+```
+
+```ts
+// scripts/sync-b.ts — same steps, same import, no logic re-typed
+import { Script } from "@michaelrwalker/stagehand";
+import { fetchContacts, dedupeContacts } from "../steps/crm.js";
+
+new Script<{ emails: string[]; region: string }>({ name: "sync-b" })
+  .addPhase("Contacts")
+  .addStep(fetchContacts)
+  .addStep(dedupeContacts)
+  .addPhase("Region")
+  .addStep({
+    name: "tag region",
+    handler: async ({ input, ctx }) => ({ tagged: ctx.contacts.map((c) => ({ ...c, region: input.region })) }),
+  });
+```
+
+Each script mixes shared and inline steps freely; `addStep` checks each shared step's `Ctx` requirement against whatever the host script has produced so far, at the mount site.
+
+### Reusing a step with a rollback across two scripts
+
+```ts
+// Script one: normal signup
+new Script<{ accountId: string }>({ name: "signup" })
+  .addPhase("Account")
+  .addStep(loadAccount)
+  .addPhase("Provision")
+  .addStep(createTenant); // rollback compensates here if a later step fails
+
+// Script two: written later, reusing the same step and its rollback
+new Script<{ accountId: string; fromRegion: string }>({ name: "migrate" })
+  .addPhase("Prepare")
+  .addStep(loadAccount)
+  .addPhase("Provision")
+  .addStep(createTenant); // same import, same compensation logic
+```
+
+`createTenant`'s rollback is identical wherever it's mounted because it's the exact same function reference each time.
+
+## Common Mistakes
+
+### HIGH Nesting WithStepFor in the reverse of execution order
+
+Wrong:
+```ts
+// "second" actually runs after "first" in the real script, but is nested as if it ran before it
+type Ctx = WithStepFor<typeof first, WithStepFor<typeof second, { conditions: string[] }>>;
+```
+
+Correct:
+```ts
+// nest in the order the steps actually run — innermost first
+type Ctx = WithStepFor<typeof second, WithStepFor<typeof first, { conditions: string[] }>>;
+```
+
+On a name collision the outermost `WithStepFor` wins, matching how a later step's return value shadows an earlier key at runtime — but nothing checks that the nesting order matches the order the steps are actually added to a script, so a reversed nest silently produces a `Ctx` type that disagrees with what the script really does at runtime.
+
+Source: docs/guides/splitting-steps.md ("nothing checks that the steps are added to a script in the order the nesting implies")
+
+### LOW Assuming a reused stepFor step gets independent state per script
+
+Wrong:
+```ts
+// steps/tenancy.ts
+let callCount = 0;
+export const createTenant = stepFor<Input, { account: Account }>()({
+  name: "create tenant",
+  handler: async () => { callCount++; return { tenantId: await api.create() }; },
+});
+// callCount keeps incrementing across every script that imports createTenant
+```
+
+Correct:
+```ts
+// keep per-run state inside ctx/output, not module-level closures, unless sharing is intended
+export const createTenant = stepFor<Input, { account: Account }>()({
+  name: "create tenant",
+  handler: async ({ attempt }) => ({ tenantId: await api.create(), attempt }),
+});
+```
+
+A step imported into two scripts is the exact same function/object reference in both, so any module-scoped mutable state its handler closes over is shared across every script that mounts it, not reset per mount.
+
+Source: docs/guides/splitting-steps.md ("Reusing one step in two scripts" — same function reference each time)
+
+### MEDIUM Writing a bespoke inline step instead of extracting a shared one
+
+Wrong:
+```ts
+// scripts/sync-a.ts
+.addStep({ name: "fetch contacts", handler: async ({ input }) => ({ contacts: await crm.fetch(input.emails) }) })
+
+// scripts/sync-b.ts — same logic, retyped, now two places to fix a bug
+.addStep({ name: "fetch contacts", handler: async ({ input }) => ({ contacts: await crm.fetchContacts(input.emails) }) })
+```
+
+Correct:
+```ts
+// steps/crm.ts — written once, with a small, generic input
+export const fetchContacts = stepFor<{ emails: string[] }>()({
+  name: "fetch contacts",
+  handler: async ({ input }) => ({ contacts: await crm.fetch(input.emails) }),
+});
+// any script that needs it:
+.addStep(fetchContacts)
+```
+
+For a workflow that recurs across scripts, a step written once with a small, generic input composes into every future script at zero type-safety cost (`addStep` still checks it against whatever mounts it), while a fresh inline closure per script forfeits that — the same logic, and any bug in it, has to be rewritten and re-verified in every script separately.
+
+Source: maintainer interview ("keep a file of common steps, with simple inputs so you can easily compose scripts... this will save developers a ton of time and costs nothing as far as type safety is concerned")