forgecad 0.10.4 → 0.11.0

package/dist-skill/library/forgecad-build-model/SKILL.md

@@ -1,189 +1,96 @@
 ---
 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.
+description: Build or edit `.forge.js` real product models through design, automatic/manual feedback gathering, inspection/simulation/FEA evidence, and iteration until ready.
 forgecad-public: true
 ---
 
 # Build Model
 
-Create new ForgeCAD models in the user's active ForgeCAD project.
+Create or edit ForgeCAD models through the loop that matters: design intent -> automatic or manual feedback gathering -> interpretation -> iteration -> readiness. Use the core `forgecad` skill as the source of truth for ForgeCAD API docs, generated API pages, CLI syntax, scene setup, assembly contracts, inspection bundles, FEA, simulation metadata, and examples. This skill defines the product-modeling workflow.
 
 ## Default Output Standard
 
-Unless the user asks otherwise, the output is a **manufacture-realistic prototype**: a model someone could fabricate, buy parts for, assemble, inspect, and iterate in a real shop — not a concept sketch, not a universal 3D-printing exercise, not a claim of certified production readiness.
+Unless the user asks otherwise, build a **real product model**: an editable parametric CAD model of the actual physical product, machine, robot, fixture, part, assembly, or simulation asset the user asked for. The model should be closed, assembled, sourced, dimensioned, inspected, tested, and ready for the next real engineering loop.
 
-- Include prototype-real features: wall thickness, fastener stacks, bosses, ribs, flanges, seats, gaskets, cable exits, service access, toleranced clearances, believable purchased parts. No invented tooling details, certifications, or safety ratings unless asked.
-- Modifiers shift the standard: `blockout` → rough massing; `production-realistic` → DFM and production-intent materials; `printable` → make the selected printed parts honest; `visual-CAD` → clearly visual, not pretending build-ready.
-- Zero unexpected final collisions is part of the definition of done (see Collision Policy).
+Real product features are not optional polish. For every physical function the artifact needs, model the corresponding product evidence: wall thickness, fastener stacks, bosses, ribs, flanges, seats, gaskets, cable exits, service access, toleranced clearances, purchased parts, BOM entries, critical dimensions, simulation artifacts when behavior evidence matters, export artifacts when requested or process-dependent, and process-appropriate materials. If evidence is still missing, keep building or name the exact missing validation loop and residual risk; do not quietly lower the target quality.
 
 ## File Placement
 
