forma-dsl-mcp 0.3.8 → 0.3.9

package/src/reference/api/evaluation-context.md

@@ -29,7 +29,7 @@ the node's digest.
 | | |
 | --- | --- |
 | **Parameter** | `node: GeometryNode` |
-| **Returns** | `Promise<Solid \| Shape>` — a `Manifold` for a 3D node, a `CrossSection` for a 2D one |
+| **Returns** | `Promise<Solid \| Shape>` - a `Manifold` for a 3D node, a `CrossSection` for a 2D one |
 | **Throws** | If the context has been disposed |
 
 Concurrent requests for the same node share one evaluation, so a shape used twice in a tree
@@ -41,12 +41,12 @@ Frees every cached object the given roots can no longer reach.
 
 | | |
 | --- | --- |
-| **`roots`** | `readonly GeometryNode[]` — the trees still in use |
+| **`roots`** | `readonly GeometryNode[]` - the trees still in use |
 | **`options.keep`** | `number`, default `512`. How many unreachable entries to keep as a most-recently-used tail |
-| **Returns** | `number` — how many objects were freed |
+| **Returns** | `number` - how many objects were freed |
 
 The retained tail matters more than it looks: editing churns the tree, so the entries that
-just fell out of it are the ones most likely to come straight back — on an undo, or on the
+just fell out of it are the ones most likely to come straight back - on an undo, or on the
 next character of a number being typed.
 
 ### `context.dispose()`
@@ -68,7 +68,7 @@ evaluations still in flight free their own results as they land. Disposing twice
 ## Why a context exists
 
 WebAssembly objects are not garbage-collected. Something has to own them, and something has
-to decide when they are no longer needed — that is this class.
+to decide when they are no longer needed - that is this class.
 
 It is also the cache. Nothing is freed as evaluation proceeds, because an intermediate result
 is also a cache entry and a later node may still need it. The two ways out are `collect`,
@@ -115,7 +115,7 @@ async function rerender(source, params) {
 }
 ```
 
-There is no `dispose` here, and that is correct — the page unloading frees the whole heap.
+There is no `dispose` here, and that is correct - the page unloading frees the whole heap.
 
 ### Tuning what is kept
 
@@ -141,7 +141,7 @@ console.log(`${evaluated} solved, ${hits} reused`);
 ```
 
 On a document where one dimension changed, `evaluated` should be a handful and `hits` most of
