forgecad 0.9.16 → 0.10.1

package/dist-skill/docs/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-skill/docs/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-skill/docs/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-skill/docs/guides/surface-members.md

@@ -0,0 +1,26 @@
+---
+skill-group: curves
+skill-order: 1
+---
+
+# Surface Members: When To Route Through Carrier + SurfaceBody
+
+Surface members model physical material that follows a carrier surface: bottle-cage arms, grip inlays, brace ribs, prop guards, helmet vents. Full API, parameter rules, and worked examples: [../generated/curves.md](../generated/curves.md).
+
+## When to use
+
+Route through this layer when the model has: a carrier surface (cylinder, plane, or `ProductSkin`); paths or bands in carrier-local coordinates; member-local features (slots, cutouts, lips, cups, ribs, section thickness/edge radius); or explicit joins between named members. Not for plain boxes, simple extrusions, sheet-metal bends, exact machined faces, or free-floating connector-positioned assemblies.
+
+## Mental model
+
+- `Carrier` owns surface coordinates and frames. `SurfaceBody(name)` owns named members — `band()` or `plate()` — and the joins between them.
+- Features attach to a member's local coordinate system before lowering. This is not a global boolean recipe.
+- Cylinder paths take degrees and handle seam wrapping — never compute angles with trig.
+- A ProductSkin path stays on one side. For multi-side detail, split into one member per side and join them at named transition anchors; `sideTransition` / `sideTransitionChain` / `sideRoute` generate the matching side-local endpoints.
+- `Product.ribbon()` stays the simple path for a one-side conformal ribbon. Upgrade to `Carrier.productSkin(skin)` + `SurfaceBody` when the detail needs member-local features, repeated ribs, explicit joins, or mirrored members.
+
+## Verification loop
+
+- `build()` returns the member geometry. `buildWithDiagnostics()` adds a serializable member graph + IR; `buildDebug()` adds visible debug markers (anchors, join radii, centerlines, frame axes) alongside the normal shapes.
+- Every diagnostic carries a stable `code` field (e.g. `region.centerOutOfBounds`). Repair loops must match on `code`, never on English prose. Clipped or crossing regions and invalid joins are reported as diagnostics, never silently accepted as valid geometry.
+- Only a limited join set lowers to real geometry: close endpoint pairs, selected named-anchor pairs, sampled landing pads, and unambiguous shared endpoints via `autoJoinAtSharedAnchors()`. Farther, missing-anchor, or ambiguous joins remain diagnostic-only intent — decompose the design into supported joins instead of expecting a fallback.

package/dist-skill/library/forgecad-3d-reconstruction/SKILL.md

@@ -6,129 +6,41 @@ forgecad-public: true
 
 # ForgeCAD 3D Reconstruction
 
-Use this skill when the user provides an existing 3D file and wants a ForgeCAD model that recreates it as parametric CAD.
+The reference asset is evidence, not the deliverable. The deliverable is a readable, parametric `.forge.js` model that runs, renders, and scores well against the source. Never return `Import.mesh()`/`Import.step()` of the source as the final model unless the user explicitly asks for an import wrapper — imports are for measurement, rendering, and scoring only.
 
