forgecad 0.9.5 → 0.9.7

package/dist-skill/docs/CLI.md

@@ -67,50 +67,63 @@ Execute scripts and produce images headless — no browser window. Renders use C
 
 ### `forgecad run`
 
-Execute a Forge script and print full geometry diagnostics — object summary, collision detection, spatial analysis, verification results, and solver profiling.
+Execute a Forge script quickly and print the inner-loop build summary: returned objects, verification results, parameters, and timing.
 
-The primary validation command. Runs your script with the real geometry kernel (no browser needed) and prints a comprehensive report:
+The fast validation command. Runs your script with the real geometry kernel (no browser needed) and reports whether it built, which objects came back, any `verify.*` results, parameter values, script logs, and elapsed script time. This is the command agents should run frequently while editing a model.
 
-**Object summary** — lists every named shape with its volume, bounding box, and body count. For constrained sketches, shows solver status (FULLY / UNDER / OVER constrained), DOF, and error residuals. Problematic constraints (conflicting, redundant, or high-residual) are flagged individually.
+**Fast by default** — a bare `forgecad run model.forge.js` does not compute per-object volumes, bounding boxes, construction history, feature tallies, spatial relationships, collision intersections, or solver profiles. Those diagnostics are useful, but they are no longer part of the hot path.
 
-**Construction history** — shows the build sequence for each shape (primitives, operations, modifications) so you can verify the modeling intent.
+**Opt-in diagnostics** — use `--details` for volume/bounding-box/object geometry summaries, `--history` for the construction tree, `--features` for feature tallies, `--solver-profile` for constraint solver timing, or `--full` for the legacy rich report. Use `--spatial bounded|exact` only when you want directional relationships and collision intersections from the run command itself.
 
-**Feature summary** — tallies geometry features across all objects (e.g. `3 extrude, 2 fillet, 1 chamfer`).
+**Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values. Verification failures remain non-fatal so the model can still render and be inspected.
 
-**Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values.
+**Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping bbox candidates are checked with exact geometry by default, while bbox-only contact is treated as evidence rather than proof of one connected component. This helps answer whether the model is one continuous assembly or several separate islands.
 
-**Automatic collision detection** — performs an all-pairs collision check on every named shape. For each pair whose bounding boxes overlap, computes the boolean intersection and reports overlap above 0.1 mm³:
-
-```
-⚠ COLLISION: bolt ∩ base (shared vol: 42.3mm³)
-```
-
-Intra-group pairs (same assembly group) and mock-to-mock pairs are skipped. If a part passes through a boolean-subtracted hole, no collision is reported — the material is gone.
+**Quality preset** — pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.
 
-**Spatial analysis** — reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). Exact pairwise collision intersections run by default only for bounded scenes; use `--spatial exact` for exhaustive collision checks or `--spatial off` to skip this section.
+For deeper confidence gates, prefer `forgecad inspect mechanical-integrity`, `forgecad check print`, `forgecad check params`, or `forgecad render inspect` instead of turning `run` back into a catch-all audit command.
 
-**Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping or touching bboxes are joined within `--connectivity-tolerance` (default `0.05` model units); use collision inspection for exact positive-volume overlaps. This helps answer whether the model is one continuous assembly or several separate islands.
+```bash
+forgecad run examples/api/static-assembly-connectors.forge.js
+forgecad run examples/api/static-assembly-connectors.forge.js --focus
+forgecad run examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
+forgecad run examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
+forgecad run examples/api/static-assembly-connectors.forge.js --details --history
+forgecad run examples/api/static-assembly-connectors.forge.js --spatial bounded
+forgecad run examples/api/static-assembly-connectors.forge.js --full
+forgecad run examples/products/cup.forge.js --connectivity
+forgecad run examples/products/cup.forge.js --journeys
+forgecad run examples/products/cup.forge.js --backend occt
+forgecad run examples/products/cup.forge.js --backend truck --quality live
+forgecad run examples/products/cup.forge.js --debug-imports
+forgecad run examples/products/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
+forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+```
 
-**Quality preset** — pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.
+### Object Filtering: `--focus` and `--hide`
 
-**Parameters** — lists all declared parameters with their current values. Overridden values are marked with `*`.
+Several CLI commands can filter the visible object set without changing model code: `run`, `render 3d`, `render wireframe`, `render inspect`, `capture`, and `check print`.
 
