kernelCAD-web CLAUDE.md

Repo conventions for Claude Code agents working in kernelCAD-web

Deployment

Before deploying anything, read docs/DEPLOY.md. Short version: one trunk (develop, no main); the Studio (src/) auto-deploys to app.kernelcad.com on push to develop; the marketing site (site/, kernelcad.com) ships ONLY via a manual gh workflow run deploy-kernelcad-com.yml -R w1ne/kernelCAD-server -f web_ref=develop; a v* tag is a full npm release, not a per-surface deploy. Don't guess the deploy path — match the changed surface to the runbook.

CAD authoring discipline

For any task that creates or modifies CAD output, use the bundled kernelcad skill first and load kernelcad-authoring before editing a .kcad.ts model. The source file is the design source of truth; generated PNG/MP4/STEP/STL/score artifacts are evidence or deliverables, not files to hand-edit.

Adopt this loop:

1. Classify the job and write down the engineering intent before coding.
2. Plan the .kcad.ts source, parameters, imports, explicit output artifacts, and verification commands.
3. Edit source and provenance only.
4. Generate named targets only; do not refresh whole artifact directories unless the task is explicitly a release/demo rebuild.
5. Validate with deterministic commands before relying on screenshots.
6. If a rendered artifact is produced, inspect it visually and report concrete visible evidence. Do not mark visually broken CAD done because tests passed.
7. When visual evidence matters, run kernelcad render inspect <file> <outDir> to produce a deterministic inspection bundle with a manifest and canonical RGB views. Add --channels rgb,mask,depth,normals when machine-readable object masks, depth, or view-space normals are needed. Use --focus <names> or --hide <names> to isolate feature ids or assembly part names when clutter would obscure the check. Keep richer channels in the same manifest packet; do not replace the canonical RGB views.

Prefer lib.fromSTEP(...) for real purchased components such as servos, bearings, motors, fasteners, sensors, PCBs, and connectors. Hand-modeled placeholder boxes/cylinders are acceptable for blockouts, but final review must either replace them with vendor/catalog geometry or label the limitation.