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

{bindery_cli-0.48.0 → 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.0 → bindery_cli-0.48.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: bindery-cli
-Version: 0.48.0
+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.0 → 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.0 → bindery_cli-0.48.2}/patchnotes.md

@@ -1,5 +1,73 @@
 # 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
+
+Three waves of four lenses audited this help surface. The flag
+inventory verified perfect (30/30 repair flags, zero misses, zero
+fabrications); the defects were the exit contracts and the safety
+silences:
+
+- **repair --help stated an exit contract the verb has never honored**
+  (trouble returns 1, not 2; a PARTIAL repair writes its output and
+  returns 0). The page and --help-json now tell the code's truth, per
+  verb: repair 0/written + 1, audit's deliberate inverse contract
+  (0 clean; 1 findings; 2 usage/environment; 3 findings plus a failed
+  report write), library and the run slices on the unified 0/2/1.
+  calibre_gates names the third metadata.db door (run phase3, guarded
+  transitively), and the contract admits the missing-stack exit-2 and
+  the exit-3 class.
+- **The library page states the no-backup default**: --apply without
+  --backup/--backup-inplace replaces in place and keeps no copy of the
+  original. --no-validate says the write still happens (status
+  unvalidated). --backup names the outside-the-library refusal.
+  --only fatals names its --audit/--sweep precondition.
+- audit and doctor got real descriptions (the eight analyzers, the CWD
+  library resolution, the one-id --json rule; doctor's always-exit-0
+  contract); the --help-repairs preamble names the five always-on
+  fixes, defines the gate metric, enumerates the status vocabulary,
+  and states the no-worse classes; phase1's exit list gains
+  audit-flagged books; repair's positionals, default output name, and
+  never-modifies-the-input are stated; the --json envelopes name all
+  keys including books; the root help points at doctor/README/spec.
+- One code fix: the no-backup lossy warning now covers
+  --strip-stub-docs (it warned for its three siblings only).
+
+3 help pins updated to the new truths (639 total, unchanged).
+
 ## v0.48.0 (2026-10-06)
 
 ### The closed-Calibre guard, stated contracts, and --help-json

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bindery-cli"
-version = "0.48.0"
+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.0 → 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.0 → 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.0"
+VERSION = "0.48.2"
 __version__ = VERSION
 
 from .epub import RepairReport, repair_epub  # noqa: E402

{bindery_cli-0.48.0 → bindery_cli-0.48.2}/src/bindery/cli.py

