phase: 148_pdf_pages_in_sources

**Phase 148 — final verification pass: complete, 100% green.**

- **Verified (tasks 01–04 already implemented):** page render/persist at index (`_persist_page_copies`, fail-soft, stale-replace, qualifier-loss, prune hook via `_delete_page_copies`); public `GET /api/documents/{id}/pages/{n}` (uuid4-credential, 404-all-non-servable, `image/png` + cache header); `DocContent.page_urls` additive-omitted; shared `renderDocument` strip (lazy imgs, "Page N" captions, text + Summary suppressed, onerror note, createElement-only); migration 0026; `pdf_page_dir` setting; `.env.example` entry
- **Completion criteria:** (1) pictorial + fallback classes get `p{N}.png` + `page_count`, text-heavy gets neither — pinned, pass; (2) unchanged re-sync renders zero (fast path) — pass; (3) changed re-index replaces copies, qualifier-loss/prune delete — pass; (4) route 404 matrix + payload key absent-never-null — pass; (5) modal AND /document.html strip with suppression, text-heavy byte-identical — E2E pass; (6) see below; (7) no completed-phase drift — full suite green
- **Tests:** `uv run pytest --cov=app --cov-report=term-missing` → **3461 passed, 0 failed**, `app/` coverage **99%** (>90%); `uv run pytest tests/e2e/test_pdf_pages_in_sources.py -v --no-cov` → **4 passed** in isolation; `uv run ruff check .` clean; `uv run pyright` → 0 errors, 0 warnings
- **Documentation:** README had **1 pre-existing inconsistency** — the Production Deployment section's standalone `podman run` example (and compose note) omitted the **required** `BOR_ADMIN_PASSWORD`/`BOR_SESSION_SECRET` (the fail-loud boot gate the README's own Admin section documents — the container would refuse to start); fixed with the two `-e` flags + a note for the compose path. All else verified consistent: 70/70 `.env.example` vars documented, all defaults match `config.py`, pages table matches routes, Containerfile/esbuild/uid-10001/healthcheck/entrypoint claims accurate, QA commands match pytest config. **AGENTS.md: verified consistent — no changes needed**
- **Notable:** repo uses `Containerfile` (Podman) — README's `podman build` example is valid as-is; no live infrastructure touched
- **Next pending phase:** `149_sync_progress_box`

app/config.py

@@ -395,6 +395,24 @@ class Settings(BaseSettings):
     #: checkouts, re-cloned) and ``upload_dir`` (replaced on every
     #: upload): the served copy must outlive the source file.
     image_dir: str = "~/bor-sources/images"
+    #: Where rendered PDF PAGE PNGs are copied for serving (phase 148,
+    #: ``BOR_PDF_PAGE_DIR`` — the ``image_dir`` convention): a
+    #: page-qualifying PDF (the phase-133 fallback class — unusable
+    #: text layer — or the phase-140 pictorial class — the sparse-page
+    #: pass described ≥1 page) gets EVERY page rendered at index time
+    #: to ``<doc-id>-p{N}.png`` here (N 1-based; ``documents.page_count``
+    #: is the page count — a per-page render failure leaves a gap),
+    #: so the document viewer shows the ACTUAL pages instead of the
+    #: page descriptions (TODO L5 — the IKEA assembly-instruction
+    #: class: the descriptions help the embeddings, "but not when
+    #: shown to the user"). Raw string — ``Path.expanduser()`` is
+    #: applied by the importer, not here (the ``sources_dir``/
+    #: ``upload_dir``/``image_dir`` convention). Deliberately separate
+    #: from ``sources_dir``/``upload_dir``: git checkouts are
+    #: re-cloned, uploads are replaced, local dirs are user-edited —
+    #: the served copy must outlive the source file (the ``image_dir``
+    #: rationale).
+    pdf_page_dir: str = "~/bor-sources/pages"
 
     # --- Pictorial PDF pages (phase 140: sparse pages rendered + vision-described) ---
     #: Master switch for the pictorial PDF pass (phase 140, LOCKED A3,