forgecad 0.10.0 → 0.10.2

package/dist-skill/docs/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>
@@ -76,7 +78,7 @@ Direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` inputs are imported automatically; ST
 
 ```bash
 forgecad run model.forge.js
-forgecad run model.forge.js --details --history
+forgecad run model.forge.js other-model.forge.js --quality live
 ```
 
 ### `forgecad ls`
@@ -102,7 +104,7 @@ Without a target, `show` renders the whole scene and behaves like a shorter, int
 
 ```bash
 forgecad show model.forge.js
-forgecad show model.forge.js Bench
+forgecad show model.forge.js --target Bench
 ```
 
 ### Object Filtering: `--focus` and `--hide`
@@ -110,7 +112,7 @@ forgecad show model.forge.js Bench
 `render 3d`, `render wireframe`, `inspect <family> <mode>`, `capture`, and `check print` can filter the visible object set without changing model code. Use `forgecad ls model.forge.js` to list exact object paths, then pass names or globs:
 
 ```bash
-forgecad render 3d model.forge.js bench.png --focus "Bench.*"
+forgecad render 3d model.forge.js --output bench.png --focus "Bench.*"
 forgecad inspect visual objects model.forge.js --hide "Bench.Slat0,Bench.Slat1" --camera iso
 ```
 
@@ -198,7 +200,7 @@ Runs the script headlessly and prints every named render view with an exact came
 
 ```bash
 forgecad render views model.forge.js
-forgecad render views model.forge.js --json
+forgecad render views model.forge.js reference.step
 ```
 
 ### `forgecad render wireframe`
@@ -222,7 +224,7 @@ Exports the scene to Blender and renders with Cycles (path tracer); requires Ble
 
 ```bash
 forgecad render hq model.forge.js
-forgecad render hq model.forge.js hero.png --preset dramatic --samples 1024
+forgecad render hq model.forge.js --output hero.png --preset dramatic --samples 1024
 ```
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
@@ -233,18 +235,22 @@ Renders an animated sequence: `--capture orbit` (default) for a turntable, `--ca
 
 ```bash
 forgecad capture gif model.forge.js
-forgecad capture gif model.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
+forgecad capture gif model.forge.js other-model.forge.js
 ```
 
 ### `forgecad render section`
 
 Render a 2D cross-section of a 3D model (cut by a plane) to SVG or PNG.
 
-Cuts all shapes with an axis-aligned plane (default XY at Z=0; `--plane XZ|YZ` reorients, `--offset` shifts the cut) and writes a 2D cross-section drawing. The file extension picks the format: `.svg` (default, vector) or `.png` (rasterized at `--size` pixels); `--edges=<off|thin|bold>` sets the outline stroke. Useful for verifying internal geometry, wall thicknesses, and fits that aren't visible in 3D renders.
+Cuts all shapes in the scene with an axis-aligned plane and produces a 2D cross-section drawing. The default plane is XY at Z=0. Use `--plane XZ` or `--plane YZ` for other orientations, and `--offset` to shift the cut position.
+
+Output defaults to `.svg`; pass `--format png` or a single-input `--output *.png` path for a rasterized PNG at `--size` pixels. Use `--edges=<off|thin|bold>` to control the outline stroke on cut shapes.
+
+Useful for verifying internal geometry, wall thicknesses, and fit checks that aren't visible in 3D renders.
 
 ```bash
 forgecad render section model.forge.js
-forgecad render section model.forge.js out/section.svg --plane XZ --offset 10
+forgecad render section model.forge.js --output out/section.svg --plane XZ --offset 10
 ```
 
 | Command | Description |
@@ -270,8 +276,8 @@ These flags work across run / render / capture / inspect commands:
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
 | `--view <name>` | Named camera view declared by the model with scene({ views }) |
 | `--size <px>` | Image size in pixels |
+| `--backend <manifold\|occt\|truck\|sdf>` | Geometry backend (default: manifold; STEP inputs default to OCCT) |
 | `--quality <default\|live\|high>` | Mesh quality preset |
-| `--backend <manifold\|occt\|truck>` | Geometry backend (default: manifold; STEP inputs default to OCCT) |
 | `--json` | Print machine-readable JSON |
 
 Every command has more — Blender-only `render hq` flags (`--preset`, `--samples`, `--engine`, `--hdri`, `--transparent`, `--video`) and capture-only flags (`--capture`, `--animation`, `--cut-plane`, `--sweep-*`, `--fps`) among them. Run `forgecad <command> --help` for the full list.
