forgecad 0.1.0 → 0.1.2

package/dist-skill/docs/API/model-building/assembly.md

@@ -0,0 +1,205 @@
+# Assembly + Mechanism API
+
+Use this API when your model is a mechanism, not a single booleaned solid.
+
+## Mental model
+- `Part` = manufacturable object (shape + metadata)
+- `Joint` = relationship between parent and child part
+- `State` = current joint values
+- `Solve` = compute world transforms for all parts
+- `Validate` = collisions / clearances / sweep checks
+
+## Quick start
+
+```javascript
+const mech = assembly("Arm")
+  .addPart("base", box(80, 80, 20, true), {
+    metadata: { material: "PETG", process: "FDM", qty: 1 },
+  })
+  .addPart("link", box(140, 24, 24).translate(0, -12, -12))
+  .addJoint("shoulder", "revolute", "base", "link", {
+    axis: [0, 1, 0],
+    min: -30,
+    max: 120,
+    default: 25,
+    frame: Transform.identity().translate(0, 0, 20),
+  });
+
+const solved = mech.solve();
+return solved.toScene();
+```
+
+## Ergonomic helpers
+- `addFrame(name, { transform? })` adds a virtual reference frame (no geometry)
+- `addRevolute(name, parent, child, opts)` shorthand for `addJoint(..., "revolute", ...)`
+- `addPrismatic(name, parent, child, opts)` shorthand for `addJoint(..., "prismatic", ...)`
+- `addFixed(name, parent, child, opts)` shorthand for `addJoint(..., "fixed", ...)`
+- `addJointCoupling(jointName, { terms, offset? })` links joints with linear relationships
+- `addGearCoupling(drivenJoint, driverJoint, opts)` links revolute joints using gear ratios
+
+## Joint couplings
+
+Use couplings when one joint should be derived from other joints.
+
+Formula:
+- `driven = offset + Σ(ratio_i * source_i)`
+
+Example:
+
+```javascript
+const mech = assembly("Differential")
+  .addFrame("Base")
+  .addFrame("Turret")
+  .addFrame("Wheel")
+  .addFrame("TopInput")
+  .addRevolute("Steering", "Base", "Turret", { axis: [0, 0, 1] })
+  .addRevolute("WheelDrive", "Turret", "Wheel", { axis: [1, 0, 0] })
+  .addRevolute("TopGear", "Base", "TopInput", { axis: [0, 0, 1] })
+  .addJointCoupling("TopGear", {
+    terms: [
+      { joint: "Steering", ratio: 1 },
+      { joint: "WheelDrive", ratio: 20 / 14 },
+    ],
+  });
+```
+
+Notes:
+- Coupled joints ignore direct values in `solve(state)` and emit a warning.
+- Coupling cycles are rejected.
+- `sweepJoint(...)` cannot sweep a coupled target; sweep one of its source joints instead.
+
+## Gear couplings
+
+Use this helper to connect two **revolute** joints as a gear mesh without manually writing `addJointCoupling(...)`.
+
+```javascript
+const pair = lib.gearPair({
+  pinion: { module: 1.25, teeth: 14, faceWidth: 8 },
+  gear: { module: 1.25, teeth: 42, faceWidth: 8 },
+});
+
+const mech = assembly("Spur Stage")
+  .addFrame("Base")
+  .addFrame("PinionPart")
+  .addFrame("GearPart")
+  .addRevolute("Pinion", "Base", "PinionPart", { axis: [0, 0, 1] })
+  .addRevolute("Driven", "Base", "GearPart", { axis: [0, 0, 1] })
+  .addGearCoupling("Driven", "Pinion", { pair }); // uses pair.jointRatio
+```
+
+`addGearCoupling(...)` ratio sources (choose exactly one):
+- `ratio` (explicit multiplier)
+- `pair` (`lib.gearPair(...)`, `lib.bevelGearPair(...)`, or `lib.faceGearPair(...)` result using `pair.jointRatio`)
+- `driverTeeth` + `drivenTeeth` (auto ratio; `internal` mesh is positive, `external`/`bevel`/`face` are negative)
+
+For bevel stages, pairing helpers also return placement aids:
+- `pinionAxis`, `gearAxis`
+- `pinionCenter`, `gearCenter`
+
+For face stages, use `centerDistance` and `meshPlaneZ` from `lib.faceGearPair(...)`; with `place: true`, the face gear stays on the Z axis and the vertical spur is placed at `[centerDistance, 0, meshPlaneZ]`.
+
+## Joint frames
+
+`frame` is a transform from the **parent part frame** to the **joint frame at zero state**.
+
+For a child part:
+
+Matrix form:
+- `childWorld = parentWorld * frame * motion(value) * childBase`
+
+Forge chain form:
+- `childWorld = composeChain(childBase, motion(value), frame, parentWorld)`
+
+This keeps kinematic chains declarative and avoids repeated manual pivot math.
+
+## Validation helpers
+- `solved.collisionReport()` returns overlapping part pairs and volume
+- `solved.minClearance("PartA", "PartB", 10)` computes minimum gap
+- `assembly.sweepJoint("elbow", -20, 140, 24)` samples motion and reports collisions
+
+Notebook-friendly pattern:
+
+```javascript
+const solved = mech.solve({ shoulder: 35, elbow: 60 });
+console.log("Collisions", solved.collisionReport());
+
+const sweep = mech.sweepJoint("elbow", -10, 135, 12, { shoulder: 35 });
+console.log("Sweep collisions", sweep.filter((step) => step.collisions.length > 0).length);
+
+show(solved.toScene());
+```
+
+That keeps mechanism setup in earlier cells and collision/sweep investigation in the current preview cell.
+
+## Common pitfalls
+- If parts vanish in the viewport, check whether a cut plane is active before debugging kinematics. The viewer-side APIs live in [../runtime/viewport.md](../runtime/viewport.md).
+- If a returned object is empty, Forge logs a warning in script output.
+
+## Metadata
+- `addPart(..., { metadata })` attaches per-part metadata to an assembly part.
+- BOM/report helpers such as `solved.bom()` and `solved.bomCsv()` live in [../output/bom.md](../output/bom.md).
+
+## Naming grouped assembly children
+
+When an assembly part is a `ShapeGroup`, Forge flattens the group into separate viewport objects. To avoid opaque labels like `Base Assembly.1`, name the group children explicitly:
+
+```javascript
+const housing = group(
+  { name: "Body", shape: body },
+  { name: "Lid", shape: lid },
+);
+
+const mech = assembly("Case")
+  .addPart("Base Assembly", housing);
+```
+
+That produces labels such as `Base Assembly.Body` and `Base Assembly.Lid`.
+
+## Robot export
+
+Use `robotExport({...})` when an assembly should become a simulator package instead of only a viewport scene.
+
+```javascript
+const rover = assembly("Scout")
+  .addPart("Chassis", box(300, 220, 50, true))
+  .addPart("Left Wheel", cylinder(30, 60, undefined, 48, true).pointAlong([0, 1, 0]))
+  .addPart("Right Wheel", cylinder(30, 60, undefined, 48, true).pointAlong([0, 1, 0]))
+  .addRevolute("leftWheel", "Chassis", "Left Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, 140, 60),
+    effort: 20,
+    velocity: 1080,
+  })
+  .addRevolute("rightWheel", "Chassis", "Right Wheel", {
+    axis: [0, 1, 0],
+    frame: Transform.identity().translate(90, -140, 60),
+    effort: 20,
+    velocity: 1080,
+  });
+
+robotExport({
+  assembly: rover,
+  modelName: "Scout",
+  links: {
+    Chassis: { massKg: 10 },
+    "Left Wheel": { massKg: 0.8 },
+    "Right Wheel": { massKg: 0.8 },
+  },
+  plugins: {
+    diffDrive: {
+      leftJoints: ["leftWheel"],
+      rightJoints: ["rightWheel"],
+      wheelSeparationMm: 280,
+      wheelRadiusMm: 60,
+    },
+  },
+  world: {
+    generateDemoWorld: true,
+  },
+});
+```
+
+Notes:
+- Revolute joint `velocity` values are expressed in degrees/second in Forge; the SDF exporter converts them to radians/second.
+- Prismatic distances are authored in millimeters and exported in meters.
+- `massKg` is preferred for demo robots; `densityKgM3` is a decent fallback when mass is unknown.

