forgecad 0.10.4 → 0.11.0

package/dist-skill/CONTEXT.md

@@ -28,7 +28,8 @@ Author or modify ForgeCAD models, sketches, assemblies, and CLI workflows. Prefe
 
 ### Import and composition
 
-- Always include the extension in relative imports: `require("./file.forge.js", { Param: value })` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Always include the extension in relative imports: `require("./file.forge.js")` for model files, `require("./helpers.js")` for plain helper modules. Extensionless imports such as `require("./file")` do not resolve; ForgeCAD resolves project imports by exact path.
+- Reusable `.forge.js` part files should return builder functions such as `return { buildPart }`; direct-run preview params belong inside `if (require.main === module)`.
 - ForgeCAD APIs are injected globals in `.forge.js` files. Use `bom()`, `box()`, `scene()`, `Shape`, etc. directly; never destructure those names from helpers (`const { bom } = require("./bom.js")`). Import helper files under a project-specific name such as `const bomHelpers = require("./bom.js")`.
 - For static multi-part models, connectors + `matchTo()` are the default way to assemble touching parts.
 - Top-level scripts can return `Assembly` or `SolvedAssembly` directly. Do not call `.toGroup()` just to render an assembly; use it only when you need `ShapeGroup` composition, transforms, or named-child lookup.
@@ -77,10 +78,10 @@ A `.forge.js` script is plain JavaScript that returns geometry. The entire forge
 
 All geometry operations are **immutable** — shapes, sketches, groups, assemblies, and boards return new values, never mutate in place.
 
-A script must return one of three shapes:
+A script should return one of three shapes:
 
 1. **A single renderable** — `Shape`, `Sketch`, `ShapeGroup`, `Assembly`, `SolvedAssembly`, or `SdfShape`.
-2. **An array** of renderables or named descriptors `{ name, tags?, shape | sketch | group, color? }`:
+2. **An array** of renderables or named descriptors `{ name, tags?, shape | sketch | group, color? }`, usually for direct-run previews and multi-object display:
 
    ```javascript
    return [
@@ -89,11 +90,38 @@ A script must return one of three shapes:
    ];
    ```
 
-3. **A metadata object** — a plain object whose renderable values are rendered and whose non-renderable values (numbers, hole tables, builder functions) are silently skipped at render but flow to importers via `require()`. Each key becomes a named group, so don't pile independent parts into one array key (`{ parts: [a, b, c] }`) — the integrity gate reads that as a single fragmented part. Give each part its own key (`{ collar12, collar16, plug }`) or use named descriptors (form 2).
+3. **A module interface object** — usually builder functions, optionally a built shape plus interface data:
+
+   ```javascript
+   return { buildBracket };
+   // or, when the file's useful output is already built:
+   return { shape, connectors, boltPattern };
+   ```
+
+For reusable part files, prefer a builder export and keep direct-run preview controls inside the entry guard:
+
+```javascript
+function buildThing(props) {
+  return box(props.width, props.depth, props.height);
+}
+
+if (require.main === module) {
+  const previewProps = {
+    width: param("Width", 80),
+    depth: param("Depth", 40),
+    height: param("Height", 12),
+  };
+  return buildThing(previewProps);
+}
+
+return { buildThing };
+```
+
+When a plain object is returned directly, renderable values are shown in the viewport and non-renderable values are available to importers through `require()`.
 
 Return an unsolved `Assembly` directly — ForgeCAD solves it at default joint values for display. Use `assembly.solve(state)` for a specific pose. Never call `.toGroup()` just to make an assembly render; use it only when you need `ShapeGroup` composition or named-child lookup.
 
-For multi-file projects — import path rules, the metadata pattern, and Forge-aware builder modules — see the [`require()` docs](../../generated/core.md).
+For multi-file projects, import path rules, and reusable builder modules, see the [`require()` docs](../../generated/core.md).
 
 ## Identity
 
@@ -135,24 +163,154 @@ activateBackend, Analysis, arcSlot, assembly, Assembly, Blend, bom, box
 cameraTrajectory, Carrier, chamfer, circle2d, Circle2D, circularLayout, circularPattern, circularPattern2d
 coalesceEdges, compareWith, connector, console, constrainedSketch, Curve, Curve3D, cutPlane
 cylinder, difference, difference2d, dim, draft, ellipse, explodeView, faceProfile
-fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis, group
-Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint, Laser
-lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft, mirrorCopy
-mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param, path
-Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder, ProductRibbonBuilder
-ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask, rect
-Rectangle2D, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape, selectEdge
-selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape, ShapeGroup
-sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg, slot
-SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody, SurfaceMembers
-sweep, text2d, textWidth, torus, toShape, Transform, union, union2d
-variableSweep, verify, Viewport, window, Wood, Wrap
+Fea, fillet, Function, gcode, GCodeBuilder, getActiveBackend, global, globalThis
+group, Import, ImportedAssembly, initKernel, intersection, intersection2d, intersectWithPlane, joint
+Laser, lib, Line2D, linearPattern, linearPattern2d, loadFont, loft, Loft
+mirrorCopy, mock, ngon, NurbsCurve3D, NurbsSurface, offsetSolid, param, Param
+path, Point2D, Points, polygon, polygonVertices, port, Product, ProductPanelBuilder
+ProductRibbonBuilder, ProductSkin, ProductSkinBuilder, ProductStationBuilder, ProductSurfaceBuilder, ProductSurfaceRef, projectToPlane, queueMicrotask
+rect, Rectangle2D, roundedRect, Route3D, scene, Sculpt, sdf, SdfShape
+selectEdge, selectEdges, self, setActiveBackend, setImmediate, setInterval, setTimeout, Shape
+ShapeGroup, sheetMetal, SheetMetalPart, sheetStock, Sim, Sketch, sketchToDxf, sketchToSvg
+slot, SolvedAssembly, spec, sphere, spline2d, stroke, Surface, SurfaceBody
+SurfaceMembers, sweep, text2d, textWidth, Thickness, torus, toShape, Transform
+union, union2d, variableSweep, verify, Viewport, window, Wood, Wrap
 ```
 
 `showLabels` is also a runtime global, but it is not part of the top-level collision check. Avoid reusing it unless you intentionally want a local value with that name.
 
 ---
 
+<!-- guides/manual-parameters.md -->
+
+# Manual Parameter Sheets
+
+Manual parameters are constrained design data: the script owns the structure and
+the user edits only the declared values. They are for cases where a numeric
+slider is the wrong shape of input.
+
+## Contents
+
+- Decision Ladder
+- Path2D
+- Spline2D
+- Placement2D
+- Spatial Anchors
+- Saving
+
+## Decision Ladder
+
+Use the smallest parameter type that matches the design intent:
+
+| Intent | Use |
+| --- | --- |
+| One scalar dimension, count, angle, or toggle | `Param.number()`, `Param.bool()`, `Param.choice()` |
+| A repeated table of named scalar fields | `Param.list()` |
+| A hand-shaped polygon, section outline, or open centerline | `Param.path2d()` |
+| A smooth hand-shaped curve with tangent/curvature intent | `Param.spline2d()` |
+| Named semantic blocks arranged in zones | `Param.placement2d()` |
+
+Do not use `path2d` or `spline2d` as a generic table. Use them when dragging
+points is meaningfully better than editing numbers.
+
+## Path2D
+
+`Param.path2d(name, points, opts)` returns a `Path2DParamValue`.
+
+- Closed paths are filled profile intent: call `.toSketch()`.
+- Open paths are centerline intent: call `.toStroke(width)`.
+- `x` and `y` ranges define the initial editor frame, not hard movement limits.
+- Override keys are `Name[0].x`, `Name[0].y`, and `Name.__count__`.
+
+```javascript
+const outline = Param.path2d('Outline', [[-30, -15], [30, -15], [24, 18], [-28, 16]], {
+  closed: true,
+  minPoints: 3,
+  maxPoints: 12,
+  unit: 'mm',
+  anchor: Param.anchor.sheetOnXY([0, 0, 8], { label: 'Top outline' }),
+});
+
+return outline.toSketch().extrude(4);
+```
+
+## Spline2D
+
+`Param.spline2d(name, points, opts)` returns a `Spline2DParamValue`.
+
+- Each point has `g`: `G0` for a hard break, `G1` for tangent smooth, `G2` for
+  curvature smooth.
+- Use `.toCurveOnXY()`, `.toCurveOnXZ()`, or `.toCurveOnYZ()` for sweeps and
+  curve consumers.
+- Use `.toPathOnXY()`, `.toPathOnXZ()`, or `.toPathOnYZ()` when an API expects
+  sampled points.
+- Override keys are `Name[0].x`, `Name[0].y`, `Name[0].g`, and `Name.__count__`.
+
+```javascript
+const sideProfile = Param.spline2d('Side Profile', [
+  { x: 0, y: 0, g: 'G2' },
+  { x: 35, y: 8, g: 'G2' },
+  { x: 70, y: 3, g: 'G1' },
+], {
+  unit: 'mm',
+  anchor: Param.anchor.sheetOnXZ([0, -20, 0], { label: 'Side profile' }),
+});
+
+const rail = sideProfile.toCurveOnXZ();
+```
+
+## Placement2D
+
+`Param.placement2d(name, spec)` returns a `Placement2DParamValue`.
+
+- The script declares stable item IDs, footprints, optional zones, and rules.
+- The user moves named items; the model decides what each item creates.
+- Use `.item(id)` for one placement or `.positions()` for keyed lookup.
+- Override keys are item based: `Layout.battery.x`, `Layout.battery.y`,
+  `Layout.battery.angle`, and `Layout.battery.zone`.
+
+```javascript
+const layout = Param.placement2d('Internal Layout', {
+  frame: { size: [120, 80] },
+  zones: [{ id: 'electronics', size: [70, 70], center: [-20, 0] }],
+  items: [
+    { id: 'battery', footprint: { type: 'rect', size: [42, 24] }, zone: 'electronics', at: [-25, 0] },
+    { id: 'speaker', footprint: { type: 'circle', radius: 12 }, at: [32, 8] },
+  ],
+  rules: { bounds: 'prevent', collisions: 'warn', snap: 1 },
+  anchor: Param.anchor.sheetOnXY([0, 0, 12], { label: 'Internal layout' }),
+});
+
+const battery = layout.item('battery');
+const batteryBlock = box(42, 24, 6).translate(battery.x, battery.y, 3);
+```
+
+## Spatial Anchors
+
+Every parameter type can carry optional viewport metadata through `anchor`.
+Anchors do not change geometry.
+
+- `Param.anchor.point([x, y, z])` creates a clickable pin for scalar, string,
+  list, boolean, or choice parameters.
+- `Param.anchor.sheetOnXY([x, y, z])` places a 2D sheet in the XY plane at
+  fixed Z.
+- `Param.anchor.sheetOnXZ([x, y, z])` places a 2D sheet in the XZ plane at
+  fixed Y.
+- `Param.anchor.sheetOnYZ([x, y, z])` places a 2D sheet in the YZ plane at
+  fixed X.
+
+The parameter still appears in the parameter panel when `anchor` is omitted; it
+just has no 3D pin or spatial sheet.
+
+## Saving
+
+Dragging a manual sheet writes parameter overrides first. The source model keeps
+the declared defaults until those overrides are intentionally folded back into
+code. Use snapshots for named parameter states, and use the parameter panel's
+AI handoff for manual canvas edits when the desired result should become source.
+
+---
+
 <!-- generated/core.md -->
 
 # Core API
@@ -170,13 +328,15 @@ variableSweep, verify, Viewport, window, Wood, Wrap
 - [Grouping & Local Coordinates](#grouping-local-coordinates)
 - [Section & Projection](#section-projection)
 - [Verification](#verification)
-- [Shape](#shape) — Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
+- [Shape](#shape) — Freeform Construction, Appearance, Face Topology, Edge Topology, Transforms, Booleans & Cutting, Features, Placement, Connectors, References, Measurement
 - [Transform](#transform)
 - [ShapeGroup](#shapegroup) — Children, Transforms, Placement, Connectors, References
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
-- [Sheet](#sheet)
+- [Path2DParamValue](#path2dparamvalue)
+- [Spline2DParamValue](#spline2dparamvalue)
+- [Placement2DParamValue](#placement2dparamvalue)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -505,11 +665,11 @@ for (const edge of coalesceEdges(topEdges)) {
 
 ### Imports & Composition
 
-#### `require(path: string, paramOverrides?: Record<string, number | string>): any` — Import a module with optional ForgeCAD parameter overrides. Returns the module's exports.
+#### `require(path: string): any` — Import a ForgeCAD or helper module. Returns the file's returned value.
 
-When importing a `.forge.js` file, most return values are passed through exactly as the script returns them. Assembly returns have one extra composition rule: an unsolved [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries, while a returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly). If the script returns a metadata object (e.g. `{ shape: myShape, bolts: {...} }`), the caller receives the full object — renderable values and metadata together.
+When importing a `.forge.js` file, return values are passed through exactly as the script returns them, except for unsolved assemblies: a returned [`Assembly`](/docs/assembly#assembly) is wrapped as an [`ImportedAssembly`](/docs/assembly#importedassembly), preserving `solve(state)` and `mergeInto()` across file boundaries. A returned [`SolvedAssembly`](/docs/assembly#solvedassembly) stays a [`SolvedAssembly`](/docs/assembly#solvedassembly).
 
-**Script return contract:** a `.forge.js` script returns one of three shapes: a single renderable (Shape, ShapeGroup, Sketch, SdfShape, Assembly), an array of renderables or named descriptors (`{ name, shape|sketch|group }`), or a metadata object mixing renderable values with plain data. When a script runs directly, renderable entries of a metadata object are rendered under their key names and non-renderable entries are silently skipped — both halves of the metadata contract: one return value serves the viewport and `require()` callers.
+**Script return contract:** a `.forge.js` script should return one of three shapes: a single renderable (Shape, ShapeGroup, Sketch, SdfShape, Assembly), an array of renderables or named descriptors (`{ name, shape|sketch|group }`) for previews and multi-object display, or a module interface object. Reusable part files should return builders such as `return { buildBracket }`; files that already build useful geometry may return `{ shape, connectors, boltPattern }`. When a script runs directly, renderable entries of a plain object are rendered under their key names and non-renderable entries are skipped.
 
 **Assembly return contract**
 
@@ -522,52 +682,56 @@ When importing a `.forge.js` file, most return values are passed through exactly
 
 **Path rule:** Always include the file extension in relative imports: use `require("./part.forge.js")` for model files and `require("./helpers.js")` for plain helper modules. ForgeCAD does not apply Node-style extension inference, so `require("./part")` will not find `part.forge.js` or `part.js`.
 
-**Parameter scoping:** Parameters declared in required files are automatically namespaced with a `"filename#N / "` prefix (e.g. `"bracket.forge.js#1 / Width"`). This prevents collisions when multiple files declare same-named params. Each file's params appear as separate sliders.
-
-**Parameter overrides:** When passing overrides, use the bare param name (not the scoped name). Overrides are type-checked — unrecognized keys throw an error with typo suggestions.
-
-**Multi-file assembly pattern** — pass cross-cutting design values from the assembly to parts:
+**Multi-file assembly pattern** — the assembly owns params and passes ordinary props to child builders:
 
 ```js
 // assembly.forge.js — owns cross-cutting params, passes to parts
 const wall = param("Wall", 3);
 const baseH = param("Base Height", 20);
 
