forgecad 0.9.13 → 0.9.15

package/dist/docs-raw/AI/ai-native-cad.md

@@ -0,0 +1,50 @@
+# AI-Native CAD Workflow
+
+ForgeCAD is an AI-native CAD workflow for turning product ideas into editable, manufacturable parametric models. The core loop is simple: describe the goal, let an AI agent edit `.forge.js` source, validate the model with the CLI, inspect visual and manufacturing evidence, then revise or fork the next iteration.
+
+The important distinction is that ForgeCAD does not stop at a pretty mesh. The model remains code. A hole can move, a wall can thicken, a fastener can change, and a product variant can branch from the same source instead of starting over.
+
+## What AI-Driven CAD Means Here
+
+AI-driven CAD should produce a model that can survive feedback. In ForgeCAD, the agent works with normal files, not a hidden binary state:
+
+- `.forge.js` files express dimensions, parameters, assemblies, connectors, materials, and export intent.
+- `forgecad run` catches syntax errors, import problems, invalid geometry, collisions, and verification failures.
+- `forgecad render` and `forgecad inspect` create visual evidence for design review, fit checks, wall thickness, sections, masks, depth, and normals.
+- `forgecad export` sends the same source toward STL, 3MF, STEP, reports, cutting layouts, robot packages, or G-code depending on the job.
+
+This makes the AI useful after the first answer. You can ask for changes in natural language, but the artifact being changed is still an editable engineering object.
+
+## Manufacturing Feedback Loop
+
+A manufacturable model needs feedback before fabrication. ForgeCAD gives agents a concrete loop:
+
+```text
+prompt -> edit source -> run -> render -> inspect -> fix -> export
+```
+
+That loop is where quality improves. The agent can inspect collision reports, check thin walls, render multiple camera views, test parameter ranges, and produce evidence for the user instead of relying on a single screenshot.
+
+## Parallel Product Idea Iterations
+
+Because ForgeCAD models are source files, parallel product exploration is cheap. An agent can create several variants in separate files or branches:
+
+- one concept optimized for 3D printing
+- one concept aimed at sheet metal or laser cutting
+- one concept with purchased hardware and service access
+- one simplified blockout for proportion and motion review
+- one production-facing version with clearer tolerances and export targets
+
+Each variant can keep the same validation contract: run it, render it, inspect it, compare it, and decide whether it deserves more detail.
+
+## Where ForgeCAD Fits
+
+ForgeCAD is useful when you want AI-assisted CAD that remains inspectable and editable:
+
+- founders exploring physical product ideas
+- makers iterating 3D printed parts and fixtures
+- engineers prototyping mechanisms, enclosures, brackets, and assemblies
+- teams that want version-controlled CAD source and reproducible exports
+- AI agents that need a deterministic toolchain instead of a purely visual prompt-to-mesh path
+
+The goal is not to hide CAD behind a chatbot. The goal is to let AI do more of the modeling work while ForgeCAD keeps the result grounded in readable source, validation evidence, and manufacturing outputs.

package/dist/docs-raw/AI/usage.md

@@ -103,15 +103,6 @@ If you only want the core modeling skill without companion workflows:
 forgecad skill install --core-only
 ```
 
-ForgeCAD developers can install the internal/development variant of the core skill:
-
-```bash
-forgecad skill install --dev
-forgecad skill install --dev --target claude
-```
-
-Use `--dev` only for work on ForgeCAD itself. It includes compiler internals, solver architecture, coding standards, release process, and skill maintenance notes.
-
 ## Recommended Agent Prompts
 
 Start the agent inside the initialized project folder. Do not ask it to create a model in a random empty folder or to work from one loose file on the desktop.
@@ -139,7 +130,7 @@ push when the result is ready for the browser.
 ```text
 Use forgecad-component-model and forgecad. Parts must build at origin. The
 assembly positions parts with connectors or explicit assembly-level placement.
