fix: ground dream customs story flow

docs/superpowers/plans/2026-06-08-dream-customs-story-ux-polish.md

@@ -0,0 +1,291 @@
+# Dream Customs Story UX Polish Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make the public Dream Customs flow feel like one complete dream-customs ritual by grounding generated cards in the submitted dream, hiding developer controls from ordinary users, and turning hosted-model wait time into story-aware status copy.
+
+**Architecture:** Keep Hugging Face Space as the public Gradio frontend and Modal as the hidden hosted MiniCPM route. Add deterministic local grounding helpers in `dream_customs/pipeline.py` so weak hosted output is repaired before rendering. Keep the UI thin and mobile-first by moving backend controls behind a collapsed developer accordion and adding user-facing processing copy without adding new backend dependencies.
+
+**Tech Stack:** Python, Pydantic, Gradio Blocks, pytest, Hugging Face Space, Modal hosted endpoints.
+
+---
+
+## File Structure
+
+- Modify `dream_customs/pipeline.py`: extract concrete dream details, detect generic model output, and repair pact fields with dream-specific visitor/action/release copy.
+- Modify `dream_customs/prompts.py`: tighten MiniCPM text prompts so generated questions and pact cards must reuse concrete dream details.
+- Modify `dream_customs/ui/app.py`: collapse developer settings by default and add story-aware loading/status text near the main action.
+- Modify `dream_customs/ui/copy.py`: add public-facing processing copy.
+- Modify `dream_customs/ui/styles.py`: style the processing note and make the collapsed developer panel quieter on desktop and mobile.
+- Modify `tests/test_pipeline.py`: add regression tests for dream-grounded hosted output repair.
+- Modify `tests/test_ui_actions.py`: add regression tests for public UI defaults and processing copy.
+
+## Task 0: Baseline And Branch Hygiene
+
+**Files:**
+- Read: `AGENTS.md`
+- Read: `PRODUCT.md`
+- Read: `docs/spec.md`
+- Read: `dream_customs/pipeline.py`
+- Read: `dream_customs/ui/app.py`
+
+- [x] **Step 1: Confirm repository and remotes**
+
+Run:
+
+```bash
+pwd
+git status --short --branch
+git remote -v
+```
+
+Expected:
+
+```text
+/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon
+## feature/dream-customs-ui-voice-settings...origin/feature/dream-customs-ui-voice-settings
+origin https://github.com/adjcjh777/dream-customs-build-small.git
+space https://huggingface.co/spaces/build-small-hackathon/dream-customs
+```
+
+- [x] **Step 2: Sync latest code**
+
+Run:
+
+```bash
+git pull
+```
+
+Expected:
+
+```text
+Already up to date.
+```
+
+## Task 1: Ground Weak Pact Output In Dream Details
+
+**Files:**
+- Modify: `tests/test_pipeline.py`
+- Modify: `dream_customs/pipeline.py`
+
+- [x] **Step 1: Add failing regression test for generic hosted output**
+
+Add a test in `tests/test_pipeline.py` that uses a weak text client returning a generic visitor, generic health tip, generic odd task, and bare time release for this input:
+
+```text
+I dreamed I was at a customs window carrying a suitcase full of wet paper. The clerk asked me to declare every unfinished promise before sunrise.
+```
+
+Expected repaired card:
+
+- `visitor_name` contains either `Wet Paper` or `Unfinished Promise`.
+- `alliance_reading` mentions at least one of `wet paper`, `customs window`, or `unfinished promise`.
+- `practical_suggestion` mentions a first step or promise, not generic hydration.
+- `weird_task` mentions paper, promise, suitcase, or customs.
+- `bedtime_release` is not a bare time such as `7:00 PM`.
+
+- [x] **Step 2: Run focused failing test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_pipeline.py::test_generate_pact_repairs_generic_hosted_output_with_dream_details -q
+```
+
+Expected: FAIL because current polishing does not repair all generic-but-valid hosted output.
+
+- [x] **Step 3: Implement dream-detail extraction and repair**
+
+In `dream_customs/pipeline.py`:
+
+- Add `_extract_dream_anchors(intake)` returning up to three concrete lower-case noun phrases from dream text, voice transcript, and visual clues.
+- Add `_is_generic_daily_tip(text)` for generic health/productivity suggestions that do not reference the dream.
+- Add `_is_bare_time_or_generic_release(text)`.
+- Extend `_polish_card_for_daily_use()` so weak visitor names, alliance readings, practical suggestions, weird tasks, and bedtime releases are repaired with the anchors.
+- Keep existing safety behavior and dated permit stamping unchanged.
+
+- [x] **Step 4: Run focused test until green**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_pipeline.py::test_generate_pact_repairs_generic_hosted_output_with_dream_details -q
+```
+
+Expected: PASS.
+
+## Task 2: Tighten MiniCPM Prompt Contracts
+
+**Files:**
+- Modify: `tests/test_pipeline.py`
+- Modify: `dream_customs/prompts.py`
+
+- [x] **Step 1: Add prompt contract test**
+
+Add a test proving `pact_prompt()` includes explicit grounding constraints:
+
+- reuse at least two concrete dream details;
+- avoid generic wellness filler;
+- `bedtime_release` must be a sentence, not a time;
+- `visitor_name` must be an object/event from the dream, not a human name unless a person appeared.
+
+- [x] **Step 2: Run focused failing test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_pipeline.py::test_pact_prompt_requires_dream_grounded_card -q
+```
+
+Expected: FAIL until prompt copy is tightened.
+
+- [x] **Step 3: Update prompts**
+
+In `dream_customs/prompts.py`, add concrete instructions to `negotiation_prompt()`, `followup_question_prompt()`, `pact_prompt()`, and `pact_revision_prompt()` that keep the model plain, non-clinical, and dream-specific.
+
+- [x] **Step 4: Run prompt contract test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_pipeline.py::test_pact_prompt_requires_dream_grounded_card -q
+```
+
+Expected: PASS.
+
+## Task 3: Hide Developer Settings From Ordinary Users
+
+**Files:**
+- Modify: `tests/test_ui_actions.py`
+- Modify: `dream_customs/ui/app.py`
+- Modify: `dream_customs/ui/styles.py`
+
+- [x] **Step 1: Add UI source regression test**
+
+Add a test that inspects `dream_customs.ui.app` source and asserts `Runtime settings` accordion is created with `open=False`.
+
+- [x] **Step 2: Run focused failing test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_ui_actions.py::test_runtime_settings_are_collapsed_for_public_flow -q
+```
+
+Expected: FAIL while the accordion is still `open=True`.
+
+- [x] **Step 3: Collapse and quiet the developer panel**
+
+Change `with gr.Accordion("Runtime settings", open=True, elem_classes=["dc-dev"]):` to `open=False`, and update CSS so collapsed runtime settings look like a quiet secondary control rather than the next stage of the user flow.
+
+- [x] **Step 4: Run focused UI test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_ui_actions.py::test_runtime_settings_are_collapsed_for_public_flow -q
+```
+
+Expected: PASS.
+
+## Task 4: Add Story-Aware Processing Copy
+
+**Files:**
+- Modify: `tests/test_ui_actions.py`
+- Modify: `dream_customs/ui/copy.py`
+- Modify: `dream_customs/ui/app.py`
+- Modify: `dream_customs/ui/styles.py`
+
+- [x] **Step 1: Add copy regression test**
+
+Add a test that imports `PROCESSING_NOTE` and asserts it mentions the clerk/model route without using secret/backend jargon such as `token`, `endpoint`, or `debug`.
+
+- [x] **Step 2: Run focused failing test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_ui_actions.py::test_processing_note_is_story_copy_not_backend_jargon -q
+```
+
+Expected: FAIL until `PROCESSING_NOTE` exists.
+
+- [x] **Step 3: Add and render processing note**
+
+Add `PROCESSING_NOTE` to `dream_customs/ui/copy.py` and render it near the submit buttons in `dream_customs/ui/app.py`.
+
+Recommended copy:
+
+```text
+When you file a dream, the clerk reads the fragment and drafts a pass. Model-backed routes may take a few seconds; text-only fallback stays ready.
+```
+
+- [x] **Step 4: Style processing note**
+
+Add `.dc-processing-note` styles in `dream_customs/ui/styles.py` with small, readable text and no layout shift on mobile.
+
+- [x] **Step 5: Run focused copy test**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_ui_actions.py::test_processing_note_is_story_copy_not_backend_jargon -q
+```
+
+Expected: PASS.
+
+## Task 5: Full Verification And Deployment
+
+**Files:**
+- Verify: all modified files
+
+- [x] **Step 1: Run full test suite**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all tests pass.
+
+- [x] **Step 2: Run whitespace check**
+
+Run:
+
+```bash
+git diff --check
+```
+
+Expected: no output.
+
+- [x] **Step 3: Run local Gradio smoke**
+
+Run:
+
+```bash
+GRADIO_SERVER_PORT=7862 .venv/bin/python app.py
+```
+
+Open `http://127.0.0.1:7862`, submit the customs-window wet-paper dream, skip optional question, and verify:
+
+- runtime settings are collapsed by default;
+- the processing note is visible before submit;
+- the final pass references wet paper/customs/unfinished promises;
+- mobile width has no obvious overflow.
+
+- [ ] **Step 4: Commit and push GitHub branch**
+
+Run:
+
+```bash
+git add docs/superpowers/plans/2026-06-08-dream-customs-story-ux-polish.md dream_customs/pipeline.py dream_customs/prompts.py dream_customs/ui/app.py dream_customs/ui/copy.py dream_customs/ui/styles.py tests/test_pipeline.py tests/test_ui_actions.py
+git commit -m "fix: ground dream customs story flow"
+git push origin feature/dream-customs-ui-voice-settings
+```
+
+- [ ] **Step 5: Sync Hugging Face Space and verify live app**
+
+Push or create a Space PR to `space/main` according to the current auth state. Then verify the live Space `/config` and public app page show the updated runtime settings behavior and pass generation flow.
+
+Stop and report if HF auth, forced public `main` overwrite, or PR merge permissions block completion.

