# Television catalog

MobLand and Chernobyl have source-backed episode imports. Series pages group episodes by
season. Each episode has its own page, summary when the provider supplies one,
review subject, independently resolved identity address and native rating target.
Main discovery lists series, not their individual episodes. The review chooser
groups episode options under the series.

Catalog filters and pagination update native browser history on the current
pathname. They do not request a server-rendered query variant of a static export.
The Next.js router observes those local query changes through `useSearchParams`.

Canonical keys stay `film:tt…` for both films and television, preserving the open
target protocol and IMDb identity. Episode URLs contain the series name and SxxExx
before the episode title and IMDb suffix. Parent relationships never redirect an
episode take to the series or pool their spending or takes.

## Source-backed imports

`tools/import-television.main.kts` accepts a frozen TVmaze show response with
embedded episodes and a matching slice of IMDb's official `title.episode.tsv`.
It joins only exact parent-series, season and episode numbers. Missing or duplicate
IMDb mappings stop the import. The public, read-only Knomee resolver supplies each
address; importing never mints, activates, signs or posts a review.

The frozen source JSON, its SHA256 and CC BY-SA attribution are published under
`public/data/television/`. Summaries are plain-text adaptations of TVmaze data;
the original bytes remain available. A missing summary remains absent, rather
than copying the series description or inventing an episode plot. Artwork is
copyrighted promotional media, separately recorded as non-free editorial use;
the data license is not an artwork license.

Run the importer from the repository root:

```text
kotlin tools/import-television.main.kts .goodtakes/show-source.json .goodtakes/show-imdb-episodes.tsv
```

The first input is `https://api.tvmaze.com/shows/{showId}?embed=episodes`.
Extract the matching parent IMDb ID from the official `title.episode.tsv.gz`
using `gzip` and `rg`, retaining the four original TSV columns and source bytes.
The importer freezes the selected mapping rows alongside the original TVmaze
JSON and hashes both. It caches public address lookups and the poster in the
ignored `.goodtakes/television-identities/` directory.

The durable television projection is merged into `catalog.json`. Oracle sync
retains imported targets and season relationships. Runtime live catalog refreshes
also retain snapshot-only titles. Source-backed TV pages do not invoke the
film-specific Wikidata hydration lane. Existing oracle films continue using it.

## Upgrading an existing series

Run the same importer with the existing series IMDb identifier. It validates the
resolved address against the catalog and enriches the existing row. Original
oracle provenance, reviews, immutable history, graph, poster and title/year routing
remain intact. A miniseries stays a miniseries. Each episode receives its own
canonical key and address. Catalog refresh and opened-title metadata preserve
the imported television classification and episode relationship.

Series classification does not imply episode coverage. Run
`kotlin tools/television-coverage.main.kts` to identify catalog series that still
need an episode import and verify imported counts against frozen source data.
Chernobyl has five episodes. Other unimported series must not be described as
episode-complete merely because they appear in the Series filter.

## Verification

Use TypeScript, lint, paired static export and the anonymous television acceptance
harness. Check series-to-episode navigation, both seasons, distinct exact review
subjects, summary text, direct routes and mobile overflow. No participant review
or authenticated signing is part of this catalog verification. Unit tests are
deferred under RAPID POC. Firebase is the current deployment scope.

Use `kotlin tools/accept-television.main.kts <origin> film:tt7366338` for Chernobyl.
Without a subject argument, the harness checks MobLand. It supports one or several
seasons and checks preserved legacy series as well as newly imported ones.
