forgecad 0.6.3 → 0.7.0

package/dist-skill/docs-dev/CLI/projects.md

@@ -0,0 +1,107 @@
+---
+skill-group: cli
+skill-order: 1
+---
+
+# ForgeCAD CLI: Projects & Setup
+
+## Install
+
+```bash
+npm install -g forgecad
+# Developers working on ForgeCAD itself:
+npm install && npm link
+```
+
+## When to use what
+
+| Context | Use |
+|---------|-----|
+| Using ForgeCAD as a tool | `forgecad *` commands |
+| Developing ForgeCAD itself | `npm run dev` / `npm run build` |
+| CI / publishing | `npm run build && npm run test:full` |
+
+## Dev vs production server
+
+```bash
+forgecad dev [path]        # Vite dev server, live reload
+forgecad studio [path]     # Static server for production build (requires dist/)
+```
+
+Both accept `--blank`, `--port <n>`, `--host`, `--open`, `--strict-port`.
+
+## Licensing
+
+```bash
+forgecad license                    # Show license status
+forgecad license activate <key>     # Activate a Pro license key
+forgecad license deactivate         # Remove license
+```
+
+| Tier | Included |
+|------|----------|
+| Free | dev, studio, run, render, export stl/3mf/svg, all checks, debug |
+| Pro  | export step/brep, render-hq, capture gif/mp4, gcode, report, cutting-layout, sdf, urdf, sketch-pdf |
+
+## Authentication
+
+```bash
+forgecad login                          # Interactive login
+forgecad login --server http://localhost:5174
+forgecad logout
+forgecad whoami                         # Show user, server, and license status
+```
+
+Credentials stored in `~/.forgecad/auth.json`.
+
+## Project Management
+
+```bash
+forgecad project init "My Project"      # Create on server + link current directory
+forgecad project clone my-project       # Download into ./my-project/
+forgecad project push [--force]         # Upload local changes
+forgecad project pull [--force]         # Download remote changes
+forgecad project status                 # Show local vs remote diff
+forgecad project list
+forgecad project info
+forgecad project rename "New Name"
+forgecad project set-visibility public  # private|shared|public
+forgecad project delete [--force]
+forgecad project open
+```
+
+Projects are linked to remote via `forgecad.json`.
+
+## File Management (Remote)
+
+```bash
+forgecad file list [path]
+forgecad file read <path>
+forgecad file save <path>               # Upload local file
+forgecad file save <path> --content "code here"
+cat model.forge.js | forgecad file save model.forge.js --stdin
+forgecad file delete <path> [--force]
+forgecad file rename <old> <new>
+forgecad file mkdir <path>
+forgecad file copy <source-slug> <path> [--dest <dest-path>]
+```
+
+Requires the current directory to have `forgecad.json`.
+
+## Member Management
+
+```bash
+forgecad project members
+forgecad project add-member alice@example.com          # editor by default
+forgecad project add-member bob@example.com --role viewer
+forgecad project remove-member alice@example.com
+forgecad project set-role bob@example.com editor
+```
+
+Roles: **owner** (full control), **editor** (read/write), **viewer** (read-only).
+
+## Shell Autocomplete
+
+```bash
+forgecad completion bash   # or zsh / fish
+```

package/dist-skill/docs-dev/CLI/studio_publishing.md

@@ -0,0 +1,52 @@
+---
+skill-group: cli
+skill-order: 4
+---
+
+# ForgeCAD CLI: Studio & Publishing
+
+## Studio & Dev Server
+
+```bash
+forgecad dev [path] [--blank] [--port n] [--host] [--open]    # Vite dev server
+forgecad studio [path] [--blank] [--port n]                   # Production static server
+forgecad web [--open]                                         # Web/embeddable mode
+```
+
+`forgecad open` is an alias for `forgecad studio`.
+
+## New File from Template
+
+```bash
+forgecad new mypart                     # Part template (default)
+forgecad new bracket --template sketch  # Constrained sketch template
+forgecad new robot --template assembly  # Multi-part assembly template
+```
+
+## Publishing & Sharing
+
+```bash
+forgecad publish model.forge.js --title "My Model"   # Publish; get shareable URL
+forgecad publish model.forge.js --no-sync             # Publish without auto-pushing
+forgecad shares list                                  # List all published models
+forgecad shares delete <share-id> [--force]
+forgecad link <gist-url-or-id>                        # Share link from GitHub Gist
+```
+
+Published at `forgecad.io/m/<shareId>`. Shares are live references — always reflect current version, not a snapshot. Requires a project directory (`forgecad.json`).
+
+## Adding New CLI Commands
+
+1. Create/extend a module under `cli/`
+2. Import from `../src/forge/headless`; call `await init()` then `runScript(code, fileName, allFiles)`
+3. Register in `cli/forgecad.ts`
+
+Pass all project files (keyed by project-relative path) to `runScript` when using `require()` / `importSvgSketch()`. Use `require("./file.forge.js", { Param: value })` for model files; `importSvgSketch()` for SVG assets.
+
+## Local Branch Cleanup
+
+```bash
+uv run cli/forge-prune-local-branches.py [--dry-run] [--base mainline]
+```
+
+Finds merged local branches with no matching remote, prompts before deleting. Removes linked worktrees first when a branch is checked out there.

package/dist-skill/docs-dev/CLI/validation.md

