reading-companionlisted

# Reading Companion (Phase 2 — Reading Surface) Turn an **EPUB** into: - a **self-contained HTML reader** (serif typography, cream/dark themes, TOC, progress, pagination/scroll, keyboard nav) with **in-flow highlights + notes**; - an **active-reading plan** (structure map + reading path + adversarial questions); - **highlights-in-context** Markdown export. The truth source for annotations is a **sidecar JSON** (`reading-state.json`). The HTML is a regenerable *view* — delete it and re-render, and highlights re-attach to the correct paragraph. This is the reading surface only; there is no live AI bridge yet (that is Phase 3). ## Tools All tools are Python **stdlib only** (no `pip install` needed). Run with `python3`. | Tool | Purpose | |------|---------| | `tools/ingest.py <file-or-url> -o content.json` | **(Phase 4) Unified entry** — routes by extension/scheme to the right adapter: `.epub`→epub-ingest, `.pdf`→pdf-ingest, `.txt`/`.md`→text-ingest, `http(s)://`→url-ingest. Unknown input → clear non-zero error. Prefer this over calling adapters directly. | | `tools/epub-ingest.py <book.epub> -o content.json` | Parse EPUB → normalized `content.json` (chapters → paragraphs with stable `pid`, `source_hash`). | | `tools/text-ingest.py <file.txt\|file.md> -o content.json` | **(Phase 4)** TXT/Markdown → content.json. MD `#`/`##`/`###` → `tag` h1/h2/h3 (heading vs body); TXT splits on blank lines. Empty input → fail loud (no file). | | `tools/url-ingest.py <http(s) URL> -o conte