forgecad 0.6.3 → 0.8.0

package/dist-skill/docs-dev/guides/geometry-conventions.md

@@ -0,0 +1,52 @@
+---
+skill-group: geometry
+skill-order: 2
+---
+
+# Geometry Conventions
+
+ForgeCAD wraps Manifold (mesh kernel) and Three.js (Y-up renderer). This doc captures convention mismatches and how ForgeCAD resolves them.
+
+## Winding Order
+
+CCW = positive area, CW = empty in Manifold's `CrossSection`. ForgeCAD auto-fixes at all entry points:
+- `polygon(points)` — computes signed area (shoelace), reverses if CW
+- `path().close()` — same fix
+
+**Rule for new code:** Any function accepting user point arrays that creates a `CrossSection` MUST auto-fix winding.
+
+## Coordinate System (Z-up vs Y-up)
+
+Three.js is Y-up; ForgeCAD is Z-up. Fix applied at camera level (`camera.up = (0,0,1)`) — geometry coordinates are native Z-up. Never swap Y/Z in geometry.
+
+## Revolution Axis
+
+`CrossSection.revolve()` revolves around Y. Profile X = radial distance, Profile Y = height (becomes Z after revolution). Profile must be at X > 0.
+
+## Boolean Winding (3D)
+
+Manifold requires consistent outward face normals. ForgeCAD only creates meshes through Manifold's own constructors, which guarantee correct normals.
+
+## Transform Order
+
+Transforms apply left-to-right. `rotate()`, `scale()`, `mirror()` operate around bounding-box center. Use `rotateAround([0,0,0], ...)` to orbit around world origin.
+
+For explicit transform objects: `A.mul(B)` = apply A then B; `composeChain(A, B, C)` = A→B→C.
+
+## Assembly Frame Composition
+
+```ts
+childWorld = composeChain(childBase, jointMotion, jointFrame, parentWorld)
+```
+
+Prefer `composeChain(...)` over manual `.mul(...).mul(...)` in kinematics code to avoid order mistakes.
+
+## Summary
+
+| Convention | User sees | Kernel needs | Where we fix it |
+|---|---|---|---|
+| Winding | Any point order | CCW | `polygon()`, `path().close()` |
+| Up axis | Z-up | Y-up (Three.js) | `camera.up`, gizmo labels |
+| Revolution | "revolve this profile" | Profile in X-Y, X>0 | Documented only |
+| Face normals | Doesn't think about it | Outward-pointing | Manifold constructors |
+| Transform order | Left-to-right chain | Post-multiply | Native match |

package/dist-skill/docs-dev/guides/joint-design.md

