forgecad 0.10.4 → 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)
@@ -107,6 +109,7 @@ Test-run, export pipelines, debug flags.
 
 - `{{SKILL_DIR}}/docs/CLI.md`
 - `{{SKILL_DIR}}/docs/guides/inspection-bundles.md`
+- `{{SKILL_DIR}}/docs/guides/structural-fea.md`
 
 ### SDF Modeling (smooth booleans, TPMS, deformations, fromFunction)
 

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
@@ -136,7 +136,8 @@ Inspect a model by asking for one explicit kind of evidence.
 - `inspect surface zebra|roughness` — surface continuity and roughness evidence
 - `inspect physical components|floating|gaps` — physical component graph evidence
 - `inspect fit interference` — positive-volume overlap evidence
-- `inspect manufacture thickness` — wall-thickness evidence
+- `inspect manufacture thickness|through-thickness` — wall-thickness and minimum solid span evidence
+- `inspect structural stress` — solver-produced structural stress scalar-field evidence
 - `inspect compare overlay` — candidate-vs-reference visual mismatch evidence
 - `inspect sections at|stack|sample` — exact section evidence for precise cuts, dense scans, or sparse samples
 - `inspect mechanical-integrity` — model-focused integrity audit for generated assemblies
@@ -292,6 +293,7 @@ Export to every format you need.
 | `export svg` | SVG | 2D vector output from sketches |
 | `export sketch-pdf` **\[Production\]** | PDF | Sketch with dimensions and constraints |
 | `export step` **\[Production\]** | STEP | CAD interchange (exact geometry) |
+| `export fea` **\[Production\]** | FEA package | Exact STEP plus authored structural load-case metadata |
 | `export brep` **\[Production\]** | BREP | Boundary representation |
 | `export 3mf` | 3MF | 3D printing (color, multi-part) |
 | `export stl` | STL | 3D printing |
@@ -356,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
 ```
@@ -393,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. |
@@ -543,7 +545,7 @@ The CLI is free for personal non-commercial use. Pro covers human-operated comme
 
 | Free | Production outputs | Pro | Enterprise |
 |------|--------------------|-----|------------|
-| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `compare 3d`, `check print`, `inspect fit interference`, `inspect mechanical-integrity` for personal non-commercial use | `cut-list`, `export sketch-pdf`, `export step`, `export brep`, `export gcode`, `export implicit`, `export sdf`, `export mjcf`, `export urdf`, `export usd`, `export report`, `export cutting-layout` are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work | `render hq`, `capture gif`, `capture mp4` plus commercial coverage for client/customer work | Backend, hosted, embedded, or application workflows that call ForgeCAD automatically |
+| `run`, `dev`, `studio`, `render 3d`, `export stl`, `export 3mf`, `export svg`, `compare 3d`, `check print`, `inspect fit interference`, `inspect mechanical-integrity` for personal non-commercial use | `cut-list`, `export sketch-pdf`, `export step`, `export fea`, `export brep`, `export gcode`, `export implicit`, `export sdf`, `export mjcf`, `export urdf`, `export usd`, `export report`, `export cutting-layout` are free to run for personal non-commercial use; Pro covers human-operated commercial CAD work | `render hq`, `capture gif`, `capture mp4` plus commercial coverage for client/customer work | Backend, hosted, embedded, or application workflows that call ForgeCAD automatically |
 
 ```bash
 forgecad license                    # Check local license status

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

@@ -26,12 +26,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.
@@ -39,8 +41,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.
@@ -71,6 +80,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.
@@ -204,7 +264,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`**
 
@@ -214,6 +274,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.
@@ -360,6 +426,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.