-New `.forge.js` files go under date-based directories (today's date) in the user's current ForgeCAD project or a clearly named local folder:
-
-```
-YYYY/MM/DD/file.forge.js           — single-file model
-YYYY/MM/DD/folder/main.forge.js    — multi-file entry point (always main.forge.js)
-YYYY/MM/DD/folder/parts/*.forge.js — standalone/importable parts
-YYYY/MM/DD/folder/lib/*.js         — pure helpers/constants, no geometry
+New `.forge.js` files go under date-based directories in the user's current ForgeCAD project or a clearly named local folder:
+
+```text
+YYYY/MM/DD/file.forge.js                         # tiny single-file model only
+YYYY/MM/DD/folder/main.forge.js                  # central entry point for every multi-file build
+YYYY/MM/DD/folder/NOTES.md                       # live build notes: learnings, API friction, surprises, follow-ups
+YYYY/MM/DD/folder/docs/PRFAQ.md                  # product/user story and decision FAQ
+YYYY/MM/DD/folder/docs/HLD.md                    # high-level design
+YYYY/MM/DD/folder/docs/LLD-*.md                  # lower-level design docs as needed
+YYYY/MM/DD/folder/docs/modules/*.md              # submodule or complex-part design notes
+YYYY/MM/DD/folder/modules/<domain>/*.forge.js    # unified nested module tree: leaf modules to system modules
+YYYY/MM/DD/folder/lib/*.js                       # pure helpers/constants, no geometry
 ```
 
-- Kebab-case descriptive names (`parametric-lego.forge.js`). Each part file must run standalone and import via `require('./parts/name.forge.js', params)`.
-- Plain `.js` only for constants, math, tables, formatting — never geometry.
-- Split files only for reusable parts or independent sub-assemblies, never for organization.
+- Use kebab-case descriptive names.
+- Use `main.forge.js` as the central entry point. It should import high-level modules, not every leaf file in a huge build.
+- Prefer one nested `modules/` tree, like software. Compose upward from leaf modules to larger modules to the system. Keep files small enough to understand and verify.
+- Reusable `.forge.js` modules should return builder functions or module interfaces. Direct-run previews belong inside `if (require.main === module)`, like Python's `if __name__ == "__main__"`.
+- Each module file must run standalone where practical and import via `require('./path/file.forge.js')`.
+- Use plain `.js` only for constants, tables, and pure helpers. Do not put geometry in helper-only files.
+- Keep `NOTES.md` current for non-trivial builds. Capture learnings, API frustrations, non-obvious modeling choices, inspection surprises, cleanup notes, and follow-up product/API ideas. Do not hide requirements or formal design decisions there; those belong in PRFAQ/HLD/LLD docs.
+- Write as many markdown design files as the project needs. Complex parts and submodules deserve their own design notes; small edits may need only a short local note.
 
 ## Workflow
 
-1. **Load the `forgecad` skill** — read at least the Core API reference. Moving parts: also the assembly group and joint-design guide. Mating parts: the positioning guide; default to connectors + `matchTo()`.
-2. `mkdir -p YYYY/MM/DD/[folder]`.
-3. Moving parts: prove the rig first (Kinematics-First below).
-4. Write the model — `param()`/`Param.bool()` for tunable dimensions; pick the manufacturing process before styling; build real internals; follow the contracts below.
-5. Validate — `forgecad run <file>` (`main.forge.js` for multi-file).
-6. Run the Final Acceptance Gate and Manufacturing Outputs checks below on `main.forge.js`.
-7. Iterate — convert every render/inspect finding into a model edit and rerun the same targeted evidence until reality matches the intended component graph.
-
-## Process, Style, and Variants
-
-**Manufacturing process is a choice, not an assumption.** Never treat every model as printable. Pick process cues from the load path and operating story: machined, bent sheet, tube-and-plate, wood/composite, molded-look, printed, or hybrid purchased-hardware construction (rideables: metal/composite structure + purchased wheels/bearings; furniture: real joinery). Print-specific features (slicer clearances, heat-set inserts, layer-oriented ribs) only when the process includes printed parts.
-
-**Visual style: expensive and credible, not generically colorful.** Restrained material-driven palette (ivory, charcoal, satin black, brushed aluminum, brass, muted burgundy/green/navy, smoked polymer, natural wood); match color to material/process so metal, polymer, rubber, PCB, and wood read differently. Bright color only as small accents (controls, seals, indicators). Keep seams, fasteners, gaskets, and purchased parts legible.
-
-**Form is part of credibility.** Real products carry deliberate edge treatment — chamfered or rounded profiles where hands, seals, or tooling meet the part, draft on molded faces, consistent proportions and design language across parts. A knife-sharp box reads as a blockout, not a product. Get the rounding from profile-level geometry (rounded sketch corners, chamfered profiles) per the fillet caveat below.
-
-**Variants are parameter-selected.** Sizes/styles/revisions go behind one choice parameter (`Variant`, `Preset`); return only the selected variant. Comparison lineups only behind an explicit debug parameter so they can never pollute collision findings.
-
-## Physical Artifact, Not Teaching Diagram
-
-Deliver the real closed artifact — covers installed, parts in assembled positions. The `forgecad` skill carries the no-labels/no-cutaway rule (no explanatory labels, arrows, or legends in production geometry; never a cutaway, sectioned, or exploded default); it binds here. Markings only when the real artifact has them (serial plates, gauge ticks, molded icons) — sparse, process-appropriate. Explain roles via named return objects and `verify.*`; review annotations go in `Viewport.label()` or a debug mode, never exported geometry.
-
-**Internal geometry is part of the model.** If the real artifact has internals, model them as real geometry even when hidden: cavities, ribs, bosses, screw holes, bearing seats, electronics/battery volumes, wire channels, mechanism clearances and stops. Verify hidden structure with exploration tools — alternate views, `inspect sections`, `--hide`, transparent shells, named ghosts — never by mutilating the returned model.
-
-## Kinematics-First for Moving Parts
-
-For any mechanism (linkage, hinge, slider, suspension, gripper, drawer), the rig is the source of truth: build and prove the motion structure first, then attach geometry — never retrofit motion onto finished shells.
-
-- Pick the rig shape before geometry: point-link graphs for closed-loop skeletons with distance/angle constraints; frames and connector joints when part orientation matters (API roster in the assembly docs).
-- Name every degree of freedom; encode limits/defaults at rig level. Mirrored revolute axes need an explicit sign mapping — equal joint values do not automatically mirror poses.
-- Attach proxy geometry only (pivot markers, bars, slider blocks, wheel discs). Run the rig at rest, mid-travel, both limits, and mirrored/coupled poses until the solver, controls, connector alignment, and `verify.*` checks all pass:
-
-  ```bash
-  forgecad run model.forge.js --joint "theta=45"
-  forgecad render 3d model.forge.js /tmp/theta-45.png --joint "theta=45" --camera iso
-  ```
-
-  Use real joint names; repeat `--joint` per control. A pose that fails to solve, clamps unexpectedly, breaks a connector check, or adds a collision means the rig is not ready for final geometry.
-- Only then attach manufacture-real geometry to the solved links, frames, and connectors — never via a final `rotate()` that makes one pose look assembled.
-- Return the unsolved `Assembly` so Motion controls re-run the real solve. Never bake a posed `SolvedAssembly` to make one pose look right.
-- Encode pose checks in-script with `verify.*`: convergence, connector origins coinciding, link lengths holding, end effectors reaching targets, running clearances positive.
-
-## Mechanical Assembly Contract
-
-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.
-
-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.
-- Handles and levers need a load path: hub-to-arm neck, pivot pin/bore, thrust shoulders, stops/detents, and the connected follower. A handle tangent to a hub is a failed mechanism.
-- Covers, doors, cartridges, service panels need seats: ledges, gasket grooves, bosses, snap hooks, tabs, or hinge barrels — plus a visible retention story.
-- Cables, wires, tubes need receiving geometry: gland, grommet, clamp, socket, ferrule, routed channel, or hose barb. Never let a cylinder end in open space.
-- Purchased loose parts may stay separate bodies — name them as purchased hardware/consumables and seat them in believable sockets, bores, races, or fastener stacks.
-- Encode interface intent with `verify.*`, not comments: `verify.clearanceBetween` for seated fits and clearance bands, `verify.minClearance`/`verify.notColliding` for keep-out and running gaps, `verify.connectorDistance` for connector mates. Part counts and generic dimensions never prove an interface.
-- No canned finished-object helpers for project-specific assemblies. Reusable vocabulary is primitives, cutters, patterns, and mechanical contracts (`lib.fastenerSet()`, `lib.boltPattern()`, real bores and pockets, connectors + `matchTo()`) — not finished backplates, brackets, or hinge leaves.
-
-Treat `fillet()`/`chamfer()` as experimental (Manifold can be incorrect, OCCT slow); prefer profile-level rounding and inspect before relying on the result.
-
-## 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-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.
-- Derive mating geometry by measurement, not eyeball: pull bore positions, diameters, and face offsets from sections, then hold them with `verify.clearanceBetween`/`verify.connectorDistance` against the import like any other body. Collision Policy applies to imports too.
-- The import is a purchased/fixed line item; the manufactured deliverables are the ForgeCAD-authored parts around it. Remodel an imported feature only where a boolean against the mesh is unreliable — and say so.
-
-## Collision Policy
-
-Each returned part is real matter. Expected final collision count: **zero**.
+Keep the workflow current in the project docs. Do not advance a stage until its acceptance criteria pass, and expect to revisit earlier stages when feedback changes the design.
 
-- Only exceptions: welded, fused, overmolded, cast-in, potted, or bonded matter — declared with `verify.intentionalOverlap` on the exact visible object pair with the physical reason. The mechanical-integrity gate honors a declaration only when that pair has a confirmed exact collision; unused or non-visible declarations still fail.
-- Never use interpenetration as a placement shortcut. Model contact honestly: pins in holes, shafts in seats, tabs in slots, hinges with knuckle clearance, nested parts with wall offsets, moving parts with travel envelopes.
-- Temporary construction overlaps (oversized cutters before `difference()`, primitives before `union()`, exploratory layouts) must be consumed, hidden, named as ghosts, or isolated with `--focus`/`--hide` so final findings stay meaningful.
-- Collision removal is part of the modeling pass, not optional polish.
+### Stage 1: Design Intent
 
-## Final Acceptance Gate
+Read `references/stage-1-design-intent.md`.
 
-Prove technical validity and visual plausibility before declaring done. Apply to any model with multiple bodies, surface details, cables, rails, handles, product skins, or hidden mating geometry.
+Accepted when the project has a product/user story, PR/FAQ or equivalent design-intent doc, output standard, process assumptions, explicit success criteria, and a first feedback plan.
 
-1. **State the intended physical component graph** — one connected component, several intentionally separate, or a selected assembly plus named ghosts — then run `forgecad inspect physical components` and require the count to match. Unexpected islands, accidental fusion, or bbox-only "touching" are model bugs.
-   - Scripts using `assembly()`: `forgecad debug assembly model.forge.js --fail-on warning`. Fix warnings (multiple roots, manual joint contracts, disconnected bodies, unused connectors, collisions); a truly intentional one gets a visible reason in code.
-   - Generated mechanical work: `forgecad inspect mechanical-integrity . --collisions` is the shareability gate — it fails on missing `verify.*` interface checks, fragmented named groups, uncontracted manual assemblies, positive-volume collisions, timeouts, runtime failures. Do not share while red unless the user asked for a blockout.
-   - Include at least one verification that proves a mechanical interface (clearance band, keep-out, connector mate), not just object counts.
-   - Moving assemblies: incomplete until poses cover rest, mid-travel, both limits, coupled and mirrored states via `--joint` and/or in-script `solve(state)` checks, with convergence, attachment, and clearances holding at every pose.
-2. **Collision evidence**: run `forgecad inspect fit interference`; read the manifest collision count AND the evidence PNGs. Zero unexpected findings per Collision Policy; visually confirm where any findings appear.
-3. **Risk-specific views, not just a hero shot.** Delivery renders use the model's `scene()` rig (Scene Presentation below) — default flat lighting in a final render is a finding. One whole-model context view plus views chosen from this object's failure modes — opposing, underside, interior-facing, or grazing angles that catch internals showing through openings, covers that don't close, bad boolean cuts. Per meaningful interface: one contextual and one focused/isolated view. Risk prompts:
-   - long products, rails, handles, tools: views along and across the dominant length (bends, sag, end attachments)
-   - enclosures/shells with internals: exterior plus hidden-cover views (fit, concealment, service access)
-   - sockets, underside joins, stands, brackets: look directly into the mating face or underside; `inspect sections` for hidden geometry
-   - cables, strings, belts, tubes: both endpoints, route clearance, sag, termination hardware
-   - surface details on curved ProductSkin bodies: grazing and contextual views proving details conform or embed
-4. **Visual attachment audit.** For every detail that should be connected, ask "where does this physically enter, seat, wrap, terminate, or fasten?" and check that view directly. Known failures to fix before delivery:
-   - a flat rail or bed sitting on a curved shell instead of being recessed, saddled, socketed, or blended in
-   - strings/cables passing through space without knots, hooks, holes, posts, ferrules, pulleys, or anchors
-   - trim lines floating above the body instead of following the surface or being inset/raised strips with real thickness
-   - handles/grips touching only by a tangent instead of having a neck, bridge, socket, screws, or overmolded landing
-   - small hardware/gems that are bbox-connected but visually levitate; give them flush/inset seats or explicit brackets
-5. **ProductSkin honesty.** Boolean-test warnings from sampled-loft boundary edges are not real collisions. Deliver only if the collision count is clean, connectivity is correct, and the attachment audit passes; mention the residual warning in the final response.
-6. **Name the evidence** in the final response: commands run, views checked, joint values tested, focus/hide filters, component count, collision count, residual warnings or intentional exceptions. Never just say "validated."
+### Stage 2: Architecture Plan
 
-## Manufacturing Outputs
+Read `references/stage-2-architecture-plan.md`.
 
-A manufacture-realistic model must yield a package a shop can consume, not just a clean viewport.
+Accepted when the HLD and needed LLD/module docs define the component graph, nested file structure, interfaces, parameters, build order, and evidence gates.
 
-- Register every purchased and fabricated part with `bom()` (exact spec, quantity, purpose) so the BOM lives in the model — `forgecad export report` must reproduce it without prose supplements.
-- Put `dim()` annotations on the dimensions a builder must hit: overall envelope, critical interfaces, mating bores and bolt patterns.
-- Prove the process-appropriate export runs cleanly and name the output path in the final response: `export stl`/`export 3mf` for printed parts; `export step` for machined parts and CAD interchange; sheet-metal parts must unfold to a valid flat pattern (`export cutting-layout` for sheet goods). `step`, `report`, and `cutting-layout` need a Production license — if unavailable, run the free exports and name the gated commands that complete the package instead of failing.
-- An export failure (non-manifold body, open shell, fused multi-part blob where one fabricated part was expected) is a model bug, not an export problem.
+### Stage 3: Build Slices
 
-## Render and Inspect Cadence
+Read `references/stage-3-build-slices.md`.
 
-**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.
+Accepted when each slice or module runs in isolation, exposes clean connectors/metadata, has targeted render/inspect evidence, and updates the design docs with findings.
 
-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.
+### Stage 4: Feedback And Iteration
 
-**Keep inspection scenes small.** Return one selected configuration; include only the parts needed to prove the current risk (if a check concerns three objects, inspect those three, not the whole shop floor); prefer `--focus`/`--hide` and parameter-selected diagnostic modes over permanent extra objects; collapse proven subassemblies into fewer named objects where identity doesn't matter for collisions, masks, or contracts. If you cannot hold the scene in your head, you cannot debug it honestly.
+Read `references/stage-4-feedback-iteration.md`. Also read `references/inspection-feedback.md` for inspection bundles and `references/simulation-feedback.md` for MuJoCo, FEA, or other behavior checks.
 
-**Ghost parts for fit checks.** When a part holds or contains another object, render both with the contained object as a compact transparent named ghost — e.g. a `box()` at the seat position with `.color('#ff4444').material({ opacity: 0.4 })`, returned as `{ name: 'Servo Ghost', shape: ghost }`.
+Accepted only after automatic and manual evidence has been gathered, interpreted, and converted into model/design edits until the model behaves the way the user expects at the relevant module and system levels.
 
-Use `verify.*` for dimensions and clearances that decide acceptance; `console.log()` only for explanatory traces (shown under "Script output:" in `forgecad run`).
+### Stage 5: Readiness Package
 
-## Build Bottom-Up
+Read `references/stage-5-readiness-package.md`.
 
-You cannot target a complex model in one pass. Decompose, solve the smallest piece, verify, compose upward:
+Accepted when the final post-iteration model passes run/render/inspect evidence, plus simulation or export evidence only when requested or process-critical, carries BOM and critical dimensions, and can be reported with evidence reviewed, residual risks, and the next validation loop if anything remains unproven.
 
-1. **Decompose** into the smallest parts you can reason about confidently. A gear is not small — a single tooth profile is.
-2. **Solve one piece** in isolation: own variables, own return, no connection logic yet.
-3. **Verify it**: `forgecad run`, then render and read the PNG. Fix while the scope is tiny.
-4. **Compose one layer at a time**, verifying at each level so a break is always at the newest seam.
+## Reference Routing
 
-For any model with more than ~3 distinct geometric features, plan the decomposition explicitly before writing geometry.
+Read only what the current stage needs:
 
-## Scene Presentation
+- Stage references — the workflow acceptance gates.
+- `references/parameter-controls.md` — deciding which user-facing `param()` controls to expose, where they live, and how to validate ranges.
+- `references/module-contracts.md` — builder-first returns, preview guards, connector/data-flow rules, and assembly anti-patterns.
+- `references/inspection-feedback.md` — choosing, running, and interpreting `forgecad inspect` evidence.
+- `references/simulation-feedback.md` — MJCF/MuJoCo verification, FEA readiness, dynamic/contact checks, and behavior evidence.
+- `references/readiness-review.md` — requirement checklist, evidence caps, and final readiness reporting.
+- Core `forgecad` skill docs — API calls, CLI command syntax, generated assembly/viewport/scene/export docs, inspection bundle contracts, structural FEA, and examples.
 
-Always set up `scene()` — default lighting looks flat. Worked recipes (studio and matte-industrial setups, named views, plinth) live in `guides/scene-presentation.md` via the `forgecad` skill; the schema is in the viewport docs. Hard-won cliffs:
+## Non-Negotiable Gates
 
-- Setting `lights` replaces ALL defaults — always include an ambient light or the scene goes black.
-- Minimum rig: ambient fill + one warm key (`castShadow: true`) + weaker cool fill/rim. Keep `environment.intensity` low — environment fill kills shadows.
-- Prefer roughness over fog for softness; keep bloom near zero for mechanical parts or they read toy-like.
-- If a render is close, nudge `toneMappingExposure` by ~0.05 before redoing the rig; avoid big ambient jumps.
-- Camera: 3/4 angle, `fov` 35–50, `target` at the visual center of mass. Ground plane with shadows for grounded objects.
-- Environment by type: `studio` for metallic/jewelry, `warehouse`/`apartment` for organic/matte, `warehouse` + strong directionals for mechanical, `night` + bloom/vignette for dramatic.
+- Build the physical artifact, not a teaching diagram: no labels, callouts, cutaways, or explanatory slabs unless explicitly requested.
+- Do not treat every model as printable; choose the process stack from load path, use, scale, and operating story.
+- Use the component model for assemblies: parts build at origin, connectors position them, and data flows through the parent.
+- Prove mechanisms with motion skeletons and pose checks before attaching final geometry.
+- Use `verify.*` for dimensions, clearances, connector mates, collisions, and acceptance checks.
+- Expected final collision count is zero unless an exact intentional overlap is declared and verified.
+- Treat every failed run, render, inspect, required simulation, requested/process-critical export, or manual review finding as an iteration input. Fix the model or revise the design, then gather the same evidence again.

package/dist-skill/library/forgecad-build-model/references/inspection-feedback.md

@@ -0,0 +1,58 @@
+# Inspection Feedback
+
+Use `forgecad inspect ...` when a shaded render is too ambiguous and you need structured evidence: collision bundles, sections, wall thickness, physical components, masks, depth, normals, surface continuity, fit, or comparison overlays. Inspection is feedback for the design loop; unexpected findings are model bugs or design gaps to fix and reinspect.
+
+## Workflow
+
+1. Identify the failure question: overlap, thin walls, hidden cavity failure, disconnected or fused bodies, floating parts, wrong identity, orientation artifacts, or surface continuity.
+2. Confirm the model executes. In this repo use `node dist-cli/forgecad.js run model.forge.js`; use `--debug-imports` for suspect imports.
+3. Pick one targeted evidence command. Use `forgecad inspect evidence` and the core `forgecad` skill's CLI docs for exact syntax. For exploratory checks, pass `--output /tmp/forgecad-inspect-<slug>` when supported so default `outputs/inspect` bundles do not clutter the model folder.
+4. Summarize the manifest first, then use `jq` for targeted follow-up:
+
+   ```bash
+   python <forgecad-build-model-skill-dir>/scripts/summarize_manifest.py /tmp/model-inspect
+   ```
+
+5. Inspect the PNGs, not only JSON. Read identity/context images first, then risk evidence, then orthogonal cameras or sections when iso hides the issue.
+6. Isolate intentional overlaps with `--focus "A,B"` or `--hide "C"` so the remaining report stays meaningful.
+7. Convert findings into edits, design-doc changes, or explicit residual risks, then rerun the same command.
+8. After findings are summarized and no bundle needs to be preserved, delete transient inspection output directories created inside the model/project folder. Keep only user-requested deliverables or explicitly curated evidence.
+
+## Evidence Selection
+
+| Question | Evidence command |
+|----------|------------------|
+| Quick visual sanity | `inspect visual image` |
+| Kinematic rig, joints, axes, and links | `inspect visual rig` |
+| Object naming and identity | `inspect visual objects` |
+| Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
+| Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at\|stack\|sample` |
+| Multi-part interference, fit checks, ghost parts, moving clearances | `inspect fit interference` |
+| Printability, shell walls, ribs, bosses, snaps, slots | `inspect manufacture thickness` plus sections |
+| Parts without a mesh-contact path to the ground | `inspect physical floating` |
+| Accidental fusion, connected solids | `inspect physical components` |
+| Air gaps between physical components | `inspect physical gaps` |
+| Surface orientation, occlusion, faceting, strange protrusions | `inspect visual depth` or `inspect visual normals` |
+| Loft, fillet, skin, and sweep surface continuity | `inspect surface zebra` or `inspect visual normals` |
+| Reference-vs-candidate reconstruction comparison | `inspect compare overlay --with reference.3mf` |
+
+## Section Probe And Replay
+
+```bash
+node dist-cli/forgecad.js inspect section model.forge.js --plane yz --ray bore:-20,0:20,0 --output /tmp/forgecad-inspect-bore
+node dist-cli/forgecad.js inspect replay /tmp/forgecad-inspect-bore/result.json --source candidate.forge.js
+```
+
+The probe contract lives in the core `forgecad` skill's inspection-bundles guide.
+
+## Misread Traps
+
+- Face-touching is not a collision; collision findings are positive-volume overlaps.
+- Gray/unresolved thickness area means evidence is incomplete, not safe.
+- Distance/gap figures are bbox-gap metrics between components, not closest-surface distances.
+- Depth, normals, and zebra are visual aids, not exact measurements or curvature proofs.
+- Resolve mask colors through the manifest's object list, never by object order.
+
+## Reporting
+
+Record exact command, manifest highlights, PNG views inspected, findings, and the model/design edit made from those findings. Record bundle paths only for retained evidence; otherwise state that transient inspection outputs were removed. Never claim geometry is verified if only `forgecad run` passed.

package/dist-skill/library/forgecad-build-model/references/module-contracts.md

@@ -0,0 +1,53 @@
+# Module Contracts
+
+Use this when planning or writing multi-file ForgeCAD models.
+
+## Builder-First Modules
+
+Reusable `.forge.js` files should return builder functions or module interfaces. Direct-run preview controls belong inside `if (require.main === module)`, like Python's `if __name__ == "__main__"`.
+
+```js
+function buildMount({ wall }) {
+  const shape = box(80, 40, wall);
+  return {
+    shape,
+    boltPattern: { diameter: 5.3, positions: [[-25, 0], [25, 0]] },
+  };
+}
+
+if (require.main === module) {
+  return buildMount({ wall: param('Wall', 3) }).shape;
+}
+
+return { buildMount };
+```
+
+The parent imports the module interface and passes ordinary values:
+
+```js
+const mountModule = require('./modules/mount/motor-mount.forge.js');
+const mount = mountModule.buildMount({ wall });
+```
+
+## Assembly Contract
+
+- Build each physical module in local coordinates around its own origin.
+- Expose connectors and metadata as the module's public interface.
+- Position structural members in parent modules through connectors, `connect()`, `match()`, or `matchTo()`.
+- Route data through the parent: props flow down, computed metadata flows up. Siblings do not import each other.
+- Use `verify.*` for interface claims. Do not use `console.log()` plus `if` as validation.
+
+## Rejection Signals
+
+- `shared-dims.js` used only to coordinate siblings.
+- Sibling `require()` for placement data.
+- Assembly-space coordinates inside a child module.
+- Final `translate()` used to mate a structural part that should have a connector.
+- Bare `connector.neutral()` outside a reusable component library with compatibility checks.
+- A module whose direct-run preview returns something materially different from the builder contract imported by parents.
+
+Before advancing, ask:
+
+1. Can the module be understood without reading sibling modules?
+2. Can the module be previewed directly with `require.main === module`?
+3. Does the parent compose modules through explicit interfaces rather than hidden coordinate math?

package/dist-skill/library/forgecad-build-model/references/parameter-controls.md

@@ -0,0 +1,22 @@
+# Parameter Controls
+
+Use this when deciding which dimensions or design choices should become user-facing ForgeCAD parameters. The core `forgecad` skill remains the source of truth for exact `Param.*`, `param()`, manual parameter, CLI override, and anchor syntax.
+
+## Good Parameter Rules
+
+- Expose design decisions the user is likely to adjust: overall envelope, fit-critical clearances, material thickness, purchased-part model, pattern counts, named layout choices, mechanism positions, and presentation/cutaway states.
+- Do not expose every intermediate number. Derived offsets, trig results, fillet compensation, connector locations, and sibling-placement math should be computed from intentful parent values.
+- Put cross-cutting parameters in `main.forge.js` or the parent assembly, then pass ordinary props into child builders. Child modules may define preview-only params only under `if (require.main === module)`.
+- Use names that are stable CLI keys and readable UI labels: `Wall Thickness`, `Servo Model`, `Door Open Angle`, not `w`, `x2`, or `tweak`.
+- Provide defensible defaults, `unit`, `min`, `max`, `step`, and `integer: true` where relevant. Ranges should cover plausible use without allowing physically impossible geometry.
+- Prefer `Param.choice()` for named options, `Param.bool()` for real toggles, `Param.list()` for repeated structured items, and manual sheets (`path2d`, `spline2d`, `placement2d`) when dragging geometry is the natural editing action.
+- Add spatial anchors for parameters the user should edit from the model, especially manual sheets and fit-critical dimensions.
+- Add `verify.*` checks for parameter extremes that can break geometry, clearances, connector mates, collision assumptions, or requested export readiness.
+
+## Rejection Signals
+
+- A slider exists only because a magic number was not understood.
+- A child module owns a parameter that changes sibling fit or assembly-level layout.
+- A parameter range permits zero wall thickness, negative clearances, invalid counts, impossible angles, or unsupported purchased-part combinations.
+- Two parameters can contradict each other without validation.
+- The final model is parametric in code but not meaningfully adjustable by the user.

package/dist-skill/library/forgecad-build-model/references/readiness-review.md

@@ -0,0 +1,43 @@
+# Readiness Review
+
+Use this in Stage 5 before reporting the model ready.
+
+## Requirement Checklist
+
+Extract the user request, PR/FAQ, HLD, LLDs, and module docs into must-haves and nice-to-haves. Mark every item:
+
+| Result | Meaning |
+| --- | --- |
+| Pass | Evidence directly proves the requirement. |
+| Partial | The requirement is present but incomplete or weakly evidenced. |
+| Fail | The requirement is absent or contradicted by evidence. |
+| Unknown | The current evidence cannot verify it. |
+
+Unknowns count against readiness. Do not turn unknowns into passes because the model looks plausible.
+
+## Evidence Caps
+
+Use these as readiness gates, not as a standalone public grading skill:
+
+- Model does not execute: not ready.
+- Executes but cannot be rendered: not ready.
+- No rendered images visually inspected: not ready.
+- Only one flattering view inspected: not ready for real product delivery.
+- A must-have requirement is absent: say what is missing and what blocks readiness.
+- Visually recognizable but physically impossible for the requested use: say what physical requirement fails.
+- Internals, fit, walls, assembly behavior, or motion central to the brief but uninspected: say what still needs inspection.
+- Multi-part assembly violates the component model: say which interface or ownership rule is broken.
+- Inspection finds unexpected collisions, floating bodies, critical thin walls, or wrong connectivity: report the finding and required fix.
+- Default flat lighting, material-false coloring, or teaching-diagram styling caps the presentation until fixed.
+
+## Report Shape
+
+The final response should include:
+
+- requirement checklist summary
+- evidence reviewed: run outcome, views inspected, inspection highlights, simulation/FEA results, and requested export results if any
+- decisive strengths and remaining defects
+- readiness summary: what is proven, what remains unverified, and what next validation loop is needed
+- next fixes: the 2-5 highest-leverage improvements when not build-ready
+
+Do not return a numeric score or fixed verdict label unless the user explicitly asks for one. The normal build workflow needs evidence, not grading theater.

package/dist-skill/library/forgecad-build-model/references/simulation-feedback.md

@@ -0,0 +1,49 @@
+# Simulation And FEA Feedback
+
+Use this when dynamic behavior, contacts, controls, joint travel, load paths, or structural stress affect readiness. Successful export is not readiness; the exported package must be exercised and the evidence must feed back into design changes.
+
+## MuJoCo Workflow
+
+1. Export from the exact source file:
+
+   ```bash
+   rm -rf /tmp/forgecad-mjcf && mkdir -p /tmp/forgecad-mjcf
+   node dist-cli/forgecad.js export mjcf path/to/model.forge.js --output /tmp/forgecad-mjcf
+   ```
+
+2. Load `scene.xml`, not only a model XML, so floor/camera/package context is included.
+3. Check root behavior. Free-root models need real support/contact geometry or an explicit fixed-root export path.
+4. Check initial poses numerically; visual intuition can disagree with joint refs and connector frames.
+5. Keep meaningful collisions. Do not disable functional contacts just to make motion pass; use defensible simplified colliders when mesh contact is unstable.
+6. Define numeric acceptance before the run: expected signed travel, final velocity, stopping behavior, root drift, contact pairs, or drive cycles.
+7. Render initial, settled, and driven frames from views that show the moving parts and contact interfaces.
+8. Interpret contacts and motion; if the mechanism jitters, moves the wrong direction, overshoots, jams, falls through the floor, or contacts impossible proxy geometry, edit the model and rerun.
+
+Helper script:
+
+```bash
+uv run --python 3.11 --with mujoco --with pillow \
+  python <forgecad-build-model-skill-dir>/scripts/mujoco_verify.py /tmp/forgecad-mjcf \
+  --settle-seconds 2 \
+  --seconds 8 \
+  --actuator drum_velocity=-0.75 \
+  --watch-joint drum_joint \
+  --expect-drive-cycles drum_joint=-0.06:-0.03 \
+  --expect-final-qvel drum_joint=-0.02:0.02 \
+  --render-dir /tmp/forgecad-mjcf/verify \
+  --camera-preview-grid
+```
+
+Use `--actuator name=value` more than once for multi-actuator models. Use `--expect-drive-cycles joint=min:max` for revolute travel in cycles, `--expect-drive-delta joint=min:max` for raw MuJoCo qpos units, and `--expect-final-qvel joint=min:max` for terminal velocity.
+
+## FEA Workflow
+
+1. Use the core `forgecad` skill's structural FEA guide and generated assembly docs for `Fea.*`, `withFeaStudy(...)`, export syntax, materials, fixtures, loads, regions, and solver limits.
+2. Define the load case before export: what is fixed, what is loaded, what material is assumed, and what stress/displacement result decides readiness.
+3. Mark only bodies and regions that have real structural meaning. Do not invent fixtures, loads, or materials to make a report pass.
+4. Export and run the FEA workflow. Inspect deformation, stress concentration, reaction sanity, and mesh warnings.
+5. If results violate expectations, edit geometry, material, support, load path, or design intent, then rerun the same study.
+
+## Reporting
+
+Record export commands, verifier commands, numeric results, contact pairs, rendered frames, FEA report paths, solver warnings, and the design/model iteration they caused. Say what was not verified. Never claim simulation or build readiness when only `forgecad run`, `check simready`, or a successful export was executed.

package/dist-skill/library/forgecad-build-model/references/stage-1-design-intent.md

@@ -0,0 +1,21 @@
+# Stage 1: Design Intent
+
+Goal: turn the request into a clear design target and first feedback plan before modeling.
+
+## Sub-Workflow
+
+1. Normalize the artifact: what it is, who uses it, where it lives, what it touches, how it is assembled, how it can fail, and what "ready" means.
+2. Write `docs/PRFAQ.md` or an equivalent short design-intent doc for non-trivial work. Capture the user-facing promise, FAQ-style decisions, rejected obvious alternatives, and open questions.
+3. Create or update `NOTES.md` in the model folder for live build notes: learnings, API friction, non-obvious choices, inspection surprises, and follow-up product/API ideas.
+4. Choose the output standard: real product model, prototype-grade, production-ready, simulation-ready, printable, visual-CAD, or a user-specified process.
+5. Choose the manufacturing/process posture from load path, scale, safety, quantity, environment, and operating story. Do not default to printing.
+6. Define first-pass success criteria and feedback signals: renders, inspections, motion poses, FEA, MuJoCo, requested or process-dependent export checks, manual design review, or physical-world follow-up.
+7. Ask the user for more requirements when the missing answer changes architecture, safety, manufacturing process, mating geometry, or readiness criteria. Prefer 1-3 concise questions with good options and their tradeoffs. If the options are low-risk, choose a defensible assumption, write it down, and proceed.
+
+## Acceptance Criteria
+
+- `docs/PRFAQ.md` or a compact equivalent exists for non-trivial work.
+- `NOTES.md` exists for non-trivial work and is ready to collect build learnings and API friction.
+- Output standard, process posture, assumptions, and purchased-part boundaries are explicit.
+- The first feedback plan says what evidence will prove or falsify the design.
+- Open questions are resolved through user answers, written as safe assumptions, or identified as true blockers with the options that would unblock them.

package/dist-skill/library/forgecad-build-model/references/stage-2-architecture-plan.md

@@ -0,0 +1,23 @@
+# Stage 2: Architecture Plan
+
+Goal: define the model architecture, docs, interfaces, and evidence gates before full implementation.
+
+## Sub-Workflow
+
+1. Write `docs/HLD.md` for the high-level design: system concept, component graph, major interfaces, materials/processes, assembly story, and failure modes.
+2. Add `docs/LLD-*.md` or `docs/modules/*.md` only where the project needs lower-level decisions: complex parts, mechanisms, electronics packages, FEA regions, imported parts, simulation contracts, or manufacturing details.
+3. Plan the file tree as one nested `modules/` tree: leaf modules, composed modules, system-level `main.forge.js`. The central file should compose high-level concepts, not import every leaf.
+4. Read `module-contracts.md` and define the module contract: reusable files return builder functions, direct-run previews live under `if (require.main === module)`, parts build locally at origin, parent modules position children, and data flows down through props and up through returned metadata.
+5. Read `parameter-controls.md` and plan user-facing params: which values belong in the parent, which are preview-only, which stay derived, and which need choices, lists, manual sheets, anchors, or range checks.
+6. Define implementation order: start with profiles, constrained sketches, path/rig skeletons, imported purchased-part wrappers, or the smallest submodule that can gather useful feedback.
+7. Define evidence gates per module: run, render views, section/fit/thickness/components inspection, motion poses, simulation, FEA, requested or process-dependent exports, and manual review questions.
+
+## Acceptance Criteria
+
+- HLD exists and matches the product intent.
+- Needed LLD/module docs exist; unnecessary docs are not created.
+- `main.forge.js` is planned as the central entry point.
+- The nested file structure keeps files small and composes upward through modules.
+- User-facing params have names, defaults, units/ranges, ownership, and validation intent; non-user-facing dimensions remain derived from design intent.
+- Every important dimension, interface, and motion range has a reason or a provisional assumption.
+- The first 1-3 implementation slices and their feedback checks are named.

package/dist-skill/library/forgecad-build-model/references/stage-3-build-slices.md

@@ -0,0 +1,39 @@
+# Stage 3: Build Slices
+
+Goal: build the model in small runnable increments and gather local evidence after each increment.
+
+## Sub-Workflow
+
+1. Implement one slice at a time: profile, sketch, path, mechanism rig, imported purchased-part wrapper, leaf module, or composed module.
+2. Keep slices local. Do not hide final assembly placement inside a part file.
+3. Add builder props, preview-only params, user-facing parent params, connectors, returned metadata, `dim()`, BOM entries, and `verify.*` checks as soon as they become part of the contract.
+4. Run the slice with the local CLI:
+
+   ```bash
+   node dist-cli/forgecad.js run path/to/file.forge.js
+   ```
+
+5. Render or inspect the smallest evidence view that can falsify the slice. Read `inspection-feedback.md` for fit, wall, component, section, and identity evidence.
+6. If evidence fails, edit the model or update the design doc, then rerun the same check.
+7. Append commands, findings, design changes, and retained evidence paths to the relevant module doc. Do not keep transient inspection bundles just to document that a check ran.
+8. Append build learnings to `NOTES.md`: what was not obvious, API friction, helper/primitive gaps, inspection surprises, cleanup performed, and follow-up ideas.
+
+## Acceptance Criteria
+
+- Every added module runs standalone where practical.
+- Every structural part exposes connectors or metadata needed by its parent.
+- Siblings do not import each other; the parent routes data and parameters.
+- Good params are present for user-adjustable design decisions, with safe defaults, ranges, units, integer/choice/list/manual types where appropriate, and verification for dangerous extremes.
+- No named part contains unintentional disconnected matter.
+- Fasteners, cables, covers, handles, panels, and purchased parts have receiving geometry and a load path.
+- Each slice has enough render/inspect/manual evidence to justify moving to the next slice.
+- `NOTES.md` captures non-obvious learnings or explicitly says there were none.
+
+## Rejection Signals
+
+- A screw head without a receiving hole, boss, insert, nut, or through-stack.
+- A handle, cable, rail, or panel touching by tangent contact only.
+- A structural part positioned by final `translate()` instead of a connector or parent-level interface.
+- A user-facing `param()` that is just an unexplained magic number, or a critical design choice hidden as an uneditable constant.
+- `console.log()` used as validation where `verify.*` should encode the contract.
+- A repeated workaround, magic number, or manual trigonometry pattern that should be a ForgeCAD primitive, helper, or clearer submodule.