CLAUDE.md git:20260805.fb6c4b3A

Immutable. This exact content never changes and is served at /api/v1/blob/b6946fb3dde1800c.

# 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 `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.
  Always assert volume against a hand estimate, and use `assert_points()` 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
  `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 is committed twice:** `skills/cadquery-modeling/` (canonical — the
  copy you EDIT, and what people copy to install elsewhere) and
  `.claude/skills/cadquery-modeling/` (the active-on-clone copy). Always edit the
  **canonical** copy.
- **HARD STEP — after ANY change under `skills/cadquery-modeling/`, before you
  commit:** run `py -3.11 tools/sync_skill.py --fix`, then
  `py -3.11 tools/sync_skill.py` and confirm it prints `[ok]`. A commit that
  touches the skill without syncing the `.claude/` copy is a defect. Three things
  catch it if you forget — `preflight.py` warns on every run, `tests/test_sync.py`
  fails, and the check above — but none of them un-ship a bad commit, so do it by
  hand. (`--fix` refuses if you edited the *active* copy instead; it won't
  silently overwrite your edit — move the change to canonical and re-run.)
- `skills/cadquery-modeling/references/*.md` and several `docs/*.md` are
  **mirrored copies**. If you change one, sync its twin (`occ_pitfalls`,
  `verification`, `diagnosis`, `environment`→`python_env_setup`,
  `solidworks_checks`→`solidworks_integration`). Because the skill is committed
  twice, an `occ_pitfalls.md` edit lives in **three** copies: the docs↔skill
  mirror pair you sync by hand, plus the `.claude/` skill copy that
  `sync_skill.py --fix` refreshes for you. `tests/test_sync.py` checks both the
  skill copies and all five doc mirror pairs.
- 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.