Consolidate MangaCircus app, scraper, and Compose baseline

docs/scraper-guide.md

@@ -83,9 +83,13 @@
   ```
   c<NNNN>[.<d>][ <title>][ [<Source>]]     regular chapter
   x<NN>[ <title>][ [<Source>]]             extra chapter outside the numbering
+  special-mangadex-<chapter-uuid>[ <title>][ [<Source>]]  unnumbered source release
   ```
   - A **space** MUST follow the number when anything follows. `c0012_Title` sorts wrongly in file browsers; `c0012a` and `c0012Title` are not recognised at all.
   - Recommended check: `^(c\d{4}(\.\d*[1-9])?|x\d{2})( [^\[\]]+?)?( \[[^\[\]]+\])?$`
+  - For the additive `special-mangadex-` form, validate the complete UUID using
+    `chapter-identity.js`. Do not apply the numeric-only check above. The key is the
+    lower-case source UUID prefix, not an invented numeric chapter. Books remain numeric.
 - **R-C2** Pad the chapter number's integer part to 4 digits. Never change the padding of an existing manga: chapter folder names are version ids.
 - **R-C3** Map upstream numbering like this:
 
@@ -102,6 +106,14 @@
 | Volume extras (afterword, sketches) | `x<NN>` in that volume's book | |
 | One-shot | its own manga (`v01/c0001`), or `x<NN>` inside an `x01 Oneshots` book of the related series | |
 | Negative or non-numeric only | `x<NN>` | Never invent a number that collides with a real one |
+| Unnumbered MangaDex release | `special-mangadex-<chapter-uuid>` | Stable upstream release identity; label Pilot, One-shot or Special; do not assign chapter 0/1 |
+
+Unnumbered source-ID releases sort after numeric chapters. Their `chapter.json`
+stores `special:true`, `label`, `sourceId` and the original `sourceNumber` (usually
+null). They are not automatically skippable extras: an entire pilot may be story
+content. Keep different release UUIDs separate rather than guessing that they are
+the same logical chapter. Reimporting the same key is duplicate-safe. Existing
+numeric and `x` folder conventions and progress IDs MUST NOT be migrated or renamed.
 
 - **R-C4** The title part of the folder name is for humans only.
   - The authoritative title is `chapter.json` → `title`, without the "Chapter 12:" prefix.
@@ -174,7 +186,7 @@ All are UTF-8 JSON **without** BOM, pretty-printing optional.
   }
   ```
 
-  - `direction`:
+  - `direction` when an operator or reliable source explicitly provides the reading order:
 
     | Upstream type | Value |
     |---------------|-------|
@@ -186,6 +198,24 @@ All are UTF-8 JSON **without** BOM, pretty-printing optional.
   - Unknown fields are kept and ignored by the app. Keep your own state in one namespaced field such as `"x-scraper"`.
   - The whole file is shown to logged-in users. It MUST NOT contain secrets (tokens, cookies, credentials).
   - **Read-modify-write:** keep fields you don't own, because people may have edited them. Write atomically (R-W5).
+  - **R-J4** The current adapters do not infer printed reading order from host,
+    language, country, or catalog labels. They emit `rtl` with
+    `"x-reading-direction":{"version":1,"value":"rtl","source":"fallback"}`.
+    The publisher checks already downloaded image dimensions: at least three pages
+    with height/width ≥ 4, at least 75% tall among known pages, consistent strip
+    widths within 25%, and dimensions known for at least 75% of pages yield
+    `direction: "ttb"` with `source: "detected"` and numeric evidence. A credits
+    card can coexist with the strips. This detects layout, not content or language.
+    Plain legacy directions and explicit `directionOverride` at any level are
+    preserved across later imports. Do not bulk-convert old `rtl` values: a past
+    scraper default and a human choice are indistinguishable. Use the reviewed
+    migration tool on a named series after checking representative chapters.
+    `node tools/review-reading-direction.js <absolute-library-manga-folder>
+    <weebcentral-series-id> --chapter=c0056` is a read-only review. To apply a
+    supported single-series correction, first pause and stop every writer and
+    create a stopped-writer snapshot, then add `--apply --writers-stopped`.
+    The tool verifies source identity, unchanged legacy RTL metadata, several
+    chapter samples, and the requested chapter before an atomic metadata write.
 
 - **R-J2** `chapter.json`, one per version folder:
 
@@ -240,7 +270,12 @@ MangaCircus can scan at any moment. Everything it can see must always be complet
   4. delete `.old-<random>`.
   The chapter is briefly absent, which is harmless: it won't be re-announced, and progress is kept.
 - **R-W5** Updating a JSON file: write `.<name>.tmp` in the same folder, then `rename` it over the target.
-- **R-W6** At start-up, delete your own leftover `.staging-*` / `.old-*` folders older than a few hours (from crashed runs).
+- **R-W6** Preserve incomplete staging folders: validated images are recovery assets,
+  not disposable garbage. The managed publisher resumes a hidden folder only when
+  its complete chapter/source/page-manifest fingerprint matches, and revalidates
+  stored images. Legacy random stages lack this identity and require manual review;
+  do not infer ownership or delete them merely because they are old. Completed
+  replacement `.old-*` backups may be cleaned after successful publication.
 - **R-W7** On Windows, `rename` can fail with `EPERM`/`EBUSY` while another process reads the folder. Retry a few times with a short delay.
 - **R-W8** Files MUST be readable by the MangaCircus process. In Docker that is uid 1000, so use mode `0644` for files and `0755` for folders.
 - **R-W9** You MUST NOT write anything into MangaCircus's `DATA` folder (`db.json`, `scan-cache.json`).