feat(tui): lovability pass - argument+sources on completion card, epigraph, actionable errors

Completion card now leads with the argument the piece made (thesis claim) + a source tally (count, high-influence, high-authority) + reading time, via a new polish.source_stats() shared with the evidence report. The welcome shows a rotating, date-stable public-domain writing epigraph with a 'Welcome back.' lead for returning writers (one line; compactness guard 14->15). ui.explain_error() now maps context-window overflow and token-budget failures to actionable next steps instead of a raw traceback. Existing _summary_card/_paused_card were already strong; this fills the gaps rather than duplicating them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: Smrutiranjan Patri

CHANGELOG.md

@@ -17,6 +17,14 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
   New files: `personas/{wildean,poe-gothic,dickensian,whitmanesque}.md`.
 - **Welcome footer shows agentic state.** The status footer now reads `agentic on|off` (replacing the
   redundant `flash` model slot, which duplicated `pro`), and the hint line surfaces `/agentic on|off`.
+- **Lovability pass on the TUI.** The completion card now leads with **the argument the piece made**
+  (its thesis claim) plus a **source tally** (N sources · high-influence · high-authority) and
+  **reading time** — "proof, not vibes" the moment a run finishes (new `polish.source_stats()`, shared
+  with the evidence report so they never disagree). The welcome shows a rotating, date-stable **writing
+  epigraph** (public-domain voices only), prefixed with **"Welcome back."** for a returning writer, on a
+  single line. And `ui.explain_error()` now maps **context-window overflow** and **token-budget**
+  failures to actionable next steps (`/set max_context_chars …` / `/set max_run_tokens 0`) instead of a
+  raw traceback.
 
 ### Changed
 - **Cache-friendly prompt ordering (token efficiency, no quality cost).** The writer + critic prompts

resume.md

