forgecad 0.6.3 → 0.8.0

package/dist-skill/SKILL-dev.md

@@ -5,43 +5,25 @@ description: ForgeCAD development skill — model authoring plus compiler intern
 
 # ForgeCAD
 
-Author or modify ForgeCAD models, sketches, assemblies, notebooks, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.
+Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.
 
 ## Workflow
 
-1. Identify the artifact: `.forge.js`, `.forge-notebook.json`, SVG asset, or CLI/export task.
-2. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed.
-3. Default to a concrete first pass — easy iteration beats speculative design review.
-4. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
-5. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues). This works for notebook preview cells too.
-6. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
+1. Identify the artifact: `.forge.js`, SVG asset, or CLI/export task.
+2. **If the model has any moving parts, load the `assembly` group AND the `joint-design.md` recipe upfront** — do not defer the kinematic structure to a refactor pass.
+3. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed.
+4. Default to a concrete first pass — easy iteration beats speculative design review.
+5. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
+6. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues).
+7. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
 
 ### Import and Composition
 
 - `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).
-- `.withReferences()` + `.placeReference()` for reusable placement.
+- `.placeReference('bottom', [0,0,0])` to align any built-in anchor to a world coordinate; also works with custom `.withReferences()`.
 - Plain `.js` modules for shared helpers/constants (not model imports).
 
-### Notebooks
-
-Use `.forge-notebook.json` for stateful iteration and debugging. Cells share state, `show()` pins visible geometry, and the preview cell can be validated or rendered directly from the CLI.
-
-Prefer notebooks when:
-
-- the task is exploratory or the geometry strategy is still unclear
-- you are debugging booleans, placements, or assembly kinematics
-- you want to inspect intermediate shapes or sketches without rewriting the whole file
-
-Useful notebook loop:
-
-- keep stable setup in early cells and the current experiment in the preview cell
-- use `show(...)` for intermediate geometry you want pinned in the viewport
-- use `forgecad notebook view <file> preview` to inspect the notebook from the terminal
-- use `forgecad run <file>.forge-notebook.json` for preview-cell validation and spatial analysis
-- use `forgecad render <file>.forge-notebook.json` or `forgecad capture gif <file>.forge-notebook.json --list` to inspect the preview cell through the CLI
-- export to `.forge.js` when the exploratory phase is over and the structure is ready to stabilize
-
 ## Source Map
 
 Load groups top-to-bottom, stopping when you have what the task needs.
@@ -50,19 +32,9 @@ Load groups top-to-bottom, stopping when you have what the task needs.
 
 Execution model, colors, coordinate system, primitives, booleans, patterns, imports, parameters, topology, edge queries.
 
-- `{{SKILL_DIR}}/docs/API/core/reserved-terms.md`
 - `{{SKILL_DIR}}/docs/API/core/concepts.md`
-- `{{SKILL_DIR}}/docs/API/core/parameters.md`
-- `{{SKILL_DIR}}/docs/API/core/topology.md`
-- `{{SKILL_DIR}}/docs/API/core/edge-queries.md`
 - `{{SKILL_DIR}}/docs/generated/core.md`
 
-### 1b. SDF Modeling (when using smooth booleans, TPMS, deformations, or fromFunction)
-
-Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas.
-
-- `{{SKILL_DIR}}/docs/API/core/sdf.md`
-
 ### 2. Geometry and Positioning (when placement/orientation matters)
 
 Axis conventions, winding rules, and placement strategy.
@@ -71,21 +43,10 @@ Axis conventions, winding rules, and placement strategy.
 - `{{SKILL_DIR}}/docs/guides/geometry-conventions.md`
 - `{{SKILL_DIR}}/docs/guides/positioning.md`
 
-### 3. Sketch APIs (when the task is sketch-heavy)
+### 3. Sketch APIs
 
 2D construction, transforms, booleans, paths, on-face sketching, extrusion, anchors, text, regions.
 
-- `{{SKILL_DIR}}/docs/API/sketch/core.md`
-- `{{SKILL_DIR}}/docs/API/sketch/primitives.md`
-- `{{SKILL_DIR}}/docs/API/sketch/path.md`
-- `{{SKILL_DIR}}/docs/API/sketch/transforms.md`
-- `{{SKILL_DIR}}/docs/API/sketch/booleans.md`
-- `{{SKILL_DIR}}/docs/API/sketch/operations.md`
-- `{{SKILL_DIR}}/docs/API/sketch/on-face.md`
-- `{{SKILL_DIR}}/docs/API/sketch/extrude.md`
-- `{{SKILL_DIR}}/docs/API/sketch/anchor.md`
-- `{{SKILL_DIR}}/docs/API/sketch/text.md`
-- `{{SKILL_DIR}}/docs/API/sketch/regions.md`
 - `{{SKILL_DIR}}/docs/generated/sketch.md`
 
 ### 4. Curves and Surfacing (for lofts, sweeps, splines)
@@ -98,38 +59,31 @@ Smooth curves, Hermite splines, lofted and swept solids.
 
 Assembly graph, joint types, couplings, validation, robot export.
 
-- `{{SKILL_DIR}}/docs/API/assembly/assembly.md`
 - `{{SKILL_DIR}}/docs/generated/assembly.md`
 
 ### 6. Sheet Metal (for bent parts, K-factor, flat patterns)
 
 Bend operations, flat pattern unfolding, K-factor configuration.
 
-- `{{SKILL_DIR}}/docs/API/sheet-metal/sheet-metal.md`
 - `{{SKILL_DIR}}/docs/generated/sheet-metal.md`
 
 ### 7. Output and Export (for STL/3MF/STEP, BOM, dimensions)
 
 Mesh export, exact geometry export, bill of materials, dimension annotations.
 
-- `{{SKILL_DIR}}/docs/API/output/export.md`
-- `{{SKILL_DIR}}/docs/API/output/brep-export.md`
-- `{{SKILL_DIR}}/docs/API/output/bom.md`
-- `{{SKILL_DIR}}/docs/API/output/dimensions.md`
 - `{{SKILL_DIR}}/docs/generated/output.md`
 
 ### 8. Toolbox (fasteners and standard parts)
 
 Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural profiles.
 
-- `{{SKILL_DIR}}/docs/API/toolbox/fasteners.md`
 - `{{SKILL_DIR}}/docs/generated/lib.md`
+- `{{SKILL_DIR}}/docs/generated/wood.md`
 
 ### 9. Runtime Viewport APIs (for cut planes, jointsView, and animation playback)
 
 Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavior.
 
-- `{{SKILL_DIR}}/docs/API/runtime/viewport.md`
 - `{{SKILL_DIR}}/docs/generated/viewport.md`
 
 ### 10. Recipes and Debugging (for patterns and troubleshooting)
@@ -137,18 +91,26 @@ Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavi
 Modeling patterns, debugging tactics, copyable snippets.
 
 - `{{SKILL_DIR}}/docs/guides/modeling-recipes.md`
+- `{{SKILL_DIR}}/docs/guides/joint-design.md`
 
 ### 11. CLI (for validation/render/export tasks)
 
-Test-run, notebook execution, export pipelines, debug flags.
+Test-run, export pipelines, debug flags.
 
 - `{{SKILL_DIR}}/docs/CLI.md`
 
+### SDF Modeling — Experimental (smooth booleans, TPMS, deformations, fromFunction)
+
+Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas. Experimental — slower render, lower mesh quality than B-rep.
+
+- `{{SKILL_DIR}}/docs/generated/sdf.md`
+
 ### 12. Internals — Compiler & Geometry Pipeline (for ForgeCAD developers)
 
 Semantic feature graphs, lowering strategy, compile plans. Read when working on the compiler or geometry backends.
 
 - `{{SKILL_DIR}}/docs/internals/compiler.md`
+- `{{SKILL_DIR}}/docs/internals/sketch-2d-pipeline.md`
 
 ### 13. Internals — Constraint Solver (for solver work)
 
@@ -157,20 +119,14 @@ Solver architecture, phases, Gauss-Seidel/Newton-Raphson, quality tuning.
 - `{{SKILL_DIR}}/docs/internals/constraint-solver.md`
 - `{{SKILL_DIR}}/docs/internals/constraint-solver-quality.md`
 
-### 14. Internals — Sketch 2D Pipeline
-
-2D sketch pipeline stages, constraint evaluation, winding enforcement.
-
-- `{{SKILL_DIR}}/docs/internals/sketch-2d-pipeline.md`
-
 ### 15. Project Conventions (coding standards, releases)
 
 Coding best practices, PR guidelines, release checklist, deployment.
 
 - `{{SKILL_DIR}}/docs/coding-best-practices.md`
 - `{{SKILL_DIR}}/docs/coding.md`
-- `{{SKILL_DIR}}/docs/deployment.md`
-- `{{SKILL_DIR}}/docs/RELEASING.md`
+- `{{SKILL_DIR}}/docs/blueprint-first.md`
+- `{{SKILL_DIR}}/docs/component-model.md`
 
 ### 16. Skill System Maintenance
 

package/dist-skill/SKILL.md

@@ -1,47 +1,29 @@
 ---
 name: forgecad
-description: ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, .forge-notebook.json, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, running notebook cells, validating scripts, or using ForgeCAD export/render tooling.
+description: ForgeCAD model authoring, editing, debugging, and execution guidance for .forge.js, SVG-import, assembly, and CLI workflows. Use when building or modifying ForgeCAD geometry, structuring multi-file projects, validating scripts, or using ForgeCAD export/render tooling.
 ---
 
 # ForgeCAD
 
-Author or modify ForgeCAD models, sketches, assemblies, notebooks, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.
+Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefer documented primitives, import rules, placement strategies, and CLI commands over inventing new APIs.
 
 ## Workflow
 
-1. Identify the artifact: `.forge.js`, `.forge-notebook.json`, SVG asset, or CLI/export task.
-2. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed.
-3. Default to a concrete first pass — easy iteration beats speculative design review.
-4. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
-5. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues). This works for notebook preview cells too.
-6. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
+1. Identify the artifact: `.forge.js`, SVG asset, or CLI/export task.
+2. **If the model has any moving parts, load the `assembly` group AND the `joint-design.md` recipe upfront** — do not defer the kinematic structure to a refactor pass.
+3. Load only the docs the task needs (see Source Map below). Start from the top group, add others as needed.
+4. Default to a concrete first pass — easy iteration beats speculative design review.
+5. If an existing model is broken, replace the weak structure rather than preserving bad architecture.
+6. Validate with `forgecad run <file>` (add `--debug-imports` for import chain issues).
+7. For `jointsView()` animations, keep wrapped revolute tracks continuous across branch cuts; do not assume the viewport will auto-fix `-180/180` jumps.
 
 ### Import and Composition
 
 - `require("./file.forge.js", { Param: value })` for any model file, with optional param overrides.
 - `importSvgSketch()` for SVG files (file format loader, not a module import).
-- `.withReferences()` + `.placeReference()` for reusable placement.
+- `.placeReference('bottom', [0,0,0])` to align any built-in anchor to a world coordinate; also works with custom `.withReferences()`.
 - Plain `.js` modules for shared helpers/constants (not model imports).
 
-### Notebooks
-
-Use `.forge-notebook.json` for stateful iteration and debugging. Cells share state, `show()` pins visible geometry, and the preview cell can be validated or rendered directly from the CLI.
-
-Prefer notebooks when:
-
-- the task is exploratory or the geometry strategy is still unclear
-- you are debugging booleans, placements, or assembly kinematics
-- you want to inspect intermediate shapes or sketches without rewriting the whole file
-
-Useful notebook loop:
-
-- keep stable setup in early cells and the current experiment in the preview cell
-- use `show(...)` for intermediate geometry you want pinned in the viewport
-- use `forgecad notebook view <file> preview` to inspect the notebook from the terminal
-- use `forgecad run <file>.forge-notebook.json` for preview-cell validation and spatial analysis
-- use `forgecad render <file>.forge-notebook.json` or `forgecad capture gif <file>.forge-notebook.json --list` to inspect the preview cell through the CLI
-- export to `.forge.js` when the exploratory phase is over and the structure is ready to stabilize
-
 ## Source Map
 
 Load groups top-to-bottom, stopping when you have what the task needs.
@@ -50,19 +32,9 @@ Load groups top-to-bottom, stopping when you have what the task needs.
 
 Execution model, colors, coordinate system, primitives, booleans, patterns, imports, parameters, topology, edge queries.
 
-- `{{SKILL_DIR}}/docs/API/core/reserved-terms.md`
 - `{{SKILL_DIR}}/docs/API/core/concepts.md`
-- `{{SKILL_DIR}}/docs/API/core/parameters.md`
-- `{{SKILL_DIR}}/docs/API/core/topology.md`
-- `{{SKILL_DIR}}/docs/API/core/edge-queries.md`
 - `{{SKILL_DIR}}/docs/generated/core.md`
 
-### 1b. SDF Modeling (when using smooth booleans, TPMS, deformations, or fromFunction)
-
-Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas.
-
-- `{{SKILL_DIR}}/docs/API/core/sdf.md`
-
 ### 2. Geometry and Positioning (when placement/orientation matters)
 
 Axis conventions, winding rules, and placement strategy.
@@ -71,21 +43,10 @@ Axis conventions, winding rules, and placement strategy.
 - `{{SKILL_DIR}}/docs/guides/geometry-conventions.md`
 - `{{SKILL_DIR}}/docs/guides/positioning.md`
 
-### 3. Sketch APIs (when the task is sketch-heavy)
+### 3. Sketch APIs
 
 2D construction, transforms, booleans, paths, on-face sketching, extrusion, anchors, text, regions.
 
-- `{{SKILL_DIR}}/docs/API/sketch/core.md`
-- `{{SKILL_DIR}}/docs/API/sketch/primitives.md`
-- `{{SKILL_DIR}}/docs/API/sketch/path.md`
-- `{{SKILL_DIR}}/docs/API/sketch/transforms.md`
-- `{{SKILL_DIR}}/docs/API/sketch/booleans.md`
-- `{{SKILL_DIR}}/docs/API/sketch/operations.md`
-- `{{SKILL_DIR}}/docs/API/sketch/on-face.md`
-- `{{SKILL_DIR}}/docs/API/sketch/extrude.md`
-- `{{SKILL_DIR}}/docs/API/sketch/anchor.md`
-- `{{SKILL_DIR}}/docs/API/sketch/text.md`
-- `{{SKILL_DIR}}/docs/API/sketch/regions.md`
 - `{{SKILL_DIR}}/docs/generated/sketch.md`
 
 ### 4. Curves and Surfacing (for lofts, sweeps, splines)
@@ -98,38 +59,31 @@ Smooth curves, Hermite splines, lofted and swept solids.
 
 Assembly graph, joint types, couplings, validation, robot export.
 
-- `{{SKILL_DIR}}/docs/API/assembly/assembly.md`
 - `{{SKILL_DIR}}/docs/generated/assembly.md`
 
 ### 6. Sheet Metal (for bent parts, K-factor, flat patterns)
 
 Bend operations, flat pattern unfolding, K-factor configuration.
 
-- `{{SKILL_DIR}}/docs/API/sheet-metal/sheet-metal.md`
 - `{{SKILL_DIR}}/docs/generated/sheet-metal.md`
 
 ### 7. Output and Export (for STL/3MF/STEP, BOM, dimensions)
 
 Mesh export, exact geometry export, bill of materials, dimension annotations.
 
-- `{{SKILL_DIR}}/docs/API/output/export.md`
-- `{{SKILL_DIR}}/docs/API/output/brep-export.md`
-- `{{SKILL_DIR}}/docs/API/output/bom.md`
-- `{{SKILL_DIR}}/docs/API/output/dimensions.md`
 - `{{SKILL_DIR}}/docs/generated/output.md`
 
 ### 8. Toolbox (fasteners and standard parts)
 
 Parametric bolts, nuts, washers, standard hardware, gears, pipes, and structural profiles.
 
-- `{{SKILL_DIR}}/docs/API/toolbox/fasteners.md`
 - `{{SKILL_DIR}}/docs/generated/lib.md`
+- `{{SKILL_DIR}}/docs/generated/wood.md`
 
 ### 9. Runtime Viewport APIs (for cut planes, jointsView, and animation playback)
 
 Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavior.
 
-- `{{SKILL_DIR}}/docs/API/runtime/viewport.md`
 - `{{SKILL_DIR}}/docs/generated/viewport.md`
 
 ### 10. Recipes and Debugging (for patterns and troubleshooting)
@@ -137,10 +91,17 @@ Viewer-only APIs such as cutPlane, explodeView, jointsView, and animation behavi
 Modeling patterns, debugging tactics, copyable snippets.
 
 - `{{SKILL_DIR}}/docs/guides/modeling-recipes.md`
+- `{{SKILL_DIR}}/docs/guides/joint-design.md`
 
 ### 11. CLI (for validation/render/export tasks)
 
-Test-run, notebook execution, export pipelines, debug flags.
+Test-run, export pipelines, debug flags.
 
 - `{{SKILL_DIR}}/docs/CLI.md`
 
+### SDF Modeling — Experimental (smooth booleans, TPMS, deformations, fromFunction)
+
+Primitives, smooth booleans, TPMS lattices, twist/bend/displace, morph, custom functions, gotchas. Experimental — slower render, lower mesh quality than B-rep.
+
+- `{{SKILL_DIR}}/docs/generated/sdf.md`
+

package/dist-skill/docs/API/core/concepts.md

@@ -5,129 +5,74 @@ skill-order: 1
 
 # ForgeCAD Core Concepts
 
-ForgeCAD scripts are JavaScript code that returns geometry. The forge API is globally available — no imports needed.
-
-## Basic Structure
+ForgeCAD scripts are JavaScript that returns geometry. The forge API is globally available — no imports needed.
 
 ```javascript