dream_customs/pipeline.py

@@ -45,6 +45,114 @@ def _stamp_card_for_today(card: PactCard) -> PactCard:
     return stamped
 
 
+_ANCHOR_STOPWORDS = {
+    "about",
+    "after",
+    "again",
+    "asked",
+    "before",
+    "behind",
+    "being",
+    "carrying",
+    "declare",
+    "dream",
+    "dreamed",
+    "dreamt",
+    "every",
+    "feeling",
+    "fragment",
+    "from",
+    "full",
+    "into",
+    "last",
+    "left",
+    "night",
+    "paper",
+    "promise",
+    "through",
+    "today",
+    "window",
+    "with",
+}
+
+
+def _dedupe_preserve_order(items: List[str]) -> List[str]:
+    seen = set()
+    result: List[str] = []
+    for item in items:
+        clean = re.sub(r"\s+", " ", item.strip(" .,:;!?\"'()[]{}")).lower()
+        if clean and clean not in seen:
+            result.append(clean)
+            seen.add(clean)
+    return result
+
+
+def _extract_dream_anchors(intake: DreamIntake) -> List[str]:
+    text = " ".join(
+        [
+            intake.dream_text,
+            intake.voice_transcript,
+            " ".join(intake.visual_clues),
+            " ".join(intake.recurring_symbols),
+        ]
+    ).lower()
+    candidates: List[str] = []
+    pair_pattern = re.compile(
+        r"\b([a-z][a-z'-]+)\s+("
+        r"paper|papers|promise|promises|window|windows|suitcase|suitcases|"
+        r"clerk|clerks|sunrise|elevator|elevators|button|buttons|hallway|"
+        r"gate|gates|floor|floors|stamp|stamps|number|numbers"
+        r")\b"
+    )
+    for match in pair_pattern.finditer(text):
+        modifier, noun = match.groups()
+        phrase = f"{modifier} {noun.rstrip('s')}"
+        if modifier not in _ANCHOR_STOPWORDS:
+            candidates.append(phrase)
+
+    noun_pattern = re.compile(
+        r"\b(customs|suitcase|clerk|sunrise|elevator|button|hallway|gate|stamp|number|floor)\b"
+    )
+    candidates.extend(match.group(1) for match in noun_pattern.finditer(text))
+    candidates.extend(clue.lower() for clue in intake.visual_clues if clue.strip())
+
+    return _dedupe_preserve_order(candidates)[:3]
+
+
+def _primary_anchor(intake: DreamIntake) -> str:
+    anchors = _extract_dream_anchors(intake)
+    return anchors[0] if anchors else "night visitor"
+
+
+def _secondary_anchor(intake: DreamIntake) -> str:
+    anchors = _extract_dream_anchors(intake)
+    return anchors[1] if len(anchors) > 1 else _primary_anchor(intake)
+
+
+def _title_anchor(text: str) -> str:
+    return " ".join(part.capitalize() for part in text.split())
+
+
+def _text_uses_anchor(text: str, anchors: List[str]) -> bool:
+    clean = (text or "").lower()
+    return any(anchor in clean for anchor in anchors)
+
+
+def _is_generic_visitor_name(text: str, intake: DreamIntake) -> bool:
+    clean = (text or "").strip()
+    if not clean:
+        return True
+    lowered = clean.lower()
+    merged = intake.merged_text().lower()
+    generic_names = {"dreamer", "night visitor", "elena", "visitor", "the visitor"}
+    if lowered in generic_names:
+        return True
+    anchors = _extract_dream_anchors(intake)
+    if anchors and not _text_uses_anchor(lowered, anchors) and lowered not in merged and len(clean.split()) <= 2:
+        return True
+    return False
+
+
 def _looks_unclear_or_dream_literal(text: str) -> bool:
     clean = (text or "").strip()
     if len(clean) < 12:
