forgecad 0.9.14 → 0.9.16

package/dist-skill/docs/guides/positioning.md

@@ -11,6 +11,16 @@ For any fixed assembly where parts are meant to stay in contact in the final mod
 
 Use raw `translate()` and `rotate()` when parts are intentionally free-floating or when you are doing quick exploratory layout. Use `attachTo()` for rough bounding-box placement. But if the relationship is a real interface, make it explicit with connectors.
 
+## Mechanisms: connector frames vs link points
+
+For serial articulated parts (hinges, hips, knees, levers, wheels), use `assembly().connect()` with connectors. `connect()` aligns the full connector frame: `origin` is the pivot/contact point, `axis` is the hinge line or slide direction, and `up` locks the zero-angle twist of the child part. `up` is a local roll reference, not world up; author it explicitly whenever the rest pose matters.
+
+Do not use `addPart(..., { mate: { connector, toLink } })` when the part must point along a bone or inherit orientation from a link edge. Link mates are point attachments only: they translate the connector origin onto the solved link position and preserve the part's existing rotation. That is good for markers, sensors, labels, and debug handles. It is not a bone-frame API.
+
+Use link graphs (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) when the hard part is solving point positions, especially closed loops. Use connector-frame joints when the hard part is orienting real physical parts.
+
+For bilateral mechanisms, remember that connector-frame revolute values are physical axis-local values. Mirrored hinge axes need negated physical revolute values for the same mirrored pose, and physical limits mirror as `[min, max] -> [-max, -min]`. If you want `HipR: 10` and `HipL: 10` to mean the same semantic pose, drive a mirrored link graph or write an explicit state mapping instead of assuming equal connector-joint values are symmetric.
+
 ## Primitive origin convention
 
 All 3D primitives are **centered on XY, base at Z=0**:
@@ -34,14 +44,14 @@ Most positioning bugs come from manual coordinate arithmetic. Use these methods
 
 ## 1. Connectors + `matchTo()` — default for mating interfaces
 
-Define connectors on parts; `matchTo()` provides automatic 6-DOF alignment. The child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model).
+Define connectors on parts; `matchTo()` provides automatic alignment. With one connector pair, the child translates and rotates so its connector aligns with the target's — origins coincide, axes oppose (plug-in model), and `up` pins the roll reference. With multiple connector pairs, the connector origins define the rigid transform; still author meaningful `axis` and `up` values so the same connectors remain useful for `connect()`, audits, and future matching.
 
 ```javascript
 const shelf = box(200, 120, 10).translate(0, 0, -5).withConnectors({
-  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0] }),
+  left_tab: connector.male("dovetail", { origin: [-100, 0, 0], axis: [-1, 0, 0], up: [0, 0, 1] }),
 });
 const panel = box(12, 120, 200).translate(0, 0, -100).withConnectors({
-  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0] }),
+  shelf_0: connector.female("dovetail", { origin: [6, 0, -50], axis: [1, 0, 0], up: [0, 0, 1] }),
 });
 const placed = shelf.matchTo(panel, "left_tab", "shelf_0");
 // Dictionary form for multiple pairs on same target:

package/dist-skill/library/forgecad-component-model/SKILL.md

@@ -26,9 +26,11 @@ A part is a function from props to `{ shape, connectors, metadata }`. It builds
 - A connector = origin + axis (outward from the part)
 - Connectors meet **face-to-face**: both axes point outward, system brings them together
 - For prismatic joints: axes point along the shared slide direction
+- Mirrored revolute axes need negated physical joint values for the same mirrored pose
 
 ### 3. Assembly Is Pure Composition
-- `addPart()` + `connect()` + `addJointCoupling()` — nothing else
+- Use `addPart()` + `connect()` for frame-aware serial assemblies
+- Use `link()` + `edgeBetweenLinks()` + `addAngleBetweenLinks()` for solved point skeletons
 - Zero `translate()` calls for structural parts
 - Zero coordinate math
 - The assembly passes props down and reads metadata up
@@ -60,6 +62,13 @@ mount.withConnectors({
 assembly.connect("Base.mount_face", "Mount.flange", { as: "mount-fix" });
 ```
 
+Revolute values are signed by the physical hinge axis. In a bilateral mechanism,
+`axis: [1, 0, 0]` on the right side and `axis: [-1, 0, 0]` on the left side are
+exact mirrors at rest, but the same `+theta` value rotates them in opposite
+fore/aft senses. Use `Right: +theta`, `Left: -theta`, and mirror physical limits
+as `[min, max] -> [-max, -min]`, or drive both sides from a side-neutral link
+graph/control layer.
+
 ## Part Return Shape
 
 Every part file returns a structured object:

package/dist-skill/library/forgecad-image-replicator/SKILL.md

@@ -114,10 +114,10 @@ node dist-cli/forgecad.js render 3d path/to/model.forge.js /tmp/<slug>-replicate
   --size 1000 --edges thin
 ```
 
-Build side-by-side boards with the bundled helper:
+Build side-by-side boards with the bundled helper. It is a self-contained `uv` script that installs Pillow on demand and does not require Chrome. The examples use the ForgeCAD source-checkout path; if the skill is installed elsewhere, resolve `scripts/compare_images.py` relative to the `forgecad-image-replicator` skill directory.
 
 ```bash
-node skills/forgecad-image-replicator/scripts/compare_images.mjs \
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py \
   /tmp/<slug>-replicate/refs/front.png \
   /tmp/<slug>-replicate/render-front.png \
   /tmp/<slug>-replicate/compare-front.png \