-const mount = require('./motor-mount.forge.js', { Wall: wall });
-const base  = require('./base-body.forge.js', { Wall: wall, Height: baseH });
+const mountModule = require('./motor-mount.forge.js');
+const baseModule = require('./base-body.forge.js');
+
+const mount = mountModule.buildMount({ wall });
+const base = baseModule.buildBase({ wall, height: baseH });
 ```
 
-**Metadata pattern** — parts publish interface data alongside geometry:
+**Builder result pattern** — parts publish interface data alongside geometry:
 
 ```js
 // motor-mount.forge.js
-return { shape: mount, bolts: { dia: 5.3, pos: holePositions } };
+function buildMount({ wall }) {
+  const shape = box(80, 40, wall);
+  return { shape, boltPattern: { dia: 5.3, positions: [[-25, 0], [25, 0]] } };
+}
 
 // base-body.forge.js
 const mount = require('./motor-mount.forge.js');
-mount.bolts.pos  // access the metadata
-mount.shape       // access the geometry
+const built = mount.buildMount({ wall: 3 });
+built.boltPattern  // access interface data
+built.shape        // access geometry
 ```
 
 **Forge-aware builder module pattern** — use `.forge.js` modules for reusable sketch, profile, shape, or assembly builders that need ForgeCAD runtime APIs:
 
 ```js
-// profiles.forge.js — inspectable on its own, reusable through require()
+// profiles.forge.js
 function wheelProfile() {
   return circle2d(40).subtract(circle2d(18));
 }
 
-return {
-  preview: [{ name: 'Wheel profile', sketch: wheelProfile() }],
-  make: { wheelProfile },
-};
+if (require.main === module) {
+  return [{ name: 'Wheel profile', sketch: wheelProfile() }];
+}
+
+return { wheelProfile };
 
 // main.forge.js
 const profiles = require('./profiles.forge.js');
-const wheel = profiles.make.wheelProfile().extrude(8);
+const wheel = profiles.wheelProfile().extrude(8);
 ```
 
-Keep exported builders pure over top-level constants, top-level `param()` values, or explicit function arguments. Do not declare new `param()` values inside an exported builder if callers need `require('./profiles.forge.js', { Width: 80 })` overrides: import overrides are validated while the module loads, before any exported builder is called. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
+Keep returned builders pure over top-level constants or explicit function arguments. Put preview-only `param()` values inside `if (require.main === module)` so parent assemblies stay in charge of design parameters. Use plain `.js` modules only for pure constants, tables, math helpers, and formatting code that does not construct ForgeCAD geometry.
 
 **Entry detection (Node semantics):** `require.main` is the entry script's module object, so `require.main === module` is true only in the file being run directly. Part files use it to build standalone preview geometry only when opened directly — importers then skip that work entirely:
 
@@ -575,16 +739,30 @@ Keep exported builders pure over top-level constants, top-level `param()` values
 // part.forge.js
 function bracket() { ... }
 if (require.main === module) {
-  return { preview: [{ name: 'Bracket', shape: bracket() }] }; // direct run: render it
+  return bracket({ width: param('Width', 80), height: param('Height', 40) });
 }
-return { make: { bracket } };                                  // imported: builders only
+return { bracket };
 ```
 
 ### Parameters
 
-#### `Param.number(name: string, defaultValue: number, opts?: { min?: number; max?: number; step?: number; unit?: string; integer?: boolean; reverse?: boolean; }): number` — Declare a numeric parameter that renders as a slider in the UI.
+#### `Param.anchor: { ... }` — Viewport anchor builders for spatial parameter editing.
 
-Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. Parameter values are also overridable from `require()` imports or the CLI `--param` flag — the `name` string is the key used in both cases.
+Anchors are metadata only: they do not change geometry. The editor uses them to show clickable parameter pins and manual-editing sheets in the 3D viewport. Use point anchors for scalar/text/list parameters and sheet anchors for `path2d`, [`spline2d`](/docs/curves#spline2d), and `placement2d` editors.
+
+A sheet anchor's origin is a world/model-space point. Its plane selects how the 2D editor coordinates map into the viewport:
+
+- `sheetOnXY([x, y, z])`: editor x/y map to world X/Y at fixed Z.
+- `sheetOnXZ([x, y, z])`: editor x/y map to world X/Z at fixed Y.
+- `sheetOnYZ([x, y, z])`: editor x/y map to world Y/Z at fixed X.
+
+Omitting `anchor` still registers the parameter in the parameter panel; it just will not create a viewport pin/sheet.
+
+`ParamAnchorOptions`: `{ label?: string, color?: string }`
+
+#### `Param.number(name: string, defaultValue: number, opts?: NumberParamOptions): number` — Declare a numeric parameter that renders as a slider in the UI.
+
+Each call registers a slider control. When the user moves the slider the entire script re-executes with the new value. The `name` string is the UI label and the CLI `--param` key.
 
 Default range rules when options are omitted:
 
@@ -600,38 +778,34 @@ const angle = Param.number("Angle", 45, { min: 0, max: 180, unit: "°" });
 const sides = Param.number("Sides", 6, { min: 3, max: 12, integer: true });
 ```
 
-**Parameter overrides** — key must match `name` exactly:
-
-```ts
-// Via require()
-const bracket = require("./bracket.forge.js", { Width: 80 });
+CLI overrides use the parameter name:
 
-// Via CLI
-// forgecad run model.forge.js --param "Wall Thickness=3"
+```bash
+forgecad run model.forge.js --param "Wall Thickness=3"
 ```
 
 Also available as the shorthand alias `param()`.
 
-#### `Param.string(name: string, defaultValue: string, opts?: { maxLength?: number; }): string` — Declare a string parameter that renders as a text input in the UI.
+`ParamAnchorableOptions`: `{ anchor?: ParamAnchorDef }`
 
-String parameters let users type free-form text — labels, names, inscriptions, file paths, etc. The `name` string is the override key.
+`NumberParamOptions`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, reverse?: boolean }`
 
-```ts
-const label = Param.string("Label", "Hello World");
-const name  = Param.string("Name", "Part-001", { maxLength: 20 });
-```
+#### `Param.string(name: string, defaultValue: string, opts?: StringParamOptions): string` — Declare a string parameter that renders as a text input in the UI.
 
-Override via import:
+String parameters let users type free-form text — labels, names, inscriptions, file paths, etc.
 
 ```ts
-const tag = require("./tag.forge.js", { Label: "Custom Text" });
+const label = Param.string("Label", "Hello World");
+const name  = Param.string("Name", "Part-001", { maxLength: 20 });
 ```
 
 Only available as `Param.string()` — no standalone alias.
 
-#### `Param.bool(name: string, defaultValue: boolean): boolean` — Declare a boolean parameter that renders as a checkbox in the UI.
+`StringParamOptions`: `{ maxLength?: number }`
+
+#### `Param.bool(name: string, defaultValue: boolean, opts?: ParamAnchorableOptions): boolean` — Declare a boolean parameter that renders as a checkbox in the UI.
 
-Internally stored as `0`/`1`. When overriding from CLI or `require()`, pass `1` for true and `0` for false. The `name` string is the override key.
+Internally stored as `0`/`1` for CLI overrides. Pass `1` for true and `0` for false.
 
 ```ts
 const showHoles = Param.bool("Show Holes", true);
@@ -639,29 +813,17 @@ if (showHoles) return difference(plate, cylinder(10, 5).translate(50, 30, 0));
 return plate;
 ```
 
-Override via import:
-
-```ts
-const pan = require("./pan.forge.js", { "Show Lid": 0 });
-```
-
-#### `Param.choice(name: string, defaultValue: string, choices: string[]): string` — Declare a choice parameter that renders as a dropdown in the UI.
+#### `Param.choice(name: string, defaultValue: string, choices: string[], opts?: ParamAnchorableOptions): string` — Declare a choice parameter that renders as a dropdown in the UI.
 
 `defaultValue` must exactly match one entry in `choices`. Returns the selected string label. Prefer `Param.choice` over `Param.number` when a slider would hide intent — named choices like `"wok"` are self-describing.
 
-Overrides may be passed as the choice label string (preferred) or as a numeric index. The `name` string is the override key.
+CLI overrides may be passed as the choice label string (preferred) or as a numeric index.
 
 ```ts
 const panStyle = Param.choice("Pan Style", "frying-pan", ["frying-pan", "saute-pan", "wok"]);
 if (panStyle === "wok") return buildWok();
 ```
 
-Override via import:
-
-```ts
-const pan = require("./pan.forge.js", { "Pan Style": "wok" });
-```
-
 Override via CLI:
 
 ```bash
@@ -680,6 +842,90 @@ Field types:
 
 `ListParamFieldDef`: `{ min?: number, max?: number, step?: number, unit?: string, integer?: boolean, boolean?: boolean, choices?: string[] }`
 
