# ForgeCAD Development

This is the private development repository for ForgeCAD.

The public/community README lives in [public-kit/README.md](public-kit/README.md). That file is copied to the root `README.md` of `forgecad-public-kit` during the public sync, so keep user-facing overview, install, examples, benchmarks, and community positioning there.

Use this README for local development notes only.

## Start Here

```bash
npm install
npm link
forgecad dev examples
```

Then open `http://localhost:5173`.

`forgecad dev examples` opens the local examples project with live reload, so you can edit and save files immediately.

To check the production studio build locally after `npm run build`:

```bash
forgecad studio examples
```

## Daily Commands

```bash
npm run dev              # Vite editor against ./examples
npm run open:homepage    # Vite public homepage/docs preview
npm run dev:studio       # hosted-mode Vite editor
npm run build:cli        # fast CLI rebuild after CLI/runtime changes
npm run build            # full solver, docs, browser, CLI, skill build
npm test                 # smoke suite
npm run check:suite      # full repo invariant suite
npm run test:unit        # Vitest unit tests
npm run lint             # Biome check
```

`npm run dev` is wired for editor work and routes `/` into the local examples project. Use `npm run open:homepage` when you need to inspect the public homepage, docs, SEO metadata, or hosted-site routes locally.

`npm run build:cli` is the fast daily-driver build. Run `npm run build` when you need the production SPA in `dist/`, the package artifacts, or a publish-ready build.

## Local Services

Hosted-mode development uses the local Postgres/Redis stack:

```bash
npm run dev:db
npm run dev:server
npm run dev:studio
```

Stop the dev services with:

```bash
npm run dev:db:stop
```

For a local production-style container run:

```bash
npm run dev:docker
```

## Repo Map

- `src/` - browser app, modeling runtime, store, and worker code
- `cli/` - `forgecad` command entrypoint and CLI workflows
- `server/` - hosted app API, auth, project storage, and routes
- `solver/` - Rust/WASM constraint solver
- `examples/` - maintained ForgeCAD model examples
- `docs/permanent/` - durable API, CLI, product, and engineering docs
- `agent-skill-library/` - package source for CLI-shipped companion skills
- `.agents/skills/` - repo-local operational skills such as `investigate`
- `dist-skill/` - generated installable `forgecad` skill output

## Solver Build Note

The solver compiles to WebAssembly via `wasm-pack`, which needs the Rust `wasm32-unknown-unknown` target. If the build fails because the target is missing:

```bash
rustup target add wasm32-unknown-unknown
```

If Rust came from Homebrew and cannot add that target, switch to [rustup](https://rustup.rs).

## Generated Docs And Skills

Refresh generated API docs, CLI docs, the installable skill, and the docs site with:

```bash
npm run refresh
```

For just the core agent skill:

```bash
npm run build:skill:forgecad
```

The [`agent-skill-library/`](agent-skill-library/README.md) directory is the source of truth for companion ForgeCAD workflows shipped by `forgecad skill install`. Public export is controlled by each skill's `forgecad-public: true` frontmatter. Repo-local operational skills live in [`.agents/skills/`](.agents/skills/README.md).

## Public Sync

The public repository is `/Users/kostard/Projects/CAD/ForgeCAD-public`.

[public-kit/README.md](public-kit/README.md) and [public-kit/LICENSE](public-kit/LICENSE) are the root README and license sources for that public repo. The public skill sync copies them to `ForgeCAD-public/README.md` and `ForgeCAD-public/LICENSE`, then mirrors the generated core skill and public companion skills:

```bash
npm run sync:public-skills -- --list
npm run sync:public-skills
```

When syncing examples or other public-safe folders manually, follow [`.agents/skills/sync-forgecad-public/SKILL.md`](.agents/skills/sync-forgecad-public/SKILL.md) and stage explicit paths only.

## Validation

Suggested local validation depends on the change:

```bash
npm run test:unit
npm run test:examples
npm run test:compiler
npm run test:brep
```

For model or API changes, validate representative files directly:

```bash
node dist-cli/forgecad.js run examples/api/01-parametric-bracket.forge.js
node dist-cli/forgecad.js check params path/to/file.forge.js --samples 10
```

## Publishing

```bash
npm login
npm version patch
npm publish
```

`npm publish` runs `npm run build` through `prepublishOnly`. Check package contents before publishing with:

```bash
npm pack --dry-run
```

The published package includes `dist/`, `dist-cli/`, `dist-skill/`, `examples/`, `README.md`, and `LICENSE`.

## Durable Docs

- API: [docs/permanent/API/README.md](docs/permanent/API/README.md)
- CLI: [docs/permanent/CLI.md](docs/permanent/CLI.md)
- Vision: [docs/permanent/VISION.md](docs/permanent/VISION.md)
- Coding notes: [docs/permanent/CODING.md](docs/permanent/CODING.md)
- Skill maintenance: [docs/permanent/guides/skill-maintenance.md](docs/permanent/guides/skill-maintenance.md)
- Benchmark maintenance SOP: [docs/processes/README_BENCHMARK_SOP.md](docs/processes/README_BENCHMARK_SOP.md)

## License

[ForgeCAD Software License](LICENSE). Personal non-commercial use is free. Human-operated commercial CAD work, including designing models for customers, requires Pro. Automated backend, hosted, embedded, AI training, evaluation, benchmarking, RL environment, or application usage requires Enterprise. Current plan details are at [forgecad.io/pricing](https://forgecad.io/pricing).