-The reference asset is evidence, not the deliverable. The deliverable is a readable `.forge.js` model that runs, renders, inspects, and scores well against the source geometry.
+Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-make-a-model` (Imported Parts section), not this skill; benchmark/RL episodes → `forgecad-reconstruction-benchmark`; inspection-bundle interpretation → `forgecad-render-inspect`; independent grading after reconstruction → `forgecad-model-grader`; API and command reference → `forgecad` skill + CLI.md.
 
-Do not solve reconstruction by returning `importMesh("reference.stl")` or `importStep("reference.step")` as the final model unless the user explicitly asks for an import wrapper. Imported source assets are for measurement, rendering, inspection, and scoring.
+## Workflow
 
-## Companion Skills
-
-- Use `forgecad` for API syntax, direct CAD CLI behavior, and validation commands.
-- Use `forgecad-reconstruction-benchmark` instead when the task is a benchmark
-  or RL episode with a fixed `submission/main.forge.js` output path.
-- Use `forgecad-make-a-model` when creating a normal user-facing `.forge.js`
-  project structure outside the benchmark harness.
-- Use `forgecad-render-inspect` when inspection bundles need interpretation.
-- Use `forgecad-model-grader` only after reconstruction, when the user asks for an independent grade.
-
-## Required Workflow
-
-1. Stage the reference.
-   Put the source 3D file in a scratch folder such as `/tmp/<slug>-reconstruct/ref/` or keep the user's original path if it is already stable. Preserve the original file.
-
-2. Inspect the source directly.
-   No wrapper script is needed. Use the local checkout CLI:
-
-   ```bash
-   node dist-cli/forgecad.js ls path/to/source.stl --quality live --long
-   node dist-cli/forgecad.js render 3d path/to/source.stl /tmp/<slug>-source.png --camera iso --edges thin --size 900
-   node dist-cli/forgecad.js inspect visual objects path/to/source.stl /tmp/<slug>-source-objects --camera iso --size 700 --force
-   node dist-cli/forgecad.js inspect sections sample path/to/source.stl /tmp/<slug>-source-sections --count 5 --size 700 --force
-   ```
-
-   For 3MF sources, `forgecad run` prints the source archive's build
-   items/resource objects with stable refs such as
-   `3mf:build:001:object:2`, automatic names, per-item bounding boxes, and
-   triangle counts. Use that item table to avoid missing hidden multi-part
-   structure before scoring the whole shape.
-
-   For STEP/STP files, the CLI auto-selects OCCT unless `--backend` is passed.
-   Run render commands sequentially; starting multiple browser renders at once can make the shared Vite renderer race and time out.
-
-3. Write a Reconstruction Brief.
-   Before modeling, record:
-   - source path and file type
-   - bounding box, volume, triangle count, and apparent units
-   - object identity and likely manufacturing process
-   - major primitive families: boxes, cylinders, plates, revolutions, lofts, sweeps, holes, fillets, ribs, threads, text, freeform surfaces
-   - symmetry, coordinate origin, and key reference planes
-   - what must be exact, what may be approximate, and what should remain parametric
-   - scoring tolerance and alignment policy
-
-4. Build the ForgeCAD candidate.
-   Model the real geometry, not a faceted copy. Start with a blockout that matches bbox and main masses, then add holes, cutouts, transitions, and details. Prefer high-level ForgeCAD APIs and blueprint-first intent over vertex chasing.
-5. Compare the candidate numerically.
-   Use the raw geometry comparison command:
+1. **Inspect the source directly** — the CLI reads CAD/mesh files as inputs, no wrapper script. Gather four evidence types: `ls --long` stats, an iso render, per-object views, sampled sections (invocations in CLI.md; when sharing a renderer server via `--port`, run renders sequentially).
+2. **3MF**: enumerate every build item before scoring — hidden multi-part structure is a common miss. Item ref syntax: `Import.mesh` docs.
+3. **Reconstruction Brief** before modeling: what must be exact vs. approximate vs. parametric; symmetry, origin, key reference planes; likely manufacturing process; scoring tolerance and alignment policy.
+4. **Blockout first.** Match bbox and main masses, then add features. Model real geometry with blueprint-first APIs — never vertex-chase a faceted copy.
+5. **Compare numerically** — the core loop:
 
    ```bash
