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

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