forgecad 0.9.2 → 0.9.3

package/dist/docs-raw/welcome.md

@@ -1,192 +1,140 @@
 # Welcome to ForgeCAD
 
-ForgeCAD is code-first CAD. A model is a normal `.forge.js` file, the browser gives you an immediate 3D workbench, and the CLI gives you the serious local loop for agents, validation, rendering, export, and sync.
+ForgeCAD is code-first CAD. A model is a normal `.forge.js` file, the browser is the live workbench, and the CLI is the reliable loop for validation, rendering, export, AI agents, and sync.
+
+The most important rule: work in a dedicated ForgeCAD project folder. Do not run ForgeCAD from your home directory, downloads folder, desktop, or a huge source tree. Use a small folder that contains the model, helper files, SVG/reference assets, and generated inspection evidence for one project.
 
 ## First 10 Minutes
 
-Start with the `Start Here` project. New accounts get these files automatically. If your account was created before the starter project existed, create the files from the code below.
+There are two good ways to start.
+
+### Start From The Browser
 
-Open these files in order:
+New accounts get a `Start Here` project automatically. Open it in the browser and try these files in order:
 
 | File | What to try |
 |---|---|
 | `00-start-here.forge.js` | Change a parameter and watch the model update. |
-| `01-parametric-bracket.forge.js` | Inspect a more realistic part with holes and proportions. |
+| `01-parametric-bracket.forge.js` | Inspect a realistic part with holes and proportions. |
 | `02-assembly-basics.forge.js` | See how multiple parts can be arranged together. |
 
-Do not try to learn the entire API first. The first useful loop is smaller:
+Then clone that same project locally:
 
-```text
-edit one number -> run -> inspect the model -> repeat
+```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 .
 ```
 
-### `00-start-here.forge.js`
+`forgecad studio .` opens the local editor around the current project folder. The `.` is not optional; `forgecad studio` requires a project path.
 
-```js
-// Welcome to ForgeCAD.
-// Try changing the Width or Height sliders, then watch the model update.
-//
-// When you are ready to work locally:
-//   npm install -g forgecad
-//   forgecad login
-//   # or, for GitHub/Google accounts: forgecad login --token
-//   forgecad project clone start-here
-//   cd start-here
-//   forgecad studio .
-//
-// More orientation: https://forgecad.io/docs/welcome
-
-const width = Param.number("Width", 80, { min: 40, max: 140, unit: "mm" });
-const depth = Param.number("Depth", 50, { min: 30, max: 90, unit: "mm" });
-const height = Param.number("Height", 18, { min: 8, max: 40, unit: "mm" });
-const holeRadius = Param.number("Hole Radius", 6, { min: 2, max: 12, unit: "mm" });
-
-const plate = box(width, depth, height)
-  .subtract(cylinder(height * 2, holeRadius))
-  .color("#5b9bd5");
-
-return { "starter plate": plate };
-```
+### Create A New Local Project
 
-### `01-parametric-bracket.forge.js`
+Use this when you want a fresh model instead of the starter project:
 
-```js
-// A small parametric bracket.
-// This file shows the normal ForgeCAD rhythm:
-// parameters -> primitives -> booleans -> named result.
-
-const width = Param.number("Width", 90, { min: 60, max: 150, unit: "mm" });
-const depth = Param.number("Depth", 64, { min: 42, max: 100, unit: "mm" });
-const height = Param.number("Height", 70, { min: 40, max: 120, unit: "mm" });
-const plate = Param.number("Plate", 8, { min: 4, max: 14, unit: "mm" });
-const holeRadius = Param.number("Hole Radius", 4, { min: 2, max: 8, unit: "mm" });
-const spacing = Param.number("Hole Spacing", 48, { min: 24, max: 80, unit: "mm" });
-
-const base = box(width, depth, plate);
-const upright = box(width, plate, height).translate(0, -depth / 2 + plate / 2, plate);
-
-const baseHoles = [-spacing / 2, spacing / 2].map((x) =>
-  cylinder(plate * 3, holeRadius).translate(x, depth * 0.18, -plate)
-);
-
-const uprightHoles = [-spacing / 2, spacing / 2].map((x) =>
-  cylinder(plate * 3, holeRadius)
-    .pointAlong([0, 1, 0])
-    .translate(x, -depth / 2 - plate, plate + height * 0.58)
-);
-
-const bracket = union(base, upright)
-  .subtract(...baseHoles, ...uprightHoles)
-  .color("#6aa84f");
-
-return { "parametric bracket": bracket };
+```bash
+npm install -g forgecad
+forgecad login
+mkdir spool-adapter
+cd spool-adapter
+forgecad project init "Spool Adapter" --visibility private
+forgecad new adapter --template part
+forgecad studio .
 ```
 
-### `02-assembly-basics.forge.js`
+`forgecad project init` creates the hosted project, writes `forgecad.json`, and uploads any existing local `.forge.js`, `.js`, and `.svg` files. After that, `forgecad project push` syncs changes back to the hosted project.
 
