forgecad 0.6.3 → 0.8.0

package/dist-skill/docs/API/README.md

@@ -1,37 +0,0 @@
-# ForgeCAD API Documentation
-
-This directory contains **hand-written API guides** for model authors. For auto-generated API docs extracted from source, see the [`generated/`](../generated/) directory (one file per module).
-
-## Directory Layout
-
-| Directory | Audience | What's in it |
-|-----------|----------|-------------|
-| `core/` | Model authors | Core reference: primitives, transforms, booleans, imports, parameters, topology, specs |
-| `sketch/` | Model authors (sketch-heavy tasks) | 2D sketch construction, transforms, booleans, on-face, extrude |
-| `assembly/` | Model authors (mechanisms) | Assembly graph, joints, couplings, kinematics |
-| `sheet-metal/` | Model authors (folded parts) | Sheet metal, flanges, flat patterns |
-| `runtime/` | Model authors (viewport) | Cut planes, exploded views, joint controls |
-| `output/` | Model authors (export/reports) | BOM, dimensions, G-code toolpaths, mesh export, STEP/BREP export |
-| `toolbox/` | Model authors (library) | Fasteners, hardware helpers |
-
-## Read Plan
-
-> Load only what the current task needs. Start from the top, add docs as needed.
-
-1. **Always start with** `core/reference.md` — the core script contract
-2. **For geometry orientation**: `../guides/coordinate-system.md`, `../guides/geometry-conventions.md`, `../guides/positioning.md`
-3. **For sketch-heavy work**: `sketch/*.md` (9 files covering 2D APIs)
-4. **For topology/constraints**: `core/topology.md`
-5. **For assemblies**: `assembly/assembly.md`
-6. **For sheet metal**: `sheet-metal/sheet-metal.md`
-7. **For viewport controls**: `runtime/viewport.md`
-8. **For recipes/debugging**: `../guides/modeling-recipes.md`
-9. **For CLI/export**: `../cli.md`, `output/*.md`
-
-## Adjacent Documentation
-
-- **[`../generated/api-reference.md`](../generated/api-reference.md)** — Auto-generated complete API index (run `npm run gen:docs` to refresh)
-- **[`../guides/`](../guides/)** — Conceptual orientation: coordinate system, conventions, recipes
-- **[`../internals/`](../internals/)** — Engine internals for ForgeCAD contributors
-- **[`../project/`](../project/)** — Development workflow, coding standards, deployment
-- **[`../cli.md`](../cli.md)** — CLI reference

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

