forgecad 0.9.15 → 0.10.0

package/dist-skill/library/forgecad-make-a-model/SKILL.md

@@ -10,591 +10,170 @@ Create new ForgeCAD models in the user's active ForgeCAD project.
 
 ## Default Output Standard
 
-Unless the user explicitly asks for a rough blockout, toy, pure visual study, mass-production release package, or specific manufacturing process, the output is a **manufacture-realistic prototype**.
+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.
 
-That means the model should look and behave like a serious prototype someone could fabricate, buy parts for, assemble, inspect, and iterate in a real shop or product lab. It is not a casual concept sketch, not a universal 3D-printing exercise, and not a claim of certified production readiness.
-
-- Choose processes that fit the artifact: machined, sheet-metal, tube, wood/composite, laser-cut, molded-look prototype, printed, or hybrid purchased-hardware construction as appropriate.
-- Include prototype-real features: wall thickness, fastener stacks, bosses, ribs, flanges, bends, seats, bushings, gaskets, cable exits, service access, toleranced clearances, and believable purchased parts.
-- Use production cues only when they help prototype realism. Do not invent expensive production tooling details, certification claims, or safety ratings unless the user asked for that level.
-- If the user asks for `production-realistic`, push toward manufacturing DFM and production-intent materials. If they ask for `printable`, make the selected printed parts honest. If they ask for `visual-CAD`, keep it clearly visual rather than pretending it is build-ready.
-- Checking for collisions and removing unexpected overlaps is part of the normal definition of done. The expected final collision count is zero except in rare, explicit cases such as welded, fused, overmolded, cast-in, potted, or bonded matter; those exceptions must be declared with `verify.intentionalOverlap(...)` or isolated with focused inspection so the remaining collision report is meaningful.
+- 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).
 
 ## File Placement
 
