@field/cascade 0.10.0 → 0.12.0

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,41 @@ 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 share <graph-file \| site-directory> [--name <slug>] [--scope <team>] [--protected]` | One link for the team: export the editor (or take a static directory with an `index.html`), deploy it to the Vercel project `cascade-<slug>` (team `field-io`), print the production URL (`data.url` with `--json`) and record it in the project's `shares.json`. Public unless `--protected` ([EDITOR_EXPORT.md](EDITOR_EXPORT.md#share-as-a-link)). |
+| `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> [--cairn <vault dir> [--vault <dir>]]` | 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). `--cairn` copies each variant to `<dir>/<id>-<nn>.png` and prints a `cairn:choice` card (`--json`: `data.cairnChoice`) to post in the Cairn chat; see [Picking on the phone](#picking-a-ladder-variant-in-cairn). |
+| `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 +133,57 @@ 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`.
+
+## Picking a ladder variant in Cairn
+
+Marcus picks on his phone, in the Cairn web chat, by tapping a picture; the tap locks it. The loop for an agent:
+
+1. `cascade ladder <graph> <node> --name <name> --seeds 1,2,3 --cairn <vault>/<space>/_attachments/ladders/<id> --json` (`<id>` is the name lower-cased with dashes). Each variant is copied to `<dir>/<id>-<nn>.png`, and `data.cairnChoice` is the card. At most 8 variants.
+2. Post `data.cairnChoice` in the reply exactly as returned:
+
+   ````text
+   ```cairn:choice
+   {"prompt":"Dial: which one? (ladder dial, index.cascade render)","options":[{"label":"seed 1","value":"pick:dial:1","image":"Work/Projects/Cascade/_attachments/ladders/dial/dial-01.png"}, …]}
+   ```
+   ````
+
+   `label` says what the variant changed (`seed 1`, `hue=0.3`); `image` is relative to the vault, the nearest `.obsidian` (then `.git`) above `--cairn`, or `--vault`.
+3. A tap comes back as `Picked: seed 1 (pick:dial:1)`. Run `cascade pick dial 1 --project <project>` (MCP: `pick { "ladder": "dial", "variant": 1 }`).
+4. Reply with the locked image, `![[<that option's image>]]`, and the lock id.
+
+## 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>`. Each run (one per frame with `--frames`) carries `ms`, the cook; `frameMs`, the whole frame to its outputs on disk; and `saveMs`, the difference (collecting and writing the outputs), beside each node's own `ms`.
+
+`--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/`. With none declared, doctor fails when a stage source imports numpy and the stage interpreter cannot (`stage imports`), which is how a project on the system Python renders nothing. 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,34 @@ 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.
+
+## Share as a link
+
+`cascade share` is the one step from a graph to a URL for the team:
+
+```sh
+cascade share plotter-social.cascade               # https://cascade-plotter-social.vercel.app
+cascade share renders/shelf --name commons-shelf   # any static directory with an index.html
+```
+
+It exports the editor into a scratch directory with the same allowlist and
+leak scan as `cascade export` (a directory is copied without dotfiles or
+`licensed/` and scanned the same way), deploys it to production in the Vercel
+project `cascade-<slug>` (team `field-io`, `--scope` for another), and prints
+the project's production URL. The slug is `--name`, else the editor id or the
+directory name. `--json` gives `data.url`, `data.deployment` and `data.shares`.
+
+Each share is recorded in the project's `shares.json` (the directory holding
+the graph, or the nearest `cascade.json` above a shared directory), one entry
+per source with its `name`, `project`, `url` and `sharedAt`. Sharing again
+replaces the entry and redeploys to the same URL.
+
+A share is public: that is what a link someone can open is. The export
+boundary above is the gate, so review `cascade export --plan` first.
+`--protected` instead requires Vercel Authentication on the project, as
+`cascade export --deploy vercel` does without `--public`.
 
 ## The `editor` section
 
@@ -121,12 +148,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 +249,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

@@ -36,9 +36,15 @@ With a global install (`npm i -g @field/cascade`), use `"command": "cascade", "a
 | `cook` | `cascade run <graph> [--node <id>]` |
 | `render` | `cascade run <graph> --frames … [--fps] [--out] [--node]… [--scene]` |
 | `export` | `cascade export <graph> --plan \| --out <dir>` |
+| `share` | `cascade share <graph \| directory> [--name] [--scope] [--protected]` (deploys; `data.url` is the link) |
 | `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] }`; `cairn`, an absolute vault directory, returns `data.cairnChoice`, a tap-to-pick card for the Cairn chat: see [Picking in Cairn](CLI_REFERENCE.md#picking-a-ladder-variant-in-cairn)), `cascade pick <ladder> <n>` (on "Picked: … (pick:<id>:<n>)", `ladder` <id>, `variant` <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 +57,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,321 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.image.Blur`
