# Source beta — 2026-09-24, revision 10

This is a local-first Linux application source release with a static HF
landing page. It is not a model release or an online OCR service.

## Revision 10: resource admission and Quick mode

- GPU admission rechecks free VRAM before OCR and after OCR exits in sequential local review. Two consecutive samples must meet the existing budget, with a bounded 30-second wait. Query errors stop admission; memory exhaustion uses the existing fallback path. This cannot reserve VRAM against unrelated processes, and external API server allocations are not controlled.
- Fast review shows pending differences alongside source images, including deferred and failed reviews. Byte-identical valid pages need no decision and retain original OCR; they are not labeled human-approved. Approve/keep-original buttons advance the pending queue. Native keyboard navigation uses Tab and Enter/Space; there are no global Enter/Escape handlers.
- Optional bulk adoption accepts valid undecided model candidates without manual verification, preserving original OCR and prior page decisions. Decision records identify `bulk_model_adoption` and `human_verified: false`. Failed or stale reviews are excluded. Deferred proposals excluded from a candidate remain excluded. A downstream LLM is not guaranteed to fix missing text, numbers or negations.
- This package has not been uploaded by the builder. Whole-book throughput and low-VRAM hardware stress testing have not been repeated.

- **Quick mode** groups optional model-candidate adoption with complete-context ZIP preparation. The ZIP includes every selected screen, original OCR, candidates (including invalid/unapproved ones, labeled accordingly), available source images, review records and missing/failure markers. Process logs and endpoint configuration are excluded. Nothing is uploaded automatically. ZIP support and context limits depend on the receiving model interface.
- Dual mode also checks Gemma GPU memory immediately before server startup. A sufficient final sample gets one additional stability sample instead of a contradictory out-of-memory error.
- Bulk-adoption provenance is retained in reviewed MD, report.json and reading-format introductions. Partial bulk-write failures still regenerate exports. Decided includes bulk-adopted unchanged candidates with deferred proposals; deferred proposals remain in the handoff.
- Dedicated Ollama logs now live under private backups/runtime-logs.

## Revision 9: community ports note

- README ends with a short "Community ports welcome" section: forks and
  ports to other platforms are welcome under AGPL-3.0-only, third-party
  terms still apply, and no support or maintenance for other platforms is
  promised. Documentation only; no license change.

## Revision 8: image layout

- Review feedback: the three-column thumbnails were too small to read. The
  review and Markdown images are now shown full width, the start screen
  smaller, with a "click to enlarge" hint; the review caption is a one-line
  summary with the specific deferred-suggestion example beneath it.
- Documentation only; no other file changed.

## Revision 7: screenshots and README order

- Three interface images (start screen, page review, exported Markdown used
  with a local model) now open the README and the landing page, under
  `docs/images/`. They show the interface on a public-domain 1890 book scan
  and a short synthetic text; they are not an accuracy claim.
- README sections reordered so the workflow and output formats come before
  the license and dependency terms. The terms themselves are unchanged.
- `scripts/verify_public.py` still rejects binary payloads everywhere except
  `docs/images/*.png|*.jpg`, which must be well-formed, at most 1 MiB, and
  free of PNG text/EXIF chunks and JPEG EXIF/XMP/comment segments, so images
  cannot carry hidden text. Public tests cover the rejected cases.
- No application code, model default, supported-model scope or license change.

## Revision 6: wording only

- The short description, README opening line and landing-page lead now name
  Kindle books first, since capturing your own Kindle books is the workflow
  this application adds beyond ordinary PDF/image OCR. No new compatibility
  claim: Kindle layouts are still not universally validated.
- No code, model default, supported-model scope or license change.

## Revision 5: updated model-comparison evidence

- Public benchmark and release-note pages now include the larger same-day
  100-case measurement of the current review pipeline. It does not establish
  a general quality advantage for 26B; 12B+C1 remains the default.
- Documentation only: application behavior, model defaults and supported-model
  scope are unchanged. Historical measurements remain labeled separately.

## Revision 4: process cleanup and connector response handling

