forgecad 0.9.13 → 0.9.15

package/dist-skill/docs-dev/agent-native-api.md

@@ -1,27 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 3
----
-
-# Agent-Native API Design
-
-ForgeCAD assumes that much of its model code will be written by AI coding agents. That is a strength of code-first CAD: the artifact is plain source, the API is documented, and the CLI gives the agent a feedback loop. A strong agent can read domain documentation and temporarily become useful in almost any specialty.
-
-But "make the agent more specialized through documentation" is not the core problem ForgeCAD should solve. If the agent needs pages of instructions to hand-derive standard mechanical behavior, manually tune magic numbers, compute trigonometry, or reconstruct common CAD operations from primitives, the missing capability belongs in the API. Documentation can teach the vocabulary, but it should not compensate for a weak vocabulary.
-
-The goal is an API specific and powerful enough to cover most serious modeling needs directly. Instead of asking agents to become gear experts, sheet-metal experts, fixture experts, or assembly-kinematics experts from scratch on every task, ForgeCAD should give them first-class concepts with names, contracts, diagnostics, and examples. The agent should read the docs to discover `lib.spurGear()`, `SheetMetal.flange()`, connector-based assemblies, inspection bundles, and exact export workflows, then compose those concepts with confidence.
-
-Docs are leverage, not product substitute. They should explain what exists, when to use it, what guarantees it provides, what limitations remain, and how to validate the result. They should not become long recipes for reimplementing missing algorithms in user code. When a doc repeatedly explains how to work around an API gap, that is a design signal: promote the intent into the API, add diagnostics, and keep the recipe as orientation rather than obligation.
-
-This is also why API specificity matters. Generic geometry escape hatches are valuable for unusual work, but the common path should preserve domain intent. A belt drive is not just a loop of tangent lines. A countersunk hole is not just three boolean cylinders. A multi-part assembly is not just a collection of translates. When ForgeCAD encodes those concepts directly, AI agents produce code that is shorter, more inspectable, easier to repair, and closer to what a mechanical designer meant.
-
-## Design Gate
-
-When improving docs or adding API surface, ask:
-
-- Are we teaching the agent an existing ForgeCAD concept, or teaching it to reimplement a concept ForgeCAD should own?
-- Would three different agents likely write three different fragile versions of this from the same docs?
-- Does the current solution require hand-tuned constants, manual trigonometry, raw coordinate derivation, or silent fallback behavior?
-- Could a domain-specific function, builder, namespace, diagnostic, or verification primitive make the intended model obvious?
-
-If the answer points to missing vocabulary, prefer an API improvement over longer instructions. Let documentation make agents fluent in ForgeCAD; do not make documentation carry the weight of the CAD system.

package/dist-skill/docs-dev/blueprint-first.md