@@ -0,0 +1,66 @@
+---
+skill-group: cli
+skill-order: 2
+---
+
+# ForgeCAD CLI: Validation & Debugging
+
+## Script Validation
+
+```bash
+forgecad run examples/cup.forge.js
+forgecad run examples/cup.forge.js --debug-imports
+forgecad run examples/cup.forge.js --param "Wall Thickness=3"
+forgecad run examples/cup.forge.js --param "Show Lid=0"
+forgecad run examples/cup.forge.js --param "Pan Style=wok"
+forgecad run examples/constraints/06-complex-spectrogram.forge.js --solver-debug-out tmp/spectrogram-debug
+```
+
+`--param "Key=Value"` overrides: numeric, boolean (`1`/`0`), or string (displayed label) params.
+
+`--debug-imports` prints source file, target file, overrides, return type, and success/error phase.
+
+`--solver-debug-out <dir>` writes a per-sketch constructive transcript + SVG snapshots bundle.
+
+## Parameter Validation
+
+```bash
+forgecad check params examples/shoe-rack-doors.forge.js [--samples 10]
+```
+
+Samples each parameter across its range; checks runtime errors, degenerate geometry (volume~0), and new collisions. `--samples N` (default 8).
+
+## Check Commands
+
+```bash
+forgecad check transforms           # Math-level transform/frame composition invariants
+forgecad check compiler [--case <name>] [--update]    # Compiler regression snapshots
+forgecad check query-propagation [--update]           # Topology-rewrite propagation snapshots
+forgecad check examples [--family <f>] [--example <path>]  # Checked example manifest
+forgecad check suite                # Full invariant suite (CI / release gate)
+forgecad check suite --profile local  # Faster local invariant suite
+forgecad check dimensions           # Shape dimension propagation invariants
+```
+
+## Invariant Test Suite
+
+```bash
+npm test                        # Faster local invariant suite
+npm run test:full              # Full invariant suite
+npm run test:examples           # Example architecture gate
+npm run test:compiler           # Compiler snapshot suite
+npm run test:compiler:update    # Refresh compiler snapshots after intentional change
+npm run test:query-propagation
+npm run test:query-propagation:update
+```
+
+## Debug Commands
+
+```bash
+forgecad debug dimensions /path/to/file.forge.js [--all] [--dim-angle-tol 12]
+forgecad debug compiler /path/to/file.forge.js [--compact]
+```
+
+`debug dimensions` prints total/per-view dimension counts, ownership routing, and coordinate list.
+
+`debug compiler` prints JSON with compile plans, CadQuery/OCCT lowering diagnostics, faceted fallback eligibility, and runtime/compiler Manifold summaries.

package/dist-skill/{docs → docs-dev}/blueprint-first.md

@@ -1,3 +1,8 @@
+---
+skill-group: dev-conventions
+skill-order: 3
+---
+
 # Blueprint-First Philosophy
 
 ## Code Should Read Like a Mechanical Blueprint

package/dist-skill/{docs → docs-dev}/coding-best-practices.md

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-conventions
 skill-order: 1
-skill-tiers: [dev]
 ---
 
 # Coding Best Practices
@@ -88,18 +87,17 @@ Biome runs as part of `forgecad check suite`. Configuration lives in `biome.json
 Public API method names must read like natural English. Prefer verbose, intuitive names over short, ambiguous ones. The method name alone should tell you exactly what it does — no options objects or magic strings needed to disambiguate.
 
 ```ts
-// BAD — ambiguous: rotates around what?
+// BAD — ambiguous: which axis? what angle?
 shape.rotate(45, 0, 0)
 // BAD — technical jargon, not a sentence
 shape.rotateAxisAngle([0,1,0], 45)
-// BAD — options bag to disambiguate
-shape.rotate(45, 0, 0, { around: 'center' })
 
 // GOOD — reads like a sentence
-shape.rotate(45, 0, 0)                         // "rotate 45 degrees" (center is default)
-shape.rotateAround(pivot, 45, 0, 0)            // "rotate around pivot"
-shape.rotateAroundAxis([0,1,0], 45)             // "rotate around axis"
-shape.rotateAroundAxisAt([0,1,0], 45, pivot)    // "rotate around axis at pivot"
+shape.rotateX(45)                               // "rotate X 45 degrees"
+shape.rotateY(45)                               // "rotate Y 45 degrees"
+shape.rotateZ(45)                               // "rotate Z 45 degrees"
+shape.rotate([0, 1, 0], 45)                     // "rotate around axis"
+shape.rotateZ(45, { pivot: [10, 0, 0] })        // "rotate Z at pivot"
 
 shape.scale(2)                                   // "scale by 2" (from center)
 shape.scaleAround(pivot, 2)                      // "scale around pivot"

package/dist-skill/{docs → docs-dev}/coding.md

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-conventions
 skill-order: 2
-skill-tiers: [dev]
 ---
 
 # ForgeCAD Coding Guidelines
@@ -308,8 +307,7 @@ Before committing UI changes:
 2. Export from `headless.ts`
 3. Add to runner sandbox in `src/forge/runner.ts`
 4. Add TypeScript hints in `src/components/CodeEditor.tsx`
-5. Update `docs/permanent/API/API.md`
-6. Commit: "Add [primitive] 3D primitive"
+5. Commit: "Add [primitive] 3D primitive"
 
 ### Adding a New CLI Command
 1. Create `cli/your-command.ts`