@@ -291,7 +297,9 @@ 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 usd` **\[Production\]** | USD package | Isaac Sim / OpenUSD simulation |
 | `export report` **\[Production\]** | PDF report | Multi-view report with BOM and dimensions |
 | `export cutting-layout` **\[Production\]** | PDF/DXF | Sheet cutting layout with cut sequence |
 | `link` | URL | Share link from a GitHub Gist URL or ID (copied to clipboard) |
@@ -300,6 +308,7 @@ Export to every format you need.
 # Sheet material
 forgecad cut-list shelf.forge.js
 forgecad export cutting-layout shelf.forge.js --sheet-width 420 --sheet-height 594 --kerf 3
+forgecad export cutting-layout shelf.forge.js --output out/layout.dxf
 
 # 3D printing
 forgecad check print bracket.forge.js
@@ -310,10 +319,12 @@ forgecad export 3mf bracket.forge.js --quality high
 forgecad export step bracket.forge.js
 
 # Technical drawings
-forgecad export report bracket.forge.js out/report.pdf
+forgecad export report bracket.forge.js --output 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
+forgecad export usd rover.forge.js --output out/forge_scout_usd
 ```
 
 <details>
@@ -322,12 +333,17 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 | Option | Description |
 |--------|-------------|
 | `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
-| `--output <path>` | Output STEP path |
+| `--output <path>` | Output SVG path for a single input |
 | `--backend <occt\|truck>` | Exact BREP exporter: occt (default) or truck (native analytic kernel) |
 | `--quality <default\|live\|high>` | Forge quality preset |
 | `-o <path>` | Shorthand for --output |
+| `--param <Key=Value>` | Override a parameter value (Key=Value). Repeatable. |
+| `-p <Key=Value>` | Shorthand for --param |
+| `--format <json\|webgpu-brick>` | Implicit artifact format |
+| `-q <live\|default\|high>` | Shorthand for --quality |
+| `--workgroup-size <x>x<y>x<z>` | WebGPU compute workgroup size |
 | `--dim-angle-tol <deg>` | Dimension routing tolerance in degrees |
-| `--format <pdf\|dxf>` | Output format |
+| `--out <path>` | Alias for --output |
 | `--sheet-width <mm>` | Stock sheet width in mm |
 | `--sheet-height <mm>` | Stock sheet height in mm |
 | `--kerf <mm>` | Cutting clearance (saw blade width) in mm |
@@ -451,7 +467,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`
 
@@ -474,7 +490,18 @@ Checks include script `verify.*` results, exact positive-volume object collision
 
 ```bash
 forgecad check print model.forge.js
-forgecad check print model.forge.js --json
+forgecad check print model.forge.js other-model.forge.js
+```
+
+### `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 model.forge.js other-model.forge.js
 ```
 
 ### `forgecad inspect mechanical-integrity`
@@ -514,7 +541,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 implicit`, `export sdf`, `export mjcf`, `export urdf`, `export usd`, `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-skill/docs/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,59 @@ 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 +204,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 +265,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 +294,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.
@@ -299,6 +354,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.
@@ -434,7 +495,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 }`
 
@@ -506,4 +567,4 @@ console.log("Collisions", solved.collisionReport());
 
 #### `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.
+Returns `0` if the parts are touching or overlapping. Manifold-backed parts use the exact Manifold gap query. SDF-backed parts use a mesh-derived sampled gap. `searchLength` bounds the Manifold search radius in mm — increase it for widely separated Manifold parts.

package/dist-skill/docs/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
@@ -151,7 +155,7 @@ chamfer(base, 3, base.edge('vert-br'))
 
 Adds a taper angle to the vertical faces of a solid so that it can be extracted from a mold. The neutral plane is the Z position where the draft angle is zero — faces above and below are tapered symmetrically. Typical values for injection molding are 1–5°.
 
