# AGENTS.md — flow-state

## Design decisions

All load-bearing decisions live in [`DESIGN.md`](./DESIGN.md). Read it before
changing behaviour. Changing a decision means updating `DESIGN.md` **and**
the gate that enforces it. `PLAN.md` is the full design; `EPIC-*.md` are the
epic designs.

## Adding / fixing a scene

Follow the `build-visualizer` skill (`.claude/skills/build-visualizer/`).
Short version:

```bash
npm run new:scene -- "Name" --family=<flow|organic|minimal|structural|geometric|glitch> --traits=...
# ... write the scene() body ...
npm run lint:scenes
# open http://localhost:5180/checks.html?scene=Name
```

Verify in order: `lint:scenes` (~1s) → per-scene gate in `checks.html` →
`checks.html?slow=1` once before committing. Each rung is ~10× the cost of
the previous.

## Rules that have bitten before (all in DESIGN.md §3–4)

- Anything multiplying `u_time` must be `rate: true` — and rate params are
  never modulated (drift/reactive/lookahead skip them).
- Discrete params (`int`/`bool`/`discrete: true`) hold per cue and are
  never reactive: **actors and objects change only at camera cuts.**
- No contract-uniform reuse, no hardcoded colours (use `pal()`), base
  image under every `prev()`, honour every declared trait, feed `sigCamera`
  into the image.
- No `Math.random` / wall-clock in render-path code; motion is analytic
  `f(t, seed)` so seek === playback and preview === export.

## Checks

```bash
npm test             # audio pipeline + venue/model headless tests
npm run lint:scenes  # determinism grep + schema/shader agreement
```