forgecad 0.9.13 → 0.9.15

package/dist-skill/SKILL.md

@@ -17,7 +17,7 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 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).
-8. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
+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.
 
@@ -40,6 +40,7 @@ Load groups top-to-bottom, stopping when you have what the task needs.
 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)
@@ -89,7 +90,7 @@ Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural
 
 ### 9. Runtime Viewport APIs (for cut planes, exploded views, hiding, and animation playback)
 
-Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavior.
+Viewer-only APIs such as cutPlane, explodeView, render labels, comparison references, and runtime display behavior.
 
 - `{{SKILL_DIR}}/docs/generated/viewport.md`
 

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

@@ -28,7 +28,32 @@ const bomHelpers = require("./bom.js");
 bomHelpers.addFasteners(...);
 ```
 
-Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class Shape {}` collide with the injected runtime names. If you need a local helper, choose a project-specific name like `projectBom`, `sceneConfig`, or `makeShape`.
+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.
+
+Use project-specific local names instead:
+
+```javascript
+// BAD — `lib` and `slot` are injected runtime names.
+const lib = require("./wheel-lib.js");
+const slot = rect(20, 5);
+
+// GOOD — local names describe the project role.
+const wheelLib = require("./wheel-lib.js");
+const axleSlotSketch = rect(20, 5);
+```
+
+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:
+
+```javascript
+// GOOD — no top-level `slot` declaration.
+const wheelHelpers = require("./wheel-helpers.js");
+const axleSlot = wheelHelpers.slot(...);
+
+// GOOD — imported helper is renamed.
+const { slot: makeAxleSlot } = require("./wheel-helpers.js");
+```
+
+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`.
 
 ## Execution Model
 
@@ -67,6 +92,44 @@ return {
 };
 ```
 
+### 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

package/dist-skill/docs/CLI.md

@@ -32,7 +32,7 @@ forgecad project push
 forgecad project open
 ```
 
-Most CLI commands require a ForgeCAD account. Run `forgecad login` and choose email/password or API token when prompted. Use `FORGECAD_TOKEN=fc_pat_... forgecad <command>` only for CI/CD and one-off automation. `forgecad studio` always requires an explicit project path; use `.` for the current project.
+Local modeling, inspection, export, and skill-install commands do not require a ForgeCAD account. Hosted project sync, publishing, token management, and license activation require sign-in. Run `forgecad login` and choose email/password or API token when prompted. Use `FORGECAD_TOKEN=fc_pat_... forgecad <hosted-command>` only for CI/CD and one-off automation. `forgecad studio` always requires an explicit project path; use `.` for the current project.
 
 You can also start from the hosted starter project with `forgecad project clone start-here`, then `cd start-here` and `forgecad studio .`.
 
@@ -66,13 +66,13 @@ Execute scripts and produce images headless — no browser window. Renders use C
 
 ### `forgecad run`
 
-Execute a Forge script quickly and print the inner-loop build summary: returned objects, verification results, parameters, and timing.
+Execute a Forge script quickly and print the inner-loop build summary: build count, verification results, parameters, and timing.
 
-The fast validation command. Runs your script with the real geometry kernel (no browser needed) and reports whether it built, which objects came back, any `verify.*` results, parameter values, script logs, and elapsed script time. This is the command agents should run frequently while editing a model.
+The fast validation command. Runs your script with the real geometry kernel (no browser needed) and reports whether it built, how many objects came back, any `verify.*` results, parameter values, script logs, and elapsed script time. This is the command agents should run frequently while editing a model.
 
-**Fast by default** — a bare `forgecad run model.forge.js` does not compute per-object volumes, bounding boxes, construction history, feature tallies, spatial relationships, collision intersections, or solver profiles. Those diagnostics are useful, but they are no longer part of the hot path.
+**Fast by default** — a bare `forgecad run model.forge.js` does not compute per-object volumes, bounding boxes, construction history, feature tallies, or solver profiles. Those run diagnostics are useful, but they are no longer part of the hot path.
 
-**Opt-in diagnostics** — use `--details` for volume/bounding-box/object geometry summaries, `--history` for the construction tree, `--features` for feature tallies, or `--solver-profile` for constraint solver timing. Use `--spatial bounded|exact` only when you want directional relationships and collision intersections from the run command itself.
+**Opt-in diagnostics** — use `--details` for volume/bounding-box/object geometry summaries, `--history` for the construction tree, `--features` for feature tallies, or `--solver-profile` for constraint solver timing. Use `inspect fit interference`, `inspect physical gaps`, or `inspect mechanical-integrity --collisions` for spatial and collision evidence.
 
 **Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values. Verification failures remain non-fatal so the model can still render and be inspected.
 
@@ -90,7 +90,6 @@ forgecad run examples/api/static-assembly-connectors.forge.js --focus
 forgecad run examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
 forgecad run examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
 forgecad run examples/api/static-assembly-connectors.forge.js --details --history
-forgecad run examples/api/static-assembly-connectors.forge.js --spatial bounded
 forgecad run examples/products/cup.forge.js --connectivity
 forgecad run examples/products/cup.forge.js --journeys
 forgecad run examples/products/cup.forge.js --backend occt
@@ -100,14 +99,45 @@ forgecad run examples/products/cup.forge.js -p "Wall Thickness=3" -p "Body Heigh
 forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
 ```
 
