---
name: solidcraft-3d-builder
description: Parametric 3D CAD modeling, STEP/3MF assembly packaging, exact B-rep interference/clearance analysis, and Vulkan GPU rendering skill for any CAD project (<ProjectName>) using solidcraft-cli. Always checks .cad-tools.json (or asks the user for the solidcraft-cli path) and builds parts and assemblies step-by-step with user parameters and named timeline features.
---

# SolidCraft Parametric 3D CAD, 3MF & GPU Render Skill (`solidcraft-3d-builder`)

Uses `solidcraft-cli` (configured via `.cad-tools.json` or provided by the user in Step 0) to build `.solidcraft` projects for **any CAD project (`<ProjectName>`)** with **100% traceable step-by-step parametric feature timeline history**, editable user parameters, face-tagged `.3mf` slicer files, B-rep clearance/interference audits, and studio renders.

---

## 0. Step 0: Resolve `solidcraft-cli` Path via `.cad-tools.json` or User Prompt

**Do NOT search the filesystem for `solidcraft-cli`.**
1. Check `.cad-tools.json` in the workspace root for `"solidcraft_cli"` (or check if the user already provided the path in the conversation/project `AGENTS.md`).
2. If not yet configured, ask the user (or have the Designer / QA Inspector agent ask via `ask_question`) whether `SolidCraft` is available and what path/command to use, then save it in `.cad-tools.json`.

---

## 1. Mandatory Core Rule: Step-by-Step Parametric Feature Tree & User Parameters

> **CRITICAL RULE: NEVER IMPORT BAKED `.step` FILES FOR DESIGNED PARTS**:
> You MUST **always** build `.solidcraft` parts and assemblies **step-by-step from scratch** using native `solidcraft-cli` parametric commands (`parameters.add`, `component.create`, `sketch.create`, `sketch.line`, `sketch.circle.*`, `sketch.rectangle.*`, `sketch.finish`, `solid.extrude`, `solid.revolve`, `solid.box`, `solid.cylinder`, `solid.fillet`, `solid.chamfer`, `plastic.*`, `sheet.*`).
> **Do NOT use `file.insert_step` to import static/dumb solids for designed parts.** Every action taken to construct a part must be recorded in the `.solidcraft` feature timeline and driven by named user parameters so the user can open any `.solidcraft` file and adjust hole sizes, fit allowances, or thicknesses directly in SolidCraft without re-running external scripts.

### 3 Requirements for Every `.solidcraft` Document
1. **Parametric User Variables (`parameters.add`) for Every Tunable Dimension & Fit Allowance**:
   - Define all slip-fit bore radii, counterbore radii/depths, structural web thicknesses, spotface radii, and joint clearance allowances at the start of the script using `parameters.add`:
     ```json
     {
       "command": "parameters.add",
       "params": {
         "name": "spool_bore_r",
         "expression": "25.8 mm",
         "comment": "Slip-fit mounting barrel bore radius (51.6 mm diameter, +0.8 mm radial clearance allowance)"
       }
     }
     ```
   - Reference parameter names directly as string expressions in feature commands (e.g., `"radius": "spool_bore_r"`, `"distance": "side_arm_w"`, `"height": "front_leg_w"`).
2. **Standard CAD Feature Naming Convention in the Timeline**:
   - Always pass an explicit, technical `"name"` on every `component.create`, `sketch.create`, `solid.extrude`, `solid.cylinder`, `solid.box`, `solid.fillet`, and `solid.chamfer` command using standard CAD nomenclature:
     - `Sketch_<Part>_<Feature>` (e.g., `Sketch_B_L_Cantilever_Web`, `Sketch_B_L_Truss_Lightening_Pocket`, `Sketch_B_L_Return_Flange_Cleat`)
     - `Extrude_<Part>_<Feature>` (bosses, webs, return flanges, dovetail tenons)
     - `Cut_<Part>_<Feature>` (through-bores, counterbores, spotfaces, rabbet reliefs, blind dovetail mortises, truss pockets)
3. **Standard Project Deliverables (`<ProjectName>`)**:
   - `CAD/SolidCraft/<PartName>.solidcraft` & `CAD/SolidCraft/<PartName>_Script.json` (each individual printable part with its full step-by-step feature timeline and user parameters)
   - `CAD/SolidCraft/<ProjectName>_Assembly.solidcraft` & `CAD/SolidCraft/<ProjectName>_Full_Assembly.solidcraft` (multi-component assemblies built step-by-step using `component.activate` `"root"` + `component.create`)
   - `CAD/3MF/<PartName>.3mf` & `CAD/3MF/<ProjectName>_Assembly.3mf` (`"format": "3mf-tagged"` slicer packages with B-rep face tags and PBR colors)
   - `CAD/SolidCraft/<ProjectName>_BRep_Inspection.json` (full step-by-step execution log + `inspect.interference` and `inspect.clearance` results)
   - `CAD/SolidCraft/<ProjectName>_Studio_Render.png` & `CAD/SolidCraft/<ProjectName>_Snapshot_<View>.png` (hardware Vulkan GPU renders)