@@ -72,6 +180,41 @@ def _looks_unclear_or_dream_literal(text: str) -> bool:
     return any(term in clean for term in dream_literals)
 
 
+def _is_generic_daily_tip(text: str, anchors: List[str]) -> bool:
+    clean = (text or "").lower()
+    generic_markers = [
+        "hydrate",
+        "dehydration",
+        "piece of fruit",
+        "cognitive function",
+        "morning routine",
+        "take a short walk",
+        "eat something",
+        "drink water",
+    ]
+    return any(marker in clean for marker in generic_markers) and not _text_uses_anchor(clean, anchors)
+
+
+def _is_generic_weird_task(text: str, anchors: List[str]) -> bool:
+    clean = (text or "").lower()
+    generic_markers = [
+        "count the number of birds",
+        "requires no special skills",
+        "harmless and playful activity",
+        "salute the kettle",
+    ]
+    return any(marker in clean for marker in generic_markers) and not _text_uses_anchor(clean, anchors)
+
+
+def _is_bare_time_or_generic_release(text: str) -> bool:
+    clean = (text or "").strip()
+    if re.fullmatch(r"\d{1,2}:\d{2}\s*(?:am|pm|AM|PM)?", clean):
+        return True
+    if len(clean.split()) <= 3:
+        return True
+    return False
+
+
 def _safe_practical_suggestion(intake: DreamIntake) -> str:
     mood = intake.mood.strip().lower()
     if mood in {"uneasy", "foggy", "tired", "焦虑", "迷雾", "累"}:
