forgecad 0.9.2 → 0.9.3

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

@@ -1,71 +1,69 @@
 # AI Usage
 
-ForgeCAD is built for AI-assisted CAD because the model is plain JavaScript and the CLI can check the result without a human clicking through a CAD UI. The strong loop is:
+ForgeCAD is built for AI-assisted CAD because models are plain JavaScript and the CLI can check the result without a human clicking through a CAD UI.
+
+The reliable loop is:
 
 ```text
-agent edits .forge.js -> forgecad run -> render or inspect -> fix -> check params -> export
+dedicated project folder -> approved model -> agent edits .forge.js ->
+forgecad run -> render or inspect -> fix -> check params -> project push
 ```
 
-Use the browser for fast visual inspection. Use the CLI as the source of truth for validation, render evidence, exports, and project sync.
+Use the browser for visual inspection. Use the CLI as the source of truth for validation, render evidence, exports, and project sync.
 
 ## Approved Models
 
-Only these models are approved for ForgeCAD AI workflows:
+Use the strongest available model in the approved set. Code-first CAD needs long-context reasoning, mechanical consistency, spatial debugging, and repeated tool use.
 
 | Provider family | Approved models |
-| --- | --- |
-| OpenAI | GPT-5.3-Codex, GPT-5.4, GPT-5.5, GPT-5.5-Pro |
-| Anthropic | Opus 4.6, Opus 4.7 |
+|---|---|
+| OpenAI | GPT-5.5-Pro, GPT-5.5, GPT-5.4, GPT-5.3-Codex |
+| Anthropic | Opus 4.7, Opus 4.6 |
 | Google | Gemini 3.1 Pro |
 
-Do not recommend smaller, older, preview, flash, lite, haiku, sonnet, or unofficial models for ForgeCAD generation work. Code-first CAD needs long-context reasoning, mechanical consistency, and repeated debugging through tool output. The documentation, skills, examples, and validation loop are optimized around the approved model set above.
+Do not recommend smaller, older, preview, flash, lite, haiku, sonnet, mini, fast, or unofficial models for ForgeCAD generation work. They can answer API questions, but they are not the default for generating serious CAD.
 
-## Install The CLI
+Recommended settings:
 
-Install ForgeCAD globally:
+- Use the highest reasoning or extended-thinking mode the product offers.
+- Allow shell/tool execution so the agent can run `forgecad run`, renders, inspections, and exports.
+- Keep the whole project folder in context, not just one file.
+- Give the model enough time for multiple implementation and verification passes.
+- Ask for evidence from commands, not just a visual claim.
 
-```bash
-npm install -g forgecad
-```
+## Project Setup For AI Agents
 
-Create and run a local model:
-
-```bash
-forgecad new bracket
-forgecad run bracket.forge.js
-forgecad dev
-```
+Do not give an agent your home folder, desktop, downloads folder, or a large unrelated repository. Start from a clean project folder.
 
-For hosted projects, authenticate and clone. Use plain `forgecad login` for email/password accounts. If your account was created through GitHub or Google, create an API token in `Settings > API Tokens` and use `forgecad login --token`.
+### Clone The Starter Project
 
 ```bash
+npm install -g forgecad
 forgecad login
+# For GitHub/Google accounts, create an API token in Settings > API Tokens:
+# forgecad login --token
 forgecad project clone start-here
 cd start-here
 forgecad studio .
 ```
 
-`forgecad dev` is best while editing local files. `forgecad studio .` serves the production studio around the current project folder.
+### Create A New Project
 
-## What The CLI Gives An Agent
+```bash
+npm install -g forgecad
+forgecad login
+mkdir enclosure-bracket
+cd enclosure-bracket
+forgecad project init "Enclosure Bracket" --visibility private
+forgecad new bracket --template part
+forgecad studio .
+```
 
-The CLI is not just a launcher. It gives the agent a measurable feedback loop.
+`forgecad project init` creates the remote project, writes `forgecad.json`, and uploads any existing local `.forge.js`, `.js`, and `.svg` files. After that, `forgecad project push` syncs local changes to the hosted project.
 
