@protoboardai/ext-frame-cad 0.0.0-stage → 0.2.0

package/py/hardware_cad.py

@@ -0,0 +1,111 @@
+"""hardware-cad: nominal bodies for fastener modules (build123d).
+
+    python hardware_cad.py <name>.params.json <out_dir>
+
+Moved from the UHD library's quadcopter generator (library/cad/py/hardware.py
+with the writer from common.py, @deltarobotics/uhd) and made generic: the
+params file (written by lib/hardware.ts from the module) gives the kind and
+the sizes, and nothing about a particular vehicle is in here.
+
+Kinds and shapes (nominal; no thread form):
+  screw     socket head (head_diameter x head_height, hex socket 0.6 deep)
+            under z = 0, plain shank 0.95 d along +Z for `length`
+  nut       hex, `outer` across flats, bore d, `length` high
+  standoff  hex, `outer` across flats, bore 0.85 d, `length` long
+  spacer    tube, `outer` diameter, bore d + 0.4, `length` long
+A nut's, standoff's or spacer's `bore`, when the params give one (the maker
+states it), replaces the nominal bore.
+Each part's origin is where its fastenerStack position is measured: a
+screw's is under its head, thread along +Z; the others sit on z = 0 and
+extend along +Z.
+
+Writes, into <out_dir>:
+  <name>.step             body (label = kind)
+  <name>.glb              the same for viewers (glTF: metres, Y-up)
+  <name>.manifest.json    volume (mass = volume x the module's material
+                          density), tool, version, source digest
+and prints a JSON summary on the last stdout line. Outputs are deterministic
+for fixed params and build123d version: the STEP timestamp is normalised.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import sys
+from pathlib import Path
+
+import build123d as bd
+from build123d import Align, BuildPart, BuildSketch, Circle, Compound, Cylinder, Locations, Mode, Pos, RegularPolygon, export_gltf, export_step, extrude
+
+MIN = (Align.CENTER, Align.CENTER, Align.MIN)
+GENERATOR = Path(__file__)
+FIXED_TIME = "2000-01-01T00:00:00"
+KINDS = ("screw", "nut", "standoff", "spacer")
+
+
+def body(part: dict) -> bd.Part:
+    kind, d, length = part["kind"], part["diameter"], part["length"]
+    bore = part.get("bore")
+    with BuildPart() as p:
+        if kind == "screw":
+            with Locations(Pos(0, 0, -part["head_height"])):
+                Cylinder(part["head_diameter"] / 2, part["head_height"], align=MIN)
+                with BuildSketch():
+                    RegularPolygon(d * 0.45, 6)
+                extrude(amount=part["head_height"] * 0.6, mode=Mode.SUBTRACT)
+            Cylinder(d / 2 * 0.95, length, align=MIN)
+        elif kind == "nut":
+            with BuildSketch():
+                RegularPolygon(part["outer"] / math.sqrt(3), 6)
+                Circle((bore or d) / 2, mode=Mode.SUBTRACT)
+            extrude(amount=length)
+        elif kind == "standoff":
+            with BuildSketch():
+                RegularPolygon(part["outer"] / math.sqrt(3), 6)
+                Circle((bore or d * 0.85) / 2, mode=Mode.SUBTRACT)
+            extrude(amount=length)
+        elif kind == "spacer":
+            Cylinder(part["outer"] / 2, length, align=MIN)
+            Cylinder((bore or d + 0.4) / 2, length, align=MIN, mode=Mode.SUBTRACT)
+        else:
+            raise SystemExit(f"unknown hardware kind {kind!r} (one of {', '.join(KINDS)})")
+    return p.part
+
+
+def build(params: dict, out: Path) -> dict:
+    name, part = params["name"], params["part"]
+    shape = body(part)
+    shape.label = part["kind"]
+    whole = Compound(label=name, children=[shape])
+
+    out.mkdir(parents=True, exist_ok=True)
+    step = out / f"{name}.step"
+    export_step(whole, str(step))
+    step.write_text(re.sub(r"FILE_NAME\('([^']*)','[^']*'", lambda m: f"FILE_NAME('{m.group(1)}','{FIXED_TIME}'", step.read_text(), count=1))
+    export_gltf(whole, str(out / f"{name}.glb"), binary=True, linear_deflection=0.05, angular_deflection=0.3)
+
+    digest = hashlib.sha256(GENERATOR.read_bytes() + json.dumps(params, sort_keys=True).encode()).hexdigest()
+    volume = round(shape.volume, 3)
+    manifest = {
+        "artifact": name,
+        "tool": "build123d",
+        "toolVersion": bd.__version__,
+        "generator": "@protoboardai/ext-frame-cad py/hardware_cad.py",
+        "params": f"{name}.params.json",
+        "sourceDigest": digest,
+        "units": "mm",
+        # solid volume, so mass = volume x the module's declared material density
+        "volume_mm3": volume,
+        "bodies": {part["kind"]: volume},
+        "features": {},
+    }
+    (out / f"{name}.manifest.json").write_text(json.dumps(manifest, indent=2) + "\n")
+    return {"name": name, "toolVersion": bd.__version__, "sourceDigest": digest, "volume_mm3": volume}
+
+
+if __name__ == "__main__":
+    params_path, out_dir = sys.argv[1], sys.argv[2]
+    result = build(json.loads(Path(params_path).read_text()), Path(out_dir))
+    print(json.dumps(result))

package/skills/frame-cad/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: frame-cad
+description: Generate a custom structure's CAD (plates, arms, raised pads, side clamps) from its UHD interfaces with ext-frame-cad, a provider of the cad capability (build123d) — bolt patterns and frames in, STEP/GLB/DXF plus a feature manifest out (protoboard run cad:generate / cad:export --module <id>, or the frame-cad alias) — keep geometry bindings honest, re-bind explicitly after a reviewed change, generate nominal fastener bodies (hardware-cad), and export for manufacturing (DXF/STEP for CNC-routed carbon). Use when a custom frame, plate or bracket needs geometry, when its interfaces change, or when `protoboard check` reports FRAME_CAD_* or UHD_GEOMETRY_BINDING findings; follow with frame-cad-verify.
+---
+
+# Frame CAD from interfaces
+
+```
+module interfaces (bolt patterns + frames) + cad.config.ts constraints
+        │  protoboard run cad:generate --module <id>
+        ▼
+frame-cad/params.json ─► py/frame_cad.py (build123d) ─► frame-cad/frames.json      (native design)
+        │  protoboard run cad:export --module <id>
+        ▼
+out/body.step / body.glb / body.manifest.json / body.dxf / interfaces/*.glb       (standard outputs)
+        │
+        └── cad:check: model frames == generated frames, params and export current
+            geometry bindings: feature signatures == manifest
+```
+
+This extension is a provider of the `cad` capability
+(`docs/specs/tool-integrations.md`): each plate module has a provider
+directory, the folder of its `cad.config.ts`, with the native design in
+`frame-cad/` and the standard outputs (the only files anything downstream
+reads) in `out/`.
+
+A custom structure is designed interface-first: it exists as requirements and
+mating interfaces (each mirroring a selected part's pattern, cited) before it
+has geometry. The generator derives the plate from those interfaces, so the
+CAD cannot drift from the model silently: a change in either is a finding.
+
+Worked example: `examples/quadcopter-5in/src/modules/frame/` — the frame
+(stack, standoff and air-unit hole patterns, four raised motor pads on arms,
+camera side clamp) — and `src/modules/top-plate/` (standoffs, GPS pattern,
+strap slots, explicit outline): each a `.uhd.ts`, a `cad.config.ts`, the
+native `frame-cad/` and the exported `out/`.
+
+## Purpose
+
+Give a plate-like structure (frame, top plate, bracket, side clamp) its
+geometry from the interfaces it must hold, and keep the model and the CAD
+honest about each other. Use it when a custom frame, plate or bracket needs
+geometry, when its interfaces or design values change, and when `protoboard
+check` reports `FRAME_CAD_*` or `UHD_GEOMETRY_BINDING`. Cases and covers
+around a board are **enclosure-cad**; routed cables are **harness-cad**. In
+**build-a-project** it is stage 6 (structures), after the system is composed;
+**frame-cad-verify** follows.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| The plate module: `plate_thickness_mm`, bolt-pattern interfaces with frames | `src/modules/<module>/<module>.uhd.ts` | **system-compose** |
+| The mating parts' patterns (cited) | the parts' interfaces (`npx protoboard inspect <instance>`) | catalog or **uhd-part-author** |
+| Provider config and design values | `src/modules/<module>/cad.config.ts` | this SOP, step 2 |
+| The `cad` runtime | `npx protoboard doctor` shows `python-build123d` ✓ | `npx protoboard tools install cad` |
+
+## Steps
+
+### 1. Runtime
+
+```bash
+npx protoboard doctor          # python-build123d: ✓ build123d 0.13.0, or ✗ with the install hint
+npx protoboard tools install cad   # if missing: a project venv with the pinned build123d (.protoboard/tools/cad)
+```
+
+`PROTOBOARD_PYTHON=/path/to/python` overrides the project runtime (default
+without either: `python3`).
+
+If the tool is missing, `run cad:generate`, `cad:export` and `frame-cad` are
+refused before anything runs (`cad:check` and `extract` need no runtime). Do
+not hand-write CAD to work around it; install the runtime or report it.
+
+### 2. Model the structure
+
+A **plate module** is a local definition whose mechanical metadata states
+`plate_thickness_mm`. Coordinates: module frame, mm, Z up, origin on the
+plate's underside. Each bolt-pattern interface (`BoltPattern(...)`) needs a
+frame (`withGeometry`):
+
+| Interface frame | Becomes | Frame the generator writes back |
+| --- | --- | --- |
+| normal +Z, square/rectangle | through holes, on the top face | `origin z = thickness` |
+| normal −Z | through holes, on the underside | `origin z = 0` |
+| normal +Z, circle (or listed in the config's `pads` constraint) | a raised pad on a hub, joined to the core by an arm (motor mounts); the pad top is the mating face | `z = thickness + pad height` |
+| horizontal normal, `hole_spacing_y` | two vertical side plates `hole_spacing_y` apart (the clamped width), holes `hole_spacing` apart vertically (camera clamp) | `z = thickness + clamp height` (mid-plane of the clamp) |
+
+X/Y positions and axes come from the frames; hole positions follow UHD's
+`boltPatternHoles` (a circle's first hole on the frame's xAxis). Design values
+(outline, fillets, arm width, pad and clamp heights, clearances, slots) are
+generator defaults overridden per module by the constraints in its
+`cad.config.ts`: see [generator reference](references/generator.md). Put
+every design value there with a comment; it is part of the design record, and
+it is this provider's, so it stays out of the UHD module.
+
+```ts
+// src/modules/frame/cad.config.ts, next to frame.uhd.ts
+import { defineCapabilityConfig } from "@protoboardai/core";
+
+export default defineCapabilityConfig({
+  provider: "@protoboardai/ext-frame-cad",
+  process: "cut", // CNC-routed plate: DXF is the manufacturing export
+  constraints: { clamp_height_mm: 10, pad_height_mm: 0.5, arm_width_mm: 14 },
+});
+```
+
+The config's folder must declare one module (or name it with `module`).
+`process` is `cut` or `machine`; `print` is refused (this provider writes no
+STL or 3MF). A constraint key the provider does not know is a warning.
+
+Declare the generated files on the module so checks and releases see them:
+`withGeometry(def, geometry, plateCadArtifacts({ dir, name, interfaces }))`,
+with `plateCadArtifacts` from `@protoboardai/ext-frame-cad/artifacts` and `dir`
+the folder of the config (body, manifest, per-interface GLBs and DXF in
+`out/`; params and frames in `frame-cad/`). `withGeometry`, `feature`, `own`
+and `procedural` are UHD's pure helpers; the file layout is this extension's.
+
+```bash
+npx protoboard capabilities                                  # the module is bound to @protoboardai/ext-frame-cad ✓
+```
+
+### 3. Generate and export
+
+```bash
+npx protoboard run cad:generate --module <id> --format json  # native design: frame-cad/params.json, frames.json
+npx protoboard run cad:export --module <id>                  # standard outputs: out/ (emptied first)
+npx protoboard run frame-cad --input module=<id>,<id>        # alias: generate + export for the named plate modules (every one without --input)
+```
+
+Every file written is listed, with digests, in the operation record under
+`operations/`. For fixed params and build123d version the output is
+byte-identical, so a re-run that changes files means an input changed.
+`cad:extract` returns the generated frames and the module's artifacts as
+facts; it never edits the module (that is `frame-cad-rebind`, step 4).
+
+`data.rebind` (`data.modules[].rebind` for the alias) is the worklist:
+`signatures` (bound feature signatures that no longer match the generated
+ones) and `frames` (model frame origins that differ from the generated ones).
+Empty lists: nothing to do.
+
+### 4. Bindings and re-binding
+
+Each interface binds to its geometry three ways (UHD geometry artifacts):
+`feature("<id>", signature)` — a named sub-shape in the STEP/GLB with an area /
+centroid / normal signature (D1, primary); `own("<id>")` — the per-interface
+GLB (D2); `procedural("bolt_pattern")` — derived from parameters (D3).
+
+After a change, `protoboard check` reports, and never silently accepts
+(`ext:@protoboardai/ext-frame-cad/cad:check`, one run per module): see
+**Failure handling**.
+
+Review the change first: does the new geometry still mate (stack-ups, prop
+clearance, standoff lengths)? Then re-bind explicitly:
+
+```bash
+npx protoboard run frame-cad-rebind --input module=<id>     # out/ signatures and frame-cad/ frame origins into the module source
+npx protoboard check                                        # 0 errors again
+```
+
+It edits only the module's own `withGeometry(...)` block, lists every change
+(`data.changes`), and leaves an operation record. Commit the source change
+with the regenerated CAD and say why in the commit. Then revisit what depends
+on the moved faces: fastener stacks (**harness-author** step 3), mate gaps,
+documents.
+
+Worked through in the extension's tests: raising the frame's
+`plate_thickness_mm` from 5 to 6 → `FRAME_CAD_STALE` → `cad:generate` (16
+changed bindings: hole areas 201.1 → 241.3 mm², pads and frames up 1 mm;
+`FRAME_CAD_EXPORT_STALE` until exported) → `cad:export` → 8
+`UHD_GEOMETRY_BINDING` + 8 `FRAME_CAD_FRAME_MISMATCH` errors → rebind → 0
+errors. The stack's M3 × 30 then has 1 mm less grip; re-derive it.
+
+### 5. Manufacturing export
+
+`out/body.dxf` holds the profiles to cut, in mm: layer `plate` (outline with
+every through hole: the bottom face of the plate) and one layer per side-clamp
+plate (`clamp_<interface>`, drawn beside the plate). The manifest's
+`manufacturing` block lists layers, quantities (clamp plates × 2) and
+thicknesses, and what is not in the DXF (raised pads). The STEP is the 3D
+reference for the shop and for inspection. Carbon routing specifics:
+[manufacturing](references/manufacturing.md). The Manufacturing Package
+copies these into the unit's `files/mechanical/<module>/` (**release**).
+
+### 6. Mounting hardware (the `cad` capability)
+
+Screws, nuts, standoffs and spacers that are local modules (bought parts
+researched in the project, `parts/local/`; catalog parts bring their own
+CAD) get nominal bodies from their sizes through the `cad` capability, so
+`assemble()` can place them and their mass follows from volume × material.
+Each has a `cad.config.ts` in a folder of its own,
+`parts/local/<id>/cad.config.ts`:
+
+```ts
+export default defineCapabilityConfig({ provider: "@protoboardai/ext-frame-cad", module: "<id>" });   // bought: no process
+```
+
+```bash
+npx protoboard run cad:generate --module <id>     # frame-cad/params.json from the module's sizes
+npx protoboard run cad:export --module <id>       # out/body.step, body.glb, body.manifest.json (volume)
+npx protoboard run hardware-cad [--input module=<id>,<id>]   # alias: both, for every hardware module (or the named ones)
+```
+
+The release traces each module's `out/` to its own `cad:export` record. The
+aliases (`hardware-cad`, `frame-cad`, `harness-cad`) run `cad:generate` and
+`cad:export` for each module and leave those per-module records (their own
+record lists them in `data.steps`), so either way is traced.
+
+A hardware module is tagged `fastener` and one of `screw`, `nut`, `standoff`,
+`spacer`; an interface states `fastener_diameter` and `length`; mechanical
+metadata states `head_diameter_mm` and `head_height_mm` (screw) or `outer_mm`
+(across flats, or a tube's diameter), and `bore_mm` when the maker states a
+nut's, standoff's or spacer's bore (otherwise the nominal bore below). A missing size fails the run; nothing
+is defaulted. Shapes are nominal (plain shank at 0.95 d, no thread form):
+see the [generator reference](references/generator.md). Declare the files with
+`hardwareCadArtifacts({ dir: "parts/local/<id>", name: "<id>" })` from
+`@protoboardai/ext-frame-cad/artifacts`. Export reports each body's volume and
+the one it replaced. A bought part's body is a model of it, not a
+fabrication file: the release lists it as bought (or included), never as a
+fabrication order. Worked example: the quadcopter's `parts/local/*.uhd.ts`
+(built with `parts/local/hardware.ts`), each with `parts/local/<id>/cad.config.ts`.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| This provider or another | Plates and frames whose features are bolt patterns: here. A case or cover around a board: **enclosure-cad**. |
+| `process` | `cut` for routed sheet (DXF required); `machine` for a machined part (STEP). Never `print` with this provider. |
+| A design value | A constraint in `cad.config.ts` with a comment saying why; never UHD metadata, never a hand edit of `frame-cad/`. |
+| Re-bind | Only after reviewing what moved and what depends on it (stack-ups, mate gaps, clearances). |
+| A structure change | Re-derive every fastener stack on the moved faces before moving on. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| Native design (generated; never edit) | `<module dir>/frame-cad/params.json`, `frames.json` |
+| Standard outputs (generated; never edit) | `<module dir>/out/body.step`, `body.glb`, `body.manifest.json`, `body.dxf`, `interfaces/*.glb` |
+| Re-bound module source | `<module dir>/<module>.uhd.ts` (`withGeometry` block, by `frame-cad-rebind`) |
+| Fastener bodies | next to the hardware definitions (the quad: `src/harnesses/cad/`) |
+| Operation records | `operations/` |
+
+## Verification
+
+```bash
+npx protoboard check --format json     # 0 errors; the module's cad:check and protoboard/standard-outputs ran with no findings
+npx protoboard run frame-cad --format json   # every modules[].rebind list empty; git status shows no changed generated file
+```
+
+Then **frame-cad-verify**, by a fresh agent, before anything is cut.
+
+## Failure handling
+
+| Code | Means | Do |
+| --- | --- | --- |
+| `FRAME_CAD_NOT_CONFIGURED` (info, the `frames` check) | A plate module has no `cad.config.ts` | Add one naming `@protoboardai/ext-frame-cad` in its folder |
+| `FRAME_CAD_NOT_A_PLATE` | The config points at a module without `plate_thickness_mm` | Add the plate metadata, or use another `cad` provider |
+| `FRAME_CAD_NOT_GENERATED` | No generated CAD yet | `run cad:generate --module <id>`, then `cad:export` |
+| `FRAME_CAD_STALE` (warning) | Interfaces or design values changed since generation | `run cad:generate`, then `cad:export`; review the re-bind list |
+| `FRAME_CAD_EXPORT_STALE` (warning) | `out/` was exported from other parameters than `frame-cad/params.json` | `run cad:export` |
+| `FRAME_CAD_FRAME_MISMATCH` (error) | A model frame differs from the generated plate | Review; `run frame-cad-rebind` if the new plate is right; check dependent stack-ups |
+| `FRAME_CAD_UNKNOWN_INTERFACE` | Generated frames name an interface the module no longer has | Regenerate |
+| `FRAME_CAD_FRAME_MISSING` | Generated geometry for an interface without a model frame | Re-bind |
+| `UHD_GEOMETRY_BINDING` (error) | "changed since binding; re-bind explicitly" | Review, then `run frame-cad-rebind` |
+| `HARDWARE_CAD_PARAMS`, `HARDWARE_CAD_STALE`, `HARDWARE_CAD_EXPORT_STALE` | A fastener module lacks a size, changed since its body was made, or its `out/` is older than its params | Add the size from the listing; `run cad:generate` then `cad:export --module <id>` |
+| `HARDWARE_CAD_NOT_CONFIGURED` (info) | A local fastener module has no body and no `cad.config.ts` | Add `parts/local/<id>/cad.config.ts` naming this provider |
+| `PB_CAPABILITY_CONSTRAINT_UNKNOWN` | A constraint this provider does not know | Check the name in the [generator reference](references/generator.md) |
+| `PB_OUTPUT_MISSING` (`body.dxf`) | `process: cut` without a DXF | Re-export; check the plate has profiles to cut |
+| `run` refused: tool `python-build123d` missing | No `cad` runtime | `npx protoboard tools install cad` |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).
+
+## Hard rules
+
+1. Never edit generated files (`frame-cad/`, `out/`); change the module
+   (interfaces, frames) or its `cad.config.ts` constraints and regenerate.
+2. Never re-bind to make a check pass without reviewing what moved.
+3. Keep the frames in the model: they are how every mating part is placed.
+4. A generated plate is geometry, not a strength, stiffness or
+   manufacturability claim; those need their own checks or tests.

package/skills/frame-cad/references/generator.md

@@ -0,0 +1,110 @@
+# Generator reference (`@protoboardai/ext-frame-cad`)
+
+Files: `lib/params.ts` (model + constraints → params), `py/frame_cad.py`
+(params → CAD), `lib/plate.ts` (the `cad` capability's generate, export,
+extract and check), `ops/cad.ts` (their entries), `ops/frame-cad.ts` (the
+alias), `ops/rebind.ts`, `checks/frames.ts`; for hardware,
+`lib/hardware.ts`, `py/hardware_cad.py`, `ops/hardware-cad.ts`,
+`checks/hardware.ts`; `lib/artifacts.ts` (the files both write, as UHD
+artifacts: `cadArtifacts`, `plateCadArtifacts`, `hardwareCadArtifacts`,
+exported as `@protoboardai/ext-frame-cad/artifacts`).
+
+`frame_cad.py` is the merged frame generator. UHD's library held the first
+one, `library/cad/py/frame.py` with `common.py`, which built the reference
+quadcopter's plates from hard-coded positions; `frame_cad.py` places the same
+features (core holes, raised pads on arms, side clamps, slots) from any
+module's bolt patterns, and generates the quadcopter's frame and top plate
+from its interfaces. For the quadcopter frame, all eight interface features
+have the same signatures as frame.py's (compared manifest to manifest); the
+body differs in outline details, so its volume, and the mass computed from
+it, is 57 154 mm³ against frame.py's 59 863 mm³. UHD's `frame.py` and `hardware.py` were removed from UHD
+; `hardware.py` became `hardware_cad.py` below.
+
+## Which modules
+
+Local definitions used by the project whose mechanical domain metadata has
+`plate_thickness_mm`, each with a `cad.config.ts` naming this provider. The
+capability operations take one module (`--module <id>`); the `frame-cad`
+alias takes every plate module, or `--input module=a,b`, and refuses a
+plate module with no config. A catalog definition is refused (derive a local
+variant). Bolt-pattern interfaces without a frame, patterns missing
+`hole_spacing` / `fastener_diameter`, and frames that are neither vertical
+nor horizontal fail the run with the reason.
+
+## Constraints in `cad.config.ts` (all optional, mm)
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `outline_mm` | extent of the core holes and clamps + `margin_mm` | `{ x: [min, max], y: [min, max] }` of the core plate |
+| `margin_mm` | 3 | outline margin around core holes and clamp plates |
+| `corner_radius_mm` | 1.5 | fillet on vertical edges (skipped if the kernel rejects it) |
+| `arm_width_mm` | 14 | arm from the core to each pad hub |
+| `arm_slot_width_mm` | 5 | lightening slot down each arm, outside the core and ≥ 4 mm from hub and core; 0 = none |
+| `hub_extra_mm` | 1 | hub disc radius beyond the pad |
+| `pad_margin_mm` | 3 | pad radius beyond the pattern (circle: spacing/2 + 3) |
+| `pad_height_mm` | 0.5 | raised pad height (its top is the mating face) |
+| `pad_center_relief_mm` | 3.5 | centre hole radius in circle pads (shaft / circlip) |
+| `pads` | circle patterns facing +Z | interface ids to build as raised pads |
+| `hole_clearance_mm` | 0.1 | radial clearance (M3 → Ø 3.2) |
+| `clamp_wall_mm` | 2 | side-plate thickness |
+| `clamp_margin_mm` | 4 | side-plate width = spacing + margin; top = centre + spacing/2 + margin |
+| `clamp_height_mm` | frame origin z − thickness | clamp centre above the plate top; state it explicitly so a thickness change moves the clamp with the plate |
+| `slots_mm` | none | extra rectangular cut-outs `[{ center: [x, y], size: [dx, dy] }]` (strap slots) |
+
+The quad frame sets `clamp_height_mm: 10, pad_height_mm: 0.5, arm_width_mm: 14`;
+the top plate sets its outline (covers the battery), `corner_radius_mm: 4` and
+two strap slots.
+
+## Params file (`frame-cad/params.json`, schema `protoboard.frame-cad.params/v0`)
+
+`plate` (thickness and the values above) and `interfaces[]`: `id`, `shape`,
+`spacing`, `spacing_y`, `hole_count`, `fastener_d`, `placement`
+(`holes_top | holes_bottom | pad | clamp`), `origin` (x, y), `normal`,
+`x_axis`, `symmetry`, `height`, `holes` (world x, y). `name` is the module
+id; it labels the STEP compound and seeds the DXF GUIDs. It is written by
+`cad:generate` and read by `cad:check`: if recomputing it from the model and
+constraints gives something different, the CAD is stale.
+
+## Outputs
+
+The generator writes `<name>.*` into a scratch folder; generate keeps the
+frames, export copies the rest to the standard names.
+
+| File | Content |
+| --- | --- |
+| `frame-cad/frames.json` | interface → `{ origin, normal, xAxis, symmetryDeg }` of the generated geometry (native design, with `params.json`) |
+| `out/body.step` | compound: `plate`, `pads`, `clamps`, and one named sub-shape per interface feature (thin solid over its faces) |
+| `out/body.glb` | the same, tessellated (glTF metres, Y-up) |
+| `out/body.manifest.json` | `features: { <interface>: { area_mm2, centroid, faces, normal? } }`, tool, toolVersion, generator, params, `sourceDigest` = sha256(generator + params), `manufacturing`, and `exportedFrom` (the params file and its digest, for the export-stale check) |
+| `out/body.dxf` | profiles: layer `plate`, layers `clamp_<interface>` |
+| `out/interfaces/<id>.glb` | one file per interface feature (D2) |
+
+Feature selection: hole patterns → the plate's cylindrical hole walls at the
+pattern's positions and radius; pads → the pad's top face; clamps → the two
+inner faces of the side plates. Signatures are rounded to 0.001.
+
+Determinism: the STEP header time and the DXF timestamps and GUIDs are fixed
+and the interpreter runs with `PYTHONHASHSEED=0`, so equal inputs give equal
+bytes with the same build123d version.
+
+## Hardware (`hardware-cad`)
+
+Params file `<name>.params.json`, schema `protoboard.hardware-cad.params/v0`:
+`part: { kind, diameter, length, head_diameter, head_height, outer }` (null
+where the kind does not use it), read by `lib/hardware.ts` from the module
+(see SKILL.md §5).
+
+| Kind | Body (origin, +Z) |
+| --- | --- |
+| `screw` | head cylinder `head_diameter` × `head_height` below z = 0 with a hex socket (circumradius 0.45 d, 0.6 × head height deep); shank 0.95 d × `length` above |
+| `nut` | hex prism, `outer` across flats, bore d, `length` high |
+| `standoff` | hex prism, `outer` across flats, bore 0.85 d, `length` long |
+| `spacer` | tube, `outer` diameter, bore d + 0.4, `length` long |
+
+A stated `bore_mm` (the params' `bore`) replaces the nominal bore of a nut,
+standoff or spacer.
+
+Outputs: `<name>.step` (one body labelled with the kind), `<name>.glb`,
+`<name>.manifest.json` (`volume_mm3`, `bodies`, empty `features`, tool,
+generator, params, `sourceDigest` = sha256(generator + params)). One process
+per module and a fixed STEP time, so equal inputs give equal bytes.

package/skills/frame-cad/references/manufacturing.md

@@ -0,0 +1,42 @@
+# Manufacturing export: CNC-routed carbon plates
+
+The generator produces geometry; the shop needs profiles, a material and
+thickness, quantities, and tolerances. Send:
+
+| File | Use |
+| --- | --- |
+| `out/body.dxf` layer `plate` | 2D toolpath source: outline + every through hole, mm, 1:1. Qty 1 per frame. |
+| `out/body.dxf` layers `clamp_<interface>` | side-clamp plates, drawn beside the plate. Qty 2 each (manifest `manufacturing.quantities`). |
+| `out/body.step` | 3D reference for the shop and for incoming inspection. |
+| a drawing or note | material (e.g. 3K twill carbon, stated grade), thickness per layer (`manufacturing.thickness_mm`), hole tolerance, edge finish (chamfer/sand edges; carbon edges fray and cut wires), quantity, revision. |
+
+Before sending:
+
+1. **Thickness exists.** Carbon sheet comes in fixed thicknesses (e.g. 1.5, 2,
+   3, 4, 5, 6 mm depending on the supplier). Check the stated thickness is a
+   stock item from the supplier you will use and cite the listing; otherwise
+   change `plate_thickness_mm` and regenerate (then re-bind and re-derive the
+   fastener stacks).
+2. **Minimum features.** Router bit diameter (commonly 1.5–3 mm for carbon)
+   sets the smallest inside radius and slot width: slots narrower than the bit
+   cannot be cut, and inside corners get the bit radius. The quad's 3 mm strap
+   slots and 5 mm arm slots need a bit of 3 mm or less. Holes below ~1.5× the
+   plate thickness in diameter are better drilled than routed; say so.
+3. **Hole sizes.** Holes are fastener + 2 × `hole_clearance_mm` (M3 → Ø 3.2,
+   M2 → Ø 2.2). A shop's routing tolerance can eat that clearance; for press
+   or tight fits change `hole_clearance_mm` in the module's `cad.config.ts`,
+   not in the DXF.
+4. **Edge distance.** A hole closer than about one diameter to an edge in
+   carbon risks breakout; check the stack and standoff holes against the
+   outline (**frame-cad-verify**).
+5. **What the DXF leaves out.** The raised motor pads (0.5 mm) are a modelling
+   device giving each motor a distinct mating face; a flat carbon plate has
+   none. Either accept the flat face (bindings stay; the pad is 0.5 mm of
+   stack-up to remove from the motor screw arithmetic) or make them as shims.
+   Clamp plates need a joint to the plate (tabs and slots, or brackets) that
+   the generator does not draw yet: agree it with the shop and record it.
+
+Record the order (supplier, quote, material, thickness, file digests from the
+operation record) against the release (**release**), and inspect the parts
+on arrival against the STEP and the hole patterns (the test plan's
+`frame-inspection`).

package/skills/frame-cad-verify/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: frame-cad-verify
+description: Verify a frame-cad structure before it is cut — bindings and frames clean, regeneration reproducible, every mating part placed on the generated faces, and the DXF manufacturable (hole edge distance, webs, router-bit limits, stock thickness) — and record the findings. Run by a fresh agent after frame-cad and before any manufacturing order or release; never edits the model.
+---
+
+# Frame CAD verify
+
+## Purpose
+
+Prove that a generated plate is what the model says, reproducible from it,
+assembles with its mating parts, and can be cut. Use it after **frame-cad**,
+after any change to a plate's interfaces or design values, and before a
+release puts its DXF in the Manufacturing Package. In **build-a-project** it
+closes stage 6 for structures. It records findings; it never edits the model
+or the CAD.
+
+## Inputs
+
+| Input | Where | From |
+| --- | --- | --- |
+| Plate modules and their configs | `src/modules/<module>/<module>.uhd.ts`, `cad.config.ts` | **frame-cad** |
+| Generated CAD | `<module dir>/frame-cad/`, `<module dir>/out/` | **frame-cad** |
+| The router bit and stock | the shop's bit diameter and sheet thicknesses | the person or the chosen fabricator's published capability |
+| Fastener stacks on the plates | `src/harnesses/` | **harness-author** |
+| The `cad` runtime | `npx protoboard doctor` shows `python-build123d` ✓ | `npx protoboard tools install cad` |
+
+## Steps
+
+### 1. Automated
+
+```bash
+npx protoboard doctor                                   # python-build123d available
+npx protoboard check --format json                      # 0 errors; each plate's cad:check and standard-outputs ran with 0 findings; geometryBindings ran
+npx protoboard run frame-cad --format json              # (generate + export of every plate) every modules[].rebind list empty
+git status --short src/                                 # no generated file changed: the committed CAD is what the model produces
+"${PROTOBOARD_PYTHON:-.protoboard/tools/cad/bin/python}" node_modules/@protoboardai/ext-frame-cad/skills/frame-cad-verify/scripts/dxf_report.py <module dir>/out/body.dxf --bit <router bit mm>
+```
+
+A file that changes on regeneration means the committed CAD was not produced
+from the committed model: find out why before anything else.
+
+`dxf_report.py` prints each layer's extent, holes by diameter, the smallest
+hole-to-edge distance and web, and flags: a hole closer to an edge than its
+diameter (breakout risk in carbon), webs under 1 mm, straight cut-outs
+narrower than the bit, and holes smaller than the bit (to be drilled; noted,
+not failed). Exit 1 on the hard rules.
+
+### 2. Review
+
+1. **Interfaces.** Each plate interface still mirrors its mating part's
+   interface (spacing, fastener, pattern shape) and cites it.
+2. **Placement.** `protoboard check` placed every mating part through the
+   generated frames (no `UHD_ASSEMBLY`); look at the assembly in the viewer
+   (`npx protoboard dev --open`, stop it with `Ctrl+C`) or the documents if
+   available: motors on pads, props clear (brief: ≥ 5 mm), stack centred,
+   camera between its plates.
+3. **Stack-ups.** Every fastener stack on this structure uses the current
+   plate thickness (**harness-verify**).
+4. **Manufacturing.** Thickness is a stock item of the chosen supplier;
+   minimum features fit the bit; what the DXF leaves out (raised pads, clamp
+   joints) has a decision (frame-cad `references/manufacturing.md`).
+
+### 3. Calibrate on the reference quadcopter
+
+Running the report on `examples/quadcopter-5in` (3 mm bit) finds, in the
+geometry inherited from the UHD generator:
+
+- the 16 motor-pad holes sit 2.39 mm from the hub edge (hub radius 12 mm,
+  holes on an 8 mm radius, Ø 3.2): under one diameter;
+- the top plate's four standoff holes are 2.4 mm from its long edges
+  (y ± 24 in a 56 mm plate);
+- each camera side plate's lower hole is 0.9 mm from the plate's bottom edge
+  (hole 2 mm above the frame's top face);
+- the M2 holes (Ø 2.2) are below a 3 mm bit: drill them.
+
+None of these moves an interface; each is a design decision (`hub_extra_mm`,
+the top plate's `outline_mm`, the clamp height or margin) for the design
+owner, with a regenerate + verify after.
+
+### 4. Write the findings
+
+`docs/reviews/frame-cad-verify-<YYYY-MM-DD>.md`: the automated results
+(commands, exit codes, report JSON) and findings
+`{ id, severity, module, layer/feature, finding, evidence, fix }`.
+
+## Decision points
+
+| Decision | Rule |
+| --- | --- |
+| Severity | **blocker** for anything that cannot be made or will not assemble; **major** for a margin under the rule (hole under one diameter from an edge); **minor** otherwise. |
+| A hole smaller than the bit | Not a failure: noted to be drilled. |
+| A finding that needs a design change | The fix names the constraint to change; the design owner decides and regenerates. |
+
+## Outputs
+
+| Output | Where |
+| --- | --- |
+| The verification report | `docs/reviews/frame-cad-verify-<YYYY-MM-DD>.md` |
+
+## Verification
+
+The report lists every plate module, the exit code of each step-1 command,
+and the `dxf_report.py` JSON per DXF; every finding cites a layer or feature
+and its evidence. `git status --short src/` was clean after regeneration.
+
+## Failure handling
+
+| Code or symptom | Means | Do |
+| --- | --- | --- |
+| A generated file changed on regeneration | The committed CAD is not the model's output | Stop; find the changed input (config, interfaces, tool version) before reviewing |
+| `FRAME_CAD_STALE`, `FRAME_CAD_EXPORT_STALE` | The CAD is behind the model | Hand back to **frame-cad** to regenerate; do not review stale CAD |
+| `FRAME_CAD_FRAME_MISMATCH`, `UHD_GEOMETRY_BINDING` | Model and CAD disagree | Finding (blocker) until the author reviews and re-binds |
+| `UHD_ASSEMBLY` | A mating part does not seat | Finding (blocker) |
+| `dxf_report.py` exit 1 | A hard manufacturing rule failed | Finding per flagged item, with the constraint to change |
+| `doctor` shows `python-build123d` ✗ | No runtime to regenerate or read the DXF | `npx protoboard tools install cad` |
+
+Every other code: **system-compose** [diagnostic codes](../system-compose/references/diagnostic-codes.md).