-**Solver profiling** — when constraint solving occurs, shows timing breakdown (clone, solve, redundancy detection, surface building) and solver internals.
+Use `forgecad run model.forge.js --quality live` to list returned object names quickly, then pass those names to `--focus` or `--hide`.
 
 ```bash
-forgecad run examples/cup.forge.js
-forgecad run examples/cup.forge.js --focus
-forgecad run examples/cup.forge.js --focus bracket,hinge
-forgecad run examples/cup.forge.js --hide "wall,bolt"
-forgecad run examples/cup.forge.js --connectivity
-forgecad run examples/cup.forge.js --journeys
-forgecad run examples/cup.forge.js --backend occt
-forgecad run examples/cup.forge.js --backend truck --quality live
-forgecad run examples/cup.forge.js --debug-imports
-forgecad run examples/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
-forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+forgecad run examples/api/static-assembly-connectors.forge.js --quality live
+forgecad render 3d examples/api/static-assembly-connectors.forge.js bench.png --focus "Bench.*"
+forgecad render 3d examples/api/static-assembly-connectors.forge.js slats.png --focus "Bench.Slat*"
+forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels rgb,mask --hide "Bench.Slat0,Bench.Slat1" --force
 ```
 
+Rules:
+
+- A bare `--focus` hides mock objects and keeps real objects.
+- `--focus name1,name2` renders only matching objects.
+- `--hide name1,name2` removes matching objects from the visible scene.
+- Matching is case-insensitive and supports `*` / `?` globs.
+- `--focus` and `--hide` are mutually exclusive.
+- Filtering happens after the script runs; it does not avoid evaluating the full model.
+- Filtering works on returned object names. For grouped children, use concrete child names or globs like `Bench.*`.
+- If a model unions many parts into one returned shape, the original parts cannot be isolated by CLI filtering.
+
 ### `forgecad render`
 
 Render a Forge scene. Use a subcommand — `3d`, `inspect`, `views`, `section`, `wireframe`, `sketch`, or `hq`.
@@ -127,13 +140,13 @@ Render a Forge scene. Use a subcommand — `3d`, `inspect`, `views`, `section`,
 - `render hq` — path-traced via Blender Cycles, for documentation and marketing shots
 
 ```bash
-forgecad render 3d examples/cup.forge.js
+forgecad render 3d examples/products/cup.forge.js
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask
 forgecad render inspect channels
-forgecad render views examples/cup.forge.js
-forgecad render wireframe examples/cup.forge.js
+forgecad render views examples/products/cup.forge.js
+forgecad render wireframe examples/products/cup.forge.js
 forgecad render section examples/furniture/01-table.forge.js --plane XZ
-forgecad render hq examples/cup.forge.js --preset dramatic
+forgecad render hq examples/products/cup.forge.js --preset dramatic
 ```
 
 ### `forgecad render 3d`
@@ -149,10 +162,10 @@ Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe
 This is the standard way to visually verify geometry from the CLI or in agent workflows. For higher quality (path-traced, materials, HDRI lighting), use `render hq` instead.
 
 ```bash
-forgecad render 3d examples/cup.forge.js
-forgecad render 3d examples/cup.forge.js --focus
-forgecad render 3d examples/cup.forge.js --focus bracket
-forgecad render 3d examples/cup.forge.js --hide "wall,bolt"
+forgecad render 3d examples/products/cup.forge.js
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
+forgecad render 3d examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
 forgecad render 3d model.forge.js --view hero
 forgecad render 3d model.forge.js --camera 45:30
 forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
@@ -186,7 +199,7 @@ For bundle layout, channel encodings, and manifest semantics, see [Inspection Bu
 
 ```bash
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask
-forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels collisions --focus Bench
+forgecad render inspect examples/api/static-assembly-connectors.forge.js out/bench-inspect --channels collisions --focus "Bench.*"
 forgecad render inspect examples/api/static-assembly-connectors.forge.js --channels rgb,mask,collisions --hide "Bench.Slat0" --force
 ```
 
@@ -206,8 +219,8 @@ Render a Forge scene as a wireframe (edges only, no shading).
 Same as `render 3d` but renders only the edge geometry — no shaded surfaces. Useful for construction-style documentation or highlighting structural features without material detail.
 
 ```bash
