forgecad 0.9.2 → 0.9.3

package/dist/docs-raw/INDEX.md

@@ -1,96 +1,113 @@
 # ForgeCAD Documentation
 
-Central entry point for all ForgeCAD documentation. Start here.
+Start here if you are new to ForgeCAD, setting up the CLI, or giving a project to an AI coding agent.
 
----
+## The Happy Path
 
-## Start Here
-
-- **[Welcome](welcome.md)** - First model, first CLI loop, and first AI-assisted iteration
-- **[AI Usage](AI/usage.md)** - Approved models, CLI validation loop, Codex/Claude Code setup, installable skills, and completion criteria for AI-authored models
-
----
-
-## Operations & Runbook
+ForgeCAD works best when every model lives in a real project folder:
 
-The first place to look when debugging, deploying, or onboarding.
+```bash
+npm install -g forgecad
+forgecad login
+mkdir spool-adapter
+cd spool-adapter
+forgecad project init "Spool Adapter"
+forgecad new adapter --template part
+forgecad studio .
+```
 
-- **[Runbook](runbook.md)** — Dev server commands, local stack setup, health checks, production SSH, incident workflow, troubleshooting
-- **[Deployment & Environment](deployment.md)** — Kamal architecture, environment variables, deploy/rollback flow, database migrations
-- **[Observability](platform/observability.md)** — Grafana, Loki, Prometheus, Uptime Kuma, dashboards, logs, metrics, incident debugging
-- **[Releasing](RELEASING.md)** — npm version, publish workflow, GitHub Releases
+Then let your AI agent work inside that same folder, validate the model from the terminal, and push the result back to the browser:
 
----
+```bash
+forgecad run adapter.forge.js
+forgecad render inspect adapter.forge.js --channels rgb,mask,collisions --force
+forgecad check params adapter.forge.js --samples 8
+forgecad project push
+forgecad project open
+```
 
-## Platform (Web App)
+`forgecad studio` always needs an explicit project path. Use `.` for the current project. Do not point it at `~`, your whole desktop, downloads, or a huge source tree; ForgeCAD and AI agents need a small folder containing only the model, helper files, references, and generated evidence for that project.
 
-Documentation for the hosted service at forgecad.io.
-
-- **[First Account Onboarding](product/onboarding-first-experience.md)** — Source of truth for new-account starter project, Welcome docs, and CLI bridge
-- **[System Architecture](platform/architecture.md)** — Stack overview, URL routes, Docker topology, security
-- **[Authentication](platform/auth.md)** — JWT tokens, OAuth (GitHub/Google), registration, password reset, session management
-- **[Projects & Files](platform/projects.md)** — Project CRUD, member roles, file storage, storage quotas, SSE watching
-- **[Model Sharing](platform/sharing.md)** — Publishing, public URLs, embeds, gist/URL/inline sharing
-- **[Admin Dashboard](platform/admin.md)** — Admin panel, audit log, user management
-- **[Email Delivery](platform/email.md)** — Resend setup, verification emails, password reset emails
+## Start Here
 
----
+- **[Welcome](welcome.md)** - First model, project setup, local editor, browser sync, and the AI-assisted loop.
+- **[AI Usage](AI/usage.md)** - Approved models, project-first agent setup, skill installation, quality prompts, validation evidence, and media ideas.
+- **[CLI Reference](CLI.md)** - Install, login, create projects, open local studios, run scripts, render, inspect, export, publish, and sync.
 
-## CLI
+## Project Workflow
 
-- **[CLI Reference](CLI.md)** — Full command reference: dev/studio servers, export (STL/STEP/SVG/G-code/SDF), render, capture, invariant checks
-- **[Inspection Bundles](guides/inspection-bundles.md)** — `render inspect` bundle layout, channel encodings, manifest semantics, and agent workflow
-- **[Monetization & Licensing](project/cli-monetization.md)** — Free vs Pro tiers, license activation, feature gating strategy
+Use this section when the question is "how do I actually start?"
 
----
+- **Create a new hosted project locally**: `forgecad project init "Project Name"` creates the remote project, writes `forgecad.json`, and uploads any existing local `.forge.js`, `.js`, and `.svg` files.
+- **Clone an existing hosted project**: `forgecad project clone <slug>` downloads files and writes `forgecad.json`.
+- **Open the local editor**: `forgecad studio .` opens the installed local editor around the current project folder.
+- **Sync back to the browser**: `forgecad project push` uploads local changes for an initialized project. It does not create a remote project from a random folder; run `project init` first.
 
