Consolidate MangaCircus app, scraper, and Compose baseline

docs/library-format.md

@@ -72,6 +72,16 @@ Ignored, with a warning in the log:
 
 ### The key
 
+The additive unnumbered MangaDex chapter form is
+`special-mangadex-<chapter-uuid> Pilot [MangaDex · Group]`. It is accepted only for
+chapters, never books. Its logical key is the complete lower-case prefix/UUID;
+`chapter.json` supplies `special:true`, `label` (Pilot/One-shot/Special), `sourceId`
+and nullable `sourceNumber`. The reader shows that label with no fabricated number.
+Such chapters sort after numbered entries and are not inherently skippable extras.
+Different source UUIDs remain distinct releases; no content equivalence is guessed.
+Numeric IDs and source-version folders are unchanged. Older reader releases ignore
+these new folders but retain them on disk; upgrade again to restore visibility.
+
 The number is normalised: leading zeros and trailing decimal zeros are dropped (`0010.50` → `10.5`), and an `x` prefix is kept. The result is the **key**:
 
 | Folder | Key |
@@ -165,10 +175,17 @@ UTF-8 JSON (a BOM is tolerated). All fields are optional, and unknown fields are
 | `tags` | string[] | Genres / tags |
 | `description` | string | Synopsis (line breaks are kept) |
 | `direction` | `"rtl"` \| `"ltr"` \| `"ttb"` | How the pages are read. `rtl` (the default): manga, right to left. `ltr`: comics, printed manhwa. `ttb`: webtoon, one vertical strip cut into slices (aliases `vertical`, `webtoon`) |
+| `directionOverride` | same values | Explicit manual choice. Use this even when choosing `rtl`, which is also the fallback. May be set at manga, book, or chapter level |
+| `x-reading-direction` | object | Generated provenance: `{ "version": 1, "value": "ttb", "source": "detected" }` or `source: "fallback"`, with optional numeric evidence. The scraper owns this field; it is not a confidence score |
 | `sources` | `{name, url}[]` | Upstream sources the manga was scraped from. Several are allowed |
+| `x-anilist` | object | AniList work ID and linked metadata. The ID identifies a work, not necessarily a particular pilot or edition |
+| `x-metadata.imported` | object | Last imported values for title, alternative titles, authors, status, year, tags and description. The scraper updates a displayed field only when it is empty or still equals its previous imported value; edits in legacy files without this snapshot are preserved |
+| `x-scraper.autoUpdate` | boolean | Optional explicit admin choice. When absent, `status: "ongoing"` enables nightly checks and other statuses disable them |
 
 The whole file is sent to logged-in users as part of the manga page. **Don't put secrets in it** (scraper tokens, cookies).
 
+An AniList refresh with a different ID is stopped for review before chapter publication. Existing files that already contain `x-scraper.autoUpdate` keep that choice; the scraper does not guess whether an older value was automatic or manual. New files leave the choice absent so the default can follow status changes.
+
 ### `book.json`
 
 | Field | Type | Meaning |
@@ -188,7 +205,17 @@ The whole file is sent to logged-in users as part of the manga page. **Don't put
 | `priority` | number | Tie-breaker between versions with equal votes. Higher wins (default `0`) |
 | `direction` | as above | Overrides book/manga direction, e.g. a colour webtoon special inside a printed series |
 
-`direction` is inherited **chapter → book → manga → `rtl`**, and each version can carry its own.
+Manual directions have priority at **chapter → book → manga**. A `directionOverride`
+or a plain `direction` without matching generated provenance is manual. Otherwise,
+the scanner checks the version's existing image dimensions for coherent tall strips
+and uses `ttb` when they are present. A prior generated vertical series direction
+applies to chapters with insufficient shape evidence. The final fallback is `rtl`;
+this does **not** classify a work as Japanese or prove its reading order. A direct
+edit to a generated `direction` becomes manual when it differs from its provenance.
+Existing plain directions are treated as manual because old scraper defaults and
+human edits cannot be distinguished safely. Set `directionOverride` to make a
+lasting choice, or explicitly review and migrate a legacy entry. Image files and
+chapter IDs do not change when direction metadata changes.
 
 ## Picture-viewer compatibility