forgecad 0.9.16 → 0.10.1

package/dist/docs-raw/skills/forgecad-component-model.md

@@ -1,3 +1,5 @@
+<!-- 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.
@@ -9,129 +11,43 @@ Enforce the ForgeCAD Component Model when building multi-part assemblies. Parts
 
 ---
 
-## Component Model — The React of CAD
-
-You are building a ForgeCAD multi-part assembly. Follow the Component Model strictly.
-
-### The Core Principle
-
-**Parts never position themselves. The assembly positions them via connectors.**
-
-A part is a function from props to `{ shape, connectors, metadata }`. It builds at origin in local space. It doesn't know where it sits in the world.
-
-### Rules (Non-Negotiable)
-
-#### 1. Parts Build at Origin
-- Geometry starts at `[0, 0, 0]` in local coordinates
-- No assembly-space offsets (no `translate(pinionPitchR, 0, layout.pinionZ)`)
-- Internal structure computed from the part's own props only
-
-#### 2. Connectors Are the Interface
-- Every part that joins an assembly declares connectors via `.withConnectors({})`
-- A connector = origin + axis (outward from the part)
-- Connectors meet **face-to-face**: both axes point outward, system brings them together
-- For prismatic joints: axes point along the shared slide direction
-- Mirrored revolute axes need negated physical joint values for the same mirrored pose
-
-#### 3. Assembly Is Pure Composition
-- Use `addPart()` + `connect()` for frame-aware serial assemblies
-- Use `link()` + `edgeBetweenLinks()` + `addAngleBetweenLinks()` for solved point skeletons
-- Zero `translate()` calls for structural parts
-- Zero coordinate math
-- The assembly passes props down and reads metadata up
-
-#### 4. Data Flows Down, Never Sideways
-- **Props down:** Assembly passes dimensions to parts via `require('./part.forge.js', { Height: 20 })`
-- **Metadata up:** Parts return `{ shape, boltPattern, pinionZ, ... }` — computed values the parent might pass to siblings
-- **Siblings never import each other.** The assembly mediates ALL sibling communication
-
-#### 5. Verify, Don't console.log
-- Use `verify.that("name", () => condition)` for spatial checks
-- Use `verify.equal()`, `verify.inRange()`, `verify.notColliding()` for specific assertions
-- Never `console.log` + `if` for validation
-
-### Connector Convention
-
-```js
-// Face-to-face: both point outward, system opposes them
-base.withConnectors({
-  mount_face: connector("bolt-face", { origin: [0, 0, 0], axis: [0, 0, -1] }),
-  //                                  ↑ bottom face          ↑ faces downward
-});
-mount.withConnectors({
-  flange: connector("bolt-face", { origin: [0, 0, 0], axis: [0, 0, 1] }),
-  //                              ↑ top face            ↑ faces upward
-});
-
-// Assembly — no flip, no coordinate math
-assembly.connect("Base.mount_face", "Mount.flange", { as: "mount-fix" });
-```
+## Component Model
 
-Revolute values are signed by the physical hinge axis. In a bilateral mechanism,
-`axis: [1, 0, 0]` on the right side and `axis: [-1, 0, 0]` on the left side are
-exact mirrors at rest, but the same `+theta` value rotates them in opposite
-fore/aft senses. Use `Right: +theta`, `Left: -theta`, and mirror physical limits
-as `[min, max] -> [-max, -min]`, or drive both sides from a side-neutral link
-graph/control layer.
+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.
 
-### Part Return Shape
+### Rules
 
-Every part file returns a structured object:
+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`.**
 
-```js
-return {
-  shape: body.color('#708090').withConnectors({ ... }),
-  // Public metadata — parent may pass to siblings:
-  boltPattern,    // bolt positions for sibling parts
-  pinionZ,        // Z center for gear alignment
-  armWidth,       // arm cross-section for cover plate slots
-};
-```
-
-### File Structure
-
-**Default: one file for project-specific assemblies.** Parts are sections within the file. Shared data is variables. Split into separate files only when parts are reusable or the file exceeds ~300 lines.
+### Part return shape
 
 ```js