-forgecad render wireframe examples/cup.forge.js
-forgecad render wireframe examples/cup.forge.js --camera iso
+forgecad render wireframe examples/products/cup.forge.js
+forgecad render wireframe examples/products/cup.forge.js --camera iso
 ```
 
 ### `forgecad render hq` **\[Pro\]**
@@ -221,12 +234,12 @@ Choose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (h
 Output defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.
 
 ```bash
-forgecad render hq examples/cup.forge.js
-forgecad render hq examples/cup.forge.js hero.png --preset dramatic --samples 1024
-forgecad render hq examples/cup.forge.js hero.png --view hero
-forgecad render hq examples/cup.forge.js hero.png --camera-json camera.json
-forgecad render hq examples/cup.forge.js --preset clay --size 2048
-forgecad render hq examples/cup.forge.js --transparent --preset glass
+forgecad render hq examples/products/cup.forge.js
+forgecad render hq examples/products/cup.forge.js hero.png --preset dramatic --samples 1024
+forgecad render hq examples/products/cup.forge.js hero.png --view hero
+forgecad render hq examples/products/cup.forge.js hero.png --camera-json camera.json
+forgecad render hq examples/products/cup.forge.js --preset clay --size 2048
+forgecad render hq examples/products/cup.forge.js --transparent --preset glass
 ```
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
@@ -236,13 +249,13 @@ Animated orbit or joint playback.
 Renders an animated sequence by either orbiting the camera around the model or playing back a `jointsView` animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joints clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
 
 ```bash
-forgecad capture gif examples/cup.forge.js
+forgecad capture gif examples/products/cup.forge.js
 forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
 forgecad capture gif model.forge.js out/raw.gif --param "Output=raw-sdf"
 forgecad capture gif model.forge.js out/front.gif --camera front
 forgecad capture gif model.forge.js out/hero.gif --view hero
 forgecad capture gif examples/3d-printer.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
-forgecad capture mp4 examples/cup.forge.js
+forgecad capture mp4 examples/products/cup.forge.js
 forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
 forgecad capture mp4 model.forge.js out/raw.mp4 --param "Output=raw-sdf"
 forgecad capture mp4 model.forge.js out/front.mp4 --camera front
@@ -276,8 +289,8 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 
 | Option | Description |
 |--------|-------------|
-| `--focus <names>` | Focus: no arg hides mocks; comma-separated names shows only those |
-| `--hide <names>` | Hide comma-separated object names |
+| `--focus <names>` | Focus: no arg hides mocks; comma-separated names/globs show only those |
+| `--hide <names>` | Hide comma-separated object names/globs |
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
 | `--camera-json <file>` | Exact viewport camera JSON file |
 | `--view <name>` | Named camera view declared by the model with scene({ views }) |
@@ -299,7 +312,8 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--min-thickness <mm>` | Critical thickness threshold in model units |
 | `--warn-thickness <mm>` | Warning thickness threshold in model units |
 | `--max-thickness <mm>` | Thick/blue heatmap threshold in model units |
-| `--thickness-samples <n>` | Maximum sampled triangles per object |
+| `--thickness-samples <n>` | Maximum thickness point samples per object |
+| `--roughness-samples <n>` | Maximum roughness point samples per object |
 | `--preset <name>` | Material/lighting preset |
 | `--width <px>` | Output width in pixels |
 | `--height <px>` | Output height in pixels |
@@ -530,7 +544,7 @@ forgecad skill one-file ~/Desktop/forgecad-context.md
 forgecad skill flattened-files ~/Desktop/forgecad-skills
 ```
 
-> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad check print` catches printability risks -> `forgecad render inspect` produces visual evidence -> `forgecad check params` sweeps parameter robustness -> export ships the result. All in the terminal.
+> **Workflow:** Agent writes the model -> `forgecad run` validates it -> `forgecad inspect mechanical-integrity` catches disconnected AI-slop patterns -> `forgecad check print` catches printability risks -> `forgecad render inspect` produces visual evidence -> `forgecad check params` sweeps parameter robustness -> export ships the result. All in the terminal.
 
 ## Validation
 
@@ -551,6 +565,20 @@ forgecad check print model.forge.js --min-wall 1.2 --warn-wall 2
 forgecad check print model.forge.js --expect-components 1 -p "Wall Thickness=3"
 ```
 
