LightWork3D/docs/superpowers/plans/2026-05-26-terminal-block-model-implementation.md

# DIN Rail Terminal Slice Model Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Generate a reusable single-slice DIN rail terminal model as both `.FCStd` and `.step`, with FreeCAD template terminal LCS semantics.

**Architecture:** Add a focused FreeCAD Python generator under the asset directory. The script creates simple parametric solid geometry, adds two template terminal LCS objects with the existing QET terminal semantic properties, saves an FCStd template, exports STEP geometry, and writes a small metadata report for verification.

**Tech Stack:** FreeCADCmd, FreeCAD Python API, Part workbench primitives, Import/ImportGui STEP export fallback, plain Markdown documentation.

---

### Task 1: Asset Directory and Generator

**Files:**
- Create: `data/examples/qet_terminal_block/create_qet_terminal_slice.py`
- Create: `data/examples/qet_terminal_block/README.md`

- [ ] **Step 1: Create the generator script**

Use `apply_patch` to create `data/examples/qet_terminal_block/create_qet_terminal_slice.py`. The script must:

- Build dimensions in millimeters: width `5.2`, depth `42.0`, height `36.0`.
- Create visible geometry pieces for the green body, white top terminal area, black bottom terminal area, light green window, DIN rail slot, and two screw/contact details.
- Add two `Part::LocalCoordinateSystem` objects named `Terminal_Top` and `Terminal_Bottom`.
- Set these properties on both terminal LCS objects: `Role`, `CanWire`, `QetTemplateSlotName`, `QetTerminalLabel`, `QetTerminalType`.
- Avoid engineering binding properties: `QetProjectUuid`, `QetElementUuid`, `QetTerminalUuid`, `QetInstanceId`.
- Save `qet_terminal_slice.FCStd`.
- Export `qet_terminal_slice.step`.
- Write `qet_terminal_slice_report.json` with dimensions, output paths, and terminal property values.

- [ ] **Step 2: Create the README**

Use `apply_patch` to create `data/examples/qet_terminal_block/README.md` explaining:

- `qet_terminal_slice.FCStd` is the formal reusable FreeCAD template.
- `qet_terminal_slice.step` is geometry-only exchange output.
- The slice spacing is `5.2 mm` along X for future terminal block arrays.
- `Terminal_Top` and `Terminal_Bottom` are template terminal LCS objects.

### Task 2: Generate the Model

**Files:**
- Generate: `data/examples/qet_terminal_block/qet_terminal_slice.FCStd`
- Generate: `data/examples/qet_terminal_block/qet_terminal_slice.step`
- Generate: `data/examples/qet_terminal_block/qet_terminal_slice_report.json`

- [ ] **Step 1: Run the FreeCAD generator**

Run with the registered FreeCAD runtime:

```powershell
$runtime = Get-Content -LiteralPath 'C:\Users\ng123\AppData\Local\QETDeps\runtime.json' -Raw | ConvertFrom-Json
$env:QET_FREECAD_RUNTIME_JSON = 'C:\Users\ng123\AppData\Local\QETDeps\runtime.json'
& $runtime.freecad_python 'D:\LightWork3D\data\examples\qet_terminal_block\create_qet_terminal_slice.py'
```

Expected: command exits `0`, and prints the generated FCStd, STEP, and report paths.

- [ ] **Step 2: Inspect output files**

Run:

```powershell
Get-ChildItem -LiteralPath 'D:\LightWork3D\data\examples\qet_terminal_block' | Select-Object Name,Length
```

Expected: `.FCStd`, `.step`, and `.json` files exist with non-zero sizes.

### Task 3: Verify Template Semantics

**Files:**
- Read: `data/examples/qet_terminal_block/qet_terminal_slice_report.json`
- Read: `data/examples/qet_terminal_block/qet_terminal_slice.FCStd`

- [ ] **Step 1: Run semantic verification**

Run a short FreeCAD Python verification command that opens `qet_terminal_slice.FCStd` and checks:

- `Terminal_Top` exists.
- `Terminal_Bottom` exists.
- Both have `Role == "Terminal"`.
- Both have `CanWire == true`.
- Both have `QetTemplateSlotName` and `QetTerminalLabel`.
- Neither has `QetProjectUuid`, `QetElementUuid`, `QetTerminalUuid`, or `QetInstanceId`.

Expected: command exits `0` and prints a success summary.

- [ ] **Step 2: Verify STEP header**

Run:

```powershell
Get-Content -LiteralPath 'D:\LightWork3D\data\examples\qet_terminal_block\qet_terminal_slice.step' -TotalCount 20
```

Expected: output contains a valid STEP header such as `ISO-10303-21`.

### Task 4: Commit the Asset

**Files:**
- Add: `docs/superpowers/plans/2026-05-26-terminal-block-model-implementation.md`
- Add: `data/examples/qet_terminal_block/create_qet_terminal_slice.py`
- Add: `data/examples/qet_terminal_block/README.md`
- Add: `data/examples/qet_terminal_block/qet_terminal_slice.FCStd`
- Add: `data/examples/qet_terminal_block/qet_terminal_slice.step`
- Add: `data/examples/qet_terminal_block/qet_terminal_slice_report.json`

- [ ] **Step 1: Check unrelated changes**

Run:

```powershell
git status --short
```

Expected: existing unrelated modified files may remain; only the plan and asset directory should be staged for this task.

- [ ] **Step 2: Stage and commit**

Run:

```powershell
git add -- docs/superpowers/plans/2026-05-26-terminal-block-model-implementation.md data/examples/qet_terminal_block
git commit -m "feat: add qet terminal block model asset"
```

Expected: a commit containing only the plan and terminal model asset files.

## Self-Review

- Spec coverage: the plan creates FCStd, STEP, generator, README, two template terminals, no engineering binding fields, and verification.
- Placeholder scan: no TBD/TODO/fill-later language is present.
- Type/property consistency: terminal object names and QET template property names match the approved design.