-// ─── Motor Mount ────────────────────────────
-const mount = buildMount({ servo, wall, clearance });
-
-// ─── Base Body ──────────────────────────────
-const base = buildBase({ gears, depth, height, boltPattern: mount.boltPattern });
-
-// ─── Assembly ───────────────────────────────
-assembly("Gripper")
-  .addPart("Base", base.shape)
-  .addPart("Mount", mount.shape)
-  .connect("Base.mount_face", "Mount.flange", { as: "fix" })
+return { shape, boltPattern, pinionZ }; // shape + metadata the parent may route to siblings
 ```
 
-### Anti-Patterns (Reject These)
-
-❌ **shared-dims.js** — A file whose only job is computing derived dimensions. The assembly should derive and pass them.
-
-❌ **Sibling imports** — `require('./motor-mount.forge.js')` inside `cover-plate.forge.js`. Data flows through the parent.
+### File structure
 
-❌ **Assembly-space coordinates in parts** — A part knowing `pinionZ = 14` from a sibling's geometry. It should receive `rackZ: 14` as a prop.
+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".
 
-❌ **`translate()` in assembly** — If you're translating to position a part, add a connector instead.
+### Anti-patterns (reject on review)
 
-❌ **console.log validation** — Use `verify.*`. Always.
+- `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.
 
-❌ **Bare `connector.neutral()`** — Use `connector()` without gender unless building a reusable component library with compatibility checking.
+### Design gate
 
-### Design Gate
-
-Before committing any multi-part assembly, verify:
+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.
-
-### Reference
-
-Full philosophy: `docs/permanent/component-model.md`
-Connector details: `docs/permanent/generated/assembly.md`
-Blueprint-first: `docs/permanent/blueprint-first.md`

package/dist/docs-raw/skills/forgecad-high-level-spec.md

@@ -1,3 +1,5 @@
+<!-- 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.
@@ -11,199 +13,89 @@ Write a high-level design document (HLD) for a model, mechanism, or assembly bef
 
 ## High-Level Design (HLD)
 
-Write a right-sized design document that works backwards from requirements. Define the problem, explore the solution space, record decisions. Include as much detail as needed for quality and shared understanding; stop before exhaustive construction details.
-
-### Philosophy
-
-An HLD is a thinking tool, not a construction document. It should be:
-
-- **Quality-first and right-sized.** Use whatever detail, evidence, diagrams, dimensions, and examples are needed for a good decision.
-- **Honest about what's unknown.** Open questions are features, not bugs.
-- **Opinionated about alternatives.** Don't just list options — recommend one and say why.
-- **Stable under iteration.** Easy to update after a round of feedback without rewriting everything.
-
-Brevity is a readability tool, not a success metric. Do not omit visible evidence, image-derived features, assumptions, interfaces, risks, or decision-driving dimensions just to keep the document short.
-
-The HLD exists so that the user and the agent can align on *what* to build before anyone thinks about *how* to build it. All design concerns, risks, and tradeoffs live here — not in conversation, not in the agent's head.
-
-Manufacturing process is part of the design problem, not a default.
-If the user has not specified a process, compare plausible approaches and recommend the one that fits the artifact, load path, scale, material needs, safety expectations, and intended use.
-Do not default to 3D printing, FDM, or "printable" unless the user asked for it or the chosen concept genuinely calls for printed parts.
+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.
 
