bindery-cli 0.39.0__tar.gz → 0.41.0__tar.gz

bindery_cli-0.41.0/.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+# A push supersedes the run for the same ref: the tree it tested is gone.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      # ruff is a dev-only linter; the rule set lives in pyproject.toml, so
+      # these mean the same thing locally. Checking `.` rather than named
+      # directories keeps a new top-level script from silently escaping lint.
+      - run: pip install ruff==0.16.2
+      - run: ruff check .
+      - run: ruff format --check .
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      # html5lib is the project's declared optional `reserialize` extra (core
+      # stays stdlib-only); installing it here lets CI exercise the
+      # --reserialize tests instead of skipping them.
+      - run: pip install . html5lib
+      - run: PYTHONPATH=src python -m unittest discover -s tests
+  core-compat:
+    name: Run the stack-free suite on the 3.12/3.13 floor
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The install floor (decision 63): vir-tui/cquarry are marker-gated
+        # to 3.14 there, so these legs install the core (tqdm only) and run
+        # exactly the test modules that never touch the gated stack: the
+        # repair core, the plugin under calibre stubs, validate, and the
+        # version/grammar pins. audit/library/CLI-stack tests stay on the
+        # 3.14 leg above.
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install . html5lib
+      - run: >
+          PYTHONPATH=src python -m unittest
+          tests.test_transforms tests.test_epub tests.test_pagination
+          tests.test_watermark tests.test_reserialize tests.test_version
+          tests.test_plugin tests.test_validate
+  plugin-compat:
+    name: Parse-check the plugin zip under the interpreters Calibre embeds
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # v0.39.0 shipped 3.14-only syntax and the plugin failed to load with
+        # a bare SyntaxError on every released Calibre. The embedded
+        # interpreters are 3.11 (7.x and the whole 8.x series) and 3.14
+        # (9.0+); 3.12/3.13 bracket the gap and match the CLI's grammar
+        # floor (tests/test_version.py). The plugin cannot be imported
+        # without Calibre, but the shipped zip can be extracted and
+        # byte-compiled, which catches exactly this class.
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Build the plugin zip from this tree
+        run: python scripts/build_plugin.py
+      - name: Byte-compile the zip contents and the CLI sources
+        run: |
+          python -m zipfile -e dist/BinderyRepair-*.zip plugin_pkg
+          python -m compileall -q plugin_pkg src

{bindery_cli-0.39.0 → bindery_cli-0.41.0}/.github/workflows/publish.yml

@@ -5,11 +5,20 @@ on:
     tags:
       - "v*.*.*"
 
+# A tag push is a release: never cancel a publish mid-run, and two tags
+# publishing concurrently would race the release page; serialize instead.
+concurrency:
+  group: publish-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: "3.14"
@@ -30,7 +39,7 @@ jobs:
       id-token: write # Required for OIDC authentication with PyPI
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: "3.14"
@@ -51,20 +60,28 @@ jobs:
     permissions:
       contents: write # create the release and attach the plugin zip
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: "3.14"
 
-      - name: Run the suite
-        run: |
-          pip install .[reserialize]
-          PYTHONPATH=src python -m unittest discover -s tests
-
+      # The suite already ran in the `test` job for this exact commit
+      # (needs: gates this job on it); running it again per job doubled the
+      # publish wall time for no extra signal.
       - name: Build the plugin zip from the tagged tree
         run: python scripts/build_plugin.py
 
+      # The tag message IS the release's patchnotes entry (verbatim, per the
+      # tagging procedure), so the release body is extracted from the tag
+      # object rather than paraphrased here. Without it the release page
+      # renders blank beside the zip.
+      - name: Extract the release body from the tag message
+        run: git tag -l --format='%(contents)' "${GITHUB_REF_NAME}" > release-body.md
+
+      # SHA-pinned to action-gh-release v2 (3bb1273): it carries contents:
+      # write, so the third-party action runs pinned, not floating.
       - name: Attach BinderyRepair zip to the release
-        uses: softprops/action-gh-release@v2
+        uses: softprops/action-gh-release@3bb12739c298aeb8a4eeaf626c5b8d85266b0e65
         with:
+          body_path: release-body.md
           files: dist/BinderyRepair-*.zip

{bindery_cli-0.39.0 → bindery_cli-0.41.0}/.gitignore

