forgecad 0.10.3 → 0.10.5

package/dist-skill/docs/guides/structural-fea.md

@@ -0,0 +1,224 @@
+---
+skill-group: cli
+skill-order: 3
+---
+
+# Structural FEA Stress Inspection
+
+Use structural FEA when you want a ForgeCAD model to answer a load-case question:
+
+- Where does this part see the highest stress?
+- How far does it deflect?
+- What is the minimum safety factor against the material yield strength?
+- Did the mesh and solver produce evidence that is good enough to inspect?
+
+ForgeCAD owns the authoring contract, solver orchestration, result feedback, and inspection report. The numerical solve is done out of process with Gmsh and CalculiX. Users author a study in the model, run `forgecad fea run`, and inspect a result bundle.
+
+## What You Get
+
+A solved FEA result bundle can produce:
+
+- max von Mises stress
+- max displacement
+- minimum safety factor
+- mesh quality and solver trust flags
+- region-level hot spots
+- `report.html`
+- `summary.json`
+- a safety-factor heatmap PNG
+- a solver stress heatmap PNG
+- a displacement magnitude heatmap PNG
+
+The deformed render is display-only. It helps explain the displacement shape; it does not change the stress, displacement, or safety-factor numbers reported by the solver.
+
+## What You Need Installed
+
+The ForgeCAD CLI creates the package and renders the heatmap. The package runner uses self-contained `uv` Python scripts for Gmsh so every package resolves the same Python dependency set by default.
+
+Run `forgecad doctor` to check these optional FEA tools in a separate section. Missing FEA tools do not block core ForgeCAD modeling, export, or render commands.
+
+| Tool | Used For | Quick Check |
+| --- | --- | --- |
+| `uv` | Runs the packaged Python scripts with pinned dependencies | `uv --version` |
+| CalculiX `ccx` | Solves the static stress deck | `ccx -v` |
+| Bash | Runs the package script | `bash --version` |
+| Chrome or Chromium | Renders PNG heatmaps from solved evidence | Chrome installed in a standard location, `CHROME_PATH=/path/to/chrome`, or `--chrome-path /path/to/chrome` |
+
+If `uv` is not on `PATH`, set `UV=/path/to/uv` when running `forgecad fea run` or `forgecad fea check`.
+
+If `ccx` is not on `PATH`, set `CCX=/path/to/ccx` when running `forgecad fea run` or `forgecad fea check`.
+
+If you need an offline or pre-provisioned Python environment, set `PYTHON=/path/to/python`. That opt-out Python must be able to `import gmsh`; use `GMSH_PYTHONPATH` / `GMSH_PYTHON_PATH` only for that override path.
+
+ForgeCAD does not bundle CalculiX. The generated `uv` scripts pin the Gmsh Python package, and `uv` downloads/caches it from the configured Python package index. If you redistribute solver binaries or Python wheels to customers, handle their licenses as part of your distribution.
+
+## Author The Study
+
+Structural FEA starts in the `.forge.js` file. The script should return an authored `assembly(...)` with:
+
+1. a structural part marked with `Fea.body(...)`
+2. one or more static stress studies from `Fea.study.staticStress(...)`
+3. explicit fixtures and loads
+4. a second-order tetrahedral mesh intent
+
+```js
+const aluminum = Fea.material("6061-T6", {
+  densityKgM3: 2700,
+  youngsModulusMPa: 68900,
+  poissonRatio: 0.33,
+  yieldStrengthMPa: 276,
+});
+
+const beam = box(120, 12, 12);
+
+return assembly("Cantilever Stress Study")
+  .addPart("Beam", beam, {
+    fea: Fea.body({ material: aluminum }),
+  })
+  .withFeaStudy(
+    Fea.study.staticStress("end-load", {
+      fixtures: [
+        Fea.fix.fixed(Fea.region.face("fixed-end", beam.face("left"))),
+      ],
+      loads: [
+        Fea.load.force(Fea.region.face("load-end", beam.face("right")), {
+          newtons: 80,
+          direction: [0, 0, -1],
+        }),
+      ],
+      target: Fea.target.minSafetyFactor(2),
+      mesh: Fea.mesh.quadraticTets({ maxSizeMm: 4 }),
+    }),
+  );
+```
+
+The complete API reference is generated from source in [Assembly](../generated/assembly.md). Keep reusable examples in `.forge.js` files; do not duplicate every API signature in handwritten docs.
+
+## Choose Stable Regions
+
+Fixtures and loads must name real geometric regions. ForgeCAD will not guess them later.
+
+Use `Fea.region.face(...)` when you can refer to a compiler-owned exact face, such as a simple box face or a named face from the model API.
+
+Use `Fea.region.plane(...)` when the target is a planar face created by profiles, booleans, or imported geometry and the face name is not stable enough. Make the plane specific enough that it matches exactly one STEP/Gmsh surface.
+
+During export, ForgeCAD writes a region map and a STEP tag plan. During the package run, the Gmsh preflight matches every authored fixture/load region against the STEP surfaces. Missing or ambiguous matches fail hard. That is intentional: a silent substitute face would make the stress result untrustworthy.
+
+## Run The Flow
+
+Installed users run the CLI as `forgecad`. Developers running inside this repository can replace `forgecad` with `node dist-cli/forgecad.js`.
+
+Run every authored FEA study and save an inspection result bundle:
+
+```bash
+forgecad fea run examples/analysis/structural-stress-fea.forge.js
+```
+
+Run one named study:
+
+```bash
+forgecad fea run bracket.forge.js --study side-load
+```
+
+Open the report:
+
+```bash
+forgecad fea open out/bracket-fea
+```
+
+Render a customer-facing safety view:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field safety
+```
+
+Render the engineering stress heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field stress
+```
+
+Render the displacement magnitude heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field displacement
+```
+
+Render a deformed stress view only when the displacement shape is useful to inspect:
+
+```bash
+forgecad fea render out/bracket-fea/side-load \
+  --field stress \
+  --shape deformed \
+  --exaggerate 10
+```
+
+The deformation scale only affects the render. It does not change the reported stress, displacement, or safety factor.
+
+Each solved study result directory includes:
+
+- `report.html` for the human inspection report
+- `summary.json` for automation
+- `renders/safety-factor.png` for the customer-facing safety heatmap
+- `renders/stress.png` for the engineering von Mises stress heatmap
+
+Displacement and deformed-shape PNGs are explicit render outputs from `forgecad fea render --field displacement` or `--shape deformed`.
+
+Compare two solved result bundles:
+
+```bash
+forgecad fea compare out/baseline-fea/side-load out/four-x-fea/side-load
+```
+
+Comparison renders use one shared camera, image size, and safety-factor legend.
+
+Run in CI and fail the process when authored targets fail:
+
+```bash
+forgecad fea check bracket.forge.js --json
+```
+
+## Read The Results
+
+Start with `report.html` or `summary.json` in the result directory. The important fields are the maximum stress, maximum displacement, minimum safety factor, hot spots, and any mesh or solver trust findings.
+
+The default user-facing result is safety factor because it answers "is this part okay?" Use stress when you need the raw engineering von Mises field.
+
+Advanced users can still run the lower-level package flow:
+
+```bash
+forgecad export fea model.forge.js --output out/beam.feapkg
+forgecad sim fea out/beam.feapkg --json
+forgecad inspect structural stress out/beam.feapkg --camera iso --output out/stress.png
+```
+
+Those commands are useful for debugging package evidence. Customer docs should prefer `forgecad fea ...`.
+
+## Current Scope
+
+Structural FEA V1 is intentionally narrow:
+
+- linear static stress only
+- one structural body per package
+- exact OCCT STEP export only
+- second-order tetrahedral elements only
+- fixed fixtures and force loads only
+- no contacts, bonded assemblies, thermal loads, buckling, fatigue, plasticity, or certification workflow
+
+ForgeCAD refuses mesh or faceted fallback for FEA export. If exact geometry export, region mapping, mesh quality, solver convergence, result parsing, or evidence trust fails, the command should fail with an actionable error instead of inventing a weaker path.
+
+## Troubleshooting
+
+| Symptom | What It Means | What To Do |
+| --- | --- | --- |
+| `FEA.TOOLCHAIN_UV_MISSING` | The package runner cannot find `uv`. | Install `uv` or run with `UV=/path/to/uv`. |
+| `FEA.TOOLCHAIN_PYTHON_MISSING` | A `PYTHON=...` override points to a missing Python executable. | Install Python 3 or fix the `PYTHON` path. |
+| `FEA.TOOLCHAIN_GMSH_MISSING` | The selected Python process cannot import Gmsh. | Prefer the default `uv` path, or install the Gmsh Python module for the `PYTHON=...` override. |
+| `FEA.TOOLCHAIN_CCX_MISSING` | CalculiX is not available as `ccx`. | Install CalculiX or run with `CCX=/path/to/ccx`. |
+| `FEA.GMSH_FACE_MATCH_NONE` | An authored fixture/load region did not match a STEP surface. | Use a more stable face reference or a more precise planar region. |
+| `FEA.GMSH_FACE_MATCH_AMBIGUOUS` | A region matched more than one STEP surface. | Make the target region more specific or change the model so the load/fixture face is unique. |
+| `FEA.MESH_QUALITY_BELOW_TARGET` | The mesh exists but did not meet the package quality target. | Reduce mesh size, simplify tiny features, or improve the geometry around the hot area. |
+| `FEA.SOLVER_FAILED` | CalculiX did not complete the solve. | Inspect `solver/static_stress.log`, then check fixtures, loads, material values, and over-constraint. |
+| `FEA.FIELD_UNTRUSTED` | The heatmap input is not trusted package evidence. | Run inspection on the `.feapkg` directory after `forgecad sim fea`, not a copied JSON file. |
+
+For command flags, use the [CLI reference](../CLI.md). For the public API, use the generated [Assembly reference](../generated/assembly.md).

package/dist-skill/library/README.md

@@ -8,15 +8,12 @@ forgecad skill install
 
 The installed skill names are namespaced to avoid collisions with a user's existing generic skills.
 
-- `forgecad-3d-reconstruction`
-- `forgecad-blockout-model`
-- `forgecad-component-model`
-- `forgecad-image-replicator`
-- `forgecad-make-a-model`
-- `forgecad-model-grader`
-- `forgecad-mujoco-verify`
-- `forgecad-project`
-- `forgecad-reconstruction-benchmark`
-- `forgecad-render-inspect`
-- `forgecad-spec-by-walking-through-it`
-- `forgecad-visual-spec`
+- `forgecad-build-model`
+- `forgecad-design-spec`
+- `forgecad-grade-model`
+- `forgecad-image-prompt`
+- `forgecad-inspect-model`
+- `forgecad-project-sync`
+- `forgecad-reconstruct-cad-file`
+- `forgecad-reconstruct-from-images`
+- `forgecad-verify-mujoco`

package/dist-skill/library/{forgecad-make-a-model → forgecad-build-model}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: forgecad-make-a-model
-description: Create manufacture-realistic prototype ForgeCAD (.forge.js) models in the active CAD project. Handles file placement, invokes the forgecad skill for API guidance, and validates the result.
+name: forgecad-build-model
+description: Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence.
 forgecad-public: true
 ---
 
-# Make a Model
+# Build Model
 
 Create new ForgeCAD models in the user's active ForgeCAD project.
 
@@ -79,7 +79,17 @@ For any mechanism (linkage, hinge, slider, suspension, gripper, drawer), the rig
 
 A mechanical script is not done when it merely looks assembled. Every visible piece needs a physical reason to be where it is: fused material, contact faces, a screw stack, a pin in a bore, a tab in a slot, a gasket on a land, a bearing in a seat, a cable in a channel, or a named intentional ghost.
 
-- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`. Final `translate()` calls are not assembly contracts.
+For multi-part assemblies, the component model is mandatory:
+
+- Parts build at origin in their own local coordinates. They do not know final assembly-space offsets, sibling dimensions, or world placement.
+- A part's public interface is `shape` plus connectors and metadata, e.g. `return { shape, boltPattern, pinionZ }`. Declare mating faces with `.withConnectors({})`; axes point outward, with prismatic slide axes as the explicit exception.
+- The parent assembly chooses the root and positions every structural part through connectors, `connect()`, `match()`, or `matchTo()`. Final `translate()` calls are not assembly contracts.
+- Data flows down through `require('./part.forge.js', params)` overrides and up through returned metadata. Siblings never import each other; the parent routes shared decisions and measured outputs.
+- Default to one file for a project-specific assembly. Split only for cross-project reuse, independent subassemblies, or when a file grows past roughly 300 lines. Never create `shared-dims.js` just to coordinate siblings.
+
+Reject these shortcuts on sight: sibling `require()`, assembly-space coordinates inside a part, `translate()` used to position a structural assembly member, `console.log` + `if` validation instead of `verify.*`, and bare `connector.neutral()` outside a reusable component library with compatibility checks.
+
+- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`.
 - Manual joint frames (`addFixed`/`addRevolute`/`addPrismatic` with a hand-built `frame:`) are scaffolding, not contracts. Before delivery, convert mating interfaces to connectors with `connect()`/`match()`, or prove the manual joint with `forgecad debug assembly --fail-on warning` and documented geometry.
 - A named part must not contain unintentional disconnected bodies: boolean-join manufactured features, model fasteners/seals as separate named parts, or add the receiving holes/lands that explain the separation.
 - Screws are not decoration: clearance/counterbore in the cover, receiving boss or through stack in the parent, material around both, axes aligned from one shared bolt pattern.
@@ -94,7 +104,7 @@ Treat `fillet()`/`chamfer()` as experimental (Manifold can be incorrect, OCCT sl
 
 ## Imported Parts (User-Supplied 3D Files)
 
-When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-3d-reconstruction`, a different request).
+When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-reconstruct-cad-file`, a different request).
 
 - Wrap each import in its own part file: `Import.mesh()` for STL/OBJ/3MF, `Import.step()` for STEP (OCCT backend), normalize scale and orientation, recenter to a sane local origin, then treat it exactly like a purchased part — connectors at its real mating features, positioned by the assembly via `matchTo()`.
 - Never trust units. Verify against a known dimension before mating anything: bbox via `forgecad run --details`, or `inspect section --ray` across a bore or face pair. For 3MF, account for every build item printed by `forgecad run` before flattening.
@@ -146,7 +156,7 @@ A manufacture-realistic model must yield a package a shop can consume, not just
 
 ## Render and Inspect Cadence
 
-**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-render-inspect` skill and the CLI docs — this skill fixes only the cadence and the gates.
+**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-inspect-model` skill and the CLI docs — this skill fixes only the cadence and the gates.
 
 Render after every feature addition, boolean cut, symmetric copy placement, and the last feature. Inspect after adding hidden geometry a surface render cannot prove, after adding or moving mating parts, ghosts, connectors, thin walls, or screw holes, and before delivery with thresholds set for the material/process.
 

package/dist-skill/library/{forgecad-spec-by-walking-through-it → forgecad-design-spec}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: forgecad-spec-by-walking-through-it
-description: Design a ForgeCAD model, mechanism, or assembly by fixing WHAT before HOW in a git-reviewed design document, validated by mentally operating the thing step by step. Covers fuzzy-request intake and process choice, high-level design (HLD), and low-level design (LLD). Use on "spec this out", "plan the design", "write the HLD/LLD", a vague build request that needs concrete decisions, or any moment the right move is a reviewable spec before code.
+name: forgecad-design-spec
+description: Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification.
 forgecad-public: true
 ---
 
-# Spec by Walking Through It
+# Design Spec
 
 The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit-and-review, and the `git diff` is the review artifact.
 
@@ -129,4 +129,4 @@ HLDs and LLDs iterate through git, not conversation:
 |-------|--------------------|--------|------|
 | Explore a fuzzy ask | Intake | engineering brief + master prompt | HLD |
 | Decide *what* to build | HLD | `*-hld.md` (Decisions filled) | LLD |
-| Detail *how* to build | LLD | `*-lld.md` | `forgecad-make-a-model` + `forgecad` → `.forge.js` |
+| Detail *how* to build | LLD | `*-lld.md` | `forgecad-build-model` + `forgecad` → `.forge.js` |

package/dist-skill/library/{forgecad-spec-by-walking-through-it → forgecad-design-spec}/references/master-prompt.md

@@ -68,6 +68,6 @@ Required outputs:
 7. Bill of materials — manufactured, printed (if any), and purchased parts; per line: name, exact spec or part class, quantity, purpose, key dimensions/ratings; mirrored in-model with `bom()` so `forgecad export report` reproduces it.
 8. Assembly package — assembly order, jointing method, insert/bearing/pin usage, fastening notes, failure-prone steps.
 9. Validation package — motion range, likely collisions, stiffness/load risks, manufacturability, tolerance stacks, wear points; check printability only for printed parts; check moving designs through their operating range, not just at rest pose.
-10. ForgeCAD implementation package — the actual file structure; in a writable workspace, write the `.forge.js` files instead of stopping at prose, with `main.forge.js` as the runnable entry point for multi-file projects; `dim()` annotations on the dimensions a builder must hit, and the process-appropriate export proven to run (per the forgecad-make-a-model Manufacturing Outputs bar).
+10. ForgeCAD implementation package — the actual file structure; in a writable workspace, write the `.forge.js` files instead of stopping at prose, with `main.forge.js` as the runnable entry point for multi-file projects; `dim()` annotations on the dimensions a builder must hit, and the process-appropriate export proven to run (per the forgecad-build-model Manufacturing Outputs bar).
 11. Final verdict — end with exactly one of `BUILD-READY` or `BEST-EFFORT BUILD CANDIDATE`.
 ```

