forgecad 0.10.5 → 0.11.0

package/dist-skill/SKILL.md

@@ -23,7 +23,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.
@@ -41,6 +42,7 @@ Execution model, colors, coordinate system, primitives, booleans, patterns, impo
 
 - `{{SKILL_DIR}}/docs/API/core/concepts.md`
 - `{{SKILL_DIR}}/docs/generated/runtime-names.md`
+- `{{SKILL_DIR}}/docs/guides/manual-parameters.md`
 - `{{SKILL_DIR}}/docs/generated/core.md`
 
 ### 2. Static Assembly and Positioning (for any multi-part model)

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

@@ -11,10 +11,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 [
@@ -23,11 +23,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
 

package/dist-skill/docs/CLI.md

@@ -13,8 +13,7 @@ Create projects, open local studios, run, inspect, export, publish, and sync `.f
 # 1. Install
 npm install -g forgecad
 
-# 2. Sign in and create a dedicated project folder
-forgecad login
+# 2. Create a dedicated local project folder
 mkdir spool-adapter
 cd spool-adapter
 forgecad project init "Spool Adapter" --visibility private
@@ -25,14 +24,15 @@ forgecad new adapter --template part
 # 4. Open the local editor
 forgecad studio .
 
-# 5. Validate, export, and push to the browser
+# 5. Validate, export, sign in, and push to the browser
 forgecad run adapter.forge.js
 forgecad export stl adapter.forge.js
+forgecad login
 forgecad project push
 forgecad project open
 ```
 
-Local modeling, inspection, export, and skill-install commands do not require a ForgeCAD account. Hosted project sync, publishing, token management, and license activation require sign-in: run `forgecad login` and choose email/password or API token (for GitHub/Google accounts, create a token in Settings > API Tokens first). Use `FORGECAD_TOKEN=fc_pat_... forgecad <hosted-command>` only for CI/CD and one-off automation. `forgecad studio` always requires an explicit project path; use `.` for the current project.
+Local modeling, project initialization, inspection, export, and skill-install commands do not require a ForgeCAD account. Hosted project sync, publishing, token management, and license activation require sign-in: run `forgecad login` and choose email/password or API token (for GitHub/Google accounts, create a token in Settings > API Tokens first). Use `FORGECAD_TOKEN=fc_pat_... forgecad <hosted-command>` only for CI/CD and one-off automation. `forgecad studio` always requires an explicit project path; use `.` for the current project.
 
 You can also start from the hosted starter project with `forgecad project clone start-here`, then `cd start-here` and `forgecad studio .`.
 
@@ -74,7 +74,7 @@ The fast validation command: runs the script with the real geometry kernel (no b
 
 A bare `forgecad run` skips expensive diagnostics. Opt in with `--details` (volumes/bounds), `--history` (construction tree), `--features` (feature tallies), `--solver-profile` (constraint solver timing), or `--connectivity` (physical connected components — bbox contact is evidence, exact geometry is checked by default). `--quality live|default|high` selects the same geometry quality profile as the editor and export tools; `live` is fastest for large models.
 
-Direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` inputs are imported automatically; STEP/STP auto-selects OCCT unless you pass `--backend`. For deeper confidence gates, prefer `inspect mechanical-integrity`, `check print`, or `inspect fit interference` instead of turning `run` into a catch-all audit command.
+Direct `.stl`/`.obj`/`.3mf`/`.step`/`.stp` inputs are imported automatically; STEP/STP auto-selects OCCT unless you pass `--backend`. Use `--project-root <dir>` when running a file inside a larger uninitialized folder and you intentionally want relative imports to resolve against that root. For deeper confidence gates, prefer `inspect mechanical-integrity`, `check print`, or `inspect fit interference` instead of turning `run` into a catch-all audit command.
 
 ```bash
 forgecad run model.forge.js
@@ -358,16 +358,16 @@ Script-backed exports accept repeatable `--param Key=Value` overrides before the
 
 ForgeCAD has a hosted platform at [forgecad.io](https://forgecad.io). The CLI connects a dedicated local project folder to it.
 
-A project is a local folder linked to the hosted app by `forgecad.json`. Use `forgecad project clone <slug>` to download an existing hosted project into a local folder, or run `forgecad project init` inside a folder that should become a new ForgeCAD project. Open local projects with `forgecad studio <project-path>`.
+A project is a local folder marked by `forgecad.json`; after the first push, that same file also links it to the hosted app. Use `forgecad project clone <slug>` to download an existing hosted project into a local folder, or run `forgecad project init` inside a folder that should become a new ForgeCAD project. Open local projects with `forgecad studio <project-path>`.
 
 Keep the project root small and intentional. Do not run the editor from `~`, downloads, desktop, or a huge source tree. ForgeCAD scans project files such as `.forge.js`, `.js`, `.svg`, and `.dxf`; broad roots make local workflows and AI-agent context slow and confusing.
 
-First-time setup (login, init, studio) is the [Quick Start](#quick-start) sequence above. `forgecad project init` creates the remote project, writes `forgecad.json`, pushes any existing local source files, and records server file IDs. `forgecad project push` syncs an already initialized project; it does not create a remote project from an arbitrary folder.
+First-time setup (init, studio, login, push) is the [Quick Start](#quick-start) sequence above. `forgecad project init` writes a local `forgecad.json` with the project name, slug, server, and visibility. It does not contact the server. The first `forgecad project push` creates the hosted project if `forgecad.json` has no project ID yet, uploads local source files, and records server file IDs. Later pushes sync the already linked hosted project. `forgecad project push` still requires `forgecad.json`; it does not initialize a random folder.
 
 ### Sync
 
 ```bash
-forgecad project push          # Upload local changes
+forgecad project push          # Create hosted project if needed; upload changes
 forgecad project pull          # Download remote changes
 forgecad project status        # See what's different
 ```
@@ -395,10 +395,10 @@ Shares are live references — always the current version, not a snapshot.
 
 | Command | Description |
 |---------|-------------|
-| `project init` | Initialize the current directory as a ForgeCAD project and create it on the server. |
+| `project init` | Initialize the current directory as a local ForgeCAD project. |
 | `project clone` | Download a remote project into a new local directory. |
 | `project pull` | Download remote changes into the current project. |
-| `project push` | Upload local changes to the remote project. |
+| `project push` | Create the hosted project if needed, then upload local changes. |
 | `project status` | Show differences between local and remote project files. |
 | `project list` | List your remote projects. |
 | `project open` | Open the current project in the browser. |

package/dist-skill/docs/generated/core.md

@@ -24,6 +24,9 @@ skill-order: 100
 - [SurfacePattern](#surfacepattern)
 - [Pattern2D](#pattern2d)
 - [Pattern2DBuilder](#pattern2dbuilder)
+- [Path2DParamValue](#path2dparamvalue)
+- [Spline2DParamValue](#spline2dparamvalue)
+- [Placement2DParamValue](#placement2dparamvalue)
 - [CurveNetBuilder](#curvenetbuilder)
 - [MatchEdgeBuilder](#matchedgebuilder)
 - [BridgeBuilder](#bridgebuilder)
@@ -352,11 +355,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**
 
@@ -369,52 +372,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:
 
@@ -422,16 +429,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.
+
+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.
 
-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.
+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:
 
@@ -447,38 +468,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);
@@ -486,29 +503,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
@@ -527,6 +532,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.
@@ -1204,7 +1293,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
 
@@ -1444,6 +1533,99 @@ 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. |
 
+### `Path2DParamValue`
+
+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 |
+|----------|------|-------------|
+| `closed` | `boolean` | True when this path is intended to close back to its first point. |
+
+**Methods:**
+
+#### `points(): Vec2[]` — Return the current points as `[x, y]` pairs in the editor coordinate system.
+
+#### `toSketch(): Sketch` — Convert a closed editable path into a sketch profile.
+
+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.
@@ -1515,6 +1697,7 @@ Pass `{ edge }` to match an adjacent sheet's tangent (G1) or curvature (G2), or
 - `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`**

package/dist-skill/docs/generated/curves.md

@@ -39,6 +39,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)
@@ -648,6 +649,10 @@ Use this when the guide path runs in the surface V direction and the sketch prof
 
 #### `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`
@@ -1523,6 +1528,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.

package/dist-skill/docs/generated/runtime-names.md

@@ -28,8 +28,8 @@ 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
+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.

package/dist-skill/docs/guides/inspection-bundles.md

@@ -5,7 +5,7 @@ skill-order: 2
 
 # Inspection Bundles — Evidence Contract
 
-`forgecad inspect <family> <mode>` writes a deterministic bundle: evidence PNGs under `evidence/<type>/` plus a root `manifest.json`. **The manifest is the authoritative contract** — take file paths, encodings, per-view ranges, thresholds, tolerances, and identity maps from it; never hard-code bundle layout or infer object identity from object order. The PNGs are a visual index for locating findings, not standalone artifacts. Command tree, flags, and `--focus`/`--hide` filtering live in `docs/skill/CLI.md` and `forgecad inspect evidence`; the inspection workflow lives in the `forgecad-inspect-model` skill. Model-authored `scene()` background, lights, fog, and exposure are ignored for inspection captures so evidence stays stable; named scene views remain available via `--view`.
+`forgecad inspect <family> <mode>` writes a deterministic bundle: evidence PNGs under `evidence/<type>/` plus a root `manifest.json`. **The manifest is the authoritative contract** — take file paths, encodings, per-view ranges, thresholds, tolerances, and identity maps from it; never hard-code bundle layout or infer object identity from object order. The PNGs are a visual index for locating findings, not standalone artifacts. Command tree, flags, and `--focus`/`--hide` filtering live in `docs/skill/CLI.md` and `forgecad inspect evidence`; the model-building inspection workflow lives in `forgecad-build-model/references/inspection-feedback.md`. Model-authored `scene()` background, lights, fog, and exposure are ignored for inspection captures so evidence stays stable; named scene views remain available via `--view`.
 
 Manifest evidence keys are evidence-oriented and stable for bundle readers: e.g. `fit interference` writes `manifest.evidence.collisions`, `physical components` writes `manifest.evidence.connectivity`.