forgecad 0.6.3 → 0.8.0

package/dist/docs-raw/CLI.md

@@ -1,865 +1,488 @@
 ---
 skill-group: cli
 skill-order: 1
-skill-tiers: [standard]
 ---
 
 # ForgeCAD CLI
 
-## Architecture
+Run, export, render, and publish `.forge.js` models from your terminal. Everything stays in code.
 
-All CLI tools share the **same forge engine** as the browser UI. There is one source of truth for geometry logic — no code duplication. See [CODING.md → Project Structure](CODING.md#project-structure) for the full source tree.
-
-**Browser** imports via `src/forge/index.ts` → re-exports from `headless.ts`.
-**CLI tools** import directly from `src/forge/headless.ts`.
-
-The key function is `runScript(code, fileName, allFiles)` — it wraps user code in a `Function()` sandbox with the entire forge API injected, and transpiles project files so standard JS `import` / `export` / `require(...)` work for shared utility modules. CLI scripts just call `init()` + `runScript()` and work with the results.
-
-## When to use what
-
-ForgeCAD has two overlapping interfaces. Use the right one for each context.
-
-| Context | Use | Avoid |
-|---------|-----|-------|
-| **Using ForgeCAD as a tool** | `forgecad *` commands | `npm run *` |
-| **Developing ForgeCAD itself** | `npm run dev` (live reload), `npm run build` (prod) | — |
-| **CI / publishing** | `npm run build && npm run test` | forgecad CLI (not installed in CI) |
-| **AI agents in this repo** | `forgecad *` commands only | `npm run build`, `npm run build:cli` |
-
-The CLI is always available after `npm install` — no explicit build step needed.
-
-### Dev server vs production server
-
-| Command | What it does | Requires |
-|---------|-------------|---------|
-| `forgecad dev [path]` | Vite dev server, live reload | nothing beyond `npm install` |
-| `forgecad studio [path]` | Fast static server for the production build | `dist/` built via `npm run build` |
-| `npm run dev` | Same as `forgecad dev` — standard JS project entry point | nothing |
-
-Use `forgecad dev` during active development of forge scripts. Use `forgecad studio` to verify the production build or serve it to others.
-
-## Install
+## Quick Start
 
 ```bash
+# 1. Install
 npm install -g forgecad
-```
-
-For developers working on ForgeCAD itself:
-
-```bash
-npm install
-npm link
-```
-
-The npm package ships a minified JS bundle (`cli.js`) — no source maps. A compiled native binary build script exists (`npm run build:binary`) for future Homebrew distribution but is not the primary channel.
-
-## Licensing
-
-Some commands require a ForgeCAD Pro license. Free-tier commands work without any key.
-
-```bash
-forgecad license                    # Show current license status
-forgecad license activate <key>     # Activate a license key
-forgecad license deactivate         # Remove license from this machine
-```
-
-| Tier | What's included |
-|------|----------------|
-| **Free** | dev, studio, run, render, export stl/3mf/svg, all checks, debug |
-| **Pro** | export step/brep, render-hq, capture gif/mp4, gcode, report, cutting-layout, sdf, urdf, sketch-pdf |
-
-Pro commands show a `[Pro]` badge in `forgecad help` and display a clear upgrade message when invoked without a license.
-
-See [cli-monetization.md](project/cli-monetization.md) for the full monetization strategy.
-
-### Shell Autocomplete
-
-ForgeCAD now ships shell completion scripts in the usual modern-tool style:
-
-```bash
-forgecad completion bash
-forgecad completion zsh
-forgecad completion fish
-```
-
-Quick install:
-
-```bash
-# bash
-echo 'source <(forgecad completion bash)' >> ~/.bashrc
-
-# zsh
-mkdir -p ~/.zsh/completions
-forgecad completion zsh > ~/.zsh/completions/_forgecad
-echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
-echo 'autoload -Uz compinit && compinit' >> ~/.zshrc
-
-# fish
-mkdir -p ~/.config/fish/completions
-forgecad completion fish > ~/.config/fish/completions/forgecad.fish
-```
-
-The completions are contextual:
-
-- nested subcommands such as `forgecad notebook view` and `forgecad export step`
-- command-specific flags and common enum values
-- ForgeCAD file suggestions where a command expects `.forge.js` or `.forge-notebook.json`
-
-## Available Commands
-
-### Authentication & Account
-
-```bash
-forgecad login                          # Interactive email/password login
-forgecad login --server http://localhost:5174  # Login to local dev server
-forgecad logout                         # Clear stored credentials
-forgecad whoami                         # Show user, server, and license status
-```
-
-Credentials are stored in `~/.forgecad/auth.json`.
-
-### Project Management
-
-```bash
-# Create and sync
-forgecad project init "My Project"      # Create on server + link current directory
-forgecad project init "My Project" --slug my-project --visibility public
-forgecad project clone my-project       # Download into ./my-project/
-forgecad project push [--force]         # Upload local changes
-forgecad project pull [--force]         # Download remote changes
-forgecad project status                 # Show local vs remote diff
-
-# Inspect and modify
-forgecad project list                   # List all your projects
-forgecad project info                   # Show current project details (name, visibility, files, URL)
-forgecad project rename "New Name"      # Rename the project
-forgecad project set-visibility public  # Change visibility (private|shared|public)
-forgecad project delete [--force]       # Permanently delete project and all files
-forgecad project open                   # Open in browser
-```
-
-Projects are stored on forgecad.io. Local projects are linked to their remote counterpart via `forgecad.json`.
-
-### File Management (Remote)
-
-Operate directly on remote project files without the push/pull cycle:
-
-```bash
-forgecad file list [path]               # List remote files (optional path prefix filter)
-forgecad file read <path>               # Print file contents to stdout
-forgecad file save <path>               # Upload local file to remote (same relative path)
-forgecad file save <path> --content "code here"  # Save inline content
-cat model.forge.js | forgecad file save model.forge.js --stdin  # Pipe content from stdin
-forgecad file delete <path> [--force]   # Delete remote file
-forgecad file rename <old> <new>        # Rename or move a remote file
-forgecad file mkdir <path>              # Create a remote directory
-forgecad file copy <source-slug> <path> [--dest <dest-path>]  # Copy from another project
-```
-
-These commands require the current directory to be an initialized ForgeCAD project (has `forgecad.json`).
-
-### Member Management
-
-```bash
-forgecad project members                          # List project members
-forgecad project add-member alice@example.com     # Add as editor (default)
-forgecad project add-member bob@example.com --role viewer
-forgecad project remove-member alice@example.com
-forgecad project set-role bob@example.com editor
-```
-
-Roles: **owner** (full control, manage members), **editor** (read/write files), **viewer** (read-only).
 
-### Publishing & Sharing
+# 2. Create a model
+forgecad new cup
 
-```bash
-forgecad publish model.forge.js --title "My Model"  # Publish model, get shareable URL
-forgecad publish model.forge.js --no-sync            # Publish without auto-pushing project
-forgecad shares list                                 # List all published models with URLs
-forgecad shares delete <share-id> [--force]          # Unpublish a shared model
-forgecad link <gist-url-or-id>                       # Generate share link from GitHub Gist
-```
+# 3. Run it
+forgecad run cup.forge.js
 
-Published models are viewable at `forgecad.io/m/<shareId>`. Shares are **live references** to project files — they always reflect the current version, not a frozen snapshot. Publishing requires being inside a project directory. The project is auto-synced first (unless `--no-sync`).
-
-### New File from Template
-
-```bash
-forgecad new mypart                     # Part template (default)
-forgecad new bracket --template sketch  # Constrained sketch template
-forgecad new robot --template assembly  # Multi-part assembly template
-```
-
-### Studio & Dev Server
-
-```bash
-# Development — Vite dev server, live reload, no build needed
+# 4. Open the editor (live reload)
 forgecad dev
-forgecad dev ~/cad/gearbox
-forgecad dev --blank --port 4173
-
-# Production — static server, requires dist/ (npm run build)
-forgecad studio
-forgecad studio ~/cad/gearbox
-forgecad studio --blank --port 4173
 
-# Web / embeddable mode — always dev server, no filesystem
-forgecad web
-forgecad web --open
+# 5. Export
+forgecad export stl cup.forge.js
 ```
 
-Both `forgecad dev` and `forgecad studio` accept the same options:
-- `--blank` — open without any project folder
-- `--port <n>` — bind to a specific port (default: 5173)
-- `--host [host]` — expose on the network
-- `--open` — open a browser tab automatically
-- `--strict-port` — fail if the port is already in use
+## Editor
 
-`forgecad open` is an alias for `forgecad studio`.
+ForgeCAD includes a local editor with live reload. Edit a `.forge.js` file, save, and the 3D view updates instantly — parameters become interactive sliders.
 
-### Notebook Cells (server-backed)
+| Command | Description |
+|---------|-------------|
+| `dev` | Start the Vite dev server with live reload. No build step required — the preferred way to run ForgeCAD during active development. |
+| `studio` | Serve the production build of the studio (requires dist/ — run `npm run build` first). |
+| `web` | Start a local dev server in web/playground mode (no filesystem, localStorage only). |
+| `open` | Alias for `forgecad studio`. |
 
-Forge notebooks live in `.forge-notebook.json` files and behave like lightweight Jupyter notebooks for ForgeCAD code cells.
+<details>
+<summary>Common flags for dev / studio</summary>
 
-The browser and CLI both use the Vite server for notebook execution. The CLI does not run Forge locally for notebook cells; it auto-starts or reuses the Forge server, sends the cell code, then prints the returned output summary.
+| Option | Description |
+|--------|-------------|
+| `--blank` | Start without a project folder |
+| `--port <n>` | Bind to a specific port |
+| `--host [host]` | Expose the server on the network |
+| `--open` | Open a browser window automatically |
+| `--strict-port` | Fail instead of selecting another port |
 
-Append a new code cell and run it immediately in one command:
+</details>
 
-```bash
-forgecad notebook examples/demo.forge-notebook.json --code "show(box(40, 20, 10));"
-```
+## Run & Render
 
-If the target notebook file does not exist yet, append mode auto-creates it first with the default ForgeCAD notebook structure, then adds the new cell.
+Execute scripts and produce images headless — no browser window. Renders use Chrome under the hood.
 
-Or pipe a larger cell in through stdin:
+### `forgecad run`
 
-```bash
-cat /tmp/cell.js | forgecad notebook examples/demo.forge-notebook.json
-```
+Execute a Forge script and print full geometry diagnostics — object summary, collision detection, spatial analysis, verification results, and solver profiling.
 
-Re-run the last preview cell, or a specific cell id:
+The primary validation command. Runs your script with the real geometry kernel (no browser needed) and prints a comprehensive report:
 
-```bash
-forgecad notebook examples/demo.forge-notebook.json
-forgecad notebook run examples/demo.forge-notebook.json <cell-id>
-```
+**Object summary** — lists every named shape with its volume, bounding box, and body count. For constrained sketches, shows solver status (FULLY / UNDER / OVER constrained), DOF, and error residuals. Problematic constraints (conflicting, redundant, or high-residual) are flagged individually.
 
-View the notebook in the terminal without dumping raw JSON:
+**Construction history** — shows the build sequence for each shape (primitives, operations, modifications) so you can verify the modeling intent.
 
-```bash
-forgecad notebook view examples/demo.forge-notebook.json
-forgecad notebook view examples/demo.forge-notebook.json preview
-forgecad notebook view examples/demo.forge-notebook.json 2
-```
-
-`view` is local-only. It parses the notebook JSON and renders notebook metadata, numbered source lines, and stored outputs for each cell. The optional selector accepts a 1-based cell number, an exact cell id, or `preview`.
+**Feature summary** — tallies geometry features across all objects (e.g. `3 extrude, 2 fillet, 1 chamfer`).
 
-`run`/`view` expect the notebook file to already exist. Auto-creation only applies to append flows (`--code`, `--file`, stdin, or the explicit `append` subcommand).
+**Verification results** — runs any `verify.*` checks in the script and reports pass/fail with expected vs actual values.
 
-Export a notebook into a plain `.forge.js` script:
+**Automatic collision detection** — performs an all-pairs collision check on every named shape. For each pair whose bounding boxes overlap, computes the boolean intersection and reports overlap above 0.1 mm³:
 
-```bash
-forgecad notebook export examples/demo.forge-notebook.json
-forgecad notebook export examples/demo.forge-notebook.json out/demo-from-notebook.forge.js
 ```
-
-If you already have a Forge server running, point the CLI at it:
-
-```bash
-forgecad notebook examples/demo.forge-notebook.json --server http://localhost:5173 --code "show(box(40, 20, 10));"
+⚠ COLLISION: bolt ∩ base (shared vol: 42.3mm³)
 ```
 
-Notebook paths are resolved from the shell working directory before the CLI calls the server, so the server's opened project root does not add an extra path prefix.
-
-Notebook cell behavior:
+Intra-group pairs (same assembly group) and mock-to-mock pairs are skipped. If a part passes through a boolean-subtracted hole, no collision is reported — the material is gone.
 
-- Cells share state top-to-bottom
-- `show(value)` pins the geometry that should stay visible in the viewport
-- A trailing expression is also treated as the cell value
-- Cell outputs are written back into the notebook JSON, similar to Jupyter
+**Spatial analysis** — reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). When no issues are found: `(no collisions, all objects well-separated)`.
 