-Truck supports vertical-prism solids with Z-axis pull directions. OCCT uses its native draft operation when available. Manifold throws.
+SDF, Manifold, and Truck lower supported vertical-prism solids with Z-axis pull directions to a tapered loft. OCCT uses its native draft operation when available.
 
 ```ts
 // Add 3° draft to a box for injection molding
@@ -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-skill/docs/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-skill/docs/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
 ```
 
 `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

@@ -53,7 +53,7 @@ An immutable SDF expression. Supports SDF-specific operations (smooth booleans,
 
 #### `clone(): SdfShape` — Clone this SDF expression and its visual metadata.
 
-#### `toShape(options?: SdfToShapeOptions): Shape` — Mesh this SDF into a ForgeCAD Shape through ForgeCAD's Surface Nets pipeline. Once converted, the result is a regular Shape — booleans, transforms, export all work.
+#### `toShape(options?: SdfToShapeOptions): Shape` — Mesh this SDF into a ForgeCAD Shape. Typed SDF trees materialize through Rust Manifold Dual Contouring; dynamic trees (custom/noise/voronoi/displace/blend callbacks) mesh through the Surface Nets pipeline. Once converted, the result is a regular Shape — booleans, transforms, export all work.
 
 #### `color(value: string | undefined): SdfShape` — Set the display color for this implicit leaf.
 
@@ -230,7 +230,7 @@ return {
 - `basketWeave(options?: BasketWeaveOptions): SurfacePattern` — Basket weave surface pattern — threads with over-under crossings in UV space. Returns a SurfacePattern for use with `.surfaceDisplace()`.
 - `pattern2d(): Pattern2DBuilder` — Create typed, composable 2D surface patterns for `.surfaceDisplace()`.
 - `SurfacePattern: typeof SurfacePattern` — A 2D surface pattern — a heightmap function for use with `.surfaceDisplace()`.
-- `fromFunction(fn: SdfFunctionSource, options: SdfFunctionOptions): SdfShape` — Create a custom SDF from one expression; shader-safe expressions raymarch directly.
+- `fromFunction(fn: SdfFunctionSource, options: SdfFunctionOptions): SdfShape` — Create a custom SDF from one expression; shader-safe expressions keep shader metadata for tooling.
 - `combine(value: unknown, options?: CombineOptions): SdfShape` — Collapse a plain object/array tree of SDF leaves into one continuous implicit field. Per-leaf color/material identity is intentionally discarded — the result is one scalar field. Use plain object returns for multi-material SDF preview, and `sdf.combine(...)` only when you want one implicit body. Explicit shape lists are covered by `a.union(b, c)`; pass `{ op: 'intersection' }` to intersect instead.
 
   ```js

package/examples/api/gyroid-voronoi-blend.forge.js

@@ -1,5 +1,5 @@
 // Gyroid-diamond blend — shader-compatible TPMS fields combined in one form.
-// Return the raw SDF for fast native preview; use toShape(...) when exporting.
+// Return the SDF directly for implicit preview data; use toShape(...) for export tuning.
 
 const bounds = sdf.sphere(22);
 const gyroid = sdf.gyroid({ cellSize: 10, thickness: 1.0 });

package/examples/api/organic-noise-sculpture.forge.js

@@ -1,5 +1,5 @@
 // Organic noise sculpture — natural, coral-like form
-// Noise is still materialized because native preview does not raymarch it yet.
+// Explicit meshing keeps the noisy field on the ordinary mesh preview/export path.
 
 const shell = sdf.sphere(20).shell(4);
 const texture = sdf.noise({ scale: 0.15, amplitude: 3, octaves: 3 });

package/examples/api/sdf-circular-array-knurling.forge.js

@@ -16,4 +16,4 @@ const leftHandGroove = sdf.box(2.4, 1.2, 48)
 return body
   .subtract(rightHandGroove, leftHandGroove)
   .color('#8da2ad')
-  .material({ roughness: 0.38, metalness: 0.18 });
+  .material({ roughness: 0.38, metalness: 0.18 }).toShape({edgeLength: 0.2});

package/examples/api/{sdf-custom-raymarch.forge.js → sdf-custom-field-mesh-preview.forge.js}

@@ -1,8 +1,7 @@
-// Custom SDF native preview — one user-authored expression drives CPU sampling
-// and, when shader-safe, native raymarch preview.
+// Custom SDF implicit preview — one user-authored expression drives the field.
 //
