CLAUDE.md git:20260721.3ce6c94A

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

# claude-cad — notes for Claude Code

This repo is a **toolkit**, not a CAD project. 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.**

## Parts belong in the user's own folder, not here

The skill installs globally, so claude-cad applies in any directory. This repo
stays useful as a reference the user returns to — `prompts/workflows/project_init.md`
for each new project, `prompts/templates/`,
`skills/cadquery-modeling/scripts/preflight.py`, `docs/`. The only
things that normally change *in* this repo are the toolkit itself and `examples/`.

If someone asks you to model something while this repo is the working directory:
say that a single throwaway part here is harmless (outputs are git-ignored, and a
cloner can't affect upstream), but that real or repeated work belongs in its own
folder — a second design has nowhere to go otherwise, and toolkit `git pull`s start
tangling with their files. Offer to set that folder up. Don't refuse outright.

## Helping someone who just arrived

Most people who open Claude Code here have just cloned the repo. Useful things to
offer, in order:

1. **Point them at `QUICKSTART.md`** — it's the linear path from clone to a
   verified part. Don't re-explain it; it's already written.
2. **Offer to install the skill for them** — copy `skills/cadquery-modeling/` to
   the location item 3 picks, using the right commands for their OS. Confirm the
   files landed, and tell them to reload Claude Code — skills only load at
   session start.
3. **Prefer project scope when installing.** Copy the skill into the user's
   project at `<project>/.claude/skills/`, not the personal directory
   (`~/.claude/skills/` on macOS/Linux, `%USERPROFILE%\.claude\skills\` on
   Windows), unless they say they do CAD constantly. A personal install loads its
   description into every session on their machine, and crowds the skill-listing
   budget.
4. **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).

## 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 check` needs `diagnose.py` copied into the project's
  `parts/` folder.** It lives in `skills/cadquery-modeling/scripts/` here; that
  path is not importable from a user's project.
- **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

- `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`).
- 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.