forgecad 0.9.16 → 0.10.0

package/dist-skill/library/forgecad-visual-spec/SKILL.md

@@ -6,135 +6,54 @@ forgecad-public: true
 
 # ForgeCAD Visual Spec
 
-Use this skill after the artifact is already concrete enough to visualize.
+## Scope
 
-Good triggers:
-
-- 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
-
-## Default Strategy
+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 to one `honest hero render`.
+Negatives (the only negatives list — reuse it, never restate variants):
 
-That is the best first image for most ForgeCAD artifacts because it balances:
+- 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
 
-- final-product readability
-- mechanical honesty
-- visual appeal
+## Prompt Skeleton
 
-Only add more prompts if the user wants them. The most useful support prompts are:
+Block order: identity → mechanism truth → materials/color truth → pose/state → shot/camera/lighting → negatives. Fill in, don't copy:
 
-- `builder-first mechanical render`
-- `mild exploded assembly render`
-- `workshop prototype realism`
-- `gripper / end-effector close-up`
+```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].
+```
 
-Prefer separate images over one collage. Multi-view boards are acceptable, but single-purpose images are usually more reliable.
+Default shot: `front-left three-quarter hero view, eye-level product camera`. Alternate: `rear-right three-quarter view showing motor placement and belt routing`.
 
-## Workflow
+## Modes
 
-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
+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.
 
-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
+| 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` |
 
-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.

package/dist-skill/website/skills/forgecad-3d-reconstruction.md

@@ -0,0 +1,58 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-3d-reconstruction/SKILL.md instead. -->
+
+# forgecad-3d-reconstruction
+
+Reconstruct a parametric ForgeCAD model from an existing 3D CAD or mesh file such as STL, OBJ, 3MF, STEP, or STP; inspect the source asset directly, author real ForgeCAD geometry, and iteratively compare the candidate with `forgecad compare 3d`.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-3d-reconstruction/SKILL.md` |
+
+---
+
+## ForgeCAD 3D Reconstruction
+
+The reference asset is evidence, not the deliverable. The deliverable is a readable, parametric `.forge.js` model that runs, renders, and scores well against the source. Never return `Import.mesh()`/`Import.step()` of the source as the final model unless the user explicitly asks for an import wrapper — imports are for measurement, rendering, and scoring only.
+
+Routing: user wants to KEEP the file as a live component and design around it (bracket, enclosure, mating assembly) → `forgecad-make-a-model` (Imported Parts section), not this skill; benchmark/RL episodes → `forgecad-reconstruction-benchmark`; inspection-bundle interpretation → `forgecad-render-inspect`; independent grading after reconstruction → `forgecad-model-grader`; API and command reference → `forgecad` skill + CLI.md.
+
+### Workflow
+
+1. **Inspect the source directly** — the CLI reads CAD/mesh files as inputs, no wrapper script. Gather four evidence types: `ls --long` stats, an iso render, per-object views, sampled sections (invocations in CLI.md; when sharing a renderer server via `--port`, run renders sequentially).
+2. **3MF**: enumerate every build item before scoring — hidden multi-part structure is a common miss. Item ref syntax: `Import.mesh` docs.
+3. **Reconstruction Brief** before modeling: what must be exact vs. approximate vs. parametric; symmetry, origin, key reference planes; likely manufacturing process; scoring tolerance and alignment policy.
+4. **Blockout first.** Match bbox and main masses, then add features. Model real geometry with blueprint-first APIs — never vertex-chase a faceted copy.
+5. **Compare numerically** — the core loop:
+
+   ```bash
+   forgecad compare 3d path/to/source.stl path/to/candidate.forge.js \
+     --samples 3000 --json --output /tmp/<slug>-score.json
+   ```
+
+6. **Iterate coarse to fine**: bbox/placement → main volumes/silhouette → holes/bosses/ribs/shells → edge treatments → small details.
+
+### Reading the Score
+
+Alignment: start `--align none`. Use `--align center` only when origins clearly differ but scale and orientation match. Use `--align center-scale` only for exploratory diagnosis — it hides dimensional errors.
+
+| Signal | Diagnosis |
+|---|---|
+| Low coverage | Missing or extra surface |
+| High RMS | Broad proportional mismatch |
+| High p95/max | Localized outlier feature (protrusion, hole) |
+| Bounds delta | Size, origin, or scale mismatch |
+| Volume delta | Mass, shell, cutout, or scale mismatch |
+
+Calibration: 95+ simple prismatic/revolved parts, 90+ ordinary mechanical parts with fillets/cutouts, 80+ acceptable for organic, faceted, or underdetermined sources. Always report raw rms, p95, max, coverage, bounds delta, and volume delta — a high overall score with a large max can hide a missing local feature.
+
+Faceted sources: decide whether tessellation itself is evidence. Matching low-poly faceting raises the score but reduces parametric clarity — prefer analytic intent unless faceting is part of the artifact or required by the acceptance criteria.
+
+### Done Criteria
+
+The final model must run, render, re-compare at `--samples 5000`, and pass an `inspect compare overlay`. Add targeted inspects (`forgecad-render-inspect`) when the object is multi-part, hollow, thin-walled, or surface-sensitive. Report: source and candidate paths, score JSON path, final metrics, and every known mismatch classified as intentional simplification or remaining work.
+
+
+## Bundled Files
+
+- `agents/openai.yaml`

