forgecad 0.10.0 → 0.10.1

package/dist/docs-raw/CLI.md

@@ -46,7 +46,9 @@ ForgeCAD includes a local editor. Open it around a dedicated project folder, edi
 | `dev <project-path> [project-path ...]` | Start the Vite dev server for ForgeCAD source development. |
 | `web` | Start a local dev server in web/playground mode (no filesystem, localStorage only). |
 
-`forgecad studio <project-path>` is the normal installed-CLI command; `forgecad dev` starts the Vite dev server and is mainly for ForgeCAD source development. Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder as an argument — the user opens the single printed localhost port once, and AI agents only create or edit files under those folders so the browser updates live without starting more servers.
+`forgecad studio <project-path>` is the normal installed-CLI command for users. `forgecad dev <project-path>` starts the Vite dev server and is mainly for ForgeCAD source development.
+
+Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
 
 <details>
 <summary>Common flags for studio / dev</summary>
@@ -291,6 +293,7 @@ Export to every format you need.
 | `export stl` | STL | 3D printing |
 | `export gcode` **\[Production\]** | G-code | Toolpath (scripted, not sliced) |
 | `export sdf` **\[Production\]** | SDF package | Gazebo robot simulation |
+| `export mjcf` **\[Production\]** | MJCF package | MuJoCo / MJX robot simulation |
 | `export urdf` **\[Production\]** | URDF package | ROS / PyBullet / MuJoCo |
 | `export report` **\[Production\]** | PDF report | Multi-view report with BOM and dimensions |
 | `export cutting-layout` **\[Production\]** | PDF/DXF | Sheet cutting layout with cut sequence |
@@ -314,6 +317,7 @@ forgecad export report bracket.forge.js out/report.pdf
 
 # Robot simulation
 forgecad export sdf rover.forge.js --output out/forge_scout
+forgecad export mjcf rover.forge.js --output out/forge_scout_mjcf
 ```
 
 <details>
@@ -451,7 +455,7 @@ forgecad skill flattened-files ~/Desktop/forgecad-skills
 
 ## Validation
 
-Check printability and run focused model integrity reviews.
+Check printability, simulation readiness, and focused model integrity.
 
 ### `forgecad compare 3d`
 
@@ -477,6 +481,17 @@ forgecad check print model.forge.js
 forgecad check print model.forge.js --json
 ```
 
+### `forgecad check simready`
+
+Validate source-authored robot and physics metadata before simulation export.
+
+Runs a Forge script and checks the returned `assembly(...).withSimulation(...)` contract without Isaac Sim, OpenUSD, or NVIDIA validators. The gate validates Sim.body metadata, explicit colliders, contact connectors, controller joints, numeric physics values, and the robot joint graph.
+
+```bash
+forgecad check simready model.forge.js
+forgecad check simready robot.forge.js --json
+```
+
 ### `forgecad inspect mechanical-integrity`
 
 Inspect generated ForgeCAD models for mechanical integrity failures.
@@ -514,7 +529,7 @@ The CLI is free for personal non-commercial use. Pro covers human-operated comme
 
 | Free | Production outputs | Pro | Enterprise |
 |------|--------------------|-----|------------|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `compare 3d`, `check print`, `inspect fit interference`, `inspect mechanical-integrity` for personal non-commercial use | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work | `render hq`, `capture gif`, `capture mp4` plus commercial coverage for client/customer work | Backend, hosted, embedded, or application workflows that call ForgeCAD automatically |
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `compare 3d`, `check print`, `inspect fit interference`, `inspect mechanical-integrity` for personal non-commercial use | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export mjcf`, `export urdf`, `export report`, `export cutting-layout` are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work | `render hq`, `capture gif`, `capture mp4` plus commercial coverage for client/customer work | Backend, hosted, embedded, or application workflows that call ForgeCAD automatically |
 
 ```bash
 forgecad license                    # Check local license status

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

@@ -5,7 +5,7 @@ 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
 
@@ -18,6 +18,63 @@ Assembly-owned links, constraints, connectors, solved poses, and robot export.
 
 ### Assembly & Joints
 
