glyphive 0.1.0__tar.gz

glyphive-0.1.0/.gitignore

@@ -0,0 +1,32 @@
+# Agent config must never be committed (global rule)
+AGENTS.md
+.agents/
+CLAUDE*
+.claude
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+site/
+.venv/
+.pytest_cache/
+.hypothesis/
+.mypy_cache/
+.ruff_cache/
+.coverage*
+htmlcov/
+
+# Local scratch / tool output
+run.log
+tmp/
+
+# OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.traineddata

glyphive-0.1.0/CHANGELOG.md

@@ -0,0 +1,250 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-18
+
+The first public release provides an end-to-end path from a file tree to
+OCR-friendly printable pages and back to a verified tree.
+
+### Changed
+
+- **Compact `#!glyphive` header line**: the display-only summary is now
+  `#!glyphive v<N> <codec>[,<comp>] files=.. bytes=.. pages=..` — a bare `v<N>`
+  token, codec and compression collapsed to one positional `codec[,comp]` token,
+  and `sha256`/`meta` dropped entirely (they live in the protected `H` frames).
+  Fewer characters on page 1 means less to OCR and less display-line overflow.
+  Any line beginning with `#!` is now treated as a comment on the read path, so
+  documents can carry arbitrary `#!` notes. (Pre-release format change; no
+  backward compatibility with the old header grammar.)
+- **`--descan auto` retry now sweeps a `0.6`/`0.8` blur ladder** (was a single
+  `0.6` pass): the widest glyphs (e.g. Courier 12 pt) can need `~0.8` to decode
+  from a raw photo, so the auto-retry covers both. The per-line CRC merge keeps
+  this strictly additive — extra blur passes only ever recover more lines.
+- **Default PDF font is now `dejavu-sans-mono`** (was Courier). DejaVu was one of
+  only two fonts that held up on real photographed scans under `tesseract-glyphive`
+  and passes the byte-for-byte restore gate, so it is preferred for recovery
+  robustness. Trade-offs, accepted deliberately: it renders ~26% fewer usable
+  bytes/page than Courier at 8 pt+ (more pages per document) and embeds ~340 KB per
+  PDF (Courier is a zero-embedding core font). Pass `--font courier` for the denser,
+  zero-embed alternative. The synthetic density comparison and the override rationale
+  are in `benchmarks/results/FONT_CANDIDATES.md`.
+- **Footer-hash mismatches are now advisory, not warnings**: an OCR restore
+  almost always produces a footer-hash mismatch (OCR inserts interior spaces
+  that change the page text hash while the `L`/`P` lines still decode via
+  CRC/RS), so logging it at WARNING cried wolf on every clean restore. These are
+  now collected separately (`meta["_footer_hash_notes"]`) and logged at INFO
+  (shown with `-v`); genuine page-integrity issues (missing/reconstructed pages)
+  stay at WARNING. `glyphive inspect` reports the advisory count. Correctness is
+  unchanged — it never rested on the page footer hash.
+- **Faster decode on clean input**: decode now skips Reed-Solomon entirely on
+  erasure-free blocks (the common case — text transcripts and good scans are
+  mostly clean), since a line whose per-line CRC matched is already trusted and
+  RS has nothing to correct. A partially-damaged stream RS-corrects only the
+  blocks that actually contain a bad/missing line. Correctness is unchanged: the
+  per-line CRC oracle plus the whole-document SHA-256 gate still catch any
+  corruption loudly. (Profiling put RS at ~75% of clean-decode time; the exact
+  speedup is measured in CI, not stated here.)
+- **Codec identifier renamed `g1` -> `base16c-crc16-rs`**: exposes the
+  composable parts (16-char OCR-safe alphabet / CRC-16 / Reed-Solomon) instead
+  of an opaque version tag. `codec/g1.py` -> `codec/base16c.py`; `G1Codec` ->
+  `Base16CCodec`; `--codec` default and `codec.names()` updated. Nothing was
+  published under the old name, so this is an in-place rename with no
+  migration path or dual-format compatibility.
+- **Dense preset documented**: the bundled `ocr-b` font (SIL OFL 1.1, OCR-B by
+  Raisty) at 6pt measures 5,050 usable bytes/page — 23% denser than the
+  Courier 8pt `safe` default — and remains safe on both tested engines
+  (Tesseract and PaddleOCR). Select it with `--font ocr-b --font-size 6`; the
+  shipped default stays Courier 8pt per the project's font-selection design.
+
+### Fixed
+
+- **PDF frames no longer silently shrink to fit**: a machine/data frame
+  (`H`/`L`/`P`/`T`) that overflows the printable width now raises a clear error
+  naming the overflow instead of quietly reducing its font size to fit.
+  Silent shrinking distorted glyphs (hurting OCR) and hid a misconfigured
+  font/size/margin/line-width. The display-only `#!glyphive` human header is
+  exempt and still scales to fit (restore never trusts it).
+- **Overwrite publication now rolls back on partial failure**: restoring onto
+  an existing destination with `--overwrite` moves each existing final file
+  aside into a private backup before replacing it. If any staged move fails
+  partway through (disk full, permission error, etc.), every file already
+  replaced is restored from its backup and any newly created file is removed
+  -- the destination is left exactly as it was, never half-migrated.
+- **Machine header now Reed-Solomon protected**: the real Tesseract 5.4.0
+  end-to-end gate (`create` -> rasterize 300 DPI -> `extract --from-images`
+  -> diff) found that `--compression zstd` deterministically failed restore:
+  a wider header caused Tesseract to misread one `H` frame's two duplicate
+  copies identically, so CRC+duplication alone could not recover it.
+  `layout.py` now adds one Reed-Solomon parity chunk over the header
+  envelope so restore reconstructs a single damaged chunk instead of only
+  detecting it; corruption spanning more than one distinct chunk still fails
+  loud. Both `--compression none` and `--compression zstd` now restore
+  byte-for-byte through the real OCR gate.
+- **Large-document parity overhead**: `parity_ratio` now targets aggregate
+  Reed-Solomon parity across all GF(255) blocks. The default is approximately
+  12% for large streams instead of repeating a capped whole-stream budget per
+  block and inflating parity to roughly 65%.
+
+### Added
+
+- **`create --no-header`**: omit the display-only `#!glyphive` summary line from
+  page 1 for the tightest possible page. Restore needs nothing from it (all
+  authoritative metadata comes from the CRC-protected `H` frames), so a
+  `--no-header` document restores byte-for-byte identically.
+- **Bundled `dejavu-sans-mono` PDF font**: DejaVu Sans Mono 2.37 (permissive
+  DejaVu Fonts License) is now a selectable bundled font
+  (`--font dejavu-sans-mono`), embedded in PDF output. It was one of only two
+  fonts (with Courier) that held up under the `tesseract-glyphive` profile in
+  real scan/restore testing — offered as a strong option; a byte-for-byte
+  restore gate is pending before it is recommended over Courier. Adds ~335 KB
+  to the wheel. (Also fixes a latent bug where a second bundled font would have
+  collided on the hardcoded `"OCR-B"` FPDF family name.)
+- **`glyphive inspect` — recovery-headroom report**: a read-only subcommand
+  that reports how much damage a document can survive without fully decoding or
+  verifying it (so it works on a partially damaged scan a restore would reject,
+  and writes nothing). Shows data/parity page counts (whole-page recovery
+  budget), the realized per-line Reed-Solomon `nsym` (scattered-damage budget),
+  and which pages are present/missing/reconstructable. `--json` for machine
+  output; `--strict` exits non-zero on an already-unrecoverable document. Backed
+  by a new pure `codec.base16c.describe_line_stream` shape oracle.
+- **`--line-width auto|max|<int>` spellings** on `create`: `auto` (default) is
+  the OCR-measured-safe capacity (≤60); `max` fills the largest row that
+  physically fits the font/size/margins (may exceed 60, not OCR-verified, and
+  an error on formats without font metrics); an integer above the safe cap now
+  requires `--force`. The renderer interface gains a public
+  `geometric_payload_capacity` hook (uncapped fit) alongside the safety-capped
+  `payload_capacity`.
+- **De-scan blur for photographed input (`--descan`, auto by default)**:
+  `extract`/`list` apply a Gaussian blur to image and rasterized-PDF input
+  before OCR. The default `--descan auto` does a single sharp pass, then
+  automatically retries once with a light `0.6` blur if that fails to decode
+  image/PDF input — raw phone photos are often too sharp/noisy for the frame
+  CRC/RS and otherwise fail, and the retry costs an extra OCR pass only on
+  failure. `--descan 0` disables the auto-retry; an explicit list
+  (`--descan 0,0.6,1.0`) OCRs each image at every radius and **merges the
+  CRC-valid lines across passes** — different blurs recover different lines and
+  the per-line CRC makes combining them safe, so a document no single blur can
+  fully read may still restore from the union. Automatic OCR-engine selection
+  also prefers the constrained `tesseract-glyphive` profile over plain
+  `tesseract` (measured substantially higher scan-restore success).
+- **Whole-page recovery (`--parity-pages K`)**: `create` can emit K extra
+  document-level Reed-Solomon parity pages over the data pages, so a document
+  survives up to K wholly lost / unscannable / destroyed pages — not just the
+  scattered per-line OCR errors the per-line RS already fixes. Restore
+  reconstructs missing data pages from the parity pages and reports which it
+  rebuilt. Default 0 (off, byte-identical to before). Data pages + K must not
+  exceed 255. Independent of `--parity-ratio`. The header gains a `pgpar`
+  token (omitted when 0) and the protected machine envelope records K and the
+  page block size. Separately, a *missing* page no longer hard-fails up front
+  even with K=0: the codec's document-wide RS is given a chance to recover it
+  from the surviving pages when the per-line parity budget allows.
+- **Progress logging for `create`/`extract`**: both commands now log
+  intermediate stage events (`archived`, `compressed`, `encoded`, `rendered`
+  for `create`; `staged`, `published` for `extract`) instead of only a final
+  one-line summary, sparsely rate-limited so a large tree doesn't flood the
+  log. The underlying `on_progress` callback is also available to library
+  callers of `restore_document_spooled`/`unarchive_spool`.
+- **Isolated QR transport primitives**: the optional `qr` extra provides
+  deterministic, versioned 1000-byte envelopes, level-H Segno PNG generation,
+  and Pillow/ZXing-C++ raw-byte decoding without OpenCV. Extract/list accept
+  explicit `--from-qr` image or directory input; ordinary image OCR behavior is
+  unchanged. Explicit `--format qr` writes six symbols per Letter page;
+  `--format hybrid` writes one symbol plus its transcript slice per page. A
+  plain `.pdf` suffix continues to select the ordinary PDF renderer.
+- **Constrained Tesseract profile** (`tesseract-glyphive`): an opt-in OCR
+  provider using PSM 6, Glyphive's exact machine alphabet, and disabled general
+  language dictionaries. The existing `tesseract` provider remains unchanged.
+- **Bounded archive and compression primitives**: archive records can now be
+  written and parsed as fixed-size chunks, and the built-in none/gzip/zstd
+  methods support binary stream adapters. Existing one-shot APIs remain
+  available while create/restore migrate to disk-backed spools. Create now
+  streams archive, compression, FEC, pagination, and renderer output through
+  temporary spools; `--temp-dir` and `--chunk-size` control spool placement and
+  I/O granularity. Restore stream-decompresses into a size-limited spool,
+  validates the global digest and archive framing, stages files privately, and
+  only then publishes final paths; `--max-output-bytes` caps expansion.
+  Transcript parsing spools normalized frames in one pass, while
+  `base16c-crc16-rs` retains only compact line offsets and processes
+  Reed-Solomon codewords blockwise.
+- **Explicit plugin discovery** (`glyphive.plugins`): trusted installed
+  distributions can provide typed codecs, compression methods, render formats,
+  or OCR providers through four documented entry-point groups. Discovery is
+  opt-in through the library API or global `--plugins` CLI flag, deterministic,
+  cached, and reports broken candidates without changing normal imports.
+- **Standalone zipapp packaging** (`package.py`): build a universal
+  `glyphive.pyz` containing the required runtime dependencies and the core
+  text/none/gzip feature set, or explicitly named platform-specific artifacts
+  with optional integrations. Lightweight OCR Python shims are optional;
+  heavyweight OCR engines and models remain external.
+- **Codec registry** (`glyphive.codec`): typed named lookup with the built-in
+  `base16c-crc16-rs` codec.
+- **Compression registry** (`glyphive.compression`): named `none`, `gzip`, and
+  lazy optional `zstd` methods.
+- **Renderer and OCR registries** (`glyphive.render`,
+  `glyphive.restore.ocr`): text, PDF, Word, and optional OCR providers use
+  explicit registries with lazy backend imports.
+- **Codec `base16c-crc16-rs`**: the measured-safe `ABCDHKLMPRTVXY34` alphabet
+  (16 symbols, 4-bit packing), a full CRC-16 per line, masked five-character
+  indices, and document-wide interleaved Reed-Solomon parity. Scattered OCR
+  errors can self-heal; correctness is judged by CRC and parity rather than
+  speculative character substitution. (Named for its composable parts —
+  16-symbol OCR-safe alphabet / CRC-16 / Reed-Solomon — instead of an opaque
+  `g1` version tag; renamed before the first release, so no migration shim
+  was needed.)
+- **Binary-safe archive stream** (`glyphive.archive`): length-prefixed records
+  for arbitrary bytes, deterministic ordering, root-level
+  `.gitignore`/`.ignore` filtering, empty-directory records, and `none`, `gzip`,
+  or `zstd` whole-stream compression.
+- **Protected layout metadata** (`glyphive.layout`): safe-alphabet `H` header
+  frames and `T` page-footer frames carry authoritative document metadata,
+  page identities, and hashes. Unrestricted human-readable summaries are
+  display aids only.
+- **Text, PDF, and Word renderers** with selectable font family and size. PDF
+  output uses built-in FPDF font families; Word output accepts installed Word
+  font names.
+- **Verified restore pipeline** (`glyphive.restore`): transcript decode,
+  whole-document SHA-256 validation, path-traversal-safe extraction, and an
+  optional multi-provider OCR layer for image input.
+- **Tar-like CLI**: `create` (`c`), `extract` (`x`), and `list` (`t`) commands
+  with codec, compression, metadata, renderer, and OCR selectors. Leading
+  `-c`, `-x`, and `-t` mode flags work without a positional command.
+- **Automatic document input**: `extract` and `list` classify each direct-child
+  input independently by magic bytes, extension, then UTF-8 text, so transcript,
+  image, PDF, and DOCX pages can be mixed in deterministic order. A conversion
+  helper renders PDF pages or diagnostic DOCX transcript pages to PNG with
+  configurable DPI and blur; DOCX restore uses `python-docx`, not an office suite.
+- **Capacity-aware rendering**: PDF/DOCX row budgets follow font size and page
+  margins; `--minimal-margins` uses a compact 12-point profile, and long PDF
+  display headers fit rather than clip. Output format is inferred from `-f`
+  when `--format` is omitted.
+- **Bundled OCR-B PDF font**: `--font ocr-b` embeds a pinned, unmodified
+  SIL-OFL-1.1 font; PDF output also accepts explicit `.ttf`/`.otf` paths.
+- **Documentation and examples**: task-focused create, restore, wire-format,
+  OCR, benchmark, and API pages plus a runnable create/restore example.
+
+### Changed
+
+- Require `pathlib_next>=0.8.1`, including its Python 3.9 import and local path
+  walking fixes.
+- A directory supplied to CLI `-f` expands its direct child files in stable
+  filename order.
+
+### Known limitations
+
+- `create` archives one directory (or `.`) at a time; wrap multiple inputs in a
+  directory.
+- Ignore files are read at the archived-tree root only; nested `.gitignore`
+  files are not applied.
+- A fully lost or unscannable page is detected and reported, not reconstructed.
+- Protected header/footer metadata detects corruption but is not itself
+  Reed-Solomon-corrected.
+- QR-code output is not implemented.
+
+[Unreleased]: https://github.com/jose-pr/glyphive/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/jose-pr/glyphive/releases/tag/v0.1.0

