@field/cascade 0.10.0 → 0.11.0

package/dist/runtime/builtins/image/contactSheet.js

@@ -0,0 +1,199 @@
+/**
+ * `cascade.image.ContactSheet` — several images as one labelled grid.
+ *
+ * The selection loop is a ladder of three to five options and a pick, and the
+ * pick is made by looking at them side by side. So the sheet is a node rather
+ * than a script beside the graph: a graph can end in one, and `cascade ladder`
+ * lays out its variants with the same layout and drawing code below.
+ *
+ * `portable` with `assets`, like `cascade.geo.Render`: it reads each image
+ * through the asset capability, decodes it with `createImageBitmap` and draws
+ * on an `OffscreenCanvas`, which both hosts supply (the headless one through
+ * @napi-rs/canvas). It lives in `cascade.image.*` beside Studio's image
+ * library, as the first definition-v1 node there; Studio does not register it
+ * yet, so today it runs headless and is listed in `../headless.ts` rather
+ * than in the built-ins Studio bundles.
+ */
+export const contactSheetDefinition = {
+    apiVersion: 1,
+    label: "Contact Sheet",
+    description: "Lay images out as one labelled grid.",
+    icon: "LayoutGrid",
+    runsOn: "portable",
+    capabilities: ["assets"],
+    inputs: {
+        images: { kind: "data", type: "image", variadic: true },
+        /** More images after the wired ones: image values or project-relative paths. */
+        list: { kind: "data", type: "array" },
+    },
+    outputs: {
+        image: { kind: "data", type: "image" },
+        asset: { kind: "data", type: "asset" },
+    },
+    props: {
+        columns: { type: "int", default: 0, min: 0, max: 64, description: "0: as square as the count allows." },
+        gap: { type: "int", default: 16, min: 0, max: 512 },
+        background: { type: "color", default: [1, 1, 1, 1], label: "Background" },
+        cellWidth: { type: "int", default: 0, min: 0, max: 8192, description: "0: images at their own size. Otherwise each is scaled to fit this width." },
+        labels: { type: "string", default: "", description: "One label per line, in image order." },
+        labelSize: { type: "int", default: 14, min: 6, max: 128 },
+        labelColor: { type: "color", default: [0.1, 0.1, 0.1, 1], label: "Label Colour" },
+        filename: { type: "string", default: "contact-sheet.png", label: "Filename" },
+    },
+};
+/**
+ * Where each image goes. By default every cell is as wide as the widest image
+ * and as tall as the tallest, and images keep their size. With `cellWidth`,
+ * cells are that wide and as tall as the tallest image needs at that width,
+ * and each image is scaled to fit. Either way an image is centred in its cell
+ * and never cropped, in whole pixels, so a sheet is the same bytes every run.
+ */
+export function contactSheetLayout(sizes, options = {}) {
+    const count = sizes.length;
+    if (!count)
+        throw new Error("cascade.image.ContactSheet needs at least one image");
+    for (const [width, height] of sizes) {
+        if (!(width > 0 && height > 0))
+            throw new Error(`cascade.image.ContactSheet: an image is ${width}x${height}`);
+    }
+    const gap = Math.max(0, Math.round(options.gap ?? 16));
+    const columns = Math.min(count, options.columns && options.columns > 0 ? Math.round(options.columns) : Math.ceil(Math.sqrt(count)));
+    const rows = Math.ceil(count / columns);
+    const scaled = Boolean(options.cellWidth && options.cellWidth > 0);
+    const cellWidth = scaled ? Math.round(options.cellWidth) : Math.max(...sizes.map(([width]) => width));
+    const cellHeight = scaled
+        ? Math.max(...sizes.map(([width, height]) => Math.round((height * cellWidth) / width)))
+        : Math.max(...sizes.map(([, height]) => height));
+    const labelHeight = Math.max(0, Math.round(options.labelHeight ?? 0));
+    const cells = sizes.map(([width, height], index) => {
+        const column = index % columns;
+        const row = Math.floor(index / columns);
+        // Native size unless a cell width was asked for; never cropped.
+        const fit = Math.min(cellWidth / width, cellHeight / height);
+        const scale = scaled ? fit : Math.min(1, fit);
+        const drawnWidth = Math.max(1, Math.round(width * scale));
+        const drawnHeight = Math.max(1, Math.round(height * scale));
+        const left = gap + column * (cellWidth + gap);
+        const top = gap + row * (cellHeight + labelHeight + gap);
+        return {
+            x: left + Math.floor((cellWidth - drawnWidth) / 2),
+            y: top + Math.floor((cellHeight - drawnHeight) / 2),
+            width: drawnWidth,
+            height: drawnHeight,
+            labelX: left,
+            labelY: top + cellHeight,
+        };
+    });
+    return {
+        width: gap + columns * (cellWidth + gap),
+        height: gap + rows * (cellHeight + labelHeight + gap),
+        columns,
+        rows,
+        cell: [cellWidth, cellHeight],
+        labelHeight,
+        cells,
+    };
+}
+/** The host's canvas, read here and nowhere else (see `cascade.geo.Render`). */
+function host() {
+    const globals = globalThis;
+    const Canvas = globals.OffscreenCanvas;
+    const createBitmap = globals.createImageBitmap;
+    if (!Canvas || !createBitmap || !globals.Blob) {
+        throw new Error("cascade.image.ContactSheet needs OffscreenCanvas and createImageBitmap, which this host does not provide");
+    }
+    const BlobType = globals.Blob;
+    return {
+        surface: (width, height) => new Canvas(width, height),
+        decode: (bytes) => createBitmap(new BlobType([bytes])),
+    };
+}
+function css(colour, fallback) {
+    const [r = 0, g = 0, b = 0, a = 1] = colour ?? fallback;
+    return `rgba(${Math.round(r * 255)}, ${Math.round(g * 255)}, ${Math.round(b * 255)}, ${a})`;
+}
+/** Encoded images (PNG, JPEG, WebP) in, one PNG sheet out. */
+export async function composeContactSheet(images, options = {}) {
+    const canvas = host();
+    const bitmaps = [];
+    try {
+        for (const bytes of images)
+            bitmaps.push(await canvas.decode(bytes));
+        const labels = options.labels ?? [];
+        const labelSize = Math.round(options.labelSize ?? 14);
+        const labelled = labels.some((label) => label.trim().length > 0);
+        const layout = contactSheetLayout(bitmaps.map((bitmap) => [bitmap.width, bitmap.height]), {
+            columns: options.columns,
+            gap: options.gap,
+            cellWidth: options.cellWidth,
+            labelHeight: labelled ? Math.round(labelSize * 1.8) : 0,
+        });
+        const surface = canvas.surface(layout.width, layout.height);
+        const context = surface.getContext("2d");
+        if (!context)
+            throw new Error("cascade.image.ContactSheet: no 2D context");
+        context.fillStyle = css(options.background, [1, 1, 1, 1]);
+        context.fillRect(0, 0, layout.width, layout.height);
+        context.imageSmoothingEnabled = true;
+        context.imageSmoothingQuality = "high";
+        layout.cells.forEach((cell, index) => context.drawImage(bitmaps[index], cell.x, cell.y, cell.width, cell.height));
+        if (labelled) {
+            context.fillStyle = css(options.labelColor, [0.1, 0.1, 0.1, 1]);
+            context.font = `${labelSize}px sans-serif`;
+            context.textBaseline = "top";
+            layout.cells.forEach((cell, index) => {
+                const label = labels[index];
+                if (label)
+                    context.fillText(label, cell.labelX, cell.labelY + Math.round((layout.labelHeight - labelSize) / 2), layout.cell[0]);
+            });
+        }
+        const blob = await surface.convertToBlob({ type: "image/png" });
+        return { bytes: new Uint8Array(await blob.arrayBuffer()), layout };
+    }
+    finally {
+        for (const bitmap of bitmaps)
+            bitmap.close?.();
+    }
+}
+/** An image value or a path, as the asset reference to read it by. */
+function imageReference(value) {
+    if (typeof value === "string" && value)
+        return { path: value };
+    const candidate = value?.path;
+    return typeof candidate === "string" && candidate ? { path: candidate } : undefined;
+}
+export async function executeContactSheet(context) {
+    const { props } = context;
+    const references = [...context.inputs.images, ...(context.inputs.list ?? [])]
+        .map(imageReference)
+        .filter((reference) => reference !== undefined);
+    const bytes = [];
+    for (const reference of references) {
+        bytes.push(await context.capabilities.assets.read(reference, { signal: context.signal }));
+    }
+    const { bytes: sheet, layout } = await composeContactSheet(bytes, {
+        columns: props.columns,
+        gap: props.gap,
+        cellWidth: props.cellWidth,
+        labels: props.labels ? props.labels.split("\n") : [],
+        labelSize: props.labelSize,
+        background: props.background,
+        labelColor: props.labelColor,
+    });
+    const asset = await context.capabilities.assets.write(sheet, { mediaType: "image/png", suggestedName: props.filename }, { signal: context.signal });
+    context.outputs.asset.set(asset);
+    context.outputs.image.set({
+        path: asset.path ?? props.filename,
+        size: [layout.width, layout.height],
+        channels: "rgba",
+        depth: "u8",
+        space: "srgb",
+    });
+}
+export const contactSheetRegistration = {
+    kind: "definition-v1",
+    moduleId: "cascade.image.ContactSheet",
+    definition: contactSheetDefinition,
+    loadExecute: async () => executeContactSheet,
+};
+//# sourceMappingURL=contactSheet.js.map

