forgecad 0.10.2 → 0.10.4

package/dist-skill/library/forgecad-verify-mujoco/scripts/mujoco_verify.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+"""Verify a ForgeCAD MJCF package by running MuJoCo dynamics and rendering frames."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+from collections import Counter
+from pathlib import Path
+from typing import Iterable
+
+
+def parse_actuator(value: str) -> tuple[str, float]:
+    if "=" not in value:
+        raise argparse.ArgumentTypeError("expected NAME=VALUE")
+    name, raw = value.split("=", 1)
+    name = name.strip()
+    if not name:
+        raise argparse.ArgumentTypeError("actuator name is empty")
+    try:
+        ctrl = float(raw)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid actuator value {raw!r}") from exc
+    return name, ctrl
+
+
+def parse_joint_range(value: str) -> tuple[str, float, float]:
+    if "=" not in value:
+        raise argparse.ArgumentTypeError("expected JOINT=MIN:MAX")
+    name, raw_range = value.split("=", 1)
+    name = name.strip()
+    if not name:
+        raise argparse.ArgumentTypeError("joint name is empty")
+    if ":" not in raw_range:
+        raise argparse.ArgumentTypeError("expected range as MIN:MAX")
+    raw_min, raw_max = raw_range.split(":", 1)
+    try:
+        min_value = float(raw_min)
+        max_value = float(raw_max)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(f"invalid numeric range {raw_range!r}") from exc
+    if min_value > max_value:
+        raise argparse.ArgumentTypeError(f"range minimum {min_value} is greater than maximum {max_value}")
+    return name, min_value, max_value
+
+
+def cycles_from_radians(value: float) -> float:
+    return value / math.tau
+
+
+def resolve_scene(path: Path) -> Path:
+    if path.is_file():
+        return path
+    scene = path / "scene.xml"
+    if scene.is_file():
+        return scene
+    raise SystemExit(f"Could not find scene.xml at {path}")
+
+
+def geom_name(mujoco, model, geom_id: int) -> str:
+    return mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_GEOM, geom_id) or f"geom#{geom_id}"
+
+
+def joint_name(mujoco, model, joint_id: int) -> str:
+    return mujoco.mj_id2name(model, mujoco.mjtObj.mjOBJ_JOINT, joint_id) or f"joint#{joint_id}"
+
+
+def contact_counts(mujoco, model, data, limit: int) -> list[dict[str, object]]:
+    counts: Counter[tuple[str, str]] = Counter()
+    for i in range(data.ncon):
+        contact = data.contact[i]
+        a = geom_name(mujoco, model, int(contact.geom1))
+        b = geom_name(mujoco, model, int(contact.geom2))
+        if a > b:
+            a, b = b, a
+        counts[(a, b)] += 1
+    return [{"geom1": a, "geom2": b, "count": count} for (a, b), count in counts.most_common(limit)]
+
+
+def qpos_for_joint(model, joint_id: int) -> float:
+    return float(model.jnt_qposadr[joint_id])
+
+
+def first_freejoint(mujoco, model) -> int | None:
+    for joint_id in range(model.njnt):
+        if model.jnt_type[joint_id] == mujoco.mjtJoint.mjJNT_FREE:
+            return joint_id
+    return None
+
+
+def make_camera(mujoco, lookat: Iterable[float], distance: float, azimuth: float, elevation: float):
+    camera = mujoco.MjvCamera()
+    camera.type = mujoco.mjtCamera.mjCAMERA_FREE
+    camera.lookat[:] = list(lookat)
+    camera.distance = distance
+    camera.azimuth = azimuth
+    camera.elevation = elevation
+    return camera
+
+
+def render_frame(mujoco, renderer, model, data, camera, label: str, path: Path) -> None:
+    from PIL import Image, ImageDraw
+
+    mujoco.mj_forward(model, data)
+    renderer.update_scene(data, camera=camera)
+    image = Image.fromarray(renderer.render())
+    draw = ImageDraw.Draw(image)
+    draw.rectangle((12, 12, min(image.width - 12, 1120), 72), fill=(255, 255, 255))
+    draw.text((22, 22), label, fill=(0, 0, 0))
+    path.parent.mkdir(parents=True, exist_ok=True)
+    image.save(path)
+
+
+def render_camera_preview_grid(mujoco, renderer, model, data, args, path: Path) -> str:
+    from PIL import Image, ImageDraw
+
+    images = []
+    for azimuth in args.camera_preview_azimuths:
+        camera = make_camera(mujoco, args.camera_lookat, args.camera_distance, azimuth, args.camera_elevation)
+        mujoco.mj_forward(model, data)
+        renderer.update_scene(data, camera=camera)
+        image = Image.fromarray(renderer.render())
+        draw = ImageDraw.Draw(image)
+        label = f"azimuth {azimuth:g}"
+        draw.rectangle((12, 12, min(image.width - 12, 260), 52), fill=(255, 255, 255))
+        draw.text((22, 22), label, fill=(0, 0, 0))
+        images.append(image)
+
+    if not images:
+        return ""
+
+    cols = min(3, len(images))
+    rows = int(math.ceil(len(images) / cols))
+    width, height = images[0].size
+    canvas = Image.new("RGB", (cols * width, rows * height), (255, 255, 255))
+    for index, image in enumerate(images):
+        canvas.paste(image, ((index % cols) * width, (index // cols) * height))
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    canvas.save(path)
+    return str(path)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("package_or_scene", type=Path, help="MJCF package directory or scene.xml path")
+    parser.add_argument("--settle-seconds", type=float, default=2.0)
+    parser.add_argument("--seconds", type=float, default=6.0)
+    parser.add_argument("--actuator", action="append", type=parse_actuator, default=[], help="Control as NAME=VALUE")
+    parser.add_argument("--watch-joint", action="append", default=[], help="Joint name whose motion should be reported")
+    parser.add_argument("--assert-min-joint-delta", type=float, default=0.0)
+    parser.add_argument(
+        "--expect-drive-delta",
+        action="append",
+        type=parse_joint_range,
+        default=[],
+        help="Require signed post-settle joint delta as JOINT=MIN:MAX in MuJoCo qpos units",
+    )
+    parser.add_argument(
+        "--expect-drive-cycles",
+        action="append",
+        type=parse_joint_range,
+        default=[],
+        help="Require signed post-settle revolute joint travel as JOINT=MIN:MAX in cycles/turns",
+    )
+    parser.add_argument(
+        "--expect-final-qvel",
+        action="append",
+        type=parse_joint_range,
+        default=[],
+        help="Require final joint velocity as JOINT=MIN:MAX in MuJoCo qvel units",
+    )
+    parser.add_argument("--max-root-drop", type=float, default=0.02, help="Maximum allowed root Z drop in meters for free-root models")
+    parser.add_argument("--contact-top-n", type=int, default=12)
+    parser.add_argument("--render-dir", type=Path)
+    parser.add_argument("--fps", type=float, default=6.0)
+    parser.add_argument("--camera-lookat", nargs=3, type=float, default=[0.0, 0.0, 0.0])
+    parser.add_argument("--camera-distance", type=float, default=0.35)
+    parser.add_argument("--camera-azimuth", type=float, default=-45.0)
+    parser.add_argument("--camera-elevation", type=float, default=-20.0)
+    parser.add_argument(
+        "--camera-preview-grid",
+        action="store_true",
+        help="Write a labeled azimuth grid to render-dir/camera_preview_grid.png before choosing/reporting a view",
+    )
+    parser.add_argument(
+        "--camera-preview-azimuths",
+        nargs="+",
+        type=float,
+        default=[-90, 0, 45, 90, 135, 180],
+        help="Azimuths in degrees to include in --camera-preview-grid",
+    )
+    args = parser.parse_args()
+    if args.camera_preview_grid and not args.render_dir:
+        parser.error("--camera-preview-grid requires --render-dir")
+
+    import mujoco
+
+    scene_path = resolve_scene(args.package_or_scene)
+    model = mujoco.MjModel.from_xml_path(str(scene_path))
+    data = mujoco.MjData(model)
+
+    actuator_ids: list[tuple[str, int, float]] = []
+    for name, ctrl in args.actuator:
+        actuator_id = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_ACTUATOR, name)
+        if actuator_id < 0:
+            raise SystemExit(f"Unknown actuator {name!r}")
+        actuator_ids.append((name, actuator_id, ctrl))
+
+    watch_names = list(dict.fromkeys(
+        args.watch_joint
+        + [name for name, _min_value, _max_value in args.expect_drive_delta]
+        + [name for name, _min_value, _max_value in args.expect_drive_cycles]
+        + [name for name, _min_value, _max_value in args.expect_final_qvel]
+    ))
+    watch_joints: list[tuple[str, int, int, int]] = []
+    for name in watch_names:
+        joint_id = mujoco.mj_name2id(model, mujoco.mjtObj.mjOBJ_JOINT, name)
+        if joint_id < 0:
+            raise SystemExit(f"Unknown joint {name!r}")
+        watch_joints.append((name, joint_id, int(model.jnt_qposadr[joint_id]), int(model.jnt_dofadr[joint_id])))
+
+    free_joint_id = first_freejoint(mujoco, model)
+    free_qadr = int(model.jnt_qposadr[free_joint_id]) if free_joint_id is not None else None
+
+    renderer = None
+    camera = None
+    if args.render_dir:
+        renderer = mujoco.Renderer(model, height=900, width=1200)
+        camera = make_camera(mujoco, args.camera_lookat, args.camera_distance, args.camera_azimuth, args.camera_elevation)
+
+    def snapshot(label: str) -> dict[str, object]:
+        root_pos = None
+        if free_qadr is not None:
+            root_pos = [float(x) for x in data.qpos[free_qadr : free_qadr + 3]]
+        return {
+            "label": label,
+            "time": float(data.time),
+            "root_pos": root_pos,
+            "watched": {
+                name: {"qpos": float(data.qpos[qadr]), "qvel": float(data.qvel[dadr])}
+                for name, _joint_id, qadr, dadr in watch_joints
+            },
+            "ncon": int(data.ncon),
+            "contacts": contact_counts(mujoco, model, data, args.contact_top_n),
+        }
+
+    mujoco.mj_forward(model, data)
+    initial = snapshot("initial")
+    initial_joint_qpos = {name: float(data.qpos[qadr]) for name, _joint_id, qadr, _dadr in watch_joints}
+    initial_root_z = float(data.qpos[free_qadr + 2]) if free_qadr is not None else None
+    if renderer and camera:
+        camera_preview_grid = None
+        if args.camera_preview_grid:
+            camera_preview_grid = render_camera_preview_grid(
+                mujoco,
+                renderer,
+                model,
+                data,
+                args,
+                args.render_dir / "camera_preview_grid.png",
+            )
+        render_frame(mujoco, renderer, model, data, camera, "initial", args.render_dir / "00_initial.png")
+    else:
+        camera_preview_grid = None
+
+    settle_steps = max(0, int(round(args.settle_seconds / model.opt.timestep)))
+    for _ in range(settle_steps):
+        mujoco.mj_step(model, data)
+    settled = snapshot("settled")
+    settled_joint_qpos = {name: float(data.qpos[qadr]) for name, _joint_id, qadr, _dadr in watch_joints}
+    if renderer and camera:
+        render_frame(mujoco, renderer, model, data, camera, "settled", args.render_dir / "01_settled.png")
+
+    total_steps = max(0, int(round(args.seconds / model.opt.timestep)))
+    frame_interval = max(1, int(round((1.0 / max(args.fps, 1e-9)) / model.opt.timestep)))
+    rendered = []
+    for step in range(total_steps):
+        for _name, actuator_id, ctrl in actuator_ids:
+            data.ctrl[actuator_id] = ctrl
+        mujoco.mj_step(model, data)
+        if renderer and camera and step % frame_interval == 0:
+            frame_path = args.render_dir / f"drive_{step:06d}.png"
+            render_frame(mujoco, renderer, model, data, camera, f"drive t={data.time:.2f}s", frame_path)
+            rendered.append(str(frame_path))
+
+    final = snapshot("final")
+    if renderer and camera:
+        render_frame(mujoco, renderer, model, data, camera, "final", args.render_dir / "99_final.png")
+        renderer.close()
+
+    joint_delta = {
+        name: float(data.qpos[qadr]) - initial_joint_qpos[name]
+        for name, _joint_id, qadr, _dadr in watch_joints
+    }
+    joint_drive_delta = {
+        name: float(data.qpos[qadr]) - settled_joint_qpos[name]
+        for name, _joint_id, qadr, _dadr in watch_joints
+    }
+    joint_cycles = {name: cycles_from_radians(value) for name, value in joint_delta.items()}
+    joint_drive_cycles = {name: cycles_from_radians(value) for name, value in joint_drive_delta.items()}
+    final_joint_qvel = {
+        name: float(data.qvel[dadr])
+        for name, _joint_id, _qadr, dadr in watch_joints
+    }
+    root_drop = None
+    if free_qadr is not None and initial_root_z is not None:
+        root_drop = initial_root_z - float(data.qpos[free_qadr + 2])
+
+    summary = {
+        "scene": str(scene_path),
+        "counts": {"nbody": int(model.nbody), "njnt": int(model.njnt), "nu": int(model.nu), "ngeom": int(model.ngeom)},
+        "free_joint": joint_name(mujoco, model, free_joint_id) if free_joint_id is not None else None,
+        "actuators": [{"name": name, "ctrl": ctrl} for name, _actuator_id, ctrl in actuator_ids],
+        "joint_delta": joint_delta,
+        "joint_drive_delta": joint_drive_delta,
+        "joint_cycles": joint_cycles,
+        "joint_drive_cycles": joint_drive_cycles,
+        "final_joint_qvel": final_joint_qvel,
+        "expectations": {
+            "drive_delta": [
+                {"joint": name, "min": min_value, "max": max_value}
+                for name, min_value, max_value in args.expect_drive_delta
+            ],
+            "drive_cycles": [
+                {"joint": name, "min": min_value, "max": max_value}
+                for name, min_value, max_value in args.expect_drive_cycles
+            ],
+            "final_qvel": [
+                {"joint": name, "min": min_value, "max": max_value}
+                for name, min_value, max_value in args.expect_final_qvel
+            ],
+        },
+        "root_drop_m": root_drop,
+        "camera": {
+            "lookat": args.camera_lookat,
+            "distance": args.camera_distance,
+            "azimuth": args.camera_azimuth,
+            "elevation": args.camera_elevation,
+            "preview_grid": camera_preview_grid,
+        },
+        "snapshots": [initial, settled, final],
+        "render_dir": str(args.render_dir) if args.render_dir else None,
+        "rendered_frames": rendered[:5] + (["..."] if len(rendered) > 5 else []),
+    }
+    print(json.dumps(summary, indent=2))
+
+    failures = []
+    if root_drop is not None and root_drop > args.max_root_drop:
+        failures.append(f"root dropped {root_drop:.6f}m > {args.max_root_drop:.6f}m")
+    if args.assert_min_joint_delta > 0:
+        max_delta = max((abs(value) for value in joint_delta.values()), default=0.0)
+        if max_delta < args.assert_min_joint_delta:
+            failures.append(f"watched joints moved only {max_delta:.6f}; expected {args.assert_min_joint_delta:.6f}")
+    for name, min_value, max_value in args.expect_drive_delta:
+        value = joint_drive_delta[name]
+        if not min_value <= value <= max_value:
+            failures.append(
+                f"{name} drive delta {value:.6f} outside expected range [{min_value:.6f}, {max_value:.6f}]"
+            )
+    for name, min_value, max_value in args.expect_drive_cycles:
+        value = joint_drive_cycles[name]
+        if not min_value <= value <= max_value:
+            failures.append(
+                f"{name} drive cycles {value:.6f} outside expected range [{min_value:.6f}, {max_value:.6f}]"
+            )
+    for name, min_value, max_value in args.expect_final_qvel:
+        value = final_joint_qvel[name]
+        if not min_value <= value <= max_value:
+            failures.append(
+                f"{name} final qvel {value:.6f} outside expected range [{min_value:.6f}, {max_value:.6f}]"
+            )
+    if any(math.isnan(value) or math.isinf(value) for value in data.qpos):
+        failures.append("qpos contains NaN or Inf")
+
+    if failures:
+        for failure in failures:
+            print(f"FAIL: {failure}")
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/{dist/docs-raw/skills/forgecad-make-a-model.md → dist-skill/website/skills/forgecad-build-model.md}

@@ -1,17 +1,17 @@
-<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-make-a-model/SKILL.md instead. -->
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-build-model/SKILL.md instead. -->
 
-# forgecad-make-a-model
+# forgecad-build-model
 
-Create manufacture-realistic prototype ForgeCAD (.forge.js) models in the active CAD project. Handles file placement, invokes the forgecad skill for API guidance, and validates the result.
+Build or edit a manufacture-realistic `.forge.js` model in a project, then validate it with run, render, inspect, and export evidence.
 
 | Field | Value |
 | --- | --- |
 | Installed by | `forgecad skill install` |
-| Source | `agent-skill-library/forgecad-make-a-model/SKILL.md` |
+| Source | `agent-skill-library/forgecad-build-model/SKILL.md` |
 
 ---
 
-## Make a Model
+## Build Model
 
 Create new ForgeCAD models in the user's active ForgeCAD project.
 
@@ -86,7 +86,17 @@ For any mechanism (linkage, hinge, slider, suspension, gripper, drawer), the rig
 
 A mechanical script is not done when it merely looks assembled. Every visible piece needs a physical reason to be where it is: fused material, contact faces, a screw stack, a pin in a bore, a tab in a slot, a gasket on a land, a bearing in a seat, a cable in a channel, or a named intentional ghost.
 
-- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`. Final `translate()` calls are not assembly contracts.
+For multi-part assemblies, the component model is mandatory:
+
+- Parts build at origin in their own local coordinates. They do not know final assembly-space offsets, sibling dimensions, or world placement.
+- A part's public interface is `shape` plus connectors and metadata, e.g. `return { shape, boltPattern, pinionZ }`. Declare mating faces with `.withConnectors({})`; axes point outward, with prismatic slide axes as the explicit exception.
+- The parent assembly chooses the root and positions every structural part through connectors, `connect()`, `match()`, or `matchTo()`. Final `translate()` calls are not assembly contracts.
+- Data flows down through `require('./part.forge.js', params)` overrides and up through returned metadata. Siblings never import each other; the parent routes shared decisions and measured outputs.
+- Default to one file for a project-specific assembly. Split only for cross-project reuse, independent subassemblies, or when a file grows past roughly 300 lines. Never create `shared-dims.js` just to coordinate siblings.
+
+Reject these shortcuts on sight: sibling `require()`, assembly-space coordinates inside a part, `translate()` used to position a structural assembly member, `console.log` + `if` validation instead of `verify.*`, and bare `connector.neutral()` outside a reusable component library with compatibility checks.
+
+- Bespoke fixed assemblies: build each part in local coordinates, pick one root, place every touching part with `matchTo()`, verify each mate with `verify.connectorDistance`.
 - Manual joint frames (`addFixed`/`addRevolute`/`addPrismatic` with a hand-built `frame:`) are scaffolding, not contracts. Before delivery, convert mating interfaces to connectors with `connect()`/`match()`, or prove the manual joint with `forgecad debug assembly --fail-on warning` and documented geometry.
 - A named part must not contain unintentional disconnected bodies: boolean-join manufactured features, model fasteners/seals as separate named parts, or add the receiving holes/lands that explain the separation.
 - Screws are not decoration: clearance/counterbore in the cover, receiving boss or through stack in the parent, material around both, axes aligned from one shared bolt pattern.
@@ -101,7 +111,7 @@ Treat `fillet()`/`chamfer()` as experimental (Manifold can be incorrect, OCCT sl
 
 ### Imported Parts (User-Supplied 3D Files)
 
-When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-3d-reconstruction`, a different request).
+When the user supplies mesh or CAD files to design around (a motor, an off-the-shelf housing, a scanned part), the import IS a component of the assembly — keep it, don't rebuild it parametrically (rebuilding is `forgecad-reconstruct-cad-file`, a different request).
 
 - Wrap each import in its own part file: `Import.mesh()` for STL/OBJ/3MF, `Import.step()` for STEP (OCCT backend), normalize scale and orientation, recenter to a sane local origin, then treat it exactly like a purchased part — connectors at its real mating features, positioned by the assembly via `matchTo()`.
 - Never trust units. Verify against a known dimension before mating anything: bbox via `forgecad run --details`, or `inspect section --ray` across a bore or face pair. For 3MF, account for every build item printed by `forgecad run` before flattening.
@@ -153,7 +163,7 @@ A manufacture-realistic model must yield a package a shop can consume, not just
 
 ### Render and Inspect Cadence
 
-**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-render-inspect` skill and the CLI docs — this skill fixes only the cadence and the gates.
+**You are building blind unless you render.** `forgecad run` passing only means the code didn't crash — it cannot tell you a hole is misplaced, a rib pokes through a cover, or a part doesn't fit. Render from angles chosen for the model's actual geometry and read every PNG. For command syntax, evidence selection, and manifest reading, use the `forgecad-inspect-model` skill and the CLI docs — this skill fixes only the cadence and the gates.
 
 Render after every feature addition, boolean cut, symmetric copy placement, and the last feature. Inspect after adding hidden geometry a surface render cannot prove, after adding or moving mating parts, ghosts, connectors, thin walls, or screw holes, and before delivery with thresholds set for the material/process.
 

package/dist-skill/website/skills/forgecad-design-spec.md

@@ -0,0 +1,145 @@
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-design-spec/SKILL.md instead. -->
+
+# forgecad-design-spec
+
+Create a ForgeCAD design brief, HLD, or LLD before coding by walking through use, assembly, interfaces, decisions, and verification.
+
+| Field | Value |
+| --- | --- |
+| Installed by | `forgecad skill install` |
+| Source | `agent-skill-library/forgecad-design-spec/SKILL.md` |
+
+---
+
+## Design Spec
+
+The design document — a git-committed, diff-reviewed markdown file — is the source of truth. Not the code, not the chat, not your head. You iterate it by commit-and-review, and the `git diff` is the review artifact.
+
+**Validate the design by mentally operating the thing, step by step.** Walk it as someone assembles, uses, or moves it. The step with no answer — *"how does the servo get inside the housing?"* — is the real design gap. A spec that reads complete on the page can still hide a hole that only surfaces when you try to put it together in your head. State each gap falsifiably: not "tolerances might be tight" but "the 12mm arm cantilevers under gripping load, may flex >0.5mm."
+
+**Every number has a reason; the narrative comes before the numbers.** Describe the object as if over the phone, then derive each value and show its math: `wallThickness = 2.4mm = 6 × 0.4mm nozzle`. The design is **implementation-blind** — shaped by the object, never by what the ForgeCAD API makes easy. **Manufacturing process is one of those reasons** — a design decision you weigh, never a default you inherit (never assume FDM/printing).
+
+**A vague request is a set of decisions you make honestly, not information to extract.** No placeholders ("appropriate motor"); choose a defensible value, show why, continue. The Decisions table fills only after user review, so the loop stays in the document.
+
+### Altitude — three phases, one document trail
+
+| Phase | When | Output |
+|-------|------|--------|
+| Intake | request is fuzzy / process unspecified | engineering brief + master prompt |
+| HLD | design is wrong in *approach*, alternatives exist | `<name>-hld.md` |
+| LLD | decisions locked, or a simple single-body part | `<name>-lld.md` |
+
+The HLD carries only decision-driving dimensions and genuinely-different alternatives; the LLD carries enough that someone builds from it alone. Speccing every tolerance in an HLD, or revisiting locked decisions in an LLD, is an altitude error — back up. Simple parts skip straight from HLD to code, or from a request to an LLD.
+
+---
+
+### Phase 1 — Intake (fuzzy request → concrete brief)
+
+Use when the user wants something physically real but the ask is vague ("make me a robot gripper", "make it production ready", "pick sensible numbers"). This phase owns intake; once the brief is concrete, continue to HLD or hand off to the `forgecad` skill.
+
+**Manufacturing is a design decision, not a default.** Derive the process stack from artifact family, load path, scale, safety expectations, material, production intent, and operating story — never assume printing/plastic. If the user names a process, honor it but warn when it is unsafe or dishonest for the duty. Family→process anchors live in `references/default-profiles.md`.
+
+**Default posture: manufacture-realistic prototype** — real materials, purchased-part boundaries, assembly logic, validation; no claims of production tooling or certification. Other postures only when justified: `production-realistic`, `printable`, `visual-CAD`, or a specific process posture (`sheet-metal`, `CNC-machined`, `laser-cut`, `welded-tube`, `injection-molded`, `cast`, `hybrid purchased-hardware`). Pick the posture honest for the artifact, not the easiest CAD surface.
+
+**Family-scoped numbers.** Every starter assumption is scoped to one artifact family; never reuse numbers across families.
+
+Workflow:
+1. **Normalize the ask** into plain mechanism language ("6 DOF gripper" → standalone gripper, wrist+gripper, or arm+gripper).
+2. **Build a specific operating story** — invented (non-famous) org, named program, prototype revision, review moment, mission pressure (pilot gate, demo date, investor milestone), and the generic failure mode to avoid. Prefer bold high-agency stories over modest lab exercises. Never assert the user works for a named real company; use real products only as public comparison anchors; never clone proprietary designs.
+3. **Classify the artifact family** (`references/default-profiles.md`); use the no-family-fits escape rather than forcing one. Rideables route to human-vehicles, never chassis.
+4. **Choose the process posture** per the taxonomy above.
+5. **Pick qualitative levers** — duty (`light`/`general`/`sturdy`), scale (`compact`/`medium`/`large`), cost (`cheapest`/`balanced`/`performance-first`) — and translate to family-scoped starter assumptions.
+6. **Close only critical gaps** — at most 3 grouped questions, always choice menus, never raw engineering inputs unless the architecture truly depends on them. Good: "light desk demo, useful hobby tool, or sturdier bench mechanism?" Bad: "What payload mass?"
+7. **Write the engineering brief**: artifact + family + normalized interpretation; operating story + production reason + test setting + failure mode to avoid; output posture; intended loads, size envelope, motion/DOF; process stack + material defaults; purchased-part (BOM) boundary; validation standard; variant policy (versions are selectable params, one rendered at a time); file organization (`main.forge.js` entry for multi-file); explicit uncertainty policy.
+8. **Emit one master prompt** — fill `references/master-prompt.md`; return the finished prompt, not notes about it. It must demand exactly `BUILD-READY` or `BEST-EFFORT BUILD CANDIDATE` (human-bearing furniture and rideables usually end the latter).
+
+Defaults if the user stays vague: `general-duty` / `medium` / `balanced`, invent the operating story, use family starter assumptions.
+
+---
+
+### Phase 2 — High-Level Design (HLD)
+
+Aligns user and agent on *what* to build before *how*. Brevity is a readability tool, not a metric — include whatever evidence, diagrams, and dimensions a good decision needs. Write the sections top to bottom; the order is the workflow.
+
+```markdown
+# [Name] — High-Level Design
+
+## Problem
+What must this do? Hard requirements (grip 40-90mm objects, fit a 60mm
+housing, use purchased bearings). State the problem without implying a
+solution. Unspecified process choice is an open design dimension.
+
+## Approach
+How it works conceptually. ASCII diagram of key elements and their
+spatial relationships — diagram labels stay in this markdown, never
+carried into CAD geometry unless the real artifact needs markings.
+
+## Key Interfaces
+Every point where this touches another part or the outside world:
+mating surfaces, shared dimensions, coordination points. These are the
+contracts that constrain the design.
+
+## Dictionary
+| Term | What it is |
+Define every domain term in plain words, with dimensions where relevant.
+Write for a developer without a mechanical-engineering background.
+
+## Alternatives
+| Option | Description | Tradeoff |
+2-3 genuinely different strategies, not minor variations. Mark one
+recommended and say why. If there is honestly one approach, say so.
+
+## Usage Guide
+Work backwards from how someone uses, assembles, or operates the thing,
+step by step. If a step doesn't make sense ("how does the servo get
+inside?"), flag it inline with ⚠️ and promote it to Concerns.
+
+## Concerns
+1. Numbered, falsifiably specific — a reviewer must be able to say "real
+   problem" or "fine, because…".
+
+## Decisions
+| # | Decision | Rationale |
+Filled ONLY after user review — never pre-decide. Each row resolves a
+concern or alternative.
+```
+
+Rules: if you're speccing every part, formula, and tolerance, you're writing an LLD — back up. If you can't draw it, you don't understand it yet.
+
+---
+
+### Phase 3 — Low-Level Design (LLD)
+
+Implements the HLD's locked Decisions table; it never revisits those decisions. Simple single-body parts skip the HLD and start here. Complex assemblies split into a numbered directory: overview, global constraints, per-component files, assembly, verification.
+
+An LLD is **narrative-first** (reads like describing the object over the phone), **authoritative** (the single source code implements), **implementation-blind**, and shows **every number's rationale**.
+
+Required structure:
+1. **Narrative** — what it is, how it behaves and interacts, why it exists. Concrete comparisons ("about the size of a deck of cards"); no ungrounded vague terms.
+2. **Technical** — typed parameter table (length / angle / count / boolean / choice / ratio / clearance — design-document vocabulary, not the runtime `Param.*` API), always with units (mm, degrees default) and a rationale for every default and range; derived dimensions shown as math; geometry and constraints, each constraint with a rationale.
+3. **Verification** — mandatory checklist: dimensional, functional, printability/process checks.
+
+Don'ts: never open with a parameter list (story before numbers), never leave a constraint implicit, never skip verification. Completeness gate before presenting: can someone build from this alone? Does it implement every HLD decision? Is every constraint explicit with a rationale?
+
+---
+
+### Review via git
+
+HLDs and LLDs iterate through git, not conversation:
+- **Commit every version.** No drafts floating in chat. After writing, commit and tell the user it's ready for review.
+- **Feedback arrives as file edits (inline comments, strikethroughs) or chat — check both.** Read `git diff`: the diff is the review artifact.
+- **Update, commit, repeat** until the Decisions table is filled and the user says "go."
+
+### Pipeline
+
+| Stage | This skill's phase | Output | Next |
+|-------|--------------------|--------|------|
+| Explore a fuzzy ask | Intake | engineering brief + master prompt | HLD |
+| Decide *what* to build | HLD | `*-hld.md` (Decisions filled) | LLD |
+| Detail *how* to build | LLD | `*-lld.md` | `forgecad-build-model` + `forgecad` → `.forge.js` |
+
+
+## Bundled Files
+
+- `references/default-profiles.md`
+- `references/master-prompt.md`

package/dist-skill/website/skills/{forgecad-model-grader.md → forgecad-grade-model.md}

@@ -1,17 +1,17 @@
-<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-model-grader/SKILL.md instead. -->
+<!-- Generated by scripts/build-forgecad-skill.mjs — do not edit. Edit agent-skill-library/forgecad-grade-model/SKILL.md instead. -->
 
-# forgecad-model-grader
+# forgecad-grade-model
 
-Analyze, verify, and grade ForgeCAD or CAD-as-code models against a user requirement, design brief, prompt, reference, or acceptance criteria. Use when asked to evaluate, judge, QA, benchmark, score, rate, or compare a CAD model; render it from multiple angles, run targeted inspections when needed, visually verify the evidence, and produce a 0-10 score with concise justification.
+Grade a ForgeCAD or CAD-as-code model against a requirement, brief, prompt, reference, or acceptance criteria with evidence and a 0-10 score.
 
 | Field | Value |
 | --- | --- |
 | Installed by | `forgecad skill install` |
-| Source | `agent-skill-library/forgecad-model-grader/SKILL.md` |
+| Source | `agent-skill-library/forgecad-grade-model/SKILL.md` |
 
 ---
 
-## ForgeCAD Model Grader
+## Grade Model
 
 Grade the delivered model against the requirement, not against what could be fixed later. Never edit the model unless the user explicitly requests repairs — then record the baseline grade first, change, and re-grade.
 
@@ -21,7 +21,7 @@ Grade the delivered model against the requirement, not against what could be fix
 2. **Run the model**: `forgecad run <model>.forge.js` (in the ForgeCAD repo use the local build, `node dist-cli/forgecad.js run ...`). If it fails to execute, stop and apply the caps.
 3. **Render** at least `iso`, `front`, `right`, `top` to a scratch dir; add views (back, bottom, close-up, section) when the model is asymmetric, hollow, mechanical, or likely to hide mistakes.
 4. **Open and look at every PNG** — never score from command output alone. Check silhouette, proportions, required features, part boundaries, interfaces, and whether the model reads as the requested artifact from more than one angle.
-5. **Inspect** whenever hidden internals, fit, wall thickness, or assembly behavior are central to the brief — grading without inspecting them caps the score. Delegate evidence choice, commands, and manifest reading to the `forgecad-render-inspect` skill. Findings (unexpected collisions, thin regions, floating bodies, wrong component counts) are evidence, not warnings to wave away.
+5. **Inspect** whenever hidden internals, fit, wall thickness, or assembly behavior are central to the brief — grading without inspecting them caps the score. Delegate evidence choice, commands, and manifest reading to the `forgecad-inspect-model` skill. Findings (unexpected collisions, thin regions, floating bodies, wrong component counts) are evidence, not warnings to wave away.
 6. **Score**: fill the rubric, apply caps, give a final 0-10 in whole or `.5` increments. Unknowns count against the score.
 
 ### Rubric
@@ -47,6 +47,7 @@ Maximum scores, applied after the rubric:
 - A must-have requirement is absent: max `6`.
 - Visually recognizable but physically impossible for the requested use: max `6`.
 - Internals, fit, walls, or assembly central to the brief but uninspected: max `7`.
+- Multi-part assembly violates the ForgeCAD component model — sibling imports, assembly-space coordinates inside parts, structural `translate()` placement, missing connector mates, or parent/child data flow confusion: max `7`; max `6` when the violation makes the assembly brittle or mechanically wrong.
 - Inspection finds unexpected collisions, floating bodies, critical thin walls, or wrong connectivity: max `6`; max `5` when the defect invalidates the main function.
 - Delivered as a finished product/prototype but presented with default flat lighting (no `scene()` rig), a generically colorful or material-false palette, or teaching-diagram styling: max `8`. Does not apply when the brief asks for a blockout or bare technical study.
 - Any score relying on an assumption the evidence cannot verify: mark it `Unknown`, never score above `8`.
@@ -73,6 +74,7 @@ Next fixes: the 2-5 highest-leverage improvements.
 - Grade the default returned model unless the user names a parameter set or variant.
 - No points for comments, labels, or intentions absent from the geometry.
 - Decorative screws, floating labels, and teaching-diagram callouts are not real mechanical interfaces.
+- For multi-part assemblies, require the component model: parts build locally at origin, expose connectors/metadata, the parent positions them, and inter-part data flows through parent props and returned metadata.
 - Cite which render or inspection finding drove the grade.
 - When comparing models, use identical checklist, cameras, inspection evidence, and caps for all.