-## API Reference (Model Authoring)
+## API Reference
 
 For users writing `.forge.js` scripts.
 
-- **[API Overview](API/README.md)** — Reading plan and orientation
-- **Sketches**: [Core](API/sketch/core.md) | [Primitives](API/sketch/primitives.md) | [Paths](API/sketch/path.md) | [Booleans](API/sketch/booleans.md) | [Operations](API/sketch/operations.md) | [Extrude/Revolve](API/sketch/extrude.md) | [Transforms](API/sketch/transforms.md) | [Regions](API/sketch/regions.md) | [Text](API/sketch/text.md) | [Anchoring](API/sketch/anchor.md) | [On-Face](API/sketch/on-face.md)
-- **Assembly**: [Assembly & Kinematics](API/assembly/assembly.md)
-- **Output**: [Export](API/output/export.md) | [BREP/STEP](API/output/brep-export.md) | [G-code](API/output/gcode.md) | [Dimensions](API/output/dimensions.md) | [BOM](API/output/bom.md)
-- **Other**: [Sheet Metal](API/sheet-metal/sheet-metal.md) | [Fasteners](API/toolbox/fasteners.md) | [Viewport](API/runtime/viewport.md)
-- **Core Concepts**: [Concepts](API/core/concepts.md) | [Parameters](API/core/parameters.md) | [Topology](API/core/topology.md) | [Edge Queries](API/core/edge-queries.md) | [Specs](API/core/specs.md) | [SDF](API/core/sdf-primitives.md)
-- **[Auto-Generated API Docs](generated/)** — Machine-generated from `forge-public-api.ts`
-
----
-
-## Guides (Modeling)
+- **[API Overview](API/README.md)** - Reading plan and orientation
+- **[Core](generated/core.md)** - Primitives, booleans, transforms, colors, materials, patterns, and shape operations
+- **[Sketches](generated/sketch.md)** - 2D geometry, constraints, profiles, extrusion, offsets, and sketch-driven modeling
+- **[Curves & Surfaces](generated/curves.md)** - Splines, lofts, sweeps, ruled surfaces, and exact surface workflows
+- **[Assembly](generated/assembly.md)** - Parts, connectors, joints, kinematics, collision checks, and exploded views
+- **[Output](generated/output.md)** - Exports, reports, BOMs, dimensions, robot packages, G-code, and manufacturing outputs
+- **[Library](generated/lib.md)** - Gears, fasteners, pipes, pulleys, belts, springs, and reusable helpers
+- **[Sheet Metal](generated/sheet-metal.md)** - Bends, flanges, flat patterns, reliefs, and sheet workflows
+- **[Viewport](generated/viewport.md)** - Cameras, animations, labels, views, and scene controls
+- **[SDF](generated/sdf.md)** - Organic fields, TPMS structures, smooth booleans, and implicit geometry
+- **[Concepts](generated/concepts.md)** - Semantic data structures and conceptual building blocks
+- **[Core Concepts](API/core/concepts.md)** - Permanent notes for core modeling concepts
+
+## Guides
 
 Techniques and conventions for model authors.
 
-- **[Coordinate System](guides/coordinate-system.md)** — Z-up convention, axis orientation
-- **[Geometry Conventions](guides/geometry-conventions.md)** — Winding order, depth, normals
-- **[Positioning](guides/positioning.md)** — Connectors, `matchTo()`, and placement strategies
-- **[Modeling Recipes](guides/modeling-recipes.md)** — Common patterns, iteration, multi-file composition
-- **[Skill Maintenance](guides/skill-maintenance.md)** — AI skill build process, `npm run refresh`
+- **[Coordinate System](guides/coordinate-system.md)** - Z-up convention, axis orientation
+- **[Geometry Conventions](guides/geometry-conventions.md)** - Winding order, depth, normals
+- **[Positioning](guides/positioning.md)** - Connectors, `matchTo()`, and placement strategies
+- **[Modeling Recipes](guides/modeling-recipes.md)** - Common patterns, iteration, multi-file composition
+- **[Joint Design](guides/joint-design.md)** - Connectors, joints, and mechanisms
+- **[Inspection Bundles](guides/inspection-bundles.md)** - `render inspect` bundle layout, channel encodings, manifest semantics, and agent workflow
+- **[Component Model](component-model.md)** - Recommended assembly structure for multi-part projects
+- **[Skill Maintenance](guides/skill-maintenance.md)** - AI skill build process, `npm run refresh`
 
