# Dev server rules (Next.js)

## Start it like this, every time
```
NODE_ENV=development WATCHPACK_POLLING=true npx next dev --webpack -p 3107
```
Why each part:
- **NODE_ENV=development**: this machine's shell exports `NODE_ENV=production`. A plain `next dev` then warns "non-standard NODE_ENV", silently serves **stale pages** (edits never show up) and adds a `.next/dev/dev/types/**/*.ts` line to `tsconfig.json`. If that line appears, revert it.
- **--webpack + WATCHPACK_POLLING=true**: Turbopack's file watcher stopped seeing edits on this machine (external disk / many files). Webpack with polling picks edits up in about 8 s.
- Fixed port so QA scripts (`PLAY_BASE=http://localhost:3107`) and subagents all hit the same server.

## Prove it is live before trusting it
Make a probe edit (a visible string on the page you're working on), fetch the page with curl or Playwright, confirm the string appears, then revert. Never conclude "my change doesn't work" from a server you haven't probed.

## Sharing the server with subagents
Tell every subagent the exact command, the port and the probe rule. Two agents each starting their own `next dev` in the same repo corrupt `.next`; one server, many clients.

## Headless QA plays audio out loud
Playwright/Chromium runs play the app's music and voice lines through the owner's speakers, and several browsers closing mid-line sound like "skipping like an old cassette". That is not an audio bug.
- Launch Chromium with `args: ["--mute-audio"]` in every ad-hoc QA script.
- WebKit has no mute flag: prefer Chromium for sound-heavy checks or stub `AudioContext` output.
- To let the owner hear a clip on purpose, play the file with `afplay` and label the takes.

## Before saying "done"
1. Probe edit visible on the dev server.
2. `npx tsc --noEmit` (or the repo's lint) passes.
3. Screen/layout check for the touched screens passes at all target sizes.
4. Report problems as text lines (what, where), not screenshots to study.

## Deploy branch discipline
`main` deploys the website automatically. Feature work for the app lives on its own branch; merging to `main` needs the owner's explicit go-ahead. Pages that must be live early (privacy, support) are cherry-picked and pushed alone.