forgecad 0.9.13 → 0.9.15

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

@@ -59,18 +59,24 @@ offsetBand(thickness: number): Sketch
 addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this
 ```
 
+`DriveWheelSpurTeethRegionOptions`: `{ name?: string, teethOnFullCircle: number, toothCount: number, firstTooth?: number, faceWidth?: number }`
+
 #### `addSolidArcBetween()` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
 
 ```ts
 addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this
 ```
 
+**`DriveWheelSolidArcRegionOptions`**: `name?: string`, `fromAngleDeg: number`, `toAngleDeg: number`, `innerRadius?: number`, `outerRadius: number`, `faceWidth?: number`, `segments?: number`
+
 #### `addShapeRegion()` — Add a fully custom region shape while preserving region metadata.
 
 ```ts
 addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this
 ```
 
+`DriveWheelShapeRegionOptions`: `{ fromAngleDeg?: number, toAngleDeg?: number, innerRadius?: number, outerRadius?: number }`
+
 #### `build()` — Build the final wheel shape with a bore connector and region metadata.
 
 ```ts
@@ -137,7 +143,7 @@ Sizes outside the supported ranges will throw at runtime with a descriptive erro
 - `routedTubeClipAssembly(options: RoutedTubeClipAssemblyOptions): RoutedTubeClipAssemblyResult` — Routed tube or cable retained by saddle clips with real bores, screw holes, and installed screws. **Details** This pattern is for hoses, wires, pump tubes, sensor leads, and appliance cable runs where generated models often draw a cylinder near a wall without clips or strain relief. The base panel has receiving screw envelopes, each saddle clip has a real through-bore around the tube and vertical screw clearances, and the installed screws share those positions. Coordinate convention: the routed tube runs along +X through the world origin. The base panel starts at `z=0`; clips sit on top of the panel, and the tube passes through their bores. **Example** ```ts const route = lib.routedTubeClipAssembly({ tubeDiameter: 6, clipCount: 3, }); verify.notColliding('tube clears clip bores', route.tube, union(...route.clips)); verify.notColliding('clip screws clear retained stack', union(...route.screws), union(route.panel, ...route.clips)); return route.parts; ```
 - `pcbTerminalBlockAssembly(options?: PcbTerminalBlockAssemblyOptions): PcbTerminalBlockAssemblyResult` — PCB terminal-block stack with a backplate, standoffs, mounting screws, pin holes, and a seated terminal block. **Details** This pattern is for thermostat backplates, appliance control panels, sensor boards, and small electronics where generated models often place a terminal block, screw heads, and holes as independent decorations. The PCB mounting holes, fused standoffs, installed screws, terminal pins, and PCB pin clearances all come from one shared datum system so the purchased block is mechanically seated and the board is actually mounted. Coordinate convention: X/Y are the board footprint, Z is up. The backplate starts at `z=0`, standoffs rise from the plate, the PCB rests on the standoffs, and the terminal block sits on top of the PCB near the front edge. **Example** ```ts const terminalStack = lib.pcbTerminalBlockAssembly({ terminalCount: 5, screwSize: 'M3', }); verify.notColliding('terminal pins clear PCB holes', terminalStack.terminalBlock, terminalStack.pcb); verify.notColliding('mounting screws clear PCB and standoff holes', union(...terminalStack.screws), union(terminalStack.pcb, terminalStack.backplate)); return terminalStack.parts; ```
 - `thumbScrewClampAssembly(options?: ThumbScrewClampAssemblyOptions): ThumbScrewClampAssemblyResult` — Thumb-screw clamp with a C-frame, threaded boss, captive pressure pad, knob, and clamped workpiece. **Details** This pattern is for bench clamps, monitor-arm desk clamps, small vise screws, capo pressure screws, fixture hold-downs, and service brackets where generated models often place a loose screw, knob, or pressure pad near a bracket. The helper creates a one-piece clamp frame with a fixed anvil pad, a bored threaded support and boss, an installed screw with a captive pressure pad and hand knob, and a representative clamped workpiece seated between the pads. Coordinate convention: the clamp screw runs along +X. The fixed anvil is on the -X side, the threaded support and knob are on the +X side, and Z is up from the base bridge. **Example** ```ts const clamp = lib.thumbScrewClampAssembly({ screwSize: 'M6', workpieceThickness: 20, }); verify.notColliding('thumb screw clears threaded boss', clamp.clampScrew, clamp.frame); verify.clearanceBetween('pressure pad is seated on workpiece', clamp.clampScrew, clamp.workpiece, -0.01, 0.05); return clamp.parts; ```