@@ -12,6 +12,11 @@ testing_facility/books_to_fix/*
 !testing_facility/books_to_fix/.gitkeep
 testing_facility/top500candidates/*.epub
 
+# The census report lists real titles at absolute library paths; the same
+# leak class as the book files above. Untracked 2026-09-15 (forward-only;
+# the file stays on disk as the --summary target).
+testing_facility/top500candidates/REPORT.md
+
 # test_facility EPUBs stopped being tracked in v0.33.0 (forward-only; 9 of
 # the 10 books are commercial and one untracked leak on a public repo is
 # one too many). Files stay on disk, out of git.

{bindery_cli-0.39.0 → bindery_cli-0.41.0}/CLAUDE.md

@@ -15,7 +15,11 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - **Minimal Dependencies.** Runtime deps are exactly: `tqdm` (progress/output),
   `vir-tui` (shared TUI rendering) and `cquarry` (read-only Calibre `metadata.db` access,
   adopted in v0.16.0), pinned as PyPI ranges in pyproject.toml (`vir-tui>=2.2.0`,
-  `cquarry>=1.9.0`); `uv.lock` records the resolved versions. `html5lib` remains the one approved
+  `cquarry>=1.19.0`); `uv.lock` records the resolved versions. Since v0.40.0 both
+  VirInvictus pins carry `; python_version >= '3.14'` markers (every release they
+  ship declares requires-python >=3.14) and the package floor is 3.12: a 3.12/3.13
+  install runs the stack-free repair core, and the audit/library surfaces degrade
+  through cli.py's dispatch guard instead of failing resolution. `html5lib` remains the one approved
   heavy-parsing exception (used only for the `--reserialize` fix, imported lazily so every
   other mode runs without it). Tests use the standard `unittest` framework. epubcheck is an
   external CLI dependency expected on PATH; `--install-to-calibre` needs no external
@@ -23,9 +27,11 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
   subprocess was retired in v0.24.0). Before adding any further Python package, stop and ask.
 - **Semantics-preserving transforms by default, everything else fenced behind a flag.**
   The always-on core is exactly five well-formedness fixes (prolog junk, duplicate
-  `xmlns`, bare `&`, named entities, void self-closing) plus the NCX pipeline; every core
+  `xmlns`, bare `&`, named entities, void self-closing), the NCX pipeline, and the
+  mimetype fix (added/normalized/first-stored, epub.py's archive rewrite); every core
   fix must render identically to the author's intent: never add, remove, or reorder
-  visible content. Two kinds of exceptions exist, both opt-in and off unless requested:
+  visible content. The canonical opt-in inventory lives in spec.md: fifteen structural
+  repairs, three lossy strips, four safe opt-ins, plus `--reserialize`.
   * **Structural repairs** (`--fix-empty-body`, `--fix-missing-title`, `--fix-id-colons`,
     `--fix-page-map`, `--strip-epub3-attrs`, `--downgrade-epub3-tags`,
     `--unwrap-block-in-inline`, `--strip-invalid-value`, `--unwrap-illegal-tags`,
@@ -43,23 +49,23 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
     `transforms.strip_attrs_in_start_tags` (prose mentioning the attributes and
     CDATA/comment content are preserved), and `strip_invalid_value` matches the
     attribute name with a `(?<![\w:.-])value` lookbehind so `data-value` survives.
-  * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`, `--strip-watermarks`;
-    pagination.py, watermark.py): remove only what a converter injected (page numbers,
-    running headers, leaked tags, watermarks), fenced behind character conservation, tag
+  * **Lossy strips** (`--strip-pagination`, `--strip-broken-tags`,
+    `--strip-watermarks`; pagination.py, watermark.py; `--strip-stub-docs`,
+    epub.py's `detect_stub_docs`): remove only what a converter injected (page numbers,
+    running headers, leaked tags, watermarks, repeated placeholder chapters), fenced behind
+    character conservation, tag
     balance, and the epubcheck no-regression bar. The watermark anchored pass's
     whole-match fallback only fires when the match holds nothing but the stamp; a
     larger match (an unclosed stamp anchor that swallowed prose) is refused, counted
     in `RepairReport.watermark_refusals`, and surfaced as a `manual_watermark_repair`
-    decision by `run phase1` on both the read-only and apply paths.
+    decision by `run phase1` on both the read-only and apply paths. `--strip-stub-docs`
+    (2026-09-15) mirrors emptytext's placeholder signals: identical short text across
+    >= 3 spine docs and >= 30% of the spine; the whole-spine-stubs book is refused
+    (EMPTY, re-source), and the drop cascades to archive entries, manifest, spine,
+    NCX navPoints, and nav toc entries.
   Do not let any NEW fix touch content without its own flag; if a candidate repair cannot
-  be made deterministically safe, it does not belong here — report it for manual repair
-  instead. A fourth, smaller group sits beside the structural repairs and lossy strips:
-  the safe opt-ins (`--fix-ids`, `--add-img-alt`, `--strip-bad-attrs`,
-  `--escape-unknown-entities`) plus `--encode-url-spaces`, which repair without
-  altering visible markup; the "twelve structural repairs and three lossy strips"
-  phrasing elsewhere in these docs was never the complete inventory, and the
-  Phase 16 package repairs (`--fix-container`, `--fix-media-types`, `--fix-cover`)
-  took the structural count to fifteen (v0.38.0 + v0.39.0).
+  be made deterministically safe, it does not belong here: report it for manual repair
+  instead.
 - **The gate is the safety contract.** Never apply a repair epubcheck has not accepted.
   Respect the two-mode logic in `validate.gate` (fatal-fixing tolerates error unmasking;
   error-cleanup does not). The lossy strips (`--strip-pagination`, `--strip-broken-tags`,
@@ -80,17 +86,18 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `src/bindery/pagination.py`: the opt-in lossy page-number strip (runhead detection, page-layer decision, block-centric removal/merge, safety nets).
 - `src/bindery/watermark.py`: the opt-in lossy watermark strip (anchored and anchorless signature removal).
 - `src/bindery/reserialize.py`: structural repair via `html5lib`.
-- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis — a damaged entry reports its own CORRUPT verdict instead of feeding emptytext — and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry — do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED).
-- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them — spine@toc, media-overlay, fallback, EPUB2 cover meta — are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
+- `src/bindery/audit.py`: read-only body-text audits (`content`, `pagenumbers`, `emptytext`, `ocr`, `monolithic` since v0.21.0 with `--max-doc-chars N`, and `completeness` since v0.36.0) behind the `audit` subcommand (v0.15.0). Since v0.18.0 library mode resolves EPUB paths through `cquarry.get_format_path()` and can apply a tag to flagged books via `cquarry.write.WritableCalibreDB` (only with explicit `--tag`; the only sanctioned write path). Since v0.19.0 `audit --id BOOK_ID` audits a single library book through cquarry's single-entity `get_book()` fetch (no library-wide cache; supports `--tag`; incompatible with the directory argument; comma lists since v0.23.0). Since v0.22.0 every archive entry is fully read (CRC + decompression) before analysis (a damaged entry reports its own CORRUPT verdict instead of feeding emptytext) and manifest/NCX references to absent files classify as `convention` (bloated ToC, consecutive span) or `fragment` (broken span). Hazard: the scan loop reuses `tag` as its per-book display column, so the `--tag` argument is captured as `audit_tag` at function entry; do not collapse them again. Since v0.29.0 `audit --json FILE` writes per-file analyzer verdicts in the `library --json` shape (directory, library, and single-book modes; with `--id`, exactly one id; emptytext omitted from a record when the archive verdict owns the body-text story). Since v0.36.0 the completeness analyzer (Phase 15) reports the phase-1 spot-check per book: spine/prose-doc counts (prose = >= 400 visible chars), first/middle/last prose-doc opening/closing excerpts, trailing-ToC classification (`_trailing_toc`: short link lines dominate, no paragraph-length blocks), and the unreadable fraction. It is ADVISORY by contract (problem always False; ADVISORY on a trailing ToC or unreadable fraction >= 10%), never moves the exit code, and is skipped like emptytext when the archive verdict owns the book. Since v0.38.0 the archive verdict distinguishes font obfuscation from DRM (`OBFUSCATION_ALGOS`: IDPF 2008/embedding + both Adobe URIs; readable obfuscated entries are the benign OBFUSCATED advisory, an unreadable one is CORRUPT, and only non-obfuscation algorithms give ENCRYPTED). Since v0.40.0 the vir-tui console renderer loads through the module-level `_LazyUI` proxy (a plain `import vir_tui as ui` at module level would make 3.12/3.13 installs unimportable now that the stack is marker-gated; LOAD_GLOBAL never consults module `__getattr__`, so a proxy object is the lazy shape that works).
+- `src/bindery/epub.py`: archive rewrite, NCX uid sync, RepairReport, mismatch detection, and the opt-in structural-repair plumbing (including the CSS precondition scan). Since v0.38.0/v0.39.0 (Phase 16): `generate_container` + the `--fix-container` gateway (insert after mimetype when missing, replace in-loop when stale; constant-epoch timestamp keeps bytes deterministic), `prune_dangling_edges` (prune_missing_manifest_items returns the pruned ids and the edges that pointed at them (spine@toc, media-overlay, fallback, EPUB2 cover meta) are rewritten so pruning cannot manufacture the regression the gate rejects), and `fix_manifest_media_types` (extension map + magic-byte confirmation via a `peek` callable over the open source zip; jpg/png/gif only), and `fix_cover_meta` (the ruling's deterministic half: dangling EPUB2 cover meta re-pointed from the guide's cover reference when exactly one manifest item carries that file, removed otherwise; accepted under no_worse like the lossy strips because cover wiring is invisible to epubcheck).
 - `src/bindery/validate.py`: epubcheck wrapper, the `gate` (improvement) and `no_worse` (no-regression, for the lossy strips) acceptance bars.
-- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched — never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book.
-- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2). Both take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract).
-- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape.
-- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin, and the Calibre plugin (build drift + run behavior under calibre stubs).
+- `src/bindery/library.py`: Calibre walk, atomic replace, backups, and native format installation. Since v0.19.0 `CalibreIdResolver` resolves the book id from `metadata.db` through cquarry (one lazy path→id map per run; since v0.20.0 the map comes from `CalibreDB.format_path_index()`, re-normalized with `resolve().lower()` for the resolver's symlinked-directory and case-insensitive matching); the `(id)` directory-name regex is only the no-catalog fallback. Since v0.24.0 `install_format()` places the repaired file atomically and updates the `data` row through `cquarry.write.WritableCalibreDB` (since v0.31.0 via `set_format`, cquarry 1.17's sanctioned remove+add in one transaction); the external `calibredb` CLI is gone. Since v0.32.0 a guessed id drives a row update only when metadata.db corroborates it (`_verify_guess`: books row exists, file in the book's own directory, catalogued `data.name` when a row exists); anything else saves in place and leaves the catalog untouched: never reintroduce directory-name guessing as the primary source: renamed/mismatched directories would replace the wrong book. Since 2026-09-15 `make_backup` takes the opt-in `--backup-keep N` ring: at most N backup files per book, the author original `.bak` never deleted, newest content at the highest name; default remains an unbounded rotation.
+- `src/bindery/cli.py`: `repair` and `library` subcommands, including `--all` and `--install-to-calibre`; `repair --json` emits the library per-book record vocabulary (2026-09-15); since v0.29.0 also the `run` verbs: `phase1` (pre-import vetting over loose files: the audit battery composed with one gated repair sweep; read-only until `--apply-lossy`, which IS the lossy-strip consent) and `phase3` (the scoped post-import apply step: `library --id --sweep --only all --apply --all --install-to-calibre` plus a pre/post summary; mechanically refuses unscoped sweeps with exit 2; since 2026-09-15 the summary sums applied/equal states only and carries rejected projections as `rejected_projection`). Plus `bindery doctor` (2026-09-15): the environment self-check that imports none of the VirInvictus stack, never raises, and always exits 0. Both run verbs take `--non-interactive` and surface open questions as `decisions_needed` in their JSON, never prompts. They drive the shipped `run_library` through the real parser, so no flag can drift between the verb and the subcommand it wraps. `library --workers N` (v0.30.0) parallelizes only the sweep's candidate pass, in windows of N consumed in order so `--limit` stays lazy; the repair phase is never parallel (shared workdir, atomic-replacement contract). Since v0.40.0 `main()` guards the VirInvictus stack: a `ModuleNotFoundError` naming `vir_tui`/`cquarry` (marker-gated to 3.14+ on the 3.12 floor) becomes one stderr line and trouble exit 2 instead of a traceback; anything else missing still raises.
+- `plugin/__init__.py` + `scripts/build_plugin.py`: the Bindery Repair Calibre plugin (v0.37.0; identity `Bindery Repair` / `bindery_repair`, approved and built per the scoped spec in roadmap.md Phase 3). The builder vendors `transforms.py`, `epub.py`, `pagination.py`, `watermark.py`, `reserialize.py` byte-identically into the zip (the zip root is a package, so their relative imports resolve unchanged; the suite's drift test pins the equality) with the version tuple substituted from the single-source VERSION; `publish.yml` attaches `BinderyRepair-v<VERSION>.zip` to each release. The plugin runs ONLY the default pass (epubcheck cannot gate inside Calibre), never raises, is byte-idempotent (zero fixes returns the original path), testzip()-verifies its output, logs one line per book, and takes JSON config via `site_customization` (`log`, `log_path`, `max_size_mb` default 150, `epubcheck_path` experimental validation default OFF). Load it in tests through the `tests/test_plugin.py` stubs: the calibre namespace is installed in sys.modules and the package loads with a two-dir `__path__` (plugin dir first, then src/bindery) exactly like calibre's zipplugin loader shape. **Plugin/interpreter compatibility (v0.40.0):** v0.39.0 shipped PEP 758 unparenthesized except tuples, and the plugin died with a bare SyntaxError on every released Calibre (7.x and the whole 8.x series embed Python 3.11, 9.0+ embeds 3.14; from calibre's bypy sources.json, checked against the upstream clone). The core is now grammar-pinned: parenthesized except tuples everywhere, `ruff`'s `target-version = "py312"` pin (inference from requires-python would rewrite the parens back off), `tests/test_version.py`'s parse guard, and CI's `plugin-compat` job byte-compiling the built zip under 3.11/3.12/3.13/3.14. `minimum_calibre_version` is (7, 0, 0): the oldest series whose interpreter CI covers, replacing the hollow (2, 0, 0); `supported_platforms` stays `["linux"]` (developed and tested on Linux only). Any new syntax in the vendored modules must clear the guard before it ships.
+- `tests/`: transforms, end-to-end repair, atomic replace, pagination, watermarks, the audit analyzers (content/pagenumbers/emptytext/ocr/monolithic/completeness, archive integrity, spine classification), the library sweep and `CalibreIdResolver`, validate, reserialize, CLI wiring, the version pin and the syntax-floor grammar guard, and the Calibre plugin (build drift + run behavior under calibre stubs).
 
 ## Conventions
 
 - Type hints, `from __future__ import annotations`, ruff for lint and format.
+- `./run_tests.sh` runs the suite in the project venv. Since the 3.12 floor, `uv run --python X` REBUILDS `.venv` for interpreter X, and the `python_version >= '3.14'` markers then gate vir-tui/cquarry OUT of it below 3.14 (the suite goes red with ModuleNotFoundError: cquarry). After interpreter experiments, rebuild with `uv run --python 3.14` before running the suite again.
 - `VERSION` lives in `src/bindery/__init__.py`, mirrored in `pyproject.toml`. Bump both.
 - Run tests with `./run_tests.sh`.
 

bindery_cli-0.39.0/README.md → bindery_cli-0.41.0/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.5
+Name: bindery-cli
+Version: 0.41.0
+Summary: Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library.
+Project-URL: Homepage, https://github.com/VirInvictus/bindery-cli
+Project-URL: Repository, https://github.com/VirInvictus/bindery-cli
+Project-URL: Changelog, https://github.com/VirInvictus/bindery-cli/blob/main/patchnotes.md
+Author: vrnvctss
+License: MIT
+License-File: LICENSE
+Keywords: calibre,ebook,epub,epubcheck,html-repair,repair,watermarks
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: cquarry>=1.19.0; python_version >= '3.14'
+Requires-Dist: tqdm
+Requires-Dist: vir-tui>=2.5.0; python_version >= '3.14'
+Provides-Extra: reserialize
+Requires-Dist: html5lib>=1.1; extra == 'reserialize'
+Description-Content-Type: text/markdown
+
 <div align="center">
   <img src="logo.svg" width="96" height="96" alt="bindery-cli logo"/>
   <h1>bindery-cli</h1>
@@ -10,7 +37,7 @@
 
 ## What it fixes
 
-bindery-cli makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over — nothing else changes without an explicit flag:
+bindery-cli makes accidentally broken markup well-formed again. It does not rewrite or reflow content. The **default pass** applies only a small set of deterministic, semantics-preserving well-formedness fixes that real-world EPUBs (especially Calibre conversions) trip over; nothing else changes without an explicit flag:
 
 - **Unclosed void elements** (`<link>`, `<br>`, `<img>`, ...) get self-closed.
 - **Undeclared named entities** (`&nbsp;`, `&deg;`, `&eacute;`, ...) become numeric character references that every XML parser understands.
@@ -22,7 +49,7 @@ bindery-cli makes accidentally broken markup well-formed again. It does not rewr
 
 ### Opt-in repairs
 
-Everything below is off until its flag is passed (or all at once via `--all`). They go further than well-formedness — altering structure or adding minimal content — so they never run by default:
+Everything below is off until its flag is passed (or all at once via `--all`). They go further than well-formedness (altering structure or adding minimal content), so they never run by default:
 
 - **`--fix-ids`**: rewrite ids that are not valid XML names (start with a digit, contain a colon) in the OPF manifest, updating every reference to them (spine, fallback, media-overlay, the EPUB 2 cover meta), and in the NCX (where old conversions stamp navPoint ids from UUIDs). Touches the OPF, so it is off by default; the dc: metadata is never altered.
 - **`--add-img-alt`**: add `alt=""` to `<img>` elements missing the required attribute. Renders identically, but it adds markup the author never wrote, and an empty alt tells a screen reader the image is decorative; hence opt-in.
@@ -34,7 +61,7 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--fix-missing-title`**: injects a `<title>Unknown</title>` fallback in the `<head>` if missing, handling both empty `<title/>` self-closing tags and entirely absent tags.
 - **`--unwrap-block-in-inline`**: safely unwraps `<span>` tags that illegally contain a block-level element (e.g. `<div>` or `<p>`), leaving the block element intact.
 - **`--strip-invalid-value`**: systematically strips invalid `value="..."` attributes from elements like `<div>`, `<span>`, `<p>`, etc.
-- **`--fix-page-map`**: normalizes legacy page-map markup — drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
+- **`--fix-page-map`**: normalizes legacy page-map markup: drops the non-standard `page-map="..."` attribute from the OPF `<spine>` and adds `class="pages"` to classless NCX `<pageList>` elements (epubcheck rejects both on older HarperCollins / Anna's Archive conversions).
 - **`--strip-epub3-attrs`**: scrubs the EPUB3-only attributes epubcheck rejects on an EPUB2 package: `page-progression-direction`, `epub:type`, `aria-label` (a fixed, documented set; rendering is unchanged, and lookalikes like `type` or the wider aria family survive). The edit is anchored to real start tags, so prose that merely mentions `epub:type="chapter"` is preserved.
 - **`--downgrade-epub3-tags`**: downgrades EPUB3/HTML5 semantic elements to their EPUB2 equivalents (`figure`/`section` to `div`, `figcaption` to `p`), keeping existing classes and appending the semantic name (`class="figure"`) as the styling hook. Tag names a stylesheet styles as an element selector are protected book-wide, so styled formatting is never destroyed. Both EPUB2-targeted fixes are gated on the package version declared in the OPF: on an EPUB 3 book they do nothing, because their target defects only exist below EPUB 3.
 - **`--unwrap-illegal-tags`**: strips completely invalid or deprecated HTML tags that break EPUB3 validation (`<st>`, `<sentence>`, `<o>`, `<w>`, `<pagebreak>`) while retaining their inner text. Any of those names styled as an *element selector* by an EPUB stylesheet (`.css` entries and inline `<style>` blocks alike; class/id selectors like `.st`/`#w` don't count) is protected for the whole book, guaranteeing format preservation.
@@ -42,15 +69,16 @@ Everything below is off until its flag is passed (or all at once via `--all`). T
 - **`--strip-broken-anchors`**: strips href attributes that cannot resolve, keeping the anchor text byte-for-byte: a `#fragment` the target document does not define (RSC-020/RSC-012; NCX navTargets fall back to the document target, so chapter navigation survives) and unresolvable URI schemes (`kindle:`, `file:`).
 - **`--encode-url-spaces`**: percent-encodes raw spaces in `src`/`href` attribute values across the package (OPF manifest, NCX, content documents). A URL with a literal space is not a valid URL (RSC-020) and unresolvable on strict readers; the encoded form denotes the same file.
 - **`--fix-container`**: generates `META-INF/container.xml` at the located OPF when the container is missing or names a file the archive does not contain. This is the gateway defect: epubcheck stays fatal while the OPF is unfindable, so no repair can be gate-accepted on such a book until the container exists.
-- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so an honestly-declared misnamed file is never made worse.
+- **`--fix-media-types`**: normalizes wrong manifest media-type declarations (OPF-029, e.g. a jpg stamped `image/png` by an aggregator). Attribute-only and quote-preserving; it fires only when the file's magic bytes confirm the extension, so a misnamed-but-consistent file (a PNG renamed .jpg) is never made worse.
 - **`--fix-cover`**: repairs dangling EPUB2 cover wiring. A `<meta name="cover">` whose content names no manifest item is re-pointed when the OPF guide's own cover reference names an existing item, and removed when nothing identifies it; EPUB3 `properties="cover-image"` is deliberately audit-only (guessing which image is the cover is not deterministic). Cover wiring is invisible to epubcheck, so cover-only repairs are accepted under the same no-worse bar the lossy strips use.
 
 
-Three opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
+Four opt-in fixes are **lossy** and stand apart from the semantics-preserving rest:
 
 - **`--strip-pagination`**: remove print page numbers and running headers that a PDF/OCR conversion baked into the body text as literal paragraphs (so they reflow into the middle of a sentence: "where the hay cart **16** was taking him"). It removes only that injected furniture, never the author's prose: where a number split a sentence it rejoins the two paragraphs (closing up a word split like `compli-` / `mentary`), and it preserves roman chapter numbers, page-list nav anchors, and years. A roman numeral counts as a page number only when it is well-formed and under 100, so ordinary words (`mid`, `mix`, `civil`) are never mistaken for pages. A book is only treated as paginated when it has both a dense run of arabic numbers and several confident mid-sentence interrupts, so a merely chapter-numbered book is left alone. Three safety nets guard every edit (character conservation, tag balance, and an epubcheck no-regression check); any failure leaves the document untouched.
 - **`--strip-broken-tags`**: remove leaked HTML closing tags missing their open brackets (e.g. `</p>`) that render as raw text.
 - **`--strip-watermarks`**: remove known producer and distributor watermarks (e.g. OceanofPDF, ABC Amber LIT Converter) and stray marker files. It locates the stamp and deletes the outermost wrapper whose entire visible text is the watermark, ensuring prose that merely mentions the URL is preserved. An inline stamp link is deleted only when it holds nothing but the stamp; a match too large to be safe (an unclosed stamp anchor that swallowed prose) is refused and reported for manual repair rather than deleted.
+- **`--strip-stub-docs`**: drop spine documents whose entire visible text is one identical short placeholder repeated across the spine: the Bookmate-style export whose chapters are all the same "content unavailable" notice, passing epubcheck because the placeholder is valid XHTML. The drop cascades (archive entries, manifest items, spine order, NCX navPoints, nav toc entries), so the book opens straight into its real chapters. The identity rule is deliberately conservative (same text, at least 3 docs, at least 30% of the spine, each doc short but not blank) and a book whose *every* spine doc is the stub is refused outright: that book is empty and needs a re-source, never a repair.
 
 All lossy edits are invisible to epubcheck, so they are accepted when the result is *no worse* rather than measurably better.
 
@@ -69,7 +97,39 @@ The lossy modes (`--strip-pagination`, `--strip-broken-tags`, and `--strip-water
 
 ## Install
 
-Python 3.14+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and `cquarry` (read-only Calibre database access); `html5lib` remains an optional extra, needed only for `--reserialize`.
+Python 3.12+, plus epubcheck on `PATH` for the gate. Dependencies: `tqdm` for
+progress output, plus the VirInvictus libraries `vir-tui` (TUI rendering) and
+`cquarry` (read-only Calibre database access), which install on Python 3.14+
+only; `html5lib` remains an optional extra, needed only for `--reserialize`.
+
+epubcheck (W3C's conformance checker) is the gate's oracle and the one
+dependency pip cannot install for you. It needs a Java runtime. Any of these
+works:
+
+- your package manager, where it ships: `apt install epubcheck` (Debian/Ubuntu),
+  `brew install epubcheck` (macOS), `epubcheck` in the AUR (Arch); or
+- the release zip from [w3c/epubcheck](https://github.com/w3c/epubcheck/releases):
+  unzip it and put its `epubcheck` launcher script somewhere on `PATH`.
+
+Verify with `epubcheck --version`. A validated run refuses to start without it
+(exit 1: "epubcheck not found") rather than silently skipping the gate; only
+`--no-validate` bypasses it, and the Calibre plugin never needs it (its default
+pass runs ungated by design). `scripts/fast_sweep.py` also accepts
+`EPUBCHECK_JAR` pointing at the jar directly.
+
+`bindery doctor` runs all of these checks for you: it reports the Python
+stack tier, the epubcheck version, Java, the optional html5lib, and whether a
+Calibre library is discoverable from the current directory. It always works
+and always exits 0; the findings are the output.
+
+The floor is two-tier by those markers: on Python 3.14 everything runs. On
+3.12/3.13 the install carries the repair core only, which is the tool's core
+job: `bindery repair` on a single EPUB works in full, while `bindery audit`,
+`bindery library` and `bindery run` print a one-line note that the command
+needs the Python 3.14 stack instead of dying in a traceback. (Every vir-tui
+and cquarry release on PyPI currently declares `requires-python >=3.14`, so
+the stack itself cannot follow the floor down until they move.) CI runs the
+stack-free test modules on real 3.12 and 3.13 interpreters.
 
 ```sh
 uv tool install bindery-cli                            # core tools
@@ -82,10 +142,23 @@ Each release also ships **BinderyRepair-v<VERSION>.zip**, a Calibre plugin that
 repairs EPUBs as they are imported: it is attached to the GitHub release beside
 the PyPI wheel (install it via Calibre's Preferences, Plugins, "Load plugin
 from file"). The plugin is the CLI's always-on core pass only: the five
-well-formedness fixes plus the NCX pipeline. The structural repairs and lossy
+well-formedness fixes, the NCX pipeline, and the mimetype fix. The structural
+repairs and lossy
 strips stay CLI-only, because their acceptance is the epubcheck gate and
 epubcheck cannot run inside Calibre; nothing runs ungated in the plugin, ever.
 
+Compatibility: the plugin declares a minimum Calibre of **7.0** and
+`supported_platforms` is Linux. Both floors state what is actually verified, no more:
+released Calibre embeds Python 3.11 through the whole 8.x series and 3.14 from
+9.0 on, and CI byte-compiles the shipped plugin zip under Python 3.11, 3.12,
+3.13 and 3.14, so the plugin parses on every current Calibre series; 7.x is
+the oldest whose interpreter CI covers, 2.x-6.x embed interpreters nothing
+verifies. The Calibre API surface the plugin uses is the long-stable
+`FileTypePlugin` shape, exercised against test stubs only; the plugin is
+developed and tested on Linux (v0.39.0 shipped the 3.14-only except syntax
+and silently failed to load on every released Calibre, which is the failure
+this floor and CI now guard against).
+
 Behavior and guarantees:
 
 - `run()` never raises and never touches the original file or `metadata.db`: a
@@ -103,9 +176,12 @@ Configuration is the plugin's customization string, parsed as JSON:
 
 ```json
 {"log": true, "log_path": "/path/bindery_repair.log", "max_size_mb": 150,
- "epubcheck_path": null}
+ "max_log_mb": 2, "epubcheck_path": null}
 ```
 
+The log rotates at `max_log_mb` (default 2MB, one `.old` generation kept;
+`0` disables rotation), so years of imports cannot grow it without bound.
+
 `epubcheck_path` opts into the experimental on-PATH validation mode: the
 repaired copy is re-measured with your epubcheck binary and refused unless it
 is no worse than the original. It defaults to off; the default pass is safe
@@ -113,16 +189,17 @@ without a gate, and the mode costs two epubcheck runs per imported book.
 
 ## Usage
 
-Four verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
+Five verbs: `bindery repair` fixes a single EPUB epubcheck-gated, `bindery audit`
 reports content flaws without touching anything, `bindery library` sweeps a Calibre
 library tree (dry run by default; `--apply` replaces accepted books atomically in place),
-and `bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
-vetting, phase-3 scoped post-import repair) for a calling agent.
+`bindery run` composes the acquisition pathway's EPUB slices (phase-1 pre-import
+vetting, phase-3 scoped post-import repair) for a calling agent, and `bindery doctor`
+checks the installation (see Install).
 The sections below take each in turn.
 
 ## Auditing
 
-bindery-cli includes a comprehensive auditing tool to inspect EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
+bindery-cli's auditing tool inspects EPUB body text for non-schema flaws that epubcheck cannot catch. It extracts and analyzes the visible text to detect content issues, producing console reports that can be used to filter your library or feed into `bindery repair`.
 
 Scan a Calibre library for specific issues:
 
@@ -156,7 +233,7 @@ Audits can also be run on a directory of loose `.epub` files by passing the path
 bindery audit pagenumbers /path/to/loose/epubs
 ```
 
-Or on one or more library books by Calibre id (comma-separated) — fetched through cquarry's single-entity `get_book()` (no library-wide scan), with the EPUB resolved via cquarry's own path logic:
+Or on one or more library books by Calibre id (comma-separated), fetched through cquarry's single-entity `get_book()` (no library-wide scan), with the EPUB resolved via cquarry's own path logic:
 ```sh
 cd ~/docs/Calibre\ Library && bindery audit all --id 1234,1235
 ```
@@ -168,14 +245,16 @@ bindery audit all ~/Downloads/epubs --json vetting-report.json
 ```
 With `--id`, `--json` accepts exactly one book id (each single-book run writes the file wholesale).
 
+**Thresholds:** `--min-chars N` and `--thin-chars N` are the EMPTY and THIN body-text thresholds (defaults 2000 and 20000); `--min-chars` above `--thin-chars` is a usage error. `--max-doc-chars N` is the monolithic-document flag threshold (default 300,000). All three belong to the audit parser only (`bindery library --min-chars …` is an unknown-flag error).
+
 **Spine-integrity reporting:** Both `audit` and `library` reports now classify manifest/NCX references that point to absent files. A `convention` verdict means the ToC is bloated but the present documents form a consecutive chapter span (e.g., the Wandering Inn official-build pattern, safe). A `fragment` verdict means the span itself is broken.
 
-**Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT — with the first broken entry named — instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
+**Archive integrity:** every audit fully reads each archive entry (CRC + decompression), so a damaged download is reported CORRUPT, with the first broken entry named, instead of being mislabeled EMPTY by `emptytext`. `library --sweep` splits its `unreadable` bucket into `not_a_zip` / `truncated` / `encrypted` / `corrupt_entry`, so the right disease is visible without leaving the sweep.
 
 ### Tagging flagged books (opt-in)
 
 By default an audit writes nothing. With `--tag TAG` (library mode only), every book the audit
-flags is tagged in `metadata.db` through cquarry's trigger-safe write module — useful for piping
+flags is tagged in `metadata.db` through cquarry's trigger-safe write module, useful for piping
 flagged books back into Calibre views:
 
 ```sh
@@ -186,7 +265,7 @@ The audit itself stays read-only; only the final tagging pass writes, it skips b
 carry the tag, and THIN emptytext advisories are never tagged. Close Calibre first so the write
 does not fight its lock. Tagged books are recorded in Calibre's `metadata_dirtied` queue, so the
 desktop app regenerates their sidecar `.opf`s (and re-pushes metadata to wireless readers) on its
-next startup — no manual resync needed.
+next startup: no manual resync needed.
 
 
 Repair one book to a new file (gated; writes only if it is an improvement):
@@ -195,8 +274,15 @@ Repair one book to a new file (gated; writes only if it is an improvement):
 bindery repair broken.epub                 # -> "broken (repaired).epub"
 bindery repair broken.epub fixed.epub
 bindery repair scanned.epub --strip-pagination   # also remove baked-in page numbers
+bindery repair stubs.epub --strip-stub-docs      # drop repeated placeholder chapters
+bindery repair broken.epub fixed.epub --json report.json  # machine-readable record
 ```
 
+`repair --json FILE` writes one record in the `library --json` per-book
+vocabulary (`status`, `applied`, `before`/`after` counts, the fix `summary`),
+on every processing outcome including nochange and reject: a calling agent
+gets the same facts the console lines carry.
+
 Scan a Calibre library and see what would be fixed, writing nothing:
 
 ```sh
@@ -219,17 +305,16 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--id <ids>` limits the sweep to a comma-separated list of Calibre book IDs, skipping the full library walk.
 - `--audit CSV` (the `fatals,errors,warnings,path` format produced by an epubcheck sweep) skips clean books so a run is fast. Paths are resolved on both sides, and a CSV that matches nothing triggers a loud warning instead of silently selecting zero books.
 - `--limit N` processes at most N candidates and stops opening archives after them (lazy within one worker window). A value below 1 is a usage error.
-- `--min-chars N` and `--thin-chars N` are the audit's EMPTY and THIN body-text thresholds (defaults 2000 and 20000); `--min-chars` above `--thin-chars` is a usage error. `--max-doc-chars N` is the audit monolithic-document flag threshold (default 300,000).
 - `--sweep` replaces the CSV step entirely: it runs a live epubcheck sweep for candidate selection and reuses each result as that book's before-measurement, so no book is checked twice. bindery-cli may serve checks from a small persistent Java daemon (see the gate section above for how it is bounded and how it fails safe); wherever the daemon cannot serve, the run falls back to the standard per-book epubcheck subprocess at the usual seconds per book. Combine with `--only fatals` for a self-contained "find and fix the broken books" run.
-- `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle honestly; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
+- `--workers N` runs the sweep's candidate pass through N concurrent epubcheck workers (default 1: serial, unchanged). The subprocess releases the GIL, so threads parallelize the oracle truthfully; books are checked in windows of N consumed in order, so the candidate set matches the serial sweep and `--limit` stays lazy within one window of overshoot. The repair phase stays serial: that is where the shared workdir and the atomic-replacement contract live.
 - `--json FILE` writes a machine-readable report of the whole run (per-book status, before/after counts, applied flag, summary totals). `--manual-list FILE` writes the paths of every book that was not auto-repaired, one per line, ready for manual follow-up.
-- `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file.
+- `--apply` is required to write; the default is a dry run. `--backup DIR` mirrors originals before replacing; `--backup-inplace` writes `.epub.bak` beside each file. `--backup-keep N` bounds the rotation: at most N backup files per book (the author original `.epub.bak` is never deleted), so a years-long apply habit cannot grow backups without bound.
 - `--install-to-calibre` resolves the Calibre book id from `metadata.db` via cquarry (one read-only path→id map per run), so a hand-renamed `Author/Title (id)/` directory can never send the repaired file to the wrong book. The directory-name regex is only a no-catalog fallback; with neither, the file is saved atomically in place.
 - `--install-to-calibre` installs the repaired EPUB through cquarry's write module: the file is placed atomically at the catalogued path (same filename, Calibre's layout never changes) and the format row is re-registered in one transaction, so the stored size stays truthful and the book lands in `metadata_dirtied`; Calibre regenerates its sidecar .opf on next start. No external `calibredb` call is involved. It falls back to atomic file replacement if the Calibre database ID cannot be resolved, and a database failure degrades to the in-place save with a warning. A directory-name-guessed id is trusted only when `metadata.db` corroborates it (the book exists and the file is that book's catalogued EPUB); an uncatalogued stray file inside a book directory is saved in place and the catalog row is left untouched.
 - `--all` automatically turns on all opt-in non-fatal fixes and lossy strips (pagination, watermarks, bad attributes, unknown entities, image alt tags, etc.) in a single run.
 - Only the `.epub` is replaced. `metadata.opf`, `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync to reconcile.
 - A per-book progress line goes to stderr (stdout stays a clean report); `--quiet` suppresses it. A corrupt or unreadable book is reported and skipped, never aborting the sweep.
-- Exit codes: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1.
+- Exit codes for `repair`, `library`, and `run`: 0 for a clean sweep, 1 for a usage error, 2 when any book was rejected, unreadable, or failed epubcheck (for scripts and cron). Note that argparse-level misuse (an unknown flag or a malformed argument) exits with 2 before any validation runs; the tool's own usage validations exit 1. The `audit` verb runs its own contract, the inverse shape: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors (a path that is not a directory, a directory with no EPUBs, an unknown book id).
 - A `partial` book (improved but still unable to open) is reported for manual follow-up and fails the run with exit 2, in `library`, `run phase1`, and `run phase3` alike: a book that still needs a human is trouble.
 - `repair` refuses to overwrite an existing output file unless `--force` is given.
 
@@ -272,7 +357,7 @@ cd ~/docs/Calibre\ Library && bindery run phase3 --ids 5071,5072 --json phase3-r
 
 `scripts/` holds standalone, read-only utilities that are useful for EPUB maintenance but fall outside bindery-cli's repair contract (fixing what they find would be a content change, which bindery-cli makes only via the opt-in `--strip-pagination`):
 
-- `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
+- `fast_sweep.py`: compiles and drives `FastSweep.java`, a parallel JVM epubcheck sweep that pays JVM startup once instead of per book (a 7,000-book dry-run sweep drops from hours to minutes). `--mode=audit` emits the `fatals,errors,warnings,path` CSV that `bindery library --audit` reads, with the counts taken from the same aggregated JSON surface the gate measures (not the raw occurrence counters), so selection and gating always agree; `--mode=extract` emits per-book error codes for aggregation (`--summary` prints the per-code report). The epubcheck jar is located from the `epubcheck` launcher or `EPUBCHECK_JAR`; the harness compiles once (`--release 25`) and is cached on mtime.
 
 The older `find_*.py` detection wedges and the `sweep.sh`/`FastSweepExtract.java` prototypes were removed: every detection they performed is now a shipped, tested flag (missing images are `--prune-missing-resources`, and the rest of the RSC-005/PKG-010 family shipped through Phases 6-12), and keeping two copies meant future behavior changes landed in only one of them. Git history preserves them.