# 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.
  Assert volume against a range **derived from the parameters** (never `Volume()`
  measured and pasted back — that checks the geometry against itself; keep any
  measured figure only as a labelled `regression_volume`), and use
  `assert_points()` — the strongest intent check — for any feature whose position
  matters. See `docs/verification.md` and Pitfall 4b.
- **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.