@@ -127,10 +127,10 @@ node skills/forgecad-image-replicator/scripts/compare_images.mjs \
 Common helper options:
 
 ```bash
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.jpg render.png compare.png --height 1200 --fit contain
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png --fit cover --labels "Target,Current"
-node skills/forgecad-image-replicator/scripts/compare_images.mjs ref.png render.png compare.png --no-labels
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.jpg render.png compare.png --height 1200 --fit contain
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --fit cover --labels "Target,Current"
+uv run agent-skill-library/forgecad-image-replicator/scripts/compare_images.py ref.png render.png compare.png --no-labels
 ```
 
 Use `--fit contain` by default. Use `--fit cover` only when both images already share the same crop and aspect.

package/dist-skill/library/forgecad-image-replicator/scripts/compare_images.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.9"
+# dependencies = ["pillow>=10"]
+# ///
+
+"""Build a reference-vs-render PNG board for ForgeCAD image replication."""
+
+from __future__ import annotations
+
+import argparse
+from math import ceil
+from pathlib import Path
+
+from PIL import Image, ImageColor, ImageDraw, ImageFont, ImageOps
+
+
+def positive_int(raw: str) -> int:
+    value = int(raw)
+    if value <= 0:
+        raise argparse.ArgumentTypeError("must be a positive integer")
+    return value
+
+
+def labels(raw: str) -> tuple[str, str]:
+    values = tuple(part.strip() for part in raw.split(",") if part.strip())
+    if len(values) != 2:
+        raise argparse.ArgumentTypeError("must contain two comma-separated labels")
+    return values
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Build a side-by-side comparison board from a reference image and ForgeCAD render.",
+    )
+    parser.add_argument("reference_image")
+    parser.add_argument("forgecad_render")
+    parser.add_argument("output_png")
+    parser.add_argument("--height", type=positive_int, default=900, help="Panel height in pixels.")
+    parser.add_argument("--panel-width", type=positive_int, default=None, help="Panel width in pixels.")
+    parser.add_argument("--gap", type=positive_int, default=16, help="Gap between panels in pixels.")
+    parser.add_argument("--padding", type=positive_int, default=16, help="Outer padding in pixels.")
+    parser.add_argument("--background", default="#111111", help="Canvas background color.")
+    parser.add_argument("--fit", choices=("contain", "cover"), default="contain", help="Image fit mode.")
+    parser.add_argument("--labels", type=labels, default=("Reference", "ForgeCAD"), help="Two comma-separated labels.")
+    parser.add_argument("--no-labels", action="store_true", help="Disable label band.")
+    parser.add_argument(
+        "--chrome-path",
+        default=None,
+        help=argparse.SUPPRESS,
+    )
+    return parser.parse_args()
+
+
+def open_image(path_arg: str) -> Image.Image:
+    path = Path(path_arg).expanduser()
+    if not path.exists():
+        raise SystemExit(f"Image not found: {path}")
+    try:
+        image = Image.open(path)
+        return ImageOps.exif_transpose(image).convert("RGBA")
+    except Exception as exc:  # Pillow gives format-specific exceptions.
+        raise SystemExit(f"Failed to open image {path}: {exc}") from exc
+
+
+def parse_background(raw: str) -> tuple[int, int, int, int]:
+    try:
+        color = ImageColor.getcolor(raw, "RGBA")
+    except ValueError as exc:
+        raise SystemExit(f"Invalid background color {raw!r}: {exc}") from exc
+    return color
+
+
+def load_label_font() -> ImageFont.ImageFont:
+    candidates = [
+        "/System/Library/Fonts/Supplemental/Arial Bold.ttf",
+        "/System/Library/Fonts/Supplemental/Arial.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/truetype/liberation2/LiberationSans-Bold.ttf",
+    ]
+    for candidate in candidates:
+        path = Path(candidate)
+        if path.exists():
+            return ImageFont.truetype(str(path), 18)
+    return ImageFont.load_default()
+
+
+def scaled_to_panel(image: Image.Image, panel_width: int, panel_height: int, fit: str) -> Image.Image:
+    width, height = image.size
+    if width <= 0 or height <= 0:
+        raise SystemExit("Image dimensions must be positive.")
+    scale = (
+        max(panel_width / width, panel_height / height)
+        if fit == "cover"
+        else min(panel_width / width, panel_height / height)
+    )
+    if fit == "cover":
+        scaled_size = (max(panel_width, ceil(width * scale)), max(panel_height, ceil(height * scale)))
+    else:
+        scaled_size = (min(panel_width, max(1, round(width * scale))), min(panel_height, max(1, round(height * scale))))
+    resized = image.resize(scaled_size, Image.Resampling.LANCZOS)
+    if fit != "cover":
+        return resized
+
+    left = max(0, (resized.width - panel_width) // 2)
+    top = max(0, (resized.height - panel_height) // 2)
+    return resized.crop((left, top, left + panel_width, top + panel_height))
+
+
+def paste_panel(
+    board: Image.Image,
+    image: Image.Image,
+    *,
+    x: int,
+    y: int,
+    panel_width: int,
+    panel_height: int,
+    fit: str,
+) -> None:
+    panel = Image.new("RGBA", (panel_width, panel_height), (0, 0, 0, 0))
+    fitted = scaled_to_panel(image, panel_width, panel_height, fit)
+    dx = (panel_width - fitted.width) // 2
+    dy = (panel_height - fitted.height) // 2
+    panel.alpha_composite(fitted, (dx, dy))
+    board.alpha_composite(panel, (x, y))
+
+
+def main() -> None:
+    args = parse_args()
+    reference = open_image(args.reference_image)
+    render = open_image(args.forgecad_render)
+
+    panel_height = args.height
+    max_aspect = max(reference.width / reference.height, render.width / render.height)
+    panel_width = args.panel_width or int(panel_height * max_aspect + 0.9999)
+    label_values = None if args.no_labels else args.labels
+    label_height = 34 if label_values else 0
+    canvas_width = args.padding * 2 + panel_width * 2 + args.gap
+    canvas_height = args.padding * 2 + label_height + panel_height
+
+    board = Image.new("RGBA", (canvas_width, canvas_height), parse_background(args.background))
+    draw = ImageDraw.Draw(board)
+    left_x = args.padding
+    right_x = args.padding + panel_width + args.gap
+    panel_y = args.padding + label_height
+
+    if label_values:
+        font = load_label_font()
+        for text, x in ((label_values[0], left_x), (label_values[1], right_x)):
+            draw.text((x, args.padding + 4), text, fill=(255, 255, 255, 230), font=font)
+
+    paste_panel(board, reference, x=left_x, y=panel_y, panel_width=panel_width, panel_height=panel_height, fit=args.fit)
+    paste_panel(board, render, x=right_x, y=panel_y, panel_width=panel_width, panel_height=panel_height, fit=args.fit)
+
+    outline = (255, 255, 255, 64)
+    draw.rectangle((left_x, panel_y, left_x + panel_width - 1, panel_y + panel_height - 1), outline=outline)
+    draw.rectangle((right_x, panel_y, right_x + panel_width - 1, panel_y + panel_height - 1), outline=outline)
+
+    output_path = Path(args.output_png).expanduser()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    board.save(output_path, "PNG")
+    print(f"Wrote {output_path} ({canvas_width}x{canvas_height})")
+
+
+if __name__ == "__main__":
+    main()

package/dist-skill/library/forgecad-make-a-model/SKILL.md

@@ -44,9 +44,14 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
 
 ## Workflow
 
-1. Load the ForgeCAD skill — always invoke the `forgecad` skill first to get API docs and authoring guidance. Read at minimum the Core API reference. If any two parts are intended to touch or mate in the final model, read the positioning guide immediately and default to connectors + `matchTo()`.
+1. Load the ForgeCAD skill — always invoke the `forgecad` skill first to get API docs and authoring guidance. Read at minimum the Core API reference. If the model has moving parts, load the assembly group and `docs/permanent/guides/joint-design.md` before writing geometry. If any two parts are intended to touch or mate in the final model, read the positioning guide immediately and default to connectors + `matchTo()`.
 2. Create the directory — `mkdir -p YYYY/MM/DD/[folder]` as needed.
-3. Write the model — create the `.forge.js` file(s) following ForgeCAD conventions:
+3. Prove moving-part kinematics before detailed geometry — for any mechanism, robot, linkage, hinge, slider, suspension, gripper, wheel train, drawer, door, linkage toy, or articulated product:
+   - Author the rig first: links, frames, fixed ground references, parent/child relationships, joints, couplings, limits, defaults, mirrored-side sign mapping, and named controls.
+   - Choose the right rig primitive before modeling the skin: use link graphs (`link()`, `edgeBetweenLinks()`, `addAngleBetweenLinks()`) for point skeletons and closed loops; use frame/connector joints (`frame()`, `revoluteJoint()`, `prismaticJoint()`, `connect()`, `match()`) when part orientation matters.
+   - Attach only simple markers, bars, or proxy parts at first. Return the `Assembly` directly and run it at rest, mid-travel, and limit joint values until the solver, controls, connector/frame alignment, and `verify.*` checks pass.
+   - Only after the rig works should you replace proxies with manufacture-real geometry attached to the solved links, frames, and connectors. Do not bake a posed `SolvedAssembly` as the default return just to make one pose look right.
+4. Write the model — create the `.forge.js` file(s) following ForgeCAD conventions:
    - Treat the default build profile as `manufacture-realistic prototype`; choose and encode the artifact's manufacturing/process cues before adding styling detail
    - Declare `param()` / `boolParam()` for all tunable dimensions
    - If the model is split across files, use `main.forge.js` as the primary entry point, import renderable parts from neighboring `.forge.js` files, and keep only pure helpers/constants in plain `.js` modules
@@ -57,11 +62,12 @@ Use today's date for the directory. Use the user's current ForgeCAD project when
    - Make final mating geometry physically plausible: parts may touch, clear each other, or be boolean-joined, but should not unintentionally pass through each other
    - Model the physical artifact, not an educational diagram: no explanatory arrows, floating labels, section labels, legends, or text plaques unless the user explicitly requested a presentation/teaching view
    - Do not make the default returned model a cutaway, sectioned shell, permanently exploded assembly, or hidden-parts teaching view. ForgeCAD gives the user viewer and inspection tools for slicing, exploding, hiding, and looking inside after the real CAD exists.
-   - Return the final geometry (single shape, array, or named objects array)
+   - Return the final artifact (single shape, array, named objects array, or `Assembly` for moving mechanisms)
+   - For moving assemblies, return the `Assembly` itself whenever possible so Motion controls re-run the real kinematic solve; avoid legacy viewport-only animation APIs for new work unless the user explicitly asks for them
    - Treat `fillet(shape, r)` and `chamfer(shape, r)` as experimental edge treatments: Manifold can produce incorrect results and OCCT can be very slow. Prefer simpler primitive profiles, lower segment counts, targeted edge selectors, and inspection before relying on the result.
-4. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`.
-5. Verify geometry — render a multi-angle visual evidence set before final delivery: whole-model context plus agent-chosen orthographic, oblique, underside, or hidden-object views that expose the relevant components and interfaces. Choose camera directions from the model's shape and likely failure modes, not from a fixed recipe. Use those views to look for internals that are accidentally visible, parts that visibly do not fit, floating details, blocked access, missing seats, and unexpected interference. Run `forgecad inspect physical components` when the model has multiple returned objects or visible attachments, run `forgecad debug assembly --fail-on warning` when the script uses `assembly()`, run `forgecad inspect mechanical-integrity <project-or-file> --collisions` before sharing generated mechanical work, and run the targeted `forgecad inspect <family> <mode>` commands that match the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`. Collision findings are model work, not FYI: remove unexpected overlaps before delivery.
-6. Iterate from visual and inspection feedback — treat every render and inspection bundle as model evidence, not a checkbox. Read the normal PNGs, manifest, and evidence PNGs; convert each unexpected collision, thin region, missing section detail, wrong component count, floating body, distance gap, confusing object-color result, accidentally exposed internal structure, bad fit, or visually unsupported interface into a concrete model edit; then rerun the same targeted evidence pass until the result matches the intended physical component graph.
+5. Validate — run `forgecad run <file>` to check for errors. For multi-file projects, always validate `main.forge.js`. For moving assemblies, also run representative joint states with `--joint`, including rest/default, mid-travel, both limits, and any coupled or mirrored poses.
+6. Verify geometry — render a multi-angle visual evidence set before final delivery: whole-model context plus agent-chosen orthographic, oblique, underside, or hidden-object views that expose the relevant components and interfaces. Choose camera directions from the model's shape and likely failure modes, not from a fixed recipe. Use those views to look for internals that are accidentally visible, parts that visibly do not fit, floating details, blocked access, missing seats, and unexpected interference. For moving assemblies, render at several joint values with `--joint` so clearance, range, stops, and connected followers are proven in motion, not only at rest. Run `forgecad inspect physical components` when the model has multiple returned objects or visible attachments, run `forgecad debug assembly --fail-on warning` when the script uses `assembly()`, run `forgecad inspect mechanical-integrity <project-or-file> --collisions` before sharing generated mechanical work, and run the targeted `forgecad inspect <family> <mode>` commands that match the task (see Final Acceptance Gate and Render-Verify Loop below). For multi-file projects, render and inspect `main.forge.js`. Collision findings are model work, not FYI: remove unexpected overlaps before delivery.
+7. Iterate from visual and inspection feedback — treat every render and inspection bundle as model evidence, not a checkbox. Read the normal PNGs, manifest, and evidence PNGs; convert each unexpected collision, thin region, missing section detail, wrong component count, floating body, distance gap, confusing object-color result, accidentally exposed internal structure, bad fit, bad joint sweep, unconverged pose, follower drift, or visually unsupported interface into a concrete model edit; then rerun the same targeted evidence pass until the result matches the intended physical component graph.
 
 ## Manufacturing Process Is Not Assumed
 
@@ -118,6 +124,28 @@ Do not reveal hidden structure by permanently cutting away the production geomet
 
 When internals are hidden by the final exterior, verify them with exploration tools instead of changing the artifact: render underside or alternate camera views, use `forgecad inspect sections at|stack|sample`, use viewer-only cut planes or explode controls, temporarily make a shell transparent, or add named ghost objects for fit checks. Those views are diagnostic/presentation modes; they must not replace the real model unless the user explicitly asked for a cutaway teaching model.
 
+## Kinematics-First for Moving Parts
+
+For moving models, the mechanism rig is the source of truth. Do not start with finished housings, arms, shells, covers, or decorative surfaces and then try to retrofit motion. Build the motion structure first, prove it, and attach geometry to it.
+
+- Decide the rig shape before geometry: point links for closed-loop skeletons and distance/angle constraints; frames and connector joints for serial rigid parts whose orientation matters.
+- Name every moving degree of freedom and encode its limits/defaults at the rig level. For mirrored revolute axes, make the sign mapping explicit instead of assuming equal values create mirrored poses.
+- Add simple proxy geometry only to expose the rig: pivot markers, bars between links, slider blocks, wheel discs, or frame axes. Use those proxies to verify the mechanism before adding real material.
+- Attach final geometry to solved links, frames, and connectors. A visible arm, cover, wheel, drawer, or follower should move because it is mated to the rig, not because a final `rotate()` or `translate()` happens to make one pose look assembled.
+- Keep the default return as the unsolved `Assembly` when possible. This lets Motion controls and CLI `--joint` overrides re-run the real solve.
+- Put representative pose checks in the script with `verify.*`: convergence, connector origins coinciding, link lengths holding, end effectors reaching their expected points, followers remaining attached, and required running clearances staying positive.
+
+At minimum, run the mechanism at rest, mid-travel, both limits, and any mirrored/coupled poses:
+
+```bash
+node dist-cli/forgecad.js run model.forge.js --joint "theta=0"
+node dist-cli/forgecad.js run model.forge.js --joint "theta=45"
+node dist-cli/forgecad.js run model.forge.js --joint "theta=90"
+node dist-cli/forgecad.js render 3d model.forge.js /tmp/model-theta-45.png --joint "theta=45" --camera iso --size 700
+```
+
+Use the real joint/control names from the assembly. For multiple controls, repeat `--joint`: `--joint "hip=20" --joint "knee=-35"`. If any pose fails to solve, clamps unexpectedly, breaks a connector check, or creates a new collision, the rig is not ready for final geometry.
+
 ## Mechanical Assembly Contract
 
 For mechanical models, a ForgeCAD script is not done when it merely looks assembled. Every visible piece must have a believable 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.
@@ -132,37 +160,7 @@ For mechanical models, a ForgeCAD script is not done when it merely looks assemb
 - Purchased loose parts may remain separate bodies, but they should be named as purchased hardware or consumables and should sit in believable sockets, bores, races, guides, or fastener stacks.
 - Encode interface intent with `verify.*`, not only comments. Use `verify.clearanceBetween("cover is seated on gasket", cover, gasket, -0.01, 0.05)` for contact/seated fits and clearance bands, `verify.minClearance(...)` or `verify.notColliding(...)` for keep-out/running gaps, and `verify.connectorDistance(...)` for connector-authored mates. Part counts and generic dimensions are useful supporting checks, but they do not prove an interface by themselves.
 
-For ordinary removable covers, prefer `lib.boltedServiceCover(...)` before hand-placing plates, tabs, screw heads, gaskets, and holes. It creates the parent ledge, gasket, cover plate with fused pull tabs, shared bolt pattern, and installed screws as one mechanically accountable interface.
-
-For electronics boxes, backplates, service-stack housings, and camera/monitor enclosures, prefer `lib.datumEnclosureAssembly(...)` before independently placing panels, ribs, bosses, ports, covers, and screws. It creates the tray, ledges, standoffs, ribs, service port, gasket, cover, and screws from one shared datum system.
-
-For PCB-mounted terminal blocks, thermostat backplates, control boards, and wire-entry electronics panels, prefer `lib.pcbTerminalBlockAssembly(...)` before placing a loose green block near a board or cover. It creates the backplate, fused standoffs, PCB mounting screws, PCB pin holes, terminal pins, and seated purchased terminal block from one shared datum system.
-
-For snap-retained covers, cartridges, small clasps, and housings, prefer `lib.snapLatchCoverAssembly(...)` before drawing decorative snap tabs. It creates latch windows, underside catch lands, fused snap hooks, barbs, and clearance checks so the cover is retained by real geometry.
-
-For ordinary pinned handles, cam levers, release levers, and latch arms, prefer `lib.pinnedLeverAssembly(...)` before hand-placing a hub, arm, washers, and pin. It creates a fused lever body, aligned pivot bore, retained pin, thrust washers, support land, and low stop land as one mechanically accountable pivot stack.
-
-For trunnions, side knobs, adjustable pivots, and clamp shafts, prefer `lib.retainedShaftAssembly(...)` before hand-placing rods, washers, and knobs. It creates bored support cheeks, a through shaft, thrust washers, knobs, retaining heads, and shared bore dimensions as one mechanically accountable stack.
-
-For thumb screws, desk clamps, vise screws, capo pressure screws, and small fixture hold-downs, prefer `lib.thumbScrewClampAssembly(...)` before hand-placing a knob, screw cylinder, pressure pad, and bracket jaw. It creates the C-frame, threaded boss/bore, captive pressure pad, hand knob, and seated workpiece contact from one shared datum system.
-
-For drawer slides, quick-release plates, and guided linear carriages, prefer `lib.capturedLinearSlide(...)` before hand-placing rails and a block. It creates a U-channel rail with return lips, end stops, a captured carriage, and explicit travel/clearance dimensions.
-
-For pump cartridges, filter cassettes, battery cartridges, skeg cassettes, and removable slide-in modules, prefer `lib.capturedCartridgeGuideAssembly(...)` before placing a loose tray and block. It creates return lips, a rear stop, a captured cartridge flange, pull tab, insertion travel, and explicit clearance dimensions.
-
-For molded flexible battery doors, sample covers, blister latches, and polypropylene-style service flaps, prefer `lib.livingHingeCoverAssembly(...)` before drawing two plates with a decorative hinge strip. It creates one fused molded strip with fixed leaf, thin flexible web, moving cover leaf, pull lip, snap barb, catch land, and web-thickness checks.
-
-For doors, barn-door leaves, lids, locket leaves, and small hinged access panels, prefer `lib.knuckledHingeAssembly(...)` before hand-placing barrels and a pin. It creates alternating fused knuckles, two leaves, a shared bore, and a retained pin as one mechanically accountable hinge.
-
-For crank links, damper rod ends, crossheads, and clevis-yoke pivots, prefer `lib.clevisPinJointAssembly(...)` before hand-placing an eyelet and pin. It creates bored clevis ears, a captured center link eye, a rear bridge, and a retained pin as one mechanically accountable load path.
-
-For bearings, rollers, burr cartridges, spindle supports, and purchased radial bearings, prefer `lib.seatedBearingAssembly(...)` before hand-placing a ring and shaft near a block. It creates a bored housing, counterbore pocket, bearing shoulder, seated bearing, shaft, collars, and shared clearance dimensions as one mechanically accountable support.
-
-For cables, wires, hoses, pump tubes, and panel pass-throughs, prefer `lib.cableGlandAnchorAssembly(...)` before hand-placing a loose cylinder near a wall. It creates the panel clearance hole, hollow gland body, compression nut, and routed cable/tube as one mechanically accountable pass-through.
-
-For routed cables, wires, hoses, pump tubes, and sensor leads that run along a surface, prefer `lib.routedTubeClipAssembly(...)` before drawing a tube that floats between endpoints. It creates a base panel, saddle clip bores, clip screw holes, installed screws, and the retained tube route from one shared datum system.
-
-For fluid hoses, pump inlets/outlets, filter ports, and lab tubing, prefer `lib.hoseBarbPortAssembly(...)` before drawing a tube that stops at a block. It creates the bored receiver, raised boss, hollow barbed fitting, installed hose, and clamp band as one accountable hose-port interface.
+Do not introduce canned finished-object helpers for project-specific assemblies. When a repeated physical pattern appears, build the project-specific interface explicitly: use `lib.fastenerSet()` or `lib.boltPattern()` for screw stacks, real bores/counterbores/pockets for purchased parts, connectors plus `matchTo()` for mating parts, and `verify.*` checks for seated contact and running clearances. Reusable library vocabulary should be primitives, cutters, patterns, and mechanical contracts, not finished thermostat backplates, clamp brackets, hinge leaves, or other canned objects.
 
 ## Final Geometry Should Be Physically Plausible
 
@@ -206,6 +204,8 @@ Before telling the user the model is done, prove both technical validity and vis
 
    The model should include at least one verification that proves a mechanical interface, not just object count. Prefer checks such as `verify.clearanceBetween("bearing is seated in pocket", bearing, housing, -0.01, 0.1)`, `verify.minClearance("carriage clears rail", carriage, rail, 0.15)`, `verify.notColliding("cover screw clears parent hole", screw, parent)`, or `verify.connectorDistance("leg connector is seated", bench, "Rail.leg_0", "Leg0.head", 0, 0.01)`.
 
+   For moving assemblies, this gate is incomplete until the rig has been run through representative control states. Use `--joint` overrides and/or in-script `solve(state)` verification to cover rest/default, mid-travel, physical limits, coupled states, and mirrored-side poses. Each tested pose should keep the solver converged, attached geometry following the rig, and clearances/collisions within the intended mechanical contract.
+
 2. Run collision evidence and read both the manifest and images:
 
    ```bash
@@ -241,7 +241,7 @@ Before telling the user the model is done, prove both technical validity and vis
 
 5. Treat ProductSkin and surface-member limitations honestly. If `inspect fit interference` reports boolean-test warnings because a sampled `Product.skin` loft has boundary edges, distinguish that from real collision findings. You may still deliver if `collisionCount` is clean, the intended connectivity is correct, and the visual attachment audit passes. Mention the residual warning briefly in the final response.
 
-6. Final response must name the evidence: commands run, render views checked, any focus/hide filters used, component count, collision count, and any residual warnings or intentional exceptions. Do not just say "validated."
+6. Final response must name the evidence: commands run, render views checked, joint values tested for moving assemblies, any focus/hide filters used, component count, collision count, and any residual warnings or intentional exceptions. Do not just say "validated."
 
 ## Render-Verify Loop
 
@@ -438,6 +438,7 @@ Primitive placement convention:
 Key composition tools:
 
 - Connectors + `matchTo()` for parts that should touch in the final model
+- `assembly()` link graphs, frames, and connector joints for moving mechanisms
 - `group()` for local-coordinate subassemblies
 - `attachTo()` for quick bounding-box placement
 - `.translate()` / `.rotate()` for free offsets or bridging computed locations, not as the default assembly contract

package/dist-skill/library/forgecad-model-grader/SKILL.md

@@ -59,7 +59,7 @@ This skill is an evaluator workflow. Do not edit the model unless the user expli
 
    ```bash
    node dist-cli/forgecad.js inspect fit interference path/to/model.forge.js /tmp/model-grade/collisions --camera iso --force --size 700
-   python skills/forgecad-render-inspect/summarize_manifest.py /tmp/model-grade/collisions
+   python agent-skill-library/forgecad-render-inspect/summarize_manifest.py /tmp/model-grade/collisions
    ```
 
    Read the manifest and inspect the relevant evidence PNGs. Treat unexpected collisions, thin regions, missing sections, wrong component counts, floating bodies, and confusing object colors as evidence, not as warnings to wave away.

package/dist-skill/library/forgecad-prepare-prompt/SKILL.md

@@ -176,7 +176,7 @@ By the end of this skill, there should be:
 
 9. If implementation continues immediately, hand off to `forgecad`.
    For moving mechanisms, load:
-   - `skills/forgecad/SKILL.md`
+   - `~/.agents/skills/forgecad/SKILL.md`
    - `docs/permanent/generated/assembly.md`
    - `docs/permanent/generated/output.md`
    - `docs/permanent/guides/joint-design.md`

package/dist-skill/library/forgecad-project/SKILL.md

@@ -10,6 +10,8 @@ forgecad-public: true
 
 **forgecad.io** is the primary platform for ForgeCAD projects. The CLI is the main way AI agents interact with it — creating projects, managing files, publishing models, and collaborating. `forgecad studio <project-path> [project-path ...]` opens the installed local editor for users; `forgecad dev <project-path> [project-path ...]` is mainly for ForgeCAD source development.
 
+Keep one long-running `forgecad studio <project-path> [project-path ...]` process open with every active project folder listed in its arguments; the user opens the single printed localhost port once, and AI agents should only create or edit files under those folders so the browser updates live without starting more servers.
+
 ## Authentication
 
 ```sh

package/dist-skill/library/forgecad-render-inspect/SKILL.md

@@ -62,7 +62,7 @@ Routing:
    Run the bundled helper:
 
    ```bash
-   python skills/forgecad-render-inspect/summarize_manifest.py /tmp/model-inspect
+   python agent-skill-library/forgecad-render-inspect/summarize_manifest.py /tmp/model-inspect
    ```
 
    Use `jq` for targeted follow-up when needed:
@@ -88,6 +88,7 @@ Routing:
 | Question | Evidence command |
 |----------|------------------|
 | Quick visual sanity | `inspect visual image` |
+| Kinematic rig, joints, axes, and links | `inspect visual rig` |
 | Object naming and identity | `inspect visual objects` |
 | Exact local section measurement, bore widths, rib thickness through a chosen line | `inspect section --ray ...` |
 | Hidden internals, cavities, pockets, screw paths, captured components | `inspect sections at|stack|sample` |
@@ -106,6 +107,7 @@ Explicit fast bundle:
 
 ```bash
 forgecad inspect visual objects model.forge.js --camera iso --size 700
+forgecad inspect visual rig model.forge.js --camera iso --size 700
 forgecad inspect sections at model.forge.js --plane yz --offset 12.5 --size 700
 forgecad inspect sections stack model.forge.js --plane yz --every 1 --size 700
 forgecad inspect sections sample model.forge.js --count 5 --size 700

package/examples/api/assembly-kinematics-foundation.forge.js

@@ -0,0 +1,65 @@
+// Assembly-owned point kinematics: return the rig, then let viewport controls
+// drive solve(state). Closed loops stay solver-backed instead of viewport-FK,
+// and the editor updates part transforms without rebuilding the marker meshes.
+//
+// This file deliberately keeps the skin as point markers. For physical bars
+// that orient from one solved link to another with two connector mates, see
+// assembly-kinematics-four-bar.forge.js.
+
+const DEFAULT_THETA = 42;
+const MAX_THETA = 95;
+
+const GROUND_A = [0, 0, 0];
+const GROUND_B = [90, 0, 0];
+const CRANK_TIP = [35, 0, 0];
+const ROCKER_TIP = [55, 42, 0];
+
+const crankLen = Points.distance(GROUND_A, CRANK_TIP);
+const couplerLen = Points.distance(CRANK_TIP, ROCKER_TIP);
+const rockerLen = Points.distance(GROUND_B, ROCKER_TIP);
+
+function linkMarker(color) {
+  return box(8, 8, 4)
+    .translate(0, 0, -2)
+    .color(color)
+    .withConnectors({
+      center: connector({ origin: [0, 0, 0], axis: [0, 0, 1] }),
+    });
+}
+
+const mechanism = assembly("Assembly Kinematics Foundation")
+  .link("groundA", { at: GROUND_A, fixed: true })
+  .link("groundB", { at: GROUND_B, fixed: true })
+  .link("crankTip", { at: CRANK_TIP })
+  .link("rockerTip", { at: ROCKER_TIP })
+  .edgeBetweenLinks("groundA", "crankTip", { name: "crank" })
+  .edgeBetweenLinks("crankTip", "rockerTip", { name: "coupler" })
+  .edgeBetweenLinks("groundB", "rockerTip", { name: "rocker" })
+  .addAngleBetweenLinks("groundB", "groundA", "crankTip", {
+    name: "theta",
+    // Past about 98 degrees this link set has no exact four-bar solution:
+    // the coupler and rocker are fully extended.
+    control: { min: 0, max: MAX_THETA, default: DEFAULT_THETA },
+  })
+  .addPart("Ground A marker", linkMarker("#4f5f67"), { mate: { connector: "center", toLink: "groundA" } })
+  .addPart("Ground B marker", linkMarker("#4f5f67"), { mate: { connector: "center", toLink: "groundB" } })
+  .addPart("Crank tip marker", linkMarker("#d55e5e"), { mate: { connector: "center", toLink: "crankTip" } })
+  .addPart("Rocker tip marker", linkMarker("#3d87c7"), { mate: { connector: "center", toLink: "rockerTip" } });
+
+const solved = mechanism.solve({ theta: DEFAULT_THETA });
+verify.equal("kinematic controls are preserved", solved.kinematics.controls.theta, DEFAULT_THETA, 0.000001);
+
+for (const theta of [0, DEFAULT_THETA, 70, MAX_THETA]) {
+  const pose = mechanism.solve({ theta });
+  const groundA = pose.getLinkPosition("groundA");
+  const groundB = pose.getLinkPosition("groundB");
+  const crankTip = pose.getLinkPosition("crankTip");
+  const rockerTip = pose.getLinkPosition("rockerTip");
+
+  verify.that(`closed loop converges at theta ${theta}`, () => pose.kinematics.converged);
+  verify.equal(`crank length holds at theta ${theta}`, Points.distance(groundA, crankTip), crankLen, 0.01);
+  verify.equal(`coupler length holds at theta ${theta}`, Points.distance(crankTip, rockerTip), couplerLen, 0.01);
+  verify.equal(`rocker length holds at theta ${theta}`, Points.distance(groundB, rockerTip), rockerLen, 0.01);
+}
+
+return mechanism;

package/examples/api/assembly-kinematics-four-bar.forge.js

@@ -0,0 +1,115 @@
+// Closed-loop four-bar linkage using the assembly kinematic graph.
+//
+// The links define the mechanism. The bars are ordinary local geometry with
+// two connector mates, so the editor slider re-solves the link graph and then
+// updates part transforms. The bar meshes are not rebuilt while theta changes.
+
+scene({
+  background: { top: "#e6ebef", bottom: "#7b858d" },
+  views: {
+    top: { camera: { position: [45, 25, 220], target: [45, 24, 0], up: [0, 1, 0], fov: 32 } },
+    iso: { camera: { position: [150, -135, 115], target: [45, 24, 0], up: [0, 0, 1], fov: 34 } },
+  },
+  lights: [
+    { type: "ambient", color: "#f4f7fa", intensity: 0.45 },
+    { type: "directional", position: [160, -140, 260], color: "#fff4dc", intensity: 2.0, castShadow: true },
+  ],
+});
+
+const DEFAULT_THETA = 42;
+
+const GROUND_A = [0, 0, 0];
+const GROUND_B = [90, 0, 0];
+const CRANK_TIP = [35, 0, 0];
+const ROCKER_TIP = [55, 42, 0];
+
+const groundLen = Points.distance(GROUND_A, GROUND_B);
+const crankLen = Points.distance(GROUND_A, CRANK_TIP);
+const couplerLen = Points.distance(CRANK_TIP, ROCKER_TIP);
+const rockerLen = Points.distance(GROUND_B, ROCKER_TIP);
+
+function bar(length, width, color) {
+  return box(length, width, 5)
+    .translate(length / 2, 0, 0)
+    .color(color)
+    .material({ metalness: 0.1, roughness: 0.55 })
+    .withConnectors({
+      near: connector({ origin: [0, 0, 0], axis: [1, 0, 0], up: [0, 0, 1] }),
+      far: connector({ origin: [length, 0, 0], axis: [1, 0, 0], up: [0, 0, 1] }),
+    });
+}
+
+function pivot(color) {
+  return cylinder(7, 5.5)
+    .translate(0, 0, -3.5)
+    .color(color)
+    .material({ metalness: 0.2, roughness: 0.45 })
+    .withConnectors({
+      center: connector({ origin: [0, 0, 0], axis: [0, 0, 1], up: [1, 0, 0] }),
+    });
+}
+
+const fourBar = assembly("Closed Loop Four Bar")
+  .link("groundA", { at: GROUND_A, fixed: true })
+  .link("groundB", { at: GROUND_B, fixed: true })
+  .link("crankTip", { at: CRANK_TIP })
+  .link("rockerTip", { at: ROCKER_TIP })
+  .edgeBetweenLinks("groundA", "crankTip", { name: "crank" })
+  .edgeBetweenLinks("crankTip", "rockerTip", { name: "coupler" })
+  .edgeBetweenLinks("groundB", "rockerTip", { name: "rocker" })
+  .addAngleBetweenLinks("groundB", "groundA", "crankTip", {
+    name: "theta",
+    control: { min: 0, max: 95, default: DEFAULT_THETA },
+  });
+
+fourBar.addPart("Ground", bar(groundLen, 10, "#56636b"), {
+  mate: [
+    { connector: "near", toLink: "groundA" },
+    { connector: "far", toLink: "groundB" },
+  ],
+});
+
+fourBar.addPart("Crank", bar(crankLen, 8, "#d95c4b"), {
+  mate: [
+    { connector: "near", toLink: "groundA" },
+    { connector: "far", toLink: "crankTip" },
+  ],
+});
+
+fourBar.addPart("Coupler", bar(couplerLen, 7, "#e5b84c"), {
+  mate: [
+    { connector: "near", toLink: "crankTip" },
+    { connector: "far", toLink: "rockerTip" },
+  ],
+});
+
+fourBar.addPart("Rocker", bar(rockerLen, 8, "#3b82c4"), {
+  mate: [
+    { connector: "near", toLink: "groundB" },
+    { connector: "far", toLink: "rockerTip" },
+  ],
+});
+
+for (const [name, link, color] of [
+  ["Ground A Pivot", "groundA", "#263238"],
+  ["Ground B Pivot", "groundB", "#263238"],
+  ["Crank Pin", "crankTip", "#8c2d25"],
+  ["Rocker Pin", "rockerTip", "#244b74"],
+]) {
+  fourBar.addPart(name, pivot(color), { mate: { connector: "center", toLink: link } });
+}
+
+for (const theta of [0, DEFAULT_THETA, 70, 95]) {
+  const solved = fourBar.solve({ theta });
+  const groundA = solved.getLinkPosition("groundA");
+  const groundB = solved.getLinkPosition("groundB");
+  const crankTip = solved.getLinkPosition("crankTip");
+  const rockerTip = solved.getLinkPosition("rockerTip");
+
+  verify.that(`closed loop converges at theta ${theta}`, () => solved.kinematics.converged);
+  verify.equal(`crank length holds at theta ${theta}`, Points.distance(groundA, crankTip), crankLen, 0.01);
+  verify.equal(`coupler length holds at theta ${theta}`, Points.distance(crankTip, rockerTip), couplerLen, 0.01);
+  verify.equal(`rocker length holds at theta ${theta}`, Points.distance(groundB, rockerTip), rockerLen, 0.01);
+}
+
+return fourBar;