- Dedicated OCR and local model processes now run under an owned-process
  supervisor. Normal exit, termination and loss of the caller's private pipe
  trigger cleanup of the owned process group. This also covers a caller killed
  with SIGKILL; it does not stop unrelated servers or external API endpoints.
- Four real subprocess tests cover normal exit, termination, a killed caller
  and failed executable startup. Stubborn descendants are cleaned up while an
  unrelated process remains alive. A real local 12B loading test on the development
  GPU returned from 7,929 MiB to its 7 MiB baseline after both a deliberate
  exception and SIGKILL of the caller. This is one host, not a universal driver
  or crash-recovery guarantee; killing the supervisor itself is outside this test.
- The optional connector exposes a server-dependent reasoning-effort setting.
  Its default omits that parameter. A probe that exhausts the output budget
  reports that explicitly instead of treating it as a generic JSON failure.
- A single Markdown fence around an otherwise valid JSON value is accepted;
  JSON is never extracted from surrounding commentary. Existing schema and
  source-preservation checks still apply. Probe characters are rendered directly
  at a readable size, instead of enlarging a tiny font bitmap.
- Twenty-two public tests pass. These changes do not add any other model to
  a supported/guaranteed-model list.

## Revision 3: optional vision API connector

- Gemma 4 remains the recommended default; other models are an opt-in option.
  **A vision-capable LLM is required** for checking source images. An
  OpenAI-compatible API alone does not guarantee image/JSON support,
  correction quality or successful completion. This is not a universal model
  support claim; the historical Gemma comparison does not apply to other models.
- Added non-streaming Chat Completions with configurable base URL, model,
  API key, JSON response mode and output token parameter. A synthetic image
  test and explicit destination consent gate new jobs. No book is sent by
  the connection test. No cloud fallback is enabled automatically.
- Default processing remains local. When this option is enabled, images and
  OCR text go to the selected endpoint, which may be remote and charge fees.
  Private plaintext credential profiles are excluded from job exports and
  release payloads. See [CONNECTORS.md](CONNECTORS.md).
- PDF, images and both Kindle capture routes share the provider setting.
  External review runs after local OCR; the app does not manage that server's
  GPU or VRAM. Existing C1 validation and original-preservation logic remain.
- HTTP contract tests cover successful C1 review through the real worker,
  partial results on provider failure, JSON modes, consent, vision-test failure,
  redirects, error redaction and capture option propagation. They use a local
  synthetic server, not a claim of compatibility with every provider.

## Revision 3 validation scope

- Seventeen public tests passed in the existing isolated Python environment.
  Added UI checks verify that changing endpoint settings disables starting
  until a new test succeeds; missing profiles fail without another provider.
- Synthetic HTTP tests run the C1 correction and worker export path, including
  a provider-failure case with retained original OCR and partial output.
- No external paid service, real API key, new model download or hosted HF test
  is part of this validation. Contract tests are not a supported-model list.
- The earlier independent-environment dependency check remains applicable;
  the connector uses the already pinned requests and Pillow dependencies.

## Standard model and revised distribution pages

- Standard installation now prepares Gemma 12B automatically using a preinstalled
  Ollama executable. C1 OCR instructions and source-preserving review logic are
  included in the application; no fine-tuned weights are claimed.
- Weights are downloaded to a private local store, not included in the ZIP.
  Setup records the store and digest; GPU workers use that same store.
- 26B is an optional additional setup command and does not change the UI default.
  `--skip-model` permits dependency-only installation; failed model downloads can
  be retried without reinstalling Python dependencies.
- Visitor-facing installation, release notes, benchmark and license links now
  open static HTML. Markdown originals remain available as explicit downloads.
  The owner publishing guide is no longer linked from the landing-page footer.
- README explains its HF metadata. ZIP and folder still contain identical bytes.
- Unexpected binary payloads now fail with an explicit text-only policy error;
  they are not silently omitted from privacy scanning.

## Optional 26B: historical observations, not a guarantee

A newer same-day test of the shipped `c1_ocr_v3` pipeline used 100 bilingual
synthetic cases x three seeds: exact corrections were **165/300 (55.0%) for
12B versus 74/300 (24.7%) for 26B**. Thus the older six-image observations
below do not establish a general quality advantage for 26B. This supports
keeping 12B+C1 as the default. Repeated short synthetic cases are not a
real-book accuracy guarantee; see [BENCHMARKS.md](BENCHMARKS.md) for errors,
timings, limitations and the separately labeled unshipped-prompt follow-up.

