forma-dsl-mcp 0.1.5 → 0.2.2

package/README.md

@@ -5,93 +5,235 @@
 
 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
-writes `.forma` documents that render.
+builds it with the real geometry kernel, so a `.forma` document is measured before anyone is
+told it works.
 
-It speaks over stdio, so any MCP client can launch it:
+It carries the language with it: the guide, the block reference, the worked examples and the
+full manual are bundled, so a model learns the syntax from the server rather than guessing at
+it.
+
+It speaks over stdio, and there is nothing to configure.
+
+## Installing it
+
+**Claude Code**
+
+```bash
+claude mcp add forma -- npx -y forma-dsl-mcp
+```
+
+**Codex**
+
+```bash
+codex mcp add forma -- npx -y forma-dsl-mcp
+```
+
+or, in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.forma]
+command = "npx"
+args = ["-y", "forma-dsl-mcp"]
+```
+
+**Claude Desktop, and anything else that takes a JSON block**
 
 ```json
 {
   "mcpServers": {
     "forma": {
       "command": "npx",
-      "args": ["-y", "forma-dsl-mcp"],
-      "env": { "FORMA_MCP_ROOT": "/absolute/path/to/your/models" }
+      "args": ["-y", "forma-dsl-mcp"]
     }
   }
 }
 ```
 
-`FORMA_MCP_ROOT` is the only configuration. It defaults to the working directory the client
-launches the server in, and **every path the file tools accept is confined to it** — an
-absolute path, a `..` that climbs out, or a symlink pointing out of the tree is refused
-rather than followed.
+## Where the files go
+
+The server does not choose. It asks the client over MCP's
+[roots](https://modelcontextprotocol.io/specification/basic/roots) capability, and reads and
+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
+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.
+
+A client that does not implement roots gets the working directory it launched the server in,
+which is the one location it did choose. Codex can set that explicitly:
+
+```toml
+[mcp_servers.forma]
+command = "npx"
+args = ["-y", "forma-dsl-mcp"]
+cwd = "/absolute/path/to/your/models"
+```
 
 ## Why it is not just a prompt
 
 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**. `forma_check`
-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 question "is this the size that was asked for, and is it actually a solid?" is
-answered before anyone is told the work is done. A part that silently solved to nothing is
-called out by name.
-
-`forma_write` runs that same check and **refuses to write a document that does not render**.
+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
+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.
+
+`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 —
+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
+answer offline.
 
 Everything the server says about the language is answerable to the language. The block and
 function catalogue is merged with the library's own registries at load time, and the tests
-assert that the two agree: a block added, renamed or given a new dimensionality in
-`forma-dsl` fails this package's build rather than becoming a confident wrong answer. Every
-worked example is rendered by the test suite, at both ends of every parameter's declared
-range.
+assert the two agree: a block added, renamed or given a new dimensionality in `forma-dsl`
+fails this package's build rather than becoming a confident wrong answer. Every worked example
+is rendered by the test suite.
 
 ## Tools
 
+**Learning the language**
+
 | Tool | What it does |
 | --- | --- |
 | `forma_guide` | The language in one page: structure, nesting, dimensionality, units, syntax, the mistakes that cost the most time |
 | `forma_blocks` | Every block with its attributes, defaults, dimensionality and caveats |
 | `forma_functions` | Every builtin function and constant, with arity |
-| `forma_reference` | The full reference manual, searchable and readable page by page |
 | `forma_examples` | Complete documents that render, each showing one way of building a real part |
-| `forma_check` | Parse, build and **measure** — errors with a line, a column and an excerpt with a caret; parts with their boxes, volumes and triangle counts |
-| `forma_write` | Check, then write a `.forma` file into the workspace |
+| `forma_reference` | The full reference manual, searchable and readable page by page |
+
+**Building with it**
+
+| Tool | What it does |
+| --- | --- |
+| `forma_write` | Check, then write a `.forma` file |
 | `forma_read` | Read a document back, checked |
-| `forma_list` | Every `.forma` file under the root |
 | `forma_export_stl` | Render and write a binary STL |
 
-## Resources and prompts
+## Resources
 
-Resources carry the same knowledge in a form a person can attach by hand:
+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
 
-Two prompts name the workflows worth having a name for: `model_a_part`, which walks from a
-description of a physical object to a checked document, and `review_a_document`, which reads
-an existing one and looks for the failures that are silent.
+## 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
+
+> **codex** — Where should I put it?
+
+> **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_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
+comes back with every block that does, and a guess at an attribute with the ones that block
+reads:
+
+```
+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",
+  "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.
+
+| Part     | Colour  | Opacity | Size (X × Y × Z) | Volume    | Triangles | Genus |
+| `trunk`  | #6b4423 |       1 | 8 × 8 × 30       | 1004.682  |       108 |     0 |
+| `canopy` | #2f7d32 |       1 | 28 × 28 × 30     | 5193.4555 |       358 |     0 |
+
+Overall bounding box: 28 × 28 × 51 (min -14, -14, 0, max 14, 14, 51)
+Triangles: 466
+```
+
+`tree.forma`:
+
+```hcl
+param trunk_height { type = number  default = 30  min = 10  max = 60 }
+param canopy_layers { type = number  default = 3  min = 1  max = 6 }
+
+local canopy_base = trunk_height * 0.7
+
+model "tree" {
+  part "trunk" {
+    color = "#6b4423"
+    cone { radius = 4  top_radius = 2.5  height = var.trunk_height }
+  }
+
+  part "canopy" {
+    color = "#2f7d32"
+    for i in range(var.canopy_layers) {
+      translate {
+        offset = [0, 0, canopy_base + i * 8]
+        cone { radius = 14 - i * 3  top_radius = 0  height = 14 }
+      }
+    }
+  }
+}
+```
+
+The document above is a test in this repo rather than an illustration: `test/server.test.js`
+builds it, checks both parts came out solid, drives `trunk_height` to the top of its declared
+range, and exports it. The wrong guesses are asserted to name their own corrections.
+
+## More to ask for
+
+> Model a wall bracket that carries a 35 mm pipe 60 mm off the wall. Two M5 screw holes in
+> the backplate, 50 mm apart. Make the pipe diameter and the standoff params, and write it
+> to `bracket.forma`.
+
+> Write `enclosure.forma`: a 90 × 60 × 25 mm box with 2 mm walls, open at the top, with a lid
+> that drops in on a 0.3 mm clearance lip. Wall thickness and clearance are params. Give the
+> body and the lid separate parts so I can see them apart.
+
+> Read `bracket.forma` and re-check it at both ends of every param's declared range. Anything
+> that solves to nothing or changes the bounding box in a way the document did not intend,
+> tell me about before you change it.
+
+> Take `enclosure.forma`, set the wall thickness to 3 mm, and export just the lid to
+> `lid.stl`.
+
+Two things are worth asking for by name, because they are what the kernel is there to answer:
+the **bounding box**, to confirm the part is the size you meant, and the **genus**, to confirm
+a part that should be a plain solid has not ended up with a hole through it.
+
+## The bundled manual
+
+`src/reference/` is a copy of [`apps/docs/content`](../../apps/docs/content/README.md), which
+is a private workspace and cannot be depended on from something that ships to npm. The copy is
+what lets the server answer offline. It is made by `npm run sync:reference -w forma-dsl-mcp`
+and compared byte for byte against the original by the tests, so it cannot drift: edit the
+manual, re-run the sync, and the test passes again.
 
 ## Running it from source
 
 ```bash
 npm install
-npm test -w forma-dsl-mcp                  # 140+ tests, including the protocol end to end
+npm test -w forma-dsl-mcp                  # including the protocol end to end
 node packages/forma-dsl-mcp/src/bin.js     # the server, on stdio
 ```
 
 Point a client at `node /absolute/path/to/packages/forma-dsl-mcp/src/bin.js` to use the
 working tree rather than the published package.
 
