@field/cascade 0.8.0 → 0.11.0

package/doc/MCP.md

@@ -0,0 +1,69 @@
+# MCP server
+
+`cascade mcp [project-directory]` serves the CLI as MCP tools over stdio, so an agent calls `set` instead of shelling out and parsing text. The tools are the CLI's commands under the same names, and every result is the same `--json` envelope (`{ ok, data, warnings }`, or `{ ok: false, error, warnings }` with `isError` set). Graph paths are relative to the project directory and may not leave it.
+
+## Set it up in Claude Code
+
+From the project directory:
+
+```sh
+claude mcp add cascade -- npx --no-install cascade mcp .
+```
+
+Or in the project's `.mcp.json`, so every session in the project has it:
+
+```json
+{
+  "mcpServers": {
+    "cascade": { "command": "npx", "args": ["--no-install", "cascade", "mcp", "."] }
+  }
+}
+```
+
+With a global install (`npm i -g @field/cascade`), use `"command": "cascade", "args": ["mcp", "."]`. The tools then appear as `mcp__cascade__set`, `mcp__cascade__render` and so on.
+
+## Tools
+
+| Tool | CLI equivalent |
+| --- | --- |
+| `graph_list`, `graph_read`, `graph_create` | `cascade graph list \| read \| create` |
+| `node_add`, `node_remove` | `cascade node add \| rm` |
+| `connect`, `disconnect` | `cascade connect \| disconnect` |
+| `set` | `cascade set` (value, `expression`, `keys`, `removeKeys`, `interpolation`, `unset`) |
+| `subnet_create`, `subnet_move`, `subnet_dissolve` | `cascade subnet create \| move \| dissolve` |
+| `edit` | `cascade edit` (a batch of operations, all or nothing) |
+| `check`, `inspect` | `cascade check \| inspect` |
+| `cook` | `cascade run <graph> [--node <id>]` |
+| `render` | `cascade run <graph> --frames … [--fps] [--out] [--node]… [--scene]` |
+| `export` | `cascade export <graph> --plan \| --out <dir>` |
+| `lock`, `replay`, `locks` | `cascade lock <graph> <node> --name`, `cascade replay <id> [--live]`, `cascade locks` |
+| `ladder`, `pick` | `cascade ladder <graph> <node> --name --vary node.prop=a,b,c \| --seeds a,b,c` (`vary` is `{ "node.prop": [a, b, c] }`), `cascade pick <ladder> <n>` |
+| `node_help` | `cascade help node [<type>]` (a node type's declaration; every type without one) |
+| `doctor` | `cascade doctor [--fix]` (Python environment, stage interpreter, ffmpeg, canvas; `fix` builds the environment) |
+
+The editing tools take `dryRun`. Reads and edits run inside the server through the same functions the CLI commands call. Cooking, rendering, checking, exporting and the lock tools run `cascade <command> --json` as one child process each, so a long render leaves nothing behind in the server and returns exactly what the CLI would print. Calls run one at a time, so two edits to one file never interleave.
+
+Each tool is an `mcp` entry on its command's row in `src/cli/verbs.ts`, with its description and input schema, so a tool cannot name a command this build does not have (`tests/cli-verbs.test.ts` checks every tool against the table and this page).
+
+## A session
+
+```text
+graph_read   { "graph": "index.cascade" }
+node_add     { "graph": "index.cascade", "type": "Transform", "set": { "rotate": 0.4 } }
+connect      { "graph": "index.cascade", "from": "motif.output_0", "to": "transform.geometry" }
+set          { "graph": "index.cascade", "target": "render.opacity", "keys": [{ "frame": 1, "value": 0.25 }, { "frame": 48, "value": 1 }] }
+render       { "graph": "index.cascade", "frames": "1-48", "out": "renders/check" }
+```
+
+See `doc/CLI_REFERENCE.md` for what each operation guarantees about diffs, placement and subnet boundaries.
+
+## Another project, per call
+
+Every tool takes an optional `project`: the project directory for that call, absolute or relative to the directory the server was started in. Without it nothing changes. With it, the call's paths (`graph`, `out`, `scene`, `directory`) resolve against that project and may not leave it, and `cook`, `render`, `check` and the others run their CLI child there. So one server started in `commons` can edit and render a sketch next to it:
+
+```text
+graph_read { "project": "/Users/me/Documents/Cascade/cloud-volumes", "graph": "index.cascade" }
+cook       { "project": "../cloud-volumes", "graph": "index.cascade", "out": "renders/check" }
+```
+
+A `project` that is not a directory is refused.

package/doc/NODE_REFERENCE.md

@@ -79,6 +79,24 @@ Runs on `portable`.
 | `result` | `any` |  |  |
 | `history` | `array` |  |  |
 
+### `cascade.core.Frozen`
+
+Frozen — Emits a frozen snapshot of a data source's chosen values
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `null` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
 ### `cascade.core.Input`
 
 Input — Defines a public graph or subnet input
@@ -173,6 +191,54 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `output` | `any` |  |  |
 
+### `cascade.core.Pack`
+
+Pack — Collects inputs into a bundle, one named field each
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `inputs` | `any` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `names` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `bundle` | `bundle` |  |  |
+
+### `cascade.core.Pick`
+
+Pick — Reads one field of a bundle
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `bundle` | `bundle` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `field` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
 ### `cascade.core.Previous`
 
 Previous — The previous step's state, inside a Feedback container. The first step gets the container's initial value.
@@ -523,6 +589,39 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.image.ContactSheet`
+
+Contact Sheet — Lay images out as one labelled grid.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `images` | `image` |  |  |
+| `list` | `array` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `columns` | `int` | `0` | 0…64 |
+| `gap` | `int` | `16` | 0…512 |
+| `background` | `color` | `[1,1,1,1]` |  |
+| `cellWidth` | `int` | `0` | 0…8192 |
+| `labels` | `string` | `""` |  |
+| `labelSize` | `int` | `14` | 6…128 |
+| `labelColor` | `color` | `[0.1,0.1,0.1,1]` |  |
+| `filename` | `string` | `"contact-sheet.png"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+| `asset` | `asset` |  |  |
+
 ### `cascade.math.Binary`
 
 Binary Math — Two values, one operation. Component-wise, and a scalar broadcasts against a vector.
@@ -907,6 +1006,115 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `scene` | `scene` |  |  |
 
+## Assertions, headless only
+
+`cascade.assert.*` fail a `cascade run` (non-zero exit, the message in
+`run --json`'s `error.message`) when their check does not hold, and pass
+their input through. The CLI registers them; Studio does not yet, and shows
+them as unresolved. An image wired only into assertions still counts as the
+graph's final image for `run --out`.
+
+### `cascade.assert.Equals`
+
+Assert Equals — Fails the run unless value equals expected (JSON-equal; numbers within tolerance); passes value through
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `null` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `expected` | `any` | `null` |  |
+| `tolerance` | `float` | `0` |  |
+| `message` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
+### `cascade.assert.NotBlank`
+
+Assert Not Blank — Fails the run when an image (PNG or PPM) is one flat colour or fully transparent; passes the image through
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `tolerance` | `int` | `0` | 0…255 |
+| `message` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.assert.Range`
+
+Assert Range — Fails the run unless value is a finite number in [min, max]; passes value through
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `float` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `min` | `float` | `0` |  |
+| `max` | `float` | `1` |  |
+| `message` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `float` |  |  |
+
+### `cascade.assert.True`
+
+Assert True — Fails the run unless value is true (wire a condition, or give the prop an expression); passes value through
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `bool` | `false` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `message` | `string` | `""` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `bool` |  |  |
+
 ## Studio node libraries
 
 Class-based nodes, available in Studio. Their parameters are declared in the

package/doc/PROJECT_AUTHORING.md

@@ -83,6 +83,13 @@ my-artwork/
 
 Keep generated output in a project-specific directory such as `renders/`. Keep reusable algorithms in `nodes/` or a normal TypeScript package rather than in Studio components.
 
+Before writing OKLCH conversions, a seeded generator, noise, paper, a pen plot,
+an ffmpeg call, a Cairn or Observatory loader or a disk cache, use the sketch
+kit, `@field/cascade-kit` (`packages/kit`, a `file:` dependency). It also
+generates the stubs for using another project's nodes without a symlink
+(`npx cascade-kit nodes <provider>`). Read [KIT.md](KIT.md). The kit is
+outside the core: Cascade never imports it.
+
 ## Add a project panel
 
 A project can provide an optional dockable Studio panel without adding UI code to Cascade. Create `panels/asset-browser/index.ts`:
@@ -191,6 +198,19 @@ image-api:
 
 The proxy accepts HTTPS only, refuses undeclared hosts, strips caller-supplied authorization headers, and never returns the credential value to the page. Studio defers its initial cook when a required credential is missing and links to File → Project Settings.
 
+## Design the graph, not one big node
+
+A piece is several nodes, each doing one job: load the data, lay it out, colour it, draw it, export it. The usage survey of November 2026 found the opposite in most projects (1 to 5 nodes of 300+ lines each over `lib/`), which leaves the graph as a parameter panel around opaque code. The graph is the record Marcus inspects, so each node boundary should be a place worth looking at, with the parameters that matter on it.
+
+Clean graph design is clean code design:
+
+- **One responsibility per node**, named for what it does (`layout_rings`, not `main`).
+- **Data flows through typed ports**, never through module-level state or files one node writes and another reads behind the graph's back.
+- **What varies is a parameter**; seeds, counts and colours are on the node, not constants in the code.
+- **Shared helpers go in `lib/` or the kit** (`KIT.md`); the node is the unit you compose and reuse.
+
+Split a node when it does two of load, generate, style, render and export, or when its `execute` grows past about 150 lines.
+
 ## Add a custom node
 
 Before writing one, check whether you need one. A parameter can hold an expression, so anything time-based is usually a parameter rather than a node. See [Animate a parameter](#animate-a-parameter). A node earns its place when it produces geometry or pixels, or when several parameters share a computation. The built-in library is listed in `NODE_REFERENCE.md`, generated from the definitions themselves; read that before searching for what a node does.
@@ -269,6 +289,58 @@ The reason is not tidiness. Two floats cannot connect to a `vec2` output, take t
 
 Keep them separate only when the components differ in kind or in range — a `width` and a `depth` that mean different things are two props, not a `vec2`.
 
+#### Bundle ports
+
+When a node would fan out more than three or four outputs that travel together, export one `bundle` instead: a single port carrying named fields. Each field is any Cascade type; an image or cache entry travels as its reference (`ImageRef`, `AssetRef`), never its pixels.
+
+```ts
+// Producer: declares the fields it carries, and optionally a schema name.
+outputs: {
+  format: {
+    kind: 'data', type: 'bundle', schema: 'format',
+    fields: {
+      size: 'vec2i',
+      size_mm: 'vec2',
+      dpi: { type: 'float', description: 'Resolution of the working canvas' },
+      paper: 'string',
+    },
+  },
+},
+// in execute:
+context.outputs.format.set({ size, size_mm, dpi, paper });
+```
+
+```ts
+// Consumer: declares the fields it reads.
+inputs: {
+  format: { kind: 'data', type: 'bundle', schema: 'format', fields: ['size', 'paper'] },
+},
+// in execute:
+const { size, paper } = context.inputs.format ?? {};
+```
+
+- **`fields` on an output** maps each field to its type. A producer may set only declared fields; a declared field may be left unset. Without `fields` the bundle is untyped and nothing can check it.
+- **`fields` on an input** lists the fields the node reads. The node then sees only those, and Studio re-cooks it only when one of them changed: a change to `dpi` does not re-cook a consumer that reads `size` and `paper`. Without `fields` a consumer depends on the whole bundle. Field access is not tracked at run time, so declare the selection when the node is expensive.
+- **`schema`** names the bundle's shape. Two named schemas must match to connect; a port without one takes any bundle.
+- **Expressions** read a field of a wired bundle input with a dotted path: `ch("format.dpi")`, `chv("format.size_mm")`, `chs("format.paper")`. The path names an input on the same node, not another node's output, so the wire is the dependency and the producer always cooks first. `ch("/spread-format/format.dpi")` is refused by `cascade check`, which says which wire to add. A field read in an expression counts as a declared field for caching.
+- **`cascade.core.Pick`** reads one field (`field` prop) for a node that wants a single value, and **`cascade.core.Pack`** builds a bundle from loose values, one name per input in its comma-separated `names` prop. Pick is cheap and its output only changes when the picked field does, so it is also how a node that cannot declare fields depends on one.
+- **`cascade check`** reports a field that the producer does not declare, in a consumer's `fields`, in an expression, or on a Pick, with the nearest declared name: `dot-layer.radius reads unknown bundle field "dpu" — did you mean "dpi"?`.
+- **Studio** draws a bundle as one port in the neutral wire colour. Hovering it lists every field with its type and current value, and the Inspector shows each field with its own control.
+
+A bundle passed to a Python stage is an ordinary JSON object, so the worker receives a `dict`; reference fields arrive as their small JSON form, e.g. `args["format"]["preview"]["path"]`. A stage that returns a dict can be set straight onto a bundle output:
+
+```ts
+const result = await runStage('signals', { format: context.inputs.format });
+context.outputs.signals.set(result as Record<string, unknown>);
+```
+
+```python
+def signals(args):
+    fmt = args["format"]            # a dict
+    w, h = fmt["size"]
+    return {"brightness": {"path": cache_png(...), "size": [w, h], ...}, "edge_count": 412}
+```
+
 ### dynamic
 
 A dynamic module declares its interface imperatively, inside `execute`, which runs once to discover the interface and again on every cook. There is no `definition` export; `runsOn` and `icon` are plain exports.
@@ -293,7 +365,7 @@ export async function execute(node: any) {
 
 `param()` is a method on the node the engine hands to `execute`, not an import. It is re-declared on every cook, so it never resets a value, an expression, or a keyframe someone set: reading `.value` gives the *resolved* value for the current frame, whichever of the three bindings is in force. The loader imports the module as real JavaScript, so top-level code does run at import time. Keep dynamic modules free of top-level effects and put interface declaration and cooking inside `execute`.
 
-Prefer `new OffscreenCanvas(width, height)` to `document.createElement('canvas')` when both hosts can run the node. A portable declaration still requires output parity checks; installing Skia does not override a browser-only declaration. Use Python for libraries or tools that require a server. Measure transport, serialization, and cold-start costs; persistent workers can avoid repeated process/model startup.
+Prefer `new OffscreenCanvas(width, height)` to `document.createElement('canvas')` when both hosts can run the node; a definition-v1 node uses `cascade/image` (see "Draw an image in any host"). A portable declaration still requires output parity checks; installing Skia does not override a browser-only declaration. Use Python for libraries or tools that require a server. Measure transport, serialization, and cold-start costs; persistent workers can avoid repeated process/model startup.
 
 Choose the narrowest execution locus:
 
@@ -315,6 +387,64 @@ export const definition = {
 
 The runtime refuses unsupported host/capability combinations before executing the graph.
 
+### Draw an image in any host
+
+A node that draws, reads or writes an image uses `cascade/image`, and then one
+body cooks in Studio, under `cascade run`/`render`/MCP, and in an exported
+editor's worker. Declare `runsOn: 'portable'` and `capabilities: ['assets']`,
+and import nothing host-specific: no `node:*`, no `@napi-rs/canvas`, no
+`document`.
+
+```ts
+import type { NodeDefinition, NodeExecutionContext } from 'cascade/contracts';
+import { readBytes, readImage, registerFont, surface, writeImage } from 'cascade/image';
+
+export const definition = {
+  apiVersion: 1,
+  label: 'Poster',
+  runsOn: 'portable',
+  capabilities: ['assets'],
+  inputs: { photo: { kind: 'data', type: 'image' } },
+  outputs: { image: { kind: 'data', type: 'image' } },
+  props: { title: { type: 'string', default: 'Hello' }, font: { type: 'string', default: 'assets/fonts/Display.otf' } },
+} as const satisfies NodeDefinition;
+
+export async function execute(context: NodeExecutionContext<typeof definition>) {
+  const photo = await readImage(context, context.inputs.photo);          // an image input, asset or project path
+  await registerFont('Display', await readBytes(context, context.props.font));
+  const { canvas, context: g } = surface(photo.width, photo.height);     // OffscreenCanvas, CPU-backed 2D
+  g.drawImage(photo, 0, 0);
+  g.font = '96px Display';
+  g.fillText(context.props.title, 40, 140);
+  context.outputs.image.set(await writeImage(context, canvas, `${context.nodeId}.png`));
+}
+```
+
+| | Browser (Studio, exported editor) | Headless (CLI, MCP) |
+| --- | --- | --- |
+| `createCanvas`, `surface` | the realm's `OffscreenCanvas` | Skia's, from `@napi-rs/canvas` |
+| `decodeImage`, `readImage` | `createImageBitmap` | Skia's decoder |
+| `writeImage` | an in-memory generated asset | `.cascade-cache/<name>.<hash>.png` |
+| `registerFont` | `FontFace` added to the page's or worker's font set | Skia's `GlobalFonts` |
+| `readBytes` | shipped files only (`editor.assets`, literal asset props, frozen files) | any project file |
+
+- The host chooses where a written image lands; never name a path or read an
+  output file back by a path you built. `cachePath` and `saveImage` from
+  `cascade/io` remain for dynamic nodes.
+- `surface(w, h)` asks for a `willReadFrequently` context, which keeps Chrome
+  on the same software Skia rasteriser the headless host uses. Expect the same
+  image, not the same bytes: on commons `plotter-social` the paper, foil and
+  wordmark match exactly and scanline marks differ at stroke edges (mean
+  channel delta under 0.5 of 255 with the same fonts).
+- A font only matches across hosts when both register the same bytes. A file
+  that is not there (a licensed face the export never ships) should fall back
+  to a named system face, not fail; read it with `readBytes` in a `try`.
+- What has no browser form is refused, not imitated: no canvas in the realm,
+  or `assets` not declared, throws a sentence saying which. A node that needs
+  the filesystem, a network fetch or ffmpeg stays `runsOn: 'server'`; to put
+  its output in an editor, freeze it (`cascade freeze <graph> <node> --fields
+  path,size,channels,depth,space` ships the image file with the snapshot).
+
 ### GPU nodes today
 
 A definition-v1 node may declare `capabilities: ['gpu']`. Studio and the optional
@@ -512,6 +642,102 @@ It may also accept inline JSON after `--args` for manual compatibility. Projects
 with expensive imports may additionally declare a newline-delimited JSON
 `worker`; Cascade keeps that process warm and correlates requests by `id`.
 
+Cascade sends the worker one request at a time. When a newer edit supersedes a
+running stage, Cascade withdraws it: a queued request is never sent, and the
+one in flight gets `SIGINT`. A worker that catches `KeyboardInterrupt` around a
+request should answer `{"id": <id>, "ok": false, "cancelled": true}` and keep
+serving, so warm models survive a scrub; it should also ignore an interrupt
+that arrives between requests. A worker that does not handle it exits and is
+respawned on the next call, and one that has not answered within three seconds
+is killed. Whatever a cancelled request returns is discarded. Write cache
+entries atomically (temp file plus rename), since a stage can now be
+interrupted part-way. Nodes can pass `{ signal }` as `runStage`'s third
+argument; without it the signal of the cook in flight is used.
+
+#### Stage code, cache keys and the run trace
+
+Cascade keys every stage call on four things: the stage code (a hash of every
+`.py` file under `exec.stages.sources`), the arguments with each input file
+replaced by a hash of its bytes, those input hashes, and the Cascade version.
+The key and the cache state are reported on every call, hit or miss: in the
+server log (`[stage] ink: miss (no entry) key 3f2a… code 99dad29d… 1204 ms`),
+in `cascade run --json` under `stages`, and in the run trace.
+
+```json
+{
+  "exec": {
+    "stages": {
+      "entrypoint": "runtime/node_cli.py",
+      "worker": "runtime/worker.py",
+      "sources": ["runtime", "src", "shared/bridge"],
+      "cache": { "exclude": ["plot-status"], "outputs": ["out", "svg_out"] }
+    }
+  }
+}
+```
+
+- `sources` lists the files and folders whose `.py` files are the stage code.
+  Without it: the folders of the entrypoint and the worker, plus `src/`. A
+  symlinked folder (such as `shared/`) is followed only when it is listed.
+- The warm worker fingerprints those sources when it starts and again before
+  every request, and restarts first when they changed, so an edited stage never
+  keeps running its old code in a live Studio. Its bytecode cache is keyed by
+  the code hash, because Python accepts a `.pyc` whose source kept its size
+  within the same second.
+- `cache` controls Cascade's own result cache. A stored result is served only
+  while every file it names still has the bytes it had, so a stage that writes
+  a fixed path and was re-run with other inputs misses rather than serving the
+  overwritten file. See "The stage cache default" below.
+
+#### The stage cache default
+
+Since 6 Nov 2026 the cache is **on by default for the calls a node's cook
+makes**, and off for everything else. A node is a pure function of its inputs,
+so a stage it calls through `runStage` from `cascade/stage` is treated as pure:
+same stage code, same arguments, same input file bytes, same answer. A second
+identical cook is served from `.cascade/cache/stages/` without starting Python
+at all; on `cloud-plots/relief.cascade` that takes a re-cook from about 4.2 s
+to 0.45 s. A call from a panel (`api.runStage`) or a hand-rolled
+`fetch('/api/exec')` is an action — `plot-start`, `plot-status` — and is not
+cached unless you say so.
+
+What is not pure, and must be opted out:
+
+- a stage whose answer changes under an identical call: it reads the clock,
+  draws fresh randomness, queries a device or a job's progress, or calls a
+  network service whose answer you want fresh each time;
+- a stage that reads a file its arguments do not name (a config file, a folder
+  it scans, a model downloaded on the side). Only files named in the arguments
+  are hashed into the key, so an edit to an unnamed file is invisible;
+- a stage whose purpose is a side effect (copying to a named place, posting
+  somewhere). A result whose named files still have their bytes is served, so
+  a copy that already happened is not repeated; when the effect must happen
+  every time, opt the stage out.
+
+How to opt out:
+
+```json
+"cache": { "exclude": ["plot-status", "camera-grab"], "outputs": ["out", "svg_out"] }
+```
+
+| Declaration | What is cached |
+|---|---|
+| absent | calls from node cooks, except `exclude` (none) |
+| `{ "exclude": [...], "outputs": [...] }` | calls from node cooks, except the named stages |
+| `{ "scope": "all", ... }` or `true` | every call, panel actions included, except `exclude` |
+| `false` or `{ "enabled": false }` | nothing |
+
+`CASCADE_STAGE_CACHE=off` in the environment still turns it off for one
+process (`cascade parity` sets it). Every call's trace says what happened and
+why: `hit`, `miss (no entry)`, `off (excluded)`, `off (not a cook call)`,
+`off (not enabled)`. A project that keeps its own Python-side cache can keep
+it; Cascade's sits in front, and on a hit the project's code is not called.
+- A request carries `"cascade": {"key", "code", "cache"}` beside `args` (the
+  worker), or `CASCADE_STAGE_ENVELOPE` in the environment (one-shot). A
+  project that keeps its own cache should stand aside when `cache` is `"off"`,
+  which `cascade parity` sets, and may answer `"cache": "hit" | "miss"` beside
+  `result` so the trace shows its state too.
+
 ## Work with `.cascade` files
 
 A graph document stores authored elements separately from runtime state. Nodes and annotations remain flat even inside subnets:
@@ -550,6 +776,11 @@ cascade run index.cascade --frames 1-100x2 --fps 25 --out frames
 cascade run index.cascade --frames 42 --entry-node logo-1024
 ```
 
+Every run writes a trace to `.cascade/runs/<time>-<graph>.json` (the last 200
+are kept): each node that cooked, its time, and every stage call it made with
+the key and cache state. `--verbose` prints the stage lines as they happen, and
+`--json` prints the status, the seed, the trace path and the stage calls.
+
 `--frames` takes a range, a stepped range, or a single frame, and refuses a range it cannot parse rather than repairing it. Files are written as `<out>/<node id>.<frame>.<ext>`, zero-padded to at least four digits, into `renders/` unless `--out` says otherwise. One rule whether the graph has one output or three. Every image output with nothing connected downstream is saved, or the outputs of `--entry-node` when one is named. Cascade stops at the image sequence; a directory of numbered frames is what an encoder takes.
 
 Offline, drawing goes through Skia: the optional `@napi-rs/canvas` supplies `OffscreenCanvas`, `Image`, `Path2D` and the rest as globals in the Node process, deliberately not `document`, because that is how a node tells which host it is in. This is why a node that draws on an `OffscreenCanvas` needs no second implementation for headless runs, and why the built-in `cascade.image.*` nodes render under `cascade run` as well as in Studio. A graph that draws nothing runs without the renderer installed.
@@ -583,6 +814,32 @@ testing the exported artifact for the particular graph. Prefer `cascade build`
 for definition-v1 browser graphs, or embed `cascade/runtime` directly when an
 application needs custom capabilities and presentation.
 
+## Seeds and parity
+
+A graph has one `seed` (an unsigned 32-bit integer, 0 when absent) and each
+node gets `context.seed`, derived from it and the node id, plus
+`context.random()`, a stream seeded with it that restarts at every cook. Both
+hosts derive them the same way, so a node that draws with `context.random`
+draws the same thing headless and in Studio. `Math.random` cannot be
+reproduced by any host; pass `context.seed` on to a Python stage instead of
+seeding there from the clock. `cascade run --seed N` cooks with another seed
+without editing the file.
+
+```bash
+cascade parity index.cascade                 # every node
+cascade parity index.cascade --node ink      # one node and what feeds it
+cascade parity index.cascade --tolerance 2 --json
+```
+
+`parity` cooks three times with every cache off: headless, headless again, and
+through Studio's own executor (the compatibility graph and its definition
+adapter) run headlessly with the same Dawn GPU and project capabilities. It
+prints one row per node output with both comparisons side by side (`same`,
+`within tolerance`, or the difference: pixels and the largest channel delta
+for an image, both values for a number) and exits 1 when anything differs.
+See [Headless GPU](HEADLESS_GPU.md#determinism) for what makes a GPU stage
+repeatable.
+
 ## Verify a project
 
 Before committing a custom node or graph: