forgecad 0.10.5 → 0.11.0

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
 

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

@@ -30,7 +30,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 #### Import and Composition
 
-- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Always include the extension in relative imports: `require("./file.forge.js")` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Reusable `.forge.js` part files should return builder functions such as `return { buildPart }`; direct-run preview params belong inside `if (require.main === module)`.
 - ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; never destructure those names from helpers (`const { bom } = require("./bom.js")`). Import helper files under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use it only when you need `ShapeGroup` composition, transforms, or named-child lookup.
@@ -48,6 +49,7 @@ Execution model, colors, coordinate system, primitives, booleans, patterns, impo
 
 - `docs/skill/API/core/concepts.md`
 - `docs/skill/generated/runtime-names.md`
+- `docs/skill/guides/manual-parameters.md`
 - `docs/skill/generated/core.md`
 
 #### 2. Static Assembly and Positioning (for any multi-part model)

package/dist/docs-raw/skills/index.md

@@ -11,12 +11,8 @@ forgecad skill install
 | Skill | Installed by | Purpose |
 | --- | --- | --- |
 | [forgecad](/docs/skills/forgecad) | `forgecad skill install` | ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, validating scripts, or using ForgeCAD export/render tooling. |
-| [forgecad-build-model](/docs/skills/forgecad-build-model) | `forgecad skill install` | Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence. |
-| [forgecad-design-spec](/docs/skills/forgecad-design-spec) | `forgecad skill install` | Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification. |
-| [forgecad-grade-model](/docs/skills/forgecad-grade-model) | `forgecad skill install` | Grade a ForgeCAD or CAD-as-code model against a requirement, brief, prompt, reference, or acceptance criteria with evidence and a 0-10 score. |
+| [forgecad-build-model](/docs/skills/forgecad-build-model) | `forgecad skill install` | Build or edit `.forge.js` real product models through design, automatic/manual feedback gathering, inspection/simulation/FEA evidence, and iteration until ready. |
 | [forgecad-image-prompt](/docs/skills/forgecad-image-prompt) | `forgecad skill install` | Write builder-honest AI image prompts from a concrete ForgeCAD model, build brief, HLD, or LLD without hiding how the artifact is built. |
-| [forgecad-inspect-model](/docs/skills/forgecad-inspect-model) | `forgecad skill install` | Select, run, and interpret ForgeCAD inspection evidence for collisions, sections, wall thickness, components, masks, depth, normals, surface continuity, and fit. |
 | [forgecad-project-sync](/docs/skills/forgecad-project-sync) | `forgecad skill install` | Manage hosted ForgeCAD project sync from the CLI: init, clone, pull, push, file operations, members, publishing, and shares. |
 | [forgecad-reconstruct-cad-file](/docs/skills/forgecad-reconstruct-cad-file) | `forgecad skill install` | Reconstruct a readable parametric ForgeCAD model from an existing CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP. |
 | [forgecad-reconstruct-from-images](/docs/skills/forgecad-reconstruct-from-images) | `forgecad skill install` | Reconstruct a real parametric ForgeCAD object from reference images by using images as evidence, not as a one-view facade. |
-| [forgecad-verify-mujoco](/docs/skills/forgecad-verify-mujoco) | `forgecad skill install` | Verify a ForgeCAD MJCF export in MuJoCo with dynamics, contacts, controls, joint travel, and rendered evidence before calling it simulation-ready. |

package/dist/docs-raw/welcome.md

@@ -39,7 +39,6 @@ Use this when you want a fresh model instead of the starter project:
 
 ```bash
 npm install -g forgecad
-forgecad login
 mkdir spool-adapter
 cd spool-adapter
 forgecad project init "Spool Adapter" --visibility private
@@ -47,7 +46,7 @@ forgecad new adapter --template part
 forgecad studio .
 ```
 
-`forgecad project init` creates the hosted project, writes `forgecad.json`, and uploads existing local model files, helper code, Markdown notes, SVG/DXF assets, and other supported text project files. After that, `forgecad project push` syncs changes back to the hosted project.
+`forgecad project init` writes local project metadata to `forgecad.json`; it does not create anything on the server. After local validation, run `forgecad login` and `forgecad project push`. The first push creates the hosted project if needed, uploads local model files, helper code, Markdown notes, SVG/DXF assets, and other supported text project files, then records server file IDs.
 
 `forgecad project push` does not create a remote project from an arbitrary folder. If a folder has no `forgecad.json`, initialize it with `forgecad project init` or clone an existing project first.
 
