forgecad 0.9.13 → 0.9.15

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

@@ -1,46 +0,0 @@
----
-skill-group: geometry
-skill-order: 1
----
-
-# Coordinate System Convention
-
-ForgeCAD uses a **Z-up** right-handed coordinate system.
-
-## Axes
-
-| Axis | Direction       | Positive |
-|------|-----------------|----------|
-| X    | Left / Right    | Right    |
-| Y    | Forward / Back  | Forward  |
-| Z    | Up / Down       | Up       |
-
-## Standard Views
-
-| View   | Camera position direction | Sees plane |
-|--------|--------------------------|------------|
-| Front  | −Y                       | XZ         |
-| Back   | +Y                       | XZ         |
-| Right  | +X                       | YZ         |
-| Left   | −X                       | YZ         |
-| Top    | +Z                       | XY         |
-| Bottom | −Z                       | XY         |
-
-## GizmoViewcube Face Mapping
-
-Three.js BoxGeometry material indices vs ForgeCAD labels (Z-up remapping):
-
-| Index | Three.js direction | ForgeCAD label |
-|-------|--------------------|----------------|
-| 0     | +X                 | Right          |
-| 1     | −X                 | Left           |
-| 2     | +Y                 | Front          |
-| 3     | −Y                 | Back           |
-| 4     | +Z                 | Top            |
-| 5     | −Z                 | Bottom         |
-
-Default drei labels are Y-up; ForgeCAD passes `faces={['Right','Left','Front','Back','Top','Bottom']}`.
-
-## Grid
-
-The ground plane is XY (Z = 0). Extrusion goes along +Z. Manifold is Y-up internally — if a kernel-facing operation behaves as if axes are swapped, check for Manifold Y-up semantics leaking through.

package/dist-skill/docs-dev/guides/geometry-conventions.md

@@ -1,52 +0,0 @@
----
-skill-group: geometry
-skill-order: 2
----
-
-# Geometry Conventions
-
-ForgeCAD wraps Manifold (mesh kernel) and Three.js (Y-up renderer). This doc captures convention mismatches and how ForgeCAD resolves them.
-
-## Winding Order
-
-CCW = positive area, CW = empty in Manifold's `CrossSection`. ForgeCAD auto-fixes at all entry points:
-- `polygon(points)` — computes signed area (shoelace), reverses if CW
-- `path().close()` — same fix
-
-**Rule for new code:** Any function accepting user point arrays that creates a `CrossSection` MUST auto-fix winding.
-
-## Coordinate System (Z-up vs Y-up)
-
-Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0,0,1)`) — geometry coordinates are native Z-up. Never swap Y/Z in geometry.
-
-## Revolution Axis
-
-`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
-
-## Boolean Winding (3D)
-
-Manifold requires consistent outward face normals. ForgeCAD only creates meshes through Manifold's own constructors, which guarantee correct normals.
-
-## Transform Order
-
-Transforms apply left-to-right. `Sketch.rotate()`, `scale()`, and `mirror()` operate around bounding-box center. For 3D `Shape` / `ShapeGroup`, `scale()` and `mirror()` operate around bounding-box center, while `rotate()` remains origin-based unless you pass `options.pivot` or use `rotateAroundAxis(...)`.
-
-For explicit transform objects: `A.mul(B)` = apply A then B; `composeChain(A, B, C)` = A→B→C.
-
-## Assembly Frame Composition
-
-```ts
-childWorld = composeChain(childBase, jointMotion, jointFrame, parentWorld)
-```
-
-Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code to avoid order mistakes.
-
-## Summary
-
-| Convention | User sees | Kernel needs | Where we fix it |
-|---|---|---|---|
-| Winding | Any point order | CCW | `polygon()`, `path().close()` |
-| Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
-| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
-| Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
-| Transform order | Left-to-right chain | Post-multiply | Native match |

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

