CAD Stage (build123d Workbench)

One project scene, many parts. Each part is one Python file; the scene is rebuilt from source on every change and you MUST look at the rendered PNGs before claiming an edit worked.

File convention

• cad/parts/<part_id>.py — defines a module-level result (a build123d Part/Compound). Optional PLACE = ((x, y, z), (rx, ry, rz)) default placement.
• cad/scene.json — placement overrides: {"parts": {"<part_id>": {"position": [x,y,z], "rotation": [rx,ry,rz]}}}. Placement lives here, NOT as offsets inside part files: model each part centered in its own frame.

Build & render loop

<repo>/.venv/bin/python <skill_dir>/scripts/cad_build.py <project>/cad            # build all, export STEP+GLB+PNGs
<repo>/.venv/bin/python <skill_dir>/scripts/cad_build.py <project>/cad --part lid # rebuild one part (faster feedback)
<repo>/.venv/bin/python <skill_dir>/scripts/cad_build.py <project>/cad --stl      # also export per-part STL for printing

Outputs land in cad/exports/: assembly.step, assembly.glb, view-iso.png, view-top.png, view-front.png, view-right.png (+ <part>.stl with --stl).

The loop: edit one part file → rebuild → Read the PNG views → make the smallest next correction. Never infer success from the script exiting 0; the image is the evidence. If a view is ambiguous, open viewer/index.html (in the plugin repo) with the GLB for an interactive check or a browser screenshot.

Live workbench: for a Replicator-style side-by-side experience, start <repo>/.venv/bin/python <repo>/workbench/serve.py <project_dir> (background) and open http://localhost:7377 in a browser pane. It tabs PRD / BOM / PCB previews / interactive 3D with a part outliner, and auto-refreshes on every rebuild.

Native Replicator projects (scripts/replicator_scene_build.py)

Projects created by the original Replicator app keep enclosure sources under design/<name>-enclosure/source/ as part scripts written in Replicator's injected DSL (param(name, default), publish(id, shape, label), plus bare build123d names) with a scene.json (schemaVersion 1: targets/objects/parameters). Build them unmodified:

<repo>/.venv/bin/python <skill_dir>/scripts/replicator_scene_build.py \
  <project>/design/<name>-enclosure/source/scene.json [--only id1,id2] [--views iso,top,front]

It replays the same namespace contract as Replicator's cad-workbench bootstrap, applies scene transforms (positionMm/rotationDeg), and writes assembly.step/assembly.glb/view-*.png into design/<name>-enclosure/exports/, which the live workbench picks up automatically. Parameter overrides in scene.json parameters win over param() defaults, exactly like the original.

Measurement (scripts/cad_inspect.py)

<repo>/.venv/bin/python <skill_dir>/scripts/cad_inspect.py <project>/cad            # bbox/volume/validity per part
<repo>/.venv/bin/python <skill_dir>/scripts/cad_inspect.py <project>/cad --pairs    # pairwise clearance + collision detection
<repo>/.venv/bin/python <skill_dir>/scripts/cad_inspect.py <project>/cad --pair body lid

Open equivalent of cad.inspect: reports exact min distances and boolean interference volumes (verdict: COLLISION | touching | clear). Run --pairs before claiming parts fit; a PNG can hide a 0.3 mm interference that this catches numerically.

Modeling rules (see references/build123d-notes.md for API)

• Algebra mode preferred: part = Box(20, 30, 10) - Pos(0, 0, 3) * Box(16, 26, 10).
• Millimeters everywhere. Keep parts parametric: dimensions as named constants at the top of the file.
• Wall thickness for FDM enclosures: >= 1.6mm (2 perimeters at 0.4mm nozzle x2). Fillets last; small radii before large radii when chaining.
• When the product has a PCB release, import pcb/releases/<n>/ geometry facts (board size, mounting holes, connector positions) as constants with a comment naming the release. Openings get 0.3-0.5mm clearance per side; snap-fit lips 0.15-0.25mm.
• Printed screw joints: use the screwjoint kit (section below); never hand-model pilot holes or threads.
• Standard purchasable parts (bearings, rails, inserts): model only their envelope + interface unless exact STEP is available; record identity in cad/part-plan.json.

Deep know-how (read before non-trivial modeling)

The original Replicator CAD knowledge base is vendored verbatim at <repo>/reference/replicator-original/me/build123d-core/references/: objects.md, operations.md, tips.md, joints.md, import-export.md, topology-selection.md, locations.md, assemblies.md, and especially dfm-rules.md (walls/overhangs/bosses/snaps with exact numbers), pitfalls.md (API mistakes table), connectors.md (port cutout dimension table: USB-C SlotOverall(9.5, 3.8), tolerances, lip/groove numbers). Read the relevant file before modeling that kind of feature.

Printed screw joints (mandatory kit)

Any screw into a 3D-printed part uses the vendored MIT screwjoint package — never hand-model pilot holes or threads:

PYTHONPATH=<repo>/reference/replicator-original/cad-scripts/packages <repo>/.venv/bin/python your_part_build.py

from screwjoint import make_screw_joint_v1, ScrewJointNotApplicableV1
joint = make_screw_joint_v1(size="M3", at=Location(...), through=[(lid, 2.0)],
                            engage_depth=2.5 * 3, into=base, material="PLA")
lid = lid - joint.through_cuts[0]
base = base + joint.bosses - joint.engage_cuts

M2-M4 → self-forming polygon holes; M5-M8 → material-compensated printed ISO thread. On ScrewJointNotApplicableV1, classify the joint free and model explicitly. Kit contract: <repo>/reference/replicator-original/me/build123d-libs/kits/printed-screw-joint-v1/KIT.md.

Board models & standard parts

• Real STEP models for common dev boards: see <repo>/seeds/board-models.json (two XIAO models vendored in <repo>/seeds/board-models/; others carry a sourceArchiveUrl for download). Import them as parts instead of modeling board placeholders when exact fit matters.
• For purchasable STEP parts (McMaster/vendor models), load the step-parts skill.
• Fasteners/bearings via bd_warehouse, V-slot rails/T-nuts via bd_vslot (both installed in the venv). API references: <repo>/reference/replicator-original/me/build123d-libs/references/.

Print preparation

<repo>/.venv/bin/python <skill_dir>/scripts/plate_prepare.py <project>/cad --parts body lid --printer x1c

Bin-packs the chosen parts (in their authored orientation, bottoms on Z=0), verifies they fit the printer plate (presets: x1c/x1e/p1s/p1p/a1 256³, a1mini 180³, h2s 340x320x340, h2d 325x320x325, or --plate WxDxH), and writes one unsliced exports/plate.3mf for the slicer. --stl on cad_build.py still exports per-part STLs. Verify printability (overhangs, bed contact) in the PNG views first.