@michaelrwalker/stagehand 0.8.0 → 0.10.0

package/skills/building-scripts/branching-steps/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: 'branching-steps'
+description: >
+  Covers `addBranch` — a step that runs `onTrue` or `onFalse` depending on `condition`, with both
+  arms required to return the same shape so `ctx` stays accurately typed whichever one ran. Load this
+  for "an override flag changes how a value is produced but later steps need it either way," "do X or
+  Y and keep the context typed," or when `when` skipped a step and a later step crashed on a missing
+  `ctx` key.
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.8.0'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
+  - 'miaklwalker/stagehand:docs/reference/script.md'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:test/branch.test.ts'
+---
+
+# Stagehand — Branching Steps
+
+`addBranch` is a step with an if/else inside it. `condition` picks the arm, `onTrue` / `onFalse` do the work, and both return the same shape — so every later step sees one `ctx` type, no matter which arm ran. Use it instead of `when` whenever later steps depend on what the step produces.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+const result = await new Script<{ service: string }>({ name: "deploy" })
+  .defineFlag({ name: "sha" })
+  .addPhase("Resolve")
+  .addBranch({
+    name: "resolve commit",
+    condition: ({ flags }) => Boolean(flags.sha),
+    onTrue: ({ flags }) => ({ sha: flags.sha as string }),
+    onFalse: async ({ input }) => ({ sha: await git.head(input.service) }),
+  })
+  .addStep({
+    name: "build",
+    handler: ({ ctx }) => ({ image: `app:${ctx.sha}` }), // ctx.sha: string
+  })
+  .run({ service: "checkout-api" }, { argv: ["--sha", "abc1234"] });
+```
+
+## Core Patterns
+
+### Everything a handler gets, in all three functions
+
+`condition`, `onTrue` and `onFalse` each receive the normal step context — `input`, `ctx`, `flags`, `status`, `note`, `log`, `prompt`, `signal`. `condition` may be async and runs once per attempt; only the chosen arm executes.
+
+```ts
+.addBranch({
+  name: "pick target",
+  condition: async ({ ctx }) => await isReachable(ctx.host),
+  onTrue: ({ ctx }) => ({ target: ctx.host }),
+  onFalse: async ({ prompt }) => ({ target: await prompt.text({ message: "fallback host?", default: "localhost" }) }),
+})
+```
+
+### Retry and timeout cover the whole branch
+
+```ts
+.addBranch({
+  name: "resolve commit",
+  retry: { attempts: 3, delayMs: 250 },
+  timeoutMs: 10_000,
+  condition: ({ flags }) => Boolean(flags.sha),
+  onTrue: ({ flags }) => ({ sha: flags.sha as string }),
+  onFalse: async ({ input }) => ({ sha: await git.head(input.service) }),
+})
+```
+
+A retry re-evaluates `condition` and re-runs the arm. Those two options, plus `name` and `description`, are the whole surface.
+
+### Caching a branch: cache the phase
+
+```ts
+.addPhase("Resolve", { cache: store })
+.addBranch({ name: "resolve commit", /* ... */ })
+```
+
+A branch has no `cache` of its own. A cached phase stores the merged output of every step in it, branch included.
+
+## Common Mistakes
+
+### HIGH Using `when` where later steps need the output
+
+Wrong:
+```ts
+.addStep({ name: "head sha", when: ({ flags }) => !flags.sha, handler: async () => ({ sha: await git.head() }) })
+.addStep({ name: "build", handler: ({ ctx }) => ctx.sha.slice(0, 7) }) // compiles; crashes with --sha set
+```
+
+Correct:
+```ts
+.addBranch({
+  name: "resolve commit",
+  condition: ({ flags }) => Boolean(flags.sha),
+  onTrue: ({ flags }) => ({ sha: flags.sha as string }),
+  onFalse: async () => ({ sha: await git.head() }),
+})
+```
+
+`when` skips the step but `ctx` is still typed as though it ran. A branch always produces the keys.
+
+### MEDIUM Arms returning different shapes
+
+Wrong:
+```ts
+onTrue: () => ({ sha: "abc" }),
+onFalse: () => ({ commit: "abc" }), // compile error on onFalse
+```
+
+Correct:
+```ts
+onTrue: () => ({ sha: "abc" }),
+onFalse: () => ({ sha: "abc" }),
+```
+
+`onTrue`'s return type fixes `Out`; `onFalse` must be assignable to it. If one path has no value, return an explicit default (`{ sha: undefined }` on both arms, or `sha: string | undefined` in `onTrue`) rather than omitting the key.
+
+### MEDIUM Expecting `rollback`, `cache`, `clean` or `when` on a branch
+
+Wrong:
+```ts
+.addBranch({ name: "b", condition, onTrue, onFalse, rollback: async () => {} }) // not accepted
+```
+
+Correct:
+```ts
+// If the work needs compensation, make it a plain addStep with its own rollback
+// and branch inside the handler; cache the enclosing phase; clean in a later step.
+.addStep({
+  name: "provision",
+  handler: async ({ input }) => ({ id: input.existingId ?? (await create()) }),
+  rollback: async ({ output }) => destroy(output.id),
+})
+```
+
+A branch is intentionally minimal: no compensation, no step-level cache, no `clean`, no `when`.
+
+Source: docs/guides/phases-and-steps.md; src/types.ts `BranchDef`
+
+See also: skills/compensation-safety/conditional-steps/SKILL.md — `when` is for work that may simply not happen; `addBranch` is for work that always happens in one of two ways.

package/skills/building-scripts/command-line-flags/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: 'command-line-flags'
+description: >
+  Covers `defineFlag` and `context.flags` — typed string and boolean flags parsed from argv once before
+  any phase runs, `long`/`short` aliases, defaults, `UnknownFlagError` / `MissingFlagValueError`,
+  `run(input, { argv })` for tests, and mapping a flag onto a mounted routine's input. Load this for
+  "add a --force or --env flag," "gate a step on a CLI flag," or "test a script with flags."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.8.0'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/flags.md'
+  - 'miaklwalker/stagehand:docs/reference/script.md'
+  - 'miaklwalker/stagehand:src/flags.ts'
+  - 'miaklwalker/stagehand:src/script.ts'
+  - 'miaklwalker/stagehand:test/flags.test.ts'
+---
+
+# Stagehand — Command-Line Flags
+
+`defineFlag` declares a flag. `run()` parses `process.argv` once, before any phase, and every step, `when`, `stale` and rollback receives the result as `flags`, typed from the declarations.
+
+## Setup
+
+```ts
+import { Script } from "@michaelrwalker/stagehand";
+
+await new Script({ name: "deploy" })
+  .defineFlag({ name: "environment", long: "env", short: "e", default: "staging" })
+  .defineFlag({ name: "force", short: "f", boolean: true })
+  .addStep({
+    name: "ship",
+    handler: ({ flags }) => {
+      // flags.environment: string   flags.force: boolean
+      return { env: flags.environment };
+    },
+  })
+  .run();
+// myScript --env production -f
+```
+
+## Core Patterns
+
+### String vs boolean
+
+A string flag with a `default` is `string`; without one it is `string | undefined`. A boolean flag (`boolean: true`) is presence-based, never consumes the next token, and resolves to `default ?? false`. `--flag=value` and `--flag value` both work; `--force=false` is honoured.
+
+### Gate work on a flag
+
+```ts
+.addPhase("Publish", { when: ({ flags }) => flags.production })
+.addStep({ name: "notify", when: ({ flags }) => !flags.quiet, handler: async () => {} })
+.addPhase("Build", { cache: { store, stale: ({ flags }) => flags.fresh } })
+```
+
+When the flag changes *how* a value is produced rather than *whether* a step runs, use `addBranch` (see skills/building-scripts/branching-steps/SKILL.md).
+
+### Test with `argv`
+
+```ts
+const result = await script.run({ service: "api" }, { argv: ["--env", "production"] });
+```
+
+`argv` replaces `process.argv.slice(2)`; use it in tests and when the script is one subcommand of a bigger CLI.
+
+### Hand a flag to a routine
+
+```ts
+new Script({ name: "sync" })
+  .defineFlag({ name: "environment", long: "env", default: "staging" })
+  .use(pullChannel, { input: ({ flags }) => ({ env: flags.environment }) })
+```
+
+## Common Mistakes
+
+### HIGH Declaring flags on a routine
+
+Wrong:
+```ts
+routineFor<{ env: string }>()("pull", (script) => script.defineFlag({ name: "env" })) // flags are top-level only
+```
+
+Correct:
+```ts
+// declare on the script you run; pass it down through use()'s input mapper
+```
+
+`defineFlag` belongs to the entry script. A mounted script's flags are not merged into the host, and a routine's `flags` are typed loosely (`Record<string, unknown>`).
+
+### MEDIUM Expecting `run()` to return `{ ok: false }` for a bad flag
+
+Wrong:
+```ts
+const result = await script.run(undefined, { argv: ["--nope"] });
+if (!result.ok) { /* never reached */ }
+```
+
+Correct:
+```ts
+try { await script.run(undefined, { argv }); }
+catch (error) { if (error instanceof UnknownFlagError) console.error(error.flag); }
+```
+
+`UnknownFlagError` and `MissingFlagValueError` are thrown directly, before any phase, and ignore `throwOnError`.
+
+### MEDIUM Assuming undeclared flags are always rejected
+
+A script with **no** `defineFlag` call ignores argv entirely; the unknown-flag check starts at the first declaration. Adding a first flag can therefore break a script that read `process.argv` by hand.
+
+### LOW Duplicate names
+
+`defineFlag` throws `DuplicateNameError` (`kind: "flag"`) if `name`, the resolved long form, or `short` is already used.
+
+Source: docs/guides/flags.md; src/flags.ts

package/skills/building-scripts/getting-started/SKILL.md

@@ -7,7 +7,7 @@ description: >
 metadata:
   type: 'lifecycle'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:README.md'
   - 'miaklwalker/stagehand:docs/quick-start.md'

package/skills/building-scripts/prompting-the-user/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: 'prompting-the-user'
+description: >
+  Covers `context.prompt` — `text`, `confirm`, `select` and `multiselect` asked mid-step, the
+  non-interactive `default` fallback, `PromptUnavailableError`, and Ctrl-C cancellation via
+  `PromptCancelledError`. Load this for "ask for confirmation before a destructive step," "let the
+  user pick an environment," or "make an interactive script runnable in CI."
+metadata:
+  type: 'core'
+  library: 'stagehand'
+  library_version: '0.8.0'
+sources:
+  - 'miaklwalker/stagehand:docs/guides/prompts.md'
+  - 'miaklwalker/stagehand:docs/reference/errors.md'
+  - 'miaklwalker/stagehand:src/ui/prompt.ts'
+  - 'miaklwalker/stagehand:test/prompt.test.ts'
+---
+
+# Stagehand — Prompting the User
+
+`prompt` is on a step handler's context. Calling it suspends the live frame, draws the question, and repaints once answered. It is hand-rolled on the renderer's ANSI primitives, so there is no extra dependency.
+
+## Setup
+
+```ts
+.addStep({
+  name: "confirm production",
+  handler: async ({ flags, prompt }) => {
+    if (flags.environment === "production" && !flags.force) {
+      const ok = await prompt.confirm({ message: "Deploy to production?", default: false });
+      if (!ok) throw new Error("cancelled by user");
+    }
+    return {};
+  },
+})
+```
+
+## Core Patterns
+
+| method | resolves to |
+| --- | --- |
+| `prompt.text({ message, default?, placeholder?, validate?, mask? })` | `string` |
+| `prompt.confirm({ message, default? })` | `boolean` |
+| `prompt.select({ message, choices, default? })` | the chosen `value` |
+| `prompt.multiselect({ message, choices, default?, min?, max? })` | `value[]` |
+
+`choices` are `{ label, value, hint? }`. `validate` returns `true` or an error string, may be async. `mask: true` echoes `•`.
+
+### Always give a `default` if the script may run unattended
+
+With no TTY (CI, a pipe) nothing is drawn: a `default` is returned immediately, and a missing one throws `PromptUnavailableError`.
+
+### Prefer a flag, prompt only as the fallback
+
+```ts
+const environment = flags.environment ?? (await prompt.select({ message: "environment?", choices, default: "staging" }));
+```
+
+## Common Mistakes
+
+### HIGH Prompting without a `default` in a script CI runs
+
+Wrong:
+```ts
+const tag = await prompt.text({ message: "release tag?" }); // PromptUnavailableError under CI
+```
+
+Correct:
+```ts
+const tag = await prompt.text({ message: "release tag?", default: "latest" });
+```
+
+### MEDIUM Treating Ctrl-C at a prompt as a handler failure
+
+Wrong:
+```ts
+if (!result.ok) report(result.error); // reports a cancellation as a bug
+```
+
+Correct:
+```ts
+if (!result.ok && isAbort(result.error)) { /* result.status === "aborted"; rollback policy applied */ }
+```
+
+`PromptCancelledError` is recognised by `isAbort`, so the run unwinds exactly like a SIGINT.
+
+### MEDIUM Prompting from a rollback
+
+`prompt` exists only on `StepContext`. A rollback runs during an unwind and cannot stop to ask; decide inside the step and keep what the rollback needs in `rollbackKeys`.
+
+Source: docs/guides/prompts.md; src/ui/prompt.ts

package/skills/building-scripts/structuring-phases-and-steps/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
   - 'miaklwalker/stagehand:docs/guides/script-options-and-result.md'
@@ -60,6 +60,10 @@ new Script<{ n: number }>({ name: "t" })
 
 The callback form groups a phase's steps visually while preserving the same type flow as the flat form; the two are interchangeable.
 
+### Two ways to do one step: `addBranch`
+
+`addBranch({ name, condition, onTrue, onFalse })` runs one of two arms that return the same shape, so the context stays typed either way. It takes `retry` and `timeoutMs` like any step, but no `rollback`, `cache` or `clean`. See skills/building-scripts/branching-steps/SKILL.md.
+
 ### Retry with backoff and veto specific errors
 
 ```ts