-- `pipeRoute(points: [ number, number, number ][], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. Each interior waypoint gets a torus-section bend. Straight segments connect them. Returns a single unioned Shape.
+- `pipeRoute(points: [ number, number, number ][], radius: number, options?: { bendRadius?: number; wall?: number; segments?: number; }): Shape` — Route a pipe (solid or hollow) through 3D waypoints with smooth bends. This is a convenience recipe over `Curve.Route.fromPolyline()` and [`sweep()`](/docs/curves#sweep). Use `Curve.Route` directly when you need route metadata, named ports, or custom swept profiles.
 - `elbow(pipeRadius: number, bendRadius: number, angle?: number | { ... }, options?: { ... }): Shape` — Pipe elbow — a curved pipe section (torus arc) for connecting two pipe directions. By default creates a bend in the XZ plane: incoming along +Z, outgoing rotated by `angle`. The bend starts at the origin, curving away from it.
 - `beltDrive(options: BeltDriveOptions): BeltDriveResult` — Create a flat open-belt body around two pulley pitch circles. The belt is generated as a tangent loop in the XY plane and extruded along +Z by `beltWidth`. The result includes the solid belt, the 2D belt profile, a thin pitch-path sketch for visualization, total belt length, tangent spans, and wrap metadata for each pulley. For more than two pulleys, the API intentionally asks for route intent before geometry is created. Use `route: "outer"` for the future outside-envelope mode, or an ordered route for future serpentine/idler layouts. ```ts const drive = lib.beltDrive({ pulleys: [ { name: "motor", center: [0, 0], pitchRadius: 12 }, { name: "output", center: [80, 0], pitchRadius: 28 }, ], beltWidth: 8, beltThickness: 2, }); return drive.belt; ```
 - `tangentLoop2d(circles: TangentCircle2D[], options?: TangentLoop2DOptions): TangentLoop2D` — Build a closed 2D route made from common tangent spans and pulley wrap arcs. Use this when you need reusable belt/chain route geometry before creating a solid body. The first implementation supports two circles. `mode: "open"` uses external tangents; `mode: "crossed"` uses internal tangents. ```ts const route = lib.tangentLoop2d([ { center: [0, 0], radius: 12 }, { center: [80, 0], radius: 28 }, ]); const belt = route.offsetBand(2).extrude(8); ```

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

@@ -68,7 +68,7 @@ Call `robotExport()` alongside your assembly definition. The CLI commands `forge
 
 - Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
 - Separate collision meshes (convex hull by default — ~50–80% smaller)
-- Joint mimic elements derived from `addJointCoupling` / `addGearCoupling`
+- Joint limits, effort/velocity/damping/friction metadata from assembly joints
 
 **Collision mesh modes** (set per-link via `links["PartName"].collision`):
 
@@ -84,7 +84,7 @@ Call `robotExport()` alongside your assembly definition. The CLI commands `forge
 - Revolute `velocity` is in degrees/second in Forge; exporters convert to rad/s.
 - Prismatic distances are in mm in Forge; exported in meters.
 - `massKg` is preferred; `densityKgM3` is used when mass is unknown.
-- Couplings with multiple terms: only the primary term (largest ratio) maps to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
+- Compatibility coupling metadata, when present, maps only the primary term (largest ratio) to `<mimic>` — SDF/URDF support single-leader mimic only. Dropped terms emit a warning.
 
 ```ts
 const rover = assembly("Scout")
@@ -140,9 +140,9 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 **`CollectedRobotExport`**: `modelName: string`, `assembly: AssemblyDefinition`, `state: JointState`, `static: boolean`, `selfCollide: boolean`, `allowAutoDisable: boolean`, `links: Record<string, RobotLinkExportOptions>`, `joints: Record<string, RobotJointExportOptions>`, `plugins: { diffDrive?: RobotDiffDrivePluginOptions; jointStatePublisher?: RobotJointStatePublisherOptions; }`, `world: RobotWorldOptions | null`
 
-`AssemblyDefinition`: `{ name: string, parts: AssemblyPartDef[], joints: AssemblyJointDef[], jointCouplings: AssemblyJointCouplingDef[] }`
+**`AssemblyDefinition`**: `name: string`, `parts: AssemblyPartDef[]`, `joints: AssemblyJointDef[]`, `jointCouplings: AssemblyJointCouplingDef[]`, `kinematics: AssemblyKinematicGraphDef`
 
-`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
+`AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata, mates: AssemblyPartMateInput[] }`
 
 **`PartMetadata`**
 
@@ -151,6 +151,11 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 | `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
 | `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
+**`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).
+
 **`AssemblyJointDef`**: `name: string`, `type: JointType`, `parent: string`, `child: string`, `frame: Transform`, `axis: Vec3`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `connectorRefs?: JointConnectorRefs`
 
 `JointConnectorRefs`: `{ parent: string, child: string, parentAlign?: PortAlign, childAlign?: PortAlign }`
@@ -159,6 +164,16 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `JointCouplingTermRecord`: `{ joint: string, ratio: number }`
 