+#### `Param.path2d(name: string, defaultPoints: Path2DPointInput[], opts?: Path2DParamOptions): Path2DParamValue` — Declare an editable 2D path parameter.
+
+Use this for hand-shaped 2D profile data: plate outlines, slice profiles, stroke centerlines, and sweep rails. The returned value keeps the model code deterministic while the editor can render a drag-handle path UI.
+
+Override keys use the same explicit row-field form as list params: `Path Name[0].x`, `Path Name[0].y`, and `Path Name.__count__`.
+
+```ts
+const outline = Param.path2d("Bracket Outline", [
+  [-40, -20],
+  [40, -20],
+  [36, 24],
+  [-30, 28],
+], {
+  closed: true,
+  anchor: Param.anchor.sheetOnXY([0, 0, 8], { label: "Bracket outline" }),
+});
+
+return outline.toSketch().filletCorners(4).extrude(5);
+```
+
+**`Path2DParamOptions`** extends ParamAnchorableOptions: `closed?: boolean`, `minPoints?: number`, `maxPoints?: number`, `x?: Partial<Path2DParamAxisDef>`, `y?: Partial<Path2DParamAxisDef>`, `unit?: string`
+
+**`Path2DParamAxisDef`**
+- `min: number` — Initial editor-frame minimum. Points may move outside this range on the infinite canvas.
+- `max: number` — Initial editor-frame maximum. Points may move outside this range on the infinite canvas.
+- Also: `step: number`.
+
+#### `Param.spline2d(name: string, defaultPoints: Spline2DPointInput[], opts?: Spline2DParamOptions): Spline2DParamValue` — Declare an editable 2D spline parameter.
+
+Use this when the model wants hand-shaped smooth curve data instead of a numeric table: handle spines, bowl station curves, sweep rails, and class-A guide profiles. Each node stores `g`, a continuity intent:
+
+- `"G0"` starts/ends a hard curve segment at that point
+- `"G1"` keeps the point in a tangent-smooth run
+- `"G2"` keeps the point in a curvature-smooth cubic run
+
+Override keys use explicit row-field form: `Curve Name[0].x`, `Curve Name[0].y`, `Curve Name[0].g`, and `Curve Name.__count__`.
+
+```ts
+const spine = Param.spline2d("Handle Spine", [
+  { x: 0, y: 0, g: "G2" },
+  { x: 35, y: 8, g: "G2" },
+  { x: 80, y: 2, g: "G1" },
+], {
+  anchor: Param.anchor.sheetOnXZ([0, -18, 0], { label: "Side-view spine" }),
+});
+
+return sweep(circle2d(2), spine.toCurveOnXZ());
+```
+
+**`Spline2DParamOptions`** extends ParamAnchorableOptions: `closed?: boolean`, `degree?: number`, `defaultContinuity?: Spline2DContinuity`, `minPoints?: number`, `maxPoints?: number`, `x?: Partial<Path2DParamAxisDef>`, `y?: Partial<Path2DParamAxisDef>`, `unit?: string`
+
+#### `Param.placement2d(name: string, spec: Placement2DParamOptions): Placement2DParamValue` — Declare an editable 2D placement sheet parameter.
+
+Use this when the user should arrange named model roles rather than draw geometry: batteries inside an enclosure, rooms across floors, controls on a panel, robot modules on a chassis, or other semantic blockouts.
+
+The script declares stable item IDs, footprints, optional rectangular zones, and interaction rules. The returned value exposes named placements as data; the model code decides what those placements mean geometrically.
+
+Override keys are item-ID based: `Layout.battery.x`, `Layout.battery.y`, `Layout.battery.angle`, and `Layout.battery.zone`.
+
+```ts
+const layout = Param.placement2d("Internal Layout", {
+  frame: { size: [120, 80] },
+  items: [
+    { id: "battery", footprint: { type: "rect", size: [42, 24] }, at: [-25, 0] },
+    { id: "speaker", footprint: { type: "circle", radius: 12 }, at: [32, 8] },
+  ],
+  rules: { bounds: "prevent", collisions: "warn", snap: 1 },
+  anchor: Param.anchor.sheetOnXY([0, 0, 12], { label: "Internal layout" }),
+});
+
+const battery = layout.item("battery");
+const batteryPocket = box(42, 24, 6).translate(battery.x, battery.y, 3);
+```
+
+**`Placement2DParamOptions`** extends ParamAnchorableOptions: `frame?: Placement2DFrameInput`, `zones?: Placement2DZoneInput[]`, `items: Placement2DItemInput[]`, `rules?: Partial<Placement2DRulesDef>`, `unit?: string`
+
+`Placement2DFrameInput`: `{ width?: number, height?: number, size?: Vec2, center?: Placement2DPointInput, at?: Placement2DPointInput }`
+
+`Placement2DZoneInput`: `{ id: string, label?: string, frame?: Placement2DFrameInput }`
+
+**`Placement2DItemInput`**: `id: string`, `label?: string`, `footprint: Placement2DFootprintInput`, `at?: Placement2DPointInput`, `center?: Placement2DPointInput`, `angle?: number`, `zone?: string`, `locked?: boolean`
+
+`Placement2DRulesDef`: `{ bounds: Placement2DRuleMode, collisions: Placement2DRuleMode, snap: number }`
+
 ### Grouping & Local Coordinates
 
 #### `group(...items: GroupInput[]): ShapeGroup` — Group multiple shapes/sketches for joint transforms without merging into a single mesh.