+
+Blur — Box (three passes, fast) or true Gaussian blur.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `method` | `string` | `"box"` |  |
+| `radius` | `float` | `5` | 0…100 |
+| `wrapEdges` | `bool` | `false` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Checkers`
+
+Checkers — A checkerboard.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `color1` | `color` | `[1,1,1,1]` |  |
+| `color2` | `color` | `[0,0,0,1]` |  |
+| `mode` | `string` | `"size"` |  |
+| `size` | `float` | `32` | 1…512 |
+| `divisions` | `int` | `16` | 1…512 |
+| `centered` | `bool` | `false` |  |
+| `resolution` | `vec2i` | `[512,512]` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Color`
+
+Color — A solid colour.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `color` | `color` | `[1,1,1,1]` |  |
+| `resolution` | `vec2i` | `[512,512]` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Composite`
+
+Composite — Blend image2 over image1.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image1` | `image` |  |  |
+| `image2` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `blendMode` | `string` | `"multiply"` |  |
+| `opacity` | `float` | `1` | 0…1 |
+| `outputResolution` | `string` | `"input1"` |  |
+| `customResolution` | `vec2i` | `[512,512]` | 1…4096 |
+| `fitMode` | `string` | `"fill"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `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.image.Image`
+
+File — An image file from the project, or an image input, optionally resized.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `file` | `string` | `""` |  |
+| `resolutionMode` | `string` | `"original"` |  |
+| `maxResolution` | `vec2i` | `[2048,2048]` | 1…4096 |
+| `fixedResolution` | `vec2i` | `[512,512]` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Noise`
+
+Noise — Fractal simplex noise, grey.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `seed` | `int` | `0` | 0…10000 |
+| `scale` | `float` | `0.01` | 0.001…1 |
+| `iterations` | `int` | `4` | 1…8 |
+| `resolution` | `vec2i` | `[512,512]` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.NormalMap`
+
+Normal Map — A normal map from the red (or grey) channel as height.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `scale` | `float` | `1` | 0…10 |
+| `flipX` | `bool` | `false` |  |
+| `flipY` | `bool` | `false` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Ramp`
+
+Ramp — A colour ramp: horizontal, vertical, radial or concentric.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `type` | `string` | `"horizontal"` |  |
+| `points` | `array` | `[{"position":0,"color":{"r":0,"g":0,"b":0},"interpolation":"linear"},{"position":1,"color":{"r":1,"g":1,"b":1},"interpolation":"linear"}]` |  |
+| `resolution` | `vec2i` | `[512,512]` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Resize`
+
+Resize — Scale an image, or resize it to a fixed size, bilinear.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `mode` | `string` | `"scale"` |  |
+| `scale` | `float` | `1` | 0.1…10 |
+| `width` | `int` | `512` | 1…4096 |
+| `height` | `int` | `512` | 1…4096 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Text`
+
+Text — Text drawn with a CSS font family, or a font file from the project.
+
+Runs on `portable`.
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `text` | `string` | `"Hello, World!"` |  |
+| `font` | `string` | `"Inter, system-ui, sans-serif"` |  |
+| `fontSize` | `float` | `48` | 1…500 |
+| `fontWeight` | `string` | `"normal"` |  |
+| `fontStyle` | `string` | `"normal"` |  |
+| `alignH` | `string` | `"center"` |  |
+| `alignV` | `string` | `"middle"` |  |
+| `color` | `color` | `[1,1,1,1]` |  |
+| `backgroundColor` | `color` | `[0,0,0,0]` |  |
+| `resolution` | `vec2i` | `[512,512]` | 1…4096 |
+| `offset` | `vec2` | `[0,0]` | -2048…2048 |
+| `rotation` | `float` | `0` | -180…180 |
+| `letterSpacing` | `float` | `0` | -50…100 |
+| `lineHeight` | `float` | `1.2` | 0.5…3 |
+| `opacity` | `float` | `1` | 0…1 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+### `cascade.image.Transform`
+
+Transform — Rotate, translate and scale an image about a pivot.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `translate` | `vec2` | `[0,0]` | -2048…2048 |
+| `rotation` | `float` | `0` | -180…180 |
+| `scale` | `vec2` | `[1,1]` | 0.01…10 |
+| `uniformScale` | `bool` | `true` |  |
+| `pivot` | `string` | `"center"` |  |
+| `customPivot` | `vec2` | `[0.5,0.5]` | 0…1 |
+| `filter` | `string` | `"bilinear"` |  |
+| `wrap` | `string` | `"clamp"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `image` | `image` |  |  |
+
 ### `cascade.math.Binary`
 
 Binary Math — Two values, one operation. Component-wise, and a scalar broadcasts against a vector.
@@ -973,6 +1288,115 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `scene` | `scene` |  |  |
 
+## Assertions
+
+`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. In Studio a failed assertion is the node's error. 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
@@ -991,16 +1415,6 @@ under `src/nodes/<library>/nodes/`.
 ### Geometry — `cascade.geo.*`
 
 **Geometry.** `cascade.geo.Rectangle` (A closed four-point polygon, counter-clockwise from bottom-left.), `cascade.geo.Circle` (A closed circle, as one cubic Bezier chain or as a polygon of divisions segments.), `cascade.geo.Transform` (Translate, rotate and scale geometry about a pivot.), `cascade.geo.Merge` (Concatenate geometries, taking the union of their attributes.), `cascade.geo.CopyToPoints` (Instance one geometry onto every point of another.), `cascade.geo.SvgExport` (Write geometry as an SVG document, one group element per group.), `cascade.geo.Render` (Draw a scene through a camera, as a raster.), `cascade.geo.FromRects` (Convert rects into geometry, one closed polygon each, keeping the tag.)
-
-### Image — `cascade.image.*`
-
-**Create.** `Image` (Load images from files), `Color` (Create a solid color canvas), `Checkers` (Generate a checkerboard pattern), `Noise` (Generate procedural noise patterns), `Ramp` (Generate color ramps), `Text` (Render text with customizable font and style)
-
-**Filter.** `Blur` (Gaussian blur), `NormalMap` (Compute normal map from height map)
-
-**Transform.** `Transform` (2D rotation, translation, and scaling), `Resize` (Scale or resize an image)
-
-**Composite.** `Composite` (Blend two images together)
 ## A project's own nodes
 
 Not listed here, because they belong to the project rather than to Cascade. Ask