bindery-cli 0.48.1__tar.gz → 0.48.2__tar.gz

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/CLAUDE.md

@@ -120,7 +120,7 @@ Born from the 2026 library audit (see the user memory `calibre-library-epubcheck
 - `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.45.0 every per-book record, the phase1 payload included, also carries the structured fix breakdown: the `fixes` dict plus `ncx_uid_synced`/`watermark_refusals` off the `Outcome`, and `_phase1_decisions` reads that data instead of substring-matching the rendered `summary`, which stays for human eyes; CalibreQuarry's lossy-consent mirror is the waiting consumer, floor `bindery>=0.45.0`); 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. Since v0.46.0 `cli._flags_from_args(args)` is the one place the argparse names map onto `RepairFlags` fields (each `or --all`), shared by `run_library` and `run_repair`; the old per-verb ~25-kwarg blocks are gone. Since v0.47.1 the help is two-level (the --help-repairs reference is
   custom-rendered and colors itself with the CPython 3.14 argparse theme,
-  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. `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.
+  gated by argparse's own _colorize detection so the levels always agree) and the repair-flag inventory is one table: `_REPAIR_FLAG_TABLE` (dest + one-line short help + long reference text) registers the compact grouped `--help` (argparse argument groups, hand-short usage line) and `--help-repairs` renders the long descriptions (a custom argparse Action, deliberately NOT store_true so the wiring test's selection count ignores it); adding a flag means adding a table row. Since v0.48.0 the metadata.db doors are enforced: `_require_closed_calibre` (pgrep fail-closed, exit 1) guards `audit --tag` and `library --apply --install-to-calibre` (run phase3 transitively), and `--help-json` (a custom argparse Action like --help-repairs, never colored) dumps the per-verb exit contract and the door list; since v0.48.1 the per-verb exit contracts tell the code's truth (repair: 0 written incl. partial / 1 trouble, never 2; audit: 0/1/2 plus 3 for findings+write-failure; library and the run slices: the unified 0/2/1). `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, `max_log_mb` rotation cap default 2, `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). Since the v0.46.0 follow-ups: `tests/test_flags_wiring.py` reflectively pins the RepairFlags inventory to the argparse dests and `_flags_from_args` mapping (a flag added without a field, a field without a flag, or a remapped line fails there), the all-off defaults, and the version gate's caller-immutability contract (test_epub's `TestVersionGateKeepsFlagsIntact`); `tests/test_comment_hyphens.py` carries the RSC-016 fix; `tests/test_flags_real_core.py` drives every repair flag from argv through the unmocked core (--no-validate; the gate itself stays pinned by the mocked-oracle tests and runs for real wherever epubcheck exists). All three ride CI's core-compat 3.12/3.13 leg; the hand-listed module list there must gain an entry for every new stack-free test module.
 

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.48.1
+Version: 0.48.2
 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
@@ -206,7 +206,9 @@ The sections below take each in turn.
 Help is two-level: `bindery repair --help` (or `library --help`) lists the
 shared repair flags grouped with one-line descriptions, and
 `bindery repair --help-repairs` prints the full reference carrying every
-flag's long rationale. On a terminal both are ANSI-colored with the same
+flag's long rationale, and `bindery --help-json` dumps the complete
+surface (every subcommand and flag, the repair reference, the per-verb
+exit contract, the Calibre gates) as machine-readable JSON. On a terminal both are ANSI-colored with the same
 theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
 `FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
 them.
@@ -236,7 +238,11 @@ bindery audit monolithic ~/docs/Calibre\ Library
 # Spot-check completeness: prose coverage, first/middle/last excerpts, trailing ToC
 bindery audit completeness ~/docs/Calibre\ Library
 
-# Run all audits and generate a comprehensive CSV
+# Cover-art quality and ToC-drift audits (advisory; never move the exit code)
+bindery audit cover ~/docs/Calibre\ Library
+bindery audit tocdrift ~/docs/Calibre\ Library
+
+# Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
@@ -265,7 +271,7 @@ With `--id`, `--json` accepts exactly one book id (each single-book run writes t
 
 **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)
+### Tagging flagged books (opt-in; the write is refused while Calibre runs)
 
 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
@@ -276,12 +282,14 @@ cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
 ```
 
 The audit itself stays read-only; only the final tagging pass writes, it skips books that already
-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
+carry the tag, and THIN emptytext advisories are never tagged. The write is REFUSED with exit 1
+while Calibre is running (a fail-closed pgrep guard: close Calibre and re-run). 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.
 
 
+## Repairing a book
+
 Repair one book to a new file (gated; writes only if it is an improvement):
 
 ```sh
@@ -297,6 +305,8 @@ 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.
 
+## Sweeping a library
+
 Scan a Calibre library and see what would be fixed, writing nothing:
 
 ```sh
@@ -328,7 +338,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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 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).
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean OR written (a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`) — it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - 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.
 

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/README.md