+#### `Sim.material(name: string, options?: SimMaterialOptions): SimMaterialDef` — Create a named physical material with density and contact coefficients for simulation export and checks.
+
+`SimMaterialOptions`: `{ densityKgM3?: number, staticFriction?: number, dynamicFriction?: number, restitution?: number }`
+
+
+`SimMaterialDef`: `{ kind: "material", name: string }`
+
+#### `Sim.body(options: SimBodyOptions): SimBodyDef` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces.
+
+**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`
+
+`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string }`
+
+`SimContactDef`: `{ kind: "wheelSurface" | "gripperSurface", connectorName: string }`
+
+
+`SimBodyDef`: `{ kind: "body" }`
+
+#### `Sim.collider` — Collision-geometry intent constructors for physical parts.
+
+- `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.
+
+#### `Sim.drive` — Joint-drive intent constructors for passive or powered assembly joints.
+
+- `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.
+
+`SimPassiveDriveOptions`: `{ damping?: number, friction?: number }`
+
+
+`SimVelocityDriveOptions`: `{ maxTorqueNm: number, maxSpeedRpm: number }`
+
+#### `Sim.contact` — Contact-surface metadata over existing part connectors.
+
+- `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.
+
+#### `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.
+
+`SimProfileDef`: `{ kind: "profile", name: SimProfileName }`
+
+#### `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.
 
 **Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
@@ -151,7 +208,7 @@ const housing = group(
 assembly.addPart("Base Assembly", housing);
 ```
 
-**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
 
 **`PartMetadata`**
 
@@ -212,7 +269,9 @@ Frame semantics: `origin` is the pivot/contact point, `axis` the hinge or slide
 
 **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()`).
 
-**Mirrored revolute axes:** revolute values follow the right-hand rule, so 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.
+**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.
+
+**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.
 
 Joint type defaults to the connector's `kind`. For `start`/`end` connectors, `align` / `parentAlign` / `childAlign` (`'start' | 'middle' | 'end'`) choose which point meets.
 
@@ -239,7 +298,7 @@ assembly("Door").addPart("Frame", frame).addPart("Door", door)
 | `align?` | `PortAlign` | Shorthand: set both parentAlign and childAlign at once. |
 | `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`.
+Also: `as?: string`, `type?: JointType`, `default?: number`, `unit?: string`, `effort?: number`, `velocity?: number`, `damping?: number`, `friction?: number`, `drive?: SimDriveDef`.
 
 **`JointFollowOptions`**
 - `joint: string` — Name of the source joint that drives this one.
@@ -312,6 +371,12 @@ return mech.solve({ theta: 45 });
 
 **Other**
 
+#### `withSimulation(options: SimAssemblySimulationOptions): Assembly` — Attach the root simulation contract for this 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.
+
+`SimAssemblySimulationOptions`: `{ profile: SimProfileDef, rootPart?: string, controllers?: SimControllerDef[] }`
+
 #### `edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly` — Add a visual skeleton edge between two rig frame origins.
 
 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.