@@ -1,617 +0,0 @@
----
-skill-group: assembly
-skill-order: 1
----
-
-# 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),
-  });
-
-return mech; // auto-solved at defaults, renders all parts
-```
-
-Returning `mech` (unsolved Assembly) auto-solves at default joint values and renders all parts.  You can also return a `SolvedAssembly` for a specific pose:
-
-```javascript
-return mech.solve({ shoulder: 60 });
-```
-
-## Return types and imports — how they fit together
-
-| Return value | Standalone | `require()` result type |
-|---|---|---|
-| `Shape` | yes | `Shape` |
-| `Sketch` | yes | `Sketch` |
-| `ShapeGroup` | yes | `ShapeGroup` |
-| `Assembly` (unsolved) | **yes** | `ImportedAssembly` |
-| `SolvedAssembly` | **yes** | `SolvedAssembly` |
-
-Use `require("./file.forge.js")` to import any `.forge.js` file. Pass param overrides as the second argument: `require("./file.forge.js", { Speed: 2 })`.
-
-**`Assembly` is the dual-use type**: a file that returns an unsolved `Assembly` works both as a standalone renderable script *and* as an import target for `require()` (which returns an `ImportedAssembly`).
-
-Pattern for dual-use assembly files:
-
-```javascript
-// handle.forge.js — works standalone AND importable via require()
-const mech = assembly("Handle")
-  .addPart("Base", baseBracket)
-  .addPart("Arm", arm)
-  .addRevolute("Fold", "Base", "Arm", { axis: [0, 1, 0], min: 0, max: 90 });
-
-// Animation setup — runs when standalone, ignored on import
-mech.toJointsView({
-  animations: [{ name: "Fold", duration: 2, loop: true,
-    keyframes: [{ values: { Fold: 0 } }, { values: { Fold: 90 } }, { values: { Fold: 0 } }],
-  }],
-});
-
-return mech; // works standalone (auto-solved + animated) AND with require()
-```
-
-```javascript
-// case.forge.js — imports the handle as a positioned assembly
-const handle = require("./handle.forge.js");
-
-// Convenience transforms: solve at defaults, return ShapeGroup
-const handleGroup = handle.rotate(0, 0, -90).translate(0, -20, 50);
-
-return [
-  { name: "Case", shape: caseBody },
-  { name: "Handle", shape: handleGroup },
-];
-```
-
-## Connector-based assembly
-
-**Connectors** are typed, gendered ports. They carry semantic metadata (type like `"dovetail"`, gender `male`/`female`/`neutral`, and optional measurements) that enables automatic positioning, type/gender validation, and connector-aware explode views.
-
-### Defining connectors
-
-```javascript
-const shelf = box(200, 120, 10, true).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
-  right_tab: connector.male("dovetail", { origin: [100, 0, 0], axis: [1, 0, 0] }),
-});
-```
-
-Connector factories: `connector.male(type, portInput)`, `connector.female(type, portInput)`, `connector.neutral(type, portInput)`.
-
-Connectors are stored as ports with extra metadata — they work everywhere ports work (`connect()`, `assembly.match()`, transforms, imports).
-
-### `matchTo()` — Static connector matching (no assembly needed)
-
-Position a part by snapping its connector to a target's connector. Full 6-DOF alignment: origins coincide, axes anti-parallel.
-
-```javascript
-// Single pair
-const placed = shelf.matchTo(panel, "left_tab", "shelf_slot_0");
-
-// Dictionary (multiple pairs, same target)
-const placed = shelf.matchTo(panel, { left_tab: "shelf_slot_0", right_tab: "shelf_slot_1" });
-```
-
-Works on `Shape` and `ShapeGroup`. Matched parts auto-get explode hints — the viewport explode slider separates them along connector axes.
-
-### `assembly.match()` — Auto-create joints from connectors
-
-```javascript
-const mech = assembly("Door")
-  .addPart("Frame", frame)
-  .addPart("Door", door)
-  .match("Door", "Frame", { hinge_top: "hinge_top" });
-// Revolute connectors → auto-creates revolute joint. No manual addRevolute needed.
-```
-
-### Connector queries
-
-```javascript
-shape.connectorNames()                    // all connector names
-shape.connectorsByType("dovetail")        // filter by type
-shape.connectorDistance("slot_1", "slot_2") // 3D distance between origins
-shape.connectorMeasurements("mount")      // { bolt_circle: 31, ... }
-```
-
-### Auto-bubbling through groups
-
-Named group children automatically expose their connectors via dotted paths:
-
-```javascript
-const cabinet = group(
-  { name: "Left", shape: leftPanel },
-  { name: "Right", shape: rightPanel },
-);
-cabinet.connectorNames() // → ["Left.shelf_0", "Left.shelf_1", "Right.shelf_0", ...]
-shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
-```
-
-## Port-based assembly
-
-Declare **ports** on parts and let `connect()` align them automatically — no manual `frame` or `axis` math.
-
-### When to use `match()` vs `connect()` vs `addRevolute()`
-
-| Pattern | Use | Example |
-|---------|-----|---------|
-| **Typed connectors with validation** | `match()` | Connector type + gender checking, auto joint creation |
-| **Ports physically meet** | `connect()` | Flange-to-flange, bolt-to-hole, motor shaft into gear bore |
-| **Shared axis, offset position** | `addRevolute()` | Hinge with arm between two ear brackets, scissor linkage |
-
-`connect()` aligns port origins — child port lands exactly on parent port. Use it when the attachment points should coincide. For mechanisms where parts share a rotation axis but are deliberately spaced apart along it (e.g. a folding hinge arm that sits between bracket ears), use `addRevolute()` with pre-positioned parts and let the transform cancellation handle placement.
-
-### Declaring ports
-
-A port is an oriented attachment frame: origin + axis + up vector, in part-local coordinates.
-
-```javascript
-const base = box(80, 80, 20, true).withPorts({
-  top: port.revolute({
-    origin: [0, 0, 10],
-    axis: [0, 0, 1],      // joint rotation axis
-    up: [0, 1, 0],         // zero-angle reference (optional, auto-computed if omitted)
-  }),
-});
-
-const arm = box(120, 20, 20).translate(60, 0, 0).withPorts({
-  shoulder: port.revolute({ origin: [0, 0, 0], axis: [0, 0, 1] }),
-  elbow: port.revolute({ origin: [120, 0, 0], axis: [0, 0, 1] }),
-});
-```
-
-Port factories: `port.revolute(...)`, `port.prismatic(...)`, `port.fixed(...)`, or generic `port(...)`.
-
-**Alternative: define by physical extent** — use `start`/`end` instead of `origin`/`axis`:
-
-```javascript
-// Origin and axis auto-computed from start→end
-const arm = arm3D.withPorts({
-  bore: port.revolute({
-    start: [0, -armWidth/2, 0],   // bore entrance
-    end: [0, armWidth/2, 0],       // bore exit
-  }),
-});
-```
-
-This also stores the extent length for alignment (see below).
-
-Ports survive transforms — if you `translate()` or `rotate()` a shape, its ports move with it.
-
-### Connecting parts
-
-```javascript
-const mech = assembly("Arm")
-  .addPart("Base", base)
-  .addPart("Link", arm)
-  .connect("Base.top", "Link.shoulder", {
-    as: "J1",              // joint name (auto-generated if omitted)
-    min: -90, max: 90,     // optional limits
-    default: 0,            // optional default angle
-  });
-
-const solved = mech.solve({ J1: 45 });
-return solved.toScene();
-```
-
-`connect()` computes the joint `frame` and `axis` from port alignment, then delegates to `addJoint()` internally. The kinematic solver is unchanged.
-
-**ConnectOptions:** `as`, `type` (override port kind), `min`, `max`, `default`, `unit`, `flip` (oppose axes for mirrored parts), `align` / `parentAlign` / `childAlign` (start/middle/end), `effort`, `velocity`, `damping`, `friction`.
-
-**Alignment along port extent:** When ports are defined with `start`/`end`, you can control which points align:
-
-```javascript
-.connect("Pin.shaft", "Arm.bore", { align: "middle" })  // default — midpoints meet
-.connect("Pin.shaft", "Arm.bore", { align: "start" })   // start points meet
-.connect("Pin.shaft", "Arm.bore", { align: "end" })     // end points meet
-.connect("Pin.shaft", "Arm.bore", {
-  parentAlign: "start", childAlign: "middle",            // independent control
-})
-```
-
-**Mirrored parts:** When a part is created with `.mirror()`, its port axis flips direction. Use `flip: true` on the connect call so the axes oppose rather than align:
-
-```javascript
-.connect("Right Base.hinge", "Right Arm.pivot", {
-  as: "Fold Right", flip: true,
-})
-```
-
-### Derived jointsView
-
-Instead of manually restating the kinematic chain for `jointsView()`, derive it from the assembly graph:
-
-```javascript
-mech.toJointsView({
-  defaults: { J1: 30 },
-  animations: [
-    {
-      name: "Swing",
-      duration: 2,
-      loop: true,
-      keyframes: [
-        { values: { J1: -45 } },
-        { values: { J1: 45 } },
-        { values: { J1: -45 } },
-      ],
-    },
-  ],
-});
-
-// IMPORTANT: solve at REST when using toJointsView — the viewport handles posing.
-return mech.solve().toScene();
-```
-
-`toJointsView()` solves the assembly at rest, computes world-space pivots and axes, and calls the existing `jointsView()` function. No manual pivot coordinates needed.
-
-**Fixed attachments are handled automatically.** Parts connected with `addFixed()` are emitted as zero-range revolute joints in the viewport chain, so they follow their parent during animation (e.g. a stick bolted to an arm will rotate with it).
-
-**Do not solve at a non-zero angle when using `toJointsView()`.** The viewport applies `toJointsView` transforms on top of the scene — solving at the same angle would double-rotate parts. Use `defaults` to set the initial pose instead:
-
-```javascript
-// BAD — double rotation
-mech.toJointsView({ defaults: { J1: 45 } });
-return mech.solve({ J1: 45 }).toScene();
-
-// GOOD — solve at rest, viewport poses via defaults
-mech.toJointsView({ defaults: { J1: 45 } });
-return mech.solve().toScene();
-```
-
-### Port API on shapes
-
-- `shape.withPorts({ name: port.revolute({...}) })` — attach ports (returns new shape)
-- `shape.portNames()` — list port names
-- Works on `Shape`, `TrackedShape`, and `ShapeGroup`
-
-### Port API on assemblies
-
-- `assembly.withPorts("PartName", { name: port.revolute({...}) })` — add ports to an existing part
-- `assembly.getPorts("PartName")` — get ports on a part
-- `assembly.getPort("Part.port")` — resolve a "Part.port" reference
-- Ports from imported parts are captured automatically in `addPart()`
-- Ports are forwarded through `mergeInto()` with the prefix
-
-## 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.
-
-## SolvedAssembly
-
-`mech.solve(state?)` returns a `SolvedAssembly` with these methods:
-
-| Method | Returns | Use for |
-|--------|---------|---------|
-| `toGroup()` | `ShapeGroup` | Primary way to get positioned parts as a group — for `show()`, embedding, transforms |
-| `getPart(name)` | `AssemblyPart` | Extract a single part at its solved position |
-| `getTransform(name)` | `Transform` | Raw world transform for a part |
-| `bom()` / `bomCsv()` | `BomRow[]` / `string` | Bill of materials |
-| `collisionReport()` | `CollisionFinding[]` | Interference detection |
-| `minClearance(a, b)` | `number` | Minimum gap between two parts |
-| `toSceneObjects()` | `Array<{name, shape?, group?}>` | Advanced: raw scene-graph array for custom rendering |
-
-**`toGroup()`** is the preferred way to convert a solved assembly to a positionable group:
-
-```javascript
-const solved = mech.solve({ shoulder: 45 });
-show(solved.toGroup()); // in notebooks
-```
-
-## 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);
-```
-
-That keeps mechanism setup in earlier cells and collision/sweep investigation in the current preview cell.
-
-## ImportedAssembly
-
-`require("./assembly.forge.js")` returns an `ImportedAssembly` when the file returns an `Assembly`. It has these capabilities:
-
-### Kinematic access
-
-```javascript
-const arm = require("./arm.forge.js");
-
-// Full kinematic access
-const solved = arm.solve({ shoulder: 45 });
-console.log(solved.bom());
-arm.assembly.sweepJoint("shoulder", -30, 120, 24);
-```
-
-### Extracting parts
-
-```javascript
-const base = arm.part("Base");                   // at default state
-const link = arm.part("Link", { shoulder: 60 }); // at specific state
-```
-
-### Converting to group
-
-```javascript
-const g = arm.toGroup({ shoulder: 45 }); // ShapeGroup with named children
-const baseChild = g.child("Base");
-```
-
-### Convenience transforms
-
-`ImportedAssembly` has `.rotate()`, `.translate()`, `.scale()`, `.mirror()`, `.color()`, and `.child()` that auto-solve at defaults and return a `ShapeGroup`:
-
-```javascript
-const handle = require("./handle.forge.js");
-const positioned = handle.rotate(0, 0, -90).translate(0, -20, 50);
-// positioned is a ShapeGroup — use directly in named arrays or group()
-```
-
-### Placement references
-
-```javascript
-const arm = require("./arm.forge.js");
-const placed = arm.placeReference("mountHole", [100, 0, 50]);
-```
-
-## Merging sub-assemblies into a parent
-
-`importedAssembly.mergeInto(parent, options)` flattens a sub-assembly's parts and joints into a parent `Assembly`, then wires a mount joint connecting a parent part to the sub-assembly root. After the merge, the parent graph can drive sub-assembly joints directly.
-
-```javascript
-// scene.forge.js
-const chassis = box(200, 80, 20, true);
-
-const robot = assembly("Robot")
-  .addPart("Chassis", chassis);
-
-// Merge left arm — all parts/joints prefixed "Left Arm."
-require("./arm.forge.js")
-  .mergeInto(robot, {
-    prefix: "Left Arm",
-    mountParent: "Chassis",
-    mountJoint: "leftMount",
-    mountOptions: { frame: Transform.identity().translate(-70, 0, 10) },
-  });
-
-// Merge right arm — same source file, different prefix and position
-require("./arm.forge.js")
-  .mergeInto(robot, {
-    prefix: "Right Arm",
-    mountParent: "Chassis",
-    mountJoint: "rightMount",
-    mountOptions: { frame: Transform.identity().translate(70, 0, 10) },
-  });
-
-// Drive sub-assembly joints from the parent using prefixed names
-return robot.solve({
-  "Left Arm.shoulder": 45,
-  "Right Arm.shoulder": -20,
-});
-```
-
-**`mergeInto(parent, options)` options:**
-
-| Option | Type | Required | Description |
-|---|---|---|---|
-| `prefix` | `string` | recommended | Prefix for all part and joint names. `"Left Arm"` turns `"Base"` into `"Left Arm.Base"`. |
-| `mountParent` | `string` | yes | Part name in `parent` to attach the sub-assembly root to. |
-| `mountJoint` | `string` | yes | Name for the new mount joint in the parent graph. |
-| `mountType` | `JointType` | no | Joint type for the mount (default: `'fixed'`). |
-| `mountOptions` | `JointOptions` | no | Frame, axis, limits, etc. for the mount joint. |
-
-**Notes:**
-- The sub-assembly must have exactly one root part. If it has multiple roots, connect them with `addFixed()` first.
-- Joint couplings inside the sub-assembly are preserved and rewritten with the prefix.
-- After merging, use `parent.sweepJoint("Left Arm.shoulder", ...)` for collision sweeps across the full hierarchy.
-- Returns `parent` for chaining.
-
-## Common pitfalls
-- **Animating assemblies with `jointsView`**: If you use [`jointsView()`](../runtime/viewport.md) to animate an assembly, solve the assembly at rest pose (all animated joints = 0) and let `jointsView` control posing via `default` values and animation keyframes. Solving at non-zero angles and then animating will double-rotate parts. See the [viewport docs](../runtime/viewport.md#using-jointsview-with-assemblies) for the full pattern.
-- 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,
-  },
-});
-```
-
-### Export formats
-
-```bash
-# SDF package (Gazebo/Ignition) — generates model.sdf + world + STL meshes
-forgecad export sdf model.forge.js
-
-# URDF package (ROS/PyBullet/MuJoCo) — generates .urdf + STL meshes
-forgecad export urdf model.forge.js
-```
-
-Both exporters produce:
-- **Mesh-based inertia tensors** — computed from actual triangle geometry via divergence theorem (not bounding-box approximation). Includes full 6-component tensor (Ixx, Iyy, Izz, Ixy, Ixz, Iyz) and center of mass.
-- **Separate collision meshes** — controlled per-link via `collision` option.
-- **Joint mimic elements** — joint couplings (`addJointCoupling`, `addGearCoupling`) are exported as `<mimic>` elements in both SDF and URDF.
-
-### Collision mesh modes
-
-Set per-link in `robotExport({ links: { "PartName": { collision: mode } } })`:
-
-| Mode | Description | Default |
-|------|-------------|---------|
-| `'convex'` | Convex hull of visual geometry (separate `_collision.stl`). Typically 50-80% smaller. | **Yes** |
-| `'box'` | Axis-aligned bounding box primitive. Fastest physics but least accurate. | |
-| `'visual'` | Same mesh as visual. Exact but slow for simulation. | |
-| `'none'` | No collision geometry. Link passes through other objects. | |
-
-### Notes
-
-- Revolute joint `velocity` values are expressed in degrees/second in Forge; the exporters convert 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.
-- Joint couplings with multiple terms use the primary term (largest ratio) for `<mimic>` since SDF/URDF only support single-leader mimic. A warning is emitted for dropped terms.