git:20260917.c1d969a to git:20261011.d7f278d

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