forgecad 0.10.4 → 0.11.0

package/dist-skill/docs/guides/manual-parameters.md

@@ -0,0 +1,130 @@
+---
+skill-group: core
+skill-order: 6
+---
+
+# 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.

package/dist-skill/docs/guides/structural-fea.md

@@ -0,0 +1,235 @@
+---
+skill-group: cli
+skill-order: 3
+---
+
+# 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).

package/dist-skill/library/README.md

@@ -9,11 +9,7 @@ forgecad skill install
 The installed skill names are namespaced to avoid collisions with a user's existing generic skills.
 
 - `forgecad-build-model`
-- `forgecad-design-spec`
-- `forgecad-grade-model`
 - `forgecad-image-prompt`
-- `forgecad-inspect-model`
 - `forgecad-project-sync`
 - `forgecad-reconstruct-cad-file`
 - `forgecad-reconstruct-from-images`
-- `forgecad-verify-mujoco`