CLAUDE.md · diff

git:20261012.4c4ab3d to git:20261016.619f84f

1 added, 1 removed. Audit A to A.

# 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. Verify the §1 bar of the memorable-builds policy spec (in kernelCAD-private) is satisfied by the *artifact itself*, not by the prose. If `heroArtifact` is generic (box, bracket, plate, etc.) or the new tool isn't visibly central to the build, fail the review and cite the policy spec.

+ 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.