package/dist-skill/library/{forgecad-model-grader → forgecad-grade-model}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: forgecad-model-grader
-description: Analyze, verify, and grade ForgeCAD or CAD-as-code models against a user requirement, design brief, prompt, reference, or acceptance criteria. Use when asked to evaluate, judge, QA, benchmark, score, rate, or compare a CAD model; render it from multiple angles, run targeted inspections when needed, visually verify the evidence, and produce a 0-10 score with concise justification.
+name: forgecad-grade-model
+description: Grade a ForgeCAD or CAD-as-code model against a requirement, brief, prompt, reference, or acceptance criteria with evidence and a 0-10 score.
 forgecad-public: true
 ---
 
-# ForgeCAD Model Grader
+# Grade Model
 
 Grade the delivered model against the requirement, not against what could be fixed later. Never edit the model unless the user explicitly requests repairs — then record the baseline grade first, change, and re-grade.
 
@@ -14,7 +14,7 @@ Grade the delivered model against the requirement, not against what could be fix
 2. **Run the model**: `forgecad run <model>.forge.js` (in the ForgeCAD repo use the local build, `node dist-cli/forgecad.js run ...`). If it fails to execute, stop and apply the caps.
 3. **Render** at least `iso`, `front`, `right`, `top` to a scratch dir; add views (back, bottom, close-up, section) when the model is asymmetric, hollow, mechanical, or likely to hide mistakes.
 4. **Open and look at every PNG** — never score from command output alone. Check silhouette, proportions, required features, part boundaries, interfaces, and whether the model reads as the requested artifact from more than one angle.