package/skills/building-scripts/typed-context-and-input/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/typed-context.md'
   - 'miaklwalker/stagehand:docs/reference/errors.md'

package/skills/caching/caching-expensive-work/SKILL.md

@@ -1,16 +1,17 @@
 ---
 name: 'caching-expensive-work'
 description: >
-  fileStore/memoryStore, per-slot stale/schema options, per-run CacheMode
+  fileStore/memoryStore, per-slot key/stale/schema options, per-run CacheMode
   ("on"/"off"/"refresh"/"read-only"), and reaching a cached slot with
   context.cache (read/write/clear/ageOf) from a later step or rollback. Load
   this for "skip re-running an expensive phase," "invalidate a cache entry
   from a later step," "correct a cached value without resetting its TTL," or
-  "guard a cache entry against an old script shape."
+  "guard a cache entry against an old script shape," or "rerun a step only
+  when its input changed since last time."
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/caching.md'
   - 'miaklwalker/stagehand:docs/reference/cache.md'
@@ -23,9 +24,9 @@ sources:
 # Stagehand — Caching Expensive Work
 
 A phase or step can point at a store and stop repeating its work on later
-runs. There is no cache key to pass: a slot's name is derived from the
-phase's or step's own name, and whether a hit is still good is entirely
-`stale`'s job.
+runs. A slot's name is derived from the phase's or step's own name, and it
+holds one entry. Whether that entry can be reused is up to `key` (was it
+computed for the same thing?) and `stale` (is it still fresh?).
 
 ## Setup
 
