phase: 142_kb_overview_freshness

All verification complete. Final report:

**Phase 142 final verification pass — all green**

- **Verified implemented** (working tree matches design; app diff is exactly 2 lines of logic): `app/rag/overview.py` — `regenerate_overview` now orders the lite-model document list `created_at` desc, `(source, path)` tie-break (newest docs survive the cap); `app/rag/prompts.py` — `_KB_INTRO` rewritten to the honest intro (recency bias, "map not inventory", verify-with-`ls`/`grep`; "(generated at import time)" gone).
- **Completion criteria:**
  1. Forced-cap outline leads with newest docs — ✅ E2E `test_kb_overview_freshness.py` test 1 (cap 300, digest from `zz_new/z.md`, no "old" tokens) + integration repro (cap 150 → `mydocs zz new 03 md zz new 03`)
  2. New honest intro served in `<knowledge_base>` — ✅ unit pin (verbatim) + E2E test 2 (`build_kb_section` surface, tag/cap byte-stable)
  3. Gates — ✅ `uv run pytest --cov=app --cov-report=term-missing`: **3359 passed**, `app/` TOTAL **99%** (>90%); `uv run pytest tests/e2e/test_kb_overview_freshness.py -v --no-cov`: **3 passed** in isolation; `uv run pytest tests/e2e/test_kb_overview.py -v --no-cov`: **4 passed** in isolation; `uv run ruff check . && uv run pyright`: **clean, 0 errors**
  4. No behavior change in completed phases — ✅ cap env knob, change-gated sync trigger, `build_kb_section` cap/marker, deflect path all byte-identical (pinned pins pass in the 3359)
- **Documentation:** README.md reviewed in full (every `.env.example` var documented with matching defaults, all endpoints/routes verified against `app/api/`, Quick Start/deploy/troubleshooting claims verified) and AGENTS.md re-reviewed (rules + quick reference accurate) — **verified consistent, no changes needed**.
- **Decisions:** none required — no defects found; no live-infra changes (only the already-running local `db` container was used by tests).
- **Next pending phase:** `.agents/phases/todo/143_mobile_keyboard_after_answer`.

app/rag/prompts.py

@@ -125,11 +125,23 @@ _STEERING_INTRO = (
     "Where these instructions conflict with the defaults above, follow the owner:\n"
 )
 
-#: One-line intro of the ``<knowledge_base>`` section (phase 31): the
-#: lite-generated outline is the agent's a-priori picture of the KB.
+#: One-line intro of the ``<knowledge_base>`` section (phase 31;
+#: phase 142, task 03 — the honest-intro rewrite, owner-confirmed
+#: 2026-09-30): the outline is a COMPACT, possibly partial picture
+#: that favors RECENT documents (task 02 orders the generation input
+#: newest-first, so recent docs are the ones it covers when the cap
+#: bites) — a map of what exists, not a complete inventory — and
+#: "latest / complete set" questions verify with ``ls``/``grep``
+#: before answering from it; "(generated at import time)" is GONE
+#: (false — the sync regenerates the row on every KB change — and it
+#: taught the model to treat a partial outline as the whole frozen KB).
 _KB_INTRO = (
-    "The basic categories of everything in this knowledge base "
-    "(generated at import time):\n"
+    'A compact picture of the knowledge base\'s categories and topics — '
+    'it favors recent documents and may omit older or lesser ones: a map '
+    'of what exists, not a complete inventory. For questions about the '
+    'latest state or the complete set ("the last N …", "everything '
+    'about …", "all the …"), verify with `ls` (drill into the folders) '
+    'or `grep` before answering from the outline:\n'
 )
 
 #: The ``<documents>`` section's start-here intro (phase 118, task 03 —