Purpose

This file documents conventions and practical tips for automated agents (LLM-driven or human) working in this repository. It prefers using the `gh` CLI for GitHub interactions and Chrome DevTools / CDP (referred to here as "mcp") for e2e debugging. It also recommends a git `worktree` + branch workflow so multiple agents can work concurrently on the same machine without interfering with each other.

Scope & precedence

- The guidelines in this file apply to the entire repository unless a more deeply nested `AGENTS.md` overrides them.
- Direct system/developer/user instructions (prompts) take precedence over this file.

Quick environment notes

- **Package Manager**: This project uses `pnpm`. Install dependencies with `pnpm install`.
- Node scripts: see `package.json` for the authoritative scripts. Common scripts:
  - `pnpm dev` — starts the Vite dev server
  - `pnpm build` — builds a production bundle
  - `pnpm preview` — preview the build
  - `pnpm test` — run unit tests with `vitest`
  - `pnpm test:e2e` — run Playwright e2e tests
  - `pnpm test:e2e:headed` — run Playwright e2e tests in headed mode
  - `pnpm lint` / `pnpm lint:fix` — ESLint + Prettier checks/fix
  - `pnpm type-check` — TypeScript type check

Workflow: git worktree + branch (recommended for multi-agent)

Rationale: multiple agents and/or editors on the same machine should not share a single working copy. Use `git worktree` to create an isolated working directory per task/agent.

Example flow (from repository root):

- Create a worktree and new branch in one command:
  - `git worktree add ../worktrees/my-feature -b my-feature` — creates `../worktrees/my-feature` and checks out a new branch `my-feature` there.
- Move into the worktree and work there:
  - `cd ../worktrees/my-feature`
  - Run and edit normally (start the dev server, run tests, make changes).
- Commit locally in the worktree; push when ready:
  - `git add -A && git commit -m "feat: short description of why"`
  - `git push -u origin my-feature`
- Create a PR with `gh` (preferred):
  - `gh pr create --title "Short title" --body "## Summary\n- bullet 1\n- bullet 2" --base main`

Notes:

- Use descriptive branch names and commit messages that explain the purpose (the why) not only the what.
- Avoid `git checkout` in the main working copy while agents are running in their worktrees.
- Clean up completed worktrees with `git worktree remove ../worktrees/my-feature` and consider pruning stale branches.

Post-merge cleanup (mandatory after every PR merge):

After a PR is merged, always perform these cleanup steps:

1. Delete the remote branch (if not auto-deleted by the merge):
   - `gh api repos/OWNER/REPO/git/refs/heads/BRANCH -X DELETE`
2. Remove the worktree:
   - `git worktree remove ../worktrees/my-feature`
   - Use `--force` if the worktree has stale uncommitted changes that are no longer needed.
3. Switch to the main repo and update local main:
   - `cd /path/to/main/repo`
   - `git fetch origin main && git reset --hard origin/main`
4. Delete the local feature branch:
   - `git branch -D my-feature`
5. Prune stale remote refs:
   - `git remote prune origin`
6. Verify clean state:
   - `git status` — should show clean working tree on main
   - `git worktree list` — should show only the main working copy

Using `gh` CLI (preferred) for GitHub interactions

- Authenticate once per machine with `gh auth login`.
- Create PRs: `gh pr create --title "..." --body "..." --base main`.
- View PRs and open in browser: `gh pr view --web`.
- Add reviewers: `gh pr edit --add-reviewer username` or during creation use `--reviewer`.
- Reference GitHub from automation scripts rather than using the web UI when possible.

E2E tests & debugging (Playwright + Chrome DevTools / CDP (mcp))

Playwright is used for e2e tests here (`pnpm test:e2e`). For debugging and deep inspection, prefer using Chrome DevTools and the Chrome DevTools Protocol (CDP / "mcp") as follows:

- Fast debug (Playwright inspector):
  - `PWDEBUG=1 npx playwright test --debug` or `PWDEBUG=1 npx playwright test --headed` opens the Playwright inspector which is useful for stepping through tests.
- Use Chrome DevTools / CDP for network/console/coverage inspection:
  1. Launch a real Chrome/Chromium with a remote debugging port:
     - macOS example:
       - `"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" --remote-debugging-port=9222 --user-data-dir=/tmp/playwright-profile`.
  2. In your test setup, connect Playwright to that browser via CDP (example in code):
     - `const browser = await chromium.connectOverCDP('http://localhost:9222');`
     - This lets tests run against a DevTools-attached browser so you can open the DevTools and inspect pages, network, and console while tests run.
  3. Open Chrome DevTools and connect to the remote debugging endpoint (DevTools will auto-connect when you open `http://localhost:9222` in another browser), or use tools that can attach to the CDP endpoint.