-5. **Inspect** whenever hidden internals, fit, wall thickness, or assembly behavior are central to the brief — grading without inspecting them caps the score. Delegate evidence choice, commands, and manifest reading to the `forgecad-render-inspect` skill. Findings (unexpected collisions, thin regions, floating bodies, wrong component counts) are evidence, not warnings to wave away.
+5. **Inspect** whenever hidden internals, fit, wall thickness, or assembly behavior are central to the brief — grading without inspecting them caps the score. Delegate evidence choice, commands, and manifest reading to the `forgecad-inspect-model` skill. Findings (unexpected collisions, thin regions, floating bodies, wrong component counts) are evidence, not warnings to wave away.
 6. **Score**: fill the rubric, apply caps, give a final 0-10 in whole or `.5` increments. Unknowns count against the score.
 
 ## Rubric
@@ -40,6 +40,7 @@ Maximum scores, applied after the rubric:
 - A must-have requirement is absent: max `6`.
 - Visually recognizable but physically impossible for the requested use: max `6`.
 - Internals, fit, walls, or assembly central to the brief but uninspected: max `7`.
+- Multi-part assembly violates the ForgeCAD component model — sibling imports, assembly-space coordinates inside parts, structural `translate()` placement, missing connector mates, or parent/child data flow confusion: max `7`; max `6` when the violation makes the assembly brittle or mechanically wrong.
 - Inspection finds unexpected collisions, floating bodies, critical thin walls, or wrong connectivity: max `6`; max `5` when the defect invalidates the main function.
 - Delivered as a finished product/prototype but presented with default flat lighting (no `scene()` rig), a generically colorful or material-false palette, or teaching-diagram styling: max `8`. Does not apply when the brief asks for a blockout or bare technical study.
 - Any score relying on an assumption the evidence cannot verify: mark it `Unknown`, never score above `8`.