@@ -447,7 +512,7 @@ The sub-assembly must have exactly one root part before it can be merged (collap
 | `connectorRefs?` | `JointConnectorRefs` | Connector refs that define this joint contract. Usually set by `connect()` / `match()`. |
 | `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`.
+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 }`
 

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

@@ -13,7 +13,7 @@ Every public API function belongs to one of 16 fundamental concepts. This is an
 - **[C7: Pattern Replication](#c7-pattern-replication)** — Duplicate geometry in regular arrangements (linear, circular, mirror). *(6 functions)*
 - **[C8: Constraint Solving](#c8-constraint-solving)** — Define geometry by relationships and let a solver find positions. *(1 functions)*
 - **[C9: Spatial Placement](#c9-spatial-placement)** — Position geometry relative to other geometry using semantic anchors. *(6 functions)*
-- **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(1 functions)*
+- **[C10: Assembly & Kinematics](#c10-assembly-kinematics)** — Compose parts with joints for kinematic simulation. *(15 functions)*
 - **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(6 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(15 functions)*
@@ -230,6 +230,20 @@ Position geometry relative to other geometry using semantic anchors.
 
 Compose parts with joints for kinematic simulation.
 
+- `Sim.material(name, options?)` — Create a named physical material with density and contact coefficients for simulation export and checks. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.body(options)` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.collider.convexHull()` — Use a generated collision mesh for the part. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.collider.boundingBox()` — Use the part bounding box as the collision geometry. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.collider.visualMesh()` — Use the visual mesh as collision geometry. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.collider.none(reason)` — Disable collision for a part with an explicit reason, such as a sensor-only or decorative object. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.drive.passive(options?)` — Mark a joint as passive while preserving damping and friction metadata for simulation export. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.drive.velocity(options)` — Mark a revolute joint as velocity-driven with torque and speed limits. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.contact.wheelSurface(connectorName)` — Mark a connector as the wheel tread contact surface for offline checks and downstream simulation metadata. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.contact.gripperSurface(connectorName)` — Mark a connector as a gripper pad/contact surface for offline checks and downstream grasp-readiness metadata. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.profile.robotBodyRunnable()` — SimReady-style profile for a robot body that should be runnable in a physics simulator. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.profile.robotBodyIsaac()` — SimReady-style profile for robot bodies targeting Isaac Sim readiness. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.profile.roboticsAssetPhysx()` — SimReady-style profile for robotics assets with PhysX-ready rigid bodies and colliders. → [assembly](/docs/assembly#assembly-joints)
+- `Sim.controller.diffDrive(options)` — Describe a differential-drive controller from left/right wheel joints and wheel dimensions. → [assembly](/docs/assembly#assembly-joints)
 - `assembly(name?)` — Create an assembly container with named parts, connectors, and kinematic links. → [assembly](/docs/assembly#assembly)
 
 ---
@@ -272,7 +286,7 @@ Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF).
 - `Laser.lookupKerf(material, thickness, laserType?)` — Look up kerf for a material + thickness + laser combo in `Laser.COMMON_KERFS`. → [sheet-metal](/docs/sheet-metal#laser)
 - `Laser.COMMON_KERFS` — Common full-kerf values by material, thickness, and laser type. → [sheet-metal](/docs/sheet-metal#laser)
 - `bom(quantity, description, opts?)` — Register a Bill of Materials entry for report export. → [output](/docs/output#bom)
-- `robotExport(options)` — Declare that this script should export the assembly as a SDF/URDF robot package. → [output](/docs/output#robotexport)
+- `robotExport(options)` — Compatibility shim for SDF/URDF robot package metadata. → [output](/docs/output#robotexport)
 - `sheetMetal(options)` — Create a parametric sheet metal part with flanges, bend allowances, and flat-pattern unfolding. → [sheet-metal](/docs/sheet-metal#sheetmetal)
 - `sketchToDxf(sketch, options?)` — Export a 2D sketch as a DXF string (R12/AC1009 — maximally compatible). → [output](/docs/output#sketchtodxf)
 - `sketchToSvg(sketch, options?)` — Export a 2D sketch as an SVG string. → [output](/docs/output#sketchtosvg)

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

@@ -111,6 +111,8 @@ The `edges` parameter is flexible:
 
 Throws if no edges match the selection, or if `radius` is not a positive finite number.
 
+Selectorless (all-edges) calls draw from a per-run broad edge-feature budget. Exceeding it throws — except in live preview, which skips the finish with a warning for responsiveness. Explicit edge selectors are never budgeted; `FORGECAD_BROAD_EDGE_FEATURE_BUDGET` / `FORGECAD_ALLOW_BROAD_EDGE_FEATURES=1` raise or lift the budget.
+
 ```ts
 // Fillet all edges
 fillet(myShape, 2)
@@ -133,6 +135,8 @@ fillet(base, 5, base.edge('vert-br'))
 
 Produces a 45° bevel at the specified `size` (distance from edge). Edge selections compile into backend operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
 
