forgecad 0.9.16 → 0.10.1

package/dist/docs-raw/skills/forgecad-reconstruction-benchmark.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-reconstruction-benchmark/SKILL.md instead. -->
+
 # forgecad-reconstruction-benchmark
 
 Solve ForgeCAD CAD reconstruction benchmark or RL episodes in a prepared workspace by rebuilding a visible reference asset as readable parametric ForgeCAD in the fixed submission path, using visual and geometric self-checks while respecting sandbox limits.
@@ -11,140 +13,46 @@ Solve ForgeCAD CAD reconstruction benchmark or RL episodes in a prepared workspa
 
 ## 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.
-
-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 Contract
-
-Read these first:
-
-- `AGENTS.md`
-- `task/instructions.md`
-- this skill
-- `agent-home/.agents/skills/forgecad/SKILL.md` for API guidance
-
-Useful companion skills:
-
-- `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
-
-Common files:
-
-- reference asset: `task/reference/*`
-- final answer: `submission/main.forge.js` unless `task/task.json` says otherwise
-- local ForgeCAD wrapper: `./bin/forgecad`
-- scratch outputs: `outputs/`
-
-Stay inside the prepared workspace. Use the local wrappers instead of global
-ForgeCAD commands.
-
-### Non-Negotiables
-
-- 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.
+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.
+
+### Workspace
+
+Read first: `AGENTS.md`, `task/instructions.md`, this skill, and `agent-home/.agents/skills/forgecad/SKILL.md` (API + CLI reference).
+
+- 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.
+
+```bash
+./bin/forgecad run submission/main.forge.js
+```
+
+### Rules and Done Criteria
+
+- 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.
+
+### Budget Discipline
+
+A runnable first candidate beats a perfect investigation with no model.
+
+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`.
+
+### Pointers
+
+- `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
 
 
 ## Bundled Files

package/dist/docs-raw/skills/forgecad-render-inspect.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-render-inspect/SKILL.md instead. -->
+
 # forgecad-render-inspect
 
 Run and interpret ForgeCAD inspection bundles for model verification. Use when asked to inspect a ForgeCAD model, analyze an inspection bundle, validate collisions, wall thickness, connectivity, floating bodies, sections, masks, depth, normals, or Zebra stripes.
@@ -11,82 +13,25 @@ Run and interpret ForgeCAD inspection bundles for model verification. Use when a
 
 ## 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`.
-
-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:
+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.
 
-| 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:
+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
-   node dist-cli/forgecad.js inspect fit interference model.forge.js --camera iso --size 700
+   python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
    ```
 
-   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:
-
-   ```bash
-   python agent-skill-library/forgecad-render-inspect/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
 
@@ -96,9 +41,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` |
@@ -106,120 +51,28 @@ 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`.
 
 
 ## Bundled Files

package/dist/docs-raw/skills/forgecad-visual-spec.md

@@ -1,3 +1,5 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-visual-spec/SKILL.md instead. -->
+
 # forgecad-visual-spec
 
 Turn a concrete ForgeCAD artifact, build brief, HLD, or existing model into builder-honest image prompts for AI image models. Use when the user wants visual-spec renders that show the final product while keeping mechanisms, seams, hardware, and build cues visible instead of drifting into concept art.
@@ -11,141 +13,59 @@ Turn a concrete ForgeCAD artifact, build brief, HLD, or existing model into buil
 
 ## ForgeCAD Visual Spec
 
-Use this skill after the artifact is already concrete enough to visualize.
-
-Good triggers:
+### Scope
 
-- a specific `.forge.js` model or project folder
-- a build brief or HLD that already defines the object
-- a request like "write image prompts for this model"
-- a request to show the final product without hiding how it is built
-
-Do not use this skill for a vague artifact brief. If the object is still underspecified, use `forgecad-prepare-prompt` first.
+Only for artifacts already concrete enough to visualize (a specific `.forge.js` model, build brief, or HLD); route vague briefs to `forgecad-prepare-prompt` first. Read minimum context — entry `.forge.js`, one key helper if it delegates geometry, brief/HLD — and capture what must survive the image model: artifact type and scale, major subassemblies, actuation style, visible mechanisms, material and color cues.
 
 ### Core Rule
 
-These prompts are not concept art prompts. They are visual-spec prompts.
-
-The image should:
-
-- show the final artifact clearly
-- preserve build truth and subsystem truth
-- keep visible the seams, modules, hardware, and mechanical hierarchy that matter
-
-The image should not:
-
-- smooth away the mechanism into a fake consumer shell
-- invent flashy sci-fi styling that hides how it works
-- pretend to be a CAD drawing, dimensioned blueprint, or engineering diagram
-- turn the artifact into a cutaway, sectioned shell, or exploded teaching view unless the user explicitly asks for that representation
+Visual-spec prompts, not concept art: show the final artifact clearly, preserve build and subsystem truth, and keep visible the seams, modules, hardware, and mechanical hierarchy that matter.
 
-### Default Strategy
+Negatives (the only negatives list — reuse it, never restate variants):
 
-Default to one `honest hero render`.
+- no fake sleek consumer shell, no hidden mechanics
+- no over-smoothed geometry, no sci-fi styling
+- no CAD-drawing, blueprint, or dimension-arrow pretense
+- no cutaway, sectioned, or exploded teaching view unless the user explicitly asks
+- no text, labels, or humans
 
-That is the best first image for most ForgeCAD artifacts because it balances:
+### Prompt Skeleton
 
-- final-product readability
-- mechanical honesty
-- visual appeal
+Block order: identity → mechanism truth → materials/color truth → pose/state → shot/camera/lighting → negatives. Fill in, don't copy:
 
-Only add more prompts if the user wants them. The most useful support prompts are:
+```text
+A [artifact identity and scale], designed as a real buildable CAD-driven object, not a fantasy concept. [Major subassemblies and mechanism truth]. [Materials, colors, finish, visible hardware]. Show it in [pose / state]. [Shot, camera, background, lighting]. It should look physically buildable and mechanically honest, with visible part boundaries and serviceable architecture. No [negative 1], no [negative 2], no [negative 3].
+```
 
-- `builder-first mechanical render`
-- `mild exploded assembly render`
-- `workshop prototype realism`
-- `gripper / end-effector close-up`
+Default shot: `front-left three-quarter hero view, eye-level product camera`. Alternate: `rear-right three-quarter view showing motor placement and belt routing`.
 
-Prefer separate images over one collage. Multi-view boards are acceptable, but single-purpose images are usually more reliable.
+### Modes
 
-### Workflow
+Default to ONE honest hero render; add support prompts only when the user asks. Prefer separate single-purpose images over collages or multi-view boards.
 
-1. Gather artifact truth.
-   Read only the minimum context needed:
-   - top-level `.forge.js` entry
-   - key helper/module file if the entry delegates the geometry
-   - build brief / HLD if they exist
+| Mode | Job | Signature phrases |
+|------|-----|-------------------|
+| Honest hero render (default) | Final object clearly, still reads as buildable | `clean premium studio product render`, `physically buildable and mechanically honest` |
+| Builder-first mechanical | Teach the build; bias to interfaces, seams, mounted actuators | `clear visibility of interfaces, seams, and subsystem boundaries`, `serious prototype, not a polished consumer shell` |
+| Mild exploded | Assembly logic; major modules only, no per-screw chaos. Image-only — the CAD model stays the complete assembled product | `major modules separated by small clean gaps`, `no tiny floating fragments` |
+| Workshop prototype realism | Feel like a real first prototype | `visible print lines and honest surface texture`, `uncluttered engineering bench background` |
+| End-effector close-up | Wrist/gripper mechanism detail | `close-up on the wrist and end effector showing the mechanism clearly` |
 
-2. Extract the truths that must survive the image model.
-   Capture:
-   - artifact type and scale
-   - major subassemblies
-   - actuation style
-   - visible mechanisms
-   - material cues
-   - color cues if already established
-   - what must stay visible for build understanding
-
-3. Choose the representation mode.
-   Default: `honest hero render`
-   Switch only if the user explicitly wants a support view or image pack.
-
-4. Write the prompt in blocks.
-   Use the template in `references/prompt-template.md`.
-   Keep the wording concrete and artifact-specific.
-
-5. Add negative constraints inline.
-   Tell the model what to avoid, especially:
-   - hidden mechanics
-   - fake sleek shelling
-   - over-smoothed geometry
-   - unreadable clutter
-   - text, labels, or dimension arrows unless explicitly requested
-
-6. Return the prompt pack.
-   If the user asked for "a prompt", return one prompt.
-   If the user asked to compare approaches, return 2-4 prompts with clearly different jobs.
-
-### Prompt Writing Rules
+### Writing Rules
 
 - Use real artifact language: base, turntable, shoulder, rails, bearings, gripper, belt, pulley, shaft.
 - Prefer visible subsystem truth over poetic adjectives.
 - Keep exact dimensions out unless they matter visually and are already known.
-- If a detail is uncertain, stay honest at the subsystem level instead of inventing internals.
-- Ask for "physically buildable", "mechanically honest", and "visible part boundaries" when that is central.
-- For robots and mechanisms, mention motors, belts, pulleys, shafts, guide rods, fasteners, or service covers only if they are genuinely part of the artifact.
-- Avoid long style dumps. A short strong prompt beats a bloated one.
-
-### Mode Guide
-
-#### Honest Hero Render
-
-Use by default.
-
-Best when the user wants one image that shows the final object clearly while still reading as something that could actually be built.
-
-#### Builder-First Mechanical Render
-
-Use when the user wants the image to teach the build more directly.
-
-Bias harder toward interfaces, seams, mounted actuators, and subsystem boundaries.
-
-#### Mild Exploded Assembly Render
-
-Use when the user wants assembly logic or modular breakdown.
-
-Keep the explosion restrained. Separate only major modules, not every screw.
-This is a visual-spec support image, not a default ForgeCAD modeling instruction; the CAD artifact should still be the complete assembled product.
-
-#### Workshop Prototype Realism
-
-Use when the user wants the artifact to feel like a real first prototype rather than a clean studio render.
-
-Bias toward print texture, honest materials, and believable workshop context.
+- If a detail is uncertain, stay honest at the subsystem level — never invent internals.
+- Ask for "physically buildable", "mechanically honest", "visible part boundaries" when central.
+- Mention motors, belts, pulleys, shafts, guide rods, fasteners, or service covers only if genuinely part of the artifact.
+- A short strong prompt beats a style dump.
 
 ### Output Contract
 
-When using this skill, the answer should usually contain:
-
-1. one sentence interpreting the artifact
-2. one primary prompt, usually the `honest hero render`
-3. optional support prompts only if useful
-4. a short note on which prompt to try first
-
-Do not bury the prompts under theory.
+Return: one sentence interpreting the artifact, the primary prompt first (usually the honest hero render), optional support prompts, and a short which-to-try-first note. Never bury the prompts under theory.
 
 
 ## Bundled Files
 
 - `agents/openai.yaml`
-- `references/prompt-template.md`