-```js
-// A tiny multi-part scene.
-// ForgeCAD projects are just code, so assemblies can be built from ordinary
-// variables and functions before you move into richer connector workflows.
-
-const spread = Param.number("Spread", 0, { min: 0, max: 40, unit: "mm" });
-const postHeight = Param.number("Post Height", 34, { min: 20, max: 70, unit: "mm" });
-
-const base = box(110, 42, 8)
-  .color("#4f6f8f");
-
-function makePost(x, color) {
-  return cylinder(postHeight, 7)
-    .translate(x, 0, 8)
-    .color(color);
-}
-
-const leftPost = makePost(-28 - spread, "#c76d39");
-const rightPost = makePost(28 + spread, "#d9a441");
-const cap = box(82 + spread * 2, 18, 8)
-  .translate(0, 0, 8 + postHeight)
-  .color("#8e5ea2");
-
-return assembly("Assembly Basics")
-  .addPart("Base Rail", base)
-  .addPart("Left Post", leftPost)
-  .addPart("Right Post", rightPost)
-  .addPart("Top Cap", cap);
-```
+`forgecad project push` does not create a remote project from an arbitrary folder. If a folder has no `forgecad.json`, initialize it with `forgecad project init` or clone an existing project first.
 
-## Move to the CLI
+## Why Projects Matter
 
-The browser is the fastest way to see ForgeCAD. The CLI is the way to make it part of your real workflow.
+ForgeCAD commands need a project root so imports, helper files, SVGs, and generated evidence resolve consistently.
 
-Install the CLI:
+A single loose `.forge.js` file is fine for a tiny experiment, but it is not the best workflow for useful AI-generated CAD. A project folder gives the agent and CLI enough context to work well:
 
-```bash
-npm install -g forgecad
-```
+- `forgecad.json` links the folder to the hosted project.
+- `.forge.js`, `.js`, and `.svg` files stay together.
+- `forgecad run` and render commands resolve local imports from the intended root.
+- `forgecad project push` knows exactly which remote project to update.
+- Inspection bundles, screenshots, and export outputs can live beside the model without mixing with unrelated files.
 
-If your ForgeCAD account uses email and password, log in directly:
+Bad roots create bad results. Pointing ForgeCAD or an AI agent at `~`, a monorepo, or a downloads folder can make file discovery slow, confusing, or effectively unusable. Start small and intentional:
 
-```bash
-forgecad login
+```text
+good:  ~/cad/spool-adapter/
+good:  ~/Projects/forgecad/start-here/
+bad:   ~/
+bad:   ~/Downloads/
+bad:   ~/Projects/
 ```
 
-If your account was created through GitHub or Google, create an API token in `Settings > API Tokens`, then log in with the token:
-
-```bash
-forgecad login --token
-```
+## First Script
 
-Clone your starter project locally:
+Inside a cloned or initialized ForgeCAD project, create `starter.forge.js`:
 
-```bash
-forgecad project clone start-here
-cd start-here
-forgecad studio .
-```
+```js
+const width = Param.number("Width", 90, { min: 50, max: 160, unit: "mm" });
+const depth = Param.number("Depth", 56, { min: 32, max: 100, unit: "mm" });
+const height = Param.number("Height", 12, { min: 6, max: 32, unit: "mm" });
+const holeRadius = Param.number("Hole Radius", 5, { min: 2, max: 10, unit: "mm" });
 
-Then validate and render from the terminal:
+const base = box(width, depth, height).color("#5f87c6");
+const hole = cylinder(height * 3, holeRadius).translate(0, 0, -height);
 
-```bash
-forgecad run 00-start-here.forge.js
-forgecad render 3d 01-parametric-bracket.forge.js
+return {
+  "starter plate": base.subtract(hole),
+};
 ```
 
-Push local changes back to the hosted project:
+Validate it and open the editor:
 
 ```bash
-forgecad project push
+forgecad run starter.forge.js
+forgecad studio .
 ```
 
-## Use an AI Coding Agent
+## Use An AI Coding Agent
 
-ForgeCAD works well with coding agents because the source of truth is plain code.
+ForgeCAD works well with coding agents because the source of truth is plain code and the CLI can prove whether the model still runs.
 
-For the full setup, approved model list, and installable skill library, see [AI Usage](AI/usage.md).
-
-Install the agent skill library:
+Install the public skill library:
 
 ```bash
 forgecad skill install
 ```
 
-This installs the core `forgecad` skill plus public workflow skills such as `forgecad-make-a-model` and `forgecad-render-inspect` into the known global skill directories for generic agents, Claude Code, Codex, and OpenCode. Use `--target` when you want to update only one agent location:
+Then start your agent from inside the project folder and give it a concrete job:
 
-```bash
-forgecad skill install --target claude
-forgecad skill install --target opencode
-forgecad skill install --target codex
+```text
+Use the ForgeCAD skills. Work in this project folder. Build or edit real
+ForgeCAD geometry in .forge.js files. Validate with forgecad run, render at
+least one 3D view or inspect bundle, and run parameter checks before calling it done.
 ```
 
-Then ask your agent to edit the local `.forge.js` files and verify with CLI commands such as:
+The strongest loop is:
+
+```text
+agent edits files -> forgecad run -> render or inspect -> fix -> check params -> project push
+```
+
+Useful commands:
 
 ```bash