+Selectorless (all-edges) calls draw from a per-run broad edge-feature budget. Exceeding it throws — except in live preview, which skips the finish with a warning for responsiveness. Explicit edge selectors are never budgeted; `FORGECAD_BROAD_EDGE_FEATURE_BUDGET` / `FORGECAD_ALLOW_BROAD_EDGE_FEATURES=1` raise or lift the budget.
+
 The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, a tracked `EdgeRef` from `shape.edge('vert-br')` (exact compiler-owned path), or `undefined` (all sharp edges).
 
 ```ts
@@ -1406,15 +1410,18 @@ Namespaced file-format import helpers — the single vocabulary for bringing ext
 
 - `dxfSketch(fileName: string, options?: DxfImportOptions): Sketch` — Parse a DXF file and return closed 2D profile geometry as a Sketch. The result can be extruded directly.
 - `svgSketch(fileName: string, options?: SvgImportOptions): Sketch` — Parse an SVG file and return it as a Sketch with options for region filtering, scaling, and simplification.
-- `mesh(fileName: string, options?: { scale?: number; center?: boolean; object?: string; separateObjects?: boolean; }): Shape | ShapeGroup` — Import an external mesh file (STL, OBJ, 3MF).
+- `mesh(fileName: string, options?: MeshImportOptions): Shape | ShapeGroup` — Import an external mesh file (STL, OBJ, 3MF).
 
   By default, 3MF build items are flattened into one Shape for compatibility. Use `separateObjects: true` to import 3MF build items/resource objects as a named ShapeGroup whose children are targetable by `forgecad ls`. Use `object` to import one item by the stable ref/name reported by `forgecad run`.
 
   For 3MF sources, `forgecad run` prints a source-structure table with one line per build item: `[3mf:build:NNN:object:N] name type=... verts=... tris=... bbox=[min] → [max]`. Build items are numbered from `001`; files with no build items list resource objects as `3mf:object:N` instead. Per-item bboxes reveal multi-part structure — account for every substantial item before flattening. Pass any listed stable ref or name as `object` to import that item alone.
 
+  Use `sourceFrame: { up: "+Y" }` when the file was authored in a non-Z-up coordinate system. ForgeCAD remains Z-up; the import is rotated so the named source axis becomes ForgeCAD +Z. Supported values: `"+X"`, `"-X"`, `"+Y"`, `"-Y"`, `"+Z"`, `"-Z"`.
+
   ```js
   const all = Import.mesh("./assembly.3mf", { separateObjects: true });
   const pin = all.child("Pin #001");
   const plate = Import.mesh("./assembly.3mf", { object: "3mf:build:001:object:7" });
+  const yUpPart = Import.mesh("./part.obj", { sourceFrame: { up: "+Y" } });
   ```
-- `step(fileName: string): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend.
+- `step(fileName: string, options?: StepImportOptions): Shape` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires running with the OCCT backend. Use `sourceFrame: { up: "+Y" }` to rotate Y-up source files into ForgeCAD's Z-up world.

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

@@ -63,7 +63,7 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 
 Pre-built parametric parts available in user scripts as `lib.*`.
 
-Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts — see the member list below for the catalog. Sizes outside the supported ranges throw at runtime with a descriptive error.
+exposed to `.forge.js` scripts — see the member list below for the catalog. Sizes outside the supported ranges throw at runtime with a descriptive error.
 
 - `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink.
 

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

@@ -58,12 +58,14 @@ bom(tubeLen, "rectangular steel tube", {
 | `notes?` | `string` | Free-form notes |
 | `grain?` | `string` | Wood grain direction, e.g. "long", "cross" |
 
-#### `robotExport(options: RobotExportOptions): CollectedRobotExport` — Declare that this script should export the assembly as a SDF/URDF robot package.
+#### `robotExport(options: RobotExportOptions): CollectedRobotExport` — Compatibility shim for SDF/URDF robot package metadata.
 
-Call `robotExport()` alongside your assembly definition. `forgecad export sdf` / `forgecad export urdf` pick up the declaration (see the CLI docs for flags) and produce a robot package with:
+Prefer returning `assembly(...).withSimulation(...)` with `Sim.body(...)`, `Sim.drive.*(...)`, and `Sim.controller.*(...)` metadata. The CLI commands `forgecad export sdf` and `forgecad export urdf` now read that assembly simulation contract directly.
+
+`robotExport()` remains available for one compatibility window. It converts the legacy descriptor into the same internal simulation model used by source-authored `Sim` metadata and produces a robot package with:
 
 - Mesh-based inertia tensors (full 6-component, not bounding-box approximations)
-- Separate collision meshes (convex hull by default — ~50–80% smaller)
+- Separate collision meshes
 - Joint limits, effort/velocity/damping/friction metadata from assembly joints
 
 **Collision mesh modes** (set per-link via `links["PartName"].collision`):
@@ -82,6 +84,8 @@ Call `robotExport()` alongside your assembly definition. `forgecad export sdf` /
 - `massKg` is preferred; `densityKgM3` is used when mass is unknown.
 - 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.
 
+**Legacy example**
+
 ```ts
 robotExport({
   assembly: rover, // assembly() with parts + revolute wheel joints
@@ -97,6 +101,13 @@ robotExport({
 });
 ```
 
+**Preferred CLI usage**
+
+```bash
+forgecad export sdf model.forge.js   # SDF package (Gazebo/Ignition)
+forgecad export urdf model.forge.js  # URDF package (ROS/PyBullet/MuJoCo)
+```
+
 **`RobotExportOptions`**: `assembly: Assembly`, `modelName?: string`, `state?: JointState`, `static?: boolean`, `selfCollide?: boolean`, `allowAutoDisable?: boolean`, `links?: Record<string, RobotLinkExportOptions>`, `joints?: Record<string, RobotJointExportOptions>`, `plugins?: { diffDrive?: RobotDiffDrivePluginOptions; jointStatePublisher?: RobotJointStatePublisherOptions; }`, `world?: RobotWorldOptions`
 
 `RobotLinkExportOptions`: `{ massKg?: number, densityKgM3?: number, collision?: "visual" | "convex" | "box" | "none" }`
@@ -111,46 +122,6 @@ robotExport({
 
 `RobotWorldKeyboardTeleopOptions`: `{ enabled?: boolean, linearStep?: number, angularStep?: number }`
 
-**`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[]`, `kinematics: AssemblyKinematicGraphDef`, `frames: AssemblyFrameDef[]`, `frameJoints: AssemblyFrameJointDef[]`, `frameEdges: AssemblyFrameEdgeDef[]`
-
-**`AssemblyPartDef`**: `name: string`, `part: AssemblyPart`, `base: Transform`, `metadata?: PartMetadata`, `mates: AssemblyPartMateInput[]`, `bindToFrame?: string`
-
-`PartMetadata` — defined in [assembly](/docs/assembly).
-
-`AssemblyPartMateInput` — defined in [assembly](/docs/assembly).
-
-**`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` — defined in [assembly](/docs/assembly).
-
-`AssemblyJointCouplingDef`: `{ joint: string, terms: JointCouplingTermRecord[], offset: number }`
-
-`JointCouplingTermRecord`: `{ joint: string, ratio: number }`
-
-**`AssemblyKinematicGraphDef`**: `links: AssemblyLinkDef[]`, `edges: AssemblyEdgeBetweenLinksDef[]`, `angles: AssemblyAngleBetweenLinksDef[]`, `derivedLinks: AssemblyDerivedLinkDef[]`
-
-`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` — defined in [assembly](/docs/assembly).
-
-**`AssemblyAngleBetweenLinksDef`**: `name: string`, `a?: string`, `b: string`, `c: string`, `reference?: AssemblyAngleReferenceDef`, `target?: number`, `min?: number`, `max?: number`, `control?: AssemblyKinematicControlOptions`, `metadata?: Record<string, unknown>`
-
-`AssemblyAngleReferenceDef`: `{ kind: "worldDirection", direction: Vec3 }`
-
-**`AssemblyDerivedLinkDef`**
-- `distance: number` — Signed: positive moves from `fromLink` toward `towardLink`, negative moves away.
-- Also: `name: string`, `fromLink: string`, `towardLink: string`.
-
-`AssemblyFrameDef`: `{ name: string, origin: Vec3, axis: Vec3, up: Vec3, fixed: boolean, metadata?: Record<string, unknown> }`
-
-**`AssemblyFrameJointDef`**: `name: string`, `type: AssemblyFrameJointType`, `parent: string`, `child: string`, `rest: Transform`, `min?: number`, `max?: number`, `defaultValue: number`, `unit?: string`, `control: boolean`, `metadata?: Record<string, unknown>`
-
-`AssemblyFrameEdgeDef`: `{ name: string, a: string, b: string, metadata?: Record<string, unknown> }`
-
 #### `dim()` — Add a dimension annotation between two points, or along an entity.
 
 Overloads:

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

@@ -26,10 +26,10 @@ Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, P
 ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
 Rectangle2D, robotExport, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
 selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
-ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sketch, sketchToDxf, sketchToSvg, slot
-SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
-sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, torus, toShape, Transform, union
+union2d, variableSweep, verify, Viewport, window, Wood
 ```
 
 <!-- forgecad-skill:exclude-start symbol="compatibility runtime names" reason="Compatibility-only renamed runtime globals." -->

package/dist/docs-raw/guides/simready-quickstart.md

@@ -0,0 +1,171 @@
+# SimReady Quickstart
+
+ForgeCAD simulation readiness starts in the model file. The `.forge.js` script should return the same assembly you want to inspect, export, and simulate; simulation metadata lives on that assembly instead of in a separate export command.
+
+Use this pattern when you want a robot, fixture, gripper, crate, or imported asset to become a physics package later:
+
+1. Build real parts with connectors.
+2. Add each part to an `assembly(...)` with `sim: Sim.body(...)`.
+3. Connect moving parts with `connect(...)` and put drive intent on the joint.
+4. Finish the root assembly with `withSimulation(...)`.
+5. Run `forgecad check simready` before exporting.
+
+## Robot Pattern
+
+```js
+const aluminum = Sim.material("6061 aluminum", {
+  densityKgM3: 2700,
+  staticFriction: 0.45,
+  dynamicFriction: 0.35,
+  restitution: 0.05,
+});
+
+const rubber = Sim.material("rubber tire", {
+  densityKgM3: 1100,
+  staticFriction: 0.9,
+  dynamicFriction: 0.75,
+  restitution: 0.12,
+});
+
+const chassis = box(220, 120, 28).withConnectors({
+  left_axle: connector({ origin: [0, 82, 0], axis: [0, 1, 0], up: [0, 0, 1], kind: "revolute" }),
+  right_axle: connector({ origin: [0, -82, 0], axis: [0, -1, 0], up: [0, 0, 1], kind: "revolute" }),
+});
+
+const wheel = cylinder(34, 28, undefined, 48)
+  .rotateX(90)
+  .withConnectors({
+    bore: connector({ origin: [0, 0, 0], axis: [0, 1, 0], up: [0, 0, 1], kind: "revolute" }),
+    tread: connector({ origin: [0, 0, -34], axis: [0, 0, -1], up: [1, 0, 0] }),
+  });
+
+return assembly("Rover")
+  .addPart("Chassis", chassis, {
+    sim: Sim.body({
+      massKg: 4.2,
+      material: aluminum,
+      collider: Sim.collider.boundingBox(),
+    }),
+  })
+  .addPart("Left Wheel", wheel, {
+    sim: Sim.body({
+      massKg: 0.32,
+      material: rubber,
+      collider: Sim.collider.convexHull(),
+      contacts: { tread: Sim.contact.wheelSurface("tread") },
+    }),
+  })
+  .addPart("Right Wheel", wheel, {
+    sim: Sim.body({
+      massKg: 0.32,
+      material: rubber,
+      collider: Sim.collider.convexHull(),
+      contacts: { tread: Sim.contact.wheelSurface("tread") },
+    }),
+  })
+  .connect("Chassis.left_axle", "Left Wheel.bore", {
+    as: "leftWheel",
+    type: "revolute",
+    drive: Sim.drive.velocity({ maxTorqueNm: 1.8, maxSpeedRpm: 220, damping: 0.02, friction: 0.01 }),
+  })
+  .connect("Chassis.right_axle", "Right Wheel.bore", {
+    as: "rightWheel",
+    type: "revolute",
+    drive: Sim.drive.velocity({ maxTorqueNm: 1.8, maxSpeedRpm: 220, damping: 0.02, friction: 0.01 }),
+  })
+  .withSimulation({
+    rootPart: "Chassis",
+    profile: Sim.profile.robotBodyRunnable(),
+    controllers: [
+      Sim.controller.diffDrive({
+        leftJoints: ["leftWheel"],
+        rightJoints: ["rightWheel"],
+        wheelRadiusMm: 34,
+        wheelSeparationMm: 164,
+      }),
+    ],
+  });
+```
+
+The important names are authored once:
+
+- `rootPart` names the body that downstream simulators treat as the robot root.
+- `leftWheel` and `rightWheel` are joint names, so controllers and exporters do not need to guess motor wiring.
+- `tread` is an existing connector on the wheel, so contact metadata is checked against geometry-owned names.
+
+## Asset Pattern
+
+Assets use the same assembly contract. In V1, a crate, prop, imported STEP, or static environment object is usually a one-part assembly:
+
+```js
+const pine = Sim.material("pine crate", {
+  densityKgM3: 520,
+  staticFriction: 0.55,
+  dynamicFriction: 0.42,
+  restitution: 0.08,
+});
+
+const crate = box(140, 110, 80).withConnectors({
+  grip: connector({ origin: [0, -56, 8], axis: [0, -1, 0], up: [0, 0, 1] }),
+});
+
+return assembly("Crate Asset")
+  .addPart("Body", crate, {
+    sim: Sim.body({
+      massKg: 2.4,
+      material: pine,
+      collider: Sim.collider.convexHull(),
+      contacts: { grip: Sim.contact.gripperSurface("grip") },
+    }),
+  })
+  .withSimulation({
+    profile: Sim.profile.roboticsAssetPhysx(),
+  });
+```
+
+Asset profiles require physical body metadata and explicit collider intent. They do not require `rootPart`, joints, or controllers.
+
+## Check Then Export
+
+Run the offline gate first:
+
+```bash
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+```
+
+Then export the package that matches your simulator:
+
+```bash
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-mjcf
+node dist-cli/forgecad.js export sdf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-sdf
+node dist-cli/forgecad.js export urdf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/rover-urdf
+```
+
+Use MJCF/MuJoCo for the fastest local physics loop. Use SDF for Gazebo Sim. Use URDF when the next tool expects a ROS/PyBullet/Isaac import path.
+
+ForgeCAD does not currently have a native USD/USDZ export command. For Isaac workflows today, export URDF as the import artifact and carry the richer ForgeCAD simulation intent through `simready-manifest.json`. A future USD exporter should consume the same source-level simulation contract instead of re-inferring physics metadata from mesh geometry.
+
+Every package includes `simready-manifest.json`. That manifest is the neutral handoff: model name, units, profile, bodies, joints, drives, controllers, contacts, and validation results.
+
+## What The Check Catches
+
+`forgecad check simready` is source-level validation. It does not need Isaac Sim, OpenUSD, `pxr`, MuJoCo, or NVIDIA validators installed.
+
+It fails when:
+
+- the returned model has no `withSimulation(...)` contract
+- a physical part is missing `Sim.body(...)`
+- mass, density, friction, restitution, torque, speed, damping, or world pose values are non-finite or invalid
+- a collider is missing for profiles that require explicit collision intent
+- `Sim.collider.none(...)` has no reason
+- a contact surface names a missing connector
+- a controller names an unknown or wrong-type joint
+- a robot profile has no `rootPart`, an unknown `rootPart`, or a disconnected joint graph
+
+It intentionally treats joint-connected bodies as connected. A robot with separated wheels, arms, or gripper fingers should pass when the articulated graph is valid.
+
+## Where Control Code Lives
+
+ForgeCAD owns geometry, physical metadata, joints, drives, controllers, manifests, and starter simulator packages. It should not own a single blessed balance controller, reward function, or RL library.
+
+For a runnable training loop, export MJCF and use the generated package scripts. The Scout Cam Rover example includes `gym_env.py`, `train_balance.py`, `train_sb3.py`, `play_balance.py`, and `live_policy_viewer.py`; see [Simulation Workflow](../simulation-workflow.md) for the full MuJoCo and Isaac Lab path.