forgecad 0.9.2 → 0.9.3

package/dist-skill/SKILL-dev.md

@@ -21,7 +21,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 ### Import and Composition
 
-- `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
+- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files and `require("./helpers.js")` for plain helper modules. Do not write extensionless imports such as `require("./file")`; ForgeCAD resolves project imports by exact path.
+- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; do not destructure those names from helpers with patterns like `const { bom } = require("./bom.js")`. If a helper file is needed, import it under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use `.toGroup()` only when you need `ShapeGroup` composition, transforms, or named-child lookup.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).

package/dist-skill/SKILL.md

@@ -21,7 +21,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 ### Import and Composition
 
-- `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
+- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files and `require("./helpers.js")` for plain helper modules. Do not write extensionless imports such as `require("./file")`; ForgeCAD resolves project imports by exact path.
+- ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; do not destructure those names from helpers with patterns like `const { bom } = require("./bom.js")`. If a helper file is needed, import it under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use `.toGroup()` only when you need `ShapeGroup` composition, transforms, or named-child lookup.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).

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

@@ -12,6 +12,24 @@ const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
 return box(width, 30, 10);
 ```
 
+## Injected Runtime Names
+
+ForgeCAD API functions and classes are injected into every `.forge.js` script. Use them directly; do not import or destructure ForgeCAD API names from helper files.
+
+```javascript
+// BAD — `bom` and `bomToCsv` are already built-in runtime names.
+const { bom, bomToCsv } = require("./bom.js");
+
+// GOOD — use the built-in directly.
+bom(4, "M4 bolt");
+
+// GOOD — keep project helpers under their own local name.
+const bomHelpers = require("./bom.js");
+bomHelpers.addFasteners(...);
+```
+
+Top-level declarations such as `const bom = ...`, `let scene = ...`, or `class Shape {}` collide with the injected runtime names. If you need a local helper, choose a project-specific name like `projectBom`, `sceneConfig`, or `makeShape`.
+
 ## Execution Model
 
 - Scripts re-execute on every parameter change (400ms debounce)
@@ -24,6 +42,8 @@ Top-level assembly scripts can return an unsolved `Assembly` directly; ForgeCAD
 
 A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, SolvedAssembly, SdfShape, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
 
+When importing project files, include the full extension in every relative path: `require('./motor-mount.forge.js')` for model files and `require('./helpers.js')` for plain helper modules. ForgeCAD resolves project imports by exact path and does not infer `.forge.js` or `.js` from `require('./motor-mount')`.
+
 ```javascript
 // motor-mount.forge.js — renders standalone, exports metadata via require()
 const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
@@ -75,6 +95,12 @@ Shapes carry semantic face labels through their lifecycle. The flow is:
 
 You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
 
+## Text vs Viewport Labels
+
+Use `text2d()` only when the letters are part of the model: raised text, engraving, cut labels, serial plates, exported markings, or geometry that should survive into STL/STEP output. `text2d()` builds filled sketch geometry from font outlines, so it can make exact/OCCT workflows slower.
+
+Use `Viewport.label(text, [x, y, z], options)` when the goal is to explain the model in the viewport. Render labels are annotations only: they do not create meshes, do not export, do not enter the B-rep path, and do not add face labels.
+
 ## SDF Modeling
 
 For organic shapes, smooth blending, TPMS lattices, and surface deformations. Return `SdfShape` values directly, or return a plain object/array tree of SDF leaves, for native raymarch preview. Use `.toShape()` or `toShape(...)` only when you need mesh-backed CAD/export behavior. See [sdf-primitives.md](sdf-primitives.md).

package/dist-skill/docs/CLI.md

@@ -5,7 +5,7 @@ skill-order: 1
 
 # ForgeCAD CLI
 
-Run, export, render, and publish `.forge.js` models from your terminal. Core workflows are included with a free ForgeCAD account; advanced exports and rendering are Pro.
+Create projects, open local studios, run, inspect, export, publish, and sync `.forge.js` models from your terminal. Core workflows are included with a free ForgeCAD account; advanced exports and rendering are Pro.
 
 ## Quick Start
 
@@ -13,36 +13,44 @@ Run, export, render, and publish `.forge.js` models from your terminal. Core wor
 # 1. Install
 npm install -g forgecad
 
-# 2. Sign in and clone a hosted project
+# 2. Sign in and create a dedicated project folder
 forgecad login
-forgecad project clone start-here
-cd start-here
+mkdir spool-adapter
+cd spool-adapter
+forgecad project init "Spool Adapter" --visibility private
 
-# 3. Run it
-forgecad run 00-start-here.forge.js
+# 3. Create a first model file
+forgecad new adapter --template part
 
-# 4. Open the editor (live reload)
-forgecad dev .
+# 4. Open the local editor
+forgecad studio .
 