package/dist-skill/docs/API/model-building/coordinate-system.md

@@ -0,0 +1,43 @@
+# Coordinate System Convention
+
+ForgeCAD uses a **Z-up** right-handed coordinate system.
+
+## Axes
+
+| Axis | Direction       | Positive |
+|------|-----------------|----------|
+| X    | Left / Right    | Right    |
+| Y    | Forward / Back  | Forward  |
+| Z    | Up / Down       | Up       |
+
+## Standard Views
+
+| View   | Camera position direction | Sees plane | Camera up |
+|--------|--------------------------|------------|-----------|
+| Front  | −Y (camera at −Y)        | XZ         | Z         |
+| Back   | +Y (camera at +Y)        | XZ         | Z         |
+| Right  | +X (camera at +X)        | YZ         | Z         |
+| Left   | −X (camera at −X)        | YZ         | Z         |
+| Top    | +Z (camera at +Z)        | XY         | +Y        |
+| Bottom | −Z (camera at −Z)        | XY         | −Y        |
+| Iso    | +X −Y +Z (diagonal)      | —          | Z         |
+
+## GizmoViewcube Face Mapping
+
+Three.js BoxGeometry material indices (cube face order):
+
+| Index | Three.js direction | ForgeCAD label |
+|-------|--------------------|----------------|
+| 0     | +X                 | Right          |
+| 1     | −X                 | Left           |
+| 2     | +Y                 | Front          |
+| 3     | −Y                 | Back           |
+| 4     | +Z                 | Top            |
+| 5     | −Z                 | Bottom         |
+
+Default drei labels are `['Right', 'Left', 'Top', 'Bottom', 'Front', 'Back']` (Y-up).
+For Z-up we pass `faces={['Right', 'Left', 'Front', 'Back', 'Top', 'Bottom']}`.
+
+## Grid
+
+The ground plane is XY (Z = 0). The grid lies on this plane.