@@ -420,17 +420,33 @@ class _HelpJsonAction(argparse.Action):
             "tool": "bindery",
             "version": __version__,
             "exit_contract": {
-                "0": "clean",
-                "1": "invocation problem (bad args; repair: existing output "
-                "without --force); lock-class refusals (Calibre open at a "
-                "metadata.db door)",
-                "2": "trouble found (rejected/error/unreadable/partial "
-                "books; unscoped phase3 sweep); argparse usage errors",
+                "0": "clean (repair: also written, including partial)",
+                "1": "library/run slices: trouble found; repair: trouble "
+                "(refused/failed/unreadable) or invocation problem; audit: "
+                "FINDINGS (the inverse contract, per spec.md); "
+                "lock-class refusals (Calibre open at a metadata.db door)",
+                "2": "library/run slices: trouble found (rejected/error/"
+                "unreadable/partial books; unscoped phase3 sweep); audit: "
+                "usage/environment errors; argparse usage errors; missing "
+                "vir_tui/cquarry on Python < 3.14",
+                "3": "audit: findings PLUS a failed --json/--tag write",
                 "130": "interrupted",
+                "per_verb": {
+                    "repair": "0 clean/written (partial writes, exit 0); "
+                    "1 trouble or invocation problem; never 2",
+                    "audit": "0 clean; 1 findings; 2 usage/environment; "
+                    "3 findings + failed report write",
+                    "library": "0 clean; 2 trouble (rejected/error/"
+                    "unreadable/partial); 1 invocation problem",
+                    "run phase1": "0 clean; 2 trouble (audit-flagged, "
+                    "rejected, partial, error, unreadable); 1 invocation",
+                },
             },
             "calibre_gates": [
                 "audit --tag",
                 "library --apply --install-to-calibre",
+                "run phase3 (transitively: it wraps library --apply "
+                "--install-to-calibre)",
             ],
             "subcommands": [],
             "repair_reference": [
@@ -632,7 +648,12 @@ def run_library(args) -> int:
     if (
         args.apply
         and not wants_backup
-        and (args.strip_pagination or args.strip_broken_tags or args.strip_watermarks)
+        and (
+            args.strip_pagination
+            or args.strip_broken_tags
+            or args.strip_watermarks
+            or args.strip_stub_docs
+        )
     ):
         print(
             "WARNING: the --strip-* modes are lossy; strongly consider --backup DIR "
@@ -1841,12 +1862,21 @@ def _repair_flag_reference(color: bool | None = None) -> str:
         + " repair-flag reference (shared by `bindery repair` and "
         "`bindery library`)",
         "",
-        "The always-on core pass is exactly five well-formedness fixes, the NCX",
-        "pipeline, and the mimetype fix. Everything below is opt-in, and every",
-        "repair is epubcheck-gated: applied only when the measured result improved",
-        "(lossy strips: only when it did not get worse). Library mode is dry-run",
-        "by default; `--all` enables every flag below at once. The README and",
-        "spec.md carry the full rationale for each repair.",
+        "The always-on core pass is exactly five well-formedness fixes",
+        "(strip prolog junk, drop duplicate xmlns, escape bare ampersands,",
+        "fix named entities, self-close void tags), the NCX pipeline, and",
+        "the mimetype fix. Everything below is opt-in, and every repair is",
+        "epubcheck-gated: applied only when the measured result improved",
+        "(strictly fewer findings than before); the lossy strips, the",
+        "cover wiring repairs, and the space-entry renames are held to the",
+        "weaker no-worse bar (not more findings). Library mode is dry-run",
+        "by default; `--all` enables every flag below at once. Statuses a",
+        "record can carry: accept (gate-applied), partial (written but",
+        "still failing epubcheck), reject (the gate refused), error,",
+        "unreadable, nochange (nothing to do), equal (already as good as",
+        "the result), unvalidated (applied under --no-validate, never",
+        "gate-checked). The README and spec.md carry the full rationale",
+        "for each repair.",
     ]
     for title, rows in _REPAIR_FLAG_TABLE.items():
         lines.append("")
@@ -1943,12 +1973,15 @@ def _add_repair_flags(p: argparse.ArgumentParser) -> None:
     g.add_argument(
         "--all",
         action="store_true",
-        help="enable every opt-in fix flag (safe, structural, and lossy)",
+        help="enable every opt-in fix flag (safe, structural, and lossy); "
+        "this IS the lossy consent here (run phase1's separate "
+        "--apply-lossy door is the phase1 equivalent)",
     )
     g.add_argument(
         "--no-validate",
         action="store_true",
-        help="skip the epubcheck gate",
+        help="skip the epubcheck gate: the repair still writes/appends "
+        "with status unvalidated (no gate check runs)",
     )
     p.add_argument(
         "--help-repairs",
@@ -2051,9 +2084,12 @@ def build_parser() -> argparse.ArgumentParser:
         "core pass: the five well-formedness fixes, the NCX pipeline, and the "
         "mimetype fix run always; every other repair is opt-in (grouped "
         "below) and applied only when epubcheck confirms the result improved. "
-        "Never prompts. Exit codes: 0 clean, 2 trouble found (repairs refused "
-        "or failed; --json carries the records), 1 invocation problem (bad "
-        "args, or an existing output without --force).",
+        "Never prompts. Exit codes: 0 clean or written (a PARTIAL repair "
+        "writes its best output and exits 0; the --json record's status "
+        "says so), 1 trouble (repair refused by the gate, epubcheck "
+        "failure, or unreadable input) or invocation problem (bad args, "
+        "or an existing output without --force). This verb does not use "
+        "the tool-wide trouble=2 contract; library and the run slices do.",
         epilog="examples:\n"
         "  bindery repair book.epub out.epub\n"
         "  bindery repair book.epub out.epub --all\n"
@@ -2084,12 +2120,25 @@ def build_parser() -> argparse.ArgumentParser:
         "doctor",
         help="check the environment: Python stack tier, epubcheck, Java, "
         "html5lib, and Calibre-library discovery",
+        description="Check the environment and exit 0 ALWAYS: the output "
+        "is the diagnosis, never a failure (run this first). Checks: the "
+        "Python stack tier, epubcheck, Java, html5lib, and Calibre-library "
+        "discovery.",
     )
     doc.set_defaults(func=run_doctor)
 
     audit = sub.add_parser(
         "audit",
         help="audit EPUB body text to detect non-schema content flaws (OCR damage, hardcoded page numbers, empty books, non-English text)",
+        description="Read-only content audit (eight analyzers: monolithic "
+        "scans, completeness, cover wiring, toc drift, and the body-text "
+        "battery over OCR damage, hardcoded page numbers, empty/thin "
+        "books, and non-English text). Library mode resolves the Calibre "
+        "library from the CURRENT DIRECTORY's metadata.db, or pass a "
+        "directory, or --id for specific books (--id plus --json takes "
+        "exactly one id). Exit codes are the audit inverse: 0 clean, "
+        "1 FINDINGS (flagged books), 2 usage or environment errors, "
+        "3 findings plus a failed --json/--tag write. Never prompts.",
     )
     audit.add_argument(
         "mode",
@@ -2141,7 +2190,7 @@ def build_parser() -> argparse.ArgumentParser:
         "--id",
         metavar="BOOK_IDS",
         default=None,
-        help="audit library book(s) by Calibre id — one id or a comma-separated "
+        help="audit library book(s) by Calibre id: one id or a comma-separated "
         "list (fetched via cquarry's single-entity get_book; cannot be "
         "combined with a directory)",
     )
@@ -2163,10 +2212,12 @@ def build_parser() -> argparse.ArgumentParser:
         "repair them in place. Dry run by default; --apply atomically "
         "replaces accepted books. Shares the repair-flag set with `bindery "
         "repair` (--all enables every opt-in). Never prompts: --apply is "
-        "the only confirmation. Exit codes: 0 all clean, 2 any "
-        "flagged/rejected/error/partial book, 1 invocation problem. "
-        "--apply --install-to-calibre writes metadata.db and demands a "
-        "closed Calibre (refused, exit 1, while it runs).",
+        "the only confirmation. --apply WITHOUT --backup or --backup-inplace "
+        "replaces in place and keeps NO copy of the original. Exit codes: "
+        "0 all clean, 2 any flagged/rejected/error/unreadable/partial book, "
+        "1 invocation problem. --apply --install-to-calibre writes "
+        "metadata.db and demands a closed Calibre (refused, exit 1, while "
+        "it runs).",
         epilog="examples:\n"
         "  bindery library ~/docs/Calibre\\ Library --sweep\n"
         "  bindery library ~/docs/Calibre\\ Library --id 1234 --apply "
@@ -2185,7 +2236,8 @@ def build_parser() -> argparse.ArgumentParser:
         choices=("fatals", "ncx", "all"),
         default="all",
         help="restrict to books with fatals, the NCX-001 mismatch "
-        "(toc.ncx dtb:uid != the OPF unique-identifier), or all (default)",
+        "(toc.ncx dtb:uid != the OPF unique-identifier), or all (default); "
+        "fatals requires --audit CSV or --sweep",
     )
     rc.add_argument(
         "--limit", type=int, help="process at most N candidates (for sampling)"
@@ -2241,7 +2293,7 @@ def build_parser() -> argparse.ArgumentParser:
     out.add_argument(
         "--json",
         metavar="FILE",
-        help="write a machine-readable JSON report of the run to FILE Top-level envelope keys: mode (apply|dry-run), root, only, validate, candidates, summary",
+        help="write a machine-readable JSON report of the run to FILE. Top-level envelope keys: mode (apply|dry-run), root, only, validate, candidates, summary, books (one record per candidate)",
     )
     out.add_argument(
         "--manual-list",

{bindery_cli-0.48.0 → 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.0 → bindery_cli-0.48.2}/tests/test_help.py

@@ -104,14 +104,18 @@ class TestHelpTruth(unittest.TestCase):
     def test_repair_page_states_the_contract(self):
         text = self._sub(self._parser(), "repair").description
         self.assertIn("Never prompts", text)
-        self.assertIn("0 clean, 2 trouble", text)
+        self.assertIn("PARTIAL repair writes its best output and exits 0", text)
+        self.assertIn("does not use", text)
         self.assertIn("without --force", text)
 
     def test_library_page_states_gate_and_codes(self):
         text = self._sub(self._parser(), "library").description
         self.assertIn("Never prompts", text)
         self.assertIn("closed Calibre", text)
-        self.assertIn("0 all clean, 2 any", text)
+        self.assertIn(
+            "0 all clean, 2 any flagged/rejected/error/unreadable/partial", text
+        )
+        self.assertIn("keeps NO copy of the original", text)
 
     def test_install_to_calibre_names_the_gate(self):
         parser = self._parser()
@@ -165,9 +169,15 @@ class TestHelpJson(unittest.TestCase):
             list(cli._REPAIR_FLAG_TABLE),
         )
         self.assertEqual(
-            data["calibre_gates"],
+            data["calibre_gates"][0:2],
             ["audit --tag", "library --apply --install-to-calibre"],
         )
+        # the third door is phase3, guarded transitively through library
+        self.assertIn("run phase3", data["calibre_gates"][2])
+        # the contract now carries the per-verb truth
+        self.assertEqual(data["exit_contract"]["per_verb"]["repair"][-7:], "never 2")
+        self.assertIn("1 findings", data["exit_contract"]["per_verb"]["audit"])
+        self.assertIn("3", data["exit_contract"])
         self.assertEqual(payload_text, self._dump())
 
     def _dump(self):

{bindery_cli-0.48.0 → 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.0 → bindery_cli-0.48.2}/uv.lock

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