-### When to Write an HLD
+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`).
 
-- Before starting a new model, mechanism, or assembly
-- When an existing design has fundamental problems (wrong approach, not just wrong numbers)
-- When the user says "spec this out", "think this through", "what should we build"
-- Before writing an LLD
-
-### Output Location
-
-HLDs go next to the model files. Name: `<name>-hld.md` or for a project: `hld.md` in the project folder.
+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 does this need to do? What role does it play? What are the hard
-requirements (must grip objects, must fit in a 60mm housing, must use
-sheet metal, must be CNC-machinable, must be printable, must use purchased
-bearings)?
-
-State the problem without implying a solution.
+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 does it work at a conceptual level? Describe the mechanism, structure,
-or behavior. Use ASCII diagrams where they make spatial relationships clearer.
-
-Keep this at the architecture level, but include enough spatial and behavioral
-detail that someone unfamiliar with the project understands the concept.
+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
-
-How does this connect to the rest of the system? What are the mating
-surfaces, shared dimensions, or coordination points? List them explicitly.
+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
-
-Define every domain-specific term used in this document. Don't assume
-engineering terminology is widely known — write for a developer who
-doesn't have a mechanical engineering background.
-
 | Term | What it is |
 |------|-----------|
-| ... | Plain-language description with dimensions if relevant |
+Define every domain term in plain words, with dimensions where relevant.
+Write for a developer without a mechanical-engineering background.
 
 ## Alternatives
-
 | Option | Description | Tradeoff |
 |--------|-------------|----------|
-| A (recommended) | ... | ... |
-| B | ... | ... |
-| C | ... | ... |
-
-For each alternative, include enough detail to understand why it fits or loses.
-One sentence is fine only when one sentence is enough. Mark the recommended option.
+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
-
-Work backwards from the user experience. Write the step-by-step needed to show
-how someone would use/assemble/operate this thing. This exposes gaps in the
-design before any code is written.
-
-For a physical product: assembly steps, tools needed, what connects to what.
-For a mechanism: how it moves, what the user does, what happens.
-For a software component: how it's called, what it returns, error cases.
-
-Flag issues inline with ⚠️.
+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
-
-Numbered list. Each concern is a risk, open question, or thing that
-could go wrong. Be specific — "tolerances might be tight" is useless;
-"the 12mm arm cantilevers under gripping load, may flex >0.5mm" is useful.
-
-Include issues discovered while writing the Usage Guide.
-
-1. ...
-2. ...
+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
-
-Filled in after review. Each decision references which concern or
-alternative it resolves.
-
 | # | Decision | Rationale |
 |---|----------|-----------|
-| 1 | ... | ... |
+Filled ONLY after user review — never pre-decide. Each row resolves a
+concern or alternative.
 ```
 
-### Workflow
-
-#### 1. Define the problem
-
-State what the part/assembly needs to accomplish. Include hard constraints (size envelope, specified manufacturing/process constraints, interfaces with other parts). Do not describe a solution yet.
-If no process is specified, treat manufacturing/process choice as an HLD alternative rather than as a hidden assumption.
-
-#### 2. Sketch the approach
-
-Describe the recommended approach at a conceptual level. Draw an ASCII diagram showing the key elements and their spatial relationships. Label the markdown diagram, but do not carry those labels into CAD geometry unless the real artifact needs markings.
-
-#### 3. Identify interfaces
-
-List every point where this design touches another part or the outside world. These are the contracts that constrain the design.
-
-#### 4. Explore alternatives
-
-Show 2-3 meaningfully different approaches. Not minor variations — genuinely different strategies. For each, state the key tradeoff in one line. Recommend one.
-
-#### 5. Write the usage guide
-
-Work backwards: describe how someone uses/assembles/operates this thing step by step. This is the most powerful validation — it forces you to think through the physical reality before writing code. If a step doesn't make sense ("how does the servo get inside?"), the design has a gap.
-
-Flag issues inline with ⚠️. These feed directly into the Concerns list.
-
-#### 6. Surface concerns
+### Review via git
 
-Collect everything from the usage guide ⚠️ flags plus any risks, open questions, or things that could go wrong. Be concrete and specific. These are the agenda for the review conversation.
+HLDs and LLDs iterate through git, not conversation:
 
-#### 7. Commit and present for review
+- **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."
 
-Commit the HLD to git. Tell the user it's ready for review. Do NOT fill in the Decisions table yet.
+### Rules
 
-#### 8. Iterate via git
+- 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.
 
