phase: 141_read_range_dedupe_fix

All gates green and verified. Final report:

**Phase 141 final verification pass — complete**

- **Verified (tasks 01–04 already in `complete/`):** `AgentHolder.read_coverage` span recording (all 4 read outcomes, refusals record nothing); coverage dedupe matrix (range read of uncovered lines proceeds, fully-covered re-read → `ALREADY_IN_CONTEXT` with a now-true claim, partial plain re-read → `REREAD_PARTIAL` naming merged spans, `REREAD_TRUNCATED` retired, fast path retired per task 02); `TOOLS_SECTION` re-read sentence re-cut to coverage-true form (prompt lock re-pinned); owner-scenario integration repro (pure + truncated variants) and mock `read two ranges` flow + dedicated E2E — all match the task specs exactly; no code defects found.
- **Tests/lint/coverage:** `uv run pytest --cov=app --cov-report=term-missing` → exit 0, TOTAL 99% (5498 stmts, `app/rag/agent.py` 99%) — run twice, both green; `uv run pytest tests/e2e/test_read_range_dedupe.py -v --no-cov` → 2 passed in isolation; `uv run ruff check . && uv run pyright` → All checks passed / 0 errors.
- **Completion criteria:** (1) two different ranges both reach the model, re-covered re-read refused truthfully — ✅ (integration + E2E); (2) partial plain re-read gets the `offset`/`limit` teaching, false claim gone both directions — ✅; (3) plain-read + phase-131 result shapes byte-identical, existing pins pass unchanged — ✅; (4) all gate commands green, >90% — ✅; (5) no behavior change in completed phases (grep/ls, truncation notice, `read_docs`/`read_truncations` signals) — ✅ (whole project suite green).
- **Documentation:** README.md — fixed pre-existing phase-140 gap: `BOR_PDF_PICTORIAL` / `BOR_PDF_PICTORIAL_MIN_CHARS` were in `.env.example`/Settings but undocumented (README claims every `.env.example` var is covered); added the pictorial-PDF-pass bullet to the PDF section + two config-reference rows. AGENTS.md — verified consistent (rules, quick-ref commands, phase refs all check out) — no changes needed.
- **Notable:** overview's "fast path survives for holder-state rows" note is superseded by task 02's authoritative decision (every dedupe row resolves — "full" needs the true line count); implementation follows task 02. No phase files touched; changes left in the working tree for the harness commit.
- **Next pending phase:** `142_kb_overview_freshness`.

app/rag/prompts.py

@@ -197,10 +197,15 @@ SUGGEST_INTRO = (
 #: phase-118 summary-seed contract (the ``<documents>`` section holds
 #: SUMMARIES — a suggested document's full text is not in the prompt
 #: until ``read`` adds it; do not re-read a document you have already
-#: read — answer from the text already in the prompt; if the user
-#: asks to open or read a suggested document, ``read`` it — that is
-#: the point of the section — the phase-72 do-not-read rule and the
-#: reverted ``<document path="...">`` anchor are retired with the
+#: read IN FULL — answer from the text already in the prompt — a
+#: PARTIAL document (a range read, or a truncated read) is not
+#: complete in the context until read all: read the other parts with
+#: ``offset`` / ``limit`` (phase 141, task 02 — the re-read sentence
+#: re-cut to the coverage-true form; the mock keys off the ``<tools>``
+#: marker's presence, not the wording, so it is untouched); if the
+#: user asks to open or read a suggested document, ``read`` it — that
+#: is the point of the section — the phase-72 do-not-read rule and
+#: the reverted ``<document path="...">`` anchor are retired with the
 #: full-text seeds);
 #: the one-call rule names the consequence (a batched second call is
 #: discarded — runs only the first); the never-repeat rule says why
@@ -232,8 +237,11 @@ TOOLS_SECTION: str = (
     "summary blocks — adding its full content to your context. The "
     "<documents> section holds SUMMARIES — the full text of a "
     "suggested document is not in your prompt until you `read` it. Do "
-    "not re-read a document you have already read — its full text is "
-    "already in your prompt; answer directly from it. If the user "
+    "not re-read a document you have already read in full — its full "
+    "text is in your prompt, answer from it. If you have read only "
+    "part of a document (a range read, or a truncated read), read the "
+    "other parts with `offset` and `limit` — the document is not "
+    "complete in your context until you have read it all. If the user "
     "asks you to open or read a suggested document, `read` it — that "
     "is the point of the section. For `read`, a bare document path "
     "(without the source name) will not resolve. Very large documents "