forgecad 0.9.16 → 0.10.1

package/dist-skill/library/forgecad-project/SKILL.md

@@ -4,136 +4,16 @@ description: ForgeCAD project CLI workflow — creating, managing, syncing proje
 forgecad-public: true
 ---
 
-# ForgeCAD Project CLI Workflow
-
-## Overview
-
-**forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` opens the installed local editor for users; `forgecad dev <project-path> [project-path ...]` is mainly for ForgeCAD source development.
-
-Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
-
-## Authentication
-
-```sh
-forgecad login                          # Choose email/password or API token
-forgecad login --server http://localhost:5174  # Local dev server
-forgecad logout
-forgecad whoami                         # Show user, server, license
-```
-
-## Project Lifecycle
-
-### Create a project
-
-```sh
-cd path/to/my-models
-forgecad project init "My Project Name"
-forgecad project init "My Project" --slug my-project --visibility public
-```
-
-Creates the project on the server, writes `forgecad.json` locally, and pushes any existing local files.
-
-### Clone an existing project
-
-```sh
-forgecad project clone <slug>
-```
-
-Downloads into a new local directory.
-
-### Sync (push/pull)
-
-```sh
-forgecad project push [--force]         # Upload local changes
-forgecad project pull [--force]         # Download remote changes
-forgecad project status                 # Show local vs remote diff
-```
-
-Sync is content-hash-based (SHA-256) — no timestamps, no git. `--force` skips confirmation.
-
-### Inspect and modify
-
-```sh
-forgecad project list                   # List all your projects
-forgecad project info                   # Name, visibility, files, URL
-forgecad project rename "New Name"      # Rename
-forgecad project set-visibility public  # private | shared | public
-forgecad project delete [--force]       # Permanently delete
-forgecad project open                   # Open in browser
-```
-
-## Remote File Management
-
-Prefer `forgecad project status`, `forgecad project pull`, and `forgecad project push` for normal local sync. Use direct remote file commands only when you need a single hosted file operation without a full push/pull cycle:
-
-```sh
-forgecad project file list [path]               # List remote files
-forgecad project file read <path>               # Print contents to stdout
-forgecad project file save <path>               # Upload local file (same relative path)
-forgecad project file save <path> --content "const x = box(10, 10, 10); return x;"
-cat model.forge.js | forgecad project file save model.forge.js --stdin
-forgecad project file delete <path> [--force]   # Delete remote file
-forgecad project file rename <old> <new>        # Rename/move
-forgecad project file mkdir <path>              # Create directory
-forgecad project file copy <source-slug> <path> [--dest <dest-path>]  # Copy from another project
-```
-
-All file commands require being inside an initialized project (has `forgecad.json`).
-
-## Member Management
-
-```sh
-forgecad project members                          # List members
-forgecad project add-member alice@example.com     # Add as editor (default)
-forgecad project add-member bob@example.com --role viewer
-forgecad project remove-member alice@example.com
-forgecad project set-role bob@example.com editor
-```
-
-Roles: **owner** (full control), **editor** (read/write), **viewer** (read-only).
-
-## Publishing & Sharing
-
-```sh
-forgecad project publish model.forge.js --title "My Model"   # Publish, get URL
-forgecad project publish model.forge.js --no-sync             # Skip auto-push
-forgecad project shares list                           # List published models
-forgecad project shares delete <share-id> [--force]    # Unpublish
-forgecad link <gist-url-or-id>                        # Share from Gist
-```
-
-Published models are viewable at `forgecad.io/m/<shareId>`. Shares are **live references** to project files — they always show the current version, not a snapshot. Publishing requires a project context.
-
-## AI Agent Workflow Example
-
-```sh
-# 1. Authenticate
-forgecad login
-
-# 2. Create project
-mkdir my-gadget && cd my-gadget
-forgecad project init "My Gadget" --visibility private
-
-# 3. Create a model
-forgecad new housing --template part
-
-# 4. Edit and push
-# ... edit housing.forge.js ...
-forgecad project push --force
-
-# 5. Or save directly to remote
-forgecad project file save housing.forge.js --content "$(cat housing.forge.js)"
-
-# 6. Validate
-forgecad run housing.forge.js
-
-# 7. Publish
-forgecad project publish housing.forge.js --title "Gadget Housing"
-```
-
-## How sync works
-
-- Scans local source files (`.forge.js`, `.js`, `.svg`), hashes each with SHA-256 (16-char prefix)
-- Fetches remote files from `/api/projects/:projectId/files`, hashes them the same way
-- Diffs: `added` (local only), `deleted` (remote only), `modified` (hash mismatch), `unchanged`
-- No timestamps, no git — purely content-based
+# ForgeCAD Project Operating Rules
+
+forgecad.io is the hosted ForgeCAD platform; a project is a local folder linked to the server by `forgecad.json`. The full command inventory (project, file, member, share, token commands and flags) lives in `forgecad project --help` and the forgecad skill's `docs/CLI.md` — do not relearn it here.
+
+- **One studio process.** Run a single long-running `forgecad studio <folder> [<folder> ...]` naming every active project folder. The user opens the one printed localhost port once; create and edit files only under those folders so the browser live-updates. Never spawn extra servers per project.
+- **studio vs dev.** `forgecad studio` is for users and agents; `forgecad dev` is only for developing ForgeCAD itself.
+- **Login only for hosted commands.** `forgecad login` before any `project`/`publish` command; local work (run, render, studio) needs no auth.
+- **init creates, push syncs.** `project init "Name"` creates the remote project, writes `forgecad.json`, and pushes existing local files. `push` only syncs an already-initialized project. `clone <slug>` is the inverse: remote → new local folder.
+- **Sync is content-hash based.** `status`/`push`/`pull` compare file content hashes — no timestamps, no git; a file is "modified" purely by content difference. Loop: edit → `project status` → `project push`.
+- **Sync vs single-file ops.** Use `status`/`pull`/`push` for normal sync; use `project file <read|save|delete|...>` only for one hosted-file operation without a full push/pull cycle.
+- **Project context required.** All `project file *` and `publish` commands must run inside a folder containing `forgecad.json`.
+- **Shares are live references.** A published model always shows the current project file, never a snapshot — pushing changes silently updates published models. `publish` prints the share URL.
+- **Non-interactive runs.** Pass `--force` to skip confirmation prompts (push, pull, delete) in agent automation.

package/dist-skill/library/forgecad-reconstruction-benchmark/SKILL.md

@@ -6,137 +6,43 @@ forgecad-public: true
 
 # ForgeCAD Reconstruction Benchmark
 
-Use this skill inside a prepared ForgeCAD reconstruction benchmark workspace.
-The task is to rebuild the supplied CAD reference as editable ForgeCAD source,
-not to wrap, embed, or copy the source asset.
+Benchmark adaptation of `forgecad-3d-reconstruction`: same reconstruction loop, but with a fixed submission path, a local CLI wrapper, sandbox limits, and a short wall-clock budget. This sheet owns only those deltas — follow `forgecad-3d-reconstruction` for the reconstruction craft.
 
-This is a benchmark adaptation of `forgecad-3d-reconstruction`: same evidence
-and coarse-to-fine reconstruction loop, but with a fixed output path, strict
-submission rules, and a short wall-clock budget.
+## Workspace
 
-## Workspace Contract
+Read first: `AGENTS.md`, `task/instructions.md`, this skill, and `agent-home/.agents/skills/forgecad/SKILL.md` (API + CLI reference).
 
-Read these first:
+- Reference asset (evidence only): `task/reference/*`
+- Final answer: `submission/main.forge.js`, unless `task/task.json` overrides
+- CLI: the local wrapper `./bin/forgecad`, never global commands
+- Scratch renders/notes: `outputs/`
+- Stay inside the prepared workspace.
 
-- `AGENTS.md`
-- `task/instructions.md`
-- this skill
-- `agent-home/.agents/skills/forgecad/SKILL.md` for API guidance
+```bash
+./bin/forgecad run submission/main.forge.js
+```
 
-Useful companion skills:
+## Rules and Done Criteria
 
-- `forgecad-3d-reconstruction` for the general reconstruction workflow
-- `forgecad-render-inspect` for interpreting inspection bundles
-- `forgecad-make-a-model` only for general model quality patterns; do not use
-  its date-based file-placement workflow in benchmark workspaces
+- Deliverable is readable parametric ForgeCAD source at the required submission path. A clean parametric approximation beats an unreadable mesh mimic.
+- The final source must not call `Import.mesh`, `Import.step`, `importMesh`, `importStep`, `readFile`, `readFileSync`, or any equivalent asset-embedding trick, and must contain no `compareWith(...)`, external reference paths, base64 payloads, or debug probes.
+- Sandbox: allowed local tools only — no web search, no broad home-directory access, no subagents, no remote services.
+- Before exit: the run command above succeeds; visual/section evidence checked after the last meaningful edit; model recognizable against the reference from the main views.
 
-Common files:
+## Budget Discipline
 
-- reference asset: `task/reference/*`
-- final answer: `submission/main.forge.js` unless `task/task.json` says otherwise
-- local ForgeCAD wrapper: `./bin/forgecad`
-- scratch outputs: `outputs/`
+A runnable first candidate beats a perfect investigation with no model.
 
-Stay inside the prepared workspace. Use the local wrappers instead of global
-ForgeCAD commands.
+1. Run the starter submission once before editing so syntax/runtime problems surface early.
+2. Inspect only the highest-value reference evidence: dimensions, volume, object count, one visual or sectional view. If a reference render/inspect command fails or stalls, continue from task instructions, filename, starter code, and mechanical inference — do not burn the budget retrying.
+3. Write a short reconstruction brief in `outputs/brief.md` (fields per `forgecad-3d-reconstruction`).
+4. Edit the submission early: coarse bbox, orientation, and main masses first, then iterate coarse-to-fine per `forgecad-3d-reconstruction`.
+5. 3MF references: the `forgecad run` source-structure table is evidence — account for every substantial 3MF item in the reconstruction (the final model may be one part or many).
+6. `inspect section` probes are replayable against the candidate via `inspect replay` — the cheap way to verify an exact local measurement transfers. Mechanics: `forgecad-render-inspect`.
 
-## Non-Negotiables
+## Pointers
 
-- Final deliverable is readable parametric ForgeCAD source at the required
-  submission path.
-- The reference asset is evidence only. The final source must not call
-  `importMesh`, `importStep`, `readFile`, `readFileSync`, or equivalent asset
-  embedding tricks.
-- Do not leave `compareWith(...)`, external reference paths, base64 payloads, or
-  debug probes in the final submission.
-- Do not spend the whole budget inspecting. A runnable first candidate is more
-  valuable than a perfect investigation with no model.
-- Use only allowed local tools. Do not rely on web search, broad home-directory
-  access, subagents, or remote services.
-
-## Budget-Aware Workflow
-
-1. Orient quickly.
-   Read `task/instructions.md`, locate the reference file, and inspect the
-   starter submission. Run the starter once so syntax or runtime problems are
-   obvious before you edit.
-
-   ```bash
-   ./bin/forgecad run submission/main.forge.js
-   ```
-
-2. Inspect only the highest-value evidence.
-   Get dimensions, volume, object count, and at least one visual or sectional
-   clue when the renderer is available. If a reference command fails or stalls,
-   continue from task instructions, filename, starter code, and mechanical
-   inference.
-
-   ```bash
-   ./bin/forgecad ls task/reference/<asset> --quality live --long
-   ./bin/forgecad render 3d task/reference/<asset> outputs/reference.png --camera iso --edges thin --size 900
-   ./bin/forgecad inspect sections sample task/reference/<asset> outputs/reference-sections --count 5 --size 700
-   ./bin/forgecad inspect section task/reference/<asset> --plane yz --offset 0 --ray width:-50,0:50,0 --size 700
-   ```
-
-   For 3MF references, the `forgecad run` output includes a source structure
-   table with stable `3mf:build:...:object:...` refs, automatic item names,
-   per-item bounding boxes, and triangle counts. Treat that table as part of
-   the evidence: the final model may be one part or many parts, but you should
-   account for every substantial 3MF item in the reconstruction brief.
-
-   Use `inspect section` when you need an exact local measurement. It writes a
-   unique probe directory with `result.json`; later you can replay that probe
-   against the candidate with `./bin/forgecad inspect replay <result.json>
-   --source submission/main.forge.js`.
-   For 3MF references, the `forgecad run` output includes a source structure
-   table with stable `3mf:build:...:object:...` refs, automatic item names,
-   per-item bounding boxes, and triangle counts. Treat that table as part of
-   the evidence: the final model may be one part or many parts, but you should
-   account for every substantial 3MF item in the reconstruction brief.
-
-3. Write a short Reconstruction Brief in your notes or `outputs/brief.md`.
-   Capture identity, bbox, major primitive families, symmetry, holes/cutouts,
-   likely manufacturing intent, and the first modeling plan. Keep it short.
-
-4. Edit the submission early.
-   Build a coarse candidate that matches bbox, orientation, and main masses
-   before adding details. Prefer simple analytic primitives, sketches, booleans,
-   revolves, patterns, and blueprint-first dimensions over vertex chasing.
-
-5. Self-check and iterate.
-   Use command success, rendered views, details, and section slices as the main
-   feedback. Improve in this order: bbox and origin, main silhouette, large
-   holes/cutouts, ribs/bosses, edge treatments, then small details.
-
-   ```bash
-   ./bin/forgecad run submission/main.forge.js
-   ./bin/forgecad render 3d submission/main.forge.js outputs/submission.png --camera iso --edges thin --size 900
-   ./bin/forgecad render section submission/main.forge.js outputs/submission-section.svg --plane XZ --offset 0
-   ```
-
-   For closer comparison, render corresponding reference and candidate views or
-   slices into `outputs/` and inspect the images/files side by side:
-
-   ```bash
-   ./bin/forgecad render 3d task/reference/<asset> outputs/reference.png --camera iso --edges thin --size 900
-   ./bin/forgecad inspect sections sample task/reference/<asset> outputs/reference-sections --count 5 --size 700
-   ```
-
-6. Final cleanup.
-   Re-run the candidate and inspect the most useful final views or sections.
-   Remove temporary imports, `compareWith`, debug-only geometry, scratch paths,
-   and comments that describe abandoned attempts. Leave the best source at the
-   required submission path.
-
-Optimize real geometry and design intent. A clean parametric approximation that
-captures the object is preferable to an unreadable mesh mimic.
-
-## Done Criteria
-
-Before exit:
-
-- `./bin/forgecad run submission/main.forge.js` succeeds.
-- Final render or section evidence has been checked after the final meaningful
-  edit.
-- The required submission file contains no banned import/read/embed path.
-- The model is recognizable against the reference from the main views.
+- `forgecad-3d-reconstruction` — the evidence → brief → coarse → fine loop and metric diagnosis
+- `forgecad-render-inspect` — inspection bundles, section probes, replay
+- forgecad skill at `agent-home/.agents/skills/forgecad/` — API and CLI syntax
+- `forgecad-make-a-model` — general quality patterns only; its date-based file-placement workflow does not apply in benchmark workspaces

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

@@ -6,82 +6,25 @@ forgecad-public: true
 
 # ForgeCAD Render Inspect
 
-Use `forgecad inspect ...` when a shaded viewport render is too ambiguous and you need structured evidence about a ForgeCAD model. Most inspection commands write a deterministic directory bundle containing evidence PNGs plus a root `manifest.json`; `inspect section` writes a one-off probe directory with `result.json`, `section.svg`, and `section.png`.
+Use `forgecad inspect ...` when a shaded render is too ambiguous and you need structured evidence: a bundle directory with evidence PNGs plus a root `manifest.json` (or, for `inspect section`, a probe directory with `result.json`, `section.svg`, `section.png`). Inspection is not a substitute artifact: look inside with sections, masks, `--focus`/`--hide`, and transparency — never edit the model into a cutaway or exploded default to make inspecting easier. Output dirs: let `inspect` allocate its timestamped directory by default (repeated probes never collide); use `/tmp/<model>-inspect` for throwaway bundles, a project directory only for persistent artifacts.
 
-This skill owns the inspection workflow: choosing evidence, generating the bundle, reading the manifest, visually inspecting the relevant PNGs, and turning the findings into model fixes or a verification report.
-
-Inspection is not a substitute artifact. Use sections, object masks, transparency, focus, and hide controls to look inside a real model; do not edit the model into a cutaway or exploded default just to make the inspection easier.
-
-## Trigger Boundary
-
-Use this skill for:
-
-- inspecting an existing `.forge.js` model
-- analyzing a previously generated inspection bundle
-- validating collisions, wall thickness, section cuts, connectivity, floating bodies, distance, object masks, depth, normals, or Zebra stripes
-- deciding which inspection evidence to run
-- producing evidence before calling a model complete
-
-Routing:
-
-| Need | Skill |
-|------|-------|
-| Learn or use ForgeCAD APIs while authoring geometry | `forgecad` |
-| Create a new model in the personal model repo | `forgecad-make-a-model` |
-| Run and interpret inspection bundles | `forgecad-render-inspect` |
-| Debug the inspection command implementation itself | `forgecad` plus this skill's source map |
+Routing: authoring/API questions → `forgecad` skill; creating a new model → `forgecad-make-a-model`.
 
 ## Workflow
 
-1. Identify the inspection question.
-   Decide what would make the model wrong: unexpected overlap, too-thin walls, missing parts, hidden cavity failure, disconnected bodies, unintentionally fused bodies, orientation artifacts, or object identity confusion.
-
-2. Choose output persistence.
-   Let `inspect section` allocate its timestamped output directory by default so repeated probes never collide. Use `/tmp/<model-name>-inspect` for temporary bundle outputs, or a project output directory only when the user wants a persistent artifact.
-
-3. Pick the evidence.
-   Prefer one targeted evidence command at a time. Use `forgecad inspect evidence`
-   to list the available commands.
-
-4. Run the command.
-   In the ForgeCAD repo, prefer the built CLI when you want the current checkout:
-
-   ```bash
-   node dist-cli/forgecad.js inspect fit interference model.forge.js --camera iso --size 700
-   ```
-
-   Outside the ForgeCAD repo, use the installed CLI:
-
-   ```bash
-   forgecad inspect fit interference model.forge.js --camera iso --size 700
-   ```
-
-   If the model may not execute, run `forgecad run model.forge.js` first. If imports are suspect, add `--debug-imports` to the run command.
-
-5. Summarize the manifest.
-   Run the bundled helper:
+1. **Identify the failure question.** What would make the model wrong: overlap, thin walls, hidden cavity failure, disconnected or accidentally fused bodies, floating parts, orientation artifacts, identity confusion?
+2. **Confirm the model executes.** If in doubt, run `forgecad run model.forge.js` first; add `--debug-imports` for suspect imports.
+3. **Pick ONE targeted evidence command** from the table below. `forgecad inspect evidence` lists everything available.
+4. **Summarize the manifest first**, then use `jq` against `manifest.json` for targeted follow-up. The helper ships beside this SKILL.md — invoke it skill-dir-relative; it accepts the bundle directory or a `manifest.json` path:
 
    ```bash
-   python agent-skill-library/forgecad-render-inspect/summarize_manifest.py /tmp/model-inspect
+   python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
    ```
 
-   Use `jq` for targeted follow-up when needed:
-
-   ```bash
-   jq '.evidence.collisions | {collisionCount, collisions, warnings}' /tmp/model-inspect/manifest.json
-   jq '.evidence.thickness.objects[] | {name, minThickness, p05Thickness, criticalAreaPercent, warningAreaPercent, unresolvedAreaPercent}' /tmp/model-inspect/manifest.json
-   jq '.evidence.connectivity | {componentCount, edges, warnings}' /tmp/model-inspect/manifest.json
-   jq '.evidence.floating | {floatingBodyCount, floatingObjectCount, warnings}' /tmp/model-inspect/manifest.json
-   ```
-
-6. Inspect the PNGs, not only the JSON.
-   Always look at the view PNGs that match the risk. Use the manifest paths instead of assuming layout when writing automation; custom cameras may not use canonical filenames.
-
-7. Decide whether findings are bugs.
-   Treat unexpected collision findings, critical thin regions, high unresolved thickness, missing sections, wrong object names, wrong component count, or surprising distance gaps as model bugs. If an overlap is intentional, isolate the check with `--focus` or `--hide` so the remaining report is meaningful.
-
-8. Report evidence.
-   Include the exact command, bundle path, evidence emitted, manifest highlights, PNG views inspected, and any residual limits. Do not say the geometry is verified if you only ran `forgecad run`.
+5. **Inspect the PNGs, not only the JSON.** View identity/context images first, then the risk evidence's view, then orthogonal cameras (`front`, `right`, `top`) when iso hides the issue, sections only when internals matter. In automation, resolve file paths through the manifest — custom cameras break canonical filenames.
+6. **Isolate intentional overlaps** with `--focus "A,B"` or `--hide "C"` so the remaining report stays meaningful.
+7. **Treat findings as model bugs**: unexpected collisions, critical thin regions, high unresolved thickness area, wrong component counts, floating bodies, or surprising gaps mean fix the model and reinspect.
+8. **Report honestly.** Include the exact command, bundle path, manifest highlights, and the PNG views actually inspected. Never claim geometry is verified if you only ran `forgecad run`.
 
 ## Evidence Selection
 
@@ -91,9 +34,9 @@ Routing:
 | Kinematic rig, joints, axes, and links | `inspect visual rig` |
 | Object naming and identity | `inspect visual objects` |
 | Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
-| Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at|stack|sample` |
+| Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at\|stack\|sample` |
 | Multi-part interference, fit checks, ghost parts, moving clearances | `inspect fit interference` |
-| Printability, shell walls, ribs, bosses, snaps, slots | `inspect manufacture thickness` plus `inspect sections at|stack|sample` when internals matter |
+| Printability, shell walls, ribs, bosses, snaps, slots | `inspect manufacture thickness` plus `inspect sections at\|stack\|sample` when internals matter |
 | Parts without a mesh-contact path to the ground | `inspect physical floating` |
 | Accidental fusion, connected solids | `inspect physical components` |
 | Air gaps between physical components | `inspect physical gaps` |
@@ -101,117 +44,25 @@ Routing:
 | Loft, fillet, skin, and sweep surface continuity | `inspect surface zebra` or `inspect visual normals` |
 | Reference-vs-candidate reconstruction comparison | `inspect compare overlay --with reference.3mf` |
 
-## Command Patterns
+## Section Probe + Replay
 
-Explicit fast bundle:
+The agent-native measure-then-recheck loop:
 
 ```bash
-forgecad inspect visual objects model.forge.js --camera iso --size 700
-forgecad inspect visual rig model.forge.js --camera iso --size 700
-forgecad inspect sections at model.forge.js --plane yz --offset 12.5 --size 700
-forgecad inspect sections stack model.forge.js --plane yz --every 1 --size 700
-forgecad inspect sections sample model.forge.js --count 5 --size 700
-```
-
-Agent-native one-off section probe:
-
-```bash
-forgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0 --size 700
+forgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0
 forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js
 ```
 
-Reference-vs-candidate comparison bundle:
-
-```bash
-forgecad inspect compare overlay candidate.forge.js --with reference.3mf --compare-samples 3000 --size 700
-```
-
-Final fit/interference check:
-
-```bash
-forgecad inspect fit interference model.forge.js --camera iso --size 700
-```
-
-Collision-focused isolation:
+The probe's `result.json` field contract (frames, rulers, gaps, replaySpec) is documented in the forgecad skill's `docs/guides/inspection-bundles.md`.
 
-```bash
-forgecad inspect fit interference model.forge.js --focus "Bracket,Screw Ghost" --camera iso
-```
-
-Thickness check with process-aware thresholds:
-
-```bash
-forgecad inspect manufacture thickness model.forge.js --min 1.6 --warn 2.4 --camera iso
-```
+## Misread Traps
 
-Hide known clutter or mock geometry:
+- Face-touching is not a collision; collision findings are positive-volume overlaps.
+- Gray/unresolved thickness area means the evidence is incomplete, not that the model is safe.
+- Distance/gap figures are bbox-gap metrics between components, not closest-surface distances.
+- Depth, normals, and zebra are visual aids (heatmap, camera-view normals, stripe shader), not exact measurements or curvature proofs.
+- Resolve mask colors through the manifest's object list, never by object order.
 
-```bash
-forgecad inspect fit interference model.forge.js --hide "Fixture Ghost,Debug Envelope" --camera iso
-```
-
-Use bare `--focus` to hide mock objects while keeping real scene objects:
-
-```bash
-forgecad inspect fit interference model.forge.js --focus --camera iso
-```
+## Reference
 
-## Reading Results
-
-Manifest fields to check first:
-
-- `bundle.evidenceRequested` / `bundle.evidenceEmitted`: confirm you inspected what you intended.
-- `bundle.filters`: confirm focus/hide did not accidentally exclude relevant geometry.
-- `scene.bbox` and `scene.volume`: catch absurd scale, missing geometry, or bad units.
-- `scene.objects`: confirm expected part names and mock flags.
-- `evidence.objects.objects`: map object colors to names; do not rely on object order alone.
-- `evidence.collisions.collisionCount`: investigate every unexpected positive-volume overlap.
-- `evidence.thickness.objects`: inspect `minThickness`, `p05Thickness`, critical/warning percentages, and unresolved area.
-- `evidence.connectivity.componentCount`: compare to the expected number of physical components.
-- `evidence.floating.floatingBodyCount`: investigate every body without a mesh-contact path to the ground plane, especially body entries from one unioned object.
-- `evidence.distance.maxRootDistance` and per-object `nearestGap`: check suspicious isolation or spacing.
-- `evidence.sections.slicingPolicy`: confirm whether the bundle used exact, count-based, or physical-spacing slices.
-- `evidence.sections.planes`: look for missing slices, wrong path counts, empty internal cuts, plane normals, spacing, and slice counts. These are inspection views, not instructions to section the returned production geometry.
-
-`inspect section` result fields to check first:
-
-- `section.frame`: use `u` and `v` to understand the section-local coordinate system for rulers.
-- `section.objects`: inspect per-object areas, bounds, and loop counts. Use `section.svg` for the actual section outlines.
-- `rulers[].insideSegments`: exact intervals where the ray is inside any sectioned object.
-- `rulers[].gaps`: exact intervals between solid spans along the ray, including end gaps.
-- `comparison.rulers`: replay deltas against the original probe when using `inspect replay`.
-- `replaySpec`: the recipe an agent can rerun against a candidate model.
-
-PNG review order:
-
-1. Image evidence for human shape sanity when needed.
-2. Object evidence and one orthogonal object view for identity when needed.
-3. The risk evidence's chosen view.
-4. Orthogonal cameras (`front`, `right`, `top`) when the iso view hides the issue.
-5. Section slices around the suspected feature when internals matter.
-
-## Interpretation Rules
-
-- Collision findings are positive-volume boolean overlaps. Face-touching is not a collision.
-- Connectivity uses bbox as a broadphase, then shared physical-contact detection for component grouping: mesh surfaces within contact tolerance count as connected, exact positive-volume overlap is used when needed, and bbox-only contact does not merge separate scene objects by default. Use collisions evidence for positive-volume overlap defects.
-- Floating uses the same shared physical-contact detection plus scene-ground reachability. Mesh gaps within contact tolerance count as connected, bbox overlap or bbox face contact alone does not, and every component without a contact path to ground is reported. Disconnected mesh islands inside one object are inspected separately.
-- Distance is a bbox-gap metric between physical components, not exact closest surface distance.
-- Thickness is a contact-aware mesh/raycast approximation. It uses the same physical-contact edges as connectivity/floating, so rays jump over direct-neighbor contact seams within contact tolerance before measuring the next surface. Gray or high unresolved area means the visual heatmap is incomplete, not that the model is safe.
-- Depth is a visual heatmap, not raw floating-point depth data.
-- Normals are camera-view normals, not world-space normals.
-- Zebra is a reflective stripe shader for visual continuity inspection, not an exact curvature-continuity proof.
-- Mask colors are stable within a bundle and resolved through the manifest.
-
-## Source Map
-
-Read these only when needed:
-
-| Need | Source |
-|------|--------|
-| Bundle contract and evidence semantics | `docs/permanent/guides/inspection-bundles.md` |
-| CLI reference and options | `docs/permanent/CLI.md` |
-| CLI parser, bundle writer, manifest generation | `cli/forge-render.mjs` |
-| Browser-side evidence rendering | `cli/render.ts` |
-| Collision semantics | `cli/collision-inspection.ts` |
-| Thickness semantics | `cli/thickness-inspection.ts` |
-| Connectivity, floating, and distance semantics | `cli/physical-connectivity.ts`, `cli/floating-inspection.ts`, and `cli/distance-inspection.ts` |
+Bundle/manifest contract, evidence semantics, and current limits: the forgecad skill's `docs/guides/inspection-bundles.md`. CLI flags and command tree: its `docs/CLI.md`.