package/dist-skill/website/skills/forgecad-blockout-model.md

@@ -0,0 +1,49 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-blockout-model/SKILL.md instead. -->
+
+# forgecad-blockout-model
+
+Create rough high-level ForgeCAD concept models from simple primitives to explore layout, proportions, motion, and part relationships without production detail. Use when asked for a quick model sketch, blockout, spatial mockup, or intuitive low-detail 3D concept.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-blockout-model/SKILL.md` |
+
+---
+
+## Block Out a Model
+
+A blockout is a spatial planning artifact: 3-7 simple masses that answer where parts go, whether a mechanism makes spatial sense, and what the silhouette, footprint, or motion envelope looks like. Not for print-ready geometry, exact fit, tolerances, or detail work.
+
+| Need | Skill |
+|------|-------|
+| High-level 3D idea using simple masses | `forgecad-blockout-model` |
+| Written concept or architecture before CAD | `forgecad-high-level-spec` |
+| Accurate, detailed, parametric ForgeCAD model | `forgecad-make-a-model` |
+
+### Method
+
+- Load the `forgecad` skill first; read its Core API and CLI docs. Load nothing else unless the concept demands it.
+- Translate the idea into 3-7 conceptual parts BEFORE writing geometry: masses and zones (base, arm, payload, sweep volume, keep-out, hand access).
+- One primitive stands in for many eventual details. A bounding box beats a fake detailed part. Never add detail as a substitute for clarity — simplify or reposition instead.
+- Use round-number dimensions; "believably shaped" beats numerically correct. Name uncertainty honestly: `armLengthGuess`, `baseWidthApprox`, `clearanceEnvelope`.
+- At most a handful of `param()` values, for comparing proportions. Do not parameterize every dimension.
+- Color by meaning; keep each conceptual part visually distinct via color or opacity. Return named shape objects so the viewer can inspect the concept part-by-part.
+- Ghost geometry: transparent volumes only for REAL physical envelopes — sweep arcs, keep-out volumes, approximate payloads, reach/access zones. Never decorative teaching overlays. Exaggerate tiny clearances when needed for readability.
+- Even a blockout represents the object in its normal assembled state: no labels, legends, cutaways, or permanently exploded layouts (full rule in the `forgecad` skill).
+- Leave out: fasteners and screw holes, wall thicknesses, fillets and blend radii, polished materials, hidden internal structure that does not affect the concept.
+
+### Verify
+
+Rendering is mandatory even for rough models. Run the script, then render from 2-3 angles with the installed `forgecad` CLI (syntax: the `forgecad` skill's CLI docs). Judge by the reader test:
+
+- Can someone unfamiliar with the idea tell what each mass represents?
+- Are proportions believable enough to discuss?
+- Is motion or interference visible where it matters?
+- Are unknowns shown honestly, not hidden behind fake detail?
+
+If any answer is no, simplify or add clearer ghost volumes.
+
+### Handoff
+
+File placement and naming follow `forgecad-make-a-model` conventions; suffix the filename `-blockout` or `-concept` unless the user supplied a clearer name. Once the high-level questions are answered, stop. If the next question is real fit, tunable dimensions, part details, or manufacturing logic, switch to `forgecad-make-a-model` instead of refining the blockout indefinitely.

package/dist-skill/website/skills/forgecad-component-model.md

@@ -0,0 +1,53 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-component-model/SKILL.md instead. -->
+
+# forgecad-component-model
+
+Enforce the ForgeCAD Component Model when building multi-part assemblies. Parts build at origin, connectors position them, data flows down from parent. Use when building or reviewing any multi-file ForgeCAD project.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-component-model/SKILL.md` |
+
+---
+
+## Component Model
+
+The React of CAD: a part is a function from props to `{ shape, connectors, metadata }`, built at origin in local space. Parts never position themselves — the assembly positions them via connectors.
+
+### Rules
+
+1. **Parts build at origin.** Geometry starts at `[0,0,0]` in local coordinates; no assembly-space offsets; internal structure derives from the part's own props only.
+2. **Connectors are the only interface.** Declare via `.withConnectors({})`; axes point outward, mating is face-to-face (exception: prismatic joints share a co-directional slide axis). Mechanics: the forgecad skill's `docs/guides/positioning.md` and `docs/generated/assembly.md`.
+3. **Assembly is pure composition.** Zero `translate()` to position structural parts, zero coordinate math — connect connectors, pass props down, read metadata up.
+4. **Data flows down, never sideways.** Props down via `require('./part.forge.js', { Height: 20 })` overrides; metadata up via the part's return object; siblings NEVER import each other — the assembly mediates all sibling communication.
+5. **Validate with `verify.*`, never `console.log` + `if`.**
+
+### Part return shape
+
+```js
+return { shape, boltPattern, pinionZ }; // shape + metadata the parent may route to siblings
+```
+
+### File structure
+
+Default: ONE file per project-specific assembly — parts as sections, shared data as variables. Split only for cross-project reuse or past ~300 lines. Never split for "organization".
+
+### Anti-patterns (reject on review)
+
+- `shared-dims.js` — a file that only computes derived dimensions; the assembly derives and passes them.
+- Sibling `require()` — e.g. `require('./motor-mount.forge.js')` inside `cover-plate.forge.js`; route through the parent.
+- Assembly-space coordinates inside a part — a part knowing `pinionZ = 14` from a sibling's geometry; receive it as a prop.
+- `translate()` to position a structural part in an assembly — add a connector instead.
+- `console.log` + `if` validation — use `verify.*`.
+- Bare `connector.neutral()` outside a reusable component library with compatibility checking.
+
+### Design gate
+
+Before committing any multi-part assembly:
+
+1. Can you understand each part without reading other files?
+2. Does the assembly contain zero coordinate math?
+3. Do all inter-part relationships flow through connectors and props?
+
+If any answer is no, refactor.