@@ -86,27 +229,96 @@ def _safe_weird_task(intake: DreamIntake) -> str:
     return "Write your smallest task on paper, draw a tiny clearance stamp beside it, and work on it for just five minutes."
 
 
+def _grounded_practical_suggestion(intake: DreamIntake) -> str:
+    primary = _primary_anchor(intake)
+    secondary = _secondary_anchor(intake)
+    if "promise" in primary or "promise" in secondary:
+        return (
+            "Choose one unfinished promise and shrink it into a first step small enough to finish in "
+            "10 minutes."
+        )
+    return (
+        f"Pick one real task that feels like the {primary}, then define only its first step for the next 10 minutes."
+    )
+
+
+def _grounded_weird_task(intake: DreamIntake) -> str:
+    primary = _primary_anchor(intake)
+    secondary = _secondary_anchor(intake)
+    if "paper" in primary or "paper" in secondary:
+        return "Write one unfinished promise on a scrap of paper, fold it like a tiny suitcase, and stamp it cleared."
+    if "customs" in primary or "customs" in secondary:
+        return "Make a one-line customs form for today's smallest task and mark it cleared after five minutes."
+    return f"Draw the {primary} as a tiny customs stamp, press it once, and work for five minutes."
+
+
+def _grounded_bedtime_release(intake: DreamIntake) -> str:
+    primary = _primary_anchor(intake)
+    secondary = _secondary_anchor(intake)
+    return f"Tonight, the {primary} and the {secondary} are logged, cleared, and allowed to rest until morning."
+
+
+def _grounded_alliance_reading(intake: DreamIntake) -> str:
+    primary = _primary_anchor(intake)
+    secondary = _secondary_anchor(intake)
+    return (
+        f"You can treat the {primary} and the {secondary} as last night's way of asking for one promise "
+        "to become smaller and easier to carry today."
+    )
+
+
+def _grounded_question(intake: DreamIntake, question: str) -> str:
+    anchors = _extract_dream_anchors(intake)
+    if not anchors or _text_uses_anchor(question, anchors):
+        return question
+    primary = _primary_anchor(intake)
+    secondary = _secondary_anchor(intake)
+    return (
+        f"When you picture the {primary} and the {secondary}, what is one real-life promise "
+        "or task you want to make easier today?"
+    )
+
+
+def _grounded_followup_question(intake: DreamIntake) -> str:
+    primary = _primary_anchor(intake)
+    return f"If the {primary} could hand you one smaller first step for today, what would that step be?"
+
+
 def _polish_card_for_daily_use(card: PactCard, intake: DreamIntake, answers: str) -> PactCard:
     polished = card.model_copy(deep=True)
     merged = "\n".join([intake.merged_text(), answers or ""])