@@ -179,7 +179,9 @@ The sections below take each in turn.
 Help is two-level: `bindery repair --help` (or `library --help`) lists the
 shared repair flags grouped with one-line descriptions, and
 `bindery repair --help-repairs` prints the full reference carrying every
-flag's long rationale. On a terminal both are ANSI-colored with the same
+flag's long rationale, and `bindery --help-json` dumps the complete
+surface (every subcommand and flag, the repair reference, the per-verb
+exit contract, the Calibre gates) as machine-readable JSON. On a terminal both are ANSI-colored with the same
 theme Python 3.14's argparse uses; piped output stays plain, and `NO_COLOR`,
 `FORCE_COLOR`, and `TERM=dumb` are honored exactly as `python --help` honors
 them.
@@ -209,7 +211,11 @@ bindery audit monolithic ~/docs/Calibre\ Library
 # Spot-check completeness: prose coverage, first/middle/last excerpts, trailing ToC
 bindery audit completeness ~/docs/Calibre\ Library
 
-# Run all audits and generate a comprehensive CSV
+# Cover-art quality and ToC-drift audits (advisory; never move the exit code)
+bindery audit cover ~/docs/Calibre\ Library
+bindery audit tocdrift ~/docs/Calibre\ Library
+
+# Run all audits and report to the console (--json FILE for machine output)
 cd ~/docs/Calibre\ Library && bindery audit all
 ```
 
@@ -238,7 +244,7 @@ With `--id`, `--json` accepts exactly one book id (each single-book run writes t
 
 **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)
+### Tagging flagged books (opt-in; the write is refused while Calibre runs)
 
 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
@@ -249,12 +255,14 @@ cd ~/docs/Calibre\ Library && bindery audit content --tag "Audit Flagged"
 ```
 
 The audit itself stays read-only; only the final tagging pass writes, it skips books that already
-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
+carry the tag, and THIN emptytext advisories are never tagged. The write is REFUSED with exit 1
+while Calibre is running (a fail-closed pgrep guard: close Calibre and re-run). 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.
 
 
+## Repairing a book
+
 Repair one book to a new file (gated; writes only if it is an improvement):
 
 ```sh
@@ -270,6 +278,8 @@ 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.
 
+## Sweeping a library
+
 Scan a Calibre library and see what would be fixed, writing nothing:
 
 ```sh
