# docs/ — reading order

Purpose: index of `docs/` so a fresh contributor/agent knows what to read and in what order.
**Update this doc in the same PR that adds, removes, or retitles a doc below.**

Read in this order at session start:

1. **`CLAUDE.md`** (repo root) — project intro: architecture, layout, dev commands, conventions.
2. **`docs/contributing.md`** — established code patterns (CQRS/MediatR, LanguageExt, Blazor/
   MudBlazor, EF Core dual-provider migrations, FFmpeg pipeline, analyzers, testing). Read before
   any non-trivial change.
3. **`docs/domain-model.md`** — what the app IS: entity glossary, channel→playout→schedule/block
   concept map, where each concept is edited in the SPA.
4. **`docs/api-conventions.md`** — checklist for adding/changing a `/api/*` endpoint (controllers,
   DTOs, error mapping, auth, OpenAPI regen, tests).
5. **`docs/spa-conventions.md`** — playbook for adding a screen to the ChicoryTV React SPA.
6. **`docs/e2e-local.md`** (+ `scripts/e2e-local.sh`) — how to run a live local instance for manual
   or Playwright-MCP verification.
7. **`docs/testing.md`** — testing map: what each `*.Tests` project / `web` suite covers,
   golden-file nets, the timezone-independence rule, how to run subsets, the per-PR verification
   gate.
8. **`docs/blazor-route-parity.md`** — the #91 phase (b) tracker: which Blazor routes are
   redirected, SPA-ready-but-not-redirected, or still Blazor-only (and which issue blocks each).
9. **`docs/decisions.md`** — append-only "why" log. Check here before challenging an existing
   convention.
10. **`docs/ci-cd.md`** — build/test/release pipeline, versioning, dependency management.

Also present in `docs/`:

- **`docs/rest-api.md`** — REST API design doc for ersatztv#2 (goals, conventions, per-slice plan).
  Largely superseded day-to-day by `docs/api-conventions.md`; read this for the original rationale.
- **`docs/channels.md`** — Channel entity field reference.
- **`docs/m3u-xmltv.md`** — M3U/XMLTV generation overview (`ChannelPlaylist`, `GetChannelGuideHandler`).
- **`docs/fork-strategy.md`** — divergence policy vs upstream ErsatzTV.
- **`docs/design-sync.md`** — Claude Design ↔ repo screen workflow (#92).
- **`docs/endpoint-index.md`** — generated REST endpoint index (method/path/operationId/summary per
  OpenAPI tag). Do not edit by hand; regenerated by `scripts/generate-endpoint-index.py` /
  `scripts/update-openapi.sh`.
- **`docs/handoffs/chicorytv-issue-queue.md`** — static session kickoff prompt + workflow lore.
  Queue state (goal, arc, what's in flight/next) lives in the pinned Gitea tracker ersatztv#237
  — read that, not this file, for current state (protocol: decisions.md 2026-07-11).
- **`docs/handoffs/rest-api.md`** — original handoff prompt for kicking off the REST API work (#2).