forgecad 0.1.1 → 0.1.2

package/dist-skill/docs/API/README.md

@@ -0,0 +1,24 @@
+# ForgeCAD API Docs
+
+This folder is split by purpose so model-building guidance stays separate from adjacent runtime, output, and internal material.
+
+## Canonical Read Path for Model Building
+
+If an AI agent or contributor needs everything required to write or modify ForgeCAD models, read:
+
+1. [model-building/README.md](model-building/README.md)
+2. Every file listed there, in order
+3. Relevant runnable examples in `examples/api/`
+
+That `model-building/` set is the complete script-authoring surface for geometry and assemblies.
+
+## Adjacent API Areas
+
+- [runtime/viewport.md](runtime/viewport.md): viewport-only controls such as cut planes, exploded-view overrides, runtime joints, and helper overlays
+- [output/bom.md](output/bom.md): BOM/report metadata APIs
+- [output/dimensions.md](output/dimensions.md): dimension annotations for viewport/report output
+- [output/brep-export.md](output/brep-export.md): exact STEP/BREP export parity matrix
+- [guides/modeling-recipes.md](guides/modeling-recipes.md): patterns, best practices, debugging, and example snippets
+- [internals/manifold.md](internals/manifold.md): implementation notes about the current geometry backend
+
+Read those only when the task explicitly involves that area.

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

