forgecad 0.10.3 → 0.10.4

package/dist-skill/CONTEXT.md

@@ -146,7 +146,7 @@ selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shap
 sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg, slot
 SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
 sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood
+variableSweep, verify, Viewport, window, Wood, Wrap
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.
@@ -186,6 +186,7 @@ variableSweep, verify, Viewport, window, Wood
 - [Points](#points)
 - [connector](#connector)
 - [Import](#import)
+- [Wrap](#wrap)
 
 ## Functions
 
@@ -893,6 +894,7 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 | `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
 | `specularColor?` | `string` | Specular highlight tint. |
 | `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+| `texture?` | `{ image: string; projection: UvProjectionSpec; ...` | Projected bitmap texture set by `Shape.wrapTexture`. `image` is a self-contained `data:` URI; `projection` maps each vertex's final world position to (u,v) in the shader, so the texture survives transforms and boolean cuts. `imageWidth`/`imageHeight` are the intrinsic pixel dimensions. |
 
 **Face Topology**
 
@@ -1241,6 +1243,22 @@ Overloads:
 
 **Other**
 
+#### `wrapTexture(image: ImageHandle, projection: UvProjectionSpec): Shape` — Wrap an imported bitmap image around this shape using a projection.
+
+The `image` comes from `Import.image('path.png')`; the `projection` is one of the `Wrap.*` helpers — `Wrap.flat({ onto: 'top' })` lays it flat on a face, `Wrap.aroundCylinder({ axis: 'z' })` wraps it like a can label, `Wrap.onSphere()` maps it like a globe, and `Wrap.box()` cube-maps it onto the six sides.
+
+By default the image **auto-fits** the shape — one copy across the relevant extent, so no `width`/`height`/`size` is needed (pass them only to override). The (u,v) is derived from each vertex's final world position, so the image stays glued to the surface through transforms and boolean cuts with no UV layout to maintain — apply `wrapTexture` *after* positioning the shape. Returns a new Shape; the original is unchanged.
+
+```js
+const logo = Import.image('./logo.png');
+box(80, 80, 10).wrapTexture(logo, Wrap.flat({ onto: 'top' }));            // auto-fits the face
+
+const label = Import.image('./label.jpg');
+cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wraps the side
+```
+
+`ImageHandle`: `{ __forgeImage: true, dataUri: string, width: number, height: number, mimeType: string, byteLength: number }`
+
 #### `clone(): Shape` — Return a new Shape wrapper for explicit duplication in scripts.
 
 #### `geometryInfo(): GeometryInfo` — Inspect which backend/representation produced this solid.
@@ -1646,6 +1664,14 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
   const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
 - `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.
+- `image(fileName: string): ImageHandle` — Import a bitmap image (PNG, JPEG, or WebP) as an ImageHandle for projected texturing. Reads the pixel dimensions from the file header and embeds the bytes as a data URI. Pass the result to `Shape.wrapTexture(image, projection)` with a `Wrap.*` projection.
+
+### `Wrap`
+
+- `flat(opts: FlatWrapOptions): UvProjectionSpec` — Project the image flat onto an axis-aligned face — `onto` is one of top/bottom/front/back/left/right. Auto-fits the face (no width/height needed).
+- `aroundCylinder(opts: CylinderWrapOptions): UvProjectionSpec` — Wrap the image around a cylinder like a can label — `axis` is 'x' | 'y' | 'z'. Auto-fits one wrap around and the full height.
+- `onSphere(opts?: SphereWrapOptions): UvProjectionSpec` — Map the image over a sphere like a globe (longitude/latitude). Auto-centers on the sphere.
+- `box(opts?: BoxWrapOptions): UvProjectionSpec` — Cube-map the image onto a box — one copy per face. Auto-fits the box (no size needed).
 
 ---
 

package/dist-skill/docs/generated/core.md

@@ -34,6 +34,7 @@ skill-order: 100
 - [Points](#points)
 - [connector](#connector)
 - [Import](#import)
+- [Wrap](#wrap)
 
 ## Functions
 
@@ -741,6 +742,7 @@ box(100, 100, 10).color('#gold').material({ metalness: 0.95, roughness: 0.05 }).
 | `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
 | `specularColor?` | `string` | Specular highlight tint. |
 | `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+| `texture?` | `{ image: string; projection: UvProjectionSpec; ...` | Projected bitmap texture set by `Shape.wrapTexture`. `image` is a self-contained `data:` URI; `projection` maps each vertex's final world position to (u,v) in the shader, so the texture survives transforms and boolean cuts. `imageWidth`/`imageHeight` are the intrinsic pixel dimensions. |
 
 **Face Topology**
 
@@ -1089,6 +1091,22 @@ Overloads:
 
 **Other**
 
+#### `wrapTexture(image: ImageHandle, projection: UvProjectionSpec): Shape` — Wrap an imported bitmap image around this shape using a projection.
+
+The `image` comes from `Import.image('path.png')`; the `projection` is one of the `Wrap.*` helpers — `Wrap.flat({ onto: 'top' })` lays it flat on a face, `Wrap.aroundCylinder({ axis: 'z' })` wraps it like a can label, `Wrap.onSphere()` maps it like a globe, and `Wrap.box()` cube-maps it onto the six sides.
+
+By default the image **auto-fits** the shape — one copy across the relevant extent, so no `width`/`height`/`size` is needed (pass them only to override). The (u,v) is derived from each vertex's final world position, so the image stays glued to the surface through transforms and boolean cuts with no UV layout to maintain — apply `wrapTexture` *after* positioning the shape. Returns a new Shape; the original is unchanged.
+
+```js
+const logo = Import.image('./logo.png');
+box(80, 80, 10).wrapTexture(logo, Wrap.flat({ onto: 'top' }));            // auto-fits the face
+
+const label = Import.image('./label.jpg');
+cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wraps the side
+```
+
+`ImageHandle`: `{ __forgeImage: true, dataUri: string, width: number, height: number, mimeType: string, byteLength: number }`
+
 #### `clone(): Shape` — Return a new Shape wrapper for explicit duplication in scripts.
 
 #### `geometryInfo(): GeometryInfo` — Inspect which backend/representation produced this solid.
@@ -1494,3 +1512,11 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
   const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
 - `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.
+- `image(fileName: string): ImageHandle` — Import a bitmap image (PNG, JPEG, or WebP) as an ImageHandle for projected texturing. Reads the pixel dimensions from the file header and embeds the bytes as a data URI. Pass the result to `Shape.wrapTexture(image, projection)` with a `Wrap.*` projection.
+
+### `Wrap`
+
+- `flat(opts: FlatWrapOptions): UvProjectionSpec` — Project the image flat onto an axis-aligned face — `onto` is one of top/bottom/front/back/left/right. Auto-fits the face (no width/height needed).
+- `aroundCylinder(opts: CylinderWrapOptions): UvProjectionSpec` — Wrap the image around a cylinder like a can label — `axis` is 'x' | 'y' | 'z'. Auto-fits one wrap around and the full height.
+- `onSphere(opts?: SphereWrapOptions): UvProjectionSpec` — Map the image over a sphere like a globe (longitude/latitude). Auto-centers on the sphere.
+- `box(opts?: BoxWrapOptions): UvProjectionSpec` — Cube-map the image onto a box — one copy per face. Auto-fits the box (no size needed).

package/dist-skill/docs/generated/runtime-names.md

@@ -29,7 +29,7 @@ selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shap
 sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg, slot
 SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
 sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood
+variableSweep, verify, Viewport, window, Wood, Wrap
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.

package/dist-skill/docs/guides/inspection-bundles.md

@@ -5,7 +5,7 @@ skill-order: 2
 
 # Inspection Bundles — Evidence Contract
 
-`forgecad inspect <family> <mode>` writes a deterministic bundle: evidence PNGs under `evidence/<type>/` plus a root `manifest.json`. **The manifest is the authoritative contract** — take file paths, encodings, per-view ranges, thresholds, tolerances, and identity maps from it; never hard-code bundle layout or infer object identity from object order. The PNGs are a visual index for locating findings, not standalone artifacts. Command tree, flags, and `--focus`/`--hide` filtering live in `docs/skill/CLI.md` and `forgecad inspect evidence`; the inspection workflow lives in the `forgecad-render-inspect` skill. Model-authored `scene()` background, lights, fog, and exposure are ignored for inspection captures so evidence stays stable; named scene views remain available via `--view`.
+`forgecad inspect <family> <mode>` writes a deterministic bundle: evidence PNGs under `evidence/<type>/` plus a root `manifest.json`. **The manifest is the authoritative contract** — take file paths, encodings, per-view ranges, thresholds, tolerances, and identity maps from it; never hard-code bundle layout or infer object identity from object order. The PNGs are a visual index for locating findings, not standalone artifacts. Command tree, flags, and `--focus`/`--hide` filtering live in `docs/skill/CLI.md` and `forgecad inspect evidence`; the inspection workflow lives in the `forgecad-inspect-model` skill. Model-authored `scene()` background, lights, fog, and exposure are ignored for inspection captures so evidence stays stable; named scene views remain available via `--view`.
 
 Manifest evidence keys are evidence-oriented and stable for bundle readers: e.g. `fit interference` writes `manifest.evidence.collisions`, `physical components` writes `manifest.evidence.connectivity`.
 

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
 

package/dist-skill/website/skills/{forgecad-make-a-model.md → forgecad-build-model.md}

@@ -1,17 +1,17 @@
-<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-make-a-model/SKILL.md instead. -->
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-build-model/SKILL.md instead. -->
 
-# forgecad-make-a-model
+# forgecad-build-model
 
-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.
+Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence.
 
 | Field | Value |
 | --- | --- |
 | Installed by | `forgecad skill install` |
-| Source | `agent-skill-library/forgecad-make-a-model/SKILL.md` |
+| Source | `agent-skill-library/forgecad-build-model/SKILL.md` |
 
 ---
 
-## Make a Model
+## Build Model
 
 Create new ForgeCAD models in the user's active ForgeCAD project.
 
@@ -86,7 +86,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.
@@ -101,7 +111,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.
@@ -153,7 +163,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/website/skills/{forgecad-spec-by-walking-through-it.md → forgecad-design-spec.md}

@@ -1,17 +1,17 @@
-<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-spec-by-walking-through-it/SKILL.md instead. -->
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-design-spec/SKILL.md instead. -->
 
-# forgecad-spec-by-walking-through-it
+# forgecad-design-spec
 
-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.
+Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification.
 
 | Field | Value |
 | --- | --- |
 | Installed by | `forgecad skill install` |
-| Source | `agent-skill-library/forgecad-spec-by-walking-through-it/SKILL.md` |
+| Source | `agent-skill-library/forgecad-design-spec/SKILL.md` |
 
 ---
 
-## 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.
 
@@ -136,7 +136,7 @@ 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` |
 
 
 ## Bundled Files