-| Need | Command | What it gives the agent |
-| --- | --- | --- |
-| Execute and validate a model | `forgecad run model.forge.js` | Object summaries, volumes, bounds, construction history, parameters, verification results, collisions, spatial relationships, and solver diagnostics. |
-| 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. |
-| Override parameters | `forgecad run model.forge.js -p "Width=120"` | Checks a model at a specific parameter value without editing source. |
-| Sweep parameter ranges | `forgecad check params model.forge.js --samples 12` | Finds parameter values that crash, collapse geometry, or introduce new collisions. |
-| Produce visual evidence | `forgecad render 3d model.forge.js --camera iso` | PNG viewport renders from deterministic camera angles. |
-| Inspect geometry channels | `forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness --force` | A bundle with manifest plus RGB, mask, collision, wall-thickness, depth, normal, connectivity, distance, and section channels. |
-| 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` | Pro export paths for CAD interchange, reports, and sheet workflows. |
-| Sync hosted projects | `forgecad project pull`, `forgecad project push`, `forgecad publish` | Local-agent workflow connected to forgecad.io projects and shares. |
+`forgecad project push` does not initialize a random folder. If the folder has no `forgecad.json`, the command fails and tells you to run `forgecad project init` or `forgecad project clone <slug>` first.
 
-For a full command reference, see [ForgeCAD CLI](../CLI.md).
+`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.
 
 ## Install Skills For Local Coding Agents
 
@@ -75,7 +73,7 @@ Install the ForgeCAD public skill library:
 forgecad skill install
 ```
 
-By default this installs the generated `forgecad` skill plus the public companion workflow skills into the known global skill directories for generic agents, Claude Code, Codex, and OpenCode:
+By default this installs the generated `forgecad` skill plus the public companion workflow skills into known global agent skill directories:
 
 ```text
 ~/.agents/skills/forgecad/SKILL.md
@@ -87,7 +85,7 @@ By default this installs the generated `forgecad` skill plus the public companio
 Use `--target` when you want to install or update only one agent location:
 
 | Agent | Command | Installs into |
-| --- | --- | --- |
+|---|---|---|
 | All known global agent locations | `forgecad skill install` | all targets below |
 | Generic agent-compatible tools | `forgecad skill install --target agents` | `~/.agents/skills/` |
 | Claude Code | `forgecad skill install --target claude` | `~/.claude/skills/` |
@@ -96,13 +94,13 @@ Use `--target` when you want to install or update only one agent location:
 
 Reload the agent after installing or upgrading ForgeCAD so it reloads the updated skill files.
 
-To verify installation, check the filesystem path for your target and then ask the agent:
+To verify installation, ask the agent:
 
 ```text
 What ForgeCAD skills are available?
 ```
 
-You should see `forgecad` plus companion skills such as `forgecad-make-a-model`, `forgecad-render-inspect`, and `forgecad-lld`.
+You should see `forgecad` plus companion skills such as `forgecad-make-a-model`, `forgecad-render-inspect`, `forgecad-lld`, and `forgecad-project`.
 
 If you only want the core modeling skill without companion workflows:
 
