forgecad 0.6.3 → 0.7.0

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