@@ -66,5 +67,6 @@ Next fixes: the 2-5 highest-leverage improvements.
 - Grade the default returned model unless the user names a parameter set or variant.
 - No points for comments, labels, or intentions absent from the geometry.
 - Decorative screws, floating labels, and teaching-diagram callouts are not real mechanical interfaces.
+- For multi-part assemblies, require the component model: parts build locally at origin, expose connectors/metadata, the parent positions them, and inter-part data flows through parent props and returned metadata.
 - Cite which render or inspection finding drove the grade.
 - When comparing models, use identical checklist, cameras, inspection evidence, and caps for all.

package/dist-skill/library/forgecad-grade-model/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ForgeCAD Grade Model"
+  short_description: "Grade CAD models against a brief"
+  default_prompt: "Use $forgecad-grade-model to evaluate this ForgeCAD model against the requirement and give a 0-10 score with evidence."

package/dist-skill/library/{forgecad-visual-spec → forgecad-image-prompt}/SKILL.md

@@ -1,18 +1,18 @@
 ---
-name: forgecad-visual-spec
-description: Turn a concrete ForgeCAD artifact, build brief, HLD, or existing model into builder-honest image prompts for AI image models. Use when the user wants visual-spec renders that show the final product while keeping mechanisms, seams, hardware, and build cues visible instead of drifting into concept art.
+name: forgecad-image-prompt
+description: Write builder-honest AI image prompts from a concrete ForgeCAD model, build brief, HLD, or LLD without hiding how the artifact is built.
 forgecad-public: true
 ---
 