-// 1. Declare parameters (creates UI sliders)
 const width = param("Width", 50, { min: 20, max: 100, unit: "mm" });
-
-// 2. Create geometry
-const shape = box(width, 30, 10);
-
-// 3. Return the final shape
-return shape;
+return box(width, 30, 10);
 ```
 
 ## Execution Model
 
 - Scripts re-execute on every parameter change (400ms debounce)
-- All operations are **immutable** — they return new shapes, never modify in place
-- Must return one of:
-  - A `Shape` (3D solid)
-  - A `Sketch` (2D profile — rendered flat on XY plane)
-  - A `TrackedShape` (3D solid with named faces/edges — auto-unwrapped)
-  - A `ShapeGroup` (multiple shapes/sketches grouped for joint transforms)
-  - An `Array` of shapes/sketches/groups (multi-object scene)
-  - An `Array` of `{ name, shape?, sketch?, color? }` objects (named multi-object scene)
+- All operations are **immutable** — return new shapes, never modify in place
+- Must return one of: `Shape`, `Sketch`, `ShapeGroup`, `Array` of shapes/sketches/groups, `Array` of `{ name, shape?, sketch?, color? }`, or a **metadata object** (see below)
 
-## Colors
+### Metadata Object Return
 
-Both `Shape` and `Sketch` support colors via `.color()`:
+A script can return a plain object whose values include renderable geometry alongside non-renderable metadata. All renderable entries (Shape, Sketch, ShapeGroup, Assembly, or Array of named objects) are rendered; non-renderable entries are silently skipped. This is useful for multi-file projects where a part needs to publish interface data (bolt positions, dimensions) to other files:
 
 ```javascript