----
+## Platform
 
-## Engine Internals
+Documentation for the hosted service at forgecad.io.
 
-For contributors working on ForgeCAD's core engine.
+- **[First Account Onboarding](product/onboarding-first-experience.md)** - Source of truth for new-account starter project, Welcome docs, and CLI bridge
+- **[User Outreach Email Templates](product/user-outreach-email-templates.md)** - Founder-style templates for Pro users, active users, team onboarding, and follow-ups
+- **[System Architecture](platform/architecture.md)** - Stack overview, URL routes, Docker topology, security
+- **[Authentication](platform/auth.md)** - JWT tokens, OAuth, registration, password reset, session management
+- **[Projects & Files](platform/projects.md)** - Project CRUD, member roles, file storage, storage quotas, SSE watching
+- **[Model Sharing](platform/sharing.md)** - Publishing, public URLs, embeds, gist/URL/inline sharing
+- **[Admin Dashboard](platform/admin.md)** - Admin panel, audit log, user management
+- **[Email Delivery](platform/email.md)** - Resend setup, verification emails, password reset emails
 
-- **[Backend Vocabulary](internals/backend-vocabulary.md)** — Canonical Forge terms for compile plans, backends, capabilities, and routes
-- **[Compiler](internals/compiler.md)** — Multi-backend architecture, compile plans, lowering
-- **[Constraint Solver](internals/constraint-solver.md)** — Solver pipeline, architecture, Levenberg-Marquardt
-- **[Solver Quality](internals/constraint-solver-quality.md)** — Tunable vs architectural parameters
-- **[2D Sketch Pipeline](internals/sketch-2d-pipeline.md)** — Two-track export, ProfileCompilePlan
+## Development And Operations
 
----
+For contributors developing, deploying, or operating ForgeCAD.
 
-## Development Standards
+- **[Runbook](runbook.md)** - Dev server commands, local stack setup, health checks, production SSH, incident workflow, troubleshooting
+- **[Deployment & Environment](deployment.md)** - Kamal architecture, environment variables, deploy/rollback flow, database migrations
+- **[Observability](platform/observability.md)** - Grafana, Loki, Prometheus, Uptime Kuma, dashboards, logs, metrics, incident debugging
+- **[Releasing](RELEASING.md)** - npm version, publish workflow, GitHub Releases
+- **[CLI Monetization & Licensing](cli-monetization.md)** - Free vs Pro tiers, license activation, feature gating strategy
+- **[Coding Guidelines](coding.md)** - Project structure, workflow, adding new features
+- **[Coding Best Practices](coding-best-practices.md)** - TypeScript, React, performance, self-review
+- **[Blueprint-First Design](blueprint-first.md)** - Intent-driven API design
 
-For contributors developing ForgeCAD itself.
+## Engine Internals
 
-- **[Coding Guidelines](project/coding.md)** — Project structure, workflow, adding new features
-- **[Coding Best Practices](project/coding-best-practices.md)** — TypeScript, React, performance, self-review
-- **[Blueprint-First Design](project/blueprint-first.md)** — No trigonometry tax, intent-driven API design
+For contributors working on ForgeCAD's core engine.
 
----
+- **[Backend Vocabulary](internals/backend-vocabulary.md)** - Canonical terms for compile plans, backends, capabilities, and routes
+- **[Compiler](internals/compiler.md)** - Multi-backend architecture, compile plans, lowering
+- **[Constraint Solver](internals/constraint-solver.md)** - Solver pipeline, architecture, Levenberg-Marquardt
+- **[Solver Quality](internals/constraint-solver-quality.md)** - Tunable vs architectural parameters
+- **[2D Sketch Pipeline](internals/sketch-2d-pipeline.md)** - Two-track export, ProfileCompilePlan
 
 ## Processes
 

package/dist/docs-raw/cli-monetization.md

@@ -6,7 +6,7 @@ ForgeCAD follows a phased monetization strategy informed by how real software co
 
 ### Phase 1: Honor System (Now)
 
-Ship a compiled binary with a local license gate. Pro commands show a clear upgrade message. No enforcement beyond that.
+Ship a compiled binary with a local license gate. Production export commands stay free and show a clear commercial-use message; Pro-only render/capture commands show a clear upgrade message.
 
 **Why this works:**
 - Sublime Text makes $5-25M/year with zero enforcement (nag popup only)