package/dist-skill/docs/API/model-building/entities.md

@@ -0,0 +1,282 @@
+# Entity-Based API
+
+Named geometric entities with stable identity, topology tracking, and constraint integration.
+
+## 2D Entities
+
+### `point(x, y)` / `new Point2D(x, y)`
+A named 2D point.
+
+```javascript
+const p = point(10, 20);
+p.distanceTo(point(30, 40));  // distance
+p.midpointTo(point(30, 40));  // midpoint
+p.translate(5, 5);            // new point
+p.toTuple();                  // [10, 20]
+```
+
+### `line(x1, y1, x2, y2)` / `Line2D`
+A named 2D line segment.
+
+```javascript
+const l = line(0, 0, 50, 0);
+l.length;      // 50
+l.midpoint;    // Point2D
+l.angle;       // degrees
+l.direction;   // [1, 0]
+l.parallel(10); // parallel line offset by 10
+
+// Line-line intersection (infinite lines)
+const l2 = line(25, -10, 25, 40);
+l.intersect(l2);        // Point2D(25, 0) — treats as infinite lines
+l.intersectSegment(l2); // Point2D or null — only if segments actually cross
+
+// Construction methods
+Line2D.fromCoordinates(0, 0, 50, 0);
+Line2D.fromPointAndAngle(point(0, 0), 45, 100);
+Line2D.fromPointAndDirection(point(0, 0), [1, 1], 50);
+```
+
+### `circle(cx, cy, radius)` / `Circle2D`
+A named 2D circle.
+
+```javascript
+const c = circle(0, 0, 25);
+c.diameter;        // 50
+c.circumference;   // ~157
+c.area;            // ~1963
+c.pointAtAngle(90); // Point2D at top
+
+// Extrude to cylinder with topology
+const cyl = c.extrude(30);
+cyl.face('top');    // FaceRef (planar)
+cyl.face('side');   // FaceRef (curved, planar === false)
+
+// Construction methods
+Circle2D.fromCenterAndRadius(point(0, 0), 25);
+Circle2D.fromDiameter(point(0, 0), 50);
+```
+
+### `rectangle(x, y, w, h)` / `Rectangle2D`
+A rectangle with named sides and vertices.
+
+```javascript
+const r = rectangle(0, 0, 100, 60);
+
+// Named sides
+r.side('top');     // Line2D
+r.side('bottom');  // Line2D
+r.side('left');    // Line2D
+r.side('right');   // Line2D
+r.sideAt(0);       // bottom (by index)
+
+// Named vertices
+r.vertex('top-left');      // Point2D
+r.vertex('bottom-right');  // Point2D
+
+// Properties
+r.width;   // 100
+r.height;  // 60
+r.center;  // Point2D
+
+// Diagonals — returns [bl-tr, br-tl] as Line2D pair
+const [d1, d2] = r.diagonals();
+const center = d1.intersect(d2);  // Point2D at center
+
+// Convert to Sketch for rendering
+r.toSketch();
+
+// Extrude to 3D with topology tracking
+const tracked = r.extrude(20);  // TrackedShape
+
+// Construction methods
+Rectangle2D.fromDimensions(0, 0, 100, 60);
+Rectangle2D.fromCenterAndDimensions(point(50, 30), 100, 60);
+Rectangle2D.from2Corners(point(0, 0), point(100, 60));
+Rectangle2D.from3Points(p1, p2, p3);  // free-angle rectangle
+```
+
+## 3D Topology (TrackedShape)
+
+When you extrude a `Rectangle2D`, you get a `TrackedShape` that knows its faces and edges by name.
+
+```javascript
+const rect = Rectangle2D.fromCenterAndDimensions(point(0, 0), 100, 60);
+const box = rect.extrude(20);
+
+// Named faces
+box.face('top');          // FaceRef { normal, center, planar, uAxis, vAxis }
+box.face('bottom');
+box.face('side-left');
+box.face('side-right');
+box.face('side-top');     // the side from rect's top edge
+box.face('side-bottom');  // the side from rect's bottom edge
+
+// Named edges
+box.edge('top-left');     // EdgeRef { start, end } — top face, left side
+box.edge('bottom-right'); // bottom face, right side
+box.edge('vert-bl');      // vertical edge at bottom-left corner
+
+// List all
+box.faceNames();  // ['top', 'bottom', 'side-bottom', 'side-right', 'side-top', 'side-left']
+box.edgeNames();  // all 12 edges
+
+// Use the underlying Shape for booleans
+const result = box.toShape().subtract(cylinder(25, 10));
+
+// Translate preserves topology
+const moved = box.translate(50, 0, 0);
+moved.face('top').center;  // shifted by [50, 0, 0]
+
+// Duplicate preserves topology metadata too
+const copy = box.clone();
+copy.face('side-left');
+```
+
+## Constraint Helpers
+
+```javascript
+const sketch = constrainedSketch();
+const p1 = sketch.point(0, 0, true);
+const p2 = sketch.point(50, 0);
+const p3 = sketch.point(50, 30);
+const l1 = sketch.line(p1, p2);
+const l2 = sketch.line(p2, p3);
+
+Constraint.horizontal(sketch, l1);
+Constraint.vertical(sketch, l2);
+Constraint.length(sketch, l1, 50);
+Constraint.perpendicular(sketch, l1, l2);
+
+const result = sketch.close().solve();
+```
+
+### Entity-aware constraints
+
+Constraint functions accept `Point2D`/`Line2D` directly — they auto-import into the builder:
+
+```javascript
+const sketch = constrainedSketch();
+const myLine = line(0, 0, 50, 0);
+const myRect = rectangle(10, 10, 40, 30);
+
+// Pass Line2D directly — auto-imported
+Constraint.makeParallel(sketch, myLine, myRect.side('top'));
+Constraint.horizontal(sketch, myLine);
+```
+
+### Importing entities into a constrained sketch
+
+```javascript
+const sketch = constrainedSketch();
+const r = rectangle(0, 0, 100, 60);
+const sides = sketch.importRectangle(r);
+// sides.bottom, sides.right, sides.top, sides.left are LineIds
+// sides.points is [bl, br, tr, tl] PointIds
+
+Constraint.horizontal(sketch, sides.bottom);
+Constraint.length(sketch, sides.bottom, 100);
+```
+
+
+## Patterns
+
+### `linearPattern(shape, count, dx, dy, dz?)`
+Repeat a shape along a direction vector, returning the union.
+
+```javascript
+const bolt = cylinder(10, 3);
+const row = linearPattern(bolt, 5, 20, 0);  // 5 bolts, 20mm apart along X
+```
+
+### `circularPattern(shape, count, centerX?, centerY?)`
+Repeat a shape around the Z axis, returning the union.
+
+```javascript
+const hole = cylinder(12, 4).translate(30, 0, -1);
+const holes = circularPattern(hole, 8);  // 8 holes evenly spaced
+```
+
+### `mirrorCopy(shape, normal)`
+Mirror a shape and union with the original.
+
+```javascript
+const half = box(50, 30, 10);
+const full = mirrorCopy(half, [1, 0, 0]);  // Mirror across YZ plane
+```
+
+For compile-covered source shapes, repeated instances created by `linearPattern`, `circularPattern`, `Shape.mirror()`, and `mirrorCopy()` keep distinct compiler owner lineage. Supported boolean unions now preserve owner-scoped canonical face queries for those repeated descendants, so later compiler inspections can still trace which repeated instance a preserved face came from. Durable post-merge face identity is still narrower than full CAD-style topology naming: reusing the same owner lineage twice without a fresh mirror/pattern owner is reported as ambiguous, and downstream subtract/intersect rewrites still record split descendants explicitly instead of guessing.
+
+## Utility Functions
+
+### `degrees(deg)` / `radians(rad)`
+Angle conversion helpers for readability:
+
+```javascript
+degrees(45);              // 45 (identity — just for clarity)
+radians(Math.PI / 4);    // 45 (converts radians to degrees)
+```
+
+## Fillets & Chamfers
+
+### `filletEdge(shape, edge, radius, quadrant?, segments?)`
+Compiler-owned edge fillet for the current tracked-edge subset.
+
+Supported today:
+- tracked vertical edges from compile-covered `box()` bodies
+- tracked vertical edges from `rectangle(...).extrude(...)`
+- rigid transforms between the tracked source body and the target shape
+- untouched sibling tracked vertical edges after earlier supported `filletEdge(...)` / `chamferEdge(...)` rewrites on the same body
+- preserved propagated vertical-edge queries after those supported edge-finish rewrites when a later supported boolean union keeps one defended edge lineage
+
+Still out of subset today:
+- the selected edge after an earlier `filletEdge(...)` / `chamferEdge(...)` rewrite as a new single finish target, because Forge now records that path as an explicit descendant edge-chain rather than pretending it stayed one edge
+- edge descendants after shell, hole/cut, trim, boolean difference/intersection, or boolean unions that did not already record one supported propagated edge lineage for the selection
+- generic sketch extrudes, tapered extrudes, and arbitrary feature-created edges
+
+Canonical quadrants for the supported rectangle/box edges:
+- `vert-bl` -> `[1, -1]`
+- `vert-br` -> `[-1, -1]`
+- `vert-tr` -> `[-1, 1]`
+- `vert-tl` -> `[1, 1]`
+
+```javascript
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const filleted = filletEdge(b.toShape(), b.edge('vert-br'), 5, [-1, -1]);
+```
+
+### `chamferEdge(shape, edge, size, quadrant?)`
+Compiler-owned edge chamfer for the same tracked vertical-edge subset as `filletEdge(...)`.
+
+```javascript
+const b = rectangle(0, 0, 50, 50).extrude(20);
+const chamfered = chamferEdge(b.toShape(), b.edge('vert-br'), 3, [-1, -1]);
+```
+
+## Arc Bridge
+
+### `arcBridgeBetweenRects(rectA, rectB, segments?)`
+Build a smooth arc surface connecting two rectangular areas. Automatically finds the closest pair of parallel edges and bridges them with a semicircular arc.
+
+**Parameters:**
+- `rectA` — `Rectangle2D` or `{ corners: [[x,y,z], [x,y,z], [x,y,z], [x,y,z]] }`
+- `rectB` — same format as rectA
+- `segments` (number, optional) — Arc smoothness. Default: 12
+
+**Returns:** `Shape` — thin arc solid
+
+```javascript
+// 2D rectangles (z=0)
+const base = rectangle(0, 0, 300, 200);
+const screen = rectangle(0, 200, 300, 200);
+const hinge = arcBridgeBetweenRects(base, screen, 16);
+```
+
+```javascript
+// 3D corners for non-planar rectangles
+const hinge = arcBridgeBetweenRects(
+  { corners: [[0,0,0], [300,0,0], [300,200,0], [0,200,0]] },
+  { corners: [[0,200,15], [300,200,15], [300,400,15], [0,400,15]] },
+  16,
+);
+```