-The user reviews the file (may edit it directly with comments/strikethroughs, or give verbal feedback). After review:
-
-1. Read the git diff or the updated file to see the user's feedback
-2. Update the HLD to address feedback
-3. Commit the update
-4. Present for another round if needed
-
-Repeat until the Decisions table is filled and the user says "go."
-
-### Git Workflow
-
-HLDs and LLDs iterate through git, not conversation. This keeps the document as the single source of truth and gives both sides a clear diff to review.
-
-```
-Agent writes HLD → git commit → User reviews (edits file or gives feedback)
-→ Agent reads diff → updates HLD → git commit → repeat until approved
-```
-
-- **Every version gets committed.** No unsaved drafts floating in conversation.
-- **User feedback goes in the file** (inline comments, strikethroughs) or in chat — agent checks both.
-- **The diff is the review artifact.** Agent reads `git diff` to see what changed.
-
-### Writing Rules
-
-- **Quality first.** There is no fixed page, time, or section-length limit. Write the HLD to the depth the design deserves.
-- **Clear, not artificially terse.** If a reviewer has to re-read a paragraph to understand it, rewrite it; do not delete needed content just to make it shorter.
-- **ASCII diagrams where useful.** A cross-section sketch can communicate layout better than paragraphs, but use whichever representation makes the design clearest.
-- **Decision-driving dimensions are welcome.** Include dimensions, size envelopes, counts, interface dimensions, and proportional constraints when they clarify architecture, risks, image matching, or feasibility. Put exhaustive construction dimensions and formulas in the LLD.
-- **Tables are allowed when they improve clarity.** Use compact tables for alternatives, interfaces, requirements, feature inventories, or visible evidence. Keep full parameter catalogs in the LLD.
-- **Concerns are not rhetorical.** Every concern must be specific enough that someone can say "yes that's a real problem" or "no, here's why it's fine."
-- **Alternatives are not padding.** If there's genuinely only one way to do it, say so and skip the table.
-
-### Relationship to Other Skills
+### Pipeline
 
 | Stage | Skill | Output |
 |-------|-------|--------|
-| 1. Explore the problem space | `/forgecad-high-level-spec` (this skill) | `*-hld.md` |
+| 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` files |
-
-The HLD must have its Decisions table filled before writing an LLD. The LLD must exist before implementation (unless the model is simple enough to skip straight from HLD to code).
-
-### Anti-Patterns
+| 3. Implementation | `/forgecad-make-a-model` + `/forgecad` | `.forge.js` |
 
-- **HLD that's actually an LLD.** If you're exhaustively specifying every part, formula, tolerance, and fabrication step before the architecture is chosen, you've gone too far. Back up.
-- **HLD with no alternatives.** You haven't explored the solution space. Even if the answer is obvious, name what you rejected and why.
-- **Concerns that are vague worries.** "This might be hard to manufacture" — hard how? Tool access? Bending radius? Wall thickness? Tolerance stack? Support material? Be specific or don't list it.
-- **Decisions made before review.** The whole point is to align with the user before committing. Present the HLD, discuss, then decide.
-- **Skipping the diagram.** If you can't draw it, you don't understand it yet.
-- **Iterating in conversation instead of in the file.** The document is the artifact. Update it, commit it, review the diff.
+The Decisions table must be filled before writing the LLD. Simple models may skip straight from HLD to code.

package/dist/docs-raw/skills/forgecad-image-replicator.md

@@ -1,3 +1,5 @@
+<!-- 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.
@@ -11,167 +13,48 @@ Build real ForgeCAD geometry from one or more reference images by treating image
 
 ## 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. It is not the deliverable.
-
-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.
+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).
 
-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.
+### Companion Skills
 
-### 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.
-
-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.
-
-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.
-
-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:
+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`.
 
-```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
-```
-
-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
-```
+### Comparison Boards
 
-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.
+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.
 
-```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:
+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 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
+uv run <skill-dir>/scripts/compare_images.py refs/front.png render-front.png compare-front.png
 ```
 
-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.
 
 
 ## Bundled Files