package/dist/runtime/builtins/image/index.d.ts

@@ -0,0 +1,9 @@
+import type { DefinitionNodeRegistration } from "../../types.js";
+/**
+ * The definition-v1 image nodes. One so far: the contact sheet a ladder of
+ * variants is judged on. Studio's `cascade.image.*` library (src/nodes/image)
+ * is the compatibility engine's and is not listed here.
+ */
+export { composeContactSheet, contactSheetDefinition, contactSheetLayout, contactSheetRegistration, executeContactSheet, type ContactSheetOptions, type SheetLayout, } from "./contactSheet.js";
+export declare const imageNodeRegistrations: readonly DefinitionNodeRegistration[];
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/builtins/image/index.js

@@ -0,0 +1,9 @@
+import { contactSheetRegistration } from "./contactSheet.js";
+/**
+ * The definition-v1 image nodes. One so far: the contact sheet a ladder of
+ * variants is judged on. Studio's `cascade.image.*` library (src/nodes/image)
+ * is the compatibility engine's and is not listed here.
+ */
+export { composeContactSheet, contactSheetDefinition, contactSheetLayout, contactSheetRegistration, executeContactSheet, } from "./contactSheet.js";
+export const imageNodeRegistrations = Object.freeze([contactSheetRegistration]);
+//# sourceMappingURL=index.js.map

