forgecad 0.9.4 → 0.9.5

package/dist-skill/docs-dev/generated/lib.md

@@ -10,6 +10,7 @@ Pre-built fasteners, gears, pipes, structural profiles, and utility shapes. Acce
 ## Contents
 
 - [TangentLoop2D](#tangentloop2d)
+- [DriveWheelBuilder](#drivewheelbuilder)
 - [lib](#lib)
 
 ---
@@ -50,6 +51,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
@@ -58,7 +85,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`
 
@@ -68,7 +95,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`
 
@@ -76,7 +105,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)); ```
@@ -114,3 +143,11 @@ 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.

package/dist-skill/docs-dev/generated/output.md

@@ -144,7 +144,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`
 

package/dist-skill/docs-dev/generated/sdf.md

@@ -191,6 +191,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
@@ -269,6 +299,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
@@ -281,8 +319,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
@@ -295,10 +333,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
@@ -370,9 +414,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.

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

@@ -59,7 +59,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.
 
@@ -128,7 +128,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`**
 
@@ -141,9 +140,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`**
 
@@ -219,10 +215,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.

package/dist-skill/docs-dev/guides/inspection-bundles.md

@@ -7,8 +7,9 @@ skill-order: 2
 
 `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
 
@@ -28,14 +29,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;
@@ -91,12 +94,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
 
@@ -123,6 +127,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

package/dist-skill/library/README.md

@@ -8,7 +8,6 @@ forgecad skill install
 
 The installed skill names are namespaced to avoid collisions with a user's existing generic skills.
 
-- `forgecad-api-dogfood`
 - `forgecad-blockout-model`
 - `forgecad-component-model`
 - `forgecad-high-level-spec`

package/dist-skill/library/forgecad-blockout-model/SKILL.md

@@ -67,6 +67,7 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 - Use at most a handful of top-level `param()` values when comparing rough proportions. Do not parameterize every dimension.
 - Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `screenVolume`, `clearanceEnvelope`.
 - Do not add text labels, callout arrows, legends, coordinate labels, or explanatory plaques to the model. Use named return objects and a short written note outside the geometry.
+- Do not cut away a shell, remove covers, or permanently explode parts just to show hidden intent. Even a blockout should represent the object in its normal assembled state unless the user explicitly asks for a presentation view.
 - Use transparent ghost geometry for:
   - sweep arcs
   - keep-out volumes

package/dist-skill/library/forgecad-image-replicator/SKILL.md

@@ -12,6 +12,8 @@ The reference image is evidence. It is not the deliverable.
 
 The deliverable is a real parametric object that remains believable from front, back, side, top, bottom, and reference camera views. A model that matches one image but falls apart from other angles has failed, even if the comparison board looks close.
 
+If a reference image is cutaway, sectioned, exploded, partly hidden, or transparent, treat that as evidence about the complete object. Do not make the default ForgeCAD result a permanently cutaway or exploded display unless the user explicitly asked for a teaching/display model. Build the closed artifact first, then use ForgeCAD viewer/inspection tools to recreate explanatory views.
+
 ## Required Companion Skills
 
 - Use `forgecad` for API docs, model authoring, and renderer behavior.
@@ -80,7 +82,7 @@ Reference matching is a validation step after the object exists.
    When multiple images are attached, do not choose one as the target and ignore the rest. Assign each image a camera, evidence list, and confidence level. Optimize one shared geometry against the whole set. If an image is decorative, distorted, or contradictory, state how it was weighted.
 
 10. Inspect the final object.
-   Run `forgecad run`, render the reference comparison boards, render canonical views, and use `forgecad render inspect` with relevant channels. For multi-part, mechanical, internal, or fit-sensitive models, include collisions and section views.
+   Run `forgecad run`, render the reference comparison boards, render canonical views, and use `forgecad render inspect` with relevant channels. For multi-part, mechanical, internal, or fit-sensitive models, include collisions and section-channel inspection, but keep the delivered model as the complete closed artifact.
 
 ## Renderer Camera Support
 

package/dist-skill/library/forgecad-make-a-model/SKILL.md

@@ -40,12 +40,14 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
    - When there are multiple versions of the same object, expose the version as a choice parameter and render one selected version at a time
    - Use clear variable names
    - Build any implied internal structure as real geometry, even when it will be hidden in the final view
+   - Build the complete physical artifact first: closed shells, installed covers, real part positions, and all meaningful internal structure in place
    - Make final mating geometry physically plausible: parts may touch, clear each other, or be boolean-joined, but should not unintentionally pass through each other
    - Model the physical artifact, not an educational diagram: no explanatory arrows, floating labels, section labels, legends, or text plaques unless the user explicitly requested a presentation/teaching view
+   - Do not make the default returned model a cutaway, sectioned shell, permanently exploded assembly, or hidden-parts teaching view. ForgeCAD gives the user viewer and inspection tools for slicing, exploding, hiding, and looking inside after the real CAD exists.
    - Return the final geometry (single shape, array, or named objects array)
-   - Avoid expensive global edge treatment on repeated decorative geometry: do not call `fillet(shape, r)` or `chamfer(shape, r)` on every edge of large unioned/repeated parts unless the render/run loop proves it is fast enough. Prefer simpler primitive profiles, lower segment counts, or targeted edge selectors.
+   - Treat `fillet(shape, r)` and `chamfer(shape, r)` as experimental edge treatments: Manifold can produce incorrect results and OCCT can be very slow. Prefer simpler primitive profiles, lower segment counts, targeted edge selectors, and inspection before relying on the result.
 4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
-5. Verify geometry — render the result and run `forgecad render inspect` with the relevant channels for the task (see Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`.
+5. Verify geometry — render the result, run `forgecad run --connectivity` when the model has multiple returned objects or visible attachments, and run `forgecad render inspect` with the relevant channels for the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`.
 
 ## Manufacturing Process Is Not Assumed
 
@@ -98,7 +100,9 @@ Build hidden features as actual geometry:
 - Mechanism clearances, travel envelopes, stops, guides, rails, hinges, gear spaces, and service access
 - Process-specific features such as bends, tubes, sheet-metal flanges, machined bosses, cast ribs, molded draft, weld tabs, laser-cut slots, or print-oriented ribs where appropriate
 
-When internals are hidden by the final exterior, add a temporary verification view: transparent shell, exploded view, cutaway, underside render, or named ghost objects. Use that view to check fit and collisions, but keep the final returned model faithful to the real closed artifact unless the user asked for a visible cutaway.
+Do not reveal hidden structure by permanently cutting away the production geometry. Keep the returned default model faithful to the real closed artifact, with covers installed and parts in their actual assembled positions.
+
+When internals are hidden by the final exterior, verify them with exploration tools instead of changing the artifact: render underside or alternate camera views, use `render inspect` section channels, use viewer-only cut planes or explode controls, temporarily make a shell transparent, or add named ghost objects for fit checks. Those views are diagnostic/presentation modes; they must not replace the real model unless the user explicitly asked for a cutaway teaching model.
 
 ## Final Geometry Should Be Physically Plausible
 
@@ -110,6 +114,46 @@ Temporary collisions during construction are fine when they are part of how the
 
 Before delivery on any multi-part, internal, or mechanical model, run the collision inspection, read the collision channel PNGs, and check `manifest.json`. Fix unexpected overlaps. If a collision is intentional, document it in the model naming/comments or isolate that inspection with `--focus` / `--hide` so the remaining collision report proves the final assembly is real.
 
+## Final Acceptance Gate
+
+Before telling the user the model is done, prove both technical validity and visual plausibility. A model can pass `forgecad run` and still be wrong because a rail, cable, trim line, handle, or fastener is merely hovering over a curved surface. Use this gate for any model with multiple bodies, surface-mounted details, cables/strings, rails/tracks, handles, product skins, visible hardware, or hidden mating geometry.
+
+1. State the intended physical component graph. Decide whether the final artifact should be one connected component, several intentionally separate components, or a selected assembly plus named ghosts. Then run:
+
+   ```bash
+   forgecad run model.forge.js --connectivity
+   ```
+
+   The reported component count must match the design intent. Treat unexpected islands, accidental fusion, or bbox-only "touching" that does not make physical sense as model bugs.
+
+2. Run a collision bundle and read both the manifest and images:
+
+   ```bash
+   forgecad render inspect model.forge.js /tmp/model-inspect --channels rgb,mask,collisions --force --size 700
+   jq '.channels.collisions | {collisionCount, collisions, warnings}' /tmp/model-inspect/manifest.json
+   ```
+
+   `collisionCount` should be zero unless an overlap is deliberately manufactured, fused, welded, overmolded, or isolated with `--focus` / `--hide`. Do not ignore the channel PNGs; visually inspect where the findings or warnings appear.
+
+3. Render risk-specific views, not only a hero shot. At minimum, render one hero view plus the orthographic views that expose the likely failure modes:
+
+   - long products, vehicles, weapons, rails, handles, and tools: side and top
+   - sockets, underside joins, stands, brackets, and handles: side plus underside; use section-channel inspection only when hidden geometry must be checked
+   - cables, strings, belts, tubes, and hoses: top plus side so endpoints and sag/clearance are visible
+   - surface details on curved ProductSkin bodies: grazing side view plus top/iso to confirm they conform or are embedded as intended
+
+4. Do a visual attachment audit. For every detail that should be connected, ask: "Where does this physically enter, seat, wrap, terminate, or fasten?" Check that view directly. Common failures to fix before delivery:
+
+   - a flat rail or arrow bed sitting on top of a curved shell instead of being recessed, saddled, socketed, or structurally blended into the body
+   - strings/cables that pass through space without terminal knots, hooks, holes, posts, ferrules, pulleys, or anchors
+   - decorative brass/trim lines floating above the body instead of following a ProductSkin surface or being built as inset/raised strips with believable thickness
+   - handles/grips touching only by a tangent or thin face instead of having a neck, bridge, socket, screws, or overmolded landing
+   - small hardware or gems that are bbox-connected but visually read as levitating; replace with flush/inset seats or explicit brackets
+
+5. Treat ProductSkin and surface-member limitations honestly. If `render inspect` reports boolean-test warnings because a sampled `Product.skin` loft has boundary edges, distinguish that from real collision findings. You may still deliver if `collisionCount` is clean, the intended connectivity is correct, and the visual attachment audit passes. Mention the residual warning briefly in the final response.
+
+6. Final response must name the evidence: commands run, component count, collision count, and any residual warnings or intentional exceptions. Do not just say "validated."
+
 ## Render-Verify Loop
 
 You are building blind unless you render. `forgecad run` only checks that code executes — it cannot tell you a hole is in the wrong place or a part doesn't fit. Render and look at the result.
@@ -231,7 +275,7 @@ Key primitives:
 
 - `box(x, y, z)`, `cylinder(h, r, rTop?, segments?)`, `sphere(r)`, `torus(R, r)`
 - `union()`, `difference()`, `intersection()`
-- `.fillet()`, `.chamfer()` for edge treatments
+- `.fillet()`, `.chamfer()` for experimental edge treatments only
 - `param(name, default, opts)`, `boolParam(name, default)`
 - Return `[{ name, shape, color }]` for multi-part colored models
 

package/dist-skill/library/forgecad-render-inspect/SKILL.md

@@ -10,6 +10,8 @@ Use `forgecad render inspect` when a shaded viewport render is too ambiguous and
 
 This skill owns the inspection workflow: choosing channels, generating the bundle, reading the manifest, visually inspecting the relevant PNGs, and turning the findings into model fixes or a verification report.
 
+Inspection is not a substitute artifact. Use section, mask, transparency, focus, and hide channels to look inside a real model; do not edit the model into a cutaway or exploded default just to make the inspection easier.
+
 ## Trigger Boundary
 
 Use this skill for:
@@ -143,7 +145,7 @@ Manifest fields to check first:
 - `channels.thickness.objects`: inspect `minThickness`, `p05Thickness`, critical/warning percentages, and unresolved area.
 - `channels.connectivity.componentCount`: compare to the expected number of physical components.
 - `channels.distance.maxRootDistance` and per-object `nearestGap`: check suspicious isolation or spacing.
-- `channels.section.planes`: look for missing slices, wrong path counts, or empty internal cuts.
+- `channels.section.planes`: look for missing slices, wrong path counts, or empty internal cuts. These are inspection views, not instructions to section the returned production geometry.
 
 PNG review order:
 

package/dist-skill/library/forgecad-visual-spec/SKILL.md

@@ -32,6 +32,7 @@ The image should not:
 - smooth away the mechanism into a fake consumer shell
 - invent flashy sci-fi styling that hides how it works
 - pretend to be a CAD drawing, dimensioned blueprint, or engineering diagram
+- turn the artifact into a cutaway, sectioned shell, or exploded teaching view unless the user explicitly asks for that representation
 
 ## Default Strategy
 
@@ -119,6 +120,7 @@ Bias harder toward interfaces, seams, mounted actuators, and subsystem boundarie
 Use when the user wants assembly logic or modular breakdown.
 
 Keep the explosion restrained. Separate only major modules, not every screw.
+This is a visual-spec support image, not a default ForgeCAD modeling instruction; the CAD artifact should still be the complete assembled product.
 
 ### Workshop Prototype Realism
 

package/examples/api/drive-wheel-regions.forge.js

@@ -0,0 +1,43 @@
+const moduleSize = Param.number("Module", 1.15, { min: 0.8, max: 2.2, step: 0.05, unit: "mm" });
+const teethOnFullCircle = Param.number("Pitch Teeth", 40, { min: 24, max: 72, integer: true });
+const toothCount = Param.number("Active Teeth", 9, { min: 2, max: 20, integer: true });
+const firstTooth = Param.number("First Tooth", 29, { min: 0, max: 71, integer: true });
+const faceWidth = Param.number("Face Width", 8, { min: 4, max: 14, unit: "mm" });
+
+const pitchRadius = (moduleSize * teethOnFullCircle) / 2;
+const rootRadius = pitchRadius - moduleSize * 1.25;
+const rimWidth = Math.max(2.4, moduleSize * 2.2);
+const hubDiameter = Math.max(9, moduleSize * 8);
+const clampedFirstTooth = Math.min(firstTooth, teethOnFullCircle - 1);
+const clampedToothCount = Math.min(toothCount, teethOnFullCircle - clampedFirstTooth);
+
+const body = lib.gearBodies.spoked({
+  outerRadius: rootRadius,
+  rimWidth,
+  hubDiameter,
+  spokeCount: 5,
+  spokeWidth: Math.max(2, moduleSize * 1.8),
+  faceWidth,
+  boreDiameter: 5,
+});
+
+const wheel = lib
+  .driveWheel({ body, faceWidth })
+  .addSpurTeethBetween({
+    name: "drive teeth",
+    module: moduleSize,
+    teethOnFullCircle,
+    firstTooth: clampedFirstTooth,
+    toothCount: Math.max(1, clampedToothCount),
+    pressureAngleDeg: 20,
+  })
+  .addSolidArcBetween({
+    name: "dwell shoulder",
+    fromAngleDeg: 100,
+    toAngleDeg: 170,
+    innerRadius: rootRadius - rimWidth,
+    outerRadius: rootRadius + moduleSize * 0.9,
+  })
+  .build();
+
+return [{ name: "Exceptional Drive Wheel", shape: wheel.color("#d5a15f") }];

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

@@ -0,0 +1,19 @@
+// SDF circular array — fogleman-style folded-domain knurling.
+// circularArray evaluates the source groove twice no matter how many copies it creates.
+
+const body = sdf.cylinder(42, 11);
+
+const rightHandGroove = sdf.box(2.4, 1.2, 48)
+  .rotateZ(45)
+  .circularArray(32, 11.6)
+  .twist(2.2);
+
+const leftHandGroove = sdf.box(2.4, 1.2, 48)
+  .rotateZ(-45)
+  .circularArray(32, 11.6)
+  .twist(-2.2);
+
+return body
+  .subtract(rightHandGroove, leftHandGroove)
+  .color('#8da2ad')
+  .material({ roughness: 0.38, metalness: 0.18 });

package/examples/api/sdf-pattern2d-ceramic-ripple-set.forge.js

@@ -0,0 +1,83 @@
+// Native Pattern2D relief on ceramic forms: flutes, bands, and woven bowl texture.
+
+scene({
+  background: { top: '#fff8f1', bottom: '#d8e4ea' },
+  camera: { position: [90, -126, 66], target: [0, 0, 8], fov: 34 },
+  environment: { preset: 'studio', intensity: 1.28 },
+  lights: [
+    { type: 'ambient', color: '#ffffff', intensity: 0.28 },
+    { type: 'point', position: [54, -72, 90], color: '#fff1d0', intensity: 2.2, distance: 280, decay: 1.12 },
+    { type: 'point', position: [-76, 48, 62], color: '#84d8ff', intensity: 1.15, distance: 240, decay: 1.18 },
+    { type: 'directional', position: [30, -56, 150], color: '#ffffff', intensity: 0.58 },
+  ],
+  postProcessing: {
+    toneMappingExposure: 1.12,
+    bloom: { intensity: 0.08, threshold: 0.84, radius: 0.38 },
+    vignette: { darkness: 0.12, offset: 0.62 },
+  },
+});
+
+const ceramic = (shape, color) =>
+  shape.color(color).material({
+    roughness: 0.46,
+    metalness: 0,
+    clearcoat: 0.72,
+    clearcoatRoughness: 0.18,
+  });
+
+const p = sdf.pattern2d();
+
+const flutedPorcelain = p
+  .sineWave({ direction: [1, 0], wavelength: 4.6, amplitude: 0.28 })
+  .add(p.sineWave({ direction: [0, 1], wavelength: 18, amplitude: 0.08 }))
+  .clamp(-0.34, 0.34);
+
+const carvedBands = p
+  .stripes({ direction: [0, 1], spacing: 7.5, width: 0.9, depth: 0.2 })
+  .add(p.sineWave({ direction: [1, 1], wavelength: 9, amplitude: 0.08 }))
+  .clamp(-0.27, 0.07);
+
+const wovenGlaze = p
+  .overUnderWeave({ spacing: 2.45, threadWidth: 1.08, depth: 0.34 })
+  .add(p.sineWave({ direction: [1, -1], wavelength: 13, amplitude: 0.055 }))
+  .clamp(-0.42, 0.06);
+
+const tallVase = ceramic(
+  sdf.cylinder(58, 11)
+    .shell(1.35)
+    .surfaceDisplace(flutedPorcelain, { uv: 'cylinder' })
+    .subtract(sdf.cylinder(66, 8.2))
+    .translate(-35, 0, 3),
+  '#f2efe2',
+);
+
+const bandedCup = ceramic(
+  sdf.cylinder(38, 14)
+    .shell(1.25)
+    .surfaceDisplace(carvedBands, { uv: 'cylinder' })
+    .subtract(sdf.cylinder(46, 10.6))
+    .translate(0, 0, -7),
+  '#8fb7c7',
+);
+
+const lowBowl = ceramic(
+  sdf.sphere(22)
+    .shell(1.4)
+    .surfaceDisplace(wovenGlaze)
+    .subtract(sdf.box(68, 68, 40).translate(0, 0, 17))
+    .translate(37, 0, -8),
+  '#c97462',
+);
+
+const footRings = ceramic(
+  sdf
+    .torus(10.5, 0.75)
+    .translate(-35, 0, -27)
+    .union(
+      sdf.torus(12.5, 0.72).translate(0, 0, -26),
+      sdf.torus(14.5, 0.72).translate(37, 0, -25),
+    ),
+  '#d8c59f',
+);
+
+return { tallVase, bandedCup, lowBowl, footRings };