+### `forgecad ls`
+
+List targetable scene objects for a model.
+
+Runs the model headlessly and prints the exact object paths that CLI tools can target. Use this before focused renders or inspections when object names, groups, or assembly paths are not obvious.
+
+The default output is a compact line-oriented list. Use `--tree` for an indented hierarchy, `--long` for geometry metrics, or `--json` for automation.
+
+```bash
+forgecad ls examples/api/static-assembly-connectors.forge.js
+forgecad ls examples/api/static-assembly-connectors.forge.js --tree
+forgecad ls examples/api/static-assembly-connectors.forge.js Bench
+forgecad ls examples/api/static-assembly-connectors.forge.js "Bench/Slat0" --long
+forgecad ls examples/api/static-assembly-connectors.forge.js --json
+```
+
+### `forgecad show`
+
+Render a quick target-focused viewport PNG.
+
+The main quick visual path for agents. Pass a model and, optionally, a target path from `forgecad ls`; ForgeCAD resolves the target and renders that object or group through the existing viewport renderer. Use `--from` for fast camera directions, or pass the lower-level render camera flags when you need exact reproducibility.
+
+Without a target, `show` renders the whole scene and behaves like a shorter, intent-first wrapper around `render 3d`.
+
+```bash
+forgecad show examples/api/static-assembly-connectors.forge.js
+forgecad show examples/api/static-assembly-connectors.forge.js Bench
+forgecad show examples/api/static-assembly-connectors.forge.js "Bench/Slat0" --from front --out slat-front.png
+forgecad show model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
+```
+
 ### Object Filtering: `--focus` and `--hide`
 
-Several CLI commands can filter the visible object set without changing model code: `run`, `render 3d`, `render wireframe`, `inspect <family> <mode>`, `capture`, and `check print`.
+Several CLI commands can filter the visible object set without changing model code: `render 3d`, `render wireframe`, `inspect <family> <mode>`, `capture`, and `check print`.
 
-Use `forgecad run model.forge.js --quality live` to list returned object names quickly, then pass those names to `--focus` or `--hide`.
+Use `forgecad ls model.forge.js` to list exact object paths quickly, then pass those names or globs to `--focus` or `--hide` on render and inspection commands.
 
 ```bash
-forgecad run examples/api/static-assembly-connectors.forge.js --quality live
+forgecad ls examples/api/static-assembly-connectors.forge.js --tree
 forgecad render 3d examples/api/static-assembly-connectors.forge.js bench.png --focus "Bench.*"
 forgecad render 3d examples/api/static-assembly-connectors.forge.js slats.png --focus "Bench.Slat*"
 forgecad inspect fit interference examples/api/static-assembly-connectors.forge.js --focus "Bench.*"
@@ -132,11 +162,12 @@ Inspect a model by asking for one explicit kind of evidence.
 
 `forgecad inspect` is the evidence-first inspection surface. Pick the job you want to verify, then choose the view like you would with `render 3d`.
 
+- `inspect sketch` — returned sketch/profile regions, selector dry-runs, and extrusion compatibility
 - `inspect history` — final-object feature recipes and feedback anchors
 - `inspect design-trace` — raw construction DAG, source spans, and cache diagnostics
 - `inspect section` — agent-native one-off section probe with optional ray rulers and replay JSON
 - `inspect replay` — rerun a saved section probe on the same or another source
-- `inspect visual image|cutaway|depth|normals|objects` — visual context, clipped 3D cutaways, depth, normals, and identity evidence
+- `inspect visual image|cutaway|depth|normals|rig|objects` — visual context, clipped 3D cutaways, depth, normals, rig skeletons, and identity evidence
 - `inspect surface zebra|roughness` — surface continuity and roughness evidence
 - `inspect physical components|floating|gaps` — physical component graph evidence
 - `inspect fit interference` — positive-volume overlap evidence
@@ -159,8 +190,27 @@ forgecad inspect sections stack main.forge.js --plane yz --every 1
 forgecad inspect compare overlay candidate.forge.js --with reference.3mf
 ```
 