-Validate with forgecad run --connectivity, inspect fit interference and visual objects,
+Validate with forgecad run, inspect physical components, inspect fit interference and visual objects,
 and run parameter checks before calling it done.
 ```
 
@@ -174,7 +165,7 @@ Do not accept a model just because it renders. CAD quality comes from command ev
 
 - `forgecad run` confirms the script executes and reports the fast inner-loop build summary.
 - `forgecad render 3d` gives visual views from deterministic cameras.
-- `forgecad inspect <family> <mode>` checks focused geometry evidence such as fit interference, manufacture thickness, visual objects, surface zebra, physical components, and precise or dense section slices.
+- `forgecad inspect <family> <mode>` checks focused geometry evidence such as fit interference, manufacture thickness, visual objects, visual rig, surface zebra, physical components, and precise or dense section slices.
 - `forgecad inspect section` runs an agent-native one-off section probe with exact ray ruler measurements and a replay recipe.
 - `forgecad inspect mechanical-integrity` checks assembly-level verification intent and optional collision evidence.
 - `forgecad run -p "Name=Value"` validates important parameter values without editing source.
@@ -186,18 +177,19 @@ The CLI is not just a launcher. It gives the agent a measurable feedback loop.
 
 | Need | Command | What it gives the agent |
 |---|---|---|
-| Execute and validate a model | `forgecad run model.forge.js` | Fast red/green execution feedback: returned object names, parameters, verification results, script logs, and timing. |
-| Inspect run details | `forgecad run model.forge.js --details --history --features` | Per-object volumes and bounds, construction history, and feature tallies when those details are worth the extra work. |
+| Execute and validate a model | `forgecad run model.forge.js` | Fast red/green execution feedback: build count, parameters, verification results, script logs, and timing. |
+| List targetable objects | `forgecad ls model.forge.js --tree` | Exact object paths, ids, groups, tags, and optional geometry metrics for focused renders or inspections. |
+| Inspect run diagnostics | `forgecad run model.forge.js --history --features` | Construction history and feature tallies when those details are worth the extra work. |
 | Debug imports | `forgecad run model.forge.js --debug-imports` | Import resolution and module-loading diagnostics for multi-file projects. |
 | Compare geometry backends | `forgecad run model.forge.js --backend occt` | Runs against a specific backend when exact geometry or backend parity matters. |
 | Test physical connectivity | `forgecad run model.forge.js --connectivity` | Connected-component reporting for assemblies and printable parts. |
-| Check spatial relationships | `forgecad run model.forge.js --spatial bounded` | Opt-in directional relationships and bounded collision intersections during a run. |
 | Override parameters | `forgecad run model.forge.js -p "Width=120"` | Checks a model at a specific parameter value without editing source. |
 | Inspect mechanical integrity | `forgecad inspect mechanical-integrity model.forge.js --collisions` | Assembly-level verification, expected component counts, and collision evidence for acceptance gates. |
+| Inspect physical gaps | `forgecad inspect physical gaps model.forge.js --camera iso` | Evidence bundle for spatial gaps between physical components. |
 | Produce visual evidence | `forgecad render 3d model.forge.js --camera iso` | PNG viewport renders from deterministic camera angles. |
 | Measure a targeted section | `forgecad inspect section model.forge.js --plane yz --ray bore:-20,0:20,0` | A unique probe directory with `result.json`, `section.svg`, `section.png`, exact solid/gap intervals along each ray, and a `replaySpec` for candidate comparisons. Use `--offset` only when the cut should move away from the zero plane. |
 | Replay a targeted section | `forgecad inspect replay outputs/inspect/<probe>/result.json --source candidate.forge.js` | Reruns the same plane and ray rulers against another source and reports measurement deltas. |
-| Inspect targeted geometry evidence | `forgecad inspect fit interference model.forge.js --camera iso` | A bundle with manifest plus the requested evidence PNGs. Visual inspection evidence uses the light technical `inspection` style by default. Use `inspect visual cutaway`, `inspect visual objects`, `inspect manufacture thickness`, `inspect sections at|stack|sample`, `inspect visual depth`, `inspect visual normals`, `inspect physical components`, or `inspect physical gaps` for other questions. |
+| Inspect targeted geometry evidence | `forgecad inspect fit interference model.forge.js --camera iso` | A bundle with manifest plus the requested evidence PNGs. Visual inspection evidence uses the light technical `inspection` style by default. Use `inspect visual cutaway`, `inspect visual objects`, `inspect visual rig`, `inspect manufacture thickness`, `inspect sections at|stack|sample`, `inspect visual depth`, `inspect visual normals`, `inspect physical components`, or `inspect physical gaps` for other questions. |
 | Export manufacturing files | `forgecad export stl model.forge.js` and `forgecad export 3mf model.forge.js` | Mesh exports for 3D printing. |
 | Export exact or advanced outputs | `forgecad export step`, `forgecad export brep`, `forgecad export report`, `forgecad export cutting-layout` | Production outputs for CAD interchange, reports, and sheet workflows. |
 | Sync hosted projects | `forgecad project pull`, `forgecad project push`, `forgecad project publish` | Local-agent workflow connected to forgecad.io projects and shares. |
@@ -222,7 +214,7 @@ For the full command reference, see [ForgeCAD CLI](../CLI.md).
 | `forgecad-visual-spec` | Producing builder-honest image prompts from a concrete model, HLD, LLD, or build brief. |
 | `forgecad-project` | Managing forgecad.io projects from the CLI: init, clone, pull, push, file commands, members, publish, and shares. |
 
-The source prompts live in the repository under `skills/`. Public export is controlled by `forgecad-public: true` in each skill's `SKILL.md` frontmatter. To list the current public set from a source checkout:
+The source prompts for CLI-shipped companion skills live in the repository under `agent-skill-library/`. Public export is controlled by `forgecad-public: true` in each skill's `SKILL.md` frontmatter. Repo-local operational skills live under `.agents/skills/` and are not shipped through the CLI. To list the current public set from a source checkout:
 
 ```bash
 npm run sync:public-skills -- --list
