Imported from fo56/TVTime (.agents/AGENTS.md). Install upstream with npx skills add fo56/TVTime --skill .agents. Copyright stays with the author.

TVTime Project Rules

Coding Standards & Style

• Detailed Comments: Everything in the codebase must have appropriate, detailed comments explaining the "why" and "how".
• Modularity: Keep the code highly modular and readable. Follow the single responsibility principle.
• Reusability: Code should be reusable. Use variables, constants, and configuration files instead of hardcoding values.

Frontend Development

• Design Guidelines: When designing anything in the frontend, always refer to docs/design.md for styling, themes, and layout rules.

Code Documentation Standards

When writing or modifying code in this repository, follow these commenting and structure conventions. The goal is that any developer (or LLM) opening a file cold can understand what it does and why within a minute, without needing to trace execution across the whole codebase.

File-level

• Every module starts with a short docstring/header comment: what this file is responsible for, and what it explicitly does NOT handle (its boundaries). Example: "Handles TMDB metadata sync for shows/movies. Does not handle watch-log writes — see routers/watch_log.py."

Function/endpoint-level

• Every function above ~10 lines gets a docstring: purpose, parameters, return shape, and any non-obvious side effects (e.g. "also writes to episode_watch_log", "commits inside this function — caller should not commit again").
• Every FastAPI route gets a one-line comment above it stating what it does in plain language, even if the function name seems self-explanatory — routes are read in isolation more than most code.

Why, not what

• Comments should explain why a non-obvious decision was made, not restate what the code already says. Bad: # increment counter above count += 1. Good: # watched_count is a cache of episode_watch_log rows — recomputed here rather than incremented, to stay correct even if a row was deleted elsewhere.
• Flag every place where a value is a derived/cached field rather than a source of truth — e.g. is_watched on episodes — with a comment pointing to the real source (episode_watch_log) so nobody edits the cache directly and creates drift.

Constraints and invariants

• Any DB constraint that isn't obvious from the column definition alone (e.g. "exactly one of show_id/movie_id must be set", "soft-delete only if never watched, hard-delete otherwise") gets a comment at both the schema definition and every place application code enforces or depends on it.

TODOs and known issues

• Use # TODO: for planned-but-not-done work, # FIXME: for known bugs, # NOTE: for context a future reader needs but that isn't a problem. Never leave a broken/incomplete implementation without one of these tags explaining its state — silent broken code (like the current GDPR import scripts referencing nonexistent models) should never happen again.

What NOT to over-comment

• Don't comment obvious code (# set title above title = data["title"]).
• Don't restate type hints in comments — the types are the documentation for "what," comments are for "why."
• Prefer clear naming over comments explaining unclear naming — rename first.

Consistency

introducing a new convention mid-file.

Documentation & README

• Vibe Check: Keep the README.md in its established vibe (casual, all lowercase, concise, edgy/no-nonsense tone). Do not rewrite it into corporate or highly formal markdown.