[T049-T055 + UX] Phase 5 documents + single-model + responder/UX fixes

Phase 5 — Document package:
- agent/tools/doc_generator.py + 4 WeasyPrint templates: real PDFs from session
data, amber-highlighted pre-fills, blanks (never [NAME]/PLACEHOLDER), logged
field sources; zip for "Download all"; head-less preview snippet
- app/phases/documents.py: preview + evidence checklist (pre-checked from
documents_available) + file list + Download all + Start over
- nav: Recommendations "Prepare my documents" -> Documents; Start over -> intake
- launch(allowed_paths=[tempdir]) so Gradio can serve the generated PDFs
- tests: 8 document tests (real PDF text via pypdf 6.12.2, pinned one-before)

Single LLM + UX fixes (from live testing):
- one model end-to-end: MODEL_ID=lfm2.5:8b (fast ~2s, tool-calling + good
multilingual); removed per-phase model split (no fallback, hackathon rule)
- languages limited to those lfm2.5:8b handles well (probe-verified): English,
French, Spanish, Portuguese, Arabic, Hindi, Chinese, Japanese, Korean, Russian
- responder: free-text box ALWAYS visible (never stuck if the model omits its
directive); pills/country shown in addition when offered; derive_answer falls
back to text; removed "Save and continue later"; fixed leaking control labels
- fixed button CSS selectors (Gradio puts elem_id on the <button>, so #id button
never matched -> buttons rendered unstyled/grey)

Co-authored-by: Codex <noreply@openai.com>

.env.example

@@ -8,6 +8,11 @@ OLLAMA_HOST=http://127.0.0.1:11434
 # Spec default is qwen2.5:7b; pick what your Ollama host actually has.
 MODEL_ID=qwen2.5:7b
 
+# Per-phase model overrides (optional). The interview is fast Q&A; a small model
+# keeps it snappy. The assessment is reasoning-heavy and can use a larger model.
+INTERVIEW_MODEL_ID=qwen2.5:7b
+ASSESSMENT_MODEL_ID=qwen2.5:7b
+
 # LLM provider: "ollama" (default) or a litellm provider name.
 MODEL_PROVIDER=ollama
 

agent/tools/doc_generator.py