-## The bundled manual
-
-`src/reference/` is a copy of [`apps/docs/content`](../../apps/docs/content/README.md), which
-is a private workspace and cannot be depended on from something that ships to npm. The copy
-is what lets the server answer offline. It is made by `npm run sync:reference -w
-forma-dsl-mcp` and compared byte for byte against the original by the tests, so it cannot
-drift: edit the manual, re-run the sync, and the test passes again.
-
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forma-dsl-mcp",
-  "version": "0.1.5",
+  "version": "0.2.2",
   "description": "A stdio MCP server that knows the forma DSL and writes .forma documents that render.",
   "keywords": [
     "mcp",
@@ -13,7 +13,7 @@
     "parametric",
     "stl"
   ],
-  "homepage": "https://github.com/kalpak44/forma-dsl/tree/main/packages/forma-dsl-mcp#readme",
+  "homepage": "https://kalpak44.github.io/forma-dsl/",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kalpak44/forma-dsl.git",
@@ -41,12 +41,12 @@
   "scripts": {
     "start": "node src/bin.js",
     "test": "node --test",
-    "sync:reference": "node scripts/sync-reference.mjs",
-    "check:package": "node scripts/check-package.mjs"
+    "check:package": "node scripts/check-package.mjs",
+    "sync:reference": "node scripts/sync-reference.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.31.0",
-    "forma-dsl": "^0.1.5",
+    "forma-dsl": "^0.2.2",
     "zod": "^4.1.13"
   }
 }

package/src/bin.js

@@ -5,25 +5,29 @@
  * 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.
+ *
+ * There is nothing to configure here. Where the file tools may read and write is asked of
+ * the client over MCP's `roots` capability once it has connected, so the directories are
+ * the client's to choose and to change.
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-import { Workspace } from './workspace.js';
 import { VERSION, createServer } from './server.js';