@@ -0,0 +1,78 @@
+---
+skill-group: recipes
+skill-order: 5
+---
+
+# Joint Design Recipes
+
+How to build mechanical joints — clevis-tongue hinges, ball-and-socket, dovetails — that actually rotate without binding and stop where they should.
+
+## The Cavity Rule
+
+Every mechanical joint has a **cavity** in one part and a **tenon** in the other. The cavity must be a real empty volume — not a gap implied by the absence of two separate solids.
+
+If two adjacent parts in an assembly show a collision volume larger than the expected clearance volume in `forgecad run`, one part is missing its cavity. Both parts have solid material at the same joint position. This will look fine at rest pose but will block rotation and produce confusing joint behavior.
+
+```ts
+// BAD — body has a stadium cap at both ends; the "slot" between two clevis tines
+// is just empty space next to a solid body cap. The next phalanx's tongue knuckle
+// has nowhere to go (it intersects the previous body's cap).
+const body  = stadiumBar(L);            // cap at X=0 AND X=L
+const tine1 = box(...).translate(L,  Y_OFF, 0);
+const tine2 = box(...).translate(L, -Y_OFF, 0);
+let phalanx = union(body, tine1, tine2);
+
+// GOOD — body ends FLAT before the joint. Tines extend forward to the pivot.
+// The X = L-KNUCK_R..L+KNUCK_R volume between the tines is genuinely empty.
+const body = box(L - KNUCK_R, TONG_T, H, true).translate((L - KNUCK_R) / 2, 0, 0);
+const tongueKnuckle = knuckleDisc(0, 0, TONG_T);  // proximal cap only
+let phalanx = union(tongueKnuckle, body, tine1, tine2, ...tineCaps);
+```
+
+After applying the cavity rule, `forgecad run` collision volume between adjacent parts in a clevis-tongue chain should drop to **zero** (or a few mm³ of clearance overlap). If it doesn't, there's still solid material where there should be a cavity.
+
+## Connecting Cantilevers
+
+A clevis tine arm at Y=±Y_OFF is geometrically separate from a body at Y=±TONG_T/2. With Y_OFF > TONG_T/2 + clearance, there is a **physical gap** between them. The tines float — they would snap off as soon as load is applied.
+
+Always add a **yoke**: a short slab spanning the full clevis width, sitting between the body's flat distal end and the tines' attachment point. The yoke fills the Y gap so material is continuous from the body through to each tine.
+
+```ts
+const yokeLen   = 3;                                  // a few mm of structural overlap
+const yokeStart = L - KNUCK_R - yokeLen;
+const totalY    = (Y_OFF + TINE_T / 2) * 2;           // full clevis width
+const yoke = box(yokeLen, totalY, H, true)
+  .translate(yokeStart + yokeLen / 2, 0, 0);
+phalanx = union(phalanx, yoke);
+```
+
+## Hard Stops vs Slider Limits
+
+`addRevolute({ min: 0, max: 90 })` sets **slider limits** — the viewport won't let the user drag past them, but the geometry permits any rotation. There is no physical stop.
+
+For a **geometric** hard stop (parts can't backbend past extension, or can't curl past full closure), add a small protrusion on one part that interferes with the other at the limit angle:
+
+- **Extension stop at 0°** (typical for fingers, knees, elbows): add a small "lip" on the dorsal side of the proximal end of the child phalanx, sized so it just touches the parent's distal dorsal corner at 0°. Negative rotation (backbending) is then blocked by part-on-part contact.
+- **Flexion stop at θmax**: add a similar lip on the palmar side, or rely on the body-to-body collision when bodies meet.
+
+Verify with `forgecad run` at the limit poses — the contact pair should show ~0 mm³ collision (just touching), and rotation past the limit should report a non-zero collision volume.
+
+## Knuckle Sizing
+
+For a clevis-tongue joint with body height H, the tongue knuckle radius and clevis tine knuckle radius must satisfy:
+
+```
+KNUCK_R >= H / 2
+```
+
+If the knuckle radius is smaller than the body's half-height, the body's corners protrude beyond the knuckle envelope. When the joint rotates, those corners sweep through space outside the cylindrical envelope and collide with the adjacent part.
+
+Setting `KNUCK_R = H / 2` exactly makes the body cross-section a stadium that perfectly fits the knuckle envelope.
+
+## Verification Workflow
+
+1. Build the joint at rest pose. Run `forgecad run`. Check collision volumes.
+2. If adjacent parts in the joint show > clearance-volume of overlap → missing cavity (apply the cavity rule).
+3. Render with `--focus PartName` to inspect each part in isolation. The clevis end should clearly show a gap between the tines (the cavity).
+4. Render at curl angles (set joint debug params) at 30°, 60°, 90°. No new collisions should appear from rotation.
+5. Render at -10° (backbend test). Either no rotation possible (geometric stop in place) or rotation occurs and you need to add a stop.

package/dist-skill/docs-dev/guides/modeling-recipes.md

@@ -0,0 +1,77 @@
+---
+skill-group: recipes
+skill-order: 1
+---
+
+# Modeling Recipes
+
+## Iteration Bias
+
+- Default to a buildable first pass instead of a long proposal.
+- Replace a broken model wholesale when that is faster than incremental patching.
+- Validate early with `forgecad run <file>`.
+
+## Common Patterns
+
+### Hollow Shell
+```javascript
+const outerBox = box(outer, outer, outer, true);
+const innerBox = box(outer - 2 * wall, outer - 2 * wall, outer - 2 * wall, true);
+return outerBox.subtract(innerBox);
+```
+
+### Sketch-Based Twist
+```javascript
+const outer = ngon(sides, radius);
+const inner = ngon(sides, radius - wall);
+return outer.subtract(inner).extrude(height, { twist: 45, divisions: 32 });
+```
+
+### Rounded Profiles
+```javascript
+// All convex corners — offset trick
+const base = rect(50, 30).offset(-3, 'Round').offset(3, 'Round');
+
+// Selected corners only
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
+```
+
+### Choosing the right sketch-rounding tool
+
+- `offset(-r).offset(+r)` — round every convex corner of a closed outline
+- `stroke(points, width, 'Round')` — centerline-based geometry (ribs, traces)
+- `filletCorners(points, ...)` — selective true-corner fillets on mixed profiles
+
+## Best Practices
+
+- All dimensions in millimeters; angles in degrees.
+- Primitives are centered on XY, base at Z=0. Use `placeReference('center', [0,0,0])` to center on all axes.
+- Prefer named intermediate values over deeply nested one-liners.
+- `union2d`, `difference2d`, `intersection2d` batch faster than chained `.add()` / `.subtract()`.
+
+## Debugging
+
+```javascript
+console.log("Volume:", shape.volume());
+```
+
+For sketch-heavy work, compare the raw profile and rounded profile side-by-side before extruding:
+
+```javascript
+return [
+  { name: "Raw", sketch: polygon(roofPoints) },
+  { name: "Rounded", sketch: filletCorners(roofPoints, [...]).translate(120, 0) },
+];
+```
+
+## Common Errors
+
+- `"Kernel not initialized"` — internal/runtime issue, reload the app
+- zero dimensions or self-intersecting sketches → invalid geometry
+- wrong variable name → `"Cannot read property of undefined"`
+
+For larger runnable examples, read `examples/api/`.