-// This returns a raw SdfShape. Do not call .toShape() here; keeping it implicit
-// proves the custom function can preview through the raymarch shader.
+// Returning SdfShape directly keeps the field implicit. Call .toShape(...) when
+// you need explicit mesh quality for CAD operations or export.
 
 const rippledSphere = sdf.fromFunction(
   (x, y, z, radius, frequency, amplitude) =>

package/examples/api/sdf-materialize-tree.forge.js

@@ -1,4 +1,4 @@
-// Materialize a raw SDF tree when you need mesh-backed CAD/export behavior.
+// Return a plain SDF tree; scene mapping keeps SDF leaves implicit.
 
 const insert = {
   shell: sdf.sphere(18)
@@ -9,4 +9,4 @@ const insert = {
     .color('#ffcf5a'),
 };
 
-return insert;
+return insert;

package/examples/api/sdf-plain-return.forge.js

@@ -1,6 +1,7 @@
-// Plain raw SDF return: no Shape, no .toShape(), no Sculpt facade.
+// Plain SDF return: no explicit Shape, no .toShape(), no Sculpt facade.
 //
-// This should render directly in Studio and the CLI.
+// Direct returns stay as implicit SDF preview data; call .toShape() when you
+// need a mesh-backed Shape for CAD operations or export.
 
 scene(Sculpt.look('soft-studio'));
 

package/examples/api/sdf-shapes.forge.js

@@ -1,6 +1,6 @@
-// SDF native preview — raw SDF leaves render directly by raymarching.
+// SDF implicit preview — SDF leaves stay lazy until .toShape(...).
 //
-// Use .toShape() only when you need mesh-backed CAD operations or export.
+// Use .toShape(...) when you need explicit meshing controls, CAD operations, or export.
 
 const smoothBlob = sdf.smoothUnion(
   sdf.sphere(12),

package/examples/api/sdf-surface-basket-weave.forge.js

@@ -1,5 +1,5 @@
-// Native SDF surface relief — user-composed Pattern2D IR lowers to shader + CPU.
-// These raw SDF leaves raymarch directly; call .toShape() only for export.
+// Native SDF surface relief — user-composed Pattern2D IR lowers to CPU sampling.
+// Direct SDF returns stay implicit; call .toShape(...) for mesh-backed export.
 
 scene({
   background: { top: '#f6fbff', bottom: '#dfe9f3' },

package/examples/generative/twisted-lattice-tower.forge.js

@@ -1,4 +1,4 @@
-// Twisted lattice tower — gyroid field raymarched directly in the viewport.
+// Twisted lattice tower — direct SDF return materializes as a mesh-backed preview.
 
 const column = sdf.cylinder(54, 13);
 

package/examples/generative/voronoi-lampshade.forge.js

@@ -1,5 +1,5 @@
 // Voronoi lampshade — organic cell-wall dome, open at the bottom.
-// Voronoi is still materialized because native preview does not raymarch it yet.
+// Explicit meshing keeps this dense field on the ordinary mesh preview/export path.
 
 const dome = sdf.sphere(30)
   .subtract(sdf.sphere(27))

package/examples/robotics/README.md

@@ -0,0 +1,46 @@
+# Robotics And SimReady Examples
+
+These examples show the current ForgeCAD simulation contract: physical parts use `Sim.body(...)`, joints carry drive intent, and the returned assembly finishes with `withSimulation(...)`.
+
+Run commands from the ForgeCAD repo root with the local CLI:
+
+```bash
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/forgecad-rover-mjcf
+```
+
+## Examples
+
+| Example | File | What It Proves |
+|---------|------|----------------|
+| Diff-drive rover | `simready-diff-drive-rover.forge.js` | Robot-body profile, wheel contact surfaces, velocity drives, and diff-drive controller metadata |
+| Parallel gripper | `simready-parallel-gripper.forge.js` | Prismatic joints, passive dynamics, and gripper contact-surface metadata |
+| Asset crate | `simready-asset-crate.forge.js` | One-part asset assembly with physical material, collider, and grasp-ready contact metadata |
+| Scout cam rover | `scout-cam-rover-simready/main.forge.js` | Larger copied robot with MJCF, SDF, URDF, MuJoCo smoke motion, starter Gym env, balance training, and push playback |
+
+## Minimum Workflow
+
+```bash
+node dist-cli/forgecad.js run examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js check simready examples/robotics/simready-diff-drive-rover.forge.js
+node dist-cli/forgecad.js export mjcf examples/robotics/simready-diff-drive-rover.forge.js --output /tmp/forgecad-rover-mjcf
+```
+
+The MJCF export writes a runnable MuJoCo package with `scene.xml`, `manifest.json`, `simready-manifest.json`, and starter Python scripts.
+
+```bash
+cd /tmp/forgecad-rover-mjcf
+uv run --python 3.11 --with mujoco --with pillow python scripts/smoke_control.py --render-gif drive.gif
+```
+
+The smaller examples are meant to be readable API references. The Scout example is the end-to-end simulator workflow.
+
+## Picking The Right Example
+
+Use `simready-diff-drive-rover.forge.js` when you want the smallest robot that proves the full controller/export path.
+
+Use `simready-parallel-gripper.forge.js` when you care about manipulators, fingertips, or grasp-readiness metadata.
+
+Use `simready-asset-crate.forge.js` when the object is not a robot but still needs physical material, collision, and contact metadata.
+
+Use `scout-cam-rover-simready/` when you want MuJoCo scripts, generated package structure, GIF output, and a realistic source-authored robot example.