forgecad 0.6.3 → 0.7.0

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

@@ -5,206 +5,147 @@ skill-order: 3
 
 # Positioning Strategy
 
-**This is the most important page for building multi-part assemblies.** Most positioning bugs come from manual coordinate arithmetic. Use the methods below in priority order.
+## Primitive origin convention
 
-## Priority Order
+All 3D primitives are **centered on XY, base at Z=0**:
 
-### 1. Connectors + `matchTo()` — Default choice for multi-part positioning
+| Primitive | X range | Y range | Z range |
+|-----------|---------|---------|---------|
+| `box(60, 40, 20)` | [-30, 30] | [-20, 20] | [0, 20] |
+| `cylinder(50, 10)` | [-10, 10] | [-10, 10] | [0, 50] |
+| `sphere(15)` | [-15, 15] | [-15, 15] | [-15, 15] |
+| `torus(20, 5)` | [-25, 25] | [-25, 25] | [-5, 5] |
 
-Define connectors on parts, then use `matchTo()` for automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's connector — origins coincide, axes oppose (plug-in model).
+Sphere and torus are fully centered (symmetric in Z). Box and cylinder sit on the XY ground plane — **Z goes up from zero, never negative**.
 
-```javascript
-// Define connectors on parts
-const shelf = box(200, 120, 10, true).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
-  right_tab: connector.male("dovetail", { origin: [100, 0, 0], axis: [1, 0, 0] }),
-});
+This means `box(w, d, h).translate(0, 0, -h/2)` is wrong for "center on Z" — the box is already at `[0, h]`, not `[-h/2, h/2]`.
 
-const panel = box(12, 120, 200, true).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
-  shelf_1: connector.female("dovetail", { origin: [6, 0, 50], axis: [1, 0, 0] }),
-});
-
-// Single pair: "put my left_tab into panel's shelf_0"
-const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
+---
 
-// Dictionary syntax for multiple pairs (same target):
-const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
+Most positioning bugs come from manual coordinate arithmetic. Use these methods in priority order.
 
-// Named group children auto-bubble connectors via dotted paths:
-const cabinet = group({ name: "Left", shape: panel });
-shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
-```
+## 1. `group()` — local coordinates for multi-part assemblies
 
-**Why connectors first:**
-- **Stable.** Connector positions are authored explicitly — they don't shift when you fillet, chamfer, or boolean the part.
-- **Semantic.** Connectors carry type and gender — `assembly.match()` validates compatibility before connecting.
-- **Oriented.** Full coordinate frame (origin + axis + up), not just a point.
-- **Queryable.** `shape.connectorDistance('a', 'b')` lets you derive dimensions from connector positions — e.g. compute pipe length from the distance between two fittings.
-- **Explode-aware.** Matched parts automatically separate along connector axes when the explode slider is used.
+The most common positioning bug: manually adding a parent's global offset to every sub-part. One wrong sign or forgotten variable and parts float into space. **Use `group()` to build parts in local coordinates (at the origin), then position the group once.**
 
-**Connector patterns:**
 ```javascript
-// Pipe length derived from connector spacing
-const length = frame.connectorDistance('inlet', 'outlet');
-const pipe = cylinder(length, radius);
-
-// Assembly-level connector matching with joint creation
-assembly
-  .addPart("Frame", frame)
-  .addPart("Door", door)
-  .match("Door", "Frame", { hinge_top: "hinge_top", hinge_bottom: "hinge_bottom" });
-
-// Query connector metadata
-const measurements = fitting.connectorMeasurements('flange');
-const outerDiam = measurements.outerDiameter;
+// BAD — every sub-part repeats the parent's global position
+const unitY = -18, unitZ = 70;
+const body = lib.roundedBox(100, 20, 32, 4).translate(0, unitY, unitZ);
+const panel = box(98, 2, 18).translate(0, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(0, unitY - 14, unitZ - 11);
+const led = sphere(1.2).translate(35, unitY - 12, unitZ + 9);
+
+// GOOD — build at local origin, group, translate once
+const body = lib.roundedBox(100, 20, 32, 4);
+const panel = box(98, 2, 18).translate(0, -12, 4);        // relative to local origin
+const louver = box(88, 2, 6).translate(0, -14, -11);      // relative to local origin
+const led = sphere(1.2).translate(35, -12, 9);             // relative to local origin
+const indoorUnit = group(
+  { name: 'Body', shape: body },
+  { name: 'Panel', shape: panel },
+  { name: 'Louver', shape: louver },
+  { name: 'LED', shape: led },
+).translate(0, -18, 70);  // ONE translate for the whole assembly
 ```
 
