forgecad 0.9.16 → 0.10.0

package/dist-skill/SKILL.md

@@ -11,25 +11,25 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 ## Workflow
 
 1. Identify the artifact: `.forge.js`, SVG asset, or CLI/export task.
-2. **If the model has any moving parts, load the `assembly` group AND the `joint-design.md` recipe upfront** — do not defer the kinematic structure to a refactor pass.
-3. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed.
-4. If any two parts are intended to touch or mate in the final model, load the positioning guide immediately and default to connectors + `matchTo()`.
+2. **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.
+3. 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.
+4. 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()`.
 5. Default to a concrete first pass — easy iteration beats speculative design review.
 6. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
-7. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues, and pass `--backend manifold|occt|truck` when the backend matters).
+7. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues; pass `--backend manifold|occt|truck` when the backend matters).
 8. For moving assemblies, return the `Assembly` directly so runtime controls re-solve the link/edge kinematics model instead of stacking viewport-only transforms.
-9. Model the physical artifact, not an educational diagram. Do not add explanatory labels, arrows, legends, or text plaques unless the user explicitly asks for a presentation or teaching view. Product markings are allowed only when they would exist on the real object.
-10. Build the real closed CAD first. Do not 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.
+9. 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.
+10. 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 and `require("./helpers.js")` for plain helper modules. Do not write extensionless imports such as `require("./file")`; ForgeCAD resolves project imports by exact path.
-- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; do not destructure those names from helpers with patterns like `const { bom } = require("./bom.js")`. If a helper file is needed, import it under a project-specific name such as `const bomHelpers = require("./bom.js")`.
+- 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 `.toGroup()` only when you need `ShapeGroup` composition, transforms, or named-child lookup.
-- `importSvgSketch()` for SVG files (file format loader, not a module import).
-- `.placeReference('bottom', [0,0,0])` to align any built-in anchor to a world coordinate; also works with custom `.withReferences()`.
-- Plain `.js` modules for shared helpers/constants (not model imports).
+- 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
 
@@ -48,7 +48,6 @@ Execution model, colors, coordinate system, primitives, booleans, patterns, impo
 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/geometry-conventions.md`
 - `{{SKILL_DIR}}/docs/guides/positioning.md`
 
 ### 3. Sketch APIs
@@ -61,6 +60,7 @@ Axis conventions, winding rules, and placement strategy. If parts should touch i
 
 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)
@@ -98,7 +98,7 @@ Viewer-only APIs such as cutPlane, explodeView, render labels, comparison refere
 
 Modeling patterns, debugging tactics, copyable snippets.
 
-- `{{SKILL_DIR}}/docs/guides/modeling-recipes.md`
+- `{{SKILL_DIR}}/docs/guides/scene-presentation.md`
 - `{{SKILL_DIR}}/docs/guides/joint-design.md`
 
 ### 11. CLI (for validation/render/export tasks)
@@ -110,6 +110,6 @@ Test-run, export pipelines, debug flags.
 
 ### SDF Modeling (smooth booleans, TPMS, deformations, fromFunction)
 
-Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas. SDF is inherently implicit and sampled, not B-rep/exact geometry; use caution for precision-critical parts and exact export workflows.
+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`

package/dist-skill/docs/API/core/concepts.md

@@ -5,177 +5,47 @@ skill-order: 1
 
 # ForgeCAD Core Concepts
 
-ForgeCAD scripts are JavaScript that returns geometry. The forge API is globally available — no imports needed.
+A `.forge.js` script is plain JavaScript that returns geometry. The entire forge API is injected as globals — never `import`, `require`-destructure, or shadow ForgeCAD API names (`const lib = ...`, `let slot = ...`, `class Shape {}` all collide). The reserved list is in [Runtime Names](../../generated/runtime-names.md); check it before using natural local names.
 
-```javascript
-const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
-return box(width, 30, 10);
-```
+## Execution & Return Values
 
-## Injected Runtime Names
+All geometry operations are **immutable** — shapes, sketches, groups, assemblies, and boards return new values, never mutate in place.
 
-ForgeCAD API functions and classes are injected into every `.forge.js` script. Use them directly; do not import or destructure ForgeCAD API names from helper files.
+A script must return one of three shapes:
 
-```javascript
-// BAD — `bom` and `bomToCsv` are already built-in runtime names.
-const { bom, bomToCsv } = require("./bom.js");
+1. **A single renderable** — `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, or `SdfShape`.
+2. **An array** of renderables or named descriptors `{ name, tags?, shape | sketch | group, color? }`:
 
-// GOOD — use the built-in directly.
-bom(4, "M4 bolt");
+   ```javascript
+   return [
+     { name: "Base Plate", tags: ["printed", "structural"], shape: base, color: "#888888" },
+     { name: "M4 Bolt", tags: "fastener", shape: bolt, color: "#4488cc" },
+   ];
+   ```
 
-// GOOD — keep project helpers under their own local name.
-const bomHelpers = require("./bom.js");
-bomHelpers.addFasteners(...);
-```
+3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`.
 
-Top-level lexical declarations such as `const bom = ...`, `let slot = ...`, `const lib = ...`, `const joint = ...`, or `class Shape {}` collide with the injected runtime names. This is checked when the script runs, so agents should treat these names as reserved before executing the model.
+Return an unsolved `Assembly` directly — ForgeCAD solves it at default joint values for display. Use `assembly.solve(state)` for a specific pose. Never call `.toGroup()` just to make an assembly render; use it only when you need `ShapeGroup` composition or named-child lookup.
 
-Use project-specific local names instead:
+For multi-file projects — import path rules, the metadata pattern, and Forge-aware builder modules — see the [`require()` docs](../../generated/core.md).
 
-```javascript
-// BAD — `lib` and `slot` are injected runtime names.
-const lib = require("./wheel-lib.js");
-const slot = rect(20, 5);
+## Identity
 
