forgecad 0.9.16 → 0.10.1

package/dist/docs-raw/guides/joint-design.md

@@ -5,98 +5,37 @@ skill-order: 5
 
 # Joint Design Recipes
 
-How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
+Geometry recipes for joints that actually rotate without binding — clevis-tongue hinges, hinge chains, hard stops.
 
-## Frame-Aware Connectors First
-
-If a part must rotate, slide, or point in a specific physical direction, define connectors and use `assembly().connect()`. A connector is a small coordinate frame on the part:
-
-- `origin` is the pivot, pin center, socket center, or contact point.
-- `axis` is the hinge line or slide direction.
-- `up` is the secondary direction that fixes the part's zero-angle twist.
-
-For a hip -> knee -> wheel chain, the upper leg should be a real part with a hip connector and a knee connector. The hip connector frame defines how the upper leg sits on the hip drum at rest; the knee connector frame defines where the next part attaches. `connect()` aligns those frames and derives the joint axis.
-
-Do not treat `up` as optional on hinges, wheels, levers, or keyed sliders. If `up` is omitted, ForgeCAD chooses a deterministic perpendicular vector, which keeps the model stable but may not match the intended mechanical rest pose.
-
-Use `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()` for solved point skeletons and closed-loop relationships. A link is a point, not a bone frame. `addPart(..., { mate: { connector, toLink } })` only moves a connector origin onto a solved link point; it does not rotate the part to aim along an edge.
-
-## Mirrored Revolute Axes
-
-Revolute joint values are physical values signed by the right-hand rule around the joint axis. If a bilateral mechanism mirrors a hinge axis, the same numeric joint value does not mean "same pose" on both sides.
-
-Example: a right ankle hinge with `axis: [1, 0, 0]` and a left ankle hinge with `axis: [-1, 0, 0]` are exact geometric mirrors at rest. But `+20` degrees around those two axes rotates the feet in opposite fore/aft senses. The mirrored pose uses `RightAnkle: 20` and `LeftAnkle: -20`.
-
-When you expose physical joint limits directly, mirror revolute limits as `[min, max] -> [-max, -min]`. Prismatic joints do not have this angle-handedness flip because their scalar value translates along the mirrored axis.
-
-For bilateral robots, legs, grippers, and suspension mechanisms, prefer a side-neutral control layer when possible: solve mirrored link positions with `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()`, then attach real parts to the solved skeleton. If you use connector-frame joints directly, make the sign mapping explicit in defaults, keyframes, and verification.
+Anything that must rotate or slide gets connector frames: `origin` = pivot, `axis` = hinge line, `up` = rest twist. Always set `up` on hinges, wheels, and levers. Connector/link/mate semantics and mirrored-axis sign rules: see the assembly API reference.
 
 ## The Cavity Rule
 
-Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.
-
-If two adjacent parts in an assembly show a collision volume larger than the expected clearance volume in `forgecad run`, one part is missing its cavity. Both parts have solid material at the same joint position. This will look fine at rest pose but will block rotation and produce confusing joint behavior.
+Every joint is a **cavity** in one part plus a **tenon** in the other, and the cavity must be a real empty volume — not a gap implied by separate solids. A body that runs solid through the joint zone (e.g. a stadium cap under the clevis slot) blocks rotation even though the rest pose looks fine. End the body FLAT before the joint; extend the tines forward to the pivot; the inter-tine volume must be genuinely empty.
 