-All new `.forge.js` files go under the date-based directory structure:
+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 project entry point
-YYYY/MM/DD/folder/parts/*.forge.js — standalone/importable model parts
-YYYY/MM/DD/folder/lib/*.js        — pure helpers/constants only, no geometry return
+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
 ```
 
-Use today's date for the directory. Use the user's current ForgeCAD project when one is available; otherwise use a clearly named local model folder.
-
-### Naming conventions
-
-- Use kebab-case for file and folder names: `parametric-lego.forge.js`
-- Use descriptive names that communicate what the model is
-- For any multi-file project, name the runnable ForgeCAD entry point `main.forge.js`
-- Put renderable/importable parts and sub-assemblies in separate `.forge.js` files when splitting is justified; each should be standalone-runnable and importable with `require('./parts/name.forge.js', params)`.
-- Use plain `.js` files only for pure constants, math helpers, tables, or formatting code that does not construct and return ForgeCAD geometry.
-- Do not create multiple `.forge.js` files merely for organization; split only for reusable parts, large self-contained components, or independent sub-assemblies.
+- 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.
 
 ## Workflow
 
-1. Load the ForgeCAD skill — always invoke the `forgecad` skill first to get API docs and authoring guidance. Read at minimum the Core API reference. If any two parts are intended to touch or mate in the final model, read the positioning guide immediately and default to connectors + `matchTo()`.
-2. Create the directory — `mkdir -p YYYY/MM/DD/[folder]` as needed.
-3. Write the model — create the `.forge.js` file(s) following ForgeCAD conventions:
-   - Treat the default build profile as `manufacture-realistic prototype`; choose and encode the artifact's manufacturing/process cues before adding styling detail
-   - Declare `param()` / `boolParam()` for all tunable dimensions
-   - If the model is split across files, use `main.forge.js` as the primary entry point, import renderable parts from neighboring `.forge.js` files, and keep only pure helpers/constants in plain `.js` modules
-   - When there are multiple versions of the same object, expose the version as a choice parameter and render one selected version at a time
-   - Use clear variable names
-   - Build any implied internal structure as real geometry, even when it will be hidden in the final view
-   - Build the complete physical artifact first: closed shells, installed covers, real part positions, and all meaningful internal structure in place
-   - Make final mating geometry physically plausible: parts may touch, clear each other, or be boolean-joined, but should not unintentionally pass through each other
-   - Model the physical artifact, not an educational diagram: no explanatory arrows, floating labels, section labels, legends, or text plaques unless the user explicitly requested a presentation/teaching view
-   - Do not make the default returned model a cutaway, sectioned shell, permanently exploded assembly, or hidden-parts teaching view. ForgeCAD gives the user viewer and inspection tools for slicing, exploding, hiding, and looking inside after the real CAD exists.
-   - Return the final geometry (single shape, array, or named objects array)
-   - Treat `fillet(shape, r)` and `chamfer(shape, r)` as experimental edge treatments: Manifold can produce incorrect results and OCCT can be very slow. Prefer simpler primitive profiles, lower segment counts, targeted edge selectors, and inspection before relying on the result.
-4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
-5. Verify geometry — render a multi-angle visual evidence set before final delivery: whole-model context plus agent-chosen orthographic, oblique, underside, or hidden-object views that expose the relevant components and interfaces. Choose camera directions from the model's shape and likely failure modes, not from a fixed recipe. Use those views to look for internals that are accidentally visible, parts that visibly do not fit, floating details, blocked access, missing seats, and unexpected interference. Run `forgecad inspect physical components` when the model has multiple returned objects or visible attachments, run `forgecad debug assembly --fail-on warning` when the script uses `assembly()`, run `forgecad inspect mechanical-integrity <project-or-file> --collisions` before sharing generated mechanical work, and run the targeted `forgecad inspect <family> <mode>` commands that match the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`. Collision findings are model work, not FYI: remove unexpected overlaps before delivery.
-6. Iterate from visual and inspection feedback — treat every render and inspection bundle as model evidence, not a checkbox. Read the normal PNGs, manifest, and evidence PNGs; convert each unexpected collision, thin region, missing section detail, wrong component count, floating body, distance gap, confusing object-color result, accidentally exposed internal structure, bad fit, or visually unsupported interface into a concrete model edit; then rerun the same targeted evidence pass until the result matches the intended physical component graph.
-
-## Manufacturing Process Is Not Assumed
-
-Do not interpret every ForgeCAD model as a printable object.
-Choose the manufacturing/process cues that fit the artifact unless the user explicitly asked for a specific process. A manufacture-realistic prototype can be CNC-machined, bent sheet, tube-and-plate, wood/composite, molded-look low-volume, printed, or hybrid; the right answer depends on the load path and operating story.
-
-- For rideable products such as scooters, bikes, skateboards, carts, or mobility-adjacent devices, use realistic metal/composite/wood structural members, purchased wheels/bearings/axles/brakes/grips, and standard hardware unless the user asked for a printable toy/model.
-- For furniture and load-bearing structures, consider wood, sheet goods, tube, metal brackets, conventional joinery, and printed parts only where they are honest secondary components.
-- For enclosures, choose injection-molded, sheet-metal, CNC, thermoformed, printed, or hybrid cues based on quantity, ruggedness, serviceability, and the brief.
-- For fixtures and tooling, choose machined, laser-cut, welded, printed, or hybrid construction based on load, repeatability, and shop realism.
-- Use printing-specific features such as slicer clearances, support strategy, layer-oriented ribs, and heat-set inserts only when the selected process includes printed parts.
-
-## Physical Artifact, Not Teaching Diagram
-
-The deliverable is the object someone would build, assemble, inspect, or export. It is not an educational display model unless the user explicitly asks for one.
+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.
 
-- Do not add explanatory text labels, arrows, callouts, legends, section-title slabs, exploded labels, coordinate axes, or "this is the motor" plaques to production geometry.
-- Do not use in-model text to make a vague object understandable. If the geometry needs labels to be understood, make the geometry more physically specific instead.
-- Explain part roles through named return objects, clear variable names, comments, BOM entries, docs, and inspection results.
-- Product markings are allowed only when they would exist on the real artifact: serial plates, connector labels, keyboard legends, gauge ticks, warning marks, alignment marks, service arrows, scale marks, branding, or molded icons.
-- Keep real markings sparse and process-appropriate. Prefer simple recessed/raised marks or icons over heavy font geometry, especially on exact/OCCT workflows.
-- If a temporary review view needs annotations, use `Viewport.label()` or a separate debug/presentation mode, not final exported geometry.
+## Process, Style, and Variants
 
-## Visual Style Defaults
+**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.
 
-Unless the user explicitly asks for a vivid, playful, toy-like, brand-specific, or unusual colorway, default to a classic high-end product palette. The model should look expensive and credible in the first render, not generically colorful.
+**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.
 
-- Prefer restrained material-driven colors: warm ivory, bone, cream, charcoal, graphite, satin black, brushed aluminum, stainless steel, brass, bronze, muted burgundy, dark green, navy, smoked translucent polymer, frosted clear, and natural wood where appropriate.
-- Use bright colors sparingly as small accents for controls, seals, indicators, warnings, or brand-neutral identity lines.
-- Match color to material/process: anodized or powder-coated metal, molded or dyed polymer, rubber/silicone, glass/acrylic, PCB/FR4, wood grain, leather/fabric, and standard hardware should each read differently.
-- Avoid one-note rainbow/neon palettes, random saturated part colors, or color groups that make a serious artifact feel like a toy unless the brief asks for that.
-- If the object normally has user-facing markings, include only the markings that belong on the real artifact: keyboard legends, button labels, gauge ticks, icons, connector labels, alignment marks, service arrows, and scale markings. Do not leave expected production markings blank, but do not add explanatory labels just to teach the model.
-- Use color to clarify part boundaries and serviceability without hiding the engineering stack: seams, fasteners, gaskets, inserts, ports, and purchased components should remain 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 Should Be Parameter-Selected
+**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.
 
-If the model supports several sizes, styles, revisions, or option bundles of the same object, do not display all variants in the default scene. Add a `Param.choice` / choice parameter such as `Variant`, `Preset`, `Style`, or `Configuration`, and return only the selected variant's production geometry.
+## Physical Artifact, Not Teaching Diagram
 
-Comparison lineups are acceptable only as an explicit debug or presentation mode, not the default. Keep those modes behind a clearly named parameter such as `Show comparison lineup`, and keep collision inspection focused on one selected final assembly so unrelated variants cannot create false collision findings.
+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
+**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.
 
-If the requested object would have meaningful internal structure in the real artifact, model that structure too. Do not satisfy an enclosure, robot, tool, mechanism, vehicle, appliance, prop, or functional manufactured part with only an exterior shell unless the user explicitly asks for a facade or blockout.
+## Kinematics-First for Moving Parts
 
-Build hidden features as actual geometry:
+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.
 
-- Internal cavities, wall thickness, ribs, bosses, posts, brackets, ledges, and snap/latch features
-- Screw holes, inserts, bearing seats, axle paths, shaft clearances, and fastener access
-- Electronics volumes, battery bays, servo/motor pockets, wire channels, cable exits, and connector clearances
-- Mechanism clearances, travel envelopes, stops, guides, rails, hinges, gear spaces, and service access
-- Process-specific features such as bends, tubes, sheet-metal flanges, machined bosses, cast ribs, molded draft, weld tabs, laser-cut slots, or print-oriented ribs where appropriate
+- 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:
 
-Do not reveal hidden structure by permanently cutting away the production geometry. Keep the returned default model faithful to the real closed artifact, with covers installed and parts in their actual assembled positions.
+  ```bash
+  forgecad run model.forge.js --joint "theta=45"
+  forgecad render 3d model.forge.js /tmp/theta-45.png --joint "theta=45" --camera iso
+  ```
 
-When internals are hidden by the final exterior, verify them with exploration tools instead of changing the artifact: render underside or alternate camera views, use `forgecad inspect sections at|stack|sample`, use viewer-only cut planes or explode controls, temporarily make a shell transparent, or add named ghost objects for fit checks. Those views are diagnostic/presentation modes; they must not replace the real model unless the user explicitly asked for a cutaway teaching model.
+  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
 
-For mechanical models, a ForgeCAD script is not done when it merely looks assembled. Every visible piece must have a believable 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 bespoke fixed assemblies that do not match an existing `lib.*` helper, start from `examples/api/static-assembly-connectors.forge.js`: build each part in local coordinates, pick one root part, place every other touching part with `matchTo()`, and verify the mate with `verify.connectorDistance(...)`. Do not use final `translate()` calls as assembly contracts.
-- If you use `assembly().addPart()`, do not treat `addFixed()`, `addRevolute()`, or `addPrismatic()` with a manual `frame: Transform.identity().translate(...)` as a physical contract. Manual joint frames are acceptable only as a temporary scaffold. Before delivery, convert mating interfaces to connectors with `connect()` / `match()` where the interfaces physically meet, or prove the manual joint with `forgecad debug assembly --fail-on warning` and documented geometry.
-- A named assembly part should not contain unintentional disconnected bodies. If a "cover plate" contains floating pull tabs, loose screw heads, or a separate gasket, either boolean-join the manufactured features, model the fasteners/seals as separate named parts, or provide the receiving holes/lands that explain the separation.
-- Screws are not decoration. A screw needs a clearance/counterbore in the cover, a receiving threaded hole/boss or through stack in the parent, enough material around both, and aligned axes from one shared bolt pattern.
-- Handles and levers need a load path. Model the hub-to-arm connection, pivot pin/bore, thrust washers or shoulders, stops/detents where relevant, and the connected follower/contact surface. A handle tangent to a hub is a failed mechanism.
-- Covers, doors, cartridges, and service panels need seats. Model ledges, gasket grooves, bosses, snap hooks, tabs, or hinge barrels, then show how the removable part is retained.
-- Cables, wires, and tubes need receiving geometry. Model a gland, grommet, clamp, socket, ferrule, routed channel, or hose barb; do not let a cylinder end in open space.
-- Purchased loose parts may remain separate bodies, but they should be named as purchased hardware or consumables and should sit in believable sockets, bores, races, guides, or fastener stacks.
-- Encode interface intent with `verify.*`, not only comments. Use `verify.clearanceBetween("cover is seated on gasket", cover, gasket, -0.01, 0.05)` for contact/seated fits and clearance bands, `verify.minClearance(...)` or `verify.notColliding(...)` for keep-out/running gaps, and `verify.connectorDistance(...)` for connector-authored mates. Part counts and generic dimensions are useful supporting checks, but they do not prove an interface by themselves.
-
-For ordinary removable covers, prefer `lib.boltedServiceCover(...)` before hand-placing plates, tabs, screw heads, gaskets, and holes. It creates the parent ledge, gasket, cover plate with fused pull tabs, shared bolt pattern, and installed screws as one mechanically accountable interface.
-
-For electronics boxes, backplates, service-stack housings, and camera/monitor enclosures, prefer `lib.datumEnclosureAssembly(...)` before independently placing panels, ribs, bosses, ports, covers, and screws. It creates the tray, ledges, standoffs, ribs, service port, gasket, cover, and screws from one shared datum system.
-
-For PCB-mounted terminal blocks, thermostat backplates, control boards, and wire-entry electronics panels, prefer `lib.pcbTerminalBlockAssembly(...)` before placing a loose green block near a board or cover. It creates the backplate, fused standoffs, PCB mounting screws, PCB pin holes, terminal pins, and seated purchased terminal block from one shared datum system.
-
-For snap-retained covers, cartridges, small clasps, and housings, prefer `lib.snapLatchCoverAssembly(...)` before drawing decorative snap tabs. It creates latch windows, underside catch lands, fused snap hooks, barbs, and clearance checks so the cover is retained by real geometry.
-
-For ordinary pinned handles, cam levers, release levers, and latch arms, prefer `lib.pinnedLeverAssembly(...)` before hand-placing a hub, arm, washers, and pin. It creates a fused lever body, aligned pivot bore, retained pin, thrust washers, support land, and low stop land as one mechanically accountable pivot stack.
-
-For trunnions, side knobs, adjustable pivots, and clamp shafts, prefer `lib.retainedShaftAssembly(...)` before hand-placing rods, washers, and knobs. It creates bored support cheeks, a through shaft, thrust washers, knobs, retaining heads, and shared bore dimensions as one mechanically accountable stack.
-
-For thumb screws, desk clamps, vise screws, capo pressure screws, and small fixture hold-downs, prefer `lib.thumbScrewClampAssembly(...)` before hand-placing a knob, screw cylinder, pressure pad, and bracket jaw. It creates the C-frame, threaded boss/bore, captive pressure pad, hand knob, and seated workpiece contact from one shared datum system.
-
-For drawer slides, quick-release plates, and guided linear carriages, prefer `lib.capturedLinearSlide(...)` before hand-placing rails and a block. It creates a U-channel rail with return lips, end stops, a captured carriage, and explicit travel/clearance dimensions.
+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 pump cartridges, filter cassettes, battery cartridges, skeg cassettes, and removable slide-in modules, prefer `lib.capturedCartridgeGuideAssembly(...)` before placing a loose tray and block. It creates return lips, a rear stop, a captured cartridge flange, pull tab, insertion travel, and explicit clearance dimensions.
+- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`. Final `translate()` calls are not assembly contracts.
+- 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.
 
-For molded flexible battery doors, sample covers, blister latches, and polypropylene-style service flaps, prefer `lib.livingHingeCoverAssembly(...)` before drawing two plates with a decorative hinge strip. It creates one fused molded strip with fixed leaf, thin flexible web, moving cover leaf, pull lip, snap barb, catch land, and web-thickness checks.
+Treat `fillet()`/`chamfer()` as experimental (Manifold can be incorrect, OCCT slow); prefer profile-level rounding and inspect before relying on the result.
 
-For doors, barn-door leaves, lids, locket leaves, and small hinged access panels, prefer `lib.knuckledHingeAssembly(...)` before hand-placing barrels and a pin. It creates alternating fused knuckles, two leaves, a shared bore, and a retained pin as one mechanically accountable hinge.
+## Imported Parts (User-Supplied 3D Files)
 
-For crank links, damper rod ends, crossheads, and clevis-yoke pivots, prefer `lib.clevisPinJointAssembly(...)` before hand-placing an eyelet and pin. It creates bored clevis ears, a captured center link eye, a rear bridge, and a retained pin as one mechanically accountable load path.
+When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-3d-reconstruction`, a different request).
 
-For bearings, rollers, burr cartridges, spindle supports, and purchased radial bearings, prefer `lib.seatedBearingAssembly(...)` before hand-placing a ring and shaft near a block. It creates a bored housing, counterbore pocket, bearing shoulder, seated bearing, shaft, collars, and shared clearance dimensions as one mechanically accountable support.
+- 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.
 
-For cables, wires, hoses, pump tubes, and panel pass-throughs, prefer `lib.cableGlandAnchorAssembly(...)` before hand-placing a loose cylinder near a wall. It creates the panel clearance hole, hollow gland body, compression nut, and routed cable/tube as one mechanically accountable pass-through.
+## Collision Policy
 
-For routed cables, wires, hoses, pump tubes, and sensor leads that run along a surface, prefer `lib.routedTubeClipAssembly(...)` before drawing a tube that floats between endpoints. It creates a base panel, saddle clip bores, clip screw holes, installed screws, and the retained tube route from one shared datum system.
+Each returned part is real matter. Expected final collision count: **zero**.
 
-For fluid hoses, pump inlets/outlets, filter ports, and lab tubing, prefer `lib.hoseBarbPortAssembly(...)` before drawing a tube that stops at a block. It creates the bored receiver, raised boss, hollow barbed fitting, installed hose, and clamp band as one accountable hose-port interface.
-
-## Final Geometry Should Be Physically Plausible
-
-Treat each returned part as real matter occupying space. In the final build, separate parts should not intersect unless the intersection is the actual manufacturing intent, such as a welded/fused region, an overmolded insert, or a boolean-unioned solid that is no longer a separate part.
-
-Do not use final interpenetration as a placement shortcut. For joints and interfaces, model the contact, clearance, or connector honestly: pins in holes, shafts in bearing seats, tabs in slots, hinges with knuckle clearance, screws through clearance holes, nested parts with wall offsets, and moving parts with their travel envelope accounted for.
-
-Temporary collisions during construction are fine when they are part of how the model is made or verified: oversized cutter solids before `difference()`, overlapping primitives before `union()`, transparent ghost parts for fit checks, or exploratory joint layouts. Those temporary bodies should be consumed, hidden, named as ghosts, or isolated with inspection filters so final collision findings stay meaningful.
-
-If a final overlap is real manufacturing intent, document the exact visible object pair with `verify.intentionalOverlap("rubber grip is overmolded on handle core", rubberGrip, handleCore, "overmolded bonded grip")`. Use this only for welded, fused, overmolded, cast-in, potted, or bonded matter. The mechanical-integrity gate honors it only when the same visible object pair has a confirmed exact collision; unused or non-visible declarations still fail.
-
-Before delivery on any multi-part, internal, or mechanical model, run `forgecad inspect fit interference`, read the collision evidence PNGs, and check `manifest.json`. Fix unexpected overlaps; collision removal is part of the expected modeling pass, not optional polish. If a collision is intentional, declare the exact visible pair with `verify.intentionalOverlap(...)` or isolate that inspection with `--focus` / `--hide` so the remaining collision report proves the final assembly is real.
+- 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.
 
 ## Final Acceptance Gate
 
-Before telling the user the model is done, prove both technical validity and visual plausibility. A model can pass `forgecad run` and still be wrong because a rail, cable, trim line, handle, or fastener is merely hovering over a curved surface. Use this gate for any model with multiple bodies, surface-mounted details, cables/strings, rails/tracks, handles, product skins, visible hardware, or hidden mating geometry.
-
-1. State the intended physical component graph. Decide whether the final artifact should be one connected component, several intentionally separate components, or a selected assembly plus named ghosts. Then run:
-
-   ```bash
-   forgecad inspect physical components model.forge.js --camera iso
-   ```
-
-   The reported component count must match the design intent. Treat unexpected islands, accidental fusion, or bbox-only "touching" that does not make physical sense as model bugs.
-
-   If the script uses `assembly()`, also run:
-
-   ```bash
-   forgecad debug assembly model.forge.js --fail-on warning
-   ```
-
-   Fix warnings about multiple roots, manual joint contracts, disconnected bodies inside parts, unused connectors, solve warnings, and collisions before delivery. If a warning is truly intentional, rename the part or add a short code comment so a reviewer can see the physical reason.
-
-   For generated mechanical projects or batches, also run:
-
-   ```bash
-   forgecad inspect mechanical-integrity . --collisions
-   ```
-
-   This is the shareability gate. It fails on missing `verify.*` checks, missing mechanical-interface verification, fragmented named groups, uncontracted manual assemblies, positive-volume object collisions, timeouts, and runtime failures. Do not share a generated mechanical model while this gate is red unless the user explicitly asked for a rough concept/blockout.
+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.
 
-   The model should include at least one verification that proves a mechanical interface, not just object count. Prefer checks such as `verify.clearanceBetween("bearing is seated in pocket", bearing, housing, -0.01, 0.1)`, `verify.minClearance("carriage clears rail", carriage, rail, 0.15)`, `verify.notColliding("cover screw clears parent hole", screw, parent)`, or `verify.connectorDistance("leg connector is seated", bench, "Rail.leg_0", "Leg0.head", 0, 0.01)`.
+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."
 
-2. Run collision evidence and read both the manifest and images:
+## Manufacturing Outputs
 
-   ```bash
-   forgecad inspect fit interference model.forge.js /tmp/model-collisions-inspect --camera <collision-evidence-camera> --force --size 700
-   jq '.evidence.collisions | {collisionCount, collisions, warnings}' /tmp/model-collisions-inspect/manifest.json
-   ```
+A manufacture-realistic model must yield a package a shop can consume, not just a clean viewport.
 
-   `collisionCount` should be zero unless an overlap is deliberately manufactured, fused, welded, overmolded, or isolated with `--focus` / `--hide`. Do not ignore the evidence PNGs; visually inspect where the findings or warnings appear.
+- 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.
 
-3. Render risk-specific views, not only a hero shot. Build a small visual evidence set that answers the model's physical questions from more than one direction:
+## Render and Inspect Cadence
 
-   - Render one whole-model hero/context view plus the agent-chosen orthographic or oblique views that expose likely failure modes for this specific object.
-   - Use opposing, underside, interior-facing, or grazing views when they are the views most likely to catch internals accidentally showing through openings, transparent shells, thin walls, bad boolean cuts, or covers that do not actually close.
-   - Render focused views for important components or subsystems with `--focus`, especially mounts, covers, hinges, cartridges, electronics, routed cables, fastener stacks, moving links, and purchased parts.
-   - Render hidden-object views with `--hide` when an exterior shell, cover, fixture, or decorative layer blocks the interface being checked. This is for evidence only; do not turn the default returned model into a cutaway or exploded teaching scene.
-   - For each meaningful interface, capture at least one contextual view with neighboring parts present and one isolated/focused view that makes the interface easy to inspect.
+**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-render-inspect` skill and the CLI docs — this skill fixes only the cadence and the gates.
 
-   Use these risk prompts when deciding where to look:
+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.
 
-   - long products, rails, handles, and tools: choose views along and across the dominant length so bends, sag, and end attachments are visible
-   - enclosures, shells, covers, and products with internals: choose exterior and hidden-cover views that reveal whether internal structures fit, stay hidden when they should, and leave service access
-   - sockets, underside joins, stands, brackets, and handles: choose views that look directly into the mating face or underside; use `inspect sections at|stack|sample` when hidden geometry must be checked
-   - cables, strings, belts, tubes, and hoses: choose views that show both endpoints, route clearance, sag, and termination hardware
-   - surface details on curved ProductSkin bodies: choose grazing and contextual views that prove details conform or are embedded as intended
+**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.
 
-4. Do a visual attachment audit. For every detail that should be connected, ask: "Where does this physically enter, seat, wrap, terminate, or fasten?" Check that view directly. Common failures to fix before delivery:
+**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 }`.
 
-   - a flat rail or arrow bed sitting on top of a curved shell instead of being recessed, saddled, socketed, or structurally blended into the body
-   - strings/cables that pass through space without terminal knots, hooks, holes, posts, ferrules, pulleys, or anchors
-   - decorative brass/trim lines floating above the body instead of following a ProductSkin surface or being built as inset/raised strips with believable thickness
-   - handles/grips touching only by a tangent or thin face instead of having a neck, bridge, socket, screws, or overmolded landing
-   - small hardware or gems that are bbox-connected but visually read as levitating; replace with flush/inset seats or explicit brackets
+Use `verify.*` for dimensions and clearances that decide acceptance; `console.log()` only for explanatory traces (shown under "Script output:" in `forgecad run`).
 
-5. Treat ProductSkin and surface-member limitations honestly. If `inspect fit interference` reports boolean-test warnings because a sampled `Product.skin` loft has boundary edges, distinguish that from real collision findings. You may still deliver if `collisionCount` is clean, the intended connectivity is correct, and the visual attachment audit passes. Mention the residual warning briefly in the final response.
+## Build Bottom-Up
 
-6. Final response must name the evidence: commands run, render views checked, any focus/hide filters used, component count, collision count, and any residual warnings or intentional exceptions. Do not just say "validated."
+You cannot target a complex model in one pass. Decompose, solve the smallest piece, verify, compose upward:
 
-## Render-Verify Loop
+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.
 
-You are building blind unless you render. `forgecad run` only checks that code executes — it cannot tell you a hole is in the wrong place, an internal rib is poking through a cover, or a part doesn't fit. Render from different angles chosen for the model's actual geometry and look at every result.
-
-### How to render and inspect
-
-```bash
-# Render from multiple agent-chosen angles; do not stop at one hero view.
-node dist-cli/forgecad.js render model.forge.js /tmp/preview.png \
-  --camera <context-az:el> \
-  --camera <failure-mode-az:el> \
-  --camera <interface-az:el> \
-  --size 600
-
-# Camera format: --camera az:el (degrees). Repeatable.
-# Choose camera directions that prove or disprove the physical questions in this model.
-# Good evidence sets usually include a context view plus views aimed at hidden internals,
-# underside joins, mating faces, routed paths, thin walls, or surface attachments.
-```
-
-Then read the PNG(s) to inspect visually. Single camera → single file. Multiple cameras → suffixed files (`_az45_el25.png`). If any angle reveals internal geometry where the outside should be closed, a cover that does not seat, a hidden part that cannot fit, or a detail that floats/intersects, edit the model and rerender the same angles.
-
-### Focused visual evidence
-
-Use focused and hidden-object renders to collect evidence from the parts a normal hero shot hides. The goal is to answer specific physical questions: "is the cover seated?", "does the cable enter a gland?", "are the screws aligned with bosses?", "does the bracket actually touch the frame?"
-
-```bash
-# Isolate the target subsystem from several angles.
-node dist-cli/forgecad.js render model.forge.js /tmp/model-cover-stack.png \
-  --focus "Cover,Screws,Gasket,Bosses" \
-  --camera <subsystem-context-az:el> \
-  --camera <seating-interface-az:el> \
-  --camera <fastener-axis-az:el> \
-  --size 700
-
-# Hide exterior clutter to inspect the installed internals in context.
-node dist-cli/forgecad.js render model.forge.js /tmp/model-internals.png \
-  --hide "Outer Shell,Top Cover" \
-  --camera <internal-context-az:el> \
-  --camera <clearance-path-az:el> \
-  --camera <underside-or-access-az:el> \
-  --size 700
-```
-
-For important components, collect both:
-
-- Context view — neighbors present, proving the part belongs in the final assembly.
-- Focus view — only the relevant objects visible, making small gaps, intersections, missing seats, and floating parts easy to see.
-
-Prefer CLI `--focus` / `--hide` filters, named views, or parameter-selected diagnostic modes over changing production geometry. Use the object paths from `node dist-cli/forgecad.js ls model.forge.js --tree` when you are unsure what the filters should target.
-
-### Structured inspection bundles
-
-After the normal PNG render, run targeted `forgecad inspect <family> <mode>` commands and read both the evidence PNGs and `manifest.json`. Keep inspection bundles targeted to the current risk; for any multi-part final build, `inspect fit interference` is mandatory:
-
-```bash
-forgecad inspect fit interference model.forge.js /tmp/model-collisions-inspect --camera <collision-evidence-camera> --force --size 700
-```
-
-### Inspection feedback loop
-
-Use inspections as the repair loop for the model:
-
-1. Ask one physical question before each bundle: "what evidence would prove this model is wrong?"
-2. Run the smallest inspection command that can answer it. Add `inspect visual image` or `inspect visual objects` alongside the risk evidence when you need visual context or object-color lookup.
-3. Read `manifest.json` first for counts, pairs, thresholds, filters, object mappings, and warnings.
-4. Read the evidence PNGs next, using `inspect visual image` and `inspect visual objects` outputs to locate findings in the real geometry when needed.
-5. Convert findings into model edits:
-   - `collisions`: add real receiving geometry, holes, seats, clearance, connectors, or `verify.intentionalOverlap(...)` for true fused/overmolded/bonded matter only.
-   - `thickness`: change wall, rib, boss, shell, slot, or process dimensions; set material/process thresholds before accepting the result.
-   - `sections`: add or repair the hidden cavity, screw path, pocket, cable route, captured part, or internal support the slice exposed.
-   - `connectivity`, `floating`, and `distance`: fix disconnected islands, accidental fusion, unsupported bodies, or surprising gaps in the component graph.
-   - `objects`, `depth`, `normals`, and `zebra`: fix missing objects, confusing object identity, flipped/odd surfaces, faceting, protrusions, and bad surface continuity.
-6. Rerun the same targeted evidence command after the edit so the before/after evidence is comparable. Add a second evidence command only when the repaired area creates a new risk.
-
-### Keep CLI inspection scenes small
-
-When using CLI inspection commands, make the scene as few returned/named objects as the requirement allows. The goal is not to hide required geometry; it is to keep the evidence small enough that the agent can reason about it properly.
-
-- Return one selected configuration, not every variant, option bundle, or debug lineup.
-- Include only the parts, ghosts, and fixtures needed to prove the current risk. If a collision, clearance, thickness, or section check concerns three objects, inspect those three objects instead of the whole shop floor.
-- Prefer `--focus` / `--hide` and parameter-selected diagnostic modes over adding permanent extra objects to the default scene.
-- Collapse decorative or already-proven subassemblies into fewer named objects when their internal boundaries are irrelevant to the inspection. Keep separate names only where object identity matters for collisions, masks, clearances, BOM roles, or mechanical contracts.
-
-Small inspection scenes make `manifest.json`, mask colors, collision pairs, component counts, and section images cognitively tractable. If the agent cannot hold the scene in its head, it cannot debug the model honestly.
-
-For faster iteration, request the evidence that matches the current risk:
-
-- `inspect fit interference` — final multi-part assemblies, fixtures, enclosures, ghost fit checks, moving clearances, and any parts intended to touch without overlapping. Visually inspect this evidence; do not rely only on the count.
-- `inspect manufacture thickness` — printed shells, sheet metal, molded walls, ribs, bosses, holes, snap fits, slots, brackets, and any feature where thin walls can fail. Set thresholds for the selected material/process instead of blindly accepting defaults.
-- `inspect sections at|stack|sample` — hidden internals, cavities, wire channels, pockets, screw paths, captured components, and anything a surface render cannot show.
-- `inspect physical components` — parts that should be one connected solid, parts that should remain separate, and assemblies where floating or accidentally fused bodies matter.
-- `inspect physical floating` and `inspect physical gaps` — loose bodies, unsupported bodies, or surprising gaps in the component graph.
-- `inspect visual objects` — object identity, missing named parts, duplicate geometry, hidden mocks, and color/name confusion.
-- `inspect visual depth` / `inspect visual normals` / `inspect surface zebra` — occlusion, orientation, flipped surfaces, odd protrusions, faceting, and surface continuity.
-- `inspect visual image` — the human-readable view that keeps structured evidence grounded.
-
-Useful manifest checks:
-
-```bash
-jq '.evidence.collisions | {collisionCount, collisions, warnings}' /tmp/model-inspect/manifest.json
-jq '.evidence.thickness.objects[] | {name, minThickness, p05Thickness, criticalAreaPercent, warningAreaPercent, unresolvedAreaPercent}' /tmp/model-inspect/manifest.json
-jq '.evidence.connectivity | {componentCount, edges, warnings}' /tmp/model-inspect/manifest.json
-```
-
-Treat unexpected collision findings, critical thin regions, high unresolved thickness, missing sections, or wrong component counts as model bugs. If an overlap is intentional, make that explicit in the model or isolate the inspection with `--focus` / `--hide` so the remaining findings are meaningful:
-
-```bash
-forgecad inspect fit interference model.forge.js /tmp/model-fit-collisions --focus "Bracket,Screw Ghost" --camera <fit-evidence-camera> --force
-forgecad inspect sections sample model.forge.js /tmp/model-fit-sections --plane yz --count 5 --focus "Bracket,Screw Ghost" --force
-forgecad inspect manufacture thickness model.forge.js /tmp/model-thickness --min 1.6 --warn 2.4 --camera <thickness-evidence-camera> --force
-```
-
-### When to render
-
-- After every feature addition (not just at the end)
-- After any boolean subtraction that creates a hole/pocket
-- After placing symmetric copies (to check symmetry)
-- After adding the last feature (final check)
-
-### When to inspect
-
-- After adding hidden/internal geometry that a surface render cannot prove
-- After adding or moving mating parts, ghosts, connectors, holes, pockets, or clearances
-- After adding thin walls, ribs, slots, snap features, bosses, or screw holes
-- Before final delivery, with the evidence that matches the remaining risks, and with thresholds appropriate to the model
-
-### Ghost parts for fit verification
-
-When building a part that holds/contains another object (enclosure, mount, bracket), render both together with the contained object transparent:
-
-```js
-// Ghost servo for visual fit check
-const ghost = box(servoW, servoD, servoH)
-  .placeReference('center', [0, 0, wallThick])
-  .color('#ff4444').material({ opacity: 0.4 });
-
-return [
-  { name: 'Mount', shape: mount.color('#556B2F') },
-  { name: 'Servo Ghost', shape: ghost },
-];
-```
-
-This immediately reveals: does it fit? Does it collide with walls? Does the shaft clear the opening?
-
-### Use verify for acceptance, console.log for traces
-
-Use `verify.*` for dimensions and clearances that decide whether the model is acceptable. Use `console.log()` only for explanatory traces that help you read the run output.
-
-```js
-verify.greaterThan("wall remains around slot", (outerW - slotW) / 2, 1.6);
-verify.greaterThan("hole clears flange edge", flangeW / 2 - holeX - holeDia / 2, 2.0);
-console.log("wall remaining:", ((outerW - slotW) / 2).toFixed(1));
-```
-
-Output appears under "Script output:" in `forgecad run`.
-
-### Self-inspecting shared constants
-
-For multi-file projects with a shared constants file (e.g. `shared-dims.js`), add a summary block that prints all computed values when the file is run directly. This replaces one-off throwaway debug scripts.
-
-```js
-// At the bottom of shared-dims.js:
-if (require.main === module) {
-  console.log('=== SERVO ===');
-  console.log('  body:', servo.bodyW, '×', servo.bodyD, '×', servo.bodyH, 'mm');
-  // ... all computed dimensions, clearance checks, etc.
-  console.log('✓ All validations passed.');
-}
-```
-
-Run with `node shared-dims.js` to see the full dimension summary. Don't write throwaway `node -e "require(...)..."` scripts — put the inspection logic in the source file itself where it stays up to date automatically.
-
-## ForgeCAD Quick Reference
-
-The `forgecad` skill has full API docs.
-
-Key primitives:
-
-- `box(x, y, z)`, `cylinder(h, r, rTop?, segments?)`, `sphere(r)`, `torus(R, r)`
-- `union()`, `difference()`, `intersection()`
-- `.fillet()`, `.chamfer()` for experimental edge treatments only
-- `param(name, default, opts)`, `boolParam(name, default)`
-- Return `[{ name, shape, color }]` for multi-part colored models
-
-Primitive placement convention:
-
-- `box()` and `cylinder()` are centered in X/Y and sit on `z=0`.
-- `sphere()` and `torus()` are centered in X/Y/Z.
-- Use `.placeReference('center', [0, 0, 0])` when a box or cylinder should be centered around the origin.
-- Do not pass `center: true` or a positional `true` to primitives; that is stale OpenSCAD-style guidance.
-
-Key composition tools:
-
-- Connectors + `matchTo()` for parts that should touch in the final model
-- `group()` for local-coordinate subassemblies
-- `attachTo()` for quick bounding-box placement
-- `.translate()` / `.rotate()` for free offsets or bridging computed locations, not as the default assembly contract
-
-## Managing Complexity: Build Bottom-Up
-
-You cannot target a complex model directly. A chess set, a mechanical assembly, an articulated figure — if you try to write the whole thing in one pass, you will get lost in coordinate math, produce subtle geometry bugs, and waste cycles debugging a tangled script.
-
-Instead, do what engineers do: decompose, solve the smallest piece, verify, then compose upward.
-
-### The process
-
-1. Decompose — Break the model into the smallest independent parts you can reason about confidently. A "gear" is not a small part — a single tooth profile is. A "house" is not small — a wall panel with a window cutout is.
-
-2. Solve the smallest piece — Write the geometry for one part. Keep it isolated: its own variables, its own return statement. Don't think about how it connects to the rest yet.
-
-3. Verify — Run `forgecad run` to check for errors, then `forgecad render` to actually see the shape. Read the rendered PNG. Does it match your intent? Are holes where they should be? Are walls thick enough? Fix it now while the scope is tiny. `forgecad run` passing does not mean the geometry is correct — it only means the code didn't crash.
-
-4. Compose upward — Once a piece is verified, combine it with the next piece. Verify again. Each level of assembly should be independently checkable.
-
-5. Repeat — Keep climbing. Each step adds one layer of complexity on top of verified foundations. If something breaks, you know it's in the new layer, not buried three levels deep.
-
-### Why this matters
-
-- Debugging is local. When a verified piece breaks after composition, the bug is at the seam, not inside the piece.
-- You avoid coordinate chaos. Small pieces use simple local coordinates. Transforms and placements happen at composition time, one layer at a time.
-- Iteration is cheap. Changing a tooth profile doesn't require re-reading 200 lines of gear assembly code.
-
-### In practice
-
-For a model with more than ~3 distinct geometric features, explicitly plan the decomposition before writing any geometry. Write each piece as a function or variable block, verify it, then combine. Do not skip verification steps to "save time" — it costs more time in the end.
+For any model with more than ~3 distinct geometric features, plan the decomposition explicitly before writing geometry.
 
 ## Scene Presentation
 
-Always set up a proper `scene()` to make models look polished. A bare model with default lighting looks flat and unfinished.
-
-### Minimum scene setup
-
-Every model should have at least:
-
-```js
-scene({
-  background: { top: '#1a1a2e', bottom: '#0a0a14' },
-  camera: { position: [x, y, z], target: [0, 0, 0], fov: 42 },
-  environment: { preset: 'studio', intensity: 0.6 },
-  lights: [
-    { type: 'ambient', color: '#c8cdd4', intensity: 0.15 },
-    { type: 'directional', position: [80, -60, 120], target: [0, 0, 0], color: '#fff4e0', intensity: 1.8, castShadow: true },
-    { type: 'directional', position: [-60, 40, 80], target: [0, 0, 0], color: '#b0c4de', intensity: 0.7 },
-  ],
-  ground: { visible: true, color: '#111118', height: -10, receiveShadow: true },
-  postProcessing: {
-    bloom: { intensity: 0.3, threshold: 0.85, radius: 0.3 },
-    vignette: { darkness: 0.5, offset: 0.4 },
-    toneMappingExposure: 1.3,
-  },
-});
-```
-
-### Named render views
-
-For models that need repeatable review, docs, or hero renders, declare named views inside
-`scene({ views })`. The canonical form wraps each camera in `{ camera: ... }`; direct camera
-shorthand is accepted by the runtime, but the wrapped form is the clearest prompt/example shape.
-
-```js
-scene({
-  camera: { position: [430, -540, 340], target: [0, 30, 125], fov: 38 },
-  views: {
-    hero: {
-      camera: { position: [430, -540, 340], target: [0, 30, 125], up: [0, 0, 1], fov: 38 },
-    },
-    side: {
-      camera: { position: [700, 0, 180], target: [0, 30, 100], up: [0, 0, 1], fov: 32 },
-    },
-  },
-});
-```
-
-Render one later with:
-
-```bash
-forgecad render 3d model.forge.js --view hero
-```
-
-### Lighting principles
-
-- When `lights` is set, all defaults are replaced, so always include an ambient light or the scene goes black.
-- Use a 3-point setup at minimum: ambient fill + warm key light (with `castShadow: true`) + cool rim/back light for edge separation.
-- Add accent point lights near focal features (e.g. a gold crown, a polished surface) for highlights.
-- Use `distance` and `decay` on point lights to keep them localized.
-
-### Adapt to the model
-
-- Metallic/jewelry models: `studio` environment, higher `toneMappingExposure` (1.2–1.5), subtle bloom for specular highlights.
-- Organic/wood/matte models: `warehouse` or `apartment` environment, lower bloom, warmer ambient.
-- Mechanical/industrial models: `warehouse` environment, stronger directional lights, minimal bloom.
-- Dark/dramatic models: dark gradient background, `night` environment, bloom + vignette for mood.
-
-### Matte industrial hero-shot recipe
-
-For mechanisms, tools, product prototypes, vehicles, and other industrial showpieces, prefer a matte studio look over glossy or atmospheric drama:
-
-```js
-scene({
-  background: { top: '#c3ccd7', bottom: '#566474' },
-  camera: { position: [430, -540, 340], target: [0, 30, 125], fov: 38 },
-  environment: { preset: 'studio', intensity: 0.15 - 0.25, background: false },
-  lights: [
-    { type: 'ambient', color: '#efe7dc', intensity: 0.12 - 0.2 },
-    { type: 'directional', position: [260, -320, 420], color: '#ffe2bf', intensity: 2.6 - 3.2, castShadow: true },
-    { type: 'directional', position: [-260, 210, 220], color: '#d4e6fb', intensity: 0.7 - 1.0 },
-    { type: 'hemisphere', skyColor: '#c7d3df', groundColor: '#495463', intensity: 0.1 - 0.2 },
-  ],
-  postProcessing: {
-    bloom: { intensity: 0.0 - 0.06, threshold: 0.92 - 0.96, radius: 0.25 - 0.3 },
-    vignette: { darkness: 0.35 - 0.45, offset: 0.3 - 0.35 },
-    toneMappingExposure: 1.05 - 1.18,
-  },
-});
-```
-
-Use a simple plinth or stage under the model, and make it intentionally matte too:
-
-```js
-const stage = cylinder(16, 226)
-  .translate(0, 0, -26)
-  .color('#8b97a4')
-  .material({ metalness: 0.04, roughness: 0.78 });
-
-mock(stage, 'StudioPlinth');
-```
-
-What worked well in practice:
-
-- Keep `environment.intensity` low. High environment fill kills shadows and makes everything look washed out.
-- Let one warm directional key light do most of the shaping. Add only a weaker cool fill/rim for separation.
-- Prefer roughness over fog for softness. Fog flattens the model and hides form; matte materials preserve shadow definition.
-- Keep bloom extremely low for mechanical scenes. A little is fine; too much makes manufactured parts feel toy-like or overly glossy.
-- If the render is close but not perfect, change `toneMappingExposure` by about `0.05` first before redoing the whole lighting rig.
-- Avoid large ambient-light jumps. They brighten fast and remove contrast faster than expected.
-
-### Ground plane
-
-Enable `ground` with `receiveShadow: true` for models that benefit from visual grounding (furniture, vehicles, standalone objects). Skip it for floating/abstract geometry.
-
-### Camera
-
-- Position the camera at a 3/4 angle (not dead-on axis) for natural perspective.
-- Use `fov` 35–50 for most models. Lower FOV = more telephoto/flatter, higher = more dramatic perspective.
-- Set `target` to the visual center of mass, not necessarily `[0,0,0]`.
-
-## Tips
+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:
 
-- Make models parametric by default — dimensions should be `param()` calls, not magic numbers
-- Do not assume primitives are XYZ-centered: `box()` and `cylinder()` are XY-centered but sit on `z=0`
-- Use `.placeReference('center', [0, 0, 0])` for full-origin-centered boxes or cylinders
-- Prefer `group()`, connectors, and `placeReference()` over manual half-height arithmetic
-- Prefer `difference()` for holes/cutouts, `union()` for additive features
-- Use `.color()` to distinguish parts visually
+- 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.