forgecad 0.7.0 → 0.8.0

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

@@ -33,6 +33,8 @@ bomToCsv(rows: BomRow[]): string
 
 #### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
+**Use this from iteration 1 for any model with moving parts.** Hinges, sliders, gears, articulated fingers, doors — all start with `assembly()`, not with manual rotation math. Don't build a static "extended pose" first and refactor to an assembly later: joint sliders, animations, sweeps, collision detection, and robot export all flow from the kinematic graph.
+
 An assembly models a mechanism as a directed graph of parts connected by joints. Parts are the nodes; joints are directed edges from parent to child. The graph must be a forest (no cycles). Root parts (those with no incoming joint) are anchored to world space.
 
 Three joint types are supported: `'revolute'` (hinge), `'prismatic'` (slider), and `'fixed'` (rigid attachment). Use `addPart()` to add geometry, `addJoint()` (or the shorthands `addRevolute()`, `addPrismatic()`, `addFixed()`) to connect parts, and `solve()` to compute world-space positions at a given joint state.
@@ -62,7 +64,7 @@ assembly(name?: string): Assembly
 
 #### `joint()` — Create a revolute joint that auto-generates a parameter slider and rotates the shape.
 
-This is a convenience wrapper for single-shape, single-joint use cases. It calls [`param()`](/docs/core#param) to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
+This is a convenience wrapper for single-shape, single-joint use cases. It calls `param()` to create a named angle slider, then applies `rotateAroundAxis()` to the shape. Use the full `Assembly` API for mechanisms with multiple parts and joints.
 
 ```ts
 const arm = joint("Shoulder", armShape, [0, 0, 20], {
@@ -268,22 +270,28 @@ addFixed(name: string, parent: string, child: string, options?: JointOptions): A
 
 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.
 
-The joint type is inferred from the connector's `kind` field if not specified in `options`. Use `flip: true` for mirrored parts whose connector axis is reflected.
+**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()`.
+
+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.
+
+The joint type is inferred from the connector's `kind` field if not specified in `options`.
 
 When connectors are defined with `start`/`end`, you can control which point on each connector meets via `align` / `parentAlign` / `childAlign` (`'start'`, `'middle'`, `'end'`).
 
 Use `connect()` when connector origins must physically coincide (flange-to-flange, bolt-into-bore). For mechanisms where parts share an axis but are deliberately spaced apart, use `addRevolute()` with pre-positioned parts instead.
 
 ```ts
-const mech = assembly("Arm")
-  .addPart("Base", base)
-  .addPart("Link", link)
-  .connect("Base.top", "Link.shoulder", {
-    as: "J1",
-    min: -90, max: 90, default: 0,
-  });
-
-return mech.solve({ J1: 45 }).toGroup();
+// 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] }),
+});
+const door = box(60, 4, 80).withConnectors({
+  hinge: connector("hinge", { origin: [0, 0, 40], axis: [0, 0, -1] }),
+});
+assembly("Door")
+  .addPart("Frame", frame)
+  .addPart("Door", door)
+  .connect("Frame.hinge", "Door.hinge", { as: "swing", min: 0, max: 110 });
 ```
 
 ```ts