Inspect Model
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.
Routing: authoring/API questions → forgecad skill; creating a new model → forgecad-build-model.
Workflow
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?
Confirm the model executes. If in doubt, run forgecad run model.forge.js first; add --debug-imports for suspect imports.
Pick ONE targeted evidence command from the table below. forgecad inspect evidence lists everything available.
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:
python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
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.
Isolate intentional overlaps with --focus "A,B" or --hide "C" so the remaining report stays meaningful.
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.
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
| Question |
Evidence command |
| Quick visual sanity |
inspect visual image |
| 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 |
| 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 |
| 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 |
| Surface orientation, occlusion, faceting, strange protrusions |
inspect visual depth or inspect visual normals |
| 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 |
Section Probe + Replay
The agent-native measure-then-recheck loop:
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
The probe's result.json field contract (frames, rulers, gaps, replaySpec) is documented in the forgecad skill's docs/guides/inspection-bundles.md.
Misread Traps
- 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.
Reference
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.
1---2name: forgecad-inspect-model3description: Select, run, and interpret ForgeCAD inspection evidence for collisions, sections, wall thickness, components, masks, depth, normals, surface continuity, and fit.4---5
6# Inspect Model
7
8Use `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.
9
10Routing: authoring/API questions → `forgecad` skill; creating a new model → `forgecad-build-model`.
11
12## Workflow
13
141. **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?
152. **Confirm the model executes.** If in doubt, run `forgecad run model.forge.js` first; add `--debug-imports` for suspect imports.
163. **Pick ONE targeted evidence command** from the table below. `forgecad inspect evidence` lists everything available.
174. **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:
18
19 ```bash
20 python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
21 ```
22
235. **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.
246. **Isolate intentional overlaps** with `--focus "A,B"` or `--hide "C"` so the remaining report stays meaningful.
257. **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.
268. **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`.
27
28## Evidence Selection
29
30| Question | Evidence command |
31|----------|------------------|
32| Quick visual sanity | `inspect visual image` |
33| Kinematic rig, joints, axes, and links | `inspect visual rig` |
34| Object naming and identity | `inspect visual objects` |
35| Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
36| Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at\|stack\|sample` |
37| Multi-part interference, fit checks, ghost parts, moving clearances | `inspect fit interference` |
38| Printability, shell walls, ribs, bosses, snaps, slots | `inspect manufacture thickness` plus `inspect sections at\|stack\|sample` when internals matter |
39| Parts without a mesh-contact path to the ground | `inspect physical floating` |
40| Accidental fusion, connected solids | `inspect physical components` |
41| Air gaps between physical components | `inspect physical gaps` |
42| Surface orientation, occlusion, faceting, strange protrusions | `inspect visual depth` or `inspect visual normals` |
43| Loft, fillet, skin, and sweep surface continuity | `inspect surface zebra` or `inspect visual normals` |
44| Reference-vs-candidate reconstruction comparison | `inspect compare overlay --with reference.3mf` |
45
46## Section Probe + Replay
47
48The agent-native measure-then-recheck loop:
49
50```bash
51forgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0
52forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js
53```
54
55The probe's `result.json` field contract (frames, rulers, gaps, replaySpec) is documented in the forgecad skill's `docs/guides/inspection-bundles.md`.
56
57## Misread Traps
58
59- Face-touching is not a collision; collision findings are positive-volume overlaps.
60- Gray/unresolved thickness area means the evidence is incomplete, not that the model is safe.
61- Distance/gap figures are bbox-gap metrics between components, not closest-surface distances.
62- Depth, normals, and zebra are visual aids (heatmap, camera-view normals, stripe shader), not exact measurements or curvature proofs.
63- Resolve mask colors through the manifest's object list, never by object order.
64
65## Reference
66
67Bundle/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`.
gabrielmoreira