@@ -0,0 +1,246 @@
+# Modeling Recipes
+
+This file collects patterns, best practices, debugging tips, and example snippets that are useful once you already know the model-building API.
+
+## Iteration Bias
+
+- For unfamiliar or high-risk geometry work, start in a notebook and keep setup, experiments, and validation in separate cells until the structure is obvious.
+- Default to a buildable first pass instead of a long proposal when the user clearly wants geometry changed.
+- Replace a broken or incoherent model wholesale when that is faster and cleaner than incremental patching.
+- Keep printed hardware structurally honest: use it for guides, spacers, retainers, and moderate-load mechanisms; use wood or metal for primary strength.
+- Validate early with `forgecad run <file>` and refine from the actual runtime result.
+- Prefer a few clean part files over one giant script once a design has repeated hardware or a small mechanism.
+
+Notebook helpers worth using during iteration:
+
+- `show(...)` pins the current intermediate geometry in the viewport
+- `forgecad notebook view <file> preview` prints the preview cell with stored outputs in the terminal
+- `forgecad run <file>.forge-notebook.json` validates the preview cell and runs the usual spatial analysis
+
+## Common Patterns
+
+### Parametric Box with Holes
+```javascript
+const w = param("Width", 80, { min: 40, max: 150, unit: "mm" });
+const h = param("Height", 60, { min: 30, max: 100, unit: "mm" });
+const t = param("Thickness", 5, { min: 2, max: 10, unit: "mm" });
+const holeD = param("Hole Diameter", 8, { min: 4, max: 20, unit: "mm" });
+
+const base = box(w, h, t);
+const hole = cylinder(t + 2, holeD / 2).translate(w / 2, h / 2, -1);
+
+return base.subtract(hole);
+```
+
+### Hollow Shell (Wall Thickness)
+```javascript
+const outer = param("Outer Size", 50, { min: 20, max: 100, unit: "mm" });
+const wall = param("Wall", 3, { min: 1, max: 10, unit: "mm" });
+
+const outerBox = box(outer, outer, outer, true);
+const innerBox = box(outer - 2 * wall, outer - 2 * wall, outer - 2 * wall, true);
+
+return outerBox.subtract(innerBox);
+```
+
+### Array/Pattern
+```javascript
+const count = param("Count", 5, { min: 2, max: 10 });
+const spacing = param("Spacing", 15, { min: 5, max: 30, unit: "mm" });
+
+let shapes = [];
+for (let i = 0; i < count; i++) {
+  shapes.push(cylinder(10, 5).translate(i * spacing, 0, 0));
+}
+
+return union(...shapes);
+```
+
+### Sketch-Based Design
+```javascript
+const sides = param("Sides", 6, { min: 3, max: 12 });
+const radius = param("Radius", 25, { min: 10, max: 50, unit: "mm" });
+const height = param("Height", 60, { min: 20, max: 120, unit: "mm" });
+const wall = param("Wall", 3, { min: 1, max: 8, unit: "mm" });
+
+const outer = ngon(sides, radius);
+const inner = ngon(sides, radius - wall);
+const profile = outer.subtract(inner);
+
+return profile.extrude(height, { twist: 45, divisions: 32 });
+```
+
+### Rounded Profiles
+```javascript
+const base = rect(50, 30).offset(-3, 'Round').offset(3, 'Round');
+return base.extrude(10);
+```
+
+Use that pattern when every convex corner should round. For mixed sharp-and-rounded outlines, fillet only the intended vertices instead:
+
+```javascript
+const roofPoints = [
+  [0, 0],
+  [90, 0],
+  [90, 44],
+  [66, 74],
+  [45, 86],
+  [24, 74],
+  [0, 44],
+];
+
+const roof = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
+
+return roof.extrude(12);
+```
+
+### Chamfers and Fillets
+```javascript
+const part = box(50, 50, 20);
+const chamfer = box(10, 60, 10)
+  .rotate(0, 45, 0)
+  .translate(50, -5, 15);
+
+return part.subtract(chamfer);
+```
+
+### Choosing the right sketch-rounding tool
+
+- `offset(-r).offset(+r)` for rounding every convex corner of a closed outline
+- `stroke(points, width, 'Round')` for centerline-based geometry such as ribs or traces
+- `hull2d()` of circles for a blended cap/capsule silhouette
+- `filletCorners(points, ...)` for selective true-corner fillets on mixed profiles
+
+## Best Practices
+
+### Performance
+- Boolean operations are expensive; minimize them
+- Use parameters for values that might change
+- Avoid deep nesting of operations in loops
+
+### Readability
+```javascript
+const base = box(100, 100, 10);
+const hole = cylinder(12, 8);
+const result = base.subtract(hole.translate(50, 50, 0));
+return result;
+```
+
+Prefer named intermediate values over deeply nested one-liners.
+
+### Units
+- All dimensions are millimeters by default
+- Angles are degrees
+- Use the `unit` parameter option when it helps the reader
+
+### Centering
+```javascript
+const centered = box(50, 50, 50, true).translate(x, y, z);
+const corner = box(50, 50, 50).translate(x - 25, y - 25, z - 25);
+```
+
+Centered primitives are usually easier to position.
+
+## Debugging
+
+### Console Output
+```javascript
+console.log("Width:", width);
+console.log("Volume:", shape.volume());
+```
+
+### Incremental Building
+```javascript
+const base = box(50, 50, 10);
+// return base;
+
+const withHole = base.subtract(cylinder(12, 5).translate(25, 25, 0));
+// return withHole;
+
+return withHole.add(cylinder(20, 3).translate(25, 25, 10));
+```
+
+For sketch-heavy work, compare the raw profile and the rounded profile before extruding:
+
+```javascript
+const raw = polygon(roofPoints);
+const rounded = filletCorners(roofPoints, [
+  { index: 3, radius: 19 },
+  { index: 4, radius: 19 },
+  { index: 5, radius: 19 },
+]);
+
+return [
+  { name: "Raw", sketch: raw },
+  { name: "Rounded", sketch: rounded.translate(120, 0) },
+];
+```
+
+## Error Handling
+
+Common errors:
+- `"Kernel not initialized"` - internal/runtime issue, reload the app
+- `"Cannot read property of undefined"` - usually a bad variable name or missing declaration
+- invalid geometry - commonly caused by zero dimensions or self-intersecting sketches
+- script execution error - inspect the JS error in console output
+
+## Example Snippets
+
+### Parametric Phone Stand
+```javascript
+const width = param("Width", 80, { min: 40, max: 150, unit: "mm" });
+const depth = param("Depth", 60, { min: 30, max: 100, unit: "mm" });
+const thick = param("Thickness", 5, { min: 2, max: 15, unit: "mm" });
+const backH = param("Back Height", 40, { min: 20, max: 80, unit: "mm" });
+const cableD = param("Cable Hole", 8, { min: 4, max: 15, unit: "mm" });
+
+const base = box(width, depth, thick);
+const back = box(width, thick, backH).translate(0, depth - thick, thick);
+const lip = box(width, 10, 8).translate(0, 0, thick);
+const hole = cylinder(thick + 2, cableD / 2)
+  .rotate(90, 0, 0)
+  .translate(width / 2, depth / 2, -1);
+
+return union(base, back, lip).subtract(hole);
+```
+
+### Multi-Object Scene with Colors
+```javascript
+const base = box(100, 100, 5).color('#888888');
+const col1 = cylinder(40, 5).translate(20, 20, 5).color('#cc4444');
+const col2 = cylinder(40, 5).translate(80, 20, 5).color('#4444cc');
+const col3 = cylinder(40, 5).translate(50, 80, 5).color('#44cc44');
+const top = box(100, 100, 3).translate(0, 0, 45).color('#888888');
+
+return [
+  { name: "Base", shape: base },
+  { name: "Column A", shape: col1 },
+  { name: "Column B", shape: col2 },
+  { name: "Column C", shape: col3 },
+  { name: "Top", shape: top },
+];
+```
+
+### Entity-Based Design with Topology
+```javascript
+const baseRect = rectangle(0, 0, 80, 60);
+const base = baseRect.extrude(20);
+
+const result = filletEdge(base.toShape(), base.edge('vert-br'), 8, [-1, -1])
+  .hole(base.face('top'), { diameter: 6, u: -16, v: 10, depth: 8 });
+
+const holes = circularPattern(
+  cylinder(25, 4).translate(40, 30, -1),
+  4, 40, 30,
+);
+
+return result.subtract(holes);
+```
+
+Use the original tracked body (`base`) when you need semantic faces after edge finishing, and keep using its untouched sibling vertical tracked edges if you apply another supported fillet/chamfer later. Those sibling edges can now also survive a later supported union when the compiler still records one preserved propagated edge lineage for them. The currently selected finished edge is still recorded as a merged descendant set, so Forge does not claim a new durable tracked edge for that rewritten corner yet.
+
+For larger runnable examples, read `examples/api/`.