-// GOOD — local names describe the project role.
-const wheelLib = require("./wheel-lib.js");
-const axleSlotSketch = rect(20, 5);
-```
+`union()` merges shapes into one solid with one identity — later operands lose separate colors and names. Use `group(...)` or named return objects when parts need separate colors, tags, or identities.
 
-If a helper module exports a name that matches a ForgeCAD runtime name, keep the module under one local object name or rename during destructuring:
+## Face Labels
 
-```javascript
-// GOOD — no top-level `slot` declaration.
-const wheelHelpers = require("./wheel-helpers.js");
-const axleSlot = wheelHelpers.slot(...);
+Shapes carry semantic face labels through their lifecycle:
 
-// GOOD — imported helper is renamed.
-const { slot: makeAxleSlot } = require("./wheel-helpers.js");
-```
+1. **Primitives** assign canonical names (`box()` → `top`, `bottom`, `side-left`, ...; `cylinder()` → `top`, `bottom`, `side`).
+2. **Extrusions** inherit sketch labels and add `top`/`bottom`.
+3. **Transforms** preserve all labels.
+4. **Booleans** preserve first-operand labels where geometry survives.
 
-The complete collision-reserved list is generated from the runtime source in [Runtime Names](../../generated/runtime-names.md). Check that list before using natural local names such as `lib`, `slot`, `joint`, `group`, `path`, `text2d`, `scene`, or `Shape`.
+Resolve labels with `.face(name)` or `.face(query)` — see the Shape class docs for the query API.
 
-## Execution Model
+## Conventions
 
-- Scripts re-execute on every parameter change (400ms debounce)
-- Geometry operations are **immutable** — shapes, sketches, groups, imported assemblies, and wood boards return new values instead of modifying in place
-- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, `SdfShape`, `Array` of renderables, `Array` of `{ name, tags?, shape?, sketch?, group?, color? }`, or a **metadata object** (see below)
+**No explanatory text inside CAD geometry.** Model the physical artifact; explain the design through names, comments, BOM entries, and docs. Use `text2d()` only when letters are part of the real object (engraving, branding, gauge ticks); use `Viewport.label()` only for temporary review/debug annotation — never to compensate for unclear geometry.
 
-Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD solves it at default joint values for display. Return `assembly.solve(state)` when you want a specific pose. Do not call `.toGroup()` just to make an assembly render — use `.toGroup()` only when you specifically need `ShapeGroup` composition, group-style transforms, or named-child lookup.
-
-### Metadata Object Return
-
-A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, SolvedAssembly, SdfShape, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
-
-When importing project files, include the full extension in every relative path: `require('./motor-mount.forge.js')` for model files and `require('./helpers.js')` for plain helper modules. ForgeCAD resolves project imports by exact path and does not infer `.forge.js` or `.js` from `require('./motor-mount')`.
-
-```javascript
-// motor-mount.forge.js — renders standalone, exports metadata via require()
-const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
-return {
-  shape: mount.color('#556B2F'),                        // rendered
-  bolts: { dia: 5.3, pos: holePositions },              // metadata — skipped in render, available via require()
-};
-
-// base-body.forge.js — imports mount, accesses .bolts
-const mount = require('./motor-mount.forge.js');
-for (const [x, y] of mount.bolts.pos) { ... }          // use metadata
-// mount.shape is the Shape if you need it in an assembly
-```
-
-Arrays inside the object are also rendered:
-
-```javascript
-return {
-  parts: [{ name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }],
-  armWidth: 6,  // metadata
-};
-```
-
-### Forge-Aware Builder Modules
-
-A `.forge.js` file can also return builder functions. Those functions keep access to
-the ForgeCAD runtime names from their defining file, so this is the supported way
-to share sketch, profile, shape, or assembly builders that need APIs such as
-`path()`, `circle2d()`, `box()`, or `assembly()`.
-
-This pattern works well when a file should be both directly inspectable and
-importable: render the flat profiles or part preview when the file is opened on
-its own, and export builders under a named object for the assembly file.
-
-```javascript
-// profiles.forge.js - inspectable on its own, reusable through require()
-function wheelProfile() {
-  return circle2d(40).subtract(circle2d(18));
-}
-
-return {
-  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
-  make: { wheelProfile },
-};
-```
-
-```javascript
-// main.forge.js - reuses the exact inspected profile
-const profiles = require('./profiles.forge.js');
-const wheel = profiles.make.wheelProfile().extrude(8);
-return wheel;
-```
-
-Keep builder modules pure over top-level constants, top-level `param()` values,
-or explicit function arguments. Do not declare new `param()` values inside an
-exported builder if callers need `require('./profiles.forge.js', { Width: 80 })`
-overrides: import overrides are validated while the module loads, before any
-exported builder is called. For plain constants, tables, math helpers, and
-formatting code that does not construct ForgeCAD geometry, use `.js` helper
-modules instead.
-
-Named return objects and named `group(...)` children can include `tags`. Tags are viewport metadata: they do not affect geometry, exports, face labels, or BOM rows, but the command palette can hide, show only, or focus every object with a selected tag.
-
-```javascript
-return [
-  { name: 'Base Plate', tags: ['printed', 'structural'], shape: base },
-  { name: 'M4 Bolt A', tags: 'fastener', shape: boltA },
-  { name: 'M4 Bolt B', tags: 'fastener', shape: boltB },
-];
-```
-
-## Coordinate System
-
-Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
-
-## Colors
-
-`.color(hex)` works on `Shape` and `Sketch`. Colors survive transforms. Boolean operations return a single result shape, so only the first operand's color survives.
-
-**`union()` merges shapes into one solid mesh** — later operands do not keep separate colors or identities. Use `group(...)` or return named objects instead when you want separate parts:
-
-```javascript
-return [
-  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
-  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
-];
-```
-
-## Face Operations
-
-Shapes carry semantic face labels through their lifecycle. The flow is:
-
-1. **Primitives** assign canonical names — `box()` gives you `top`, `bottom`, `side-left`, etc.; `cylinder()` gives `top`, `bottom`, `side`.
-2. **Extrusions** inherit labels from the sketch and add `top`/`bottom`.
-3. **Transforms** (translate, rotate, scale, mirror) preserve all labels.
-4. **Booleans** preserve labels from the first operand where geometry survives.
-
-You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
-
-## Text vs Viewport Labels
-
-Default to no explanatory text inside CAD geometry. A ForgeCAD model should represent the physical artifact, not a labeled teaching diagram. Explain the design through file names, named return objects, comments, BOM entries, inspection bundles, and companion docs.
-
-Use `text2d()` only when the letters are part of the real object: raised branding, engraving, serial plates, keyboard legends, gauge ticks, connector labels, service arrows, scale markings, or exported manufacturing markings. `text2d()` builds filled sketch geometry from font outlines, so it can make exact/OCCT workflows slower.
-
-Use `Viewport.label(text, [x, y, z], options)` only for temporary review, debug, tutorial, or explicitly requested presentation views. Render labels are annotations only: they do not create meshes, do not export, do not enter the B-rep path, and do not add face labels. Do not use viewport labels to compensate for unclear geometry in the final model.
-
-## SDF Modeling
-
-For organic shapes, smooth blending, TPMS lattices, and surface deformations. Return `SdfShape` values directly, or return a plain object/array tree of SDF leaves, for native raymarch preview. Use `.toShape()` or `toShape(...)` only when you need mesh-backed CAD/export behavior. See [sdf-primitives.md](sdf-primitives.md).
+**SDF shapes preview natively** when returned directly; call `.toShape()` only when mesh-backed CAD/export behavior is needed. See [SDF docs](../../generated/sdf.md).