@@ -301,7 +311,7 @@ bindery library ~/docs/Calibre\ Library --only all --apply --all --install-to-ca
 - `--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 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).
+- Exit codes, per verb (for scripts and cron; `--help-json`'s `exit_contract` carries this machine-side): `repair` exits 0 when clean OR written (a PARTIAL repair writes its best output and exits 0; the `--json` record's status says so) and 1 on trouble (gate-rejected, epubcheck failure, unreadable input) or invocation problems (bad args, an existing output without `--force`) — it never exits 2. `library`, `run phase1`, and `run phase3` use the unified contract: 0 clean, 2 when any book was flagged, rejected, unreadable, errored, or partial, 1 for invocation problems. `audit` runs the inverse contract: 0 clean, 1 when any book was flagged (a flag is the audit's trouble), 2 for its own usage errors, 3 when findings coexist with a failed `--json`/`--tag` write. `audit --tag` and `library --apply --install-to-calibre` are lock-class doors: they are REFUSED with exit 1 while Calibre is running. Argparse-level misuse exits 2 everywhere before any validation runs.
 - 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.
 

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/patchnotes.md

@@ -1,5 +1,37 @@
 # bindery-cli Patch Notes
 
+## v0.48.2 (2026-10-06)
+
+### The 12-agent docs audit: README/spec/CLAUDE tell the v0.48 truth
+
+v0.48.0/v0.48.1 truthed the help and `--help-json` but touched only
+cli.py; the four-lens documentation audit converged on that lag. This
+propagates it (docs and two docstrings only, no behavior changes):
+
+- **README's exit-contract bullet taught repair's dead contract**
+  (trouble=2, usage=1) and omitted partial-writes-at-0, audit's exit 3,
+  and the lock-class refusals: it is per-verb now, mirroring
+  `--help-json`'s exit_contract block.
+- **The enforced closed-Calibre gate is stated where trust is earned**:
+  README's tagging section (advice became enforcement) and the
+  install-to-calibre story name the three doors and exit 1; spec's
+  Library replacement, Native installation, and audit sections name
+  their refusals; CLAUDE.md carries the v0.48 pair
+  (`_require_closed_calibre`, `--help-json`) plus the per-verb exit
+  truth.
+- spec's audit exit vocabulary gains the exit-3 class and the repair
+  carve-out is named where the inverse shape is attributed; the
+  partial-repair rule gets repair's writes-the-output exception;
+  spec's plugin config list gains `max_log_mb`.
+- README: Repairing a book / Sweeping a library section headers (the
+  usage docs were buried headerless inside the tagging subsection),
+  cover/tocdrift audit examples, `--help-json` in the help paragraph.
+- Two stale code docstrings the audit flagged: `__init__` (four lossy
+  strips, eight analyzers) and validate.py's `no_worse` (stub strips
+  and the rename half included).
+- One pin added (640 total): the newest patchnotes heading must carry
+VERSION.
+
 ## v0.48.1 (2026-10-06)
 
 ### The 12-agent audit: the exit contracts tell the truth
@@ -34,7 +66,7 @@ silences:
 - One code fix: the no-backup lossy warning now covers
   --strip-stub-docs (it warned for its three siblings only).
 
-15 pins updated/added (639 total).
+3 help pins updated to the new truths (639 total, unchanged).
 
 ## v0.48.0 (2026-10-06)
 

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.48.1"
+version = "0.48.2"
 description = "Audit EPUB body text and repair broken EPUBs with deterministic, epubcheck-gated fixes; atomic in-place replacement in a Calibre library."
 readme = "README.md"
 classifiers = [

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/spec.md

@@ -433,32 +433,7 @@ book can never be auto-applied through the lossy path.
 
 For a Calibre library (`Author/Title (id)/Title - Author.epub`):
 
-- Work is done on a temporary copy; the original is read-only until the gate accepts.
-- Replacement is **atomic**: the repaired bytes are written to a temp file in the same
-  directory, fsynced, then `os.replace()`d over the original. The filename and path
-  Calibre expects never change; no partial file is ever visible.
-- The original file mode is preserved. Only the `.epub` is touched; `metadata.opf`,
-  `cover.jpg`, and `metadata.db` are left for Calibre's Quality Check sync.
-- Writing requires `--apply` (default is a dry run). A backup is taken first when
-  `--backup DIR` or `--backup-inplace` is given.
-- A book that cannot be read at all (not a zip, truncated, encrypted entries) is
-  reported and counted as `unreadable`; it never aborts the rest of the sweep.
-- The `library` exit code is 0 for a clean sweep, 1 for a usage error, and 2 when any
-  book was rejected, unreadable, or failed epubcheck, so scripts can detect trouble.
-  Argparse-level misuse (unknown flag, malformed argument) exits 2 before the tool's
-  own validation runs; the tool's own usage validations exit 1. A `partial` book
-  (improved but still fatal) is reported for manual follow-up and counts as trouble:
-  `library`, `run phase1`, and `run phase3` all exit 2 on it (unified 2026-09-10).
-  The `audit` verb is the deliberate exception, its own contract in the inverse
-  shape: 0 clean, 1 when any book was flagged (a flag is the audit's trouble, so it
-  takes the trouble slot), 2 for its own usage errors (a path that is not a
-  directory, a directory with no EPUBs, an unknown book id) and for tagging-setup
-  failure.
-- With `--sweep`, `--workers N` runs the candidate-selection epubcheck pass through N
-  concurrent workers (default 1: serial, unchanged). Books are checked in windows of N
-  consumed in input order, so the candidate set and the before-measurements are identical
-  to the serial sweep; the repair phase is never parallel (the shared workdir and the
-  atomic-replacement contract live there).
+`--apply` is a filesystem write door and the install door is a metadata.db write door: `--apply --install-to-calibre` is REFUSED with exit 1 while Calibre is running (a fail-closed pgrep guard). `--backup-keep N` (minimum 2) caps the ring of same-named per-book backups.
 
 ### Native format installation (`--install-to-calibre`)
 Optionally, bindery-cli installs the repaired EPUB as the book's format through cquarry's write module (`WritableCalibreDB`): the file is placed atomically (an in-place replace over the catalogued file when one exists, same path and `data.name`; a fresh placement under the repaired file's stem otherwise) and the `data` row follows through `set_format` (cquarry 1.17's sanctioned remove+add in one transaction), keeping the size truthful and queuing the book in `metadata_dirtied` so Calibre regenerates its sidecar .opf. The external `calibredb` CLI is no longer used (the v0.23.1 `--replace` crash class is gone with it). It automatically falls back to atomic filesystem replacement if a valid Calibre ID cannot be extracted, and a database failure degrades to the in-place save with a warning rather than losing the repair.
@@ -472,6 +447,8 @@ wrote the stray's size over the catalogued entry, the 2026-09-08 stray-size inci
 and a stale `(N)` directory whose book no longer exists saves in place instead of
 crashing the sweep.
 
+This door is lock-class: `--install-to-calibre` is REFUSED with exit 1 while Calibre is running (a fail-closed pgrep guard; close Calibre and re-run).
+
 ## Audit subcommand (read-only)
 
 `bindery audit {content,pagenumbers,emptytext,ocr,monolithic,completeness,cover,tocdrift,all} [PATH] [--max-doc-chars N]