- If you need to record traces or videos for failing tests, use Playwright tracing and video options (see Playwright docs). The repo already includes Playwright in devDependencies.
- **MCP Chrome DevTools for interactive testing**:
  - When available, use the MCP Chrome DevTools tools to interactively test functionality:
    - Start dev server: `pnpm dev`
    - Use `mcp_chromedevtool_navigate_page` to navigate to `http://localhost:5173`
    - Use `mcp_chromedevtool_take_snapshot` to capture page structure and identify elements
    - Use `mcp_chromedevtool_click`, `mcp_chromedevtool_fill`, etc. to interact with the UI
    - Use `mcp_chromedevtool_list_console_messages` to check for errors or debug logs
    - Use `mcp_chromedevtool_evaluate_script` to inspect application state
  - This approach is useful for:
    - Reproducing user-reported issues interactively
    - Testing complex interactions (e.g., clicking segments during generation)
    - Verifying fixes before writing formal E2E tests
    - Inspecting application state and console logs in real-time

Recommendations when running e2e locally/CI

- Run `pnpm dev` (or `pnpm preview` for a full build preview) before `pnpm test:e2e` when you need a live app server.
- For local debugging prefer `pnpm test:e2e:headed` so you can see the browser window.
- Use `PWDEBUG=1` whenever you want interactive test debugging.

Agent safety & repository etiquette

- Read the repo files you will edit before making changes — start with `package.json`, `vitest.config.ts`, `playwright.config.ts`, and `src/`.
- Make minimal, focused changes. Do not change unrelated code or formatting unless required by a pre-commit hook.
- Respect existing linters and pre-commit hooks: this repo uses `husky` + `lint-staged` (see `package.json` for details).
- Run `pnpm lint` and `pnpm type-check` before pushing changes to catch issues early.

Testing requirements for new features (Test-Driven Development)

This project follows **Test-Driven Development (TDD)** principles. Write tests BEFORE implementing functionality.

TDD Workflow (Red-Green-Refactor):

1. **Red**: Write a failing test that describes the desired behavior
   - Start with the simplest test case
   - Run test and verify it fails for the right reason
   - Do not write implementation yet

2. **Green**: Write minimal code to make the test pass
   - Implement only what's needed to pass the test
   - It's okay if the implementation is naive/simple
   - Run test and verify it passes

3. **Refactor**: Clean up code while keeping tests green
   - Improve structure, naming, efficiency
   - Run tests after each refactor to ensure nothing broke
   - Commit when tests pass

Test Requirements:

- **Unit tests are mandatory** for all new features and bug fixes. Place tests in `src/lib/**/*.test.ts` alongside the code they test.
  - Write tests FIRST before implementation (TDD)
  - Test both happy-path and error scenarios.
  - Test edge cases relevant to the feature (empty inputs, boundary conditions, state transitions, etc.).
  - Aim for meaningful coverage; focus on testing logic and behavior, not just line coverage.
- **E2E tests are strongly recommended** when the feature involves user interactions or cross-component workflows.
  - Add tests to `e2e/**/*.spec.ts` that verify the feature from the user's perspective.
  - E2E tests can be written after unit tests pass (since they're slower and more complex)
  - Test against realistic use cases (e.g., for audio playback, test playing different languages, switching chapters, etc.).
  - Use `pnpm test:e2e:headed` locally to debug flaky tests interactively.

TDD Best Practices:

- Start with the simplest test case, then add more complex ones
- One test should verify one specific behavior
- Keep test names descriptive: `should return mobile chunk size of 300 when on mobile device`
- Run tests frequently during development (`pnpm test --watch`)
- Commit after each green test (with passing implementation)
- If you find yourself writing implementation first, stop and write the test

- **Always run the full test suite before submitting changes:**
  - `pnpm lint` and `pnpm type-check` to catch style/type issues.
  - `pnpm test` to run all unit tests and ensure nothing breaks.
  - `pnpm test:e2e` to run end-to-end tests (or a subset if specified).
  - If any test fails, investigate and fix before pushing. Do not ignore failing tests.

Testing and validation

- Unit tests: `pnpm test` (vitest)
- E2E tests: `pnpm test:e2e` (Playwright)
- Lint and format: `pnpm lint` / `pnpm format`

Files & locations (quick references)

- Main scripts and dependencies: `package.json`
- Playwright config: `playwright.config.ts`
- Vitest config: `vitest.config.ts`
- Source code: `src/` (components, lib, etc.)
- E2E test specs: `e2e/` (e.g. `e2e/audiobook-generation.spec.ts`)

Troubleshooting tips

- If Playwright can't launch browsers (CI/mac differences), try installing Playwright browsers: `npx playwright install`.
- If you get port collisions when creating worktrees and running servers, use different dev server ports via environment variables.
- If `gh` is not authenticated, run `gh auth login`.

If you want, I can:

- Add per-folder or per-file agent guidance (e.g. where to find tests, how to run a specific test).
- Create a small script `scripts/new-worktree.sh` to automate creating a worktree + branch template.

End of AGENTS.md