# AGENTS.md

> Repository-level rules for AI coding agents. Read this before changing files.

## Mission

Build a mobile-first, installable, offline-capable English intensive-listening PWA for "Family Album, U.S.A." using audio plus sentence-synced English subtitles. The MVP is not a video site, social product, generic course platform, or AI speaking scorer.

## Required Reading Order

Before writing code, read these files in order:

1. `docs/00-ai-start-here.md`
2. `docs/01-vision.md`
3. `docs/02-requirements.md`
4. `docs/03-tech-stack.md`
5. `docs/04-architecture.md`
6. `docs/05-coding-rules.md`
7. `docs/06-tasks.md`
8. `CLAUDE.md`

Use `docs/00-ai-start-here.md` for navigation. Use `docs/05-coding-rules.md` as the hard implementation rulebook.

## Task Discipline

- Work from `docs/06-tasks.md`.
- Pick only the first `TODO` task whose dependencies are all `DONE`.
- Do exactly one task per development turn.
- Mark it `DOING` before implementation, then `DONE` only after its acceptance checks pass.
- Do not jump ahead, batch multiple tasks, or add V2/V3 scope while doing MVP work.

## MVP Scope

MVP scope is ep1-17 plus these P0 capabilities:

- Course list
- Audio playback
- Sentence-synced subtitles
- Vocabulary notebook
- Account and cross-device sync
- PWA install/offline use

Do not implement video playback, line-level Chinese translation, social features, AI speaking scoring, SRS, tests/quizzes, AB repeat, or multi-course logic unless a task explicitly asks for it.

## Technical Constraints

- Frontend: go-app, Go to WebAssembly.
- Styling: plain CSS files, mobile-first, loaded via go-app handler styles.
- State: go-app native state and observers.
- Backend: Go `net/http`.
- Database: SQLite for user data only.
- Auth: httpOnly Session Cookie.
- Deployment target: single self-hosted Go binary serving wasm, static assets, audio, and APIs.
- Do not add new frameworks, heavy libraries, or third-party dependencies without explicit approval.

## Data Rules

- Content truth source: `family-album-usa/episodes.json`.
- Do not invent fields. `line` has only `{ "t", "en" }`; there is no `zh`.
- JSON audio paths such as `/family-album/audio/u0101.mp3` are service paths. Map them to disk under `family-album-usa/audio/`.
- Do not fabricate audio for ep18-26.
- `notion_docs/` and `*.bak` are read-only archives. Do not edit, delete, or treat them as source of truth.

## Verification

Before claiming a task is done, run the relevant checks from `docs/05-coding-rules.md` and report exactly what passed or failed.

This project is primarily developed under WSL / Linux (bash). Use bash commands first:

```bash
GOOS=js GOARCH=wasm go build -o app.wasm   # frontend wasm
go build                                    # backend
go vet ./...
python3 scripts/validate_episodes.py
```

Windows PowerShell equivalents:

```powershell
$env:GOOS='js'; $env:GOARCH='wasm'; go build -o app.wasm
go build
go vet ./...
python scripts/validate_episodes.py
```

Only run the content validator when content data or its schema is touched.