forgecad 0.10.4 → 0.11.0

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

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

package/dist/docs-raw/skills/forgecad-build-model.md

@@ -2,7 +2,7 @@
 
 # forgecad-build-model
 
-Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence.
+Build or edit `.forge.js` real product models through design, automatic/manual feedback gathering, inspection/simulation/FEA evidence, and iteration until ready.
 
 | Field | Value |
 | --- | --- |
@@ -13,184 +13,107 @@ Build or edit a manufacture-realistic `.forge.js` model in a project, then valid
 
 ## 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).
+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.
 
-- 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.
+#### Stage 1: Design Intent
 
-### Collision Policy
+Read `references/stage-1-design-intent.md`.
 
-Each returned part is real matter. Expected final collision count: **zero**.
+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.
 
-- 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 2: Architecture Plan
 
-### Final Acceptance Gate
+Read `references/stage-2-architecture-plan.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 HLD and needed LLD/module docs define the component graph, nested file structure, interfaces, parameters, build order, and evidence gates.
 
-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 3: Build Slices
 
-### Manufacturing Outputs
+Read `references/stage-3-build-slices.md`.
 
-A manufacture-realistic model must yield a package a shop can consume, not just a clean viewport.
+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.
 
-- 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 4: Feedback And Iteration
 
-### Render and Inspect Cadence
+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.
 
-**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 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.
 
-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 5: Readiness Package
 
-**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-5-readiness-package.md`.
 
-**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 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.
 
-Use `verify.*` for dimensions and clearances that decide acceptance; `console.log()` only for explanatory traces (shown under "Script output:" in `forgecad run`).
+### Reference Routing
 
-### Build Bottom-Up
+Read only what the current stage needs:
 
-You cannot target a complex model in one pass. Decompose, solve the smallest piece, verify, compose upward:
+- 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.
 
-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.
+### Non-Negotiable Gates
 
-For any model with more than ~3 distinct geometric features, plan the decomposition explicitly before writing geometry.
+- 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.
 
-### Scene Presentation
 
-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:
+## Bundled Files
 
-- 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.
+- `references/inspection-feedback.md`
+- `references/module-contracts.md`
+- `references/parameter-controls.md`
+- `references/readiness-review.md`
+- `references/simulation-feedback.md`
+- `references/stage-1-design-intent.md`
+- `references/stage-2-architecture-plan.md`
+- `references/stage-3-build-slices.md`
+- `references/stage-4-feedback-iteration.md`
+- `references/stage-5-readiness-package.md`
+- `scripts/mujoco_verify.py`
+- `scripts/summarize_manifest.py`

package/dist/docs-raw/skills/forgecad-image-prompt.md

@@ -15,7 +15,7 @@ Write builder-honest AI image prompts from a concrete ForgeCAD model, build brie
 
 ### Scope
 
-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.
+Only for artifacts already concrete enough to visualize (a specific `.forge.js` model, build brief, or HLD). If the user wants a model after the prompt, route vague physical briefs to `forgecad-build-model` so its design stages own the build. 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
 

package/dist/docs-raw/skills/forgecad-project-sync.md

@@ -13,12 +13,12 @@ Manage hosted ForgeCAD project sync from the CLI: init, clone, pull, push, file
 
 ## 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.
+forgecad.io is the hosted ForgeCAD platform; a project is a local folder marked by `forgecad.json`, and linked to the server after its first push. 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.
 
 - **One studio process.** Run a single long-running `forgecad studio <folder> [<folder> ...]` naming every active project folder. The user opens the one printed localhost port once; create and edit files only under those folders so the browser live-updates. Never spawn extra servers per project.
 - **studio vs dev.** `forgecad studio` is for users and agents; `forgecad dev` is only for developing ForgeCAD itself.
-- **Login only for hosted commands.** `forgecad login` before any `project`/`publish` command; local work (run, render, studio) needs no auth.
-- **init creates, push syncs.** `project init "Name"` creates the remote project, writes `forgecad.json`, and pushes existing local files. `push` only syncs an already-initialized project. `clone <slug>` is the inverse: remote → new local folder.
+- **Login only for hosted commands.** `project init` plus local work (run, render, studio) need no auth. Run `forgecad login` before hosted sync/admin commands such as `project push`, `project pull`, `project file *`, members, shares, and `publish`.
+- **init is local, push creates remote.** `project init "Name"` writes local project metadata to `forgecad.json` without contacting the server. The first `project push` creates the hosted project if `forgecad.json` has no project ID yet, uploads existing local files, and records server file IDs. Later pushes sync the already-linked project. `clone <slug>` is the inverse: remote → new local folder.
 - **Sync is content-hash based.** `status`/`push`/`pull` compare file content hashes — no timestamps, no git; a file is "modified" purely by content difference. Loop: edit → `project status` → `project push`.
 - **Sync vs single-file ops.** Use `status`/`pull`/`push` for normal sync; use `project file <read|save|delete|...>` only for one hosted-file operation without a full push/pull cycle.
 - **Project context required.** All `project file *` and `publish` commands must run inside a folder containing `forgecad.json`.

package/dist/docs-raw/skills/forgecad-reconstruct-cad-file.md

@@ -15,7 +15,7 @@ Reconstruct a readable parametric ForgeCAD model from an existing CAD or mesh fi
 
 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-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.
+Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-build-model`, not this skill; prepared benchmark/RL episodes → use the task-local benchmark instructions, not the public skill library; inspection-bundle interpretation → `forgecad-build-model/references/inspection-feedback.md`; readiness review → `forgecad-build-model/references/readiness-review.md`; API and command reference → `forgecad` skill + CLI.md.
 
 ### Workflow
 
@@ -50,7 +50,7 @@ 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-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.
+The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects using `forgecad-build-model`'s inspection feedback reference 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.
 
 
 ## Bundled Files

package/dist/docs-raw/skills/forgecad-reconstruct-from-images.md

@@ -18,9 +18,8 @@ The reference image is evidence, not the deliverable. The deliverable is a real
 ### Companion Skills
 
 - `forgecad` — API docs, model authoring, renderer behavior.
-- `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.
+- `forgecad-build-model` — design stages, file placement, project structure, decomposition, definition of done.
+- `forgecad-build-model/references/inspection-feedback.md` — pre-delivery inspection for multi-part, internal, mechanical, thin-wall, or fit-sensitive objects.
 
 ### Core Rule
 
@@ -30,13 +29,13 @@ 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-design-spec` when these are underdetermined.
+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. Follow `forgecad-build-model` design stages 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-inspect-model`.
+9. Validate the final object: `forgecad run`, reference comparison boards, canonical renders, and targeted inspections via `forgecad-build-model`'s inspection feedback reference.
 
 ### Comparison Boards