-For the `forgecad` entrypoints below, passing a `.forge-notebook.json` uses that notebook's preview cell. That means you can inspect with `view`, validate with `run`, and render or capture the current preview without exporting first.
+**Parameters** — lists all declared parameters with their current values. Overridden values are marked with `*`.
 
-### Script Validation
+**Solver profiling** — when constraint solving occurs, shows timing breakdown (clone, solve, redundancy detection, surface building) and solver internals.
 
 ```bash
 forgecad run examples/cup.forge.js
-forgecad run examples/api/notebook-iteration.forge-notebook.json
+forgecad run examples/cup.forge.js --focus
+forgecad run examples/cup.forge.js --focus bracket,hinge
+forgecad run examples/cup.forge.js --hide "wall,bolt"
+forgecad run examples/cup.forge.js --backend occt
 forgecad run examples/cup.forge.js --debug-imports
-forgecad run examples/cup.forge.js --param "Wall Thickness=3"
-forgecad run examples/cup.forge.js --param "Show Lid=0"
-forgecad run examples/cup.forge.js --param "Pan Style=wok"
+forgecad run examples/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
 ```
 
-Runs a `.forge.js` or notebook preview cell in the real runtime and prints object stats, diagnostics, and execution time.
-
-`--param "Key=Value"` overrides script parameters for that run. It supports:
-
-- numeric `param()` values such as `"Wall Thickness=3"`
-- boolean `boolParam()` values using `1` or `0`
-- string `choiceParam()` values using the displayed label, such as `"Pan Style=wok"`
-
-`--debug-imports` adds an import trace (source file, target file, overrides, return type, success/error phase), useful when debugging `require()` import behavior.
-
-`--solver-debug-out <dir>` enables the Rust planner's constructive transcript and SVG snapshots for every solved sketch in that run, then writes a reusable artifact bundle to disk:
-
-- `README.md` summary at the output root
-- one subdirectory per sketch
-- `constructive-transcript.md` with the step-by-step planner story
-- `svg/*.svg` snapshots keyed to transcript steps
-
-### SVG Export (no browser needed)
-
-```bash
-forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js [output.svg]
-```
+### `forgecad render`
 