+### `forgecad inspect sketch`
+
+Inspect returned sketches and profile regions used by returned shapes.
+
+Runs a model and reports inspectable 2D sketch/profile regions without requiring model code to register inspection hooks. The command inspects returned Sketch objects and profile-bearing shape compile plans such as extrude, cut, and revolve. Use `--seed x,y` to dry-run which region a point selector would consume, and `--operation extrude` to check extrusion compatibility.
+
+```bash
+forgecad inspect sketch examples/api/sketch-regions.forge.js
+forgecad inspect sketch model.forge.js --object "Profile" --seed 45,15
+forgecad inspect sketch model.forge.js --json --object "Body" --seed 45,15 --operation extrude
+```
+
+`inspect sketch` is external inspection: it runs the script, then reads returned scene objects and shape compile plans. Model code should not call an inspection API. It reports selectable 2D `regions` from returned `Sketch` / `ConstraintSketch` objects and from profile-bearing returned shapes (`extrude.profile`, `cut.profile`, `revolve.profile`).
+
+JSON contract: `targets[]` are inspectable sketches/profile uses; `regions[]` are filled selectable areas sorted largest-first with run-local ids like `R0`; `holes[]` are excluded interiors; `selection` is present only with `--seed`; `profileTree` is compile-plan provenance, not JavaScript variable names. Stable selection v1 is `--seed x,y`, not region id.
+
+Seed failures are explicit and exit nonzero when no target matches: outside every region, on a boundary, inside a hole, ambiguous, no regions, or incompatible operation. `--operation extrude` only checks whether the selected filled region can be consumed by extrusion; open path/rail selection is intentionally unsupported in v1.
+
 | Command | Description |
 |---------|-------------|
+| `inspect sketch` | Inspect returned sketches and profile regions used by returned shapes. |
 | `inspect visual image` | Capture standard shaded viewport evidence. |
 | `inspect visual objects` | Capture object identity evidence. |
 | `inspect section` | Run one exact section probe with optional ray rulers. |
@@ -199,7 +249,7 @@ forgecad render hq examples/products/cup.forge.js --preset dramatic
 
 Render a Forge scene to PNG using the real viewport renderer.
 
-Launches a headless Chrome instance, renders the scene with the same WebGL viewport as the editor, and saves a PNG. The output path defaults to `<script-name>.png` next to the input file.
+Launches a headless Chrome instance, renders the scene with the same WebGL viewport as the editor, and saves a PNG. The output path defaults to `<script-name>.png` next to the input file. Each render uses a private renderer server by default, so parallel renders do not compete for the same Vite port.
 
 The input can be a `.forge.js` script or a direct `.stl`, `.obj`, `.3mf`, `.step`, or `.stp` asset. Direct STEP/STP rendering auto-selects OCCT unless you pass `--backend`.
 
@@ -269,9 +319,9 @@ forgecad render hq examples/products/cup.forge.js --transparent --preset glass
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
 
-Animated orbit or joint playback.
+Animated orbit, section sweep, or named joint playback.
 
-Renders an animated sequence by either orbiting the camera around the model or playing back a `jointsView` animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joints clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
+Renders an animated sequence by either orbiting the camera around the model or playing back a named joint animation. Use `--capture orbit` (default) for a turntable rotation, `--capture animation --animation <name>` to play a named joint clip, or `--capture section-sweep` to move a clipping plane through the model. Supports `--cut-plane` to animate with a static cross-section visible. Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` to choose the orbit base camera or the fixed camera for animations and section sweeps.
 
 ```bash
 forgecad capture gif examples/products/cup.forge.js