-```ts
-// BAD — body has a stadium cap at both ends; the "slot" between two clevis tines
-// is just empty space next to a solid body cap. The next phalanx's tongue knuckle
-// has nowhere to go (it intersects the previous body's cap).
-const body  = stadiumBar(L);            // cap at X=0 AND X=L
-const tine1 = box(...).translate(L,  Y_OFF, 0);
-const tine2 = box(...).translate(L, -Y_OFF, 0);
-let phalanx = union(body, tine1, tine2);
+Diagnostic: adjacent-part collision volume > expected clearance in `forgecad run` = missing cavity (both parts have solid material at the joint position). After fixing, the collision volume should drop to ~0 (or a few mm³ of clearance overlap).
 
-// GOOD — body ends FLAT before the joint. Tines extend forward to the pivot.
-// The X = L-KNUCK_R..L+KNUCK_R volume between the tines is genuinely empty.
-const body = box(L - KNUCK_R, TONG_T, H).translate((L - KNUCK_R) / 2, 0, -H / 2);
-const tongueKnuckle = knuckleDisc(0, 0, TONG_T);  // proximal cap only
-let phalanx = union(tongueKnuckle, body, tine1, tine2, ...tineCaps);
-```
+## Structural Sizing
 
-After applying the cavity rule, `forgecad run` collision volume between adjacent parts in a clevis-tongue chain should drop to **zero** (or a few mm³ of clearance overlap). If it doesn't, there's still solid material where there should be a cavity.
+**Yoke (connecting cantilevers).** Clevis tines at Y = ±Y_OFF are physically disconnected from a body of thickness TONG_T when Y_OFF > TONG_T/2 + clearance — the tines float and would snap under load. Always bridge with a yoke slab spanning the full clevis width, `(Y_OFF + TINE_T/2) * 2`, with a few mm of structural overlap along the joint axis, so material runs continuously from body to each tine.
 
-## Connecting Cantilevers
-
-A clevis tine arm at Y=±Y_OFF is geometrically separate from a body at Y=±TONG_T/2. With Y_OFF > TONG_T/2 + clearance, there is a **physical gap** between them. The tines float — they would snap off as soon as load is applied.
-
-Always add a **yoke**: a short slab spanning the full clevis width, sitting between the body's flat distal end and the tines' attachment point. The yoke fills the Y gap so material is continuous from the body through to each tine.
-
-```ts
-const yokeLen   = 3;                                  // a few mm of structural overlap
-const yokeStart = L - KNUCK_R - yokeLen;
-const totalY    = (Y_OFF + TINE_T / 2) * 2;           // full clevis width
-const yoke = box(yokeLen, totalY, H)
-  .translate(yokeStart + yokeLen / 2, 0, -H / 2);
-phalanx = union(phalanx, yoke);
-```
+**Knuckle radius.** For body height H, require `KNUCK_R >= H/2`. Smaller, and the body corners protrude past the knuckle's cylindrical envelope and sweep into the adjacent part during rotation. `KNUCK_R = H/2` makes the body cross-section a stadium that exactly fits the envelope.
 
 ## Hard Stops vs Slider Limits
 
-`addRevolute({ min: 0, max: 90 })` sets **slider limits** — the viewport won't let the user drag past them, but the geometry permits any rotation. There is no physical stop.
-
-For a **geometric** hard stop (parts can't backbend past extension, or can't curl past full closure), add a small protrusion on one part that interferes with the other at the limit angle:
-
-- **Extension stop at 0°** (typical for fingers, knees, elbows): add a small "lip" on the dorsal side of the proximal end of the child phalanx, sized so it just touches the parent's distal dorsal corner at 0°. Negative rotation (backbending) is then blocked by part-on-part contact.
-- **Flexion stop at θmax**: add a similar lip on the palmar side, or rely on the body-to-body collision when bodies meet.
+Declared joint min/max are not geometry — they only constrain the viewport slider; the geometry still permits any rotation. A physical stop requires an interfering protrusion:
 
-Verify with `forgecad run` at the limit poses — the contact pair should show ~0 mm³ collision (just touching), and rotation past the limit should report a non-zero collision volume.
+- **Extension stop at 0°**: a small lip on the dorsal side of the child's proximal end, sized to just touch the parent's distal dorsal corner at 0°; backbending is then blocked by contact.
+- **Flexion stop at θmax**: a palmar lip, or body-on-body contact when bodies meet.
 
