forgecad 0.9.4 → 0.9.5

package/dist-skill/CONTEXT.md

@@ -25,6 +25,7 @@ Prefer documented primitives, import rules, and placement strategies over invent
 
 - `.forge.js` — parametric part or assembly script; return a `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, array of renderables, or metadata object. Assemblies render directly; do not add `.toGroup()` unless you need `ShapeGroup` behavior.
 - Model the physical artifact, not an educational diagram. Do not add explanatory labels, arrows, legends, or text plaques unless the user explicitly asks for a presentation or teaching view. Product markings are allowed only when they would exist on the real object.
+- Build the real closed CAD first. Do not bake cutaways, sectioned shells, permanently exploded layouts, or hidden-parts views into the default model just to show internals. Use viewer-only cut planes, `explodeView`, object hiding, transparency, or `render inspect` section channels after the artifact exists.
 
 ### Import and composition
 
@@ -58,10 +59,12 @@ Use the CLI to validate, inspect, and export the model the AI is editing. Keep c
 forgecad run path/to/model.forge.js
 forgecad run path/to/model.forge.js --debug-imports
 forgecad run path/to/model.forge.js --backend occt
+forgecad check print path/to/model.forge.js --json
 forgecad check params path/to/model.forge.js --samples 12
 ```
 
 - `forgecad run` prints geometry diagnostics, object summaries, collisions, verification results, and solver info.
+- `forgecad check print` reports collisions, mesh health, sampled walls, overhangs, and bed contact.
 - `forgecad check params` sweeps declared parameter ranges and reports crashes, degenerates, and new collisions.
 
 ## Visual Checks
@@ -126,7 +129,7 @@ Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class S
 
 - Scripts re-execute on every parameter change (400ms debounce)
 - Geometry operations are **immutable** — shapes, sketches, groups, imported assemblies, and wood boards return new values instead of modifying in place
-- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
+- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, tags?, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
 
 Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD solves it at default joint values for display. Return `assembly.solve(state)` when you want a specific pose. Do not call `.toGroup()` just to make an assembly render — use `.toGroup()` only when you specifically need `ShapeGroup` composition, group-style transforms, or named-child lookup.
 
@@ -159,6 +162,16 @@ return {
 };
 ```
 
+Named return objects and named `group(...)` children can include `tags`. Tags are viewport metadata: they do not affect geometry, exports, face labels, or BOM rows, but the command palette can hide, show only, or focus every object with a selected tag.
+
+```javascript
+return [
+  { name: 'Base Plate', tags: ['printed', 'structural'], shape: base },
+  { name: 'M4 Bolt A', tags: 'fastener', shape: boltA },
+  { name: 'M4 Bolt B', tags: 'fastener', shape: boltB },
+];
+```
+
 ## Coordinate System
 
 Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
@@ -218,15 +231,15 @@ For organic shapes, smooth blending, TPMS lattices, and surface deformations. Re
 - [Grouping & Local Coordinates](#grouping-local-coordinates) — `group`
 - [Section & Projection](#section-projection) — `intersectWithPlane`, `faceProfile`, `projectToPlane`
 - [Transforms](#transforms) — `composeChain`
-- [Backend Runtime](#backend-runtime) — `initKernel`, `setActiveBackend`, `activateBackend`, `getActiveBackend`
 - [Verification](#verification) — `spec`
 - [Shape](#shape) — Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
 - [Transform](#transform)
 - [ShapeGroup](#shapegroup) — Children, Transforms, Placement, Connectors, References
 - [SurfacePattern](#surfacepattern)
+- [Pattern2D](#pattern2d)
+- [Pattern2DBuilder](#pattern2dbuilder)
 - [ShapeRef](#shaperef)
 - [ANCHOR3D_NAMES](#anchor3d-names)
-- [DEFAULT_ACTIVE_BACKEND](#default-active-backend)
 - [verify](#verify)
 - [Constraint](#constraint)
 - [Points](#points)
@@ -321,9 +334,11 @@ intersection(...inputs: ShapeOperandInput[]): Shape
 
 ### Edge Features
 
-#### `fillet()` — Apply fillets (rounded edges) to one or more edges of a shape.
+#### `fillet()` — Apply experimental fillets (rounded edges) to one or more edges of a shape.
 
-Works on edge selections from any active backend. Truck and OCCT route edge finishes through native kernel operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
+**Experimental**: fillets are still backend-sensitive. The Manifold backend is known to produce incorrect results for some edge-finish cases, and the OCCT backend can be very slow, especially with broad edge selections. Prefer targeted edge selectors and inspect the result before treating it as production-ready geometry.
+
+Edge selections compile into backend operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
 
 The `edges` parameter is flexible:
 
@@ -349,9 +364,11 @@ fillet(myShape, 3, edges)
 fillet(shape: Shape, radius: number, edges?: EdgeSelector, segments?: number): Shape
 ```
 
-#### `chamfer()` — Apply chamfers (beveled edges) to one or more edges of a shape.
+#### `chamfer()` — Apply experimental chamfers (beveled edges) to one or more edges of a shape.
+
+**Experimental**: chamfers are still backend-sensitive. The Manifold backend is known to produce incorrect results for some edge-finish cases, and the OCCT backend can be very slow, especially with broad edge selections. Prefer targeted edge selectors and inspect the result before treating it as production-ready geometry.
 
-Produces a 45° bevel at the specified `size` (distance from edge). Works on edge selections from any active backend. Truck and OCCT route chamfers through native kernel operations; unsupported selections fail as explicit kernel gaps instead of using TypeScript geometry fallbacks.
+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.
 
 The `edges` parameter accepts the same options as `fillet()`: inline `EdgeQuery`, pre-selected `EdgeSegment`/`EdgeSegment[]`, or `undefined` (all sharp edges).
 
@@ -576,11 +593,8 @@ selectEdges(shape: Shape, query?: EdgeQuery): EdgeSegment[]
 | `normalA` | `Vec3` | Normal of first adjacent face. |
 | `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
 | `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
-| `nativeTopology?` | `EdgeNativeTopologyRef` | Native kernel topology identity when the active backend can provide one. |
 | `start`, `end`, `midpoint`, `length` | | — |
 
-`EdgeNativeTopologyRef`: `{ backend: "truck", edge: number }`
-
 #### `selectEdge()` — Select the single best-matching edge from a shape.
 
 When `near` is specified, returns the edge whose midpoint is closest to that point. Otherwise returns the first matching edge in mesh order. Throws if no edges match the query — useful as a guard when you expect exactly one result.
@@ -681,7 +695,7 @@ importSvgSketch(fileName: string, options?: SvgImportOptions): Sketch
 importMesh(fileName: string, options?: { scale?: number; center?: boolean; }): Shape
 ```
 
-#### `importStep()` — Import a STEP file (.step, .stp) as an exact OCCT-backed Shape. Preserves NURBS curves, B-spline surfaces, and exact topology. Requires `setActiveBackend('occt')`.
+#### `importStep()` — 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.
 
 ```ts
 importStep(fileName: string): Shape
