Local Development

Use the lockfiles and supported runtimes. JavaScript dependencies install with npm ci; the audio lock targets CPython 3.11 on Linux x86_64 and must retain hash verification.

npm ci
npm run build
npm run check
npm test
npm run story -- check --all --strict
npm exec playwright install chromium
PW_PORT=4207 npm run test:browser -- --workers=1
# Optional local escape hatch only when a matching server is already running:
PW_REUSE_EXISTING_SERVER=1 PW_PORT=4207 npm run test:browser -- --workers=1
 
python3.11 -m venv audio-service/.venv
audio-service/.venv/bin/pip install --require-hashes -r audio-service/requirements.txt
(cd audio-service && .venv/bin/python -m unittest discover -s tests -v)

The commands have distinct contracts:

• build transactionally regenerates CSS/icons and the checksum ledger without changing the token.
• check verifies syntax, release markers/manifest, and checksums; it does not prove deployment.
• test exercises Node contracts.
• strict story checks reject normalization warnings.
• Playwright exercises browser behavior.

PW_REUSE_EXISTING_SERVER=1 is an opt-in local convenience for reusing an already-running server on the PW_PORT endpoint. It can serve stale or different bytes, so CI and all release/gate commands must omit it and start a fresh server from the candidate tree.

Run the app through the repository’s browser-test server or another static server; do not infer same-origin audio behavior from a server that does not proxy /api/audio/. Local absence of host release trees or a sidecar is a valid fail-open audit state, not production proof. (docs/OPERATIONS.md:62-68)