-   node dist-cli/forgecad.js compare 3d path/to/source.stl path/to/candidate.forge.js \
+   forgecad compare 3d path/to/source.stl path/to/candidate.forge.js \
      --samples 3000 --json --output /tmp/<slug>-score.json
    ```
 
-   Start with `--align none`. Use `--align center` only when the source and candidate clearly use different origins but the same scale and orientation. Use `--align center-scale` only for exploratory diagnosis because it can hide dimensional errors.
-
-6. Iterate from coarse to fine.
-   Improve in this order:
-   - bbox size and coordinate placement
-   - main volumes and silhouette
-   - major holes, bosses, ribs, shells, and cutouts
-   - edge treatments and transitions
-   - small details, labels, textures, and decorative features
-
-   Use score metrics as evidence:
-   - low coverage means missing or extra surface area
-   - high RMS means broad proportional mismatch
-   - high p95 or max means localized protrusions, holes, or outliers
-   - bounds delta means size, origin, or scale mismatch
-   - volume delta means mass, shell, cutout, or scale mismatch
-
-7. Validate the final model.
-   Minimum final checks:
-
-   ```bash
-   node dist-cli/forgecad.js run path/to/candidate.forge.js
-   node dist-cli/forgecad.js render 3d path/to/candidate.forge.js /tmp/<slug>-candidate.png --camera iso --edges thin --size 900
-   node dist-cli/forgecad.js compare 3d path/to/source.stl path/to/candidate.forge.js --samples 5000 --json --output /tmp/<slug>-final-score.json
-   node dist-cli/forgecad.js inspect compare overlay path/to/candidate.forge.js /tmp/<slug>-compare --compare-samples 5000 --force --size 700
-   ```
-
-   Add targeted evidence commands such as `inspect fit interference`, `inspect manufacture thickness`, `inspect physical components`, `inspect physical floating`, or `inspect surface zebra` when the object is multi-part, hollow, mechanical, thin-walled, or surface-sensitive.
-
-## Scoring Guidance
-
-`forgecad compare 3d` returns an overall 0-100 raw geometry score plus distance, feature, bounds, and volume metrics. Treat the score as a guide, not a license to make unmaintainable code.
-
-Suggested targets:
-
-- `95+`: excellent reconstruction for simple prismatic or revolved parts
-- `90+`: good target for ordinary mechanical parts with fillets and cutouts
-- `80+`: acceptable rough reconstruction when the source is organic, faceted, or underdetermined
-
-Always report the raw `rms`, `p95`, `max`, coverage, bounds delta, and volume delta. A high score with a large `max` distance can still hide a missing local feature.
-
-For faceted source meshes, decide whether tessellation itself is evidence. If the source is an exported primitive or low-poly mesh, exact triangle/segment matching can raise the numeric score but may reduce parametric clarity. Prefer analytic intent when the user wants a clean CAD reconstruction; match tessellation only when the faceting is part of the artifact or required by the acceptance criteria.
+6. **Iterate coarse to fine**: bbox/placement → main volumes/silhouette → holes/bosses/ribs/shells → edge treatments → small details.
 
-## Subagent Validation
+## Reading the Score
 
-When validating this skill with a subagent, give the subagent only:
+Alignment: start `--align none`. Use `--align center` only when origins clearly differ but scale and orientation match. Use `--align center-scale` only for exploratory diagnosis — it hides dimensional errors.
 
-- the reference file path
-- the desired output folder
-- this skill name
-- the command to use the local CLI: `node dist-cli/forgecad.js`
+| Signal | Diagnosis |
+|---|---|
+| Low coverage | Missing or extra surface |
+| High RMS | Broad proportional mismatch |
+| High p95/max | Localized outlier feature (protrusion, hole) |
+| Bounds delta | Size, origin, or scale mismatch |
+| Volume delta | Mass, shell, cutout, or scale mismatch |
 
-Do not provide your intended modeling strategy, hidden measurements, or expected score. The point is to test whether the skill guides a fresh agent through evidence, modeling, scoring, and iteration.
+Calibration: 95+ simple prismatic/revolved parts, 90+ ordinary mechanical parts with fillets/cutouts, 80+ acceptable for organic, faceted, or underdetermined sources. Always report raw rms, p95, max, coverage, bounds delta, and volume delta — a high overall score with a large max can hide a missing local feature.
 
-## Output Contract
+Faceted sources: decide whether tessellation itself is evidence. Matching low-poly faceting raises the score but reduces parametric clarity — prefer analytic intent unless faceting is part of the artifact or required by the acceptance criteria.
 
-When finished, report:
+## Done Criteria
 
-- source file path
-- candidate `.forge.js` path
-- Reconstruction Brief summary
-- source inspection bundle and renders
-- candidate renders and inspection bundle, if used
-- final `forgecad compare 3d` command and score JSON path
-- final score, RMS, p95, max distance, coverage, bounds delta, and volume delta
-- known mismatches and whether they are intentional simplifications or remaining work
+The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects (`forgecad-render-inspect`) when the object is multi-part, hollow, thin-walled, or surface-sensitive. Report: source and candidate paths, score JSON path, final metrics, and every known mismatch classified as intentional simplification or remaining work.