kernelCAD-web: Instructions file for Claude Code

Repo conventions for Claude Code agents working in kernelCAD-web

Every feature and tool

Follow AGENTS.md: check current comparable websites and the existing kernelCAD website before implementation, update discovery/docs, and produce and visually inspect a short MP4 demonstration for every new or materially changed feature/tool. This expands the release-only demo rule below. Keep dated competitor comparisons private; retain source, verification and truthful demo provenance.

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; eligible pushes to develop also trigger the private marketing deploy for kernelcad.com, including docs/guide/** blog sources and docs/demos/** media. The listed top-level prose files and unrelated docs-only changes do not trigger it. Manual gh workflow run deploy-kernelcad-com.yml -R w1ne/kernelCAD-server -f web_ref=develop remains available as an override. Blog drafts still require editorial approval before publication. Verify the actual deploy and live URLs; upload success does not prove the separate cache purge passed. 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.