-    if not polished.visitor_name.strip() or polished.visitor_name.strip().lower() == "dreamer":
-        polished.visitor_name = "Night Visitor"
+    anchors = _extract_dream_anchors(intake)
+    if _is_generic_visitor_name(polished.visitor_name, intake):
+        polished.visitor_name = _title_anchor(_primary_anchor(intake))
 
     if _looks_unclear_or_dream_literal(polished.practical_suggestion):
         polished.practical_suggestion = _safe_practical_suggestion(intake)
+    elif _is_generic_daily_tip(polished.practical_suggestion, anchors):
+        polished.practical_suggestion = _grounded_practical_suggestion(intake)
+    elif anchors and not _text_uses_anchor(polished.practical_suggestion, anchors):
+        polished.practical_suggestion = _grounded_practical_suggestion(intake)
 
     if _looks_unclear_or_dream_literal(polished.weird_task) and polished.weird_task.strip() == polished.practical_suggestion.strip():
         polished.weird_task = _safe_weird_task(intake)
     elif len((polished.weird_task or "").strip()) < 8:
         polished.weird_task = _safe_weird_task(intake)
-
-    if len((polished.alliance_reading or "").strip()) < 12 or "联盟成员" in polished.alliance_reading:
-        polished.alliance_reading = (
-            "You can treat this as a small signal from last night's feelings, not a prophecy. "
-            "Today, protect a realistic pace."
-        )
+    elif _is_generic_weird_task(polished.weird_task, anchors):
+        polished.weird_task = _grounded_weird_task(intake)
+    elif anchors and not _text_uses_anchor(polished.weird_task, anchors):
+        polished.weird_task = _grounded_weird_task(intake)
+
+    if (
+        len((polished.alliance_reading or "").strip()) < 12
+        or "联盟成员" in polished.alliance_reading
+        or (anchors and not _text_uses_anchor(polished.alliance_reading, anchors))
+    ):
+        polished.alliance_reading = _grounded_alliance_reading(intake)
     if polished.risk_level.strip() in {"低", "中", "高", "low", "medium", "high"}:
         polished.risk_level = "medium: handle gently, without treating it as a warning sign"
+    if _is_bare_time_or_generic_release(polished.bedtime_release) or (
+        anchors and not _text_uses_anchor(polished.bedtime_release, anchors)
+    ):
+        polished.bedtime_release = _grounded_bedtime_release(intake)
 
     if not needs_escalation(merged):
         polished.safety_note = ""