-# 5. Export
-forgecad export stl 00-start-here.forge.js
+# 5. Validate, export, and push to the browser
+forgecad run adapter.forge.js
+forgecad export stl adapter.forge.js
+forgecad project push
+forgecad project open
 ```
 
-Most CLI commands require a ForgeCAD account. Use `forgecad login` for email/password accounts, `forgecad login --token` for GitHub/Google web-auth accounts, or `FORGECAD_TOKEN=fc_pat_... forgecad <command>` for CI/CD.
+Most CLI commands require a ForgeCAD account. Use `forgecad login` for email/password accounts, `forgecad login --token` for GitHub/Google web-auth accounts, or `FORGECAD_TOKEN=fc_pat_... forgecad <command>` for CI/CD. `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 .`.
 
 ## Editor
 
-ForgeCAD includes a local editor with live reload. Edit a `.forge.js` file, save, and the 3D view updates instantly — parameters become interactive sliders.
+ForgeCAD includes a local editor. Open it around a dedicated project folder, edit a `.forge.js` file, save, and the 3D view updates — parameters become interactive sliders.
 
 | Command | Description |
 |---------|-------------|
-| `dev <project-path> [project-path ...]` | Start the Vite dev server with live reload. No build step required — the preferred way to run ForgeCAD during active development. |
-| `studio <project-path> [project-path ...]` | Serve the production build of the studio (requires dist/ — run `npm run build` first). |
+| `studio <project-path> [project-path ...]` | Open the installed local editor around one or more project folders. |
+| `dev <project-path> [project-path ...]` | Start the Vite dev server for ForgeCAD source development. |
 | `web` | Start a local dev server in web/playground mode (no filesystem, localStorage only). |
 | `open <project-path> [project-path ...]` | Alias for `forgecad studio`. |
 
+`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.
+
 <details>
-<summary>Common flags for dev / studio</summary>
+<summary>Common flags for studio / dev</summary>
 
 | Option | Description |
 |--------|-------------|
@@ -79,7 +87,7 @@ The primary validation command. Runs your script with the real geometry kernel (
 
 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.
 
-**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)`.
+**Spatial analysis** — reports directional relationships and gap distances between nearby objects (e.g. `bracket is ABOVE base (gap: 5mm)`). Exact pairwise collision intersections run by default only for bounded scenes; use `--spatial exact` for exhaustive collision checks or `--spatial off` to skip this section.
 
 **Physical connectivity** — pass `--connectivity` to list physically connected components across visible objects. Overlapping or touching bboxes are joined within `--connectivity-tolerance` (default `0.05` model units); use collision inspection for exact positive-volume overlaps. This helps answer whether the model is one continuous assembly or several separate islands.
 
@@ -93,6 +101,7 @@ 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 --connectivity
+forgecad run examples/cup.forge.js --journeys
 forgecad run examples/cup.forge.js --backend occt
 forgecad run examples/cup.forge.js --debug-imports
 forgecad run examples/cup.forge.js -p "Wall Thickness=3" -p "Body Height=200"
@@ -126,7 +135,7 @@ 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.
 
-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`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass it multiple times to render several viewpoints in one run.
+Use `--focus` to isolate specific parts (hides everything else) or `--hide` to remove clutter like mock objects. The `--view` flag selects a named camera declared in `scene({ views })`. The `--camera` flag accepts built-in views (`front`, `top`, `iso`), `azimuth:elevation` angles, or an exact `proj/pos/target/up/fov` camera spec — pass `--camera` multiple times to render several viewpoints in one run.
 
 Use `--edges=<off|thin|bold>` to control the edge overlay. For a pure wireframe look, use `render wireframe` instead.
 
@@ -137,6 +146,7 @@ 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 --view hero
 forgecad render 3d model.forge.js --camera 45:30
 forgecad render 3d model.forge.js --camera "proj=perspective;pos=200,-160,120;target=0,0,20;up=0,0,1;fov=38"
 forgecad render 3d model.forge.js --camera front --camera side