-forgecad run 01-parametric-bracket.forge.js
-forgecad render inspect 01-parametric-bracket.forge.js --channels rgb,mask
+forgecad run adapter.forge.js
+forgecad render 3d adapter.forge.js --camera iso
+forgecad render inspect adapter.forge.js --channels rgb,mask,collisions,thickness --force
+forgecad check params adapter.forge.js --samples 8
+forgecad project push
+forgecad project open
 ```
 
-This is the strongest workflow: the agent writes code, the CLI checks geometry, and the browser gives you fast visual inspection.
+For the full approved model list, agent setup, quality guidance, and recording ideas, see [AI Usage](AI/usage.md).
 
-## Where to Go Next
+## Where To Go Next
 
 | Goal | Start here |
 |---|---|
@@ -194,6 +142,6 @@ This is the strongest workflow: the agent writes code, the CLI checks geometry,
 | Build sketches and extrusions | [Sketches](/docs/sketch) |
 | Build assemblies | [Assembly](/docs/assembly) |
 | Export files and renders | [Output](/docs/output) and [CLI](/docs/cli) |
-| Try another concrete model pattern | Open `01-parametric-bracket.forge.js` or `02-assembly-basics.forge.js`, then browse the [public repo examples](https://github.com/KoStard/ForgeCAD/tree/mainline/examples/api) |
+| Try concrete examples | Browse the [public repo examples](https://github.com/KoStard/ForgeCAD/tree/mainline/examples/api) |
 
-If you get lost, come back to the starter project and change one thing at a time. The whole product grows from that loop.
+If you get lost, return to the `Start Here` project, change one number, run the file, and inspect the result. ForgeCAD grows from that loop.

package/dist/index.html

@@ -55,7 +55,7 @@
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body, #root { width: 100%; min-height: 100%; background: var(--fc-bg); color: var(--fc-text); font-family: system-ui, -apple-system, sans-serif; }
     </style>
-    <script type="module" crossorigin src="/assets/app-BdBoMQeO.js"></script>
+    <script type="module" crossorigin src="/assets/app-CWucmnLZ.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/app-aLOpQQza.css">
   </head>
   <body>

package/dist/llms.txt

@@ -4,14 +4,15 @@
 
 ForgeCAD turns ordinary `.forge.js` files into live CAD models. Parameters become sliders, scripts return shapes or assemblies, and the same source can be validated, rendered, inspected, and exported from the command line.
 
-For coding agents, start with the welcome guide, then read the relevant raw Markdown docs and examples before editing model code. ForgeCAD models use millimeters by default, expose parameters through `Param.*`, and should be verified with `forgecad run` or `forgecad render inspect` when shell access is available.
+For coding agents, start with the welcome guide and AI Usage guide, then read the relevant raw Markdown docs and examples before editing model code. Work inside a dedicated ForgeCAD project folder with `forgecad.json`; do not use a home directory, downloads folder, desktop, or broad repository root as the project context. ForgeCAD models use millimeters by default, expose parameters through `Param.*`, and should be verified with `forgecad run`, `forgecad render inspect`, and `forgecad check params` when shell access is available. Project imports must include the full extension: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for helper modules.
 
 ## Start Here
 
 - [ForgeCAD browser app](https://forgecad.io/): Hosted CAD workbench for editing, previewing, sharing, and publishing parametric models.
-- [Welcome guide](https://forgecad.io/docs-raw/welcome.md): First model, first CLI loop, and the fastest route into ForgeCAD.
+- [Welcome guide](https://forgecad.io/docs-raw/welcome.md): Project setup, local editor, browser sync, and the first AI loop.
+- [AI Usage guide](https://forgecad.io/docs-raw/AI/usage.md): Approved models, project-first agent setup, skills, validation gates, quality prompts, and recording ideas.
 - [Documentation home](https://forgecad.io/docs): Human-readable documentation with search and navigation.
-- [CLI reference](https://forgecad.io/docs-raw/CLI.md): Install, login, open studios, run scripts, render, export, inspect, and sync projects.
+- [CLI reference](https://forgecad.io/docs-raw/CLI.md): Install, login, create projects, open studios with explicit paths, run scripts, render, export, inspect, and sync.
 
 ## API Reference
 

package/dist/sitemap.xml

@@ -2,37 +2,37 @@
 <urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
   <url>
     <loc>https://forgecad.io/</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>weekly</changefreq>
     <priority>1.0</priority>
   </url>
   <url>
     <loc>https://forgecad.io/docs</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.8</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.7</priority>
   </url>
   <url>
     <loc>https://forgecad.io/pricing</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://forgecad.io/examples</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>weekly</changefreq>
     <priority>0.6</priority>
   </url>
   <url>
     <loc>https://forgecad.io/blog/hello-forgecad-io</loc>
-    <lastmod>2026-05-03</lastmod>
+    <lastmod>2026-05-06</lastmod>
     <changefreq>monthly</changefreq>
     <priority>0.5</priority>
   </url>