The standard remains 12B+C1. For users with more available VRAM, 26B+C1 is
optional. An earlier six-image comparison recorded 52.291 seconds for 12B and
40.022 seconds for 26B across 18 review requests. Exact-match corrections were
51/54 versus 45/54; allowing colon/adjacent-space differences gave 51/54 versus
54/54. Neither arm changed an originally correct field in that test.

These are repeated fields on six synthetic images with an earlier C1 prompt,
not a current c1_ocr_v3 end-to-end speed or quality evaluation. More VRAM use
can force sequential execution, making full jobs slower. See
[BENCHMARKS.md](BENCHMARKS.md) and its numeric data for scope and tradeoffs.

## Packaging changes

- Explicit allowlist builder; source hashes and archive consistency checks.
- No book samples, processing records, profiles, keys, virtual environments,
  model weights, machine logs or private evidence archives.
- Isolated Python installer and pinned direct dependency lists; optional
  YomiToku remains separately installed and explicitly selected.
- Default dedicated Chrome profile moved to captures/chrome-profile;
  old profiles are not moved. Fresh profile login is required.
- Removed legacy capture-process termination. Other tools are not stopped.
- Chrome bridge requires the Enable button or BOOK_OCR_ENABLE_BRIDGE=1.
- Synthetic, redistributable export/UI tests replace private book fixtures.

## Revision 2 validation

- Nine public tests passed in the isolated Python environment prepared for
  revision 1. Added tests cover download invocation, reuse, failed download,
  missing post-download model, invalid configuration and store precedence.
- A real, owned Ollama server successfully reused the existing 12B artifact,
  recorded its digest and stopped. That probe deliberately prohibited downloads
  and did not run inference or alter the main application model settings.
- First-time multi-GB transfer remains untested in this revision. Download and
  failure control flow were tested with mocks; no inference-quality retest is claimed.
- Python dependency installation was executed for revision 1. Revision 2 adds
  markdown2 as a direct dependency; its same pinned version was already in the
  tested environment and constraints. There was no second full dependency install.
- Static documentation omits optional syntax highlighting so clean and development
  environments produce identical HTML.
- HF-hosted rendering remains untested; HTML freshness, relative destinations
  and release-byte integrity are checked locally.

## Revision 1 validation scope

- Built an isolated environment from this source package on the development
  Linux x86-64 host, CPython 3.10.14, with system-site-packages disabled.
- Installer completed, pip check passed, and all listed runtime import probes
  passed, including Marker, Torch, Transformers and Playwright. CUDA was
  detected. No new model download or inference was performed.
- Three public tests passed in that fresh environment: private capture-profile
  placement/URL rejection, bridge opt-in UI behavior, and offline synthetic
  MD/HTML/PDF/EPUB export with unchanged source bytes and valid EPUB XML.
- Existing one-click UI and licensing regression checks passed in the
  development environment. Shell syntax, Python syntax and extension JS
  syntax checks passed. Existing-environment installer refusal was verified.
- Package checker passed a clean fixture and rejected an extra private file,
  altered source, a symlink, and an altered archive. The builder also checks
  payload bytes against the development bridge key without printing it.
- Optional YomiToku dependencies resolved in a pip dry run; its fresh isolated
  installation and inference were not executed in this packaging task.
- Python 3.10 resolved versions are retained in constraints-linux-py310.txt.
  Python 3.11 is allowed by the installer but remains untested here.

## Limitations

Full end-to-end installation, model download and GPU inference on a second
clean physical machine are not established by source packaging. Browser
layouts, driver versions and GPUs vary. Tests with generated pages do not
prove OCR or correction accuracy. No universal multilingual accuracy claim
is made. The scheduler is not proven optimal; 26B is optional.

Version pins and the Python 3.10 constraints are not artifact-hash locks or a complete license SBOM. Exact
weight licenses and intended commercial eligibility need separate review.
Neither HF publication nor legal clearance is performed by the builder.