forgecad 0.9.16 → 0.10.0

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

@@ -9,7 +9,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ## Contents
 
-- [Viewport & Runtime](#viewport-runtime) — `Viewport.label`, `scene`, `viewConfig`, `explodeView`, `compareWith`, `cutPlane`, `mock`, `showLabels`, `highlight`
+- [Viewport & Runtime](#viewport-runtime)
 - [RouteBuilder](#routebuilder)
 - [route](#route)
 
@@ -17,7 +17,7 @@ Cut planes, exploded views, joint animations, and scene configuration.
 
 ### Viewport & Runtime
 
-#### `Viewport.label()` — Add a render-only viewport label at a world-space point.
+#### `Viewport.label(text: string, at: Vec3, options?: RenderLabelOptions): void` — Add a render-only viewport label at a world-space point.
 
 `Viewport.label()` is for temporary review, debug, tutorial, or explicitly requested presentation overlays. It does not create sketches, meshes, B-rep topology, exported text, or face labels, so it stays off the OCCT path. Default production models should be understandable from physical geometry, materials, part boundaries, and named objects, not viewport annotations.
 
@@ -36,10 +36,6 @@ Viewport.label('Bearing bore', [0, 0, 18], {
 return box(40, 30, 12);
 ```
 
-```ts
-Viewport.label(text: string, at: [ number, number, number ], options?: RenderLabelOptions): void
-```
-
 **`RenderLabelOptions`**
 
 | Option | Type | Description |
@@ -47,23 +43,54 @@ Viewport.label(text: string, at: [ number, number, number ], options?: RenderLab
 | `color?` | `string` | Text color as any CSS color string. |
 | `background?` | `string` | Background color as any CSS color string. Use `'transparent'` for no pill background. |
 | `size?` | `number` | Font size in CSS pixels. Defaults to 12. |
-| `offset?` | `[ number, number, number ]` | Additional world-space offset from `at`. |
+| `offset?` | `Vec3` | Additional world-space offset from `at`. |
 | `anchor?` | `RenderLabelAnchor` | Which point of the label box is anchored to `at`. Defaults to `'center'`. |
 | `alwaysOnTop?` | `boolean` | When false, the label is hidden when occluded by scene geometry. Defaults to true. |
 
-#### `scene()` — Configure the scene environment for the current script execution.
+#### `Viewport.highlight(target: unknown, options?: HighlightOptions): void` — Highlight any geometry for visual debugging in the viewport.
+
+`Viewport.highlight()` draws render-only debug overlays — distinctive colored markers that appear in the viewport but never become geometry, never export, and never appear in `objects`.
+
+Supported inputs:
+
+- `[x, y, z]` — 3D point
+- `[[x1,y1,z1], [x2,y2,z2]]` — edge (line segment)
+- `{ normal: [x,y,z], offset: number }` — plane by normal + distance from origin
+- `{ normal: [x,y,z], point: [x,y,z] }` — plane by normal + point on plane
+- [`Shape`](/docs/core#shape) — highlight an entire 3D shape
+- `FaceRef` (from `shape.face('top')`) — highlight as plane at face center
+- `EdgeRef` (from `shape.edge('left')`) — highlight as edge segment
+- `string` — 2D sketch entity ID (e.g. `'L0'`, `'P0'`)
+
+Pass `{ labels: true }` with a [`Shape`](/docs/core#shape) to annotate every user-authored labeled face with its name (the face-label debugging view).
+
+```js
+const b = box(30, 20, 15);
+Viewport.highlight([0, 0, 0], { color: 'cyan', label: 'origin' });
+Viewport.highlight(b.face('top'), { color: 'red' });
+Viewport.highlight(b, { labels: true }); // annotate all user-labeled faces
+return b;
+```
+
+**`HighlightOptions`**
+- `size?: number` — Size hint for points (radius in mm) or planes (disc radius in mm).
+- `labels?: boolean` — Shape inputs only: when true, annotate every user-authored labeled face with its label name (one plane highlight per labeled face). The whole-shape tint is added only when other visual options (`color`, `label`, `pulse`) are also passed.
+- Also: `color?: string`, `label?: string`, `pulse?: boolean`.
+
+#### `scene(options: SceneOptions): void` — Configure the scene environment for the current script execution.
 
-Controls camera position, named render views, optional model journeys, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
+Controls camera, named render views, guided journeys, lighting, background, fog, environment maps, post-processing, capture defaults, and the joint-control helper overlay (`jointOverlay` — axis arrows and arc indicators, renderer-only). Multiple `scene()` calls merge per-key — later values win — so configuration can be split across calls.
 
-When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
+Two behavioral cliffs:
 
-Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
+- Specifying `lights` removes **all** default lights. Include your own ambient light or the scene is fully dark.
+- Setting `camera.position` disables auto-framing — the viewport no longer auto-fits the geometry on script reload.
 
-Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `--view hero` on `forgecad render 3d`, `forgecad render hq`, or `forgecad capture`.
+Named views are repeatable cameras checked in with the model code. Canonical shape is `{ camera: { position, target } }`; a direct `{ position, target }` shorthand is also accepted. Render one with `--view <name>` (see CLI docs).
 
-Model journeys let scripts check in a compact guided path through named objects. Each journey has ordered `steps`; each step can name a `focus` target by object name/tree path, provide a caption, and optionally provide an explicit camera. In the viewer, journeys are opt-in: they appear as a small Explore control and do not move the camera until the user starts them. Use `forgecad run model.forge.js --journeys` or `--journeys-json` to inspect resolved targets.
+Journeys are ordered `steps`, each focusing a returned object by name/tree path with an optional caption and camera. In the viewer they are opt-in (an Explore control; the camera does not move until started). Inspect resolved targets with `forgecad run --journeys`.
 
-Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
+Post-processing (`bloom`, `vignette`, `grain`) is browser-only; the CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
 
 All numeric values accept `param()` expressions.
 
@@ -72,52 +99,32 @@ scene({
   background: { top: '#000814', bottom: '#001d3d' },
   camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
   views: {
-    hero: {
-      camera: { position: [180, -140, 90], target: [0, 0, 25], up: [0, 0, 1], fov: 38 },
-    },
-    side: { position: [240, 0, 70], target: [0, 0, 25], fov: 34 },
+    hero: { camera: { position: [180, -140, 90], target: [0, 0, 25], fov: 38 } },
   },
   journeys: {
-    grandTour: {
-      title: 'Grand Tour',
-      startsAt: 'overview',
-      steps: [
-        { id: 'overview', focus: 'Solar System', caption: 'Start with the whole model.' },
-        { id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' },
-      ],
-    },
+    tour: { steps: [{ id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' }] },
   },
   lights: [
     { type: 'ambient', color: '#001233', intensity: 0.08 },
-    { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
-    { type: 'point', position: [-100, 60, 20], color: '#f72585', intensity: 3, distance: 350 },
     { type: 'directional', position: [50, -30, 200], color: '#ffd60a', intensity: 1.2 },
-    { type: 'hemisphere', skyColor: '#003566', groundColor: '#000814', intensity: 0.2 },
   ],
   fog: { color: '#000814', near: 100, far: 450 },
-  postProcessing: {
-    bloom: { intensity: param('bloom', 1.5, 0, 4), threshold: 0.5, radius: 0.7 },
-    vignette: { darkness: 0.8, offset: 0.25 },
-    grain: { intensity: 0.08 },
-    toneMappingExposure: param('exposure', 1.5, 0.5, 4),
-  },
+  postProcessing: { bloom: { intensity: param('bloom', 1.5, 0, 4) } },
+  jointOverlay: { axisColor: '#13dfff', arcColor: '#ff7a1a' },
 });
 ```
 
-```ts
-scene(options: SceneOptions): void
-```
-
 **`SceneOptions`**
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+
+Also: `background?: string | SceneBackgroundGradient`, `camera?: SceneCameraConfig`, `views?: Record<string, SceneViewInputConfig>`, `journeys?: Record<string, SceneJourneyConfig>`, `lights?: SceneLightConfig[]`, `environment?: SceneEnvironmentConfig`, `fog?: SceneFogConfig`, `postProcessing?: ScenePostProcessingConfig`, `ground?: SceneGroundConfig`.
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
-**`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
+`SceneCameraConfig`: `{ position?: Vec3, target?: Vec3, up?: Vec3, fov?: number, type?: "perspective" | "orthographic" }`
 
 **`SceneJourneyConfig`**
 
@@ -145,7 +152,7 @@ scene(options: SceneOptions): void
 
 | Option | Type | Description |
 |--------|------|-------------|
-| `target?` | `[ number, number, number ]` | Target for directional/spot lights |
+| `target?` | `Vec3` | Target for directional/spot lights |
 | `groundColor?` | `string` | Ground color for hemisphere lights |
 | `skyColor?` | `string` | Sky color alias for hemisphere lights (same as color) |
 | `angle?` | `number` | Spot light cone angle in radians |
@@ -153,7 +160,8 @@ scene(options: SceneOptions): void
 | `decay?` | `number` | Point/spot light decay |
 | `distance?` | `number` | Point/spot light distance (0 = infinite) |
 | `castShadow?` | `boolean` | Whether this light casts shadows |
-| `type`, `color?`, `intensity?`, `position?` | | — |
+
+Also: `type: SceneLightType`, `color?: string`, `intensity?: number`, `position?: Vec3`.
 
 **`SceneEnvironmentConfig`**
 - `preset?: "studio" | "sunset" | "dawn" | "warehouse" | "forest" | "apartment" | "lobby" | "city" | "park" | "night" | "none"` — Built-in preset name or 'none' to disable
@@ -164,7 +172,7 @@ scene(options: SceneOptions): void
 - `near?: number` — Linear fog near distance
 - `far?: number` — Linear fog far distance
 - `density?: number` — Exponential fog density (if set, uses FogExp2 instead of linear Fog)
-- Also: `color?: string`
+- Also: `color?: string`.
 
 `ScenePostProcessingConfig`: `{ bloom?: SceneBloomConfig, vignette?: SceneVignetteConfig, grain?: SceneGrainConfig, toneMappingExposure?: number }`
 
@@ -194,28 +202,7 @@ scene(options: SceneOptions): void
 | `size?` | `number` | Output frame size in pixels (default: 960) |
 | `background?` | `string` | Canvas background color for capture (default: '#252526') |
 
-#### `viewConfig()` — Configure viewport helper visuals for the current script execution.
-
-Controls renderer-only overlays that appear in the viewport but are not part of the geometry. Currently supports the joint overlay that renders axis arrows and arc indicators when joint controls are active. Multiple calls merge — later values override earlier ones per key.
-
-This does **not** trigger a geometry recompute; it only affects the visual helpers drawn on top of the 3D scene.
-
-```js
-viewConfig({
-  jointOverlay: {
-    axisColor: '#13dfff',
-    arcColor: '#ff7a1a',
-    axisLineRadiusScale: 0.03,
-    arcLineRadiusScale: 0.022,
-  },
-});
-```
-
-```ts
-viewConfig(options?: ViewConfigOptions): void
-```
-
-#### `explodeView()` — Configure how the viewport explode slider offsets returned objects.
+#### `explodeView(options?: ExplodeViewOptions): void` — Configure how the viewport explode slider offsets returned objects.
 
 Offsets are resolved from the returned object tree, not a flat list. In `radial` mode each node follows its parent branch direction, then fans locally from the immediate parent center — nested assemblies peel apart level by level. In fixed-axis or fixed-vector modes, the branch follows that axis/vector but nested descendants fan out perpendicular by default.
 
@@ -232,10 +219,6 @@ explodeView({
 });
 ```
 
-```ts
-explodeView(options?: ExplodeViewOptions): void
-```
-
 **`ExplodeViewOptions`**
 
 | Option | Type | Description |
@@ -253,7 +236,7 @@ explodeView(options?: ExplodeViewOptions): void
 - `direction?: ExplodeDirection` — Direction mode for this node
 - `axisLock?: ExplodeAxis` — Optional axis lock after direction is resolved
 
-#### `compareWith()` — Declare a reference model for comparison inspection.
+#### `compareWith(path: string, options?: CompareWithOptions): void` — Declare a reference model for comparison inspection.
 
 `compareWith()` lets a model carry its own comparison target for inspection workflows. `forgecad inspect compare overlay model.forge.js` uses this reference to render the same Difference Only comparison overlay as the live viewport. Amber marks candidate mismatch evidence, cyan marks reference mismatch evidence, and faint model context keeps the overlay readable. When the CLI can resolve the referenced file, the manifest also includes the same geometric score produced by `forgecad compare 3d`.
 
@@ -264,10 +247,6 @@ compareWith('./reference.3mf', { align: 'center', toleranceMm: 0.25, samples: 30
 return rebuiltBearing;
 ```
 
-```ts
-compareWith(path: string, options?: CompareWithOptions): void
-```
-
 **`CompareWithOptions`**
 
 | Option | Type | Description |
@@ -279,6 +258,11 @@ compareWith(path: string, options?: CompareWithOptions): void
 
 #### `cutPlane()` — Define a named section plane for inspecting internal geometry.
 
+Overloads:
+
+- `cutPlane(name: string, normal: Vec3, offset?: number, options?: CutPlaneOptions): void`
+- `cutPlane(name: string, normal: Vec3, options?: CutPlaneOptions): void`
+
 Registers a cut plane that appears as a toggle in the viewport View Panel. When enabled, geometry on the positive side of the plane (the side the normal points toward) is clipped away, revealing the internal cross-section. The newly exposed section faces render with a hatched overlay; pre-existing coplanar boundary faces are left unhatched.
 
 Planes are registered once per script run. The viewport toggle state (on/off) persists across parameter changes without re-running the script. The `exclude` option only works correctly when the excluded object names are stable across parameter changes.
@@ -290,16 +274,11 @@ const cutZ = param('Cut Height', 10, { min: -50, max: 50, unit: 'mm' });
 cutPlane('Inspection', [0, 0, 1], cutZ, { exclude: ['Probe', 'Fasteners'] });
 ```
 
-Overloads:
-
-- `cutPlane(name: string, normal: [ number, number, number ], offset?: number, options?: CutPlaneOptions): void`
-- `cutPlane(name: string, normal: [ number, number, number ], options?: CutPlaneOptions): void`
-
 **`CutPlaneOptions`**
 - `offset?: number` — Optional offset along the plane normal (primarily for object-form overload).
 - `exclude?: CutPlaneExcludeInput` — Object names to keep uncut for this plane.
 
-#### `mock()` — Register a mock (context) object for visualization and inspection.
+#### `mock<T extends Shape>(shape: T, name?: string): T` — Register a mock (context) object for visualization and inspection.
 
 Mock objects appear in the viewport and inspection analysis when you run a file directly, but are excluded when the file is imported via [`require()`](/docs/core#require). This lets you model the surrounding context — walls, bolts, mating parts — without polluting the module's exports.
 
@@ -322,174 +301,47 @@ return bracket;
 // When run directly: bracket + wall + bolt all visible
 ```
 
-```ts
-mock<T extends Shape>(shape: T, name?: string): T
-```
-
-#### `showLabels()` — Highlight all user-labeled faces on a shape for visual debugging.
-
-Shows each user-authored label name in the viewport for visual debugging. Returns the shape unchanged for chaining: `return showLabels(myShape)`.
-
-```ts
-showLabels(shape: Shape): Shape
-```
-
-#### `highlight()` — Highlight any geometry for visual debugging in the viewport.
-
-Supported inputs:
-
-- `string` — sketch entity ID (e.g. `'L0'`, `'P0'`, `'C0'`)
-- `[x, y, z]` — 3D point
-- `[[x1,y1,z1], [x2,y2,z2]]` — edge (line segment)
-- `{ normal: [x,y,z], offset: number }` — plane by normal + distance from origin
-- `{ normal: [x,y,z], point: [x,y,z] }` — plane by normal + point on plane
-- [`Shape`](/docs/core#shape) — highlight entire 3D shape
-- `FaceRef` (from `shape.face('top')`) — highlight as plane at face center
-- `EdgeRef` (from `shape.edge('left')`) — highlight as edge segment
-
-Overloads:
-
-- `highlight(entityId: string, opts?: HighlightOptions): void`
-- `highlight(point: [ number, number, number ], opts?: HighlightOptions): void`
-- `highlight(edge: [ [ number, number, number ], [ number, number, number ] ], opts?: HighlightOptions): void`
-- `highlight(plane: { normal: [ number, number, number ]; offset: number; }, opts?: HighlightOptions): void`
-- `highlight(plane: { normal: [ number, number, number ]; point: [ number, number, number ]; }, opts?: HighlightOptions): void`
-- `highlight(shape: Shape, opts?: HighlightOptions): void`
-- `highlight(face: FaceRef, opts?: HighlightOptions): void`
-- `highlight(edge: EdgeRef, opts?: HighlightOptions): void`
-
-**`HighlightOptions`**
-- `size?: number` — Size hint for points (radius in mm) or planes (disc radius in mm).
-- Also: `color?: string, label?: string, pulse?: boolean`
-
-**`FaceRef`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `normal` | `[ number, number, number ]` | Normal direction of the face |
-| `center` | `[ number, number, number ]` | Center point of the face |
-| `query?` | `FaceQueryRef` | Compiler-owned face query when available. |
-| `planar?` | `boolean` | True when the face can host a 2D sketch placement frame |
-| `uAxis?` | `[ number, number, number ]` | Face-local horizontal axis for planar faces |
-| `vAxis?` | `[ number, number, number ]` | Face-local vertical axis for planar faces |
-| `surface?` | `FaceSurface` | Analytic surface family when the backend can identify one. |
-| `descendant?` | `FaceDescendantMetadata` | Shared descendant-resolution metadata when this face is a semantic region/set. |
-| `name` | | — |
-
-**`FaceDescendantMetadata`**: `kind: "single" | "face-set"`, `semantic: FaceDescendantSemantic`, `memberCount: number`, `memberNames: string[]`, `coplanar: boolean`
-
-**`EdgeRef`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `start` | `[ number, number, number ]` | Start point |
-| `end` | `[ number, number, number ]` | End point |
-| `query?` | `EdgeQueryRef` | Compiler-owned edge query when available. |
-| `curve?` | `EdgeCurve` | Exact or parametric curve family when the backend/source can identify one. |
-| `faceName?` | `string` | Owning face name when the edge is associated with one face in a larger topology. |
-| `name` | | — |
-
 ---
 
 ## Classes
 
 ### `RouteBuilder`
 
-#### `up()` — Vertical line going +Y. Length is optional (solver determines it from constraints).
-
-```ts
-up(length?: number): LineId
-```
-
-#### `down()` — Vertical line going -Y. Length is optional.
-
-```ts
-down(length?: number): LineId
-```
-
-#### `right()` — Horizontal line going +X. Length is optional.
-
-```ts
-right(length?: number): LineId
-```
-
-#### `left()` — Horizontal line going -X. Length is optional.
-
-```ts
-left(length?: number): LineId
-```
+#### `up(length?: number): LineId` — Vertical line going +Y. Length is optional (solver determines it from constraints).
 
-#### `lineAt()` — Line at an arbitrary angle (degrees from +X). Length is optional.
+#### `down(length?: number): LineId` — Vertical line going -Y. Length is optional.
 
-```ts
-lineAt(angleDeg: number, length?: number): LineId
-```
+#### `right(length?: number): LineId` — Horizontal line going +X. Length is optional.
 
-#### [`line()`](/docs/sketch#line) — Line with solver-determined direction. Length is optional. Direction comes from tangency to previous arc or from constraints.
+#### `left(length?: number): LineId` — Horizontal line going -X. Length is optional.
 
-```ts
-line(length?: number): LineId
-```
+#### `lineAt(angleDeg: number, length?: number): LineId` — Line at an arbitrary angle (degrees from +X). Length is optional.
 
-#### `toward()` — Line toward a specific point. Length defaults to the distance to that point.
+#### `line(length?: number): LineId` — Line with solver-determined direction. Length is optional. Direction comes from tangency to previous arc or from constraints.
 
-```ts
-toward(x: number, y: number): LineId
-```
+#### `toward(x: number, y: number): LineId` — Line toward a specific point. Length defaults to the distance to that point.
 
-#### `arcLeft()` — Tangent arc turning left relative to travel direction.
+#### `arcLeft(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId` — Tangent arc turning left relative to travel direction.
 
 or `{ minSweep: degrees }` to seed the geometry without constraining. `minSweep` guides the solver to the correct branch for arcs that sweep more than the default 90° seed.
 
-```ts
-arcLeft(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId
-```
-
-#### `arcRight()` — Tangent arc turning right relative to travel direction.
+#### `arcRight(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId` — Tangent arc turning right relative to travel direction.
 
 or `{ minSweep: degrees }` to seed without constraining.
 
-```ts
-arcRight(radius?: number, sweepDegOrOpts?: number | { minSweep: number; }): ArcId
-```
-
-#### `close()` — Close the route with a straight line back to the start point.
-
-```ts
-close(): void
-```
+#### `close(): void` — Close the route with a straight line back to the start point.
 
-#### `done()` — Close the route back to its start point and register as a profile loop.
+#### `done(): void` — Close the route back to its start point and register as a profile loop.
 
 No extra line segment is added. A coincident constraint connects the last point to the start, and tangency is added for G1 smoothness when arcs are at the junction. The session's incremental solver processes these constraints, keeping seed positions accurate for the final solve.
 
-```ts
-done(): void
-```
-
-#### `start()` — PointId of the route's start point.
-
-```ts
-get start(): PointId
-```
-
-#### `end()` — PointId of the current cursor (route's end).
+#### `get start(): PointId` — PointId of the route's start point.
 
-```ts
-get end(): PointId
-```
-
-#### `startOf()` — Get the start point of a segment.
-
-```ts
-startOf(segId: LineId | ArcId): PointId
-```
+#### `get end(): PointId` — PointId of the current cursor (route's end).
 
-#### `endOf()` — Get the end point of a segment.
+#### `startOf(segId: LineId | ArcId): PointId` — Get the start point of a segment.
 
-```ts
-endOf(segId: LineId | ArcId): PointId
-```
+#### `endOf(segId: LineId | ArcId): PointId` — Get the end point of a segment.
 
 ---
 

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

@@ -36,59 +36,23 @@ WoodBoard operations are immutable. Joint operations return new boards instead o
 
 **Methods:**
 
-#### `cut()` — Subtract a cutter from this board, returning a new board. Used by joint functions (dado, rabbet, mortiseAndTenon).
+#### `cut(cutter: Shape): WoodBoard` — Subtract a cutter from this board, returning a new board. Used by joint functions (dado, rabbet, mortiseAndTenon).
 
-```ts
-cut(cutter: Shape): WoodBoard
-```
+#### `translate(x: number, y: number, z: number): WoodBoard` — Translate the board in 3D space.
 
-#### `translate()` — Translate the board in 3D space.
+#### `rotate(axis: Vec3, angleDeg: number, options?: { pivot?: Vec3; }): WoodBoard` — Rotate the board around an axis by a given angle in degrees.
 
-```ts
-translate(x: number, y: number, z: number): WoodBoard
-```
+#### `rotateX(angleDeg: number): WoodBoard` — Rotate the board around the X axis by a given angle in degrees.
 
-#### `rotate()` — Rotate the board around an axis by a given angle in degrees.
+#### `rotateY(angleDeg: number): WoodBoard` — Rotate the board around the Y axis by a given angle in degrees.
 
-```ts
-rotate(axis: [ number, number, number ], angleDeg: number, options?: { pivot?: [ number, number, number ]; }): WoodBoard
-```
+#### `rotateZ(angleDeg: number): WoodBoard` — Rotate the board around the Z axis by a given angle in degrees.
 
-#### `rotateX()` — Rotate the board around the X axis by a given angle in degrees.
+#### `mirror(normal: Vec3): WoodBoard` — Mirror the board across a plane defined by its normal.
 
-```ts
-rotateX(angleDeg: number): WoodBoard
-```
+#### `color(value: string): WoodBoard` — Set the board's display color.
 
-#### `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
-```
+#### `clone(): WoodBoard` — Clone the board (creates an independent copy of the underlying shape).
 
 ---
 
@@ -102,7 +66,15 @@ Woodworking namespace — create boards and cut joints.
 
 **Joints:** `Wood.dado()`, `Wood.rabbet()`, and `Wood.mortiseAndTenon()` are immutable — they return new board value(s) with the joint cut applied.
 
-- `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): WoodBoard` — Cut a dado (channel) across the face of a host board for a guest board to sit in. Returns a new host board with the dado cut applied.
-- `rabbet(board: WoodBoard, opts: RabbetOptions): WoodBoard` — Cut a rabbet (L-shaped step) along an edge of a board. Returns a new board with the rabbet cut applied.
-- `mortiseAndTenon(mortiseBoard: WoodBoard, tenonBoard: WoodBoard, opts?: MortiseAndTenonOptions): MortiseAndTenonResult` — Cut a mortise in one board and shape a tenon on another. Returns new boards with the mortise pocket and tenon cuts applied.
+- `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): WoodBoard` — Cut a dado (channel) across the face of a host board for a guest board to sit in.
+
+  Returns a new host board with the dado cut applied.
+- `rabbet(board: WoodBoard, opts: RabbetOptions): WoodBoard` — Cut a rabbet (L-shaped step) along an edge of a board.
+
+  Returns a new board with the rabbet cut applied.
+- `mortiseAndTenon(mortiseBoard: WoodBoard, tenonBoard: WoodBoard, opts?: MortiseAndTenonOptions): MortiseAndTenonResult` — Cut a mortise in one board and shape a tenon on another.
+
+  Returns new boards with the mortise pocket and tenon cuts applied.

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

@@ -3,48 +3,10 @@ skill-group: geometry
 skill-order: 1
 ---
 
-# Coordinate System Convention
+# Coordinate System
 
-ForgeCAD uses a **Z-up** right-handed coordinate system.
+Z-up right-handed: +X right, +Y back, +Z up. Ground plane is XY at Z = 0; extrusion goes along +Z. Units are millimeters; angles are degrees.
 
-For objects with a clear facing direction, model the front/face/nose/camera side toward **-Y**. The rear/back side is **+Y**. In code, a forward/fore direction vector is `[0, -1, 0]`.
+Model fronts (face/nose/camera side) point toward **-Y**; rear is +Y; the forward vector is `[0, -1, 0]`. Anchors follow: `front` resolves to the minimum-Y side, `back` to the maximum-Y side.
 
-## Axes
-
-| Axis | Direction       | Positive |
-|------|-----------------|----------|
-| X    | Left / Right    | Right    |
-| Y    | Front / Back    | Back     |
-| Z    | Up / Down       | Up       |
-
-## Standard Views
-
-The camera position direction says where the camera sits relative to the model. A front view camera sits at `-Y` and looks toward `+Y`, so it sees the model's `-Y` front face.
-
-| View   | Camera position direction | Sees plane |
-|--------|---------------------------|------------|
-| Front  | -Y                        | XZ         |
-| Back   | +Y                        | XZ         |
-| Right  | +X                       | YZ         |
-| Left   | -X                       | YZ         |
-| Top    | +Z                       | XY         |
-| Bottom | -Z                       | XY         |
-
-## GizmoViewcube Face Mapping
-
-Renderer/view-cube internals may have their own material ordering. Map any view-cube labels to the ForgeCAD directions below:
-
-| Direction | ForgeCAD label |
-|-----------|----------------|
-| +X        | Right          |
-| -X        | Left           |
-| +Y        | Back           |
-| -Y        | Front          |
-| +Z        | Top            |
-| -Z        | Bottom         |
-
-The face/anchor API is the source of truth: `front` resolves to the minimum-Y side and `back` resolves to the maximum-Y side.
-
-## Grid
-
-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.
+A `front` view camera sits on the -Y side looking toward +Y, so it sees the model's front face. The other views follow: back +Y, right +X, left -X, top +Z, bottom -Z.