---

## 2. Translating User Descriptions into Technical CAD Features in SolidCraft

| User Request / Intent | Technical CAD Feature Name | SolidCraft Feature Construction Pattern |
| :--- | :--- | :--- |
| *"Reverse L notch to clear an overhanging lid/cover"* | **Stepped Edge Rabbet Relief (`Rabbet_Relief`)** | Profile step in the primary `YZ` sketch plus a boolean `solid.box` (`"operation": "cut"`, `"name": "Cut_<Part>_Top_Cover_Rabbet_Relief"`) removing the upper-rear interference zone while preserving the lower **Undercut Datum Contact Toe**. |
| *"Make the boss flush with the arm so it lies flat on the bed"* | **Coplanar Flush Boss (`Flush_Spool_Boss`)** | Extrude the side web and the coaxial `solid.cylinder` boss from the exact same datum plane `x0` with identical `"distance"` / `"height": "side_arm_w"` (`"operation": "join"`) so the outer plane has **zero stickout** and serves as the flat print-bed datum. |
| *"Wrap around the corner so it can't rotate"* | **Orthogonal Anti-Rotation Return Flange (`Return_Flange`)** | Create a `YZ` sketch at the outer side datum plane spanning the front bearing pad and extrude across the orthogonal front pillar width (`"distance": "front_leg_w"`, `"operation": "join"`). |
| *"Hook over from the top"* | **Interlocking Cleat Tang & Shrouded Clevis Saddle (`Cleat_Tang` / `Clevis_Saddle`)** | Model an upward **Male Cleat Tang** + **Rear Receiver Channel** + **Lower Bearing Shoulder** on the lower return flange, and a mating **Female Clevis Saddle** + **Axial Retention End-Cheeks** on the upper cantilever rail. |
| *"Rest on a lip with drop-in dovetails (no separate bowties)"* | **Shouldered Half-Lap Dovetail Ledger (`Blind_Dovetail_Mortise` / `Dovetail_Tenon`)** | Cut **Blind (Stopped) Female Dovetail Mortises** (`Sketch_<Part>_Dovetail_Mortise` + `solid.extrude` `"cut"`) into the top half of a solid lower **Bearing Ledger**, and extrude **Integral Male Dovetail Tenons** (`0.20 mm` clearance allowance) on the mating spreader beam ends. |
| *"Open up a tight hole by 0.5 mm"* | **Slip-Fit Bore Allowance (`Slip_Fit_Bore` + `Flange_Counterbore`)** | Update the user parameter `spool_bore_r` (or `mount_bore_r`) via `parameters.add` / `parameters.set` and cut with coaxial `solid.cylinder` features (`Cut_<Part>_Flange_Counterbore` + `Cut_<Part>_Barrel_Bore`). |

---

## 3. CLI Reference & Coordinate Plane Mapping

1. **Step-by-Step Native Parametric Modeling (`run`)**:
   ```bash
   <solidcraft_cli_path> run <script.json> --results --json-out <report.json>
   ```
   - **2D Sketches on Custom Planes (`sketch.create`)**:
     - **`YZ` Plane at $X = x_0$** (2D `(u, v)` maps 1:1 to world `(Y, Z)`, extrudes along $+X$):
       `{"origin": [x0, 0.0, 0.0], "x_dir": [0.0, 1.0, 0.0], "y_dir": [0.0, 0.0, 1.0]}`
     - **`XY` Plane at $Z = z_0$** (2D `(u, v)` maps 1:1 to world `(X, Y)`, extrudes along $+Z$):
       `{"origin": [0.0, 0.0, z0], "x_dir": [1.0, 0.0, 0.0], "y_dir": [0.0, 1.0, 0.0]}`
     - **`XZ` Plane at $Y = y_0$** (2D `(u, v)` maps 1:1 to world `(X, Z)`):
       `{"origin": [0.0, y0, 0.0], "x_dir": [1.0, 0.0, 0.0], "y_dir": [0.0, 0.0, 1.0]}`
2. **Instant B-Rep & Timeline Audit (`eval` / `inspect`)**:
   ```bash
   <solidcraft_cli_path> eval CAD/SolidCraft/<part_or_assembly>.solidcraft
   ```
   Verify `"params"`, `"sketches"` (`"status": "solved"`), `"timeline"` (`"error": null`), and `"bodies"`.
3. **In-Place Parameter Revision Without Re-Engineering**:
   ```json
   {
     "commands": [
       {"command": "file.open", "params": {"path": "CAD/SolidCraft/<PartName>.solidcraft"}},
       {"command": "parameters.set", "params": {"name": "spool_bore_r", "expression": "26.0 mm"}},
       {"command": "timeline.rebuild", "params": {}},
       {"command": "file.export", "params": {"path": "CAD/3MF/<PartName>.3mf", "format": "3mf-tagged"}},
       {"command": "file.save", "params": {"path": "CAD/SolidCraft/<PartName>.solidcraft", "preview": true}}
     ]
   }
   ```