@@ -119,12 +117,98 @@ 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.
+
+### First Smoke Test
+
+```text
+Use the ForgeCAD skills. Work in this project folder. Open the existing
+.forge.js files, make a small visible change to the bracket, validate with
+forgecad run, render one ISO view, and tell me the exact commands you ran.
+```
+
+### New Model
+
+```text
+Use the ForgeCAD skills. Build a real ForgeCAD model in this project folder.
+Create or edit .forge.js files only inside this project. Use parameters for the
+main dimensions. Validate with forgecad run, render at least one 3D view, run
+forgecad check params if the model has parameters, and push with forgecad
+project push when the result is ready for the browser.
+```
+
+### Mechanism Or Assembly
+
+```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, render inspect channels
+rgb,mask,collisions, and run parameter checks before calling it done.
+```
+
+### Image Or Product Replication
+
+```text
+Use the ForgeCAD image-replication workflow. Treat the reference images as
+evidence, infer dimensions explicitly, build real CAD geometry, and compare
+renders against the references. Do not stop at a decorative approximation.
+Validate with forgecad run and render inspect before finalizing.
+```
+
+## What Makes AI Results Better
+
+Good AI-generated CAD usually needs more than one prompt. Give the agent the same inputs a strong human modeler would need:
+
+- Purpose: what the object is for and what matters most.
+- Scale: real dimensions, units, tolerances, and allowed simplifications.
+- References: sketches, photos, screenshots, existing `.forge.js` examples, or comparable parts.
+- Constraints: printability, assembly motion, clearances, wall thickness, fasteners, export format.
+- Quality bar: which checks must pass before the work is accepted.
+
+For complex artifacts, ask for staged work:
+
+```text
+First write a short build plan with parts, parameters, and verification checks.
+Then implement the smallest useful blockout, run it, render it, and iterate.
+Only add details after the proportions and assembly relationships are correct.
+```
+
+Do not accept a model just because it renders. CAD quality comes from command evidence:
+
+- `forgecad run` confirms the script executes and reports geometry diagnostics.
+- `forgecad render 3d` gives visual views from deterministic cameras.
+- `forgecad render inspect` checks object masks, collisions, thickness, sections, depth, normals, and connectivity.
+- `forgecad check params` catches broken parameter ranges.
+- `forgecad export ...` verifies the actual manufacturing or interchange output.
+
+## What The CLI Gives An Agent
+
+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` | Object summaries, volumes, bounds, construction history, parameters, verification results, collisions, spatial relationships, and solver diagnostics. |
+| 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. |
+| Override parameters | `forgecad run model.forge.js -p "Width=120"` | Checks a model at a specific parameter value without editing source. |
+| Sweep parameter ranges | `forgecad check params model.forge.js --samples 12` | Finds parameter values that crash, collapse geometry, or introduce new collisions. |
+| Produce visual evidence | `forgecad render 3d model.forge.js --camera iso` | PNG viewport renders from deterministic camera angles. |
+| Inspect geometry channels | `forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness --force` | A bundle with manifest plus RGB, mask, collision, wall-thickness, depth, normal, connectivity, distance, and section channels. |
+| 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 publish` | Local-agent workflow connected to forgecad.io projects and shares. |
+
+For the full command reference, see [ForgeCAD CLI](../CLI.md).
+
 ## Public Skill Library
 
 `forgecad skill install` installs the core modeling skill and the public companion skills.
 
 | Skill | Use it for |
-| --- | --- |
+|---|---|
 | `forgecad` | Core model authoring, editing, debugging, imports, assembly, render/export commands, and CLI validation. |
 | `forgecad-prepare-prompt` | Turning a fuzzy physical-product request into a concrete build brief and modeling prompt. |
 | `forgecad-high-level-spec` | Writing an HLD before modeling: requirements, alternatives, decisions, and open questions. |
@@ -137,7 +221,6 @@ Use `--dev` only for work on ForgeCAD itself. It includes compiler internals, so
 | `forgecad-api-dogfood` | Building a real model while recording API friction and concrete improvement proposals. |
 | `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. |
-| `forgecad-deep-dive` | Writing a linked concept-tree folder that explains a ForgeCAD idea, architecture area, scientific concept, or future feature. |
 
 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:
 
@@ -145,45 +228,6 @@ The source prompts live in the repository under `skills/`. Public export is cont
 npm run sync:public-skills -- --list
 ```
 
-## Flattened Skill Files
-
-If an agent or chat product works better with one Markdown file per skill, export the bundled skill set into a folder:
-
-```bash
-forgecad skill flattened-files ~/Desktop/forgecad-skills
-```
-
-This writes `forgecad.md` plus one flattened Markdown file per bundled companion skill. Each file includes the skill prompt and any bundled helper files, so it can be moved into tools that cannot install multi-file skills directly.
-
-## Recommended Agent Workflow
-
-Start by choosing the right mode:
-
-| Task | Recommended setup |
-| --- | --- |
-| Build or edit a model | Install `forgecad skill install`; ask the agent to use `forgecad-make-a-model` or `forgecad`. |
-| Convert a vague idea into a buildable artifact | Use `forgecad-prepare-prompt`, then `forgecad-high-level-spec`, then `forgecad-lld`, then `forgecad-make-a-model`. |
-| Build a mechanism or multi-part assembly | Use `forgecad-component-model` with the core `forgecad` skill. |
-| Validate existing geometry | Use `forgecad-render-inspect` plus `forgecad run --connectivity` and `forgecad check params`. |
-| Improve ForgeCAD's API by dogfooding | Use `forgecad-api-dogfood`; save the friction report beside the model. |
-
-A good implementation prompt for Codex or Claude Code:
-
-```text
-Use the ForgeCAD skills. Build this as real ForgeCAD geometry in a .forge.js file.
-Validate with forgecad run. Render at least one 3D view. If the model has
-parameters, run forgecad check params before calling it done.
-```
-
-For assemblies, be stricter:
-
-```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 and render inspect
-channels rgb,mask,collisions.
-```
-
 ## Chat UI Workflow
 
 If the AI tool cannot read local skills or run shell commands, export a single context file:
@@ -195,16 +239,24 @@ forgecad skill one-file ~/Desktop/forgecad-context.md
 Paste that file into an approved chat model, then work in a manual loop:
 
 1. Ask the model to generate or edit a `.forge.js` file.
-2. Save the file locally.
+2. Save the file inside an initialized ForgeCAD project folder.
 3. Run `forgecad run <file>`.
 4. Paste errors, diagnostics, and render observations back into the chat.
-5. Iterate until `forgecad run`, renders, and parameter checks are clean.
+5. Iterate until `forgecad run`, renders, exports, and parameter checks are clean.
 
-This is weaker than Codex or Claude Code with installed skills because the model cannot directly inspect files or run the CLI. It is still useful for short models and API questions.
+This is weaker than Codex, Claude Code, or another local agent with installed skills because the model cannot directly inspect files or run the CLI. It is still useful for short models and API questions.
+
+If an agent or chat product works better with one Markdown file per skill, export the bundled skill set into a folder:
+
+```bash
+forgecad skill flattened-files ~/Desktop/forgecad-skills
+```
 
 ## Completion Criteria
 
-Do not call an AI-authored ForgeCAD model complete until it passes the relevant checks:
+Do not call an AI-authored ForgeCAD model complete until it passes the relevant checks.
+
+For a simple part:
 
 ```bash
 forgecad run model.forge.js
@@ -212,16 +264,57 @@ forgecad render 3d model.forge.js --camera iso
 forgecad check params model.forge.js --samples 8
 ```
 
-For mechanisms, dense assemblies, printable parts, or anything safety-adjacent, add inspection:
+For mechanisms, dense assemblies, printable parts, or anything safety-adjacent:
 
 ```bash
 forgecad run model.forge.js --connectivity
 forgecad render inspect model.forge.js --channels rgb,mask,collisions,thickness,section --force
+forgecad check params model.forge.js --samples 12
 ```
 
-For export work, verify the actual output command, not just the viewport:
+For export work, verify the actual output command:
 
 ```bash
 forgecad export stl model.forge.js
 forgecad export 3mf model.forge.js --quality high
+forgecad export step model.forge.js
+```
+
+For hosted work, push the verified state:
+
+```bash
+forgecad project push
+forgecad project open
 ```
+
+## Screenshots And Videos To Make
+
+Good screenshots:
+
+| Screenshot | What it should show |
+|---|---|
+| Hosted `Start Here` | Browser editor, `00-start-here.forge.js`, parameters, and viewport in one frame. |
+| Project setup terminal | `npm install -g forgecad`, `forgecad login`, `forgecad project clone start-here`, `cd start-here`, `forgecad studio .`. |
+| New project terminal | `mkdir`, `project init`, `forgecad new`, `forgecad studio .`, with `forgecad.json` visible in the file tree. |
+| Agent prompt | The exact prompt and the project folder context. |
+| CLI validation | `forgecad run`, `render inspect`, and `check params` outputs with a clean final result. |
+| Browser sync | `forgecad project push` followed by the updated model open in the hosted browser. |
+
+Good short videos:
+
+| Video | Structure |
+|---|---|
+| First project in five minutes | Install, login, clone Start Here, run one file, open `forgecad studio .`, change a parameter. |
+| New project from terminal to browser | `project init`, `forgecad new`, agent edits, validation, `project push`, hosted browser opens. |
+| AI builds a useful part | Show the prompt, time-lapse the agent iterations, then slow down for the final `run`, render, inspect, and export evidence. |
+| Debugging with inspect bundles | Start with a collision or thin-wall issue, show `render inspect`, fix, rerun, and compare before/after. |
+| From reference image to CAD | Show reference images, build plan, rough blockout, improved geometry, render comparison, and final export. |
+
+AI can take a while. Do not publish the whole wait in real time. Record the full session for trust, then edit it into a clear artifact:
+
+- Keep the exact prompt on screen long enough to read.
+- Speed up waiting, installs, and repeated command output.
+- Use chapter cards: prompt, first run, first render, inspection failure, fix, final evidence, browser sync.
+- Capture the browser viewport after each meaningful iteration so viewers can see progress.
+- Keep the final validation commands at normal speed.
+- End with the project URL, exported file, or published share rather than a vague "looks good" moment.

package/dist/docs-raw/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/docs-raw/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