-# ForgeCAD Visual Spec
+# Image Prompt
 
 ## Scope
 
-Only for artifacts already concrete enough to visualize (a specific `.forge.js` model, build brief, or HLD); route vague briefs to `forgecad-spec-by-walking-through-it` first. Read minimum context — entry `.forge.js`, one key helper if it delegates geometry, brief/HLD — and capture what must survive the image model: artifact type and scale, major subassemblies, actuation style, visible mechanisms, material and color cues.
+Only for artifacts already concrete enough to visualize (a specific `.forge.js` model, build brief, or HLD); route vague briefs to `forgecad-design-spec` first. Read minimum context — entry `.forge.js`, one key helper if it delegates geometry, brief/HLD — and capture what must survive the image model: artifact type and scale, major subassemblies, actuation style, visible mechanisms, material and color cues.
 
 ## Core Rule
 
-Visual-spec prompts, not concept art: show the final artifact clearly, preserve build and subsystem truth, and keep visible the seams, modules, hardware, and mechanical hierarchy that matter.
+Image prompts, not concept art: show the final artifact clearly, preserve build and subsystem truth, and keep visible the seams, modules, hardware, and mechanical hierarchy that matter.
 
 Negatives (the only negatives list — reuse it, never restate variants):
 

package/dist-skill/library/forgecad-image-prompt/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ForgeCAD Image Prompt"
+  short_description: "Builder-honest image prompt packs"
+  default_prompt: "Use $forgecad-image-prompt to turn this ForgeCAD artifact into image prompts that show the final product without hiding how it is built."

