Letterboxd

Build a local-first personal film diary web app. Single user, no accounts, no cloud, no telemetry.

Stack, non-negotiable:
- Next.js 15 with the App Router, TypeScript, Tailwind.
- SQLite via better-sqlite3, one file at ./data/diary.db, schema created on first run.
- No auth, no external services except TMDB for metadata.

Secrets:
- .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing.

Data model:
- films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
- entries: id, tmdb_id, watched_on (date), rating (0.5 to 5 in half steps, nullable), review (text, nullable), rewatch (boolean), liked (boolean), created_at.
- watchlist: tmdb_id, added_at, note.

Features in scope:
- Search box that hits TMDB search, shows posters and years, one click to log. Cache the film row locally so the app works offline for anything already logged.
- Log form: watched date defaults to today, half-star rating widget, review textarea, rewatch and liked toggles.
- Diary view grouped by month, newest first, poster grid plus compact list toggle.
- Film detail page: local metadata, every entry you have for it, rating history.
- Watchlist page with add from search and a one-click promote to a diary entry.
- Stats page: films per year and per month, rating distribution histogram, top directors by count, total runtime in hours and days, longest streak of consecutive days with a log.
- CSV import that accepts the Letterboxd export format (Name, Year, Watched Date, Rating, Review, Rewatch) and matches to TMDB with a manual disambiguation queue for anything ambiguous.
- CSV export of everything.

Explicitly out of scope: any social features, follower graphs, comments, aggregate ratings, streaming availability, mobile apps, push notifications, deployment config.

Deliver: working app, README with setup in under five commands, seed script that inserts three sample entries so the stats page is not empty on first load.

# AGENTS.md — Build guide for Letterboxd

## Project scope
A local film diary that searches TMDB for a title, logs a watch date, rating and review, and shows your history plus a stats page.

Catalogue verdict: no. The logging half of Letterboxd is trivial: a table of films, a date, a rating, a note. The half people actually open the app for is everyone else, friends' four-star shrugs, review pages with thousands of jokes, lists that function as film school syllabi, and the year-end stats that only mean something because they are comparable. A one-shot build gives you a private diary with no one in it, and you will still need TMDB to get posters and metadata that do not look broken. If you genuinely only want a watch log, build it and enjoy the speed. If you want the film internet, you are not building the film internet this weekend.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- TMDB API key for film metadata and posters
- Node 20+
- SQLite (no server to run)

## Stack and architecture
- SQLite via better-sqlite3, one file at ./data/diary.db, schema created on first run.
- Data model:.
- Interface for this film logging and reviews workflow: a focused film logging and reviews input, review, and export interface.

## Security and data integrity
- .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: Every other human: friends' ratings, popular reviews, comment threads.

## Agent implementation rules
- Project rule, data: Data model:.
- Project rule, behavior: films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
- Project rule, recovery: .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this film logging and reviews operation with sample or user-owned data: films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
- Show a concrete result or export: CSV import that accepts the Letterboxd export format (Name, Year, Watched Date, Rating, Review, Rewatch) and matches to TMDB with a manual disambiguation queue for anything ambiguous.
- State the practical limit: Every other human: friends' ratings, popular reviews, comment threads.

## Engineering roadmap
1. Phase 1, architecture and data: SQLite via better-sqlite3, one file at ./data/diary.db, schema created on first run. Data model:.
2. Phase 2, implement: films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
3. Phase 3, implement: entries: id, tmdb_id, watched_on (date), rating (0.5 to 5 in half steps, nullable), review (text, nullable), rewatch (boolean), liked (boolean), created_at.
4. Phase 4, review and output: watchlist: tmdb_id, added_at, note. CSV import that accepts the Letterboxd export format (Name, Year, Watched Date, Rating, Review, Rewatch) and matches to TMDB with a manual disambiguation queue for anything ambiguous.
5. Phase 5, recovery and acceptance: .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing. Verify this invariant with a saved fixture: A failed platform call retains the draft and cannot be marked published; retries use a stable delivery key. State the practical limit: Every other human: friends' ratings, popular reviews, comment threads.

## Paid-product capabilities outside this build
- Every other human: friends' ratings, popular reviews, comment threads
- Curated and community lists, which are most of the discovery value
- Aggregate ratings and the histogram that tells you if a film is divisive or just bad
- Mobile apps, offline logging, share cards, streaming availability data
- Importing your existing history back out of anything without a CSV wrangle

## Implementation prompt
Build a local-first personal film diary web app. Single user, no accounts, no cloud, no telemetry.

Stack, non-negotiable:
- Next.js 15 with the App Router, TypeScript, Tailwind.
- SQLite via better-sqlite3, one file at ./data/diary.db, schema created on first run.
- No auth, no external services except TMDB for metadata.

Secrets:
- .env.local with TMDB_API_KEY. Commit .env.example only. Fail loudly with a readable message if the key is missing.

Data model:
- films: tmdb_id (primary key), title, year, director, runtime, poster_path, overview, cached_at.
- entries: id, tmdb_id, watched_on (date), rating (0.5 to 5 in half steps, nullable), review (text, nullable), rewatch (boolean), liked (boolean), created_at.
- watchlist: tmdb_id, added_at, note.

Features in scope:
- Search box that hits TMDB search, shows posters and years, one click to log. Cache the film row locally so the app works offline for anything already logged.
- Log form: watched date defaults to today, half-star rating widget, review textarea, rewatch and liked toggles.
- Diary view grouped by month, newest first, poster grid plus compact list toggle.
- Film detail page: local metadata, every entry you have for it, rating history.
- Watchlist page with add from search and a one-click promote to a diary entry.
- Stats page: films per year and per month, rating distribution histogram, top directors by count, total runtime in hours and days, longest streak of consecutive days with a log.
- CSV import that accepts the Letterboxd export format (Name, Year, Watched Date, Rating, Review, Rewatch) and matches to TMDB with a manual disambiguation queue for anything ambiguous.
- CSV export of everything.

Explicitly out of scope: any social features, follower graphs, comments, aggregate ratings, streaming availability, mobile apps, push notifications, deployment config.

Deliver: working app, README with setup in under five commands, seed script that inserts three sample entries so the stats page is not empty on first load.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.