@@ -267,7 +259,7 @@ forgecad check print model.forge.js --json
 For mechanisms, dense assemblies, printable parts, or anything safety-adjacent:
 
 ```bash
-forgecad run model.forge.js --connectivity
+forgecad inspect physical components model.forge.js --camera iso
 forgecad inspect mechanical-integrity model.forge.js --collisions
 forgecad inspect fit interference model.forge.js --camera iso
 forgecad inspect manufacture thickness model.forge.js --min 1.6 --warn 2.4 --camera iso

package/dist/docs-raw/CLI.md

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

package/dist/docs-raw/component-model.md

@@ -35,18 +35,27 @@ return rack.withConnectors({
 
 ### Rule 2: Connectors Are the Interface
 
-Every part that participates in an assembly declares connectors. A connector says: "here's where I connect, and here's what direction I face." It's the part's public interface — the only thing the assembly needs to know.
+Every part that participates in an assembly declares connectors. A connector says: "here's where I connect, what direction I face, and what roll I consider upright." It's the part's public interface — the only thing the assembly needs to know.
 
 ```js
 return mount.withConnectors({
   flange: connector("bolt-face", {
     origin: [0, 0, 0],       // where the mating surface is
     axis: [0, 0, 1],         // direction it faces (outward from part)
+    up: [1, 0, 0],           // roll reference when orientation matters
   }),
 });
 ```
 
-Connectors meet **face-to-face**. Both axes point outward from their respective parts. The system brings them together from opposite sides — like plugging a USB cable into a port.
+A connector is a small local frame:
+
+- `origin` is the pivot, contact point, socket center, or mating-face point.
+- `axis` is the primary direction: face normal, hinge line, or slide direction.
+- `up` is the secondary direction that fixes roll around `axis`.
+
+`up` is not world up. It is the connector's local roll reference and must not be parallel to `axis`. If `up` is omitted, ForgeCAD picks a deterministic perpendicular vector. That is fine when roll does not matter, but hinges, wheels, levers, and keyed parts should author `up` explicitly.
+
+Connectors meet **face-to-face**. Both axes point outward from their respective parts. The system brings them together from opposite sides, then uses `up` to pin the rest orientation — like plugging in a keyed connector instead of a round peg.
 
 ### Rule 3: The Assembly Is Pure Composition
 
@@ -117,22 +126,29 @@ Change the servo model → the mount rebuilds with new cavity dimensions → its
 
 ## The Connector Convention
 
-Connectors follow one convention: **face-to-face**.
+Connectors follow one convention: **face-to-face connector frames**.
 
-Each connector's axis points **outward** from its part — the direction the connection faces. When two connectors mate, the system negates one axis so they approach from opposite sides.
+Each connector's axis points **outward** from its part — the direction the connection faces. When two connectors mate, the system makes their origins coincide and, for fixed/revolute joints, negates one axis so they approach from opposite sides. The `up` vectors define the roll reference that makes the rest pose deterministic.
 
 - **Fixed joints** (bolt flange): both faces point outward, system brings them together
-- **Revolute joints** (hinge): both parts point outward along the hinge line, system opposes them
-- **Prismatic joints** (slider): both connectors point along the slide direction (co-directional exception — the slide axis IS the shared direction)
+- **Revolute joints** (hinge): both parts point outward along the hinge line, system opposes them, and `up` pins zero angle
+- **Prismatic joints** (slider): both connectors point along the slide direction (co-directional exception — the slide axis IS the shared direction), while `up` still pins roll around the rail
+
+Revolute joint values are still signed by the physical hinge axis. If a bilateral
+mechanism mirrors a hinge axis, the mirrored pose uses the negated physical value
+(`Right: +theta`, `Left: -theta`), and physical limits mirror as
+`[min, max] -> [-max, -min]`. Prismatic joints do not have this angle-handedness
+flip. Use a side-neutral link graph or explicit state mapping when equal semantic
+pose values should drive both sides.
 
 ```js
 // Base bottom face points down, mount flange points up → meet in the middle
-base.withConnectors({ mount_face: connector("bolt-face", { origin: [0,0,0], axis: [0,0,-1] }) });
-mount.withConnectors({ flange: connector("bolt-face", { origin: [0,0,0], axis: [0,0,1] }) });
+base.withConnectors({ mount_face: connector("bolt-face", { origin: [0,0,0], axis: [0,0,-1], up: [1,0,0] }) });
+mount.withConnectors({ flange: connector("bolt-face", { origin: [0,0,0], axis: [0,0,1], up: [1,0,0] }) });
 
-// Hinge: frame points up along hinge line, door points down → shared rotation axis
-frame.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,1] }) });
-door.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,-1] }) });
+// Hinge: axes oppose along the pin, up pins the closed/rest roll
+frame.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,1], up: [1,0,0] }) });
+door.withConnectors({ hinge: connector("hinge", { origin: [0,0,40], axis: [0,0,-1], up: [1,0,0] }) });
 ```
 
 ## One File vs. Many Files