-
-/**
- * Where the file tools are allowed to read and write.
- *
- * Defaults to the working directory, which is what a client that launches the server inside
- * a project gives it. `FORMA_MCP_ROOT` overrides it.
- */
-const root = process.env.FORMA_MCP_ROOT ?? process.cwd();
+import { askClientForRoots } from './roots.js';
 
 try {
-  const workspace = await Workspace.open(root);
-  const server = createServer(workspace);
+  const server = createServer();
+
+  // Logged for the operator's benefit, not the protocol's: a server writing somewhere
+  // unexpected is the failure worth being able to see in the client's log.
+  server.server.oninitialized = () => {
+    askClientForRoots(server.server)
+      .then((roots) => console.error(`forma-dsl-mcp: working in ${roots.join(', ')}`))
+      .catch(() => {});
+  };
+
   await server.connect(new StdioServerTransport());
-  console.error(`forma-dsl-mcp ${VERSION} ready — workspace ${workspace.root}`);
+  console.error(`forma-dsl-mcp ${VERSION} ready`);
 } catch (error) {
   console.error(`forma-dsl-mcp failed to start: ${error?.message ?? error}`);
   process.exit(1);

package/src/reference/errors.md

@@ -135,11 +135,11 @@ Raised while building geometry.
 
 | Message | Cause |
 | --- | --- |
-| `unknown block "bloop"` | Not a builtin and not a declared component. Check the spelling against the [block list](README.md#shapes) |
+| `unknown block "bloop" — the blocks are …` | Not a builtin and not a declared component. The message lists every block there is, this document's own components first |
 | `"box" does not take a label` | Only [`part`](reference/part.md) takes a meaningful label |
 | `"box" is a shape and cannot contain other blocks` | A shape is a leaf. Usually a missing `}` swallowed the next block |
 | `"translate" needs at least one shape inside it` | An operation with nothing to act on |
-| `box: unknown attribute "colour"` | Every block rejects attributes it did not read, so a typo fails loudly |
+| `box: unknown attribute "colour" — box reads …` | Every block rejects attributes it did not read, so a typo fails loudly, and names what it would have read |
 | `attribute "size" is set twice` | The same attribute written twice in one block |
 | `box: "size" must be a number or an array of 3 numbers` | Wrong shape of value |
 | `circle: "radius" must be a finite number` | A `NaN` or `Infinity` reached the block |
@@ -149,13 +149,19 @@ Raised while building geometry.
 | `cylinder: give "radius"/"diameter", or both "bottom_radius" and "top_radius"` | One end radius on its own is ambiguous |
 | `offset: "join" must be one of "Square", "Round", "Miter"` | An enum attribute with an unrecognised value |
 
-### `box: unknown attribute "colour"`
+### `box: unknown attribute "colour" — box reads "center", "size"`
 
 Worth dwelling on, because it is the error that saves the most time. A misspelled attribute
 would otherwise be silent, and the model would render subtly wrong with nothing to point at.
 The one exception is a [`param`](reference/param.md) block, which is metadata and passes
 anything through.
 
+Both this and `unknown block` carry the alternatives, because the reader is often a program
+with no copy of this manual: an error that says only what is wrong leaves it guessing at
+spellings. A block that branches on which of two spellings it was given — `radius` against
+`diameter` — reads only one of them, so the list is what that call would accept rather than
+always the whole set.
+
 ---
 
 ## Dimensionality

package/src/reference.js

@@ -68,17 +68,19 @@ const BY_PATH = new Map(PAGES.map((page) => [page.path, page]));
  * @returns {Promise<string[]>} Paths relative to the manual's root, sorted.
  */
 export async function discoverPages() {
-  /** @type {string[]} */
-  const found = [];
+  // Subdirectories are independent of each other, so they are walked together rather than
+  // one after the next; the sort at the end is what makes the result order-stable regardless.
   const walk = async (directory) => {
-    for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const found = await Promise.all(entries.map(async (entry) => {
       const child = join(directory, entry.name);
-      if (entry.isDirectory()) await walk(child);
-      else if (entry.name.endsWith('.md')) found.push(relative(ROOT, child));
-    }
+      if (entry.isDirectory()) return walk(child);
+      return entry.name.endsWith('.md') ? [relative(ROOT, child)] : [];
+    }));
+    return found.flat();
   };
-  await walk(ROOT);
-  return found.sort((a, b) => a.localeCompare(b));
+
+  return (await walk(ROOT)).sort((a, b) => a.localeCompare(b));
 }
 
 /**
@@ -130,8 +132,13 @@ export async function searchReference(query, limit = 6) {
   /** @type {Array<{ score: number, path: string, title: string, heading: string, snippet: string }>} */
   const hits = [];
 
-  for (const page of PAGES) {
-    const markdown = await readFile(join(ROOT, page.path), 'utf8');
+  // Every page is read on every search, so the reads are independent work and belong
+  // together: awaiting them one at a time made a search wait on 28 round trips for nothing.
+  const pages = await Promise.all(
+    PAGES.map(async (page) => ({ page, markdown: await readFile(join(ROOT, page.path), 'utf8') })),
+  );
+
+  for (const { page, markdown } of pages) {
     const lower = markdown.toLowerCase();
     if (!terms.every((term) => lower.includes(term))) continue;
 

package/src/roots.js

@@ -0,0 +1,81 @@
+/**
+ * Where the client says the files may go.
+ *
+ * The server does not get to choose the patch of disk it writes to. The MCP `roots`
+ * capability is the client's declaration of which directories it is handing over, and asking
+ * for it — rather than reading an environment variable the client cannot see — is the whole
+ * of this module. A client that declares nothing gets the directory it launched the server
+ * in, which is the one location it did choose.
+ */
+import { fileURLToPath } from 'node:url';
+
+import { RootsListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { Workspace } from './workspace.js';
+
+/**
+ * The part of the low-level server this module needs.
+ *
+ * Named structurally rather than as the SDK's `Server`, which is deprecated in favour of
+ * `McpServer` — but `McpServer` does not carry `listRoots` or `setNotificationHandler`, so the
+ * low-level object is genuinely the right one to take. Describing the three members used is
+ * both the honest contract and what lets a test hand this a stub.
+ *
+ * @typedef {object} RootsClient
+ * @property {() => ({ roots?: object } | undefined)} getClientCapabilities What the client
+ *   declared at initialisation.
+ * @property {() => Promise<{ roots?: Array<{ uri?: string }> }>} listRoots Asks it for them.
+ * @property {(schema: object, handler: () => unknown) => void} setNotificationHandler
+ *   Registers interest in a notification it may send.
+ */
+
+/**
+ * Asks the client which directories the server may work in.
+ *
+ * Every failure funnels to the launch directory rather than to an error: a client that does
+ * not implement roots is the common case, not a broken one, and a server that refuses to
+ * work with such a client is worse than one that writes where it was started.
+ *
+ * @param {RootsClient} server The low-level server, once a client is connected.
+ * @returns {Promise<string[]>} Absolute directories, in the order the client gave them.
+ */
+export async function askClientForRoots(server) {
+  if (!server.getClientCapabilities()?.roots) return [process.cwd()];
+
+  /** @type {{ roots?: Array<{ uri: string }> }} */
+  let result;
+  try {
+    result = await server.listRoots();
+  } catch (error) {
+    const why = /** @type {Error} */ (error)?.message ?? String(error);
+    console.error(`forma-dsl-mcp: the client would not list its roots (${why})`);
+    return [process.cwd()];
+  }
+
+  // Roots are URIs, and the spec allows schemes this server cannot write to. Anything that
+  // is not a local file is dropped rather than guessed at.
+  const directories = (result?.roots ?? [])
+    .map((root) => root?.uri)
+    .filter((uri) => typeof uri === 'string' && uri.startsWith('file://'))
+    .map((uri) => fileURLToPath(uri));
+
+  return directories.length ? directories : [process.cwd()];
+}
+
+/**
+ * A workspace that takes its roots from the connected client, and re-reads them when the
+ * client says they have changed.
+ *
+ * The roots are asked for lazily, at the first file tool call, because `roots/list` is a
+ * request back to the client and there is no client to ask until initialisation is done.
+ *
+ * @param {RootsClient} server The low-level server the client connects to.
+ * @returns {Workspace} The workspace, with nothing resolved yet.
+ */
+export function clientWorkspace(server) {
+  const workspace = new Workspace(() => askClientForRoots(server));
+  server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+    workspace.forget();
+  });
+  return workspace;
+}

package/src/server.js

@@ -4,20 +4,35 @@
  * Tools are the part a model calls; resources are the part a client can attach to a
  * conversation by hand, and carry the same knowledge in a form a person can browse. Both
  * read from the same modules, so there is one description of the language here, not two.
+ *
+ * The knowledge is bundled rather than left to the error messages. A refusal names the
+ * alternatives, which is enough to correct a misspelling and not enough to learn a language:
+ * it teaches the name of a block and nothing about what that block means, what it takes, or
+ * which of its attributes interact. A caller with no manual can find `cone` from `frustum`
+ * that way; it cannot find `revolve` at all.
  */
 /** @import { Workspace } from './workspace.js' */
 
+import { createRequire } from 'node:module';
+
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { z } from 'zod';
 
 import { CONSTRUCTS, LANGUAGE_CONSTANTS, LANGUAGE_FUNCTIONS } from './catalogue.js';
 import { EXAMPLES, EXAMPLES_BY_NAME } from './examples.js';
 import { PAGES, readPage } from './reference.js';
+import { clientWorkspace } from './roots.js';
 import { guide } from './guide.js';
 import { registerTools } from './tools.js';
 
-/** The package's own version, reported in the handshake. */
-export const VERSION = '0.1.0';
+/**
+ * The package's own version, reported in the handshake.
+ *
+ * Read from the manifest rather than written out here, because the two drifted the moment
+ * they were allowed to: a client was told 0.1.0 by a server published as 0.1.5, and nothing
+ * in the release could notice. `files` ships `src/` and npm always ships the manifest, so
+ * this resolves in the published package as well as in the tree.
+ */
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
 
 /**
  * What the server tells a client it is for, offered as instructions during initialisation.
@@ -25,34 +40,42 @@ export const VERSION = '0.1.0';
  * Clients put this in front of the model before it has called anything, so it is the one
  * place to say the thing that changes behaviour most: check before you claim it works.
  */
-const INSTRUCTIONS = `This server knows forma, a declarative DSL for 3D solids, and can write
-and solve .forma documents.
+const INSTRUCTIONS = `This server knows forma, a declarative DSL for 3D solids, builds it with
+the real geometry kernel, and writes the documents it builds.
 
 Start with \`forma_guide\` — it is the language in one page. Use \`forma_blocks\` for the
 attributes of the blocks you are about to write, \`forma_examples\` for a working document of
 a similar shape, and \`forma_reference\` when you need the manual.
 
-Never hand a .forma document to anyone without running \`forma_check\` on it first. The check
-builds the geometry with the real kernel and reports the bounding box, the volume and the
-triangle count of every part, which is the only way to know that the model is the size that
-was asked for and has not silently solved to nothing. Write files with \`forma_write\`, which
-runs the same check and refuses a document that does not render.`;
+Never hand a .forma document to anyone without writing it through \`forma_write\`. It compiles
+the document, solves it and reports the bounding box, the volume and the triangle count of
+every part, which is the only way to know that the model is the size that was asked for and
+has not silently solved to nothing. A document that does not build is refused rather than
+written. Read one back with \`forma_read\`, and export a solid with \`forma_export_stl\`.
+
+Where those files go is the client's decision, not the server's: the tools read and write
+inside the directories the client declares as MCP roots, and a path is taken relative to the
+first of them. Every write reports the directory it landed in.`;
 
 /**
- * Builds the server, with every tool, resource and prompt registered.
+ * Builds the server, with every tool and resource registered.
  *
- * @param {Workspace} workspace The patch of filesystem the file tools may touch.
+ * The workspace is optional, and left out is the normal case: the server then takes its
+ * directories from whatever the connected client declares as its roots, which is the point —
+ * the client knows where the user's files belong and the server does not.
+ *
+ * @param {Workspace} [workspace] The patch of filesystem the tools may touch. Omitted, the
+ *   client's roots are used.
  * @returns {McpServer} The server, not yet connected to a transport.
  */
 export function createServer(workspace) {
   const server = new McpServer(
     { name: 'forma-dsl', version: VERSION },
-    { capabilities: { tools: {}, resources: {}, prompts: {} }, instructions: INSTRUCTIONS },
+    { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS },
   );
 
-  registerTools(server, workspace);
+  registerTools(server, workspace ?? clientWorkspace(server.server));
   registerResources(server);
-  registerPrompts(server);
 
   return server;
 }
@@ -136,84 +159,3 @@ function registerResources(server) {
   );
 }
 
-/**
- * Registers the prompts, which are the workflows worth having a name for.
- *
- * @param {McpServer} server The server.
- * @returns {void}
- */
-function registerPrompts(server) {
-  server.registerPrompt('model_a_part', {
-    title: 'Model a part in forma',
-    description: 'Walks from a description of a physical object to a checked .forma document.',
-    argsSchema: {
-      part: z.string().describe('What to model, e.g. "a wall bracket for a 35 mm pipe".'),
-      constraints: z.string().optional()
-        .describe('Dimensions, tolerances, print constraints — anything the result has to satisfy.'),
-      path: z.string().optional().describe('Where to write the finished document.'),
-    },
-  }, ({ part, constraints, path }) => ({
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: [
-          `Model this in forma: ${part}.`,
-          constraints ? `\nIt has to satisfy: ${constraints}` : '',
-          '',
-          'Work in this order:',
-          '1. Call `forma_guide` if you have not already read it this session.',
-          '2. Call `forma_examples` and read the one closest to what this is.',
-          '3. Decide what is a `param` (anything a person would reasonably change, with a '
-          + 'default, a min and a max) and what is a `local` (anything derived from those).',
-          '4. Write the document. Prefer a 2D profile given thickness by `extrude` or '
-          + '`revolve` over composing solids. Name any repeated feature — including the '
-          + 'negative of one — as a `component`. Give each physical piece its own `part` with '
-          + 'a colour.',
-          '5. Call `forma_check` with `solve: true`. Read the bounding box and the volume back '
-          + 'and confirm they are what was asked for. A part with zero volume means the model '
-          + 'silently produced nothing — fix it, do not report it as done.',
-          '6. Iterate until it renders and measures correctly.',
-          path
-            ? `7. Write it to \`${path}\` with \`forma_write\`.`
-            : '7. Offer to write it with `forma_write` once it checks out.',
-          '',
-          'Report the finished document along with its measured size, and say which params '
-          + 'drive which dimension.',
-        ].filter(Boolean).join('\n'),
-      },
-    }],
-  }));
-
-  server.registerPrompt('review_a_document', {
-    title: 'Review a .forma document',
-    description: 'Checks an existing document and reports what is wrong or fragile about it.',
-    argsSchema: { path: z.string().describe('The document to review.') },
-  }, ({ path }) => ({
-    messages: [{
-      role: 'user',
-      content: {
-        type: 'text',
-        text: [
-          `Review the forma document at \`${path}\`.`,
-          '',
-          'Call `forma_read` on it, then look for:',
-          '- parts that solved to nothing, or a bounding box that is not what the document '
-          + 'seems to intend;',
-          '- a `part` nested inside a transform or a boolean, which is silently dropped;',
-          '- a `difference` whose cutter ends exactly on a face, leaving a zero-thickness skin;',
-          '- dimensions written as bare numbers where a `param` or a `local` would say what '
-          + 'they mean;',
-          '- a `param` whose `min`/`max` the model does not actually clamp, since those bounds '
-          + 'are advisory and never enforced;',
-          '- geometry that would not print: unsupported overhangs, walls thinner than a nozzle, '
-          + 'a non-zero genus where a solid was meant.',
-          '',
-          'Re-check with different param values at the ends of their declared ranges — a model '
-          + 'that only works at its defaults is the common failure. Report what you found, and '
-          + 'propose the smallest edit that fixes each one.',
-        ].join('\n'),
-      },
-    }],
-  }));
-}

