forgecad 0.9.6 → 0.9.7

package/dist/docs-raw/AI/usage.md

@@ -172,9 +172,10 @@ Only add details after the proportions and assembly relationships are correct.
 
 Do not accept a model just because it renders. CAD quality comes from command evidence:
 
-- `forgecad run` confirms the script executes and reports geometry diagnostics.
+- `forgecad run` confirms the script executes and reports the fast inner-loop build summary.
 - `forgecad render 3d` gives visual views from deterministic cameras.
 - `forgecad render inspect` checks object masks, collisions, thickness, sections, depth, normals, and connectivity.
+- `forgecad inspect mechanical-integrity` checks assembly-level verification intent and optional collision evidence.
 - `forgecad check params` catches broken parameter ranges.
 - `forgecad export ...` verifies the actual manufacturing or interchange output.
 
@@ -184,12 +185,15 @@ The CLI is not just a launcher. It gives the agent a measurable feedback loop.
 
 | Need | Command | What it gives the agent |
 |---|---|---|
-| Execute and validate a model | `forgecad run model.forge.js` | Object summaries, volumes, bounds, construction history, parameters, verification results, collisions, spatial relationships, and solver diagnostics. |
+| Execute and validate a model | `forgecad run model.forge.js` | Fast red/green execution feedback: returned object names, parameters, verification results, script logs, and timing. |
+| Inspect run details | `forgecad run model.forge.js --details --history --features` | Per-object volumes and bounds, construction history, and feature tallies when those details are worth the extra work. |
 | Debug imports | `forgecad run model.forge.js --debug-imports` | Import resolution and module-loading diagnostics for multi-file projects. |
 | Compare geometry backends | `forgecad run model.forge.js --backend occt` | Runs against a specific backend when exact geometry or backend parity matters. |
 | Test physical connectivity | `forgecad run model.forge.js --connectivity` | Connected-component reporting for assemblies and printable parts. |
+| Check spatial relationships | `forgecad run model.forge.js --spatial bounded` | Opt-in directional relationships and bounded collision intersections during a run. |
 | Override parameters | `forgecad run model.forge.js -p "Width=120"` | Checks a model at a specific parameter value without editing source. |
 | Sweep parameter ranges | `forgecad check params model.forge.js --samples 12` | Finds parameter values that crash, collapse geometry, or introduce new collisions. |
+| Inspect mechanical integrity | `forgecad inspect mechanical-integrity model.forge.js --collisions` | Assembly-level verification, expected component counts, and collision evidence for acceptance gates. |
 | Produce visual evidence | `forgecad render 3d model.forge.js --camera iso` | PNG viewport renders from deterministic camera angles. |
 | Inspect geometry channels | `forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness --force` | A bundle with manifest plus RGB, mask, collision, wall-thickness, depth, normal, connectivity, distance, and section channels. |
 | Export manufacturing files | `forgecad export stl model.forge.js` and `forgecad export 3mf model.forge.js` | Mesh exports for 3D printing. |
@@ -262,6 +266,7 @@ For mechanisms, dense assemblies, printable parts, or anything safety-adjacent:
 
 ```bash
 forgecad run model.forge.js --connectivity
+forgecad inspect mechanical-integrity model.forge.js --collisions
 forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness,section --force
 forgecad check params model.forge.js --samples 12
 ```

package/dist/docs-raw/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/docs-raw/beta-operations.md

@@ -246,6 +246,11 @@ for the isolation win.
    callback to the prod app.
 2. Create a **new** Google OAuth client (OAuth 2.0 client ID, web app).
    Authorised redirect URI `https://beta.forgecad.io/auth/callback/google`.
+
+   Use Google Auth Platform → Clients in the Google Cloud Console for this.
+   Do not use `gcloud iam oauth-clients`; that command creates IAM/IAP OAuth
+   application resources, not the normal Google Sign-In web client that
+   ForgeCAD's `/auth/callback/google` flow expects.
 3. Add the four secrets to `.kamal/secrets.beta`:
 
    ```bash

package/dist/docs-raw/coding.md

@@ -19,7 +19,7 @@ npm run preview      # Preview production build
 ### CLI Tools
 ```bash
 forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js  # Export sketch to SVG
-forgecad render 3d examples/cup.forge.js         # Render to PNG (Puppeteer + Chrome)
+forgecad render 3d examples/products/cup.forge.js # Render to PNG (Puppeteer + Chrome)
 ```
 
 See [CLI.md](../CLI.md) for full CLI documentation.

package/dist/docs-raw/generated/concepts.md

@@ -17,7 +17,7 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 - **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(7 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(5 functions)*
-- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(31 functions)*
+- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(35 functions)*
 - **[C15: Import & Composition](#c15-import-composition)** — Bring external geometry or other ForgeCAD modules into the current script. *(1 functions)*
 - **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(4 functions)*
 
@@ -2868,6 +2868,46 @@ verify.centersCoincide(label: string, a: ShapeLike, b: ShapeLike, tolerance?: nu
 
 `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
@@ -2880,6 +2920,23 @@ verify.notColliding(label: string, a: ShapeLike, b: ShapeLike, searchLength?: nu
 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
@@ -3034,7 +3091,7 @@ Mock objects appear in the viewport and spatial analysis when you run a file dir
 
 The shape is returned unchanged, so you can reference it for alignment, dimensioning, and `verify` checks.
 
-Mock objects participate in `forgecad run` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
+Mock objects participate in `forgecad run --spatial bounded|exact` collision detection and spatial analysis. Their names appear with a `(mock)` suffix in reports.
 
 In the viewport, mock objects render at reduced opacity so they are visually distinct from real geometry.