package/dist-skill/docs/API/model-building/geometry-conventions.md

@@ -0,0 +1,104 @@
+# Geometry Conventions
+
+ForgeCAD wraps Manifold (a mesh kernel) and Three.js (a Y-up renderer). These libraries have their own conventions that conflict with each other and with CAD norms. This doc captures every convention mismatch and how ForgeCAD resolves it.
+
+**Core principle: the user script should never need to know about kernel or renderer internals.** If the user writes something geometrically reasonable, it should work. All convention translation happens inside ForgeCAD's layer.
+
+## Winding Order
+
+**What it is:** The order of vertices in a 2D polygon determines its "direction" — counter-clockwise (CCW) = positive area, clockwise (CW) = negative/zero area in Manifold's `CrossSection`.
+
+**The problem:** Manifold silently produces empty geometry for CW polygons. A user writing `polygon([[0,0], [50,0], [50,30]])` vs `polygon([[0,0], [50,30], [50,0]])` gets either a triangle or nothing, with no error.
+
+**ForgeCAD's fix:** All entry points that accept raw points auto-fix winding:
+- `polygon(points)` — computes signed area, reverses if CW
+- `path().close()` — same fix
+
+**Signed area test** (shoelace formula):
+```
+signedArea = Σ (x₂ - x₁)(y₂ + y₁)
+```
+If `signedArea > 0` → CW → reverse to make CCW.
+
+**Implementation:** `src/forge/sketch/primitives.ts` (polygon), `src/forge/sketch/path.ts` (close).
+
+**Rule for new code:** Any function that takes user-provided point arrays and creates a `CrossSection` MUST auto-fix winding. Never pass raw user points to Manifold without this check.
+
+## Coordinate System (Z-up vs Y-up)
+
+**The problem:** Three.js uses Y-up. CAD convention (and ForgeCAD) uses Z-up.
+
+**ForgeCAD's fix:** We set `camera.up = (0, 0, 1)` everywhere. Geometry coordinates are native Z-up — no matrix swizzling. The camera orientation handles the visual mapping.
+
+**Where this matters:**
+- `camera.up.set(0, 0, 1)` in `sceneBuilder.ts` and `render.ts`
+- GizmoViewcube face labels remapped (see coordinate-system.md)
+- Grid plane is XY (Z=0)
+- Extrusion goes along +Z
+- Revolution axis is Y (sketch plane), result maps to Z-up space
+
+**Rule for new code:** Never swap Y/Z in geometry. Always fix it at the camera/renderer level.
+
+## Revolution Axis
+
+**What it is:** `CrossSection.revolve()` in Manifold revolves around the Y axis. The sketch profile must be in the X-Y plane with X = radius (distance from axis) and Y = height.
+
+**The mapping:**
+- Profile X coordinate → radial distance from center
+- Profile Y coordinate → height (becomes Z after revolution)
+- Profile must be on the positive X side (X > 0) for valid geometry
+
+**Rule for new code:** Document which axis any new sweep/revolution operation uses. If it differs from user expectation, add a transform wrapper.
+
+## Boolean Winding (3D)
+
+**What it is:** Manifold requires consistent face normals (outward-pointing) for boolean operations. Manifold handles this internally for its own primitives, but imported meshes or degenerate operations can produce inside-out faces.
+
+**ForgeCAD's fix:** We only create meshes through Manifold's own constructors (`extrude`, `revolve`, `cylinder`, `sphere`, etc.), which guarantee correct normals. No raw mesh import path exists yet.
+
+**Rule for new code:** If adding mesh import (STL, OBJ), run `Manifold.asOriginal()` or validate manifoldness before allowing booleans.
+
+## Transform Order
+
+**What it is:** Transforms are applied in call order (left to right in the chain). `shape.translate(10,0,0).rotate(0,0,45)` first moves, then rotates around origin — so the shape orbits.
+
+**Convention:** This matches the standard "post-multiply" convention. No surprises here, but worth noting because some systems (OpenSCAD) apply transforms in reverse order.
+
+For explicit transform objects:
+- `A.mul(B)` means **apply A, then B**.
+- `composeChain(A, B, C)` means **A -> B -> C**.
+
+**Rule for new code:** Keep this chain order everywhere. Document any operation that deviates.
+
+## Assembly Frame Composition
+
+This is where regressions are most likely if convention is unclear.
+
+For a point in child geometry-local coordinates:
+- local -> `childBase` -> `jointMotion(value)` -> `jointFrame` -> `parentWorld`
+
+In Forge chain notation:
+```ts
+childWorld = composeChain(childBase, jointMotion, jointFrame, parentWorld)
+```
+
+Equivalent matrix-style equation (for reference):
+```txt
+T_world_child = T_parent_world * T_joint_frame * T_joint_motion * T_child_base
+```
+
+**Rule for new code:** In kinematics/assembly code, prefer `composeChain(...)` over manual `.mul(...).mul(...)` sequences to avoid order mistakes.
+
+## Summary of Shield Points
+
+These are the places where ForgeCAD translates between "what the user means" and "what the kernel needs":
+
+| Convention | User sees | Kernel needs | Where we fix it |
+|---|---|---|---|
+| Winding | Any point order | CCW | `polygon()`, `path().close()` |
+| Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
+| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented, not auto-fixed |
+| Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
+| Transform order | Left-to-right chain | Post-multiply | Native match, no fix needed |
+
+When adding new geometry operations, check this table. If the operation introduces a new convention mismatch between user intent and kernel requirement, either auto-fix it (preferred) or document it clearly in the API docs.