package/dist-skill/library/{forgecad-render-inspect → forgecad-inspect-model}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: forgecad-render-inspect
-description: Run and interpret ForgeCAD inspection bundles for model verification. Use when asked to inspect a ForgeCAD model, analyze an inspection bundle, validate collisions, wall thickness, connectivity, floating bodies, sections, masks, depth, normals, or Zebra stripes.
+name: forgecad-inspect-model
+description: Select, run, and interpret ForgeCAD inspection evidence for collisions, sections, wall thickness, components, masks, depth, normals, surface continuity, and fit.
 forgecad-public: true
 ---
 
-# ForgeCAD Render Inspect
+# Inspect Model
 
 Use `forgecad inspect ...` when a shaded render is too ambiguous and you need structured evidence: a bundle directory with evidence PNGs plus a root `manifest.json` (or, for `inspect section`, a probe directory with `result.json`, `section.svg`, `section.png`). Inspection is not a substitute artifact: look inside with sections, masks, `--focus`/`--hide`, and transparency — never edit the model into a cutaway or exploded default to make inspecting easier. Output dirs: let `inspect` allocate its timestamped directory by default (repeated probes never collide); use `/tmp/<model>-inspect` for throwaway bundles, a project directory only for persistent artifacts.
 
-Routing: authoring/API questions → `forgecad` skill; creating a new model → `forgecad-make-a-model`.
+Routing: authoring/API questions → `forgecad` skill; creating a new model → `forgecad-build-model`.
 
 ## Workflow
 

package/dist-skill/library/{forgecad-project → forgecad-project-sync}/SKILL.md

@@ -1,10 +1,10 @@
 ---
-name: forgecad-project
-description: ForgeCAD project CLI workflow — creating, managing, syncing projects and files on forgecad.io. Covers init, push, pull, file operations, member management, publishing, and sharing.
+name: forgecad-project-sync
+description: Manage hosted ForgeCAD project sync from the CLI: init, clone, pull, push, file operations, members, publishing, and shares.
 forgecad-public: true
 ---
 
-# ForgeCAD Project Operating Rules
+# Project Sync
 
 forgecad.io is the hosted ForgeCAD platform; a project is a local folder linked to the server by `forgecad.json`. The full command inventory (project, file, member, share, token commands and flags) lives in `forgecad project --help` and the forgecad skill's `docs/CLI.md` — do not relearn it here.
 

package/dist-skill/library/{forgecad-3d-reconstruction → forgecad-reconstruct-cad-file}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: forgecad-3d-reconstruction
-description: Reconstruct a parametric ForgeCAD model from an existing 3D CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP; inspect the source asset directly, author real ForgeCAD geometry, and iteratively compare the candidate with `forgecad compare 3d`.
+name: forgecad-reconstruct-cad-file
+description: Reconstruct a readable parametric ForgeCAD model from an existing CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP.
 forgecad-public: true
 ---
 