+`AssemblyKinematicGraphDef`: `{ links: AssemblyLinkDef[], edges: AssemblyEdgeBetweenLinksDef[], angles: AssemblyAngleBetweenLinksDef[] }`
+
+`AssemblyLinkDef`: `{ name: string, at: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
+
+**`AssemblyEdgeBetweenLinksDef`**: `name: string`, `a: string`, `b: string`, `length: number | null`, `min?: number`, `max?: number`, `visualOnly: boolean`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
+`AssemblyKinematicControlOptions`: `{ min?: number, max?: number, default?: number, unit?: string }`
+
+**`AssemblyAngleBetweenLinksDef`**: `name: string`, `a: string`, `b: string`, `c: string`, `target?: number`, `min?: number`, `max?: number`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
+
 #### `dim()` — Add a dimension annotation between two points.
 
 Dimension annotations are purely visual callouts rendered in the viewport and report export. They do not affect geometry or constrain the model.

package/dist-skill/docs/generated/runtime-names.md

@@ -0,0 +1,41 @@
+---
+skill-group: core
+skill-order: 2
+---
+
+# Runtime Names
+
+Generated by `scripts/gen-api-docs.mjs` from `src/forge/script-runtime/runScript.ts`. Do not edit by hand.
+
+ForgeCAD injects API functions, classes, namespaces, and sandbox guard names into every `.forge.js` script. Top-level lexical declarations using these names collide with the injected runtime bindings when the script runs.
+
+Agents should avoid declaring these names with top-level `const`, `let`, destructured imports, or `class` declarations. Use project-specific local names such as `wheelLib`, `axleSlotSketch`, `driveJointConfig`, or `labelTextSketch` instead.
+
+These collision-reserved names are case-sensitive:
+
+```text
+activateBackend, Analysis, arcSlot, assembly, Assembly, assemblyInstructions, assemblyPreview, Blend
+bom, bomToCsv, boolParam, box, cameraTrajectory, Carrier, chamfer, chamferTrackedEdge
+choiceParam, circle, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d, coalesceEdges
+combine, COMMON_KERFS, compareWith, composeChain, connectEdges, connector, console, constrainedSketch
+Constraint, Counterbore, Curve, Curve3D, cutPlane, cylinder, degrees, difference
+difference2d, dim, dimLine, draft, ellipse, explodeView, faceProfile, fillet
+filletCorners, filletTrackedEdge, fingerJoint, flatPanel, flatPart, formatInstructions, Function, gcode
+GCodeBuilder, getActiveBackend, global, globalThis, group, Helix, HelixCurve, hermiteTransitionG2
+highlight, Import, ImportedAssembly, importMesh, importStep, importSvgSketch, initKernel, intersection
+intersection2d, intersectWithPlane, joint, jointsView, laserKit, lib, line, Line2D
+linearPattern, linearPattern2d, listParam, loadFont, loft, Loft, loftAlongSpine, lookupKerf
+mirrorCopy, mock, ngon, nurbs3d, NurbsCurve3D, nurbsSurface, NurbsSurface, offsetSolid
+param, Param, path, point, Point2D, Points, polygon, polygonVertices
+port, Product, ProductHandleBuilder, ProductHandleFeature, ProductPanelBuilder, ProductRibbonBuilder, ProductSkin, ProductSkinBuilder
+ProductSpoutBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, radians, rect
+Rectangle2D, Ribs, robotExport, roundedRect, Route3D, scene, Sculpt, sdf
+SdfShape, selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout
+Shape, ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch, sketchToDxf, sketchToSvg
+slot, Slot, SolvedAssembly, spec, sphere, spline2d, spline3d, star
+stroke, Surface, SurfaceBody, SurfaceMembers, surfacePatch, sweep, tabSlot, text2d
+textWidth, torus, toShape, Transform, transitionCurve, transitionSurface, union, union2d
+variableSweep, verify, viewConfig, Viewport, window, Wood
+```
+
+`showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.

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

@@ -101,12 +101,33 @@ color(value: string | undefined): SdfShape
 material(props: ShapeMaterialProps): SdfShape
 ```
 
+**`ShapeMaterialProps`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
+| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
+| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
+| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
+| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
+| `wireframe?` | `boolean` | Render as wireframe. Default: false |
+| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
+| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
+| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
+| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
+| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
+| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
+| `specularColor?` | `string` | Specular highlight tint. |
+| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
+
 #### `bounds()` — Set explicit preview/meshing bounds for this implicit leaf.
 
 ```ts
 bounds(bounds: SdfBounds | [ Vec3, Vec3 ]): SdfShape
 ```
 
+`SdfBounds`: `{ min: Vec3, max: Vec3 }`
+
 #### `at()` — Sculpt-style alias for translate().
 
 ```ts
