# Agent Guidelines — ChessSRS Website & Demo

This repository hosts the marketing website and live interactive web demo for **ChessSRS** (deployed to GitHub Pages).

## 1. Environment & CLI Conventions
- **Shell**: The execution shell is **Zsh** on Arch Linux. There is no standalone `bash` tool—execute bash scripts via `bash -c "..."` inside `shell`.
- **Throwaway Probes**: Always write temporary diagnostic scripts inside `/tmp/` (e.g. `/tmp/probe.js`), never in the git working tree. `node_modules` can be referenced by passing full paths or setting `NODE_PATH`. There is no top-level `playwright` package here — probe scripts must `require('<repo>/node_modules/@playwright/test')` by absolute path.
- **Single-Worker Tests**: To preserve local system performance, always run Playwright tests file-by-file with `--workers=1`:
  ```bash
  npx playwright test tests/e2e/<file>.spec.js --workers=1
  ```

## 2. Oracle & Design Pipeline
- **App Source of Truth**: `scripts/resolve-app-dir.js` locates it (`CHESSSRS_APP_DIR` override, else a `ChessSRS` checkout cloned alongside this repo, else legacy paths).
- **Never Hand-Edit Generated Files**:
  - `assets/demo-tokens.css`, `assets/demo-reference.css`, `pieces.js`, `assets/app-meta.js`, and `assets/figurines.js` are generated by `scripts/sync-design.js`.
  - `design/app-ui.json` is generated by `scripts/sync-strings.js`.
  - Put demo-specific CSS overrides inside the `DEMO-ONLY ADDITIONS` block in `styles.css`.

## 3. Verification Gates
Run the full gate sequence before declaring any task complete:
```bash
npx biome check                 # Fast linter & syntax validator
npm test                        # Biome lint + DOM shim unit tests + FSRS math tests
npm run sync:check              # Asserts zero drift against app design tokens and Dart UI strings
npm run test:e2e                # Playwright E2E suite (accessibility, parity, interactions)
python3 build.py                # Verifies single-file distribution bundle
```

For UX-facing changes, gates passing is not enough: click through the happy path as a first-time visitor (screenshot or e2e) and confirm zero detours before declaring done. Green checks once shipped forge links and dev commands on this homepage — only looking at the result as a visitor catches that class of miss.

## 4. Experience Invariants
`docs/site-invariants.md` is binding: every Download entry opens the same platform menu in place with direct file downloads (honest "Coming soon" wait while no files are attached, no forge or toolchain surface in the block), and every support route in `#support`/footer/FAQ/`privacy.html` §3 must resolve — both selected by DOM scope so new providers are covered without edits. Add no friction to these paths; run their gates (`tests/download.test.js`, `tests/support-links.test.js`, `tests/e2e/download.spec.js`) with any change near them.

For visual review against the app's headless screenshot captures:
```bash
npm run parity:pixels           # 60-pair visual diff against app goldens
npm run parity:pixels:self-test # Verifies pixel comparator sensitivity
npm run review:screenshots      # Interactive before/after web inspector (http://127.0.0.1:4777)
```