-Runs a sketch `.forge.js` script in Node.js using the real forge engine and outputs SVG. No browser, no Puppeteer — pure Node.
+Render a Forge scene. Use a subcommand — `3d`, `section`, `wireframe`, `sketch`, or `hq`.
 
-**How it works:** Initializes the Manifold WASM kernel, runs the script through `runScript()`, extracts the Sketch result, converts polygons to SVG paths.
+`forgecad render` is a group of rendering subcommands. Pick one based on what you want:
 
-### STEP / BREP Export (exact subset, Python + CadQuery)
+- `render 3d` — standard viewport PNG, the usual way to visually verify geometry
+- `render wireframe` — edges only, no shading
+- `render section` — 2D cross-section cut by a plane (SVG or PNG)
+- `render sketch` — 2D sketch script to PNG
+- `render hq` — path-traced via Blender Cycles, for documentation and marketing shots
 
 ```bash
-forgecad export step examples/api/brep-exportable.forge.js
-forgecad export brep examples/api/brep-exportable.forge.js
-
-# Optional overrides:
-forgecad export step examples/api/brep-exportable.forge.js --output out/demo.step
-forgecad export step examples/api/brep-exportable.forge.js --python 3.11
-forgecad export step examples/api/brep-exportable.forge.js --uv /custom/path/to/uv
-forgecad export step examples/chess-set.forge.js --allow-faceted
+forgecad render 3d examples/cup.forge.js
+forgecad render wireframe examples/cup.forge.js
+forgecad render section examples/furniture/01-table.forge.js --plane XZ
+forgecad render hq examples/cup.forge.js --preset dramatic
 ```
 
-This exporter is `uv`-first. `cli/forge-brep-export.py` carries inline dependency metadata, so `uv run` provisions CadQuery automatically for the exporter environment.
-
-By default this exporter is exact-subset only. It does **not** silently convert arbitrary triangle meshes back into fake BREP. Instead, Forge lowers compile-covered geometry into the `cadquery-occt` compiler target and exports that exact subset through CadQuery/OpenCascade.
-
-If you pass `--allow-faceted`, unsupported closed mesh solids are exported as explicit faceted OCCT solids. This keeps mesh-heavy designs exportable to STEP/BREP, but that fallback is tessellation-driven rather than exact replay.
-
-The maintained feature matrix lives in [`docs/permanent/API/output/brep-export.md`](API/output/brep-export.md).
+### `forgecad render 3d`
 
-If any returned solid object falls outside the exact subset, the CLI fails with a reason instead of silently exporting degraded geometry. When a scene mixes solids and 2D sketches, the exact solids export and the sketch-only objects are skipped with a warning.
+Render a Forge scene to PNG using the real viewport renderer.
 
-With `--allow-faceted`, mesh-solid blockers that still lack an exact replay plan are exported as faceted solids instead of failing. The CLI prints which objects used the fallback.
+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.
 
-For coverage runs across many examples, use the `uv` matrix scripts:
+Use `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--camera` flag accepts named views (`front`, `top`, `iso`) or `azimuth:elevation` angles — pass it multiple times to render several viewpoints in one run.
 
-```bash
-uv run scripts/brep/matrix.py --format step examples
-uv run scripts/brep/matrix.py --format brep examples
-uv run scripts/brep/rerun_failures.py tmp/brep-matrix-step-20260306T120000Z.json
-```
-
-These scripts use the repo-local `.venv-brep/.venv/bin/python` by default, run exports through a bounded parallel worker pool, and write JSON reports under `tmp/`.
+Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.
 
-### G-code Toolpath Export
+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.
 
 ```bash
-forgecad export gcode examples/gcode/parametric-vase.forge.js
-forgecad export gcode examples/gcode/parametric-vase.forge.js --output out/vase.gcode
+forgecad render 3d examples/cup.forge.js
+forgecad render 3d examples/cup.forge.js --focus
+forgecad render 3d examples/cup.forge.js --focus bracket
+forgecad render 3d examples/cup.forge.js --hide "wall,bolt"
+forgecad render 3d model.forge.js --camera 45:30
+forgecad render 3d model.forge.js --camera front --camera side
+forgecad render 3d model.forge.js --edges bold
+forgecad render 3d model.forge.js --edges off
 ```
 
-Exports a G-code toolpath script directly to `.gcode` for FDM 3D printing. The script must return a `GCodeBuilder` instance (created via the `gcode()` factory function).
-
-This is a **toolpath scripting API**, not a slicer. You define print movements directly in code — enabling parametric vases, mathematical surfaces, non-planar paths, and other geometries that conventional slicers cannot produce.
-
-**How it works:** Initializes the forge kernel, runs the script, extracts the `GCodeBuilder` result, and writes the generated G-code text to disk. Prints segment count, estimated time, filament usage, and bounding box.
+### `forgecad render wireframe`
 