@@ -281,7 +331,7 @@ forgecad capture gif model.forge.js out/front.gif --camera front
 forgecad capture gif model.forge.js out/hero.gif --view hero
 forgecad capture gif examples/3d-printer.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
 forgecad capture mp4 examples/products/cup.forge.js
-forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
+forgecad capture mp4 examples/api/assembly-kinematics-four-bar.forge.js out/four-bar.mp4 --view iso
 forgecad capture mp4 model.forge.js out/raw.mp4 --param "Output=raw-sdf"
 forgecad capture mp4 model.forge.js out/front.mp4 --camera front
 forgecad capture mp4 model.forge.js out/hero.mp4 --view hero
@@ -326,9 +376,9 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--background <color>` | Canvas background override |
 | `--render-mode <solid\|wireframe>` | Shaded solid (default) or wireframe only |
 | `--edges <off\|thin\|bold>` | Edge overlay preset in solid mode (default: off) |
-| `--render-style <classic\|studio\|fast\|glass\|inspection\|precision\|hybrid\|scan>` | Visual render style (render default: classic; inspect default: inspection) |
-| `--scan-granularity <12-72>` | Scan cells across the scene longest axis |
-| `--port <n>` | Vite dev server port |
+| `--render-style <classic\|studio\|fast\|glass\|inspection\|contour\|scan>` | Visual render style (render default: classic; inspect default: inspection) |
+| `--scan-granularity <12-144>` | Scan cells across the scene longest axis |
+| `--port <n>` | Renderer server port |
 | `--fresh-server` | Start a fresh renderer instead of reusing an existing one |
 | `--chrome-path <path>` | Chrome or Chromium executable path |
 | `--output <path>` | Output file path |
@@ -349,7 +399,7 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--pitch <deg>` | Camera pitch angle in degrees |
 | `--format <gif\|mp4>` | Output format |
 | `--capture <orbit\|animation\|section-sweep>` | Capture preset |
-| `--animation <name>` | Named jointsView animation clip |
+| `--animation <name>` | Named joint animation clip |
 | `--animation-loops <n>` | Repeat the selected animation clip |
 | `--cut-plane <name>` | Enable a named cut plane |
 | `--sweep-plane <XY\|XZ\|YZ>` | Moving plane for section-sweep |
@@ -419,8 +469,8 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 | Option | Description |
 |--------|-------------|
 | `--output <path>` | Output STEP path |
+| `--backend <occt\|truck>` | Exact BREP exporter: occt (default) or truck (native analytic kernel) |
 | `--quality <default\|live\|high>` | Forge quality preset |
-| `--backend <manifold\|occt\|truck>` | Geometry backend (default: manifold) |
 | `-o <path>` | Shorthand for --output |
 | `--dim-angle-tol <deg>` | Dimension routing tolerance in degrees |
 | `--format <pdf\|dxf>` | Output format |
@@ -454,7 +504,7 @@ cd start-here
 forgecad studio .
 ```
 
-`forgecad login` asks how you want to sign in, then prompts for either email/password or an API token. If your account was created through GitHub or Google, create an API token in Settings > API Tokens, run `forgecad login`, and choose API token. Use `FORGECAD_TOKEN=fc_pat_...` only for CI/CD and one-off automation. See [Platform authentication](platform/auth.md#cli-auth-for-oauth-accounts) for details.
+`forgecad login` asks how you want to sign in, then prompts for either email/password or an API token. If your account was created through GitHub or Google, create an API token in Settings > API Tokens, run `forgecad login`, and choose API token. Use `FORGECAD_TOKEN=fc_pat_...` only for CI/CD and one-off automation.
 
 `forgecad project init` creates the remote project, writes `forgecad.json`, pushes any existing local source files, and records server file IDs. `forgecad project push` syncs an already initialized project; it does not create a remote project from an arbitrary folder.
 
@@ -641,7 +691,7 @@ The CLI is free for personal non-commercial use. Pro covers human-operated comme
 | `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `compare 3d`, `check print`, `inspect fit interference`, `inspect mechanical-integrity` for personal non-commercial use | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work | `render hq`, `capture gif`, `capture mp4` plus commercial coverage for client/customer work | Backend, hosted, embedded, or application workflows that call ForgeCAD automatically |
 
 ```bash
-forgecad license                    # Check signed-in account status
+forgecad license                    # Check local license status
 forgecad license activate           # Activate Pro for the signed-in account
 forgecad license deactivate         # Remove license
 ```