@@ -817,18 +831,21 @@ Param.list<T extends Record<string, number | boolean | string>>(name: string, de
 
 Unlike union(), child colors and individual identities are preserved. Children can be plain shapes, named descriptors ({ name, shape/sketch/group }), or nested groups. The returned ShapeGroup supports all Shape transforms (translate, rotate, etc.).
 
+Named descriptors can include `tags` for viewport organization. Tags do not affect geometry; they let the command palette hide, show only, or focus all objects with the same tag.
+
 **Local coordinate pattern:** Build child parts at the origin (local coordinates), then group and translate once to place the whole assembly. This eliminates the error-prone pattern of manually adding parent offsets to every sub-part.
 
 ```js
-// BAD — every sub-part repeats the parent's global offset
-const unitX = 0, unitY = -18, unitZ = 70;
-const body = roundedBox(100, 20, 32, 4).translate(unitX, unitY, unitZ);
-const panel = box(98, 2, 18).translate(unitX, unitY - 12, unitZ + 4);
-const louver = box(88, 2, 6).translate(unitX, unitY - 14, unitZ - 11);
+const body = roundedBox(100, 20, 32, 4);
+const panel = box(98, 2, 18).translate(0, -12, 4);
+const louver = box(88, 2, 6).translate(0, -14, -11);
+const indoorUnit = group(
+  { name: 'Body', shape: body },
+  { name: 'Panel', tags: 'cover', shape: panel },
+  { name: 'Louver', tags: ['cover', 'moving'], shape: louver },
+).translate(0, -18, 70);
 ```
 
-// GOOD — build at origin, group, translate once const body = roundedBox(100, 20, 32, 4); const panel = box(98, 2, 18).translate(0, -12, 4); const louver = box(88, 2, 6).translate(0, -14, -11); const indoorUnit = group( { name: 'Body', shape: body }, { name: 'Panel', shape: panel }, { name: 'Louver', shape: louver }, ).translate(0, -18, 70);
-
 ```ts
 group(...items: GroupInput[]): ShapeGroup
 ```
@@ -863,32 +880,6 @@ projectToPlane(shape: Shape, plane: PlaneSpec): Sketch
 composeChain(...steps: TransformInput[]): Transform
 ```
 
-### Backend Runtime
-
-#### `initKernel()`
-
-```ts
-initKernel(): Promise<unknown>
-```
-
-#### `setActiveBackend()`
-
-```ts
-setActiveBackend(backend: ActiveBackend): void
-```
-
-#### `activateBackend()` — Set the active backend and ensure its WASM module is initialized. Call this instead of `setActiveBackend` when you're about to execute code — it guarantees the backend is ready, not just selected.
-
-```ts
-activateBackend(backend: ActiveBackend): Promise<void>
-```
-
-#### `getActiveBackend()`
-
-```ts
-getActiveBackend(): ActiveBackend
-```
-
 ### Verification
 
 #### `spec()` — Create a named, reusable bundle of verification checks.
@@ -1874,6 +1865,82 @@ color(hex: string): ShapeGroup
 | `body` | `string` | Function body: receives (u, v) in surface mm, returns height displacement. |
 | `constants` | `Record<string, number>` | Named constants injected into the function. |
 
+### `Pattern2D`
+
+#### `add()` — Add this pattern to one or more patterns or constant height offsets.
+
+```ts
+add(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `subtract()` — Subtract another pattern or constant height offset from this pattern.
+
+```ts
+subtract(pattern: Pattern2DInput): Pattern2D
+```
+
+#### `multiply()` — Multiply this pattern by one or more patterns or numeric scale factors.
+
+```ts
+multiply(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `min()` — Keep the lower height between this pattern and one or more other patterns.
+
+```ts
+min(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `max()` — Keep the higher height between this pattern and one or more other patterns.
+
+```ts
+max(...patterns: Pattern2DInput[]): Pattern2D
+```
+
+#### `clamp()` — Limit pattern height to the inclusive `[min, max]` range in millimeters.
+
+```ts
+clamp(min: number, max: number): Pattern2D
+```
+
+#### `abs()` — Convert negative heights to positive heights.
+
+```ts
+abs(): Pattern2D
+```
+
+#### `negate()` — Flip the pattern height sign.
+
+```ts
+negate(): Pattern2D
+```
+
+### `Pattern2DBuilder`
+
+#### `constant()` — Create a constant-height pattern in millimeters.
+
+```ts
+constant(value?: number): Pattern2D
+```
+
+#### `sineWave()` — Create a sinusoidal wave pattern in UV space.
+
+```ts
+sineWave(options: Pattern2DSineWaveOptions): Pattern2D
+```
+
+#### `stripes()` — Create recessed stripe bands in UV space.
+
+```ts
+stripes(options: Pattern2DStripesOptions): Pattern2D
+```
+
+#### `overUnderWeave()` — Create an over-under woven relief pattern in UV space.
+
+```ts
+overUnderWeave(options: Pattern2DOverUnderWeaveOptions): Pattern2D
+```
+
 ### `ShapeRef`
 
 A first-class reference path over a shape's semantic faces and face relationships.
@@ -1996,10 +2063,6 @@ toString(): string
 
 ### `ANCHOR3D_NAMES`
 
-### `DEFAULT_ACTIVE_BACKEND`
-
-Default geometry backend when no explicit backend is selected.
-
 ### `verify`
 
 - `that(label: string, check: () => boolean, message?: string): void` — Custom predicate check.
@@ -4125,7 +4188,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 ## Contents
 
 - [Curves & Surfacing](#curves-surfacing) — `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
-- [Surface Members](#surface-members) — `surfaceBand`, `compileSurfaceMember`, `SurfaceBody`
+- [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
@@ -4142,7 +4205,6 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [ProductSpoutBuilder](#productspoutbuilder)
 - [ProductHandleBuilder](#producthandlebuilder)
 - [ProductHandleFeature](#producthandlefeature)
-- [ProductRibbonBuilder](#productribbonbuilder)
 - [CylinderCarrier](#cylindercarrier)
 - [PlaneCarrier](#planecarrier)
 - [ProductSkinCarrier](#productskincarrier)
@@ -4490,11 +4552,8 @@ connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptio
 | `normalA` | `Vec3` | Normal of first adjacent face. |
 | `normalB` | `Vec3` | Normal of second adjacent face (same as normalA for boundary edges). |
 | `boundary` | `boolean` | true if this is a boundary (unmatched) edge — unusual for closed solids. |
-| `nativeTopology?` | `EdgeNativeTopologyRef` | Native kernel topology identity when the active backend can provide one. |
 | `start`, `end`, `midpoint`, `length` | | — |
 
-`EdgeNativeTopologyRef`: `{ backend: "truck", edge: number }`
-
 
 **`ConnectEdgesOptions`** extends TransitionSurfaceOptions
 
@@ -4517,63 +4576,6 @@ connectEdges(edgeA: EdgeSegment, edgeB: EdgeSegment, options?: ConnectEdgesOptio
 surfaceBand<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>
 ```
 
-#### `compileSurfaceMember()`
-
-```ts
-compileSurfaceMember<C extends SurfaceCoordinate>(input: Omit<SurfaceMemberSpec<C>, "section"> & { section: MemberSection | MemberSectionInput; }): CompiledSurfaceMember
-```
-
-**`SurfaceMemberSpec`**: `name: string`, `kind: SurfaceMemberKind`, `path?: SurfacePath<C> | SurfacePathBuilder<C>`, `anchor?: SurfaceAnchor<C>`, `size?: { width: number; height: number; }`, `section: MemberSection`, `features: MemberFeature[]`, `capStyle?: SurfaceBandCap`, `explicitAnchors?: SurfaceMemberExplicitAnchor<C>[]`
-
-`SurfaceAnchor`: `{ carrier: CarrierSurface<C>, coordinate: C }`
-
-`CarrierSurface`: `{ name: string, kind: SurfaceCarrierKind }`
-
-**`MemberSection`**: `width?: number`, `thickness: number`, `edgeRadius: number`, `direction: MemberOutwardDirection`, `material?: ProductMaterial`, `stations: MemberSectionStation[]`
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-`MemberSectionStation`: `{ t: number, width?: number, thickness?: number }`
-
-**`MemberFeature`**: `type: MemberFeatureType`, `name?: string`, `length?: number`, `width?: number`, `diameter?: number`, `counterboreDiameter?: number`, `clearanceDiameter?: number`, `height?: number`, `depth?: number`, `count?: number`, `along?: number`, `across?: number`, `verticalTravel?: number`
-
-`SurfaceMemberExplicitAnchor`: `{ name: string, coordinate: C, carrierName?: string }`
-
-**`MemberSectionInput`**: `width?: number`, `thickness: number`, `edgeRadius?: number`, `direction?: MemberOutwardDirection`, `material?: ProductMaterial`, `stations?: MemberSectionStation[]`
-
-**`CompiledSurfaceMember`**: `name: string`, `shape: Shape`, `mesh: MemberMesh`, `diagnostics: SurfaceDiagnostic[]`, `anchors: { start?: CompiledSurfaceMemberAnchor; end?: CompiledSurfaceMemberAnchor; center: CompiledSurfaceMemberAnchor; landings?: CompiledSurfaceMemberAnchor[]; boundaries?: CompiledSurfaceMemberAnchor[]; features?: CompiledSurfaceMemberAnchor[]; explicit?: CompiledSurfaceMemberAnchor[]; }`
-
-`MemberMesh`: `{ vertices: Vec3[], triangles: Array<[ number, number, number ]> }`
-
-**`SurfaceDiagnostic`**
-- `code?: SurfaceDiagnosticCode` — Stable machine-readable repair hook. Messages may change; codes should not.
-- Also: `category: "carrier" | "path" | "region" | "member" | "feature" | "join" | "compiler", level: "info" | "warning" | "error", message: string, subject?: string`
-
-**`SurfaceMemberAnchorIR`**: `role: SurfaceMemberAnchorRole`, `kind: "member-end" | "member-center" | "member-landing" | "member-boundary" | "plate-edge" | "plate-center" | "plate-landing" | "feature-center" | "surface-coordinate"`, `name?: string`, `point: Vec3`, `normal?: Vec3`
-
-`CompiledSurfaceMemberAnchor`: `{ frame?: SurfaceFrame }`
-
-**`SurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentAlong: Vec3`, `tangentAcross: Vec3`, `matrix: Mat4`, `carrier: string`, `representation: SurfaceCarrierKind | string`, `coordinate: SurfaceCoordinate`
-
 #### `SurfaceBody()` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
 
 ```js
@@ -5149,18 +5151,6 @@ with(...children: GroupInput[]): ShapeGroup
 integrate(...details: Shape[]): Shape
 ```
 
-#### `diagnostics()` — Return lowering representation, station names, rail names, and warnings.
-
-```ts
-diagnostics(): ProductSkinDiagnostics
-```
-
-**`ProductSkinDiagnostics`**: `representation: ProductSkinRepresentation`, `lowering: string[]`, `warnings: string[]`, `stationNames: string[]`, `railNames: string[]`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `uv()` — Create a side/u/v surface-ref query on this skin.
 
 ```ts
@@ -5216,7 +5206,7 @@ stationAt(vOrAxis: number): { ... }
 frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 ```
 
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
+`ProductSurfaceFrame`: `{ point: Vec3, normal: Vec3, tangentU: Vec3, tangentV: Vec3, matrix: Mat4, skin: string }`
 
 ### `ProductSurfaceRef`
 
@@ -5234,25 +5224,6 @@ frame(query: ProductSkinRefQuery): ProductSurfaceFrame
 frame(overrides?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `with()` — Return a copy of this ref with side/u/v/offset overrides.
 
 ```ts
@@ -5297,31 +5268,12 @@ ref(u?: number, v?: number, offset?: number): ProductSurfaceRef
 uv(u?: number, v?: number, offset?: number): ProductSkinRefQuery
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### `frame()` — Resolve a point/frame on this surface using the builder's side.
 
 ```ts
 frame(query?: Partial<ProductSkinRefQuery>): ProductSurfaceFrame
 ```
 
-**`ProductSurfaceFrame`**: `point: Vec3`, `normal: Vec3`, `tangentU: Vec3`, `tangentV: Vec3`, `matrix: Mat4`, `skin: string`, `representation: ProductSkinRepresentation`
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
 #### `ribbon()` — Start a conformal ribbon on this skin side.
 
 Path points use side-local `u`/`v` coordinates; this builder supplies the side. The returned ProductRibbonBuilder is already bound to the source skin and can be further configured before build(). Use `widthSamples` >= 3 when the ribbon must visibly wrap over curved product sections instead of behaving like a flat strip.
@@ -5399,11 +5351,7 @@ stations(stations: Array<ProductStationBuilder | ProductStationSpec>): this
 
 `ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
 
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
-#### `rails()` — Attach guide rails as ProductSkin IR metadata and diagnostics.
+#### `rails()` — Attach named guide rails for product-skin construction and downstream surface references.
 
 ```ts
 rails(rails: Record<string, ProductRailSpec>): this
@@ -5421,19 +5369,6 @@ rails(rails: Record<string, ProductRailSpec>): this
 ref(name: string, query: ProductSkinRefQuery): this
 ```
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### `refs()` — Publish multiple named semantic surface refs on the skin.
 
 ```ts
@@ -5452,27 +5387,6 @@ uv(side: ProductSkinSide, u?: number, v?: number): ProductSkinRefQuery
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `color()` — Apply a simple color override to the lowered skin.
 
 ```ts
@@ -5485,7 +5399,7 @@ color(color: string): this
 edgeLength(value: number): this
 ```
 
-#### `wall()` — Records a target wall thickness; v1 keeps exterior skin lowering sampled and reports wall as a diagnostic.
+#### `wall()` — Record intended wall thickness for product design metadata. Use explicit shelling when the model needs real inner-wall geometry.
 
 ```ts
 wall(thickness: number): this
@@ -5563,7 +5477,7 @@ circle(diameter: number, options?: { segments?: number; }): this
 custom(sketch: Sketch, width: number, depth: number): this
 ```
 
-#### `crown()` — Stores a semantic crown amount for diagnostics and future rail solving.
+#### `crown()` — Set the station crown amount for soft product-section intent.
 
 ```ts
 crown(amount: number): this
@@ -5575,14 +5489,6 @@ crown(amount: number): this
 toSpec(): ProductStationSpec
 ```
 
-`ProductStationSpec`: `{ name: string, center: Vec3, profile: ProductStationProfile, crown?: number }`
-
-`ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
-
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
 ### `ProductPanelBuilder`
 
 **Properties:**
@@ -5623,27 +5529,6 @@ thickness(thickness: number): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `color()` — Apply a simple color override to the panel.
 
 ```ts
@@ -5666,23 +5551,9 @@ attachTo(ref: ProductRefInput, options?: ProductPanelAttachOptions): Shape
 
 `ProductSurfaceRef`
 
-`ProductAttachOptions`: `{ offset?: number, inset?: number }`
 
 `ProductPanelAttachOptions`: `{ at?: Partial<ProductSkinRefQuery>, thickness?: number, material?: ProductMaterial, color?: string }`
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 ### `ProductRibbonBuilder`
 
 Builder for thin trim, label, grip, and split-line features that bend with a ProductSkin surface.
@@ -5707,56 +5578,9 @@ on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonB
 
 `ProductSkinRefQuery | ProductSurfaceRef`
 
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
+#### `fromRefs()` — Follow explicit surface refs.
 
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductRibbonBuildOptions`** — Options shared by Product.ribbon() builders and Product.surface(...).ribbon(...).
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `width?` | `number` | Width across the surface in millimeters. |
-| `thickness?` | `number` | Solid thickness outward from the source surface in millimeters. |
-| `offset?` | `number` | Positive clearance between the source surface and the ribbon's inner face. |
-| `samples?` | `number` | Samples along the ribbon path. Higher values bend more smoothly. |
-| `widthSamples?` | `number` | Samples across the ribbon width. Use 3+ to visibly wrap over curved cross-sections. |
-| `resolution?` | `number` | Tessellation resolution passed to the lowered NURBS surface. |
-| `material?` | `ProductMaterial` | Apply a product material preset to the ribbon. |
-| `color?` | `string` | Apply a simple color override. |
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-#### `fromRefs()` — Follow explicit surface refs.
-
-Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
+Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
 
 ```ts
 fromRefs(points: ProductSurfaceRef[], options?: ProductRibbonBuildOptions): this
@@ -5816,48 +5640,6 @@ color(color: string): this
 build(options?: ProductRibbonBuildOptions): Shape
 ```
 
-#### `buildWithDiagnostics()` — Build a conformal ribbon and return surface-feature diagnostics.
-
-Use this while validating API usage or model fidelity; diagnostics report sampling counts, side-span clamping, lowering mode, and warnings that should be visible in reviews.
-
-```ts
-buildWithDiagnostics(options?: ProductRibbonBuildOptions): ProductRibbonResult
-```
-
-**`ProductRibbonResult`** — Shape plus diagnostics returned by ProductRibbonBuilder.buildWithDiagnostics().
-- `shape: Shape` — Lowered conformal ribbon shape.
-- `diagnostics: ProductRibbonDiagnostics` — Sampling and lowering diagnostics for the returned shape.
-
-**`ProductRibbonDiagnostics`** — Diagnostics describing how a conformal ribbon was sampled and lowered.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Ribbon shape name. |
-| `skin?` | `string` | Source skin name when the ribbon follows a ProductSkin directly. |
-| `side?` | `ProductSkinSide` | Source skin side when all path points are on one semantic side. |
-| `pathPointCount` | `number` | Number of control path points supplied before interpolation. |
-| `width` | `number` | Final ribbon width in millimeters. |
-| `thickness` | `number` | Final ribbon solid thickness in millimeters. |
-| `offset` | `number` | Final normal offset from the source surface in millimeters. |
-| `samples` | `number` | Final sample count along the ribbon path. |
-| `widthSamples` | `number` | Final sample count across the ribbon width. |
-| `resolution` | `number` | NURBS tessellation resolution used for the lowered surface. |
-| `lowering` | `"nurbsSurface"` | Lowering primitive used for the ribbon shape. |
-| `expectedFidelity` | `ProductSkinRepresentation` | Expected fidelity inherited from the source skin/ref sampling mode. |
-| `clampedUCount` | `number` | Number of generated width samples clamped to the valid side span. |
-| `maxUClampDistance` | `number` | Largest absolute u-distance lost to side-span clamping. |
-| `warnings` | `string[]` | Non-fatal sampling and lowering warnings. |
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
-#### `diagnostics()` — Return diagnostics from the most recent build, if this builder has been built.
-
-```ts
-diagnostics(): ProductRibbonDiagnostics | undefined
-```
-
 ### `ProductSpoutBuilder`
 
 **Properties:**
@@ -5880,14 +5662,6 @@ from(ref: ProductSurfaceRef): this
 sections(sections: Array<Sketch | ProductStationBuilder | ProductStationSpec>): this
 ```
 
-`ProductStationSpec`: `{ name: string, center: Vec3, profile: ProductStationProfile, crown?: number }`
-
-`ProductStationProfile`: `{ sketch: Sketch, width: number, depth: number, kind: ProductProfileKind, radius?: number, exponent?: number }`
-
-**`ProductProfileKind`**
-
-`"oval" | "roundedRect" | "circle" | "superEllipse" | "custom"`
-
 #### `projection()` — Set the projection length along the source ref normal.
 
 ```ts
@@ -5906,27 +5680,6 @@ edgeLength(value: number): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `color()` — Apply a simple color override to the spout.
 
 ```ts
@@ -5945,8 +5698,6 @@ build(): Shape
 attach(options?: ProductAttachOptions): Shape
 ```
 
-`ProductAttachOptions`: `{ offset?: number, inset?: number }`
-
 ### `ProductHandleBuilder`
 
 **Properties:**
@@ -5969,12 +5720,6 @@ between(upper: ProductSurfaceRef, lower: Vec3): this
 spine(points: Vec3[] | ProductRailSpec): this
 ```
 
-`ProductRailSpec`: `{ kind: ProductRailKind, points: Vec3[], degree?: number, name?: string }`
-
-**`ProductRailKind`**
-
-`"bezier" | "nurbs" | "polyline"`
-
 #### `grip()` — Set the grip cross-section profile.
 
 ```ts
@@ -5987,27 +5732,6 @@ grip(profile: Sketch): this
 material(material: ProductMaterial): this
 ```
 
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
 #### `padMaterial()` — Apply a product material preset to handle landing pads.
 
 ```ts
@@ -6056,181 +5780,6 @@ toShape(): Shape
 toGroup(): ShapeGroup
 ```
 
-### `ProductRibbonBuilder`
-
-Builder for thin trim, label, grip, and split-line features that bend with a ProductSkin surface.
-
-**Properties:**
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `name` | `string` | — |
-
-**Methods:**
-
-#### `on()` — Follow a ProductSkin with side/u/v path queries or refs.
-
-This is the highest-fidelity mode because every interpolated sample is resolved through ProductSkin.frame(), so the ribbon bends along the selected side as station width/depth changes. All query path points must stay on one side; split side transitions into separate ribbons.
-
-```ts
-on(skin: ProductSkin, points: ProductRibbonPathPoint[], options?: ProductRibbonBuildOptions): this
-```
-
-**`ProductRibbonPathPoint`** — Path point for Product.ribbon().on(...): either a side/u/v query or a resolved surface ref.
-
-`ProductSkinRefQuery | ProductSurfaceRef`
-
-**`ProductSkinRefQuery`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `side` | `ProductSkinSide` | Side of the product skin. `front` is the minimum axis cap, `rear`/`back` is the maximum axis cap. |
-| `u?` | `number` | Across-side parameter for side refs. Defaults to 0.5. |
-| `v?` | `number` | Along-axis parameter, 0 at the first cap and 1 at the rear/back cap. Defaults to 0.5. |
-| `offset?` | `number` | Positive distance away from the surface along the resolved normal. |
-
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
-**`ProductRibbonBuildOptions`** — Options shared by Product.ribbon() builders and Product.surface(...).ribbon(...).
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `width?` | `number` | Width across the surface in millimeters. |
-| `thickness?` | `number` | Solid thickness outward from the source surface in millimeters. |
-| `offset?` | `number` | Positive clearance between the source surface and the ribbon's inner face. |
-| `samples?` | `number` | Samples along the ribbon path. Higher values bend more smoothly. |
-| `widthSamples?` | `number` | Samples across the ribbon width. Use 3+ to visibly wrap over curved cross-sections. |
-| `resolution?` | `number` | Tessellation resolution passed to the lowered NURBS surface. |
-| `material?` | `ProductMaterial` | Apply a product material preset to the ribbon. |
-| `color?` | `string` | Apply a simple color override. |
-
-`ProductMaterial`: `{ color?: string, material?: ShapeMaterialProps }`
-
-**`ShapeMaterialProps`**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `metalness?` | `number` | Metalness factor (0 = dielectric, 1 = metal). Default: 0.05 |
-| `roughness?` | `number` | Roughness factor (0 = mirror, 1 = fully diffuse). Default: 0.35 |
-| `emissive?` | `string` | Emissive glow color (hex string, e.g. "#ff6b35"). |
-| `emissiveIntensity?` | `number` | Emissive intensity multiplier. Default: 1 |
-| `opacity?` | `number` | Opacity (0 = fully transparent, 1 = fully opaque). Default: 1 |
-| `wireframe?` | `boolean` | Render as wireframe. Default: false |
-| `clearcoat?` | `number` | Clearcoat intensity (0–1). Default: 0.1 |
-| `clearcoatRoughness?` | `number` | Clearcoat roughness (0–1). Default: 0.4 |
-| `transmission?` | `number` | Glass/translucency transmission factor (0–1). Renderer support depends on target. |
-| `ior?` | `number` | Index of refraction for transmissive materials. Typical glass is ~1.45. |
-| `thickness?` | `number` | Approximate transmissive volume thickness in model units. |
-| `specularIntensity?` | `number` | Specular highlight intensity (0–1). |
-| `specularColor?` | `string` | Specular highlight tint. |
-| `reflectivity?` | `number` | Reflection strength for supported renderers (0–1). |
-
-#### `fromRefs()` — Follow explicit surface refs.
-
-Useful for named refs or paths assembled elsewhere. The builder resolves each ref frame and interpolates between those frames; use on(skin, points) when you need full skin-side sampling between sparse control points.
-
-```ts
-fromRefs(points: ProductSurfaceRef[], options?: ProductRibbonBuildOptions): this
-```
-
-#### `width()` — Set ribbon width in millimeters.
-
-```ts
-width(width: number): this
-```
-
-#### `thickness()` — Set solid thickness outward from the source surface in millimeters.
-
-```ts
-thickness(thickness: number): this
-```
-
-#### `offset()` — Set positive clearance between the source surface and the ribbon's inner face.
-
-```ts
-offset(offset: number): this
-```
-
-#### `samples()` — Set samples along the path.
-
-```ts
-samples(samples: number): this
-```
-
-#### `widthSamples()` — Set samples across the width. Use 3+ to bend over curved cross-sections.
-
-```ts
-widthSamples(samples: number): this
-```
-
-#### `resolution()` — Set NURBS tessellation resolution.
-
-```ts
-resolution(resolution: number): this
-```
-
-#### `material()` — Apply a product material preset.
-
-```ts
-material(material: ProductMaterial): this
-```
-
-#### `color()` — Apply a simple color override.
-
-```ts
-color(color: string): this
-```
-
-#### `build()` — Build a conformal ribbon as a thin NURBS surface solid.
-
-```ts
-build(options?: ProductRibbonBuildOptions): Shape
-```
-
-#### `buildWithDiagnostics()` — Build a conformal ribbon and return surface-feature diagnostics.
-
-Use this while validating API usage or model fidelity; diagnostics report sampling counts, side-span clamping, lowering mode, and warnings that should be visible in reviews.
-
-```ts
-buildWithDiagnostics(options?: ProductRibbonBuildOptions): ProductRibbonResult
-```
-
-**`ProductRibbonResult`** — Shape plus diagnostics returned by ProductRibbonBuilder.buildWithDiagnostics().
-- `shape: Shape` — Lowered conformal ribbon shape.
-- `diagnostics: ProductRibbonDiagnostics` — Sampling and lowering diagnostics for the returned shape.
-
-**`ProductRibbonDiagnostics`** — Diagnostics describing how a conformal ribbon was sampled and lowered.
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `name` | `string` | Ribbon shape name. |
-| `skin?` | `string` | Source skin name when the ribbon follows a ProductSkin directly. |
-| `side?` | `ProductSkinSide` | Source skin side when all path points are on one semantic side. |
-| `pathPointCount` | `number` | Number of control path points supplied before interpolation. |
-| `width` | `number` | Final ribbon width in millimeters. |
-| `thickness` | `number` | Final ribbon solid thickness in millimeters. |
-| `offset` | `number` | Final normal offset from the source surface in millimeters. |
-| `samples` | `number` | Final sample count along the ribbon path. |
-| `widthSamples` | `number` | Final sample count across the ribbon width. |
-| `resolution` | `number` | NURBS tessellation resolution used for the lowered surface. |
-| `lowering` | `"nurbsSurface"` | Lowering primitive used for the ribbon shape. |
-| `expectedFidelity` | `ProductSkinRepresentation` | Expected fidelity inherited from the source skin/ref sampling mode. |
-| `clampedUCount` | `number` | Number of generated width samples clamped to the valid side span. |
-| `maxUClampDistance` | `number` | Largest absolute u-distance lost to side-span clamping. |
-| `warnings` | `string[]` | Non-fatal sampling and lowering warnings. |
-
-**`ProductSkinRepresentation`** — Reported lowering mode for ProductSkin and conformal feature diagnostics.
-
-`"exact" | "sampled" | "mixed" | "fallback"`
-
-#### `diagnostics()` — Return diagnostics from the most recent build, if this builder has been built.
-
-```ts
-diagnostics(): ProductRibbonDiagnostics | undefined
-```
-
 ### `CylinderCarrier`
 
 **Properties:**
@@ -6362,12 +5911,6 @@ bounds(): SurfaceBounds
 offset(distance: number): CylinderCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6487,12 +6030,6 @@ bounds(): SurfaceBounds
 offset(distance: number): PlaneCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6517,10 +6054,6 @@ mirrorCoordinate(coordinate: PlaneSurfaceCoordinate): PlaneSurfaceCoordinate
 surface(side: ProductSkinSide): ProductSkinCarrier
 ```
 
-**`ProductSkinSide`** — Semantic side of a ProductSkin. `back` is accepted as an alias for `rear`.
-
-`"left" | "right" | "top" | "bottom" | "front" | "rear" | "back"`
-
 #### [`path()`](/docs/sketch#path)
 
 ```ts
@@ -6609,16 +6142,6 @@ bounds(): SurfaceBounds
 offset(distance: number): ProductSkinCarrier
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(): SurfaceDiagnostic[]
-```
-
-**`SurfaceDiagnostic`**
-- `code?: SurfaceDiagnosticCode` — Stable machine-readable repair hook. Messages may change; codes should not.
-- Also: `category: "carrier" | "path" | "region" | "member" | "feature" | "join" | "compiler", level: "info" | "warning" | "error", message: string, subject?: string`
-
 #### `mirrorCoordinate()`
 
 ```ts
@@ -6761,12 +6284,6 @@ withHole(name: string, input: SurfaceBandHoleInput): SurfaceBand<C>
 holes(): SurfaceBandHoleRegion[]
 ```
 
-#### `diagnostics()`
-
-```ts
-diagnostics(samples?: number): SurfaceDiagnostic[]
-```
-
 ### `SurfaceBodyBuilder`
 
 **Properties:**
@@ -6807,18 +6324,6 @@ autoJoinAtSharedAnchors(): this
 build(): Shape | ShapeGroup
 ```
 
-#### `buildWithDiagnostics()`
-
-```ts
-buildWithDiagnostics(): SurfaceBodyBuildResult
-```
-
-#### `buildDebug()`
-
-```ts
-buildDebug(): SurfaceBodyBuildResult
-```
-
 ### `SurfaceMemberBuilder`
 
 #### `plate()`
@@ -6881,7 +6386,7 @@ cutout(name: string, feature: MemberFeature | RoundedSlotBuilder): this
 counterbore(name: string, feature: MemberFeature | CounterboreBuilder): this
 ```
 
-#### `anchorAt()` — Add a named anchor at a carrier surface coordinate for diagnostics, debug views, and future named-anchor joins.
+#### `anchorAt()` — Add a named anchor at a carrier surface coordinate for explicit member joins.
 
 ```ts
 anchorAt(name: string, coordinate: C | SurfaceAnchor<C>): this
@@ -6929,18 +6434,6 @@ autoJoinAtSharedAnchors(): SurfaceBodyBuilder
 build(): Shape | ShapeGroup
 ```
 
-#### `buildWithDiagnostics()`
-
-```ts
-buildWithDiagnostics(): SurfaceBodyBuildResult
-```
-
-#### `buildDebug()`
-
-```ts
-buildDebug(): SurfaceBodyBuildResult
-```
-
 ### `SurfaceJoinBuilder`
 
 #### `betweenAnchors()` — Select named anchors on the source and target members before lowering this join.
@@ -7023,7 +6516,6 @@ toFeature(name?: string): MemberFeature
 
 - `Edge(options: BlendEdgeOptions): Shape`
 - `Surface(options: BlendSurfaceOptions): Shape`
-- `CornerY(options: BlendCornerYOptions): Shape` — Current implementation uses continuity-controlled edge fillets on solid edges. It does not yet provide a dedicated open-sheet or multi-patch Y-corner solver. Follow progress: https://github.com/KoStard/forgecad-private/issues/162
 
 ### `Analysis`
 
@@ -7062,15 +6554,12 @@ toFeature(name?: string): MemberFeature
 - `cylinder(name: string): CylinderCarrier` — Create an analytic cylinder carrier for bottles, limbs, tubes, guards, and cuffs.
 - `plane(name: string): PlaneCarrier` — Create an analytic plane carrier for plates and local flat construction surfaces.
 - `productSkin(skin: ProductSkin): ProductSkinCarrier` — Adapt an existing ProductSkin into the general surface-member carrier protocol.
-- `mesh(name: string): never` — Reserved stub for future parameterized mesh carriers; arbitrary mesh parameterization is not implemented yet.
-- `scan(name: string): never` — Reserved stub for future scan/body-fit carriers; arbitrary scan parameterization is not implemented yet.
 
 ### `SurfaceMembers`
 
 - `Body(name: string): SurfaceBodyBuilder` — Start a surface-member body builder for straps, inlays, guards, braces, cuffs, and similar physical members that live on a carrier surface.
 - `Band: typeof SurfaceBand`
 - `band<C extends SurfaceCoordinate>(path: SurfacePath<C> | SurfacePathBuilder<C>, width: WidthProfile, cap?: SurfaceBandCap): SurfaceBand<C>`
-- `compileMember<C extends SurfaceCoordinate>(input: Omit<SurfaceMemberSpec<C>, "section"> & { section: MemberSection | MemberSectionInput; }): CompiledSurfaceMember`
 
 ### `Slot`
 
@@ -7114,7 +6603,12 @@ bomToCsv(rows: BomRow[]): string
 
 **`BomRow`**: `part: string`, `qty: number`, `material?: string`, `process?: string`, `tolerance?: string`, `notes?: string`, `metadata?: PartMetadata`
 
-**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+**`PartMetadata`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
+| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
 #### `assembly()` — Create an assembly container with named parts and joints for kinematic mechanisms.
 
@@ -7755,13 +7249,13 @@ toGroup(): ShapeGroup
 Each part becomes `{ name, shape }` or `{ name, group: [...] }` if the part is a [`ShapeGroup`](/docs/core#shapegroup). Top-level scripts should normally return the `SolvedAssembly` directly. Use `toGroup()` when you need [`ShapeGroup`](/docs/core#shapegroup) behavior; use this method only for advanced scene-graph control where you need access to the flat per-part array with metadata.
 
 ```ts
-toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+toSceneObjects(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
 ```
 
 #### `toScene()` — Backward-compatible alias for `toSceneObjects()`.
 
 ```ts
-toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; }>; metadata?: PartMetadata; }>
+toScene(): Array<{ name: string; shape?: Shape; group?: Array<{ name: string; shape: Shape; tags?: string[]; }>; metadata?: PartMetadata; }>
 ```
 
 #### [`bom()`](/docs/output#bom) — Generate a bill of materials for all parts in the solved assembly.
@@ -8522,7 +8016,12 @@ robotExport(options: RobotExportOptions): CollectedRobotExport
 
 `AssemblyPartDef`: `{ name: string, part: AssemblyPart, base: Transform, metadata?: PartMetadata }`
 
-**`PartMetadata`**: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`
+**`PartMetadata`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `tags?` | `string \| readonly string[]` | Viewport organization tags applied to scene objects produced from this part. |
+| `material?`, `process?`, `tolerance?`, `qty?`, `notes?`, `densityKgM3?`, `massKg?` | | — |
 
 **`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`
 
@@ -8630,6 +8129,7 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 ## Contents
 
 - [TangentLoop2D](#tangentloop2d)
+- [DriveWheelBuilder](#drivewheelbuilder)
 - [lib](#lib)
 
 ---
@@ -8670,6 +8170,32 @@ toProfile(): Sketch
 offsetBand(thickness: number): Sketch
 ```
 
+### `DriveWheelBuilder`
+
+#### `addSpurTeethBetween()` — Add an involute spur-tooth window on part of the pitch circle.
+
+```ts
+addSpurTeethBetween(options: DriveWheelSpurTeethRegionOptions): this
+```
+
+#### `addSolidArcBetween()` — Add a constant-radius solid arc region such as a dwell, stop, or pusher.
+
+```ts
+addSolidArcBetween(options: DriveWheelSolidArcRegionOptions): this
+```
+
+#### `addShapeRegion()` — Add a fully custom region shape while preserving region metadata.
+
+```ts
+addShapeRegion(name: string, shape: Shape, options?: DriveWheelShapeRegionOptions): this
+```
+
+#### `build()` — Build the final wheel shape with a bore connector and region metadata.
+
+```ts
+build(): Shape
+```
+
 ---
 
 ## Constants
@@ -8678,7 +8204,7 @@ offsetBand(thickness: number): Sketch
 
 Pre-built parametric parts available in user scripts as `lib.*`.
 
-Every key in this object becomes a method on the `lib` namespace exposed to `.forge.js` scripts. The catalog includes:
+Every key in this object becomes a method or namespace on the `lib` object exposed to `.forge.js` scripts. The catalog includes:
 
 **Fasteners:** `bolt`, `nut`, `washer`, `fastenerSet`, `fastenerHole`, `boltHole`, `counterbore`, `hexNut`, `holePattern`
 
@@ -8688,7 +8214,9 @@ Every key in this object becomes a method on the `lib` namespace exposed to `.fo
 
 **Threads:** `thread`
 
-**Gears:** `spurGear`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair`
+**Gears:** `spurGear`, `sectorGear`, `driveWheel`, `bevelGear`, `faceGear`, `sideGear`, `ringGear`, `rackGear`, `gearPair`, `bevelGearPair`, `faceGearPair`, `sideGearPair`
+
+**Gear bodies:** `gearBodies.disk`, `gearBodies.diskWithHub`, `gearBodies.spoked`, `gearBodies.fromProfile` plus direct aliases `gearBodyDisk`, `gearBodyDiskWithHub`, `gearBodySpoked`, `gearBodyFromProfile`
 
 **Gear ratios (pure math helpers):** `gearRatio`, `rackRatio`, `planetaryRatio`
 
@@ -8696,7 +8224,7 @@ Every key in this object becomes a method on the `lib` namespace exposed to `.fo
 
 **Utilities:** `explode`
 
-Extend this by adding new entries here and registering the corresponding runner binding in `runner.ts`. Sizes outside the supported ranges will throw at runtime with a descriptive error.
+Sizes outside the supported ranges will throw at runtime with a descriptive error.
 
 - `boltHole(diameter: number, depth: number): Shape` — Simple cylindrical through-hole cutter centered on Z=0. Subtract the result from a part to produce a plain cylindrical clearance hole. For ISO metric sizes with fit classes and counterbore/countersink, use {
 - `fastenerHole(opts: FastenerHoleOptions): Shape` — ISO metric fastener hole cutter with optional counterbore or countersink. **Details** Returns a cutter shape (subtract from a solid to produce the hole). Sizes outside M2–M10 will throw. Extend `METRIC_HOLE_TABLE` in this file to add new sizes. **Example** ```ts const plate = box(60, 40, 8) .subtract(lib.fastenerHole({ size: 'M5', fit: 'normal', depth: 8 }) .translate(15, 10, 4)); ```
@@ -8734,6 +8262,14 @@ Extend this by adding new entries here and registering the corresponding runner
 - `rackRatio(module: number, pinionTeeth: number): number` — Coupling ratio between a pinion and a rack. When the pinion rotates by `θ` degrees, the rack slides by `θ × (π × module × teeth / 360)` mm. Equivalently, 1mm of rack travel = `180 / (π × pitchRadius)` degrees of pinion rotation.
 - `planetaryRatio(sunTeeth: number, ringTeeth: number): number` — Planetary gear reduction ratio when the ring is held fixed. Input: sun. Output: carrier. Ratio: `1 + ringTeeth / sunTeeth`. One turn of the sun produces `1 / ratio` turns of the carrier.
 - `boltPattern(options: BoltPatternOptions): BoltPattern` — Define a bolt pattern once and cut it from multiple parts. const base = bolts.cut(box(60, 50, 10), 12, { from: -1 }); const cover = bolts.cut(box(60, 50, 3), 5, { from: -1 }); // Same positions in both parts — guaranteed aligned. ```
+- `driveWheel(options?: DriveWheelOptions): DriveWheelBuilder` — Start a composable exceptional gear or drive wheel.
+- `readDriveWheelMeta(shape: Shape): DriveWheelMeta | null` — Read the functional-region metadata attached by `driveWheel().build()`.
+- `sectorGear(options: SectorGearOptions): Shape` — Involute sector gear with teeth on only part of the pitch circle. Specify the full-circle pitch as `teethOnFullCircle`, then choose the active tooth window with `firstTooth` and `toothCount`. The body is separate from the tooth region: pass a `gearBody...` shape for spokes, hubs, and product styling, or omit it for a simple root-radius disk. **Example** ```ts const body = lib.gearBodies.spoked({ outerRadius: 22, rimWidth: 3, hubDiameter: 10, spokeCount: 5, spokeWidth: 2.5, faceWidth: 8, boreDiameter: 5, }); const sector = lib.sectorGear({ module: 1.25, teethOnFullCircle: 36, toothCount: 10, faceWidth: 8, body, }); ```
+- `gearBodies: { ... }` — Gear body preset namespace: disk, diskWithHub, spoked, and fromProfile.
+- `gearBodyDisk(options: GearBodyDiskOptions): Shape` — Solid disk/ring gear body, independent from any tooth geometry.
+- `gearBodyDiskWithHub(options: GearBodyDiskWithHubOptions): Shape` — Disk gear body with a raised center hub.
+- `gearBodySpoked(options: GearBodySpokedOptions): Shape` — Spoked gear body with an outer rim, center hub, and radial spokes.
+- `gearBodyFromProfile(profile: Sketch, options: GearBodyFromProfileOptions): Shape` — Extrude a custom 2D profile into a gear body.
 
 ---
 
@@ -8903,7 +8439,7 @@ When `lights` is specified, **all** default lights are removed. You must include
 
 Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit 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 `forgecad render 3d model.forge.js --view hero`.
+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`.
 
 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.
 
@@ -8972,7 +8508,6 @@ scene(options: SceneOptions): void
 | `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
 | `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
 | `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
-| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
 
 **`SceneJourneyStepConfig`**
 
@@ -8985,9 +8520,6 @@ scene(options: SceneOptions): void
 | `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
 | `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
 | `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
-| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
-
-`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
 
 **`SceneLightConfig`**
 
@@ -9063,10 +8595,6 @@ viewConfig({
 viewConfig(options?: ViewConfigOptions): void
 ```
 
-`ViewConfigOptions`: `{ jointOverlay?: JointOverlayViewConfigOptions }`
-
-**`JointOverlayViewConfigOptions`**: `enabled?: boolean`, `axisColor?: string`, `axisCoreColor?: string`, `arcColor?: string`, `zeroColor?: string`, `arcVisualLimitDeg?: number`, `axisLengthScale?: number`, `axisLengthMin?: number`, `axisLineRadiusScale?: number`, `axisLineRadiusMin?: number`, `axisLineRadiusMax?: number`, `spokeLineRadiusScale?: number`, `spokeLineRadiusMin?: number`, `spokeLineRadiusMax?: number`, `arcLineRadiusScale?: number`, `arcLineRadiusMin?: number`, `arcLineRadiusMax?: number`, `axisDotRadiusScale?: number`, `axisDotRadiusMin?: number`, `axisArrowRadiusScale?: number`, `axisArrowRadiusMin?: number`, `axisArrowLengthScale?: number`, `axisArrowLengthMin?: number`, `axisArrowOffsetFactor?: number`, `arcRadiusScale?: number`, `arcRadiusMin?: number`, `arcDotRadiusScale?: number`, `arcDotRadiusMin?: number`, `arcArrowRadiusScale?: number`, `arcArrowRadiusMin?: number`, `arcArrowLengthScale?: number`, `arcArrowLengthMin?: number`, `arcArrowOffsetFactor?: number`, `arcStepDeg?: number`, `arcMinSteps?: number`, `arcTubeSegmentsMin?: number`, `arcTubeSegmentsFactor?: number`, `arcTubeRadialSegments?: number`
-
 #### `explodeView()` — 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.
@@ -9576,8 +9104,9 @@ Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that pe
 
 `forgecad render inspect` writes a deterministic directory bundle for agents,
 tests, and automation. Use it when a single shaded PNG is too ambiguous and the
-consumer needs geometry-aware signals such as depth, normals, part identity,
-physical connected components, collisions, local thickness, or cross-sections.
+consumer needs geometry-aware signals such as depth, normals, surface roughness,
+part identity, physical connected components, collisions, local thickness, or
+cross-sections.
 
 ## When To Use It
 
@@ -9597,14 +9126,16 @@ forgecad render inspect model.forge.js --channels rgb,mask,section
 forgecad render inspect model.forge.js --channels collisions --focus Bench
 forgecad render inspect model.forge.js --channels rgb,mask --hide "Bench.Slat0,Bench.Slat1"
 forgecad render inspect model.forge.js --channels thickness --min-thickness 1.2 --warn-thickness 2.0
+forgecad render inspect channels
 ```
 
 The default output directory is `<script-name>-inspect/` next to the input file.
 Pass `--force` to replace an existing bundle directory.
 
 There are no default channels. Pass `--channels` every time as a
-comma-separated subset. Keep bundles targeted to the current question so heavy
-analyses do not run unnecessarily.
+comma-separated subset. Run `forgecad render inspect channels` to list the
+supported channels in the installed CLI. Keep bundles targeted to the current
+question so heavy analyses do not run unnecessarily.
 
 `--focus` and `--hide` use the same object-name filtering semantics as
 `forgecad run` and `forgecad render 3d`. A bare `--focus` hides mock objects;
@@ -9660,12 +9191,13 @@ implemented channel in one bundle:
 
 ```bash
 forgecad render inspect model.forge.js --channels depth,normals
+forgecad render inspect model.forge.js --channels rgb,roughness
 forgecad render inspect model.forge.js --channels rgb,mask,collisions
 forgecad render inspect model.forge.js --channels rgb,section,thickness
 ```
 
-Supported channels are `rgb`, `depth`, `normals`, `mask`, `connectivity`,
-`distance`, `collisions`, `thickness`, and `section`.
+Supported channels are `rgb`, `depth`, `normals`, `roughness`, `mask`,
+`connectivity`, `distance`, `collisions`, `thickness`, and `section`.
 
 ## Channel Semantics
 
@@ -9692,6 +9224,27 @@ normal = normalize((rgb / 255) * 2 - 1)
 
 Background pixels are black and should be treated as `null`.
 
+`roughness` emits a mesh-dihedral surface-quality heatmap. Smooth and gently
+curved triangles render as a faint translucent shadow over black, while
+triangles adjacent to sharp, harsh, boundary, or non-manifold mesh edges render
+in orange or magenta:
+
+```text
+shadow  = max adjacent angle < sharpAngleDeg
+orange  = sharpAngleDeg <= angle < harshAngleDeg
+magenta = angle >= harshAngleDeg, boundary, or non-manifold
+```
+
+The default thresholds are `smoothAngleDeg=5`, `sharpAngleDeg=30`, and
+`harshAngleDeg=90`. The manifest stores the method, thresholds, palette, object
+list, per-object triangle and edge counts, area percentages by smooth,
+moderate, sharp, and harsh classes, angle percentiles, maximum angle, quality
+score, and warnings. Moderate angles are reported in the manifest but stay in
+the shadow layer by default so intentionally curved surfaces do not light up as
+defects. Use this channel to spot spiky tessellation, accidental faceting,
+jagged boolean residue, and dense sharp-corner regions without losing the
+silhouette of otherwise smooth surfaces.
+
 `mask` emits one object-color image per view. Black is background. Non-black
 pixels resolve through `manifest.channels.mask.objects`, which includes object
 index, RGB color, object id, name, group, tree path, and mock flag. Edge pixels
@@ -10026,6 +9579,36 @@ intersect(...others: SdfShape[]): SdfShape
 clipBox(x: number, y: number, z: number): SdfShape
 ```
 
+#### `fillWith()` — Keep only the material where this shape overlaps another SDF pattern.
+
+```ts
+fillWith(pattern: SdfShape): SdfShape
+```
+
+#### `fillWithGyroid()` — Keep only the gyroid lattice inside this shape.
+
+```ts
+fillWithGyroid(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithSchwarzP()` — Keep only the Schwarz-P lattice inside this shape.
+
+```ts
+fillWithSchwarzP(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithDiamond()` — Keep only the diamond TPMS lattice inside this shape.
+
+```ts
+fillWithDiamond(options: TpmsOptions): SdfShape
+```
+
+#### `fillWithLidinoid()` — Keep only the lidinoid TPMS lattice inside this shape.
+
+```ts
+fillWithLidinoid(options: TpmsOptions): SdfShape
+```
+
 #### `smoothUnion()` — Smooth union — blends shapes together with a smooth radius.
 
 ```ts
@@ -10104,6 +9687,14 @@ bend(radius: number): SdfShape
 repeat(spacing: Vec3, count?: Vec3): SdfShape
 ```
 
+#### `circularArray()` — Arrange this SDF in a circular array around the Z axis.
+
+The source shape is translated by `offset` in +X before arraying. This uses angular domain folding, so evaluation stays O(1): the source SDF is sampled twice no matter how many copies are requested.
+
+```ts
+circularArray(count: number, offset?: number): SdfShape
+```
+
 #### `shell()` — Hollow out, keeping only a shell of given thickness.
 
 ```ts
@@ -10116,8 +9707,8 @@ shell(thickness: number): SdfShape
 // Function displacement
 shape.displace((x, y, z) => Math.sin(x) * 0.5)
 
-// Pattern displacement (e.g. basketWeave)
-shape.displace(sdf.basketWeave({ threads: 16, spacing: 3 }))
+// Pattern displacement from a 3D SDF field
+shape.displace(sdf.knurl({ pitch: 2, depth: 0.3 }))
 ```
 
 ```ts
@@ -10130,10 +9721,16 @@ Automatically detects the shape's UV parametrization (sphere, cylinder, torus) f
 
 UV coordinates are in **surface millimeters** — patterns defined with `spacing: 3` always produce 3mm spacing, regardless of shape size.
 
+Prefer `sdf.pattern2d()` or built-in surface patterns when the relief should stay on the native shader and meshing path. Callback functions are supported for experimentation, but they are opaque to the typed pattern optimizer.
+
 ```js
-// Surface-following basket weave — auto-detects sphere UV
+// Native typed pattern — auto-detects sphere UV
+const p = sdf.pattern2d()
+const ribs = p.stripes({ spacing: 3, width: 0.8, depth: 0.35 })
+  .add(p.sineWave({ direction: [0, 1], wavelength: 14, amplitude: 0.08 }))
+
 sdf.sphere(27).shell(3)
-  .surfaceDisplace(sdf.basketWeave({ spacing: 3, depth: 0.8 }))
+  .surfaceDisplace(ribs)
   .toShape()
 
 // Custom 2D pattern via function
@@ -10205,9 +9802,11 @@ return {
 - `brick(options?: BrickOptions): SdfShape` — Brick/stone wall pattern — running bond with mortar grooves.
 - `weave(options?: WeaveOptions): SdfShape` — Grid lattice pattern — two families of infinite slabs crossing at 90°.
 - `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()`.
 - `twist(shape: SdfShape, degreesPerUnit: number): SdfShape` — Twist an SDF shape around the Z axis.
 - `bend(shape: SdfShape, radius: number): SdfShape` — Bend an SDF shape around the Z axis.
 - `repeat(shape: SdfShape, spacing: Vec3, count?: Vec3): SdfShape` — Repeat an SDF shape in space.
+- `circularArray(shape: SdfShape, count: number, offset?: number): SdfShape` — Arrange an SDF shape in a circular array around the Z axis with O(1) folded-domain evaluation.
 - `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.
 - `Sculpt: { sphere: (radius: number) => SdfShape; box: (x: number, y: number, z: number, options?: SculptBoxOptions) => SdfShape; cylinder: (height: number, radius: number) => SdfShape; disk: (radius: number, thickness?: number) => SdfShape; circle: (radius: number, thickness?: number) => SdfShape; capsule: (height: number, radius: number) => SdfShape; torus: (majorRadius: number, minorRadius: number) => SdfShape; cone: (height: number, radius: number) => SdfShape; tube: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; curve: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; path: (points: SculptPointList, options?: SculptTubeOptions) => SdfShape; blend: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; union: (first?: SculptBlendInput, ...rest: SculptBlendInput[]) => SdfShape; carve: (base: SdfShape, cutters: SculptBlendInput, options?: SculptBlendOptions) => SdfShape; keep: (first?: SculptBlendInput | SculptBlendOptions, optionsOrShape?: SculptBlendInput | SculptBlendOptions, ...rest: (SculptBlendInput | SculptBlendOptions)[]) => SdfShape; polish: (shape: SdfShape, input?: SculptPolishInput) => SdfShape; material: (input?: SculptPolishInput) => ShapeMaterialProps & { color?: string; }; look: (preset?: SculptLookPreset) => SceneOptions; knownMaterials: typeof knownSculptMaterialPresets; }` — Sculpt-like facade: friendly liquid-modeling verbs backed by the same SDF kernel.