@@ -17,7 +17,8 @@ Ship a compiled binary with a local license gate. Pro commands show a clear upgr
 **What we ship:**
 - Compiled native binary via `bun build --compile --minify` (source not trivially readable)
 - Local JWT license validation at `~/.forgecad/license.json`
-- Pro commands blocked with helpful message + free alternatives
+- Production outputs marked with commercial-use guidance, not blocked
+- Pro-only render/capture commands blocked with helpful message + free alternatives
 - `forgecad license activate/deactivate/status` commands
 
 **What we accept:**
@@ -37,9 +38,9 @@ These features don't need anti-piracy because they're inherently organizational.
 
 ### Phase 3: Server-Side Pro Features (Later)
 
-Move high-value exports to run on the ForgeCAD server. The CLI uploads the model, the server processes it, the CLI downloads the result.
+Move high-value compute to run on the ForgeCAD server after the security model is ready. The CLI uploads the model, the server processes it, the CLI downloads the result.
 
-**Why this is piracy-proof:** The code for STEP export, Blender rendering, and gcode computation never ships to the user. You can't crack what you don't have.
+**Why this is piracy-proof:** The code for server-only rendering, optimization, and future compute-heavy workflows never ships to the user. You can't crack what you don't have.
 
 **Proven by:**
 - Cursor: $2B ARR — the editor is free, AI calls are server-side
@@ -50,15 +51,15 @@ Move high-value exports to run on the ForgeCAD server. The CLI uploads the model
 
 | Tier | Price | Features |
 |------|-------|----------|
-| **Free** | $0 | Editor, dev server, run scripts, render PNG, export STL/3MF/SVG, all checks, debug tools |
-| **Pro** | $15-25/mo | STEP/BREP export, render-hq (Blender), capture GIF/MP4, gcode, cut-list, report PDF, cutting layout, SDF/URDF, sketch PDF |
+| **Free** | $0 | Editor, dev server, run scripts, render PNG, exports including STEP/BREP/report/layout, all checks, debug tools |
+| **Pro** | $15-25/mo | Commercial coverage, render-hq (Blender), capture GIF/MP4, 500 MB cloud storage, support for production workflows |
 | **Team** | $40-60/seat/mo | Everything in Pro + license server, floating seats, audit log, SSO, priority support |
 
 ### Why this split?
 
-**Free tier** includes everything needed to learn ForgeCAD, build models, and 3D print. This is the funnel — hobbyists, students, and evaluators use this. It's genuinely useful, not a crippled demo.
+**Free tier** includes everything needed to learn ForgeCAD, build models, export files, and 3D print. This is the funnel — hobbyists, students, and evaluators use this. It's genuinely useful, not a crippled demo.
 
-**Pro tier** gates the features professionals need: exact CAD interchange (STEP), manufacturing outputs (gcode, cut lists, cutting layouts), and presentation (render-hq, animations). These are the commands that save hours of work and justify a subscription.
+**Pro tier** covers the work professionals need to pay for: client work, employer work, funded projects, products for sale, closed commercial IP, larger hosted storage, support, and Pro-only render/capture tools. Exact and manufacturing exports remain free actions with production/commercial reminders.
 
 **Team tier** gates organizational features that individuals don't need.
 

package/dist/docs-raw/generated/concepts.md