@@ -234,6 +244,7 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 | `--focus <names>` | Focus: no arg hides mocks; comma-separated names shows only those |
 | `--hide <names>` | Hide comma-separated object names |
 | `--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. |
+| `--view <name>` | Named camera view declared by the model with scene({ views }) |
 | `--size <px>` | Image size in pixels |
 | `--scene <json>` | Viewport scene state JSON |
 | `--background <color>` | Canvas background override |
@@ -292,22 +303,22 @@ forgecad render section examples/furniture/01-table.forge.js out/bold.svg --edge
 
 ## Export
 
-Export to every format you need. Account-included formats work after login; advanced formats are Pro.
+Export to every format you need. Export actions are free to run; production outputs carry commercial-use guidance.
 
 | Command | Format | Use case |
 |---------|--------|----------|
-| `cut-list` **\[Pro\]** | Terminal | Grouped sheet-material cut list from `sheetStock()` |
+| `cut-list` **\[Production\]** | Terminal | Grouped sheet-material cut list from `sheetStock()` |
 | `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 sketch-pdf` **\[Production\]** | PDF | Sketch with dimensions and constraints |
+| `export step` **\[Production\]** | STEP | CAD interchange (exact geometry) |
+| `export brep` **\[Production\]** | 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 |
+| `export gcode` **\[Production\]** | G-code | Toolpath (scripted, not sliced) |
+| `export sdf` **\[Production\]** | SDF package | Gazebo robot simulation |
+| `export urdf` **\[Production\]** | URDF package | ROS / PyBullet / MuJoCo |
+| `export report` **\[Production\]** | PDF report | Multi-view report with BOM and dimensions |
+| `export cutting-layout` **\[Production\]** | PDF | 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
@@ -351,22 +362,32 @@ forgecad export sdf rover.forge.js --output out/forge_scout
 
 ## Projects & Publishing
 
-ForgeCAD has a hosted platform at [forgecad.io](https://forgecad.io). The CLI connects your local files to it.
+ForgeCAD has a hosted platform at [forgecad.io](https://forgecad.io). The CLI connects a dedicated local project folder to it.
+
+A project is a local folder linked to the hosted app by `forgecad.json`. Use `forgecad project clone <slug>` to download an existing hosted project into a local folder, or run `forgecad project init` inside a folder that should become a new ForgeCAD project. Open local projects with `forgecad studio <project-path>`.
 
-A project is a local folder linked to the hosted app by `.forgecad/project.json`. Use `forgecad project clone <slug>` to download an existing hosted project into a local folder, or run `forgecad project init` inside a folder that should become a ForgeCAD project. Open local projects with `forgecad studio <project-path> [project-path ...]`.
+Keep the project root small and intentional. Do not run the editor from `~`, downloads, desktop, or a huge source tree. ForgeCAD scans project files such as `.forge.js`, `.js`, and `.svg`; broad roots make local workflows and AI-agent context slow and confusing.
 
 ### Get started
 
 ```bash
 forgecad login
-forgecad project clone start-here
-
-# or initialize the current folder as a new project:
+mkdir spool-adapter
+cd spool-adapter
 forgecad project init "Spool Adapter"
+forgecad new adapter --template part
+forgecad studio .
+
+# or clone an existing hosted project:
+forgecad project clone start-here
+cd start-here
+forgecad studio .
 ```
 
 `forgecad login` prompts for email/password. If your account was created through GitHub or Google, create an API token in Settings > API Tokens and run `forgecad login --token`; it prompts securely when the token is omitted. Use `FORGECAD_TOKEN=fc_pat_...` instead for CI/CD and one-off automation. See [Platform authentication](platform/auth.md#cli-auth-for-oauth-accounts) for details.
 
+`forgecad project init` creates the remote project, writes `forgecad.json`, pushes any existing local source files, and records server file IDs. `forgecad project push` syncs an already initialized project; it does not create a remote project from an arbitrary folder.
+
 ### Sync
 
 ```bash
@@ -457,7 +478,7 @@ Shares are live references — always the current version, not a snapshot.
 
 ## AI Integration
 
-ForgeCAD files are plain JavaScript. AI coding agents write and iterate on them directly. The CLI closes the loop. See [AI Usage](AI/usage.md) for approved models, Codex/Claude Code setup, installable skills, and completion criteria.
+ForgeCAD files are plain JavaScript. AI coding agents should work inside an initialized project folder, write and iterate on local files, and use the CLI for evidence. See [AI Usage](AI/usage.md) for approved models, project-first setup, installable skills, quality prompts, and completion criteria.
 
 ```bash
 # Install the full public ForgeCAD skill library
@@ -542,11 +563,11 @@ forgecad check params path/to/model.forge.js --samples 12
 
 ### Licensing
 
-Core CLI workflows are included with a free account. Advanced exports and rendering are Pro.
+The CLI is free for core workflows and exports. Production outputs are free to run; Pro covers commercial use. High-value render and capture tools require Pro.
 
-| Free | Pro |
-|------|-----|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check params`, `check suite` | `render hq`, `capture gif`, `capture mp4`, `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` |
+| Free | Production outputs | Pro |
+|------|--------------------|-----|
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `check params`, `check suite` | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export sdf`, `export urdf`, `export report`, `export cutting-layout` are free to run; Pro covers commercial use. | `render hq`, `capture gif`, `capture mp4` |
 
 ```bash
 forgecad license                    # Check signed-in account status

package/dist-skill/docs/generated/core.md

@@ -414,6 +414,8 @@ coalesceEdges(segments: EdgeSegment[], tolerance?: number): EdgeSegment[]
 
 When importing a `.forge.js` file, the return value is what the script returns. If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
 
+**Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
+
 **Parameter scoping:** Parameters declared in required files are automatically namespaced with a `"filename#N / "` prefix (e.g. `"bracket.forge.js#1 / Width"`). This prevents collisions when multiple files declare same-named params. Each file's params appear as separate sliders.
 
 **Parameter overrides:** When passing overrides, use the bare param name (not the scoped name). Overrides are type-checked — unrecognized keys throw an error with typo suggestions.