forgecad 0.9.16 → 0.10.1

package/dist/docs-raw/generated/assembly.md

@@ -5,98 +5,94 @@ skill-order: 100
 
 # Assembly API
 
-Assembly-owned links, constraints, connectors, solved poses, and robot export.
+Assembly-owned links, constraints, connectors, solved poses, and source-level simulation metadata.
 
 ## Contents
 
-- [Assembly & Joints](#assembly-joints) — `bomToCsv`, `assembly`
+- [Assembly & Joints](#assembly-joints)
 - [Assembly](#assembly) — Kinematics, Structure, Connectors, References, Solving
 - [ImportedAssembly](#importedassembly)
 - [SolvedAssembly](#solvedassembly)
-- [MateBuilder](#matebuilder)
 
 ## Functions
 
 ### Assembly & Joints
 
-#### `bomToCsv()` — Convert an array of BOM rows into a CSV string.
+#### `Sim.material(name: string, options?: SimMaterialOptions): SimMaterialDef` — Create a named physical material with density and contact coefficients for simulation export and checks.
 
-Produces a CSV with columns: `part`, `qty`, `material`, `process`, `tolerance`, `notes`. String values are quoted and internal double-quotes are escaped. Prefer calling `solvedAssembly.bomCsv()` directly — this function is exposed for custom BOM processing.
+`SimMaterialOptions`: `{ densityKgM3?: number, staticFriction?: number, dynamicFriction?: number, restitution?: number }`
 
-```ts
-bomToCsv(rows: BomRow[]): string
-```
 
-**`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
+`SimMaterialDef`: `{ kind: "material", name: string }`
 
-**`PartMetadata`**
+#### `Sim.body(options: SimBodyOptions): SimBodyDef` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces.
 
-| Option | Type | Description |
-|--------|------|-------------|
-| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
-| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
+**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`
 
-#### `assembly()` — Create an assembly container with named parts, connectors, and kinematic links.
+`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string }`
 
-**Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
+`SimContactDef`: `{ kind: "wheelSurface" | "gripperSurface", connectorName: string }`
 
-Links are named kinematic markers in the assembly. `edgeBetweenLinks()` records structural distances or visual relationships. `addAngleBetweenLinks()` records measured, limited, or controlled angles. These APIs solve point positions, not rigid-body frames.
 
-`addPart(..., { mate })` attaches a part connector origin to a solved link point by translation only. It is right for markers and point-following geometry. Use `connect()` / `match()` for physical articulated parts that need full connector frame alignment and deterministic rest orientation.
+`SimBodyDef`: `{ kind: "body" }`
 
-Return an `Assembly` directly to expose its connector joints and driven link controls in the editor. Moving those controls re-runs the assembly solve with the new state, so closed-loop link/edge mechanisms move through the real kinematic solver instead of a viewport-only forward-kinematics approximation.
+#### `Sim.collider` — Collision-geometry intent constructors for physical parts.
 
-If no link in a connected kinematic component is fixed, ForgeCAD chooses a deterministic gauge link for solving and reports a floating-component warning.
+- `Sim.collider.convexHull(): SimColliderDef` — Use a generated collision mesh for the part. This is the default fast rigid-body collider for irregular parts.
+- `Sim.collider.boundingBox(): SimColliderDef` — Use the part bounding box as the collision geometry. This is fastest and works well for chassis and simple blocks.
+- `Sim.collider.visualMesh(): SimColliderDef` — Use the visual mesh as collision geometry. This is exact but usually slower in physics engines.
+- `Sim.collider.none(reason: string): SimColliderDef` — Disable collision for a part with an explicit reason, such as a sensor-only or decorative object.
 
-The legacy joint-chain APIs still exist for compatibility and exporter plumbing. New work should choose between point-link kinematics and connector-frame joints based on whether the part needs orientation.
+#### `Sim.drive` — Joint-drive intent constructors for passive or powered assembly joints.
 
-For multi-file assemblies, a file that returns an `Assembly` is importable via [`require()`](/docs/core#require) and yields an `ImportedAssembly`. Use `mergeInto()` to flatten a sub-assembly into a parent assembly.
+- `Sim.drive.passive(options?: SimPassiveDriveOptions): SimDriveDef` — Mark a joint as passive while preserving damping and friction metadata for simulation export.
+- `Sim.drive.velocity(options: SimVelocityDriveOptions): SimDriveDef` — Mark a revolute joint as velocity-driven with torque and speed limits. Speed is authored in rpm and exported as deg/s or rad/s as needed.
 
-**Point-link example**
+`SimPassiveDriveOptions`: `{ damping?: number, friction?: number }`
 
-This snippet mates a marker to the solved `tip` point. It does not orient a bar along `ground -> tip`.
 
-```ts
-const marker = box(8, 8, 4).withConnectors({
-  center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
-});
+`SimVelocityDriveOptions`: `{ maxTorqueNm: number, maxSpeedRpm: number }`
 
-const mech = assembly("Linkage")
-  .link("ground", { at: [0, 0, 0], fixed: true })
-  .link("worldX", { at: [10, 0, 0], fixed: true })
-  .link("tip", { at: [40, 0, 0] })
-  .edgeBetweenLinks("ground", "tip", { name: "bar" })
-  .addAngleBetweenLinks("worldX", "ground", "tip", {
-    name: "theta",
-    control: { min: 0, max: 120, default: 30 },
-  })
-  .addPart("Tip marker", marker, { mate: { connector: "center", toLink: "tip" } });
+#### `Sim.contact` — Contact-surface metadata over existing part connectors.
 
-return mech;
-```
+- `Sim.contact.wheelSurface(connectorName: string): SimContactDef` — Mark a connector as the wheel tread contact surface for offline checks and downstream simulation metadata.
+- `Sim.contact.gripperSurface(connectorName: string): SimContactDef` — Mark a connector as a gripper pad/contact surface for offline checks and downstream grasp-readiness metadata.
 
-```ts
-assembly(name?: string): Assembly
-```
+#### `Sim.profile` — Named validation/export profile constructors.
 
----
+- `Sim.profile.robotBodyRunnable(): SimProfileDef` — SimReady-style profile for a robot body that should be runnable in a physics simulator.
+- `Sim.profile.robotBodyIsaac(): SimProfileDef` — SimReady-style profile for robot bodies targeting Isaac Sim readiness.
+- `Sim.profile.roboticsAssetPhysx(): SimProfileDef` — SimReady-style profile for robotics assets with PhysX-ready rigid bodies and colliders.
 
-## Classes
+`SimProfileDef`: `{ kind: "profile", name: SimProfileName }`
 
-### `Assembly`
+#### `Sim.controller` — Standard controller metadata constructors for simulator package generation.
+
+- `Sim.controller.diffDrive(options: SimDiffDriveControllerOptions): SimDiffDriveControllerDef` — Describe a differential-drive controller from left/right wheel joints and wheel dimensions.
+
+**`SimDiffDriveControllerOptions`**: `leftJoints: string[]`, `rightJoints: string[]`, `wheelSeparationMm: number`, `wheelRadiusMm: number`, `topic?: string`, `odomTopic?: string`, `tfTopic?: string`, `frameId?: string`, `odomFrameId?: string`, `maxLinearVelocity?: number`, `maxAngularVelocity?: number`, `linearAcceleration?: number`, `angularAcceleration?: number`
+
+
+`SimDiffDriveControllerDef`: `{ kind: "diffDrive" }`
+
+#### `assembly(name?: string): Assembly` — Create an assembly container with named parts, connectors, and kinematic links.
 
-Container for a kinematic mechanism made up of links, relationships, and parts.
+**Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
+
+Two motion tools:
+
+- **Link-graph kinematics** (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) solve named point positions — a link is a point, not a rigid-body frame. Use when the hard part is solving positions, especially closed loops.
+- **Connector-frame joints** (`connect()` / `match()`) align full connector frames (`origin`, `axis`, `up`) and derive joint frame + axis. Use for serial articulated parts whose orientation matters: hips, hinges, drums, sliders, wheels.
 
-Assembly has two related but different motion tools:
+`addPart(..., { mate })` places geometry on the solved link graph by **translation only**: one mate pins a connector origin to a link, two mates orient a part to span two solved links, a third pins roll. Right for markers and point-following geometry; use `connect()`/`match()` when the part needs a deterministic rest orientation.
 
-- **Link graph kinematics** (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) solve named point positions. A link is a point, not a rigid-body frame or bone. Connector-to-link mates then place geometry on the solved graph: one mate translates a connector origin onto a link, two mates orient a part so it spans between two solved links, and a third mate pins roll about that span.
-- **Connector-frame joints** (`connect()` / `match()`) align full connector frames and derive joint frame + axis from `origin`, `axis`, and `up`. Use this for serial articulated geometry such as hips, knees, hinges, drums, sliders, and wheels where the physical part orientation matters.
+Return the `Assembly` itself to expose its joints and driven link controls in the editor; moving a control re-runs `solve(state)`, so closed loops move through the real solver instead of a viewport-only FK approximation.
 
-Use link graphs when the hard part is solving positions, especially closed loops. Use connector-frame joints when the hard part is a serial tree of explicit rigid-body joint frames such as hinges, sliders, drums, and wheels.
+If no link in a connected kinematic component is fixed, ForgeCAD chooses a deterministic gauge link for solving and reports a floating-component warning.
 
-**Point-link quick start**
+A file that returns an `Assembly` is importable via [`require()`](/docs/core#require) and yields an `ImportedAssembly`; use `mergeInto()` to flatten it into a parent assembly.
 
-This attaches a marker to a solved point. It is intentionally not a bone or oriented part example.
+**Point-link example** (mates a marker to the solved `tip` point; does not orient a bar along `ground -> tip`):
 
 ```ts
 const marker = box(8, 8, 4).withConnectors({
@@ -112,46 +108,20 @@ const mech = assembly("Linkage")
     name: "theta",
     control: { min: 0, max: 120, default: 30 },
   })
-  .addPart("Tip marker", marker, {
-    mate: { connector: "center", toLink: "tip" },
-  });
+  .addPart("Tip marker", marker, { mate: { connector: "center", toLink: "tip" } });
 
 return mech;
 ```
 
-Returning an unsolved `Assembly` keeps the graph available to the runtime. Return a `SolvedAssembly` directly for a specific control state:
-
-```ts
-return mech.solve({ theta: 60 });
-```
+---
 
-**Frame-aware serial joint**
+## Classes
 
-```ts
-const hip = cylinder(12, 10).withConnectors({
-  socket: connector("hinge", {
-    origin: [0, 0, 6],
-    axis: [0, 0, 1],
-    up: [1, 0, 0],
-    kind: "revolute",
-  }),
-});
+### `Assembly`
 
-const upperLeg = box(60, 10, 8).translate(30, 0, -4).withConnectors({
-  hip: connector("hinge", {
-    origin: [0, 0, 0],
-    axis: [0, 0, -1],
-    up: [1, 0, 0],
-    kind: "revolute",
-  }),
-});
+Container for a kinematic mechanism made up of links, relationships, and parts. See `assembly` for the link-graph vs connector-frame decision rules.
 
-return assembly("Leg")
-  .addPart("Hip", hip)
-  .addPart("Upper Leg", upperLeg)
-  .connect("Hip.socket", "Upper Leg.hip", { as: "hip", min: -35, max: 55 })
-  .solve({ hip: 20 });
-```
+Returning an unsolved `Assembly` keeps the graph available to the runtime; return `mech.solve({ theta: 60 })` for a fixed pose instead.
 
 **Return types**
 
@@ -168,64 +138,61 @@ return assembly("Leg")
 
 **Kinematics**
 
-#### `link()` — Add a named kinematic link to the assembly graph.
+#### `link(name: string, options?: AssemblyLinkOptions): Assembly` — Add a named kinematic link to the assembly graph.
 
 Links are assembly-native solved points. They can exist before any geometry is attached, can be displayed by the viewport, and are solved by link/edge/angle constraints.
 
 A link is not a rigid-body frame. It has a world position but no orientation basis. Use `connect()` when a physical part must inherit a connector frame and rotate about a real hinge/slider axis.
 
-```ts
-link(name: string, options?: AssemblyLinkOptions): Assembly
-```
-
 **`AssemblyLinkOptions`**
-- `at?: [ number, number, number ]` — Initial world-space position of this link before kinematic constraints solve it.
+- `at?: Vec3` — Initial world-space position of this link before kinematic constraints solve it.
 - `fixed?: boolean` — Keep the link locked at its authored `at` position during solves.
 - `metadata?: Record<string, unknown>` — User metadata carried through the kinematic graph for inspection and tooling.
 
-#### `edgeBetweenLinks()` — Add a relationship edge between two kinematic links.
+#### `linkAlong(name: string, fromLink: string, towardLink: string, distance: number): Assembly` — Create a derived link on the line through `fromLink` and `towardLink`, at a **signed** distance from `fromLink`.
 
-By default the edge captures the authored distance between links as a structural length. Pass `{ length: 'free' }` or `{ visualOnly: true }` for a non-structural overlay edge.
+**Sign convention** (read this first):
+
+- `distance > 0` — the point moves from `fromLink` **toward** `towardLink`.
+- `distance < 0` — the point moves from `fromLink` **away from** `towardLink` (the coupler-extension case, e.g. the Chebyshev lambda linkage's trace point beyond the rocker joint).
+- `distance` greater than the solved edge length places the point **beyond** `towardLink`, still on the same line.
+
+Derived links are trace/reference points. They are recomputed after the primary link solve and cannot participate in structural edges or angle constraints. Because the distance is one signed parameter, a `param()`-driven value can sweep continuously from extension (negative) through `fromLink` (zero) to beyond `towardLink` (large positive).
 
 ```ts
-edgeBetweenLinks(a: string, b: string, options?: AssemblyEdgeBetweenLinksOptions): Assembly
+// Chebyshev lambda linkage: trace point C3 extends beyond C2, away from C1.
+mech.linkAlong('C3', 'C2', 'C1', -2.5 * a);
+// Midpoint-style reference 30 mm from A toward B:
+mech.linkAlong('probe', 'A', 'B', 30);
 ```
 
+#### `edgeBetweenLinks(a: string, b: string, options?: AssemblyEdgeBetweenLinksOptions): Assembly` — Add a relationship edge between two kinematic links.
+
+By default the edge captures the authored distance between links as a structural length. Pass `{ length: 'free' }` or `{ visualOnly: true }` for a non-structural overlay edge.
+
 **`AssemblyEdgeBetweenLinksOptions`**: `name?: string`, `length?: number | "lockCurrent" | "free"`, `min?: number`, `max?: number`, `visualOnly?: boolean`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
 
 `AssemblyKinematicControlOptions`: `{ min?: number, max?: number, default?: number, unit?: string }`
 
-#### `addAngleBetweenLinks()` — Add an angle relationship among three kinematic links.
+#### `addAngleBetweenLinks(a: string, b: string, c: string, options?: AssemblyAngleBetweenLinksOptions): Assembly` — Add an angle relationship among three kinematic links.
 
 The middle link is the vertex. When `control` is set, `solve(state)` reads the control value from `state[name]` and solves dependent links from that driven angle.
 
-```ts
-addAngleBetweenLinks(a: string, b: string, c: string, options?: AssemblyAngleBetweenLinksOptions): Assembly
-```
-
 **`AssemblyAngleBetweenLinksOptions`**: `name?: string`, `value?: number`, `min?: number`, `max?: number`, `control?: boolean | AssemblyKinematicControlOptions`, `limit?: AssemblyKinematicLimitOptions`, `metadata?: Record<string, unknown>`
 
 `AssemblyKinematicLimitOptions`: `{ min?: number, max?: number }`
 
-#### `addAngleBetweenLinkSegmentAndWorldDirection()` — Add an absolute angle relationship from a world direction to a link segment.
+#### `addAngleBetweenLinkSegmentAndWorldDirection(fromLink: string, toLink: string, direction: Vec3, options?: AssemblyAngleBetweenLinksOptions): Assembly` — Add an absolute angle relationship from a world direction to a link segment.
 
 The first link is the vertex/pivot and the second link is the moving point. A value of `0` places `fromLink -> toLink` along `direction` in the mechanism plane; positive angles rotate counter-clockwise in that plane.
 
 Use `Points.polar(1, angleDeg)` when the reference direction is planar and angle-based instead of axis-aligned.
 
-```ts
-addAngleBetweenLinkSegmentAndWorldDirection(fromLink: string, toLink: string, direction: Vec3, options?: AssemblyAngleBetweenLinksOptions): Assembly
-```
-
-#### `describeKinematics()` — Return the assembly-native kinematic graph definition.
-
-```ts
-describeKinematics(): AssemblyKinematicGraphDef
-```
+#### `describeKinematics(): AssemblyKinematicGraphDef` — Return the assembly-native kinematic graph definition.
 
 **Structure**
 
-#### `addPart()` — Add a named part to the assembly.
+#### `addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly` — Add a named part to the assembly.
 
 Connectors declared on the part (via `withConnectors()`) are captured automatically. Parts are positioned at world origin by default unless a `transform` is provided in `options`. For root parts (no incoming joint), `transform` is their final world position.
 
@@ -241,144 +208,104 @@ const housing = group(
 assembly.addPart("Base Assembly", housing);
 ```
 
-```ts
-addPart(name: string, part: AssemblyPart, options?: PartOptions): Assembly
-```
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+
+**`PartMetadata`**
 
-**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
+
+Also: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`.
 
 **`AssemblyPartMateInput`**
 - `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
 - `toLink: string` — Name of the link this connector's origin is pinned to.
 - `aimLink?: string` — Optional second link to orient toward. When set, the part is rotated so the connector's **axis** aims from `toLink` toward `aimLink`, posing an oriented bone instead of only translating it. For full pose without relying on a connector axis, declare a second mate (two connectors → two links).
 
-#### `frame()` — Add a named rig frame to the assembly.
+#### `frame(name: string, options: AssemblyFrameOptions): Assembly` — Add a named rig frame to the assembly.
 
 A frame is a solved pose: `origin` plus orientation. `axis` is the frame's primary direction and `up` fixes roll around that axis. Use frames for robot links, joint axes, and parts that must carry orientation. Use `link()` for solved points in distance/angle graphs.
 
-```ts
-frame(name: string, options: AssemblyFrameOptions): Assembly
-```
+`AssemblyFrameOptions`: `{ origin: Vec3, axis: Vec3, up: Vec3, fixed?: boolean, metadata?: Record<string, unknown> }`
 
-**`AssemblyFrameOptions`**: `origin: [ number, number, number ]`, `axis: [ number, number, number ]`, `up: [ number, number, number ]`, `fixed?: boolean`, `metadata?: Record<string, unknown>`
-
-#### `fixedJoint()` — Rigidly attach a child rig frame to a parent rig frame.
+#### `fixedJoint(name: string, options: AssemblyFixedFrameJointOptions): Assembly` — Rigidly attach a child rig frame to a parent rig frame.
 
 Fixed joints carry frame hierarchy but do not expose a Motion control.
 
-```ts
-fixedJoint(name: string, options: AssemblyFixedFrameJointOptions): Assembly
-```
-
 `AssemblyFixedFrameJointOptions`: `{ parent: string, child: string, metadata?: Record<string, unknown> }`
 
-#### `revoluteJoint()` — Add a revolute rig-frame joint.
+#### `revoluteJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly` — Add a revolute rig-frame joint.
 
 The child frame rotates around the parent frame's `axis` direction. Moving frame joints appear in Motion by default; pass `control: false` to keep the joint solved at its default value without showing a Motion control.
 
-```ts
-revoluteJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly
-```
-
 **`AssemblyMovingFrameJointOptions`**: `parent: string`, `child: string`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `control?: boolean`, `metadata?: Record<string, unknown>`
 
-#### `prismaticJoint()` — Add a prismatic rig-frame joint.
+#### `prismaticJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly` — Add a prismatic rig-frame joint.
 
 The child frame translates along the parent frame's `axis` direction. Moving frame joints appear in Motion by default; pass `control: false` to keep the joint solved at its default value without showing a Motion control.
 
-```ts
-prismaticJoint(name: string, options: AssemblyMovingFrameJointOptions): Assembly
-```
-
 **Connectors**
 
-#### `usedConnectorRefs()` — Connector refs (e.g. "PartName.connectorName") consumed by connect/match calls.
-
-```ts
-get usedConnectorRefs(): ReadonlySet<string>
-```
+#### `get usedConnectorRefs(): ReadonlySet<string>` — Connector refs (e.g. "PartName.connectorName") consumed by connect/match calls.
 
-#### `withConnectors()` — Attach named connectors to a specific part or the assembly as a whole.
+#### `withConnectors(partName: string, connectors: Record<string, ConnectorInput>): Assembly` — Attach named connectors to a specific part or the assembly as a whole.
 
 Connectors declared this way are in the part's local coordinate system. They are captured automatically if the incoming [`Shape`](/docs/core#shape) already has connectors via `shape.withConnectors(...)`, but you can also add or override connectors after the fact with this method.
 
 Use the single-argument overload to attach assembly-level connectors — these are exposed when this assembly is imported as a sub-assembly.
 
-```ts
-withConnectors(partName: string, connectors: Record<string, ConnectorInput>): Assembly
-```
-
-**`PortInput`**: `origin?: [ number, number, number ]`, `axis?: [ number, number, number ]`, `start?: [ number, number, number ]`, `end?: [ number, number, number ]`, `up?: [ number, number, number ]`, `kind?: JointType`, `min?: number`, `max?: number`
-
-`ConnectorInput`: `{ connectorType?: string, gender?: ConnectorGender, measurements?: Record<string, number | string> }`
-
-#### `getConnectors()` — Get connectors declared on a part in part-local space.
-
-```ts
-getConnectors(partName: string): ConnectorMap
-```
-
-#### `getConnector()` — Parse a "PartName.connectorName" reference and return the resolved connector. Throws descriptive errors if the part or connector doesn't exist.
-
-```ts
-getConnector(ref: string): { partName: string; connectorName: string; connector: ConnectorDef; }
-```
+`ConnectorInput` — defined in [core](/docs/core).
 
-#### `connect()` — Connect two parts by aligning their declared connectors, automatically computing frame and axis.
+#### `getConnectors(partName: string): ConnectorMap` — Get connectors declared on a part in part-local space.
 
-Connector references use `"PartName.connectorName"` format. The system aligns connector origins (child connector lands exactly on parent connector) and derives the joint frame and axis from the connector geometry — no manual `frame` or `axis` math needed.
+#### `getConnector(ref: string): { partName: string; connectorName: string; connector: ConnectorDef; }` — Parse a "PartName.connectorName" reference and return the resolved connector. Throws descriptive errors if the part or connector doesn't exist.
 
-Use `connect()` for frame-aware articulated geometry. A connector's `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` is the secondary orientation vector that locks the part's zero-angle twist. If `up` is omitted, ForgeCAD chooses a deterministic perpendicular vector, but authored mechanisms should provide `up` whenever rest orientation matters.
+#### `connect(parentConnectorRef: string, childConnectorRef: string, options?: ConnectOptions): Assembly` — Connect two parts by aligning their declared connectors, automatically computing frame and axis.
 
-**Face-to-face convention:** Connectors always meet face-to-face, like a USB plug meeting a socket. Each connector's axis points "outward" from its part. When two connectors mate, the system brings them together so their axes oppose (anti-parallel). This is the same convention used by `matchTo()`.
+Connector refs use `"PartName.connectorName"`. The child connector origin lands exactly on the parent connector origin; joint frame and axis are derived from the connector geometry — no manual `frame`/`axis` math.
 
-For a revolute joint (hinge), both connectors' axes should point outward from their respective parts along the hinge line. For a prismatic joint (slider), both axes should point along the slide direction from their part's perspective.
+Frame semantics: `origin` is the pivot/contact point, `axis` the hinge or slide direction, `up` locks the part's zero-state twist. Omitted `up` gets a deterministic perpendicular — provide `up` whenever rest orientation matters. (`addPart(..., { mate })` translates only; see `addPart`.)
 
-**Mirrored revolute axes:** Revolute values follow the right-hand rule around the joint axis. If a bilateral mechanism mirrors a hinge axis, for example `[1, 0, 0]` on the right side and `[-1, 0, 0]` on the left side, the same physical `+theta` value rotates the two sides in opposite fore/aft senses. The mirrored pose uses the negated revolute value; physical limits mirror as `[min, max] -> [-max, -min]`. Prismatic joints do not have this handedness flip. For bilateral mechanisms, prefer side-neutral link controls or an explicit state mapping when you want equal semantic pose values on both sides.
+**Face-to-face:** each connector's axis points outward from its part; mating makes the axes anti-parallel, like a plug meeting a socket (same convention as `matchTo()`).
 
-The joint type is inferred from the connector's `kind` field if not specified in `options`.
+**Revolute sign:** a positive joint value follows the right-hand rule about the **child** connector's placed axis. Because face-to-face mating makes the axes anti-parallel, that is the *left*-hand rule about the parent connector's outward axis — if `+30` swings the opposite way you expected, you predicted from the parent's axis. `forgecad debug assembly` prints each joint's resolved world axis.
 
-When connectors are defined with `start`/`end`, you can control which point on each connector meets via `align` / `parentAlign` / `childAlign` (`'start'`, `'middle'`, `'end'`).
+**Mirrored revolute axes:** because of the right-hand rule, a mirrored hinge axis (`[1, 0, 0]` vs `[-1, 0, 0]`) rotates oppositely for the same `+theta`: negate the mirrored side's value and mirror limits as `[min, max] -> [-max, -min]`. Prismatic joints have no handedness flip. Use an explicit per-side sign mapping (or side-neutral link controls) for bilateral mechanisms.
 
-Use `connect()` when connector origins must physically coincide (flange-to-flange, bolt-into-bore).
+Joint type defaults to the connector's `kind`. For `start`/`end` connectors, `align` / `parentAlign` / `childAlign` (`'start' | 'middle' | 'end'`) choose which point meets.
 
 ```ts
-// Hinge: both axes point outward along the hinge line
 const frame = box(100, 10, 80).withConnectors({
-  hinge: connector("hinge", {
-    origin: [0, 0, 40],
-    axis: [0, 0, 1],
-    up: [1, 0, 0],
-  }),
+  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, 1], up: [1, 0, 0] }),
 });
 const door = box(60, 4, 80).withConnectors({
-  hinge: connector("hinge", {
-    origin: [0, 0, 40],
-    axis: [0, 0, -1],
-    up: [1, 0, 0],
-  }),
+  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, -1], up: [1, 0, 0] }),
 });
-assembly("Door")
-  .addPart("Frame", frame)
-  .addPart("Door", door)
+assembly("Door").addPart("Frame", frame).addPart("Door", door)
   .connect("Frame.hinge", "Door.hinge", { as: "swing", min: 0, max: 110 });
 ```
 
-```ts
-connect(parentConnectorRef: string, childConnectorRef: string, options?: ConnectOptions): Assembly
-```
-
 **`ConnectOptions`**
 
 | Option | Type | Description |
 |--------|------|-------------|
+| `min?` | `number` | Lower joint-slider limit; solve clamps to it with a warning. Not a physical stop — enforce real travel limits with stop geometry. |
+| `max?` | `number` | Upper joint-slider limit; same semantics as `min`. |
 | `flip?` | `boolean` | This parameter is ignored. If your connectors produce wrong orientation, fix the connector axis directions instead of using flip. |
 | `parentAlign?` | `PortAlign` | Which point on the parent connector to align: 'start', 'middle' (default), or 'end'. |
 | `childAlign?` | `PortAlign` | Which point on the child connector to align: 'start', 'middle' (default), or 'end'. |
 | `align?` | `PortAlign` | Shorthand: set both parentAlign and childAlign at once. |
-| `as?`, `type?`, `min?`, `max?`, `default?`, `unit?`, `effort?`, `velocity?`, `damping?`, `friction?` | | — |
+| `follows?` | `JointFollowOptions` | Slave this joint to another joint: `value = ratio × source + offset` (e.g. a mirrored jaw with `ratio: -1`). |
+
+Also: `as?: string`, `type?: JointType`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `drive?: SimDriveDef`.
 
-#### `match()` — Auto-create a joint by matching typed connectors between two parts.
+**`JointFollowOptions`**
+- `joint: string` — Name of the source joint that drives this one.
+- `ratio?: number` — Multiplier applied to the source joint value (default 1).
+- `offset?: number` — Constant added after the ratio (default 0).
+
+#### `match(childPartName: string, parentPartName: string, pairs: Record<string, string>, options?: MatchToOptions & { as?: string; }): Assembly` — Auto-create a joint by matching typed connectors between two parts.
 
 Connectors can carry a `connectorType` string and a `gender` (`'male'`, `'female'`, or `'neutral'`). `match()` validates type and gender compatibility (use `{ force: true }` to skip validation) and creates the joint automatically from the connector's `kind` metadata.
 
@@ -403,29 +330,17 @@ const mech = assembly("Door")
 // Matching connectors computes the placement relationship automatically.
 ```
 
-```ts
-match(childPartName: string, parentPartName: string, pairs: Record<string, string>, options?: MatchToOptions & { as?: string; }): Assembly
-```
-
-`MatchToOptions`: `{ force?: boolean, angle?: number, distance?: number }`
+`MatchToOptions` — defined in [core](/docs/core).
 
 **References**
 
-#### `withReferences()` — Attach named placement reference points to this assembly. These are surfaced automatically on the ImportedAssembly when this file is imported via require(), so consumers can use placeReference() without re-declaring them. Returns a new Assembly — does not mutate.
+#### `withReferences(refs: Pick<PlacementReferenceInput, "points">): Assembly` — Attach named placement reference points to this assembly. These are surfaced automatically on the ImportedAssembly when this file is imported via require(), so consumers can use placeReference() without re-declaring them. Returns a new Assembly — does not mutate.
 
-```ts
-withReferences(refs: Pick<PlacementReferenceInput, "points">): Assembly
-```
-
-**`PlacementReferenceInput`**: `points?: Record<string, [ number, number, number ]>`, `edges?: Record<string, PlacementEdgeRef>`, `surfaces?: Record<string, PlacementSurfaceRef>`, `objects?: Record<string, PlacementObjectInput>`
-
-`PlacementEdgeRef`: `{ start: Vec3, end: Vec3 }`
-
-`PlacementSurfaceRef`: `{ center: Vec3, normal: Vec3 }`
+`PlacementReferenceInput` — defined in [core](/docs/core).
 
 **Solving**
 
-#### `solve()` — Solve the assembly at the given control state and return positioned parts.
+#### `solve(state?: JointState): SolvedAssembly` — Solve the assembly at the given control state and return positioned parts.
 
 Solves assembly-native kinematic links first. Controlled `addAngleBetweenLinks()` relationships read values from `state` by name, clamp to their declared limits, and expose the solved graph on `SolvedAssembly.kinematics`. Angles solve in the plane of their three authored link positions, so a limb that swings out of the `z = 0` plane poses correctly; structural edges hold their bone lengths so a fully angle-driven serial chain follows forward kinematics.
 
@@ -441,123 +356,79 @@ Connector-frame joints created by `connect()` / `match()` are also evaluated; th
 return mech.solve({ theta: 45 });
 ```
 
-```ts
-solve(state?: JointState): SolvedAssembly
-```
-
 <!-- forgecad-skill:exclude-start symbol="Assembly.Compatibility methods" reason="Compatibility-only renamed API. Use `addAngleBetweenLinkSegmentAndWorldDirection()` instead." -->
 **Compatibility**
 <!-- forgecad-skill:exclude-end -->
 
 <!-- forgecad-skill:exclude-start symbol="Assembly.addAngleOfLinkSegmentFromXAxis" reason="Compatibility-only renamed API. Use `addAngleBetweenLinkSegmentAndWorldDirection()` instead." -->
-#### `addAngleOfLinkSegmentFromXAxis()`
-
-> **Not included in ForgeCAD AI skill context yet.** This API remains visible in human docs, but is intentionally omitted from shipped agent skills until it is ready for agent-first use. Compatibility-only renamed API. Use `addAngleBetweenLinkSegmentAndWorldDirection()` instead.
-
-```ts
-addAngleOfLinkSegmentFromXAxis(fromLink: string, toLink: string, options?: AssemblyAngleBetweenLinksOptions): Assembly
-```
+- `addAngleOfLinkSegmentFromXAxis(fromLink: string, toLink: string, options?: AssemblyAngleBetweenLinksOptions): Assembly`
 <!-- forgecad-skill:exclude-end -->
 
 <!-- forgecad-skill:exclude-start symbol="Assembly.addAngleOfLinkSegmentFromYAxis" reason="Compatibility-only renamed API. Use `addAngleBetweenLinkSegmentAndWorldDirection()` instead." -->
-#### `addAngleOfLinkSegmentFromYAxis()`
-
-> **Not included in ForgeCAD AI skill context yet.** This API remains visible in human docs, but is intentionally omitted from shipped agent skills until it is ready for agent-first use. Compatibility-only renamed API. Use `addAngleBetweenLinkSegmentAndWorldDirection()` instead.
-
-```ts
-addAngleOfLinkSegmentFromYAxis(fromLink: string, toLink: string, options?: AssemblyAngleBetweenLinksOptions): Assembly
-```
+- `addAngleOfLinkSegmentFromYAxis(fromLink: string, toLink: string, options?: AssemblyAngleBetweenLinksOptions): Assembly`
 <!-- forgecad-skill:exclude-end -->
 
-<!-- forgecad-skill:exclude-start symbol="Assembly.toJointsView" reason="Compatibility-only viewport FK adapter. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model." -->
-#### `toJointsView()` — Deprecated adapter that derives viewport-only FK controls from the assembly graph.
-
-> **Not included in ForgeCAD AI skill context yet.** This API remains visible in human docs, but is intentionally omitted from shipped agent skills until it is ready for agent-first use. Compatibility-only viewport FK adapter. Prefer returning `Assembly` directly so controls move through the solver-backed link/edge kinematics model.
-
-Prefer returning the `Assembly` itself. The runtime now exposes returned assembly controls automatically and re-evaluates the assembly with `solve(state)` when a control changes. That path is the source of truth for link/edge kinematics, handles closed-loop mechanisms through the real solver, and avoids stacking a viewport transform on top of already-solved geometry.
-
-`toJointsView()` remains for legacy scripts that intentionally want the old viewport-only FK behavior.
-
-**Legacy mirrored revolute tracks:** Viewport defaults and animation keyframes use physical joint values. If two mirrored revolute joints have opposite axes, equal keyframe values are not a mirrored pose; negate the mirrored side's values, or prefer returned-assembly controls so the solver owns the side-neutral state.
-
-**Preferred**
-
-```ts
-return mech; // editor controls call mech.solve(state)
-```
-
-```ts
-toJointsView(options?: ToJointsViewOptions): void
-```
-
-**`ToJointsViewOptions`**: `defaults?: Record<string, number>`, `overrides?: Record<string, Partial<JointViewInput>>`, `animations?: JointViewAnimationInput[]`, `couplings?: JointViewCouplingInput[]`, `defaultAnimation?: string`, `enabled?: boolean`
-
-**`JointViewInput`**: `name: string`, `child: string`, `parent?: string`, `type?: JointViewType`, `axis?: JointViewAxis`, `pivot?: [ number, number, number ]`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `hidden?: boolean`
-
-`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
-
-**`JointViewAnimationKeyframeInput`**
-- `at?: number` — Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights.
-- `ticks?: number` — Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored.
-- Also: `values: Record<string, number>`
-
-`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
-
-`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
-<!-- forgecad-skill:exclude-end -->
 
 **Other**
 
-#### `mate()` — Register mate constraints between parts. Constraints are solved during `solve()` to derive part positions and explode hints. Part references use "partName:featureName" format.
+#### `withSimulation(options: SimAssemblySimulationOptions): Assembly` — Attach the root simulation contract for this assembly.
 
-```ts
-mate(fn: (m: MateBuilder) => void): Assembly
-```
+Use this after adding physical parts and joints. Robot-body profiles require `rootPart`; asset profiles can describe one-part or multi-part physical assets. URDF/SDF exporters and `forgecad check simready` read this contract directly, so model files no longer need a separate `robotExport(...)` side effect.
 
-#### `edgeBetweenFrames()` — Add a visual skeleton edge between two rig frame origins.
+`SimAssemblySimulationOptions`: `{ profile: SimProfileDef, rootPart?: string, controllers?: SimControllerDef[] }`
 
-Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
+#### `edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly` — Add a visual skeleton edge between two rig frame origins.
 
-```ts
-edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly
-```
+Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
 
 `AssemblyFrameEdgeOptions`: `{ name?: string, metadata?: Record<string, unknown> }`
 
-#### `linkToward()` — Create a derived link at a fixed distance from `fromLink` toward `towardLink`.
+#### `addAnimation(name: string, options: AssemblyAnimationOptions): Assembly` — Register a named keyframe animation for this assembly's Motion view.
 
-Derived links are trace/reference points. They are recomputed after the primary link solve and cannot participate in structural edges or angle constraints.
+Works with the returned-assembly controls path: return the unsolved `Assembly` and the animation appears in the Motion tab alongside the solver-backed joint controls. Keyframes hold control values by joint name; joints declared with `follows` are derived automatically and must not appear in keyframes.
 
 ```ts
-linkToward(name: string, fromLink: string, towardLink: string, distance: number): Assembly
+robot.addAnimation("Pick and place", {
+  duration: 12,
+  loop: true,
+  keyframes: [
+    { values: { J1: 0, J2: -90 } },
+    { values: { J1: 45, J2: -30 } },
+    { values: { J1: 0, J2: -90 } },
+  ],
+});
+return robot;
 ```
 
-#### `linkAwayFrom()` — Create a derived link at a fixed distance from `fromLink` away from `awayFromLink`.
+**`AssemblyAnimationOptions`**
 
-Use this for coupler trace/extension points such as the Chebyshev lambda linkage's point beyond the rocker joint.
+| Option | Type | Description |
+|--------|------|-------------|
+| `duration?` | `number` | Animation length in seconds (default chosen by the viewer). |
+| `loop?` | `boolean` | Loop the animation (default false). |
+| `continuous?` | `boolean` | Interpolate continuously through keyframes instead of pausing on each. |
+| `keyframes` | `JointViewAnimationInput["keyframes"]` | Keyframes of control values by joint/control name. `at` (0..1) or `ticks` control timing. |
+| `default?` | `boolean` | Make this the animation that plays when the model loads. |
 
-```ts
-linkAwayFrom(name: string, fromLink: string, awayFromLink: string, distance: number): Assembly
-```
+`JointViewAnimationInput`: `{ name: string, duration?: number, loop?: boolean, continuous?: boolean, keyframes: JointViewAnimationKeyframeInput[] }`
 
-#### `describe()` — Return the serializable assembly definition used by solve/inspect pipelines.
+**`JointViewAnimationKeyframeInput`**
+- `at?: number` — Timeline position [0, 1]. If omitted from ALL keyframes, positions are auto-computed from tick weights.
+- `ticks?: number` — Relative weight of the segment from this keyframe to the next (default 1). Only used in tick-based mode (when `at` is omitted). Last keyframe's ticks value is ignored.
+- Also: `values: Record<string, number>`.
 
-```ts
-describe(): AssemblyDefinition
-```
+#### `describe(): AssemblyDefinition` — Return the serializable assembly definition used by solve/inspect pipelines.
 
 **Compatibility Aliases**
 
-- `usedPortRefs` -> `usedConnectorRefs`
 - `withPorts()` -> `withConnectors()`
 - `getPorts()` -> `getConnectors()`
-- `getPort()` -> `getConnector()`
 
 ### `ImportedAssembly`
 
 A wrapper around an imported `Assembly` that provides kinematic access and convenient transform helpers.
 
-When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core#require) wraps it in an `ImportedAssembly`. This preserves the kinematic structure — you can call `solve()` and `mergeInto()` — while also allowing convenience transforms that auto-solve at default values.
+When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core#require) wraps it in an `ImportedAssembly`. This preserves the kinematic structure — you can call `solve()` and `mergeInto()` — and converts to a static [`ShapeGroup`](/docs/core#shapegroup) via the explicit `toGroup(state?)` boundary when group-style transforms are needed.
 
 **Kinematic access**
 
@@ -565,14 +436,14 @@ When a `.forge.js` file returns an unsolved `Assembly`, [`require()`](/docs/core
 const arm = require("./arm.forge.js");
 
 const solved = arm.solve({ shoulder: 45 });   // full kinematic solve
-const link   = arm.part("Link", { shoulder: 60 }); // single part at state
+const link   = arm.getPart("Link", { shoulder: 60 }); // single part at state
 const group  = arm.toGroup({ shoulder: 45 });  // only when ShapeGroup behavior is needed
 ```
 
-**Convenience transforms** (auto-solve at defaults, return [`ShapeGroup`](/docs/core#shapegroup)):
+**Static positioning** — convert explicitly, then transform the group (`toGroup()` solves at default joint values and discards kinematics):
 
 ```ts
-const positioned = arm.rotateZ(-90).translate(0, -20, 50);
+const positioned = arm.toGroup().rotateZ(-90).translate(0, -20, 50);
 ```
 
 **Merging into a parent**
@@ -586,154 +457,43 @@ require("./arm.forge.js").mergeInto(robot, {
 });
 ```
 
-#### `assembly()` — The underlying Assembly, for advanced composition and inspection.
-
-```ts
-get assembly(): Assembly
-```
-
-#### `solve()` — Solve the assembly at the given joint state (defaults to each joint's default value).
-
-```ts
-solve(state?: JointState): SolvedAssembly
-```
-
-#### `part()` — Return a specific named part positioned at the given joint state, with any stored placement offset applied.
-
-```ts
-part(name: string, state?: JointState): AssemblyPart
-```
-
-#### `getPart()` — Return a specific named part positioned at the default solved pose.
+#### `get assembly(): Assembly` — The underlying Assembly, for advanced composition and inspection.
 
-This mirrors `SolvedAssembly.getPart()` for imported assemblies. Use `solve(state).getPart(name)` when inspecting a non-default joint state.
+#### `solve(state?: JointState): SolvedAssembly` — Solve the assembly at the given joint state (defaults to each joint's default value).
 
-```ts
-getPart(partName: string): AssemblyPart
-```
-
-#### `toGroup()` — Convert all assembly parts to a ShapeGroup with named children. Use this for composition, transforms, or child lookup — not as a required render step for assemblies. Child names match the part names used in the assembly. Any stored placement offset and placement references are forwarded to the group.
-
-```ts
-toGroup(state?: JointState): ShapeGroup
-```
+#### `getPart(partName: string, state?: JointState): AssemblyPart` — Return a specific named part positioned at the solved pose, with any stored placement offset applied.
 
-#### `withReferences()` — Attach named placement reference points to this assembly. Points are simple 3D coordinates (relative to the assembly's own origin). Returns a new ImportedAssembly — does not mutate.
+This mirrors `SolvedAssembly.getPart()` for imported assemblies, with one addition: any offset stored by `placeReference()` is applied, so the part lands where the imported assembly was placed. (`solve(state).getPart(name)` returns the part in the assembly's own coordinates, without that offset.)
 
-```ts
-withReferences(refs: Pick<PlacementReferenceInput, "points">): ImportedAssembly
-```
-
-#### `referenceNames()` — List all attached placement reference names.
-
-```ts
-referenceNames(kind?: PlacementReferenceKind): string[]
-```
+#### `toGroup(state?: JointState): ShapeGroup` — Convert all assembly parts to a ShapeGroup with named children. Use this for composition, transforms, or child lookup — not as a required render step for assemblies. Child names match the part names used in the assembly. Any stored placement offset and placement references are forwarded to the group.
 
-#### `placeReference()` — Translate the assembly so the named reference point lands on `target`. Returns a new ImportedAssembly — does not mutate. All point refs are translated by the same delta.
-
-```ts
-placeReference(ref: string, target: [ number, number, number ], offset?: [ number, number, number ]): ImportedAssembly
-```
-
-#### `translate()` — Solve at defaults and return a translated ShapeGroup.
-
-```ts
-translate(x: number, y: number, z: number): ShapeGroup
-```
-
-#### `rotate()` — Solve at defaults and return a rotated ShapeGroup.
-
-```ts
-rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
-```
+#### `withReferences(refs: Pick<PlacementReferenceInput, "points">): ImportedAssembly` — Attach named placement reference points to this assembly. Points are simple 3D coordinates (relative to the assembly's own origin). Returns a new ImportedAssembly — does not mutate.
 
-#### `rotateX()` — Solve at defaults and return a ShapeGroup rotated around X.
-
-```ts
-rotateX(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
-```
-
-#### `rotateY()` — Solve at defaults and return a ShapeGroup rotated around Y.
-
-```ts
-rotateY(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
-```
-
-#### `rotateZ()` — Solve at defaults and return a ShapeGroup rotated around Z.
-
-```ts
-rotateZ(angleDeg: number, options?: { pivot?: [ number, number, number ]; }): ShapeGroup
-```
-
-#### `scale()` — Solve at defaults and return a scaled ShapeGroup.
-
-```ts
-scale(v: number | [ number, number, number ]): ShapeGroup
-```
-
-#### `mirror()` — Solve at defaults and return a mirrored ShapeGroup.
-
-```ts
-mirror(normal: [ number, number, number ]): ShapeGroup
-```
-
-#### `color()` — Solve at defaults and return a colored ShapeGroup.
-
-```ts
-color(hex: string): ShapeGroup
-```
+#### `referenceNames(kind?: PlacementReferenceKind): string[]` — List all attached placement reference names.
 
-#### `child()` — Solve at defaults, get a named child part from the resulting group.
+#### `placeReference(ref: string, target: Vec3, offset?: Vec3): ImportedAssembly` — Translate the assembly so the named reference point lands on `target`. Returns a new ImportedAssembly — does not mutate. All point refs are translated by the same delta.
 
-```ts
-child(name: string): Shape | Sketch | ShapeGroup
-```
+#### `child(name: string): Shape | Sketch | ShapeGroup` — Solve at defaults, get a named child part from the resulting group.
 
-#### `collisionReport()` — Detect overlapping part pairs at the default solved pose.
+#### `collisionReport(options?: CollisionOptions): CollisionFinding[]` — Detect overlapping part pairs at the default solved pose.
 
 This mirrors `SolvedAssembly.collisionReport()` for imported assemblies. Use `solve(state).collisionReport(options)` when inspecting a non-default joint state.
 
-```ts
-collisionReport(options?: CollisionOptions): CollisionFinding[]
-```
-
 `CollisionOptions`: `{ parts?: string[], ignorePairs?: Array<[ string, string ]>, minOverlapVolume?: number }`
 
-#### `minClearance()` — Compute the minimum gap between two parts at the default solved pose.
+#### `minClearance(partA: string, partB: string, searchLength?: number): number` — Compute the minimum gap between two parts at the default solved pose.
 
 This mirrors `SolvedAssembly.minClearance()` for imported assemblies. Use `solve(state).minClearance(partA, partB, searchLength)` when inspecting a non-default joint state.
 
-```ts
-minClearance(partA: string, partB: string, searchLength?: number): number
-```
-
-#### `mergeInto()` — Flatten this sub-assembly's parts and relationships into `parent` and wire a mount relationship.
+#### `mergeInto(parent: Assembly, options: MergeIntoOptions): Assembly` — Flatten this sub-assembly's parts and relationships into `parent` and wire a mount relationship.
 
-All part, link, and legacy joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions. After the merge, controls are driven from the parent using the prefixed names:
+All part, link, and legacy joint names from the sub-assembly are prefixed with `"${options.prefix}."` to avoid collisions; connectors are forwarded with the same prefix. After the merge, drive controls from the parent using the prefixed names:
 
 ```ts
 parent.solve({ "Left Arm.theta": 45, "Right Arm.theta": -20 })
 ```
 
-Connectors from sub-assembly parts are forwarded with the prefix.
-
-The sub-assembly must have exactly one root part before it can be merged.
-
-```ts
-const robot = assembly("Robot").addPart("Chassis", chassis);
-
-require("./arm.forge.js").mergeInto(robot, {
-  prefix: "Left Arm",
-  mountParent: "Chassis",
-  mountJoint: "leftMount",
-  mountOptions: { frame: Transform.identity().translate(-70, 0, 10) },
-});
-```
-
-```ts
-mergeInto(parent: Assembly, options: MergeIntoOptions): Assembly
-```
+The sub-assembly must have exactly one root part before it can be merged (collapse multiple roots with `addFixed()` first). See the `ImportedAssembly` class docs for a full merge example.
 
 **`MergeIntoOptions`**
 
@@ -750,7 +510,9 @@ mergeInto(parent: Assembly, options: MergeIntoOptions): Assembly
 | Option | Type | Description |
 |--------|------|-------------|
 | `connectorRefs?` | `JointConnectorRefs` | Connector refs that define this joint contract. Usually set by `connect()` / `match()`. |
-| `frame?`, `origin?`, `axis?`, `min?`, `max?`, `default?`, `unit?`, `effort?`, `velocity?`, `damping?`, `friction?` | | — |
+| `follows?` | `JointFollowOptions` | Slave this joint to another joint: `value = ratio × source + offset`. Use for mechanisms with one physical DOF expressed through several joints — a mirrored gripper jaw (`ratio: -1`), a gear pair, a drive crank turning with its servo. A followed joint stops being an independent control: the Motion view drives it from its source, `solve()` derives its value (a direct state override is ignored with a warning), and limits still clamp the derived value. |
+
+Also: `frame?: TransformInput`, `origin?: Vec3`, `axis?: Vec3`, `min?: number`, `max?: number`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `drive?: SimDriveDef`.
 
 `JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
 
@@ -778,73 +540,23 @@ return solved;
 
 **Methods:**
 
-#### `warnings()` — Return any warnings generated during solve (clamped joints, unconverged mates, etc.).
-
-```ts
-warnings(): string[]
-```
-
-#### `getJointState()` — Return a snapshot of resolved joint values (after clamping and coupling).
-
-```ts
-getJointState(): JointState
-```
-
-#### `mateExplodeHints()` — Explode direction hints derived from mate constraints, or null if no mates.
-
-```ts
-get mateExplodeHints(): Record<string, { direction: Vec3; }> | null
-```
-
-#### `mateDof()` — Remaining degrees of freedom after mate constraints, or null if no mates.
+#### `warnings(): string[]` — Return any warnings generated during solve (clamped joints, unconverged mates, etc.).
 
-```ts
-get mateDof(): number | null
-```
+#### `getJointState(): JointState` — Return a snapshot of resolved joint values (after clamping and coupling).
 
-#### `mateConverged()` — Whether the mate constraint solver converged, or null if no mates.
+#### `get kinematics(): SolvedAssemblyKinematics | null` — Solved assembly-native kinematic or frame-edge overlay data, or null when no rig overlay data was declared.
 
-```ts
-get mateConverged(): boolean | null
-```
+#### `getLinkPosition(linkName: string): Vec3` — Return the solved world position of a kinematic link.
 
-#### `kinematics()` — Solved assembly-native kinematic or frame-edge overlay data, or null when no rig overlay data was declared.
+#### `getFrame(frameName: string): Transform` — Return the solved world transform for a named rig frame.
 
-```ts
-get kinematics(): SolvedAssemblyKinematics | null
-```
+#### `get frames(): SolvedAssemblyFrameDef[]` — Return solved rig frames, including origin, axis, up, and transform.
 
-#### `getLinkPosition()` — Return the solved world position of a kinematic link.
+#### `getTransform(partName: string): Transform` — Return the world-space [`Transform`](/docs/core#transform) for the named part at the solved pose.
 
-```ts
-getLinkPosition(linkName: string): Vec3
-```
+#### `getPart(partName: string): AssemblyPart` — Return the named part already positioned at its solved world transform.
 
-#### `getFrame()` — Return the solved world transform for a named rig frame.
-
-```ts
-getFrame(frameName: string): Transform
-```
-
-#### `frames()` — Return solved rig frames, including origin, axis, up, and transform.
-
-```ts
-get frames(): SolvedAssemblyFrameDef[]
-```
-
-#### `getTransform()` — Return the world-space [`Transform`](/docs/core#transform) for the named part at the solved pose.
-
-```ts
-getTransform(partName: string): Transform
-```
-
-#### `getPart()` — Return the named part already positioned at its solved world transform.
-
-```ts
-getPart(partName: string): AssemblyPart
-```
-
-#### `toGroup()` — Convert all solved parts into a [`ShapeGroup`](/docs/core#shapegroup) with named children.
+#### `toGroup(): ShapeGroup` — Convert all solved parts into a [`ShapeGroup`](/docs/core#shapegroup) with named children.
 
 Each part becomes a named child in the group, already positioned at its solved world transform. Use this only when you specifically need a [`ShapeGroup`](/docs/core#shapegroup) for composition, [`ShapeGroup`](/docs/core#shapegroup) transforms, or named-child access. Top-level scripts can return the `SolvedAssembly` directly; do not call `toGroup()` just to make a solved assembly render.
 
@@ -853,37 +565,15 @@ const armGroup = mech.solve({ shoulder: 60 }).toGroup(); // only because we need
 return armGroup.rotateZ(90);
 ```
 
-```ts
-toGroup(): ShapeGroup
-```
-
-#### `toSceneObjects()` — Return an array of named scene objects for the viewport renderer.
+#### `toSceneObjects(): Array<{ ... }>` — Return an array of named scene objects for the viewport renderer.
 
 Each part becomes `{ name, shape }` or `{ name, group: [...] }` if the part is a [`ShapeGroup`](/docs/core#shapegroup). Top-level scripts should normally return the `SolvedAssembly` directly. Use `toGroup()` when you need [`ShapeGroup`](/docs/core#shapegroup) behavior; use this method only for advanced scene-graph control where you need access to the flat per-part array with metadata.
 
-```ts
-toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
-```
-
-#### `toScene()` — Backward-compatible alias for `toSceneObjects()`.
+#### `bom(): BomRow[]` — Generate a bill of materials for all parts in the solved assembly.
 
-```ts
-toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
-```
+#### `bomCsv(): string` — Generate a bill of materials as a CSV string.
 
-#### [`bom()`](/docs/output#bom) — Generate a bill of materials for all parts in the solved assembly.
-
-```ts
-bom(): BomRow[]
-```
-
-#### `bomCsv()` — Generate a bill of materials as a CSV string.
-
-```ts
-bomCsv(): string
-```
-
-#### `collisionReport()` — Detect overlapping (colliding) part pairs in this solved pose.
+#### `collisionReport(options?: CollisionOptions): CollisionFinding[]` — Detect overlapping (colliding) part pairs in this solved pose.
 
 Computes boolean intersections between all part pairs and returns findings where the overlap volume exceeds `minOverlapVolume` (default 0.1 mm³).
 
@@ -892,90 +582,6 @@ const solved = mech.solve({ shoulder: 35, elbow: 60 });
 console.log("Collisions", solved.collisionReport());
 ```
 
-```ts
-collisionReport(options?: CollisionOptions): CollisionFinding[]
-```
-
-#### `minClearance()` — Compute the minimum gap (clearance) between two parts in this solved pose.
+#### `minClearance(partA: string, partB: string, searchLength?: number): number` — Compute the minimum gap (clearance) between two parts in this solved pose.
 
 Returns `0` if the parts are touching or overlapping. Requires the Manifold backend. `searchLength` bounds the search radius in mm — increase it for widely separated parts.
-
-```ts
-minClearance(partA: string, partB: string, searchLength?: number): number
-```
-
-### `MateBuilder`
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `constraints` | `Constraint3D[]` | — |
-
-**Methods:**
-
-#### `flush()` — Constrain two faces so they stay flush.
-
-```ts
-flush(faceA: string, faceB: string): string
-```
-
-#### `align()` — Constrain two faces so their normals align.
-
-```ts
-align(faceA: string, faceB: string): string
-```
-
-#### `parallel()` — Constrain two faces so they remain parallel.
-
-```ts
-parallel(faceA: string, faceB: string): string
-```
-
-#### `faceDistance()` — Constrain the distance between two faces.
-
-```ts
-faceDistance(faceA: string, faceB: string, distance: number): string
-```
-
-#### `concentric()` — Constrain two axes to share the same center line.
-
-```ts
-concentric(axisA: string, axisB: string): string
-```
-
-#### `axisParallel()` — Constrain two axes to remain parallel.
-
-```ts
-axisParallel(axisA: string, axisB: string): string
-```
-
-#### `pointCoincident()` — Constrain two points to coincide.
-
-```ts
-pointCoincident(pointA: string, pointB: string): string
-```
-
-#### `pointOnFace()` — Constrain a point to lie on a face.
-
-```ts
-pointOnFace(point: string, face: string): string
-```
-
-#### `pointOnAxis()` — Constrain a point to lie on an axis.
-
-```ts
-pointOnAxis(point: string, axis: string): string
-```
-
-#### `angle()` — Constrain the angle between two faces.
-
-```ts
-angle(faceA: string, faceB: string, degrees: number): string
-```
-
-#### `totalEquations()` — Total constraint equations.
-
-```ts
-get totalEquations(): number
-```