forgecad 0.9.15 → 0.10.0

package/dist-skill/docs/CLI.md

@@ -5,7 +5,7 @@ skill-order: 1
 
 # ForgeCAD CLI
 
-Create projects, open local studios, run, inspect, export, publish, and sync `.forge.js` models from your terminal. Core workflows are included with a free ForgeCAD account; advanced exports and rendering are Pro.
+Create projects, open local studios, run, inspect, export, publish, and sync `.forge.js` models from your terminal. Licensing tiers are summarized once in [Setup & Licensing](#setup--licensing).
 
 ## Quick Start
 
@@ -32,7 +32,7 @@ forgecad project push
 forgecad project open
 ```
 
-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.
+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 (for GitHub/Google accounts, create a token in Settings > API Tokens first). 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 .`.
 
@@ -46,7 +46,7 @@ ForgeCAD includes a local editor. Open it around a dedicated project folder, edi
 | `dev <project-path> [project-path ...]` | Start the Vite dev server for ForgeCAD source development. |
 | `web` | Start a local dev server in web/playground mode (no filesystem, localStorage only). |
 
-`forgecad studio <project-path>` is the normal installed-CLI command for users. `forgecad dev <project-path>` starts the Vite dev server and is mainly for ForgeCAD source development.
+`forgecad studio <project-path>` is the normal installed-CLI command; `forgecad dev` starts the Vite dev server and is mainly for ForgeCAD source development. Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder as an argument — the user opens the single printed localhost port once, and AI agents only create or edit files under those folders so the browser updates live without starting more servers.
 
 <details>
 <summary>Common flags for studio / dev</summary>
@@ -68,35 +68,15 @@ Execute scripts and produce images headless — no browser window. Renders use C
 
 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, 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.
+The fast validation command: runs the script with the real geometry kernel (no browser) and reports build status, object count, `verify.*` pass/fail with expected vs actual values (non-fatal — the model still renders), parameter values, script logs, and timing. Run it frequently while editing.
 
-**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.
+A bare `forgecad run` skips expensive diagnostics. Opt in with `--details` (volumes/bounds), `--history` (construction tree), `--features` (feature tallies), `--solver-profile` (constraint solver timing), or `--connectivity` (physical connected components — bbox contact is evidence, exact geometry is checked by default). `--quality live|default|high` selects the same geometry quality profile as the editor and export tools; `live` is fastest for large models.
 
-**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.
-
-**Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping bbox candidates are checked with exact geometry by default, while bbox-only contact is treated as evidence rather than proof of one connected component. This helps answer whether the model is one continuous assembly or several separate islands.
-
-**Quality preset** — pass `--quality live|default|high` to select the same geometry quality profile used by the editor and export tools. `live` is the fastest preset for large audit models.
-
-**Direct CAD inputs** — pass `.stl`, `.obj`, `.3mf`, `.step`, or `.stp` directly when you just want to inspect an external asset. Mesh files are imported with `importMesh(...)`; STEP/STP files are imported with `importStep(...)` and auto-select OCCT unless you pass `--backend`.
-
-For deeper confidence gates, prefer `forgecad inspect mechanical-integrity`, `forgecad check print`, or targeted evidence commands such as `forgecad inspect fit interference` instead of turning `run` back into a catch-all audit command.
+Direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` inputs are imported automatically; STEP/STP auto-selects OCCT unless you pass `--backend`. For deeper confidence gates, prefer `inspect mechanical-integrity`, `check print`, or `inspect fit interference` instead of turning `run` into a catch-all audit command.
 
 ```bash
-forgecad run examples/api/static-assembly-connectors.forge.js
-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/products/cup.forge.js --connectivity
-forgecad run examples/products/cup.forge.js --journeys
-forgecad run examples/products/cup.forge.js --backend occt
-forgecad run examples/products/cup.forge.js --backend truck --quality live
-forgecad run examples/products/cup.forge.js --debug-imports
-forgecad run examples/products/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
-forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+forgecad run model.forge.js
+forgecad run model.forge.js --details --history
 ```
 
 ### `forgecad ls`
@@ -108,11 +88,8 @@ Runs the model headlessly and prints the exact object paths that CLI tools can t
 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 ls model.forge.js
+forgecad ls model.forge.js --tree
 ```
 
 ### `forgecad show`
@@ -124,37 +101,23 @@ The main quick visual path for agents. Pass a model and, optionally, a target pa
 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"
+forgecad show model.forge.js
+forgecad show model.forge.js Bench
 ```
 
 ### Object Filtering: `--focus` and `--hide`
 
-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 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.
+`render 3d`, `render wireframe`, `inspect <family> <mode>`, `capture`, and `check print` can filter the visible object set without changing model code. Use `forgecad ls model.forge.js` to list exact object paths, then pass names or globs:
 
 ```bash
-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.*"
-forgecad inspect visual objects examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1" --camera iso
+forgecad render 3d model.forge.js bench.png --focus "Bench.*"
+forgecad inspect visual objects model.forge.js --hide "Bench.Slat0,Bench.Slat1" --camera iso
 ```
 
-Rules:
-
-- A bare `--focus` hides mock objects and keeps real objects.
-- `--focus name1,name2` renders only matching objects.
-- `--hide name1,name2` removes matching objects from the visible scene.
-- Matching is case-insensitive and supports `*` / `?` globs.
-- `--focus` and `--hide` are mutually exclusive.
-- Filtering happens after the script runs; it does not avoid evaluating the full model.
-- Filtering works on returned object names. For grouped children, use concrete child names or globs like `Bench.*`.
-- If a model unions many parts into one returned shape, the original parts cannot be isolated by CLI filtering.
-- Filtered renders fail when no renderable objects remain, and exact cameras report visible objects that are partially or fully outside the camera frame.
+- `--focus name1,name2` shows only matching objects; a bare `--focus` (no value) hides mock objects and keeps real ones.
+- `--hide name1,name2` removes matching objects. `--focus` and `--hide` are mutually exclusive.
+- Matching is case-insensitive with `*` / `?` globs against returned object names — use child names or globs like `Bench.*` for grouped children. Parts unioned into one returned shape cannot be isolated.
+- Filtering happens after the script runs (the full model is always evaluated). Filtered renders fail when no renderable objects remain, and exact cameras report visible objects partially or fully outside the frame.
 
 ### `forgecad inspect`
 
@@ -179,49 +142,20 @@ Inspect a model by asking for one explicit kind of evidence.
 ```bash
 forgecad inspect history main.forge.js --object "Left Leg" --level object
 forgecad inspect design-trace main.forge.js --query feature:hole
-forgecad inspect fit interference main.forge.js --camera iso
-forgecad inspect visual cutaway main.forge.js --plane yz
-forgecad inspect visual objects main.forge.js --camera front --camera right
-forgecad inspect manufacture thickness main.forge.js --min 1.6 --warn 2.4
-forgecad inspect section main.forge.js --plane yz --ray bore:-20,0:20,0
-forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js
-forgecad inspect sections at main.forge.js --plane yz --offset 12.5
-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.
+External inspection: runs the model, then reads returned `Sketch`/`ConstraintSketch` objects and profile-bearing shape compile plans (extrude, cut, revolve) — model code never calls an inspection API. Reports filled selectable regions (sorted largest-first, run-local ids like `R0`) and excluded hole interiors. `--seed x,y` is the stable selection mechanism (not region ids): it dry-runs which region a point selector would consume, and seed failures exit nonzero (outside every region, on a boundary, inside a hole, ambiguous, or incompatible operation). `--operation extrude` checks only whether the selected filled region can be consumed by extrusion.
 
 ```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
 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. |
-| `inspect replay` | Replay a saved section inspection result on a source model. |
-| `inspect fit interference` | Capture positive-volume interference evidence. |
-| `inspect manufacture thickness` | Capture wall-thickness evidence. |
-| `inspect sections at` | Capture one exact section at a plane offset. |
-| `inspect sections stack` | Capture periodic physical section slices. |
-| `inspect sections sample` | Capture a fixed number of representative section slices. |
-| `inspect compare overlay` | Capture candidate-vs-reference comparison evidence. |
-| `inspect evidence` | List available inspect commands. |
+The full `inspect sketch` JSON contract (`targets[]`/`regions[]`/`holes[]`/`selection`/`profileTree` semantics) lives in [guides/inspection-bundles.md](guides/inspection-bundles.md).
 
 ### `forgecad render`
 
@@ -237,43 +171,23 @@ Render a Forge scene. Use a subcommand — `3d`, `views`, `section`, `wireframe`
 - `render hq` — path-traced via Blender Cycles, for documentation and marketing shots
 
 ```bash
-forgecad render 3d examples/products/cup.forge.js
-forgecad inspect fit interference examples/api/static-assembly-connectors.forge.js --camera iso
-forgecad render views examples/products/cup.forge.js
-forgecad render wireframe examples/products/cup.forge.js
-forgecad render section examples/furniture/01-table.forge.js --plane XZ
-forgecad render hq examples/products/cup.forge.js --preset dramatic
+forgecad render 3d model.forge.js
+forgecad render section model.forge.js --plane XZ
 ```
 
 ### `forgecad render 3d`
 
 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. 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`.
+Launches headless Chrome, 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; the input can be a `.forge.js` script or a direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` asset.
 
-Use `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--view` flag selects a named camera declared in `scene({ views })`. The `--camera` flag accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass `--camera` multiple times to render several viewpoints in one run. Use `--camera-json <file>` or `--scene <file>` for exact reproducible viewport cameras without shell escaping. Filtered renders report any visible objects whose bounding boxes are partially or fully outside the camera frame; exact cameras fail when they frame none of the visible objects.
+`--camera` accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass it multiple times to render several viewpoints in one run. `--view` selects a named camera declared in `scene({ views })`; `--camera-json <file>` or `--scene <file>` give exact reproducible cameras without shell escaping. `--focus`/`--hide` filter visible objects; `--edges=<off|thin|bold>` controls the edge overlay.
 
-Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.
-
-This is the standard way to visually verify geometry from the CLI or in agent workflows. For higher quality (path-traced, materials, HDRI lighting), use `render hq` instead.
+This is the standard way to visually verify geometry from the CLI or in agent workflows. For path-traced quality use `render hq`; for edges only use `render wireframe`.
 
 ```bash
-forgecad render 3d examples/products/cup.forge.js
-forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus
-forgecad render 3d examples/api/static-assembly-connectors.forge.js --focus "Bench.Slat*"
-forgecad render 3d examples/api/static-assembly-connectors.forge.js --hide "Bench.Slat0,Bench.Slat1"
-forgecad render 3d model.forge.js --view hero
-forgecad render 3d model.forge.js --camera 45:30
-forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
-forgecad render 3d model.forge.js --camera-json camera.json
-forgecad render 3d model.forge.js --scene scene.json
-forgecad render 3d model.forge.js --camera front --camera side
-forgecad render 3d model.forge.js -p "Wall Thickness=3"
-forgecad render 3d model.forge.js --edges bold
-forgecad render 3d model.forge.js --edges off
-forgecad render 3d bracket.3mf bracket.png
+forgecad render 3d model.forge.js
+forgecad render 3d model.forge.js --camera front --camera side --edges bold
 ```
 
 ### `forgecad render views`
@@ -294,137 +208,77 @@ Render a Forge scene as a wireframe (edges only, no shading).
 Same as `render 3d` but renders only the edge geometry — no shaded surfaces. Useful for construction-style documentation or highlighting structural features without material detail.
 
 ```bash
-forgecad render wireframe examples/products/cup.forge.js
-forgecad render wireframe examples/products/cup.forge.js --camera iso
+forgecad render wireframe model.forge.js
+forgecad render wireframe model.forge.js --camera iso
 ```
 
 ### `forgecad render hq` **\[Pro\]**
 
 High-quality render via Blender Cycles — path-traced, HDRI, material presets.
 
-Exports the scene to Blender and renders with Cycles (path tracer). Requires Blender installed and on PATH.
-
-Choose a `--preset` for the look: `studio` (neutral product shot), `dramatic` (high-contrast), `clay` (matte, no color), `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more. Control quality vs speed with `--samples` (default 256). Use `--view`, `--camera`, `--camera-json`, or `--scene <file>` for still camera control, matching `render 3d`. Use `--transparent` for a transparent background (compositing-ready).
+Exports the scene to Blender and renders with Cycles (path tracer); requires Blender on PATH. Output defaults to `<script-name>-hq.png`.
 
-Output defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.
+`--preset` picks the look (`studio`, `dramatic`, `clay`, `glass`, `metallic`, `toon`, `xray`, `normals`, `silhouette`, and more); `--samples` (default 256) trades quality vs speed; `--transparent` gives a compositing-ready background. Camera control (`--view`, `--camera`, `--camera-json`, `--scene <file>`) matches `render 3d`.
 
 ```bash
-forgecad render hq examples/products/cup.forge.js
-forgecad render hq examples/products/cup.forge.js hero.png --preset dramatic --samples 1024
-forgecad render hq examples/products/cup.forge.js hero.png --view hero
-forgecad render hq examples/products/cup.forge.js hero.png --camera-json camera.json
-forgecad render hq examples/products/cup.forge.js --preset clay --size 2048
-forgecad render hq examples/products/cup.forge.js --transparent --preset glass
+forgecad render hq model.forge.js
+forgecad render hq model.forge.js hero.png --preset dramatic --samples 1024
 ```
 
 ### `forgecad capture gif|mp4` **\[Pro\]**
 
 Animated orbit, section sweep, or named joint playback.
 
-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.
+Renders an animated sequence: `--capture orbit` (default) for a turntable, `--capture animation --animation <name>` for a named joint clip, or `--capture section-sweep` to move a clipping plane through the model. `--cut-plane` keeps a static cross-section visible while animating; the orbit base or fixed camera comes from `--view`, `--camera`, `--camera-json`, or `--scene <file>`.
 
 ```bash
-forgecad capture gif examples/products/cup.forge.js
-forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
-forgecad capture gif model.forge.js out/raw.gif --param "Output=raw-sdf"
-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/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
-forgecad capture mp4 examples/3d-printer.forge.js out/sweep.mp4 --capture section-sweep --sweep-plane YZ --sweep-frames 180
+forgecad capture gif model.forge.js
+forgecad capture gif model.forge.js out/sweep.gif --capture section-sweep --sweep-plane YZ
 ```
 
 ### `forgecad render section`
 
 Render a 2D cross-section of a 3D model (cut by a plane) to SVG or PNG.
 
-Cuts all shapes in the scene with an axis-aligned plane and produces a 2D cross-section drawing. The default plane is XY at Z=0. Use `--plane XZ` or `--plane YZ` for other orientations, and `--offset` to shift the cut position.
-
-Output format is determined by the file extension: `.svg` (default, vector) or `.png` (rasterized at `--size` pixels). Use `--edges=<off|thin|bold>` to control the outline stroke on cut shapes.
-
-Useful for verifying internal geometry, wall thicknesses, and fit checks that aren't visible in 3D renders.
+Cuts all shapes with an axis-aligned plane (default XY at Z=0; `--plane XZ|YZ` reorients, `--offset` shifts the cut) and writes a 2D cross-section drawing. The file extension picks the format: `.svg` (default, vector) or `.png` (rasterized at `--size` pixels); `--edges=<off|thin|bold>` sets the outline stroke. Useful for verifying internal geometry, wall thicknesses, and fits that aren't visible in 3D renders.
 
 ```bash
-forgecad render section examples/furniture/01-table.forge.js
-forgecad render section examples/furniture/01-table.forge.js out/section.svg --plane XZ --offset 10
-forgecad render section examples/furniture/01-table.forge.js out/section.png --size 2048
-forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edges bold
+forgecad render section model.forge.js
+forgecad render section model.forge.js out/section.svg --plane XZ --offset 10
 ```
 
 | Command | Description |
 |---------|-------------|
 | `render sketch` | Render a 2D sketch .forge.js to PNG. |
 
-<details>
-<summary>All render / capture flags</summary>
+### Behavioral notes
+
+- Each render starts a private renderer server by default, so parallel renders do not collide. When sharing one server via `--port`, run renders sequentially — concurrent renders against a shared Vite server race and time out.
+- Direct `.step` / `.stp` inputs auto-select the OCCT backend unless `--backend` is passed.
+- Passing `--camera` several times writes one PNG per camera named `<output>_<camera>.png`; a single camera writes exactly the given output path. If a multi-camera run does not emit the PNGs you expect, rerun one camera at a time with explicit output paths.
+
+### Cross-cutting flags
+
+These flags work across run / render / capture / inspect commands:
 
 | Option | Description |
 |--------|-------------|
 | `--param <Key=Value>` | Override a parameter value (Key=Value). Repeatable. |
-| `-p <Key=Value>` | Shorthand for --param |
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--focus <names>` | Focus: no arg hides mocks; comma-separated names/globs show only those |
 | `--hide <names>` | Hide comma-separated object names/globs |
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
-| `--camera-json <file>` | Exact viewport camera JSON file |
 | `--view <name>` | Named camera view declared by the model with scene({ views }) |
 | `--size <px>` | Image size in pixels |
-| `--scene <json\|file>` | Viewport scene state JSON or JSON file |
-| `--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\|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 |
-| `--json` | Print machine-readable JSON |
 | `--quality <default\|live\|high>` | Mesh quality preset |
-| `--backend <manifold\|occt\|truck>` | Geometry backend (default: manifold) |
-| `--preset <name>` | Material/lighting preset |
-| `--width <px>` | Output width in pixels |
-| `--height <px>` | Output height in pixels |
-| `--samples <n>` | Render samples (more = higher quality, slower) |
-| `--engine <cycles\|eevee>` | Render engine |
-| `--transparent` | Transparent background (RGBA) |
-| `--no-denoise` | Disable denoising |
-| `--hdri <path.hdr>` | Custom HDRI environment map path |
-| `--video` | Render orbit turntable video (MP4) |
-| `--frames <n>` | Video frames per revolution |
-| `--fps <n>` | Video frame rate |
-| `--pitch <deg>` | Camera pitch angle in degrees |
-| `--format <gif\|mp4>` | Output format |
-| `--capture <orbit\|animation\|section-sweep>` | Capture preset |
-| `--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 |
-| `--sweep-normal <x,y,z>` | Custom section-sweep normal |
-| `--sweep-from <min\|max\|offset>` | Section-sweep start offset |
-| `--sweep-to <min\|max\|offset>` | Section-sweep end offset |
-| `--sweep-padding <n>` | Auto sweep range padding in model units |
-| `--sweep-frames <n>` | Moving frames for section-sweep |
-| `--sweep-ease <linear\|smoothstep>` | Section-sweep interpolation |
-| `--section-style <hatched\|clean>` | Section cap style for sweep captures |
-| `--wireframe-pass` | Enable an extra wireframe pass (off by default) |
-| `--no-wireframe-pass` | Disable the extra wireframe pass |
-| `--pixel-ratio <n>` | Render supersampling factor |
-| `--frames-per-turn <n>` | Frames for one orbit turn |
-| `--hold-frames <n>` | Freeze frames before each pass |
-| `--encoder <auto\|ffmpeg\|js>` | GIF encoder strategy |
-| `--crf <n>` | ffmpeg/libx264 quality |
-| `--ffmpeg-path <path>` | ffmpeg executable path |
-| `--list` | Print available animations and cut planes |
+| `--backend <manifold\|occt\|truck>` | Geometry backend (default: manifold; STEP inputs default to OCCT) |
+| `--json` | Print machine-readable JSON |
 
-</details>
+Every command has more — Blender-only `render hq` flags (`--preset`, `--samples`, `--engine`, `--hdri`, `--transparent`, `--video`) and capture-only flags (`--capture`, `--animation`, `--cut-plane`, `--sweep-*`, `--fps`) among them. Run `forgecad <command> --help` for the full list.
 
 ## Export
 
-Export to every format you need. Export actions are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work, and Enterprise covers backend or embedded application usage.
+Export to every format you need.
 
 | Command | Format | Use case |
 |---------|--------|----------|
@@ -440,13 +294,12 @@ Export to every format you need. Export actions are free to run for personal non
 | `export urdf` **\[Production\]** | URDF package | ROS / PyBullet / MuJoCo |
 | `export report` **\[Production\]** | PDF report | Multi-view report with BOM and dimensions |
 | `export cutting-layout` **\[Production\]** | PDF/DXF | Sheet cutting layout with cut sequence |
-| `link` | URL | Generate a ForgeCAD share link from a GitHub Gist URL or ID and copy it to clipboard. |
+| `link` | URL | Share link from a GitHub Gist URL or ID (copied to clipboard) |
 
 ```bash
 # Sheet material
-forgecad cut-list examples/api/sheet-stock-cut-list.forge.js
-forgecad export cutting-layout examples/api/sheet-stock-cut-list.forge.js --sheet-width 420 --sheet-height 594 --kerf 3
-forgecad export cutting-layout examples/api/sheet-stock-cut-list.forge.js out/layout.dxf
+forgecad cut-list shelf.forge.js
+forgecad export cutting-layout shelf.forge.js --sheet-width 420 --sheet-height 594 --kerf 3
 
 # 3D printing
 forgecad check print bracket.forge.js
@@ -468,6 +321,7 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 
 | Option | Description |
 |--------|-------------|
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--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 |
@@ -488,25 +342,7 @@ A project is a local folder linked to the hosted app by `forgecad.json`. Use `fo
 
 Keep the project root small and intentional. Do not run the editor from `~`, downloads, desktop, or a huge source tree. ForgeCAD scans project files such as `.forge.js`, `.js`, `.svg`, and `.dxf`; broad roots make local workflows and AI-agent context slow and confusing.
 
-### Get started
-
-```bash
-forgecad login
-mkdir spool-adapter
-cd spool-adapter
-forgecad project init "Spool Adapter"
-forgecad new adapter --template part
-forgecad studio .
-
-# or clone an existing hosted project:
-forgecad project clone start-here
-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.
-
-`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.
+First-time setup (login, init, studio) is the [Quick Start](#quick-start) sequence above. `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.
 
 ### Sync
 
@@ -601,13 +437,9 @@ Shares are live references — always the current version, not a snapshot.
 ForgeCAD files are plain JavaScript. AI coding agents should work inside an initialized project folder, write and iterate on local files, and use the CLI for evidence. See [AI Usage](AI/usage.md) for approved models, project-first setup, installable skills, quality prompts, and completion criteria.
 
 ```bash
-# Install the full public ForgeCAD skill library
+# Install the full public ForgeCAD skill library (--target claude|opencode for a specific agent)
 forgecad skill install
 
-# Target a specific local agent skill directory when needed
-forgecad skill install --target claude
-forgecad skill install --target opencode
-
 # Or export a single context file for chat UIs (Claude.ai, ChatGPT, ...)
 forgecad skill one-file ~/Desktop/forgecad-context.md
 
@@ -630,7 +462,6 @@ Runs both inputs headlessly, samples their triangle surfaces, feature edges, bou
 ```bash
 forgecad compare 3d reference.stl reconstruction.forge.js
 forgecad compare 3d reference.step reconstruction.forge.js --json --samples 3000
-forgecad compare 3d source.3mf candidate.3mf --align center --tolerance-mm 0.5 --fail-under 90
 ```
 
 ### `forgecad check print`
@@ -642,24 +473,19 @@ Runs a Forge script with the headless kernel and emits a slicer-adjacent printab
 Checks include script `verify.*` results, exact positive-volume object collisions, physical component count, mesh topology, sampled wall thickness, unsupported overhang budget, and bed-contact area. Use `--json` for automation and `--output` to save the full report while keeping the readable terminal summary.
 
 ```bash
-forgecad check print examples/api/attachTo-basics.forge.js
-forgecad check print examples/api/verification-demo.forge.js --json
-forgecad check print model.forge.js --min-wall 1.2 --warn-wall 2
-forgecad check print model.forge.js --expect-components 1 -p "Wall Thickness=3"
+forgecad check print model.forge.js
+forgecad check print model.forge.js --json
 ```
 
 ### `forgecad inspect mechanical-integrity`
 
 Inspect generated ForgeCAD models for mechanical integrity failures.
 
-Scans a Forge script or a folder of generated projects and runs a mechanical integrity inspection. The inspection flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, optional positive-volume object collisions, and excessive physical component counts when requested. Markdown details include suggested repair patterns such as connector-authored mates, bolted service covers, pinned levers, captured slides, hinges, clevis joints, retained shafts, and seated bearings. When `--collisions` is enabled, the Markdown details list the largest overlapping object pairs by volume so agents can repair the highest-risk interfaces first. Exact collision checks use a default 40-pair bbox-overlap budget and 30s exact-check time budget; exhausting either budget fails the file instead of silently passing a partial check. Script-authored `console.warn()` diagnostics are reported as warnings; use `verify.*` checks or `console.error()` for gate-failing contracts. Script-side joint sweeps use a separate validation step budget so the gate can keep default geometry quality while failing truncated validation explicitly.
+Scans a Forge script or a folder of generated projects and flags timeouts, runtime errors, missing `verify.*` checks, missing executed mechanical-interface checks, fragmented named groups, uncontracted manual assemblies, and (when requested) positive-volume collisions and excessive physical component counts. Details suggest concrete repair patterns. With `--collisions`, the largest overlapping object pairs are listed by volume so the highest-risk interfaces get repaired first; exhausting the exact-check pair or time budget fails the file instead of silently passing a partial check, and truncated script-side joint-sweep validation fails explicitly. Script `console.warn()` diagnostics are reported as warnings; use `verify.*` checks or `console.error()` for gate-failing contracts.
 
 ```bash
 forgecad inspect mechanical-integrity path/to/generated-models
-forgecad inspect mechanical-integrity path/to/model/main.forge.js --min-verifications 2
-forgecad inspect mechanical-integrity path/to/model/main.forge.js --collisions
-forgecad inspect mechanical-integrity path/to/generated-models --collisions --collision-pair-limit 250
-forgecad inspect mechanical-integrity path/to/generated-models --json --timeout-ms 40000 --jobs 4
+forgecad inspect mechanical-integrity model.forge.js --min-verifications 2
 ```
 
 <details>