@@ -318,6 +530,17 @@ def ask_questions(session: CustomsSession, text_client, force_another: bool = Fa
         fresh_questions = ["If today only needs one smaller first step, what should that step be?"]
     if not fresh_questions:
         fresh_questions = questions[:3]
+    if fresh_questions:
+        fresh_questions = [_grounded_question(next_session.intake, fresh_questions[0])] + fresh_questions[1:]
+    seen_questions = set(next_session.question_history)
+    deduped_questions: List[str] = []
+    for question in fresh_questions:
+        if question and question not in seen_questions:
+            deduped_questions.append(question)
+            seen_questions.add(question)
+    if force_another and not deduped_questions:
+        deduped_questions = [_grounded_followup_question(next_session.intake)]
+    fresh_questions = deduped_questions
 
     next_session.question_history.extend(fresh_questions[:3])
     next_session.phase = "negotiating"

dream_customs/prompts.py

@@ -18,6 +18,9 @@ The tone should be gentle, plain, and specific. Do not make medical claims.
 Ask questions that an ordinary person can understand without knowing the app lore.
 Prefer questions about today's mood, one small real-life concern, or one safe action.
 Do not ask vague symbolic questions such as what a stamp wants to release.
+Ground every question in a concrete detail from the intake when possible, such as an object,
+place, action, color, or phrase the user actually provided.
+Do not invent a human name unless the user mentioned a person.
 
 Dream intake:
 {intake.merged_text()}
@@ -36,6 +39,8 @@ Do not diagnose. Do not repeat previous questions.
 The question must be plain and useful: ask what the user wants to make easier today,
 or whether there is one realistic thing they want help starting.
 Do not use unclear metaphors about stamps, release, fate, symbols, or hidden meanings.
+Reuse one concrete dream detail from the intake so the user can feel the question belongs
+to this dream rather than to a generic reflection form.
 
 Dream intake:
 {intake.merged_text()}
@@ -59,11 +64,16 @@ You are the Dream Customs diplomat. Generate a final Today's Pact card.
 Do not diagnose. Do not claim the dream has one certain meaning.
 The card must be useful for the user's real day, not only poetic.
 Give:
-- practical_suggestion: one safe, concrete life tip for today, such as hydration, eating, writing one task down, taking a short walk, reducing one task, checking the calendar, or asking for help. It must not be mystical or dream-literal.
-- weird_task: one harmless, playful, slightly odd thing doable in 5 minutes. It can be imaginative, but it must be understandable.
+- visitor_name: a short object/event phrase from the dream, not a human name unless a person appears.
+- alliance_reading: reuse at least two concrete dream details from the intake and say what the dream may be trying to protect today.
+- practical_suggestion: one safe, concrete next step for today. Tie it to the user's dream details or answers. avoid generic wellness filler such as hydration, fruit, exercise, or sleep hygiene unless the user explicitly asked for that.
+- weird_task: one harmless, playful, slightly odd thing doable in 5 minutes. It must reuse at least one concrete dream detail and be understandable.
+- bedtime_release: bedtime_release must be a sentence-length release phrase, not a time, schedule, diagnosis, or command.
 - safety_note: empty string unless the user mentions self-harm, harming others, severe distress, severe insomnia, panic, or inability to function.
 Use warm, non-clinical language.
-Avoid generic names like "Dreamer"; name the dream visitor with a short, vivid phrase.
+Avoid generic names like "Dreamer"; name the dream visitor with a short, vivid phrase from the user's own dream.
+The final card must reuse at least two concrete dream details across visitor_name,
+alliance_reading, practical_suggestion, weird_task, and bedtime_release.
 Write the final card in polished English for an English-language demo, even if the dream fragment contains another language.
 
 Dream intake:
@@ -85,6 +95,10 @@ Keep the same dream visitor unless the user's new material clearly changes it.
 Do not diagnose. Do not make the dream sound certain or frightening.
 Keep practical_suggestion safe, concrete, and useful for daily life.
 Keep weird_task playful but understandable and separate from the practical suggestion.
+The revised card must reuse at least two concrete dream details from the intake.
+visitor_name should be an object or event from the dream, not a human name unless a person appears.
+bedtime_release must be a sentence, not a time or schedule.
+Avoid generic wellness filler unless the user explicitly requested it.
 Use safety_note only for severe distress or safety risk; otherwise return an empty string.
 Write the revised card in polished English for an English-language demo, even if the dream fragment contains another language.
 

dream_customs/ui/app.py

@@ -35,6 +35,7 @@ from dream_customs.ui.copy import (
     EXAMPLE_MOOD,
     DEFAULT_MOOD,
     MOOD_OPTIONS,
+    PROCESSING_NOTE,
 )
 from dream_customs.ui.styles import CSS
 
@@ -371,6 +372,7 @@ def build_demo() -> gr.Blocks:
                         with gr.Row(elem_classes=["dc-submit-row"]):
                             example_button = gr.Button("Try the sample  →", variant="secondary")
                             submit_button = gr.Button("Issue today's pass  →", variant="primary")
+                        gr.HTML(f"<p class='dc-processing-note'>{escape(PROCESSING_NOTE)}</p>")
                         with gr.Accordion("Additional material", open=False, elem_classes=["dc-attachment-drawer"]):
                             image_input = gr.Image(label="Image clue", type="filepath", height=160)
 
@@ -420,7 +422,7 @@ def build_demo() -> gr.Blocks:
 </div>
 """.strip()
                     )
-                    with gr.Accordion("Runtime settings", open=True, elem_classes=["dc-dev"]):
+                    with gr.Accordion("Runtime settings", open=False, elem_classes=["dc-dev"]):
                         gr.HTML(
                             """
 <div class="dc-dev-help">

dream_customs/ui/copy.py

@@ -1,5 +1,9 @@
 APP_TITLE = "Dream Customs"
 APP_SUBTITLE = "Turn last night's strange fragment into one gentle clearance pass for today."
+PROCESSING_NOTE = (
+    "When you file a dream, the clerk reads the fragment and drafts a pass. "
+    "Model-backed routes may take a few seconds; text-only fallback stays ready."
+)
 
 DREAM_PLACEHOLDER = "For example: I kept missing an elevator, and the buttons melted like wax."
 ANSWER_PLACEHOLDER = "Add one sentence if it helps, or leave this blank and skip ahead."

dream_customs/ui/styles.py

@@ -591,6 +591,20 @@ button.secondary {
   font-size: 1.05rem !important;
 }
 
+.dc-processing-note {
+  color: var(--dc-muted);
+  font-size: 0.84rem;
+  line-height: 1.45;
+  margin: 12px 2px 0;
+  max-width: 44rem;
+}
+
+.dc-processing-note::before {
+  color: var(--dc-coral-dark);
+  content: "While the stamp dries: ";
+  font-weight: 850;
+}
+
 .dc-attachment-drawer {
   background: rgba(230, 221, 208, 0.52) !important;
   border: 1px solid var(--dc-line) !important;
@@ -810,12 +824,18 @@ a.built-with[href*="gradio.app"] {
 }
 
 .dc-dev {
-  background: rgba(255, 249, 238, 0.7) !important;
-  border: 1px solid rgba(189, 168, 143, 0.58) !important;
+  background: rgba(255, 249, 238, 0.46) !important;
+  border: 1px dashed rgba(189, 168, 143, 0.55) !important;
   border-radius: var(--dc-radius-md) !important;
   box-shadow: none;
   margin-top: 0;
-  padding: 12px !important;
+  padding: 10px !important;
+}
+
+.dc-dev > button {
+  color: rgba(19, 41, 47, 0.74) !important;
+  font-size: 0.84rem !important;
+  min-height: 42px !important;
 }
 
 .dc-dev-help {

tests/test_pipeline.py

@@ -16,6 +16,7 @@ from dream_customs.pipeline import (
     seal_pact,
     skip_question,
 )
+from dream_customs.prompts import pact_prompt
 from dream_customs.schema import PactCard
 
 
@@ -57,6 +58,23 @@ def test_generate_negotiation_returns_questions():
     assert len(negotiation["questions"]) == 3
 
 
+def test_ask_questions_grounds_generic_question_in_dream_detail():
+    session = add_evidence(
+        create_session(),
+        dream_text=(
+            "I dreamed I was at a customs window carrying a suitcase full of wet paper. "
+            "The clerk asked me to declare every unfinished promise before sunrise."
+        ),
+        mood="Uneasy",
+        vision_client=FakeVisionClient(),
+        asr_client=FakeASRClient(),
+    )
+
+    session = ask_questions(session, FakeTextClient())
+
+    assert "customs window" in session.question_history[0].lower() or "wet paper" in session.question_history[0].lower()
+
+
 def test_generate_pact_returns_card_and_html():
     intake = build_intake(dream_text="I missed an elevator.", mood="anxious")
     card, html = generate_pact(intake, "I want a small start.", FakeTextClient())
@@ -95,6 +113,70 @@ def test_generate_pact_polishes_unclear_model_output_into_daily_tip():
     assert "Life tip" in html
 
 
+def test_generate_pact_repairs_generic_hosted_output_with_dream_details():
+    class GenericHostedTextClient:
+        def generate_pact(self, prompt):
+            return PactCard(
+                visitor_name="Elena",
+                permit_id="DC-015",
+                contraband=["unfiled worry", "one stamp asking to be noticed"],
+                risk_level="medium",
+                alliance_reading=(
+                    "You can treat this as a small signal from last night's feelings, not a prophecy. "
+                    "Today, protect a realistic pace."
+                ),
+                practical_suggestion=(
+                    "Hydrate and eat a piece of fruit to support your morning routine, as dehydration "
+                    "can affect cognitive function."
+                ),
+                weird_task=(
+                    "Count the number of birds in the sky before bed, as it is a harmless and playful "
+                    "activity that requires no special skills."
+                ),
+                bedtime_release="7:00 PM",
+                safety_note="",
+            )
+
+    intake = build_intake(
+        dream_text=(
+            "I dreamed I was at a customs window carrying a suitcase full of wet paper. "
+            "The clerk asked me to declare every unfinished promise before sunrise."
+        ),
+        mood="Uneasy",
+    )
+
+    card, html = generate_pact(intake, "", GenericHostedTextClient())
+    joined = "\n".join(
+        [
+            card.visitor_name,
+            card.alliance_reading,
+            card.practical_suggestion,
+            card.weird_task,
+            card.bedtime_release,
+        ]
+    ).lower()
+
+    assert "wet paper" in joined or "unfinished promise" in joined
+    assert "customs window" in card.alliance_reading.lower() or "wet paper" in card.alliance_reading.lower()
+    assert "promise" in card.practical_suggestion.lower() or "first step" in card.practical_suggestion.lower()
+    assert any(anchor in card.weird_task.lower() for anchor in ["paper", "promise", "suitcase", "customs"])
+    assert card.bedtime_release != "7:00 PM"
+    assert "Hydrate and eat a piece of fruit" not in html
+
+
+def test_pact_prompt_requires_dream_grounded_card():
+    intake = build_intake(
+        dream_text="I carried wet paper through a customs window before sunrise.",
+        mood="Uneasy",
+    )
+    prompt = pact_prompt(intake, "I want to keep one promise small today.")
+
+    assert "reuse at least two concrete dream details" in prompt
+    assert "avoid generic wellness filler" in prompt
+    assert "bedtime_release must be a sentence" in prompt
+    assert "not a human name unless a person appears" in prompt
+
+
 def test_add_evidence_updates_session_with_text_image_audio_and_mood():
     session = add_evidence(
         create_session(),

tests/test_ui_actions.py

@@ -1,9 +1,11 @@
 import json
+import inspect
 from datetime import date
 
 from dream_customs.ui.actions import answer_to_card_action, initial_mobile_state, skip_to_card_action, submit_dream_action
+import dream_customs.ui.app as ui_app
 from dream_customs.ui.app import _reset
-from dream_customs.ui.copy import DEFAULT_MOOD
+from dream_customs.ui.copy import DEFAULT_MOOD, PROCESSING_NOTE
 
 
 def test_mobile_defaults_to_model_backends():
@@ -14,6 +16,22 @@ def test_mobile_defaults_to_model_backends():
     assert view["debug"]["vision_backend"] == "model"
 
 
+def test_runtime_settings_are_collapsed_for_public_flow():
+    source = inspect.getsource(ui_app.build_demo)
+
+    assert 'gr.Accordion("Runtime settings", open=False' in source
+
+
+def test_processing_note_is_story_copy_not_backend_jargon():
+    lowered = PROCESSING_NOTE.lower()
+
+    assert "clerk" in lowered
+    assert "model" in lowered
+    assert "token" not in lowered
+    assert "endpoint" not in lowered
+    assert "debug" not in lowered
+
+
 def test_mobile_reset_restores_calm_mood():
     settings_values = [
         "",