@@ -57,10 +56,10 @@ ForgeCAD commands need a project root so imports, helper files, SVGs, and genera
 
 A single loose `.forge.js` file is fine for a tiny experiment, but it is not the best workflow for useful AI-generated CAD. A project folder gives the agent and CLI enough context to work well:
 
-- `forgecad.json` links the folder to the hosted project.
+- `forgecad.json` marks the project root locally, and links it to the hosted project after the first push.
 - `.forge.js`, helper code, Markdown notes, and SVG/DXF assets stay together.
 - `forgecad run` and render commands resolve local imports from the intended root.
-- `forgecad project push` knows exactly which remote project to update.
+- `forgecad project push` knows when to create the hosted project, then which remote project to update afterward.
 - Inspection bundles, screenshots, and export outputs can live beside the model without mixing with unrelated files.
 
 Bad roots create bad results. Pointing ForgeCAD or an AI agent at `~`, a monorepo, or a downloads folder can make file discovery slow, confusing, or effectively unusable. Start small and intentional:

package/dist/index.html

@@ -83,7 +83,7 @@
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body, #root { width: 100%; min-height: 100%; background: var(--fc-bg); color: var(--fc-text); font-family: system-ui, -apple-system, sans-serif; }
     </style>
-    <script type="module" crossorigin src="/assets/app-xW3hOdq9.js"></script>
+    <script type="module" crossorigin src="/assets/app-BKjogwIZ.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/app-CjsbDlb7.css">
   </head>
   <body>

package/dist/llms.txt

@@ -41,8 +41,7 @@ For coding agents, start with the welcome guide and AI Usage guide, then read th
 
 - [ForgeCAD modeling skill](https://forgecad.io/docs-raw/skills/forgecad.md): Core agent guidance for authoring, editing, debugging, and validating ForgeCAD geometry.
 - [Skill library index](https://forgecad.io/docs-raw/skills/index.md): Overview of the public agent workflows shipped with ForgeCAD.
-- [Build model](https://forgecad.io/docs-raw/skills/forgecad-build-model.md): Workflow for creating or editing `.forge.js` models, including assembly discipline and validation.
-- [Design spec](https://forgecad.io/docs-raw/skills/forgecad-design-spec.md): Workflow for turning fuzzy physical artifact requests into concrete briefs, HLDs, and LLDs.
+- [Build model](https://forgecad.io/docs-raw/skills/forgecad-build-model.md): Design-first workflow for creating or editing `.forge.js` models, including staged implementation, assembly discipline, and validation.
 - [Inspect model](https://forgecad.io/docs-raw/skills/forgecad-inspect-model.md): Workflow for checking collisions, wall thickness, sections, masks, depth, and normals.
 - [Grade model](https://forgecad.io/docs-raw/skills/forgecad-grade-model.md): Workflow for scoring a model against a prompt, brief, reference, or acceptance criteria.
 

package/dist/sitemap.xml

@@ -2,91 +2,91 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://forgecad.io/</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/ai-native-cad</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.9</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/ai-usage</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/cli</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/simready-quickstart</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/simulation-workflow</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs/skills/forgecad-build-model</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
   <url>
     <loc>https://forgecad.io/benchmark</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://forgecad.io/pricing</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.5</priority>
   </url>
   <url>
     <loc>https://forgecad.io/terms</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>yearly</changefreq>
     <priority>0.3</priority>
   </url>
   <url>
     <loc>https://forgecad.io/privacy</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>yearly</changefreq>
     <priority>0.3</priority>
   </url>
   <url>
     <loc>https://forgecad.io/license</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>yearly</changefreq>
     <priority>0.3</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog/hello-forgecad-io</loc>
-    <lastmod>2026-06-18</lastmod>
+    <lastmod>2026-06-20</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.5</priority>
   </url>

package/dist-cli/{check-compiler-7YAHVXYM.js → check-compiler-UJWUEIDC.js}

@@ -9,7 +9,7 @@ import {
   resolvePackagePath,
   runDirectCliMain,
   setActiveBackend
-} from "./chunk-VNM67DIV.js";
+} from "./chunk-MNDROM7T.js";
 
 // cli/check-compiler.ts
 import assert from "assert/strict";

package/dist-cli/{check-query-propagation-ZRR6IOJW.js → check-query-propagation-O2EPDJSY.js}

@@ -12,7 +12,7 @@ import {
   resolvePackagePath,
   runDirectCliMain,
   setActiveBackend
-} from "./chunk-VNM67DIV.js";
+} from "./chunk-MNDROM7T.js";
 
 // cli/check-query-propagation.ts
 import assert from "assert/strict";