+### `forgecad inspect mechanical-integrity`
+
+Inspect generated ForgeCAD models for mechanical integrity failures.
+
+Scans a Forge script or a folder of generated projects and runs a mechanical integrity inspection. The inspection flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, optional positive-volume object collisions, and excessive physical component counts when requested. Markdown details include suggested repair patterns such as connector-authored mates, bolted service covers, pinned levers, captured slides, hinges, clevis joints, retained shafts, and seated bearings. When `--collisions` is enabled, the Markdown details list the largest overlapping object pairs by volume so agents can repair the highest-risk interfaces first. Exact collision checks use a default 40-pair bbox-overlap budget and 30s exact-check time budget; exhausting either budget fails the file instead of silently passing a partial check.
+
+```bash
+forgecad inspect mechanical-integrity path/to/generated-models
+forgecad inspect mechanical-integrity path/to/model/main.forge.js --min-verifications 2
+forgecad inspect mechanical-integrity path/to/model/main.forge.js --collisions
+forgecad inspect mechanical-integrity path/to/generated-models --collisions --collision-pair-limit 250
+forgecad inspect mechanical-integrity path/to/generated-models --json --timeout-ms 40000 --jobs 4
+```
+
 ### `forgecad check params`
 
 Sweep parameter ranges and report runtime failures, degeneracy, and new collisions.
@@ -574,6 +602,7 @@ forgecad check params path/to/model.forge.js --samples 12
 | Command | Description |
 |---------|-------------|
 | `check suite` | Run the repo invariant suite, with smoke and full profiles for the fast merge lane vs the broader regression sweep. |
+| `inspect mechanical-integrity` | Inspect generated ForgeCAD models for mechanical integrity failures. |
 | `check runtime-globals` | Ensure the script sandbox does not add new lowercase injected globals. |
 | `check transforms` | Run transform and assembly invariants. |
 | `check dimensions` | Run dimension propagation invariants. |
@@ -617,7 +646,7 @@ The CLI is free for core workflows and exports. Production outputs are free to r
 
 | Free | Production outputs | Pro |
 |------|--------------------|-----|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check print`, `check params`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check print`, `check params`, `inspect mechanical-integrity`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
 
 ```bash
 forgecad license                    # Check signed-in account status

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

@@ -18,7 +18,7 @@ skill-order: 100
 - [Grouping & Local Coordinates](#grouping-local-coordinates) — `group`
 - [Section & Projection](#section-projection) — `intersectWithPlane`, `faceProfile`, `projectToPlane`
 - [Transforms](#transforms) — `composeChain`
-- [Verification](#verification) — `spec`
+- [Verification](#verification) — `verify.that`, `verify.equal`, `verify.notEqual`, `verify.greaterThan`, `verify.lessThan`, `verify.inRange`, `verify.centersCoincide`, `verify.connectorDistance`, `verify.physicalComponentCount`, `verify.intentionalOverlap`, `verify.notColliding`, `verify.minClearance`, `verify.clearanceBetween`, `verify.parallel`, `verify.perpendicular`, `verify.coplanar`, `verify.faceAt`, `verify.sameDirection`, `verify.isEmpty`, `verify.notEmpty`, `verify.volumeApprox`, `verify.areaApprox`, `verify.boundingBoxSize`, `verify.edgeContinuity`, `verify.noTinyEdges`, `verify.noSliverFaces`, `verify.noSelfIntersection`, `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
@@ -669,6 +669,207 @@ composeChain(...steps: TransformInput[]): Transform
 
 ### Verification
 