@@ -1 +1,210 @@
-# doc_generator.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""agent/tools/doc_generator.py — Phase 5 document package generator (T049/T050).
+
+Generates four PDFs from the completed session using WeasyPrint + HTML templates
+(agent/tools/templates/). Every pre-filled value comes only from
+``session.interview`` / ``session.assessment`` / ``session.selected_country`` —
+nothing is invented (CLAUDE.md Critical Rule 4). Pre-filled fields are wrapped in
+an amber-highlight ``.fill`` span; missing fields render as a blank line (never a
+literal "PLACEHOLDER"/"[NAME]"). Every filled field is logged with its source key.
+
+Output PDFs go to an ephemeral temp directory (ARCHITECTURE.md §Security).
+"""
+
+from __future__ import annotations
+
+import html
+import logging
+import tempfile
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from weasyprint import HTML
+
+from agent.tools.country_lookup import lookup_country
+
+logger = logging.getLogger("refuge.doc_generator")
+
+TEMPLATES = Path(__file__).resolve().parent / "templates"
+_HEAD = (TEMPLATES / "_head.html").read_text(encoding="utf-8")
+
+
+@dataclass
+class GeneratedDoc:
+    key: str
+    title: str
+    meta: str
+    path: Path
+
+
+# -- field helpers ----------------------------------------------------------
+
+def _is_empty(value) -> bool:
+    return value is None or value == "" or value == [] or value == {}
+
+
+def fill(value, source_key: str, *, fallback_blank: bool = True) -> str:
+    """Amber-highlight a pre-filled value, logging its source. Blank if missing."""
+    if _is_empty(value):
+        return '<span class="blank">&nbsp;</span>' if fallback_blank else ""
+    text = ", ".join(str(v) for v in value) if isinstance(value, list) else str(value)
+    logger.info("Filling field from session key: %s", source_key)
+    return f'<span class="fill">{html.escape(text)}</span>'
+
+
+def _render(template_name: str, tokens: dict[str, str]) -> str:
+    tpl = (TEMPLATES / template_name).read_text(encoding="utf-8")
+    tpl = tpl.replace("%%HEAD%%", _HEAD)
+    for key, value in tokens.items():
+        tpl = tpl.replace(f"%%{key}%%", value)
+    return tpl
+
+
+# -- per-document HTML builders --------------------------------------------
+
+def _personal_statement_html(session) -> str:
+    iv = session.interview
+    family_clause = ""
+    if not _is_empty(iv.family_situation):
+        family_clause = f", traveling with {fill(iv.family_situation, 'interview.family_situation')}"
+    history_para = ""
+    if not _is_empty(iv.free_text_history):
+        history_para = f"<p>{fill(iv.free_text_history, 'interview.free_text_history')}</p>"
+    return _render("personal_statement.html", {
+        "full_name": fill(None, "interview.full_name"),  # not collected — blank to complete
+        "origin_country": fill(iv.origin_country, "interview.origin_country"),
+        "current_country": fill(iv.current_country, "interview.current_country"),
+        "family_clause": family_clause,
+        "persecution": fill(iv.persecution_types, "interview.persecution_types"),
+        "history_para": history_para,
+    })
+
+
+def _action_plan_html(session, rec: dict | None) -> str:
+    country = session.selected_country or "your chosen country"
+    months = (rec or {}).get("processingTimeMonths")
+    processing = f"about {months} months" if months else "a variable amount of time"
+    office = (rec or {}).get("unhcrOffice")
+    unhcr = f"Yes — {office}" if office else ("Yes" if (rec or {}).get("unhcrPresence") else "Check locally")
+    steps_src = (rec or {}).get("steps") or [
+        "Register with UNHCR or the asylum authority",
+        "File your asylum claim with your personal statement",
+        "Attend your refugee status interview (RSD)",
+        "Receive the decision (appeal if refused)",
+        "Access integration support",
+    ]
+    steps_html = "".join(
+        f'<p class="step"><b>Step {i}.</b> {html.escape(str(s))}</p>'
+        for i, s in enumerate(steps_src, start=1)
+    )
+    return _render("action_plan.html", {
+        "selected_country": html.escape(str(country)),
+        "processing": processing,
+        "unhcr_office": html.escape(str(unhcr)),
+        "steps": steps_html,
+    })
+
+
+def _emergency_contacts_html(session, rec: dict | None) -> str:
+    country = session.selected_country or "your chosen country"
+    office = (rec or {}).get("unhcrOffice") or "Nearest UNHCR office"
+    orgs = (rec or {}).get("legalAidOrgs") or []
+    if orgs:
+        orgs_html = "".join(
+            f'<div class="org"><b>{html.escape(str(o.get("name", "")))}</b>'
+            f'<span>{html.escape(str(o.get("url", "")))}</span></div>'
+            for o in orgs if isinstance(o, dict)
+        )
+    else:
+        orgs_html = "<p>Ask the UNHCR office for a list of registered legal-aid partners.</p>"
+    return _render("emergency_contacts.html", {
+        "selected_country": html.escape(str(country)),
+        "unhcr_office": html.escape(str(office)),
+        "orgs": orgs_html,
+    })
+
+
+def _rights_card_html(session) -> str:
+    grounds = session.assessment.convention_grounds or []
+    grounds_txt = ", ".join(grounds) if grounds else "to be confirmed in your interview"
+    return _render("rights_summary_card.html", {
+        "origin_country": fill(session.interview.origin_country, "interview.origin_country"),
+        "selected_country": html.escape(str(session.selected_country or "your chosen country")),
+        "grounds": html.escape(grounds_txt),
+    })
+
+
+# -- public API -------------------------------------------------------------
+
+_DOCS = [
+    ("personal_statement", "Personal statement (pre-filled)", "PDF · narrative for your claim"),
+    ("action_plan", "Action plan", "PDF · step-by-step roadmap with contacts"),
+    ("emergency_contacts", "Emergency contacts", "PDF · UNHCR offices & legal aid"),
+    ("rights_summary_card", "Your rights — summary card", "PDF · key protections"),
+]
+
+
+def build_html(session) -> dict[str, str]:
+    """Return {key: full_html} for all four documents (handy for tests/preview)."""
+    rec = None
+    if session.selected_country:
+        looked = lookup_country(session.selected_country)
+        rec = None if looked.get("error") else looked
+    return {
+        "personal_statement": _personal_statement_html(session),
+        "action_plan": _action_plan_html(session, rec),
+        "emergency_contacts": _emergency_contacts_html(session, rec),
+        "rights_summary_card": _rights_card_html(session),
+    }
+
+
+def preview_statement_html(session) -> str:
+    """Inline (head-less) personal-statement snippet for the on-screen preview."""
+    iv = session.interview
+    family_clause = ""
+    if not _is_empty(iv.family_situation):
+        family_clause = f", traveling with {fill(iv.family_situation, 'interview.family_situation')}"
+    history = ""
+    if not _is_empty(iv.free_text_history):
+        history = f"<p>{fill(iv.free_text_history, 'interview.free_text_history')}</p>"
+    return (
+        '<article class="doc"><h4>Personal Statement</h4>'
+        '<p class="doc__sub">In support of an application for refugee status · Prepared with Refuge</p>'
+        f"<p>My name is {fill(None, 'interview.full_name')}. I am a national of "
+        f"{fill(iv.origin_country, 'interview.origin_country')}. I am currently in "
+        f"{fill(iv.current_country, 'interview.current_country')}{family_clause}.</p>"
+        '<div class="doc__divider"></div>'
+        f"<p>I left my home because of {fill(iv.persecution_types, 'interview.persecution_types')}.</p>"
+        f"{history}"
+        "</article>"
+    )
+
+
+def generate(session, out_dir: Path | None = None) -> list[GeneratedDoc]:
+    """Generate the four PDFs. Returns GeneratedDoc records with file paths."""
+    out_dir = Path(out_dir) if out_dir else Path(tempfile.mkdtemp(prefix="refuge_docs_"))
+    out_dir.mkdir(parents=True, exist_ok=True)
+    htmls = build_html(session)
+
+    docs: list[GeneratedDoc] = []
+    for key, title, meta in _DOCS:
+        path = out_dir / f"{key}.pdf"
+        HTML(string=htmls[key]).write_pdf(str(path))
+        docs.append(GeneratedDoc(key=key, title=title, meta=meta, path=path))
+    logger.info("Generated %d documents in %s", len(docs), out_dir)
+    return docs
+
+
+def zip_package(docs: list[GeneratedDoc], out_dir: Path | None = None) -> Path:
+    """Bundle the generated PDFs into a single zip for "Download all"."""
+    base = Path(out_dir) if out_dir else docs[0].path.parent
+    zip_path = base / "refuge_documents.zip"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for d in docs:
+            zf.write(d.path, arcname=d.path.name)
+    return zip_path
+
+
+__all__ = [
+    "generate", "build_html", "preview_statement_html", "zip_package", "GeneratedDoc", "fill",
+]

agent/tools/templates/_head.html

@@ -0,0 +1,30 @@
+<meta charset="utf-8" />
+<style>
+  @page { size: A4; margin: 22mm 20mm; }
+  :root {
+    --primary: #0E6A58; --primary-deep: #0A5042; --accent-tint: #FBEDE1;
+    --text: #1A1A1A; --muted: #6B7280; --line: #E7E2D8;
+  }
+  * { box-sizing: border-box; }
+  body { font-family: "Inter", "Helvetica Neue", Arial, sans-serif; color: var(--text);
+    font-size: 12pt; line-height: 1.6; }
+  h1, h2, h3, h4 { font-family: "Fraunces", Georgia, "Times New Roman", serif; color: var(--primary-deep);
+    margin: 0 0 4px; line-height: 1.2; }
+  h1 { font-size: 22pt; }
+  h2 { font-size: 15pt; margin-top: 18px; }
+  .sub { color: var(--muted); font-size: 10pt; margin: 0 0 16px; letter-spacing: .02em; }
+  p { margin: 0 0 11px; }
+  .fill { background: var(--accent-tint); color: #7a431a; padding: 0 4px; border-radius: 3px; font-weight: 600; }
+  .blank { display: inline-block; min-width: 120px; border-bottom: 1px solid #999; }
+  .divider { height: 1px; background: var(--line); margin: 14px 0; }
+  .note { color: var(--muted); font-size: 9.5pt; margin-top: 20px; border-top: 1px solid var(--line); padding-top: 8px; }
+  ul, ol { margin: 0 0 11px; padding-left: 20px; }
+  li { margin-bottom: 6px; }
+  .step { margin-bottom: 12px; }
+  .step b { color: var(--primary-deep); }
+  .chip { display: inline-block; background: #E5EFEA; color: var(--primary-deep); font-size: 9.5pt;
+    padding: 2px 8px; border-radius: 999px; margin-right: 4px; }
+  .org { margin-bottom: 8px; }
+  .org b { display: block; }
+  .org span { color: var(--muted); font-size: 10pt; }
+</style>

agent/tools/templates/action_plan.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html>
+<html lang="en"><head>%%HEAD%%</head><body>
+  <h1>Action Plan — %%selected_country%%</h1>
+  <p class="sub">A step-by-step roadmap to seek asylum · Prepared with Refuge</p>
+
+  <p>This plan is for seeking protection in %%selected_country%%. Processing typically
+  takes %%processing%%. UNHCR presence: %%unhcr_office%%.</p>
+
+  <div class="divider"></div>
+
+  %%steps%%
+
+  <p class="note">Timeframes are typical estimates from UNHCR data and may vary.
+  Keep copies of every document you submit.</p>
+</body></html>

agent/tools/templates/emergency_contacts.html

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html lang="en"><head>%%HEAD%%</head><body>
+  <h1>Emergency Contacts</h1>
+  <p class="sub">UNHCR offices &amp; legal aid · Prepared with Refuge</p>
+
+  <h2>%%selected_country%%</h2>
+  <p>UNHCR office: %%unhcr_office%%</p>
+
+  <h2>Legal aid &amp; support organisations</h2>
+  %%orgs%%
+
+  <div class="divider"></div>
+  <h2>If you are in immediate danger</h2>
+  <ul>
+    <li>Contact the nearest UNHCR office or registration centre.</li>
+    <li>Ask for an asylum-seeker certificate — it protects you from being returned.</li>
+    <li>You have the right to request a translator and free legal assistance.</li>
+  </ul>
+
+  <p class="note">Contacts are drawn from the curated Refuge country reference.
+  Verify details locally where possible.</p>
+</body></html>

agent/tools/templates/personal_statement.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en"><head>%%HEAD%%</head><body>
+  <h1>Personal Statement</h1>
+  <p class="sub">In support of an application for refugee status · Prepared with Refuge</p>
+
+  <p>My name is %%full_name%%. I am a national of %%origin_country%%. I am currently
+  in %%current_country%%%%family_clause%%.</p>
+
+  <div class="divider"></div>
+
+  <p>I left my home because of %%persecution%%.</p>
+
+  %%history_para%%
+
+  <p>I fear that if I return I will be at risk of serious harm because of the
+  circumstances described above. I am asking for protection and the right not to be
+  returned to a place where my life or freedom would be threatened.</p>
+
+  <p class="note">Fields highlighted in amber were pre-filled from what you told Refuge.
+  Anything left blank is for you to complete. You can edit any part of this statement.</p>
+</body></html>

agent/tools/templates/rights_summary_card.html

@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en"><head>%%HEAD%%</head><body>
+  <h1>Your Rights — Summary Card</h1>
+  <p class="sub">Key protections for people seeking asylum · Prepared with Refuge</p>
+
+  <h2>Non-refoulement</h2>
+  <p>You cannot be forced back to a country where your life or freedom would be at
+  serious risk. This is a core protection under the 1951 Refugee Convention.</p>
+
+  <h2>Your rights while your claim is decided</h2>
+  <ul>
+    <li>The right to seek asylum and have your claim heard fairly.</li>
+    <li>The right to an interpreter and to free legal assistance.</li>
+    <li>The right not to be detained arbitrarily.</li>
+    <li>The right to basic dignity: shelter, food, and emergency healthcare.</li>
+  </ul>
+
+  <h2>For your situation</h2>
+  <p>Origin: %%origin_country%% &nbsp;·&nbsp; Seeking protection in: %%selected_country%%</p>
+  <p>Convention grounds identified: %%grounds%%</p>
+
+  <p class="note">Carry this card with you. If anyone tries to return you, show it and
+  ask to speak to UNHCR.</p>
+</body></html>

app/app.py

@@ -15,6 +15,7 @@ here (CLAUDE.md Design Rule 7).
 
 from __future__ import annotations
 
+import os
 import sys
 from pathlib import Path
 
@@ -27,6 +28,7 @@ from agent.loop import create_loop  # noqa: E402
 from app.config import load_env  # noqa: E402
 from app.design_tokens import root_css  # noqa: E402
 from app.phases import assessment as assessment_phase  # noqa: E402
+from app.phases import documents as documents_phase  # noqa: E402
 from app.phases import intake as intake_phase  # noqa: E402
 from app.phases import interview as interview_phase  # noqa: E402
 from app.phases import recommendations as reco_phase  # noqa: E402
@@ -35,6 +37,9 @@ from app.state.session import SessionState, State  # noqa: E402
 # Load .env (OLLAMA_HOST, MODEL_ID, …) before anything reads the environment.
 load_env()
 
+# One model for the whole flow (hackathon: single LLM, no fallback). Read from
+# MODEL_ID via the loop factory.
+
 # Web fonts: Fraunces (display serif) + Inter (UI sans) per DESIGN.md §3.
 FONT_IMPORT = (
     "@import url('https://fonts.googleapis.com/css2?"
@@ -73,7 +78,8 @@ APP_CSS = (
     + intake_phase.INTAKE_CSS + "\n"
     + interview_phase.INTERVIEW_CSS + "\n"
     + assessment_phase.ASSESSMENT_CSS + "\n"
-    + reco_phase.RECO_CSS
+    + reco_phase.RECO_CSS + "\n"
+    + documents_phase.DOCUMENTS_CSS
 )
 
 
@@ -98,6 +104,7 @@ def build_app() -> gr.Blocks:
         interview_ui = interview_phase.build(visible=False, session_st=session_st, loop_st=loop_st)
         assess_ui = assessment_phase.build(visible=False, session_st=session_st, loop_st=loop_st)
         reco_ui = reco_phase.build(visible=False, session_st=session_st)
+        docs_ui = documents_phase.build(visible=False, session_st=session_st)
 
         async def begin(lang, session, loop):
             if not lang:
@@ -121,7 +128,9 @@ def build_app() -> gr.Blocks:
             # confirmed, then hands off to the assessment screen.
             if not _confirmed_review(session):
                 return
-            async for facts_html, reason_html, progress_html, sess in assess_ui.start_fn(session, loop):
+            # Fresh loop for the assessment turn (same model, its own steering/abort).
+            assess_loop = create_loop()
+            async for facts_html, reason_html, progress_html, sess in assess_ui.start_fn(session, assess_loop):
                 yield (gr.update(visible=False), gr.update(visible=True),
                        facts_html, reason_html, progress_html, sess)
 
@@ -150,12 +159,48 @@ def build_app() -> gr.Blocks:
         # Once the assessment stream finishes, show the recommendation cards.
         assess_event.then(show_recommendations, inputs=[session_st], outputs=reco_outputs)
 
+        # Recommendations -> Documents: generate the package for the chosen country.
+        docs_outputs = [reco_ui.column, docs_ui.column, *docs_ui.render_outputs]
+
+        def show_documents(session):
+            if session is None or not session.selected_country:
+                return [gr.update()] * len(docs_outputs)
+            if session.state < State.DOCUMENTS:
+                from app.phases.interview import advance_to
+                advance_to(session, State.DOCUMENTS)
+            updates = docs_ui.populate(session)
+            return [gr.update(visible=False), gr.update(visible=True), *updates]
+
+        reco_ui.proceed.click(show_documents, inputs=[session_st], outputs=docs_outputs)
+
+        # Start over: return to the intake screen for a fresh session.
+        def start_over():
+            return (
+                gr.update(visible=True), gr.update(visible=False),
+                gr.update(visible=False), gr.update(visible=False),
+                gr.update(visible=False), None, None,
+            )
+
+        docs_ui.start_over.click(
+            start_over,
+            inputs=[],
+            outputs=[intake_ui.column, interview_ui.column, assess_ui.column,
+                     reco_ui.column, docs_ui.column, session_st, loop_st],
+        )
+
     return demo
 
 
 def main() -> None:
+    import tempfile
+
     demo = build_app()
-    demo.launch(server_name="0.0.0.0", css=APP_CSS, theme=gr.themes.Base())
+    # allowed_paths lets Gradio serve the generated PDFs (written to the system
+    # temp dir) for download.
+    demo.launch(
+        server_name="0.0.0.0", css=APP_CSS, theme=gr.themes.Base(),
+        allowed_paths=[tempfile.gettempdir()],
+    )
 
 
 if __name__ == "__main__":

app/phases/documents.py

@@ -1 +1,122 @@
-# documents.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""app/phases/documents.py — Phase 5 document package screen (T051/T052).
+
+Matches mockup.html #phase-5: a document preview (with amber-tint highlights on
+pre-filled fields), an evidence checklist (pre-checked from
+``session.interview.documents_available``), the four generated files, a
+"Download all" primary action, and a "Start over" ghost button.
+
+The PDFs are generated by ``agent.tools.doc_generator`` from real session data.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import gradio as gr
+
+from agent.tools.doc_generator import generate, preview_statement_html, zip_package
+from app.state.session import SessionState
+
+# Evidence checklist: (label, sublabel, document_available key or None).
+CHECKLIST = [
+    ("Personal statement", "Drafted by Refuge · ready", "_always"),
+    ("Identity document or sworn statement", "Passport, national ID, or a sworn statement", "passport"),
+    ("Proof of journey / entry", "Tickets, stamps, or a written account", "travel"),
+    ("Photos or messages showing the threat", "Optional, but strengthens your claim", "evidence"),
+    ("Names of witnesses", "People who can confirm what happened", "witnesses"),
+    ("Medical or police reports", "If you have any", "medical"),
+]
+
+DOCUMENTS_CSS = """
+#docs-screen { background: var(--surface); border: 1px solid var(--line);
+  border-radius: var(--r-lg); box-shadow: var(--shadow-md); overflow: hidden;
+  max-width: 1180px; margin: 0 auto; }
+.pkg { display:grid; grid-template-columns:1.1fr .9fr; gap:0; }
+@media(max-width:820px){ .pkg { grid-template-columns:1fr; } }
+.pkg__preview { padding:clamp(18px,4vw,28px); border-right:1px solid var(--line); background:var(--surface-2); }
+@media(max-width:820px){ .pkg__preview { border-right:0; border-bottom:1px solid var(--line); } }
+.pkg__side { padding:clamp(18px,4vw,28px); background:var(--surface); }
+.pkg__lbl { font-size:12px; letter-spacing:.06em; text-transform:uppercase; color:var(--text-muted); font-weight:600; margin:0 0 12px; }
+.doc { background:#fff; border:1px solid var(--line-strong); border-radius:var(--r-md); box-shadow:var(--shadow-sm);
+  padding:26px 28px; max-height:360px; overflow:hidden; position:relative; }
+.doc::after { content:""; position:absolute; left:0; right:0; bottom:0; height:70px; background:linear-gradient(180deg,rgba(255,255,255,0),#fff); }
+.doc h4 { font-family:var(--font-display); font-size:18px; font-weight:600; margin:0 0 2px; }
+.doc .doc__sub { font-size:12px; color:var(--text-muted); margin:0 0 16px; }
+.doc p { font-size:13px; line-height:1.7; color:#33373f; margin:0 0 11px; }
+.doc .fill { background:var(--accent-tint); color:#7a431a; padding:0 4px; border-radius:3px; font-weight:600; }
+.doc .blank { display:inline-block; min-width:90px; border-bottom:1px solid #aaa; }
+.doc__divider { height:1px; background:var(--line); margin:14px 0; }
+
+#docs-checklist .wrap label { font-size:14.5px !important; }
+#docs-files .download-link, #docs-files label { font-size:13.5px; }
+#docs-download, #docs-download button { background:var(--accent) !important; color:var(--on-accent) !important;
+  box-shadow:0 2px 0 var(--accent-deep) !important; border:0 !important; font-weight:600 !important;
+  border-radius:var(--r-md) !important; padding:14px 22px !important; }
+#docs-download:hover, #docs-download button:hover { background:var(--accent-deep) !important; }
+#docs-startover, #docs-startover button { background:transparent !important; color:var(--primary-deep) !important;
+  border:0 !important; box-shadow:none !important; font-weight:600 !important; }
+#docs-startover:hover, #docs-startover button:hover { background:var(--primary-tint) !important; }
+"""
+
+
+@dataclass
+class DocumentsUI:
+    column: gr.Column
+    populate: callable      # (session) -> list of updates for render_outputs
+    render_outputs: list
+    start_over: gr.Button
+    session: gr.State
+
+
+def _checklist_values(session: SessionState) -> list[str]:
+    """Labels that should be pre-checked, from documents_available (SC-043)."""
+    available = {d.lower() for d in (session.interview.documents_available or [])}
+    checked = []
+    for label, _sub, key in CHECKLIST:
+        if key == "_always" or (key and key in available):
+            checked.append(label)
+    return checked
+
+
+def build(visible: bool = False, session_st: gr.State | None = None) -> DocumentsUI:
+    session_st = session_st or gr.State(None)
+
+    with gr.Column(elem_id="docs-screen", visible=visible) as column:
+        with gr.Row(elem_classes=["pkg"]):
+            with gr.Column(elem_classes=["pkg__preview"]):
+                gr.HTML('<p class="pkg__lbl">Preview · Personal statement</p>')
+                preview = gr.HTML('<article class="doc"></article>')
+            with gr.Column(elem_classes=["pkg__side"]):
+                gr.HTML('<p class="pkg__lbl">Evidence to gather</p>')
+                checklist = gr.CheckboxGroup(
+                    choices=[label for label, _s, _k in CHECKLIST],
+                    value=[], label="", elem_id="docs-checklist",
+                )
+                gr.HTML('<p class="pkg__lbl">Your files</p>')
+                files = gr.File(label="", interactive=False, elem_id="docs-files")
+                download_all = gr.DownloadButton(
+                    "⤓ Download all (4 files)", elem_id="docs-download", visible=False
+                )
+                start_over = gr.Button(
+                    "↺ Start over for a different country", elem_id="docs-startover"
+                )
+
+    render_outputs = [preview, checklist, files, download_all]
+
+    def populate(session: SessionState) -> list:
+        docs = generate(session)
+        zip_path = zip_package(docs)
+        return [
+            gr.update(value=preview_statement_html(session)),
+            gr.update(value=_checklist_values(session)),
+            gr.update(value=[str(d.path) for d in docs]),
+            gr.update(value=str(zip_path), visible=True),
+        ]
+
+    return DocumentsUI(
+        column=column, populate=populate, render_outputs=render_outputs,
+        start_over=start_over, session=session_st,
+    )
+
+
+__all__ = ["build", "DocumentsUI", "DOCUMENTS_CSS", "CHECKLIST"]

app/phases/intake.py

@@ -17,16 +17,19 @@ import gradio as gr
 
 from app.state.session import SessionState, State
 
-# (native script label, English gloss). Order matches the mockup grid.
+# (native script label, English gloss). Limited to the languages the single
+# model (lfm2.5:8b) handles reliably — verified by a language probe.
 LANGUAGES = [
     ("English", "English"),
     ("Français", "French"),
-    ("العربية", "Arabic"),
-    ("Kiswahili", "Swahili"),
-    ("አማርኛ", "Amharic"),
-    ("Soomaali", "Somali"),
-    ("Hausa", "Hausa"),
+    ("Español", "Spanish"),
     ("Português", "Portuguese"),
+    ("العربية", "Arabic"),
+    ("हिन्दी", "Hindi"),
+    ("中文", "Chinese"),
+    ("日本語", "Japanese"),
+    ("한국어", "Korean"),
+    ("Русский", "Russian"),
 ]
 
 # Map a chosen pill label (native) to the English name stored on the session.
@@ -62,10 +65,10 @@ INTAKE_CSS = """
   color:var(--on-primary) !important; box-shadow:var(--shadow-sm) !important; }
 
 .intake-cta { margin-top:30px; }
-#intake-begin button { background:var(--accent) !important; color:var(--on-accent) !important;
+#intake-begin, #intake-begin button { background:var(--accent) !important; color:var(--on-accent) !important;
   box-shadow:0 2px 0 var(--accent-deep) !important; border:0 !important; border-radius:var(--r-md) !important;
   font-weight:600 !important; font-size:16px !important; padding:16px 28px !important; }
-#intake-begin button:hover { background:var(--accent-deep) !important; box-shadow:0 2px 0 #a8531f !important; }
+#intake-begin:hover, #intake-begin button:hover { background:var(--accent-deep) !important; box-shadow:0 2px 0 #a8531f !important; }
 
 .intake-trust { margin-top:24px; display:inline-flex; align-items:center; gap:9px; font-size:13px;
   color:var(--text-muted); background:var(--surface-2); border:1px solid var(--line);

app/phases/interview.py

@@ -98,12 +98,9 @@ INTERVIEW_CSS = """
 
 /* Native Gradio controls themed to match the responder */
 #iv-choice .wrap label, #iv-multi .wrap label { border-radius:var(--r-full) !important; }
-#iv-continue button { background:var(--primary) !important; color:var(--on-primary) !important;
+#iv-continue, #iv-continue button { background:var(--primary) !important; color:var(--on-primary) !important;
   box-shadow:0 2px 0 var(--primary-deep) !important; border:0 !important; font-weight:600 !important; }
-#iv-continue button:hover { background:var(--primary-deep) !important; }
-#iv-save button { background:transparent !important; color:var(--primary-deep) !important;
-  border:0 !important; box-shadow:none !important; font-weight:600 !important; }
-#iv-save button:hover { background:var(--primary-tint) !important; }
+#iv-continue:hover, #iv-continue button:hover { background:var(--primary-deep) !important; }
 """
 
 
@@ -190,29 +187,38 @@ def advance_to(session: SessionState, target: "State | str | None") -> None:
 
 
 def derive_answer(spec: ResponderSpec, radio_v, multi_v, country_v, text_v) -> str:
-    if spec.mode == "choice" and spec.multi:
-        return ", ".join(multi_v) if multi_v else ""
-    if spec.mode == "choice":
-        return radio_v or ""
-    if spec.mode == "country":
-        return country_name(country_v) if country_v else ""
+    """Read the answer, preferring a structured selection, else the text box.
+
+    The text box is always available, so it is the fallback whenever the
+    structured control (pills/country) wasn't used.
+    """
+    if spec.mode == "choice" and spec.multi and multi_v:
+        return ", ".join(multi_v)
+    if spec.mode == "choice" and radio_v:
+        return radio_v
+    if spec.mode == "country" and country_v:
+        return country_name(country_v)
     return (text_v or "").strip()
 
 
 def responder_updates(spec: ResponderSpec):
-    """gr.update() tuple for (radio, multi, country, text) given the spec."""
-    is_choice_single = spec.mode == "choice" and not spec.multi
-    is_choice_multi = spec.mode == "choice" and spec.multi
+    """gr.update() tuple for (radio, multi, country, text) given the spec.
+
+    The free-text box is ALWAYS visible so the person can always answer and
+    continue, even if the model omits or malforms its responder directive. Pills
+    or the country selector appear in addition when the model offers them.
+    """
+    is_choice_single = spec.mode == "choice" and not spec.multi and bool(spec.options)
+    is_choice_multi = spec.mode == "choice" and spec.multi and bool(spec.options)
     is_country = spec.mode == "country"
-    is_text = spec.mode == "text"
     return (
         gr.update(visible=is_choice_single, choices=spec.options if is_choice_single else [], value=None),
         gr.update(visible=is_choice_multi, choices=spec.options if is_choice_multi else [], value=[]),
         gr.update(visible=is_country, value=None),
         gr.update(
-            visible=is_text,
+            visible=True,  # safety net — always available
             value="",
-            placeholder=spec.placeholder or "Take your time. You can write in any language.",
+            placeholder=spec.placeholder or "Type your answer here…",
         ),
     )
 
@@ -256,19 +262,17 @@ def build(
 
         with gr.Column(elem_id="iv-responder"):
             gr.HTML('<div class="label-row">Your answer</div>')
-            radio = gr.Radio(choices=[], label="", visible=False, elem_id="iv-choice")
-            multi = gr.CheckboxGroup(choices=[], label="", visible=False, elem_id="iv-multi")
+            radio = gr.Radio(choices=[], label="", show_label=False, visible=False, elem_id="iv-choice")
+            multi = gr.CheckboxGroup(choices=[], label="", show_label=False, visible=False, elem_id="iv-multi")
             country = gr.Dropdown(
-                choices=country_choices(), label="", visible=False,
+                choices=country_choices(), label="", show_label=False, visible=False,
                 allow_custom_value=True, filterable=True, elem_id="iv-country",
             )
             text = gr.Textbox(
-                label="", lines=3, visible=False, elem_id="iv-text",
-                placeholder="Take your time. You can write in any language.",
+                label="", show_label=False, lines=3, visible=True, elem_id="iv-text",
+                placeholder="Type your answer here…",
             )
-            with gr.Row():
-                save = gr.Button("⤓ Save and continue later", elem_id="iv-save", scale=1)
-                cont = gr.Button("Continue →", elem_id="iv-continue", scale=1)
+            cont = gr.Button("Continue →", elem_id="iv-continue")
 
     stream_outputs = [chat, rail, radio, multi, country, text, session_st, loop_st, spec_st]
 

app/phases/recommendations.py

@@ -47,10 +47,10 @@ details.prep ul { margin:11px 0 0; padding:0; list-style:none; display:flex; fle
 details.prep li { font-size:13.5px; color:var(--text-secondary); display:flex; gap:9px; line-height:1.45; }
 details.prep li::before { content:""; flex:0 0 auto; width:6px; height:6px; border-radius:50%; background:var(--accent); margin-top:7px; }
 
-.ccard-slot .btn-card-select button { width:100% !important; border-radius:var(--r-md) !important; font-weight:600 !important;
+.ccard-slot .btn-card-select, .ccard-slot .btn-card-select button { width:100% !important; border-radius:var(--r-md) !important; font-weight:600 !important;
   background:var(--surface) !important; color:var(--primary-deep) !important; border:1px solid var(--line-strong) !important; box-shadow:none !important; }
-.ccard-slot .btn-card-select button:hover { border-color:var(--primary) !important; background:var(--primary-tint) !important; }
-.ccard-slot.is-selected .btn-card-select button { background:var(--primary) !important; color:var(--on-primary) !important;
+.ccard-slot .btn-card-select:hover, .ccard-slot .btn-card-select button:hover { border-color:var(--primary) !important; background:var(--primary-tint) !important; }
+.ccard-slot.is-selected .btn-card-select, .ccard-slot.is-selected .btn-card-select button { background:var(--primary) !important; color:var(--on-primary) !important;
   border-color:var(--primary) !important; box-shadow:0 2px 0 var(--primary-deep) !important; }
 
 #reco-roadmap { margin-top:30px; background:var(--surface-2); border:1px solid var(--line); border-radius:var(--r-lg); padding:clamp(18px,4vw,26px); }
@@ -67,6 +67,11 @@ details.prep li::before { content:""; flex:0 0 auto; width:6px; height:6px; bord
 .step__body p { font-size:14px; color:var(--text-secondary); margin:0 0 7px; }
 .step__meta { display:flex; gap:8px; flex-wrap:wrap; }
 .tag-s { font-size:12px; font-weight:500; color:var(--text-secondary); background:var(--surface); border:1px solid var(--line); padding:3px 10px; border-radius:var(--r-full); display:inline-flex; align-items:center; gap:6px; }
+#reco-proceed-row { margin-top:24px; justify-content:center; }
+#reco-proceed, #reco-proceed button { background:var(--accent) !important; color:var(--on-accent) !important;
+  box-shadow:0 2px 0 var(--accent-deep) !important; border:0 !important; font-weight:600 !important;
+  border-radius:var(--r-md) !important; padding:14px 26px !important; }
+#reco-proceed:hover, #reco-proceed button:hover { background:var(--accent-deep) !important; }
 """
 
 
@@ -215,6 +220,7 @@ class RecommendationsUI:
     render_outputs: list  # [slot,card,btn]*MAX_CARDS + [roadmap]
     populate: callable     # (session) -> list of updates for render_outputs
     session: gr.State
+    proceed: gr.Button     # "Prepare my documents" -> Phase 5
 
 
 def build(visible: bool = False, session_st: gr.State | None = None) -> RecommendationsUI:
@@ -236,6 +242,8 @@ def build(visible: bool = False, session_st: gr.State | None = None) -> Recommen
                 cards.append(card)
                 btns.append(btn)
         roadmap = gr.HTML(roadmap_html(None))
+        with gr.Row(elem_id="reco-proceed-row"):
+            proceed = gr.Button("Prepare my documents →", elem_id="reco-proceed")
 
     render_outputs = []
     for i in range(MAX_CARDS):
@@ -282,6 +290,7 @@ def build(visible: bool = False, session_st: gr.State | None = None) -> Recommen
 
     return RecommendationsUI(
         column=column, render_outputs=render_outputs, populate=populate, session=session_st,
+        proceed=proceed,
     )
 
 

requirements.txt

@@ -20,6 +20,7 @@ litellm==1.87.1         # latest 1.88.0
 # Testing
 pytest==9.0.2           # latest 9.0.3
 pytest-asyncio==1.3.0   # latest 1.4.0
+pypdf==6.12.2           # latest 6.13.0 — PDF text extraction in document tests
 
 # E2E browser driver (Phase 6) — uncomment when Phase 6 begins
 # playwright==1.55.0

scripts/validate_design_tokens.py

@@ -32,6 +32,7 @@ CSS_SOURCES = [
     REPO_ROOT / "app" / "phases" / "interview.py",
     REPO_ROOT / "app" / "phases" / "assessment.py",
     REPO_ROOT / "app" / "phases" / "recommendations.py",
+    REPO_ROOT / "app" / "phases" / "documents.py",
 ]
 
 _ROOT_DEF_RE = re.compile(r"--([a-z0-9-]+):\s*([^;]+);")

tests/integration/test_documents.py

@@ -1 +1,70 @@
-# test_documents.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""tests/integration/test_documents.py — document package generation (T053).
+
+Seeds a complete session (real Ethiopia/Sudan scenario) and generates the four
+PDFs with WeasyPrint. Asserts they are real, valid, non-empty, contain the
+person's real data, and contain no placeholder tokens.
+"""
+
+from pathlib import Path
+
+from agent.tools.country_lookup import lookup_country
+from agent.tools.doc_generator import generate, zip_package
+from app.state.session import SessionState, State
+
+
+def _complete_session(origin="Ethiopia") -> SessionState:
+    s = SessionState()
+    for target in (State.INTAKE, State.SITUATION, State.HISTORY, State.GOALS,
+                   State.REVIEW, State.ASSESSMENT, State.RECOMMENDATIONS, State.DOCUMENTS):
+        s.transition_to(target)
+    s.language = "Amharic"
+    s.interview.origin_country = origin
+    s.interview.current_country = "Sudan"
+    s.interview.persecution_types = ["Political", "Ethnic"]
+    s.interview.immediate_danger = True
+    s.interview.family_situation = "two children"
+    s.interview.documents_available = ["passport"]
+    s.interview.languages_spoken = ["Amharic", "Arabic"]
+    s.interview.free_text_history = "Armed men came to our village in November."
+    s.assessment.convention_grounds = ["Political opinion"]
+    s.assessment.recommended_countries = [lookup_country("Kenya")]
+    s.selected_country = "Kenya"
+    return s
+
+
+def _pdf_text(path: Path) -> str:
+    from pypdf import PdfReader
+
+    reader = PdfReader(str(path))
+    return "\n".join(page.extract_text() or "" for page in reader.pages)
+
+
+def test_generates_four_nonempty_valid_pdfs(tmp_path):
+    docs = generate(_complete_session(), out_dir=tmp_path)
+    assert len(docs) == 4
+    for d in docs:
+        assert d.path.exists()
+        data = d.path.read_bytes()
+        assert len(data) > 1000          # non-trivial
+        assert data[:5] == b"%PDF-"      # valid PDF header
+
+
+def test_personal_statement_contains_real_origin(tmp_path):
+    docs = generate(_complete_session(), out_dir=tmp_path)
+    statement = next(d for d in docs if d.key == "personal_statement")
+    assert "Ethiopia" in _pdf_text(statement.path)  # SC-039: real data
+
+
+def test_no_placeholder_tokens(tmp_path):
+    docs = generate(_complete_session(), out_dir=tmp_path)
+    for d in docs:
+        text = _pdf_text(d.path)
+        for forbidden in ("PLACEHOLDER", "[NAME]", "[COUNTRY]"):
+            assert forbidden not in text, f"{forbidden} found in {d.key}"
+
+
+def test_download_all_zip(tmp_path):
+    docs = generate(_complete_session(), out_dir=tmp_path)
+    zip_path = zip_package(docs, out_dir=tmp_path)
+    assert zip_path.exists()
+    assert zip_path.stat().st_size > 1000

tests/unit/test_doc_fields.py

@@ -1 +1,49 @@
-# test_doc_fields.py — see PLAN.md and ARCHITECTURE.md for implementation spec
+"""tests/unit/test_doc_fields.py — pre-fill field rules (T055).
+
+Pre-filled values trace to real session keys and are amber-highlighted; missing
+fields render as a blank line (never a crash, never an invented value).
+"""
+
+from agent.tools.doc_generator import build_html, fill
+from app.state.session import SessionState, State
+
+
+def test_fill_present_value_is_highlighted():
+    out = fill("Ethiopia", "interview.origin_country")
+    assert "Ethiopia" in out
+    assert 'class="fill"' in out
+
+
+def test_fill_missing_value_is_blank_not_placeholder():
+    out = fill(None, "interview.origin_country")
+    assert 'class="blank"' in out
+    assert "Ethiopia" not in out
+    assert "None" not in out  # never leak the literal None
+    assert "PLACEHOLDER" not in out and "[NAME]" not in out
+
+
+def test_fill_list_is_joined_and_escaped():
+    out = fill(["Political", "Ethnic"], "interview.persecution_types")
+    assert "Political, Ethnic" in out
+    safe = fill("<script>x</script>", "interview.free_text_history")
+    assert "<script>" not in safe  # HTML-escaped
+
+
+def _min_session() -> SessionState:
+    s = SessionState()
+    for t in (State.INTAKE, State.SITUATION, State.HISTORY, State.GOALS, State.REVIEW,
+              State.ASSESSMENT, State.RECOMMENDATIONS, State.DOCUMENTS):
+        s.transition_to(t)
+    return s
+
+
+def test_build_html_with_no_data_does_not_crash():
+    # origin_country is None and nothing is filled — must render blanks, not crash.
+    s = _min_session()
+    htmls = build_html(s)
+    assert set(htmls) == {
+        "personal_statement", "action_plan", "emergency_contacts", "rights_summary_card"
+    }
+    statement = htmls["personal_statement"]
+    assert 'class="blank"' in statement  # origin rendered as a blank line
+    assert "None" not in statement

tests/unit/test_intake_state.py

@@ -43,10 +43,10 @@ def test_begin_without_language_raises():
 
 def test_begin_with_language_transitions_to_intake():
     s = SessionState()
-    select_language(s, "Kiswahili")
+    select_language(s, "Español")
     assert begin_interview(s) is State.INTAKE
     assert s.state is State.INTAKE
-    assert s.language == "Swahili"
+    assert s.language == "Spanish"
 
 
 def test_toggle_selection_single_and_deselect():