forgecad 0.6.3 → 0.8.0

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

@@ -0,0 +1,104 @@
+---
+skill-group: toolbox
+skill-order: 100
+---
+
+# Woodworking
+
+Wood boards with grain/species metadata, and joinery operations: dado, rabbet, mortise & tenon. Access via `Wood.*`.
+
+## Contents
+
+- [WoodBoard](#woodboard)
+- [Wood](#wood)
+
+---
+
+## Classes
+
+### `WoodBoard`
+
+A board of wood with metadata for manufacturing: grain direction, species, and dimensions. The underlying geometry is a simple box.
+
+Shape is mutable — joint operations (Wood.dado, Wood.rabbet, Wood.mortiseAndTenon) subtract material in-place. Transform methods return new WoodBoard instances preserving all metadata.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `shape` | `Shape` | The underlying 3D shape — mutable, joints modify it in-place. |
+| `width` | `number` | Board width (mm) — the longer flat dimension |
+| `height` | `number` | Board height (mm) — the shorter flat dimension |
+| `thickness` | `number` | Board thickness (mm) |
+| `grain` | `string` | Grain direction: "long" or "cross" |
+| `species` | `string` | Wood species, e.g. "birch", "oak" |
+| `material` | `string` | Material label for BOM |
+
+**Methods:**
+
+#### `cut()` — Subtract a cutter from this board, modifying it in-place. Used by joint functions (dado, rabbet, mortiseAndTenon).
+
+```ts
+cut(cutter: Shape): this
+```
+
+#### `translate()` — Translate the board in 3D space.
+
+```ts
+translate(x: number, y: number, z: number): WoodBoard
+```
+
+#### `rotate()` — Rotate the board around an axis by a given angle in degrees.
+
+```ts
+rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): WoodBoard
+```
+
+#### `rotateX()` — Rotate the board around the X axis by a given angle in degrees.
+
+```ts
+rotateX(angleDeg: number): WoodBoard
+```
+
+#### `rotateY()` — Rotate the board around the Y axis by a given angle in degrees.
+
+```ts
+rotateY(angleDeg: number): WoodBoard
+```
+
+#### `rotateZ()` — Rotate the board around the Z axis by a given angle in degrees.
+
+```ts
+rotateZ(angleDeg: number): WoodBoard
+```
+
+#### `mirror()` — Mirror the board across a plane defined by its normal.
+
+```ts
+mirror(normal: [ number, number, number ]): WoodBoard
+```
+
+#### `color()` — Set the board's display color.
+
+```ts
+color(value: string): WoodBoard
+```
+
+#### `clone()` — Clone the board (creates an independent copy of the underlying shape).
+
+```ts
+clone(): WoodBoard
+```
+
+---
+
+## Constants
+
+### `Wood`
+
+Woodworking namespace — create boards and cut joints. **Boards:** `Wood.board()` creates a WoodBoard with grain, species, and BOM metadata. **Joints:** `Wood.dado()`, `Wood.rabbet()`, `Wood.mortiseAndTenon()` mutate boards in-place by subtracting material, following the same pattern as LaserKit's [`fingerJoint()`](/docs/sheet-metal#fingerjoint).
+
+- `readonly board: (width: number, height: number, thickness: number, opts?: WoodBoardOptions) => WoodBoard` — Create a wood board with metadata for manufacturing. The board is a box(width, height, thickness) centered on XY, base at Z=0. Width along X, height along Y, thickness along Z (0 to thickness).
+- `dado(host: WoodBoard, guest: WoodBoard, opts: DadoOptions): void` — Cut a dado (channel) across the face of a host board for a guest board to sit in. Mutates `host.shape` by subtracting a rectangular channel.
+- `rabbet(board: WoodBoard, opts: RabbetOptions): void` — Cut a rabbet (L-shaped step) along an edge of a board. Mutates `board.shape` by subtracting a step from the specified edge.
+- `mortiseAndTenon(mortiseBoard: WoodBoard, tenonBoard: WoodBoard, opts?: MortiseAndTenonOptions): void` — Cut a mortise in one board and shape a tenon on another. Mutates both boards — subtracts the mortise pocket and removes shoulder material to form the tenon.

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

@@ -17,19 +17,18 @@ ForgeCAD uses a **Z-up** right-handed coordinate system.
 
 ## Standard Views
 
-| View   | Camera position direction | Sees plane | Camera up |
-|--------|--------------------------|------------|-----------|
-| Front  | −Y (camera at −Y)        | XZ         | Z         |
-| Back   | +Y (camera at +Y)        | XZ         | Z         |
-| Right  | +X (camera at +X)        | YZ         | Z         |
-| Left   | −X (camera at −X)        | YZ         | Z         |
-| Top    | +Z (camera at +Z)        | XY         | +Y        |
-| Bottom | −Z (camera at −Z)        | XY         | −Y        |
-| Iso    | +X −Y +Z (diagonal)      | —          | Z         |
+| View   | Camera position direction | Sees plane |
+|--------|--------------------------|------------|
+| Front  | −Y                       | XZ         |
+| Back   | +Y                       | XZ         |
+| Right  | +X                       | YZ         |
+| Left   | −X                       | YZ         |
+| Top    | +Z                       | XY         |
+| Bottom | −Z                       | XY         |
 
 ## GizmoViewcube Face Mapping
 
-Three.js BoxGeometry material indices (cube face order):
+Three.js BoxGeometry material indices vs ForgeCAD labels (Z-up remapping):
 
 | Index | Three.js direction | ForgeCAD label |
 |-------|--------------------|----------------|
@@ -40,13 +39,8 @@ Three.js BoxGeometry material indices (cube face order):
 | 4     | +Z                 | Top            |
 | 5     | −Z                 | Bottom         |
 
-Default drei labels are `['Right', 'Left', 'Top', 'Bottom', 'Front', 'Back']` (Y-up).
-For Z-up we pass `faces={['Right', 'Left', 'Front', 'Back', 'Top', 'Bottom']}`.
-
-## Kernel Axis Convention
-
-Manifold (the geometry kernel) is Y-up internally. ForgeCAD is Z-up externally. If a kernel-facing operation behaves as if axes are swapped, check whether a Manifold call is still assuming Y-up semantics.
+Default drei labels are Y-up; ForgeCAD passes `faces={['Right','Left','Front','Back','Top','Bottom']}`.
 
 ## Grid
 
-The ground plane is XY (Z = 0). The grid lies on this plane.
+The ground plane is XY (Z = 0). Extrusion goes along +Z. Manifold is Y-up internally — if a kernel-facing operation behaves as if axes are swapped, check for Manifold Y-up semantics leaking through.

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

@@ -5,105 +5,48 @@ skill-order: 2
 
 # Geometry Conventions
 
-ForgeCAD wraps Manifold (a mesh kernel) and Three.js (a Y-up renderer). These libraries have their own conventions that conflict with each other and with CAD norms. This doc captures every convention mismatch and how ForgeCAD resolves it.
-
-**Core principle: the user script should never need to know about kernel or renderer internals.** If the user writes something geometrically reasonable, it should work. All convention translation happens inside ForgeCAD's layer.
+ForgeCAD wraps Manifold (mesh kernel) and Three.js (Y-up renderer). This doc captures convention mismatches and how ForgeCAD resolves them.
 
 ## Winding Order
 
-**What it is:** The order of vertices in a 2D polygon determines its "direction" — counter-clockwise (CCW) = positive area, clockwise (CW) = negative/zero area in Manifold's `CrossSection`.
-
-**The problem:** Manifold silently produces empty geometry for CW polygons. A user writing `polygon([[0,0], [50,0], [50,30]])` vs `polygon([[0,0], [50,30], [50,0]])` gets either a triangle or nothing, with no error.
-
-**ForgeCAD's fix:** All entry points that accept raw points auto-fix winding:
-- `polygon(points)` — computes signed area, reverses if CW
+CCW = positive area, CW = empty in Manifold's `CrossSection`. ForgeCAD auto-fixes at all entry points:
+- `polygon(points)` — computes signed area (shoelace), reverses if CW
 - `path().close()` — same fix
 
-**Signed area test** (shoelace formula):
-```
-signedArea = Σ (x₂ - x₁)(y₂ + y₁)
-```
-If `signedArea > 0` → CW → reverse to make CCW.
-
-**Implementation:** `src/forge/sketch/primitives.ts` (polygon), `src/forge/sketch/path.ts` (close).
-
-**Rule for new code:** Any function that takes user-provided point arrays and creates a `CrossSection` MUST auto-fix winding. Never pass raw user points to Manifold without this check.
+**Rule for new code:** Any function accepting user point arrays that creates a `CrossSection` MUST auto-fix winding.
 
 ## Coordinate System (Z-up vs Y-up)
 
-**The problem:** Three.js uses Y-up. CAD convention (and ForgeCAD) uses Z-up.
-
-**ForgeCAD's fix:** We set `camera.up = (0, 0, 1)` everywhere. Geometry coordinates are native Z-up — no matrix swizzling. The camera orientation handles the visual mapping.
-
-**Where this matters:**
-- `camera.up.set(0, 0, 1)` in `sceneBuilder.ts` and `render.ts`
-- GizmoViewcube face labels remapped (see coordinate-system.md)
-- Grid plane is XY (Z=0)
-- Extrusion goes along +Z
-- Revolution axis is Y (sketch plane), result maps to Z-up space
-
-**Rule for new code:** Never swap Y/Z in geometry. Always fix it at the camera/renderer level.
+Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0,0,1)`) — geometry coordinates are native Z-up. Never swap Y/Z in geometry.
 
 ## Revolution Axis
 
-**What it is:** `CrossSection.revolve()` in Manifold revolves around the Y axis. The sketch profile must be in the X-Y plane with X = radius (distance from axis) and Y = height.
-
-**The mapping:**
-- Profile X coordinate → radial distance from center
-- Profile Y coordinate → height (becomes Z after revolution)
-- Profile must be on the positive X side (X > 0) for valid geometry
-
-**Rule for new code:** Document which axis any new sweep/revolution operation uses. If it differs from user expectation, add a transform wrapper.
+`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
 
 ## Boolean Winding (3D)
 
-**What it is:** Manifold requires consistent face normals (outward-pointing) for boolean operations. Manifold handles this internally for its own primitives, but imported meshes or degenerate operations can produce inside-out faces.
-
-**ForgeCAD's fix:** We only create meshes through Manifold's own constructors (`extrude`, `revolve`, `cylinder`, `sphere`, etc.), which guarantee correct normals. No raw mesh import path exists yet.
-
-**Rule for new code:** If adding mesh import (STL, OBJ), run `Manifold.asOriginal()` or validate manifoldness before allowing booleans.
+Manifold requires consistent outward face normals. ForgeCAD only creates meshes through Manifold's own constructors, which guarantee correct normals.
 
 ## Transform Order
 
-**What it is:** Transforms are applied in call order (left to right in the chain). Default `rotate()`, `scale()`, and `mirror()` operate around the shape's own bounding-box center, so `shape.translate(10,0,0).rotate(0,0,45)` moves first and then spins in place. To orbit around world origin, use `rotateAround([0,0,0], ...)`.
+Transforms apply left-to-right. `rotate()`, `scale()`, `mirror()` operate around bounding-box center. Use `rotateAround([0,0,0], ...)` to orbit around world origin.
 
-**Convention:** This matches the standard "post-multiply" convention. No surprises here, but worth noting because some systems (OpenSCAD) apply transforms in reverse order.
-
-For explicit transform objects:
-- `A.mul(B)` means **apply A, then B**.
-- `composeChain(A, B, C)` means **A -> B -> C**.
-
-**Rule for new code:** Keep this chain order everywhere. Document any operation that deviates.
+For explicit transform objects: `A.mul(B)` = apply A then B; `composeChain(A, B, C)` = A→B→C.
 
 ## Assembly Frame Composition
 
-This is where regressions are most likely if convention is unclear.
-
-For a point in child geometry-local coordinates:
-- local -> `childBase` -> `jointMotion(value)` -> `jointFrame` -> `parentWorld`
-
-In Forge chain notation:
 ```ts
 childWorld = composeChain(childBase, jointMotion, jointFrame, parentWorld)
 ```
 
-Equivalent matrix-style equation (for reference):
-```txt
-T_world_child = T_parent_world * T_joint_frame * T_joint_motion * T_child_base
-```
-
-**Rule for new code:** In kinematics/assembly code, prefer `composeChain(...)` over manual `.mul(...).mul(...)` sequences to avoid order mistakes.
+Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code to avoid order mistakes.
 
-## Summary of Shield Points
-
-These are the places where ForgeCAD translates between "what the user means" and "what the kernel needs":
+## Summary
 
 | Convention | User sees | Kernel needs | Where we fix it |
 |---|---|---|---|
 | Winding | Any point order | CCW | `polygon()`, `path().close()` |
 | Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
-| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented, not auto-fixed |
+| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
 | Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
-| Transform order | Left-to-right chain | Post-multiply | Native match, no fix needed |
-
-When adding new geometry operations, check this table. If the operation introduces a new convention mismatch between user intent and kernel requirement, either auto-fix it (preferred) or document it clearly in the API docs.
+| Transform order | Left-to-right chain | Post-multiply | Native match |

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

@@ -0,0 +1,78 @@
+---
+skill-group: recipes
+skill-order: 5
+---
+
+# Joint Design Recipes
+
+How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
+
+## The Cavity Rule
+
+Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.
+
+If two adjacent parts in an assembly show a collision volume larger than the expected clearance volume in `forgecad run`, one part is missing its cavity. Both parts have solid material at the same joint position. This will look fine at rest pose but will block rotation and produce confusing joint behavior.
+
+```ts
+// BAD — body has a stadium cap at both ends; the "slot" between two clevis tines
+// is just empty space next to a solid body cap. The next phalanx's tongue knuckle
+// has nowhere to go (it intersects the previous body's cap).
+const body  = stadiumBar(L);            // cap at X=0 AND X=L
+const tine1 = box(...).translate(L,  Y_OFF, 0);
+const tine2 = box(...).translate(L, -Y_OFF, 0);
+let phalanx = union(body, tine1, tine2);
+
+// GOOD — body ends FLAT before the joint. Tines extend forward to the pivot.
+// The X = L-KNUCK_R..L+KNUCK_R volume between the tines is genuinely empty.
+const body = box(L - KNUCK_R, TONG_T, H, true).translate((L - KNUCK_R) / 2, 0, 0);
+const tongueKnuckle = knuckleDisc(0, 0, TONG_T);  // proximal cap only
+let phalanx = union(tongueKnuckle, body, tine1, tine2, ...tineCaps);
+```
+
+After applying the cavity rule, `forgecad run` collision volume between adjacent parts in a clevis-tongue chain should drop to **zero** (or a few mm³ of clearance overlap). If it doesn't, there's still solid material where there should be a cavity.
+
+## Connecting Cantilevers
+
+A clevis tine arm at Y=±Y_OFF is geometrically separate from a body at Y=±TONG_T/2. With Y_OFF > TONG_T/2 + clearance, there is a **physical gap** between them. The tines float — they would snap off as soon as load is applied.
+
+Always add a **yoke**: a short slab spanning the full clevis width, sitting between the body's flat distal end and the tines' attachment point. The yoke fills the Y gap so material is continuous from the body through to each tine.
+
+```ts
+const yokeLen   = 3;                                  // a few mm of structural overlap
+const yokeStart = L - KNUCK_R - yokeLen;
+const totalY    = (Y_OFF + TINE_T / 2) * 2;           // full clevis width
+const yoke = box(yokeLen, totalY, H, true)
+  .translate(yokeStart + yokeLen / 2, 0, 0);
+phalanx = union(phalanx, yoke);
+```
+
+## Hard Stops vs Slider Limits
+
+`addRevolute({ min: 0, max: 90 })` sets **slider limits** — the viewport won't let the user drag past them, but the geometry permits any rotation. There is no physical stop.
+
+For a **geometric** hard stop (parts can't backbend past extension, or can't curl past full closure), add a small protrusion on one part that interferes with the other at the limit angle:
+
+- **Extension stop at 0°** (typical for fingers, knees, elbows): add a small "lip" on the dorsal side of the proximal end of the child phalanx, sized so it just touches the parent's distal dorsal corner at 0°. Negative rotation (backbending) is then blocked by part-on-part contact.
+- **Flexion stop at θmax**: add a similar lip on the palmar side, or rely on the body-to-body collision when bodies meet.
+
+Verify with `forgecad run` at the limit poses — the contact pair should show ~0 mm³ collision (just touching), and rotation past the limit should report a non-zero collision volume.
+
+## Knuckle Sizing
+
+For a clevis-tongue joint with body height H, the tongue knuckle radius and clevis tine knuckle radius must satisfy:
+
+```
+KNUCK_R >= H / 2
+```
+
+If the knuckle radius is smaller than the body's half-height, the body's corners protrude beyond the knuckle envelope. When the joint rotates, those corners sweep through space outside the cylindrical envelope and collide with the adjacent part.
+
+Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that perfectly fits the knuckle envelope.
+
+## Verification Workflow
+
+1. Build the joint at rest pose. Run `forgecad run`. Check collision volumes.
+2. If adjacent parts in the joint show > clearance-volume of overlap → missing cavity (apply the cavity rule).
+3. Render with `--focus PartName` to inspect each part in isolation. The clevis end should clearly show a gap between the tines (the cavity).
+4. Render at curl angles (set joint debug params) at 30°, 60°, 90°. No new collisions should appear from rotation.
+5. Render at -10° (backbend test). Either no rotation possible (geometric stop in place) or rotation occurs and you need to add a stop.

package/dist-skill/docs/guides/modeling-recipes.md

@@ -5,246 +5,73 @@ skill-order: 1
 
 # Modeling Recipes
 
-This file collects patterns, best practices, debugging tips, and example snippets that are useful once you already know the model-building API.
-
 ## Iteration Bias
 
-- For unfamiliar or high-risk geometry work, start in a notebook and keep setup, experiments, and validation in separate cells until the structure is obvious.
-- Default to a buildable first pass instead of a long proposal when the user clearly wants geometry changed.
-- Replace a broken or incoherent model wholesale when that is faster and cleaner than incremental patching.
-- Keep printed hardware structurally honest: use it for guides, spacers, retainers, and moderate-load mechanisms; use wood or metal for primary strength.
-- Validate early with `forgecad run <file>` and refine from the actual runtime result.
-- Prefer a few clean part files over one giant script once a design has repeated hardware or a small mechanism.
-
-Notebook helpers worth using during iteration:
-
-- `show(...)` pins the current intermediate geometry in the viewport
-- `forgecad notebook view <file> preview` prints the preview cell with stored outputs in the terminal
-- `forgecad run <file>.forge-notebook.json` validates the preview cell and runs the usual spatial analysis
+- Default to a buildable first pass instead of a long proposal.
+- Replace a broken model wholesale when that is faster than incremental patching.
+- Validate early with `forgecad run <file>`.
 
 ## Common Patterns
 
-### Parametric Box with Holes
-```javascript
-const w = param("Width", 80, { min: 40, max: 150, unit: "mm" });
-const h = param("Height", 60, { min: 30, max: 100, unit: "mm" });
-const t = param("Thickness", 5, { min: 2, max: 10, unit: "mm" });
-const holeD = param("Hole Diameter", 8, { min: 4, max: 20, unit: "mm" });
-
-const base = box(w, h, t);
-const hole = cylinder(t + 2, holeD / 2).translate(w / 2, h / 2, -1);
-
-return base.subtract(hole);
-```
-
-### Hollow Shell (Wall Thickness)
+### Hollow Shell
 ```javascript
-const outer = param("Outer Size", 50, { min: 20, max: 100, unit: "mm" });
-const wall = param("Wall", 3, { min: 1, max: 10, unit: "mm" });
-
 const outerBox = box(outer, outer, outer, true);
 const innerBox = box(outer - 2 * wall, outer - 2 * wall, outer - 2 * wall, true);
-
 return outerBox.subtract(innerBox);
 ```
 
-### Array/Pattern
-```javascript
-const count = param("Count", 5, { min: 2, max: 10 });
-const spacing = param("Spacing", 15, { min: 5, max: 30, unit: "mm" });
-
-let shapes = [];
-for (let i = 0; i < count; i++) {
-  shapes.push(cylinder(10, 5).translate(i * spacing, 0, 0));
-}
-
-return union(...shapes);
-```
-
-### Sketch-Based Design
+### Sketch-Based Twist
 ```javascript
-const sides = param("Sides", 6, { min: 3, max: 12 });
-const radius = param("Radius", 25, { min: 10, max: 50, unit: "mm" });
-const height = param("Height", 60, { min: 20, max: 120, unit: "mm" });
-const wall = param("Wall", 3, { min: 1, max: 8, unit: "mm" });
-
 const outer = ngon(sides, radius);
 const inner = ngon(sides, radius - wall);
-const profile = outer.subtract(inner);
-
-return profile.extrude(height, { twist: 45, divisions: 32 });
+return outer.subtract(inner).extrude(height, { twist: 45, divisions: 32 });
 ```
 
 ### Rounded Profiles
 ```javascript
+// All convex corners — offset trick
 const base = rect(50, 30).offset(-3, 'Round').offset(3, 'Round');
-return base.extrude(10);
-```
-
-Use that pattern when every convex corner should round. For mixed sharp-and-rounded outlines, fillet only the intended vertices instead:
-
-```javascript
-const roofPoints = [
-  [0, 0],
-  [90, 0],
-  [90, 44],
-  [66, 74],
-  [45, 86],
-  [24, 74],
-  [0, 44],
-];
 
+// Selected corners only
 const roof = filletCorners(roofPoints, [
   { index: 3, radius: 19 },
   { index: 4, radius: 19 },
   { index: 5, radius: 19 },
 ]);
-
-return roof.extrude(12);
-```
-
-### Chamfers and Fillets
-```javascript
-const part = box(50, 50, 20);
-const chamfer = box(10, 60, 10)
-  .rotate(0, 45, 0)
-  .translate(50, -5, 15);
-
-return part.subtract(chamfer);
 ```
 
 ### Choosing the right sketch-rounding tool
 
-- `offset(-r).offset(+r)` for rounding every convex corner of a closed outline
-- `stroke(points, width, 'Round')` for centerline-based geometry such as ribs or traces
-- `filletCorners(points, ...)` for selective true-corner fillets on mixed profiles
+- `offset(-r).offset(+r)` — round every convex corner of a closed outline
+- `stroke(points, width, 'Round')` — centerline-based geometry (ribs, traces)
+- `filletCorners(points, ...)` — selective true-corner fillets on mixed profiles
 
 ## Best Practices
 
-### Performance
-- Boolean operations are expensive; minimize them
-- Use parameters for values that might change
-- Avoid deep nesting of operations in loops
-
-### Readability
-```javascript
-const base = box(100, 100, 10);
-const hole = cylinder(12, 8);
-const result = base.subtract(hole.translate(50, 50, 0));
-return result;
-```
-
-Prefer named intermediate values over deeply nested one-liners.
-
-### Units
-- All dimensions are millimeters by default
-- Angles are degrees
-- Use the `unit` parameter option when it helps the reader
-
-### Centering
-```javascript
-const centered = box(50, 50, 50, true).translate(x, y, z);
-const corner = box(50, 50, 50).translate(x - 25, y - 25, z - 25);
-```
-
-Centered primitives are usually easier to position.
+- All dimensions in millimeters; angles in degrees.
+- Primitives are centered on XY, base at Z=0. Use `placeReference('center', [0,0,0])` to center on all axes.
+- Prefer named intermediate values over deeply nested one-liners.
+- `union2d`, `difference2d`, `intersection2d` batch faster than chained `.add()` / `.subtract()`.
 
 ## Debugging
 
-### Console Output
 ```javascript
-console.log("Width:", width);
 console.log("Volume:", shape.volume());
 ```
 
-### Incremental Building
-```javascript
-const base = box(50, 50, 10);
-// return base;
-
-const withHole = base.subtract(cylinder(12, 5).translate(25, 25, 0));
-// return withHole;
-
-return withHole.add(cylinder(20, 3).translate(25, 25, 10));
-```
-
-For sketch-heavy work, compare the raw profile and the rounded profile before extruding:
+For sketch-heavy work, compare the raw profile and rounded profile side-by-side before extruding:
 
 ```javascript
-const raw = polygon(roofPoints);
-const rounded = filletCorners(roofPoints, [
-  { index: 3, radius: 19 },
-  { index: 4, radius: 19 },
-  { index: 5, radius: 19 },
-]);
-
 return [
-  { name: "Raw", sketch: raw },
-  { name: "Rounded", sketch: rounded.translate(120, 0) },
+  { name: "Raw", sketch: polygon(roofPoints) },
+  { name: "Rounded", sketch: filletCorners(roofPoints, [...]).translate(120, 0) },
 ];
 ```
 
-## Error Handling
-
-Common errors:
-- `"Kernel not initialized"` - internal/runtime issue, reload the app
-- `"Cannot read property of undefined"` - usually a bad variable name or missing declaration
-- invalid geometry - commonly caused by zero dimensions or self-intersecting sketches
-- script execution error - inspect the JS error in console output
-
-## Example Snippets
-
-### Parametric Phone Stand
-```javascript
-const width = param("Width", 80, { min: 40, max: 150, unit: "mm" });
-const depth = param("Depth", 60, { min: 30, max: 100, unit: "mm" });
-const thick = param("Thickness", 5, { min: 2, max: 15, unit: "mm" });
-const backH = param("Back Height", 40, { min: 20, max: 80, unit: "mm" });
-const cableD = param("Cable Hole", 8, { min: 4, max: 15, unit: "mm" });
-
-const base = box(width, depth, thick);
-const back = box(width, thick, backH).translate(0, depth - thick, thick);
-const lip = box(width, 10, 8).translate(0, 0, thick);
-const hole = cylinder(thick + 2, cableD / 2)
-  .rotate(90, 0, 0)
-  .translate(width / 2, depth / 2, -1);
-
-return union(base, back, lip).subtract(hole);
-```
-
-### Multi-Object Scene with Colors
-```javascript
-const base = box(100, 100, 5).color('#888888');
-const col1 = cylinder(40, 5).translate(20, 20, 5).color('#cc4444');
-const col2 = cylinder(40, 5).translate(80, 20, 5).color('#4444cc');
-const col3 = cylinder(40, 5).translate(50, 80, 5).color('#44cc44');
-const top = box(100, 100, 3).translate(0, 0, 45).color('#888888');
-
-return [
-  { name: "Base", shape: base },
-  { name: "Column A", shape: col1 },
-  { name: "Column B", shape: col2 },
-  { name: "Column C", shape: col3 },
-  { name: "Top", shape: top },
-];
-```
-
-### Entity-Based Design with Topology
-```javascript
-const baseRect = rectangle(0, 0, 80, 60);
-const base = baseRect.extrude(20);
-
-const result = filletEdge(base.toShape(), base.edge('vert-br'), 8, [-1, -1])
-  .hole(base.face('top'), { diameter: 6, u: -16, v: 10, depth: 8 });
-
-const holes = circularPattern(
-  cylinder(25, 4).translate(40, 30, -1),
-  4, 40, 30,
-);
-
-return result.subtract(holes);
-```
+## Common Errors
 
-Use the original tracked body (`base`) when you need semantic faces after edge finishing, and keep using its untouched sibling vertical tracked edges if you apply another supported fillet/chamfer later. Those sibling edges can now also survive a later supported union when the compiler still records one preserved propagated edge lineage for them. The currently selected finished edge is still recorded as a merged descendant set, so Forge does not claim a new durable tracked edge for that rewritten corner yet.
+- `"Kernel not initialized"` — internal/runtime issue, reload the app
+- zero dimensions or self-intersecting sketches → invalid geometry
+- wrong variable name → `"Cannot read property of undefined"`
 
 For larger runnable examples, read `examples/api/`.