@@ -1,145 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 3
----
-
-# Blueprint-First Philosophy
-
-## Code Should Read Like a Mechanical Blueprint
-
-ForgeCAD is a **mechanical compiler**. The user inputs design intent — dimensions, constraints, relationships — and the engine handles the geometry. If a mechanical feature can be dimensioned on a 2D drawing without explicit X/Y coordinates, a user should be able to model it in ForgeCAD without calculating those coordinates.
-
-We are building a geometry engine, not a math test.
-
-## The Trigonometry Tax
-
-Every time a user writes `Math.sin()` or `Math.cos()` to place a bolt hole, position a circular pattern, or compute a tangent point, our API has failed them. This is the **Trigonometry Tax** — the cost of translating declarative engineering intent into imperative Cartesian math.
-
-The tax is real and measurable. In our own example library, ~40 of 250+ files contain manual trig. The same patterns repeat: circular positioning, polygon vertex layout, rotation result computation, polar-to-cartesian conversion. Each one is a place where the API should have provided an abstraction but didn't.
-
-## The Core Pillars
-
-### Pillar I: Intent-Driven Constraints over Explicit Coordinates
-
-Traditional CAD-as-code requires calculating exact center points and intersections. ForgeCAD uses **constraint-driven pathing** — users define the knowns (radii, angles, distances), and the solver calculates the implicit intersections.
-
-```javascript
-// The old way — calculating tangent arc intercepts by hand
-const cx = r1 * Math.cos(angle) + offset * Math.sin(angle);
-const cy = r1 * Math.sin(angle) - offset * Math.cos(angle);
-
-// The ForgeCAD way — declare intent, solver handles geometry
-sketch.route([
-  { tangent: circleA },
-  { fillet: 17 },
-  { tangent: circleB },
-]);
-```
-
-### Pillar II: Topological Selection
-
-Hardcoding vertex indices or exact 3D coordinates to apply fillets makes models brittle. If a base dimension changes, the coordinates change, and the build breaks. ForgeCAD borrows from the DOM: **select geometry via topological queries, not hardcoded indices.**
-
-```javascript
-// Brittle — breaks if topology changes
-body.fillet(5, edgeIndex[14]);
-
-// ForgeCAD — semantic edge selection
-fillet(body, 5, { parallel: [0, 0, 1], convex: true });
-fillet(body, 3, selectEdges(body, { atZ: 0 }));
-```
-
-### Pillar III: Mechanical First-Class Citizens
-
-Primitives should not be limited to circles, rectangles, and polygons. Mechanical engineering relies on standard features that are tedious to build from scratch. If a machinist has a specific tool bit for it, the API should have a specific primitive for it.
-
-```javascript
-// Holes with real mechanical features — not raw boolean subtraction
-shape.hole('top', { diameter: 11, depth: 20,
-  counterbore: { diameter: 18, depth: 5 },
-  thread: { designation: 'M10' },
-});
-
-// Standard mechanical profiles
-slot(30, 10);
-arcSlot({ pitchRadius: 50, sweep: 60, width: 12 });
-lib.spurGear({ module: 2, teeth: 24 });
-```
-
-### Pillar IV: Relative Workplanes
-
-Everything in mechanical design is relative. You don't drill a hole at `[15.5, 30.2, 100.0]` in global space. You drill a hole on the top face of the flange, centered on the lug. The API must support dynamic coordinate systems that attach to existing geometry.
-
-```javascript
-// Global coordinates — fragile, unreadable
-const hole = circle2d(5).extrude(20).translate(15.5, 30.2, 100.0);
-
-// Relative to geometry — moves with the parent
-circle2d(5).onFace(flange, 'top', { u: 10, v: 0 }).extrude(-20);
-```
-
-### Pillar V: No Manual Math for Standard Layout
-
-If a user has to import `Math.sin` to place elements in a circle, compute `Math.sqrt(3)` for an equilateral triangle, or manually convert degrees to radians, our API has a gap. Standard layout operations are first-class:
-
-```javascript
-// Circular layout — no trig
-const positions = circularLayout(12, radius);
-
-// Polygon vertex positions — no sqrt(3)
-const vertices = polygonVertices(3, radius);
-
-// Polar positioning — no sin/cos
-shape.translatePolar(radius, angleDeg);
-```
-
-## The Anti-Patterns
-
-### 1. No sin/cos in user code for standard layout
-If a user imports `Math.sin` to place a bolt hole, we have a missing abstraction. We provide polar coordinates, patterns, and layout helpers natively.
-
-### 2. No magic shrinkwraps without explicit control
-Connections between shapes must be explicit. "Connect Shape A to Shape B with a tangent arc of R15" — not a black-box convex hull that guesses intent.
-
-### 3. No silent failures
-If a fillet radius is too large, or a tangent route can't be solved, the API throws a descriptive mechanical error — not a generic engine crash. (See also: CLAUDE.md "No Silent Fallbacks" rule.)
-
-### 4. No coordinate math for relative positioning
-If a feature is defined relative to another feature (a hole on a face, a boss centered on a lug), the API must express that relationship directly — not force the user to compute the absolute position.
-
-## Design Gate
-
-**Every new public API method must pass this test:**
-
-> Can the user accomplish this without `Math.sin`, `Math.cos`, `Math.atan2`, manual degree-to-radian conversion, or computing intermediate Cartesian coordinates from polar/angular intent?
-
-If the answer is no, the API needs a higher-level alternative. The raw math path can still exist for power users, but the common case must be trig-free.
-
-## Ergonomics in JavaScript
-
-JavaScript lacks Python's `with` statement, so ForgeCAD relies on **method chaining** and **callback scopes** for clean, fluid modeling:
-
-```javascript
-// Fluid chaining — sketch to solid to features
-const part = circle2d(50)
-  .extrude(15)
-  .fillet(5, { atZ: 0 });
-
-// Callback workplane — scoped 2D ops on a 3D face
-shape.onFace('top', (face) => {
-  face.subtract(
-    circularPattern(circle2d(5.5), 6, { radius: 32.5 })
-  );
-});
-```
-
-## Architecture Constraints
-
-- **TypeScript native.** Autocomplete and compile-time checking for mechanical parameters are mandatory.
-- **B-Rep capable.** Topological naming and precise filleting require a real CAD kernel (Manifold for mesh, OCCT for B-Rep).
-- **Immutable geometry, mutable builders.** Underlying geometry is immutable for predictable undo/redo. Builder classes maintain state for ergonomic chaining.
-- **Degrees at the API boundary.** All user-facing angles are in degrees. Radians are an internal implementation detail.
-
-## Summary
-
-We are not building a 3D drawing tool. We are building a **mechanical compiler**. The user inputs the blueprint's design intent, and our API handles the geometry.

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