-# ForgeCAD 3D Reconstruction
+# Reconstruct CAD File
 
 The reference asset is evidence, not the deliverable. The deliverable is a readable, parametric `.forge.js` model that runs, renders, and scores well against the source. Never return `Import.mesh()`/`Import.step()` of the source as the final model unless the user explicitly asks for an import wrapper — imports are for measurement, rendering, and scoring only.
 
-Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-make-a-model` (Imported Parts section), not this skill; benchmark/RL episodes → `forgecad-reconstruction-benchmark`; inspection-bundle interpretation → `forgecad-render-inspect`; independent grading after reconstruction → `forgecad-model-grader`; API and command reference → `forgecad` skill + CLI.md.
+Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-build-model` (Imported Parts section), not this skill; prepared benchmark/RL episodes → use the task-local benchmark instructions, not the public skill library; inspection-bundle interpretation → `forgecad-inspect-model`; independent grading after reconstruction → `forgecad-grade-model`; API and command reference → `forgecad` skill + CLI.md.
 
 ## Workflow
 
@@ -43,4 +43,4 @@ Faceted sources: decide whether tessellation itself is evidence. Matching low-po
 
 ## Done Criteria
 
-The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects (`forgecad-render-inspect`) when the object is multi-part, hollow, thin-walled, or surface-sensitive. Report: source and candidate paths, score JSON path, final metrics, and every known mismatch classified as intentional simplification or remaining work.
+The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects (`forgecad-inspect-model`) when the object is multi-part, hollow, thin-walled, or surface-sensitive. Report: source and candidate paths, score JSON path, final metrics, and every known mismatch classified as intentional simplification or remaining work.

package/dist-skill/library/forgecad-reconstruct-cad-file/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ForgeCAD Reconstruct CAD File"
+  short_description: "Rebuild CAD files as ForgeCAD models"
+  default_prompt: "Use $forgecad-reconstruct-cad-file to inspect this 3D file, rebuild it as parametric ForgeCAD, and score the result against the source."

package/dist-skill/library/{forgecad-image-replicator → forgecad-reconstruct-from-images}/SKILL.md

@@ -1,19 +1,19 @@
 ---
-name: forgecad-image-replicator
-description: Build real ForgeCAD geometry from one or more reference images by treating images as evidence, inferring the object, then validating against both reference-matched and canonical views.
+name: forgecad-reconstruct-from-images
+description: Reconstruct a real parametric ForgeCAD object from reference images by using images as evidence, not as a one-view facade.
 forgecad-public: true
 ---
 
