partforge 0.8.0 → 0.9.0

package/bin/cli.js

@@ -14,10 +14,31 @@ import { measure } from "../src/testing/measure.js";
 import { verify } from "../src/testing/verify.js";
 import { renderViews } from "../src/testing/render.js";
 import { createPickServer, requestPicks, formatPickResult } from "../src/framework/pick-request/server.js";
+import { matchPattern } from "../src/testing/error-patterns.js";
 
 const die = (msg) => { console.error(msg); process.exit(1); };
 const USAGE = "usage: partforge <measure|render|pick-serve|pick> …";
 
+// Crash contract (issue #27): with --json, a thrown error becomes structured
+// stdout JSON; either way the message is matched against ERROR-PATTERNS.md and
+// the pattern's fix is surfaced. Exit 1 always. NOTE on stdout purity: crash
+// JSON is the only thing on stdout for errors thrown before any report printing
+// (load/boot/measure). But verify() runs after printMeasure and can throw (an
+// unknown metric in verify.expect, or a per-case build crash), so a throw after
+// printing appends the JSON after the human lines — it is not pure. Consumers
+// should prefer --out for robust machine parsing.
+function crash(cmd, e, jsonMode) {
+  const message = e?.message || String(e);
+  const m = matchPattern(message);
+  if (jsonMode) {
+    console.log(JSON.stringify({ ok: false, error: { message, ...(m && { pattern: m.id, hint: m.fix }) } }, null, 2));
+  } else {
+    console.error(`${cmd} failed: ${message}`);
+    if (m) console.error(`pattern: ERROR-PATTERNS.md#${m.id} — ${m.fix}`);
+  }
+  process.exit(1);
+}
+
 const parse = (args, options, usage) => {
   try {
     return parseArgs({ args, options, strict: true, allowPositionals: true });
@@ -29,9 +50,9 @@ const parse = (args, options, usage) => {
 async function loadPart(partPath, usage) {
   if (!partPath) die(usage);
   const mod = await import(pathToFileURL(resolve(process.cwd(), partPath)))
-    .catch((e) => die(`cannot load part "${partPath}": ${e.message}`));
+    .catch((e) => { throw new Error(`cannot load part "${partPath}": ${e.message}`); });
   const part = mod.default;
-  if (!part?.parts || !part?.views) die(`"${partPath}" has no default-exported PartDefinition`);
+  if (!part?.parts || !part?.views) throw new Error(`"${partPath}" has no default-exported PartDefinition`);
   return part;
 }
 
@@ -46,27 +67,33 @@ const commands = {
       json: { type: "boolean" },
       out: { type: "string" },
     }, usage);
-    const part = await loadPart(partPath, usage);
-    const kernel = await bootKernel(part);
     try {
+      const part = await loadPart(partPath, usage);
+      const kernel = await bootKernel(part);
       const report = measure(kernel, part, view);
       printMeasure(report);
+      // Write --out right after measure succeeds, then re-write once verify has
+      // attached report.verify. If verify throws (unknown metric, per-case build
+      // crash) the file already holds the measure half (no `verify` key) — matching
+      // the doc's advice to prefer --out for exactly that non-pure-stdout case.
+      const writeOut = () => {
+        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
+        writeFileSync(flags.out, JSON.stringify(report, null, 2));
+      };
+      if (flags.out) writeOut();
       let vok = true;
       if ((part.verify || flags.process) && !flags["no-verify"]) {
         const v = verify(kernel, part, { process: flags.process, view });
         printVerify(v);
         report.verify = v;
         vok = v.ok;
+        if (flags.out) writeOut();
       }
-      if (flags.out) {
-        mkdirSync(dirname(resolve(flags.out)), { recursive: true });
-        writeFileSync(flags.out, JSON.stringify(report, null, 2));
-        console.log(`\nwrote ${flags.out}`);
-      }
+      if (flags.out) console.log(`\nwrote ${flags.out}`);
       if (flags.json) console.log(JSON.stringify(report, null, 2));
       process.exit(report.ok && vok ? 0 : 1);
     } catch (e) {
-      die(`measure failed: ${e.message || e}`);
+      crash("measure", e, !!flags.json);
     }
   },
 
@@ -76,15 +103,15 @@ const commands = {
       views: { type: "string" },
       out: { type: "string" },
     }, usage);