@@ -71,16 +72,32 @@ const BuildSchema = z.object({ artifact: z.string() });
   name: "compile",
   cache: {
     store: cache,
-    stale: ({ value, ctx, ageMs }) => ageMs > 3_600_000,
+    stale: ({ value, ctx, flags, ageMs }) => flags.fresh || ageMs > 3_600_000,
     schema: BuildSchema,
   },
   handler: async ({ input }) => ({ artifact: `dist/${input.ref}.tgz` }),
 })
 ```
 
-`stale` and `schema` both see the live context as of that step; a stored
+`stale` and `schema` both see the live context as of that step (`stale` also gets `flags`, so a `--fresh` flag can force a miss); a stored
 value that fails `schema` is treated as a miss, not an error.
 
+### Rerunning only when the input changed, with `key`
+
+```ts
+.addStep({
+  name: "price",
+  cache: { store: cache, key: ({ ctx }) => [...ctx.skus].sort().join(",") },
+  handler: async ({ ctx }) => ({ prices: await priceAll(ctx.skus) }),
+})
+```
+
+`key` returns a string, stored with the entry and compared with `===` next
+run. Same key hits; a different key — or an entry written before `key` was
+added — reruns and overwrites, reported as `cacheMiss: "key changed"` on the
+`StepReport`. There is one entry, not one per key. The function owns
+equality: sort when order doesn't matter, serialise objects deliberately.
+
 ### Controlling caching per run without touching the script
 
 ```ts
@@ -238,6 +255,47 @@ A store that throws — an unreadable file, a full disk, a buggy `stale` predica
 
 Source: docs/guides/caching.md ("A store that throws... logs a warning and does the work")
 
+### HIGH Encoding a cache key through `stale` and a returned field
+
+Wrong:
+```ts
+.addStep({
+  name: "price",
+  cache: { store, stale: ({ value, ctx }) => (value as { sku: string }).sku !== ctx.sku },
+  handler: async ({ ctx }) => ({ sku: ctx.sku, price: await price(ctx.sku) }), // sku leaks into ctx
+})
+```
+
+Correct:
+```ts
+.addStep({
+  name: "price",
+  cache: { store, key: ({ ctx }) => ctx.sku },
+  handler: async ({ ctx }) => ({ price: await price(ctx.sku) }),
+})
+```
+
+`key` stores the fingerprint beside the entry instead of inside the value, so the handler's output — and the context type downstream — carries only what later steps need.
+
+Source: README.md ("Caching"); src/cache.ts readCache()
+
+### MEDIUM Returning a non-canonical key
+
+Wrong:
+```ts
+cache: { store, key: ({ ctx }) => ctx.skus.join(",") }        // API order varies run to run
+cache: { store, key: ({ ctx }) => JSON.stringify(ctx.filter) } // object key order varies too
+```
+
+Correct:
+```ts
+cache: { store, key: ({ ctx }) => [...ctx.skus].sort().join(",") }
+```
+
+Keys are compared with `===` and the library never normalises them, so two orderings of the same data are two keys — a needless miss every time the order shifts.
+
+Source: README.md ("Caching")
+
 ### MEDIUM Patching a value with `cache.write` and losing its age
 
 Wrong:

package/skills/caching/caching-expensive-work/references/cache-api.md

@@ -83,11 +83,12 @@ const stepSlot = (phase: string, step: string): string => `${phase}::${step}`;
 interface CachedEntry {
   value: unknown;
   savedAt: number; // Date.now() at the moment it was written
+  key?: string;    // what `key` returned on the run that wrote it, if declared
 }
 ```
 
 The exact shape a `CacheStore` reads and writes — one stored result plus its
-write timestamp.
+write timestamp, and the key it was computed for when the slot declares one.
 
 ## `CacheSource<In, Ctx, Value>`
 
@@ -107,12 +108,21 @@ expands it to `{ store: source }`; anything else is passed through as
 ```ts
 interface CacheOptions<In = unknown, Ctx = unknown, Value = unknown> {
   store: CacheStore;
+  key?: (context: KeyContext<In, Ctx>) => Awaitable<string>;
   stale?: (context: StaleContext<In, Ctx>) => Awaitable<boolean>;
   schema?: StandardSchemaV1<unknown, Value>;
 }
 ```
 
-- `store` is required; `stale` and `schema` are both optional.
+- `store` is required; `key`, `stale` and `schema` are all optional.
+- `key` is evaluated once, against `{ input, ctx, flags }` as they stand
+  entering the phase or step, before the read. Its string is compared with
+  `===` against the stored entry's `key`; a mismatch (including an entry with
+  no key) is a miss with reason `"key changed"`, and the write that follows
+  stores the new key. There is still one entry per slot — it is not a memo
+  table. A `key` that throws or returns a non-string logs a warning, runs the
+  work, and neither reads nor writes the slot. `run(…, { cache: "off" })`
+  never calls it.
 - `stale` returning `true` treats a stored entry as a miss — the work runs
   again and the entry is overwritten on success.
 - `schema`, when given, validates the stored value on every read via
@@ -157,18 +167,18 @@ Passed as `run(input, { cache })`. Default is `"on"`.
 Implementation detail from `src/cache.ts`:
 
 ```ts