package/dist-skill/website/skills/forgecad-high-level-spec.md

@@ -0,0 +1,101 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-high-level-spec/SKILL.md instead. -->
+
+# forgecad-high-level-spec
+
+Write a high-level design document (HLD) for a model, mechanism, or assembly before detailed specification or coding. Use when starting a new design, rethinking an existing one, or when the user asks to spec out, plan, or think through a model at a high level. Works backwards from requirements — defines the problem, explores alternatives, records decisions. Produces a right-sized design document for review and iteration.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-high-level-spec/SKILL.md` |
+
+---
+
+## High-Level Design (HLD)
+
+The HLD aligns the user and the agent on *what* to build before anyone thinks about *how*. Every design concern, risk, and tradeoff lives in the document — not in conversation, not in the agent's head. Brevity is a readability tool, not a success metric: there is no page limit; include whatever evidence, diagrams, and dimensions a good decision needs. Decision-driving dimensions belong here; exhaustive construction dimensions belong in the LLD.
+
+Manufacturing process is a design decision, not a default — never assume 3D printing/FDM. If the user didn't specify a process, treat process choice as an HLD alternative (full posture taxonomy: `/forgecad-prepare-prompt`).
+
+Write an HLD before any LLD, and whenever an existing design is wrong in approach, not just in numbers. Output: `<name>-hld.md` beside the model files, or `hld.md` for a whole project.
+
+### Document Structure
+
+The section order is the workflow — write it top to bottom, following the embedded instructions.
+
+```markdown
+# [Name] — High-Level Design
+
+## Problem
+What must this do? Hard requirements (must grip objects, fit a 60mm
+housing, use purchased bearings). State the problem without implying
+a solution. Unspecified process choice is an open design dimension.
+
+## Approach
+How it works at a conceptual level. ASCII diagram of the key elements
+and their spatial relationships — diagram labels stay in this markdown;
+never carry them into CAD geometry unless the real artifact needs
+markings.
+
+## Key Interfaces
+Every point where this touches another part or the outside world:
+mating surfaces, shared dimensions, coordination points. These are the
+contracts that constrain the design.
+
+## Dictionary
+| Term | What it is |
+|------|-----------|
+Define every domain term in plain words, with dimensions where relevant.
+Write for a developer without a mechanical-engineering background.
+
+## Alternatives
+| Option | Description | Tradeoff |
+|--------|-------------|----------|
+2-3 genuinely different strategies, not minor variations. Enough detail
+per row to see why it fits or loses. Mark one recommended and say why.
+If there is honestly only one approach, say so and skip the table.
+
+## Usage Guide
+The strongest validation: work backwards from how someone uses,
+assembles, or operates the thing, step by step (physical product:
+assembly steps, tools, what connects to what; mechanism: how it moves
+and what the user does). If a step doesn't make sense ("how does the
+servo get inside?"), the design has a gap — flag it inline with ⚠️ and
+promote it to Concerns.
+
+## Concerns
+1. Numbered, falsifiably specific — a reviewer must be able to say
+   "real problem" or "fine, because…". "Tolerances might be tight" is
+   useless; "the 12mm arm cantilevers under gripping load, may flex
+   >0.5mm" is useful.
+
+## Decisions
+| # | Decision | Rationale |
+|---|----------|-----------|
+Filled ONLY after user review — never pre-decide. Each row resolves a
+concern or alternative.
+```
+
+### Review via git
+
+HLDs and LLDs iterate through git, not conversation:
+
+- **Commit every version.** No drafts floating in chat. After writing, commit and tell the user it's ready for review.
+- **Feedback arrives as file edits** (inline comments, strikethroughs) **or chat — check both.** Read `git diff`: the diff is the review artifact.
+- **Update, commit, repeat** until the Decisions table is filled and the user says "go."
+
+### Rules
+
+- If you're speccing every part, formula, tolerance, and fabrication step, you're writing an LLD — back up.
+- If you can't draw it, you don't understand it yet.
+- Tables are welcome where they clarify (interfaces, requirements, visible evidence); full parameter catalogs go to the LLD.
+
+### Pipeline
+
+| Stage | Skill | Output |
+|-------|-------|--------|
+| 1. Explore the problem space | this skill | `*-hld.md` |
+| 2. Detailed design | `/forgecad-lld` | `*-lld.md` |
+| 3. Implementation | `/forgecad-make-a-model` + `/forgecad` | `.forge.js` |
+
+The Decisions table must be filled before writing the LLD. Simple models may skip straight from HLD to code.

package/dist-skill/website/skills/forgecad-image-replicator.md

@@ -0,0 +1,63 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-image-replicator/SKILL.md instead. -->
+
+# forgecad-image-replicator
+
+Build real ForgeCAD geometry from one or more reference images by treating images as evidence, inferring the object, then validating against both reference-matched and canonical views.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-image-replicator/SKILL.md` |
+
+---
+
+## ForgeCAD Image Replicator
+
+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).
+
+### Companion Skills
+
+- `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 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. 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`.
+
+### Comparison Boards
+
+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.
+
+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
+uv run <skill-dir>/scripts/compare_images.py refs/front.png render-front.png compare-front.png
+```
+
+Use `--fit contain` (default); use `--fit cover` only when both images already share the same crop and aspect. Run with `--help` for other options.
+
+### Done and Report
+
+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.
+
+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.
+
+
+## Bundled Files
+
+- `agents/openai.yaml`
+- `scripts/compare_images.py`

package/dist-skill/website/skills/forgecad-lld.md

@@ -0,0 +1,41 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-lld/SKILL.md instead. -->
+
+# forgecad-lld
+
+Write a Low-Level Design (LLD) for a CAD model — exact dimensions, constraints, parameters, and verification criteria. Use after a High-Level Design (HLD) exists and decisions are locked, or for simple parts that don't need an HLD. The detailed design document that code implements.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-lld/SKILL.md` |
+
+---
+
+## Low-Level Design (LLD)
+
+### When and 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.
+
+### What an LLD is
+
+- **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`).
+
+### Required structure
+
+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.
+
+Don'ts: never open with a parameter list (story before numbers), never leave a constraint implicit, never skip verification.
+
+### Process
+
+Iterate via git exactly as in `/forgecad-high-level-spec`: commit every version; the diff, not the conversation, is the review artifact.
+
+Completeness gate before presenting: Can someone build from this alone? Does it implement every HLD decision? Is every constraint explicit with rationale?