-## Knuckle Sizing
-
-For a clevis-tongue joint with body height H, the tongue knuckle radius and clevis tine knuckle radius must satisfy:
-
-```
-KNUCK_R >= H / 2
-```
-
-If the knuckle radius is smaller than the body's half-height, the body's corners protrude beyond the knuckle envelope. When the joint rotates, those corners sweep through space outside the cylindrical envelope and collide with the adjacent part.
-
-Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that perfectly fits the knuckle envelope.
+Verify: ~0 mm³ collision exactly at the limit pose (just touching), non-zero past it.
 
 ## Verification Workflow
 
-1. Build the joint at rest pose. Run `forgecad run`. Check collision volumes.
-2. If adjacent parts in the joint show > clearance-volume of overlap → missing cavity (apply the cavity rule).
-3. Render with `--focus PartName` to inspect each part in isolation. The clevis end should clearly show a gap between the tines (the cavity).
-4. Render at curl angles (set joint debug params) at 30°, 60°, 90°. No new collisions should appear from rotation.
-5. Render at -10° (backbend test). Either no rotation possible (geometric stop in place) or rotation occurs and you need to add a stop.
+Check the loop, not just the rest pose:
+
+1. Build at rest; `forgecad run`; check collision volumes.
+2. Overlap > clearance volume between joint neighbors → apply the cavity rule.
+3. Render each part with `--focus PartName`; the clevis end must show a visible gap between tines.
+4. Re-check at swept angles (30°/60°/90°) — rotation reveals collisions the rest pose hides.
+5. Backbend test at -10°: blocked = hard stop exists; rotates = add a stop.

package/dist/docs-raw/guides/positioning.md

@@ -3,169 +3,47 @@ skill-group: geometry
 skill-order: 3
 ---
 
-# Positioning Strategy
+# Positioning Decision Ladder
 
-## Rule 0: if parts should touch, use connectors first
+Most positioning bugs come from manual coordinate arithmetic. Pick the **highest applicable rung**; drop down only when the rung above doesn't fit.
 
-For any fixed assembly where parts are meant to stay in contact in the final model, start with connectors + `matchTo()`. This applies to furniture, fixtures, toys, enclosures, sleds, and any other static multi-part object, not only mechanisms.
+## 1. Connectors + `matchTo()` — every real part-to-part interface
 