package/dist/stage.js

@@ -53,7 +53,10 @@ async function overHttp(stage, args, signal) {
   const postStage = async () => fetch("/api/exec", {
     method: "POST",
     headers: { "Content-Type": "application/json", "X-Cascade-Exec-Capability": await capability() },
-    body: JSON.stringify({ stage, args }),
+    // `cook`: a node's cook is a pure function of its inputs, so the server's
+    // default stage cache may serve it (see StageCachePolicy). A panel posts
+    // through its own api.runStage, without this, and is never cached unasked.
+    body: JSON.stringify({ stage, args, caller: "cook" }),
     signal
   });
   let response;

package/doc/CLI_REFERENCE.md

@@ -1,6 +1,6 @@
 # CLI reference: editing graphs
 
-Everything an agent needs to build or change a `.cascade` graph without hand-editing JSON. Each command is one graph concept (node, wire, parameter, subnet), checks the edit with the same code as `cascade check`, and writes the file atomically. For running, rendering and exporting, see `cascade --help`, `doc/EDITOR_EXPORT.md` and `doc/WEB_PLAYER.md`.
+Everything an agent needs to build or change a `.cascade` graph without hand-editing JSON. Each command is one graph concept (node, wire, parameter, subnet), checks the edit with the same code as `cascade check`, and writes the file atomically. Running, rendering, exporting and locks are listed under [The other commands](#the-other-commands); see also `cascade --help`, `doc/EDITOR_EXPORT.md` and `doc/WEB_PLAYER.md`.
 
 ## The guarantees
 
@@ -15,7 +15,7 @@ Everything an agent needs to build or change a `.cascade` graph without hand-edi
 | --- | --- |
 | `cascade graph create <graph> [--name <title>]` | A new empty graph. Never overwrites. |
 | `cascade graph read <graph> [--in <subnet>]` | Nodes with stored parameters, subnets with their ports, wires as `a.out -> b.in`. |
-| `cascade graph list [dir]` | Every `.cascade` under a directory, with node and wire counts. |
+| `cascade graph list [dir]` | Every `.cascade` under a directory, with node and wire counts. Skips `renders/`, `out/`, `dist/` and `node_modules/` below it. |
 | `cascade node add <graph> <type> [--name <id>] [--in <subnet>] [--set k=v]... [--at x,y] [--comment <text>]` | Add a node. `<type>` is a module id or a short name: `Circle` is `cascade.geo.Circle`, `InkVocabulary` is `project.InkVocabulary`. The id defaults to the type in kebab case (`copy-to-points`, then `copy-to-points-2`). |
 | `cascade node rm <graph> <node> [--recursive]` | Remove a node and its wires. A subnet with children needs `--recursive`. |
 | `cascade connect <graph> <node.output> <node.input> [--no-layout]` | Wire two ports. A port can be left off when the node has one on that side. An input that was fed is rewired, and the old wire is reported. |
@@ -31,6 +31,40 @@ Everything an agent needs to build or change a `.cascade` graph without hand-edi
 
 Every edit takes `--dry-run` (check, write nothing) and `--json`.
 
+## The other commands
+
+Running, sharing, locks and Studio. `cascade --help` has their options; `cascade render --help` and `cascade lock --help` have their own.
+
+| Command | What it does |
+| --- | --- |
+| `cascade [project-directory \| graph-file]` | Open Studio on a project or graph. |
+| `cascade new <name>` | Create a Cascade project. |
+| `cascade node <Name> [project-directory]` | Create a deterministic custom node. |
+| `cascade projects [directory]` | Show or set the default projects directory. |
+| `cascade serve start\|stop\|restart\|status\|logs\|install` | Run Studio as a managed background service. |
+| `cascade run <graph-file> [options]` | Cook a graph headlessly; `--frames` renders a sequence. |
+| `cascade render <graph-file>` | Render an animation across worker processes, then a preview video. |
+| `cascade validate <graph-file>` | Validate a graph file without executing. |
+| `cascade check <graph-file>` | Statically check node definitions, types and graph structure. |
+| `cascade inspect <graph-file>` | Every node with its classification and full definition. |
+| `cascade parity <graph-file>` | Cook headless twice and through Studio's path; report per-node differences. |
+| `cascade build <graph-file> --out <new-directory>` | A standalone browser player ([WEB_PLAYER.md](WEB_PLAYER.md)). |
+| `cascade export <graph-file> (--plan \| --out <dir>)` | The graph's published editor as a static site ([EDITOR_EXPORT.md](EDITOR_EXPORT.md)). |
+| `cascade publish <graph-file> <node>.<prop>` | Publish a node prop as an editor parameter. |
+| `cascade freeze <graph-file> <node> --fields <a,b>` | Snapshot chosen fields of a live data source for export. |
+| `cascade scene <graph-file> <scene.json> --out <new-graph-file>` | Apply a scene file to a copy of the graph. |
+| `cascade mcp [project-directory]` | Serve these commands as MCP tools over stdio ([MCP.md](MCP.md)). |
+| `cascade lock <graph-file> <node> --name <name>` | Record a render (graph, params, seeds, inputs, code) in `locks/<id>.json`. |
+| `cascade lock verify [<lock-id>...]` | Replay locks and report which still match. |
+| `cascade replay <lock-id>` | Re-render a lock from its stored code and compare fingerprints. |
+| `cascade locks` | List the project's locks. |
+| `cascade ladder <graph-file> <node> --name <name> --vary <node.prop>=<a,b,c> \| --seeds <a,b,c>` | Cook 3 to 5 variants (values zipped across params, or graph seeds) from the stored code; write `ladders/<id>/<n>.png`, a labelled contact sheet `ladders/<id>/sheet.png` and the record `ladders/<id>.json` (per variant: graph, params, seed, inputs, fingerprint; the code and git commit once). |
+| `cascade pick <ladder-id> <n> [--name <lock name>]` | At approval, write `locks/<id>.json` for variant `n` from the ladder's record, without cooking again; `cascade replay` reproduces that image pixel for pixel. |
+| `cascade help node [<type>] [--project <dir>]` | A node type's inputs, props and outputs (type, default, range, description), where it runs and its capabilities, read from the installed package or the project's `nodes/`; without a type, every node type. No repository checkout needed. |
+| `cascade doctor [project-directory] [--fix]` | What a headless run here will find: the declared Python environment, the stage interpreter, ffmpeg, the canvas. `--fix` builds the environment. See [Python for stages](#python-for-stages-cascadejson-python). |
+
+Every verb is one row in `src/cli/verbs.ts`: its usage and summary for `--help`, the handler that runs it, how it treats `--json`, and the MCP tools that call it. A new verb is a row there, its handler, and its line here (`tests/cli-verbs.test.ts` checks both this page and [MCP.md](MCP.md)).
+
 ## `--json`, on every command
 
 Every command, not only the editing ones, prints one envelope on stdout and nothing else:
@@ -98,3 +132,40 @@ cascade check index.cascade && cascade run index.cascade --frames 1 --json
 ```
 
 Opened in Studio, the top level reads `motif → transform → render`, with the camera beside `transform`, and `motif` holds the circle and rectangle side by side above `copy-to-points` and its output.
+
+## Outputs as files (`run --out`)
+
+`cascade run <graph> --out <dir>` copies each image output to `<dir>/<node>.<ext>`, or `<dir>/<node>.<port>.<ext>` for a node with more than one image output. With `--frames` the same names carry the frame: `<node>[.<port>].<frame>.<ext>`. Which outputs: every image output nothing downstream consumes (a `cascade.core.Null` passing an image counts), or those of `--node`; `--out-node <id>` (repeatable) adds a mid-graph node's. `--out` may be project-relative or absolute; `files` in the result is spelled the same way. `run --json` lists every image output as `data.images: [{ node, port, source, file? }]`, with or without `--out`. The MCP `cook` and `render` tools take `out` and `outNodes`.
+
+## Checks that fail a run (`cascade.assert.*`)
+
+Put the check in the graph instead of a script beside it:
+
+```sh
+cascade node add index.cascade NotBlank --name poster-not-blank --set 'message="the poster rendered empty"'
+cascade connect index.cascade render.image poster-not-blank.image
+cascade node add index.cascade cascade.assert.Range --name density-ok --set min=0.2 --set max=0.8
+cascade connect index.cascade stats.density density-ok.value
+cascade run index.cascade --json      # exit 1: { "ok": false, "error": { "message": "Assertion failed in \"density-ok\" (cascade.assert.Range): value 0.93 is outside [0.2, 0.8]." } }
+```
+
+`Range` (a finite number in `[min, max]`), `Equals` (JSON-equal to `expected`, numbers within `tolerance`), `True`, and `NotBlank` (a PNG or PPM that is not one flat colour within `tolerance`, nor fully transparent). Each passes its input through and runs when the graph runs whole, or when the `--node` you name is downstream of it. An image wired only into assertions is still saved by `--out`. Headless only for now; see `doc/NODE_REFERENCE.md`.
+
+## Debug output and environment (`.cascade/runs/`, `--env`)
+
+Every run's trace in `.cascade/runs/<time>-<graph>.json` holds, per node, what it printed while it cooked: `console.log/info/warn/error/debug` from the node, and its Python stages' stderr, as `logs: [{ level, text }]` (500 lines per node, the rest counted in `logsDropped`). `run --json` gives the same lines as `data.logs: [{ node, level, text }]`. A failed run writes its trace too, and the error ends with `Run trace: <path>`.
+
+`--env NAME=value` (repeatable) sets a variable for the run: Python stages, the warm stage worker and `cascade render`'s worker processes see it, so `CLOUD_ANALYST_ONLINE=1` no longer needs a shell prefix. The trace records the names under `env`, never the values. The MCP `cook` and `render` tools take `env: { NAME: "value" }`.
+
+## Python for stages (`cascade.json` `python`)
+
+A project whose stages import numpy or Pillow declares them, and Cascade keeps a virtual environment for it in `.cascade-cache/python/venv` (inside the project, never system-wide):
+
+```json
+{
+  "exec": { "stages": { "entrypoint": "runtime/node_cli.py" } },
+  "python": { "requirements": ["numpy", "Pillow>=10"] }
+}
+```
+
+`requirements` is a list of pip specifiers or a project-relative requirements file; `interpreter` (default `python3`) is what creates the venv. `cascade doctor` reports it as `current`, `missing` or `stale` (cascade.json changed since it was built); `cascade doctor --fix` creates or rebuilds it, moving an old one to `.cascade-cache/python/_archive/`. While one is declared, stages run under its interpreter instead of a bare `python`/`python3` in `exec.stages.python` (a project-relative executable there still wins), and a stage call with the environment missing or stale fails with the command that fixes it, rather than later on an `ImportError`. MCP: `doctor { "fix": true }`.

package/doc/EDITOR_EXPORT.md

@@ -92,7 +92,8 @@ prints the same manifest without building anything.
    directory, so no `.env.local` can land in the site. It deploys to
    production, then checks that an anonymous request to
    `https://<project>.vercel.app` is refused. If it is not, it says to turn on
-   Vercel Authentication.
+   Vercel Authentication. Add `--public` when the editor is meant to be open to
+   anyone: a readable site is then reported as intended instead of failing.
 
 ## The `editor` section
 
@@ -121,12 +122,18 @@ Studio keeps it verbatim when it saves. The types are in
     { "id": "soft", "label": "Soft", "values": { "strength": 1 }, "keep": ["colour", "font"] }
   ],
   "assets": ["assets/fonts/InterDisplay-Medium.otf"],
+  "fonts": [{ "family": "DM Mono", "file": "assets/fonts/DMMono-Regular.woff2", "license": "OFL-1.1", "weight": 400 }],
   "freeze": [{ "node": "moment", "output": "moment", "snapshot": "frozen/moment.json" }],
   "panel": { "module": "editor/panel.ts", "placement": "extend" },
   "inspect": true
 }
 ```
 
+`fonts` ships open-licensed fonts with the site and loads them in the page
+(`@font-face`) and in the engine worker (`FontFace`), so a panel or a canvas
+that names the family draws with it. Each entry must say `"license": "OFL-1.1"`;
+anything else, or a file under `licensed/`, is refused.
+
 - **Parameter `id`** is the key a scene uses. It survives renaming the node
   or the prop, so keep it stable.
 - **`control`** is one of `number`, `slider`, `int`, `bool`, `select`
@@ -216,7 +223,9 @@ The same scene gives byte-identical output in the editor and under `cascade run`
 
 - Only browser-runnable definition-v1 nodes ship. Python, shell and dynamic
   nodes are listed together as "not exportable". Port them to TypeScript, or
-  freeze their output.
+  freeze their output. A node that draws ships when it uses `cascade/image`
+  (PROJECT_AUTHORING.md, "Draw an image in any host"); fonts and images it
+  reads must be shipped files (`editor.assets`, `editor.fonts`, frozen files).
 - The editor cooks in a module worker. Unchanged stages are reused
   (`run({ reuse: true })`), so only the stages after an edit re-cook, and the
   page stays responsive while they do. Values cross to the page by structured

package/doc/MCP.md

@@ -37,8 +37,13 @@ With a global install (`npm i -g @field/cascade`), use `"command": "cascade", "a
 | `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 and exporting run `cascade <command> --json` as a child process, 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.
+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
 
@@ -51,3 +56,14 @@ 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

@@ -589,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.
@@ -973,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