-export async function readCache(cache, slot, input, ctx, mode) {
+export async function readCache(cache, slot, key, input, ctx, mode, flags) {
   if (mode === "off" || mode === "refresh") return MISS;
-  // ...store.read, schema validate, stale check...
+  // ...store.read, key compare, schema validate, stale check...
 }
 
-export async function writeCache(cache, slot, value, mode) {
+export async function writeCache(cache, slot, value, key, mode) {
   if (mode === "off" || mode === "read-only") return;
-  await cache.store.write(slot, { value, savedAt: Date.now() });
+  await cache.store.write(slot, { value, savedAt: Date.now(), key });
 }
 ```
 
-A store or `stale`/`schema` call that throws is caught elsewhere in
+A store or `key`/`stale`/`schema` call that throws is caught elsewhere in
 `script.ts` and treated as a miss with a logged warning — caching never
 decides whether the run itself passes or fails.
 

package/skills/compensation-safety/adding-rollbacks/SKILL.md

@@ -10,7 +10,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/rollbacks.md'
   - 'miaklwalker/stagehand:docs/reference/errors.md'
@@ -26,6 +26,8 @@ completed, first undone. The step that actually failed is never compensated: it
 there's nothing to undo. A rollback gets no context by default; it has to name every key it needs
 through `rollbackKeys`, which both narrows and permanently reserves them.
 
+Rollback timing, retries and scope are specified exactly in docs/guides/error-handling.md (summary: skills/errors-results/handling-results-and-errors/SKILL.md, "The failure contract"). Notably, retries do not trigger rollback and the failed step is never rolled back.
+
 ## Setup
 
 ```ts

package/skills/compensation-safety/cleaning-context/SKILL.md

@@ -5,7 +5,7 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/cleaning-context.md'
   - 'miaklwalker/stagehand:src/script.ts'

package/skills/compensation-safety/conditional-steps/SKILL.md

@@ -8,16 +8,17 @@ description: >
 metadata:
   type: 'core'
   library: 'stagehand'
-  library_version: '0.5.3'
+  library_version: '0.8.0'
 sources:
   - 'miaklwalker/stagehand:docs/guides/phases-and-steps.md'
   - 'miaklwalker/stagehand:docs/guides/reusable-scripts.md'
+  - 'miaklwalker/stagehand:docs/guides/flags.md'
   - 'miaklwalker/stagehand:src/script.ts'
 ---
 
 # Stagehand — Conditional Steps and Phases
 
-`when` on `addStep` or `addPhase` is a function of `{ input, ctx }` (may be async) that gates whether the step, or every step in the phase, runs at all. A falsy result marks the step `"skipped"` — it never runs its handler and never runs its `rollback`.
+`when` on `addStep` or `addPhase` is a function of `{ input, ctx, flags }` (may be async) that gates whether the step, or every step in the phase, runs at all. A falsy result marks the step `"skipped"` — it never runs its handler and never runs its `rollback`.
 
 ## Setup
 
@@ -58,7 +59,7 @@ new Script<{ environment: "development" | "production" }>({ name: "deploy" })
   });
 ```
 
-`when` sees the same `{ input, ctx }` shape a handler does, so it can read anything an earlier step already put in context.
+`when` sees the same `{ input, ctx, flags }` a handler does, so it can read anything an earlier step already put in context, and any `defineFlag` value (`when: ({ flags }) => !flags.quiet`).
 
 ### Gate an entire phase
 
@@ -87,6 +88,21 @@ A falsy phase-level `when` marks every step in `"Release"` `"skipped"` in one sh
 
 `when` may return a promise; the script awaits it before deciding whether to run or skip the step (or, at phase level, the whole phase).
 
+### Need the output either way? Use `addBranch`
+
+A skipped step produces nothing, but `ctx` is still typed as though it ran. When later steps depend on the value, pick between two ways of producing it instead:
+
+```ts
+.addBranch({
+  name: "resolve commit",
+  condition: ({ flags }) => Boolean(flags.sha),
+  onTrue: ({ flags }) => ({ sha: flags.sha as string }),
+  onFalse: async () => ({ sha: await git.head() }),
+})
+```
+
+See skills/building-scripts/branching-steps/SKILL.md.
+
 ## Common Mistakes
 
 ### MEDIUM Skipped step's `clean` still runs