@@ -17,7 +17,7 @@ Every public API function belongs to one of 16 fundamental concepts. This docume
 - **[C11: Parameterization & UI](#c11-parameterization-ui)** — Declare user-facing controls that drive model geometry. *(7 functions)*
 - **[C12: Dimensional Demotion](#c12-dimensional-demotion)** — Extract 2D geometry from a 3D solid (section, projection). *(3 functions)*
 - **[C13: Export & Output](#c13-export-output)** — Convert geometry to external formats (STL, 3MF, SVG, DXF, G-code, PDF). *(5 functions)*
-- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(30 functions)*
+- **[C14: Visual & Debugging](#c14-visual-debugging)** — Control viewport appearance and debugging aids. *(31 functions)*
 - **[C15: Import & Composition](#c15-import-composition)** — Bring external geometry or other ForgeCAD modules into the current script. *(1 functions)*
 - **[C16: Part Library](#c16-part-library)** — Pre-built parametric parts accessible via `lib.*`. *(4 functions)*
 
@@ -347,12 +347,38 @@ sdf.Sculpt: { sphere: (radius: number) => SdfShape; box: (x: number, y: number,
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
 **`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
 
+**`SceneJourneyConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title?` | `string` | Viewer-facing journey title. Defaults to the journey id. |
+| `startsAt?` | `string` | Optional starting step id. Defaults to the first step. |
+| `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
+| `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
+| `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
+
+**`SceneJourneyStepConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Stable step id used by viewer links and Next/Back state. |
+| `title?` | `string` | Viewer-facing title. Defaults to the step id. |
+| `focus?` | `string` | Object name or slash-separated tree path to focus. |
+| `caption?` | `string` | Short optional viewer caption. |
+| `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
+| `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
+| `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
+
+`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
+
 **`SceneLightConfig`**
 
 | Option | Type | Description |
@@ -754,6 +780,8 @@ stroke(points: [ number, number ][], width: number, join?: "Round" | "Square"):
 
 The Sketch origin is at the left end of the text baseline by default. Use `align` and `baseline` options to adjust placement. Text is rendered using the bundled Inter font by default, or any TTF/OTF/WOFF font you provide.
 
+`text2d()` creates real geometry. For non-exported explanatory labels in the viewport, prefer `Viewport.label()` so the text stays off the geometry and OCCT compile paths.
+
 Alignment reference table:
 
 | `align`    | `baseline`   | Origin                              |
@@ -2409,6 +2437,7 @@ BOM entries are accumulated during script execution and exported alongside the m
 - `quantity` must be a finite number `>= 0`. A quantity of `0` is silently ignored (useful for conditional scripting with `param()`-driven counts).
 - `unit` defaults to `"pieces"` when omitted or empty.
 - The assembly `solved.bom()` / `solved.bomCsv()` API is separate and covers per-part assembly metadata; this function is for free-form purchased-item annotation.
+- `bom()` is injected into every `.forge.js` script. Call it directly; do not write `const { bom } = require(...)`, because top-level declarations named `bom` collide with the built-in runtime name.
 
 ```ts
 const tubeLen = param("Tube Length", 1200, { min: 300, max: 4000, unit: "mm" });
@@ -2635,6 +2664,38 @@ sketchToSvg(sketch: Sketch, options?: SketchSvgOptions): string
 
 Control viewport appearance and debugging aids.
 
+#### `Viewport.label()` — Add a render-only viewport label at a world-space point.
+
+`Viewport.label()` is for explanatory text that helps a viewer understand the model. It does not create sketches, meshes, B-rep topology, exported text, or face labels, so it stays off the OCCT path. Use `text2d()` only when the letters should become manufactured geometry, such as raised lettering, engraved serial numbers, or exported nameplates.
+
+Labels are collected during script execution and rendered by the viewport as lightweight overlay annotations. They are ignored by exports and do not appear in `objects`.
+
+```js
+Viewport.label('Bearing bore', [0, 0, 18], {
+  color: '#f8fafc',
+  background: '#0f172acc',
+  offset: [0, 0, 8],
+  anchor: 'bottom',
+});
+
+return box(40, 30, 12);
+```
+
+```ts
+Viewport.label(text: string, at: [ number, number, number ], options?: RenderLabelOptions): void
+```
+
+**`RenderLabelOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `color?` | `string` | Text color as any CSS color string. |
+| `background?` | `string` | Background color as any CSS color string. Use `'transparent'` for no pill background. |
+| `size?` | `number` | Font size in CSS pixels. Defaults to 12. |
+| `offset?` | `[ number, number, number ]` | Additional world-space offset from `at`. |
+| `anchor?` | `RenderLabelAnchor` | Which point of the label box is anchored to `at`. Defaults to `'center'`. |
+| `alwaysOnTop?` | `boolean` | When false, the label is hidden when occluded by scene geometry. Defaults to true. |
+
 #### `verify.that()` — Custom predicate check.
 
 ```ts
@@ -2868,12 +2929,16 @@ mock<T extends Shape>(shape: T, name?: string): T
 
 #### `scene()` — Configure the scene environment for the current script execution.
 
-Controls camera position, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
+Controls camera position, named render views, optional model journeys, lighting rig, background color or gradient, atmospheric fog, environment maps, post-processing effects, and capture parameters for the `forgecad capture` command. Multiple calls merge — later values override earlier ones on a per-key basis, so you can split configuration across multiple `scene()` calls.
 
 When `lights` is specified, **all** default lights are removed. You must include your own ambient light or the scene will be fully dark.
 
 Setting `camera.position` overrides auto-framing — the viewport will no longer auto-fit the geometry on script reload.
 
+Named render views let scripts check in repeatable cameras next to the model code. The canonical shape is `{ camera: { position, target } }`, and a direct camera shorthand `{ position, target }` is also accepted. Use the canonical shape when you may add view metadata later. Use it from the CLI with `forgecad render 3d model.forge.js --view hero`.
+
+Model journeys let scripts check in a compact guided path through named objects. Each journey has ordered `steps`; each step can name a `focus` target by object name/tree path, provide a caption, and optionally provide an explicit camera. In the viewer, journeys are opt-in: they appear as a small Explore control and do not move the camera until the user starts them. Use `forgecad run model.forge.js --journeys` or `--journeys-json` to inspect resolved targets.
+
 Post-processing effects (`bloom`, `vignette`, `grain`) work in the browser viewport only. The CLI applies camera, lights, background, fog, and `toneMappingExposure` but skips shader effects.
 
 All numeric values accept `param()` expressions.
@@ -2882,6 +2947,22 @@ All numeric values accept `param()` expressions.
 scene({
   background: { top: '#000814', bottom: '#001d3d' },
   camera: { position: [160, -120, 100], target: [0, 0, 50], fov: 52 },
+  views: {
+    hero: {
+      camera: { position: [180, -140, 90], target: [0, 0, 25], up: [0, 0, 1], fov: 38 },
+    },
+    side: { position: [240, 0, 70], target: [0, 0, 25], fov: 34 },
+  },
+  journeys: {
+    grandTour: {
+      title: 'Grand Tour',
+      startsAt: 'overview',
+      steps: [
+        { id: 'overview', focus: 'Solar System', caption: 'Start with the whole model.' },
+        { id: 'earth', focus: 'Earth', caption: 'Fit and inspect Earth.' },
+      ],
+    },
+  },
   lights: [
     { type: 'ambient', color: '#001233', intensity: 0.08 },
     { type: 'point', position: [120, -80, 130], color: '#00f5d4', intensity: 4, distance: 400, decay: 1 },
@@ -2908,12 +2989,38 @@ scene(options: SceneOptions): void
 | Option | Type | Description |
 |--------|------|-------------|
 | `capture?` | `SceneCaptureConfig` | Default capture parameters for `forgecad capture` — CLI flags override these. |
-| `background?`, `camera?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
+| `background?`, `camera?`, `views?`, `journeys?`, `lights?`, `environment?`, `fog?`, `postProcessing?`, `ground?` | | — |
 
 `SceneBackgroundGradient`: `{ top: string, bottom: string }`
 
 **`SceneCameraConfig`**: `position?: [ number, number, number ]`, `target?: [ number, number, number ]`, `up?: [ number, number, number ]`, `fov?: number`, `type?: "perspective" | "orthographic"`
 
+**`SceneJourneyConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `title?` | `string` | Viewer-facing journey title. Defaults to the journey id. |
+| `startsAt?` | `string` | Optional starting step id. Defaults to the first step. |
+| `behavior?` | `"opt-in" \| "auto"` | Whether the viewer should offer or auto-open the journey. First slice supports opt-in. |
+| `steps` | `SceneJourneyStepConfig[]` | Ordered journey spine. Branches can be added later without changing this core contract. |
+| `valid?` | `boolean` | True unless any journey or step diagnostic has level "error". |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Whole-journey diagnostics, including unresolved startsAt and step target diagnostics. |
+
+**`SceneJourneyStepConfig`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `id` | `string` | Stable step id used by viewer links and Next/Back state. |
+| `title?` | `string` | Viewer-facing title. Defaults to the step id. |
+| `focus?` | `string` | Object name or slash-separated tree path to focus. |
+| `caption?` | `string` | Short optional viewer caption. |
+| `camera?` | `SceneViewCameraConfig` | Optional explicit camera for this step. When omitted, the viewer fits `focus`. |
+| `resolvedFocusId?` | `string \| null` | Resolved object id after script execution, when `focus` matched exactly one object. |
+| `resolvedFocusPath?` | `string \| null` | Resolved object tree path or name after script execution. |
+| `diagnostics?` | `SceneJourneyDiagnostic[]` | Resolution diagnostics for this step. |
+
+`SceneJourneyDiagnostic`: `{ level: SceneJourneyDiagnosticLevel, message: string, stepId?: string, suggestions?: string[] }`
+
 **`SceneLightConfig`**
 
 | Option | Type | Description |

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