glyphive-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing to Glyphive
+
+Thanks for helping improve Glyphive. The project is alpha: wire-format and CLI
+changes are welcome when they include tests and clear documentation.
+
+## Development setup
+
+```bash
+git clone https://github.com/jose-pr/glyphive.git
+cd glyphive
+python -m venv .venv/dev
+python -m pip install -e ".[all,dev,docs]"
+```
+
+Activate the environment using the command appropriate for your shell, or call
+its Python executable directly.
+
+## Checks
+
+Run the automated suite and strict documentation build before opening a pull
+request:
+
+```bash
+python -m pytest -q
+python -m mkdocs build --strict
+```
+
+Core timing checks are separate from correctness tests:
+
+```bash
+python benchmarks/run.py
+```
+
+Local timings are sanity checks, not publishable performance evidence. Keep
+performance claims tied to comparable CI results. OCR sweeps and other
+compute-heavy experiments should run on an appropriate remote machine and must
+record engine, model, font, size, DPI, platform, and corpus provenance.
+
+## Changes and commits
+
+- Add focused tests for behavior changes.
+- Update the relevant guide and `CHANGELOG.md` for user-visible changes.
+- Do not commit generated `site/`, `dist/`, temporary OCR output, or agent files.
+- Use `type: description` commits, such as `feat:`, `fix:`, `docs:`, `test:`,
+  or `chore:`.
+- Keep unrelated changes in separate commits.
+
+## Pull requests and bug reports
+
+Open a focused pull request describing the behavior, its tests, and any wire or
+density impact. Bug reports should include the Glyphive and Python versions, the
+operating system, the exact command, expected and observed behavior, and a small
+reproducer when possible. Remove private archive contents from transcripts and
+images before attaching them publicly.

