forgecad

name: forgecad description: ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, validating scripts, or using ForgeCAD export/render tooling. forgecad-public: true

Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.

Workflow

Identify the artifact: .forge.js, SVG asset, or CLI/export task.
If the model has any moving parts, load the assembly group and {{SKILL_DIR}}/docs/guides/joint-design.md upfront — do not defer the kinematic structure to a refactor pass.
Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed, and prefer these docs and recipes over ad-hoc repo examples.
If any two parts are intended to touch or mate in the final model, load {{SKILL_DIR}}/docs/guides/positioning.md immediately and default to connectors + matchTo().
Default to a concrete first pass — easy iteration beats speculative design review.
If an existing model is broken, replace the weak structure rather than preserving bad architecture.
Validate with forgecad run <file> (add --debug-imports for import chain issues; pass --backend manifold|occt|truck when the backend matters).
For moving assemblies, return the Assembly directly so runtime controls re-solve the link/edge kinematics model instead of stacking viewport-only transforms.
Model the physical artifact, not an educational diagram. No explanatory labels, arrows, legends, or text plaques unless the user explicitly asks for a presentation or teaching view; product markings only where the real object would carry them.
Build the real closed CAD first. Never bake cutaways, sectioned shells, permanently exploded layouts, or hidden-parts views into the default model just to show internals — use viewer-only cut planes, explodeView, object hiding, transparency, or inspect sections after the artifact exists.

Import and Composition

Always include the extension in relative imports: require("./file.forge.js", { Param: value }) for model files, require("./helpers.js") for plain helper modules. Extensionless imports such as require("./file") do not resolve; ForgeCAD resolves project imports by exact path.
ForgeCAD APIs are injected globals in .forge.js files. Use bom(), box(), scene(), Shape, etc. directly; never destructure those names from helpers (const { bom } = require("./bom.js")). Import helper files under a project-specific name such as const bomHelpers = require("./bom.js").
For static multi-part models, connectors + matchTo() are the default way to assemble touching parts.
Top-level scripts can return Assembly or SolvedAssembly directly. Do not call .toGroup() just to render an assembly; use it only when you need ShapeGroup composition, transforms, or named-child lookup.
Import.svgSketch() loads SVG files (file format loader, not a module import).
.placeReference('bottom', [0,0,0]) aligns any built-in anchor to a world coordinate; also works with custom .withReferences().
Plain .js modules hold shared helpers/constants (not model imports).

Source Map

Load groups top-to-bottom, stopping when you have what the task needs.

1. Core API (always read first)

Execution model, colors, coordinate system, primitives, booleans, patterns, imports, parameters, topology, edge queries.

{{SKILL_DIR}}/docs/API/core/concepts.md
{{SKILL_DIR}}/docs/generated/runtime-names.md
{{SKILL_DIR}}/docs/generated/core.md

2. Static Assembly and Positioning (for any multi-part model)

Axis conventions, winding rules, and placement strategy. If parts should touch in the final model, read this group before writing placement code. Connectors + matchTo() are the default for mating interfaces; raw translate() and rotate() are for free offsets, not assembly contracts.

{{SKILL_DIR}}/docs/guides/coordinate-system.md
{{SKILL_DIR}}/docs/guides/positioning.md

3. Sketch APIs

2D construction, transforms, booleans, paths, on-face sketching, extrusion, anchors, text, regions.

{{SKILL_DIR}}/docs/generated/sketch.md

4. Curves and Surfacing (for lofts, sweeps, splines)

Smooth curves, Hermite splines, lofted and swept solids. For straps, inlays, guards, brace members, vents, or physical bands that live on a carrier surface, use Carrier + SurfaceBody surface-member primitives before reaching for variableSweep, SDF sculpting, or manual boolean overlap recipes.

{{SKILL_DIR}}/docs/guides/surface-members.md
{{SKILL_DIR}}/docs/generated/curves.md

5. Assemblies and Mechanisms (for joints or kinematics)

Assembly graph, joint types, couplings, validation, and simulation export.

{{SKILL_DIR}}/docs/generated/assembly.md

6. Sheet Metal (for bent parts, K-factor, flat patterns)

Bend operations, flat pattern unfolding, K-factor configuration.

{{SKILL_DIR}}/docs/generated/sheet-metal.md

7. Output and Export (for STL/3MF/STEP, BOM, dimensions)

Mesh export, exact geometry export, bill of materials, dimension annotations.

{{SKILL_DIR}}/docs/generated/output.md

8. Toolbox (fasteners and standard parts)

Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural profiles.

{{SKILL_DIR}}/docs/generated/lib.md
{{SKILL_DIR}}/docs/generated/wood.md

9. Runtime Viewport APIs (for cut planes, exploded views, hiding, and animation playback)

Viewer-only APIs such as cutPlane, explodeView, render labels, comparison references, and runtime display behavior.

{{SKILL_DIR}}/docs/generated/viewport.md

10. Recipes and Debugging (for patterns and troubleshooting)

Modeling patterns, debugging tactics, copyable snippets.

{{SKILL_DIR}}/docs/guides/scene-presentation.md
{{SKILL_DIR}}/docs/guides/joint-design.md

11. CLI (for validation/render/export tasks)

Test-run, export pipelines, debug flags.

{{SKILL_DIR}}/docs/CLI.md
{{SKILL_DIR}}/docs/guides/inspection-bundles.md

SDF Modeling (smooth booleans, TPMS, deformations, fromFunction)

Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas. The doc preamble's precision caution applies to every SDF workflow.

{{SKILL_DIR}}/docs/generated/sdf.md