forgecad 0.9.14 → 0.9.16

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

@@ -64,6 +64,8 @@ forgecad studio .
 
 `forgecad studio .` opens the installed local editor around the current project. It requires an explicit project path; `.` means the current folder. `forgecad dev <project-path>` is for ForgeCAD source development and internal live-reload work, not the normal user onboarding path.
 
+Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
+
 ## Install Skills For Local Coding Agents
 
 Install the ForgeCAD public skill library:
@@ -103,15 +105,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.
@@ -174,7 +167,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.
@@ -198,7 +191,7 @@ The CLI is not just a launcher. It gives the agent a measurable feedback loop.
 | 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. |
@@ -223,7 +216,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

package/dist/docs-raw/CLI.md

@@ -48,6 +48,8 @@ ForgeCAD includes a local editor. Open it around a dedicated project folder, edi
 
 `forgecad studio <project-path>` is the normal installed-CLI command for users. `forgecad dev <project-path>` starts the Vite dev server and is mainly for ForgeCAD source development.
 
+Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
+
 <details>
 <summary>Common flags for studio / dev</summary>
 
@@ -162,11 +164,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
@@ -189,8 +192,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. |
@@ -229,7 +251,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`.
 
@@ -299,9 +321,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
@@ -311,7 +333,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
@@ -346,6 +368,7 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 |--------|-------------|
 | `--param <Key=Value>` | Override a parameter value (Key=Value). Repeatable. |
 | `-p <Key=Value>` | Shorthand for --param |
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--focus <names>` | Focus: no arg hides mocks; comma-separated names/globs show only those |
 | `--hide <names>` | Hide comma-separated object names/globs |
 | `--camera <front\|back\|side\|right\|top\|iso\|az:el\|az:el:dist\|spec>` | Camera preset, spherical (az:el), or full spec such as `proj=perspective;pos=x,y,z;target=x,y,z;up=x,y,z;fov=45`. Repeatable. |
@@ -356,9 +379,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) |
+| `--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>` | Vite dev server port |
+| `--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 |
@@ -379,7 +402,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 |
@@ -448,9 +471,10 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 
 | Option | Description |
 |--------|-------------|
+| `--joint <JointName=Value>` | Override a Motion tab joint value (JointName=Value). Repeatable. |
 | `--output <path>` | Output STEP path |
+| `--backend <occt\|truck>` | Exact BREP exporter: occt (default) or truck (native analytic kernel) |
 | `--quality <default\|live\|high>` | Forge quality preset |
-| `--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 |
@@ -484,7 +508,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.
 

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