step-parse/skill.src/SETUP_CHECKLIST.md

# STEP Processor — macOS Setup Checklist
### Apple Silicon (Mac Studio M-series) · No Rosetta Required

Work through this top to bottom. Each section has a ✅ verification command
so you know it worked before moving on.

---

## PHASE 1 — Prerequisites

### 1.1 — Confirm Python version

```bash
python3 --version
```

**You need Python 3.10, 3.11, or 3.12.**
3.13 will work but is less tested. 3.9 is too old.

If your version is wrong, install via Homebrew:
```bash
brew install python@3.11
```
Then use `python3.11` explicitly in all commands below.

---

### 1.2 — Confirm Homebrew is installed

```bash
brew --version
```

If missing:
```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

---

### 1.3 — Create a dedicated virtual environment

Keep everything isolated from your system Python.
Pick a folder — e.g. your CoWork dev directory.

```bash
python3 -m venv ~/step-processor-env
source ~/step-processor-env/bin/activate
```

You should see `(step-processor-env)` in your terminal prompt.
**All pip commands below assume this environment is active.**

✅ Verify:
```bash
which python   # should point inside step-processor-env
```

---

## PHASE 2 — Primary Library: build123d

### 2.1 — Upgrade pip first

```bash
pip install --upgrade pip
```

---

### 2.2 — Install cadquery-ocp (the OCC kernel, native arm64)

This is now on PyPI directly — no manual wheel download needed.

```bash
pip install cadquery-ocp
```

This is a large download (~300MB). Let it run.

✅ Verify:
```bash
python -c "import OCP; print('OCP kernel OK')"
```

---

### 2.3 — Install build123d

```bash
pip install build123d
```

✅ Verify:
```bash
python -c "import build123d; print('build123d OK')"
```

---

### 2.4 — Install the rendering stack

```bash
pip install trimesh pyrender Pillow numpy pandas anthropic openpyxl
```

> **Note:** `openpyxl` is required for Excel BOM output. If missing, the skill silently
> falls back to CSV. Install it here to get MPM-branded `.xlsx` output.

✅ Verify each:
```bash
python -c "import trimesh; print('trimesh OK')"
python -c "import pyrender; print('pyrender OK')"
python -c "import PIL; print('Pillow OK')"
python -c "import pandas; print('pandas OK')"
python -c "import anthropic; print('anthropic OK')"
python -c "import openpyxl; print('openpyxl OK')"
```

---

## PHASE 3 — Diagram Export: cairosvg

Required for converting SVG diagrams to PNG and PDF.

### 3.1 — Install system libraries via Homebrew

```bash
brew install cairo pango gdk-pixbuf libffi
```

### 3.2 — Install cairosvg

```bash
pip install cairosvg
```

✅ Verify:
```bash
python -c "import cairosvg; print('cairosvg OK')"
```

If you get a library not found error, run this and retry:
```bash
export PKG_CONFIG_PATH="/opt/homebrew/lib/pkgconfig"
pip install cairosvg
```

---

## PHASE 4 — Fallback Library: FreeCAD Headless

Only needed if build123d fails on a specific file.

> **macOS 15 Sequoia note:** The conda-forge FreeCAD package is killed silently
> by Gatekeeper on Sequoia due to unsigned binaries. Use the official signed
> FreeCAD.app instead (approach below). Conda approach will NOT work on Sequoia.

### 4.1 — Install official FreeCAD.app (signed & notarized)

Download the latest arm64 release from:
```
https://github.com/FreeCAD/FreeCAD/releases/latest
```

Open the .dmg and drag FreeCAD.app to /Applications as normal.
Launch it once from /Applications so macOS registers the security approval.

### 4.2 — Verify headless via app bundle

The binary is `freecadcmd` (all lowercase) inside the bundle:

```bash
/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd --version
# Should print: FreeCAD 1.x.x Revision: ...
```

✅ Verify Python import:
```bash
/Applications/FreeCAD.app/Contents/Resources/bin/python -c \
  "import sys; sys.path.insert(0, '/Applications/FreeCAD.app/Contents/Resources/lib'); \
   import FreeCAD; print('FreeCAD', FreeCAD.Version())"
```

**Key paths for loader.py:**
- CLI binary: `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd`
- Python interpreter: `/Applications/FreeCAD.app/Contents/Resources/bin/python`
- Module path (add to sys.path): `/Applications/FreeCAD.app/Contents/Resources/lib`

The code invokes FreeCAD using the bundle's own Python — no conda env needed.

---

## PHASE 5 — API Key

### 5.1 — Set your Anthropic API key

```bash
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY="sk-ant-YOUR-KEY-HERE"' >> ~/.zshenv
source ~/.zshrc
```

> **Important:** Add the key to **both** `~/.zshrc` AND `~/.zshenv`.
> `~/.zshrc` is only sourced in interactive terminal sessions.
> `~/.zshenv` is sourced for all zsh invocations including Desktop Commander's
> non-interactive shells — without it, translation will silently fail when
> running via CoWork/Desktop Commander.

✅ Verify:
```bash
echo $ANTHROPIC_API_KEY   # should print your key (or at least sk-ant-...)
```

---

## PHASE 6 — Place the Skill Files

### 6.1 — Copy the step-processor folder to your working location

Recommended: somewhere in your CoWork project or a dedicated tools directory.

```
~/your-project/
  step-processor/
    step_processor.py
    modules/
      __init__.py
      loader.py
      bom.py
      renderer.py
      translator.py
      rewriter.py
      query_engine.py
      external_diagram.py
    schemas/
      external_diagram_schema.json
      parts_mapping_schema.json
    templates/
      datablock_template.md
    SKILL.md
    INSTALL.md