@@ -31,6 +31,13 @@
     config requests run from plain English ("turn on researcher", "set chapters to 12", "use the
     poe-gothic persona"). Only `/user` + `delete` stay manual. Fixed a latent bug where the prompt told
     the model to emit `/set` while the extractor dropped it. Test updated (`test_hardening.py`).
+  - **TUI lovability pass.** Audited the shell for delight and found the base is already strong
+    (`_summary_card`, `_paused_card` exist + are wired). Implemented the genuine gaps: the completion
+    card now leads with the **argument made** + **source tally** + **reading time** (new
+    `polish.source_stats()`, shared with the evidence report); the welcome shows a rotating, date-stable
+    **writing epigraph** + a **"Welcome back."** lead for returning writers (one line; compactness guard
+    bumped 14→15); `ui.explain_error()` maps **context-overflow** and **budget** failures to actionable
+    fixes. Skipped a redundant `/why` (eval/tableread/summary already show the work).
   - **Test hermeticity.** Added an autouse `_isolated_settings` fixture (`tests/conftest.py`) pointing
     `config._SETTINGS` at a tmp path, so the suite always runs against shipped dataclass defaults and a
     developer's personal `settings.yaml` (e.g. `agentic=true`) can't turn the local run red. CI already

src/writingagent/polish.py

@@ -351,6 +351,27 @@ def build_evidence_report(manuscript_md: str, thesis_md: str = "", title: str =
     return "\n".join(out).rstrip() + "\n"
 
 
+def source_stats(manuscript_md: str) -> dict:
+    """A quick, deterministic tally of the finished piece's References (no model call):
+    ``{count, high_influence, credible, avg_auth}``. Shares the row parsing + authority
+    scoring with ``build_evidence_report`` so the completion card and the evidence report
+    can never disagree. ``count == 0`` when there is no ranked References block yet."""
+    rows = _REF_ROW.findall(manuscript_md or "")
+    if not rows:
+        return {"count": 0, "high_influence": 0, "credible": 0, "avg_auth": 0}
+    scores = [int(s) for s, _d, _t in rows]
+    auths = []
+    for _s, _d, tail in rows:
+        um = _ROW_URL.search(tail)
+        auths.append(source_authority(um.group(1) if um else ""))
+    return {
+        "count": len(rows),
+        "high_influence": sum(1 for s in scores if s >= 50),
+        "credible": sum(1 for a in auths if a >= AUTH_REPUTABLE),
+        "avg_auth": round(sum(auths) / len(auths)) if auths else AUTH_NEUTRAL,
+    }
+
+
 # ── cross-chapter cohesion (book, D-008) ─────────────────────────────────────────
 def _prose_only(md: str) -> str:
     """Strip fenced code and headings so repetition scanning sees only prose."""

src/writingagent/shell/branding.py

@@ -398,6 +398,25 @@ def _book_status_rows(uid: str, projects: list[tuple[str, str]]) -> list[tuple[s
     return rows
 
 
+# A rotating writing epigraph for the welcome - public-domain voices only (consistent with the
+# personas' no-living-author rule). Kept short so it never wraps; chosen by the date so it's
+# stable within a day, varied across days.
+_EPIGRAPHS = [
+    ("Easy reading is damn hard writing.", "Nathaniel Hawthorne"),
+    ("Omit needless words.", "William Strunk Jr."),
+    ("Vigorous writing is concise.", "William Strunk Jr."),
+    ("The pen is the tongue of the mind.", "Cervantes"),
+    ("The secret of being a bore is to tell everything.", "Voltaire"),
+    ("What is written without effort is read without pleasure.", "Samuel Johnson"),
+    ("Substitute 'damn' for every 'very'; your editor will delete it.", "Mark Twain"),
+]
+
+
+def _epigraph() -> tuple[str, str]:
+    import datetime
+    return _EPIGRAPHS[datetime.date.today().toordinal() % len(_EPIGRAPHS)]
+
+
 def _welcome(console, cfg: ModelConfig, settings: Settings, uid: str) -> None:
     sdir = brain.skills_dir(uid)
     skl = sorted(p.stem for p in sdir.glob("*.md")) if sdir.exists() else []
@@ -433,6 +452,12 @@ def _welcome(console, cfg: ModelConfig, settings: Settings, uid: str) -> None:
     if fake:
         console.print(Text(f"  {fake_msg}", style=f"bold {ERR}"))
 
+    # A single warm line: a rotating writing epigraph, prefixed with a greeting for a
+    # returning writer. One line by design (see the compactness note above).
+    quote, who = _epigraph()
+    lead = "Welcome back.  " if projects else ""
+    console.print(Text(f"  {lead}“{quote}”  — {who}", style=f"italic {DIM}"))
+
     # ── No API key yet: point at the one command that fixes it (the wizard ran first). ─
     if _provider_needs_key(settings):
         p = _active_provider(settings)

src/writingagent/shell/dashboard.py

@@ -340,21 +340,38 @@ def _summary_card(console, dash, state: dict, uid: str, book_id: str) -> None:
     from rich.panel import Panel
     from rich.text import Text
 
-    from .. import llm
+    from .. import llm, polish
     from ..brain import ArticlePaths, BookPaths
     console.print()   # settle: the Live's last frame has no trailing newline, so the
     #                   summary Panel border would otherwise glue onto the last log line
     is_article = state.get("mode") == "article"
     paths = ArticlePaths(book_id, uid) if is_article else BookPaths(book_id, uid)
-    words = len((brain.read_text(paths.manuscript) or "").split())
+    manuscript = brain.read_text(paths.manuscript) or ""
+    words = len(manuscript.split())
+    read_min = polish.read_time_min(manuscript)
     insights = [i for i in (state.get("insights") or []) if isinstance(i, int)]
     units = state.get("num_sections" if is_article else "num_chapters", "?")
     toks, cost = llm.current_tokens(), llm.current_cost()
 
     body = Text()
     body.append(f"{units} {'sections' if is_article else 'chapters'}", style=PARCH)
     body.append(f"   ·   {words:,} words", style=PARCH)
+    if read_min:
+        body.append(f"   ·   {read_min} min read", style=DIM)
     body.append(f"   ·   {dash._elapsed()} elapsed\n", style=DIM)
+    # Proof, not vibes: the argument it made + how grounded it is, right at the top.
+    if dash.brief:
+        body.append("argued:  ", style=DIM)
+        claim = dash.brief if len(dash.brief) <= 150 else dash.brief[:149].rstrip() + "…"
+        body.append(f"{claim}\n", style=f"italic {PARCH}")
+    stats = polish.source_stats(manuscript)
+    if stats["count"]:
+        body.append(f"sourced: {stats['count']} sources", style=DIM)
+        if stats["high_influence"]:
+            body.append(f" · {stats['high_influence']} high-influence", style=DIM)
+        if stats["credible"]:
+            body.append(f" · {stats['credible']} high-authority", style=DIM)
+        body.append("\n", style=DIM)
     body.append(f"{toks:,} tokens", style=DIM)
     if cost > 0:
         body.append(f"   ·   ${cost:.4f}", style=f"bold {GOLD}")

src/writingagent/ui.py

@@ -278,6 +278,13 @@ def explain_error(exc) -> str | None:
         return "Network/provider hiccup — check your connection, then run again (saved & resumable)."
     if any(k in s for k in ("permission", "another process", "being used", "in use", "locked")):
         return "A file is locked (open in another program?) — close it, then try again."
+    if any(k in s for k in ("context length", "context_length", "maximum context", "context window",
+                            "too many tokens", "reduce the length", "string too long")):
+        return ("Prompt outgrew the model's context window — try a smaller context "
+                "(`/set max_context_chars 16000`) or split into more, shorter units; progress is saved.")
+    if any(k in s for k in ("budget", "max_run_tokens", "token budget")):
+        return ("Run token budget reached — lift it with `/set max_run_tokens 0` (0 = unlimited), "
+                "then run again (everything committed is saved).")
     return None
 
 

tests/test_ui.py

@@ -127,7 +127,7 @@ def test_welcome_is_compact(tmp_brain, monkeypatch):
     from writingagent.config import load_config, load_settings
     console = _record_console()
     shell._welcome(console, load_config(), load_settings(), "u")
-    assert len(console.file.getvalue().splitlines()) <= 14
+    assert len(console.file.getvalue().splitlines()) <= 15   # +1 for the one-line epigraph
 
 
 def test_welcome_warns_on_fake_mode(tmp_brain, monkeypatch):