@@ -203,6 +224,12 @@ fillWith(pattern: SdfShape): SdfShape
 fillWithGyroid(options: TpmsOptions): SdfShape
 ```
 
+**`TpmsOptions`**
+- `thickness?: number` — Dimensionless field threshold kept for compatibility. Prefer `wallThickness` for approximate millimeter units.
+- `wallThickness?: number` — Approximate physical wall thickness in millimeters.
+- `tpmsThicknessMode?: TpmsThicknessMode` — Override TPMS thickness interpretation. Defaults to metric when `wallThickness` is used, field-threshold when `thickness` is used.
+- Also: `cellSize: number`
+
 #### `fillWithSchwarzP()` — Keep only the Schwarz-P lattice inside this shape.
 
 ```ts
@@ -353,6 +380,10 @@ shape.surfaceDisplace((u, v) => -Math.sin(u * 2) * 0.3)
 surfaceDisplace(pattern: SurfacePattern | ((u: number, v: number) => number), options?: SurfaceDisplaceOptions): SdfShape
 ```
 
+**`SurfaceDisplaceOptions`**
+- `uv?: "auto" | "sphere" | "cylinder" | "torus" | "triplanar"` — Override auto-detected UV mode. Default: 'auto' (detects from SDF tree).
+- `triplanarSharpness?: number` — Triplanar blend sharpness — higher = crisper transitions. Default: 4. Only used in triplanar mode.
+
 #### `onion()` — Create concentric onion layers.
 
 ```ts

package/dist-skill/docs/generated/sheet-metal.md