@@ -1,485 +0,0 @@
----
-skill-group: cli
-skill-order: 2
----
-
-# Inspection Bundles
-
-`forgecad inspect <family> <mode>` 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 evidence such as depth, normals, Zebra
-stripes, surface roughness, part identity, physical connected components,
-interference, local thickness, or cross-sections.
-
-## When To Use It
-
-- Use `forgecad inspect <family> <mode>` for local agent repair loops, model
-  debugging, and targeted visual evidence.
-- Use `forgecad render 3d` for a quick human viewport PNG.
-- Use `forgecad render section` when you only need one specific cut plane.
-- Use `forgecad render hq` for presentation-quality output, docs, and marketing
-  renders.
-
-## Command
-
-```bash
-forgecad inspect fit interference model.forge.js --camera iso
-forgecad inspect visual cutaway model.forge.js --plane yz
-forgecad inspect visual objects model.forge.js --camera front --camera right
-forgecad inspect manufacture thickness model.forge.js --min 1.2 --warn 2.0
-forgecad inspect sections at model.forge.js --plane yz --offset 12.5
-forgecad inspect sections stack model.forge.js --plane yz --every 1
-forgecad inspect sections sample model.forge.js --count 5
-forgecad inspect compare overlay model.forge.js --with reference.3mf
-forgecad inspect evidence
-```
-
-The default output directory is a unique, non-colliding run directory under
-`outputs/inspect`, relative to the current working directory:
-
-```text
-outputs/inspect/2026-05-28T23-19-14.412Z__visual-objects__ball-bearing__43d0ee/
-```
-
-Pass a positional `output-dir` or `--output`/`--out` for a preferred directory.
-If that directory already exists, ForgeCAD writes to a numbered sibling unless
-`--force` is passed. `--force` is the explicit replace path.
-
-Non-section inspection commands emit one `iso` view by default, except
-`inspect visual cutaway`, which emits one automatic orthographic cut-side view.
-Pass `--camera` repeatedly, `--view`, `--camera-json`, or `--scene` to use the
-same view strategy as `render 3d`.
-
-Inspection visual evidence defaults to the `inspection` render style: a light
-technical background, matte neutral lighting, and thin dark edges for shaded
-image/cutaway evidence. Pass `--background`, `--render-style`, or `--edges` when
-you need a different presentation. Model-authored `scene()` background, lights,
-fog, and exposure are ignored for inspection bundle captures so evidence remains
-stable; named scene views are still available through `--view`.
-
-The command tree is intentionally job-shaped:
-
-```text
-inspect visual image|cutaway|depth|normals|objects
-inspect surface zebra|roughness
-inspect physical components|floating|gaps
-inspect fit interference
-inspect manufacture thickness
-inspect compare overlay
-inspect sections at|stack|sample
-```
-
-Manifest keys stay evidence-oriented for stable bundle readers. For example,
-`forgecad inspect fit interference` writes `manifest.evidence.collisions`, and
-`forgecad inspect physical components` writes `manifest.evidence.connectivity`.
-
-`--focus` and `--hide` use the same object-name filtering semantics as
-`forgecad run` and `forgecad render 3d`. A bare `--focus` hides mock objects;
-`--focus name1,name2` emits only matching objects; `--hide name1,name2` removes
-matching objects from an otherwise visible scene. Matching is case-insensitive
-and supports `*` / `?` globs, so grouped child objects are usually best matched
-with patterns such as `Bench.*`.
-
-## Bundle Layout
-
-Bundles store image evidence under an `evidence/` directory. An
-`inspect visual objects` bundle with `front`, `right`, and `iso` cameras has this
-layout:
-
-```text
-outputs/inspect/2026-05-28T23-19-14.412Z__visual-objects__model__43d0ee/
-  manifest.json
-  evidence/
-    objects/
-      front.png
-      right.png
-      iso.png
-```
-
-Use targeted evidence commands for expensive analyses:
-
-```bash
-forgecad inspect visual depth model.forge.js --camera iso
-forgecad inspect visual normals model.forge.js --camera iso
-forgecad inspect surface zebra model.forge.js --camera iso
-forgecad inspect surface roughness model.forge.js --camera iso
-forgecad inspect visual objects model.forge.js --camera iso
-forgecad inspect fit interference model.forge.js --camera iso
-forgecad inspect sections at model.forge.js --plane yz --offset 12.5
-forgecad inspect sections stack model.forge.js --plane yz --every 1
-forgecad inspect sections sample model.forge.js --count 5
-forgecad inspect manufacture thickness model.forge.js --min 1.2 --warn 2.0 --camera iso
-forgecad inspect compare overlay model.forge.js --with reference.3mf
-```
-
-Run `forgecad inspect evidence` for the canonical command list and the matching
-manifest evidence keys.
-
-## How To Read A Bundle
-
-Read inspection bundles as feedback about the model, not as standalone images.
-Start with `manifest.json`, then use the evidence PNGs to locate and understand
-the finding in the rendered geometry.
-
-1. Confirm `bundle.evidenceRequested`, `bundle.evidenceEmitted`, and
-   `bundle.filters` so you know what was inspected and what was hidden.
-2. Check `scene.bbox`, `scene.volume`, and `scene.objects` for missing geometry,
-   absurd scale, unexpected mocks, or wrong object names.
-3. For identity evidence such as `objects`, `connectivity`, `distance`, and
-   `collisions`, resolve colors through the evidence manifest. The same visual
-   color does not carry a universal meaning across bundles.
-4. For metric evidence such as `depth`, `roughness`, `thickness`, `distance`, and `comparison`,
-   read the thresholds, ranges, object summaries, and warnings before judging a
-   PNG by eye.
-5. Inspect image and object evidence first when you need visual context, then
-   the risk evidence and any orthographic view that exposes the issue. Use
-   section slices only to inspect hidden internals; do not turn the production
-   model into a permanent cutaway.
-6. Treat unexpected collisions, critical thin regions, unresolved thickness,
-   missing section detail, wrong component counts, floating bodies, or surprising
-   distance gaps as model bugs to fix and reinspect.
-
-Common color reading rules:
-
-- Black is usually background; in `floating`, black also means ground-reachable
-  geometry.
-- `objects` and `connectivity` colors are labels. Use the manifest to map colors to
-  objects, groups, components, or body entries.
-- `collisions` colors mark solid overlap findings; match them to
-  `manifest.evidence.collisions.collisions[].color`.
-- `thickness` uses red/orange for critical or warning-thin regions, green/blue
-  for acceptable or thick regions, and gray for unresolved samples.
-- `distance` grades rooted component gaps from green near the root through
-  yellow to red farther away.
-- `comparison` uses the same Difference Only overlay as the viewport: faint
-  model context, amber candidate mismatch evidence, and cyan reference mismatch
-  evidence.
-- `depth` grades visible camera distance from blue near the camera through green
-  to red farther away.
-- `roughness` uses orange and magenta for sharp, harsh, boundary, or
-  non-manifold edge neighborhoods.
-- `zebra` is read by stripe continuity: smooth flowing bands are healthy, while
-  kinks, breaks, and faceting deserve investigation.
-- `normals` is an encoded camera-view normal map. Use it with `image` and `zebra`
-  to debug orientation and faceting rather than as a fixed semantic palette.
-
-## Evidence Semantics
-
-`image` emits the standard solid viewport render with a thin edge overlay. Views
-are canonical `front`, `right`, `top`, and `iso`.
-
-`depth` emits visible ray-distance heatmaps. Each shaded pixel is colored by the
-distance from the camera position to the visible surface point, normalized per
-view between `minDistance` and `maxDistance` from the manifest:
-
-```text
-rayDistance = distance(cameraPosition, surfacePoint)
-normalized = (rayDistance - minDistance) / (maxDistance - minDistance)
-```
-
-The ramp is blue near the camera, green in the middle, and red far from the
-camera. Background pixels are black and should be treated as `null`.
-
-`normals` emits camera-view normals packed into RGB:
-
-```text
-normal = normalize((rgb / 255) * 2 - 1)
-```
-
-Background pixels are black and should be treated as `null`.
-
-`zebra` emits reflective black-and-white stripe renders for visual
-surface-continuity inspection. Stripes are generated from the visible
-camera-view normal and simulated reflection direction, so smooth surfaces show
-smooth flowing bands while normal discontinuities, faceting, and unexpected
-creases kink or break the bands.
-
-Use Zebra with `image` and `normals` when judging lofts, fillets, swept surfaces,
-and skin-like forms. It is a human-readable shader diagnostic, not an exact
-curvature-continuity proof; mesh tessellation quality and available smooth
-normals determine how faithfully it represents the underlying surface.
-
-`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 evidence to spot spiky tessellation, accidental faceting,
-jagged boolean residue, and dense sharp-corner regions without losing the
-silhouette of otherwise smooth surfaces.
-
-The evidence also writes `evidence/roughness/point-cloud.json`. Each point sample
-stores object identity, object-local position, normal, dihedral angle, class,
-RGB color, and represented surface area. The PNG renders those samples over
-muted source geometry so the visual evidence stays point-level instead of
-painting a whole object.
-
-`objects` emits one object-color image per view. Black is background. Non-black
-pixels resolve through `manifest.evidence.objects.objects`, which includes object
-index, RGB color, object id, name, group, tree path, and mock flag. Edge pixels
-may be antialiased blends; use solid interior colors for exact object lookup.
-
-`connectivity` emits one physical-component-color image per view. Black is
-background. Non-black pixels resolve through
-`manifest.evidence.connectivity.components`, and every visible object also has a
-`componentIndex` in `manifest.evidence.connectivity.objects`.
-
-Connectivity is computed from visible scene objects:
-
-```text
-bbox candidate = bbox interiors overlap or bbox contact gap <= 0.05 model units
-mesh contact edge = minimum mesh-surface distance <= contactTolerance
-overlap edge = exact boolean intersection volume > 0.1 model units^3 for positive-volume overlap
-component = transitive closure over mesh contact and exact overlap edges
-```
-
-The manifest stores the edge list, component list, per-object body counts, and
-warnings. Component colors group scene objects and mesh body entries. If one
-scene object contains multiple disconnected mesh islands, those islands are
-reported and colored separately as entries such as `Part body 1` and
-`Part body 2`.
-
-Connectivity uses bbox only as a broadphase. Bbox contact alone is not enough to
-merge separate scene objects by default, but mesh surfaces within contact
-tolerance count as physically connected. This keeps concave assemblies such as
-cages and captive balls from being falsely colored as one component while still
-allowing stacked or nearly touching parts to share a component. Use the
-`collisions` evidence when you need positive-volume overlap evidence as a defect
-report rather than a component grouping.
-
-`floating` emits one disconnected-body highlight image per view. Black is
-background or ground-reachable geometry. The highlight color marks physical
-components that have no contact path to the ground plane.
-
-Floating body detection splits visible meshes into disconnected body islands,
-links bodies only when their minimum mesh-surface distance is within contact
-tolerance (or exact positive-volume overlap when only shape evidence is
-available), treats any connected component whose lower Z reaches the viewport
-ground plane plus bed tolerance as grounded, then highlights every ungrounded
-component. The default ground plane is the visible model's minimum Z;
-`scene({ ground: { offset } })` moves it below that by the configured offset.
-
-```text
-grounded = component bbox minZ <= groundZ + bedTolerance
-floating body = !grounded
-```
-
-This means a `union()` result with two disconnected mesh islands is inspected as
-two separate bodies instead of being treated as one safe object. Bbox overlap or
-bbox face contact alone is not support evidence. Use `connectivity`, `distance`,
-or `collisions` when you need the full physical graph, rooted gap distances, or
-collision defects.
-
-`distance` emits one rooted physical-component-distance heatmap per view. Black
-is background. Non-black pixels resolve through
-`manifest.evidence.distance.components`, and every visible object also has
-`componentIndex`, `rootDistance`, `nearestGap`, and parent-tree metadata in
-`manifest.evidence.distance.objects`.
-
-Distance is computed from visible scene objects:
-
-```text
-component = physical connectivity component
-gap edge = Euclidean distance between component bounding boxes
-root = largest component by body count, object count, then bbox volume
-rootDistance = shortest accumulated gap distance from root component
-```
-
-For large scenes the manifest does not materialize the complete component gap
-graph, because that graph is quadratic in the number of components. The
-`gapEdgeCount` field reports the logical complete-graph edge count used by the
-analysis. `gapEdges` stores a compact evidence subset containing nearest-gap
-and root-parent edges.
-
-The PNG colors components from green at the root/near distances through yellow to
-red at the farthest rooted component. The manifest stores the root component,
-maximum rooted distance, compact gap edge evidence, nearest-gap data, and
-shortest-path parent fields. The current v1 metric is bbox-based: it measures air
-gaps between component bounding boxes, not exact closest mesh-surface distance.
-
-`comparison` emits one reference-vs-candidate overlay per view. Pass
-`--compare-with <reference>` or declare the target in model code with
-`compareWith('./reference.3mf')`. The PNG uses the same Difference Only
-comparison overlay as the viewport. Amber marks candidate mismatch evidence,
-cyan marks reference mismatch evidence, and faint candidate/reference context
-keeps the overlay readable while rotating or comparing against the standard RGB
-render.
-
-Colored mismatch evidence comes from sampled nearest-surface distances: cyan
-means reference surface missing from the candidate, and amber means extra
-candidate surface. Run `forgecad inspect sections at`, `stack`, or `sample` when
-you also want exact cross-section evidence next to the comparison context views.
-
-The manifest stores visual screen-space mismatch counts, the geometric
-`compare 3d` score when the CLI can resolve both inputs, and a
-`evidence/comparison/mismatch-points.json` point cloud with world-space sample
-positions. Use the geometric score and point-cloud summary as the source of
-truth; the PNG is the fast visual index for where to look.
-
-`collisions` emits one ghosted-overlap image per view. It uses the same
-`--focus` / `--hide` visibility set as every other inspect evidence: focused
-objects are the only inspected objects. Source objects render as translucent
-ghosts, while actual boolean intersection volumes render as solid per-finding
-palette colors.
-
-Collision findings are computed from visible scene objects:
-
-```text
-collision = boolean intersection volume > 0.1mm^3
-```
-
-The manifest stores the inspected objects, collision pair names/ids, overlap
-volume, broadphase counters, warnings, render style, and each collision finding's
-`groupIndex`, `color`, and `hex`. Exact interior pixels can be matched against
-`manifest.evidence.collisions.collisions[].color`; antialiased edges may blend
-with the ghosted source geometry. If `--focus PartA,PartB` is used, everything
-except those objects is hidden, `PartA` and `PartB` are ghosted, and their
-overlap volume is highlighted if present.
-
-Collision broadphase prunes exact boolean checks when the bbox intersection
-volume is already below the overlap threshold. This does not change findings:
-the real intersection volume cannot exceed the bbox intersection volume.
-
-`thickness` emits one local wall-thickness heatmap per view. The renderer places
-deterministic area-weighted point samples across visible mesh surfaces, casts
-through the object along each sample normal, and colors each point by the first
-opposite-surface distance:
-
-```text
-red    = thickness <= minThickness
-orange = thickness <= warnThickness
-green  = acceptable thickness
-blue   = thickness >= maxThickness
-gray   = unresolved sample
-```
-
-Thickness uses the same physical-contact edges as `connectivity` and `floating`.
-When a ray crosses from one object to a direct physical-contact neighbor, hits
-within `contactTolerance` are treated as contact seams and the ray continues to
-the next surface. This prevents a tiny modeled gap between touching parts from
-being reported as a paper-thin wall.
-
-The default thresholds are `minThickness=1.2`, `warnThickness=2.0`, and
-`maxThickness=6.0` model units. Override them with `--min-thickness`,
-`--warn-thickness`, and `--max-thickness`. Use `--thickness-samples` to raise or
-lower the maximum thickness point samples per object.
-
-The manifest stores the method, thresholds, palette, object list, per-object
-triangle counts, sampled-triangle counts, minimum, p05, median, mean, maximum,
-critical-area percentage, warning-area percentage, below-warning percentage, and
-unresolved-area percentage. This makes the PNG useful for visual debugging while
-the manifest remains the machine-readable source of truth.
-
-The evidence also writes `evidence/thickness/point-cloud.json`. Each point sample
-stores object identity, object-local position, normal, measured thickness,
-class, RGB color, and represented surface area. The PNG renders those samples
-over muted source geometry, so local evidence survives even when neighboring
-triangles have very different values.
-
-`roughness` uses the same area-weighted point placement. Point colors are local
-to nearby physical feature edges: smooth tessellation diagonals do not become
-visible roughness lines. Use `--roughness-samples` to raise or lower the maximum
-roughness point samples per object.
-
-`sections` is split into three explicit modes:
-
-- `sections at`: one precise section at an exact plane offset.
-- `sections stack`: periodic physical slices for reconstruction scans.
-- `sections sample`: a fixed number of sparse representative slices.
-
-Use `at` when an agent has localized a feature and needs the exact cross-section
-through it:
-
-```bash
-forgecad inspect sections at model.forge.js --plane yz --offset 12.5
-forgecad inspect sections at model.forge.js --angle 45 --offset 20
-```
-
-For reconstruction-grade evidence, request a physical stack:
-
-```bash
-forgecad inspect sections stack model.forge.js --plane yz --every 1
-```
-
-This emits a slice from the selected plane-family minimum to maximum at the
-requested spacing, plus a final max-bound slice when the span is not an exact
-multiple. Use `--plane xy|xz|yz` repeatedly or comma-separated to choose
-principal planes.
-
-Vertical angled families are available without manual normal math:
-
-```bash
-forgecad inspect sections stack model.forge.js --angle 45 --every 1
-```
-
-`--angle 0` is equivalent to a YZ-style vertical stack, `90` is
-equivalent to XZ, and other angles rotate the vertical plane family around Z.
-
-Use `sample` when you want sparse evidence without choosing exact offsets:
-
-```bash
-forgecad inspect sections sample model.forge.js --count 5
-forgecad inspect sections sample model.forge.js --plane yz --count 9
-```
-
-If no `--plane` or `--angle` is passed, `sample` emits the principal `xy`, `xz`,
-and `yz` families. The renderer refuses accidental giant bundles above
-`--max-slices` (default `1000`); raise that limit intentionally for large
-reconstruction scans.
-
-Each section slice records its exact offset, fraction when applicable, area,
-path count, size, and contributing object count in the manifest. Each plane
-family records its kind, normal, range, spacing, and slice count.
-
-## Manifest
-
-`manifest.json` is the authoritative contract for consuming a bundle. It
-contains:
-
-- `schemaVersion` and generator metadata.
-- Source entry file and project root paths.
-- Requested evidence, emitted evidence, filters, image size, and quality.
-- Canonical views.
-- Scene metadata: bbox, volume, params, cut planes, animations, verifications,
-  and objects.
-- Evidence metadata and relative file paths.
-
-A consumer should prefer paths from the manifest over hard-coding bundle layout.
-The layout is intentionally simple, but the manifest is where encoding details,
-per-view depth ranges, and object identity mappings live.
-
-## Current Limits
-
-- Depth is a visual heatmap, not an EXR or raw float array.
-- Normals are camera-view normals, not world-space normals.
-- Object evidence colors are stable within a bundle and resolved through the manifest; do
-  not infer identity from object order alone.
-- Connectivity is object-level. It reports disconnected kernel bodies in the
-  manifest, but the PNG does not split a single scene object into per-body colors.
-- Bbox contact is only broadphase evidence and does not merge separate scene
-  objects by default. Boolean-overlap edges are exact.
-- Distance is a physical-component bbox-gap metric in v1, not exact nearest
-  mesh-surface distance. Concave components and loose bounding boxes can make the
-  reported gap smaller than the real closest-surface distance.
-- Comparison PNG coverage is screen-space evidence. Hidden or internal
-  mismatches need the sampled point cloud and geometric score in the manifest.
-- Collisions are only positive-volume boolean overlaps. Face-touching parts are
-  not collision findings.
-- Thickness is a mesh/raycast approximation, not FEA or a manufacturability
-  guarantee. Open meshes, concave geometry, very coarse tessellation, or low
-  `--thickness-samples` values can leave gray/unresolved or approximate regions.
-- Section evidence is exact 2D contour slicing. Use `sections at`, `sections
-  stack`, or `sections sample`; bare `inspect sections` only explains the modes.
-- Zebra is a shader-based visual continuity aid, not exact curvature analysis.

package/dist-skill/docs-dev/guides/joint-design.md

@@ -1,78 +0,0 @@
----
-skill-group: recipes
-skill-order: 5
----
-
-# Joint Design Recipes
-
-How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
-
-## The Cavity Rule
-
-Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.
-
-If two adjacent parts in an assembly show a collision volume larger than the expected clearance volume in `forgecad run`, one part is missing its cavity. Both parts have solid material at the same joint position. This will look fine at rest pose but will block rotation and produce confusing joint behavior.
-
-```ts
-// BAD — body has a stadium cap at both ends; the "slot" between two clevis tines
-// is just empty space next to a solid body cap. The next phalanx's tongue knuckle
-// has nowhere to go (it intersects the previous body's cap).
-const body  = stadiumBar(L);            // cap at X=0 AND X=L
-const tine1 = box(...).translate(L,  Y_OFF, 0);
-const tine2 = box(...).translate(L, -Y_OFF, 0);
-let phalanx = union(body, tine1, tine2);
-
-// GOOD — body ends FLAT before the joint. Tines extend forward to the pivot.
-// The X = L-KNUCK_R..L+KNUCK_R volume between the tines is genuinely empty.
-const body = box(L - KNUCK_R, TONG_T, H).translate((L - KNUCK_R) / 2, 0, -H / 2);
-const tongueKnuckle = knuckleDisc(0, 0, TONG_T);  // proximal cap only
-let phalanx = union(tongueKnuckle, body, tine1, tine2, ...tineCaps);
-```
-
-After applying the cavity rule, `forgecad run` collision volume between adjacent parts in a clevis-tongue chain should drop to **zero** (or a few mm³ of clearance overlap). If it doesn't, there's still solid material where there should be a cavity.
-
-## Connecting Cantilevers
-
-A clevis tine arm at Y=±Y_OFF is geometrically separate from a body at Y=±TONG_T/2. With Y_OFF > TONG_T/2 + clearance, there is a **physical gap** between them. The tines float — they would snap off as soon as load is applied.
-
-Always add a **yoke**: a short slab spanning the full clevis width, sitting between the body's flat distal end and the tines' attachment point. The yoke fills the Y gap so material is continuous from the body through to each tine.
-
-```ts
-const yokeLen   = 3;                                  // a few mm of structural overlap
-const yokeStart = L - KNUCK_R - yokeLen;
-const totalY    = (Y_OFF + TINE_T / 2) * 2;           // full clevis width
-const yoke = box(yokeLen, totalY, H)
-  .translate(yokeStart + yokeLen / 2, 0, -H / 2);
-phalanx = union(phalanx, yoke);
-```
-
-## Hard Stops vs Slider Limits
-
-`addRevolute({ min: 0, max: 90 })` sets **slider limits** — the viewport won't let the user drag past them, but the geometry permits any rotation. There is no physical stop.
-
-For a **geometric** hard stop (parts can't backbend past extension, or can't curl past full closure), add a small protrusion on one part that interferes with the other at the limit angle:
-
-- **Extension stop at 0°** (typical for fingers, knees, elbows): add a small "lip" on the dorsal side of the proximal end of the child phalanx, sized so it just touches the parent's distal dorsal corner at 0°. Negative rotation (backbending) is then blocked by part-on-part contact.
-- **Flexion stop at θmax**: add a similar lip on the palmar side, or rely on the body-to-body collision when bodies meet.
-
-Verify with `forgecad run` at the limit poses — the contact pair should show ~0 mm³ collision (just touching), and rotation past the limit should report a non-zero collision volume.
-
-## Knuckle Sizing
-
-For a clevis-tongue joint with body height H, the tongue knuckle radius and clevis tine knuckle radius must satisfy:
-
-```
-KNUCK_R >= H / 2
-```
-
-If the knuckle radius is smaller than the body's half-height, the body's corners protrude beyond the knuckle envelope. When the joint rotates, those corners sweep through space outside the cylindrical envelope and collide with the adjacent part.
-
-Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that perfectly fits the knuckle envelope.
-
-## Verification Workflow
-
-1. Build the joint at rest pose. Run `forgecad run`. Check collision volumes.
-2. If adjacent parts in the joint show > clearance-volume of overlap → missing cavity (apply the cavity rule).
-3. Render with `--focus PartName` to inspect each part in isolation. The clevis end should clearly show a gap between the tines (the cavity).
-4. Render at curl angles (set joint debug params) at 30°, 60°, 90°. No new collisions should appear from rotation.
-5. Render at -10° (backbend test). Either no rotation possible (geometric stop in place) or rotation occurs and you need to add a stop.