@@ -857,6 +1103,96 @@ Supports transforms (translate, rotate, scale, mirror, transform, rotateAround,
 |----------|------|-------------|
 | `materialProps` | `ShapeMaterialProps \| undefined` | — |
 
+**Freeform Construction**
+
+#### `slicePerpendicularToX(x: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the X axis.
+
+The profile is drawn in the YZ plane. `options.center` is `[y, z]`, so authors can place changing section centers without manually translating sketches in ForgeCAD's internal plane axes.
+
+```js
+Shape.fromSlices([
+  Shape.slicePerpendicularToX(-20, ellipse(10, 2), { center: [0, 3] }),
+  Shape.slicePerpendicularToX(20, ellipse(8, 1.5), { center: [0, 6] }),
+]);
+```
+
+**`FromSlicesAxisSliceOptions`**
+- `center?: FromSlicesVec2` — Plane-local profile center. XY uses [x, y], XZ uses [x, z], YZ uses [y, z].
+
+#### `slicePerpendicularToY(y: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Y axis.
+
+The profile is drawn in the XZ plane. `options.center` is `[x, z]`.
+
+#### `slicePerpendicularToZ(z: number, profile: Sketch, options?: FromSlicesAxisSliceOptions): FromSlicesSlice` — Create a slice descriptor perpendicular to the Z axis.
+
+The profile is drawn in the XY plane. `options.center` is `[x, y]`.
+
+#### `sliceThrough(center: FromSlicesVec3, normal: FromSlicesVec3, profile: Sketch): FromSlicesSlice` — Create a slice descriptor through a world point with an arbitrary plane normal.
+
+The profile origin lands at `center`. Use this when the section plane is not one of the world XY/XZ/YZ planes.
+
+#### `sliceOnFrame(frame: FromSlicesFrameInput, profile: Sketch): FromSlicesSlice` — Create a slice descriptor on a full 3D work frame.
+
+Sheet frame helpers return the right shape for `frame`. Use `Sheet.frameAt()` for tangent construction planes, or `Sheet.framePerpendicularToU()` / `Sheet.framePerpendicularToV()` for cross-sections normal to a surface path. On the Manifold backend, framed slices are lofted in input order when every slice comes from a frame.
+
+**`FromSlicesFrameInput`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point?` | `FromSlicesVec3` | World-space frame origin. Sheet frame helpers return this as `point`. |
+| `origin?` | `FromSlicesVec3` | Alias for `point` when using generic CAD frame terminology. |
+| `normal` | `FromSlicesVec3` | World-space frame normal. |
+| `tangentU?` | `FromSlicesVec3` | World-space direction for the profile's local X axis. Sheet frame helpers return this as `tangentU`. |
+| `tangentV?` | `FromSlicesVec3` | Optional world-space direction for the profile's local Y axis. Sheet frame helpers return this as `tangentV`. |
+| `xAxis?` | `FromSlicesVec3` | Alias for `tangentU`. |
+| `yAxis?` | `FromSlicesVec3` | Alias for `tangentV`. |
+
+#### `fromSlices(slices: FromSlicesSlice[], options?: FromSlicesOptions): Shape` — Construct a 3D shape from cross-section slices on one or more planes.
+
+On the Manifold backend, slices created with `Shape.sliceOnFrame()` are lofted in their input order while preserving each full 3D frame. Other slices with the same normal direction are lofted together. Slices with different normals are combined via smooth radial blending — each silhouette constrains the shape's extent, producing smooth ellipsoidal cross-sections.
+
+```js
+// Egg from two orthogonal silhouettes
+const eggProfile = ellipse(15, 25);
+return Shape.fromSlices([
+  { on: 'xz', at: 0, profile: eggProfile },
+  { on: 'yz', at: 0, profile: eggProfile },
+]);
+```
+
+```js
+// Vase with cross-section transitions
+return Shape.fromSlices([
+  Shape.slicePerpendicularToZ(0, circle2d(20)),
+  Shape.slicePerpendicularToZ(40, rect(25, 25)),
+  Shape.slicePerpendicularToZ(80, circle2d(8)),
+  Shape.slicePerpendicularToY(0, vaseOutline),
+]);
+```
+
+**`FromSlicesSlice`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `on` | `SlicePlane` | Plane normal: axis name or arbitrary unit vector. |
+| `at?` | `number` | Signed offset along the normal from the origin. Omit when `center` defines the plane. |
+| `center?` | `FromSlicesVec3` | World-space point where the 2D profile origin should land on the slice plane. |
+| `profile` | `Sketch` | 2D cross-section profile on that plane. |
+| `frame?` | `FromSlicesFramePlacement` | Full 3D section frame, preserved for ordered lofts through rotating planes. |
+
+**`FromSlicesFramePlacement`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `point` | `FromSlicesVec3` | World-space frame origin. |
+| `normal` | `FromSlicesVec3` | World-space section normal. |
+| `tangentU` | `FromSlicesVec3` | World-space direction for the profile's local X axis. |
+| `tangentV` | `FromSlicesVec3` | World-space direction for the profile's local Y axis. |
+
+**`FromSlicesOptions`**
+- `edgeLength?: number` — Marching-grid edge length for level-set meshing (Manifold only).
+- `boundsPadding?: number` — Extra bounding-box padding (Manifold only).
+
 **Appearance**
 
 #### `color(value: string | undefined): Shape` — Set the color of this shape (hex string, e.g. "#ff0000"). Returns a new Shape with the color applied.
@@ -1267,7 +1603,7 @@ cylinder(60, 20).wrapTexture(label, Wrap.aroundCylinder({ axis: 'z' }));  // wra
 
 #### `ref(path: string): ShapeRef` — Resolve a semantic reference path like `lid`, `lid/back`, or a midpoint selector on `lid/back`.
 
-#### `thicken(thickness: number): Shape` — Offset-thicken an exact open surface or shell into a solid.
+#### `thicken(thickness: ThicknessInput): Shape` — Offset-thicken an exact open surface or shell into a solid.
 
 #### `getMesh(): ShapeRuntimeMesh` — Extract triangle mesh for Three.js rendering
 
@@ -1507,57 +1843,200 @@ const bracket = group(
 | `depth?` | `number` | Thread groove depth in millimeters. Default: 0.8. |
 | `underScale?` | `number` | Relative height of the under-crossing thread. Default: 0.15. |
 
-### `Sheet`
+### `Path2DParamValue`
 
-A parametric open surface value (control grid + knots + analytic differential geometry).
+Runtime value returned by `Param.path2d()`.
+
+Use closed paths as editable profile outlines via `toSketch()`. Use open paths as editable centerlines via `toStroke(width)`.
 
 **Properties:**
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `surface` | `BSplineSurface` | — |
+| `closed` | `boolean` | True when this path is intended to close back to its first point. |
 
 **Methods:**
 
-#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+#### `points(): Vec2[]` — Return the current points as `[x, y]` pairs in the editor coordinate system.
 
-#### `thicken(wall: number, options?: { resolution?: number; }): Shape` — Offset the sheet along its analytic normals into a watertight solid shell of the given wall thickness. Throws if the wall would self-intersect on a concave region (no silent degenerate solid).
+#### `toSketch(): Sketch` — Convert a closed editable path into a sketch profile.
 
-#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+This is the common path for hand-edited plates, outlines, and 2D section profiles that will be extruded, subtracted, or used in sketch booleans. Throws for open paths; use `toStroke(width)` for editable centerlines.
+
+#### `toStroke(width: number, join?: "Round" | "Square"): Sketch` — Convert an editable path into a stroked sketch with physical width.
+
+Use this for rails, ribs, cable routes, gasket paths, and other open centerlines. Closed paths can also be stroked when the intent is a looped band rather than a filled profile.
+
+### `Spline2DParamValue`
+
+Runtime value returned by `Param.spline2d()`.
+
+Spline params preserve both editable point coordinates and each point's continuity intent (`G0`, `G1`, or `G2`). Convert them to curves for sweeps and loft rails, or to sampled paths when an API expects plain points.
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `closed` | `boolean` | True when this spline is intended to close back to its first point. |
+| `degree` | `number` | Requested fitting degree before any automatic reduction for short spans. |
+
+**Methods:**
+
+#### `points(): Vec2[]` — Return the current control nodes as `[x, y]` pairs without continuity metadata.
+
+#### `nodes(): Spline2DPointDef[]` — Return the current editable nodes, including per-point `g` continuity values.
+
+#### `continuities(): Spline2DContinuity[]` — Return only the per-node continuity intents in point order.
+
+#### `toPolyline(samples?: number): Vec2[]` — Sample the spline into 2D `[x, y]` points.
+
+Use this when downstream code needs a polyline instead of a curve object.
+
+#### `toCurveOnXY(z?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the XY plane at constant `z`.
+
+The point's `x` maps to world X and `y` maps to world Y.
+
+`Spline2DCurveOptions`: `{ degree?: number, tolerance?: number, samples?: number }`
+
+#### `toCurveOnXZ(y?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the XZ plane at constant `y`.
+
+The point's `x` maps to world X and `y` maps to world Z. This is useful for side-view height/depth profiles such as spoon bowls, handles, and rails.
+
+#### `toCurveOnYZ(x?: number, options?: Spline2DCurveOptions): NurbsCurve3D` — Fit the editable spline as a 3D curve on the YZ plane at constant `x`.
+
+The point's `x` maps to world Y and `y` maps to world Z.
+
+#### `toCurveSegmentsOnXY(z?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on XY and return separate curve segments split at `G0` nodes.
+
+Use segment output when a hard break should remain visible to downstream code instead of being joined into one continuous curve.
+
+#### `toCurveSegmentsOnXZ(y?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on XZ and return separate curve segments split at `G0` nodes.
+
+#### `toCurveSegmentsOnYZ(x?: number, options?: Spline2DCurveOptions): NurbsCurve3D[]` — Fit the spline on YZ and return separate curve segments split at `G0` nodes.
+
+#### `toPathOnXY(z?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the XY plane at constant `z`.
+
+This is useful for sweeps and surface helpers that accept point paths.
+
+#### `toPathOnXZ(y?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the XZ plane at constant `y`.
+
+#### `toPathOnYZ(x?: number, options?: Spline2DCurveOptions): Vec3[]` — Sample the spline as 3D points on the YZ plane at constant `x`.
+
+### `Placement2DParamValue`
+
+Runtime value returned by `Param.placement2d()`.
+
+Placement sheets return semantic item positions. The model decides what each item means geometrically, so users can drag named blocks without editing the construction code.
+
+#### `items(): Placement2DItemPlacement[]` — Return all current item placements as immutable copies.
+
+#### `positions(): Record<string, Placement2DItemPlacement>` — Return current placements keyed by item id for table-style lookup.
+
+#### `item(id: string): Placement2DItemPlacement` — Return one named item placement.
+
+Throws if `id` was not declared in the sheet, which keeps model code tied to stable semantic item IDs rather than fragile list indices.
+
+### `CurveNetBuilder`
+
+#### `alongRails(railA: CurveInput, railB: CurveInput): this` — Use two lengthwise boundary curves as guide rails.
+
+Chain `.sections(...)` to create a bi-rail surface: the rails define the sheet edges while each section curve shapes the cross-span at its station.
+
+#### `sections(...curves: CurveInput[]): this` — Add crosswise section curves.
+
+By itself this skins the sections into a surface. After `.alongRails(...)`, the sections are fitted between the two rails so the surface follows both the boundary guide curves and the section profiles.
+
+#### `resolution(samples: number): this` — Set the sampling resolution used to build curve-family surface grids.
+
+This affects `.lengthwise(...)`, `.crosswise(...)`, and `.alongRails(...).sections(...)` surfaces. It does not resample explicit `.cage(grid)` input because the cage already is the authored control net.
+
+#### `matchStartU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 0` (left) boundary.
+
+Pass `{ edge }` to match an adjacent sheet's tangent (G1) or curvature (G2), or `{ tangent }` to impose an explicit cross-boundary direction. See `BoundaryCondition`.
+
+**`BoundaryCondition`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge?` | `SheetEdge` | Match the tangent (G1) and curvature (G2) of an existing sheet edge across this boundary. |
+| `tangent?` | `Vec3` | Or impose an explicit cross-boundary tangent direction in world space (auto-normalized). |
+| `tangentScale?` | `number` | Scalar magnitude for the imposed `tangent` ramp, in model units. Ignored when `edge` is given. Default: the local cross-boundary control-span length (chord-scaled), so the imposed tangent has the same strength as the surface already carries — no magic number. |
+| `continuity?` | `0 \| 1 \| 2` | Continuity order to enforce on this side. Default inferred: 1 if a tangent or edge is given, else 0. G2 (curvature) requires an `edge` to copy the neighbor's second difference. |
 
 **`SheetEdge`**
 - `fixed: "u" | "v"` — Which parameter is held fixed along this edge.
 - `value: 0 | 1` — The fixed value (0 or 1).
 - Also: `sheet: Sheet`.
 
-- `get rearEdge(): SheetEdge`
-- `get leftEdge(): SheetEdge`
-- `get rightEdge(): SheetEdge`
-- `pointAt(u: number, v: number): Vec3`
-- `normalAt(u: number, v: number): Vec3`
-- `curvatureAt(u: number, v: number): SurfaceCurvature`
+#### `matchEndU(condition: BoundaryCondition): this` — Enforce a continuity condition on the `u = 1` (right) boundary. See `matchStartU`.
 
-### `CurveNetBuilder`
+#### `matchStartV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 0` (front) boundary. See `matchStartU`.
+
+#### `matchEndV(condition: BoundaryCondition): this` — Enforce a continuity condition on the `v = 1` (rear) boundary. See `matchStartU`.
+
+#### `closedU(): this` — Weld the two ends of the U direction into a tangent-continuous periodic loop, so the `u = 0` and `u = 1` boundaries coincide with NO G0 kink (a closed tube/ring in U — e.g. a bowl's around-rim seam). The cage's first and last U rows must already be coincident (the loop must close in position).
+
+#### `closedV(): this` — Weld the two ends of the V direction into a tangent-continuous periodic loop. See `closedU`.
 
 #### `toSheet(): Sheet` — Build (once) and return the Sheet.
 
 - `lengthwise(...curves: CurveInput[]): this`
 - `crosswise(...curves: CurveInput[]): this`
-- `alongRails(railA: CurveInput, railB: CurveInput): this`
-- `sections(...curves: CurveInput[]): this`
 - `cage(grid: Vec3[][]): this`
 - `degree(u: number, v: number): this`
 - `get frontEdge(): SheetEdge`
 - `get rearEdge(): SheetEdge`
 - `get leftEdge(): SheetEdge`
 - `get rightEdge(): SheetEdge`
+- `get frontCurve(): NurbsCurve3D`
+- `get rearCurve(): NurbsCurve3D`
+- `get leftCurve(): NurbsCurve3D`
+- `get rightCurve(): NurbsCurve3D`
 - `get surface(): BSplineSurface`
 - `pointAt(u: number, v: number): Vec3`
 - `normalAt(u: number, v: number): Vec3`
+- `frameAt(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToU(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
+- `framePerpendicularToV(u: number, v: number, options?: SheetFrameOptions): SheetFrame`
 - `curvatureAt(u: number, v: number): SurfaceCurvature`
+- `curveAlong(edge: SheetEdge): NurbsCurve3D`
+- `curveAlongU(v: number): NurbsCurve3D`
+- `curveAlongV(u: number): NurbsCurve3D`
+- `pathAlong(edge: SheetEdge, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongBoundary(spans: SheetBoundaryPathSpan[], options?: SheetBoundaryPathOptions): Vec3[]`
+- `pathAlongU(v: number, options?: SheetPathAlongOptions): Vec3[]`
+- `pathAlongV(u: number, options?: SheetPathAlongOptions): Vec3[]`
 - `thicken(wall: number, options?: { resolution?: number; }): Shape`
+- `thickenInsideBy(thickness: ThicknessInput, options?: { resolution?: number; }): Shape`
 - `matchEdge(edge: SheetEdge): MatchEdgeBuilder`
 
+**`SheetFrameOptions`**
+- `normalOffset?: number` — Offset the frame origin along the analytic surface normal. Default 0.
+
+**`SheetPathAlongOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Samples along the path span. Default 32. |
+| `start?` | `number` | Normalized start parameter along the path. Default 0. |
+| `end?` | `number` | Normalized end parameter along the path. Default 1. |
+| `reverse?` | `boolean` | Return points from end to start after sampling the span. Default false. |
+| `normalOffset?` | `number` | Offset each path point along the analytic surface normal. Default 0. |
+
+**`SheetBoundaryPathSpan`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `edge` | `SheetEdge` | Boundary edge to sample for this span. |
+| `start?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 0. |
+| `end?` | `SheetPathParameter` | Normalized edge parameter or world point projected to the closest edge parameter. Default 1. |
+| `samples?` | `number` | Samples along this edge span. Defaults to options.samplesPerEdge or 32. |
+
+**`SheetBoundaryPathOptions`**
+- `samplesPerEdge?: number` — Samples for spans that do not specify their own count. Default 32.
+- `normalOffset?: number` — Offset each path point along the analytic surface normal. Default 0.
+- `tolerance?: number` — Maximum allowed gap between adjacent sampled spans. Default 1e-6.
+
 ### `MatchEdgeBuilder`
 
 - `toG0(neighbor: SheetEdge): Sheet`
@@ -2126,7 +2605,22 @@ donut.region([40, 0]).extrude(10); // seed at radius 40, inside the ring
 
 **Promotion**
 
-#### `extrude(height: number, opts?: { twist?: number; divisions?: number; scaleTop?: number | Vec2; }): Shape` — Extrude this 2D sketch along Z to create a 3D solid. Supports twist and scale tapering.
+#### `extrude(extent: number | EndCondition, opts?: { twist?: number; divisions?: number; scaleTop?: number | Vec2; }): Shape` — Extrude this 2D sketch along Z to create a 3D solid. Supports twist and scale tapering. The extent may be a numeric height or an `EndCondition` (up to a face, plane, or vertex).
+
+**`EndCondition`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `upToFace?` | `FaceRef \| SketchFaceTarget` | Terminate flush with a planar face perpendicular to the feature direction. |
+| `upToPlane?` | `PlaneOp` | Terminate at an arbitrary plane (ray-plane intersection along the direction). |
+| `upToVertex?` | `Vec3` | Terminate at the plane through this point, perpendicular to the direction. |
+| `offset?` | `number` | Signed offset PAST the resolved surface in the travel direction (default 0). |
+
+`FaceRef` — defined in [core](/docs/core).
+
+**`PlaneOp`**
+- `normal: Vec3` — Plane normal. Need not be unit length; it is normalized internally.
+- `offset?: number` — Signed offset of the plane along its normal from the world origin (default 0).
 
 #### `revolve(degrees?: number, segments?: number): Shape` — Revolve this 2D sketch around the world Z axis. Sketch X is radius; sketch Y becomes world Z height. Keep the profile at X > 0 unless it intentionally touches the axis.
 
@@ -2147,8 +2641,6 @@ const shifted = rect(4, 70).attachTo(plate, 'bottom-left', 'top-left', [5, 0]);
 
 Use this when a 2D profile should be oriented onto a 3D face before extrusion or other downstream operations.
 
-`FaceRef` — defined in [core](/docs/core).
-
 **Labels**
 
 #### `labelEdge(name: string): Sketch` — Label the single boundary edge (for circles, single-loop profiles). Returns a new sketch.
@@ -2709,6 +3201,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Route3D](#route3d)
 - [NurbsCurve3D](#nurbscurve3d)
 - [NurbsSurface](#nurbssurface)
+- [Sheet](#sheet)
 - [PathBuilder](#pathbuilder) — Line Segments, Arcs, Curves, Closing & Output
 - [ProductSkin](#productskin)
 - [ProductSurfaceRef](#productsurfaceref)
@@ -2732,6 +3225,7 @@ Smooth curves, lofted surfaces, swept solids, splines, and high-level product sk
 - [Surface](#surface)
 - [Blend](#blend)
 - [Analysis](#analysis)
+- [Thickness](#thickness)
 - [Product](#product)
 - [Carrier](#carrier)
 - [SurfaceMembers](#surfacemembers)
@@ -2771,17 +3265,45 @@ const rail = Curve.BlendG2(
 **`CurveBlendG2Endpoint`** extends CurveBlendEndpoint
 - `curvature?: Vec3` — Optional endpoint curvature/second-derivative vector. Default is zero.
 
-#### `Curve.Arc(options: CurveArcOptions): NurbsCurve3D` — Create an exact circular 3D arc from start, end, and start tangent.
+#### `Curve.Bridge(options: CurveBridgeOptions): NurbsCurve3D` — Bridge two existing curve endpoints with inferred tangent or curvature continuity.
 
-The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
+This is the Onshape-style "select two curves and bridge them" primitive: ForgeCAD reads the endpoint positions, tangent directions, and NURBS curvature from the selected curves so callers do not hand-author tangent vectors. Use `continuity: 'G1'` for a cubic tangent bridge or the default `G2` for a quintic curvature bridge.
 
 ```js
-const rail = Curve.Arc({
-  start: [40, 0, 0],
-  end: [0, 40, 0],
-  tangent: [0, 1, 0],
+const leftRim = Curve.Fit([[20, -12, 0], [0, -18, 2], [-30, -14, 1]]);
+const rightRim = Curve.Fit([[20, 12, 0], [0, 18, 2], [-30, 14, 1]]);
+const roundedNose = Curve.Bridge({
+  from: { curve: leftRim, at: 'end' },
+  to: { curve: rightRim, at: 'end' },
+  continuity: 'G2',
 });
-const tube = sweep(circle2d(2), rail);
+```
+
+**`CurveBridgeOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `from` | `CurveBridgeEndpoint` | Endpoint where the bridge starts. |
+| `to` | `CurveBridgeEndpoint` | Endpoint where the bridge ends. |
+| `continuity?` | `CurveBridgeContinuity` | Continuity target. Default `G2`. |
+| `weight?` | `number` | Tangent reach relative to bridge chord. Default 0.6. |
+
+**`CurveBridgeEndpoint`**
+- `curve: CurveTrimInput` — Existing curve endpoint to bridge from or to.
+- `at?: CurveBridgeEndpointAt` — Which endpoint of the curve to use. Default is `end`.
+- `weight?: number` — Tangent reach relative to bridge chord. Overrides `CurveBridgeOptions.weight` for this side.
+
+#### `Curve.Arc(options: CurveArcOptions): NurbsCurve3D` — Create an exact circular 3D arc from start, end, and start tangent.
+
+The returned curve is a rational quadratic `NurbsCurve3D`, split into stable spans when needed, so it can feed `sweep` without sampling the authoring intent away.
+
+```js
+const rail = Curve.Arc({
+  start: [40, 0, 0],
+  end: [0, 40, 0],
+  tangent: [0, 1, 0],
+});
+const tube = sweep(circle2d(2), rail);
 ```
 
 **`CurveArcOptions`**
@@ -2835,6 +3357,52 @@ const loop = Curve.Fit(
 - `tolerance?: number` — Maximum allowed interpolation residual in model units. Default 1e-7.
 - `closed?: boolean` — Interpolate a closed periodic loop through the points. The loop closes from the last point back to the first automatically — do not repeat the first point at the end.
 
+#### `Curve.ProjectOnSurface(curve: NurbsCurve3D | Vec3[], sheet: Sheet, options?: CurveProjectOnSurfaceOptions): NurbsCurve3D` — Project a curve onto a `Sheet` along the surface normal and return the exact NURBS foot curve.
+
+This is the "drape a curve onto a surface" primitive: each sampled point of the source curve is inverted onto the sheet (closest surface point via the analytic jet), and the foot points are fitted with `Curve.Fit`. Use it to trace a planned trim line, seam, or graphic onto a freeform panel, then sweep or trim from the real on-surface curve.
+
+The source may be an exact `NurbsCurve3D` or a `Vec3[]` polyline (for example a placed 2D path). With `{ closed: true }` the result is a periodic loop, for draping a closed boundary onto the sheet. Set `maxGap` to require that every sample lands within a distance of the surface; the call throws if any sample misses (no silent fallback).
+
+```js
+const panel = Surface.Net().cage(cage);
+const guide = Curve.Line([-20, 0, 30], [20, 0, 30]);
+const seam = Curve.ProjectOnSurface(guide, panel);
+const bead = sweep(circle2d(0.6), seam);
+```
+
+**`CurveProjectOnSurfaceOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Coarse samples taken along the source curve before per-sample projection. Default 64. |
+| `refineIterations?` | `number` | Newton refinement iterations of the (u, v) foot-point per sample. Default 8. |
+| `tolerance?` | `number` | Interpolation tolerance passed to Curve.Fit for the result. Default 1e-4. |
+| `closed?` | `boolean` | Fit a closed periodic loop (use when the source curve is a closed loop). Default false. |
+| `maxGap?` | `number` | Max allowed projection gap; throws if any sample lands farther than this from the surface foot. Default Infinity (no gate). |
+
+#### `Curve.Intersect(sheetA: Sheet, sheetB: Sheet, options?: CurveIntersectOptions): NurbsCurve3D[]` — Intersect two `Sheet` surfaces and return the exact NURBS intersection branches.
+
+This is curve-following surface-surface intersection (SSI): a transversal marcher follows each intersection branch using the analytic surface jets (the intersection tangent is `cross(normalA, normalB)`), converging every step onto both surfaces, then fits each branch with `Curve.Fit`. A single pair of sheets can intersect in several disjoint curves, so the result is an array (empty when the sheets do not meet).
+
+Only transversal intersections (where the surfaces cross and the intersection tangent `cross(normalA, normalB)` is well defined) are detected. A tangential / grazing contact (where the surface normals are parallel and the tangent is undefined) is not marched and may be reported as no-intersection (an empty array) — tangential SSI is a documented follow-on, not a silent fallback.
+
+```js
+const wing = Surface.Net().cage(wingCage);
+const rib = Surface.Net().cage(ribCage);
+const [seam] = Curve.Intersect(wing, rib);
+const weld = sweep(circle2d(0.5), seam);
+```
+
+**`CurveIntersectOptions`**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `samples?` | `number` | Grid resolution per axis for seeding the marcher (samples x samples on sheetA). Default 48. |
+| `step?` | `number` | Marching step as a fraction of sheetA's average sample spacing. Default 0.5. |
+| `refineIterations?` | `number` | Newton iterations to converge each marched point onto both surfaces. Default 12. |
+| `tolerance?` | `number` | Convergence/coincidence tolerance in model units. Default 1e-4. |
+| `fitTolerance?` | `number` | Fit tolerance passed to Curve.Fit. Default 1e-3. |
+
 #### `Curve.Trim<T extends CurveTrimInput>(curve: T, start: number, end: number): CurveTrimOutput<T>` — Extract an exact curve segment from normalized parameter `start` to `end`.
 
 `NurbsCurve3D` inputs are trimmed with exact knot insertion/subdomain extraction. Polyline point arrays are trimmed by arclength over their exact line segments. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
@@ -2843,6 +3411,67 @@ const loop = Curve.Fit(
 
 `NurbsCurve3D` inputs reverse control points, weights, and knots. Polyline point arrays are cloned and reversed. Sampled `Curve3D` splines are rejected until ForgeCAD has a tolerance-controlled rebuild path.
 
+#### `Curve.closestParameter(curve: CurveClosestParameterInput, point: Vec3, options?: CurveClosestParameterOptions): number` — Find the normalized parameter on an exact curve closest to a world point.
+
+This is the query companion to `Curve.Trim()`: use it to locate where a construction point lands on an existing rail, surface boundary, or edge curve, then trim/sweep from that real geometric station instead of copying the original construction points.
+
+`NurbsCurve3D` inputs are searched by curve parameter with coarse sampling plus local refinement. Polyline point arrays are projected onto their exact line segments and return an arclength-normalized parameter.
+
+```js
+const start = Curve.closestParameter(sheet.frontCurve, [-20, -12, 4]);
+const end = Curve.closestParameter(sheet.frontCurve, [20, -12, 4]);
+const rimRail = Curve.Trim(sheet.frontCurve, start, end);
+```
+
+**`CurveClosestParameterOptions`**
+- `samples?: number` — Coarse samples before local refinement. Default 96.
+
+#### `Curve.join(curves: CurveJoinInput[], options?: CurveJoinOptions): Vec3[]` — Join touching curve segments into one sampled sweep path.
+
+This is the composite-curve primitive for downstream features that need to follow several real edges as one path: rolled rims, seam beads, trim strips, weld beads, and surface-boundary inlays. ForgeCAD validates that adjacent segment endpoints touch; it will not silently reverse or bridge gaps.
+
+```js
+const rimPath = Curve.join([
+  Curve.Reverse(Curve.Trim(sheet.frontCurve, 0, u)),
+  sheet.leftCurve,
+  Curve.Trim(sheet.rearCurve, 0, u),
+]);
+const rim = sweep(ellipse(0.8, 0.35), rimPath);
+```
+
+**`CurveJoinOptions`**
+- `samples?: number` — Points sampled per exact curve segment. Default 32.
+- `tolerance?: number` — Maximum allowed gap between adjacent segment endpoints. Default 1e-6.
+
+#### `Curve.placeOnXY(path: CurvePath2D, z?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the XY plane at world Z.
+
+The returned 3D point array can feed `Surface.Net`, `Curve.Fit`, `sweep`, `Curve.Trim`, and any other curve consumer that accepts points.
+
+```js
+const rail = Curve.placeOnXY(path().moveTo(0, 0).bezierTo(30, 8, 60, -4, 90, 0), 12);
+const smoothRail = Curve.Fit(rail);
+```
+
+**`CurvePathPlacementOptions`**
+- `samples?: number` — Optional sample count when [`path`](/docs/sketch#path) is a path-like object.
+
+#### `Curve.placeOnXZ(path: CurvePath2D, y?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the XZ plane at world Y.
+
+The path's first coordinate becomes X and the second becomes Z.
+
+#### `Curve.placeOnYZ(path: CurvePath2D, x?: number, options?: CurvePathPlacementOptions): Vec3[]` — Place a 2D path onto the YZ plane at world X.
+
+The path's first coordinate becomes Y and the second becomes Z. This is the direct "sketch cross-sections on offset planes" primitive for surface nets.
+
+#### `Curve.placeOnPlane(path: CurvePath2D, options: CurvePlanePlacementOptions): Vec3[]` — Place a 2D path onto an arbitrary world plane.
+
+`origin` is the 2D sketch origin in world space. `xAxis` and `yAxis` are perpendicular world directions for the local sketch axes.
+
+**`CurvePlanePlacementOptions`** extends CurvePathPlacementOptions
+- `origin: Vec3` — World-space origin of the 2D sketch plane.
+- `xAxis: Vec3` — World-space direction for the sketch X axis.
+- `yAxis: Vec3` — World-space direction for the sketch Y axis.
+
 #### `Curve.Route: typeof Route3D` — Build analytic 3D line/arc routes for sweeps.
 
 `Curve.Route.fromPolyline()` is the canonical route API. It returns a `Route3D` value object, preserving exact route segments, named port frames, and the lowerable `route3d` sweep compile plan.
@@ -2941,7 +3570,7 @@ A closed spline (default) returns a filled profile. An open spline requires a st
 | `strokeWidth?` | `number` | For open splines, provide stroke width to return a solid Sketch. If omitted for open splines, an error is thrown. |
 | `join?` | `"Round" \| "Square"` | Stroke join for open splines. Default 'Round'. |
 
-#### `loft(profiles: Sketch[], heights: number[], options?: LoftOptions): Shape` — Loft between multiple sketches along Z stations.
+#### `loft(profiles: Sketch[], heights: (number | EndCondition)[], options?: LoftOptions): Shape` — Loft between multiple sketches along Z stations.
 
 Profiles can differ in topology and vertex count: interpolation is done on signed-distance fields and meshed with level-set extraction. Heights must be strictly increasing. Compatible loft stacks can also stay on the maintained export-backend path.
 
@@ -2949,6 +3578,8 @@ The surface is smooth through 3+ stations (C1 spanwise interpolation, like CAD l
 
 Performance note: loft is significantly heavier than primitive/extrude/revolve. If the part is axis-symmetric (bottles, vases, knobs), prefer revolve().
 
+`EndCondition` — defined in [sketch](/docs/sketch).
+
 #### `sweep(profile: Sketch, path: SweepPathInput, options?: SweepOptions): Shape`
 
 **`SweepOptions`**
@@ -3128,6 +3759,95 @@ Uses Algorithm A2.3 basis-function derivatives with the rational quotient rule,
 
 #### `tessellate(resU?: number, resV?: number): { positions: Vec3[]; normals: Vec3[]; indices: number[]; }` — Tessellate the surface into a triangle mesh. Returns positions, normals, and triangle indices.
 
+### `Sheet`
+
+A parametric open surface value (control grid + knots + analytic differential geometry).
+
+**Properties:**
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `surface` | `BSplineSurface` | — |
+
+**Methods:**
+
+#### `get frontEdge(): SheetEdge` — Edge naming follows parameter direction (documented): front=v0, rear=v1, left=u0, right=u1.
+
+#### `get frontCurve(): NurbsCurve3D` — Exact curve along the front boundary (`v = 0`).
+
+#### `get rearCurve(): NurbsCurve3D` — Exact curve along the rear boundary (`v = 1`).
+
+#### `get leftCurve(): NurbsCurve3D` — Exact curve along the left boundary (`u = 0`).
+
+#### `get rightCurve(): NurbsCurve3D` — Exact curve along the right boundary (`u = 1`).
+
+#### `curveAlong(edge: SheetEdge): NurbsCurve3D` — Extract an exact NURBS iso-curve from one of this sheet's boundary edges.
+
+Use this when a downstream feature should be driven by the actual sheet boundary, such as a swept rim, seam bead, trim strip, or adjacent blend.
+
+`SheetEdge` — defined in [core](/docs/core).
+
+#### `curveAlongU(vInput: number): NurbsCurve3D` — Extract an exact NURBS iso-curve in the sheet U direction at fixed `v`.
+
+Use this for centerline rails, ribs, beads, and trim features that live on the interior of a freeform sheet instead of on a boundary edge.
+
+#### `curveAlongV(uInput: number): NurbsCurve3D` — Extract an exact NURBS iso-curve in the sheet V direction at fixed `u`.
+
+Use this for cross-surface rails, seam lines, straps, and inspection paths that should be driven by the sheet parameterization rather than global axes.
+
+#### `pathAlong(edge: SheetEdge, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path along a sheet boundary edge.
+
+Use this when a downstream feature should follow the real surface edge but does not need to stay an exact NURBS curve, for example a lip, gasket bead, trim strip, weld seam, or inlay lifted off the surface by `normalOffset`.
+
+`SheetPathAlongOptions` — defined in [core](/docs/core).
+
+#### `pathAlongBoundary(spans: SheetBoundaryPathSpan[], options?: SheetBoundaryPathOptions): Vec3[]` — Sample one connected path across ordered sheet boundary edge spans.
+
+This is the composite-boundary primitive for rolled rims, weld beads, gaskets, trim strips, and inlays that follow several sheet edges as one continuous rail. Span `start` / `end` values may be normalized parameters or world points; world points are resolved to the closest point on that edge so callers do not have to manually invoke `Curve.closestParameter()`.
+
+`SheetBoundaryPathSpan` — defined in [core](/docs/core).
+
+`SheetBoundaryPathOptions` — defined in [core](/docs/core).
+
+#### `pathAlongU(vInput: number, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path in the sheet U direction at fixed `v`.
+
+Unlike `curveAlongU()`, this can lift points along the analytic normal with `normalOffset`, which is the common path for swept ribs, inlays, and raised details on a freeform carrier surface.
+
+#### `pathAlongV(uInput: number, options?: SheetPathAlongOptions): Vec3[]` — Sample a world-space path in the sheet V direction at fixed `u`.
+
+Use this for lifted cross-surface features where a sampled path is more useful than an exact iso-curve, for example straps, grooves, or probes.
+
+#### `frameAt(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build an orthonormal local work frame on the sheet.
+
+This is the "construct tangent plane/frame on a surface" primitive for downstream sketches, profiles, fixtures, inspection probes, and features that must be oriented from the sheet itself rather than global axes.
+
+`SheetFrameOptions` — defined in [core](/docs/core).
+
+#### `framePerpendicularToU(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build a section work frame perpendicular to the sheet's U direction.
+
+This is the "plane normal to path" primitive for ribs, raised handles, bosses, and other details whose cross-sections should be sketched across a carrier surface while marching along the surface U direction. The returned frame can be passed directly to `Shape.sliceOnFrame()`.
+
+#### `framePerpendicularToV(uInput: number, vInput: number, options?: SheetFrameOptions): SheetFrame` — Build a section work frame perpendicular to the sheet's V direction.
+
+Use this when the guide path runs in the surface V direction and the sketch profile should span the U direction while its height follows the surface normal. The returned frame can be passed directly to `Shape.sliceOnFrame()`.
+
+#### `toShape(options?: { resolution?: number; }): Shape` — Return this open sheet as a renderable surface Shape.
+
+#### `thicken(wall: number, options?: { resolution?: number; }): Shape` — Offset the sheet along its analytic normals into a watertight solid shell of the given wall thickness. Throws if the wall would self-intersect on a concave region (no silent degenerate solid).
+
+#### `thickenInsideBy(thickness: ThicknessInput, options?: { resolution?: number; }): Shape` — Thicken this sheet inward by a scalar UV thickness field.
+
+Numeric input delegates to `Sheet.thicken()`. `Thickness.*` fields produce a sampled solid because a variable normal offset is not generally an exact NURBS surface.
+
+#### `matchEdge(edge: SheetEdge): MatchEdgeBuilder` — Per-edge continuity match against a neighbor (returns a NEW Sheet).
+
+- `get rearEdge(): SheetEdge`
+- `get leftEdge(): SheetEdge`
+- `get rightEdge(): SheetEdge`
+- `pointAt(u: number, v: number): Vec3`
+- `normalAt(u: number, v: number): Vec3`
+- `curvatureAt(u: number, v: number): SurfaceCurvature`
+
 ### `PathBuilder`
 
 **Line Segments**
@@ -3822,7 +4542,7 @@ Canonical exact/smooth 3D curve constructors.
 
 `Curve.*` is the public home for reference curves and route centerlines that feed `sweep`, `variableSweep`, route visualization, and future path consumers. Standalone 3D curve constructors have been collapsed into this namespace.
 
-Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Blend`, `Curve.BlendG2`, `Curve.Arc`, `Curve.Line`, `Curve.Nurbs`, `Curve.Fit`, `Curve.Trim`, `Curve.Reverse`, `Curve.Route`, `Curve.Helix`.
+Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Blend`, `Curve.BlendG2`, `Curve.Bridge`, `Curve.Arc`, `Curve.Line`, `Curve.Nurbs`, `Curve.Fit`, `Curve.ProjectOnSurface`, `Curve.Intersect`, `Curve.Trim`, `Curve.Reverse`, `Curve.closestParameter`, `Curve.join`, `Curve.placeOnXY`, `Curve.placeOnXZ`, `Curve.placeOnYZ`, `Curve.placeOnPlane`, `Curve.Route`, `Curve.Helix`.
 
 ### `Surface`
 
@@ -3831,6 +4551,31 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
 - `Cone(options: SurfaceConeOptions): Shape` — Create a finite analytic conical or frustum sheet, optionally bounded by start/end angles.
 - `Sphere(options: SurfaceSphereOptions): Shape` — Create a finite analytic spherical sheet bounded by longitude and latitude ranges.
 - `Torus(options: SurfaceTorusOptions): Shape` — Create a finite analytic torus sheet bounded by major and tube angle ranges.
+- `Sweep(profile: SurfaceSweepProfileInput, spine: SweepPathInput, options?: SurfaceSweepOptions): Sheet` — Sweep an open 2D profile path along a 3D spine to create an open surface sheet.
+
+  This is the surface-first counterpart to the solid `sweep()` function. Use it for class-A/product workflows where the shape starts as an infinitely thin carrier sheet, then becomes physical material with `.thicken(...)`. The profile's local X axis maps across the sheet, local Y maps along the swept frame's up/normal direction, and the spine direction becomes sheet U.
+
+  ```js
+  const sideProfile = Curve.Fit(Curve.placeOnXZ(path().moveTo(0, 0).bezierTo(40, -8, 90, 8, 140, 3)));
+  const crossSection = path().moveTo(-20, 2).bezierTo(-8, -4, 8, -4, 20, 2);
+  const sheet = Surface.Sweep(crossSection, sideProfile);
+  const thinPart = sheet.thicken(1.2);
+  ```
+- `Loft(input: SurfaceLoftInput): Sheet` — Loft an open surface sheet through ordered profile stations.
+
+  This is the surface-first counterpart to solid lofts: profiles are open 2D section curves, point stations intentionally collapse a smooth tip, and guide curves can pin named connection landmarks such as rims or low points. The result is an open `Sheet`; call `.thicken(...)` to make physical material.
+
+  ```js
+  const sheet = Surface.Loft({
+    axis: 'X',
+    profiles: [
+      { at: -40, point: [-40, 0, 0] },
+      { at: 0, profile: path().moveTo(-12, 2).bezierTo(-4, -4, 4, -4, 12, 2) },
+      { at: 40, profile: path().moveTo(-5, 0).lineTo(5, 0) },
+    ],
+    connections: [{ name: 'lowPoint', profileParameter: 0.5 }],
+  });
+  ```
 - `Nurbs(controlGrid: Vec3[][], options?: NurbsSurfaceOptions): Shape` — Create an exact NURBS surface from a grid of control points.
 
   The control grid is indexed as `controlGrid[u][v]` — each row is a curve in the V direction, and columns trace curves in the U direction. With default options this builds a bicubic non-rational B-spline sheet with uniform clamped knots; `NurbsSurfaceOptions` controls degrees, weights, knots, trim loops, tessellation, domain, and an optional `thickness` to return a thin solid instead of an open sheet.
@@ -3856,20 +4601,109 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
   const panel = Surface.Patch({ bottom, top, left, right }).thicken(1.5);
   ```
 - `Boundary(input: SurfaceBoundaryInput): Shape`
-- `Fill(input: SurfaceFillInput): Shape`
+- `Fill(input: SurfaceFillInput): Shape` — Create an n-sided open surface sheet from 3 or more boundary curves (energy-minimizing constrained fill).
+
+  Boundaries form a closed loop of any size (n >= 3). They are exact by default: pass `NurbsCurve3D` values or `Shape.edge()` refs, or set `{ approximate: true }` to accept sampled `Curve3D`/`Vec3[]` boundaries. Use `match` to make a named boundary G0/G1/G2-tangent to a neighboring face. The result is an open sheet — call `.thicken(t)` for a thin solid.
+
+  Two optional fields pull the fill onto interior features (OCCT backend only; the Truck/SDF backends reject them):
+
+  - `through` — interior constraint curves the surface must pass through (not part of the boundary loop). These are matched positionally (G0) only; G1/G2 on a free interior curve is not honored, so a non-`'G0'` `continuity` throws.
+  - `points` — isolated interior points the surface must interpolate.
+
+  ```js
+  const skin = Surface.Fill({
+    boundaries: [
+      { name: 'a', curve: edgeA }, { name: 'b', curve: edgeB },
+      { name: 'c', curve: edgeC }, { name: 'd', curve: edgeD }, { name: 'e', curve: edgeE },
+    ],
+    match: { a: { target: neighbor.edge('top'), continuity: 'G1' } },
+    through: [{ curve: interiorSpine }], // pull the fill onto an internal feature line
+    points: [[10, 10, 4]],               // pin an interior bump
+  });
+  ```
 - `Sew(shapes: Shape[], options?: { tolerance?: number; }): Shape`
 - `Solid(input: Shape | Shape[], options?: SurfaceSolidOptions): Shape` — Sew surface faces or consume an existing sewn shell and make a solid B-rep.
 - `Extend(shape: Shape, options: SurfaceExtendOptions): Shape`
 - `Trim(shape: Shape, tool: Shape | SurfacePlaneOp): Shape`
 - `Split(shape: Shape, tool: Shape | SurfacePlaneOp): [ Shape, Shape ]`
 - `Match(shape: Shape, options: { edge: "u0" | "u1" | "v0" | "v1"; target: EdgeRef; continuity?: SurfaceContinuity; }): Shape`
-- `Net(): CurveNet` — Begin a curve-network (Gordon) surface — the class-A keystone. Chain `.lengthwise(...)/.crosswise(...)` (or `.alongRails(a,b).sections(...)`, or `.cage(grid)`), then `.thicken(wall)` to get a solid Shape. Returns a fluent [`Sheet`](/docs/core#sheet) builder with analytic point/normal/curvature queries and named edges.
+- `Net(): CurveNet` — Begin a curve-network (Gordon) surface — the class-A keystone. Chain `.lengthwise(...)/.crosswise(...)` (or `.alongRails(a,b).sections(...)`, or `.cage(grid)`), then `.thicken(wall)` to get a solid Shape. Returns a fluent `Sheet` builder with analytic point/normal/curvature queries and named edges.
+- `BoundaryNet(): CurveNet` — Begin a **Boundary Surface** — the canonical class-A surfacing primitive (SolidWorks "Boundary Boss/Base", Onshape "Boundary surface", Rhino NetworkSrf). It fills a curve cage exactly like `Net` (same Gordon interior), then adds the two foundational boundary capabilities a real boundary surface has:
+
+  1. **Per-side continuity** — `.matchStartU/.matchEndU/.matchStartV/.matchEndV` enforce G0/G1/G2 across a side, either matching an adjacent sheet's edge (tangent/curvature) or imposing an explicit cross-boundary tangent.
+  2. **Closed / periodic form** — `.closedU()/.closedV()` weld a direction's two ends into a tangent-continuous loop, so a closed-rim surface (e.g. a bowl's around-rim seam) is smooth with NO G0 kink.
+
+  Returns the same fluent builder as `Net` (cage/families/degree plus the new boundary methods); finish with `.toSheet()` or `.thicken(wall)`. Verify a matched seam with `Analysis.EdgeMatch`.
+
+  ```js
+  // Smooth closed-rim dished bowl: a closed rim + radial sections, welded.
+  const bowl = Surface.BoundaryNet()
+    .lengthwise(...radialSections)   // rim -> center, one per around-rim station
+    .closedV()                       // weld the around-rim seam (no kink)
+    .thicken(1.2);
+  ```
+
+  ```js
+  // Match a fender panel to the hood with curvature (G2) continuity.
+  const fender = Surface.BoundaryNet()
+    .lengthwise(sill, belt, crown)
+    .crosswise(nose, aPillar)
+    .matchStartV({ edge: hood.rearEdge, continuity: 2 })
+    .toSheet();
+  ```
+
+  U-sides then V-sides, so clean continuity is guaranteed along edge interiors, not exactly at the four corners (same limitation as `Sheet.matchEdge`).
 
 ### `Blend`
 
-- `Edge(options: BlendEdgeOptions): Shape`
+- `Edge(options: BlendEdgeOptions): Shape` — Fillet one or more edges with constant or variable radius.
+
+  Pass `variableRadius` for a tapered or station-law blend — it overrides the constant `radius`. Variable radius requires `--backend occt`.
+
+  Orientation caveat: for a linear `{ start, end }` taper, `start` maps to the matched edge's first vertex (u=0), whose orientation is not guaranteed to match the named edge's start. If the taper runs the wrong way, pass a `stations` law (explicit `at` positions) or swap `start`/`end`.
+
+  ```js
+  // Constant radius
+  let b = box(40, 20, 10)
+  b = Blend.Edge({ edges: [b.edge('top-front')], radius: 3 })
+  ```
+
+  ```js
+  // Linear taper from 1mm to 5mm along the edge
+  b = Blend.Edge({ edges: [b.edge('top-front')], variableRadius: { start: 1, end: 5 } })
+  ```
+
+  ```js
+  // Station law — bulge in the middle
+  b = Blend.Edge({ edges: [b.edge('top-front')], variableRadius: {
+    stations: [{ at: 0, radius: 1 }, { at: 0.5, radius: 4 }, { at: 1, radius: 1 }] } })
+  ```
 - `Surface(options: BlendSurfaceOptions): Shape`
-- `Bridge(edgeA: SheetEdge, edgeB: SheetEdge): BridgeBuilder` — Build a transition strip between two `Surface.Net` sheet edges. Chain `.bulge(a, b)` then `.g0()/.g1()/.g2()` for the continuity order. Returns a [`Sheet`](/docs/core#sheet); verify the seam with `Analysis.EdgeMatch`.
+- `Bridge(edgeA: SheetEdge, edgeB: SheetEdge): BridgeBuilder` — Build a transition strip between two `Surface.Net` sheet edges. Chain `.bulge(a, b)` then `.g0()/.g1()/.g2()` for the continuity order. Returns a `Sheet`; verify the seam with `Analysis.EdgeMatch`.
+- `Face(options: BlendFaceOptions): Shape` — Fillet every edge SHARED by a pair of faces — a "face fillet". Resolves the shared edges of the two faces and rolls a constant or variable-radius blend along all of them. Requires `--backend occt`.
+
+  ```js
+  let body = box(80, 50, 30).faces({ lid: 'top', wall: 'side-left' })
+  body = Blend.Face({ faces: [body.face('lid'), body.face('wall')], radius: 4 })
+  ```
+
+  ```js
+  // Variable radius along the shared edges
+  body = Blend.Face({ faces: [body.face('lid'), body.face('wall')],
+    variableRadius: { start: 2, end: 6 } })
+  ```
+- `FullRound(options: BlendFullRoundOptions): Shape` — Full round — roll a blend over a narrow center face so it is consumed and its two neighbouring faces meet tangentially (classic 3-face full round). The radius defaults to half the center-face span. Requires `--backend occt`.
+
+  ```js
+  let bar = box(60, 8, 20).faces({ topRail: 'top', left: 'side-left', right: 'side-right' })
+  bar = Blend.FullRound({ centerFace: bar.face('topRail') })
+  ```
+
+  ```js
+  // Explicit neighbours
+  bar = Blend.FullRound({ centerFace: bar.face('topRail'),
+    sideFaces: [bar.face('left'), bar.face('right')] })
+  ```
 
 ### `Analysis`
 
@@ -3880,6 +4714,14 @@ Members (full entries under [Curves & Surfacing](#curves-surfacing)): `Curve.Ble
 - `SurfaceHealth(shape: Shape, options?: { tinyEdgeThreshold?: number; sliverThreshold?: number; }): SurfaceHealthReport`
 - `BRepValidity(shape: Shape, options?: BRepValidityOptions): BRepValidityReport` — Validate B-rep/shell/solid structure and return closedness, manifoldness, orientation, and issue diagnostics.
 
+### `Thickness`
+
+- `constant: (thickness: number) => ThicknessField` — Use the same wall thickness everywhere on the sheet.
+- `alongU: (profile: ThicknessStation[] | ThicknessStationProfile) => ThicknessField` — Vary wall thickness across the sheet U direction.
+- `alongV: (profile: ThicknessStation[] | ThicknessStationProfile) => ThicknessField` — Vary wall thickness across the sheet V direction.
+- `grid: (values: number[][], options?: ThicknessGridOptions) => ThicknessField` — Bilinearly interpolate wall thickness from a rectangular UV grid.
+- `nurbs: (values: number[][], options?: ThicknessNurbsOptions) => ThicknessField` — Interpolate wall thickness from a scalar tensor-product B-spline over sheet UV.
+
 ### `Product`
 
 - `skin(name: string): ProductSkinBuilder` — Start a named product skin builder.
@@ -3998,12 +4840,14 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 
 #### `Sim.body(options: SimBodyOptions): SimBodyDef` — Describe one assembly part as a physical body with mass/density, material, collider intent, and optional contact surfaces.
 
-**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`
+**`SimBodyOptions`**: `massKg?: number`, `densityKgM3?: number`, `material?: SimMaterialDef`, `collider?: SimColliderDef`, `contacts?: Record<string, SimContactDef>`, `motion?: SimMotionDef`
 
-`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string }`
+`SimColliderDef`: `{ kind: "collider", mode: SimColliderMode, reason?: string, sdfResolution?: number }`
 
 `SimContactDef`: `{ kind: "wheelSurface" | "gripperSurface", connectorName: string }`
 
+`SimMotionDef`: `{ kind: "motion", mode: SimMotionMode }`
+
 `SimBodyDef`: `{ kind: "body" }`
 
 #### `Sim.collider` — Collision-geometry intent constructors for physical parts.
@@ -4011,8 +4855,15 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 - `Sim.collider.convexHull(): SimColliderDef` — Use a generated collision mesh for the part. This is the default fast rigid-body collider for irregular parts.
 - `Sim.collider.boundingBox(): SimColliderDef` — Use the part bounding box as the collision geometry. This is fastest and works well for chassis and simple blocks.
 - `Sim.collider.visualMesh(): SimColliderDef` — Use the visual mesh as collision geometry. This is exact but usually slower in physics engines.
+- `Sim.collider.sdfMesh: (options?: { resolution?: number` — Use an SDF mesh collider for complex concave contact geometry. Exporters warn when their target cannot encode it.
 - `Sim.collider.none(reason: string): SimColliderDef` — Disable collision for a part with an explicit reason, such as a sensor-only or decorative object.
 
+#### `Sim.motion` — Body motion-state intent for simulation export. Dynamic is the default when omitted.
+
+- `Sim.motion.dynamic(): SimMotionDef` — Simulate this body as a normal dynamic rigid body with mass and inertia.
+- `Sim.motion.kinematic(): SimMotionDef` — Simulate this body as kinematic: moved by the simulator/user, but not force-integrated.
+- `Sim.motion.static(): SimMotionDef` — Keep this body fixed in the world as a static collision/environment body.
+
 #### `Sim.drive` — Joint-drive intent constructors for passive or powered assembly joints.
 
 - `Sim.drive.passive(options?: SimPassiveDriveOptions): SimDriveDef` — Mark a joint as passive while preserving damping and friction metadata for simulation export.
@@ -4043,6 +4894,57 @@ Assembly-owned links, constraints, connectors, solved poses, and source-level si
 
 `SimDiffDriveControllerDef`: `{ kind: "diffDrive" }`
 
+#### `Fea.material(name: string, options: FeaMaterialOptions): FeaMaterialDef` — Create a named linear-elastic structural material for static stress studies.
+
+#### `Fea.body(options: FeaBodyOptions): FeaBodyDef` — Mark one assembly part as a structural body with a `Fea.material(...)` value.
+
+#### `Fea.region` — Stable explicit region references for solver package manifests.
+
+- `Fea.region.face(partName: string, faceName: string): FeaPartFaceRegionRef` — Reference a named face on a named assembly part without relying on object identity.
+- `Fea.region.plane(partName: string, faceName: string, options: FeaPlaneRegionOptions): FeaPartPlaneRegionRef` — Reference a planar face by a point on the face and its outward normal in part-local coordinates.
+
+`FeaPartFaceRegionRef`: `{ kind: "fea-region-face", partName: string, faceName: string }`
+
+`FeaPlaneRegionOptions`: `{ center: Vec3, normal: Vec3 }`
+
+`FeaPartPlaneRegionRef`: `{ kind: "fea-region-plane", partName: string, faceName: string, center: Vec3, normal: Vec3 }`
+
+#### `Fea.fix` — Fixture constructors over authored face/region references.
+
+- `Fea.fix.fixed(region: FeaRegionRef): FeaFixedFixtureDef` — Fully fix all translational degrees of freedom on a face/region.
+
+`FeaFixedFixtureDef`: `{ kind: "fixed", region: FeaRegionRef }`
+
+#### `Fea.load` — Load constructors over authored face/region references.
+
+- `Fea.load.force(region: FeaRegionRef, options: FeaForceLoadOptions): FeaForceLoadDef` — Apply a force with magnitude in newtons along the given direction vector.
+
+`FeaForceLoadOptions`: `{ newtons: number, direction: Vec3 }`
+
+`FeaForceLoadDef`: `{ kind: "force", region: FeaRegionRef }`
+
+#### `Fea.target` — Study target constructors used by feedback and pass/fail gates.
+
+- `Fea.target.minSafetyFactor(value: number): FeaMinSafetyFactorTargetDef` — Require the solved minimum safety factor to be at least `value`.
+
+`FeaMinSafetyFactorTargetDef`: `{ kind: "minSafetyFactor", value: number }`
+
+#### `Fea.mesh` — Volume mesh intent. V1 structural stress uses second-order tetrahedra only.
+
+- `Fea.mesh.quadraticTets(options: FeaQuadraticTetMeshOptions): FeaQuadraticTetMeshDef` — Request quadratic tetrahedral C3D10 elements with a maximum size in mm.
+
+`FeaQuadraticTetMeshOptions`: `{ maxSizeMm: number, minQuality?: number }`
+
+`FeaQuadraticTetMeshDef`: `{ kind: "quadraticTets", order: 2, element: "C3D10" }`
+
+#### `Fea.study` — Study constructors.
+
+- `Fea.study.staticStress(name: string, options: FeaStaticStressStudyOptions): FeaStaticStressStudyDef` — Create a linear static structural stress study.
+
+`FeaStaticStressStudyOptions`: `{ fixtures: FeaFixtureDef[], loads: FeaLoadDef[], target?: FeaTargetDef, mesh: FeaMeshDef }`
+
+`FeaStaticStressStudyDef`: `{ kind: "staticStress", name: string }`
+
 #### `assembly(name?: string): Assembly` — Create an assembly container with named parts, connectors, and kinematic links.
 
 **Use this from iteration 1 for any model with moving parts.** Do not build one static pose and retrofit motion later.
@@ -4176,7 +5078,7 @@ const housing = group(
 assembly.addPart("Base Assembly", housing);
 ```
 
-**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
+**`PartOptions`**: `transform?: TransformInput`, `metadata?: PartMetadata`, `sim?: SimBodyDef`, `fea?: FeaBodyDef`, `mate?: AssemblyPartMateInput | AssemblyPartMateInput[]`, `bindToFrame?: string`
 
 **`PartMetadata`**
 
@@ -4186,6 +5088,12 @@ assembly.addPart("Base Assembly", housing);
 
 Also: `material?: string`, `process?: string`, `tolerance?: string`, `qty?: number`, `notes?: string`, `densityKgM3?: number`, `massKg?: number`.
 
+`FeaBodyDef`: `{ kind: "fea-body", material: FeaMaterialDef }`
+
+`FeaMaterialOptions`: `{ densityKgM3: number, youngsModulusMPa: number, poissonRatio: number, yieldStrengthMPa: number }`
+
+`FeaMaterialDef`: `{ kind: "fea-material", name: string }`
+
 **`AssemblyPartMateInput`**
 - `connector: string` — Name of a connector declared on the part (via `withConnectors()`).
 - `toLink: string` — Name of the link this connector's origin is pinned to.
@@ -4332,6 +5240,10 @@ Use this after adding physical parts and joints. Robot-body profiles require `ro
 
 `SimAssemblySimulationOptions`: `{ profile: SimProfileDef, rootPart?: string, controllers?: SimControllerDef[] }`
 
+#### `withFeaStudy(study: FeaStudyDef): Assembly` — Attach a structural FEA study to this assembly.
+
+The study is authored with `Fea.study.staticStress(...)` and consumed by `forgecad export fea`. This records load-case intent only; ForgeCAD refuses to invent fixtures, loads, mesh order, or region tags during export.
+
 #### `edgeBetweenFrames(a: string, b: string, options?: AssemblyFrameEdgeOptions): Assembly` — Add a visual skeleton edge between two rig frame origins.
 
 Frame edges follow the solved frame poses produced by `fixedJoint()`, `revoluteJoint()`, and `prismaticJoint()`. They do not add constraints, degrees of freedom, parts, or geometry; use them to make a frame-only rig readable in the Motion/rig inspection overlay.
@@ -4814,3 +5726,238 @@ Check the loop, not just the rest pose:
 3. Render each part with `--focus PartName`; the clevis end must show a visible gap between tines.
 4. Re-check at swept angles (30°/60°/90°) — rotation reveals collisions the rest pose hides.
 5. Backbend test at -10°: blocked = hard stop exists; rotates = add a stop.
+
+---
+
+<!-- guides/structural-fea.md -->
+
+# Structural FEA Stress Inspection
+
+Use structural FEA when you want a ForgeCAD model to answer a load-case question:
+
+- Where does this part see the highest stress?
+- How far does it deflect?
+- What is the minimum safety factor against the material yield strength?
+- Did the mesh and solver produce evidence that is good enough to inspect?
+
+ForgeCAD owns the authoring contract, solver orchestration, result feedback, and inspection report. The numerical solve is done out of process with Gmsh and CalculiX. Users author a study in the model, run `forgecad fea run`, and inspect a result bundle.
+
+## Contents
+
+- What You Get
+- What You Need Installed
+- Author The Study
+- Choose Stable Regions
+- Run The Flow
+- Read The Results
+- Current Scope
+- Troubleshooting
+
+## What You Get
+
+A solved FEA result bundle can produce:
+
+- max von Mises stress
+- max displacement
+- minimum safety factor
+- mesh quality and solver trust flags
+- region-level hot spots
+- `report.html`
+- `summary.json`
+- a safety-factor heatmap PNG
+- a solver stress heatmap PNG
+- a displacement magnitude heatmap PNG
+
+The deformed render is display-only. It helps explain the displacement shape; it does not change the stress, displacement, or safety-factor numbers reported by the solver.
+
+## What You Need Installed
+
+The ForgeCAD CLI creates the package and renders the heatmap. The package runner uses self-contained `uv` Python scripts for Gmsh so every package resolves the same Python dependency set by default.
+
+Run `forgecad doctor` to check these optional FEA tools in a separate section. Missing FEA tools do not block core ForgeCAD modeling, export, or render commands.
+
+| Tool | Used For | Quick Check |
+| --- | --- | --- |
+| `uv` | Runs the packaged Python scripts with pinned dependencies | `uv --version` |
+| CalculiX `ccx` | Solves the static stress deck | `ccx -v` |
+| Bash | Runs the package script | `bash --version` |
+| Chrome or Chromium | Renders PNG heatmaps from solved evidence | Chrome installed in a standard location, `CHROME_PATH=/path/to/chrome`, or `--chrome-path /path/to/chrome` |
+
+If `uv` is not on `PATH`, set `UV=/path/to/uv` when running `forgecad fea run` or `forgecad fea check`.
+
+If `ccx` is not on `PATH`, set `CCX=/path/to/ccx` when running `forgecad fea run` or `forgecad fea check`.
+
+If you need an offline or pre-provisioned Python environment, set `PYTHON=/path/to/python`. That opt-out Python must be able to `import gmsh`; use `GMSH_PYTHONPATH` / `GMSH_PYTHON_PATH` only for that override path.
+
+ForgeCAD does not bundle CalculiX. The generated `uv` scripts pin the Gmsh Python package, and `uv` downloads/caches it from the configured Python package index. If you redistribute solver binaries or Python wheels to customers, handle their licenses as part of your distribution.
+
+## Author The Study
+
+Structural FEA starts in the `.forge.js` file. The script should return an authored `assembly(...)` with:
+
+1. a structural part marked with `Fea.body(...)`
+2. one or more static stress studies from `Fea.study.staticStress(...)`
+3. explicit fixtures and loads
+4. a second-order tetrahedral mesh intent
+
+```js
+const aluminum = Fea.material("6061-T6", {
+  densityKgM3: 2700,
+  youngsModulusMPa: 68900,
+  poissonRatio: 0.33,
+  yieldStrengthMPa: 276,
+});
+
+const beam = box(120, 12, 12);
+
+return assembly("Cantilever Stress Study")
+  .addPart("Beam", beam, {
+    fea: Fea.body({ material: aluminum }),
+  })
+  .withFeaStudy(
+    Fea.study.staticStress("end-load", {
+      fixtures: [
+        Fea.fix.fixed(Fea.region.face("fixed-end", beam.face("left"))),
+      ],
+      loads: [
+        Fea.load.force(Fea.region.face("load-end", beam.face("right")), {
+          newtons: 80,
+          direction: [0, 0, -1],
+        }),
+      ],
+      target: Fea.target.minSafetyFactor(2),
+      mesh: Fea.mesh.quadraticTets({ maxSizeMm: 4 }),
+    }),
+  );
+```
+
+The complete API reference is generated from source in [Assembly](../generated/assembly.md). Keep reusable examples in `.forge.js` files; do not duplicate every API signature in handwritten docs.
+
+## Choose Stable Regions
+
+Fixtures and loads must name real geometric regions. ForgeCAD will not guess them later.
+
+Use `Fea.region.face(...)` when you can refer to a compiler-owned exact face, such as a simple box face or a named face from the model API.
+
+Use `Fea.region.plane(...)` when the target is a planar face created by profiles, booleans, or imported geometry and the face name is not stable enough. Make the plane specific enough that it matches exactly one STEP/Gmsh surface.
+
+During export, ForgeCAD writes a region map and a STEP tag plan. During the package run, the Gmsh preflight matches every authored fixture/load region against the STEP surfaces. Missing or ambiguous matches fail hard. That is intentional: a silent substitute face would make the stress result untrustworthy.
+
+## Run The Flow
+
+Installed users run the CLI as `forgecad`. Developers running inside this repository can replace `forgecad` with `node dist-cli/forgecad.js`.
+
+Run every authored FEA study and save an inspection result bundle:
+
+```bash
+forgecad fea run examples/analysis/structural-stress-fea.forge.js
+```
+
+Run one named study:
+
+```bash
+forgecad fea run bracket.forge.js --study side-load
+```
+
+Open the report:
+
+```bash
+forgecad fea open out/bracket-fea
+```
+
+Render a customer-facing safety view:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field safety
+```
+
+Render the engineering stress heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field stress
+```
+
+Render the displacement magnitude heatmap:
+
+```bash
+forgecad fea render out/bracket-fea/side-load --field displacement
+```
+
+Render a deformed stress view only when the displacement shape is useful to inspect:
+
+```bash
+forgecad fea render out/bracket-fea/side-load \
+  --field stress \
+  --shape deformed \
+  --exaggerate 10
+```
+
+The deformation scale only affects the render. It does not change the reported stress, displacement, or safety factor.
+
+Each solved study result directory includes:
+
+- `report.html` for the human inspection report
+- `summary.json` for automation
+- `renders/safety-factor.png` for the customer-facing safety heatmap
+- `renders/stress.png` for the engineering von Mises stress heatmap
+
+Displacement and deformed-shape PNGs are explicit render outputs from `forgecad fea render --field displacement` or `--shape deformed`.
+
+Compare two solved result bundles:
+
+```bash
+forgecad fea compare out/baseline-fea/side-load out/four-x-fea/side-load
+```
+
+Comparison renders use one shared camera, image size, and safety-factor legend.
+
+Run in CI and fail the process when authored targets fail:
+
+```bash
+forgecad fea check bracket.forge.js --json
+```
+
+## Read The Results
+
+Start with `report.html` or `summary.json` in the result directory. The important fields are the maximum stress, maximum displacement, minimum safety factor, hot spots, and any mesh or solver trust findings.
+
+The default user-facing result is safety factor because it answers "is this part okay?" Use stress when you need the raw engineering von Mises field.
+
+Advanced users can still run the lower-level package flow:
+
+```bash
+forgecad export fea model.forge.js --output out/beam.feapkg
+forgecad sim fea out/beam.feapkg --json
+forgecad inspect structural stress out/beam.feapkg --camera iso --output out/stress.png
+```
+
+Those commands are useful for debugging package evidence. Customer docs should prefer `forgecad fea ...`.
+
+## Current Scope
+
+Structural FEA V1 is intentionally narrow:
+
+- linear static stress only
+- one structural body per package
+- exact OCCT STEP export only
+- second-order tetrahedral elements only
+- fixed fixtures and force loads only
+- no contacts, bonded assemblies, thermal loads, buckling, fatigue, plasticity, or certification workflow
+
+ForgeCAD refuses mesh or faceted fallback for FEA export. If exact geometry export, region mapping, mesh quality, solver convergence, result parsing, or evidence trust fails, the command should fail with an actionable error instead of inventing a weaker path.
+
+## Troubleshooting
+
+| Symptom | What It Means | What To Do |
+| --- | --- | --- |
+| `FEA.TOOLCHAIN_UV_MISSING` | The package runner cannot find `uv`. | Install `uv` or run with `UV=/path/to/uv`. |
+| `FEA.TOOLCHAIN_PYTHON_MISSING` | A `PYTHON=...` override points to a missing Python executable. | Install Python 3 or fix the `PYTHON` path. |
+| `FEA.TOOLCHAIN_GMSH_MISSING` | The selected Python process cannot import Gmsh. | Prefer the default `uv` path, or install the Gmsh Python module for the `PYTHON=...` override. |
+| `FEA.TOOLCHAIN_CCX_MISSING` | CalculiX is not available as `ccx`. | Install CalculiX or run with `CCX=/path/to/ccx`. |
+| `FEA.GMSH_FACE_MATCH_NONE` | An authored fixture/load region did not match a STEP surface. | Use a more stable face reference or a more precise planar region. |
+| `FEA.GMSH_FACE_MATCH_AMBIGUOUS` | A region matched more than one STEP surface. | Make the target region more specific or change the model so the load/fixture face is unique. |
+| `FEA.MESH_QUALITY_BELOW_TARGET` | The mesh exists but did not meet the package quality target. | Reduce mesh size, simplify tiny features, or improve the geometry around the hot area. |
+| `FEA.SOLVER_FAILED` | CalculiX did not complete the solve. | Inspect `solver/static_stress.log`, then check fixtures, loads, material values, and over-constraint. |
+| `FEA.FIELD_UNTRUSTED` | The heatmap input is not trusted package evidence. | Run inspection on the `.feapkg` directory after `forgecad sim fea`, not a copied JSON file. |
+
+For command flags, use the [CLI reference](../CLI.md). For the public API, use the generated [Assembly reference](../generated/assembly.md).