-Use raw `translate()` and `rotate()` when parts are intentionally free-floating or when you are doing quick exploratory layout. Use `attachTo()` for rough bounding-box placement. But if the relationship is a real interface, make it explicit with connectors.
-
-## Mechanisms: connector frames vs link points
-
-For serial articulated parts (hinges, hips, knees, levers, wheels), use `assembly().connect()` with connectors. `connect()` aligns the full connector frame: `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` locks the zero-angle twist of the child part. `up` is a local roll reference, not world up; author it explicitly whenever the rest pose matters.
-
-Do not use `addPart(..., { mate: { connector, toLink } })` when the part must point along a bone or inherit orientation from a link edge. Link mates are point attachments only: they translate the connector origin onto the solved link position and preserve the part's existing rotation. That is good for markers, sensors, labels, and debug handles. It is not a bone-frame API.
-
-Use link graphs (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) when the hard part is solving point positions, especially closed loops. Use connector-frame joints when the hard part is orienting real physical parts.
-
-For bilateral mechanisms, remember that connector-frame revolute values are physical axis-local values. Mirrored hinge axes need negated physical revolute values for the same mirrored pose, and physical limits mirror as `[min, max] -> [-max, -min]`. If you want `HipR: 10` and `HipL: 10` to mean the same semantic pose, drive a mirrored link graph or write an explicit state mapping instead of assuming equal connector-joint values are symmetric.
-
-## Primitive origin convention
-
-All 3D primitives are **centered on XY, base at Z=0**:
-
-| Primitive | X range | Y range | Z range |
-|-----------|---------|---------|---------|
-| `box(60, 40, 20)` | [-30, 30] | [-20, 20] | [0, 20] |
-| `cylinder(50, 10)` | [-10, 10] | [-10, 10] | [0, 50] |
-| `sphere(15)` | [-15, 15] | [-15, 15] | [-15, 15] |
-| `torus(20, 5)` | [-25, 25] | [-25, 25] | [-5, 5] |
-
-Sphere and torus are fully centered (symmetric in Z). Box and cylinder sit on the XY ground plane — **Z goes up from zero, never negative**.
-
-This means `box(w, d, h).translate(0, 0, -h / 2)` is the manual way to "center on Z" — it moves the box from `[0, h]` to `[-h / 2, h / 2]`. Prefer `box(w, d, h).placeReference('center', [0, 0, 0])` when you want full XYZ centering.
-
-Do not assume `center: true` or a positional `true` gives OpenSCAD-style full XYZ centering. Primitive placement is fixed unless the primitive docs explicitly say otherwise.
-
----
-
-Most positioning bugs come from manual coordinate arithmetic. Use these methods in priority order.
-
-## 1. Connectors + `matchTo()` — default for mating interfaces
-
-Define connectors on parts; `matchTo()` provides automatic alignment. With one connector pair, the child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model), and `up` pins the roll reference. With multiple connector pairs, the connector origins define the rigid transform; still author meaningful `axis` and `up` values so the same connectors remain useful for `connect()`, audits, and future matching.
+**Rule 0:** if parts are meant to stay in contact, define connectors and `matchTo()` — including *static* assemblies (furniture, enclosures, fixtures, toys), not just mechanisms. Connectors win because they are **stable** (don't shift on fillet/chamfer/boolean), **semantic** (type/gender), **oriented** (full frame), **queryable** (`verify.connectorDistance`), and **explode-aware**.
 
 ```javascript
-const shelf = box(200, 120, 10).translate(0, 0, -5).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0], up: [0, 0, 1] }),
+const shelf = box(200, 120, 10).withConnectors({
+  tab: connector.male("dovetail", { origin: [-100, 0, 5], axis: [-1, 0, 0], up: [0, 0, 1] }),
 });
-const panel = box(12, 120, 200).translate(0, 0, -100).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0], up: [0, 0, 1] }),
-});
-const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
-// Dictionary form for multiple pairs on same target:
-const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
-// Named group children bubble connectors via dotted paths:
-const cabinet = group({ name: "Left", shape: panel });
-shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
+const placed = shelf.matchTo(panel, "tab", "shelf_slot");
 ```
 
-**Why connectors first:** stable (don't shift on fillet/chamfer/boolean), semantic (carry type/gender), oriented (full frame), queryable (`shape.connectorDistance('a','b')`), explode-aware.
-
-For a non-mechanism fixed-assembly example, see `examples/api/static-assembly-connectors.forge.js`.
+Alignment semantics, dictionary form, and dotted group paths: see `matchTo()` JSDoc. For cross-file part alignment, prefer connectors over `withReferences()` placement points.
 
 ## 2. `group()` — local coordinates for multi-part assemblies
 
-The most common positioning bug: manually adding a parent's global offset to every sub-part. One wrong sign or forgotten variable and parts float into space. **Use `group()` to build parts in local coordinates (at the origin), then position the group once.**
+Build sub-parts at the **local origin**, group them, then translate the group **once** — never add a parent's global offset to every sub-part. Groups nest; each level has its own local origin. Groups cannot be booleaned: do subtract/intersect first in local coordinates, then group the result. Worked example: `group()` JSDoc.
 
-```javascript
-// BAD — every sub-part repeats the parent's global position
-const unitY = -18, unitZ = 70;
-const body = lib.roundedBox(100, 20, 32, 4).translate(0, unitY, unitZ);
-const panel = box(98, 2, 18).translate(0, unitY - 12, unitZ + 4);
-const louver = box(88, 2, 6).translate(0, unitY - 14, unitZ - 11);
-const led = sphere(1.2).translate(35, unitY - 12, unitZ + 9);
-
-// GOOD — build at local origin, group, translate once
-const body = lib.roundedBox(100, 20, 32, 4);
-const panel = box(98, 2, 18).translate(0, -12, 4);        // relative to local origin
-const louver = box(88, 2, 6).translate(0, -14, -11);      // relative to local origin
-const led = sphere(1.2).translate(35, -12, 9);             // relative to local origin
-const indoorUnit = group(
-  { name: 'Body', shape: body },
-  { name: 'Panel', shape: panel },
-  { name: 'Louver', shape: louver },
-  { name: 'LED', shape: led },
-).translate(0, -18, 70);  // ONE translate for the whole assembly
-```
+## 3. `pointAlong()` — orient before positioning
 
-**Groups nest.** Build sub-assemblies as groups, then group those into larger assemblies — each level has its own local origin.
+Always call `pointAlong()` **before** `matchTo()`/`translate()` — it reorients around the origin.
 
-```javascript
-const fan = group(hub, ...blades).translate(0, 25, 0);  // fan assembly
-const outdoorUnit = group(
-  { name: 'Body', shape: casing },
-  { name: 'Fan', shape: fan },             // already a group
-  { name: 'Grille', shape: grille },
-).translate(0, 23, -42);                    // position the whole outdoor unit
-```
+## 4. `attachTo()` — rough bounding-box placement only
 
-**When to use something else:** `group()` preserves individual shapes — you can't boolean (subtract/intersect) a group. If a sub-part needs a boolean with the parent body, do that boolean first in local coordinates, then group the result.
+Anchor points shift after fillet/chamfer/boolean: fine for quick prototyping, fragile for assembly interfaces — promote real interfaces to connectors.
 
-## 3. `pointAlong()` — orient cylinders before positioning
+## 5. `placeReference()` — land a named anchor on a world coordinate
 
-```javascript
-// BAD
-const pipe = cylinder(100, 5).rotateX(90).translate(x, y, z);
-// GOOD — reads as "pipe pointing along Y"
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
-```
+Grounding, centering, edge alignment, custom reference points: see `placeReference()` JSDoc.
 
-**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
+## 6. Last resort: `rotateAroundTo()`, `moveToLocal()`, `translate()`
 
-## 4. `attachTo()` — quick bounding-box positioning
+For computed offsets and free-floating or exploratory layout. Raw `translate()`/`rotate()` is correct only when parts are intentionally unrelated.
 
-```javascript
-const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
-```
-
-`child.attachTo(parent, parentAnchor, selfAnchor, offset)`. Anchor points shift on fillet/chamfer/boolean — fragile for assembly interfaces, fine for quick prototyping.
-
-## 5. `rotateAroundTo()` — aim a point around a hinge/axis
-
-```javascript
-const aimed = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 20]);
-// Exact line solve:
-const lineHit = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 0], { mode: 'line' });
-```
-
-## 6. `moveToLocal()` — offset from another shape's min corner
-
-```javascript
-const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
-```
-
-## 7. `translate()` — for simple offsets or bridging computed locations
-
-```javascript
-const pipeLen = bb2.min[1] - bb1.max[1];
-const pipe = cylinder(pipeLen, 5).pointAlong([0, 1, 0]).translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
-```
-
-## 8. `placeReference()` — align any anchor to a world coordinate
-
-Place a shape so a named anchor point lands exactly where you want it. Accepts all built-in anchors (`'bottom'`, `'center'`, `'top-front-left'`, etc.) plus custom references from `withReferences()`.
-
-```javascript
-// Ground a shape — bottom face center at Z = 0
-const grounded = shape.placeReference('bottom', [0, 0, 0])
+## Mechanisms
 
-// Center at the world origin
-const centered = shape.placeReference('center', [0, 0, 0])
+Link graphs (`link()`, `edgeBetweenLinks()`) solve **point positions** (closed loops); connector-frame joints (`assembly().connect()`) **orient physical parts**. Frame semantics and mirrored-revolute rules: assembly docs; joint geometry: `guides/joint-design.md`.
 
-// Align left edge to X = 10
-const aligned = shape.placeReference('left', [10, 0, 0])
-```
-
-Also works with custom placement references for cross-file parts:
-
-```javascript
-// widget.forge.js — define once
-return union(base, post).withReferences({ points: { mount: [0, -16, -4] } });
-
-// importer — consume
-const widget = require("./widget.forge.js").placeReference("mount", [120, 40, 0]);
-```
+## Primitive placement
 
-For cross-file parts needing proper alignment, prefer connectors over placement references.
+Box and cylinder sit base-at-Z=0, centered on XY; sphere and torus are fully centered. There is no OpenSCAD-style `center: true` — placement is fixed; use `placeReference('center', [0, 0, 0])` to fully center. Exact per-axis extents: primitive JSDoc.

package/dist/docs-raw/guides/scene-presentation.md

@@ -0,0 +1,89 @@
+---
+skill-group: recipes
+skill-order: 1
+---
+
+# Scene Presentation Recipes
+
+Worked `scene()` setups. The option schema and behavioral cliffs (e.g. setting `lights` replaces all defaults) live in the `scene()` API docs (viewport group) — this file is copyable recipes only.
+
+## Baseline studio setup
+
+Every model deserves at least this; default lighting looks flat.
+
+```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,
+  },
+});
+```
+
+Adapt to the material family: metallic/jewelry → `studio`, exposure 1.2–1.5, subtle bloom; organic/wood/matte → `warehouse`/`apartment`, warmer ambient, lower bloom; dark/dramatic → `night`, bloom + vignette. Ground with `receiveShadow: true` only for objects that stand on something.
+
+Camera: 3/4 angle, `fov` 35–50 (lower = flatter/telephoto), `target` at the visual center of mass — not necessarily `[0,0,0]`.
+
+## Matte industrial hero shot
+
+For mechanisms, tools, product prototypes, and vehicles, prefer a matte studio look over gloss or atmosphere (ranges = tuning room, not options syntax):
+
+```js
+scene({
+  background: { top: '#c3ccd7', bottom: '#566474' },
+  camera: { position: [430, -540, 340], target: [0, 30, 125], fov: 38 },
+  environment: { preset: 'studio', intensity: 0.2, background: false },  // 0.15–0.25
+  lights: [
+    { type: 'ambient', color: '#efe7dc', intensity: 0.15 },                                            // 0.12–0.2
+    { type: 'directional', position: [260, -320, 420], color: '#ffe2bf', intensity: 2.8, castShadow: true }, // 2.6–3.2
+    { type: 'directional', position: [-260, 210, 220], color: '#d4e6fb', intensity: 0.85 },             // 0.7–1.0
+    { type: 'hemisphere', skyColor: '#c7d3df', groundColor: '#495463', intensity: 0.15 },               // 0.1–0.2
+  ],
+  postProcessing: {
+    bloom: { intensity: 0.04, threshold: 0.94, radius: 0.28 },
+    vignette: { darkness: 0.4, offset: 0.32 },
+    toneMappingExposure: 1.1,  // 1.05–1.18
+  },
+});
+```
+
+Stage the model on an intentionally matte plinth:
+
+```js
+const stage = cylinder(16, 226).translate(0, 0, -26)
+  .color('#8b97a4').material({ metalness: 0.04, roughness: 0.78 });
+mock(stage, 'StudioPlinth');
+```
+
+Iteration rules that held up in practice:
+
+- Prefer roughness over fog for softness — fog flattens form; matte materials keep shadow definition.
+- Keep bloom near zero for mechanical scenes; too much reads toy-like.
+- If the render is close but not right, nudge `toneMappingExposure` by ~0.05 before touching the light rig; avoid large ambient jumps — they kill contrast fastest.
+- Add accent point lights near focal features, localized with `distance` and `decay`.
+
+## Named render views
+
+For repeatable review or hero renders, declare views in `scene({ views })` — wrap each camera in `{ camera: ... }`:
+
+```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 with `forgecad render 3d model.forge.js --view hero`.

package/dist/docs-raw/guides/simready-quickstart.md

@@ -0,0 +1,171 @@
+# SimReady Quickstart
+
+ForgeCAD simulation readiness starts in the model file. The `.forge.js` script should return the same assembly you want to inspect, export, and simulate; simulation metadata lives on that assembly instead of in a separate export command.
+
+Use this pattern when you want a robot, fixture, gripper, crate, or imported asset to become a physics package later:
+
+1. Build real parts with connectors.
+2. Add each part to an `assembly(...)` with `sim: Sim.body(...)`.
+3. Connect moving parts with `connect(...)` and put drive intent on the joint.
+4. Finish the root assembly with `withSimulation(...)`.
+5. Run `forgecad check simready` before exporting.
+
+## Robot Pattern
+
+```js
+const aluminum = Sim.material("6061 aluminum", {
+  densityKgM3: 2700,
+  staticFriction: 0.45,
+  dynamicFriction: 0.35,
+  restitution: 0.05,
+});
+
+const rubber = Sim.material("rubber tire", {
+  densityKgM3: 1100,
+  staticFriction: 0.9,
+  dynamicFriction: 0.75,
+  restitution: 0.12,
+});
+
+const chassis = box(220, 120, 28).withConnectors({
+  left_axle: connector({ origin: [0, 82, 0], axis: [0, 1, 0], up: [0, 0, 1], kind: "revolute" }),
+  right_axle: connector({ origin: [0, -82, 0], axis: [0, -1, 0], up: [0, 0, 1], kind: "revolute" }),
+});
+
+const wheel = cylinder(34, 28, undefined, 48)
+  .rotateX(90)
+  .withConnectors({
+    bore: connector({ origin: [0, 0, 0], axis: [0, 1, 0], up: [0, 0, 1], kind: "revolute" }),
+    tread: connector({ origin: [0, 0, -34], axis: [0, 0, -1], up: [1, 0, 0] }),
+  });
+
+return assembly("Rover")
+  .addPart("Chassis", chassis, {
+    sim: Sim.body({
+      massKg: 4.2,
+      material: aluminum,
+      collider: Sim.collider.boundingBox(),
+    }),
+  })
+  .addPart("Left Wheel", wheel, {
+    sim: Sim.body({
+      massKg: 0.32,
+      material: rubber,
+      collider: Sim.collider.convexHull(),
+      contacts: { tread: Sim.contact.wheelSurface("tread") },
+    }),
+  })
+  .addPart("Right Wheel", wheel, {
+    sim: Sim.body({
+      massKg: 0.32,
+      material: rubber,
+      collider: Sim.collider.convexHull(),
+      contacts: { tread: Sim.contact.wheelSurface("tread") },
+    }),
+  })
+  .connect("Chassis.left_axle", "Left Wheel.bore", {
+    as: "leftWheel",
+    type: "revolute",
+    drive: Sim.drive.velocity({ maxTorqueNm: 1.8, maxSpeedRpm: 220, damping: 0.02, friction: 0.01 }),
+  })
+  .connect("Chassis.right_axle", "Right Wheel.bore", {
+    as: "rightWheel",
+    type: "revolute",
+    drive: Sim.drive.velocity({ maxTorqueNm: 1.8, maxSpeedRpm: 220, damping: 0.02, friction: 0.01 }),
+  })
+  .withSimulation({
+    rootPart: "Chassis",
+    profile: Sim.profile.robotBodyRunnable(),
+    controllers: [
+      Sim.controller.diffDrive({
+        leftJoints: ["leftWheel"],
+        rightJoints: ["rightWheel"],
+        wheelRadiusMm: 34,
+        wheelSeparationMm: 164,
+      }),
+    ],
+  });
+```
+
+The important names are authored once:
+
+- `rootPart` names the body that downstream simulators treat as the robot root.
+- `leftWheel` and `rightWheel` are joint names, so controllers and exporters do not need to guess motor wiring.
+- `tread` is an existing connector on the wheel, so contact metadata is checked against geometry-owned names.
+
+## Asset Pattern
+
+Assets use the same assembly contract. In V1, a crate, prop, imported STEP, or static environment object is usually a one-part assembly:
+
+```js
+const pine = Sim.material("pine crate", {
+  densityKgM3: 520,
+  staticFriction: 0.55,
+  dynamicFriction: 0.42,
+  restitution: 0.08,
+});
+
+const crate = box(140, 110, 80).withConnectors({
+  grip: connector({ origin: [0, -56, 8], axis: [0, -1, 0], up: [0, 0, 1] }),
+});
+
+return assembly("Crate Asset")
+  .addPart("Body", crate, {
+    sim: Sim.body({
+      massKg: 2.4,
+      material: pine,
+      collider: Sim.collider.convexHull(),
+      contacts: { grip: Sim.contact.gripperSurface("grip") },
+    }),
+  })
+  .withSimulation({
+    profile: Sim.profile.roboticsAssetPhysx(),
+  });
+```
+
+Asset profiles require physical body metadata and explicit collider intent. They do not require `rootPart`, joints, or controllers.
+
+## Check Then Export
+
+Run the offline gate first:
+
+```bash
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+```
+
+Then export the package that matches your simulator:
+
+```bash
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-mjcf
+node dist-cli/forgecad.js export sdf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-sdf
+node dist-cli/forgecad.js export urdf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-urdf
+```
+
+Use MJCF/MuJoCo for the fastest local physics loop. Use SDF for Gazebo Sim. Use URDF when the next tool expects a ROS/PyBullet/Isaac import path.
+
+ForgeCAD does not currently have a native USD/USDZ export command. For Isaac workflows today, export URDF as the import artifact and carry the richer ForgeCAD simulation intent through `simready-manifest.json`. A future USD exporter should consume the same source-level simulation contract instead of re-inferring physics metadata from mesh geometry.
+
+Every package includes `simready-manifest.json`. That manifest is the neutral handoff: model name, units, profile, bodies, joints, drives, controllers, contacts, and validation results.
+
+## What The Check Catches
+
+`forgecad check simready` is source-level validation. It does not need Isaac Sim, OpenUSD, `pxr`, MuJoCo, or NVIDIA validators installed.
+
+It fails when:
+
+- the returned model has no `withSimulation(...)` contract
+- a physical part is missing `Sim.body(...)`
+- mass, density, friction, restitution, torque, speed, damping, or world pose values are non-finite or invalid
+- a collider is missing for profiles that require explicit collision intent
+- `Sim.collider.none(...)` has no reason
+- a contact surface names a missing connector
+- a controller names an unknown or wrong-type joint
+- a robot profile has no `rootPart`, an unknown `rootPart`, or a disconnected joint graph
+
+It intentionally treats joint-connected bodies as connected. A robot with separated wheels, arms, or gripper fingers should pass when the articulated graph is valid.
+
+## Where Control Code Lives
+
+ForgeCAD owns geometry, physical metadata, joints, drives, controllers, manifests, and starter simulator packages. It should not own a single blessed balance controller, reward function, or RL library.
+
+For a runnable training loop, export MJCF and use the generated package scripts. The Scout Cam Rover example includes `gym_env.py`, `train_balance.py`, `train_sb3.py`, `play_balance.py`, and `live_policy_viewer.py`; see [Simulation Workflow](../simulation-workflow.md) for the full MuJoCo and Isaac Lab path.