forgecad 0.9.16 → 0.10.1

package/dist-skill/website/skills/forgecad-make-a-model.md

@@ -0,0 +1,186 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-make-a-model/SKILL.md instead. -->
+
+# forgecad-make-a-model
+
+Create manufacture-realistic prototype ForgeCAD (.forge.js) models in the active CAD project. Handles file placement, invokes the forgecad skill for API guidance, and validates the result.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-make-a-model/SKILL.md` |
+
+---
+
+## Make a Model
+
+Create new ForgeCAD models in the user's active ForgeCAD project.
+
+### Default Output Standard
+
+Unless the user asks otherwise, the output is a **manufacture-realistic prototype**: a model someone could fabricate, buy parts for, assemble, inspect, and iterate in a real shop — not a concept sketch, not a universal 3D-printing exercise, not a claim of certified production readiness.
+
+- Include prototype-real features: wall thickness, fastener stacks, bosses, ribs, flanges, seats, gaskets, cable exits, service access, toleranced clearances, believable purchased parts. No invented tooling details, certifications, or safety ratings unless asked.
+- Modifiers shift the standard: `blockout` → rough massing; `production-realistic` → DFM and production-intent materials; `printable` → make the selected printed parts honest; `visual-CAD` → clearly visual, not pretending build-ready.
+- Zero unexpected final collisions is part of the definition of done (see Collision Policy).
+
+### File Placement
+
+New `.forge.js` files go under date-based directories (today's date) in the user's current ForgeCAD project or a clearly named local folder:
+
+```
+YYYY/MM/DD/file.forge.js           — single-file model
+YYYY/MM/DD/folder/main.forge.js    — multi-file entry point (always main.forge.js)
+YYYY/MM/DD/folder/parts/*.forge.js — standalone/importable parts
+YYYY/MM/DD/folder/lib/*.js         — pure helpers/constants, no geometry
+```
+
+- Kebab-case descriptive names (`parametric-lego.forge.js`). Each part file must run standalone and import via `require('./parts/name.forge.js', params)`.
+- Plain `.js` only for constants, math, tables, formatting — never geometry.
+- Split files only for reusable parts or independent sub-assemblies, never for organization.
+
+### Workflow
+
+1. **Load the `forgecad` skill** — read at least the Core API reference. Moving parts: also the assembly group and joint-design guide. Mating parts: the positioning guide; default to connectors + `matchTo()`.
+2. `mkdir -p YYYY/MM/DD/[folder]`.
+3. Moving parts: prove the rig first (Kinematics-First below).
+4. Write the model — `param()`/`Param.bool()` for tunable dimensions; pick the manufacturing process before styling; build real internals; follow the contracts below.
+5. Validate — `forgecad run <file>` (`main.forge.js` for multi-file).
+6. Run the Final Acceptance Gate and Manufacturing Outputs checks below on `main.forge.js`.
+7. Iterate — convert every render/inspect finding into a model edit and rerun the same targeted evidence until reality matches the intended component graph.
+
+### Process, Style, and Variants
+
+**Manufacturing process is a choice, not an assumption.** Never treat every model as printable. Pick process cues from the load path and operating story: machined, bent sheet, tube-and-plate, wood/composite, molded-look, printed, or hybrid purchased-hardware construction (rideables: metal/composite structure + purchased wheels/bearings; furniture: real joinery). Print-specific features (slicer clearances, heat-set inserts, layer-oriented ribs) only when the process includes printed parts.
+
+**Visual style: expensive and credible, not generically colorful.** Restrained material-driven palette (ivory, charcoal, satin black, brushed aluminum, brass, muted burgundy/green/navy, smoked polymer, natural wood); match color to material/process so metal, polymer, rubber, PCB, and wood read differently. Bright color only as small accents (controls, seals, indicators). Keep seams, fasteners, gaskets, and purchased parts legible.
+
+**Form is part of credibility.** Real products carry deliberate edge treatment — chamfered or rounded profiles where hands, seals, or tooling meet the part, draft on molded faces, consistent proportions and design language across parts. A knife-sharp box reads as a blockout, not a product. Get the rounding from profile-level geometry (rounded sketch corners, chamfered profiles) per the fillet caveat below.
+
+**Variants are parameter-selected.** Sizes/styles/revisions go behind one choice parameter (`Variant`, `Preset`); return only the selected variant. Comparison lineups only behind an explicit debug parameter so they can never pollute collision findings.
+
+### Physical Artifact, Not Teaching Diagram
+
+Deliver the real closed artifact — covers installed, parts in assembled positions. The `forgecad` skill carries the no-labels/no-cutaway rule (no explanatory labels, arrows, or legends in production geometry; never a cutaway, sectioned, or exploded default); it binds here. Markings only when the real artifact has them (serial plates, gauge ticks, molded icons) — sparse, process-appropriate. Explain roles via named return objects and `verify.*`; review annotations go in `Viewport.label()` or a debug mode, never exported geometry.
+
+**Internal geometry is part of the model.** If the real artifact has internals, model them as real geometry even when hidden: cavities, ribs, bosses, screw holes, bearing seats, electronics/battery volumes, wire channels, mechanism clearances and stops. Verify hidden structure with exploration tools — alternate views, `inspect sections`, `--hide`, transparent shells, named ghosts — never by mutilating the returned model.
+
+### Kinematics-First for Moving Parts
+
+For any mechanism (linkage, hinge, slider, suspension, gripper, drawer), the rig is the source of truth: build and prove the motion structure first, then attach geometry — never retrofit motion onto finished shells.
+
+- Pick the rig shape before geometry: point-link graphs for closed-loop skeletons with distance/angle constraints; frames and connector joints when part orientation matters (API roster in the assembly docs).
+- Name every degree of freedom; encode limits/defaults at rig level. Mirrored revolute axes need an explicit sign mapping — equal joint values do not automatically mirror poses.
+- Attach proxy geometry only (pivot markers, bars, slider blocks, wheel discs). Run the rig at rest, mid-travel, both limits, and mirrored/coupled poses until the solver, controls, connector alignment, and `verify.*` checks all pass:
+
+  ```bash
+  forgecad run model.forge.js --joint "theta=45"
+  forgecad render 3d model.forge.js /tmp/theta-45.png --joint "theta=45" --camera iso
+  ```
+
+  Use real joint names; repeat `--joint` per control. A pose that fails to solve, clamps unexpectedly, breaks a connector check, or adds a collision means the rig is not ready for final geometry.
+- Only then attach manufacture-real geometry to the solved links, frames, and connectors — never via a final `rotate()` that makes one pose look assembled.
+- Return the unsolved `Assembly` so Motion controls re-run the real solve. Never bake a posed `SolvedAssembly` to make one pose look right.
+- Encode pose checks in-script with `verify.*`: convergence, connector origins coinciding, link lengths holding, end effectors reaching targets, running clearances positive.
+
+### Mechanical Assembly Contract
+
+A mechanical script is not done when it merely looks assembled. Every visible piece needs a physical reason to be where it is: fused material, contact faces, a screw stack, a pin in a bore, a tab in a slot, a gasket on a land, a bearing in a seat, a cable in a channel, or a named intentional ghost.
+
+- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`. Final `translate()` calls are not assembly contracts.
+- Manual joint frames (`addFixed`/`addRevolute`/`addPrismatic` with a hand-built `frame:`) are scaffolding, not contracts. Before delivery, convert mating interfaces to connectors with `connect()`/`match()`, or prove the manual joint with `forgecad debug assembly --fail-on warning` and documented geometry.
+- A named part must not contain unintentional disconnected bodies: boolean-join manufactured features, model fasteners/seals as separate named parts, or add the receiving holes/lands that explain the separation.
+- Screws are not decoration: clearance/counterbore in the cover, receiving boss or through stack in the parent, material around both, axes aligned from one shared bolt pattern.
+- Handles and levers need a load path: hub-to-arm neck, pivot pin/bore, thrust shoulders, stops/detents, and the connected follower. A handle tangent to a hub is a failed mechanism.
+- Covers, doors, cartridges, service panels need seats: ledges, gasket grooves, bosses, snap hooks, tabs, or hinge barrels — plus a visible retention story.
+- Cables, wires, tubes need receiving geometry: gland, grommet, clamp, socket, ferrule, routed channel, or hose barb. Never let a cylinder end in open space.
+- Purchased loose parts may stay separate bodies — name them as purchased hardware/consumables and seat them in believable sockets, bores, races, or fastener stacks.
+- Encode interface intent with `verify.*`, not comments: `verify.clearanceBetween` for seated fits and clearance bands, `verify.minClearance`/`verify.notColliding` for keep-out and running gaps, `verify.connectorDistance` for connector mates. Part counts and generic dimensions never prove an interface.
+- No canned finished-object helpers for project-specific assemblies. Reusable vocabulary is primitives, cutters, patterns, and mechanical contracts (`lib.fastenerSet()`, `lib.boltPattern()`, real bores and pockets, connectors + `matchTo()`) — not finished backplates, brackets, or hinge leaves.
+
+Treat `fillet()`/`chamfer()` as experimental (Manifold can be incorrect, OCCT slow); prefer profile-level rounding and inspect before relying on the result.
+
+### Imported Parts (User-Supplied 3D Files)
+
+When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-3d-reconstruction`, a different request).
+
+- Wrap each import in its own part file: `Import.mesh()` for STL/OBJ/3MF, `Import.step()` for STEP (OCCT backend), normalize scale and orientation, recenter to a sane local origin, then treat it exactly like a purchased part — connectors at its real mating features, positioned by the assembly via `matchTo()`.
+- Never trust units. Verify against a known dimension before mating anything: bbox via `forgecad run --details`, or `inspect section --ray` across a bore or face pair. For 3MF, account for every build item printed by `forgecad run` before flattening.
+- Derive mating geometry by measurement, not eyeball: pull bore positions, diameters, and face offsets from sections, then hold them with `verify.clearanceBetween`/`verify.connectorDistance` against the import like any other body. Collision Policy applies to imports too.
+- The import is a purchased/fixed line item; the manufactured deliverables are the ForgeCAD-authored parts around it. Remodel an imported feature only where a boolean against the mesh is unreliable — and say so.
+
+### Collision Policy
+
+Each returned part is real matter. Expected final collision count: **zero**.
+
+- Only exceptions: welded, fused, overmolded, cast-in, potted, or bonded matter — declared with `verify.intentionalOverlap` on the exact visible object pair with the physical reason. The mechanical-integrity gate honors a declaration only when that pair has a confirmed exact collision; unused or non-visible declarations still fail.
+- Never use interpenetration as a placement shortcut. Model contact honestly: pins in holes, shafts in seats, tabs in slots, hinges with knuckle clearance, nested parts with wall offsets, moving parts with travel envelopes.
+- Temporary construction overlaps (oversized cutters before `difference()`, primitives before `union()`, exploratory layouts) must be consumed, hidden, named as ghosts, or isolated with `--focus`/`--hide` so final findings stay meaningful.
+- Collision removal is part of the modeling pass, not optional polish.
+
+### Final Acceptance Gate
+
+Prove technical validity and visual plausibility before declaring done. Apply to any model with multiple bodies, surface details, cables, rails, handles, product skins, or hidden mating geometry.
+
+1. **State the intended physical component graph** — one connected component, several intentionally separate, or a selected assembly plus named ghosts — then run `forgecad inspect physical components` and require the count to match. Unexpected islands, accidental fusion, or bbox-only "touching" are model bugs.
+   - Scripts using `assembly()`: `forgecad debug assembly model.forge.js --fail-on warning`. Fix warnings (multiple roots, manual joint contracts, disconnected bodies, unused connectors, collisions); a truly intentional one gets a visible reason in code.
+   - Generated mechanical work: `forgecad inspect mechanical-integrity . --collisions` is the shareability gate — it fails on missing `verify.*` interface checks, fragmented named groups, uncontracted manual assemblies, positive-volume collisions, timeouts, runtime failures. Do not share while red unless the user asked for a blockout.
+   - Include at least one verification that proves a mechanical interface (clearance band, keep-out, connector mate), not just object counts.
+   - Moving assemblies: incomplete until poses cover rest, mid-travel, both limits, coupled and mirrored states via `--joint` and/or in-script `solve(state)` checks, with convergence, attachment, and clearances holding at every pose.
+2. **Collision evidence**: run `forgecad inspect fit interference`; read the manifest collision count AND the evidence PNGs. Zero unexpected findings per Collision Policy; visually confirm where any findings appear.
+3. **Risk-specific views, not just a hero shot.** Delivery renders use the model's `scene()` rig (Scene Presentation below) — default flat lighting in a final render is a finding. One whole-model context view plus views chosen from this object's failure modes — opposing, underside, interior-facing, or grazing angles that catch internals showing through openings, covers that don't close, bad boolean cuts. Per meaningful interface: one contextual and one focused/isolated view. Risk prompts:
+   - long products, rails, handles, tools: views along and across the dominant length (bends, sag, end attachments)
+   - enclosures/shells with internals: exterior plus hidden-cover views (fit, concealment, service access)
+   - sockets, underside joins, stands, brackets: look directly into the mating face or underside; `inspect sections` for hidden geometry
+   - cables, strings, belts, tubes: both endpoints, route clearance, sag, termination hardware
+   - surface details on curved ProductSkin bodies: grazing and contextual views proving details conform or embed
+4. **Visual attachment audit.** For every detail that should be connected, ask "where does this physically enter, seat, wrap, terminate, or fasten?" and check that view directly. Known failures to fix before delivery:
+   - a flat rail or bed sitting on a curved shell instead of being recessed, saddled, socketed, or blended in
+   - strings/cables passing through space without knots, hooks, holes, posts, ferrules, pulleys, or anchors
+   - trim lines floating above the body instead of following the surface or being inset/raised strips with real thickness
+   - handles/grips touching only by a tangent instead of having a neck, bridge, socket, screws, or overmolded landing
+   - small hardware/gems that are bbox-connected but visually levitate; give them flush/inset seats or explicit brackets
+5. **ProductSkin honesty.** Boolean-test warnings from sampled-loft boundary edges are not real collisions. Deliver only if the collision count is clean, connectivity is correct, and the attachment audit passes; mention the residual warning in the final response.
+6. **Name the evidence** in the final response: commands run, views checked, joint values tested, focus/hide filters, component count, collision count, residual warnings or intentional exceptions. Never just say "validated."
+
+### Manufacturing Outputs
+
+A manufacture-realistic model must yield a package a shop can consume, not just a clean viewport.
+
+- Register every purchased and fabricated part with `bom()` (exact spec, quantity, purpose) so the BOM lives in the model — `forgecad export report` must reproduce it without prose supplements.
+- Put `dim()` annotations on the dimensions a builder must hit: overall envelope, critical interfaces, mating bores and bolt patterns.
+- Prove the process-appropriate export runs cleanly and name the output path in the final response: `export stl`/`export 3mf` for printed parts; `export step` for machined parts and CAD interchange; sheet-metal parts must unfold to a valid flat pattern (`export cutting-layout` for sheet goods). `step`, `report`, and `cutting-layout` need a Production license — if unavailable, run the free exports and name the gated commands that complete the package instead of failing.
+- An export failure (non-manifold body, open shell, fused multi-part blob where one fabricated part was expected) is a model bug, not an export problem.
+
+### Render and Inspect Cadence
+
+**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-render-inspect` skill and the CLI docs — this skill fixes only the cadence and the gates.
+
+Render after every feature addition, boolean cut, symmetric copy placement, and the last feature. Inspect after adding hidden geometry a surface render cannot prove, after adding or moving mating parts, ghosts, connectors, thin walls, or screw holes, and before delivery with thresholds set for the material/process.
+
+**Keep inspection scenes small.** Return one selected configuration; include only the parts needed to prove the current risk (if a check concerns three objects, inspect those three, not the whole shop floor); prefer `--focus`/`--hide` and parameter-selected diagnostic modes over permanent extra objects; collapse proven subassemblies into fewer named objects where identity doesn't matter for collisions, masks, or contracts. If you cannot hold the scene in your head, you cannot debug it honestly.
+
+**Ghost parts for fit checks.** When a part holds or contains another object, render both with the contained object as a compact transparent named ghost — e.g. a `box()` at the seat position with `.color('#ff4444').material({ opacity: 0.4 })`, returned as `{ name: 'Servo Ghost', shape: ghost }`.
+
+Use `verify.*` for dimensions and clearances that decide acceptance; `console.log()` only for explanatory traces (shown under "Script output:" in `forgecad run`).
+
+### Build Bottom-Up
+
+You cannot target a complex model in one pass. Decompose, solve the smallest piece, verify, compose upward:
+
+1. **Decompose** into the smallest parts you can reason about confidently. A gear is not small — a single tooth profile is.
+2. **Solve one piece** in isolation: own variables, own return, no connection logic yet.
+3. **Verify it**: `forgecad run`, then render and read the PNG. Fix while the scope is tiny.
+4. **Compose one layer at a time**, verifying at each level so a break is always at the newest seam.
+
+For any model with more than ~3 distinct geometric features, plan the decomposition explicitly before writing geometry.
+
+### Scene Presentation
+
+Always set up `scene()` — default lighting looks flat. Worked recipes (studio and matte-industrial setups, named views, plinth) live in `guides/scene-presentation.md` via the `forgecad` skill; the schema is in the viewport docs. Hard-won cliffs:
+
+- Setting `lights` replaces ALL defaults — always include an ambient light or the scene goes black.
+- Minimum rig: ambient fill + one warm key (`castShadow: true`) + weaker cool fill/rim. Keep `environment.intensity` low — environment fill kills shadows.
+- Prefer roughness over fog for softness; keep bloom near zero for mechanical parts or they read toy-like.
+- If a render is close, nudge `toneMappingExposure` by ~0.05 before redoing the rig; avoid big ambient jumps.
+- Camera: 3/4 angle, `fov` 35–50, `target` at the visual center of mass. Ground plane with shadows for grounded objects.
+- Environment by type: `studio` for metallic/jewelry, `warehouse`/`apartment` for organic/matte, `warehouse` + strong directionals for mechanical, `night` + bloom/vignette for dramatic.

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

@@ -0,0 +1,82 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-model-grader/SKILL.md instead. -->
+
+# forgecad-model-grader
+
+Analyze, verify, and grade ForgeCAD or CAD-as-code models against a user requirement, design brief, prompt, reference, or acceptance criteria. Use when asked to evaluate, judge, QA, benchmark, score, rate, or compare a CAD model; render it from multiple angles, run targeted inspections when needed, visually verify the evidence, and produce a 0-10 score with concise justification.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-model-grader/SKILL.md` |
+
+---
+
+## ForgeCAD Model Grader
+
+Grade the delivered model against the requirement, not against what could be fixed later. Never edit the model unless the user explicitly requests repairs — then record the baseline grade first, change, and re-grade.
+
+### Workflow
+
+1. **Extract the requirement** into a checklist, must-haves separate from nice-to-haves. If the brief is vague, grade the most reasonable literal interpretation and mark unverifiable items `Unknown`.
+2. **Run the model**: `forgecad run <model>.forge.js` (in the ForgeCAD repo use the local build, `node dist-cli/forgecad.js run ...`). If it fails to execute, stop and apply the caps.
+3. **Render** at least `iso`, `front`, `right`, `top` to a scratch dir; add views (back, bottom, close-up, section) when the model is asymmetric, hollow, mechanical, or likely to hide mistakes.
+4. **Open and look at every PNG** — never score from command output alone. Check silhouette, proportions, required features, part boundaries, interfaces, and whether the model reads as the requested artifact from more than one angle.
+5. **Inspect** whenever hidden internals, fit, wall thickness, or assembly behavior are central to the brief — grading without inspecting them caps the score. Delegate evidence choice, commands, and manifest reading to the `forgecad-render-inspect` skill. Findings (unexpected collisions, thin regions, floating bodies, wrong component counts) are evidence, not warnings to wave away.
+6. **Score**: fill the rubric, apply caps, give a final 0-10 in whole or `.5` increments. Unknowns count against the score.
+
+### Rubric
+
+| Dimension | Points | What To Look For |
+| --- | ---: | --- |
+| Requirement fit | 4 | Satisfies the stated must-haves, captures the intended object/function, no drift into a generic substitute. |
+| Geometric completeness | 2 | Correct silhouette, proportions, visible details, part boundaries, internal structure when required, no missing major components. |
+| Mechanical/manufacturing plausibility | 2 | Believable materials/process, real interfaces, clear load paths, fasteners/seats/clearances where needed, no impossible assembly. |
+| Validation health | 1 | Runs cleanly, renders from multiple views, targeted inspections reveal no major unaddressed issues. |
+| Code/model quality | 1 | Parametric clarity, readable organization, meaningful names, no debug junk, appropriate ForgeCAD APIs. |
+
+Anchors: 9-10 = evidence-backed match for the brief; 7-8 = recognizable and mostly complete, fixable gaps; 5-6 = main idea only; below 5 = broken or loosely related.
+
+### Evidence Caps
+
+Maximum scores, applied after the rubric:
+
+- Model does not execute: max `2`.
+- Executes but cannot be rendered: max `4`.
+- No rendered images visually inspected: max `5`.
+- Only one flattering view inspected: max `6`.
+- A must-have requirement is absent: max `6`.
+- Visually recognizable but physically impossible for the requested use: max `6`.
+- Internals, fit, walls, or assembly central to the brief but uninspected: max `7`.
+- Inspection finds unexpected collisions, floating bodies, critical thin walls, or wrong connectivity: max `6`; max `5` when the defect invalidates the main function.
+- Delivered as a finished product/prototype but presented with default flat lighting (no `scene()` rig), a generically colorful or material-false palette, or teaching-diagram styling: max `8`. Does not apply when the brief asks for a blockout or bare technical study.
+- Any score relying on an assumption the evidence cannot verify: mark it `Unknown`, never score above `8`.
+
+### Report Format
+
+```markdown
+Score: N / 10
+
+Requirement checklist:
+| Item | Result | Evidence |
+| --- | --- | --- |
+| ... | Pass/Partial/Fail/Unknown | render/inspection/file evidence |
+
+Evidence reviewed: run outcome; views inspected; inspection highlights.
+Why this score: decisive strengths and defects.
+Caps applied: list, or `None`.
+Next fixes: the 2-5 highest-leverage improvements.
+```
+
+### Grading Rules
+
+- A beautiful render with missing functional geometry is not a high score.
+- Grade the default returned model unless the user names a parameter set or variant.
+- No points for comments, labels, or intentions absent from the geometry.
+- Decorative screws, floating labels, and teaching-diagram callouts are not real mechanical interfaces.
+- Cite which render or inspection finding drove the grade.
+- When comparing models, use identical checklist, cameras, inspection evidence, and caps for all.
+
+
+## Bundled Files
+
+- `agents/openai.yaml`

package/dist-skill/website/skills/forgecad-prepare-prompt.md

@@ -0,0 +1,63 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-prepare-prompt/SKILL.md instead. -->
+
+# forgecad-prepare-prompt
+
+Turn a fuzzy physical product, mechanism, or CAD artifact request into a concrete manufacture-realistic prototype ForgeCAD build brief and a single master prompt for the modeling pass. Use when the engineering brief is incomplete, manufacturing/process choice is underspecified, or the work needs a specific operating story to avoid generic toy solutions.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-prepare-prompt/SKILL.md` |
+
+---
+
+## Prepare ForgeCAD Prompt
+
+Use before modeling when the user wants something physically real and buildable but the request is fuzzy ("make me a robot gripper", "make it production ready", "I don't know the numbers, make sensible choices"). This skill owns intake and prompt preparation; once the brief is concrete, hand off to the `forgecad` skill.
+
+### Core Rules
+
+**Manufacturing is a design decision, not a default.** Never assume FDM, 3D printing, "printable", or plastic parts unless the user explicitly asked, the artifact family honestly points there, or the chosen process stack includes printed parts. Derive the process stack from artifact family, load path, scale, safety expectations, material properties, production intent, and operating story — family→process examples and all numeric anchors live in `references/default-profiles.md`. If the user names a process, honor it but warn when it is unsafe or dishonest for the duty.
+
+**Posture taxonomy.** Default output posture is **manufacture-realistic prototype**: a serious build candidate with real materials, purchased-part boundaries, assembly logic, and validation — no claims of production tooling, certification, rider safety, or release-ready DFM. Other postures only when the brief justifies them: `production-realistic` (explicit production intent), `printable` (printing is the selected process), `visual-CAD` (form study), or a specific process posture (`sheet-metal`, `CNC-machined`, `laser-cut`, `welded tube`, `injection-molded`, `cast`, `hybrid purchased-hardware`). Pick the posture that is honest for the artifact, not the easiest CAD surface.
+
+**Family-scoped numbers.** Every starter assumption is scoped to one artifact family. Never reuse numbers across families; never apply one default profile to unrelated artifacts.
+
+### Workflow
+
+1. **Normalize the ask** into plain mechanism language. "6 DOF gripper" usually means one of: standalone gripper with finger joints, wrist plus gripper, or full arm plus gripper.
+
+2. **Build the specific operating story**: an invented specific (non-famous) org, a named program, a prototype revision, a review moment, a test setting, mission pressure (pilot gate, demo date, investor milestone, customer deployment), and the generic failure mode to avoid. Prefer bold high-agency stories — go/no-go gates, first-customer pilots, investor demos — over modest lab exercises.
+   - Good: "RivetLine Automation is racing toward a first-customer kitting-cell pilot and needs the RG-4 gripper jaw for a live demo next Wednesday. The jaw must pick 40-90 mm plastic housings from a tray, use hardware the build tech can source this week, and make finger-pad replacement possible without rebuilding the linkage."
+   - Bad: vague prestige labels ("frontier robotics startup") with no program/rig/milestone specifics.
+   - Never assert the user works for a named real company unless they said so. Named real products only as public comparison anchors. Never clone proprietary designs — public-domain patterns and first-principles engineering only.
+
+3. **Classify the artifact family** (`references/default-profiles.md`): grippers and small mechanisms; fixtures/jigs/holders; enclosures and electronics housings; furniture and load-bearing structures; chassis and mobile robot structures; human vehicles and rideable forms. Rideables always route to human-vehicles, never chassis. If no family fits, use the no-family-fits escape there — never force one.
+
+4. **Choose the process posture** per the taxonomy above.
+
+5. **Pick the qualitative levers** — duty: `light-duty`/`general-duty`/`sturdy-duty`; scale: `compact`/`medium`/`large`; cost: `cheapest`/`balanced`/`performance-first` — and translate them into family-scoped starter assumptions.
+
+6. **Close only the critical gaps.** At most 3 grouped questions, always choice menus, never raw engineering inputs (payload mass, torque budget, backlash tolerance) unless the architecture truly depends on them and cannot be bracketed safely. Good: "Which feels closest: a light desk demo, a useful hobby tool, or a sturdier bench mechanism?" Bad: "What payload mass?"
+
+7. **Write the engineering brief.** Required fields: artifact + family + normalized interpretation; operating story + production reason + test setting + generic failure mode to avoid; output posture; intended objects/loads, size envelope, motion style and DOF; process stack and material defaults; purchased-part (BOM) boundary; validation standard; variant policy — multiple versions of one object are selectable params (`Variant`/`Preset`/`Style`), one rendered at a time, a comparison lineup only as an explicit non-default debug mode so collision inspection proves one real assembly; file organization — `main.forge.js` entry point for multi-file projects (convention owned by `forgecad-make-a-model`); explicit uncertainty policy.
+
+8. **Emit one master prompt.** Fill `references/master-prompt.md` from the chosen profile and assumptions. Return the finished prompt, not notes about it.
+
+9. **Hand off** to the `forgecad` skill if implementation continues; for moving mechanisms its index routes to the assembly and joint-design docs.
+
+### Defaults And Verdict
+
+If the user stays vague: `general-duty` / `medium` / `balanced`, invent the operating story, and use the family starter assumptions from `references/default-profiles.md`.
+
+The prompt must demand exactly `BUILD-READY` or `BEST-EFFORT BUILD CANDIDATE`. If the request outruns the chosen profile, downgrade the claim and keep going. No placeholders ("appropriate motor", "adjust as needed") — choose a defensible value, state it, continue. No follow-up questions unless the architecture would materially change and no safe assumption bundle exists. Human-bearing furniture and rideable vehicles usually end `BEST-EFFORT BUILD CANDIDATE`.
+
+### Output Contract
+
+Reply with a short interpretation of the request, the chosen family + operating story + assumption bundle (compact, options menu only if truly needed), then the single filled master prompt last. Do not bury the prompt under theory.
+
+
+## Bundled Files
+
+- `references/default-profiles.md`
+- `references/master-prompt.md`

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

@@ -0,0 +1,26 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-project/SKILL.md instead. -->
+
+# forgecad-project
+
+ForgeCAD project CLI workflow — creating, managing, syncing projects and files on forgecad.io. Covers init, push, pull, file operations, member management, publishing, and sharing.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-project/SKILL.md` |
+
+---
+
+## ForgeCAD Project Operating Rules
+
+forgecad.io is the hosted ForgeCAD platform; a project is a local folder linked to the server by `forgecad.json`. The full command inventory (project, file, member, share, token commands and flags) lives in `forgecad project --help` and the forgecad skill's `docs/CLI.md` — do not relearn it here.
+
+- **One studio process.** Run a single long-running `forgecad studio <folder> [<folder> ...]` naming every active project folder. The user opens the one printed localhost port once; create and edit files only under those folders so the browser live-updates. Never spawn extra servers per project.
+- **studio vs dev.** `forgecad studio` is for users and agents; `forgecad dev` is only for developing ForgeCAD itself.
+- **Login only for hosted commands.** `forgecad login` before any `project`/`publish` command; local work (run, render, studio) needs no auth.
+- **init creates, push syncs.** `project init "Name"` creates the remote project, writes `forgecad.json`, and pushes existing local files. `push` only syncs an already-initialized project. `clone <slug>` is the inverse: remote → new local folder.
+- **Sync is content-hash based.** `status`/`push`/`pull` compare file content hashes — no timestamps, no git; a file is "modified" purely by content difference. Loop: edit → `project status` → `project push`.
+- **Sync vs single-file ops.** Use `status`/`pull`/`push` for normal sync; use `project file <read|save|delete|...>` only for one hosted-file operation without a full push/pull cycle.
+- **Project context required.** All `project file *` and `publish` commands must run inside a folder containing `forgecad.json`.
+- **Shares are live references.** A published model always shows the current project file, never a snapshot — pushing changes silently updates published models. `publish` prints the share URL.
+- **Non-interactive runs.** Pass `--force` to skip confirmation prompts (push, pull, delete) in agent automation.

package/dist-skill/website/skills/forgecad-reconstruction-benchmark.md

@@ -0,0 +1,60 @@
+<!-- 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.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-reconstruction-benchmark/SKILL.md` |
+
+---
+
+## ForgeCAD Reconstruction Benchmark
+
+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
+
+- `agents/openai.yaml`

package/dist-skill/website/skills/forgecad-render-inspect.md

@@ -0,0 +1,80 @@
+<!-- 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.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-render-inspect/SKILL.md` |
+
+---
+
+## ForgeCAD Render Inspect
+
+Use `forgecad inspect ...` when a shaded render is too ambiguous and you need structured evidence: a bundle directory with evidence PNGs plus a root `manifest.json` (or, for `inspect section`, a probe directory with `result.json`, `section.svg`, `section.png`). Inspection is not a substitute artifact: look inside with sections, masks, `--focus`/`--hide`, and transparency — never edit the model into a cutaway or exploded default to make inspecting easier. Output dirs: let `inspect` allocate its timestamped directory by default (repeated probes never collide); use `/tmp/<model>-inspect` for throwaway bundles, a project directory only for persistent artifacts.
+
+Routing: authoring/API questions → `forgecad` skill; creating a new model → `forgecad-make-a-model`.
+
+### Workflow
+
+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
+   python <this-skill-dir>/summarize_manifest.py /tmp/model-inspect
+   ```
+
+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
+
+| Question | Evidence command |
+|----------|------------------|
+| Quick visual sanity | `inspect visual image` |
+| Kinematic rig, joints, axes, and links | `inspect visual rig` |
+| Object naming and identity | `inspect visual objects` |
+| Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
+| Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at\|stack\|sample` |
+| Multi-part interference, fit checks, ghost parts, moving clearances | `inspect fit interference` |
+| Printability, shell walls, ribs, bosses, snaps, slots | `inspect manufacture thickness` plus `inspect sections at\|stack\|sample` when internals matter |
+| Parts without a mesh-contact path to the ground | `inspect physical floating` |
+| Accidental fusion, connected solids | `inspect physical components` |
+| Air gaps between physical components | `inspect physical gaps` |
+| Surface orientation, occlusion, faceting, strange protrusions | `inspect visual depth` or `inspect visual normals` |
+| Loft, fillet, skin, and sweep surface continuity | `inspect surface zebra` or `inspect visual normals` |
+| Reference-vs-candidate reconstruction comparison | `inspect compare overlay --with reference.3mf` |
+
+### Section Probe + Replay
+
+The agent-native measure-then-recheck loop:
+
+```bash
+forgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0
+forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js
+```
+
+The probe's `result.json` field contract (frames, rulers, gaps, replaySpec) is documented in the forgecad skill's `docs/guides/inspection-bundles.md`.
+
+### Misread Traps
+
+- Face-touching is not a collision; collision findings are positive-volume overlaps.
+- Gray/unresolved thickness area means the evidence is incomplete, not that the model is safe.
+- Distance/gap figures are bbox-gap metrics between components, not closest-surface distances.
+- Depth, normals, and zebra are visual aids (heatmap, camera-view normals, stripe shader), not exact measurements or curvature proofs.
+- Resolve mask colors through the manifest's object list, never by object order.
+
+### Reference
+
+Bundle/manifest contract, evidence semantics, and current limits: the forgecad skill's `docs/guides/inspection-bundles.md`. CLI flags and command tree: its `docs/CLI.md`.
+
+
+## Bundled Files
+
+- `summarize_manifest.py`

package/dist-skill/website/skills/forgecad-visual-spec.md

@@ -0,0 +1,71 @@
+<!-- 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.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-visual-spec/SKILL.md` |
+
+---
+
+## ForgeCAD Visual Spec
+
+### Scope
+
+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
+
+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.
+
+Negatives (the only negatives list — reuse it, never restate variants):
+
+- 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
+
+### Prompt Skeleton
+
+Block order: identity → mechanism truth → materials/color truth → pose/state → shot/camera/lighting → negatives. Fill in, don't copy:
+
+```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].
+```
+
+Default shot: `front-left three-quarter hero view, eye-level product camera`. Alternate: `rear-right three-quarter view showing motor placement and belt routing`.
+
+### Modes
+
+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.
+
+| 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` |
+
+### 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 — 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
+
+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`