glyphive-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose A.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

glyphive-0.1.0/PKG-INFO

@@ -0,0 +1,304 @@
+Metadata-Version: 2.4
+Name: glyphive
+Version: 0.1.0
+Summary: Archive file trees to compact, OCR-friendly printable pages (text/PDF/docx) and restore them from scans.
+Project-URL: Homepage, https://github.com/jose-pr/glyphive/
+Project-URL: Documentation, https://jose-pr.github.io/glyphive/
+Project-URL: Issues, https://github.com/jose-pr/glyphive/issues
+Project-URL: Repository, https://github.com/jose-pr/glyphive
+Author: Jose A.
+License-Expression: MIT
+License-File: LICENSE
+License-File: src/glyphive/assets/fonts/dejavu_sans_mono/LICENSE
+License-File: src/glyphive/assets/fonts/ocr_b/LICENSE.md
+Keywords: archive,backup,ocr,paper-backup,print,reed-solomon
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: duho>=0.2.0
+Requires-Dist: pathlib-next>=0.8.1
+Requires-Dist: pathspec
+Requires-Dist: reedsolo
+Provides-Extra: all
+Requires-Dist: fpdf2; extra == 'all'
+Requires-Dist: pillow; extra == 'all'
+Requires-Dist: pypdfium2; extra == 'all'
+Requires-Dist: pytesseract; extra == 'all'
+Requires-Dist: python-docx; extra == 'all'
+Requires-Dist: segno==1.6.6; extra == 'all'
+Requires-Dist: zstandard; extra == 'all'
+Requires-Dist: zxing-cpp==2.3.0; (python_version < '3.10') and extra == 'all'
+Requires-Dist: zxing-cpp==3.1.0; (python_version >= '3.10') and extra == 'all'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: hatchling; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == 'docs'
+Requires-Dist: mkdocs-material; extra == 'docs'
+Requires-Dist: mkdocstrings[python]; extra == 'docs'
+Provides-Extra: document-input
+Requires-Dist: pillow; extra == 'document-input'
+Requires-Dist: pypdfium2; extra == 'document-input'
+Requires-Dist: python-docx; extra == 'document-input'
+Provides-Extra: docx
+Requires-Dist: python-docx; extra == 'docx'
+Provides-Extra: ocr
+Requires-Dist: pillow; extra == 'ocr'
+Requires-Dist: pytesseract; extra == 'ocr'
+Provides-Extra: pdf
+Requires-Dist: fpdf2; extra == 'pdf'
+Provides-Extra: qr
+Requires-Dist: pillow; extra == 'qr'
+Requires-Dist: segno==1.6.6; extra == 'qr'
+Requires-Dist: zxing-cpp==2.3.0; (python_version < '3.10') and extra == 'qr'
+Requires-Dist: zxing-cpp==3.1.0; (python_version >= '3.10') and extra == 'qr'
+Provides-Extra: zstd
+Requires-Dist: zstandard; extra == 'zstd'
+Description-Content-Type: text/markdown
+
+# glyphive
+
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](CHANGELOG.md)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-latest-blue.svg)](https://jose-pr.github.io/glyphive/)
+[![CI](https://img.shields.io/github/actions/workflow/status/jose-pr/glyphive/test.yml)](https://github.com/jose-pr/glyphive/actions/workflows/test.yml)
+
+Archive a file tree to **compact, OCR-friendly, printable pages** and restore
+it from a transcript or scan. Glyphive keeps the paper representation
+human-readable while using checksums and error correction to detect or repair
+the character errors that make ordinary base64-on-paper fragile.
+
+> **Status: alpha.** The wire format and CLI may change before 1.0.
+
+## Features
+
+- **Printable text, PDF, or Word output** with selectable font family and size.
+- **Bundled OCR-B PDF option** under the SIL Open Font License, plus custom
+  `.ttf`/`.otf` PDF font paths for measured channels.
+- **Measured OCR-safe `base16c-crc16-rs` alphabet** (`ABCDHKLMPRTVXY34`) with no confusable
+  character aliases.
+- **Localized integrity checks** on every encoded line and protected page
+  metadata.
+- **Document-wide Reed-Solomon parity** for correcting scattered OCR errors.
+- **Optional whole-page recovery** (`--parity-pages K`, default off): survives
+  up to K wholly lost/unscannable pages, independent of the per-line parity.
+- **Binary-safe archives** for nested trees, empty directories, and arbitrary
+  file contents.
+- **Deterministic restore** from text; optional OCR providers are loaded only
+  when image input is requested.
+
+## Installation
+
+```bash
+pip install glyphive
+```
+
+Optional features:
+
+| Extra | Adds | Needed for |
+| --- | --- | --- |
+| `pdf` | `fpdf2` | PDF output |
+| `docx` | `python-docx` | Word (`.docx`) output |
+| `zstd` | `zstandard` | zstd compression |
+| `ocr` | `Pillow`, `pytesseract` | Tesseract image bridge; the Tesseract program is installed separately |
+| `qr` | `segno`, `zxing-cpp`, `Pillow` | QR envelope generation and image decoding without OpenCV |
+| `all` | all packages above | All lightweight integrations |
+
+Glyphive requires `pathlib_next>=0.8.1` and Python 3.9 or newer.
+
+## Quick start
+
+Create a text archive from one directory, inspect it, and restore it:
+
+```bash
+glyphive create -f backup.txt --compression gzip -C project .
+glyphive list -f backup.txt
+glyphive inspect -f backup.txt          # recovery-headroom report (read-only)
+glyphive extract -f backup.txt -C restored
+```
+
+Restore or inspect an already-generated GQ1 QR image set explicitly with
+`glyphive extract -f qr-pages/ --from-qr -C restored` or
+`glyphive list -f qr-pages/ --from-qr`. Ordinary image input continues through
+OCR; QR mode requires `glyphive[qr]` and rejects mixed, duplicate, corrupt, or
+incomplete symbol sets before writing files.
+
+Create QR-only or hybrid human-readable/QR PDF pages with an explicit format:
+
+```bash
+glyphive create -f backup.pdf --format qr -C project .
+glyphive create -f backup-hybrid.pdf --format hybrid -C project .
+```
+
+A `.pdf` filename without `--format` remains the ordinary text PDF renderer;
+the suffix cannot distinguish PDF, QR, and hybrid presentations.
+
+Tar-style mode flags are equivalent when a positional command is inconvenient:
+
+```bash
+glyphive -c -f backup.txt -C project .
+glyphive -t -f backup.txt
+glyphive -x -f backup.txt -C restored
+```
+
+### Installed plugins
+
+Glyphive can explicitly discover implementations supplied by installed Python
+distributions. Pass the global `--plugins` flag to opt in for that invocation:
+
+```bash
+glyphive --plugins create -f backup.txt --codec vendor_codec -C project .
+```
+
+Plugin distributions register a concrete typed class under one of these entry
+point groups:
+
+| Entry-point group | Required base class |
+| --- | --- |
+| `glyphive.codecs` | `glyphive.codec.Codec` |
+| `glyphive.compression` | `glyphive.compression.CompressionMethod` |
+| `glyphive.render_formats` | `glyphive.render.RenderFormat` |
+| `glyphive.ocr_providers` | `glyphive.restore.ocr.OcrProvider` |
+
+The entry-point name must exactly match the class's lowercase registry `name`.
+Library callers use `glyphive.plugins.discover()`; normal imports and registry
+lookups never discover plugins. Discovery is deterministic and cached, and a
+bad candidate is reported without preventing valid candidates from loading.
+
+Installed plugin code executes with the same permissions as Glyphive and is
+not sandboxed. Use `--plugins` only when you trust every installed distribution
+that declares one of these groups. Discovery does not download or update code.
+
+Create a PDF instead:
+
+```bash
+pip install "glyphive[pdf,zstd]"
+glyphive create -f backup.pdf --compression zstd -C project .
+```
+
+Creation uses bounded-memory disk spools; `--temp-dir` selects their location
+and `--chunk-size` tunes sequential I/O for unusually constrained systems.
+
+Restore scans or generated documents with Tesseract. Input type is detected
+from file contents first and the extension second:
+
+```bash
+pip install "glyphive[ocr,document-input]"
+glyphive extract -f scans/ --ocr-engine tesseract -C restored
+glyphive list -f backup.pdf --ocr-engine tesseract
+```
+
+Restore verifies global integrity before publishing staged files. Advanced
+resource controls include `--temp-dir`, `--chunk-size`, and
+`--max-output-bytes` on both `extract` and `list`. Transcript frames,
+compressed payload, decompressed archive, and staged files are disk-backed;
+Reed-Solomon correction retains only compact offsets and one codeword at a time.
+
+The operating-system Tesseract executable and language data must also be
+installed. PDF input uses `pypdfium2`; Glyphive-generated DOCX transcripts are
+read directly with `python-docx`, without Microsoft Word or LibreOffice. See the
+[create guide](https://jose-pr.github.io/glyphive/guides/create/),
+[restore guide](https://jose-pr.github.io/glyphive/guides/restore/), and
+[OCR guide](https://jose-pr.github.io/glyphive/guides/ocr/) for details.
+
+## Format at a glance
+
+The default `base16c-crc16-rs` format uses exactly 16 payload symbols, or 4 bits per printed
+character. Each data (`L`) or parity (`P`) line has a masked index and a full
+CRC-16 encoded in the same safe alphabet:
+
+```text
+L<5 safe index chars> <up to 60 safe payload chars> #<4 safe CRC chars>
+```
+
+CRC-protected `H` header frames carry the codec, compression method, page
+count, and whole-document SHA-256. Each page has a protected `T` footer with
+its page number and a truncated page hash. Human-facing `#!glyphive` and
+`PAGE n/total` text is display-only; restore trusts the protected frames.
+
+Small, scattered line errors become known erasures and can be repaired by the
+document-wide Reed-Solomon parity. A missing page is reported rather than
+guessed, and the document-wide RS may still recover it from the surviving
+pages when the budget allows. `create --parity-pages K` (default 0, off)
+opts into a separate, guaranteed layer: K extra pages of document-level
+parity that survive up to K wholly lost pages regardless of the per-line
+budget. Read the [wire-format guide](https://jose-pr.github.io/glyphive/guides/wire-format/)
+for the complete layering and framing rules.
+
+## Standalone zipapp
+
+Releases may include a self-contained `glyphive.pyz`. Build the universal core
+artifact with:
+
+```bash
+python package.py --out dist/glyphive.pyz
+python dist/glyphive.pyz --help
+```
+
+The universal zipapp includes text output with `none` and `gzip` compression.
+Optional, platform-specific artifacts can be built with `--extras`; use
+`python package.py --help` for the declared choices.
+
+## API overview
+
+| Module | Purpose |
+| --- | --- |
+| `glyphive.archive` | Serialize and inspect deterministic archive streams, including chunked reader/writer primitives |
+| `glyphive.codec` | Resolve printable codecs; includes `base16c-crc16-rs` |
+| `glyphive.compression` | Resolve `none`, `gzip`, and optional `zstd` compression |
+| `glyphive.layout` | Paginate frames and verify protected page metadata |
+| `glyphive.plugins` | Explicitly discover trusted installed entry points |
+| `glyphive.render` | Render pages as text, PDF, or Word |
+| `glyphive.restore` | Decode documents and safely restore file trees |
+| `glyphive.restore.ocr` | Select OCR providers and OCR page images |
+
+Full generated API documentation is available on the
+[documentation site](https://jose-pr.github.io/glyphive/api/overview/).
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, test, documentation, and pull
+request guidance.
+
+Use a project-local virtual environment, then run the lightweight suite:
+
+```bash
+python -m venv .venv/dev
+.venv/dev/Scripts/python -m pip install -e ".[all,dev,docs]"
+.venv/dev/Scripts/python -m pytest -q
+.venv/dev/Scripts/python -m mkdocs build --strict
+```
+
+On POSIX, replace `.venv/dev/Scripts/python` with
+`.venv/dev/bin/python`. OCR sweeps and performance measurements are separate
+manual workloads; see [Benchmarks](https://jose-pr.github.io/glyphive/benchmarks/).
+
+### Releasing
+
+Glyphive follows [Semantic Versioning](https://semver.org/) and keeps a
+[`CHANGELOG.md`](CHANGELOG.md). Pushing a `v*` tag runs the release validation,
+package build, publication, and documentation deployment workflow.
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+The bundled OCR-B font retains its SIL Open Font License 1.1; see
+[third-party licenses](THIRD_PARTY_LICENSES.md).