git:20260805.5649319 to git:20260807.7934638

# claude-cad — notes for Claude Code

This repo is **a toolkit *and* the default workspace**. It ships a Claude Code

skill, prompts, and docs for generating CadQuery parts whose STEP files reliably

open in SolidWorks. The defining idea: **never trust generated geometry — prove

it's valid before export.**

## The clone is the workspace (default)

The skill is committed at `.claude/skills/cadquery-modeling/`, so a fresh clone

arrives with it **already active — no install, no reload**. The default workflow

is: clone → open in VS Code → describe a part. Parts go in the top-level `parts/`

(a `diagnose.py` is shipped there so imports resolve); output lands in `output/`.

Both are git-ignored, so the user's work stays out of `git status` and `git pull`

(to update the toolkit) stays clean.

If someone asks you to model something while this repo is the working directory,

**that is now the intended path — just do it.** Mention the standalone alternative

only when it actually fits.

## When to suggest a separate project (the alternative)

A standalone project folder elsewhere — set up by pasting

`prompts/workflows/project_init.md`, producing the three-folder `claude-cad/` +

`parts/` + `output/` layout that `examples/sbc-case/` demonstrates — is worth

suggesting when the user wants to:

- **version their own designs** (the clone git-ignores `parts/`, and committing

there tangles with toolkit `git pull`s),

- keep **several unrelated projects** apart, or

- keep this clone **pristine** as a reference they `git pull` to update.

Don't push it by default; the point of the new layout is that most people never

need it.

## Helping someone who just arrived

Most people who open Claude Code here have just cloned the repo. The skill is

already active (committed at `.claude/skills/`), so there's little to set up:

1. **Point them at `QUICKSTART.md`** — clone → Python → open in VS Code → confirm

the skill is already listed (`/skills`) → describe a part. Don't re-explain it.

2. **Check their Python** — `py -3.11 -c "import cadquery, OCP; print('env OK')"`.

If `OCP` fails to import they're on too-new a Python (see below).

3. **Then just build.** First part goes in `parts/`; run it with

`py -3.11 parts/<name>.py`; batch-verify with `py -3.11 preflight.py`.

If `/skills` doesn't list `cadquery-modeling`, they likely opened a subfolder as

the workspace root instead of the repo root, or need to reload the window — skills

load at session start.

## Conventions that differ from what you'd assume

These are the things that bite people. They're not derivable from the code:

- **Python 3.11, not the newest release.** The `OCP` kernel binding lags new

Python versions, so `pip install cadquery` succeeds while `import OCP` fails.

- **Export paths resolve from the script file, never the working directory.** A

bare `"../output/x.step"` silently writes one folder too high when the script is

run from the project root. Always

`Path(__file__).resolve().parent.parent / "output"`, and print the resolved path.

- **`from diagnose import ...` resolves against `parts/diagnose.py`**, which is

shipped in the clone. In a standalone project, `project_init` copies it there

(and keeps the canonical copy in that project's `claude-cad/`). The skill's

master copy lives in `.claude/skills/cadquery-modeling/scripts/`.

- **A green `[OK]` proves nothing — and neither do validity + solid count alone.**

A `.shell()` that silently no-ops returns a valid, single, *un-hollowed* solid.

- **The one verified silent-corruption trap is `.shell()` on a solid whose

removed face was filleted** (Pitfall 4b — returns the part un-hollowed,

`IsValid=True`). The historically blamed operations (countersinks on shelled

walls, face-selected `cutThruAll`, lofted domes) do **not** reproduce on the

current kernel; their replacement patterns are kept as preferred constructions.

Read `docs/occ_pitfalls.md` (each pitfall's Verified behaviour block) before

writing code that shells, fillets, or lofts; re-test with

`.claude/tests/repro_pitfalls.py` after a kernel upgrade.

- **Auto-repair is deliberately conservative.** It only discards unambiguous

debris; it never patches invalid topology, because that would hide real design

errors. Don't "improve" it into something that silently fixes more.

## Editing this repo

- **The skill lives in exactly one place: `.claude/skills/cadquery-modeling/`** —

the path Claude Code loads, and the canonical source. Edit it directly; there is

no second copy to sync. (This replaced a former two-copy setup — `skills/` plus

`.claude/skills/` — and the drift guard that policed it. One copy can't drift, so

the guard is gone.)

- Five `docs/*.md` files are still **mirrored** into the skill's references at

`.claude/skills/cadquery-modeling/references/*.md` (`occ_pitfalls`,

`verification`, `diagnosis`, `environment`→`python_env_setup`,

`solidworks_checks`→`solidworks_integration`). If you change one, sync its twin by

hand — they must stay byte-identical. `.claude/tests/test_mirrors.py` fails if

they drift; run it (or the whole `.claude/tests/` suite) before committing.

- The same rule often appears in the skill, the docs, and the prompts. After

changing a rule, grep for it — leaving one copy stale is the most common defect

in this repo.

- **Examples and templates must stay generic.** No proprietary, confidential, or

patent-pending designs. Abstract the method, never someone's product.

- Any Python added here must pass its own verification block before it's

presented as working.