package/src/tools.js

@@ -1,5 +1,5 @@
 /**
- * The tools the server offers, and how their results are worded.
+ * The three tools the server offers, and how their results are worded.
  *
  * Results are Markdown rather than JSON on purpose. Everything here is read by a language
  * model deciding what to write next, and a bounding box in a table is acted on where the
@@ -34,7 +34,7 @@ const say = (text, isError = false) => ({
  *
  * A thrown error becomes a protocol-level failure, which most clients surface as "the tool
  * broke" rather than as something the model can correct. A refusal it can read — a path
- * outside the root, a part that does not exist — belongs in the result instead.
+ * outside the roots, a part that does not exist — belongs in the result instead.
  *
  * @param {() => Promise<object>} handler What to run.
  * @returns {Promise<object>} Its result, or the failure as text.
@@ -189,40 +189,30 @@ export function formatReport(report) {
   lines.push(...parameterLines(report.parameters));
 
   if (report.scene) lines.push(...sceneLines(report.scene, report.stats));
-  else if (report.ok) lines.push('_Parsed only — pass `solve: true` to build the geometry and measure it._');
 
   return lines.join('\n');
 }
 
 /**
- * Resolves the `source`-or-`path` pair every document-taking tool accepts.
+ * Resolves the `source`-or-`path` pair the export tool accepts.
  *
  * @param {Workspace} workspace Where a path is resolved.
  * @param {{ source?: string, path?: string }} args What the caller gave.
- * @returns {Promise<{ source: string, from: string }>} The document, and where it came from.
+ * @returns {Promise<string>} The document.
  * @throws {Error} If neither or both were given.
  */
 async function documentFrom(workspace, { source, path }) {
   if (source && path) throw new Error('give either "source" or "path", not both');
-  if (source) return { source, from: 'the supplied source' };
-  if (path) return { source: await workspace.read(path), from: `\`${path}\`` };
-  throw new Error('give either "source" — the document itself — or "path" to one in the workspace');
+  if (source) return source;
+  if (path) return workspace.read(path);
+  throw new Error('give either "source" — the document itself — or "path" to one already written');
 }
 