-const red = box(50, 50, 50).color('#ff0000');
-const blue = circle2d(25).color('#0066ff');
+// motor-mount.forge.js — renders standalone, exports metadata via require()
+const holePositions = [[17, 15], [-29, 15], [17, -15], [-29, -15]];
+return {
+  shape: mount.color('#556B2F'),                        // rendered
+  bolts: { dia: 5.3, pos: holePositions },              // metadata — skipped in render, available via require()
+};
+
+// base-body.forge.js — imports mount, accesses .bolts
+const mount = require('./motor-mount.forge.js');
+for (const [x, y] of mount.bolts.pos) { ... }          // use metadata
+// mount.shape is the Shape if you need it in an assembly
 ```
 
-Colors are preserved through transforms. In boolean operations the first operand's color wins.
-
-When returning multiple objects, set color per-object:
+Arrays inside the object are also rendered:
 
 ```javascript
-return [
-  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
-  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
-];
+return {
+  parts: [{ name: 'Left', shape: leftShape }, { name: 'Right', shape: rightShape }],
+  armWidth: 6,  // metadata
+};
 ```
 
-## ⚠️ Unions Remove Colors
+## Coordinate System
 
-`union()` merges shapes into one solid mesh — individual colors are lost:
+Z-up right-handed: X = left/right, Y = forward/back, Z = up/down.
 
-```javascript
-// ❌ BAD: Colors are lost after union
-const red = box(30, 30, 30).color('#ff0000');
-const blue = box(20, 20, 20).translate(30, 0, 0).color('#0066ff');
-return union(red, blue); // Result is all one color
-```
+## Colors
+
+`.color(hex)` works on `Shape` and `Sketch`. Colors survive transforms. In booleans the first operand's color wins.
 
-Return as named objects instead to keep each color:
+**`union()` removes colors** — shapes merge into one solid mesh. Return named objects instead:
 
 ```javascript