```

### 6.2 — Activate your environment before running

```bash
source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor
```

---

## PHASE 7 — Test Run (do this when you have a STEP file ready)

Work through these tests in order. Stop at the first failure and fix it
before continuing.

---

### TEST 1 — Confirm the skill loads without errors

```bash
python step_processor.py --help
```

Expected: prints the CLI help/usage block with no ImportError or traceback.

---

### TEST 2 — Load a STEP file and extract BOM

Replace `yourfile.step` with your actual file path.

```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --verbose
```

Expected output:
```
INFO  Loading: yourfile.step
INFO  [build123d] Loaded: yourfile.step
INFO  BOM extracted: N parts
INFO  BOM XLSX → /path/to/yourfile_bom.xlsx
```

Open the `.xlsx` file to confirm part names look right.
If you see Chinese characters in the `Supplier Part Name` column — that's expected and correct.
The `Part Description` column will be populated with English in Test 4.
If you see a CSV instead of xlsx, `openpyxl` is not installed — run `pip install openpyxl`.

---

### TEST 3 — Generate thumbnails

```bash
python step_processor.py /path/to/yourfile.step --no-bom --verbose
```

Expected: 6 PNG files appear next to the STEP file:
`yourfile_front.png`, `yourfile_bottom.png`, `yourfile_left.png`,
`yourfile_right.png`, `yourfile_iso_left.png`, `yourfile_iso_right.png`

Open them in Preview to confirm they look like your enclosure from different angles.

---

### TEST 4 — Translation (requires API key)

Only run this if the BOM from Test 2 has Chinese part names.

```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --translate --verbose
```

Expected: `part_name_english` column in the CSV is now populated with English names.
A `yourfile_EN.step` should appear if Chinese labels were found in the STEP file itself.

---

### TEST 5 — Geometry query REPL

```bash
python step_processor.py /path/to/yourfile.step --no-thumbnails --no-bom --repl
```

At the `>` prompt, try:
```
> bounding box
> list all holes
> all parts
> help
> exit
```

Confirm the output tables look reasonable for your file.

---

### TEST 6 — External dimensional diagram

```bash
python step_processor.py /path/to/yourfile.step --diagram --verbose
```

Expected files next to the STEP:
- `yourfile__external-diagram.svg`
- `yourfile__external-diagram.png`
- `yourfile__meta.json`

Open the SVG in a browser (drag and drop into Safari or Chrome) to inspect the diagram.
Open the PNG for the rasterized version.
Open the JSON to confirm the metadata block populated correctly.

---

### TEST 7 — Diagram with PDF output

```bash
python step_processor.py /path/to/yourfile.step --diagram --diagram-pdf --verbose
```

Expected: adds `yourfile__external-diagram.pdf` to the outputs.
Open in Preview to confirm it renders cleanly.

---

## Quick Reference — Re-activating After Restart

Every time you open a new terminal session:
```bash
source ~/step-processor-env/bin/activate
cd ~/your-project/step-processor
export ANTHROPIC_API_KEY="sk-ant-..."   # only if not already in ~/.zshrc
```

---

## Troubleshooting Quick Reference

| Symptom | Fix |
|---------|-----|
| `ModuleNotFoundError: build123d` | `pip install build123d` (check env is activated) |
| `ModuleNotFoundError: OCP` | `pip install cadquery-ocp` |
| `ModuleNotFoundError: cairosvg` | `brew install cairo && pip install cairosvg` |
| `pyrender` offscreen crash | Expected on some macOS setups — thumbnails will warn but diagram still generates |
| BOM shows no parts / 1 part | Normal for single-body STEP files — the STEP text parser falls back to 1-row BOM |
| Chinese labels not translated | Check `$ANTHROPIC_API_KEY` is set. If running via CoWork/Desktop Commander, add key to `~/.zshenv` not just `~/.zshrc` |
| BOM output is CSV not xlsx | `openpyxl` not installed — `pip install openpyxl` with venv active |
| `_EN.step` entity count mismatch warning | File has unusual STEP encoding — rewrite skipped, original untouched, BOM still correct |
| FreeCAD fallback not working | Use signed FreeCAD.app — conda-forge is Gatekeeper-blocked on Sequoia. Path: `/Applications/FreeCAD.app/Contents/Resources/bin/freecadcmd` (all lowercase) |
| Diagram SVG opens blank | Check `yourfile__meta.json` warnings array for geometry errors |