-/** The arguments shared by every tool that takes a document and may render it. */
-const DOCUMENT_ARGS = {
-  source: z.string().optional().describe('The .forma document itself.'),
-  path: z.string().optional().describe('A .forma file in the workspace, instead of `source`.'),
-  model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
-  params: z.record(z.string(), z.any()).optional()
-    .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
-};
-
 /**
  * Registers every tool on a server.
  *
  * @param {McpServer} server The server.
- * @param {Workspace} workspace The patch of filesystem the file tools may touch.
+ * @param {Workspace} workspace The patch of filesystem the tools may touch.
  * @returns {void}
  */
 export function registerTools(server, workspace) {
@@ -393,48 +383,25 @@ export function registerTools(server, workspace) {
     ].join('\n'));
   }));
 
-  // --- writing and checking ----------------------------------------------------------------
-
-  server.registerTool('forma_check', {
-    title: 'Check and measure a document',
-    description:
-      'Parses a .forma document and, unless told not to, builds one of its models with the '
-      + 'real geometry kernel. Reports any error with the line, the column and an excerpt with '
-      + 'a caret on it, and reports a successful build as a table of parts with their bounding '
-      + 'boxes, volumes, triangle counts and genus. This is how you find out whether what you '
-      + 'wrote is the size you meant, is watertight, and is not silently empty. Use it after '
-      + 'every edit.',
-    inputSchema: {
-      ...DOCUMENT_ARGS,
-      solve: z.boolean().optional()
-        .describe('Run the geometry kernel. Default true; false parses only, which is faster while drafting.'),
-    },
-    annotations: { readOnlyHint: true, openWorldHint: false },
-  }, async (args) => attempt(async () => {
-    const { source, from } = await documentFrom(workspace, args);
-    const report = await checkDocument(source, {
-      model: args.model ?? null,
-      params: args.params ?? {},
-      solve: args.solve ?? true,
-    });
-    return {
-      content: [{ type: /** @type {'text'} */ ('text'), text: `${formatReport(report)}\n\n_Checked ${from}._` }],
-      ...(report.ok ? {} : { isError: false }),
-    };
-  }));
+  // --- writing and building ----------------------------------------------------------------
 
   server.registerTool('forma_write', {
-    title: 'Write a .forma file',
+    title: 'Check, then write a .forma file',
     description:
-      'Checks a document and writes it into the workspace. The check runs first and a document '
-      + 'that does not render is refused, so a file on disk is one that works — pass '
-      + '`force: true` to write it anyway. Refuses to replace an existing file unless '
-      + '`overwrite` is set.',
+      'Builds a .forma document with the real geometry kernel and, if it renders, writes it. '
+      + 'The result is the measurement: a table of every part with its bounding box, volume, '
+      + 'triangle count and genus, or the error with the line, the column and an excerpt with '
+      + 'a caret on it. This is how you find out whether what you wrote is the size you meant, '
+      + 'is watertight, and is not silently empty. A document that does not render is refused '
+      + 'and nothing is written — pass `force: true` to write it anyway. Refuses to replace an '
+      + 'existing file unless `overwrite` is set.',
     inputSchema: {
-      path: z.string().describe('Where to write, relative to the workspace root. Must end in .forma.'),
+      path: z.string()
+        .describe('Where to write, relative to the first directory the client declared as a root. Must end in .forma.'),
       source: z.string().describe('The document.'),
-      model: z.string().optional().describe('Which model to check. Defaults to the first one.'),
-      params: z.record(z.string(), z.any()).optional().describe('Param values to check with.'),
+      model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
+      params: z.record(z.string(), z.any()).optional()
+        .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
       overwrite: z.boolean().optional().describe('Replace the file if it already exists. Default false.'),
       force: z.boolean().optional().describe('Write even if the document does not render. Default false.'),
     },
@@ -452,19 +419,23 @@ export function registerTools(server, workspace) {
 
     const written = await workspace.write(path, source, { overwrite, extension: '.forma' });
     return say([
-      `Wrote \`${written.relative}\` — ${written.bytes} bytes${written.replaced ? ', replacing what was there' : ''}.`,
+      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes`
+      + `${written.replaced ? ', replacing what was there' : ''}.`,
       '',
       formatReport(report),
     ].join('\n'));
   }));
 
   server.registerTool('forma_read', {
-    title: 'Read a .forma file',
-    description: 'Reads a document from the workspace and checks it, so you see the source and '
-      + 'its current state together.',
+    title: 'Read a document back',
+    description:
+      'Reads a .forma file the client has given access to and builds it, so you see the source '
+      + 'and its current measurements together. Use it before editing something you did not '
+      + 'write in this session.',
     inputSchema: {
-      path: z.string().describe('The file, relative to the workspace root.'),
-      solve: z.boolean().optional().describe('Run the geometry kernel. Default true.'),
+      path: z.string().describe('The file, relative to the first directory the client declared as a root.'),
+      solve: z.boolean().optional()
+        .describe('Run the geometry kernel. Default true; false parses only, which is faster.'),
     },
     annotations: { readOnlyHint: true, openWorldHint: false },
   }, async ({ path, solve }) => attempt(async () => {
@@ -473,39 +444,28 @@ export function registerTools(server, workspace) {
     return say(['```hcl', source.trimEnd(), '```', '', formatReport(report)].join('\n'));
   }));
 
-  server.registerTool('forma_list', {
-    title: 'List the .forma files in the workspace',
-    description: 'Every .forma document under the workspace root, so you can find what is '
-      + 'already here instead of guessing at names.',
-    inputSchema: {},
-    annotations: { readOnlyHint: true, openWorldHint: false },
-  }, async () => attempt(async () => {
-    const files = await workspace.list('.forma');
-    if (!files.length) return say(`No .forma files under ${workspace.root}.`);
-    const plural = files.length > 1 ? 's' : '';
-    return say([
-      `# ${files.length} document${plural} under ${workspace.root}`,
-      '',
-      ...files.map((file) => `- \`${file}\``),
-    ].join('\n'));
-  }));
-
   server.registerTool('forma_export_stl', {
-    title: 'Export a model as binary STL',
+    title: 'Render and write a binary STL',
     description:
-      'Renders a document and writes one part — or every part unioned — as a binary STL into '
-      + 'the workspace. Lengths are unitless in forma and STL has no unit either; every '
-      + 'consumer treats them as millimetres.',
+      'Renders a document and writes one part — or every part unioned — as a binary STL. '
+      + 'Lengths are unitless in forma and STL has no unit either; every consumer treats them '
+      + 'as millimetres.',
     inputSchema: {
-      ...DOCUMENT_ARGS,
-      out: z.string().describe('Where to write, relative to the workspace root. Must end in .stl.'),
+      source: z.string().optional().describe('The .forma document itself.'),
+      path: z.string().optional()
+        .describe('A .forma file the client has given access to, instead of `source`.'),
+      model: z.string().optional().describe('Which model to build. Defaults to the first one declared.'),
+      params: z.record(z.string(), z.any()).optional()
+        .describe('Values for the document\'s params, by name. Anything not given uses its default.'),
+      out: z.string()
+        .describe('Where to write, relative to the first directory the client declared as a root. Must end in .stl.'),
       part: z.string().optional()
         .describe('One part by name. Omitted, a single-part model exports that part and a multi-part model exports them unioned.'),
       overwrite: z.boolean().optional().describe('Replace the file if it already exists. Default false.'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   }, async (args) => attempt(async () => {
-    const { source } = await documentFrom(workspace, args);
+    const source = await documentFrom(workspace, args);
     const result = await exportStl(source, {
       model: args.model ?? null,
       params: args.params ?? {},
@@ -516,8 +476,8 @@ export function registerTools(server, workspace) {
       extension: '.stl',
     });
     return say(
-      `Wrote \`${written.relative}\` — ${written.bytes} bytes, ${result.triangles} triangles, `
-      + `from model \`${result.model}\`, part \`${result.part}\`.`,
+      `Wrote \`${written.relative}\` under \`${written.root}\` — ${written.bytes} bytes, `
+      + `${result.triangles} triangles, from model \`${result.model}\`, part \`${result.part}\`.`,
     );
   }));
 }

package/src/workspace.js

@@ -2,19 +2,25 @@
  * The patch of filesystem the server is allowed to touch.
  *
  * An MCP server writes files on behalf of a model, so the set of paths it will accept is a
- * security boundary rather than a convenience. Everything goes through `resolve`, which
- * refuses anything that lands outside the root — including by way of `..`, an absolute path,
- * or a symlink pointing out of the tree.
+ * security boundary rather than a convenience. Which directories make up that set is the
+ * client's decision — it declares them as MCP roots, and {@link Workspace} only asks. What
+ * the workspace enforces is that everything goes through `resolve`, which refuses anything
+ * landing outside all of them, including by way of `..`, an absolute path, or a symlink
+ * pointing out of the tree.
  */
-import { mkdir, readdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, realpath, stat, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 
-/** How deep `list` will descend before it stops looking. */
-const MAX_DEPTH = 8;
-
-/** Directories that are never worth walking, and are large enough to be worth skipping. */
-const SKIPPED = new Set(['node_modules', '.git', 'dist', 'coverage', '.cache']);
+/**
+ * What one path segment inside a root may be.
+ *
+ * Nothing that separates, escapes or terminates: no slash either way, no NUL, and `..`
+ * is rejected alongside it. Every path handed to the filesystem is rebuilt from a root and
+ * segments that passed this, so the value that reaches `readFile` is constructed here rather
+ * than carried in from the caller.
+ */
+const SAFE_SEGMENT = /^[^\0/\\]+$/;
 
 /** Raised for a path the workspace refuses, so a handler can report it as the caller's fault. */
 export class WorkspaceError extends Error {
@@ -29,101 +35,231 @@ export class WorkspaceError extends Error {
 }
 
 /**
- * A rooted view of the filesystem.
+ * @typedef {object} Root
+ * @property {string} path The directory as the client named it, made absolute.
+ * @property {string} realPath The same directory with symlinks followed, which containment
+ *   is tested against.
+ */
+
+/**
+ * A view of the filesystem confined to the directories the client declared.
  *
- * The root is resolved through symlinks once, at construction, so a root that is itself a
- * link still compares equal to the paths resolved beneath it.
+ * The directories are asked for lazily and then cached, because the client cannot be asked
+ * until it has finished connecting, and because asking on every call would put a round trip
+ * in front of every file read. `forget` drops the cache when the client says they changed.
  */
 export class Workspace {
+  /** @type {() => Promise<string[]> | string[]} Where the directories come from. */
+  #supply;
+
+  /** @type {Root[] | null} The resolved roots, once they have been asked for. */
+  #roots = null;
+
   /**
-   * @param {string} root The directory every path is resolved against and confined to.
+   * @param {(() => Promise<string[]> | string[]) | string[] | string} supply The directories
+   *   to confine to, or something that produces them when asked.
    */
-  constructor(root) {
-    /** @type {string} The absolute root, before symlinks are followed. */
-    this.root = resolve(root);
-    /** @type {string} The root with symlinks resolved; the one containment is tested against. */
-    this.realRoot = this.root;
+  constructor(supply) {
+    this.#supply = typeof supply === 'function' ? supply : () => supply;
   }
 
   /**
-   * Resolves the root through symlinks.
+   * A workspace confined to one directory, checked now rather than at first use.
    *
-   * Separate from the constructor because it touches the disk, and a constructor that can
-   * fail on I/O is a constructor every caller has to wrap.
+   * Useful for embedding the server in something that already knows where the files live,
+   * and for tests, which want a bad root to fail where it is written.
    *
    * @param {string} root The directory to root the workspace at.
-   * @returns {Promise<Workspace>} The workspace, ready to use.
+   * @returns {Promise<Workspace>} The workspace, with its root already resolved.
    * @throws {WorkspaceError} If the root does not exist or is not a directory.
    */
   static async open(root) {
-    const workspace = new Workspace(root);
-    let info;
-    try {
-      workspace.realRoot = await realpath(workspace.root);
-      info = await stat(workspace.realRoot);
-    } catch {
-      throw new WorkspaceError(`the workspace root ${workspace.root} does not exist`);
+    const workspace = new Workspace([root]);
+    await workspace.roots();
+    return workspace;
+  }
+
+  /**
+   * The directories in force, resolved through symlinks.
+   *
+   * A root is resolved once and remembered, so a root that is itself a link still compares
+   * equal to the paths resolved beneath it. Roots that do not exist are dropped rather than
+   * fatal — a client may well declare a directory this server has no business in — and only
+   * an empty result is an error.
+   *
+   * @returns {Promise<Root[]>} The roots, in the order the client gave them.
+   * @throws {WorkspaceError} If not one of them is a usable directory.
+   */
+  async roots() {
+    if (this.#roots) return this.#roots;
+
+    const given = await this.#supply();
+    // Deduplicated before anything touches the disk, so a client that declares the same
+    // directory twice is one stat rather than two.
+    const wanted = [...new Set((Array.isArray(given) ? given : [given])
+      .filter((each) => typeof each === 'string' && each.trim() !== '')
+      .map((each) => resolve(each)))];
+
+    const examined = await Promise.all(wanted.map(async (path) => {
+      try {
+        const realPath = await realpath(path);
+        if (!(await stat(realPath)).isDirectory()) {
+          return { path, why: `${path} is not a directory` };
+        }
+        return { path, realPath };
+      } catch {
+        return { path, why: `${path} does not exist` };
+      }
+    }));
+
+    /** @type {Root[]} */
+    const roots = [];
+    /** @type {string[]} */
+    const refused = [];
+    for (const entry of examined) {
+      if (entry.why) refused.push(entry.why);
+      else roots.push({ path: entry.path, realPath: /** @type {string} */ (entry.realPath) });
     }
-    if (!info.isDirectory()) {
-      throw new WorkspaceError(`the workspace root ${workspace.root} is not a directory`);
+
+    if (!roots.length) {
+      throw new WorkspaceError(
+        refused.length
+          ? `no usable workspace root — ${refused.join('; ')}`
+          : 'the client has declared no workspace root, so there is nowhere to read or write; '
+            + 'declare one with the MCP roots capability',
+      );
     }
-    return workspace;
+
+    this.#roots = roots;
+    return roots;
   }
 
   /**
-   * Turns a caller's path into an absolute one inside the root.
+   * Drops the resolved roots, so the next call asks for them again.
+   *
+   * Called when the client sends `notifications/roots/list_changed`, which is the only way
+   * the set is allowed to move.
+   *
+   * @returns {void}
+   */
+  forget() {
+    this.#roots = null;
+  }
+
+  /**
+   * The root a relative path is taken against, which is the first the client declared.
+   *
+   * @returns {Promise<Root>} The primary root.
+   * @throws {WorkspaceError} If there is no usable root.
+   */
+  async primary() {
+    const [first] = await this.roots();
+    return first;
+  }
+
+  /**
+   * Turns a caller's path into an absolute one inside a root.
    *
    * Containment is checked twice: once on the lexical path, and again on the nearest
    * existing ancestor with symlinks followed. The first catches `../../etc/passwd`; the
-   * second catches a directory inside the root that is a link to somewhere outside it.
+   * second catches a directory inside a root that is a link to somewhere outside it.
    *
-   * @param {string} path A path relative to the root, or an absolute one inside it.
+   * @param {string} path A path relative to the primary root, or an absolute one inside any
+   *   of them.
    * @param {string} [what] What the path is for, used in the error message.
-   * @returns {Promise<string>} The absolute path.
-   * @throws {WorkspaceError} If the path escapes the root.
+   * @returns {Promise<{ absolute: string, root: Root }>} The path, and the root holding it.
+   * @throws {WorkspaceError} If the path escapes every root.
    */
   async resolve(path, what = 'path') {
     if (typeof path !== 'string' || path.trim() === '') {
       throw new WorkspaceError(`the ${what} is empty`);
     }
 
-    const absolute = isAbsolute(path) ? resolve(path) : resolve(this.root, path);
-    this.#assertInside(absolute, path, what);
+    const roots = await this.roots();
+    const lexical = isAbsolute(path) ? resolve(path) : resolve(roots[0].path, path);
+
+    const root = this.#holderOf(roots, lexical);
+    if (!root) throw this.#outside(roots, path, what);
+
+    // Rebuilt before anything touches the disk, which is the order that matters: the string
+    // the caller gave is used to choose segments and never to name a file. Each segment has
+    // to match SAFE_SEGMENT, and what comes out is assembled onto a directory the client
+    // declared. Every line below, and every caller, works with that value rather than the one
+    // that came in — so the walk beneath cannot be steered by a name this never approved.
+    const base = this.#baseOf(root, lexical);
+    const segments = relative(base, lexical).split(sep).filter(Boolean);
+    if (!segments.every((segment) => SAFE_SEGMENT.test(segment))) {
+      throw this.#outside(roots, path, what);
+    }
+    const absolute = segments.reduce((at, segment) => join(at, segment), base);
 
     // The file itself may not exist yet — a write is the common case — so the deepest
-    // ancestor that does exist is what gets its links followed.
+    // ancestor that does exist is what gets its links followed. This is the one check that
+    // cannot be made without the filesystem: whether a directory inside a root is a link out
+    // of it is not answerable from the path alone.
     let existing = absolute;
     while (!existsSync(existing) && dirname(existing) !== existing) existing = dirname(existing);
     const real = await realpath(existing);
-    this.#assertInside(join(real, relative(existing, absolute)), path, what);
+    if (!this.#holderOf(roots, join(real, relative(existing, absolute)))) {
+      throw this.#outside(roots, path, what);
+    }
 
-    return absolute;
+    return { absolute, root };
   }
 
   /**
+   * Which spelling of a root a path sits under — the one the client gave, or the one symlinks
+   * resolve it to.
+   *
+   * @param {Root} root The root holding it.
+   * @param {string} absolute The path.
+   * @returns {string} The prefix to measure against.
+   */
+  #baseOf(root, absolute) {
+    return absolute === root.path || absolute.startsWith(root.path + sep) ? root.path : root.realPath;
+  }
+
+  /**
+   * @param {Root[]} roots The roots to test against.
    * @param {string} candidate An absolute path.
+   * @returns {Root | null} The root that holds it, or null if none does.
+   */
+  #holderOf(roots, candidate) {
+    return roots.find(({ path, realPath }) => [path, realPath].some(
+      (root) => candidate === root || candidate.startsWith(root + sep),
+    )) ?? null;
+  }
+
+  /**
+   * @param {Root[]} roots The roots the path missed.
    * @param {string} original The path as the caller wrote it, for the message.
    * @param {string} what What the path is for.
-   * @returns {void}
-   * @throws {WorkspaceError} If the candidate is neither the root nor beneath it.
+   * @returns {WorkspaceError} The refusal, ready to throw.
    */
-  #assertInside(candidate, original, what) {
-    const roots = [this.root, this.realRoot];
-    const inside = roots.some((root) => candidate === root || candidate.startsWith(root + sep));
-    if (!inside) {
-      throw new WorkspaceError(
-        `the ${what} "${original}" is outside the workspace root ${this.root}`,
-      );
-    }
+  #outside(roots, original, what) {
+    const named = roots.map((root) => root.path).join(', ');
+    const noun = roots.length > 1 ? 'roots' : 'root';
+    return new WorkspaceError(
+      `the ${what} "${original}" is outside the workspace ${noun} ${named}`,
+    );
+  }
+
+  /**
+   * @param {Root} root The root the path was resolved against.
+   * @param {string} absolute The path.
+   * @returns {string} The path within the root.
+   */
+  #within(root, absolute) {
+    return relative(this.#baseOf(root, absolute), absolute) || '.';
   }
 
   /**
    * @param {string} path The file to read.
    * @returns {Promise<string>} Its contents, as UTF-8.
-   * @throws {WorkspaceError} If the path escapes the root or names no file.
+   * @throws {WorkspaceError} If the path escapes the roots or names no file.
    */
   async read(path) {
-    const absolute = await this.resolve(path, 'path');
+    const { absolute } = await this.resolve(path, 'path');
     try {
       return await readFile(absolute, 'utf8');
     } catch {
@@ -143,14 +279,14 @@ export class Workspace {
    * @param {object} [options] How to write it.
    * @param {boolean} [options.overwrite] Whether replacing an existing file is allowed.
    * @param {string} [options.extension] An extension the path must have.
-   * @returns {Promise<{ path: string, relative: string, bytes: number, replaced: boolean }>}
+   * @returns {Promise<{ path: string, relative: string, root: string, bytes: number, replaced: boolean }>}
    *   Where it went and how big it was.
-   * @throws {WorkspaceError} If the path escapes the root, has the wrong extension, or
+   * @throws {WorkspaceError} If the path escapes the roots, has the wrong extension, or
    *   already exists and `overwrite` was not set.
    */
   async write(path, contents, options = {}) {
     const { overwrite = false, extension } = options;
-    const absolute = await this.resolve(path, 'path');
+    const { absolute, root } = await this.resolve(path, 'path');
 
     if (extension && extname(absolute).toLowerCase() !== extension) {
       throw new WorkspaceError(`"${path}" must end in ${extension}`);
@@ -165,40 +301,6 @@ export class Workspace {
     await writeFile(absolute, contents);
 
     const bytes = typeof contents === 'string' ? Buffer.byteLength(contents) : contents.length;
-    return { path: absolute, relative: relative(this.root, absolute) || '.', bytes, replaced };
-  }
-
-  /**
-   * Finds files by extension, so a caller can discover what is already here rather than
-   * guessing at names.
-   *
-   * @param {string} [extension] The extension to match, including the dot.
-   * @returns {Promise<string[]>} Paths relative to the root, sorted, depth-first.
-   */
-  async list(extension = '.forma') {
-    /** @type {string[]} */
-    const found = [];
-
-    const walk = async (directory, depth) => {
-      if (depth > MAX_DEPTH) return;
-      /** @type {import('node:fs').Dirent[]} */
-      let entries;
-      try {
-        entries = await readdir(directory, { withFileTypes: true });
-      } catch {
-        return;
-      }
-      for (const entry of entries) {
-        if (entry.name.startsWith('.') || SKIPPED.has(entry.name)) continue;
-        const child = join(directory, entry.name);
-        if (entry.isDirectory()) await walk(child, depth + 1);
-        else if (entry.isFile() && extname(entry.name).toLowerCase() === extension) {
-          found.push(relative(this.realRoot, child));
-        }
-      }
-    };
-
-    await walk(this.realRoot, 0);
-    return found.sort((a, b) => a.localeCompare(b));
+    return { path: absolute, relative: this.#within(root, absolute), root: root.path, bytes, replaced };
   }
 }