@@ -518,7 +495,7 @@ storage-layout logic is not duplicated here. The scan itself still writes nothin
 separate trigger-safe write module (it registers Calibre's `title_sort`/`uuid4` SQL functions,
 bumps `books.last_modified`, and cleans link tables before tag deletion). THIN emptytext
 advisories stay untagged; already-tagged books are skipped; a missing file is a scan error, not a
-silent skip.
+silent skip. The tag write is lock-class: REFUSED with exit 1 while Calibre is running.
 
 `--json FILE` (v0.29.0) writes the same verdicts machine-readably, in the `library --json`
 shape: one record per file with a `status` (`clean`, `problem`, or `error`) and per-analyzer
@@ -630,6 +607,7 @@ Behavior contract:
   the user's epubcheck binary under the `no_worse` bar and refused on a
   regression; an unanswered measurement never refuses. The mode is off by
   default (the latency ruling stands; the default pass is safe ungated).
+- **`max_log_mb`** (default 2): the plugin log's size cap in megabytes, one `.old` generation kept on rotation; `0` disables logging.
 
 ## Out of scope (non-goals)
 

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/src/bindery/__init__.py

@@ -1,17 +1,17 @@
 """bindery-cli: deterministic, epubcheck-gated EPUB repair and content auditing.
 
 The repair side: an always-on core of five well-formedness fixes plus the NCX
-pipeline and the mimetype fix, with the structural repairs, the three lossy
-strips (page numbers, broken tags, watermarks), and the safe opt-ins behind
-explicit flags. Around it: the read-only `audit` verb (six body-text
-analyzers), the `library` sweep with atomic in-place replacement in a Calibre
+pipeline and the mimetype fix, with the structural repairs, the four lossy
+strips (page numbers, broken tags, watermarks, stub documents), and the safe opt-ins behind
+explicit flags. Around it: the read-only `audit` verb (eight body-text and
+structural analyzers), the `library` sweep with atomic in-place replacement in a Calibre
 library, the `run phase1`/`phase3` acquisition slices, and the Bindery Repair
 Calibre plugin built from this core.
 
 Single source of truth for the version. pyproject.toml must match VERSION below.
 """
 
-VERSION = "0.48.1"
+VERSION = "0.48.2"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/src/bindery/validate.py

@@ -2,7 +2,8 @@
 
 epubcheck is the external oracle. The `gate` demands measured improvement
 (fewer fatals, or fewer errors on a clean book) and `no_worse` accepts the
-lossy strips and cover repairs when nothing regressed. There is no degrade
+lossy strips (including stub-document strips), the cover wiring repairs, and
+the space-entry renames when nothing regressed. There is no degrade
 path: if epubcheck is not installed, callers refuse (exit 1, "epubcheck not
 found") unless the user explicitly passes --no-validate, which skips the gate
 and trusts the RepairReport alone.

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/tests/test_version.py

@@ -111,3 +111,14 @@ class TestSyntaxFloor(unittest.TestCase):
         # the tree has dozens of modules; a broken path glob must not
         # let the guard pass vacuously
         self.assertGreaterEqual(checked, 20)
+
+    def test_patchnotes_newest_heading_matches(self):
+        # the docs-audit lesson: the release log's newest heading is a
+        # version carrier like any other
+        patchnotes = (
+            Path(__file__).resolve().parent.parent / "patchnotes.md"
+        ).read_text()
+        heading = next(
+            line.strip() for line in patchnotes.splitlines() if line.startswith("## v")
+        )
+        self.assertIn(CODE_VERSION, heading)

{bindery_cli-0.48.1 → bindery_cli-0.48.2}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "bindery-cli"
-version = "0.48.1"
+version = "0.48.2"
 source = { editable = "." }
 dependencies = [
     { name = "cquarry", marker = "python_full_version >= '3.14'" },