# Welcome to ForgeCAD

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

There are two good ways to start.

### Start From The Browser

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 realistic part with holes and proportions. |
| `02-assembly-basics.forge.js` | See how multiple parts can be arranged together. |

Then clone that same project locally:

```bash
npm install -g forgecad
forgecad login
# Choose email/password or API token when prompted.
forgecad project clone start-here
cd start-here
forgecad studio .
```

`forgecad studio .` opens the local editor around the current project folder. The `.` is not optional; `forgecad studio` requires a project path.

### Create A New Local Project

Use this when you want a fresh model instead of the starter project:

```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 .
```

`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.

`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.

## Why Projects Matter

ForgeCAD commands need a project root so imports, helper files, SVGs, and generated evidence resolve consistently.

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:

- `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.

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:

```text
good:  ~/cad/spool-adapter/
good:  ~/Projects/forgecad/start-here/
bad:   ~/
bad:   ~/Downloads/
bad:   ~/Projects/
```

## First Script

Inside a cloned or initialized ForgeCAD project, create `starter.forge.js`:

```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" });

const base = box(width, depth, height).color("#5f87c6");
const hole = cylinder(height * 3, holeRadius).translate(0, 0, -height);

return {
  "starter plate": base.subtract(hole),
};
```

Validate it and open the editor:

```bash
forgecad run starter.forge.js
forgecad studio .
```

## Use An AI Coding Agent

ForgeCAD works well with coding agents because the source of truth is plain code and the CLI can prove whether the model still runs.

Install the public skill library:

```bash
forgecad skill install
```

Then start your agent from inside the project folder and give it a concrete job:

```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 test important parameter values before calling it done.
```

The strongest loop is:

```text
agent edits files -> forgecad run -> render or inspect -> fix -> project push
```

Useful commands:

```bash
forgecad run adapter.forge.js
forgecad render 3d adapter.forge.js --camera iso
forgecad inspect fit interference adapter.forge.js --camera iso --force
forgecad inspect manufacture thickness adapter.forge.js --min 1.6 --warn 2.4 --camera iso --force
forgecad check print adapter.forge.js --json
forgecad project push
forgecad project open
```

For the full approved model list, agent setup, quality guidance, and recording ideas, see [AI Usage](AI/usage.md).

## Where To Go Next

| Goal | Start here |
|---|---|
| Learn primitives, booleans, transforms, and parameters | [Core API](/docs/core) |
| Build sketches and extrusions | [Sketches](/docs/sketch) |
| Build assemblies | [Assembly](/docs/assembly) |
| Export files and renders | [Output](/docs/output) and [CLI](/docs/cli) |
| Try concrete examples | Browse the [public kit examples](https://github.com/KoStard/forgecad-public-kit/tree/mainline/examples/api) |

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.
