forma-dsl-mcp 0.3.7 → 0.3.9

package/README.md

@@ -5,7 +5,7 @@
 [![M8ven Verified](https://m8ven.ai/api/agent-verify/badge?score=100)](https://m8ven.ai/verified/verify?id=d3529b4756004447)
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that knows
-[forma](https://www.npmjs.com/package/forma-dsl) — the declarative DSL for 3D solids — and
+[forma](https://www.npmjs.com/package/forma-dsl) - the declarative DSL for 3D solids - and
 builds it with the real geometry kernel, so a `.forma` document is measured before anyone is
 told it works.
 
@@ -57,7 +57,7 @@ The server does not choose. It asks the client over MCP's
 writes only inside the directories the client hands over. A relative path is taken against
 the first of them, and every write reports the directory it landed in.
 
-**Every path is confined to those directories** — an absolute path outside them, a `..` that
+**Every path is confined to those directories** - an absolute path outside them, a `..` that
 climbs out, or a symlink pointing out of the tree is refused rather than followed. When the
 client says its roots have changed, the server re-reads them before the next call.
 
@@ -76,7 +76,7 @@ cwd = "/absolute/path/to/your/models"
 A model that has read the language's documentation still writes forma that does not build.
 The difference this server makes is that it **runs the geometry kernel**. Every tool compiles
 the document, solves it with [Manifold](https://github.com/elalish/manifold) and reports back
-the bounding box, the volume, the triangle count and the genus of every part — so the
+the bounding box, the volume, the triangle count and the genus of every part - so the
 question "is this the size that was asked for, and is it actually a solid?" is answered
 before the work is handed over. A part that silently solved to nothing is called out by name,
 and an error comes back with the line, the column and an excerpt with a caret on it.
@@ -84,7 +84,7 @@ and an error comes back with the line, the column and an excerpt with a caret on
 `forma_write` **refuses to write a document that does not render**.
 
 Refusals carry the vocabulary too: an unknown block comes back with every block there is, and
-an unknown attribute with the ones that block reads. That is the backstop, not the teacher —
+an unknown attribute with the ones that block reads. That is the backstop, not the teacher -
 it is enough to correct a misspelling and not enough to learn a language, since it gives the
 name of a block and nothing about what that block means or what it takes. `forma_guide`,
 `forma_blocks` and `forma_reference` are what answer that, and they are bundled so they
@@ -120,24 +120,24 @@ is rendered by the test suite.
 
 The same knowledge in the form a person can attach to a conversation by hand:
 
-- `forma://guide` — the language in brief
-- `forma://catalogue` — every block and function, as JSON
-- `forma://reference/{path}` — one page of the manual
-- `forma://example/{name}` — one worked document
+- `forma://guide` - the language in brief
+- `forma://catalogue` - every block and function, as JSON
+- `forma://reference/{path}` - one page of the manual
+- `forma://example/{name}` - one worked document
 
 ## Asking for a part
 
 Install it in Codex as above, `cd` to wherever you keep your models, and ask:
 
-> **you** — build me a forma file with a tree in it
+> **you** - build me a forma file with a tree in it
 
-> **codex** — Where should I put it?
+> **codex** - Where should I put it?
 
-> **you** — the current folder
+> **you** - the current folder
 
 Codex reads the language before it writes any: `forma_guide` for the shape of a document,
-`forma_blocks` for the attributes of the blocks it is about to use — here `cone`, `translate`
-and `for` — and `forma_examples` for a document of a similar shape. Then it writes, and
+`forma_blocks` for the attributes of the blocks it is about to use - here `cone`, `translate`
+and `for` - and `forma_examples` for a document of a similar shape. Then it writes, and
 `forma_write` builds what it wrote with the real kernel before anything reaches the disk.
 
 Where the vocabulary runs out, the refusals carry it. A guess at a block that does not exist
@@ -145,17 +145,17 @@ comes back with every block that does, and a guess at an attribute with the ones
 reads:
 
 ```
-unknown block "frustum" — the blocks are "align", "for", "if", "part", "box", "circle",
+unknown block "frustum" - the blocks are "align", "for", "if", "part", "box", "circle",
   "cone", "cylinder", "difference", … "union"
 
-cone: unknown attribute "bottom_radius" — cone reads "center", "height", "radius",
+cone: unknown attribute "bottom_radius" - cone reads "center", "height", "radius",
   "segments", "top_radius"
 ```
 
 Then it lands, and the tool answers with the part rather than with a claim about it:
 
 ```
-Wrote `tree.forma` under `/home/you/models` — 537 bytes.
+Wrote `tree.forma` under `/home/you/models` - 537 bytes.
 
 | Part     | Colour  | Opacity | Size (X × Y × Z) | Volume    | Triangles | Genus |
 | `trunk`  | #6b4423 |       1 | 8 × 8 × 30       | 1004.682  |       108 |     0 |
@@ -243,7 +243,7 @@ this tarball, so it works with no network at all. There is no telemetry, no anal
 update check and no account.
 
 It writes only inside the directories your client declares as MCP roots, never replaces a file
-unless told to, and leaves nothing elsewhere — no cache, no config, no logs.
+unless told to, and leaves nothing elsewhere - no cache, no config, no logs.
 
 Your MCP client is a separate program with its own policy. Documents you ask a model to write
 travel wherever that client sends them, which this server neither controls nor sees.
@@ -252,4 +252,4 @@ Full text: [PRIVACY.md](https://github.com/kalpak44/forma-dsl/blob/main/PRIVACY.
 
 ## License
 
-MIT — see [LICENSE](LICENSE).
+MIT - see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-mcp",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "A stdio MCP server that knows the forma DSL and writes .forma documents that render.",
   "keywords": [
     "mcp",
@@ -45,8 +45,8 @@
     "sync:reference": "node scripts/sync-reference.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.0",
-    "forma-dsl": "^0.3.7",
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "forma-dsl": "^0.3.9",
     "zod": "^4.1.13"
   }
 }

package/src/bin.js

@@ -2,7 +2,7 @@
 /**
  * The executable: one MCP server, speaking over stdin and stdout.
  *
- * Nothing may be written to stdout but the protocol — a stray `console.log` corrupts the
+ * Nothing may be written to stdout but the protocol - a stray `console.log` corrupts the
  * JSON-RPC stream and the client disconnects with an error that names nothing. Everything
  * this file has to say goes to stderr, which clients collect as the server's log.
  *

package/src/catalogue.js

@@ -1,9 +1,9 @@
 /**
  * What the server knows about every construct in the language.
  *
- * The descriptions and the attribute tables are written here; the structural facts — which
+ * The descriptions and the attribute tables are written here; the structural facts - which
  * blocks exist, what dimensionality each produces and takes, which functions exist and with
- * what arity — are read from the package's own registries at load time and merged in. Where
+ * what arity - are read from the package's own registries at load time and merged in. Where
  * the two disagree, the registry wins and `catalogueDrift` says so, which is what
  * `test/catalogue.test.js` asserts is empty. A block added to the language therefore cannot
  * ship without this file learning about it.
@@ -81,7 +81,7 @@ const BLOCK_ENTRIES = [
       CENTER,
     ],
     example: 'rounded_rect { size = [62, 13]  radius = 6.5  center = true }',
-    notes: ['`rounded_rect { size = [10, 10]  radius = 5 }` is a circle of diameter 10 — `size` is the outer size.'],
+    notes: ['`rounded_rect { size = [10, 10]  radius = 5 }` is a circle of diameter 10 - `size` is the outer size.'],
   },
   {
     name: 'circle', group: '2D shapes', summary: 'A circle, from a radius or a diameter.',
@@ -112,7 +112,7 @@ const BLOCK_ENTRIES = [
       { name: 'sides', type: 'integer', default: 'required', description: 'At least 3' },
       {
         name: 'width_across_flats', type: 'number',
-        description: 'Distance between opposite flats — how a nut or a hex key is specified',
+        description: 'Distance between opposite flats - how a nut or a hex key is specified',
       },
       { name: 'width_across_corners', type: 'number', description: 'Distance between opposite corners' },
       { name: 'radius', type: 'number', default: '1', description: 'Centre to corner' },
@@ -479,17 +479,17 @@ const DECLARATIONS = [
         name: 'type', type: 'enum', values: ['number', 'string', 'bool', 'vector', 'list', 'angle'],
         description: 'Which control to build. Written bare, without quotes. Inferred from `default` when omitted',
       },
-      { name: 'min', type: 'number', description: 'Lower bound of the control. Advisory — never enforced' },
-      { name: 'max', type: 'number', description: 'Upper bound of the control. Advisory — never enforced' },
+      { name: 'min', type: 'number', description: 'Lower bound of the control. Advisory - never enforced' },
+      { name: 'max', type: 'number', description: 'Upper bound of the control. Advisory - never enforced' },
       { name: 'step', type: 'number', description: 'Granularity of the control. Advisory' },
       { name: 'description', type: 'string', description: 'Help text' },
       { name: 'options', type: 'list', description: 'A fixed set of choices, for a dropdown. Advisory' },
     ],
     example: 'param height { type = number  default = 20  min = 8  max = 40  step = 1 }\nparam wall = 2.5',
     notes: [
-      'This is the one block that does not reject attributes it does not understand — a param block is metadata.',
+      'This is the one block that does not reject attributes it does not understand - a param block is metadata.',
       '`min`, `max`, `step` and `options` shape the editor control and nothing else. Clamp in the model if a bound matters.',
-      "A default may refer to params declared above it by their bare name, but never to `var` — `var` is assembled after every param resolves.",
+      "A default may refer to params declared above it by their bare name, but never to `var` - `var` is assembled after every param resolves.",
       'A param declared inside a `model` must have a default and cannot be set from outside.',
       '`param s` on its own is a syntax error; write `param s { }` for a required one.',
     ],
@@ -513,7 +513,7 @@ const DECLARATIONS = [
     notes: [
       'Params are read by their bare name inside the body; there is no `var.` for them.',
       'Only declared params may be passed. There is no pass-through.',
-      'A component body cannot see the call site — it is evaluated in a fresh scope rooted at the document.',
+      'A component body cannot see the call site - it is evaluated in a fresh scope rooted at the document.',
       'A component cannot declare parts, cannot shadow a builtin, and cannot recurse.',
       'Reuse is free: the same call with the same arguments is one node in the tree, evaluated once.',
     ],
@@ -596,8 +596,8 @@ const FUNCTION_DESCRIPTIONS = {
   round: 'Rounds to the nearest integer, halves upwards',
   sqrt: 'Square root. A negative input gives NaN, which fails where it is used',
   sign: '-1, 0 or 1',
-  pow: 'pow(x, y) — x raised to y',
-  atan2: 'atan2(y, x) — degrees, in the correct quadrant',
+  pow: 'pow(x, y) - x raised to y',
+  atan2: 'atan2(y, x) - degrees, in the correct quadrant',
   log: 'Natural logarithm',
   exp: 'e raised to x',
   sin: 'Takes degrees, returns a ratio',
@@ -612,8 +612,8 @@ const FUNCTION_DESCRIPTIONS = {
   len: 'Length of a list or a string; 0 for anything else',
   concat: 'Every argument flattened into one list',
   reverse: 'A list, back to front',
-  contains: 'contains(list, value) — whether the list holds it',
-  join: 'join(separator, list) — the items as one string',
+  contains: 'contains(list, value) - whether the list holds it',
+  join: 'join(separator, list) - the items as one string',
   str: 'The value as a string',
   num: 'The value as a number; non-numeric text gives NaN',
   range: 'range(end), range(start, end) or range(start, end, step). Excludes the end; capped at 100000 values',
@@ -679,7 +679,7 @@ export function formatConstruct(entry) {
   /** @type {string[]} */
   const facts = [];
   if (entry.dim) facts.push(`produces ${entry.dim}D`);
-  if (entry.leaf) facts.push('a leaf — it takes no children');
+  if (entry.leaf) facts.push('a leaf - it takes no children');
   else if (entry.takes === 'same') facts.push("takes 2D or 3D children, passing the dimensionality through");
   else if (entry.takes) facts.push(`takes ${entry.takes}D children`);
   if (entry.ordered) facts.push('the order of its children matters');
@@ -691,7 +691,7 @@ export function formatConstruct(entry) {
       const type = attribute.values
         ? attribute.values.map((value) => `\`"${value}"\``).join(' ')
         : attribute.type;
-      lines.push(`| \`${attribute.name}\` | ${type} | ${attribute.default ?? '—'} | ${attribute.description} |`);
+      lines.push(`| \`${attribute.name}\` | ${type} | ${attribute.default ?? '-'} | ${attribute.description} |`);
     }
     lines.push('');
   }

package/src/document.js

@@ -13,19 +13,17 @@ import {
   GeometryNode,
   Program,
   describeParameters,
+  excerpt,
   render,
   toBinarySTL,
 } from 'forma-dsl';
 
-/** How many lines of source to show either side of an error. */
-const CONTEXT_LINES = 2;
-
 /**
  * How much geometry one document may build before the server refuses it.
  *
  * This server exists to build text a model wrote, which is the case the library leaves a
  * budget off for. Nesting limits and `range` each bound one loop; only this bounds two of
- * them nested, and that shape asks for more geometry than the process can finish — on a pipe,
+ * them nested, and that shape asks for more geometry than the process can finish - on a pipe,
  * with no request timeout of its own, that is a server that never answers again.
  *
  * Set far above any honest document: the worked examples build tens of blocks. A model that
@@ -38,7 +36,7 @@ const MAX_NODES = 50_000;
  * that changed.
  *
  * Kept at module scope rather than per-request because that is the whole point of the digest
- * cache — a context that lives for one call caches nothing.
+ * cache - a context that lives for one call caches nothing.
  *
  * @type {EvaluationContext | null}
  */
@@ -56,38 +54,10 @@ export function disposeSharedContext() {
   shared = null;
 }
 
-/**
- * Renders a source excerpt with a caret under the column an error points at.
- *
- * An error message with a line number still makes a model count lines. An excerpt does not.
- *
- * @param {string} source The document.
- * @param {{ line: number, column: number } | null | undefined} loc Where the error was raised.
- * @returns {string | undefined} The excerpt, or undefined when there is no position.
- */
-export function excerpt(source, loc) {
-  if (!loc || !Number.isInteger(loc.line)) return undefined;
-
-  const lines = source.split('\n');
-  const first = Math.max(1, loc.line - CONTEXT_LINES);
-  const last = Math.min(lines.length, loc.line + CONTEXT_LINES);
-  const width = String(last).length;
-
-  /** @type {string[]} */
-  const out = [];
-  for (let n = first; n <= last; n++) {
-    out.push(`${String(n).padStart(width)} | ${lines[n - 1]}`);
-    if (n === loc.line) {
-      out.push(`${' '.repeat(width)} | ${' '.repeat(Math.max(0, loc.column - 1))}^`);
-    }
-  }
-  return out.join('\n');
-}
-
 /**
  * Turns a thrown error into the shape a tool result reports.
  *
- * @param {string} stage Which pass raised it — the stage is what tells a caller whether the
+ * @param {string} stage Which pass raised it - the stage is what tells a caller whether the
  *   mistake was a typo, a misunderstanding of meaning, or a degenerate solid.
  * @param {unknown} error What was thrown.
  * @param {string} source The document, for the excerpt.
@@ -119,7 +89,7 @@ const tidy = (value) => Number.parseFloat(value.toFixed(4));
  * What a solved part is, measured.
  *
  * The bounding box and the volume are what let a caller check a model against a requirement
- * it was given — "it has to fit in 100 x 60" is answerable from here without a viewer.
+ * it was given - "it has to fit in 100 x 60" is answerable from here without a viewer.
  *
  * @param {Solid} solid The solved part.
  * @returns {object} Its measurements.
@@ -198,7 +168,7 @@ export async function checkDocument(source, options = {}) {
       ...declared,
       error: {
         stage: 'render',
-        message: 'the document declares no model — add a `model "name" { ... }` block',
+        message: 'the document declares no model - add a `model "name" { ... }` block',
       },
     };
   }
@@ -276,7 +246,7 @@ export async function exportStl(source, options = {}) {
     const wanted = result.parts.find((candidate) => candidate.name === part);
     if (!wanted) {
       const names = result.parts.map((candidate) => `"${candidate.name}"`).join(', ');
-      throw new Error(`no part named "${part}" in model "${result.name}" — it has ${names}`);
+      throw new Error(`no part named "${part}" in model "${result.name}" - it has ${names}`);
     }
     solid = wanted.concrete;
     name = wanted.name;
@@ -285,7 +255,7 @@ export async function exportStl(source, options = {}) {
     name = result.parts[0].name;
   } else {
     // Several parts in one file: STL has no notion of a part, so they are unioned rather
-    // than concatenated — a slicer reading two overlapping shells makes a mess of them.
+    // than concatenated - a slicer reading two overlapping shells makes a mess of them.
     solid = await shared.evaluate(GeometryNode.union(result.parts.map((each) => each.node)));
     name = 'all';
   }

package/src/examples.js

@@ -126,7 +126,7 @@ model "stacked_trays" {
 
   {
     name: 'revolved-profile',
-    summary: 'A vase turned from a profile — the shortest route from a drawing to a solid.',
+    summary: 'A vase turned from a profile - the shortest route from a drawing to a solid.',
     shows: ['polygon from a table of points', 'revolve', 'a second profile derived from the first', 'segments'],
     source: `param wall   { type = number  default = 2.4  min = 1.2  max = 5    step = 0.2 }
 param base   { type = number  default = 3.5  min = 2    max = 8    step = 0.5 }

package/src/guide.js

@@ -1,7 +1,7 @@
 /**
  * The language, compressed to what someone writing a document has to hold in their head.
  *
- * This is deliberately not the reference manual — the manual is bundled too, and
+ * This is deliberately not the reference manual - the manual is bundled too, and
  * `forma_reference` serves it. This is the page that goes into a model's context before it
  * writes anything: the rules that are not guessable, the mistakes that are expensive, and
  * the shape of a working document.
@@ -43,7 +43,7 @@ model "riser" {
 }
 \`\`\`
 
-Order does not matter between declarations of different kinds — a model may use a component
+Order does not matter between declarations of different kinds - a model may use a component
 declared below it. Order does matter among top-level \`local\`s, which resolve top to bottom.`,
 
   nesting: `## Nesting is composition
@@ -77,8 +77,8 @@ children is an error.`,
 
 Every piece of geometry is 2D or 3D, and the language tracks which.
 
-- **2D** — \`rect\` \`rounded_rect\` \`circle\` \`ellipse\` \`regular_polygon\` \`stadium\` \`polygon\`
-- **3D** — \`box\` \`sphere\` \`cylinder\` \`cone\` \`torus\`
+- **2D** - \`rect\` \`rounded_rect\` \`circle\` \`ellipse\` \`regular_polygon\` \`stadium\` \`polygon\`
+- **3D** - \`box\` \`sphere\` \`cylinder\` \`cone\` \`torus\`
 - **Operations** either fix what they take (\`extrude\` takes 2D, \`refine\` takes 3D) or pass
   their children's dimensionality through (\`translate\` \`rotate\` \`scale\` \`mirror\` \`hull\`
   \`simplify\` \`align\`, the booleans).
@@ -89,17 +89,17 @@ Three rules, each with its own error:
 | --- | --- |
 | Children of one block must all be the same dimensionality | \`"union" cannot mix 2D and 3D shapes\` |
 | A block that fixes what it takes must get it | \`"extrude" takes 2D geometry, got 3D\` |
-| Anything rendered must be 3D | \`part "body" is 2D — extrude or revolve it before rendering\` |
+| Anything rendered must be 3D | \`part "body" is 2D - extrude or revolve it before rendering\` |
 
 2D → 3D with \`extrude\` or \`revolve\`; 3D → 2D with \`project\` or \`slice\`.`,
 
   units: `## Units and orientation
 
 - **Lengths are unitless.** Every consumer treats them as millimetres.
-- **Angles are always degrees.** Everywhere — \`rotate { z = 90 }\`, \`revolve { angle = 180 }\`,
+- **Angles are always degrees.** Everywhere - \`rotate { z = 90 }\`, \`revolve { angle = 180 }\`,
   \`sin(30)\`, \`param a { type = angle }\`. There is no radian form.
 - **Z is up.** \`extrude\` sweeps along +Z. \`revolve\` spins a profile written in the XY plane
-  about the Y axis, mapping the profile's Y to the result's Z — so a profile drawn upwards
+  about the Y axis, mapping the profile's Y to the result's Z - so a profile drawn upwards
   from \`[0, 0]\` produces a solid standing on the XY plane.
 - **3D rotations apply X, then Y, then Z**, matching OpenSCAD.
 - **Transforms act about the origin.** Centre a shape (\`center = true\`) before rotating it,
@@ -107,11 +107,11 @@ Three rules, each with its own error:
 
   syntax: `## Syntax
 
-**Comments** — \`// line\`, \`# line\`, \`/* block */\`. Block comments do not nest.
+**Comments** - \`// line\`, \`# line\`, \`/* block */\`. Block comments do not nest.
 
-**Numbers** — \`12\` \`0.5\` \`.5\` \`1e3\` \`2.5e-3\`. No hex, no separators, no unit suffix.
+**Numbers** - \`12\` \`0.5\` \`.5\` \`1e3\` \`2.5e-3\`. No hex, no separators, no unit suffix.
 
-**Strings** — double quotes only, no literal newline. Exactly six escapes: \`\\n\` \`\\t\` \`\\r\`
+**Strings** - double quotes only, no literal newline. Exactly six escapes: \`\\n\` \`\\t\` \`\\r\`
 \`\\"\` \`\\\\\` \`\\$\`. \`\${ expr }\` splices any expression in.
 
 **Identifiers** start with a letter or \`_\` and continue with letters, digits, \`_\` **or \`-\`**.
@@ -127,7 +127,7 @@ Three rules, each with its own error:
 is \`name = expression\`; anything else that is followed by a brace is a nested block. Setting
 the same attribute twice is an error.
 
-**The newline rule.** Outside brackets, **a line break ends an expression** — that is what
+**The newline rule.** Outside brackets, **a line break ends an expression** - that is what
 lets attributes be written one per line with no separators. Inside \`(...)\`, \`[...]\` or an
 argument list the rule is suspended, so break there to continue across lines:
 
@@ -138,7 +138,7 @@ local total = (
 )
 
 local b = base
-          + extra      // NOT a continuation — this is a parse error
+          + extra      // NOT a continuation - this is a parse error
 \`\`\`
 
 Trailing commas are allowed in lists, objects and argument lists.`,
@@ -156,7 +156,7 @@ Trailing commas are allowed in lists, objects and argument lists.`,
 
 There is no vector type: **a vector is a list of numbers**, and a block says how many
 components it wants. Where a block wants a vector, **a single number stands for every
-component** — \`scale { factor = 2 }\` is \`scale { factor = [2, 2, 2] }\`.
+component** - \`scale { factor = 2 }\` is \`scale { factor = [2, 2, 2] }\`.
 
 **Operators**, loosest first: \`?:\` · \`||\` · \`&&\` · \`== !=\` · \`< <= > >=\` · \`+ -\` ·
 \`* / %\` · prefix \`-x !x\` · postfix \`a.b a[i] f(x)\`.
@@ -174,21 +174,21 @@ errors**, not \`Infinity\`.
 
 \`<\` \`<=\` \`>\` \`>=\` need both sides to be the same type. \`==\` compares structurally.
 
-**Truthy / falsy** — falsy is \`false\`, \`0\`, \`""\`, \`[]\`, \`null\`. Everything else is truthy,
+**Truthy / falsy** - falsy is \`false\`, \`0\`, \`""\`, \`[]\`, \`null\`. Everything else is truthy,
 including \`{}\`.
 
-**Members** — \`.x\` \`.y\` \`.z\` read index 0, 1, 2 off a list, so \`size.z\` works on a
+**Members** - \`.x\` \`.y\` \`.z\` read index 0, 1, 2 off a list, so \`size.z\` works on a
 3-vector. \`a[i]\` indexes. \`var.NAME\` reads a param.`,
 
   scope: `## Scope and names
 
-- **\`var\` holds params only** — never locals. A local with the same name shadows the bare
+- **\`var\` holds params only** - never locals. A local with the same name shadows the bare
   name but \`var.NAME\` still means the param.
 - **Component params are read by their bare name.** There is no \`var.\` for them.
 - **A component body cannot see the call site.** It is evaluated in a fresh scope rooted at
   the document, so a \`local\` where it is called does not leak in. Document params and other
   components are in scope.
-- **A param default may use earlier params by their bare name**, but never \`var\` — \`var\` is
+- **A param default may use earlier params by their bare name**, but never \`var\` - \`var\` is
   assembled only after every param has resolved.
 - **Top-level locals are ordered**; locals inside a body are not, so a block may use a local
   written below it.
@@ -209,7 +209,7 @@ if cond { ... } else if other { ... } else { ... }
   backwards, so a loop can never spin forever.
 - There is no \`break\`, no \`continue\` and no accumulator. Filter the list instead.
 - A loop over an empty list produces nothing, which is an error where something was
-  required — guard it with \`if\`.
+  required - guard it with \`if\`.
 - For a *value* that depends on a condition, use \`cond ? a : b\`, not \`if\`.
 
 The radial-array idiom, which is most of what loops are for:
@@ -237,7 +237,7 @@ model "assembly" {
 \`\`\`
 
 - Declare parts **directly in a model**, or inside a \`for\`/\`if\` in one. A part nested inside
-  a transform or a boolean is **silently dropped** — no error, it is just gone.
+  a transform or a boolean is **silently dropped** - no error, it is just gone.
 - A part cannot contain another part, cannot be empty, and cannot come out of a component.
 - Geometry written outside any part becomes one default part named after the model.
 - The label is an expression: \`part "leg_\${i}"\`.
@@ -246,7 +246,7 @@ model "assembly" {
   pitfalls: `## The mistakes that cost the most time
 
 1. **Hyphens bind into names.** \`outer-inner\` is one identifier. Write \`outer - inner\`.
-2. **A misspelled attribute is an error, not a silent no-op** — \`box: unknown attribute
+2. **A misspelled attribute is an error, not a silent no-op** - \`box: unknown attribute
    "colour"\`. The one exception is a \`param\` block, which passes anything through.
 3. **A part inside a transform disappears** with no warning. Put the transform inside the
    part.
@@ -260,11 +260,11 @@ model "assembly" {
 9. **\`min\`/\`max\`/\`step\`/\`options\` on a param are advisory** and never enforced. Clamp in
    the model if the bound matters: \`local n = max(3, min(16, var.bolts))\`.
 10. **Empty geometry is silent.** \`extrude { height = 0 }\`, a \`difference\` that removes
-    everything and a backwards \`range\` all produce nothing rather than an error — and then
+    everything and a backwards \`range\` all produce nothing rather than an error - and then
     fail further out with \`model "m" produced no geometry\`.
 11. **A line break ends an expression** outside brackets. Continue inside \`(...)\` or end the
     line on an operator.
-12. **\`rotate\` spells its 2D and 3D attributes differently** — \`angle\` in 2D, \`x\`/\`y\`/\`z\`
+12. **\`rotate\` spells its 2D and 3D attributes differently** - \`angle\` in 2D, \`x\`/\`y\`/\`z\`
     or \`angles\` in 3D.`,
 
   workflow: `## How to write one of these
@@ -274,7 +274,7 @@ model "assembly" {
 2. **Write the profile, then give it thickness.** Most real parts are a 2D outline extruded
    or revolved. Modelling in 2D and converting once is shorter and more robust than
    composing solids.
-3. **Name repeated features as components** — including the *negative* of a feature. A
+3. **Name repeated features as components** - including the *negative* of a feature. A
    \`component "counterbore"\` subtracted in a loop reads far better than four inlined unions.
 4. **One \`part\` per physical piece**, each with a colour. It is what makes a render legible
    and what lets a single piece be exported.
@@ -307,7 +307,7 @@ export function guide(section) {
     return ['# The forma language, in brief', '', ...ORDER.map((name) => SECTIONS[name])].join('\n\n');
   }
   if (!SECTIONS[section]) {
-    throw new Error(`no guide section "${section}" — it is one of ${ORDER.join(', ')}`);
+    throw new Error(`no guide section "${section}" - it is one of ${ORDER.join(', ')}`);
   }
   return SECTIONS[section];
 }

package/src/reference/README.md

@@ -3,7 +3,7 @@
 `forma` is a declarative language for describing solids. A document is a list of top-level
 blocks; geometry is written by **nesting blocks**, where a block's children are its operands.
 The evaluator turns a document into a tree of immutable geometry nodes, and the
-[Manifold](https://github.com/elalish/manifold) CSG kernel — compiled to WebAssembly — solves
+[Manifold](https://github.com/elalish/manifold) CSG kernel - compiled to WebAssembly - solves
 that tree into meshes.
 
 ```hcl
@@ -28,8 +28,8 @@ model "riser" {
 ```
 
 This reference documents every construct in the language and every function the JavaScript
-package exports. For a tour of the project itself — how to run the editor, how to consume the
-library from Node — see the [top-level README](../../../README.md).
+package exports. For a tour of the project itself - how to run the editor, how to consume the
+library from Node - see the [top-level README](../../../README.md).
 
 ---
 
@@ -79,7 +79,7 @@ Leaf blocks. They take attributes and never contain other blocks.
 | [`cone`](reference/shapes-3d.md#cone) | 3D | A cone, or a truncated cone |
 | [`torus`](reference/shapes-3d.md#torus) | 3D | A ring, optionally a partial arc |
 
-2D shapes cannot be rendered on their own — [`extrude`](reference/conversions.md#extrude) or
+2D shapes cannot be rendered on their own - [`extrude`](reference/conversions.md#extrude) or
 [`revolve`](reference/conversions.md#revolve) them first.
 
 ---
@@ -149,5 +149,15 @@ the package root and typed by hand-written declarations.
 
 ## Errors
 
-[Every error message](errors.md), what raises it, and what to change — the language's errors
+[Every error message](errors.md), what raises it, and what to change - the language's errors
 in one place, grouped by the stage that raises them.
+
+---
+
+## Running it
+
+| Tool | What it is |
+| --- | --- |
+| [Command line](cli.md) | `forma render part.forma -o part.stl` - solving a document in a build, with no browser |
+| [Editor](https://kalpak44.github.io/forma-dsl/editor/) | The same kernel in a browser, with live previews and a control per declared param |
+| [MCP server](https://www.npmjs.com/package/forma-dsl-mcp) | The language as a tool an agent can write, with every document it produces solved before it answers |

package/src/reference/api/describe-parameters.md

@@ -15,7 +15,7 @@ const params = describeParameters(source);
 ### `describeParameters(source)`
 
 Parses `source` and returns one descriptor per top-level [`param`](../reference/param.md), in
-source order. No geometry is evaluated and no kernel is loaded — this is the call a front end
+source order. No geometry is evaluated and no kernel is loaded - this is the call a front end
 makes to build controls before it can have any values to render with.
 
 #### Parameters
@@ -51,7 +51,7 @@ makes to build controls before it can have any values to render with.
 - **`min`, `max`, `step` and `options` are advisory.** Nothing enforces them, including
   [`render`](render.md). Clamp in the model if a bound matters.
 - **Model params are not listed.** A `param` inside a `model` is a constant, not an input.
-- It still throws on a **syntax error** — the document has to parse.
+- It still throws on a **syntax error** - the document has to parse.
 
 #### Type inference
 
@@ -127,7 +127,7 @@ default, and a front end can act on that before rendering fails.
 
 ### Re-reading after an edit
 
-`describeParameters` is cheap — a parse, no kernel — so calling it on every edit is
+`describeParameters` is cheap - a parse, no kernel - so calling it on every edit is
 reasonable. Keep any value the user has already set, for a param that still exists with a
 compatible type:
 
@@ -147,7 +147,7 @@ function reconcile(source, previous) {
 
 ### A descriptor's `default` is `undefined`
 
-Either the param declares no default — check `required` — or its default could not be
+Either the param declares no default - check `required` - or its default could not be
 evaluated. A default that refers to a param declared **below** it cannot resolve; params are
 read in source order.