CLAUDE.md git:20261016.619f84fA

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

# Repo conventions for Claude Code agents working in kernelCAD-web

## Every feature and tool

Follow [AGENTS.md](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.

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.

## Demo discipline (v0.X.0-tag PR review rule)

When reviewing a PR that ships a `v0.X.0` tag (cuts a per-module release):

1. Verify `docs/demos/v0.X/<task>/whats-new.md` contains a `## Hero artifact` section, a `## Why memorable` section with all three bullets filled (no `TODO:`), and a `## What's new` section.
2. Verify `docs/demos/v0.X/<task>/meta.json` contains `heroArtifact`, `catalogSource`, and `overrideApprovedBy` keys.
3. Judge the *artifact itself*, not the prose. From v0.18 the hero must be a real user job taken end to end (for example a Pi 5 case with heat-set inserts, a motor mount, a coupler with set screws), and `meta.json.proof` must name that job and point at a passing verify report or a photo of the printed or fabricated part. Fail the review if the hero is a bare primitive (box, cube, cylinder), if the new tool isn't visibly central to the build, or if the proof doesn't show the part working. A recognisable object with no proof is not enough.
4. If `meta.json.overrideApprovedBy` is non-null, the override path was used. Surface this to the controller for traceability — it is not automatically a fail, but should not be a default.

This rule binds the `superpowers:code-reviewer` agent and any human reviewer working in this repo.

## Quality ratchet

`scripts/lib/qualityBaseline.json` and `scripts/lib/cycleBaseline.json` may only
shrink over time; a value going back up (even to an old baselined value) fails CI.
After reducing findings or cycles, run `npx tsx scripts/qualityBaselineRegen.ts`
to regenerate both baselines — it refuses to write (exit 1) if any finding is new
or grew, unless you pass `--allow-new`. `eslint.config.js` also enforces a
one-way import layering (shared -> kernel -> modeling -> kinematic -> agent ->
studio); a `no-restricted-imports`/`no-restricted-syntax` error there means you
imported from a higher layer — move the code down or add it to that block's
allowlist with a follow-up ticket, don't silence the rule.