-**Options:**
-- `--output <path>` / `-o <path>` — Output file path (default: replaces `.forge.js` with `.gcode`)
+Render a Forge scene as a wireframe (edges only, no shading).
 
-**Demo scripts:**
-- `examples/gcode/parametric-vase.forge.js` — Sine-wave modulated continuous spiral vase
-- `examples/gcode/spiral-tower.forge.js` — Twisted hexagonal polygon tower
-- `examples/gcode/math-surface.forge.js` — Non-planar bowl with wave rim
-- `examples/gcode/lissajous-vase.forge.js` — Lissajous curve vase with morphing profile
-
-Preview these scripts in ForgeCAD's interactive viewport. The current `forgecad render` CLI expects shape outputs and does not render `GCodeBuilder` scenes yet.
-
-See [`docs/permanent/API/output/gcode.md`](API/output/gcode.md) for the dedicated G-code mode guide and full `GCodeBuilder` API reference.
-
-### SDF Robot Export (Gazebo package)
+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 export sdf examples/api/sdf-rover-demo.forge.js
-
-# Optional output directory:
-forgecad export sdf examples/api/sdf-rover-demo.forge.js --output out/forge_scout
+forgecad render wireframe examples/cup.forge.js
+forgecad render wireframe examples/cup.forge.js --camera iso
 ```
 
-This exporter writes a Gazebo-friendly package workspace:
-
-- `models/<model-name>/model.sdf`
-- `models/<model-name>/model.config`
-- `models/<model-name>/meshes/*.stl`
-- `worlds/<world-name>.sdf` when the script requests a demo world
-- `manifest.json` with topic names, link/joint mappings, and exporter warnings
+### `forgecad render hq` **\[Pro\]**
 
-The script must call `robotExport({...})` with an `assembly(...)` graph. The exporter uses the declared parts + joints directly; it does **not** try to infer a robot from flattened scene meshes.
+High-quality render via Blender Cycles — path-traced, HDRI, material presets.
 
-When `world.generateDemoWorld` and `world.keyboardTeleop.enabled` are on, the exported world includes both:
+Exports the scene to Blender and renders with Cycles (path tracer). Requires Blender installed and on PATH.
 
-- Gazebo's GUI `KeyPublisher` plugin
-- server-side `TriggeredPublisher` bindings that map arrow keys to the diff-drive `cmd_vel` topic
+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 `--transparent` for a transparent background (compositing-ready).
 
-Recommended launch flow:
+Output defaults to `<script-name>-hq.png`. Great for documentation, marketing renders, and social media.
 
 ```bash
-export GZ_SIM_RESOURCE_PATH="$PWD/out/forge_scout/models${GZ_SIM_RESOURCE_PATH:+:$GZ_SIM_RESOURCE_PATH}"
-
-# Terminal 1: server
-gz sim -s -r out/forge_scout/worlds/forge_scout_trial.sdf
-
-# Terminal 2: GUI client using the same world layout
-gz sim -g out/forge_scout/worlds/forge_scout_trial.sdf
+forgecad render hq examples/cup.forge.js
+forgecad render hq examples/cup.forge.js hero.png --preset dramatic --samples 1024
+forgecad render hq examples/cup.forge.js --preset clay --size 2048
+forgecad render hq examples/cup.forge.js --transparent --preset glass
 ```
 
-Notes:
-
-- On macOS, use the split `-s` / `-g` flow above. `gz sim <world.sdf>` is not supported there.
-- Click the 3D view so it has keyboard focus, then use `W` / `X` for forward / reverse, `A` / `D` to rotate, `Q` / `E` / `Z` / `C` for diagonals, and `S` or `Space` to stop.
-- For older exports created before the GUI plugin was added, load `Key Publisher` manually from the Gazebo GUI plugins menu.
-
-Current behavior:
-
-- Per-link geometry is exported as STL mesh assets
-- Collision geometry reuses the same mesh unless `collision: 'none'` is set on a link
-- Link mass comes from `massKg`, else `densityKgM3 * volume`, else a default density
-- Inertia is an approximate box fit based on link bounds
-- Coupled joints are currently rejected
-- Parts without geometry are currently rejected
-
-### PNG Render (requires Chrome)
-
-```bash
-forgecad render examples/cup.forge.js [output.png]
-forgecad render examples/api/notebook-iteration.forge-notebook.json [output.png]
-forgecad render examples/cup.forge.js out/scene.png --scene '{"camera":{"projectionMode":"perspective","position":[200,-160,120],"target":[0,0,20],"up":[0,0,1]},"objects":{"obj-2":{"visible":false},"obj-3":{"opacity":0.35}}}'
-```
-
-Renders 3D shapes to PNG images from multiple camera angles. Uses Puppeteer to launch headless Chrome with WebGL for Three.js rendering.
-
-When the input is a notebook, `forgecad render` renders the notebook's preview cell.
-
-**How it works:**
-1. `cli/forge-render.mjs` — Node launcher script. Auto-starts Vite dev server if not running, launches Puppeteer.
-2. `cli/render.html` + `cli/render.ts` — Loaded in the browser by Puppeteer. Imports from `src/forge/headless.ts`, runs the script, builds a Three.js scene, renders from multiple angles.
-3. Screenshots are captured as base64 PNG and saved to disk.
-
-**Environment variables:**
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `FORGE_ANGLES` | `front,side,top,iso` | Camera angles to render |
-| `FORGE_SIZE` | `1024` | Image size in pixels |
-| `FORGE_PORT` | `5173` | Vite dev server port |
-| `CHROME_PATH` | Auto-detected | Chrome/Chromium executable path |
+### `forgecad capture gif|mp4` **\[Pro\]**
 
-**CLI options:**
-- `--angles <front,side,top,iso>` — standard angles to render
-- `--size <px>` — output size override
-- `--port <n>` — Vite port override
-- `--camera <spec>` — exact camera pose, e.g. `proj=perspective;pos=120,80,120;target=0,0,0;up=0,0,1`
-- `--scene <json>` — full scene state copied from the viewport, including camera plus object visibility/opacity/color overrides
-- `--background <color>` — background override
-- `--chrome-path <path>` — Chrome executable path override
+Animated orbit or joint playback.
 
-**Camera angles:** `front` (−Y), `back` (+Y), `side` (+X), `top` (+Z), `iso` (diagonal)
-
-### Animated Capture (GIF or MP4, requires Chrome)
+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, or `--capture animation --animation <name>` to play a named joints clip. Supports `--cut-plane` to animate with a cross-section visible.
 
 ```bash
-forgecad capture gif examples/cup.forge.js [output.gif]
-forgecad capture mp4 examples/cup.forge.js [output.mp4]
-forgecad capture gif examples/api/notebook-assembly-debug.forge-notebook.json --list
-forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
+forgecad capture gif examples/cup.forge.js
 forgecad capture gif examples/3d-printer.forge.js out/section.gif --cut-plane "Front Section"
+forgecad capture mp4 examples/cup.forge.js
+forgecad capture mp4 examples/api/runtime-joints-view.forge.js out/step.mp4 --capture animation --animation Step
 ```
 
-Creates high-quality animated captures from the real Forge viewport renderer:
-- Orbit captures with optional wireframe pass
-- Fixed-camera animation captures for `jointsView()` clips
-- Named cut-plane captures
-- Exact camera replay via `--camera`
-- Full viewport scene replay via `--scene`
-
-When the input is a notebook, `forgecad capture gif` / `forgecad capture mp4` capture the notebook's preview cell.
-
-**How it works:**
-1. Auto-starts (or reuses) the Vite dev server.
-2. Loads `cli/render.html` in headless Chrome.
-3. Runs the script once, then captures frames from the same scene while applying the selected animation, cut planes, and camera pose.
-4. Encodes with `ffmpeg` when available:
-   - GIF: palettegen/paletteuse for much better colors
-   - MP4: H.264 via `libx264`
-5. Falls back to the pure-JS GIF encoder only when `ffmpeg` is unavailable.
-
-**Options:**
-- `--format <gif|mp4>` — output format
-- `--capture <orbit|animation>` — moving orbit camera or fixed animation camera
-- `--animation <name>` — select one `jointsView()` clip
-- `--animation-loops <n>` — repeat the chosen clip
-- `--cut-plane <name>` — enable a named cut plane (repeatable)
-- `--camera <spec>` — exact camera pose, e.g. `proj=perspective;pos=120,80,120;target=0,0,0;up=0,0,1`
-- `--scene <json>` — full scene state copied from the viewport, including camera plus object visibility/opacity/color overrides
-- `--render-mode <solid|wireframe>` — primary render mode
-- `--wireframe-pass` / `--no-wireframe-pass` — enable/disable the extra wireframe pass (off by default)
-- `--size <px>` — output frame resolution (default `960`)
-- `--pixel-ratio <n>` — render supersampling factor (default `2`)
-- `--fps <n>` — capture frame rate (default `24`)
-- `--frames-per-turn <n>` — frames per full orbit pass (default `100`)
-- `--hold-frames <n>` — freeze frames before each pass (default `6`)
-- `--pitch <deg>` — orbit elevation override
-- `--background <color>` — background color (default `#252526`)
-- `--quality <default|live|high>` — Forge geometry quality preset for export (default `high`)
-- `--encoder <auto|ffmpeg|js>` — GIF encoder strategy
-- `--crf <n>` — MP4 quality for `libx264` (default `18`)
-- `--list` — print the script's available animation clips and cut planes
-- `--port <n>` — Vite port (default `5173`)
-- `--chrome-path <path>` — Chrome executable path override
-- `--ffmpeg-path <path>` — ffmpeg executable path override
-
-**Environment variables:**
-- `FORGE_CAPTURE_SIZE`
-- `FORGE_CAPTURE_PIXEL_RATIO`
-- `FORGE_CAPTURE_FPS`
-- `FORGE_CAPTURE_FRAMES_PER_TURN`
-- `FORGE_CAPTURE_HOLD_FRAMES`
-- `FORGE_CAPTURE_PITCH_DEG`
-- `FORGE_CAPTURE_BACKGROUND`
-- `FORGE_CAPTURE_QUALITY`
-- `FORGE_CAPTURE_ANIMATION_LOOPS`
-- `FORGE_CAPTURE_CRF`
-- `FFMPEG_PATH`
-- Legacy `FORGE_GIF_*` vars are still honored as fallbacks
-- `FORGE_PORT`
-- `CHROME_PATH`
-
-**UI scene handoff:**
-- The View Panel exposes a `Camera` section.
-- Use `Copy CLI --scene` to grab the current viewport framing plus per-object scene overrides and paste it directly into `render`, `capture gif`, or `capture mp4`.
-
-### PDF Report (2D drawing pack)
-
-```bash
-forgecad export report examples/cup.forge.js [output.pdf]
-forgecad export report examples/cup.forge.js [output.pdf] --dim-angle-tol 18
-```
-
-Generates a searchable-text PDF report with multiple projected drawing views:
-- Bill of Materials page (auto-summed from script `bom()` entries)
-- Combined model page (front/right/top/isometric)
-- Disassembled component pages (same view set per unique component geometry; repeated identical items collapse into one page)
-- Auto-generated detail continuation pages for elongated/high-detail views (separate pages, not overlayed)
-- `dim()` annotations included per view only when their axis aligns with that view's projection plane axes
-
-BOM aggregation rules:
-- Each `bom(quantity, description, { unit })` call contributes one raw entry
-- Report export groups by `key` (if provided) else by normalized `description + unit`
-- Quantities are summed per group and rendered as line items in the BOM table
+### `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.
+
+```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
+```
+
+| Command | Description |
+|---------|-------------|
+| `render sketch` | Render a 2D sketch .forge.js to PNG. |
+
+<details>
+<summary>All render / capture flags</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--focus <names>` | Focus: no arg hides mocks; comma-separated names shows only those |
+| `--hide <names>` | Hide comma-separated object names |
+| `--camera <front\|side\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec. Repeatable. |
+| `--size <px>` | Image size in pixels |
+| `--scene <json>` | Viewport scene state JSON |
+| `--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: thin) |
+| `--port <n>` | Vite dev server port |
+| `--chrome-path <path>` | Chrome or Chromium executable path |
+| `--output <path>` | Output file path |
+| `--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 |
+| `--quality <default\|live\|high>` | Mesh tessellation quality |
+| `--backend <manifold\|occt>` | Geometry backend |
+| `--format <gif\|mp4>` | Output format |
+| `--capture <orbit\|animation>` | Capture preset |
+| `--animation <name>` | Named jointsView animation clip |
+| `--animation-loops <n>` | Repeat the selected animation clip |
+| `--cut-plane <name>` | Enable a named cut plane |
+| `--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 |
 
-Component dimension ownership for disassembled pages:
-- Preferred: explicit binding via `dim(..., { component: \"Part Name\" })`
-- Imported-part ownership: `dim(..., { currentComponent: true })` to pin to the owning returned component instance (no bbox heuristic)
-- Other-component ownership: `dim(..., { component: \"Tabletop\" })`
-- If multiple owners are bound (e.g. `currentComponent: true` plus another component), it is treated as shared and stays on the overview page
-- Fallback: automatic ownership only when both dimension endpoints are unambiguously inside exactly one returned component bounding box
-- Ambiguous dimensions are intentionally skipped for disassembled pages
+</details>
 
-Optional report flag:
-- `--dim-angle-tol <degrees>`: include dimensions whose projected direction is within this many degrees of the nearest view axis (default: `12`)
+## Export
 
-### STL Export (from browser)
+Export to every format you need. Free-tier formats work out of the box.
 
-STL export is available in the browser UI via the Export panel. Binary STL format.
-
-### Parameter Validation
+| Command | Format | Use case |
+|---------|--------|----------|
+| `export svg` | SVG | 2D vector output from sketches |
+| `export sketch-pdf` **\[Pro\]** | PDF | Sketch with dimensions and constraints |
+| `export step` **\[Pro\]** | STEP | CAD interchange (exact geometry) |
+| `export brep` **\[Pro\]** | BREP | Boundary representation |
+| `export 3mf` | 3MF | 3D printing (color, multi-part) |
+| `export stl` | STL | 3D printing |
+| `export gcode` **\[Pro\]** | G-code | Toolpath (scripted, not sliced) |
+| `export sdf` **\[Pro\]** | SDF package | Gazebo robot simulation |
+| `export urdf` **\[Pro\]** | URDF package | ROS / PyBullet / MuJoCo |
+| `export report` **\[Pro\]** | PDF report | Multi-view report with BOM and dimensions |
+| `export cutting-layout` **\[Pro\]** | PDF | 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. |
 
 ```bash
-forgecad check params examples/shoe-rack-doors.forge.js [--samples 10]
-```
+# 3D printing
+forgecad export stl bracket.forge.js
+forgecad export 3mf bracket.forge.js --quality high
 
-Samples each parameter across its range and checks for runtime errors, degenerate geometry (volume ≈ 0), and new collisions between parts. Skips intra-group collisions when assembly groups are used.
+# CAD interchange
+forgecad export step bracket.forge.js
+forgecad export step bracket.forge.js --allow-faceted
 
-**Options:**
-- `--samples N` — Number of sample points per parameter (default: 8)
+# Technical drawings
+forgecad export report bracket.forge.js out/report.pdf
 
-**Output example:**
+# Robot simulation
+forgecad export sdf rover.forge.js --output out/forge_scout
+```
+
+<details>
+<summary>Export flags</summary>
+
+| Option | Description |
+|--------|-------------|
+| `--output <path>` | Output STEP path |
+| `--python <path>` | Python interpreter for uv |
+| `--uv <path>` | uv executable path |
+| `--allow-faceted` | Allow faceted fallback for closed mesh solids |
+| `--quality <default\|live\|high>` | Forge quality preset |
+| `--backend <manifold\|occt>` | Geometry backend |
+| `--dim-angle-tol <deg>` | Dimension routing tolerance in degrees |
+| `--sheet-width <mm>` | Stock sheet width in mm |
+| `--sheet-height <mm>` | Stock sheet height in mm |
+| `--kerf <mm>` | Cutting clearance (saw blade width) in mm |
+
+</details>
+
+## Projects & Publishing
+
+ForgeCAD has a hosted platform at [forgecad.io](https://forgecad.io). The CLI connects your local files to it.
+
+### Get started
+
+```bash
+forgecad login
+forgecad project init "Spool Adapter"
 ```
-✓ Baseline: 6 objects, 12 params
-✓ Checked 91 parameter samples (8 per param)
 
-⚠ Found 8 issues across 4 parameters:
-
-  Parameter "Bottom Left Door":
-    💥 New collision at values: -120.0, -102.9
-       Bottom Left Door ∩ Frame (shared vol: 2561.9mm³)
-```
-
-### Transform/Assembly Invariant Check
+### Sync
 
 ```bash
-forgecad check transforms
+forgecad project push          # Upload local changes
+forgecad project pull          # Download remote changes
+forgecad project status        # See what's different
 ```
 
-Runs fast math-level invariants to catch transform order and frame composition regressions before they leak into examples.
-
-### Compiler Snapshot Check
+### Publish
 
 ```bash
-forgecad check compiler
-forgecad check compiler --case segmented-runtime-hints
-forgecad check compiler --update
+forgecad publish adapter.forge.js --title "AMS Lite Adapter"
 ```
 
-Runs curated compiler regression cases and compares them against committed snapshots.
-This is a unit-style invariant check, not just a debugger convenience.
-The ordinary multi-feature part corpus lives in [`examples/compiler-corpus/README.md`](../../examples/compiler-corpus/README.md).
-
-Each snapshot records:
-- Forge compile plans
-- CadQuery/OCCT lowerings
-- export routing decisions
-- quantized runtime Manifold mesh summaries
-- quantized compiler-lowered Manifold mesh summaries
+Shares are live references — always the current version, not a snapshot.
 
-This check also fails if:
-- a plan-covered shape or sketch no longer matches its compiler-lowered runtime output
-- export manifests drift away from the per-object compiler routing decisions
-- exact/faceted support claims stop matching the lowered artifacts and diagnostics
+<details>
+<summary>All project commands</summary>
 
-### Query Propagation Snapshot Check
+**Authentication**
 
-```bash
-forgecad check query-propagation
-forgecad check query-propagation --update
-```
-
-Runs focused topology-rewrite query-propagation snapshots without dumping the
-entire compiler scene. This keeps supported, ambiguous, and intentionally
-unsupported rewrite semantics reviewable as the propagation layer evolves.
+| Command | Description |
+|---------|-------------|
+| `login` | Authenticate with ForgeCAD (email/password). |
+| `logout` | Clear stored authentication credentials. |
+| `whoami` | Show the current user, server, and license status. |
 
-Each snapshot records:
-- the propagated shape objects that actually carry topology-rewrite metadata
-- exact versus faceted routing outcomes for those objects
-- deterministic rewrite-operation ordering
-- preserved and created query summaries
-- explicit ambiguity/unsupported diagnostic codes
+**Projects**
 
-This check also fails if:
-- a defended propagation case loses the expected preserved or created query shape
-- a known unsupported rewrite stops reporting its explicit diagnostic boundary
-- a multi-feature corpus part stops surfacing the expected rewrite ordering
+| Command | Description |
+|---------|-------------|
+| `project init` | Initialize the current directory as a ForgeCAD project and create it on the server. |
+| `project clone` | Download a remote project into a new local directory. |
+| `project pull` | Download remote changes into the current project. |
+| `project push` | Upload local changes to the remote project. |
+| `project status` | Show differences between local and remote project files. |
+| `project list` | List your remote projects. |
+| `project open` | Open the current project in the browser. |
+| `project info` | Show details of the current project (name, visibility, files, URL). |
+| `project rename` | Rename the current project. |
+| `project set-visibility` | Change project visibility. |
+| `project delete` | Permanently delete the current project and all its files on the server. |
 
-### Example Architecture Gate
+**Members**
 
-```bash
-forgecad check examples
-forgecad check examples --family api-parts --family compiler-corpus
-forgecad check examples --example examples/api/brep-exportable.forge.js
-```
+| Command | Description |
+|---------|-------------|
+| `project members` | List members of the current project. |
+| `project add-member` | Add a member to the current project. |
+| `project remove-member` | Remove a member from the current project. |
+| `project set-role` | Change a member's role. |
 
-Runs the checked example manifest for the entire `examples/` tree.
+**Files (remote)**
 
-The manifest currently lives in `cli/example-manifest/` and covers every:
+| Command | Description |
+|---------|-------------|
+| `file list` | List remote files in the current project. |
+| `file read` | Read a remote file and print its contents. |
+| `file save` | Create or update a remote file. Reads from local file, --content, or --stdin. |
+| `file delete` | Delete a remote file. |
+| `file rename` | Rename or move a remote file. |
+| `file mkdir` | Create a directory in the remote project. |
+| `file copy` | Copy a file from another project into the current one. |
 
-- `.forge.js`
-- `.forge-notebook.json`
+**Shares**
 
-The command always verifies manifest coverage first, so it fails if:
+| Command | Description |
+|---------|-------------|
+| `publish` | Publish a model and get a shareable link. Auto-syncs project if inside one. |
+| `shares list` | List your published models. |
+| `shares delete` | Unpublish a shared model. |
 
-- a new example file was added without classification
-- a checked manifest entry points at a missing file
-- an example's assigned validation path fails
-- a `part` example's declared route expectation no longer matches the compiler report
+**API Tokens**
 
-Current example classes:
+| Command | Description |
+|---------|-------------|
+| `token create` | Create a new API token for CLI and CI/CD access. |
+| `token list` | List your API tokens. |
+| `token revoke` | Revoke an API token. |
 
-- `part`: runtime execution plus optional exact/faceted route assertions on the selected primary shapes
-- `assembly`: runtime solve + scene emission, not exact-route parity
-- `runtime-scene`: viewport/report/runtime examples that still need to execute successfully
-- `sketch`: sketch payload validation via the sketch export path
-- `notebook`: preview-cell validation for `.forge-notebook.json`
-- `experimental`: temporary fenced examples that still have to run
+**Scaffolding**
 
-The gate dispatches by declared validation path, not just by class label:
+| Command | Description |
+|---------|-------------|
+| `new` | Create a new .forge.js file from a template. |
 
-- `part-runtime`: execute and then enforce any declared exact/faceted route contract
-- `assembly-runtime`: execute and validate solved-scene/assembly-owned runtime behavior
-- `runtime-scene`: execute as a viewport/report/runtime scene without treating it as part-route evidence
-- `sketch-svg`: render returned sketch payloads through the sketch SVG path
-- `notebook-preview`: materialize and execute the notebook preview cell
-- `experimental-runtime`: execute only, while the example stays outside the active architecture claim
+</details>
 
-For non-part entries, the manifest can also pin specific runtime surfaces that
-must remain available to repo checks, such as BOM entries, cut planes,
-`jointsView()` controls, grouped scene structure, or collected
-`robotExport(...)` data.
+## AI Integration
 
-Current part route states:
-
-- `exact`: selected primary shapes must stay on the exact compiler route
-- `faceted`: exact must stay blocked and allow-faceted must succeed with diagnostics
-- `holdout`: runtime-checked, but intentionally outside the exact-route claim because the example still mixes route outcomes or depends on a documented unsupported capability; this is a temporary recovery state and should normally trend back to zero
-
-Successful runs also print the current temporary fence list, including each
-remaining `holdout` or `experimental` entry's blocker and follow-up task, so
-the command output can be used directly in a phase-entry review.
-
-Use `--family` when a task owns only one manifest lane, and `--example` when you
-want to debug a single checked artifact.
-
-### Invariant Test Suite
+ForgeCAD files are plain JavaScript. AI coding agents write and iterate on them directly. The CLI closes the loop.
 
 ```bash
-forgecad check suite
-npm test
-npm run test:examples
-npm run test:compiler
-npm run test:compiler:update
-npm run test:query-propagation
-npm run test:query-propagation:update
-```
+# Give your agent full ForgeCAD API knowledge
+forgecad skill install
 
-ForgeCAD's current unit-test surface is assertion-based CLI checks, not a separate Vitest/Jest harness.
-
-The important entrypoints are:
-- `npm test` runs the repo invariant suite (`transforms`, `dimensions`, `placement`, `js-modules`, `brep`, `compiler`, `query-propagation`, `examples`, `api`)
-- `npm run test:examples` runs the example architecture gate across the checked `examples/` manifest
-- `npm run test:compiler` runs just the compiler snapshot/invariant suite
-- `npm run test:compiler:update` refreshes committed compiler snapshots after an intentional change
-- `npm run test:query-propagation` runs the focused topology-rewrite query-propagation snapshots
-- `npm run test:query-propagation:update` refreshes those query-propagation snapshots after an intentional change
-- `forgecad check suite` is the CLI equivalent of the invariant suite runner
-
-### Dimension Propagation Invariant Check
-
-```bash
-forgecad check dimensions
+# Or export a single context file for chat UIs (Claude.ai, ChatGPT, ...)
+forgecad skill one-file ~/Desktop/forgecad-context.md
 ```
 
-Runs shape-level invariants for dimension metadata propagation across:
-- transform APIs (`translate`, `rotate`, `transform`, `scale`, `mirror`, `rotateAround`)
-- copy/style APIs (`clone`, `color`, `setColor`)
-- boolean APIs (`add/subtract/intersect`, plus `union/difference/intersection`)
-- import runtime path (`require(...).color(...).translate(...)`)
+> **Workflow:** Agent writes the model → `forgecad run` validates it → `forgecad check params` sweeps the parameter range → `forgecad export stl` ships the result. All in the terminal.
 
-### Dimension Debugger
+## Validation
 
-```bash
-forgecad debug dimensions /path/to/file.forge.js [--all]
-forgecad debug dimensions /path/to/file.forge.js [--all] [--dim-angle-tol 12]
-```
+Test parameter ranges and run invariant suites.
 
-Prints:
-- total object count
-- total dimension count
-- per-view visibility counts (`front/right/top/iso`) using report angle tolerance
-- report ownership routing (`combined` vs `component:<name>`) per dimension
-- per-object approximate dimension ownership (both endpoints inside object bbox)
-- a dimension coordinate list (first 20 by default, `--all` for full dump)
+### `forgecad check params`
 
-### Compiler Debugger
+Sweep parameter ranges and report runtime failures, degeneracy, and new collisions.
 
-```bash
-forgecad debug compiler /path/to/file.forge.js
-forgecad debug compiler /path/to/file.forge.js --compact
-```
+For each declared parameter, samples `N` values evenly across its `[min, max]` range (default 8) while holding all other parameters at their defaults. At each sample, checks for:
 
-Prints JSON for the current script's compiler state, including:
-- per-object compile plans
-- CadQuery/OCCT lowering diagnostics and lowered plans
-- faceted fallback eligibility
-- runtime Manifold summaries
-- compiler-lowered Manifold summaries
+1. **Runtime errors** — script crashes at certain parameter values
+2. **Degenerate geometry** — shapes with near-zero volume (collapsed geometry)
+3. **New collisions** — part pairs that collide at the sampled value but not at the default
 
-### Local Branch Cleanup
+Baseline collisions (those present at default parameter values) are listed but not flagged as issues — only *new* collisions introduced by parameter changes are reported. Results are grouped by parameter with the problematic value ranges shown.
 
 ```bash
-uv run cli/forge-prune-local-branches.py
-uv run cli/forge-prune-local-branches.py --dry-run
-uv run cli/forge-prune-local-branches.py --base mainline
+forgecad check params examples/shoe-rack-doors.forge.js
+forgecad check params path/to/model.forge.js --samples 12
 ```
 
-This is a `uv`-backed Python utility for repository housekeeping. It finds local branches with no matching remote branch that are already merged into the selected base ref, shows them in a Rich terminal UI, then prompts one by one before deleting anything.
-
-Behavior:
-- Deletes with `git branch -d`, not force-delete
-- Removes linked worktrees first when the branch is checked out in a secondary worktree
-- Requires an explicit `force` choice if one of those linked worktrees is dirty
-- Refuses to touch the current worktree, the primary worktree, or prunable/missing worktree entries
-- `--path` lets you point at any location inside the target repository
-
-## Adding New CLI Commands
-
-1. Create or extend a module under `cli/`
-2. Import from `../src/forge/headless`
-3. Call `await init()` to load the WASM kernel
-4. Use `runScript(code, fileName, allFiles)` to execute user scripts
-5. Register the new subcommand in `cli/forgecad.ts`
-
-### Minimal Example
-
-```typescript
-#!/usr/bin/env node
-import { readFileSync } from 'fs';
-import { init, runScript } from '../src/forge/headless';
-
-const code = readFileSync(process.argv[2], 'utf-8');
-
-await init();
-const result = runScript(code, 'main.forge.js', {});
-
-if (result.error) {
-  console.error(result.error);
-  process.exit(1);
-}
-
-for (const obj of result.objects) {
-  if (obj.shape) {
-    console.log(`${obj.name}: volume=${obj.shape.volume().toFixed(1)}mm³`);
-  }
-  if (obj.sketch) {
-    console.log(`${obj.name}: area=${obj.sketch.area().toFixed(1)}mm²`);
-  }
-  if (obj.toolpath) {
-    console.log(`${obj.name}: ${obj.toolpath.segments.length} G-code segments`);
-  }
-}
-```
+<details>
+<summary>All check commands (CI / development)</summary>
 
-### Cross-file imports
+| Command | Description |
+|---------|-------------|
+| `check suite` | Run the repo invariant suite, with local and full profiles for everyday checks vs CI gates. |
+| `check transforms` | Run transform and assembly invariants. |
+| `check dimensions` | Run dimension propagation invariants. |
+| `check placement` | Run placement reference invariants. |
+| `check js-modules` | Run JavaScript module import invariants. |
+| `check brep` | Run exact BREP export invariants. |
+| `check constraints` | Run constraint solver invariants and snapshot regression tests. |
+| `check compiler` | Run compiler routing snapshots and runtime-vs-lowered invariants. |
+| `check query-propagation` | Run focused topology-rewrite query-propagation snapshots and invariants. |
+| `check examples` | Run the example architecture gate across the checked manifest for `examples/`. |
+| `check api` | Run script API contract invariants. |
+| `check text` | Run text2d geometry contract tests. |
+| `check occt-lower` | Run OCCT lowerer geometry invariant tests. |
+| `check backend-parity` | Compare Manifold vs OCCT backend outputs across example files. |
 
-When running scripts that use `require()` / `importSvgSketch()` or plain JS module imports, pass all project files (or at least all files reachable by imports), keyed by project-relative path. This supports root-relative and relative imports, utility `.js` modules, and `.svg` assets (`./assets/logo.svg`):
+</details>
 
-```typescript
-import { readdirSync, readFileSync } from 'fs';
+<details>
+<summary>Debug commands (ForgeCAD development)</summary>
 
-const allFiles: Record<string, string> = {};
-for (const f of readdirSync(scriptDir)) {
-  if (f.endsWith('.forge.js') || f.endsWith('.js') || f.endsWith('.svg')) {
-    allFiles[f] = readFileSync(join(scriptDir, f), 'utf-8');
-  }
-}
+| Command | Description |
+|---------|-------------|
+| `debug compiler` | Inspect compiler routes, lowered plans, and runtime snapshots for a script. |
+| `debug dimensions` | Inspect report-dimension routing for a script. |
+| `debug faces` | Inspect face transformation histories for a script. |
 
-const result = runScript(code, 'main.forge.js', allFiles);
-```
+</details>
 
-For utility modules that want explicit ForgeCAD imports instead of globals, use the virtual runtime module:
+## Setup & Licensing
 
-```javascript
-import { box, union } from "forgecad";
-```
+| Command | Description |
+|---------|-------------|
+| `completion` | Generate shell completion scripts for bash, zsh, or fish. |
+| `whoami` | Show the current user, server, and license status. |
+| `new` | Create a new .forge.js file from a template. |
+| `doctor` | Check system dependencies for all CLI features. |
+
+### Licensing
 
-Use `require("./file.forge.js", { Param: value })` for model/sketch files when you want ForgeCAD-specific behavior like param override scopes. Use `importSvgSketch()` for SVG assets.
+The CLI is free for core workflows. Advanced exports and rendering are Pro.
 
-## Dependencies
+| Free | Pro |
+|------|-----|
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check params`, `check suite` | `render hq`, `capture gif`, `capture mp4`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` |
 
-| Package | Purpose | Context |
-|---------|---------|---------|
-| `forgecad` | Installable CLI binary (`forgecad ...`) | Runtime package |
-| `puppeteer-core` | Headless Chrome for PNG/GIF/MP4 rendering | Runtime dependency |
-| `manifold-3d` | Geometry kernel (WASM) | Works in both Node and browser |
-| `three` | 3D rendering (used by render.ts) | Loaded in browser context by Puppeteer |
+```bash
+forgecad license                    # Check status
+forgecad license activate           # Activate Pro
+forgecad license deactivate         # Remove license
+```