-the tree. If `evaluated` is the whole document every time, something is defeating the cache —
+the tree. If `evaluated` is the whole document every time, something is defeating the cache -
 see [Troubleshooting](#every-render-re-evaluates-everything).
 
 ### Evaluating a node directly
@@ -167,7 +167,7 @@ context.dispose();
 1. **Everything a context returns belongs to the context.** Never call `delete()` on a
    `Solid`, a `Shape` or anything hanging off `part.concrete`.
 2. **A result is valid only while its context is alive.** After `dispose()`, every object it
-   produced is gone. Copy out what you need first — `toRenderMesh` and `toBinarySTL` both
+   produced is gone. Copy out what you need first - `toRenderMesh` and `toBinarySTL` both
    produce plain typed arrays that outlive the context.
 3. **`render` does not dispose a context you supplied.** It disposes only one it created
    itself, and only on failure.
@@ -179,7 +179,7 @@ context.dispose();
 ### `EvaluationContext has been disposed`
 
 An `evaluate` or a `render` used a context after `dispose()`. Usually an async render that
-was still in flight when a page or a test tore the context down — await it first.
+was still in flight when a page or a test tore the context down - await it first.
 
 ### `EvaluationContext used before create() resolved`
 
@@ -198,19 +198,19 @@ Add a `collect` after each render, passing the roots that are still in use:
 context.collect(result.parts.map((part) => part.node));
 ```
 
-Without it, every intermediate solid from every render is retained — which is the correct
+Without it, every intermediate solid from every render is retained - which is the correct
 default, because the context cannot know whether you still hold a reference.
 
 ### `collect` freed nothing
 
-It returns `0` when the number of unreachable entries is at or below `keep` — the default 512
+It returns `0` when the number of unreachable entries is at or below `keep` - the default 512
 tail. That is expected on a small document. Pass `{ keep: 0 }` to see whether anything is
 genuinely unreachable.
 
 ### Every render re-evaluates everything
 
-Either a fresh context is being created per render — check that the same one is passed back
-in — or the document's content genuinely changes on every render. A param that feeds a
+Either a fresh context is being created per render - check that the same one is passed back
+in - or the document's content genuinely changes on every render. A param that feeds a
 dimension changes the digest of everything downstream of it, which is correct; a param that
 feeds only one wall should not.
 

package/src/reference/api/export.md

@@ -6,8 +6,8 @@ Turning a solved solid into buffers a renderer can upload, or a file a slicer ca
 import { toRenderMesh, toBinarySTL } from 'forma-dsl';
 ```
 
-Both take a `Solid` — the `concrete` field of a
-[rendered part](render.md#returns) — and both return plain typed arrays that **outlive the
+Both take a `Solid` - the `concrete` field of a
+[rendered part](render.md#returns) - and both return plain typed arrays that **outlive the
 context**, so they are what to copy out before disposing.
 
 ---
@@ -25,7 +25,7 @@ Converts a solid into flat arrays for a renderer.
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `positions` | `Float32Array` | Three vertices per triangle, expanded — `triangleCount * 9` floats |
+| `positions` | `Float32Array` | Three vertices per triangle, expanded - `triangleCount * 9` floats |
 | `normals` | `Float32Array` | One face normal, repeated for all three corners |
 | `triangleCount` | `number` | Triangles |
 | `vertexCount` | `number` | Vertices **before** expansion, as the kernel counted them |
@@ -44,7 +44,7 @@ The cost is that `positions.length / 3` is `triangleCount * 3` rather than `vert
 
 - A degenerate triangle keeps a zero normal rather than dividing by zero and poisoning the
   buffer with NaN.
-- [`render`](render.md) already calls this for every part — `part.mesh` is the result. Call
+- [`render`](render.md) already calls this for every part - `part.mesh` is the result. Call
   it yourself only for a solid you built directly.
 
 ---
@@ -59,7 +59,7 @@ Encodes a solid as binary STL.
 | --- | --- |
 | **`solid`** | `Solid` |
 | **`header`** | `string`, default `'forma-dsl'`. Free text for the 80-byte header, truncated to fit |
-| **Returns** | `Uint8Array` — the file |
+| **Returns** | `Uint8Array` - the file |
 
 Binary rather than ASCII: a model of any size is several times smaller and every slicer reads
 it.
@@ -141,7 +141,7 @@ function toThree(part) {
 
 ### Keeping geometry past the context
 
-Typed arrays are plain memory, so they survive disposal — unlike `part.concrete`:
+Typed arrays are plain memory, so they survive disposal - unlike `part.concrete`:
 
 ```js
 const result = await render(source);
@@ -159,7 +159,7 @@ result.context.dispose();              // …so this is safe
 
 ### `EvaluationContext has been disposed`
 
-The solid was freed before it was encoded. Export first, dispose after — or copy the arrays
+The solid was freed before it was encoded. Export first, dispose after - or copy the arrays
 out, which is what the example above does.
 
 ### The STL is empty, or has zero triangles

package/src/reference/api/geometry-node.md

@@ -7,7 +7,7 @@ the kernel consumes them.
 import { GeometryNode } from 'forma-dsl';
 
 const box = GeometryNode.shape(3, 'box', { size: [10, 10, 10], center: true });
-box.digest;       // '3f2a…' — 32 hex characters
+box.digest;       // '3f2a…' - 32 hex characters
 box.subtreeSize;  // 1
 ```
 
@@ -36,7 +36,7 @@ process, so it is identical in every browser and every run.
 | Property | Type | Description |
 | --- | --- | --- |
 | `dim` | `2 \| 3` | Whether this node is a cross-section or a solid |
-| `kind` | `string` | What the node does — `shape3d`, `boolean`, `transform`, `extrude`, … |
+| `kind` | `string` | What the node does - `shape3d`, `boolean`, `transform`, `extrude`, … |
 | `props` | `Record<string, unknown>` | The node's own parameters |
 | `children` | `readonly GeometryNode[]` | The operands |
 | `digest` | `string` | 128-bit content digest, 32 lowercase hex characters |
@@ -47,13 +47,13 @@ Nodes are frozen. Every factory returns a new node rather than mutating one.
 
 ### Factories
 
-Prefer these to the constructor — they apply the algebraic simplifications that keep the tree
+Prefer these to the constructor - they apply the algebraic simplifications that keep the tree
 small.
 
 | Factory | Description |
 | --- | --- |
 | `GeometryNode.empty(dim)` | A node standing for no geometry |
-| `GeometryNode.shape(dim, shape, params)` | A leaf primitive — `'box'`, `'circle'`, `'cylinder'`, … |
+| `GeometryNode.shape(dim, shape, params)` | A leaf primitive - `'box'`, `'circle'`, `'cylinder'`, … |
 | `GeometryNode.union(children)` | Everything added together |
 | `GeometryNode.difference(children)` | The first child with the rest removed |
 | `GeometryNode.intersection(children)` | Only what every child shares |
@@ -82,7 +82,7 @@ call and a cache entry:
 - **`dim` must be 2 or 3.** Anything else throws `bad dimensionality`.
 - **Booleans cannot mix dimensionality**: `cannot combine 2D and 3D geometry in a union`.
 - `GeometryNode.unary` defaults its result dimensionality to the child's, which is wrong for
-  the operations that change it — pass `dim` explicitly for anything extrude-like.
+  the operations that change it - pass `dim` explicitly for anything extrude-like.
 - Two nodes with the same digest are interchangeable. Nothing stops you building the same
   node twice; the cache will treat both as one.
 
@@ -108,7 +108,7 @@ for (const node of walk(result.parts[0].node)) {
 }
 ```
 
-Deduplicating on `digest` is what makes the walk reflect what the kernel will actually do —
+Deduplicating on `digest` is what makes the walk reflect what the kernel will actually do -
 the tree is a DAG, not a tree, once sharing is taken into account.
 
 ### Measuring how much a model shares
@@ -123,7 +123,7 @@ for (const node of walk(root)) unique.add(node.digest);
 console.log(`${root.subtreeSize} nodes written, ${unique.size} distinct`);
 ```
 
-A large gap is the digest cache doing its job — eight spheres in a loop are one sphere node
+A large gap is the digest cache doing its job - eight spheres in a loop are one sphere node
 and eight transforms.
 
 ### Building geometry without the language
@@ -151,7 +151,7 @@ await writeFile('ring.stl', toBinarySTL(solid));
 context.dispose();
 ```
 
-Note that `pin` is one node used six times — the kernel builds one cylinder.
+Note that `pin` is one node used six times - the kernel builds one cylinder.
 
 ### Checking whether an edit changed anything
 
@@ -211,5 +211,5 @@ GeometryNode.unary('extrude', profile, { height: 10, /* … */ }, 3);
 
 Digests cover **all** props. A `segments` of `0` and a `segments` of `32` are different
 shapes even when they look alike, and a float that differs in the last bit is a different
-number. Digest equality is exact, by design — the alternative is a cache that occasionally
+number. Digest equality is exact, by design - the alternative is a cache that occasionally
 returns the wrong solid.

package/src/reference/api/kernel.md

@@ -21,8 +21,8 @@ Loads and sets up the Manifold module, once per page or process.
 
 | | |
 | --- | --- |
-| **`options.locateFile`** | `() => string` — returns the URL of the `.wasm` file |
-| **Returns** | `Promise<Kernel>` — the `manifold-3d` toplevel module |
+| **`options.locateFile`** | `() => string` - returns the URL of the `.wasm` file |
+| **Returns** | `Promise<Kernel>` - the `manifold-3d` toplevel module |
 
 #### Caveats
 
@@ -30,7 +30,7 @@ Loads and sets up the Manifold module, once per page or process.
   share one instantiation rather than each starting their own.
 - **Only the first call's options take effect.** Later calls get the memoized promise, so
   `locateFile` has to be right the first time.
-- A rejected load is *not* memoized — a WASM fetch that lost the network can be retried
+- A rejected load is *not* memoized - a WASM fetch that lost the network can be retried
   rather than being permanently broken for the page.
 
 ### Bundlers and `locateFile`
@@ -48,7 +48,7 @@ await loadKernel({ locateFile: () => wasmUrl });
 Do this **before** the first `EvaluationContext.create()`, or the default path is what gets
 memoized.
 
-In Node, nothing is needed — the module resolves the file itself.
+In Node, nothing is needed - the module resolves the file itself.
 
 ---
 
@@ -75,7 +75,7 @@ left alone when omitted.
   solid built at draft quality will be *reused* at final quality unless the cache is cleared.
   See [Usage](#a-draft-pass-and-a-final-pass).
 - A shape's own `segments` attribute overrides all of this for that shape. Prefer it whenever
-  a specific facet count matters — a hole that must clear a printed bolt should not depend on
+  a specific facet count matters - a hole that must clear a printed bolt should not depend on
   a global.
 
 ## `resetQuality`
@@ -91,7 +91,7 @@ Restores the kernel's own defaults. Returns `Promise<void>`.
 ### A draft pass and a final pass
 
 Because quality is global and digests do not include it, the cache has to be dropped between
-passes — otherwise the final render happily reuses the draft's geometry:
+passes - otherwise the final render happily reuses the draft's geometry:
 
 ```js
 import { setQuality, EvaluationContext, render } from 'forma-dsl';
@@ -149,7 +149,7 @@ const context = await EvaluationContext.create();
 const { Manifold, CrossSection } = context.wasm;
 ```
 
-Anything you construct this way is **yours** to delete — the context only owns what it built
+Anything you construct this way is **yours** to delete - the context only owns what it built
 itself.
 
 ---
@@ -167,7 +167,7 @@ await loadKernel({ locateFile: () => wasmUrl });
 
 ### `locateFile` is being ignored
 
-The kernel was already loaded — the promise is memoized, so only the first call's options
+The kernel was already loaded - the promise is memoized, so only the first call's options
 count. Move the `loadKernel` call earlier, before anything creates a context.
 
 ### `setQuality` had no effect on an existing model

package/src/reference/api/low-level.md

@@ -1,7 +1,7 @@
 # Compiler stages
 
 The pipeline, stage by stage, plus the registries the evaluator reads. These are exported so
-that editors, linters and tools can reach into the compiler without re-implementing it — the
+that editors, linters and tools can reach into the compiler without re-implementing it - the
 [editor](../../../editor) uses them for syntax
 highlighting and inline diagnostics.
 
@@ -63,7 +63,7 @@ duplicate names and a component that shadows a builtin.
 ### `program.parameterDescriptors(evaluator?)`
 
 The declared params as [`ParameterDescriptor`](describe-parameters.md#returns)s. Without an
-evaluator, every field but the name comes back `undefined` —
+evaluator, every field but the name comes back `undefined` -
 [`describeParameters`](describe-parameters.md) is this with one supplied.
 
 #### Listing a document's models without rendering
@@ -104,10 +104,10 @@ everything unioned.
 
 #### Caveats
 
-- **The evaluator does not call the kernel** — except for `align`. Its output is a node tree;
+- **The evaluator does not call the kernel** - except for `align`. Its output is a node tree;
   solving it is [`EvaluationContext`](evaluation-context.md)'s job.
 - Without a `context`, a document containing `align` fails with
-  `align needs a kernel context — render the model rather than building it`.
+  `align needs a kernel context - render the model rather than building it`.
 - `requireParams: false` is for inspection only. A param with no value is simply absent from
   scope, so evaluating geometry that reads it will fail.
 
@@ -152,7 +152,7 @@ try {
 }
 ```
 
-Not every failure is a `FormaError` — a few come from the kernel, and `render` raises a plain
+Not every failure is a `FormaError` - a few come from the kernel, and `render` raises a plain
 `Error` for a 2D part. Check `error.loc` rather than the class when all you need is a
 position. See [Errors](../errors.md) for the full catalogue.
 
@@ -172,7 +172,7 @@ Every block the language understands, by name, as `Record<string, BlockDefinitio
 | `combine` | `'list'` receives every child; anything else receives them unioned |
 | `build(args, children?)` | Produces the node |
 
-**[`part`](../reference/part.md) and [`align`](../reference/align.md) are not in it** — the
+**[`part`](../reference/part.md) and [`align`](../reference/align.md) are not in it** - the
 evaluator handles both itself, because neither is an ordinary geometry operation.
 
 ```js
@@ -184,8 +184,8 @@ Object.keys(BLOCKS).filter((k) => BLOCKS[k].leaf);     // just the shapes
 
 ### `FUNCTIONS`
 
-Every builtin function, as `Record<string, FunctionDefinition>` with `arity` — `null` for
-variadic — and `call(args)`.
+Every builtin function, as `Record<string, FunctionDefinition>` with `arity` - `null` for
+variadic - and `call(args)`.
 
 ### `CONSTANTS`
 
@@ -213,7 +213,7 @@ cannot be added without the documentation's code samples learning about it.
 
 ## Troubleshooting
 
-### `align needs a kernel context — render the model rather than building it`
+### `align needs a kernel context - render the model rather than building it`
 
 Pass a context, or avoid `align` in documents you intend to evaluate without one:
 

package/src/reference/api/render.md

@@ -33,7 +33,7 @@ A `Promise<RenderResult>`:
 | Field | Type | Description |
 | --- | --- | --- |
 | `name` | `string` | The model's name |
-| `parts` | `RenderedPart[]` | One per [`part`](../reference/part.md) — see below |
+| `parts` | `RenderedPart[]` | One per [`part`](../reference/part.md) - see below |
 | `program` | [`Program`](low-level.md#program) | The parsed document, for inspecting params |
 | `context` | `EvaluationContext` | The context that owns every solid in `parts` |
 | `stats` | `RenderStats` | `nodes`, `evaluated`, `cacheHits`, `milliseconds` |
@@ -60,7 +60,7 @@ Each `RenderedPart`:
 - Params are resolved before any geometry is built, so a missing required param fails
   immediately rather than halfway through a model.
 - `options.params` sets **top-level** params only. A param declared inside a `model` is a
-  constant — see [model params](../reference/model.md#model-params).
+  constant - see [model params](../reference/model.md#model-params).
 
 ---
 
@@ -129,7 +129,7 @@ async function rerender(source, params) {
 }
 ```
 
-Typing a digit into a dimension re-solves that wall and nothing else — `stats.cacheHits`
+Typing a digit into a dimension re-solves that wall and nothing else - `stats.cacheHits`
 against `stats.evaluated` shows how much was skipped.
 
 ### Choosing a model
@@ -165,7 +165,7 @@ result.context.dispose();
 ```js
 const { stats } = await render(source, { context });
 
-stats.nodes;        // nodes in the tree — a measure of the document's size
+stats.nodes;        // nodes in the tree - a measure of the document's size
 stats.evaluated;    // kernel calls actually made, across the context's life
 stats.cacheHits;    // how many were avoided
 stats.milliseconds; // wall clock for this render
@@ -181,7 +181,7 @@ them across calls rather than reading one in isolation.
 ### `EvaluationContext has been disposed`
 
 Something held on to a result after disposing the context that owns it. `part.concrete` and
-`part.mesh` are only valid while the context is alive — copy the mesh arrays out first if you
+`part.mesh` are only valid while the context is alive - copy the mesh arrays out first if you
 need them later.
 
 ### Memory grows across renders
@@ -193,18 +193,18 @@ Add the `collect` call. A reused context caches every solid it has ever built, b
 context.collect(result.parts.map((part) => part.node));
 ```
 
-### `part "body" is 2D — extrude or revolve it before rendering`
+### `part "body" is 2D - extrude or revolve it before rendering`
 
 The model produced a cross-section. See [2D ↔ 3D](../reference/conversions.md).
 
-### `align needs a kernel context — render the model rather than building it`
+### `align needs a kernel context - render the model rather than building it`
 
 Only happens when driving [`Evaluator`](low-level.md#evaluator) directly without a context.
 `render` always supplies one.
 
 ### The error has no line number
 
-Most do — `FormaError` carries a `loc` with `line`, `column` and `offset`, and appends it to
+Most do - `FormaError` carries a `loc` with `line`, `column` and `offset`, and appends it to
 the message. A few errors are raised before any position is known (`the document declares no
 model`) or inside a value helper that has none (`no attribute "a"`).
 

package/src/reference/api/values.md

@@ -1,8 +1,8 @@
 # Values
 
 Three small immutable classes the evaluator works in: [`Vector`](#vector),
-[`Angle`](#angle) and [`Transform`](#transform). Documents never see them directly — a
-document writes lists and bare numbers — but they are exported for anyone building geometry
+[`Angle`](#angle) and [`Transform`](#transform). Documents never see them directly - a
+document writes lists and bare numbers - but they are exported for anyone building geometry
 through the [`GeometryNode`](geometry-node.md) API.
 
 ```js
@@ -26,7 +26,7 @@ separate 3D class would be the same code with one more letter.
 | `Vector.of(value, dimensions)` | From anything vector-like |
 | `Vector.zero(dimensions)` | The origin |
 
-`Vector.of` accepts a `Vector`, a **number** — broadcast to every component — an array, or an
+`Vector.of` accepts a `Vector`, a **number** - broadcast to every component - an array, or an
 `{x, y, z}` object whose missing keys read as zero. This is what makes
 `scale { factor = 2 }` work the same as `factor = [2, 2, 2]`.
 
@@ -89,7 +89,7 @@ wrong rather than an error.
 | `plus(other)` `minus(other)` | Other may be an `Angle` or a number of degrees |
 | `times(factor)` | A plain multiplier, not an angle |
 
-The unit names appear twice — `Angle.degrees(90)` builds one, `angle.degrees` reads one back.
+The unit names appear twice - `Angle.degrees(90)` builds one, `angle.degrees` reads one back.
 They are different namespaces and do not collide.
 
 ---
@@ -121,9 +121,9 @@ renders.
 | --- | --- |
 | `dim` | 2 or 3 |
 | `m` | The matrix, column-major and frozen |
-| `order` | Side length — one more than `dim` |
+| `order` | Side length - one more than `dim` |
 | `at(row, col)` | One entry, read out of column-major storage |
-| `concat(other)` | `this ∘ other` — **`other` runs first** |
+| `concat(other)` | `this ∘ other` - **`other` runs first** |
 | `toArray()` | A copy, safe to keep |
 
 #### Caveats
@@ -145,7 +145,7 @@ renders.
 ```js
 import { Transform, GeometryNode } from 'forma-dsl';
 
-// Rotate, then move — the argument to concat runs first.
+// Rotate, then move - the argument to concat runs first.
 const placement = Transform.translation([30, 0, 0], 3)
   .concat(Transform.rotation3D([0, 0, 45]));
 
@@ -176,7 +176,7 @@ import { Angle } from 'forma-dsl';
 const a = Angle.degrees(30);
 a.sin;         // 0.5
 a.radians;     // 0.5235987755982988
-a.plus(60).degrees;   // 90 — a bare number is read as degrees
+a.plus(60).degrees;   // 90 - a bare number is read as degrees
 ```
 
 ### Vector arithmetic
@@ -190,8 +190,8 @@ const wall = 2;
 const inner = size.minus(new Vector([wall * 2, wall * 2, 0]));
 inner.toArray();      // [36, 26, 12]
 
-Vector.of(3, 3).toArray();          // [3, 3, 3] — a scalar broadcasts
-Vector.of({ x: 1, z: 5 }, 3).toArray();  // [1, 0, 5] — missing keys are zero
+Vector.of(3, 3).toArray();          // [3, 3, 3] - a scalar broadcasts
+Vector.of({ x: 1, z: 5 }, 3).toArray();  // [1, 0, 5] - missing keys are zero
 ```
 
 ---
@@ -205,7 +205,7 @@ surfaces more helpfully as `translate: "offset" must be a number or an array of
 
 ### `cannot read an angle from string`
 
-`Angle.of` takes an `Angle` or a number. A string is not coerced — that would let `"90deg"`
+`Angle.of` takes an `Angle` or a number. A string is not coerced - that would let `"90deg"`
 silently become `NaN`.
 
 ### My composed transform is applied in the wrong order
@@ -219,5 +219,5 @@ Every transform is about the origin. Centre the geometry, rotate, then translate
 
 ### Non-uniform scaling made my circle an ellipse
 
-Expected — that is how [`ellipse`](../reference/shapes-2d.md#ellipse) is built internally, and
+Expected - that is how [`ellipse`](../reference/shapes-2d.md#ellipse) is built internally, and
 it is the cheapest route to an ellipsoid from a sphere.

package/src/reference/cli.md

@@ -0,0 +1,146 @@
+# Command line
+
+[`forma-dsl-cli`](https://www.npmjs.com/package/forma-dsl-cli) solves a document and writes a
+binary STL, with no browser and no build step. It is what puts a `.forma` file in a Makefile,
+a CI job or a release pipeline.
+
+```bash
+npm install -g forma-dsl-cli
+forma render riser.forma -p height=32 -o build/riser.stl
+```
+
+Or, without installing it, `npx forma-dsl-cli render riser.forma -o riser.stl`.
+
+It knows nothing about the language itself. Every answer comes from `forma-dsl` - the same
+package the editor and the MCP server import - so a block added to the language is one it
+renders without being told, and an error it reports is the evaluator's own, with the
+evaluator's own position.
+
+---
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `forma render <file>` | solve a document and write a binary STL |
+| `forma params <file>` | list the parameters the document declares |
+| `forma models <file>` | list the models the document declares |
+
+A `<file>` of `-` reads the document from stdin. `params` and `models` take `--json`.
+
+### `render`
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `-o, --out <file>` | `<file>.stl` | where to write. `-` is stdout |
+| `-m, --model <name>` | the first declared | which [model](reference/model.md) to build |
+| `--part <name>` | see below | one [part](reference/part.md) by name |
+| `-p, --param <name=val>` | each param's own default | a value for one declared [param](reference/param.md). Repeatable |
+| `--segments <n>` | the kernel's own | a fixed segment count for every curve |
+| `--min-angle <deg>` | the kernel's own | smallest angle between adjacent segments of a curve |
+| `--min-edge <n>` | the kernel's own | smallest length a curve segment may be shortened to |
+| `--max-nodes <n>` | no limit | refuse a document that would build more blocks than this |
+| `-q, --quiet` | off | do not print the summary |
+
+The three resolution options are [`setQuality`](api/kernel.md) under another name, and are
+global to the kernel exactly as they are there. `--max-nodes` is
+[`render`](api/render.md)'s own budget.
+
+Without `--part`, a model with one part exports that part, and a model with several exports
+them **unioned**. STL has no notion of a part, and a slicer reading two overlapping shells
+makes a mess of them.
+
+---
+
+## Parameter values
+
+A value is JSON where it parses as JSON, and the string as written otherwise. That is what
+makes all four of these arrive as the type the document expects, with no second layer of
+quoting:
+
+```bash
+forma render part.forma -p count=6 -p center=true -p size=[10,20] -p label=M6
+```
+
+---
+
+## In a pipeline
+
+Only what was asked for goes to stdout - the STL under `-o -`, and the listings. The summary
+and every diagnostic go to stderr, so a pipe stays clean:
+
+```bash
+forma render riser.forma --segments 64 -o - > riser.stl
+```
+
+Exit codes are the three a script needs to tell apart:
+
+| Code | What happened |
+| --- | --- |
+| `0` | it worked |
+| `1` | the document did not build - a syntax error, an unknown name, a degenerate solid |
+| `2` | the invocation was wrong - an unknown flag, a missing file, a part that does not exist |
+
+The summary names the cache hits, because that is the number explaining why the second render
+of the same document in a loop is faster, and it is otherwise invisible:
+
+```
+build/riser.stl - 252 triangles · model "riser", part "body" · 6 nodes, 6 solved, 0 cached · 9 ms
+```
+
+---
+
+## Failures
+
+A failure is reported where an editor and a CI annotation can both find it: the position as a
+`file:line:column:` prefix, then the lines around it with a caret under the column.
+
+```
+riser.forma:7:23: size must be positive
+ 5 |   part "body" {
+ 6 |     extrude {
+ 7 |       rect { size = [-40, 20] }
+   |                     ^
+ 8 |     }
+ 9 |   }
+```
+
+The position comes from the error itself - see [Errors](errors.md) for what each stage raises
+and what it means.
+
+---
+
+## Building a matrix
+
+`params --json` is the document describing itself, which is what lets a script build every
+variant without being told what the variants are:
+
+```bash
+forma params riser.forma --json
+```
+
+```json
+[
+  {
+    "name": "height",
+    "type": "number",
+    "default": 20,
+    "required": false,
+    "min": 8,
+    "max": 40
+  }
+]
+```
+
+```bash
+for h in 8 20 40; do
+  forma render riser.forma -p "height=$h" -o "build/riser-$h.stl"
+done
+```
+
+---
+
+## Units
+
+Lengths are unitless in forma, and STL has no unit either. Every consumer treats them as
+millimetres.