-    const part = await loadPart(partPath, usage);
-    const kernel = await bootKernel(part);
     try {
+      const part = await loadPart(partPath, usage);
+      const kernel = await bootKernel(part);
       const views = flags.views ? flags.views.split(",") : undefined;
       const files = await renderViews(kernel, part, view, { views, out: flags.out || "render" });
       for (const f of files) console.log(`wrote ${f}`);
       process.exit(0);
     } catch (e) {
-      die(`render failed: ${e.message || e}`);
+      crash("render", e, false);
     }
   },
 
@@ -120,7 +147,9 @@ function printMeasure(r) {
   }
   const a = r.aggregate;
   console.log(`  ── view  bbox ${a.bbox.map((n) => n.toFixed(1)).join("×")}  vol ${(a.volume / 1000).toFixed(2)}cm³  tris ${a.triangleCount}`);
-  console.log(`  overlaps: ${r.overlaps.length ? r.overlaps.map((o) => `${o.a}×${o.b} (${o.volume.toFixed(1)}mm³)`).join(", ") : "none"}`);
+  console.log(`  overlaps: ${r.overlaps.length
+    ? r.overlaps.map((o) => `${o.a}×${o.b} (${o.volume.toFixed(1)}mm³ at [${o.location.map((n) => n.toFixed(1)).join(", ")}])`).join(", ")
+    : "none"}`);
 }
 
 function printVerify(v) {
@@ -130,6 +159,10 @@ function printVerify(v) {
     for (const ch of c.checks) {
       const icon = ch.status === "pass" ? "✓" : ch.status === "fail" ? "✗" : ch.status === "warn" ? "⚠" : "·";
       console.log(`    ${icon} ${ch.subpart ?? "_view"} ${ch.metric} ${ch.expr}  (${ch.message})`);
+      if (ch.status === "fail" || ch.status === "warn") {
+        if (ch.location) console.log(`        at [${ch.location.map((n) => n.toFixed(1)).join(", ")}]`);
+        if (ch.hint) console.log(`        hint: ${ch.hint}${ch.pattern ? ` (ERROR-PATTERNS.md#${ch.pattern})` : ""}`);
+      }
     }
   }
   const f = v.failures.length, w = v.warnings.length;

package/docs/AUTHORING-PARTS.md

@@ -431,9 +431,10 @@ stylesheet). `mount` looks up these element IDs:
 Copy `demo.html` and change the title, the panel heading, and the `<script src>`. Two workers are spawned from your one worker entry
 (`name` = `"manifold"` for preview/STL/3MF, `"occt"` for STEP — handled for you).
 
-> Production deploy builds `index.html` only. Extra `*.html` files are **dev-only**
-> (Vite serves any root HTML in `npm run dev`). To also ship one, add it to
-> `build.rollupOptions.input` in `vite.config.js`.
+> Production deploy compiles only the pages listed in `build.rollupOptions.input`
+> (currently the landing gallery + the demo part pages). Other root `*.html` files are
+> **dev-only** (Vite serves any root HTML in `npm run dev`) unless added there. To also
+> ship one, add it to `build.rollupOptions.input` in `vite.config.js`.
 
 ### Developing against a local (linked) partforge
 
@@ -518,6 +519,54 @@ The `measure` function is also exported for vitest (boot a Manifold kernel as in
       expect(r.subparts[0].holes).toBe(1);   // e.g. expects one bore
     });
 
+### The diagnostics contract (for agents)
+
+`partforge measure <part> --json` / `--out <file>` emits the machine-readable
+report. Every `fail`/`warn` check in `verify.failures` / `verify.warnings`
+carries:
+
+- `hint` — one self-contained corrective sentence (always present),
+- `pattern` — a stable [ERROR-PATTERNS.md](ERROR-PATTERNS.md) entry ID when one
+  applies (follow it with `ERROR-PATTERNS.md#<id>`),
+- `location` — `[x, y, z]` in mm where the metric has one: `minWall` (thinnest
+  sample point) and `overlaps` (the center of the first offending intersection's
+  *bounding box* — a nearby indicator, not an exact point: when a pair overlaps in
+  more than one place the bbox center can fall in the empty space between regions).
+  Whole-solid metrics (bbox, volume, …) have none.
+
+Subpart facts include `minWall` (number or `null` — null exactly when no reading
+exists, e.g. the OCCT backend or min-wall measurement turned off, matching
+`minWallAt`'s null) and `minWallAt` (`[x,y,z]` or `null`); overlap entries are
+`{ a, b, volume, location }`.
+
+A **thrown** error (bad part module, kernel failure) with `--json` prints pure
+JSON to stdout and exits 1:
+
+```json
+{ "ok": false, "error": { "message": "…", "pattern": "<id>", "hint": "…" } }
+```
+
+`pattern`/`hint` appear when the message matches an ERROR-PATTERNS.md symptom
+string. Exit codes: 0 pass, 1 gate failure or crash — unchanged. Caveat: a throw
+*after* measure output has printed (e.g. an unknown metric in `verify.expect`, or
+a per-case build crash) appends this JSON after the human lines, so stdout is no
+longer pure JSON; prefer `--out` (or parse the trailing JSON object — the crash
+JSON is pretty-printed across multiple lines) for robust machine parsing. With
+`--out` the measure report is written to the file as soon as `measure` succeeds,
+so even if a later `verify` throw crashes the run the file is there — it just
+lacks the `verify` key.
+
+**Part-authored hints.** Any `verify.expect` metric accepts `{ expr, hint }` in
+place of a bare expression — use it to name the governing parameter:
+
+```js
+verify: {
+  expect: {
+    body: { minWall: { expr: ">=1.2", hint: "increase `wallThickness` or reduce `twist`" } },
+  },
+}
+```
+
 ---
 
 ## Self-verification (the `verify` block)
@@ -622,20 +671,23 @@ entirely on OCCT, its fillets are exact in the STEP **and** present in the print
 
 ## Conventions & gotchas
 
-- **replicad (OCCT) transforms consume their input.** `s.translate/.rotate/.mirror/.cut`
-  delete the operand and return a new solid; never reuse a solid after transforming it.
-  The framework rebuilds each sub-part fresh per job and applies `place` once, which
-  avoids this — follow the same pattern in your own code.
-- **Part modules are DOM-free and side-effect-free** — they import into both the main
-  thread (schema → controls) and the worker (build → kernel).
+When something fails confusingly, **grep [ERROR-PATTERNS.md](ERROR-PATTERNS.md) for the
+symptom first** — it maps error text → cause → fix. The invariants, one line each:
+
+- **replicad (OCCT) transforms consume their input** — never reuse a transformed solid;
+  `.clone()` first ([replicad-consumed-operand](ERROR-PATTERNS.md#replicad-consumed-operand)).
+- **Part modules are DOM-free and side-effect-free** — they load in both the main thread
+  and the worker ([worker-imports-main-entry](ERROR-PATTERNS.md#worker-imports-main-entry)).
+- **`build` is a pure function of `(k, p, d)`** — impurity silently defeats the geometry
+  cache ([impure-build-stale-preview](ERROR-PATTERNS.md#impure-build-stale-preview)).
 - **Units are millimetres** throughout.
-- **Preview vs print quality.** Manifold bakes segment counts in at primitive creation,
-  so the export path uses a separate high-res "print" kernel — your `build` is quality-
-  agnostic; just build the geometry.
-- **Display placement is view-independent** (so meshes cache across views); only
-  `place(..., { purpose: "export" })` may depend on `view`.
-- Keep geometry backend-agnostic (kernel calls only) so it works in both backends; only
-  STEP requires OCCT.
+- **Preview vs print quality:** Manifold bakes segment counts in at primitive creation,
+  so builds are quality-agnostic; the export path uses a separate high-res "print" kernel.
+- **Display placement is view-independent**; only `place(..., { purpose: "export" })` may
+  depend on `view` ([view-dependent-display-place](ERROR-PATTERNS.md#view-dependent-display-place)).
+- **Keep geometry backend-agnostic** (kernel calls only); only STEP requires OCCT
+  ([probe-routed-to-occt](ERROR-PATTERNS.md#probe-routed-to-occt),
+  [occt-holes-watertight-na](ERROR-PATTERNS.md#occt-holes-watertight-na)).
 
 ---
 

package/docs/ERROR-PATTERNS.md

@@ -0,0 +1,150 @@
+# Error patterns — symptom-indexed lookup
+
+When a build, test, `measure`, or `verify` run fails confusingly: **grep this file
+for the symptom first** — the literal error text, or a phrase describing the
+misbehavior — before debugging from scratch.
+
+**How to add a pattern** (`##` headings are reserved for pattern entries — the lint
+test parses every one; keep prose like this as plain paragraphs):
+
+- One pattern per `## <id>` heading. The heading is a **stable kebab-case ID**:
+  permanent once committed — never renamed, never reused. External consumers
+  (issue #27 diagnostics, HARDWARE.md, skills) cite `ERROR-PATTERNS.md#<id>`.
+- **Namespaces:** core framework patterns are bare slugs. Subsystem patterns take
+  a reserved prefix — `hardware-*` is reserved for the parts library (issue #30).
+  One `#`-level section per namespace.
+- Entry shape — exactly these three list lines, then optional note paragraphs:
+  - **Symptom:** the literal string an agent would see, verbatim in backticks,
+    when one exists; otherwise the observable misbehavior. This is the grep target.
+  - **Cause:** one sentence.
+  - **Fix:** the concrete change, linking the governing rule
+    ([AUTHORING-PARTS.md](AUTHORING-PARTS.md) section) rather than restating it.
+- No tables inside entries.
+- Code that throws should throw greppable strings: an error message thrown by
+  partforge should appear verbatim, in a backtick literal **at the start** of its
+  pattern's Symptom line. Only that leading literal is what the crash matcher
+  matches on — backticks used for prose later in the line never participate, so a
+  reworded Symptom must lead with the thrown string, not bury it mid-sentence.
+- `test/error-patterns.test.js` lints this file's structure.
+
+# Core framework
+
+## worker-imports-main-entry
+
+- **Symptom:** `ReferenceError: document is not defined` thrown from a worker build.
+- **Cause:** The part (or a helper it imports) imports `partforge` instead of `partforge/geometry`, and the main entry pulls in the DOM viewer/controls.
+- **Fix:** Import geometry helpers only from `partforge/geometry` in anything a worker loads. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## impure-build-stale-preview
+
+- **Symptom:** Preview geometry doesn't change after editing the part's `build` (or changes once, then sticks), with no error anywhere.
+- **Cause:** The preview kernel memoizes geometry by content hash, and an impure `build` (`Math.random`, clock, module-level mutable state) silently defeats it.
+- **Fix:** Make `build` a pure function of `(k, p, d)`; move randomness/state into `derive` inputs or delete it. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Caching & determinism".
+
+## replicad-consumed-operand
+
+- **Symptom:** On the OCCT backend a solid is unexpectedly empty, or the build crashes, right after the same solid was transformed or used in a boolean — often only in STEP export, with the Manifold preview fine.
+- **Cause:** replicad transforms and booleans (`translate`/`rotate`/`mirror`/`cut`/…) consume their operand — the input solid is deleted and a new one returned.
+- **Fix:** Never reuse a solid after transforming it; take a `.clone()` first when you need the original again. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API" (the `s.clone()` row).
+
+The framework itself rebuilds each sub-part fresh per job and applies `place` once, which avoids the problem — follow the same pattern in your own code.
+
+## probe-routed-to-occt
+
+- **Symptom:** A part builds far slower than expected (preview takes seconds instead of milliseconds), and the worker logs show it running on the `occt` worker.
+- **Cause:** The geometry-free probe runs `build` against a recording proxy (dummy query values), and a `fillet`/`chamfer`/`shell` call it reaches — including a branch the real build wouldn't take, since queries return dummies — routes the whole part to OCCT.
+- **Fix:** Remove the CAD-only call the probe reaches unnecessarily, or force the backend with `meta.backend: "manifold"` (or `"occt"`). See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Fillet & chamfer (automatic OCCT backend)".
+
+## boolean-not-watertight
+
+- **Symptom:** `NOT watertight ✗` from `partforge measure` (non-zero exit) after adding a boolean cut or union.
+- **Cause:** A coplanar-face or grazing-cut degeneracy — the tool surface exactly touches the body surface, leaving zero-thickness geometry.
+- **Fix:** Overcut: extend the tool past the faces it pierces (e.g. the demo's cut tool is `h + 4` starting at `z = -2`) and avoid exactly-flush faces in unions. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Verifying a part headlessly (render + measure)".
+
+## dual-kernel-same-process
+
+- **Symptom:** A test file crashes or hangs (WASM abort) when it boots both geometry kernels.
+- **Cause:** OCCT and Manifold WASM must not boot in the same process.
+- **Fix:** Keep OCCT-booting tests in their own files (vitest isolates per file) and boot via `bootOcctKernel()` in a `beforeAll`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Testing a part".
+
+## view-dependent-display-place
+
+- **Symptom:** A sub-part renders correctly in one view but appears misplaced (usually in its other-view pose) after switching views.
+- **Cause:** A `place` that depends on `ctx.view` for `purpose: "display"` — display meshes are built once per sub-part and cached across views.
+- **Fix:** Make display placement view-independent; only `place(..., { purpose: "export" })` may branch on `view`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "The `PartDefinition` contract".
+
+## wrong-node-version
+
+- **Symptom:** Confusing failures during `npm install`, tests, or CLI runs — WASM load errors, syntax errors in dependencies, or kernels that never boot — on a machine that built fine before.
+- **Cause:** The shell's default Node is older than the required Node 24 (`.nvmrc` pins it).
+- **Fix:** Run `nvm use` before `npm install`, tests, or any `npx partforge` command. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Quickstart".
+
+## worker-url-not-inline
+
+- **Symptom:** The app loads but geometry never builds — the worker 404s or is missing from the production bundle (works in `npm run dev`, breaks in `npm run build`).
+- **Cause:** The `new Worker(new URL(...))` call was moved out of the app entry file (into a helper or variable), so Vite's static analysis can't see and bundle the worker.
+- **Fix:** Keep `new Worker(new URL("./<part>-worker.js", import.meta.url), ...)` inline in `src/app-<part>.js`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
+
+## minwall-sliver-triangles
+
+- **Symptom:** `⚠` minWall warnings from `verify` on a faceted part whose walls are clearly thicker than the profile minimum.
+- **Cause:** The ray-shot wall-thickness measurement can catch sliver triangles at facet seams, reading a near-zero "wall" that isn't a designed wall.
+- **Fix:** Check where the reported thin spot is: at a facet seam or chamfer transition it's a sliver artifact (minWall is a warning, never a gate — safe to note and move on); along a real wall, thicken the wall. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
+
+## param-key-missing-from-defaults
+
+- **Symptom:** The affected control's number box renders empty/blank (internally `numStr(undefined)` produces the string `NaN`, which a number input sanitizes to empty), or its range slider sits at a browser-default position and edits don't drive the geometry — no error is thrown — and if the key is `hidden`, no control is rendered for it at all.
+- **Cause:** A `key` used in the `parameters` schema (slider, feature, or preset override) doesn't exist in `defaults` — every key must, including `hidden` ones.
+- **Fix:** Add the key to `defaults` with a sensible starting value. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Parameters: the control-panel schema".
+
+## dimmed-control-vestigial-param
+
+- **Symptom:** A control renders dimmed (but still editable) and changing it does nothing on screen.
+- **Cause:** No sub-part visible in the active view reads that parameter — the relevance-aware panel dims controls with no on-screen effect.
+- **Fix:** This is a signal, not a bug: either the parameter is vestigial (delete it), the control is in the wrong section/view scope, or you're in a view that legitimately doesn't use it. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "The relevance-aware panel".
+
+## linked-checkout-wasm-403
+
+- **Symptom:** In a consuming app using an `npm link`ed partforge checkout, the kernel never boots and the dev-server network tab shows `403` on the Manifold/OCCT `.wasm` files.
+- **Cause:** The linked checkout lives outside the app's project root, so Vite's dev server refuses to serve its files.
+- **Fix:** Allow-list it: `server: { fs: { allow: ["./", "../partforge"] } }` in the app's `vite.config.js`. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Developing against a local (linked) partforge".
+
+## ring-sector-full-circle
+
+- **Symptom:** `ringSectorPolygon: arcDeg must be < 360 (use a cut for a full ring)`
+- **Cause:** A full annulus can't be a single simple polygon — it's a contour-with-hole.
+- **Fix:** Cut an inner cylinder from an outer one (or `k.extrude({ outer, holes })`); use `ringSectorPolygon` only for partial arcs. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Profiles & patterns".
+
+## occt-closed-loop-unsupported
+
+- **Symptom:** `loft: closed:true loops are only supported on the Manifold backend` (or the same message from `sweep:`) — typically during STEP export of a part that previews fine.
+- **Cause:** Capless closed loops are a Manifold-only capability; the OCCT backend rejects them, and STEP export always runs on OCCT.
+- **Fix:** Keep the part on Manifold (no STEP) or model the loop as a capped solid both backends support. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## smooth-geometry-faceted-preview
+
+- **Symptom:** A `ruled:false` loft or `smooth:true` sweep looks faceted/straight-walled in the viewer even though the options are set.
+- **Cause:** Smooth blending is OCCT-native; the Manifold preview always tessellates ruled straight walls — only STEP export carries the smooth surface.
+- **Fix:** Nothing is wrong — verify smoothness in the exported STEP, not the preview. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## scale-moved-the-part
+
+- **Symptom:** After `s.scale(f)` a part is resized but also relocated — features drift away from where they were built.
+- **Cause:** `scale(factor, center?)` defaults its center to the origin, so scaling an off-origin solid about the origin also translates it.
+- **Fix:** Pass the center you mean, e.g. `s.scale(f, s.boundingBox().center)` to resize in place. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Geometry: the kernel / `Solid` API".
+
+## occt-holes-watertight-na
+
+- **Symptom:** `watertight n/a` in `partforge measure` output, and `holes`/`watertight` assertions in a `verify` block don't run, on a part with fillets/chamfers.
+- **Cause:** `holes` and `watertight` are Manifold-only topology facts, and this part auto-routed to OCCT — the assertions skip rather than fail.
+- **Fix:** Expected behavior: assert on backend-independent facts (`bbox`, `volume`, `overlaps`) for OCCT parts, or split topology assertions into a Manifold-buildable configuration. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Self-verification (the `verify` block)".
+
+## html-page-missing-in-prod
+
+- **Symptom:** A part's page 404s in the production deploy while working fine under `npm run dev`.
+- **Cause:** Only pages listed in `build.rollupOptions.input` are compiled by the production build; other root `*.html` pages are dev-only conveniences Vite serves without building.
+- **Fix:** Add the page to `build.rollupOptions.input` in `vite.config.js` if it should ship. See [AUTHORING-PARTS.md](AUTHORING-PARTS.md) § "Wiring a part into a runnable app".
+
+# Hardware library
+
+Reserved for `hardware-*` patterns (issue #30). No entries yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "partforge",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Turn a declarative part definition into a parametric-CAD web app (three.js + Manifold/Replicad). Requires a Vite-based consumer.",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,7 @@
     "bin",
     "skills/partforge/SKILL.md",
     "docs/AUTHORING-PARTS.md",
+    "docs/ERROR-PATTERNS.md",
     "README.md"
   ],
   "exports": {

package/skills/partforge/SKILL.md

@@ -56,3 +56,8 @@ Picks come back **in request order**, each echoing its prompt, so you can map th
 
 - This only *reads* a click — it never edits files. You make the edits yourself after.
 - The server is localhost-only and holds one request at a time.
+
+## Related: debugging failures
+
+If anything fails while you're editing a part, grep `docs/ERROR-PATTERNS.md` for the
+symptom first — its preamble states the full grep-first rule.

package/src/framework/assembly.js

@@ -6,7 +6,7 @@ import { viewSubParts, resolveParams, buildPosed } from "./jobs.js";
 // Parts meant to fit together (e.g. a block seated in a pocket void) read ~0 and
 // don't trip it. Manifold-only (needs Solid.intersect + Solid.volume); meant for
 // part tests so an author/LLM editing a part sees collisions fail.
-//   → [{ a, b, volume }] for each offending pair (empty = no collisions)
+//   → [{ a, b, volume, location }] for each offending pair (empty = no collisions)
 export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance = 1 } = {}) {
   const { p, d } = resolveParams(part, params);
   const posed = viewSubParts(part, view, p).map((name) => ({
@@ -17,8 +17,14 @@ export function assemblyOverlaps(kernel, part, view, params = {}, { tolerance =
   const overlaps = [];
   for (let i = 0; i < posed.length; i++) {
     for (let j = i + 1; j < posed.length; j++) {
-      const volume = posed[i].solid.intersect(posed[j].solid).volume();
-      if (volume > tolerance) overlaps.push({ a: posed[i].name, b: posed[j].name, volume });
+      const inter = posed[i].solid.intersect(posed[j].solid);
+      const volume = inter.volume();
+      if (volume > tolerance) {
+        // location = the intersection's bounding-box center — a nearby indicator, not
+        // an exact contact point: for a disjoint (multi-region) intersection it is the
+        // midpoint of those regions and can land in the empty space between them.
+        overlaps.push({ a: posed[i].name, b: posed[j].name, volume, location: inter.boundingBox().center });
+      }
     }
   }
   kernel.cleanup?.(); // free the per-check WASM objects

package/src/testing/error-patterns.js

@@ -0,0 +1,78 @@
+// Shared parser + matcher for docs/ERROR-PATTERNS.md — the symptom-indexed
+// error→pattern library (issue #28). The parser here is the single source of
+// truth: the format lint (test/error-patterns.test.js) and the CLI crash-path
+// matcher (issue #27) both import it. Contract: partforge code that throws must
+// throw strings appearing verbatim, in a backtick literal AT THE START of some
+// entry's Symptom line — only a leading literal participates in matching, so
+// backticks used for prose mid-sentence never mis-attribute an unrelated crash.
+import { readFileSync } from "node:fs";
+
+// Single-pass, fence-aware parse: a heading inside a ``` / ~~~ fence is quoted
+// content, not structure. Each `## <id>` entry records the `# <section>` it sits
+// under; its body runs to the next h1/h2 heading. (Moved verbatim from the lint
+// test, then enriched with symptom/cause/fix extraction.)
+export function parsePatterns(md) {
+  const entries = [];
+  let section = null;
+  let entry = null;
+  let inFence = false;
+  for (const line of md.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      if (entry) entry.body += line + "\n";
+      continue;
+    }
+    if (!inFence) {
+      const h1 = line.match(/^# (.+)$/);
+      const h2 = line.match(/^## (.+)$/);
+      if (h1) { section = h1[1]; entry = null; continue; }
+      if (h2) { entry = { id: h2[1], section, body: "" }; entries.push(entry); continue; }
+    }
+    if (entry) entry.body += line + "\n";
+  }
+  const field = (body, label) => {
+    const i = body.indexOf(`- **${label}:**`);
+    return i < 0 ? null : body.slice(i).split("\n")[0].replace(`- **${label}:**`, "").trim();
+  };
+  return entries.map((e) => {
+    const symptom = field(e.body, "Symptom");
+    // Leading-literal convention: only a backtick literal at the very START of the
+    // Symptom text is a match literal (kept as a ≤1-element array for compatibility
+    // — tests and the matcher read symptomStrings). Mid-line backticks are prose.
+    const leading = symptom?.match(/^`([^`]+)`/);
+    return {
+      ...e,
+      symptom,
+      cause: field(e.body, "Cause"),
+      fix: field(e.body, "Fix"),
+      symptomStrings: leading ? [leading[1]] : [],
+    };
+  });
+}
+
+// Cached read of the live doc, resolved relative to this module so it works from
+// a consuming app's node_modules too. Any read/parse error → null (callers treat
+// that as "no patterns available", never an error).
+let cached;
+export function loadPatterns() {
+  if (cached !== undefined) return cached;
+  try {
+    cached = parsePatterns(readFileSync(new URL("../../docs/ERROR-PATTERNS.md", import.meta.url), "utf8"));
+  } catch {
+    cached = null;
+  }
+  return cached;
+}
+
+// Leading symptom literals ≥ 6 chars, longest match wins. Never throws.
+export function matchPattern(message, patterns = loadPatterns()) {
+  if (!patterns || typeof message !== "string") return null;
+  let best = null;
+  let bestLen = 5;
+  for (const p of patterns) {
+    for (const s of p.symptomStrings) {
+      if (s.length > bestLen && message.includes(s)) { best = p; bestLen = s.length; }
+    }
+  }
+  return best ? { id: best.id, fix: best.fix } : null;
+}

package/src/testing/measure.js

@@ -20,6 +20,7 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
   const subparts = built.map(({ name, solid, mesh }) => {
     const b = bounds(mesh.positions);
     subBounds.push(b);
+    const mw = opts.minWall ? minWall(mesh) : null;
     return {
       name,
       bbox: size(b),
@@ -28,7 +29,8 @@ export function measure(kernel, part, view = Object.keys(part.views)[0], params
       triangleCount: mesh.triangles,
       watertight: typeof solid.isEmpty === "function" ? !solid.isEmpty() : null,
       holes: typeof solid.genus === "function" ? solid.genus() : null,
-      minWall: opts.minWall ? (minWall(mesh)?.value ?? null) : null,
+      minWall: mw?.value ?? null,
+      minWallAt: mw?.location ?? null,
     };
   });
 

package/src/testing/verify.js

@@ -4,36 +4,70 @@ import { resolveProfile } from "./dfm-profiles.js";
 import { expandCases } from "./cases.js";
 import { subPartReadKeys, relevanceHash, RELEVANT_ALL } from "../framework/param-deps.js";
 
-// Metric registry: name → how to pull the value out of facts, and whether a failure
-// is a hard gate or a warning. `manifoldOnly` facts are null on OCCT parts.
-const SUBPART_METRICS = {
-  holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes },
-  watertight: { kind: "gate", manifoldOnly: true, extract: (s) => s.watertight },
-  volume: { kind: "gate", extract: (s) => s.volume },
-  surfaceArea: { kind: "gate", extract: (s) => s.surfaceArea },
-  triangleCount: { kind: "gate", extract: (s) => s.triangleCount },
-  bbox: { kind: "gate", extract: (s) => s.bbox },
-  minWall: { kind: "warn", extract: (s) => s.minWall },
+// Metric registry: name → how to pull the value out of facts, whether a failure
+// is a hard gate or a warning, and the diagnostics attached to a non-pass check:
+// `hint` (required — the report contract promises one on every fail/warn),
+// `pattern` (optional stable ERROR-PATTERNS.md#<id>), `locate` (optional
+// [x,y,z] source). `manifoldOnly` facts are null on OCCT parts.
+export const SUBPART_METRICS = {
+  holes: { kind: "gate", manifoldOnly: true, extract: (s) => s.holes,
+    hint: "genus is wrong — an unintended tunnel exists or an intended bore is blocked; make cut tools pierce fully (overcut past the faces)" },
+  watertight: { kind: "gate", manifoldOnly: true, extract: (s) => s.watertight,
+    hint: "a boolean produced an open shell — check for coplanar faces or a cut that exactly grazes a surface",
+    pattern: "boolean-not-watertight" },
+  volume: { kind: "gate", extract: (s) => s.volume,
+    hint: "solid volume is out of range — a feature is missing, doubled, or a governing parameter is mis-scaled" },
+  surfaceArea: { kind: "gate", extract: (s) => s.surfaceArea,
+    hint: "surface area is out of range — detail features (facets, ribs, textures) are missing or doubled" },
+  triangleCount: { kind: "gate", extract: (s) => s.triangleCount,
+    hint: "triangle count is out of range — tessellation quality or feature count changed unexpectedly" },
+  bbox: { kind: "gate", extract: (s) => s.bbox,
+    hint: "bounding box is out of range — check the governing dimensions and the part's orientation" },
+  minWall: { kind: "warn", extract: (s) => s.minWall,
+    hint: "thinnest wall is at the reported location — increase the governing wall/thickness parameter or reduce the intersecting feature's depth",
+    pattern: "minwall-sliver-triangles",
+    locate: (s) => s.minWallAt },
 };
-const VIEW_METRICS = {
-  bbox: { kind: "gate", extract: (r) => r.aggregate.bbox },
-  volume: { kind: "gate", extract: (r) => r.aggregate.volume },
-  overlaps: { kind: "gate", extract: (r) => r.overlaps.length },
+export const VIEW_METRICS = {
+  bbox: { kind: "gate", extract: (r) => r.aggregate.bbox,
+    hint: "the assembled view exceeds its size limit — shrink the assembly or pick a process with a larger bed" },
+  volume: { kind: "gate", extract: (r) => r.aggregate.volume,
+    hint: "total assembly volume is out of range — a sub-part is missing, doubled, or mis-scaled" },
+  overlaps: { kind: "gate", extract: (r) => r.overlaps.length,
+    hint: "sub-parts interpenetrate near the reported location — adjust placement or add clearance in derive()",
+    locate: (r) => r.overlaps[0]?.location ?? null },
 };
 
-function check(scope, subpart, metric, expr, registry, factsObj) {
+// An expectation is a bare expression (string/number/boolean) or { expr, hint }.
+const normalizeExpectation = (spec) =>
+  spec !== null && typeof spec === "object" && !Array.isArray(spec) && "expr" in spec
+    ? { expr: spec.expr, hint: spec.hint }
+    : { expr: spec, hint: undefined };
+
+function check(scope, subpart, metric, spec, registry, factsObj) {
   const reg = registry[metric];
   if (!reg) throw new Error(`unknown ${scope} metric "${metric}"${subpart ? ` on sub-part "${subpart}"` : ""}`);
+  const { expr, hint: partHint } = normalizeExpectation(spec);
   const actual = reg.extract(factsObj);
   const base = { scope, subpart, metric, kind: reg.kind, expr: String(expr) };
   if (actual === null || actual === undefined) {
     if (reg.manifoldOnly) return { ...base, actual, status: "skip", pass: null, message: "n/a (OCCT backend)" };
-    if (metric === "minWall") return { ...base, actual, status: "warn", pass: null, message: "min wall unavailable" };
+    if (metric === "minWall") {
+      return { ...base, actual, status: "warn", pass: null, message: "min wall unavailable",
+        hint: partHint ?? "no min-wall reading for this mesh — treat thin features as unverified" };
+    }
     return { ...base, actual, status: "skip", pass: null, message: "unavailable" };
   }
   const { pass, message } = evaluateAssertion(parseAssertion(expr), actual);
   const status = pass ? "pass" : reg.kind === "warn" ? "warn" : "fail";
-  return { ...base, actual, status, pass, message };
+  const out = { ...base, actual, status, pass, message };
+  if (!pass) {
+    out.hint = partHint ?? reg.hint;
+    if (reg.pattern) out.pattern = reg.pattern;
+    const loc = reg.locate?.(factsObj);
+    if (loc) out.location = loc;
+  }
+  return out;
 }
 
 // Pure policy: profile rules + per-part expect → checks for one case's facts.