package/dist-skill/docs-dev/guides/positioning.md

@@ -0,0 +1,151 @@
+---
+skill-group: geometry
+skill-order: 3
+---
+
+# Positioning Strategy
+
+## Primitive origin convention
+
+All 3D primitives are **centered on XY, base at Z=0**:
+
+| Primitive | X range | Y range | Z range |
+|-----------|---------|---------|---------|
+| `box(60, 40, 20)` | [-30, 30] | [-20, 20] | [0, 20] |
+| `cylinder(50, 10)` | [-10, 10] | [-10, 10] | [0, 50] |
+| `sphere(15)` | [-15, 15] | [-15, 15] | [-15, 15] |
+| `torus(20, 5)` | [-25, 25] | [-25, 25] | [-5, 5] |
+
+Sphere and torus are fully centered (symmetric in Z). Box and cylinder sit on the XY ground plane — **Z goes up from zero, never negative**.
+
+This means `box(w, d, h).translate(0, 0, -h/2)` is wrong for "center on Z" — the box is already at `[0, h]`, not `[-h/2, h/2]`.
+
+---
+
+Most positioning bugs come from manual coordinate arithmetic. Use these methods in priority order.
+
+## 1. `group()` — local coordinates for multi-part assemblies
+
+The most common positioning bug: manually adding a parent's global offset to every sub-part. One wrong sign or forgotten variable and parts float into space. **Use `group()` to build parts in local coordinates (at the origin), then position the group once.**
+
+```javascript
+// BAD — every sub-part repeats the parent's global position
+const unitY = -18, unitZ = 70;
+const body = lib.roundedBox(100, 20, 32, 4).translate(0, unitY, unitZ);
+const panel = box(98, 2, 18).translate(0, unitY - 12, unitZ + 4);
+const louver = box(88, 2, 6).translate(0, unitY - 14, unitZ - 11);
+const led = sphere(1.2).translate(35, unitY - 12, unitZ + 9);
+
+// GOOD — build at local origin, group, translate once
+const body = lib.roundedBox(100, 20, 32, 4);
+const panel = box(98, 2, 18).translate(0, -12, 4);        // relative to local origin
+const louver = box(88, 2, 6).translate(0, -14, -11);      // relative to local origin
+const led = sphere(1.2).translate(35, -12, 9);             // relative to local origin
+const indoorUnit = group(
+  { name: 'Body', shape: body },
+  { name: 'Panel', shape: panel },
+  { name: 'Louver', shape: louver },
+  { name: 'LED', shape: led },
+).translate(0, -18, 70);  // ONE translate for the whole assembly
+```
+
+**Groups nest.** Build sub-assemblies as groups, then group those into larger assemblies — each level has its own local origin.
+
+```javascript
+const fan = group(hub, ...blades).translate(0, 25, 0);  // fan assembly
+const outdoorUnit = group(
+  { name: 'Body', shape: casing },
+  { name: 'Fan', shape: fan },             // already a group
+  { name: 'Grille', shape: grille },
+).translate(0, 23, -42);                    // position the whole outdoor unit
+```
+
+**When to use something else:** `group()` preserves individual shapes — you can't boolean (subtract/intersect) a group. If a sub-part needs a boolean with the parent body, do that boolean first in local coordinates, then group the result.
+
+## 2. Connectors + `matchTo()` — default for mating interfaces
+
+Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
+
+```javascript
+const shelf = box(200, 120, 10, true).withConnectors({
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+});
+const panel = box(12, 120, 200, true).withConnectors({
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+});
+const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
+// Dictionary form for multiple pairs on same target:
+const placed2 = shelf.matchTo(panel, { left_tab: "shelf_0" });
+// Named group children bubble connectors via dotted paths:
+const cabinet = group({ name: "Left", shape: panel });
+shelf.matchTo(cabinet, "left_tab", "Left.shelf_0");
+```
+
+**Why connectors first:** stable (don't shift on fillet/chamfer/boolean), semantic (carry type/gender), oriented (full frame), queryable (`shape.connectorDistance('a','b')`), explode-aware.
+
+## 3. `pointAlong()` — orient cylinders before positioning
+
+```javascript
+// BAD
+const pipe = cylinder(100, 5).rotateX(90).translate(x, y, z);
+// GOOD — reads as "pipe pointing along Y"
+const pipe = cylinder(100, 5).pointAlong([0, 1, 0]).translate(x, y, z);
+```
+
+**Always call `pointAlong()` BEFORE `matchTo()` or `translate()`** — it reorients around the origin.
+
+## 4. `attachTo()` — quick bounding-box positioning
+
+```javascript
+const column = cylinder(50, 8).attachTo(base, 'top', 'bottom');
+```
+
+`child.attachTo(parent, parentAnchor, selfAnchor, offset)`. Anchor points shift on fillet/chamfer/boolean — fragile for assembly interfaces, fine for quick prototyping.
+
+## 5. `rotateAroundTo()` — aim a point around a hinge/axis
+
+```javascript
+const aimed = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 20]);
+// Exact line solve:
+const lineHit = arm.rotateAroundTo([0, 0, 1], [0, 0, 0], "tip", [30, 30, 0], { mode: 'line' });
+```
+
+## 6. `moveToLocal()` — offset from another shape's min corner
+
+```javascript
+const part = box(20, 20, 30).moveToLocal(base, 10, 10, 10);
+```
+
+## 7. `translate()` — for simple offsets or bridging computed locations
+
+```javascript
+const pipeLen = bb2.min[1] - bb1.max[1];
+const pipe = cylinder(pipeLen, 5).pointAlong([0, 1, 0]).translate(40, (bb1.max[1] + bb2.min[1]) / 2, bb1.min[2] + 15);
+```
+
+## 8. `placeReference()` — align any anchor to a world coordinate
+
+Place a shape so a named anchor point lands exactly where you want it. Accepts all built-in anchors (`'bottom'`, `'center'`, `'top-front-left'`, etc.) plus custom references from `withReferences()`.
+
+```javascript
+// Ground a shape — bottom face center at Z = 0
+const grounded = shape.placeReference('bottom', [0, 0, 0])
+
+// Center at the world origin
+const centered = shape.placeReference('center', [0, 0, 0])
+
+// Align left edge to X = 10
+const aligned = shape.placeReference('left', [10, 0, 0])
+```
+
+Also works with custom placement references for cross-file parts:
+
+```javascript
+// widget.forge.js — define once
+return union(base, post).withReferences({ points: { mount: [0, -16, -4] } });
+
+// importer — consume
+const widget = require("./widget.forge.js").placeReference("mount", [120, 40, 0]);
+```
+
+For cross-file parts needing proper alignment, prefer connectors over placement references.

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

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-skill
 skill-order: 1
-skill-tiers: [dev]
 ---
 
 # Skill System Maintenance
@@ -47,14 +46,12 @@ The build script discovers docs by scanning `docs/permanent/` for files with `sk
 |-------|----------|---------|-------------|
 | `skill-group` | Yes | — | Group name (must match `GROUP_REGISTRY` in build script) |
 | `skill-order` | No | 50 | Sort order within the group |
-| `skill-tiers` | No | `[standard, one-file]` | Which outputs include this file |
 
-### Tier values
+### Inclusion rules
 
-- `[standard, one-file]` (default) — included in installed skill and CONTEXT.md
-- `[standard]` — installed skill only (too verbose for one-file paste)
-- `[one-file]` — CONTEXT.md only (slim excerpt replacing a standard doc)
-- `[dev]` — dev skill only (SKILL-dev.md)
+- **`skill-group: <name>`** — included in SKILL.md (index) and CONTEXT.md (inlined).
+- **`skill-group: dev-<name>`** — dev-only, appears in SKILL-dev.md only.
+- **No `skill-group`** — not part of the skill at all.
 
 ### Adding a new group
 
@@ -62,12 +59,11 @@ If you need a new group, add it to `GROUP_REGISTRY` in `scripts/build-forgecad-s
 
 ## Adding Dev-Only Docs
 
-Use `skill-tiers: [dev]` in the frontmatter. These appear in `SKILL-dev.md` but not in `SKILL.md` or `CONTEXT.md`. Use this for:
+Use a `skill-group` with a `dev-` prefix (e.g. `dev-compiler`, `dev-solver`, `dev-conventions`). These appear in `SKILL-dev.md` but not in `SKILL.md` or `CONTEXT.md`. Use this for:
 
 - Compiler/solver internals
 - Coding conventions and PR guidelines
-- Deployment and release processes
-- Full CLI reference (vs the slim `skill-cli.md` excerpt)
+- Full CLI reference (vs the slim user-facing docs)
 
 ## Deciding Standard vs Dev
 
@@ -78,6 +74,21 @@ Use `skill-tiers: [dev]` in the frontmatter. These appear in `SKILL-dev.md` but
 | Does it cover team process (coding standards, releases, CI)? | Dev only |
 | Is it a CLI command only developers run (`check suite`, `sdf`, debug flags)? | Dev only |
 
+## Orphan files
+
+`skill install` uses `cpSync` — it copies `dist-skill/docs/` on top of the installed skill directory but **does not delete** files that no longer exist in the source. If a doc is removed or loses its `skill-group` frontmatter, its copy persists in `~/.agents/skills/forgecad/docs/` as an orphan.
+
+To check for orphans:
+```bash
+for f in $(find ~/.agents/skills/forgecad/docs -name '*.md'); do
+  echo "$f" | grep -q '/generated/' && continue
+  base=$(echo "$f" | sed "s|$HOME/.agents/skills/forgecad/docs/|docs/permanent/|")
+  [ -f "$base" ] || echo "ORPHAN: $f"
+done
+```
+
+Delete any orphans found. They're stale copies that can mislead agents with outdated information.
+
 ## Verifying
 
 After changes, check that the build succeeds and the doc counts look right:

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

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-compiler
 skill-order: 1
-skill-tiers: [dev]
 ---
 
 # Forge Compiler Architecture
@@ -173,10 +172,10 @@ Current progress:
 - trim/split-by-plane, shell, hole, cut, boolean, and edge-finish rewrites now also declare descendant contracts on top of that propagation kernel
 - the shared descendant-resolution layer turns those lineage inputs into defended singles, face regions/sets, edge chains, or explicit unsupported results instead of making each caller reverse-engineer rewrite heuristics
 - trim/split-by-plane now expose their plane-cap face plus descendant-region contracts for preserved source surfaces, while hole/cut host-face splits and supported boolean difference/intersection descendants stay reviewable as defended regions instead of disappearing behind one generic ambiguity bucket
-- boolean rewrites now consume that same contract: supported unions still preserve operand canonical-face/query lineage when the source owners stay distinct, and coplanar/multi-member descendants can now surface as defended face sets instead of only masked name conflicts
+- boolean rewrites now consume that same contract: supported unions still preserve operand label/query lineage when the source owners stay distinct, and coplanar/multi-member descendants can now surface as defended face sets instead of only masked name conflicts
 - shell, hole, and cut now layer defended created-face slots plus defended descendant regions on top of that propagation kernel instead of leaving all post-rewrite face meaning as placeholders
 - compile-covered `Shape.face(name)` resolution now reads from the compile graph plus the descendant layer, so supported shell inner walls, blind-hole floors, cut-created walls, split host faces, and defended boolean face sets can produce real `FaceRef` values after topology rewrites
-- non-canonical `onFace(shape, 'inner-side-right', ...)` placement now routes through that same compiler-owned face resolver, while direct `FaceRef` placements preserve created-face/propagated-face provenance instead of collapsing everything back to anonymous refs
+- label-based `onFace(shape, 'inner-side-right', ...)` placement now routes through the compiler-owned face resolver, while direct `FaceRef` placements preserve created-face/propagated-face provenance instead of collapsing everything back to anonymous refs
 - `src/forge/kernel.ts` and the compiler inspection surface now expose collected topology-rewrite propagation plus descendant contracts directly, and the placement/compiler invariants assert that those contracts stay inspectable and deterministic through later transforms
 - `forgecad check query-propagation` now snapshots both the propagation surface and the descendant contracts directly, so defended plane-cap faces, split-face regions, face sets, merged-edge chains, and explicit unsupported rewrite boundaries stay reviewable without wading through the full compiler-scene baseline
 
@@ -217,10 +216,10 @@ Current progress:
 - the regression suite now also includes a file-backed ordinary-parts corpus under `examples/compiler-corpus/`, so shell, richer hole/cut workflows, projection replay, trim-created faces, repeated descendants, and finishing flows are exercised together instead of only as isolated unit slices
 - the MLP closeout review surface now lives in that corpus plus `forgecad check compiler`, `forgecad check query-propagation`, and `forgecad check brep`, so the defended subset is reviewable from the repo instead of from tribal knowledge
 - mirrored downstream features and helper-driven linear/circular repetition now preserve repeated-result ownership on top of the shared face-query backbone
-- supported boolean unions now also preserve owner-scoped canonical face queries from repeated descendants, and compiler regressions cover both explicit duplicate-owner merge ambiguity and later boolean chains that inherit those propagated queries
+- supported boolean unions now also preserve owner-scoped label queries from repeated descendants, and compiler regressions cover both explicit duplicate-owner merge ambiguity and later boolean chains that inherit those propagated queries
 - exact export regression coverage now includes a repeated-feature part where a mirrored descendant drives a downstream workplane feature inside a boolean chain
 - `projectToPlane()` sketches now keep an explicit projection node in the compiler graph instead of collapsing immediately to anonymous runtime geometry
-- compile-covered `Sketch.onFace(shape, name)` resolution now prefers the defended face-query table on `Shape` targets, so supported boolean-preserved names and explicit repeated-descendant `FaceRef`s stay visible to later features instead of falling back to anonymous canonical heuristics
+- compile-covered `Sketch.onFace(shape, name)` resolution now prefers the defended face-query table on `Shape` targets, so supported boolean-preserved names and explicit repeated-descendant `FaceRef`s stay visible to later features instead of falling back to anonymous heuristics
 - the supported exact subset can now replay projection-driven follow-on features when the source reduces to one defended planar projection basis: placed straight extrusions, compatible shell/hole/cut descendants, and boolean unions of compatible projected operands all stay aligned on matching parallel target planes
 
 Current limits:
@@ -230,7 +229,7 @@ Current limits:
 - `filletEdge()` / `chamferEdge()` v1 cover tracked vertical edges on compile-covered `box()` and `rectangle(...).extrude(...)` bodies plus preserved propagated sibling edges through supported edge-finish and boolean-union chains; the selected rewritten edge now resolves as an explicit descendant edge-chain for inspection/debug, but not yet as a new single finishable edge target
 - two-sided extents, tapered cutouts, and thread metadata are now supported; combined counterbore+countersink heads, modeled helical threads, and broader durable identity beyond today's defended shell/hole/cut created-face subset are still missing
 - `upToFace` currently requires a planar termination face parallel to the feature direction, but defended split termination faces can now stay queryable as descendant regions where Forge still owns the source plane
-- boolean/pattern propagation currently defends owner-scoped canonical face lineage through supported unions, and the descendant layer can now expose some post-merge/post-difference results as face sets/regions, but broader durable per-face ownership after arbitrary merged topology changes is still incomplete
+- boolean/pattern propagation currently defends owner-scoped face label lineage through supported unions, and the descendant layer can now expose some post-merge/post-difference results as face sets/regions, but broader durable per-face ownership after arbitrary merged topology changes is still incomplete
 - repeated-feature ownership currently tracks repeated bodies and mirrored descendants, not durable per-face identity after merged pattern topology changes
 - shell, hole/cut, tracked-edge finishing, and repeated-feature workflows now preserve parent-body ownership lineage, but stable downstream face/edge ownership after topology-changing edits is still not solved, which is why richer boolean-difference/intersection targets and broader fillet/chamfer workflows remain harder next layers
 - projection replay still rejects boolean difference/intersection sources, trim/fillet/chamfer silhouette changes, and non-parallel projection bases with explicit compiler diagnostics instead of silently pretending those paths are exact-safe

package/dist-skill/{docs → docs-dev}/internals/constraint-solver-quality.md

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-solver
 skill-order: 2
-skill-tiers: [dev]
 ---
 
 # Constraint Solver Quality — What's Tunable vs What's Architecture

package/dist-skill/{docs → docs-dev}/internals/constraint-solver.md

@@ -1,7 +1,6 @@
 ---
 skill-group: dev-solver
 skill-order: 1
-skill-tiers: [dev]
 ---
 
 # Constraint Solver Internals

package/dist-skill/{docs → docs-dev}/internals/sketch-2d-pipeline.md

@@ -1,7 +1,6 @@
 ---
-skill-group: dev-sketch-pipeline
-skill-order: 1
-skill-tiers: [dev]
+skill-group: dev-compiler
+skill-order: 2
 ---
 
 # 2D Sketch Pipeline: Manifold ↔ ProfileCompilePlan ↔ OCCT

package/examples/api/attachTo-basics.forge.js

@@ -8,31 +8,31 @@
 //   2 words = edge midpoint: 'top-front', 'back-left', etc.
 //   3 words = corner:        'top-front-left', 'bottom-back-right', etc.
 
-const baseW = param("Base Width", 100, { min: 50, max: 200, unit: "mm" });
-const baseD = param("Base Depth", 80, { min: 40, max: 150, unit: "mm" });
-const baseH = param("Base Height", 10, { min: 5, max: 30, unit: "mm" });
+const baseW = Param.number("Base Width", 100, { min: 50, max: 200, unit: "mm" });
+const baseD = Param.number("Base Depth", 80, { min: 40, max: 150, unit: "mm" });
+const baseH = Param.number("Base Height", 10, { min: 5, max: 30, unit: "mm" });
 
-const base = box(baseW, baseD, baseH, true).color('#888888');
+const base = box(baseW, baseD, baseH).color('#888888');
 
 // Stack on top: column's bottom face meets base's top face
 const column = cylinder(40, 8).color('#4488cc')
   .attachTo(base, 'top', 'bottom');
 
 // Protrude from front: button's back face meets base's front face
-const button = box(20, 6, 10, true).color('#cc4444')
+const button = box(20, 6, 10).color('#cc4444')
   .attachTo(base, 'front', 'back');
 
 // Hang below: bracket's top face meets base's bottom face
-const bracket = box(30, 30, 5, true).color('#44cc44')
+const bracket = box(30, 30, 5).color('#44cc44')
   .attachTo(base, 'bottom', 'top');
 
 // Attach to side with offset: panel's left face meets base's right face,
 // then shift 0mm on X, 0mm on Y, 10mm up on Z
-const sidePanel = box(4, 40, 25, true).color('#cc8844')
+const sidePanel = box(4, 40, 25).color('#cc8844')
   .attachTo(base, 'right', 'left', [0, 0, 10]);
 
 // Corner alignment: small cube at top-front-right corner of base
-const corner = box(8, 8, 8, true).color('#8844cc')
+const corner = box(8, 8, 8).color('#8844cc')
   .attachTo(base, 'top-front-right', 'bottom-back-left');
 
 return [

package/examples/api/bill-of-materials.forge.js

@@ -1,14 +1,14 @@
 // API demo: script-declared bill of materials that gets auto-summed in report export
 
-const frameWidth = param('Frame Width', 900, { min: 300, max: 1800, unit: 'mm' });
-const frameDepth = param('Frame Depth', 500, { min: 200, max: 1200, unit: 'mm' });
-const legHeight = param('Leg Height', 720, { min: 300, max: 1200, unit: 'mm' });
-const tubeW = param('Tube Width', 30, { min: 15, max: 80, unit: 'mm' });
-const tubeH = param('Tube Height', 20, { min: 10, max: 80, unit: 'mm' });
-
-const frontBolts = param('Front Bolts', 8, { min: 0, max: 64, integer: true });
-const rearBolts = param('Rear Bolts', 8, { min: 0, max: 64, integer: true });
-const boltLength = param('Bolt Length', 16, { min: 6, max: 60, unit: 'mm' });
+const frameWidth = Param.number('Frame Width', 900, { min: 300, max: 1800, unit: 'mm' });
+const frameDepth = Param.number('Frame Depth', 500, { min: 200, max: 1200, unit: 'mm' });
+const legHeight = Param.number('Leg Height', 720, { min: 300, max: 1200, unit: 'mm' });
+const tubeW = Param.number('Tube Width', 30, { min: 15, max: 80, unit: 'mm' });
+const tubeH = Param.number('Tube Height', 20, { min: 10, max: 80, unit: 'mm' });
+
+const frontBolts = Param.number('Front Bolts', 8, { min: 0, max: 64, integer: true });
+const rearBolts = Param.number('Rear Bolts', 8, { min: 0, max: 64, integer: true });
+const boltLength = Param.number('Bolt Length', 16, { min: 6, max: 60, unit: 'mm' });
 
 const wall = 2;
 const longTubeMm = frameWidth * 2;

package/examples/api/bolt-pattern.forge.js

@@ -1,10 +1,10 @@
 // Bolt Pattern — circularPattern + linearPattern demo
 
-const baseR = param("Base Radius", 40, { min: 20, max: 80, unit: "mm" });
-const baseH = param("Base Height", 10, { min: 5, max: 20, unit: "mm" });
-const boltR = param("Bolt Radius", 3, { min: 1, max: 6, unit: "mm" });
-const boltCount = param("Bolt Count", 6, { min: 3, max: 12 });
-const boltCircleR = param("Bolt Circle", 30, { min: 15, max: 70, unit: "mm" });
+const baseR = Param.number("Base Radius", 40, { min: 20, max: 80, unit: "mm" });
+const baseH = Param.number("Base Height", 10, { min: 5, max: 20, unit: "mm" });
+const boltR = Param.number("Bolt Radius", 3, { min: 1, max: 6, unit: "mm" });
+const boltCount = Param.number("Bolt Count", 6, { min: 3, max: 12 });
+const boltCircleR = Param.number("Bolt Circle", 30, { min: 15, max: 70, unit: "mm" });
 
 // Base plate
 const base = circle2d(baseR).extrude(baseH);

package/examples/api/boolean-operations.forge.js

@@ -9,13 +9,13 @@
 // and the helper functions also accept arrays:
 // difference([a, b, c]), union([a, b, c]), intersection([a, b, c])
 
-const size = param("Size", 30, { min: 15, max: 50, unit: "mm" });
-const overlap = param("Overlap", 15, { min: 0, max: 30, unit: "mm" });
+const size = Param.number("Size", 30, { min: 15, max: 50, unit: "mm" });
+const overlap = Param.number("Overlap", 15, { min: 0, max: 30, unit: "mm" });
 const spacing = 80;
 
 // Two overlapping shapes for each demo
 function makePair(offsetX) {
-  const a = box(size, size, size, true).translate(offsetX, 0, 0).color('#4488cc');
+  const a = box(size, size, size).translate(offsetX, 0, 0).color('#4488cc');
   const b = sphere(size * 0.6).translate(offsetX + size - overlap, 0, 0).color('#cc4444');
   return [a, b];
 }
@@ -26,7 +26,7 @@ const unioned = union(u1, u2).color('#8866cc');
 
 // 2. Difference — box minus sphere and cross-bore
 const [d1, d2] = makePair(spacing);
-const d3 = cylinder(size * 1.2, size * 0.14, undefined, undefined, true)
+const d3 = cylinder(size * 1.2, size * 0.14)
   .pointAlong([0, 1, 0])
   .translate(spacing, 0, 0);
 const diffed = d1.subtract(d2, d3);
@@ -36,7 +36,7 @@ const [i1, i2] = makePair(2 * spacing);
 const intersected = intersection(i1, i2).color('#cc8844');
 
 // Show the original shapes (translucent-ish via separate objects) for reference
-const refA = box(size, size, size, true).translate(3 * spacing, 0, 0).color('#4488cc');
+const refA = box(size, size, size).translate(3 * spacing, 0, 0).color('#4488cc');
 const refB = sphere(size * 0.6).translate(3 * spacing + size - overlap, 0, 0).color('#cc4444');
 
 return [

package/examples/api/bounding-box-visualizer.forge.js

@@ -36,8 +36,8 @@ function vizBBox(shape) {
 // --- Demo shapes ---
 
 // A rotated box — bbox is larger than the shape itself
-const angle = param("Rotation", 30, { min: 0, max: 90, unit: "°" });
-const rotBox = box(40, 30, 20, true).rotate(0, 0, angle).color('#4488cc');
+const angle = Param.number("Rotation", 30, { min: 0, max: 90, unit: "°" });
+const rotBox = box(40, 30, 20).rotateZ(angle).color('#4488cc');
 const rotBBox = vizBBox(rotBox).color('#cc4444');
 
 // A sphere — bbox is a perfect cube around it
@@ -45,7 +45,7 @@ const sph = sphere(20).translate(80, 0, 0).color('#44cc44');
 const sphBBox = vizBBox(sph).color('#cc4444');
 
 // A tilted cylinder — bbox shows the extent
-const tiltCyl = cylinder(50, 10).rotate(30, 0, 0).translate(0, 80, 0).color('#cc88ff');
+const tiltCyl = cylinder(50, 10).rotateX(30).translate(0, 80, 0).color('#cc88ff');
 const cylBBox = vizBBox(tiltCyl).color('#cc4444');
 
 return [

package/examples/api/clone-duplicate.forge.js

@@ -1,9 +1,9 @@
 // clone() / duplicate() — explicit copy helpers for Shape, TrackedShape, Sketch, and ShapeGroup.
 
-const spacing = param("Spacing", 90, { min: 40, max: 180, unit: "mm" });
+const spacing = Param.number("Spacing", 90, { min: 40, max: 180, unit: "mm" });
 
 // --- Shape clone ---
-const block = box(36, 20, 12, true).color("#4a90e2");
+const block = box(36, 20, 12).color("#4a90e2");
 const blockL = block.clone().translate(-spacing / 2, 0, 0);
 const blockR = block.duplicate().translate(spacing / 2, 0, 0);