+#### `verify.that()` — Custom predicate check.
+
+```ts
+verify.that(label: string, check: () => boolean, message?: string): void
+```
+
+#### `verify.equal()` — Check that two numbers are approximately equal (within tolerance).
+
+```ts
+verify.equal(label: string, actual: number, expected: number, tolerance?: number, message?: string): void
+```
+
+#### `verify.notEqual()` — Check that two numbers are NOT equal (differ by more than tolerance).
+
+```ts
+verify.notEqual(label: string, actual: number, unexpected: number, tolerance?: number, message?: string): void
+```
+
+#### `verify.greaterThan()` — Check that actual > min.
+
+```ts
+verify.greaterThan(label: string, actual: number, min: number, message?: string): void
+```
+
+#### `verify.lessThan()` — Check that actual < max.
+
+```ts
+verify.lessThan(label: string, actual: number, max: number, message?: string): void
+```
+
+#### `verify.inRange()` — Check that min <= actual <= max.
+
+```ts
+verify.inRange(label: string, actual: number, min: number, max: number, message?: string): void
+```
+
+#### `verify.centersCoincide()` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
+
+```ts
+verify.centersCoincide(label: string, a: ShapeLike, b: ShapeLike, tolerance?: number): void
+```
+
+`ShapeLike`: `{ min: number[], max: number[] }`
+
+#### `verify.connectorDistance()` — Check the distance between two named connectors on a shape or group.
+
+Use this when connectors + `matchTo()` define a static assembly interface. It proves the mate at runtime, unlike a plain source-level connector declaration. The common case is `expected = 0`, meaning the two connector origins should coincide after placement.
+
+```ts
+verify.connectorDistance("leg is seated", bench, "Rail.leg_0", "Leg0.head", 0, 0.01);
+```
+
+```ts
+verify.connectorDistance(label: string, target: ConnectorDistanceLike, connectorA: string, connectorB: string, expected?: number, tolerance?: number): void
+```
+
+#### `verify.physicalComponentCount()` — Declare the expected physical connectivity component count for the returned visible model.
+
+Use this for generated mechanical models that should have a clear component graph: one connected fixture, a purchased part plus a removable cartridge, a root assembly plus named intentional ghosts, and so on. `forgecad inspect mechanical-integrity` resolves the returned visible objects with the same physical-connectivity analysis used in the quality gate and fails if the actual component count differs.
+
+This catches the common generated-CAD failure where a script returns a visually plausible artifact but the handle, screw, washer, cover, or terminal block is actually a separate island.
+
+```ts
+verify.physicalComponentCount("vise is one connected installed assembly", 1);
+```
+
+```ts
+verify.physicalComponentCount(label: string, expected: number): void
+```
+
+#### `verify.intentionalOverlap()` — Declare that two visible objects intentionally overlap because the overlap is real manufacturing intent.
+
+Use this only for overlaps that a mechanical reviewer would accept as actual matter sharing volume: welded/fused regions, overmolded inserts, potted electronics, cast-in hardware, or deliberately bonded laminations. This is not a shortcut for screws without holes, shafts without bores, covers without pockets, or parts placed with collision as a positioning hack.
+
+`forgecad inspect mechanical-integrity --collisions` only honors this declaration when both shapes are returned as visible objects and the exact collision report finds that same object pair. Unused or non-visible declarations fail the quality gate so annotations cannot hide unrelated collisions.
+
+```ts
+verify.intentionalOverlap("rubber grip is overmolded on handle", rubberGrip, handleCore, "overmolded insert");
+```
+
+```ts
+verify.intentionalOverlap(label: string, a: ShapeLike, b: ShapeLike, reason: string): void
+```
+
+#### `verify.notColliding()` — Check that two shapes do not collide (minGap > 0).
+
+```ts
+verify.notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: number): void
+```
+
+#### `verify.minClearance()` — Check that a minimum clearance gap exists between two shapes.
+
+```ts
+verify.minClearance(label: string, a: ShapeLike, b: ShapeLike, minGap: number, searchLength?: number): void
+```
+
+#### `verify.clearanceBetween()` — Check that the clearance gap between two shapes is inside an allowed range.
+
+Use this for seated and retained interfaces where a part must be close enough to be mechanically accountable, but must not collide beyond the allowed minimum. It catches both failure modes that make generated CAD look fake: parts floating away from their receiver, and parts intersecting their receiver because the pocket, bore, or running clearance was not modeled.
+
+For contact, use a narrow range such as `[-0.01, 0.05]` to tolerate tiny numerical noise. For a running fit, use the intended clearance band.
+
+Manifold-backed shapes use exact min-gap distance. Other backends use a mesh-derived min-gap check and say so in the verification message; keep `forgecad inspect mechanical-integrity --collisions` in the acceptance gate for positive-volume interference.
+
+```ts
+verify.clearanceBetween("cover is seated on gasket", cover, gasket, -0.01, 0.05);
+verify.clearanceBetween("carriage runs inside rail", carriage, rail, 0.2, 0.5);
+```
+
+```ts
+verify.clearanceBetween(label: string, a: ShapeLike, b: ShapeLike, minGap: number, maxGap: number, searchLength?: number): void
+```
+
+#### `verify.parallel()` — Check that two face normals are parallel (within toleranceDeg degrees).
+
+```ts
+verify.parallel(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+`FaceRefLike`: `{ normal: [ number, number, number ], center: [ number, number, number ] }`
+
+#### `verify.perpendicular()` — Check that two face normals are perpendicular (within toleranceDeg degrees).
+
+```ts
+verify.perpendicular(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+#### `verify.coplanar()` — Check that a face is coplanar with (same plane as) another face, meaning they are parallel AND their centers lie on the same plane.
+
+```ts
+verify.coplanar(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number, toleranceMm?: number): void
+```
+
+#### `verify.faceAt()` — Check that a face center lies at a specific position (within toleranceMm).
+
+```ts
+verify.faceAt(label: string, face: FaceRefLike, expectedPos: [ number, number, number ], toleranceMm?: number): void
+```
+
+#### `verify.sameDirection()` — Check that two face normals point in the same direction (not antiparallel). Stricter than parallel — both |angle| AND sign must match.
+
+```ts
+verify.sameDirection(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void
+```
+
+#### `verify.isEmpty()` — Check that a shape is empty.
+
+```ts
+verify.isEmpty(label: string, shape: ShapeLike, message?: string): void
+```
+
+#### `verify.notEmpty()` — Check that a shape is NOT empty.
+
+```ts
+verify.notEmpty(label: string, shape: ShapeLike, message?: string): void
+```
+
+#### `verify.volumeApprox()` — Check that a shape's volume is approximately equal to expected (mm³).
+
+```ts
+verify.volumeApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
+```
+
+#### `verify.areaApprox()` — Check that a shape's surface area is approximately equal to expected (mm²).
+
+```ts
+verify.areaApprox(label: string, shape: ShapeLike, expected: number, tolerance?: number): void
+```
+
+#### `verify.boundingBoxSize()` — Check that a shape's bounding box has approximately the given size.
+
+```ts
+verify.boundingBoxSize(label: string, shape: ShapeLike, expectedSize: [ number, number, number ], tolerance?: number): void
+```
+
+#### `verify.edgeContinuity()` — Check that every sampled seam on a shape meets a requested continuity threshold.
+
+```ts
+verify.edgeContinuity(label: string, shape: ShapeLike, options?: EdgeContinuityThresholds): void
+```
+
+**`EdgeContinuityThresholds`**: `continuity?: SurfaceContinuity`, `samples?: number`, `positionTolerance?: number`, `tangentToleranceDeg?: number`, `curvatureTolerance?: number`
+
+#### `verify.noTinyEdges()` — Check that a shape has no tiny edges below the requested threshold.
+
+```ts
+verify.noTinyEdges(label: string, shape: ShapeLike, threshold?: number): void
+```
+
+#### `verify.noSliverFaces()` — Check that a shape has no sliver faces below the requested score threshold.
+
+```ts
+verify.noSliverFaces(label: string, shape: ShapeLike, threshold?: number): void
+```
+
+#### `verify.noSelfIntersection()` — Best-effort exact-shape validity guard for self-intersections or broken B-Rep topology.
+
+```ts
+verify.noSelfIntersection(label: string, shape: ShapeLike): void
+```
+
 #### `spec()` — Create a named, reusable bundle of verification checks.
 
 A spec groups related `verify.*` calls under a collapsible header in the Checks panel. This makes large check suites scannable. Specs can be applied to multiple shapes and can check relationships between parts.
@@ -1859,8 +2060,12 @@ toString(): string
 - `lessThan(label: string, actual: number, max: number, message?: string): void` — Check that actual < max.
 - `inRange(label: string, actual: number, min: number, max: number, message?: string): void` — Check that min <= actual <= max.
 - `centersCoincide(label: string, a: ShapeLike, b: ShapeLike, tolerance?: number): void` — Check that the bounding-box centers of two shapes coincide within tolerance (mm).
+- `connectorDistance(label: string, target: ConnectorDistanceLike, connectorA: string, connectorB: string, expected?: number, tolerance?: number): void` — Check the distance between two named connectors on a shape or group. Use this when connectors + `matchTo()` define a static assembly interface. It proves the mate at runtime, unlike a plain source-level connector declaration. The common case is `expected = 0`, meaning the two connector origins should coincide after placement. **Example** ```ts verify.connectorDistance("leg is seated", bench, "Rail.leg_0", "Leg0.head", 0, 0.01); ```
+- `physicalComponentCount(label: string, expected: number): void` — Declare the expected physical connectivity component count for the returned visible model. **Details** Use this for generated mechanical models that should have a clear component graph: one connected fixture, a purchased part plus a removable cartridge, a root assembly plus named intentional ghosts, and so on. `forgecad inspect mechanical-integrity` resolves the returned visible objects with the same physical-connectivity analysis used in the quality gate and fails if the actual component count differs. This catches the common generated-CAD failure where a script returns a visually plausible artifact but the handle, screw, washer, cover, or terminal block is actually a separate island. **Example** ```ts verify.physicalComponentCount("vise is one connected installed assembly", 1); ```
+- `intentionalOverlap(label: string, a: ShapeLike, b: ShapeLike, reason: string): void` — Declare that two visible objects intentionally overlap because the overlap is real manufacturing intent. **Details** Use this only for overlaps that a mechanical reviewer would accept as actual matter sharing volume: welded/fused regions, overmolded inserts, potted electronics, cast-in hardware, or deliberately bonded laminations. This is not a shortcut for screws without holes, shafts without bores, covers without pockets, or parts placed with collision as a positioning hack. `forgecad inspect mechanical-integrity --collisions` only honors this declaration when both shapes are returned as visible objects and the exact collision report finds that same object pair. Unused or non-visible declarations fail the quality gate so annotations cannot hide unrelated collisions. **Example** ```ts verify.intentionalOverlap("rubber grip is overmolded on handle", rubberGrip, handleCore, "overmolded insert"); ```
 - `notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: number): void` — Check that two shapes do not collide (minGap > 0).
 - `minClearance(label: string, a: ShapeLike, b: ShapeLike, minGap: number, searchLength?: number): void` — Check that a minimum clearance gap exists between two shapes.
+- `clearanceBetween(label: string, a: ShapeLike, b: ShapeLike, minGap: number, maxGap: number, searchLength?: number): void` — Check that the clearance gap between two shapes is inside an allowed range. **Details** Use this for seated and retained interfaces where a part must be close enough to be mechanically accountable, but must not collide beyond the allowed minimum. It catches both failure modes that make generated CAD look fake: parts floating away from their receiver, and parts intersecting their receiver because the pocket, bore, or running clearance was not modeled. For contact, use a narrow range such as `[-0.01, 0.05]` to tolerate tiny numerical noise. For a running fit, use the intended clearance band. Manifold-backed shapes use exact min-gap distance. Other backends use a mesh-derived min-gap check and say so in the verification message; keep `forgecad inspect mechanical-integrity --collisions` in the acceptance gate for positive-volume interference. **Example** ```ts verify.clearanceBetween("cover is seated on gasket", cover, gasket, -0.01, 0.05); verify.clearanceBetween("carriage runs inside rail", carriage, rail, 0.2, 0.5); ```
 - `parallel(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void` — Check that two face normals are parallel (within toleranceDeg degrees).
 - `perpendicular(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number): void` — Check that two face normals are perpendicular (within toleranceDeg degrees).
 - `coplanar(label: string, faceA: FaceRefLike, faceB: FaceRefLike, toleranceDeg?: number, toleranceMm?: number): void` — Check that a face is coplanar with (same plane as) another face, meaning they are parallel AND their centers lie on the same plane.

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

@@ -9,7 +9,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`
+- [Curves & Surfacing](#curves-surfacing) — `Loft.station`, `Loft.leftRail`, `Loft.rightRail`, `Loft.frontRail`, `Loft.backRail`, `Loft.centerRail`, `Loft.pathOnXz`, `Loft.pathOnYz`, `Loft.pathOnXy`, `Loft.withGuideRails`, `hermiteTransitionG2`, `nurbs3d`, `spline2d`, `spline3d`, `loft`, `loftAlongSpine`, `sweep`, `variableSweep`, `nurbsSurface`, `surfacePatch`, `transitionCurve`, `transitionSurface`, `connectEdges`
 - [Surface Members](#surface-members) — `surfaceBand`, `SurfaceBody`
 - [Curve3D](#curve3d)
 - [NurbsCurve3D](#nurbscurve3d)
@@ -52,6 +52,87 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 
 ### Curves & Surfacing
 
+#### `Loft.station()` — Create a loft station from a 2D profile and an axis position.
+
+```ts
+Loft.station(profile: Sketch, position: number): LoftStation
+```
+
+`LoftStation`: `{ profile: Sketch, position: number }`
+
+#### `Loft.leftRail()` — Create a guide rail that constrains the section-local negative-X side.
+
+```ts
+Loft.leftRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+`LoftGuideRail`: `{ side: LoftGuideRailSide, path: LoftGuideRailPath }`
+
+#### `Loft.rightRail()` — Create a guide rail that constrains the section-local positive-X side.
+
+```ts
+Loft.rightRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.frontRail()` — Create a guide rail that constrains the section-local positive-Y side.
+
+```ts
+Loft.frontRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.backRail()` — Create a guide rail that constrains the section-local negative-Y side.
+
+```ts
+Loft.backRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.centerRail()` — Create a guide rail that moves section centers along the loft.
+
+```ts
+Loft.centerRail(path: LoftGuideRailPath): LoftGuideRail
+```
+
+#### `Loft.pathOnXz()` — Place a 2D guide path onto the XZ plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Z. Use this for left/right silhouette rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnXz(path: LoftPath2D, y?: number): Vec3[]
+```
+
+#### `Loft.pathOnYz()` — Place a 2D guide path onto the YZ plane.
+
+The path's first coordinate becomes Y and its second coordinate becomes Z. Use this for front/back crown rails authored with [`path()`](/docs/sketch#path) or [`constrainedSketch()`](/docs/sketch#constrainedsketch).
+
+```ts
+Loft.pathOnYz(path: LoftPath2D, x?: number): Vec3[]
+```
+
+#### `Loft.pathOnXy()` — Place a 2D guide path onto the XY plane.
+
+The path's first coordinate becomes X and its second coordinate becomes Y. Use this when lofting along X or Y and a rail lives in a horizontal sketch plane.
+
+```ts
+Loft.pathOnXy(path: LoftPath2D, z?: number): Vec3[]
+```
+
+#### `Loft.withGuideRails()` — Loft through profile stations while forcing generated sections to follow guide rails.
+
+Stations define the cross-section family. Guide rails define the side or center paths the loft must pass through. With opposite side rails, the section is scaled to touch both rails. With one side rail, the section keeps its interpolated size unless a center rail is also present.
+
+```ts
+Loft.withGuideRails(stations: LoftStation[], rails: LoftGuideRail[], options?: LoftWithGuideRailsOptions): Shape
+```
+
+**`LoftOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
+- `boundsPadding?: number` — Optional extra bounds padding.
+
+**`LoftWithGuideRailsOptions`** extends LoftOptions
+- `axis?: LoftAxis` — Primary station axis. Default Z.
+- `samples?: number` — Number of generated loft stations including ends. Default scales with station count.
+- `railSamples?: number` — Number of points sampled from curve-backed rails before axis interpolation. Default 64.
+
 #### `hermiteTransitionG2()` — Create a quintic Hermite transition curve between two edge endpoints (G2 continuity).
 
 The curve starts at `a.point` tangent to `a.tangent` with curvature `a.curvature`, and ends at `b.point` tangent to `b.tangent` with curvature `b.curvature`, with smooth G2-continuous interpolation matching position, tangent, and curvature.
@@ -140,10 +221,6 @@ Performance note: loft is significantly heavier than primitive/extrude/revolve.
 loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape
 ```
 
-**`LoftOptions`**
-- `edgeLength?: number` — Marching-grid edge length for level-set meshing. Smaller = finer.
-- `boundsPadding?: number` — Optional extra bounds padding.
-
 #### `loftAlongSpine()` — Loft between multiple profiles positioned along an arbitrary 3D spine curve.
 
 Unlike loft() which only supports Z heights, loftAlongSpine() places each profile at a position along a 3D spine, oriented perpendicular to the spine tangent. This enables lofting along curved paths — e.g., a wing root-to-tip transition that follows a swept-back leading edge.
@@ -821,6 +898,21 @@ path().moveTo(0,0).lineTo(10,0).lineTo(10,5).mirror('x').close()
 mirror(axis: "x" | "y" | [ number, number ]): this
 ```
 
+#### `toPolyline()` — Return the open path as a sampled 2D polyline.
+
+This is for construction geometry such as guide rails, measured centerlines, and curve-driven helpers where the authored path should stay open instead of becoming a filled sketch or stroked profile.
+
+```ts
+const rail = path()
+  .moveTo(24, 0)
+  .bezierTo(32, 44, 28, 92, 18, 120)
+  .toPolyline();
+```
+
+```ts
+toPolyline(): [ number, number ][]
+```
+
 #### `closeOffset()` — Close the path and return an offset version of the filled Sketch. Positive delta expands outward, negative shrinks inward.
 
 ```ts