@@ -284,6 +284,10 @@ const part = sheetMetal({ panel: { width: 100, height: 60 }, thickness: 1.5, ben
 flange(edge: SheetMetalEdge, options: SheetMetalFlangeOptions): SheetMetalPart
 ```
 
+**`SheetMetalFlangeOptions`**
+- `length: number` — Flange leg length in mm, measured from the outside of the bend to the tip.
+- `angleDeg?: number` — Bend angle in degrees (default: `90`). Only `90°` is supported in v1. Values other than 90 will be rejected at build time.
+
 #### `cutout()` — Subtract a 2D sketch cutout from a planar region of the sheet metal part.
 
 `region` must be `'panel'` or one of `'flange-top'`, `'flange-right'`, `'flange-bottom'`, `'flange-left'` (only available once the corresponding flange has been added). Cutouts inside bend regions are **not** supported in v1.
@@ -303,6 +307,11 @@ const part = sheetMetal({ panel: { width: 180, height: 110 }, thickness: 1.5, be
 cutout(region: SheetMetalPlanarRegionName, sketch: Sketch, options?: SheetMetalCutoutOptions): SheetMetalPart
 ```
 
+**`SheetMetalCutoutOptions`**
+- `u?: number` — Horizontal offset within the region, measured from the region centre (mm). Default: `0`.
+- `v?: number` — Vertical offset within the region, measured from the region centre (mm). Default: `0`.
+- `selfAnchor?: Anchor` — Anchor point on the sketch that aligns to `(u, v)`. Use `'center'` for most cases. For asymmetric profiles, verify orientation by placing one test cutout before committing to the final position. Default: `'center'`.
+
 #### `regionNames()` — Return all semantic region names currently available on this part.
 
 The returned list always includes `'panel'`. For every flange that has been added, the list also includes the corresponding `'flange-<edge>'` and `'bend-<edge>'` entries.

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

@@ -500,7 +500,6 @@ addRegularPolygon(sk: ConstrainedSketchBuilder, options: RegularPolygonOptions):
 | `startAngle?` | `number` | Angle (in degrees) of vertex[0] measured from the +X axis (CCW positive). Default: 0 (rightmost vertex). |
 | `blockRotation?` | `boolean` | Prevent 180° rotation (ensures first edge maintains its initial direction). Default: false. |
 
-
 **`ConstrainedRegularPolygon`** extends ConstrainedPolygon
 - `center: PointId` — Center point. Use `sk.fix(poly.center, x, y)` to pin location, or `sk.coincident(poly.center, other)` to align with other geometry.
 
@@ -740,7 +739,7 @@ region(seed: [ number, number ]): Sketch
 extrude(height: number, opts?: { twist?: number; divisions?: number; scaleTop?: number | [ number, number ]; }): Shape
 ```
 
-#### `revolve()` — Revolve this 2D sketch around the Y axis to create a 3D solid of revolution.
+#### `revolve()` — Revolve this 2D sketch around the world Z axis. Sketch X is radius; sketch Y becomes world Z height.
 
 ```ts
 revolve(degrees?: number, segments?: number): Shape
@@ -771,6 +770,22 @@ Use this when a 2D profile should be oriented onto a 3D face before extrusion or
 onFace(parentOrFace: Shape | { toShape(): Shape; } | { _bbox(): { min: number[]; max: number[]; }; } | FaceRef, faceOrOpts?: "front" | "back" | "left" | "right" | "top" | "bottom" | string | FaceRef | { u?: number; v?: number; protrude?: number; selfAnchor?: Anchor; }, opts?: { u?: number; v?: number; protrude?: number; selfAnchor?: Anchor; }): Sketch
 ```
 
+**`FaceRef`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `normal` | `[ number, number, number ]` | Normal direction of the face |
+| `center` | `[ number, number, number ]` | Center point of the face |
+| `query?` | `FaceQueryRef` | Compiler-owned face query when available. |
+| `planar?` | `boolean` | True when the face can host a 2D sketch placement frame |
+| `uAxis?` | `[ number, number, number ]` | Face-local horizontal axis for planar faces |
+| `vAxis?` | `[ number, number, number ]` | Face-local vertical axis for planar faces |
+| `surface?` | `FaceSurface` | Analytic surface family when the backend can identify one. |
+| `descendant?` | `FaceDescendantMetadata` | Shared descendant-resolution metadata when this face is a semantic region/set. |
+| `name` | | — |
+
+**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
+
 **Labels**
 
 #### `labelEdge()` — Label the single boundary edge (for circles, single-loop profiles). Returns a new sketch.
@@ -1069,6 +1084,16 @@ regularPolygon(options: RegularPolygonOptions): ConstrainedRegularPolygon
 groupRect(options: GroupRectOptions): ConstrainedGroupRect
 ```
 
+**`GroupRectOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `x?` | `number` | Bottom-left x coordinate (world). Default: 0. |
+| `y?` | `number` | Bottom-left y coordinate (world). Default: 0. |
+| `width` | `number` | Width (along x in local coords). Required. |
+| `height` | `number` | Height (along y in local coords). Required. |
+| `allowRotation?` | `boolean` | Allow the solver to rotate this rectangle. Default: false. |
+
 **Geometric Constraints**
 
 #### `horizontal()` — Constrain a line to be horizontal (parallel to the X axis).
@@ -1412,6 +1437,23 @@ result.withUpdatedConstraint('cst-5', 120); // update a dimension without rebuil
 solve(options?: SolveOptions): ConstraintSketch | Sketch
 ```
 
+**`SolveOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `iterations?` | `number` | Maximum number of LM outer iterations per restart. |
+| `tolerance?` | `number` | Infinity-norm residual tolerance for declaring convergence. |
+| `restarts?` | `number` | Number of deterministic restart seeds used by the global solver. |
+| `warmStartIterations?` | `number` | Optional projector iterations used only for initialisation, not as the main solver. |
+| `maxScaledStep?` | `number` | Maximum LM step length in scaled variable space. Larger = bolder, smaller = safer. |
+| `skipRedundancyCheck?` | `boolean` | Skip redundancy detection (safe when topology is unchanged and previous DOF >= 0). |
+| `presolveConstraintId?` | `string` | Run the targeted presolve hook for this constraint before the main solve. |
+| `fallbackRestarts?` | `number` | When set and the first solve exceeds tolerance*5, retry with this many restarts. |
+| `progressive?` | `boolean` | Add constraints progressively with short LM solves, all in one WASM call. |
+| `timeBudgetMs?` | `number` | Wall-clock time budget in ms for the entire solve. 0 = no limit. |
+| `debugConstructiveTranscript?` | `boolean` | Capture a readable constructive transcript in `constraintMeta.debug`. |
+| `debugSvgSnapshots?` | `boolean` | Capture SVG snapshots for constructive steps in `constraintMeta.debug`. |
+
 #### `solveConstraintsOnly()` — Run the solver without building a full `ConstraintSketch`.
 
 Lighter than `solve()` — skips profile and DOF analysis. Useful for lightweight constraint validation or progress monitoring mid-construction.

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

@@ -9,7 +9,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `jointsView`, `compareWith`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `compareWith`, `cutPlane`, `mock`, `showLabels`, `highlight`
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -196,7 +196,7 @@ scene(options: SceneOptions): void
 
 #### `viewConfig()` — Configure viewport helper visuals for the current script execution.
 
-Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when `jointsView` is active. Multiple calls merge — later values override earlier ones per key.
+Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when joint controls are active. Multiple calls merge — later values override earlier ones per key.
 
 This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
 
@@ -253,91 +253,6 @@ explodeView(options?: ExplodeViewOptions): void
 - `direction?: ExplodeDirection` — Direction mode for this node
 - `axisLock?: ExplodeAxis` — Optional axis lock after direction is resolved
 
-#### `jointsView()` — Register viewport-only mechanism controls that animate returned objects without re-running the script.
-
-Defines joints (revolute or prismatic), optional gear/rack couplings, and named animations. The viewport resolves transforms through the joint chain at display time — the script geometry is computed only once at rest pose.
-
-**Critical:** Solve the assembly at **rest pose** (all animated joints = 0). The viewport applies `jointsView` transforms on top of the returned scene. If geometry is already solved at non-zero angles, animation will double-rotate everything.
-
-```js
-// BAD — double rotation
-const solved = mech.solve({ shoulder: 45, elbow: 30 });
-jointsView({ joints: [{ name: 'shoulder', ... }] });
-return solved;
-
-// GOOD — rest pose, jointsView controls all posing
-const solved = mech.solve({ shoulder: 0, elbow: 0 });
-jointsView({
-  joints: [
-    { name: 'shoulder', child: 'Upper Arm', default: 45, ... },
-    { name: 'elbow', child: 'Forearm', parent: 'Upper Arm', default: 30, ... },
-  ],
-});
-return solved;
-```
-
-**Pivot coordinates** are world-space positions of each joint origin at rest pose. For `addRevolute('shoulder', 'Base', 'Link', { frame: Transform.identity().translate(0, 0, 20) })` where "Base" is at world origin, the pivot is `[0, 0, 20]`.
-
-**Fixed attachments** that must follow a parent during animation need a zero-angle revolute joint in the chain:
-
-```js
-{ name: 'EE_Follow', child: 'End Effector', parent: 'Last Link',
-  type: 'revolute', axis: [0, 0, 1], pivot: [linkLength, 0, 0],
-  min: 0, max: 0, default: 0 }
-```
-
-Animation values are interpolated linearly between keyframes. ForgeCAD does **not** auto-wrap revolute values across `-180/180`. Keep keyframe values continuous — a `-180 -> 171` jump spins the part the long way around. Use `-180 -> -189` instead. Author high-speed multi-turn joints as accumulating angles (`0, 360, 720, ...`) with `continuous: true`.
-
-**Tick-based keyframes:** Omit `at` from all keyframes to auto-distribute by tick weight:
-
-```js
-keyframes: [
-  { ticks: 3, values: { Shoulder: 20 } },  // slow segment (3x weight)
-  { ticks: 1, values: { Shoulder: -10 } }, // fast segment (1x weight)
-  { values: { Shoulder: 20 } },            // last keyframe; ticks ignored
-]
-// positions: 0, 0.75, 1.0
-```
-
-Mixing explicit `at` and omitted `at` in the same animation is not allowed.
-
-```js
-jointsView({
-  joints: [{
-    name: 'Shoulder', child: 'Upper Arm', parent: 'Base',
-    type: 'revolute', axis: [0, -1, 0], pivot: [0, 0, 46],
-    min: -30, max: 110, default: 15,
-  }],
-  animations: [{
-    name: 'Walk Cycle', duration: 1.6, loop: true,
-    keyframes: [
-      { values: { Shoulder: 20 } },
-      { values: { Shoulder: -10 } },
-      { values: { Shoulder: 20 } },
-    ],
-  }],
-});
-```
-
-```ts
-jointsView(options?: JointsViewOptions): void
-```
-
-**`JointsViewOptions`**: `enabled?: boolean`, `joints?: JointViewInput[]`, `couplings?: JointViewCouplingInput[]`, `animations?: JointViewAnimationInput[]`, `defaultAnimation?: string`
-
-**`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`
-
-`JointViewCouplingInput`: `{ joint: string, terms: JointViewCouplingTermInput[], offset?: number }`
-
-`JointViewCouplingTermInput`: `{ joint: string, ratio?: number }`
-
-`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>`
-
 #### `compareWith()` — Declare a reference model for comparison inspection.
 
 `compareWith()` lets a model carry its own comparison target for inspection workflows. `forgecad inspect compare overlay model.forge.js` uses this reference to render the same Difference Only comparison overlay as the live viewport. Amber marks candidate mismatch evidence, cyan marks reference mismatch evidence, and faint model context keeps the overlay readable. When the CLI can resolve the referenced file, the manifest also includes the same geometric score produced by `forgecad compare 3d`.
@@ -384,13 +299,13 @@ Overloads:
 - `offset?: number` — Optional offset along the plane normal (primarily for object-form overload).
 - `exclude?: CutPlaneExcludeInput` — Object names to keep uncut for this plane.
 
-#### `mock()` — Register a mock (context) object for visualization and collision checking.
+#### `mock()` — Register a mock (context) object for visualization and inspection.
 
-Mock objects appear in the viewport and spatial analysis when you run a file directly, but are excluded when the file is imported via [`require()`](/docs/core#require). This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
+Mock objects appear in the viewport and inspection analysis when you run a file directly, but are excluded when the file is imported via [`require()`](/docs/core#require). This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
 
 The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
 
-Mock objects participate in `forgecad run --spatial bounded|exact` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
+Mock objects participate in focused inspection commands such as `forgecad inspect fit interference` and `forgecad inspect physical gaps`. Their names appear with a `(mock)` suffix in reports.
 
 In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.
 

package/dist-skill/docs/guides/coordinate-system.md

@@ -7,39 +7,43 @@ skill-order: 1
 
 ForgeCAD uses a **Z-up** right-handed coordinate system.
 
+For objects with a clear facing direction, model the front/face/nose/camera side toward **-Y**. The rear/back side is **+Y**. In code, a forward/fore direction vector is `[0, -1, 0]`.
+
 ## Axes
 
 | Axis | Direction       | Positive |
 |------|-----------------|----------|
 | X    | Left / Right    | Right    |
-| Y    | Forward / Back  | Forward  |
+| Y    | Front / Back    | Back     |
 | Z    | Up / Down       | Up       |
 
 ## Standard Views
 
+The camera position direction says where the camera sits relative to the model. A front view camera sits at `-Y` and looks toward `+Y`, so it sees the model's `-Y` front face.
+
 | View   | Camera position direction | Sees plane |
-|--------|--------------------------|------------|
-| Front  | −Y                       | XZ         |
-| Back   | +Y                       | XZ         |
+|--------|---------------------------|------------|
+| Front  | -Y                        | XZ         |
+| Back   | +Y                        | XZ         |
 | Right  | +X                       | YZ         |
-| Left   | −X                       | YZ         |
+| Left   | -X                       | YZ         |
 | Top    | +Z                       | XY         |
-| Bottom | −Z                       | XY         |
+| Bottom | -Z                       | XY         |
 
 ## GizmoViewcube Face Mapping
 
-Three.js BoxGeometry material indices vs ForgeCAD labels (Z-up remapping):
+Renderer/view-cube internals may have their own material ordering. Map any view-cube labels to the ForgeCAD directions below:
 
-| Index | Three.js direction | ForgeCAD label |
-|-------|--------------------|----------------|
-| 0     | +X                 | Right          |
-| 1     | −X                 | Left           |
-| 2     | +Y                 | Front          |
-| 3     | −Y                 | Back           |
-| 4     | +Z                 | Top            |
-| 5     | −Z                 | Bottom         |
+| Direction | ForgeCAD label |
+|-----------|----------------|
+| +X        | Right          |
+| -X        | Left           |
+| +Y        | Back           |
+| -Y        | Front          |
+| +Z        | Top            |
+| -Z        | Bottom         |
 
-Default drei labels are Y-up; ForgeCAD passes `faces={['Right','Left','Front','Back','Top','Bottom']}`.
+The face/anchor API is the source of truth: `front` resolves to the minimum-Y side and `back` resolves to the maximum-Y side.
 
 ## Grid
 

package/dist-skill/docs/guides/geometry-conventions.md

@@ -21,7 +21,7 @@ Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0
 
 ## Revolution Axis
 
-`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
+`Sketch.revolve()` produces a world Z-axis solid of revolution. Profile X = radial distance from the Z axis, Profile Y = world Z height after revolution. Profile should stay at X > 0 unless intentionally touching the axis.
 
 ## Boolean Winding (3D)
 
@@ -47,6 +47,6 @@ Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code t
 |---|---|---|---|
 | Winding | Any point order | CCW | `polygon()`, `path().close()` |
 | Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
-| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
+| Revolution | "revolve this profile" | Profile X = radius, Profile Y = world Z height | Documented and regression-tested |
 | Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
 | Transform order | Left-to-right chain | Post-multiply | Native match |

package/dist-skill/docs/guides/inspection-bundles.md

@@ -60,7 +60,7 @@ stable; named scene views are still available through `--view`.
 The command tree is intentionally job-shaped:
 
 ```text
-inspect visual image|cutaway|depth|normals|objects
+inspect visual image|cutaway|depth|normals|rig|objects
 inspect surface zebra|roughness
 inspect physical components|floating|gaps
 inspect fit interference
@@ -101,6 +101,7 @@ Use targeted evidence commands for expensive analyses:
 ```bash
 forgecad inspect visual depth model.forge.js --camera iso
 forgecad inspect visual normals model.forge.js --camera iso
+forgecad inspect visual rig model.forge.js --camera iso
 forgecad inspect surface zebra model.forge.js --camera iso
 forgecad inspect surface roughness model.forge.js --camera iso
 forgecad inspect visual objects model.forge.js --camera iso

package/dist-skill/docs/guides/joint-design.md

@@ -7,6 +7,30 @@ skill-order: 5
 
 How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
 
+## Frame-Aware Connectors First
+
+If a part must rotate, slide, or point in a specific physical direction, define connectors and use `assembly().connect()`. A connector is a small coordinate frame on the part:
+
+- `origin` is the pivot, pin center, socket center, or contact point.
+- `axis` is the hinge line or slide direction.
+- `up` is the secondary direction that fixes the part's zero-angle twist.
+
+For a hip -> knee -> wheel chain, the upper leg should be a real part with a hip connector and a knee connector. The hip connector frame defines how the upper leg sits on the hip drum at rest; the knee connector frame defines where the next part attaches. `connect()` aligns those frames and derives the joint axis.
+
+Do not treat `up` as optional on hinges, wheels, levers, or keyed sliders. If `up` is omitted, ForgeCAD chooses a deterministic perpendicular vector, which keeps the model stable but may not match the intended mechanical rest pose.
+
+Use `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()` for solved point skeletons and closed-loop relationships. A link is a point, not a bone frame. `addPart(..., { mate: { connector, toLink } })` only moves a connector origin onto a solved link point; it does not rotate the part to aim along an edge.
+
+## Mirrored Revolute Axes
+
+Revolute joint values are physical values signed by the right-hand rule around the joint axis. If a bilateral mechanism mirrors a hinge axis, the same numeric joint value does not mean "same pose" on both sides.
+
+Example: a right ankle hinge with `axis: [1, 0, 0]` and a left ankle hinge with `axis: [-1, 0, 0]` are exact geometric mirrors at rest. But `+20` degrees around those two axes rotates the feet in opposite fore/aft senses. The mirrored pose uses `RightAnkle: 20` and `LeftAnkle: -20`.
+
+When you expose physical joint limits directly, mirror revolute limits as `[min, max] -> [-max, -min]`. Prismatic joints do not have this angle-handedness flip because their scalar value translates along the mirrored axis.
+
+For bilateral robots, legs, grippers, and suspension mechanisms, prefer a side-neutral control layer when possible: solve mirrored link positions with `link()`, `edgeBetweenLinks()`, and `addAngleBetweenLinks()`, then attach real parts to the solved skeleton. If you use connector-frame joints directly, make the sign mapping explicit in defaults, keyframes, and verification.
+
 ## The Cavity Rule
 
 Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.

package/dist-skill/docs/guides/positioning.md

@@ -11,6 +11,16 @@ For any fixed assembly where parts are meant to stay in contact in the final mod
 
 Use raw `translate()` and `rotate()` when parts are intentionally free-floating or when you are doing quick exploratory layout. Use `attachTo()` for rough bounding-box placement. But if the relationship is a real interface, make it explicit with connectors.
 
+## Mechanisms: connector frames vs link points
+
+For serial articulated parts (hinges, hips, knees, levers, wheels), use `assembly().connect()` with connectors. `connect()` aligns the full connector frame: `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` locks the zero-angle twist of the child part. `up` is a local roll reference, not world up; author it explicitly whenever the rest pose matters.
+
+Do not use `addPart(..., { mate: { connector, toLink } })` when the part must point along a bone or inherit orientation from a link edge. Link mates are point attachments only: they translate the connector origin onto the solved link position and preserve the part's existing rotation. That is good for markers, sensors, labels, and debug handles. It is not a bone-frame API.
+
+Use link graphs (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) when the hard part is solving point positions, especially closed loops. Use connector-frame joints when the hard part is orienting real physical parts.
+
+For bilateral mechanisms, remember that connector-frame revolute values are physical axis-local values. Mirrored hinge axes need negated physical revolute values for the same mirrored pose, and physical limits mirror as `[min, max] -> [-max, -min]`. If you want `HipR: 10` and `HipL: 10` to mean the same semantic pose, drive a mirrored link graph or write an explicit state mapping instead of assuming equal connector-joint values are symmetric.
+
 ## Primitive origin convention
 
 All 3D primitives are **centered on XY, base at Z=0**:
@@ -34,14 +44,14 @@ Most positioning bugs come from manual coordinate arithmetic. Use these methods
 
 ## 1. Connectors + `matchTo()` — default for mating interfaces
 
-Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
+Define connectors on parts; `matchTo()` provides automatic alignment. With one connector pair, the child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model), and `up` pins the roll reference. With multiple connector pairs, the connector origins define the rigid transform; still author meaningful `axis` and `up` values so the same connectors remain useful for `connect()`, audits, and future matching.
 
 ```javascript
 const shelf = box(200, 120, 10).translate(0, 0, -5).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0], up: [0, 0, 1] }),
 });
 const panel = box(12, 120, 200).translate(0, 0, -100).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0], up: [0, 0, 1] }),
 });
 const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
 // Dictionary form for multiple pairs on same target:

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

@@ -31,13 +31,13 @@ Do not solve reconstruction by returning `importMesh("reference.stl")` or `impor
    No wrapper script is needed. Use the local checkout CLI:
 
    ```bash
-   node dist-cli/forgecad.js run path/to/source.stl --quality live --details
+   node dist-cli/forgecad.js ls path/to/source.stl --quality live --long
    node dist-cli/forgecad.js render 3d path/to/source.stl /tmp/<slug>-source.png --camera iso --edges thin --size 900
    node dist-cli/forgecad.js inspect visual objects path/to/source.stl /tmp/<slug>-source-objects --camera iso --size 700 --force
    node dist-cli/forgecad.js inspect sections sample path/to/source.stl /tmp/<slug>-source-sections --count 5 --size 700 --force
    ```
 
-   For 3MF sources, `run --details` also prints the source archive's build
+   For 3MF sources, `forgecad run` prints the source archive's build
    items/resource objects with stable refs such as
    `3mf:build:001:object:2`, automatic names, per-item bounding boxes, and
    triangle counts. Use that item table to avoid missing hidden multi-part