-### 2. `pointAlong()` — Orient cylinders/extrusions before positioning
-
-Cylinders default to Z-up. Instead of `rotate(90, 0, 0)` (which is confusing), use `pointAlong()`:
+**Groups nest.** Build sub-assemblies as groups, then group those into larger assemblies — each level has its own local origin.
 
 ```javascript
-// Pipe running along Y axis
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]);
-
-// Axle along X
-const axle = cylinder(80, 3).pointAlong([1, 0, 0]);
+const fan = group(hub, ...blades).translate(0, 25, 0);  // fan assembly
+const outdoorUnit = group(
+  { name: 'Body', shape: casing },
+  { name: 'Fan', shape: fan },             // already a group
+  { name: 'Grille', shape: grille },
+).translate(0, 23, -42);                    // position the whole outdoor unit
 ```
 
-**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
+**When to use something else:** `group()` preserves individual shapes — you can't boolean (subtract/intersect) a group. If a sub-part needs a boolean with the parent body, do that boolean first in local coordinates, then group the result.
 
-### 3. `attachTo()` — Quick bounding-box positioning
+## 2. Connectors + `matchTo()` — default for mating interfaces
 
-For simple "stack this on that" placement where you don't need connectors. Uses bounding-box anchor points — fast to write but fragile if geometry changes.
+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).
 
 ```javascript
-const base = box(100, 100, 10);
-const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
+const shelf = box(200, 120, 10, true).withConnectors({
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+});
+const panel = box(12, 120, 200, true).withConnectors({
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+});
+const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
+// Dictionary form for multiple pairs on same target:
+const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
+// Named group children bubble connectors via dotted paths:
+const cabinet = group({ name: "Left", shape: panel });
+shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
 ```
 
