# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A static, responsive single-page site listing the user's TV series, ranked by a fixed personal ranking, with poster/title/year/season-count sourced from a local Plex Media Server library. No build step, no framework, no dependencies — plain HTML/CSS/JS served as static files. Deployed to Vercel (`https://serie-tv.vercel.app`), auto-deploying on every push to `main` via a connected GitHub repo (`paoloalby/serie-tv`, private).

## Data pipeline

The site's data does not come from an API at request time — it's pre-generated and committed as static JSON/images.

1. **`data/rank.json`** — the source of truth for ordering: a hand-maintained list of `{rank, title, year}` reflecting the user's personal ranking. Edit this file to reorder, add, or remove series from the site.
2. **`data/plex-shows.json`** (gitignored, not committed) — raw export of the full Plex "Serie TV" library section (`title`, `year`, `seasons`, `ratingKey`). Regenerated by pulling from the local Plex server (`http://127.0.0.1:32400`), which requires an `X-Plex-Token` obtained from the Plex web UI's `localStorage` (`myPlexAccessToken`). This token must never be printed/logged — see `scripts/relay.py`.
3. **`scripts/relay.py`** — a throwaway local HTTP relay (port 8765) used to pull poster images and metadata out of the Plex web UI's browser context (where the auth token lives) without the token ever having to be typed, printed, or pasted anywhere. Run it, then from the Plex tab's JS console/devtools POST metadata to `/metadata` and poster blobs to `/poster/<ratingKey>`. It writes `data/plex-shows.json` and `public/posters/<ratingKey>.jpg`. Not needed unless refreshing the Plex export.
4. **`scripts/build-data.py`** — merges `data/rank.json` with `data/plex-shows.json` by normalized title (+ year fallback), and writes the final `public/data.json` consumed by the page. Run this after updating `data/rank.json` or re-pulling Plex data:
   ```
   python3 scripts/build-data.py
   ```
   It prints how many ranked entries matched and lists any unmatched titles — check this output after edits, since a typo in `rank.json` silently drops that series from the site.
5. Unused posters (in the Plex library but not in the current ranking) are pruned from `public/posters/` before committing, to keep the repo small.

## Site (`public/`)

- `public/index.html` — the entire site: inline `<style>` and `<script>`, fetches `data.json` client-side, renders a responsive poster grid (3 columns below 640px, auto-fill minmax(150px) above), with a client-side title search filter. No rank number is displayed on cards.
- `public/data.json` — generated output, ordered by rank, each entry `{rank, title, year, seasons, poster}` where `poster` is a relative path into `public/posters/`.
- `public/posters/` — JPEGs downloaded and resized (300x450) from Plex via the transcode endpoint.

## Deployment

- `vercel.json` sets `outputDirectory: public` — this is a static deployment, no build command.
- Vercel project is git-connected: any push to `main` on GitHub auto-deploys to production.
- **Gotcha**: Vercel blocks a deployment if the pushing commit's author email isn't a verified email on the connected GitHub account. This repo's local git config is pinned to `user.email = paoloalby@hotmail.com` for that reason — don't let it fall back to a machine-generated default (e.g. `user@hostname.local`).
- Manual deploy (rarely needed): `vercel deploy --prod --yes --scope paoloalbys-projects`.