@michaelrwalker/stagehand 0.7.0 → 0.9.0

package/dist/types.d.ts

@@ -7,12 +7,34 @@ export type Prettify<T> = {
 /**
  * Context after a step contributes `Out`. A step that returns nothing leaves
  * the context untouched; later keys win over earlier ones.
+ *
+ * Written to stay *flat*. `Script`'s context parameter is rebuilt by every
+ * `addStep`, so whatever this produces is fed straight back in as the next
+ * call's `Ctx` — a hundred links deep in a long script. TypeScript re-walks
+ * that accumulated type on each link, and its instantiation depth limit (100)
+ * is reached after `depth-per-link × links` — so every layer this adds costs
+ * roughly a hundredth of the longest chain a script may have before
+ * `TS2589: Type instantiation is excessively deep` lands on the whole chain.
+ *
+ * A plain intersection is the one shape that costs nothing: TypeScript
+ * flattens `A & B & C` into a single list of leaves and stops. A mapped type —
+ * `Omit`, `Pick`, `Prettify` — does not flatten, so a chain of them has to be
+ * walked one level per link. Hence, the three-way split: shadowing a key needs
+ * `Omit` and pays for it, and the overwhelmingly common case of a step adding
+ * fresh keys does not.
+ *
+ * `Prettify` deliberately does *not* appear here. It is applied where the
+ * context is read — a handler's `ctx`, `RunResult.ctx` — which is where a
+ * tooltip is actually wanted, and which is a leaf rather than a link.
  */
-export type Merge<Ctx, Out> = [Out] extends [void] ? Ctx : [Out] extends [undefined] ? Ctx : Prettify<Omit<Ctx, keyof Out> & Out>;
+export type Merge<Ctx, Out> = [Out] extends [void] ? Ctx : [Out] extends [undefined] ? Ctx : [Extract<keyof Ctx, keyof Out>] extends [never] ? Ctx & Out : Omit<Ctx, keyof Out> & Out;
 /**
  * Context with `Keys` dropped — what `clean` leaves behind for later steps.
+ *
+ * Identity when nothing is being cleaned, for the reason spelled out on
+ * {@link Merge}: the `Omit` is a chain link, and almost no step cleans.
  */
-export type Cleaned<Ctx, Keys extends PropertyKey> = Prettify<Omit<Ctx, Keys>>;
+export type Cleaned<Ctx, Keys extends PropertyKey> = [Keys] extends [never] ? Ctx : Omit<Ctx, Keys>;
 /**
  * The slice of the context a `rollback` sees: exactly the keys it asked for
  * via `rollbackKeys`, and nothing else. With no keys declared it is `{}` — a
@@ -80,12 +102,14 @@ export interface CacheStore {
     clear(slot: string): Awaitable<void>;
 }
 /** What `stale` gets to decide on. */
-export interface StaleContext<In, Ctx> {
+export interface StaleContext<In, Ctx, Flags = unknown> {
     /** The stored value — the phase's context delta, or the step's return value. */
     value: unknown;
     input: In;
     /** The live context as it stands right now, *before* the entry is applied. */
     ctx: Ctx;
+    /** Values parsed from every `defineFlag` this script declared. */
+    flags: Flags;
     /** Wall-clock ms at which the entry was written. */
     savedAt: number;
     /** How old the entry is, in ms. A TTL is `({ ageMs }) => ageMs > 3_600_000`. */
@@ -98,14 +122,14 @@ export interface StaleContext<In, Ctx> {
  * There is no key: the store *is* the identity. Whether an entry is still
  * usable is `stale`'s job, and nothing else's.
  */
-export interface CacheOptions<In = unknown, Ctx = unknown, Value = unknown> {
+export interface CacheOptions<In = unknown, Ctx = unknown, Value = unknown, Flags = unknown> {
     store: CacheStore;
     /**
      * Return true to treat the stored entry as a miss — the work runs again and
      * the entry is overwritten. Given `value` as `unknown`; annotate the
      * parameter yourself, or hand over a `schema` and let it do the narrowing.
      */
-    stale?: (context: StaleContext<In, Ctx>) => Awaitable<boolean>;
+    stale?: (context: StaleContext<In, Ctx, Flags>) => Awaitable<boolean>;
     /**
      * Checked against the stored value on every read. A stored value that no
      * longer fits is a **miss**, not an error — which is what keeps a cache
@@ -114,7 +138,7 @@ export interface CacheOptions<In = unknown, Ctx = unknown, Value = unknown> {
      */
     schema?: StandardSchemaV1<unknown, Value>;
 }
-export type CacheSource<In = unknown, Ctx = unknown, Value = unknown> = CacheStore | CacheOptions<In, Ctx, Value>;
+export type CacheSource<In = unknown, Ctx = unknown, Value = unknown, Flags = unknown> = CacheStore | CacheOptions<In, Ctx, Value, Flags>;
 /**
  * The value type a slot reads back as.
  *
@@ -290,8 +314,14 @@ export interface PromptHandle {
 export interface StepContext<In, Ctx, Slots = UnknownSlots, Flags = UnknownFlags> {
     /** The input the script was run with. */
     readonly input: In;
-    /** Data produced by every step that has already succeeded. */
-    readonly ctx: Ctx;
+    /**
+     * Data produced by every step that has already succeeded.
+     *
+     * `Prettify` here rather than on {@link Merge}: this is a leaf — nothing is
+     * accumulated off it — so flattening for the tooltip costs one instantiation
+     * instead of one per step in the whole chain.
+     */
+    readonly ctx: Prettify<Ctx>;
     /** Aborts on timeout, on Ctrl-C, or when `run` is canceled. */
     readonly signal: AbortSignal;
     /** 1 on the first try, 2 on the first retry, and so on. */
@@ -403,6 +433,7 @@ export interface StepDef<In, Ctx, Out, RollbackKeys extends readonly PropertyKey
     when?: (context: {
         input: In;
         ctx: Ctx;
+        flags: Flags;
     }) => Awaitable<boolean>;
     /**
      * Reuse this step's return value from a previous run instead of running the
@@ -415,7 +446,30 @@ export interface StepDef<In, Ctx, Out, RollbackKeys extends readonly PropertyKey
      * cache: { store: fileStore("./cache.json"), stale: ({ ageMs }) => ageMs > 60_000 }
      * ```
      */
-    cache?: CacheSource<In, Ctx>;
+    cache?: CacheSource<In, Ctx, unknown, Flags>;
+    retry?: RetryPolicy;
+    timeoutMs?: number;
+}
+/**
+ * A step that does one of two jobs and hands back the same shape either way.
+ *
+ * `onTrue` is the source of truth for `Out`; `onFalse` has to return something
+ * assignable to it, so every later step sees one `ctx` type whichever arm ran.
+ * That is the difference from `when`, which skips a step and leaves nothing
+ * behind for the steps that depended on it.
+ *
+ * Deliberately small: no `rollback`, no `cache`, no `clean`. Cache the phase
+ * the branch sits in, and `clean` in a later step.
+ */
+export interface BranchDef<In, Ctx, Out, Slots = UnknownSlots, Flags = UnknownFlags> {
+    name: string;
+    description?: string;
+    /** Picks the arm. May be async; evaluated once per attempt. */
+    condition: (context: StepContext<In, Ctx, Slots, Flags>) => Awaitable<boolean>;
+    /** Runs when `condition` resolves truthy. Its return type fixes `Out`. */
+    onTrue: (context: StepContext<In, Ctx, Slots, Flags>) => Awaitable<Out>;
+    /** Runs otherwise. Must return the same shape as `onTrue`. */
+    onFalse: (context: StepContext<In, Ctx, Slots, Flags>) => Awaitable<NoInfer<Out>>;
     retry?: RetryPolicy;
     timeoutMs?: number;
 }
@@ -467,9 +521,10 @@ export interface InheritedKeyStepDef<In, Ctx, Out, RollbackKeys extends readonly
     when?: (context: {
         input: In;
         ctx: Ctx;
+        flags: Flags;
     }) => Awaitable<boolean>;
     /** See {@link StepDef.cache}. */
-    cache?: CacheSource<In, Ctx>;
+    cache?: CacheSource<In, Ctx, unknown, Flags>;
     retry?: RetryPolicy;
     timeoutMs?: number;
 }
@@ -518,12 +573,13 @@ export type WithStepFor<Step extends {
 }, Rest extends object = {}> = Step extends {
     handler: (context: never) => infer Out;
 } ? Merge<Rest, Awaited<Out>> : never;
-export interface PhaseOptions<In = unknown, Ctx = unknown> {
+export interface PhaseOptions<In = unknown, Ctx = unknown, Flags = unknown> {
     description?: string;
     /** Skip every step in the phase when this resolves falsy. */
     when?: (context: {
         input: In;
         ctx: Ctx;
+        flags: Flags;
     }) => Awaitable<boolean>;
     /**
      * Reuse this phase's work from a previous run. What gets stored is the
@@ -531,8 +587,9 @@ export interface PhaseOptions<In = unknown, Ctx = unknown> {
      * anything they cleaned — so a hit skips every step and merges that delta
      * over the live context, leaving keys from earlier phases alone.
      *
-     * `stale` and `when` see the context as it stands when the phase is reached,
-     * which is exactly `Ctx` here, so both are typed without any annotation.
+     * `stale` and `when` see the context (and `flags`) as they stand when the
+     * phase is reached, which is exactly `Ctx`/`Flags` here, so both are typed
+     * without any annotation.
      *
      * ```ts
      * .addPhase("Build", {
@@ -543,7 +600,7 @@ export interface PhaseOptions<In = unknown, Ctx = unknown> {
      * })
      * ```
      */
-    cache?: CacheSource<In, Ctx>;
+    cache?: CacheSource<In, Ctx, unknown, Flags>;
 }
 export interface ScriptOptions {
     name?: string;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@michaelrwalker/stagehand",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Fully typesafe saga-style script framework with modern terminal visuals",
   "homepage": "https://michaelrwalker.netlify.app/stagehand",
   "type": "module",

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

@@ -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/caching.md'
   - 'miaklwalker/stagehand:docs/reference/cache.md'
@@ -71,14 +71,14 @@ 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.
 
 ### Controlling caching per run without touching the script