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/schemas.py

@@ -602,6 +602,19 @@ class DocContent(BaseModel):
     #: repository's default branch — nothing to show); also dropped by
     #: the serializer (never ``null``).
     origin_branch: str | None = None
+    #: Phase 148 (task 02) — the rendered-page BYTES routes for a
+    #: page-QUALIFYING PDF (the phase-133 fallback class or the
+    #: phase-140 pictorial class): ``/api/documents/<id>/pages/<i>``
+    #: for ``i`` in 1..``page_count`` (1-based — the importer's
+    #: ``<doc-id>-p{N}.png`` copy names; a per-page render failure
+    #: leaves a GAP the route 404s — the viewer's note covers it). The
+    #: viewer's page strip (task 03) renders from it; the document's
+    #: text stays in the DB for Q&A, it is simply not displayed. ABSENT
+    #: from the wire for every OTHER document — text docs, images,
+    #: text-heavy PDFs (``None`` → dropped by the serializer — never
+    #: ``null``, the :attr:`image_url` omission precedent), so a
+    #: non-qualifying doc's payload is byte-identical to pre-phase.
+    page_urls: list[str] | None = None
 
     @model_serializer(mode="wrap")
     def _serialize(self, handler: SerializerFunctionWrapHandler) -> Any:
@@ -612,6 +625,8 @@ class DocContent(BaseModel):
             data.pop("origin_url", None)
         if self.origin_branch is None:
             data.pop("origin_branch", None)
+        if self.page_urls is None:
+            data.pop("page_urls", None)
         return data