-# ForgeCAD Image Replicator
+# Reconstruct From Images
 
 The reference image is evidence, not the deliverable. The deliverable is a real parametric object that holds up from front, back, side, top, bottom, and reference camera views — a model that matches one image but falls apart from other angles has failed, even if the comparison board looks close. Cutaway, sectioned, exploded, or transparent references are evidence about the complete object: build the closed artifact and recreate explanatory views with viewer/inspection tools (the main `forgecad` skill's closed-artifact rule applies).
 
 ## Companion Skills
 
 - `forgecad` — API docs, model authoring, renderer behavior.
-- `forgecad-spec-by-walking-through-it` — when the images underdetermine artifact family, process posture, scale, operating story, or validation boundary.
-- `forgecad-make-a-model` — file placement, project structure, decomposition, definition of done.
-- `forgecad-render-inspect` — pre-delivery inspection for multi-part, internal, mechanical, thin-wall, or fit-sensitive objects.
+- `forgecad-design-spec` — when the images underdetermine artifact family, process posture, scale, operating story, or validation boundary.
+- `forgecad-build-model` — file placement, project structure, decomposition, definition of done.
+- `forgecad-inspect-model` — pre-delivery inspection for multi-part, internal, mechanical, thin-wall, or fit-sensitive objects.
 
 ## Core Rule
 
@@ -23,19 +23,19 @@ Infer the real object before matching any camera — identity, manufacture, scal
 
 1. Stage references in `/tmp/<slug>-replicate/refs`, keeping originals and adding view names where possible (`front`, `side`, `rear-iso`, `top`, `detail`).
 2. Read each image as evidence, recording: visible facts; scale cues; camera cues; unknowns (hidden/occluded geometry); conflicts across images or stylization.
-3. Write a Real Object Brief — a hard gate before modeling: (a) artifact identity + operating story; (b) assumed scale and units; (c) process posture + part/BOM boundary (real geometry vs purchased vs ghost vs omitted); (d) inferred hidden-side geometry + expected canonical front/back/left/right/top/bottom forms; (e) validation views and inspection evidence. Use `forgecad-spec-by-walking-through-it` when these are underdetermined.
-4. Build a coarse 3D blockout — model the object, not the image: large volumes, axes, symmetry, side depth, rear form, underside, hidden continuations. Render canonical views before any reference-camera comparison. Follow `forgecad-make-a-model` for project structure.
+3. Write a Real Object Brief — a hard gate before modeling: (a) artifact identity + operating story; (b) assumed scale and units; (c) process posture + part/BOM boundary (real geometry vs purchased vs ghost vs omitted); (d) inferred hidden-side geometry + expected canonical front/back/left/right/top/bottom forms; (e) validation views and inspection evidence. Use `forgecad-design-spec` when these are underdetermined.
+4. Build a coarse 3D blockout — model the object, not the image: large volumes, axes, symmetry, side depth, rear form, underside, hidden continuations. Render canonical views before any reference-camera comparison. Follow `forgecad-build-model` for project structure.
 5. Calibrate one camera per usable reference, only after the blockout makes sense from canonical views. Use the object center as `target`; estimate azimuth/elevation/distance/FOV from visible faces and perspective cues; use orthographic when parallel edges stay parallel with no perspective convergence.
 6. Render comparison boards: render the model from each calibrated reference camera and place it next to the original. Never compare from memory.
 7. Iterate one class of change at a time, in order: object hypothesis → major proportions → canonical geometry → camera → details → presentation. If improving one reference view makes another view or a canonical render worse, the object hypothesis is wrong — fix the model, not the camera illusion.
 8. Use every image as a constraint. Never pick one target image and ignore the rest: assign each image a camera, evidence list, and confidence; optimize one shared geometry against the whole set; state how distorted or decorative images were weighted.
-9. Validate the final object: `forgecad run`, reference comparison boards, canonical renders, and targeted inspections via `forgecad-render-inspect`.
+9. Validate the final object: `forgecad run`, reference comparison boards, canonical renders, and targeted inspections via `forgecad-inspect-model`.
 
 ## Comparison Boards
 
 Render with exact `--camera` specs (see the forgecad CLI doc for supported forms). If exact full camera specs do not render, fix the renderer before continuing — never substitute guesses from default `iso` renders.
 
-Build side-by-side boards with the bundled self-contained `uv` helper (installs Pillow on demand). Resolve `scripts/compare_images.py` relative to the installed `forgecad-image-replicator` skill directory:
+Build side-by-side boards with the bundled self-contained `uv` helper (installs Pillow on demand). Resolve `scripts/compare_images.py` relative to the installed `forgecad-reconstruct-from-images` skill directory:
 
 ```bash
 uv run <skill-dir>/scripts/compare_images.py refs/front.png render-front.png compare-front.png

package/dist-skill/library/forgecad-reconstruct-from-images/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ForgeCAD Reconstruct From Images"
+  short_description: "Build real CAD objects from images"
+  default_prompt: "Use $forgecad-reconstruct-from-images to infer the real object from these reference images and build a ForgeCAD model that holds up from all views."

package/dist-skill/library/{forgecad-mujoco-verify → forgecad-verify-mujoco}/SKILL.md

@@ -1,14 +1,14 @@
 ---
-name: forgecad-mujoco-verify
-description: Verify ForgeCAD MJCF exports in MuJoCo with real dynamics, contacts, root behavior, controls, required joint travel, and rendered evidence before calling a model simulation-ready. Use when making a ForgeCAD assembly sim-ready, debugging MJCF contacts, checking why a body falls through the floor, validating actuator motion, or proving a mechanism moved through the intended range.
+name: forgecad-verify-mujoco
+description: Verify a ForgeCAD MJCF export in MuJoCo with dynamics, contacts, controls, joint travel, and rendered evidence before calling it simulation-ready.
 forgecad-public: true
 ---
 
-# ForgeCAD MuJoCo Verify
+# Verify MuJoCo
 
 Use this when `forgecad export mjcf ...` is part of the deliverable. A model is not sim-ready just because `forgecad check simready` passes or the MJCF file loads: it must be loaded in MuJoCo, stepped under gravity, driven with the intended controls, contact pairs inspected, and rendered from useful views.
 
-Routing: geometry-only visual inspection -> `forgecad-render-inspect`; model authoring/API questions -> `forgecad`; building a new model -> `forgecad-make-a-model`.
+Routing: geometry-only visual inspection -> `forgecad-inspect-model`; model authoring/API questions -> `forgecad`; building a new model -> `forgecad-build-model`.
 
 ## Definition Of Done