-`child.attachTo(parent, parentAnchor, selfAnchor, offset)` — parentAnchor/selfAnchor are bounding-box anchors like `'top'`, `'bottom-front-left'`, etc.
-
-**Limitations:** Anchor points are derived from the bounding box, so they shift when you fillet, chamfer, or boolean the part. No orientation, no validation, no semantic meaning. Prefer connectors for anything beyond quick prototyping.
-
-### 5. `rotateAroundTo()` — Aim a point around a hinge/axis
+**Why connectors first:** stable (don't shift on fillet/chamfer/boolean), semantic (carry type/gender), oriented (full frame), queryable (`shape.connectorDistance('a','b')`), explode-aware.
 
-Use this when a part already has the correct pivot/axis, and you want to solve the angle from geometry instead of doing trig by hand.
+## 3. `pointAlong()` — orient cylinders before positioning
 
 ```javascript
-const arm = box(80, 8, 8, true)
-  .translate(40, 0, 0)
-  .withReferences({ points: { tip: [80, 0, 0] } });
-
-// Rotate around Z until the tip lies in the plane formed by the Z axis and the target point
-const aimed = arm.rotateAroundTo(
-  [0, 0, 1],
-  [0, 0, 0],
-  "tip",
-  [30, 30, 20],
-);
-
-// Exact line solve: throws if the target line is unreachable while preserving radius about the axis
-const lineHit = arm.rotateAroundTo(
-  [0, 0, 1],
-  [0, 0, 0],
-  "tip",
-  [30, 30, 0],
-  { mode: 'line' },
-);
+// BAD
+const pipe = cylinder(100, 5).rotateX(90).translate(x, y, z);
+// GOOD — reads as "pipe pointing along Y"
+const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
 ```
 
-### 6. `moveToLocal()` — Position relative to another shape's corner
+**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
 
-When you need to place something at a specific offset from another shape's bounding box origin (min corner):
+## 4. `attachTo()` — quick bounding-box positioning
 
 ```javascript
-const base = box(100, 100, 10);
-const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
+const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
 ```
 
-### 7. `translate()` — Only for simple offsets or connecting independently-positioned parts
+`child.attachTo(parent, parentAnchor, selfAnchor, offset)`. Anchor points shift on fillet/chamfer/boolean — fragile for assembly interfaces, fine for quick prototyping.
 
-Use `translate()` when:
-- Moving a shape by a known fixed amount
-- Positioning between two shapes whose locations you've already computed via `boundingBox()`
+## 5. `rotateAroundTo()` — aim a point around a hinge/axis
 
 ```javascript
-// Pipe spanning between two independently-positioned units
-const bb1 = indoor.boundingBox();
-const bb2 = outdoor.boundingBox();
-const pipeLen = bb2.min[1] - bb1.max[1];
-const pipe = cylinder(pipeLen, 5)
-  .pointAlong([0, 1, 0])
-  .translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
+const aimed = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 20]);
+// Exact line solve:
+const lineHit = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 0], { mode: 'line' });
 ```
 
-### 8. `placeReference()` / named import references — For reusable multi-file parts
-
-When a part will be imported elsewhere, define semantic placement references once in the source file:
+## 6. `moveToLocal()` — offset from another shape's min corner
 
 ```javascript
-// widget.forge.js
-return union(base, post).withReferences({
-  points: {
-    mount: [0, -16, -4],
-  },
-  objects: {
-    post,
-  },
-});
+const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
 ```
 
-Then consume them in the importing file:
+## 7. `translate()` — for simple offsets or bridging computed locations
 
 ```javascript
-const widget = require("./widget.forge.js")
-  .placeReference("mount", [120, 40, 0]);
+const pipeLen = bb2.min[1] - bb1.max[1];
+const pipe = cylinder(pipeLen, 5).pointAlong([0, 1, 0]).translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
 ```
 
-Use this when manual coordinate math starts to feel like assembly bookkeeping. For cross-file parts that need proper alignment, prefer connectors on the exported shape over placement references.
+## 8. `placeReference()` — align any anchor to a world coordinate
 
-## Common Mistakes
+Place a shape so a named anchor point lands exactly where you want it. Accepts all built-in anchors (`'bottom'`, `'center'`, `'top-front-left'`, etc.) plus custom references from `withReferences()`.
 
-### ❌ Manual center-offset math
 ```javascript
-// BAD: easy to get wrong, hard to read
-const child = box(w, d, h, true)
-  .translate(0, -parentThickness/2 - d/2 - 5, parentHeight/2 - h/2 - 20);
-```
+// Ground a shape — bottom face center at Z = 0
+const grounded = shape.placeReference('bottom', [0, 0, 0])
 
-### ✅ Connector-based positioning
-```javascript
-// GOOD: stable, semantic, self-documenting
-const parent = box(100, 40, 60, true).withConnectors({
-  mount: connector.female("bracket", { origin: [0, -20, 10], axis: [0, -1, 0] }),
-});
-const child = box(w, d, h, true).withConnectors({
-  tab: connector.male("bracket", { origin: [0, d/2, 0], axis: [0, 1, 0] }),
-});
-const placed = child.matchTo(parent, "tab", "mount");
-```
+// Center at the world origin
+const centered = shape.placeReference('center', [0, 0, 0])
 
-### ❌ rotate() for cylinder orientation
-```javascript
-// BAD: which axis? what happens to center?
-const pipe = cylinder(100, 5).rotate(90, 0, 0).translate(x, y, z);
+// Align left edge to X = 10
+const aligned = shape.placeReference('left', [10, 0, 0])
 ```
 
-### ✅ pointAlong() for cylinder orientation
-```javascript
-// GOOD: reads as "pipe pointing along Y"
-const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
-```
+Also works with custom placement references for cross-file parts:
 
-### ❌ Bounding-box positioning for assembly interfaces
 ```javascript
-// BAD: fragile — changes if parent geometry is filleted or modified
-const shelf = plank.attachTo(sidePanel, 'left', 'right', [0, 0, -50]);
-```
+// widget.forge.js — define once
+return union(base, post).withReferences({ points: { mount: [0, -16, -4] } });
 
-### ✅ Connectors for assembly interfaces
-```javascript
-// GOOD: connector positions are explicit and stable
-const shelf = plank.matchTo(sidePanel, "left_tab", "shelf_slot_0");
+// importer — consume
+const widget = require("./widget.forge.js").placeReference("mount", [120, 40, 0]);
 ```
+
+For cross-file parts needing proper alignment, prefer connectors over placement references.

package/dist-skill/docs-dev/API/core/concepts.md

@@ -0,0 +1,51 @@
+---
+skill-group: core
+skill-order: 1
+---
+
+# ForgeCAD Core Concepts
+
+ForgeCAD scripts are JavaScript that returns geometry. The forge API is globally available — no imports needed.
+
+```javascript
+const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
+return box(width, 30, 10);
+```
+
+## Execution Model
+
+- Scripts re-execute on every parameter change (400ms debounce)
+- All operations are **immutable** — return new shapes, never modify in place
+- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Array` of shapes/sketches/groups, or `Array` of `{ name, shape?, sketch?, color? }`
+
+## Coordinate System
+
+Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
+
+## Colors
+
+`.color(hex)` works on `Shape` and `Sketch`. Colors survive transforms. In booleans the first operand's color wins.
+
+**`union()` removes colors** — shapes merge into one solid mesh. Return named objects instead:
+
+```javascript
+return [
+  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
+  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
+];
+```
+
+## Face Operations
+
+Shapes carry semantic face labels through their lifecycle. The flow is:
+
+1. **Primitives** assign canonical names — `box()` gives you `top`, `bottom`, `side-left`, etc.; `cylinder()` gives `top`, `bottom`, `side`.
+2. **Extrusions** inherit labels from the sketch and add `top`/`bottom`.
+3. **Transforms** (translate, rotate, scale, mirror) preserve all labels.
+4. **Booleans** preserve labels from the first operand where geometry survives.
+
+You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
+
+## SDF Modeling
+
+For organic shapes, smooth blending, TPMS lattices, and surface deformations. SDF shapes convert via `.toShape()`. See [sdf-primitives.md](sdf-primitives.md).

package/dist-skill/docs-dev/API/core/sdf-advanced.md

@@ -0,0 +1,92 @@
+---
+skill-group: dev-sdf
+skill-order: 2
+---
+
+# SDF Advanced Operations
+
+## TPMS Lattices
+
+```javascript
+sdf.gyroid({ cellSize, thickness })    // most common for 3D printing
+sdf.schwarzP({ cellSize, thickness })  // isotropic pores
+sdf.diamond({ cellSize, thickness })   // stiffest structure
+```
+
+TPMS fills all space — **always clip with an intersect before `.toShape()`**:
+
+```javascript
+const lattice = sdf.gyroid({ cellSize: 8, thickness: 1.2 })
+  .intersect(sdf.sphere(25))
+  .toShape();
+```
+
+`cellSize`: larger = coarser. `thickness`: thicker = denser.
+
+## Domain Operations
+
+### Twist
+Rotates slices around Y axis as function of Y position.
+```javascript
+sdf.cylinder(50, 8).twist(0.9).toShape()  // 45° total over 50mm (0.9 deg/mm)
+```
+
+### Bend
+Bends around Z axis. Smaller radius = tighter arc.
+```javascript
+sdf.cylinder(60, 5).bend(20).toShape()  // arch shape
+```
+
+### Repeat
+Tiles in space. Spacing `0` = no repeat on that axis. Count `0` = infinite.
+```javascript
+sdf.sphere(4).repeat([15, 15, 0], [3, 3, 0]).toShape()  // 3×3 grid
+```
+
+### Shell
+Hollows to surface shell of given thickness.
+```javascript
+sdf.sphere(20).shell(2).subtract(sdf.box(60, 60, 30).translate(0, 0, -15)).toShape()
+```
+
+### Displace
+Offsets surface by a function of position.
+```javascript
+sdf.sphere(15).displace((x, y, z) => Math.sin(x * 0.8) * Math.sin(y * 0.8) * Math.sin(z * 0.8) * 2).toShape()
+```
+
+**Critical gotcha for `displace()` and `fromFunction()`:** The function is serialized as a string and re-evaluated via `new Function("x","y","z", "return ...")`. This means:
+- **No closure variables** — cannot reference `param()` values inside
+- **Single expression only** — no `const`, `let`, `if`, `for`
+- Multi-statement blocks **silently produce bad geometry**
+
+### Onion
+Concentric shells.
+```javascript
+sdf.sphere(20).onion(3, 2).toShape()  // 3 shells, 2mm apart
+```
+
+## Morphing
+
+Interpolate between two shapes. `t=0` = a, `t=1` = b.
+```javascript
+sdf.morph(sdf.sphere(12), sdf.box(20, 20, 20), 0.5).toShape()
+a.morph(b, t)  // method form
+```
+
+## Custom SDF Functions
+
+```javascript
+sdf.fromFunction(fn, { min: [x0, y0, z0], max: [x1, y1, z1] })
+```
+
+`fn(x, y, z)` returns signed distance: negative = inside, positive = outside, zero = surface. Bounds are required — provide tightly to avoid wasted computation.
+
+```javascript
+const heart = sdf.fromFunction(
+  (x, y, z) => (x*x + z*z*1.1 + y*y - 1)**3 - x*x*y*y*y - z*z*y*y*y * 0.11,
+  { min: [-20, -25, -15], max: [20, 20, 15] }
+).toShape();
+```
+
+Same serialization gotcha as `displace()` — no closure variables, single expression only.

package/dist-skill/docs-dev/API/core/sdf-primitives.md

@@ -0,0 +1,58 @@
+---
+skill-group: dev-sdf
+skill-order: 1
+---
+
+# SDF Primitives & Booleans
+
+> **Experimental.** Slower render times than B-rep; lower mesh quality from marching-tetrahedra extraction. Use for organic forms, TPMS lattices, smooth blending. For mechanical parts, prefer B-rep.
+
+SDF operations are accessed via the globally available `sdf` namespace. All shapes live as a lazy expression tree until `.toShape()` is called.
+
+## Primitives
+
+All centered at origin unless noted.
+
+```javascript
+sdf.sphere(radius)
+sdf.box(x, y, z)                    // full dimensions — box(20,20,20) → 20mm cube
+sdf.cylinder(height, radius)        // axis along Y (rotate 90,0,0 for Z-axis)
+sdf.torus(majorRadius, minorRadius) // ring in XZ plane (hole axis = Y)
+sdf.capsule(height, radius)         // axis along Y
+sdf.cone(height, radius)            // base at y=0, tip at y=height (not centered)
+```
+
+## Boolean Operations
+
+```javascript
+// Sharp
+a.union(b, c, d); a.subtract(b); a.intersect(b)
+
+// Smooth — blend over transition radius
+sdf.smoothUnion(a, b, { radius: 5 })       // factory: radius in options object
+sdf.smoothDifference(a, b, { radius: 5 })
+sdf.smoothIntersection(a, b, { radius: 5 })
+
+a.smoothUnion(b, 5)      // method: radius as direct number
+a.smoothSubtract(b, 5)   // note: smoothSubtract, not smoothDifference
+a.smoothIntersect(b, 5)
+```
+
+**API mismatch:** Factory functions take `{ radius }` (object). Instance methods take `radius` (number). Don't mix them.
+
+## Transforms
+
+```javascript
+shape.translate(x, y, z)
+shape.rotateX(deg)               // also rotateY, rotateZ, rotate(axis, deg)
+shape.scale(factor)              // uniform only
+```
+
+## Reserved Names
+
+The global scope defines `sphere`, `box`, `cylinder`, `torus`, `capsule`, `cone`, `shell` as B-rep primitives. Always use `sdf.*` prefix — and avoid naming local variables after these globals:
+
+```javascript
+const orb = sdf.sphere(10);       // correct — not 'sphere'
+const s = sdf.sphere(10);         // bad — shadows global 'sphere' if named 'sphere'
+```

package/dist-skill/docs-dev/API/core/sdf-workflow.md

@@ -0,0 +1,42 @@
+---
+skill-group: dev-sdf
+skill-order: 3
+---
+
+# SDF Workflow & Mesh Quality
+
+## Converting to Shape
+
+```javascript
+shape.toShape()
+shape.toShape({ edgeLength: 0.5 })                        // finer mesh
+shape.toShape({ bounds: { min: [...], max: [...] } })     // override auto bounds
+```
+
+| Option | Default | Effect |
+|--------|---------|--------|
+| `edgeLength` | `maxDim / 100` | Smaller = smoother, slower |
+| `bounds` | auto-estimated | Override sampling volume |
+
+For smooth shapes use `0.3–0.5`. For fast previews use `1–2`.
+
+After meshing, Laplacian smoothing + SDF projection runs automatically (2 iterations) to reduce axis-aligned triangle artifacts.
+
+## Workflow Tips
+
+- **Start coarse, refine last** — design at `edgeLength: 2`, drop to `0.5` for output
+- **Clip TPMS before `toShape()`** — intersect with bounding shape first
+- **Compose before meshing** — do all booleans/deformations in SDF space, then call `.toShape()` once
+- **Mix with B-rep freely** — after `.toShape()`, use in `difference()`, `union()`, `.fillet()`, etc.
+
+```javascript
+const organicBase = sdf.smoothUnion(sdf.sphere(20), sdf.box(30, 30, 10), { radius: 8 }).toShape();
+return difference(organicBase, cylinder(15, 3));  // B-rep cut on SDF result
+```
+
+## Serialization Gotcha
+
+`displace()` and `fromFunction()` serialize the function body via `new Function("x","y","z", "return ...")`:
+- **No closure variables** — cannot reference `param()` values
+- **Single expression only** — no `const`, `let`, `if`, `for`
+- Multi-statement blocks silently produce bad geometry

package/dist-skill/docs-dev/CLI/export.md

@@ -0,0 +1,91 @@
+---
+skill-group: cli
+skill-order: 3
+---
+
+# ForgeCAD CLI: Export Commands
+
+## SVG Export
+
+```bash
+forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js [output.svg]
+```
+
+Pure Node — no browser needed. Runs the sketch script through the forge engine and converts polygons to SVG paths.
+
+## STEP / BREP Export (exact subset, CadQuery)
+
+```bash
+forgecad export step examples/api/brep-exportable.forge.js [--output out/demo.step] [--python 3.11] [--uv /path/to/uv]
+forgecad export brep examples/api/brep-exportable.forge.js
+forgecad export step examples/chess-set.forge.js --allow-faceted
+```
+
+`uv`-first: provisions CadQuery automatically. Exact-subset only by default — fails with a reason rather than silently exporting degraded geometry. With `--allow-faceted`, unsupported mesh solids export as faceted OCCT solids (tessellation-driven, not exact replay).
+
+The maintained feature matrix: `docs/permanent/API/output/brep-export.md`.
+
+## G-code Toolpath Export
+
+```bash
+forgecad export gcode examples/gcode/parametric-vase.forge.js [--output out/vase.gcode]
+```
+
+The script must return a `GCodeBuilder` (from the `gcode()` factory). This is a toolpath scripting API, not a slicer — you define print movements in code. See `docs/permanent/API/output/gcode.md` for the full API.
+
+## SDF Robot Export (Gazebo)
+
+```bash
+forgecad export sdf examples/api/sdf-rover-demo.forge.js [--output out/forge_scout]
+```
+
+Writes a Gazebo-friendly package: `model.sdf`, `model.config`, `meshes/*.stl`, optional world file. Script must call `robotExport({...})` with an `assembly(...)` graph.
+
+Launch flow (macOS — use split `-s`/`-g`):
+```bash
+export GZ_SIM_RESOURCE_PATH="$PWD/out/forge_scout/models${GZ_SIM_RESOURCE_PATH:+:$GZ_SIM_RESOURCE_PATH}"
+gz sim -s -r out/forge_scout/worlds/forge_scout_trial.sdf
+gz sim -g out/forge_scout/worlds/forge_scout_trial.sdf
+```
+
+## URDF Export
+
+```bash
+forgecad export urdf examples/api/sdf-rover-demo.forge.js
+```
+
+## PNG Render (requires Chrome/Puppeteer)
+
+```bash
+forgecad render examples/cup.forge.js [output.png]
+forgecad render examples/cup.forge.js out/scene.png --scene '<json from viewport>'
+```
+
+Options: `--angles <front,side,top,iso>`, `--size <px>`, `--port <n>`, `--camera <spec>`, `--scene <json>`, `--background <color>`, `--chrome-path <path>`.
+
+## Animated Capture (GIF or MP4, requires Chrome)
+
+```bash
+forgecad capture gif examples/cup.forge.js [output.gif]
+forgecad capture mp4 examples/cup.forge.js [output.mp4]
+forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
+forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
+```
+
+`--list` prints available animation clips and cut planes. Uses `ffmpeg` when available (better GIF colors, H.264 MP4); falls back to pure-JS GIF encoder.
+
+Key options: `--capture <orbit|animation>`, `--animation <name>`, `--cut-plane <name>`, `--camera <spec>`, `--scene <json>`, `--size <px>`, `--fps <n>`, `--frames-per-turn <n>`, `--quality <default|live|high>`.
+
+Use `Copy CLI --scene` from the View Panel to grab the current viewport framing and paste into `render` or `capture`.
+
+## PDF Report
+
+```bash
+forgecad export report examples/cup.forge.js [output.pdf] [--dim-angle-tol 18]
+```
+
+Generates a searchable PDF with BOM page, combined model page, and per-component pages. Dimensions included per view when their axis aligns with that view's projection plane (within `--dim-angle-tol` degrees, default 12).
+
+## STL Export
+
+Available in the browser UI via the Export panel (binary STL).