-// ✅ GOOD: Each object keeps its color
 return [
-  { name: "Red Box", shape: box(30, 30, 30), color: '#ff0000' },
-  { name: "Blue Box", shape: box(20, 20, 20).translate(30, 0, 0), color: '#0066ff' },
+  { name: "Base", shape: box(100, 100, 5), color: "#888888" },
+  { name: "Column", shape: cylinder(50, 10).translate(50, 50, 5), color: "#4488cc" },
 ];
 ```
 
-## Coordinate System
-
-ForgeCAD uses **Z-up** right-handed coordinates:
-- **X** = left/right
-- **Y** = forward/back
-- **Z** = up/down
-
-See [coordinate-system.md](../guides/coordinate-system.md) for view mapping details.
-
 ## Face Operations
 
-Pocket, boss, and profile operations work on any planar face — identified by string name or geometric query.
-
-### Face Selection
-
-```javascript
-// Canonical names (primitives and tracked shapes)
-shape.face('top')       // topmost upward face
-shape.face('front')     // front face (-Y normal)
-
-// Geometric queries (any shape — booleans, imports, complex bodies)
-shape.face({ normal: [0, 0, 1], pick: 'largest' })   // largest upward face
-shape.face({ normal: [0, 0, 1], nearest: [50, 50] }) // nearest to XY point
-shape.faces({ normal: [0, 0, 1] })                    // all upward faces (FaceRef[])
-```
-
-Query properties: `normal`, `nearest`, `at`, `pick` (`'largest'`/`'smallest'`/`'max-z'`/...), `area` (`{ min?, max? }`).
-
-### Pocket and Boss
-
-```javascript
-// Cut a pocket into the top face
-box(100, 100, 20).pocket('top', 8, { inset: 5 })
-
-// Add a boss from the top face
-box(100, 100, 20).boss('top', 5, { scale: 0.6 })
-
-// Target a specific face on a complex body with a query
-const body = box(100, 100, 20).pocket('top', 10, { inset: 5 });
-body.boss({ normal: [0, 0, 1], pick: 'smallest' }, 5)  // boss from pocket floor
-```
-
-Options: `inset` (shrink boundary, mm), `scale` (uniform scale, e.g. 0.8), `join` (`'Round'`/`'Square'`/`'Miter'`).
+Shapes carry semantic face labels through their lifecycle. The flow is:
 
-### Face Profile
+1. **Primitives** assign canonical names — `box()` gives you `top`, `bottom`, `side-left`, etc.; `cylinder()` gives `top`, `bottom`, `side`.
+2. **Extrusions** inherit labels from the sketch and add `top`/`bottom`.
+3. **Transforms** (translate, rotate, scale, mirror) preserve all labels.
+4. **Booleans** preserve labels from the first operand where geometry survives.
 
-Extract a face's 2D boundary as a `Sketch` for manual workflows:
-
-```javascript
-const profile = faceProfile(box(100, 100, 20), 'top');
-const tool = profile.offset(-5).extrude(8);  // shrink + extrude manually
-```
+You resolve labels to geometry with `.face(name)` or `.face(query)` — see the Shape class docs for the full query API. Operations like `.pocket()`, `.boss()`, `.hole()`, and `faceProfile()` all consume face references.
 
 ## SDF Modeling
 
-For organic shapes, smooth blending, TPMS lattices, and surface deformations, ForgeCAD provides a parallel SDF (Signed Distance Field) pipeline via the `sdf` namespace. SDF shapes convert to regular `Shape` objects via `.toShape()`.
-
-See [sdf.md](sdf.md) for the full reference — primitives, smooth booleans, TPMS, twist/bend/displace, custom functions, and workflow tips.
+For organic shapes, smooth blending, TPMS lattices, and surface deformations. SDF shapes convert via `.toShape()`. See [sdf-primitives.md](sdf-primitives.md).