forgecad 0.9.15 → 0.10.0

package/dist-skill/library/forgecad-image-replicator/SKILL.md

@@ -6,164 +6,45 @@ forgecad-public: true
 
 # ForgeCAD Image Replicator
 
-Use this skill when the user provides one or more images and wants a ForgeCAD model of the object shown.
+The reference image is evidence, not the deliverable. The deliverable is a real parametric object that holds up from front, back, side, top, bottom, and reference camera views — a model that matches one image but falls apart from other angles has failed, even if the comparison board looks close. Cutaway, sectioned, exploded, or transparent references are evidence about the complete object: build the closed artifact and recreate explanatory views with viewer/inspection tools (the main `forgecad` skill's closed-artifact rule applies).
 
-The reference image is evidence. It is not the deliverable.
+## Companion Skills
 
-The deliverable is a real parametric object that remains believable from front, back, side, top, bottom, and reference camera views. A model that matches one image but falls apart from other angles has failed, even if the comparison board looks close.
-
-If a reference image is cutaway, sectioned, exploded, partly hidden, or transparent, treat that as evidence about the complete object. Do not make the default ForgeCAD result a permanently cutaway or exploded display unless the user explicitly asked for a teaching/display model. Build the closed artifact first, then use ForgeCAD viewer/inspection tools to recreate explanatory views.
-
-## Required Companion Skills
-
-- Use `forgecad` for API docs, model authoring, and renderer behavior.
-- Use `forgecad-prepare-prompt` when the image does not fully determine the artifact family, process posture, scale, operating story, or validation boundary.
-- Use `forgecad-make-a-model` for file placement, decomposition, parametric modeling, and definition of done.
-- Use `forgecad-render-inspect` before final delivery when the object has multiple parts, internal geometry, mechanisms, thin walls, or fit-sensitive features.
+- `forgecad` — API docs, model authoring, renderer behavior.
+- `forgecad-prepare-prompt` — when the images underdetermine artifact family, process posture, scale, operating story, or validation boundary.
+- `forgecad-make-a-model` — file placement, project structure, decomposition, definition of done.
+- `forgecad-render-inspect` — pre-delivery inspection for multi-part, internal, mechanical, thin-wall, or fit-sensitive objects.
 
 ## Core Rule
 
-Infer the real object before matching the camera.
-
-Do not begin by chasing pixels, silhouettes, or the prettiest view. First form a 3D object hypothesis: what the artifact is, how it is made, what hidden sides must contain, what scale it likely has, and what geometry must exist for it to be physically coherent.
-
-Reference matching is a validation step after the object exists.
+Infer the real object before matching any camera — identity, manufacture, scale, what hidden sides must contain, what geometry must exist for physical coherence. Reference matching is a validation step after the object exists; never start by chasing pixels or the prettiest view.
 
 ## Workflow
 
-1. Save the references.
-   Put all provided images in `/tmp/<slug>-replicate/refs`. Keep the original filenames. If there are multiple views, add clear view names when possible: `front`, `side`, `rear-iso`, `top`, `detail`, and so on.
-
-2. Read the images as evidence.
-   For each image, record:
-   - visible facts: silhouette, view direction, visible faces, major masses, feature counts, color and material boundaries, seams, holes, fasteners, labels, repeated spacing
-   - scale cues: hands, hardware, wheels, ports, boards, screws, wall thickness, known product proportions
-   - camera cues: perspective strength, parallel edges, lens distortion, crop, object center, likely elevation and azimuth
-   - unknowns: hidden sides, occluded parts, ambiguous thickness, missing rear or underside geometry
-   - conflicts: details that disagree across images or appear stylized, distorted, cropped, or shadow-hidden
-
-3. Write a Real Object Brief.
-   This is a hard gate before modeling. Include:
-   - artifact identity and family
-   - likely purpose or operating story
-   - assumed scale and units
-   - manufacturing/process posture and material cues
-   - part and BOM boundary: what is modeled as real geometry, purchased hardware, ghost geometry, or omitted context
-   - visible facts from the reference set
-   - inferred hidden-side geometry
-   - expected canonical front, back, left, right, top, and bottom forms
-   - required internal, interface, or fit geometry
-   - validation views and inspection evidence
-
-4. Choose the modeling structure.
-   Use a multi-file `main.forge.js` project when the object has distinct parts, repeated feature families, internals, purchased hardware, variants, or meaningful manufacturing assumptions. Put renderable/importable parts and sub-assemblies in neighboring `.forge.js` files; keep only pure dimensions, materials, math helpers, and lookup tables in plain `.js` files.
-
-5. Build a coarse 3D blockout.
-   Model the object, not the image. Start with the large volumes, axes, symmetry, side depth, rear form, underside, and hidden continuations. Render canonical views before doing reference-camera comparison.
+1. Stage references in `/tmp/<slug>-replicate/refs`, keeping originals and adding view names where possible (`front`, `side`, `rear-iso`, `top`, `detail`).
+2. Read each image as evidence, recording: visible facts; scale cues; camera cues; unknowns (hidden/occluded geometry); conflicts across images or stylization.
+3. Write a Real Object Brief — a hard gate before modeling: (a) artifact identity + operating story; (b) assumed scale and units; (c) process posture + part/BOM boundary (real geometry vs purchased vs ghost vs omitted); (d) inferred hidden-side geometry + expected canonical front/back/left/right/top/bottom forms; (e) validation views and inspection evidence. Use `forgecad-prepare-prompt` when these are underdetermined.
+4. Build a coarse 3D blockout — model the object, not the image: large volumes, axes, symmetry, side depth, rear form, underside, hidden continuations. Render canonical views before any reference-camera comparison. Follow `forgecad-make-a-model` for project structure.
+5. Calibrate one camera per usable reference, only after the blockout makes sense from canonical views. Use the object center as `target`; estimate azimuth/elevation/distance/FOV from visible faces and perspective cues; use orthographic when parallel edges stay parallel with no perspective convergence.
+6. Render comparison boards: render the model from each calibrated reference camera and place it next to the original. Never compare from memory.
+7. Iterate one class of change at a time, in order: object hypothesis → major proportions → canonical geometry → camera → details → presentation. If improving one reference view makes another view or a canonical render worse, the object hypothesis is wrong — fix the model, not the camera illusion.
+8. Use every image as a constraint. Never pick one target image and ignore the rest: assign each image a camera, evidence list, and confidence; optimize one shared geometry against the whole set; state how distorted or decorative images were weighted.
+9. Validate the final object: `forgecad run`, reference comparison boards, canonical renders, and targeted inspections via `forgecad-render-inspect`.
 
-6. Calibrate one camera per usable reference.
-   Match camera after the blockout makes sense from canonical views. Use the object center as `target`. Estimate azimuth, elevation, distance, and FOV from visible faces and perspective cues. Use orthographic when parallel edges stay parallel and there is no visible perspective convergence.
+## Comparison Boards
 
-7. Render comparison boards.
-   Render the model from each calibrated reference camera and place the result next to the original image. Do not compare from memory.
+Render with exact `--camera` specs (see the forgecad CLI doc for supported forms). If exact full camera specs do not render, fix the renderer before continuing — never substitute guesses from default `iso` renders.
 
-8. Iterate in the right order.
-   Change one class of thing at a time:
-   - object hypothesis: identity, scale, symmetry, hidden-side assumptions, process logic
-   - major proportions: width, depth, height, taper, curvature, radius families
-   - canonical geometry: rear, underside, side depth, internal clearances, part interfaces
-   - camera: azimuth, elevation, target, distance, FOV, orthographic zoom
-   - details: holes, seams, fasteners, labels, vents, edge treatments, small hardware
-   - presentation: colors, materials, lighting, background, edge style
-
-   If improving one reference view makes another view or canonical render worse, the object hypothesis is probably wrong. Fix the model, not the camera illusion.
-
-9. Use every image as a constraint.
-   When multiple images are attached, do not choose one as the target and ignore the rest. Assign each image a camera, evidence list, and confidence level. Optimize one shared geometry against the whole set. If an image is decorative, distorted, or contradictory, state how it was weighted.
-
-10. Inspect the final object.
-   Run `forgecad run`, render the reference comparison boards, render canonical views, and use targeted `forgecad inspect <family> <mode>` commands. For multi-part, mechanical, internal, or fit-sensitive models, include `inspect fit interference` and the appropriate `inspect sections at|stack|sample` mode, but keep the delivered model as the complete closed artifact.
-
-## Renderer Camera Support
-
-ForgeCAD `render 3d` supports explicit camera control:
+Build side-by-side boards with the bundled self-contained `uv` helper (installs Pillow on demand). Resolve `scripts/compare_images.py` relative to the installed `forgecad-image-replicator` skill directory:
 
 ```bash
-forgecad render 3d model.forge.js /tmp/render.png \
-  --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38" \
-  --size 1000
+uv run <skill-dir>/scripts/compare_images.py refs/front.png render-front.png compare-front.png
 ```
 
-Supported camera forms:
-
-- `--camera front`, `top`, `side`, `right`, `iso`
-- `--camera 45:25` for azimuth/elevation in degrees
-- `--camera 45:25:260` for azimuth/elevation/distance
-- `--camera "proj=perspective;pos=x,y,z;target=x,y,z;up=0,0,1;fov=42"`
-- `--camera "proj=orthographic;pos=x,y,z;target=x,y,z;up=0,0,1;zoom=4"`
-
-If exact full camera specs do not render in the current checkout, fix the renderer before continuing. Do not work around missing camera control by guessing from default `iso` renders.
-
-## Rendering And Comparison
-
-Prefer the built CLI from the repo checkout when available:
-
-```bash
-node dist-cli/forgecad.js render 3d path/to/model.forge.js /tmp/<slug>-replicate/render-front.png \
-  --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38" \
-  --size 1000 --edges thin
-```
-
-Build side-by-side boards with the bundled helper. It is a self-contained `uv` script that installs Pillow on demand and does not require Chrome. The examples use the ForgeCAD source-checkout path; if the skill is installed elsewhere, resolve `scripts/compare_images.py` relative to the `forgecad-image-replicator` skill directory.
-
-```bash
-uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py \
-  /tmp/<slug>-replicate/refs/front.png \
-  /tmp/<slug>-replicate/render-front.png \
-  /tmp/<slug>-replicate/compare-front.png \
-  --height 900 --labels "Reference,ForgeCAD"
-```
-
-Common helper options:
-
-```bash
-uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png
-uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.jpg render.png compare.png --height 1200 --fit contain
-uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --fit cover --labels "Target,Current"
-uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --no-labels
-```
-
-Use `--fit contain` by default. Use `--fit cover` only when both images already share the same crop and aspect.
-
-## Acceptance Standard
-
-A successful result:
-
-- has a written Real Object Brief
-- has parametric ForgeCAD geometry, not a billboard, facade, pasted texture, or one-view shell
-- makes sense from canonical views before reference matching
-- matches each usable reference image as closely as the evidence allows
-- includes honest hidden-side assumptions where the images are silent
-- includes internal, interface, purchased, or hardware geometry when the artifact calls for it
-- passes `forgecad run`
-- includes final reference comparison boards and canonical renders
-- includes inspection results for the risk evidence that matters
-
-A result fails if it only works from the original camera.
-
-## Output Contract
+Use `--fit contain` (default); use `--fit cover` only when both images already share the same crop and aspect. Run with `--help` for other options.
 
-When finished, report:
+## Done and Report
 
-- model file path
-- reference images used
-- Real Object Brief summary
-- hidden-side and scale assumptions
-- final camera spec for each reference image
-- comparison board path for each usable reference image
-- canonical render paths
-- inspection bundle path, when used
-- validation commands run
-- remaining mismatches, unknowns, or downgraded confidence
+Done means: a written Real Object Brief; real parametric geometry (not a billboard, facade, or one-view shell) that makes sense from all canonical views; honest hidden-side assumptions where images are silent; passes `forgecad run`; comparison boards plus canonical renders exist. The result fails if it only works from the original camera — one render is never enough; expect several render/compare/inspect iterations.
 
-For non-trivial references, expect several render, compare, canonical-view, and inspect iterations. One render is not enough.
+Report: model path; Real Object Brief summary + assumptions; per-reference camera spec, weighting, and board path; canonical render paths; inspection evidence; remaining mismatches or downgraded confidence.

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

@@ -6,125 +6,29 @@ forgecad-public: true
 
 # Low-Level Design (LLD)
 
-Create detailed, authoritative design documents for ForgeCAD models. This is the construction document — exact dimensions, constraints, parameters, and verification criteria.
+## When and prerequisites
 
-## Prerequisites
+- An HLD (`/forgecad-high-level-spec`) with a filled Decisions table must exist. The LLD implements those decisions — it never revisits them.
+- Simple parts (single body, no alternatives to explore) skip the HLD and go straight to the LLD.
+- Output: `<name>-lld.md` next to the model files. Complex assemblies split into a numbered directory: overview, global constraints, per-component files, assembly, verification.
 
-Before writing an LLD, a High-Level Design (`/forgecad-high-level-spec`) should exist with its Decisions table filled. The HLD defines *what* to build and *why*. The LLD defines *exactly how*.
+## What an LLD is
 
-For simple parts (single body, no alternatives to explore), skip the HLD and write the LLD directly.
+- **Narrative first** — reads like describing the object over the phone: shape, behavior, purpose, proportions, feel.
+- **Authoritative** — the single source of truth that code implements.
+- **Implementation-blind** — the LLD knows nothing about ForgeCAD's capabilities; never let API convenience shape the design.
+- **Every number has a rationale** — each constraint and each parameter default/range gets an explicit reason; show the math (e.g. `wallThickness = 2.4mm = 6 × 0.4mm nozzle`).
 
-## Philosophy
+## Required structure
 
-An LLD should read like you're describing the object to someone over the phone — vivid, narrative, conveying shape, behavior, purpose, and intent. But it must also be **authoritative** — the single source of truth that code will implement.
+1. **Narrative** — what it is, how it behaves and interacts, why it exists. Concrete comparisons ("about the size of a deck of cards"); no vague terms without grounding.
+2. **Technical** — typed parameter table (length / angle / count / boolean / choice / ratio / clearance — this is design-document vocabulary, not the runtime `Param.*` API), always with units (mm and degrees are the defaults) and a rationale for every default and range; derived dimensions shown as math; geometry and constraints, each constraint with rationale.
+3. **Verification** — mandatory checklist: dimensional checks, functional checks, printability checks.
 
-**Key principles:**
-- **Story-first**: Lead with the "what it is" narrative before technical details
-- **Sensory richness**: Describe appearance, proportions, materials, feel
-- **Behavioral clarity**: How it functions, moves, interacts
-- **Technical precision**: Exact constraints, dimensions, and relationships
-- **No implementation assumptions**: The LLD knows nothing about ForgeCAD's capabilities
+Don'ts: never open with a parameter list (story before numbers), never leave a constraint implicit, never skip verification.
 
-## Output Location
+## Process
 
-LLDs go next to the model files. Name: `<name>-lld.md`. For complex assemblies, use a directory:
+Iterate via git exactly as in `/forgecad-high-level-spec`: commit every version; the diff, not the conversation, is the review artifact.
 
-```
-<project>-lld/
-├── 00-overview.md
-├── 01-global-constraints.md
-├── 02-components/
-│   ├── base.md
-│   └── bracket.md
-├── 03-assembly.md
-└── 04-verification.md
-```
-
-## Document Template
-
-### 1. Narrative Section
-
-Lead with vivid description — what it is, purpose, visual character, how it behaves.
-
-### 2. Technical Section
-
-Parameters table, derived dimensions, geometry description, constraints with rationale.
-
-### 3. Verification
-
-Dimensional checks, functional checks, printability checks — as a checklist.
-
-(See examples in the sections below.)
-
-## Workflow
-
-### Phase 1: Verify HLD decisions are locked
-
-If an HLD exists, check that its Decisions table is filled. The LLD implements the decisions — it doesn't revisit them.
-
-### Phase 2: Write the document
-
-1. Capture the narrative (what it is, how it works)
-2. Extract parameters and constraints
-3. Define verification criteria
-
-### Phase 3: Commit and present for review
-
-Commit the LLD to git. Tell the user it's ready for review.
-
-### Phase 4: Iterate via git
-
-Same as HLD: user reviews the file (edits or verbal feedback), agent reads the diff, updates, commits, repeats.
-
-```
-Agent writes LLD → git commit → User reviews
-→ Agent reads diff → updates LLD → git commit → repeat until approved
-```
-
-### Phase 5: Review for completeness
-
-- Can someone build from this alone?
-- Does it implement every HLD decision?
-- Are all constraints explicit with rationale?
-
-## Git Workflow
-
-LLDs iterate through git, not conversation. The document is the single source of truth.
-
-- **Every version gets committed.** No unsaved drafts in conversation.
-- **User feedback goes in the file** (inline comments, strikethroughs) or in chat — agent checks both.
-- **The diff is the review artifact.**
-
-## Writing Guidelines
-
-**Do:**
-- Use concrete comparisons ("about the size of a deck of cards")
-- Show the math: `wallThickness = 2.4mm`
-- Provide rationale for every constraint
-- Start with the story, then the numbers
-
-**Don't:**
-- Start with a parameter list
-- Leave constraints implicit
-- Skip verification criteria
-- Use vague terms without grounding
-
-## Parameter Types
-
-- `length` — mm default
-- `angle` — degrees default
-- `count` — integer
-- `boolean` — true/false
-- `choice` — enumerated options
-- `ratio` — dimensionless
-- `clearance` — fit tolerances, mm default
-
-Always specify units. Always provide rationale for defaults and ranges.
-
-## Relationship to Other Skills
-
-| Stage | Skill | Output |
-|-------|-------|--------|
-| 1. Explore the problem space | `/forgecad-high-level-spec` | `*-hld.md` |
-| 2. Detailed design | `/forgecad-lld` (this skill) | `*-lld.md` |
-| 3. Implementation | `/forgecad-make-a-model` + `/forgecad` | `.forge.js` files |
+Completeness gate before presenting: Can someone build from this alone? Does it implement every HLD decision? Is every constraint explicit with rationale?