package/dist-skill/docs/API/internals/compiler.md

@@ -0,0 +1,300 @@
+# Forge Compiler Architecture
+
+This is the durable architecture record for ForgeCAD's multi-backend modeling system.
+
+If you add or refactor geometry features, read this first.
+
+## Core Position
+
+Forge should not invent a new CAD language or a new geometry kernel.
+
+Forge should:
+
+- keep JS/TS as the host language
+- keep Forge's semantic feature model as the source of truth
+- lower that model into different geometry backends intentionally
+- make capability gaps explicit in diagnostics and tests
+
+The unique thing to protect is not backend code. It is Forge's code-first modeling layer:
+
+- browser-first iteration
+- parametric code as the authoring format
+- composable multi-file projects
+- AI-writable design code
+- explicit provenance and backend visibility
+
+## What To Steal
+
+We should steal proven ideas aggressively.
+
+Steal from Fusion 360 / Onshape / FeatureScript:
+
+- semantic feature graphs
+- workplanes and sketch planes as first-class modeling context
+- query/reference systems for faces, edges, bodies, and feature results
+- feature definitions that lower into kernels instead of directly calling them from UI/API code
+
+Steal from CadQuery / build123d / replicad:
+
+- OCCT execution patterns
+- exact solid feature expectations
+- practical scripting ergonomics around sketches, planes, and feature builders
+
+Steal from OCAF-style document systems:
+
+- durable reference identity
+- explicit ownership of topology/reference propagation
+
+Do not steal:
+
+- a separate Forge DSL
+- backend object models as the user-facing API
+- exporter-only side systems that bypass the compiler
+
+## The Make-Or-Break Layer
+
+This is where Forge will likely succeed or fail:
+
+- the semantic feature graph
+- the compiled-scene routing layer
+- the reference / workplane / query system
+
+Why:
+
+- primitives, booleans, extrudes, and revolves are not the hard part
+- real mechanical design depends on downstream face- and edge-driven features
+- those features only stay usable if references survive feature chains predictably
+
+If this layer is weak, the repo will accumulate:
+
+- backend-specific feature code at callsites
+- export-only implementations
+- brittle face-name assumptions
+- features that work in demos but collapse in real parts
+
+If this layer is strong, future features stay additive.
+
+## Success Criteria
+
+We are succeeding only if all of these are true:
+
+1. Forge compile intent is the source of truth for mainstream part-design features.
+2. Scene-level routing is centralized, inspectable, and reused by export/debug/test flows.
+3. New features do not need ad hoc backend decisions at callsites.
+4. Workplane/reference/query semantics are stable enough for ordinary downstream feature chains.
+5. Most normal Design-workspace features can be added by extending one semantic node family and two lowerers.
+6. Tests catch plan drift, routing drift, and backend-output drift before release.
+
+We are failing if any of these become normal:
+
+- "this feature only works in export"
+- "this feature only works in Manifold"
+- "this feature only works if you know the right face name"
+- "just add one more backend escape hatch"
+- "the snapshot changed, probably fine"
+
+## Contributor Contract
+
+When adding a geometry feature:
+
+1. Define the Forge semantic intent first.
+2. Decide which domain owns it.
+3. Add or extend the compile node.
+4. Lower it through Manifold.
+5. Lower it through CadQuery/OCCT, or add explicit unsupported diagnostics.
+6. Route it through the scene compiler.
+7. Add invariants and snapshot coverage.
+8. Update permanent docs and the living mission tracker.
+
+Do not:
+
+- call Manifold or CadQuery directly from user-facing feature APIs unless that code is the backend lowerer itself
+- add exporter-only feature behavior that is invisible to the compiler
+- silently widen or narrow exact coverage
+
+## Implementation Path
+
+### Phase 1: Compiler Ownership
+
+Goal:
+
+- every supported feature records Forge intent
+- lowerers consume that intent
+- scene routing is centralized
+
+Deliverables:
+
+- backend-neutral compile nodes
+- compiled-scene routing and diagnostics
+- snapshot and invariant coverage
+
+### Phase 2: Reference / Workplane / Query Model
+
+Goal:
+
+- face-, edge-, and plane-driven features stop depending on brittle synthetic naming
+
+Deliverables:
+
+- first-class workplane representation
+- query/reference API for "what this feature means"
+- propagation rules for downstream feature ownership
+
+This is the highest-leverage next layer. Without it, `shell`, fillet/chamfer, holes, projection, and sheet-metal-style features will all stay fragile.
+
+Initial slice:
+
+- sketches placed with `onFace()` should carry semantic workplane/query metadata, not just a resolved 4x4 matrix
+- downstream feature code should be able to ask "which workplane/query produced this?" without reverse-engineering transforms
+
+Current progress:
+
+- `onFace()` placements now record semantic workplane models on sketches
+- `extrude()` and `revolve()` now preserve that intent in the shape compile graph as a first-class workplane-placement transform instead of collapsing it to an anonymous rigid transform
+- downstream compiler-aware code can now inspect that preserved workplane placement directly
+- that compiler-visible workplane placement now propagates through later shape transforms, so provenance inspection stays aligned with the current transformed feature state
+- both lowerers now execute that preserved workplane-placement intent, and exact export regression tests exercise the CadQuery/OCCT path end-to-end
+- compile-covered feature results now carry compiler-owned query-owner lineage, so parent-body ownership is no longer implicit runtime state
+- `src/forge/queryModel.ts` now defines the shared query/reference contract for face provenance instead of letting workplane and topology code drift separately
+- workplane sources and `FaceRef` values now share that face-query contract when compiler-owned provenance exists
+- `src/forge/queryModel.ts` now also defines the shared edge-query contract for tracked edges and direct edge refs, including selector semantics for whole-edge vs. `start` / `end` / `midpoint` references
+- tracked-topology flows now preserve that edge-query metadata through clone/translate/workplane-placement transforms, and placement invariants assert that tracked edge selectors stay aligned with the actual transformed edge geometry
+- booleans, shell, split/trim flows, and downstream workplane-driven features now preserve that owner lineage through the compile graph instead of erasing it at each feature boundary
+- mirrored results plus `linearPattern()` / `circularPattern()` helper copies now get fresh compiler-owned repeated-result owners when their source shapes stay compile-covered
+- placement and exact-export invariants now check that owner lineage survives ordinary shell-plus-cut-plus-boolean style part workflows
+- topology-changing compile nodes now also carry an explicit backend-neutral `queryPropagation` contract for preserved/created query meaning instead of leaving post-rewrite semantics implicit
+- that shared propagation contract now models propagated face/edge queries, feature-created query slots, and explicit ambiguity/unsupported diagnostics on rewrite-producing results
+- 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
+- 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
+- `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
+
+Still missing:
+
+- universal durable face/edge identity across topology-changing operations
+- mesh/SDF rewrite families still need their own explicit descendant contracts instead of borrowed BREP-style assumptions
+- shared edge-query selectors exist for tracked topology, but topology-changing features still do not produce new single-edge ownership for most rewritten/created edges beyond today's defended preserved-edge and edge-chain subset
+- stable downstream face/edge references beyond today's defended single/region/set/chain subset still need the follow-on work in tasks 180, 190, and 195
+
+### Phase 3: Mainstream Feature Families
+
+Goal:
+
+- dual-lower the ordinary part-design stack
+
+Priority order:
+
+- `shell`
+- fillet / chamfer
+- holes / patterned cuts
+- projection and sketch-on-face refinement
+- mirror / pattern workflows driven by semantic references
+
+Current progress:
+
+- `shell()` is now compiler-owned as the first mainstream exact feature-family slice instead of being left for exporter-only logic
+- both lowerers consume the same semantic `shell` node and rewrite supported cases into backend-native boolean/extrude/cylinder plans
+- `shape.hole()` and `shape.cutout()` now form a compiler-owned hole/cut workflow slice anchored to the shared face-query/workplane model
+- through holes, blind holes, counterbores, countersinks, and planar `upToFace` hole/cut extents now lower through both Manifold and CadQuery/OCCT from that shared semantic node family
+- shell, hole, and cut now expose defended named created-face subsets on top of the topology-rewrite kernel, so downstream features can target inner shell walls, blind-hole floors, and supported cut walls/floors without falling back to anonymous runtime placement
+- richer hole variants now also expose defended `counterbore-floor`, `counterbore-wall`, and `countersink-wall` created-face slots where Forge can model them directly
+- `filletEdge()` and `chamferEdge()` now form a first compiler-owned tracked-edge finishing slice for supported vertical edges on compile-covered `box()` and `rectangle(...).extrude(...)` bodies
+- the post-rewrite edge-query layer now also defends untouched sibling vertical edges after those supported edge-finish rewrites, plus later supported boolean-union descendants when one preserved propagated-edge lineage stays explicit
+- regression coverage now includes compiler snapshots plus exact-export invariants for `shell()`
+- regression coverage now also includes exact/runtime/export checks for the supported hole/cut workflow subset
+- regression coverage now also includes API, placement-owner, query-propagation, compiler-snapshot, exact-plan, corpus, and end-to-end export checks for the broadened tracked-edge fillet/chamfer subset
+- 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
+- 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
+- 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:
+
+- `shell()` v1 only covers compile-covered `box()`, `cylinder()`, and straight `extrude()` bases with optional `top` / `bottom` openings, while defended named created faces currently cover the exact profile families Forge can model directly (`rect`, `roundedRect`, `circle`)
+- `shape.hole()` still only covers circular holes, and `shape.cutout()` still only covers sketches already placed with `onFace(...)`
+- `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
+- 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
+
+### Phase 4: Higher-Order Workflows
+
+Goal:
+
+- features like sheet metal, advanced library helpers, and richer manufacturing flows build on the same semantic core
+
+Current progress:
+
+- `sheetMetal()` now exists as the first dedicated higher-order semantic family on top of the descendant-resolution layer
+- one sheet-metal model now lowers to both a folded solid and a flat pattern instead of splitting folded/export logic across backend-specific codepaths
+- named `panel`, `flange-*`, and `bend-*` descendants now flow through the shared face-descendant machinery, so downstream cutouts can still expose honest region/set semantics after topology rewrites
+- the maintained `folded-service-panel-cover` proof part now lives in the API examples, compiler corpus, query-propagation snapshots, API invariants, and exact BREP checks
+
+These higher-order families should keep arriving only after the shared reference/workplane/query layer is credible enough to defend them honestly.
+
+## Current Architectural Boundary
+
+Today, the intended compiler boundary is:
+
+```text
+Forge scripts
+    -> Forge semantic feature graph
+    -> compiled scene + capability routing
+    -> Manifold lowerer / CadQuery-OCCT lowerer / faceted fallback
+```
+
+Future feature work should strengthen this boundary, not route around it.
+
+## Next Achievable CAD Families
+
+Once the descendant-resolution layer is in place, the next credible expansion lanes are:
+
+- richer hole and cut variants
+- broader shell workflows
+- broader fillet/chamfer workflows
+- stronger projection and sketch-on-face flows
+- richer sheet-metal corner and detail workflows on top of the new semantic family
+- manufacturing outputs such as flat patterns and DXF/SVG profile export
+- toolbox and library feature families
+- stronger assembly metadata and exact/faceted route visibility
+
+These are all good fits for the compiler architecture because they can be expressed as Forge-owned semantic intent and lowered intentionally into both backends.
+
+## Bigger Leap Areas
+
+Some CAD-adjacent areas are still important, but they are a bigger leap than the current compiler program:
+
+- arbitrary direct editing over imported or heavily rewritten BReps
+- advanced surfacing or subD/T-spline workflows
+- CAM
+- simulation / FEA
+- full enterprise document/PDM systems
+- full large-assembly and mate-solver parity with major desktop CAD tools
+
+Keep these visible, but do not plan them as if they were just another feature module on the current part-design stack.
+
+## Legacy Cleanup Rule
+
+Yes, the old architecture needs cleanup.
+
+No, that should not happen as a single flag-day rewrite.
+
+The rule is:
+
+1. add compiler-owned replacements first
+2. fence old bypass paths so new work cannot extend them
+3. retire legacy shims once supported features and examples no longer need them
+
+That keeps the repo honest without destabilizing active work.

