/forgecad-build-model

name: forgecad-build-model
description: Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence.
forgecad-public: true

Build 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 — e