@@ -1,120 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 1
----
-
-# Coding Best Practices
-
-## Minimal Implementation
-
-Write only the code needed to solve the problem. No verbose implementations, no speculative features.
-
-## TypeScript
-
-- Use explicit types for function parameters and return values
-- Avoid `any` — use `unknown` or proper types
-- Prefer interfaces for object shapes
-
-## React Components
-
-- Functional components only
-- Inline styles for simplicity (no CSS files unless necessary)
-- Extract reusable logic to custom hooks or store actions
-
-### Stable References in Render Bodies
-
-Never use `?? []`, `?? {}`, or inline fallback literals in a component render body if the value flows (directly or transitively) into a `useMemo`/`useCallback`/`useEffect` dependency array. Each render creates a new reference, which silently invalidates every downstream memo.
-
-```tsx
-// BAD — new [] every render, breaks every useMemo that depends on `items`
-const items = config?.items ?? [];
-
-// GOOD — stable reference across renders
-const items = useMemo(() => config?.items ?? [], [config]);
-```
-
-Use `useMemo` for any derived-with-fallback value that feeds into other hooks.
-
-## State Management
-
-- All global state lives in `forgeStore.ts`
-- Use Zustand selectors to prevent unnecessary re-renders
-- Keep actions pure and synchronous where possible
-
-## Performance
-
-### Geometry Operations
-
-- Manifold operations are expensive — minimize boolean ops
-- Cache geometry results when parameters don't change
-- Use debouncing for real-time updates
-
-### React Rendering
-
-- Use Zustand selectors to prevent unnecessary re-renders
-- Memoize expensive computations with `useMemo`
-- Keep component tree shallow
-
-## Linting & Formatting
-
-[Biome](https://biomejs.dev/) handles both linting and formatting for all TS/JS code.
-
-```bash
-npm run lint          # check for lint issues (no changes)
-npm run lint:fix      # auto-fix lint issues
-npm run format        # auto-format all files
-```
-
-Biome runs as part of `npm run check:suite`. Configuration lives in `biome.json` at the repo root.
-
-## Self-Review Before Commit
-
-1. Remove console.logs and debug code
-2. Check for unused imports
-3. Verify TypeScript has no errors
-4. Test the change works as intended
-5. Read the diff — does it make sense?
-
-### What to Look For
-
-- Does this solve the problem with minimal code?
-- Are there edge cases not handled?
-- Is the code readable without comments?
-- Does it follow existing patterns?
-
-## API Naming: Methods Read Like Sentences
-
-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 — technical jargon, not a sentence
-shape.rotateAxisAngle([0,1,0], 45)
-
-// GOOD — reads like a sentence
-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"
-
-shape.mirror([1,0,0])                           // "mirror along X" (through center)
-shape.mirrorThrough(point, [1,0,0])             // "mirror through point"
-```
-
-Rules:
-- The **bare method** (`rotate`, `scale`, `mirror`) does the common-sense default (operates relative to the shape's own center)
-- **Longer names** make the reference point explicit — no ambiguity
-- **No string literals** as behavior selectors (`'center'`, `'origin'`)
-- **No options objects** to disambiguate what should be separate methods
-
-## Runtime Global Namespace
-
-Do not add new lowercase injected globals to `.forge.js` scripts. Existing lowercase globals such as `box`, `union`, and `loft` are established core vocabulary; new domain helpers must live under a PascalCase namespace or class such as `Product.materials`, `Product.profiles`, or `Shape.fromSlices`.
-
-The repo enforces this in `npm run check:suite -- --profile smoke`. If a lowercase global truly must be added for compatibility, it needs an explicit API review and an allowlist update in `cli/check-runtime-globals.ts`.
-
-## File length
-Keep files under 200 lines. If a file grows beyond that, consider splitting it into smaller, focused files.

package/dist-skill/docs-dev/coding.md

@@ -1,340 +0,0 @@
----
-skill-group: dev-conventions
-skill-order: 2
----
-
-# ForgeCAD Coding Guidelines
-
-## Development Workflow
-
-### Building & Running
-```bash
-npm install          # Install dependencies
-npm link             # Install the local forgecad binary
-forgecad studio examples  # Start the browser studio (localhost:5173)
-npm run build        # Production build
-npm run preview      # Preview production build
-```
-
-### CLI Tools
-```bash
-forgecad export svg examples/constraints/01-fully-constrained-rect.forge.js  # Export sketch to SVG
-forgecad render 3d examples/products/cup.forge.js # Render to PNG (Puppeteer + Chrome)
-```
-
-See [CLI.md](../CLI.md) for full CLI documentation.
-
-### Project Structure
-```
-src/
-├── forge/                # Core geometry engine (shared by browser + CLI)
-│   ├── kernel.ts         # Manifold WASM wrapper, Shape class, primitives
-│   ├── headless.ts       # Single entry point for all contexts (browser + Node CLI)
-│   ├── index.ts          # Browser entry point (re-exports from headless.ts)
-│   ├── runner.ts         # Script sandbox — executes user scripts and resolves imported .svg assets
-│   ├── params.ts         # Parameter system (param() → UI sliders)
-│   ├── library.ts        # Part library (lib.boltHole, lib.pipe, etc.)
-│   ├── section.ts        # Plane intersection / projection
-│   ├── meshToGeometry.ts # Manifold mesh → Three.js BufferGeometry
-│   ├── sceneBuilder.ts   # Three.js scene setup (shared with CLI renderer)
-│   └── sketch/           # 2D sketch system
-│       ├── core.ts       # Sketch class
-│       ├── primitives.ts # rect, circle2d, polygon, ngon, etc.
-│       ├── transforms.ts # translate, rotate, scale, mirror
-│       ├── booleans.ts   # add, subtract, intersect, union2d
-│       ├── operations.ts # offset, simplify, warp
-│       ├── extrude.ts    # extrude, revolve (2D → 3D)
-│       ├── path.ts       # PathBuilder, stroke
-│       ├── anchor.ts     # attachTo/matchTo positioning
-│       ├── constraints.ts # Constraint solver (18 types)
-│       ├── entities.ts   # Point2D, Line2D, Circle2D, Rectangle2D, Constraint helpers
-│       ├── topology.ts   # TrackedShape, face/edge naming
-│       ├── patterns.ts   # linearPattern, circularPattern, mirrorCopy
-│       ├── fillets.ts    # filletEdge, chamferEdge
-│       ├── arcBridge.ts  # arcBridgeBetweenRects
-│       └── index.ts      # Re-exports everything
-├── components/           # React UI components
-│   ├── Viewport.tsx      # 3D viewport (Three.js + R3F)
-│   ├── CodeEditor.tsx    # Monaco editor with ForgeCAD types
-│   ├── FileExplorer.tsx  # Project file tree
-│   ├── ViewPanel.tsx     # Render mode, views, object settings
-│   ├── ParamPanel.tsx    # Parameter sliders
-│   └── ExportPanel.tsx   # STL export
-├── store/
-│   └── forgeStore.ts     # Zustand global state
-├── App.tsx               # Main application shell
-└── main.tsx              # React entry point
-
-cli/
-├── forgecad.ts           # Top-level CLI entrypoint and command routing
-├── forge-svg.ts          # SVG export (uses real engine via headless.ts)
-├── forge-render.mjs      # PNG render launcher (Puppeteer)
-├── render.ts             # Headless render entry (loaded in browser by Puppeteer)
-└── render.html           # HTML shell for headless render
-
-examples/                 # Example scripts
-├── *.forge.js            # 3D part and 2D sketch examples
-└── constraints/          # Constrained sketch examples
-```
-
-## Coding Standards
-
-See [coding-best-practices.md](coding-best-practices.md) for TypeScript, React, state management, and performance best practices.
-
-## Agent-Native API Design Standard (Required)
-
-ForgeCAD expects AI agents to author serious `.forge.js` models, but agent specialization through documentation is not a substitute for API design. Read [agent-native-api.md](agent-native-api.md) before treating a modeling difficulty as "just a docs problem."
-
-If a common modeling task requires agents to reimplement a known CAD concept from recipes, trigonometry, magic numbers, or raw boolean construction, prefer a domain-specific API improvement with clear docs and diagnostics. Documentation should make agents fluent in ForgeCAD's vocabulary; it should not carry missing vocabulary.
-
-## Domain Localization Standard (Required)
-
-This standard is package-wide for any new user-facing concept or API family.
-
-### Contract
-- Each concept family must have a clear primary home in both code and docs.
-- Extend the module that already owns the mental model instead of scattering helpers across unrelated files.
-- When a feature spans multiple layers, pick one domain owner and make the other layers mirror that owner.
-- Keep related runtime code, examples, checks, and docs close to the same domain name whenever practical.
-
-### Examples
-- Assembly and kinematics live under `src/forge/assembly.ts` and `docs/permanent/API/assembly/assembly.md`.
-- Sketch constraints live under `src/forge/sketch/constraints.ts` and the sketch/entity API docs.
-- Transform/placement helpers should stay grouped with transform and positioning surfaces, not reappear as ad-hoc helpers in unrelated modules.
-
-### Enforcement
-- Before adding a new API, state which domain owns it.
-- If a concept currently has no clean home, create one instead of spreading the first implementation across multiple files.
-
-## Backend Compiler Standard (Required)
-
-This standard is package-wide for any geometry feature that affects runtime lowering, export-backend coverage, or backend capability routing.
-
-Read [compiler.md](../internals/compiler.md) before changing this area.
-For large multi-agent migrations or architecture programs, also read [PROGRAM-LEAD.md](../../processes/PROGRAM-LEAD.md).
-
-### Contract
-- Forge semantic intent comes first. Backends are lowerers, not the authoring model.
-- Scene-level capability routing must stay centralized. Do not re-derive export/runtime policy ad hoc in unrelated modules.
-- Public feature APIs must not hide backend-specific behavior directly in their callsites. Backend code belongs in the lowerers.
-- New backend limitations must surface as diagnostics, not silent fallback or silent exactness loss.
-
-### Enforcement
-- If a feature is compile-covered, update the canonical compile graph and the scene compiler.
-- If a feature is not yet dual-lowered, add explicit unsupported diagnostics for the missing backend rather than bypassing the compiler.
-- Any geometry feature change must update invariant coverage and the living backend-compiler tracker.
-
-## Multi-Agent Program Standard (Required For Large Migrations)
-
-For work that spans multiple agent branches or staged dependency waves, the Program Lead role in [PROGRAM-LEAD.md](../../processes/PROGRAM-LEAD.md) is the default operating model.
-
-Use it when:
-
-- one missing foundation blocks several feature lanes
-- multiple agents need isolated tasks with dependency ordering
-- the repo needs a living task graph and capability tracker to stay truthful
-
-The key rule is simple:
-
-- solve the deepest shared prerequisite first
-- only then open the parallel wave that builds on top of it
-
-## Frame Composition Standard (Required)
-
-This standard is package-wide for any code that composes transforms (`Transform`, joints, assemblies, kinematic helpers).
-
-### Contract
-- `A.mul(B)` means **apply A, then B**
-- Use `composeChain(...)` for 3+ composed transforms instead of manual `.mul()` chains
-- In assembly/kinematics, always express composition in this canonical order:
-  - `local -> childBase -> jointMotion -> jointFrame -> parentWorld`
-
-### Why this is mandatory
-Transform order bugs can produce geometry that "looks valid" but is globally wrong (detached mechanism segments, drifting pivots, mirrored motion paths) and often pass casual visual checks.
-
-### 5-Why (2026-02 Assembly disconnect incident)
-1. Why were arm segments disconnected?  
-Because child world transforms were composed in the wrong order in `assembly.solve()`.
-2. Why was order wrong?  
-Because `.mul()` chain semantics (apply self, then other) were interpreted inconsistently with matrix notation.
-3. Why was that ambiguity possible?  
-Because there was no single canonical frame equation documented and enforced in code review.
-4. Why didn’t tests catch it immediately?  
-Because there was no invariant test comparing assembly-solved frame origins against an analytic kinematic oracle.
-5. Why no invariant test existed?  
-Because we had feature-level example checks, but no package-wide transform convention gate.
-
-Root cause: **missing, enforced transform/frame composition contract across code + tests.**
-
-### Enforcement
-- Any change touching transforms, joints, or assembly solving must run:
-  - `npm run check:suite -- --profile smoke`
-- If the change affects user-facing geometry behavior, also run:
-  - `forgecad run <affected-example>`
-
-## Editor Declaration Parity Standard (Required)
-
-This standard is package-wide for any user-facing API exposed to scripts.
-
-### Contract
-- Runtime API and editor declarations must ship together:
-  - Runtime surface: `src/forge/*` exports + `src/forge/runner.ts` sandbox bindings
-  - Editor surface: `src/components/CodeEditor.tsx` `FORGE_TYPES`
-  - Docs surface: `docs/permanent/API/**/*.md`
-- If an important feature is missing from editor declarations, you must either:
-  - implement declarations in the same change, or
-  - create a tracked task in `tasks/` that explicitly names the missing surface and scope.
-
-### Enforcement
-- Before merge, verify new/changed script APIs are present in all three surfaces above.
-- Do not ship runtime-only features without either declaration parity or a tracking task.
-
-## Multi-File Native Standard (Required)
-
-ForgeCAD projects must scale cleanly across multiple files. Complex models should be **expressible as a composition of separate, independently-authored files** — not as a single growing script.
-
-### Tenet
-
-Every user-facing import mechanism must make multi-file composition a first-class path, not an afterthought:
-
-- Any `.forge.js` file (returning a `Shape`, `ShapeGroup`, `Assembly`, or other type) can be imported with `require("./file.forge.js")`.
-- `require()` accepts an optional second argument for parameter overrides: `require("./part.forge.js", { Width: 100 })`.
-- Files can also use `exports.name = value` alongside or instead of `return` for named multi-export.
-- Plain JS helpers and constants belong in regular `.js` modules imported via `require()` or standard `import`.
-
-No user should have to choose between "clean file structure" and "full API access". If a new return type or authoring primitive appears, **its import path must ship at the same time or in the same milestone**.
-
-### Consequences for API design
-
-- New authoring primitives (anything a user might `return` from a `.forge.js` file) are automatically importable via `require()`.
-- Imported objects must expose the same child-access and placement-reference ergonomics that inline objects do.
-- Parameter overrides must be supported via the second argument to `require()` so multi-instance use is natural.
-- If a sub-file feature cannot yet be fully composed (e.g. kinematic merge across file boundaries), document the limitation explicitly and create a tracked task — do not silently downgrade.
-
-### Enforcement
-
-- When adding a new return-type contract, check: is there an `import*()` function for it?
-- When adding placement-reference or child-access APIs to an object type, check: do imported versions of that type also expose those APIs?
-- Verify with `forgecad run` that a multi-file example using the new feature works end-to-end before merge.
-
-## Script API Contract Standard (Required)
-
-This standard is package-wide for any API exposed to user scripts.
-
-### Contract
-- Collection-shaped script APIs must accept the intuitive collection forms the docs advertise:
-  - variadic operands when the operation naturally works on many inputs
-  - a single array of operands when that keeps call sites composable
-- Method syntax and function syntax must mirror each other for the same operation family.
-- User-facing APIs must not silently ignore extra arguments. Unsupported arity or operand types must throw a direct runtime error with the API name in the message.
-- If a future API needs configuration, do not smuggle it in as an ambiguous trailing object on an operand list. Use a distinct helper or a clearly named options-bearing API.
-
-### Enforcement
-- Any change to user-facing script APIs must run:
-  - `npm run check:suite`
-- If the change also affects transforms, dimensions, placement refs, or geometry semantics, run the relevant existing invariant checks too.
-
-## Git Workflow
-
-### Commit Every Major Change
-Each logical unit of work should be a separate commit:
-
-```bash
-git add <files>
-git commit -m "Add file explorer panel"
-```
-
-### Commit Message Format
-```
-<verb> <what>
-
-Examples:
-- Add file explorer panel
-- Fix measure mode toggle
-- Update parameter slider styling
-- Remove unused imports
-```
-
-Use present tense verbs: Add, Fix, Update, Remove, Refactor
-
-### What Counts as "Major"
-- New feature or component
-- Bug fix
-- Refactoring that changes structure
-- Performance improvement
-- Breaking API change
-
-### What to Commit Together
-- Related files for a single feature
-- Tests with the code they test
-- Documentation with the feature it describes
-
-### Example Workflow
-```bash
-# Feature: Add file explorer
-git add src/components/FileExplorer.tsx
-git add src/store/forgeStore.ts
-git add src/App.tsx
-git commit -m "Add file explorer panel"
-
-# Next feature: Add keyboard shortcuts
-git add src/hooks/useKeyboard.ts
-git add src/App.tsx
-git commit -m "Add keyboard shortcuts for file operations"
-```
-
-## Testing
-
-### Manual Testing Checklist
-Before committing UI changes:
-- [ ] Test in browser at localhost:5173
-- [ ] Check console for errors
-- [ ] Verify responsive behavior
-- [ ] Test with example scripts
-
-### Integration Testing
-- Load example files and verify they render
-- Test parameter sliders update geometry
-- Verify STL export produces valid files
-- Check measure mode calculates correctly
-
-## Common Patterns
-
-### Adding a New Sketch Primitive
-1. Add function to `src/forge/sketch/primitives.ts`
-2. It's auto-exported via `sketch/index.ts` → `headless.ts` → `index.ts`
-3. Add it to the sandbox in `src/forge/runner.ts` (both the `new Function()` args and the call)
-4. Add TypeScript hints in `src/components/CodeEditor.tsx` (`FORGE_TYPES`)
-5. Update `docs/permanent/API/sketch/primitives.md`
-6. Commit: "Add [primitive] sketch primitive"
-
-### Adding a New 3D Primitive
-1. Add function to `src/forge/kernel.ts`
-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. Commit: "Add [primitive] 3D primitive"
-
-### Adding a New CLI Command
-1. Create `cli/your-command.ts`
-2. Import from `../src/forge/headless`
-3. Call `await init()` then use `runScript()`
-4. Add script to `package.json`
-5. Update `docs/permanent/CLI.md`
-6. Commit: "Add [command] CLI command"
-
-### Adding UI State
-1. Add to `src/store/forgeStore.ts` interface
-2. Add initial value and actions
-3. Wire up to component
-4. Commit: "Add [feature] UI state"
-
-### Adding a Component
-1. Create in `src/components/`
-2. Import and use in `App.tsx` or parent
-3. Commit: "Add [Component] component"
-
-### Key Architecture Rule: Single Source of Truth
-All geometry logic lives in `src/forge/`. CLI tools import from `src/forge/headless.ts`.
-**Never** duplicate forge logic in CLI scripts. If you need something in CLI, make sure
-it's exported from `headless.ts` and import it.