package/dist-skill/docs/API/internals/manifold.md

@@ -0,0 +1,7 @@
+Underneath ForgeCAD currently uses Manifold for browser-time geometry work.
+
+Implementation note:
+- Manifold is Y-up internally
+- ForgeCAD is Z-up externally
+
+If a kernel-facing operation behaves as if axes are swapped, check whether a Manifold call is still assuming Y-up semantics.

package/dist-skill/docs/API/model-building/README.md

@@ -0,0 +1,31 @@
+# Model-Building Docs
+
+This folder is partitioned so each API surface has one primary owner file. Avoid reading everything by default; load only what the current task needs.
+
+## Ownership
+
+- [reference.md](reference.md): core script contract, 3D primitives/transforms, booleans, imports, library helpers, return formats, and curves/surfacing APIs.
+- [coordinate-system.md](coordinate-system.md), [geometry-conventions.md](geometry-conventions.md), [positioning.md](positioning.md): orientation rules, winding/transform conventions, and placement strategy.
+- [sketch-core.md](sketch-core.md), [sketch-primitives.md](sketch-primitives.md), [sketch-path.md](sketch-path.md), [sketch-transforms.md](sketch-transforms.md), [sketch-booleans.md](sketch-booleans.md), [sketch-operations.md](sketch-operations.md), [sketch-on-face.md](sketch-on-face.md), [sketch-extrude.md](sketch-extrude.md), [sketch-anchor.md](sketch-anchor.md): detailed 2D sketch APIs.
+- [entities.md](entities.md): named entities, tracked topology, constrained sketches, patterns, and fillet/chamfer utilities.
+- [sheet-metal.md](sheet-metal.md): compiler-owned sheet-metal modeling, folded outputs, flat patterns, and defended region names.
+- [assembly.md](assembly.md): assembly graph, joints, couplings, validation, and robot export behavior.
+
+## Read Plan
+
+1. Start with [reference.md](reference.md) plus [coordinate-system.md](coordinate-system.md), [geometry-conventions.md](geometry-conventions.md), and [positioning.md](positioning.md).
+2. If the task is exploratory, unfamiliar, or likely to need debugging, use a `.forge-notebook.json` during the first iteration instead of jumping straight to a final script layout.
+3. Add sketch docs only when the task is sketch-heavy.
+4. Add [entities.md](entities.md) for topology-aware edits, constraints, or pattern helpers.
+5. Add [sheet-metal.md](sheet-metal.md) when the task is about folded covers, brackets, flat patterns, or named panel/flange/bend descendants.
+6. Add [assembly.md](assembly.md) only for joint/coupling/mechanism work.
+7. Pull in guides and CLI docs when you need recipes, notebook workflow guidance, troubleshooting, or command usage.
+
+## Intentionally Excluded
+
+These files are still part of the ForgeCAD API, but they are not required for baseline model building:
+
+- `../runtime/` for viewport-only behavior
+- `../output/` for reporting/export behavior
+- `../guides/` for recipes and troubleshooting
+- `../internals/` for engine notes