docs: align dream qa requirements

.gitattributes

@@ -33,3 +33,6 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png filter=lfs diff=lfs merge=lfs -text
+docs/prototypes/2026-06-08-dream-qa-mobile-flow.png filter=lfs diff=lfs merge=lfs -text
+docs/prototypes/2026-06-08-dream-qa-tips-card.png filter=lfs diff=lfs merge=lfs -text

AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md - Dream Customs / 梦境海关
+# AGENTS.md - Dream QA / 梦境问答台
 
 ## 语言规则
 
@@ -7,9 +7,10 @@
 
 ## 项目定位
 
-- 当前项目是 Build Small Hackathon 的 `Dream Customs / 梦境海关`。
-- 核心定位：帮用户和昨晚的梦结盟，把不安转成第二天的小建议，把怪梦转成一件有趣的小事。
-- 这不是心理诊断、医疗建议或治疗工具。
+- 当前项目是 Build Small Hackathon 的 `Dream QA / 梦境问答台`，代码仓库和 Space 仍沿用 `Dream Customs` 名称以保持部署连续性。
+- 核心定位：做一个循序渐进的解梦 Gradio app，帮助用户一步步说清梦境、表达疑惑、回答追问，最后得到一个温和的 `今日小 Tips`。
+- `今日小 Tips` 可以是一个认真建议、一个用户未尝试过的小事，或一句关心用户的短句；它必须引用梦里的具体细节，不能变成泛泛鸡汤。
+- 这不是心理诊断、医疗建议、治疗工具、占卜工具或宿命论解释器。
 
 ## 竞赛约束
 
@@ -17,13 +18,13 @@
 - 模型总参数必须 <= 32B。
 - 优先叙事赛道：An Adventure in Thousand Token Wood。
 - 次级叙事：Backyard AI，因为项目来自真实睡眠/做梦困扰。
-- demo 必须能在短视频中快速展示：输入梦境，获得今日盟约卡。
+- demo 必须能在短视频中快速展示：输入梦境，回答或跳过追问，获得今日小 Tips。
 
 ## 模型规则
 
 - 首选模型组合：
   - `openbmb/MiniCPM-V-4.6`：图片、草图、便签、截图理解。
-  - `openbmb/MiniCPM5-1B`：文本推理、梦境外交官人格、结构化输出和建议生成。
+  - `openbmb/MiniCPM5-1B`：文本推理、追问生成、梦境解读草稿、结构化今日 Tips。
 - 不要在 MiniCPM 路线未验证前扩展到任意其他小模型。
 - 语音输入需要 ASR 适配器；ASR 只做转写，不承担梦境理解。
 - 首版不要实现语音输出，避免扩大部署风险。
@@ -33,23 +34,32 @@
 - 必须支持文字输入。
 - 应支持图片输入，用 MiniCPM-V-4.6 提取视觉线索。
 - 应支持语音输入，通过小 ASR 适配器转成文本。
-- 所有输入统一进入 `DreamIntake`，不要做成三套割裂产品。
+- 所有输入统一进入同一个梦境 intake，不要做成三套割裂产品。
+- 用户流程必须是渐进式的：
+  1. 记录梦境。
+  2. 明确用户最想理解的问题。
+  3. 生成 1-3 个温和追问。
+  4. 用户回答、跳过或请求换个角度。
+  5. 生成梦境解读草稿。
+  6. 输出一个今日小 Tips。
 - 输出必须包含：
-  - dream visitor / 梦境来访者
-  - permit id / 入境编号
-  - contraband / 携带情绪违禁品
-  - risk level / 风险等级
-  - alliance reading / 结盟解读
-  - practical suggestion / 今日认真建议
-  - weird task / 5 分钟怪趣任务
-  - bedtime release / 睡前放行仪式
-  - safety note / 必要时的安全提示
+  - `dream_summary` / 梦境摘要
+  - `main_question` / 用户最想理解的问题
+  - `dream_anchors` / 梦境具体线索
+  - `followup_questions` / 追问
+  - `user_answers` / 用户回答或跳过记录
+  - `interpretation` / 非确定性的解读草稿
+  - `today_tip` / 今日小 Tips
+  - `tiny_action` / 可选的小行动
+  - `caring_note` / 可选的关心语句
+  - `safety_note` / 必要时的安全提示
 
 ## 安全规则
 
 - 不做心理疾病诊断。
 - 不声称梦境有唯一含义。
 - 不输出恐吓性、宿命论、神秘绝对化内容。
+- 不把梦解释成“预兆”“证明”“创伤证据”或医学结论。
 - 普通输出使用“也许”“可以把它当作”“今天先试试”这类非确定措辞。
 - 如果用户表达自伤、伤人、长期严重失眠、无法正常生活或极强痛苦，必须显示寻求可信任的人或专业支持的提示。
 
@@ -57,11 +67,15 @@
 
 实现前先阅读：
 
-1. `docs/spec.md`
-2. `docs/prd.md`
-3. `docs/handoff.md`
-4. `docs/superpowers/plans/2026-06-05-dream-customs-mvp.md`
-5. `docs/dream-customs-concept/index.html`
+1. `docs/handoff.md`
+2. `docs/spec.md`
+3. `docs/prd.md`
+4. `PRODUCT.md`
+5. `DESIGN.md`
+6. `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md`
+7. `docs/superpowers/plans/2026-06-08-dream-qa-refactor-doc-plan.md`
+
+旧的 pact/customs 计划、smoke 和概念页是历史记录。除非用户明确要求复盘历史，否则不要再把 permit、contraband、sealed pact 当作新实现目标。
 
 ## 开发流程
 
@@ -82,6 +96,7 @@
 - JSON 解析失败时必须有修复或降级路径。
 - Text-only path 必须永远可用，作为 demo fallback。
 - Gradio 页面应优先移动端可用，因为用户可能在手机上记录梦。
+- 今日 Tips 必须有梦境锚点，不能是“多休息、多喝水、保持积极”这类脱离梦境的通用话。
 
 ## 验收命令
 
@@ -94,8 +109,11 @@ python app.py
 
 人工验收：
 
-- 输入一段文字梦境，能生成盟约卡。
-- 上传一张草图或便签，视觉线索进入 `DreamIntake`。
+- 输入一段文字梦境后，app 能提出至少一个相关追问。
+- 用户可以回答追问，也可以跳过。
+- 上传一张草图或便签后，视觉线索进入同一个 intake。
 - 上传/录制语音后，有转写或清晰降级提示。
-- 输出不包含诊断、恐吓或医疗化建议。
+- 最终输出包含梦境摘要、解读草稿和一个今日小 Tips。
+- 今日小 Tips 引用至少一个具体梦境细节。
+- 输出不包含诊断、恐吓、预言或医疗化建议。
 - 页面在手机宽度下可读。

DESIGN.md

@@ -1,32 +1,31 @@
 ---
-name: Dream Customs
-description: A nocturnal dream customs workbench for turning dream evidence into a next-day pact.
+name: Dream QA
+description: A guided dream Q&A interface for turning dream fragments into one grounded today tip.
 colors:
-  bg-night: "oklch(0.185 0.018 55)"
-  bg-void: "oklch(0.130 0.012 55)"
-  surface-ink: "oklch(0.235 0.018 58)"
-  surface-raised: "oklch(0.295 0.020 62)"
-  primary-sage: "oklch(0.690 0.105 150)"
-  primary-sage-deep: "oklch(0.455 0.090 155)"
-  accent-coral-stamp: "oklch(0.700 0.140 32)"
-  accent-amber-lamp: "oklch(0.830 0.120 76)"
-  accent-aurora: "oklch(0.745 0.080 185)"
-  ink-main: "oklch(0.960 0.010 78)"
-  ink-muted: "oklch(0.760 0.018 78)"
-  border-dream: "oklch(0.465 0.024 70)"
+  morning-mist: "oklch(0.965 0.014 210)"
+  warm-paper: "oklch(0.985 0.010 82)"
+  soft-ink: "oklch(0.205 0.020 70)"
+  muted-ink: "oklch(0.500 0.030 82)"
+  surface-card: "oklch(0.995 0.006 82)"
+  surface-sage: "oklch(0.930 0.035 145)"
+  primary-sage: "oklch(0.555 0.105 145)"
+  primary-sage-deep: "oklch(0.390 0.095 145)"
+  accent-amber: "oklch(0.820 0.120 78)"
+  accent-coral: "oklch(0.710 0.135 32)"
+  border-soft: "oklch(0.825 0.020 85)"
   warning: "oklch(0.760 0.150 75)"
 typography:
   display:
     fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
-    fontSize: "2.25rem"
+    fontSize: "2rem"
     fontWeight: 760
-    lineHeight: 1.05
+    lineHeight: 1.08
     letterSpacing: "0"
   headline:
     fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
-    fontSize: "1.5rem"
+    fontSize: "1.375rem"
     fontWeight: 720
-    lineHeight: 1.18
+    lineHeight: 1.2
   title:
     fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, Segoe UI, sans-serif"
     fontSize: "1rem"
@@ -44,8 +43,8 @@ typography:
     lineHeight: 1.25
 rounded:
   sm: "6px"
-  md: "10px"
-  lg: "14px"
+  md: "8px"
+  lg: "12px"
   pill: "999px"
 spacing:
   xs: "6px"
@@ -56,101 +55,96 @@ spacing:
 components:
   button-primary:
     backgroundColor: "{colors.primary-sage-deep}"
-    textColor: "{colors.ink-main}"
+    textColor: "{colors.warm-paper}"
     rounded: "{rounded.md}"
     padding: "12px 16px"
-  button-accent:
-    backgroundColor: "{colors.accent-coral-stamp}"
-    textColor: "{colors.bg-void}"
+  button-secondary:
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.primary-sage-deep}"
     rounded: "{rounded.md}"
     padding: "12px 16px"
   input-composer:
-    backgroundColor: "{colors.surface-ink}"
-    textColor: "{colors.ink-main}"
+    backgroundColor: "{colors.surface-card}"
+    textColor: "{colors.soft-ink}"
     rounded: "{rounded.lg}"
     padding: "14px 16px"
 ---
 
-# Design System: Dream Customs
+# Design System: Dream QA
 
 ## 1. Overview
 
-**Creative North Star: "The Morning Customs Desk"**
+**Creative North Star: "The Morning Question Desk"**
 
-Dream Customs should feel like a small warm customs desk that appears after waking: quiet, slightly strange, and easy enough to use before the day fully starts. The surface can stay dark like Codex, but it should read as warm charcoal and lamplight rather than a cold technical dashboard. Sage action color, amber light, muted coral seal ink, and a little aurora evidence color carry the identity.
+Dream QA should feel like a calm morning workspace for unpacking a dream while it is still fresh. The surface is light, readable, and ordinary-user friendly, with enough dream atmosphere to feel memorable. The interface is a product experience first: the user needs to record, answer, skip, add detail, and receive one today tip without decoding a metaphor-heavy ritual.
 
-This is product UI first. The user needs to type, attach, optionally add voice, answer, and decide what happens next. The dream atmosphere belongs in the background wash, pact inspector, stamps, and evidence chips, while controls stay clear and predictable.
-
-**V4 Unified Composer Rule.** The dream input should behave like a Codex-style multimodal composer, not like a Gradio form. Text, image upload, voice upload, mood, add-material, and send belong visually inside one rounded input surface. Technical model routes and advanced workflow shortcuts should be collapsed by default.
+The old customs/pact visual language is deprecated for new work. A small `Dream Customs` label may remain for repo/Space continuity, but the primary visible experience should be `梦境问答台 / Dream QA`.
 
 **Key Characteristics:**
 
-- Unified composer as the primary input, modeled after Codex app behavior.
-- Conversation timeline for declarations, questions, and pact drafts.
-- Evidence tray for text, image, audio, mood, and model status.
-- Pact inspector that can be drafted, revised, or sealed.
-- Generated bitmap art as atmospheric header and state art, never as unreadable UI chrome.
+- Stepper with four phases: Record, Ask, Interpret, Tip.
+- Conversation timeline for dream fragments, follow-up questions, answers, and interpretation draft.
+- Unified multimodal composer for text, image, voice, mood, and primary action.
+- Right-side desktop panel for interpretation draft and Today Tip preview.
+- Mobile final screen that prioritizes the Today Tip before optional explanation.
 
 ## 2. Colors
 
-The palette is nocturnal and atmospheric: neutral dark surfaces, cobalt primary actions, aurora hints, and coral stamp moments.
+The palette is soft morning product UI: warm white surfaces, charcoal text, sage actions, amber note highlights, and coral used sparingly for warmth or safety.
 
 ### Primary
 
-- **Sage Gate** (`oklch(0.690 0.105 150)`): primary selection, active step, focus accents, and subtle interactive outlines.
-- **Deep Sage Gate** (`oklch(0.455 0.090 155)`): filled primary buttons and selected composer controls with near-white text.
+- **Sage Guide** (`oklch(0.555 0.105 145)`): stepper progress, selected chips, focus accents.
+- **Deep Sage Guide** (`oklch(0.390 0.095 145)`): primary buttons and active controls.
 
 ### Secondary
 
-- **Coral Stamp Ink** (`oklch(0.700 0.140 32)`): final seal action, permit stamp, alert edge for safety notes, and one memorable highlight per screen.
-- **Amber Lamp** (`oklch(0.830 0.120 76)`): warmth, trust cue, and section highlights.
-- **Aurora Evidence Light** (`oklch(0.745 0.080 185)`): image/audio evidence status, successful extraction, and soft dream-glow details.
+- **Amber Note** (`oklch(0.820 0.120 78)`): follow-up question highlight, Today Tip accent, gentle attention.
+- **Coral Care** (`oklch(0.710 0.135 32)`): caring note, safety edge, and one small emotional highlight per result.
 
 ### Neutral
 
-- **Warm Night Background** (`oklch(0.185 0.018 55)`): app body and mobile shell.
-- **Soft Void Rail** (`oklch(0.130 0.012 55)`): app outer edge, header underlay, and screenshot-safe negative space.
-- **Charcoal Ink Surface** (`oklch(0.235 0.018 58)`): composer, timeline items, and tool panels.
-- **Raised Warm Surface** (`oklch(0.295 0.020 62)`): active inspector panels and output cards.
-- **Main Ink** (`oklch(0.960 0.010 78)`): body text on dark surfaces.
-- **Muted Ink** (`oklch(0.760 0.018 78)`): secondary labels that still remain readable.
+- **Morning Mist** (`oklch(0.965 0.014 210)`): app background.
+- **Warm Paper** (`oklch(0.985 0.010 82)`): main reading surface.
+- **Soft Ink** (`oklch(0.205 0.020 70)`): primary text.
+- **Muted Ink** (`oklch(0.500 0.030 82)`): secondary labels with readable contrast.
+- **Soft Border** (`oklch(0.825 0.020 85)`): panel and input borders.
 
 ### Named Rules
 
-**The Stamp Rarity Rule.** Coral is used for sealing, warnings, and permit marks only. It must not become a general decoration color.
+**The One Tip Rule.** Visual emphasis should guide the eye to one primary Today Tip. Do not create multiple equally loud recommendation blocks.
 
-**The No Parchment Rule.** Do not return to cream, beige, or faux paper backgrounds. Dream color comes from night, ink, and evidence light.
+**The No Oracle Rule.** Avoid tarot, prophecy, mystic symbols, parchment certificates, and theatrical stamps.
 
 ## 3. Typography
 
-**Display Font:** Inter with system fallbacks
+**Display Font:** Inter with system fallbacks.
 
-**Body Font:** Inter with system fallbacks
-**Label/Mono Font:** Use system mono only for permit IDs, debug JSON, and model telemetry.
+**Body Font:** Inter with system fallbacks.
 
-**Character:** The interface uses one sans family so the product feels controlled. Personality comes from naming, layout, stamps, and generated imagery rather than decorative fonts.
+**Label/Mono Font:** Use system mono only for debug JSON, model telemetry, or structured IDs.
 
 ### Hierarchy
 
-- **Display** (760, 2.25rem, 1.05): app title and sealed pact headline only.
-- **Headline** (720, 1.5rem, 1.18): step titles and pact section names.
-- **Title** (680, 1rem, 1.3): timeline item headers, buttons, inspector labels.
-- **Body** (450, 1rem, 1.55): dream text, questions, pact explanations, max 70ch for prose.
-- **Label** (650, 0.8125rem, 1.25): compact field labels, evidence chips, status text.
+- **Display** (760, 2rem, 1.08): app title and final Today Tip headline.
+- **Headline** (720, 1.375rem, 1.2): step titles and result section names.
+- **Title** (680, 1rem, 1.3): timeline item headers, buttons, and compact panel labels.
+- **Body** (450, 1rem, 1.55): dream text, questions, interpretations, max 70ch for prose.
+- **Label** (650, 0.8125rem, 1.25): chips, status text, and small metadata.
 
 ### Named Rules
 
-**The Low-Light Readability Rule.** Muted text must remain legible on dark surfaces. Never use low-contrast gray for field labels or placeholders.
+**The Morning Readability Rule.** The user may be half-awake. Body text, buttons, placeholders, and chips must stay readable on mobile.
 
 ## 4. Elevation
 
-Depth is mostly tonal, not shadow-heavy. The app should feel layered like a dark desk under soft light, not like floating cards on a SaaS page. Shadows appear only for the active composer, a hovered evidence item, or a sealed pact.
+Depth is subtle and functional. Panels should feel placed on a calm desk, not floating in a SaaS layout.
 
 ### Shadow Vocabulary
 
-- **composer-focus** (`0 0 0 1px oklch(0.690 0.105 232), 0 12px 32px rgba(0, 0, 0, 0.28)`): focused bottom composer.
-- **pact-lift** (`0 10px 28px rgba(0, 0, 0, 0.24)`): sealed pact card only.
-- **stamp-glow** (`0 0 20px rgba(255, 107, 84, 0.24)`): coral seal hover or success state.
+- **composer-focus** (`0 0 0 1px rgba(65, 115, 78, 0.35), 0 12px 28px rgba(45, 56, 42, 0.14)`): focused composer.
+- **tip-lift** (`0 10px 24px rgba(45, 56, 42, 0.16)`): final Today Tip card only.
+- **question-glow** (`0 0 18px rgba(230, 178, 75, 0.22)`): active follow-up question.
 
 ### Named Rules
 
@@ -160,58 +154,68 @@ Depth is mostly tonal, not shadow-heavy. The app should feel layered like a dark
 
 ### Buttons
 
-- **Shape:** medium rectangle, 10px radius.
-- **Primary:** Deep Cobalt Gate fill, Main Ink text, 12px 16px padding.
-- **Accent:** Coral Stamp Ink for `Seal today's pact` only.
-- **Hover / Focus:** tonal lift plus visible cobalt focus ring.
-- **Secondary:** transparent or Ink Surface fill with full border, never ghost text alone.
+- **Shape:** 8px radius.
+- **Primary:** Deep Sage Guide fill, Warm Paper text, 12px 16px padding.
+- **Secondary:** Warm Paper fill, Deep Sage text, full border.
+- **Care / Safety:** Coral Care only for safety/support actions or caring note markers.
+- **Hover / Focus:** tonal lift plus visible focus ring.
 
 ### Chips
 
 - **Style:** small rounded pills with icon, label, and state dot.
-- **State:** queued, extracted, failed, or selected. Evidence type uses icon and color, not long explanatory text.
+- **Use:** mood, image clue status, voice transcript status, answer/skip choices, and alternate angle request.
+- **Text:** short labels only. Long explanatory text belongs in timeline or result body.
 
 ### Cards / Containers
 
-- **Corner Style:** 10px to 14px. No 32px rounded cards.
-- **Background:** Ink Surface for timeline items, Raised Surface for active inspector.
-- **Shadow Strategy:** flat by default, lifted only when active or sealed.
-- **Border:** full border using Border Dream, not a side stripe.
+- **Corner Style:** 8px to 12px. No oversized rounded blobs.
+- **Background:** Warm Paper or Surface Card.
+- **Shadow Strategy:** flat by default, lifted only when active or final.
+- **Border:** full soft border.
 - **Internal Padding:** 16px mobile, 24px desktop.
 
 ### Inputs / Fields
 
-- **Style:** Codex-like bottom composer with large multiline input, attachment controls, model selector menu, and primary action clustered on the right.
-- **Focus:** cobalt ring, slightly raised surface, no layout shift.
+- **Style:** unified composer with multiline dream input, attachment controls, mood, and primary action.
+- **Focus:** sage ring, slightly raised surface, no layout shift.
 - **Error / Disabled:** inline message below composer, disabled actions stay readable and explain why.
 
 ### Navigation
 
-- **Style:** compact status rail with current phase: Declare, Inspect, Negotiate, Draft, Seal.
-- **Mobile:** phase rail collapses to segmented steps above the composer.
+- **Style:** visible stepper with current phase: Record, Ask, Interpret, Tip.
+- **Mobile:** stepper collapses to compact segmented steps above the conversation.
+- **Desktop:** left rail or top rail is acceptable, but it must map to real states.
+
+### Signature Component: Today Tip Panel
+
+The Today Tip Panel is the final surface. It shows:
 
-### Signature Component: Pact Inspector
+- Dream summary.
+- Main question.
+- Grounded interpretation.
+- One primary Today Tip.
+- Optional tiny action.
+- Optional caring note.
+- Safety note only when needed.
 
-The pact inspector is a live customs file, not just a final HTML card. It shows visitor, permit ID, evidence count, risk, suggested action, weird task, and whether the pact is draft or sealed. It gives the user three choices: add material, ask another question, or seal today's pact.
+The tip should be first-class and easy to screenshot, but it must not look like a diagnosis card or mystical certificate.
 
 ## 6. Do's and Don'ts
 
 ### Do:
 
-- **Do** make the unified composer the most obvious control on mobile and desktop.
-- **Do** keep the first declaration controls above the timeline so a tired user can start immediately.
+- **Do** make the first action obvious on mobile and desktop.
+- **Do** show the gradual Q&A flow so users understand why the final tip is grounded.
 - **Do** keep every phase actionable with one clear next step.
-- **Do** use generated raster imagery for the dream atmosphere, header state, or empty state.
-- **Do** verify dark-mode contrast for body text, labels, placeholders, chips, and disabled controls.
+- **Do** cite concrete dream anchors in the final result.
 - **Do** preserve a deterministic demo backend while adding a model-backed route.
+- **Do** verify text fits inside controls at 390px mobile width.
 
 ### Don't:
 
 - **Don't** ship a plain Gradio two-column form as the primary experience.
-- **Don't** use beige parchment, tarot, faux therapy, or generic purple AI visuals.
-- **Don't** use one-shot generation as the whole flow.
+- **Don't** use tarot, parchment, prophecy, medical intake, or generic healing-app aesthetics.
 - **Don't** expose technical model routes as first-level controls unless the user opens model settings.
 - **Don't** render navigation-looking text that cannot be clicked.
-- **Don't** reserve tall empty panels for future content on the first screen.
-- **Don't** pair a 1px border with a large soft shadow on every card.
-- **Don't** use side-stripe borders, gradient text, or decorative glass panels.
+- **Don't** create several competing tips in the final result.
+- **Don't** let the final advice become generic wellness copy unrelated to the dream.

PRODUCT.md

@@ -6,35 +6,38 @@ product
 
 ## Users
 
-Dream Customs serves people who wake up with vivid, strange, or unsettling dreams and want a small morning ritual before the day takes over. The primary user may still be half asleep, on a phone, and emotionally sticky from the dream. The secondary user is a hackathon judge or playful AI explorer who needs to understand the loop quickly and see why small multimodal models matter.
+Dream QA / 梦境问答台 serves people who wake up with vivid, strange, or unsettling dreams and want a small morning conversation before the day takes over. The primary user may still be half asleep, on a phone, and emotionally sticky from the dream. The secondary user is a hackathon judge or playful AI explorer who needs to understand the loop quickly and see why small multimodal models matter.
 
 ## Product Purpose
 
-Dream Customs helps a user form a playful alliance with last night's dream. It accepts text, image, and voice evidence, turns those fragments into a structured dream declaration, asks a few customs questions, and lets the user choose whether to add more material, continue negotiation, or seal a next-day pact.
+The product helps a user unpack a dream through a guided, step-by-step Q&A. It accepts text, image, and voice fragments, turns them into one structured dream intake, asks gentle follow-up questions, drafts a grounded interpretation, and ends with one `今日小 Tips`.
 
-Success means the user receives something more useful than a one-shot interpretation: a clear visitor, a practical suggestion for today, a weird five-minute task, and a bedtime release phrase. The experience should feel like a small ceremony, not a diagnosis.
+Success means the user receives something more useful than a one-shot interpretation: a short summary of the dream, one clear question they were trying to answer, a non-certain explanation grounded in concrete dream details, and a tiny suggestion for today. The tip can be practical, playful, or simply caring, but it must feel connected to the dream.
 
 ## Brand Personality
 
 Gentle, strange, lucid.
 
-The voice is an overnight border clerk who takes odd evidence seriously without becoming mystical or clinical. It should feel curious and companionable, with enough dream color to be memorable and enough product discipline to be usable on a phone.
+The voice is a calm dream companion who asks good questions and takes odd details seriously without becoming mystical or clinical. It should feel curious, ordinary-user friendly, and companionable: less secret ritual, more warm morning dialogue.
 
 ## Anti-references
 
 - Do not look like a plain Gradio form with two columns and one submit button.
 - Do not look like a beige parchment certificate, generic tarot card, therapy intake form, or purple AI SaaS dashboard.
-- Do not use medical, diagnostic, frightening, or fate-telling language.
+- Do not sound like generic healing-app advice that could fit any input.
+- Do not use medical, diagnostic, frightening, fate-telling, or prophecy language.
 - Do not bury the main action below many controls.
-- Do not end the flow after one answer when the user still wants to add evidence or keep negotiating.
+- Do not force the user to complete a long questionnaire before seeing value.
+- Do not end with multiple competing recommendations; the final result needs one primary today tip.
 
 ## Design Principles
 
-1. The AI is a clerk in a ritual, not a text generator behind a form.
-2. The user keeps agency: add evidence, answer, skip, continue, revise, or seal.
+1. The AI is a question guide, not an oracle.
+2. The user keeps agency: answer, skip, add detail, ask for another angle, or finish.
 3. The interface should be dream-colored but product-trustworthy.
-4. Every output should lead to a tiny next-day action.
-5. The demo path must survive Space constraints and still have a model-backed route.
+4. Every final output should lead to one small next-day reference or action.
+5. The final tip must cite a concrete dream anchor.
+6. The demo path must survive Space constraints and still have a model-backed route.
 
 ## Accessibility & Inclusion
 

README.md

@@ -1,15 +1,15 @@
 ---
 title: Dream Customs
-emoji: ⚡
-colorFrom: blue
-colorTo: pink
+emoji: 🌤️
+colorFrom: green
+colorTo: yellow
 sdk: gradio
 sdk_version: 4.44.1
 python_version: "3.10"
 app_file: app.py
 pinned: false
 license: mit
-short_description: Turn dream declarations into a playful next-day pact.
+short_description: Guided dream Q&A with one gentle today tip.
 models:
   - openbmb/MiniCPM5-1B
   - openbmb/MiniCPM-V-4.6
@@ -20,22 +20,45 @@ tags:
   - dream-journal
 ---
 
-# Dream Customs
+# Dream QA / 梦境问答台
 
-A Build Small Hackathon Gradio app that helps users form a playful alliance with last night's dream.
+A Build Small Hackathon Gradio app that helps users unpack a dream step by step and leave with one grounded tip for today.
+
+The Hugging Face Space may still be named `Dream Customs` for continuity, but the current product direction is Dream QA: record a dream, answer or skip gentle follow-up questions, read a grounded interpretation draft, and receive a `今日小 Tips`.
 
 ## Concept
 
-Dream Customs accepts dream declarations by text, image, or voice. It turns the dream into a gentle "customs negotiation" and returns a Today's Pact card: one practical suggestion, one weird 5-minute task, and one bedtime release phrase.
+Dream QA accepts dream fragments by text, image, or voice. It turns those fragments into a shared dream intake, asks a few gentle questions, and returns a Today Tip card: a short non-certain interpretation, one practical or caring suggestion for today, and an optional tiny action.
+
+This is not a therapy, diagnosis, or prophecy product.
 
 ## Models
 
 - `openbmb/MiniCPM-V-4.6` for image/sketch/note understanding.
-- `openbmb/MiniCPM5-1B` for dream negotiation and pact generation.
+- `openbmb/MiniCPM5-1B` for dream summary, follow-up questions, interpretation, and Today Tip generation.
 - A small ASR adapter may be used only for voice transcription.
 - The app defaults to a stable demo backend so the local Gradio flow always works.
 - Optional Ollama adapters are included for local MiniCPM testing.
 
+## User Flow
+
+1. Enter a dream by text, image, voice, or a mix.
+2. State or let the app infer the main question.
+3. Answer or skip one or more follow-up questions.
+4. Review a grounded interpretation.
+5. Receive one Today Tip tied to concrete dream details.
+
+## Current Direction References
+
+- Product spec: `docs/spec.md`
+- PRD: `docs/prd.md`
+- Handoff: `docs/handoff.md`
+- Design system: `DESIGN.md`
+- Prototype images:
+  - `docs/prototypes/2026-06-08-dream-qa-mobile-flow.png`
+  - `docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png`
+  - `docs/prototypes/2026-06-08-dream-qa-tips-card.png`
+
 ## Run
 
 ```bash
@@ -89,7 +112,7 @@ client = HostedMiniCPMTextClient(
     token=os.getenv("DREAM_CUSTOMS_HOSTED_TOKEN", ""),
 )
 result = client.generate_negotiation("I missed an elevator in a foggy dream.")
-print(result["visitor_name"])
+print(result)
 PY
 ```
 
@@ -116,12 +139,8 @@ python -m pytest -q
 
 ## Deployment Smoke Status
 
-2026-06-05 local V2 verification passed: tests were green and the workbench flow reached a sealed pact through `Send to customs`, `Ask another question`, `Add material`, `Draft pact`, `Revise pact`, and `Seal today's pact`.
-
-The public Space now serves the V2 workbench from Space `main` commit `8ad6f00628f800abc2dbefab05163aba94a5723f`. Public browser smoke, mobile readability, diagnostics, raw remote queue prediction, and a hosted text route smoke all reached a sealed pact on 2026-06-05. The current Modal backend pass requires a real `openbmb/MiniCPM-V-4.6` vision route smoke before delivery; demo vision fallback is runtime resilience, not a substitute for that smoke.
-
-Current smoke details are tracked in `docs/smoke/2026-06-05-space-deployment-smoke.md`.
+Historical smoke notes under `docs/smoke/` describe earlier pact/customs UI passes. They remain useful deployment history, but the current implementation target is the Dream QA flow documented in `docs/handoff.md`, `docs/spec.md`, and `docs/prd.md`.
 
 ## Safety
 
-This is not a therapy or diagnosis product. It gives playful reflection, small actions, and escalation copy for severe distress.
+This is not a therapy or diagnosis product. It gives playful reflection, one small today tip, and escalation copy for severe distress.

design-qa.md

@@ -1,24 +1,27 @@
-# Dream Customs V4 Design QA
+# Dream QA Design QA
 
-Date: 2026-06-05
+Date: 2026-06-08
 
-Reference: user-provided Codex-style multimodal composer screenshot.
+Reference: 2026-06-08 Dream QA prototype images and updated source docs.
 
 ## Checks
 
-- First screen uses one rounded multimodal composer instead of separate form blocks.
-- Visible composer tools are limited to Image, Voice, Mood, Add, and Send.
-- Technical Text/Vision routes are collapsed under Model routes.
-- Pact inspector remains visible beside the composer on desktop.
-- Timeline, diagnostics, examples, workflow shortcuts, and refinement controls are secondary.
-- Text-only Chrome flow completed: Send -> Draft pact -> Seal today's pact.
-- Sealed output renders a screenshot-friendly Today's Pact card.
-- No desktop horizontal overflow in Chrome at the inspected viewport.
+- First screen should introduce `梦境问答台 / Dream QA`, with `Dream Customs` only as continuity context if needed.
+- The primary loop is Record -> Ask -> Interpret -> Tip.
+- The main surface is a conversational Q&A timeline, not a permit or pact inspector.
+- The composer supports text, image, voice, mood, and one clear continue action.
+- Follow-up questions are visible and skippable.
+- The final result prioritizes one Today Tip, with optional tiny action and caring note.
+- Interpretation text uses non-certain language and cites concrete dream anchors.
+- Technical text/vision routes remain collapsed under developer/model settings.
+- Text-only flow must remain available as the fallback path.
+- Mobile width should keep buttons, chips, and Today Tip text readable.
 
 ## Notes
 
-- Image and voice use compact upload buttons to avoid large Gradio media drop zones in the first screen.
-- Voice upload remains available as an input to the existing ASR adapter path.
+- The older V4 customs workbench passed its historical design QA, but it is no longer the current target.
+- Do not reintroduce permit, contraband, sealed pact, or bedtime release as required UX fields.
+- Do not replace the new Q&A flow with a generic healing-app result card; the tip must remain dream-grounded.
 - The UI keeps safety copy non-diagnostic.
 
-final result: passed
+Current desired result: pending implementation.

docs/design/2026-06-05-uiux-v2-brief.md

@@ -2,6 +2,8 @@
 
 Last updated: 2026-06-05
 
+> Historical note: this V2 brief documents the earlier customs/pact workbench direction. As of 2026-06-08, the current product target is `Dream QA / 梦境问答台`: Record -> Ask -> Interpret -> Today Tip. Use `DESIGN.md`, `docs/handoff.md`, and `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md` for new work.
+
 ## 1. Feature Summary
 
 Redesign Dream Customs from a one-shot Gradio form into a dream customs workbench. The user should be able to declare a dream through text, image, or voice, receive customs questions, add more evidence, continue negotiation, revise the pact draft, or seal the final pact.

docs/goal-prompts/2026-06-08-model-led-pact-v2.md

@@ -0,0 +1,23 @@
+# Goal Prompt: Model-Led Pact V2
+
+> Superseded on 2026-06-08: do not use this for new work unless the user explicitly revives the pact direction. Current source of truth is `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md`.
+
+Work in `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon`.
+
+Use the repo plan `docs/superpowers/plans/2026-06-08-model-led-pact-v2.md`. Implement it task by task with `superpowers:subagent-driven-development` or `superpowers:executing-plans`. Keep the public demo language English-first: users may input any language, but the final clearance pass should be polished natural English for judges and demo video.
+
+Do not broaden beyond MiniCPM before exhausting the current pair:
+
+- `openbmb/MiniCPM5-1B` owns dream brief, pact draft, critique, and rewrite.
+- `openbmb/MiniCPM-V-4.6` owns visual witness reports.
+- ASR remains transcription only.
+
+Main acceptance case:
+
+```text
+I kept missing an elevator. The buttons melted like wax, and the floor number froze at 14.
+```
+
+The final card must not contain `the an`, `the the`, invented `lever`, diagnosis, prophecy, or frightening certainty. It must mention at least two concrete details from the dream, give one real next step for today, and include one harmless five-minute odd task grounded in the dream.
+
+Before changes: confirm cwd, branch, remotes, and run `git pull`. During implementation: use tests first, keep commits small, and preserve text-only fallback. After implementation: run `.venv/bin/python -m pytest -q`, `git diff --check`, local Gradio smoke on port `7862`, push GitHub branch, then sync or prepare HF Space update. Stop and ask before exposing secrets, confirming paid deploy/build costs, force-pushing public Space `main`, or handling a manual PR merge.

docs/handoff.md

@@ -1,53 +1,60 @@
-# Dream Customs / 梦境海关 Handoff
+# Dream QA / 梦境问答台 Handoff
 
-Last updated: 2026-06-05
+Last updated: 2026-06-08
 
-## Current State
+## Current Product Direction
 
-The project has shipped a working Gradio MVP and a V4 local UI pass. The current interface centers a warm Codex-like multimodal composer: text, image upload, voice upload, mood, add-material, and send live inside one rounded input surface. Model routes, workflow shortcuts, diagnostics, and examples are collapsed by default.
+The project is pivoting from a customs/pact-centered ritual into a step-by-step dream Q&A Gradio app.
 
-Current V4 UX decisions:
+The repo and Space still use the `Dream Customs` name for continuity, but future product work should use the `Dream QA / 梦境问答台` direction:
 
-- The first screen prioritizes the dream declaration composer and pact inspector.
-- Image and voice use compact upload buttons to avoid large Gradio media drop zones in the main composer.
-- `Draft pact` and `Seal today's pact` sit beside the live pact inspector.
-- The timeline is a supporting "Story so far" section below the first-screen workflow.
-- Technical model route controls are available but not first-level visual chrome.
+> 输入梦境，回答或跳过几个温和追问，最后得到一个和梦境细节相关的今日小 Tips。
 
-The original visual HTML concept note remains useful background:
+## Deprecated Context
 
-- `docs/dream-customs-concept/index.html`
+Earlier implementation and smoke docs mention:
 
-Supporting images:
+- dream visitor
+- customs negotiation
+- permit ID
+- contraband
+- sealed pact
+- bedtime release
 
-- `docs/dream-customs-concept/assets/dream-passport.svg`
-- `docs/dream-customs-concept/assets/multimodal-intake.svg`
-- `docs/dream-customs-concept/assets/alliance-card.svg`
+Those are historical context, not the new target. Do not build new work around permit/contraband/sealed-pact unless the user explicitly reverses this pivot.
 
-Project context documents:
+## Current Source Documents
 
-- `docs/spec.md`
-- `docs/prd.md`
-- `docs/handoff.md`
-- `docs/superpowers/plans/2026-06-05-dream-customs-mvp.md`
-- `docs/superpowers/plans/2026-06-05-dream-customs-uiux-v2.md`
-- `docs/superpowers/plans/2026-06-05-dream-customs-uiux-v3.md`
-- `AGENTS.md`
+Read in this order:
+
+1. `AGENTS.md`
+2. `docs/spec.md`
+3. `docs/prd.md`
+4. `PRODUCT.md`
+5. `DESIGN.md`
+6. `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md`
+7. `docs/superpowers/plans/2026-06-08-dream-qa-refactor-doc-plan.md`
+
+Prototype references:
+
+- `docs/prototypes/2026-06-08-dream-qa-mobile-flow.png`
+- `docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png`
+- `docs/prototypes/2026-06-08-dream-qa-tips-card.png`
 
 ## Product Decision
 
-Build Dream Customs as a "dream alliance" app, not a dream diagnosis app.
+Build a guided dream interpretation app, not a diagnosis app, not a fortune-telling app, and not a one-shot pact generator.
 
 Final positioning:
 
-> 梦境海关帮你和昨晚的梦结盟：把不安转成明天的小建议，把怪梦转成一件有趣的小事。
+> 梦境问答台帮你一步步整理梦境疑惑：先记录梦，回答几个温和追问，再得到一个今天可以参考的小 Tips。
 
 ## Model Decision
 
 Use:
 
 - `openbmb/MiniCPM-V-4.6` for image/sketch/note understanding.
-- `openbmb/MiniCPM5-1B` for text reasoning, negotiation, and final output.
+- `openbmb/MiniCPM5-1B` for text reasoning, follow-up questions, interpretation, and final Today Tip.
 
 Do not broaden to arbitrary small models unless MiniCPM paths fail.
 
@@ -67,31 +74,36 @@ Voice input is allowed, but current MiniCPM pair does not directly transcribe ra
 1. User submits dream using text, image, voice, or a combination.
 2. Audio is transcribed by a small adapter.
 3. Image is converted into visual clues by MiniCPM-V-4.6.
-4. App builds a `DreamIntake` object.
-5. MiniCPM5-1B generates dream visitor and 2-3 negotiation questions.
-6. User answers or skips.
-7. MiniCPM5-1B generates final "Today's Pact" card.
-8. Gradio renders a screenshot-friendly HTML card.
+4. App builds a `DreamQuestionIntake`.
+5. MiniCPM5-1B creates a short dream summary and identifies the user's likely main question.
+6. MiniCPM5-1B asks 1-3 gentle follow-up questions.
+7. User answers, skips, adds detail, or asks for another angle.
+8. MiniCPM5-1B drafts a grounded interpretation.
+9. MiniCPM5-1B generates a final `TodayTipCard`.
+10. Gradio renders a mobile-readable result card and plain text.
 
 ## Required Output Fields
 
-- `visitor_name`
-- `permit_id`
-- `contraband`
-- `risk_level`
-- `alliance_reading`
-- `practical_suggestion`
-- `weird_task`
-- `bedtime_release`
+- `dream_summary`
+- `main_question`
+- `dream_anchors`
+- `followup_questions`
+- `user_answers`
+- `interpretation`
+- `today_tip`
+- `tiny_action`
+- `caring_note`
 - `safety_note`
 
+The final `today_tip` must reference at least one concrete dream anchor. Generic wellness advice is a regression.
+
 ## Safety Boundary
 
 The product must never present itself as therapy, medical advice, or diagnosis. It should use playful, non-certain language. Severe distress should trigger a professional-help suggestion.
 
-## Recommended First Implementation
+## Recommended Implementation Scope
 
-The minimal Python package already exists:
+The existing package should be refactored rather than replaced from scratch:
 
 ```text
 app.py
@@ -105,37 +117,45 @@ dream_customs/
   render.py
   pipeline.py
   models.py
+  ui/
 tests/
-  test_schema.py
-  test_safety.py
-  test_render.py
-  test_pipeline.py
 ```
 
-The current implementation keeps deterministic demo clients as the default and exposes optional model routes. For V3, do not rebuild the pipeline from scratch. Fix the app shell, control hierarchy, phase actions, and visual polish while preserving the existing `CustomsSession` state flow.
+Likely code files to change:
+
+- `dream_customs/schema.py`
+- `dream_customs/prompts.py`
+- `dream_customs/pipeline.py`
+- `dream_customs/render.py`
+- `dream_customs/ui/actions.py`
+- `dream_customs/ui/app.py`
+- `dream_customs/ui/copy.py`
+- `dream_customs/ui/styles.py`
+- tests covering schema, prompts, pipeline, render, UI actions, and safety
 
 ## Implementation Priorities
 
-1. First-screen trust and immediate declaration controls.
-2. Clickable phase actions.
-3. Mobile-readable composer and inspector.
-4. Removal of long blank page regions.
-5. Tests and local browser verification.
-6. Branch commit/push and Space update when credentials allow.
+1. Preserve text-only demo fallback.
+2. Replace pact schema with Q&A state and Today Tip output.
+3. Preserve image and voice as optional evidence in the same intake.
+4. Make follow-up questions a first-class user action.
+5. Render one clear final tip, not a multi-field customs certificate.
+6. Keep mobile readability.
+7. Run tests and local Gradio smoke before any Space sync.
 
 ## Repository Status
 
-This directory is now a dedicated Dream Customs repository:
+This directory is a dedicated Dream Customs/Dream QA repository:
 
 - Local path: `/Users/junhaocheng/working-dir/ai-competitions/build-small-hackthon`
 - GitHub remote: `https://github.com/adjcjh777/dream-customs-build-small.git`
 - Hugging Face Space remote: `https://huggingface.co/spaces/build-small-hackathon/dream-customs`
 
-Continue to confirm `git remote -v` before pushing, but the earlier VLA remote warning is no longer the active state.
+Continue to confirm `git remote -v` before pushing.
 
 ## Modal Backend Route
 
-The intended production-quality route is:
+The intended production-quality route remains:
 
 ```text
 Hugging Face Space Gradio UI
@@ -146,13 +166,12 @@ Hugging Face Space Gradio UI
 
 The Space defaults to `model` for both text and vision backends, so a configured Space calls Modal immediately. The `demo` backend remains available in developer settings as the deterministic fallback path.
 
-The public Space can run on ZeroGPU after `dream_customs.zerogpu` registers the lightweight `@spaces.GPU` startup probe. Modal credits still pay for the hidden L4 GPU backend; the ZeroGPU probe is only there to make the HF hardware setting valid for this Gradio frontend.
+The public Space can run on ZeroGPU after `dream_customs.zerogpu` registers the lightweight `@spaces.GPU` startup probe. Modal credits still pay for the hidden GPU backend; the ZeroGPU probe is only there to make the HF hardware setting valid for this Gradio frontend.
 
 ## Open Questions For User
 
-These do not block initial scaffolding:
+These do not block document alignment:
 
-- Should the demo language be Chinese-only or bilingual?
-- Which Hugging Face Space name should be used?
-- Should we reuse any previous `build-small-relics` assets, or keep Dream Customs separate?
+- Should the public name remain `Dream Customs`, or should visible UI switch fully to `梦境问答台 / Dream QA`?
+- Should final demo language be Chinese-first, English-first, or bilingual?
 - Which ASR adapter is acceptable for the hackathon submission?

docs/prd.md

@@ -1,23 +1,27 @@
-# Dream Customs / 梦境海关 PRD
+# Dream QA / 梦境问答台 PRD
 
-Last updated: 2026-06-05
+Last updated: 2026-06-08
 
 ## 1. Executive Summary
 
 ### Problem Statement
 
-Users who wake up from frequent or vivid dreams may feel unsettled, tired, or mentally cluttered. They need a lightweight way to turn dream residue into a gentle next-day action without receiving pseudo-clinical dream diagnosis.
+Users who wake up from vivid dreams may feel unsettled, curious, or mentally cluttered. They often do not need a definitive "meaning"; they need a short, safe conversation that helps them identify what question the dream left behind and what tiny thing they can do today.
 
 ### Proposed Solution
 
-Dream Customs is a Gradio app that accepts voice, image, and text dream declarations, normalizes them into a structured dream intake, and uses MiniCPM models to generate a playful "dream alliance" card with practical advice, a weird 5-minute task, and a bedtime release phrase.
+Dream QA is a Gradio app that accepts voice, image, and text dream fragments, normalizes them into a structured dream intake, asks gentle follow-up questions, drafts a grounded interpretation, and ends with one `今日小 Tips`.
+
+The repository and Space may continue to use `Dream Customs` as the deployed project name, but the product experience should no longer be built around permits, contraband, or sealed pact cards.
 
 ### Success Criteria
 
-- A user can complete the core flow from input to final card in <= 90 seconds on the hosted demo.
-- At least 90% of demo runs produce a parseable final output object matching the required schema.
-- At least 5 real users can understand the output without extra explanation and rate it >= 4/5 for delight.
-- At least 3 real users report that the "today's pact" feels actionable.
+- A user can complete the core text-only Q&A flow in <= 90 seconds on the hosted demo.
+- At least one follow-up question feels related to the dream in >= 90% of demo runs.
+- Final output references at least one concrete dream detail.
+- Final output gives exactly one primary today tip.
+- Ordinary cases contain no diagnostic, prophetic, or frightening language.
+- Distress-edge cases show a support note.
 - The app runs with total model parameters <= 32B and is packaged for Gradio/Hugging Face Space.
 
 ## 2. User Experience & Functionality
@@ -26,7 +30,7 @@ Dream Customs is a Gradio app that accepts voice, image, and text dream declarat
 
 1. Primary persona: vivid dreamer.
    - Recently sleeps poorly or wakes with strong dream fragments.
-   - Wants a small morning ritual, not therapy.
+   - Wants a small morning reflection, not therapy or fortune-telling.
 
 2. Secondary persona: playful AI explorer.
    - Wants a strange AI experience worth showing a friend.
@@ -38,28 +42,30 @@ Dream Customs is a Gradio app that accepts voice, image, and text dream declarat
 
 ### User Stories
 
-#### Story 1: Text Dream Declaration
+#### Story 1: Text Dream Q&A
 
-As a vivid dreamer, I want to type my dream so that I can get a next-day pact even if I have no image or audio.
+As a vivid dreamer, I want to type my dream so that the app can help me figure out what I am actually wondering about.
 
 Acceptance criteria:
 
 - User can submit text-only input.
-- App creates a valid `DreamIntake` object.
-- Final card includes dream visitor, practical suggestion, weird task, and bedtime release phrase.
+- App creates a valid dream intake object.
+- App asks at least one relevant follow-up question.
+- User can answer or skip.
+- Final output includes a grounded today tip.
 
-#### Story 2: Image Dream Declaration
+#### Story 2: Image-Assisted Dream Clues
 
 As a user who remembers images better than words, I want to upload a sketch or bedside note so that the system can use visual dream clues.
 
 Acceptance criteria:
 
 - User can upload one image.
-- MiniCPM-V-4.6 extracts at least 3 visual clues when visible content exists.
-- Visual clues are included in the final `DreamIntake`.
+- MiniCPM-V-4.6 extracts visible clues when content exists.
+- Visual clues are included in the dream intake and final interpretation.
 - If image extraction fails, text-only flow still works.
 
-#### Story 3: Voice Dream Declaration
+#### Story 3: Voice Dream Capture
 
 As a half-awake user, I want to speak my dream so that I do not need to type immediately after waking.
 
@@ -67,33 +73,35 @@ Acceptance criteria:
 
 - User can record or upload an audio clip.
 - ASR adapter returns a transcript.
-- Transcript is visible/editable before final submission or transparently included in the declaration.
+- Transcript is visible/editable or transparently included in the dream intake.
 - If ASR fails, user receives a concise fallback message and can type manually.
 
-#### Story 4: Alliance Negotiation
+#### Story 4: Follow-Up Question Flow
 
-As a user, I want the AI to ask me a few questions so that the final advice feels connected to my dream.
+As a user, I want the AI to ask me a few questions so that the final interpretation feels connected to my dream rather than generic.
 
 Acceptance criteria:
 
-- App generates 2-3 questions.
-- User can answer all, answer some, or skip.
-- Skip path still generates a final card.
+- App generates 1-3 follow-up questions.
+- User can answer all, answer some, skip, or ask for another angle.
+- Skip path still generates a final tip.
+- Questions avoid clinical or diagnostic phrasing.
 
-#### Story 5: Today's Pact Card
+#### Story 5: Today Tip Card
 
-As a user, I want a visually clear output card so that I can screenshot or share the result.
+As a user, I want a clear final result so that I leave with one small thing for today.
 
 Acceptance criteria:
 
-- Card includes all required output fields.
-- Card is readable on mobile and desktop.
-- Card avoids medical or diagnostic framing.
-- Card includes a short safety note only when needed.
+- Result includes dream summary, main question, interpretation, today tip, optional tiny action, optional caring note, and safety note when needed.
+- Result is readable on mobile and desktop.
+- Result avoids medical, prophetic, or deterministic framing.
+- Today tip references a concrete dream anchor.
 
 ### Non-Goals
 
 - Medical diagnosis or therapy.
+- Dream prophecy or symbolic certainty.
 - Sleep-stage tracking.
 - Long-term journaling database.
 - Account creation.
@@ -106,10 +114,10 @@ Acceptance criteria:
 ### Tool Requirements
 
 - MiniCPM-V-4.6 for image-to-text visual clue extraction.
-- MiniCPM5-1B for text reasoning, persona, structured output, and alliance card generation.
+- MiniCPM5-1B for text reasoning, follow-up questions, interpretation, and Today Tip generation.
 - A small ASR adapter for voice-to-text. This adapter is not the core AI experience.
 - Gradio for UI.
-- Optional HTML/CSS card renderer.
+- Optional HTML/CSS result renderer.
 
 ### Prompt Requirements
 
@@ -119,7 +127,8 @@ Prompts must:
 - Keep the tone playful, gentle, and non-clinical.
 - Avoid strong claims about dream meaning.
 - Include a safety boundary for severe distress.
-- Keep final advice small enough to execute in 5-10 minutes.
+- Keep final advice small enough to execute today.
+- Require at least one dream anchor in the final tip.
 
 ### Evaluation Strategy
 
@@ -133,9 +142,10 @@ Create an eval set with at least 12 dream inputs:
 Measure:
 
 - Schema validity.
+- Follow-up relevance.
 - Tone safety.
-- Practicality of advice.
-- Weird-task delight.
+- Dream-anchor grounding.
+- Practicality of today tip.
 - Ability to recover from missing modality.
 
 Pass thresholds:
@@ -143,7 +153,8 @@ Pass thresholds:
 - Schema validity: >= 90%.
 - No diagnostic language in ordinary cases: 100%.
 - Safety note appears in distress-edge cases: >= 90%.
-- Human delight rating on 5 demo cases: average >= 4/5.
+- At least one concrete dream anchor in final result: >= 90%.
+- Human usefulness/delight rating on 5 demo cases: average >= 4/5.
 
 ## 4. Technical Specifications
 
@@ -154,28 +165,31 @@ Gradio inputs
   -> text input
   -> image upload -> MiniCPM-V-4.6 visual clue extractor
   -> audio upload/record -> ASR adapter
-  -> DreamIntake builder
-  -> MiniCPM5-1B customs officer prompt
-  -> negotiation questions
-  -> final MiniCPM5-1B pact prompt
-  -> HTML card renderer
+  -> DreamQuestionIntake builder
+  -> MiniCPM5-1B summary/main-question prompt
+  -> follow-up question flow
+  -> user answer/skip/another-angle
+  -> MiniCPM5-1B interpretation prompt
+  -> TodayTipCard prompt
+  -> HTML result renderer
 ```
 
 ### Core Components
 
-- `app.py`: Gradio UI composition and event wiring.
-- `dream_customs/schema.py`: dataclasses or Pydantic models for inputs and outputs.
+- `app.py`: thin Gradio entrypoint.
+- `dream_customs/schema.py`: Pydantic models for dream intake, Q&A state, and Today Tip output.
 - `dream_customs/models.py`: model/client loading and inference wrappers.
 - `dream_customs/prompts.py`: prompt templates.
 - `dream_customs/pipeline.py`: orchestration logic.
 - `dream_customs/safety.py`: lightweight safety checks and copy.
-- `dream_customs/render.py`: HTML card rendering.
-- `tests/`: schema, prompt, safety, and pipeline unit tests with mocked model outputs.
+- `dream_customs/render.py`: HTML result rendering.
+- `dream_customs/ui/`: Gradio UI shell, copy, actions, and styles.
+- `tests/`: schema, prompt, safety, pipeline, render, and UI action unit tests with mocked model outputs.
 
 ### Integration Points
 
 - Hugging Face Space runtime.
-- Hugging Face model downloads or inference endpoints.
+- Hugging Face model downloads or private Modal endpoints.
 - Gradio audio, image, and text components.
 - Optional model cache in Space environment.
 
@@ -195,22 +209,22 @@ Gradio inputs
 - Text, image, and voice input.
 - Dream intake normalization.
 - MiniCPM-V-4.6 image clue extraction.
-- MiniCPM5-1B negotiation and final card.
+- MiniCPM5-1B follow-up and final Today Tip.
 - HTML output card.
 - Safety boundary.
 
 #### v1.1
 
-- More polished card export.
 - Better example gallery.
 - Optional bilingual output.
 - More robust eval harness.
+- Better result export.
 
 #### v2.0
 
 - Voice output through VoxCPM2.
 - Local dream history stored only in browser/session.
-- Multiple customs officer styles.
+- Multiple question-guide styles.
 
 ### Technical Risks
 
@@ -218,12 +232,4 @@ Gradio inputs
 - MiniCPM5-1B output may fail strict JSON without repair.
 - ASR adapter may complicate dependencies.
 - Audio input on mobile browsers may behave inconsistently.
-- Safety classification may be too weak if only prompt-based.
-
-### Mitigations
-
-- Keep text-only demo path always functional.
-- Add JSON repair and schema validation.
-- Use examples with fixed sample media for demo recording.
-- Make ASR optional and fallback to manual transcript.
-- Keep image extraction output concise to reduce latency.
+- Final tips may become generic unless prompts and repair logic enforce dream anchors.

docs/spec.md

@@ -1,10 +1,10 @@
-# Dream Customs / 梦境海关 Product Spec
+# Dream QA / 梦境问答台 Product Spec
 
-Last updated: 2026-06-05
+Last updated: 2026-06-08
 
 ## 1. One-Line Concept
 
-梦境海关帮用户和昨晚的梦结盟：用户用语音、图片或文字申报梦境，系统把不安转成第二天的小建议，把怪梦转成一件 5 分钟能完成的有趣小事。
+梦境问答台帮用户循序渐进地理解昨晚的梦：用户用文字、图片或语音记录梦境，系统先追问关键细节，再给出一个非诊断、非宿命论的解读草稿，最后生成一个温和的今日小 Tips。
 
 ## 2. Contest Fit
 
@@ -12,26 +12,27 @@ Last updated: 2026-06-05
 - Build window: 2026-06-05 to 2026-06-15.
 - Deployment target: Gradio app on Hugging Face Space.
 - Model constraint: total model parameters must be <= 32B.
-- Primary track fit: An Adventure in Thousand Token Wood, because the AI is the load-bearing delight of the experience.
-- Secondary story: Backyard AI, because the concept comes from a real sleep problem: frequent vivid dreams and poor sleep.
+- Primary track fit: An Adventure in Thousand Token Wood, because the AI-driven conversation is the main experience.
+- Secondary story: Backyard AI, because the concept comes from a real sleep problem: frequent vivid dreams and morning confusion.
 - Model family constraint: prioritize MiniCPM models before considering any unrelated small model.
 
 ## 3. Core User Problem
 
-The user wakes up after vivid or unsettling dreams and wants a quick, non-clinical way to make sense of the dream before the day begins. Existing dream tools often feel either too mystical, too diagnostic, or too generic. This product should feel like a playful ritual that gives emotional order without pretending to be therapy.
+The user wakes up after a vivid or unsettling dream and wants help making sense of it without receiving mystical certainty, therapy language, or generic advice. They may not know the right question yet, so the app should help them gradually clarify what they are curious or worried about.
 
 ## 4. Product Principles
 
 1. Do not diagnose.
 2. Do not frighten the user.
-3. Convert dream residue into a small next-day action.
-4. Keep the output weird enough to show a friend.
-5. Make the AI the main experience, not a helper hidden behind a form.
-6. Keep the MVP stable enough for Gradio Space and demo-video recording.
+3. Do not claim the dream has one fixed meaning.
+4. Ask before interpreting.
+5. Ground every final answer in concrete dream details.
+6. End with one small today tip, not a pile of advice.
+7. Keep the MVP stable enough for Gradio Space and demo-video recording.
 
 ## 5. User Inputs
 
-All inputs are normalized into one `DreamIntake` object so the app does not become three separate products.
+All inputs are normalized into one dream intake object so the app does not become three separate products.
 
 ### 5.1 Text Input
 
@@ -39,6 +40,7 @@ The user writes:
 
 - Dream narrative.
 - Wake-up mood.
+- What feels confusing or important.
 - Repeated symbols.
 - Any second-day concern or wish.
 
@@ -59,7 +61,15 @@ The user speaks the dream immediately after waking.
 
 Implementation note: MiniCPM-V-4.6 and MiniCPM5-1B are not raw audio ASR models. Voice input needs a small transcription adapter. The adapter only converts audio to text; dream understanding remains MiniCPM-driven.
 
-## 6. Dream Intake Schema
+## 6. Data Model
+
+The refactor should move from `DreamIntake -> PactCard` toward:
+
+```text
+DreamQuestionIntake -> DreamQAState -> TodayTipCard
+```
+
+### 6.1 DreamQuestionIntake
 
 ```json
 {
@@ -67,12 +77,43 @@ Implementation note: MiniCPM-V-4.6 and MiniCPM5-1B are not raw audio ASR models.
   "voice_transcript": "我梦见我一直赶不上电梯...",
   "visual_clues": ["歪斜电梯门", "蓝色楼道", "融化的数字 14"],
   "mood": "焦虑但有点滑稽",
+  "main_question": "这个梦是不是和我最近拖延有关？",
   "recurring_symbols": ["电梯", "迟到", "融化的按钮"],
   "uncertainty": "梦的后半段记不清",
   "user_context": "最近晚上常做梦，睡醒后想获得第二天建议"
 }
 ```
 
+### 6.2 DreamQAState
+
+```json
+{
+  "dream_summary": "你梦见自己赶不上电梯，楼层按钮像蜡一样融化。",
+  "dream_anchors": ["赶不上电梯", "融化的按钮", "焦虑但滑稽"],
+  "main_question": "这个梦和最近拖延有关吗？",
+  "followup_questions": [
+    "梦里最强烈的感受是着急、害怕，还是荒诞？",
+    "最近有没有一件事让你觉得还没开始就已经迟到？"
+  ],
+  "user_answers": ["更像是还没开始就觉得迟到。"],
+  "current_step": "interpret"
+}
+```
+
+### 6.3 TodayTipCard
+
+```json
+{
+  "dream_summary": "你梦见赶不上电梯，按钮融化，醒来有点焦虑。",
+  "main_question": "它是否和最近拖延有关？",
+  "interpretation": "也许这个梦不是在证明你真的迟到了，而是在把“还没开始就担心来不及”的感觉演成了电梯。",
+  "today_tip": "今天先选一件小事，只���打开它的第一步，别要求自己马上抵达。",
+  "tiny_action": "用 5 分钟写下：如果电梯只停一层，我今天先停在哪一层？",
+  "caring_note": "你不需要一醒来就解决所有问题，先把节奏找回来就很好。",
+  "safety_note": ""
+}
+```
+
 ## 7. Model Responsibilities
 
 ### MiniCPM-V-4.6
@@ -87,19 +128,21 @@ Responsibilities:
 
 Non-responsibilities:
 
-- Do not generate the final alliance card.
-- Do not provide psychological interpretation.
+- Do not generate the final TodayTipCard.
+- Do not provide psychological diagnosis.
 
 ### MiniCPM5-1B
 
-Role: dream diplomat.
+Role: dream question guide.
 
 Responsibilities:
 
 - Merge dream text, voice transcript, and visual clues.
-- Name the dream visitor.
-- Ask 2-3 alliance negotiation questions.
-- Generate the final alliance card.
+- Summarize the dream without overexplaining.
+- Infer or ask the user's main question.
+- Ask 1-3 gentle follow-up questions.
+- Draft a non-certain interpretation grounded in dream anchors.
+- Generate exactly one primary today tip, with optional tiny action and caring note.
 - Keep tone playful, gentle, and non-clinical.
 
 ## 8. MVP User Flow
@@ -108,45 +151,36 @@ Responsibilities:
 2. User submits any combination of text, image, and voice.
 3. App transcribes voice if present.
 4. App calls MiniCPM-V-4.6 if image is present.
-5. App builds `DreamIntake`.
-6. MiniCPM5-1B generates a dream visitor profile and 2-3 follow-up questions.
-7. User answers questions or clicks "skip / refuse cooperation".
-8. MiniCPM5-1B generates a final alliance card.
-9. App renders the card as a shareable visual block and plain text.
+5. App builds `DreamQuestionIntake`.
+6. MiniCPM5-1B summarizes the dream and identifies the likely `main_question`.
+7. App asks 1-3 follow-up questions.
+8. User answers, skips, adds detail, or asks for another angle.
+9. MiniCPM5-1B drafts a grounded interpretation.
+10. MiniCPM5-1B generates a final `TodayTipCard`.
+11. Gradio renders a mobile-readable result block and plain text.
 
 ## 9. Output Contract
 
-The final card must include:
+The final result must include:
 
-- Dream visitor name.
-- Entry permit number.
-- Carried emotional contraband.
-- Risk level, phrased playfully.
-- Alliance reading: what the dream may be trying to protect.
-- One practical next-day suggestion.
-- One 5-minute weird task.
-- One bedtime release phrase.
+- Dream summary.
+- Main question.
+- Grounded interpretation.
+- One primary today tip.
+- Optional tiny action.
+- Optional caring note.
 - Safety note if the input indicates severe distress.
 
-Example:
+The final result must:
 
-```json
-{
-  "visitor_name": "迟到的电梯",
-  "permit_id": "DC-0605-014",
-  "contraband": ["未申报的焦虑", "融化的按钮", "一小袋没来得及开始的事"],
-  "risk_level": "橙色：需要被安置，但不需要被害怕",
-  "alliance_reading": "这个梦像是在提醒你，今天不要把启动一件事和完成一件事混成同一个压力。",
-  "practical_suggestion": "提前 10 分钟开始一件最小的任务，只要求打开它。",
-  "weird_task": "给电梯写一句道歉信：抱歉总让你替我背迟到的锅。",
-  "bedtime_release": "今日电梯已停靠，未完成事项明日再报关。",
-  "safety_note": ""
-}
-```
+- Reference at least one concrete dream anchor.
+- Avoid diagnosis, prophecy, or frightening certainty.
+- Avoid generic advice that could fit any dream.
+- Keep the today tip small enough to try today.
 
 ## 10. UX Structure
 
-### Screen 1: Dream Declaration Desk
+### Screen 1: Record
 
 Inputs:
 
@@ -154,40 +188,51 @@ Inputs:
 - Image upload for dream sketch or bedside note.
 - Audio input for spoken dream.
 - Optional mood selector.
+- Optional field: "你最想理解什么？"
 
 Primary action:
 
-- "Submit to Customs"
+- "继续解梦" / "Continue"
 
-### Screen 2: Alliance Negotiation
+### Screen 2: Ask
 
 Content:
 
-- Dream visitor name.
-- 2-3 questions from the customs officer.
-- Buttons: answer, skip, refuse cooperation.
+- Short dream summary.
+- Main question guess.
+- 1-3 follow-up questions.
+- Buttons: answer, skip, ask another angle.
 
-### Screen 3: Today's Pact Card
+### Screen 3: Interpret
 
 Content:
 
-- Card-style result.
+- Dream anchors detected.
+- Draft interpretation using "也许 / 可以把它当作 / 今天先试试" language.
+- Controls: add detail, regenerate angle, finish.
+
+### Screen 4: Today Tip
+
+Content:
+
+- One primary today tip.
+- Optional tiny action.
+- Optional caring note.
 - Copy text button.
-- Download/share image target if feasible.
-- "Release this dream for tonight" reset action.
+- Reset action.
 
 ## 11. Safety Boundaries
 
 The app must:
 
 - Avoid diagnoses, medical claims, or certainty about dream meaning.
-- Avoid telling users that a dream proves trauma, illness, or danger.
+- Avoid telling users that a dream proves trauma, illness, danger, fate, or prophecy.
 - Use language such as "may be", "could be treated as", and "for today, try".
 - If the user mentions self-harm, intent to harm others, severe insomnia, panic, or inability to function, show a supportive escalation note.
 
 Escalation copy:
 
-> This dream sounds heavier than a playful customs ritual should handle. If you feel unsafe, unable to sleep for many nights, or worried you may hurt yourself or someone else, please reach out to a trusted person or professional support now.
+> This dream sounds heavier than a playful reflection tool should handle. If you feel unsafe, unable to sleep for many nights, or worried you may hurt yourself or someone else, please reach out to a trusted person or professional support now.
 
 ## 12. Recommended MVP Scope
 
@@ -197,8 +242,9 @@ Included:
 - Text input.
 - Image input through MiniCPM-V-4.6.
 - Voice input through small ASR adapter.
-- MiniCPM5-1B prompt flow.
-- Result card in HTML.
+- Dream intake normalization.
+- Progressive follow-up questions.
+- Today Tip result in HTML.
 - Example mode for demo stability.
 - Basic safety classifier prompt or rule layer.
 
@@ -210,27 +256,15 @@ Excluded from MVP:
 - Dream history database.
 - Personalized therapy plans.
 - Multi-user social feed.
+- Fine-tuning during the hackathon MVP.
 
 ## 13. Grill Questions And Recommended Answers
 
 1. Is this a therapy tool?
-   - Recommended answer: no. It is a playful reflection and next-day ritual tool.
+   - Recommended answer: no. It is a playful reflection and next-day tip tool.
 
 2. Which track should the submission emphasize?
    - Recommended answer: Thousand Token Wood first, Backyard AI second.
 
-3. Should voice be core?
-   - Recommended answer: voice input yes, voice output no for MVP.
-
-4. Should the image input be mandatory?
-   - Recommended answer: no. Image is a strong MiniCPM-V demo path but text alone must work.
-
-5. What is the winning demo moment?
-   - Recommended answer: user speaks a dream, uploads a quick sketch, and receives a strange but useful "Today's Pact" card.
-
-## 14. Open Questions
-
-- Which ASR adapter should be used on Hugging Face Space for the MVP?
-- Should the first demo be in Chinese, English, or bilingual?
-- Do we want to submit under the same team/repo as the earlier Ordinary Relics MVP, or create a new Space?
-- Should the visual card support image download in MVP or only screenshot-friendly HTML?
+3. What should the demo show?
+   - Recommended answer: user enters a dream, answers or skips one follow-up question, and receives a grounded today tip.

docs/superpowers/plans/2026-06-08-dream-qa-refactor-doc-plan.md

@@ -0,0 +1,202 @@
+# Dream QA Refactor Document Plan
+
+Last updated: 2026-06-08
+
+## Goal
+
+Refactor Dream Customs from a customs/pact-centered ritual into a step-by-step dream Q&A Gradio app.
+
+The new product should help the user gradually answer doubts about a dream, then end with one gentle "today tip". The tip can be a practical suggestion, a tiny thing the user has not tried before, or a short caring sentence. It must stay non-clinical and avoid claiming a single fixed dream meaning.
+
+## Prototype Images
+
+Use these generated mockups as discussion references before implementation:
+
+- `docs/prototypes/2026-06-08-dream-qa-mobile-flow.png`
+- `docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png`
+- `docs/prototypes/2026-06-08-dream-qa-tips-card.png`
+
+## Product Shift
+
+Current docs emphasize:
+
+- Dream visitor.
+- Customs negotiation.
+- Permit ID.
+- Contraband.
+- Today's pact card.
+- Seal/revise pact actions.
+
+New direction should emphasize:
+
+- Dream question intake.
+- One clear uncertainty the user wants to understand.
+- 2-4 progressive follow-up questions.
+- A grounded interpretation draft that references specific dream details.
+- One final "today tip" with optional tiny action.
+- Safety note only when needed.
+
+Keep the good parts:
+
+- Text-only path must always work.
+- Image and voice can enrich the same intake object.
+- MiniCPM-V-4.6 remains the image clue extractor.
+- MiniCPM5-1B remains the main reasoning and generation model.
+- No diagnosis, prophecy, therapy framing, or fear-based copy.
+
+## Document Modification Plan
+
+### 1. `AGENTS.md`
+
+Rewrite the project positioning and product boundary sections.
+
+Change from:
+
+- "和昨晚的梦结盟"
+- "获得今日盟约卡"
+- required output fields such as `permit_id`, `contraband`, `risk_level`, `bedtime_release`
+
+Change to:
+
+- "循序渐进帮用户理解梦境疑惑"
+- final output is `today_tip` / `今日小 Tips`
+- required output fields:
+  - `dream_summary`
+  - `main_question`
+  - `followup_questions`
+  - `user_answers`
+  - `interpretation`
+  - `today_tip`
+  - `tiny_action`
+  - `caring_note`
+  - `safety_note`
+
+Also update manual acceptance:
+
+- Submit a dream.
+- App asks at least one useful follow-up question.
+- User can answer or skip.
+- Final result references concrete dream details and gives one today tip.
+- Output avoids diagnosis, prophecy, and medicalized advice.
+
+### 2. `docs/spec.md`
+
+Rewrite the product spec around a `DreamQuestionIntake -> DreamQAState -> TodayTipCard` flow.
+
+Needed edits:
+
+- Replace pact/card schema with Q&A schema.
+- Replace "MVP User Flow" with progressive steps:
+  1. User records dream.
+  2. User picks or writes the doubt they want answered.
+  3. Model asks a gentle follow-up.
+  4. User answers, skips, or asks for a different angle.
+  5. Model drafts an interpretation grounded in dream details.
+  6. Model produces one today tip.
+- Keep MiniCPM and multimodal constraints.
+- Add a rule that final advice must cite at least one dream anchor.
+
+### 3. `docs/prd.md`
+
+Update user stories and success criteria.
+
+New user stories:
+
+- Text dream Q&A.
+- Image-assisted dream clue extraction.
+- Voice dream capture.
+- Follow-up question flow.
+- Final Today Tip card.
+
+New success criteria:
+
+- User can complete a text-only Q&A in <= 90 seconds.
+- At least one follow-up question feels related to the dream.
+- Final tip references concrete dream details.
+- Ordinary cases never include diagnostic or frightening language.
+- Distress cases show support guidance.
+
+### 4. `PRODUCT.md`
+
+Rewrite product purpose and anti-references.
+
+Keep:
+
+- Gentle, strange, lucid.
+- Mobile-first morning use.
+- Not therapy.
+
+Change:
+
+- Reduce customs clerk metaphor.
+- Use "dream companion / question guide" framing.
+- Keep playful language, but make the experience easier for ordinary users to understand.
+- Anti-reference should include generic healing app output, not only plain Gradio/tarot/therapy.
+
+### 5. `DESIGN.md`
+
+Update the north star from "Morning Customs Desk" to a softer Q&A interface.
+
+Needed design changes:
+
+- Primary screen is a conversational Q&A flow with a visible stepper: record, ask, interpret, tip.
+- Right-side desktop panel becomes "interpretation draft / today tip preview", not "pact inspector".
+- Mobile final screen should prioritize Today Tip first, then optional explanation.
+- Keep high contrast, 8-12px radii, readable controls, and no purple AI SaaS theme.
+
+### 6. `docs/handoff.md`
+
+Rewrite handoff as the source of truth for the refactor.
+
+Needed edits:
+
+- Mark current V4 customs flow as deprecated context.
+- List the new Q&A flow and schema.
+- Identify files likely to change:
+  - `dream_customs/schema.py`
+  - `dream_customs/prompts.py`
+  - `dream_customs/pipeline.py`
+  - `dream_customs/render.py`
+  - `dream_customs/ui/app.py`
+  - `dream_customs/ui/copy.py`
+  - `dream_customs/ui/styles.py`
+  - tests covering schema, prompts, pipeline, UI actions, and safety
+- Preserve Modal/HF deployment constraints.
+
+### 7. `README.md`
+
+Update public-facing positioning after implementation is ready.
+
+Needed edits:
+
+- Short description should shift from "pact" to "guided dream Q&A".
+- Usage section should show:
+  - enter dream
+  - answer follow-up
+  - receive today tip
+- Keep model and deployment details accurate.
+
+### 8. Existing execution plans
+
+Do not rewrite old completed plan files as if they never happened.
+
+Add a new implementation plan instead:
+
+- `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md`
+
+That plan should include code steps, tests, local Gradio verification, GitHub push, and HF Space sync/merge path.
+
+## Implementation Acceptance Targets
+
+- Text-only path works with no image/audio.
+- Image upload contributes visual clues to the Q&A.
+- Voice transcript, when available, contributes to the same state.
+- User can answer or skip follow-up questions.
+- Final output has exactly one primary today tip.
+- Final output includes a concrete dream anchor.
+- Ordinary output avoids diagnosis, therapy claims, prophecy, and fear.
+- Severe distress triggers support guidance.
+- Mobile width remains readable.
+- `python -m pytest -q` passes.
+- Local Gradio smoke passes before Space sync.
+

docs/superpowers/plans/2026-06-08-dream-qa-refactor.md

@@ -0,0 +1,195 @@
+# Dream QA Refactor Implementation Plan
+
+Last updated: 2026-06-08
+
+## Goal
+
+Refactor the current Dream Customs Gradio app into Dream QA / 梦境问答台: a step-by-step dream interpretation app that records a dream, asks gentle follow-up questions, drafts a grounded interpretation, and ends with one Today Tip.
+
+## Source Of Truth
+
+Read before implementation:
+
+1. `AGENTS.md`
+2. `docs/handoff.md`
+3. `docs/spec.md`
+4. `docs/prd.md`
+5. `PRODUCT.md`
+6. `DESIGN.md`
+7. `docs/superpowers/plans/2026-06-08-dream-qa-refactor-doc-plan.md`
+
+Prototype references:
+
+- `docs/prototypes/2026-06-08-dream-qa-mobile-flow.png`
+- `docs/prototypes/2026-06-08-dream-qa-desktop-workbench.png`
+- `docs/prototypes/2026-06-08-dream-qa-tips-card.png`
+
+## Non-Goals
+
+- Do not rebuild the whole repo from scratch.
+- Do not change model family away from MiniCPM.
+- Do not implement voice output.
+- Do not build account, history, therapy plan, or diagnosis flows.
+- Do not preserve permit/contraband/sealed pact as required user-facing fields.
+
+## Task 1: Schema And State
+
+Files:
+
+- `dream_customs/schema.py`
+- `tests/test_schema.py`
+
+Steps:
+
+- Add or rename models for `DreamQuestionIntake`, `DreamQAState`, and `TodayTipCard`.
+- Keep compatibility wrappers only if needed to avoid breaking intermediate UI code.
+- Ensure final output has `dream_summary`, `main_question`, `dream_anchors`, `interpretation`, `today_tip`, `tiny_action`, `caring_note`, and `safety_note`.
+- Add tests for missing modalities, skipped answers, and required dream anchors.
+
+Verification:
+
+```bash
+python -m pytest tests/test_schema.py -q
+```
+
+## Task 2: Prompts And Safety
+
+Files:
+
+- `dream_customs/prompts.py`
+- `dream_customs/safety.py`
+- relevant prompt/safety tests
+
+Steps:
+
+- Replace pact/permit prompt language with Q&A language.
+- Add prompts for dream summary, main-question detection, follow-up questions, interpretation draft, and Today Tip.
+- Require non-certain language: "maybe", "could treat it as", "for today, try".
+- Require at least one dream anchor in final tips.
+- Preserve severe distress support copy.
+
+Verification:
+
+```bash
+python -m pytest tests/test_safety.py tests/test_pipeline.py -q
+```
+
+## Task 3: Pipeline Refactor
+
+Files:
+
+- `dream_customs/pipeline.py`
+- `dream_customs/models.py`
+- pipeline/model tests
+
+Steps:
+
+- Route all modalities into `DreamQuestionIntake`.
+- Add actions for record, answer, skip, ask another angle, interpret, and finish.
+- Keep deterministic fake clients as the default fallback path.
+- Repair generic model output so final tips cite dream anchors.
+- Ensure hosted Modal/Ollama route failures fall back safely.
+
+Verification:
+
+```bash
+python -m pytest tests/test_pipeline.py tests/test_ollama_models.py -q
+```
+
+## Task 4: Rendering And UI Copy
+
+Files:
+
+- `dream_customs/render.py`
+- `dream_customs/ui/copy.py`
+- render/copy tests
+
+Steps:
+
+- Render Today Tip cards instead of pact cards.
+- Prioritize one primary `today_tip`.
+- Include optional tiny action and caring note.
+- Keep safety note visible only when needed.
+- Remove visible permit/contraband/seal copy from current UI copy.
+
+Verification:
+
+```bash
+python -m pytest tests/test_render.py tests/test_ui_actions.py -q
+```
+
+## Task 5: Gradio UI
+
+Files:
+
+- `dream_customs/ui/app.py`
+- `dream_customs/ui/actions.py`
+- `dream_customs/ui/styles.py`
+- `app.py` only if needed
+
+Steps:
+
+- Build the visible flow around Record -> Ask -> Interpret -> Tip.
+- Keep text, image, voice, mood, and primary action in one composer.
+- Make follow-up questions answerable and skippable.
+- Keep developer/model routes collapsed by default.
+- Ensure 390px mobile readability.
+
+Verification:
+
+```bash
+python -m pytest tests/test_ui_actions.py -q
+python app.py
+```
+
+Manual smoke:
+
+- Submit a text-only dream.
+- Answer or skip one follow-up.
+- Reach a Today Tip card.
+- Confirm the tip references dream details.
+- Confirm no diagnosis, prophecy, or frightening certainty appears.
+
+## Task 6: Docs And Deployment
+
+Files:
+
+- `README.md`
+- `docs/handoff.md`
+- `docs/smoke/<new-smoke-file>.md`
+
+Steps:
+
+- Update any implementation-specific docs after code lands.
+- Record local pytest and Gradio smoke.
+- Commit and push the feature branch.
+- Sync to Hugging Face Space through the safest available path.
+
+Verification:
+
+```bash
+python -m pytest -q
+git diff --check
+git remote -v
+```
+
+HF Space sync rules:
+
+- Confirm `space` remote is `https://huggingface.co/spaces/build-small-hackathon/dream-customs`.
+- Do not print or save any token.
+- If direct push or API merge returns 403, create/leave a Space PR and report the exact blocker.
+- Do not force overwrite public `main` without explicit user confirmation.
+
+## Acceptance Criteria
+
+- Text-only path works with no image/audio.
+- Image upload contributes visual clues to the Q&A.
+- Voice transcript, when available, contributes to the same state.
+- User can answer or skip follow-up questions.
+- Final output has exactly one primary today tip.
+- Final output includes a concrete dream anchor.
+- Ordinary output avoids diagnosis, therapy claims, prophecy, and fear.
+- Severe distress triggers support guidance.
+- Mobile width remains readable.
+- `python -m pytest -q` passes.
+- Local Gradio smoke passes before Space sync.

docs/superpowers/plans/2026-06-08-model-led-pact-v2.md

@@ -0,0 +1,1357 @@
+# Model-Led Pact V2 Implementation Plan
+
+> Superseded on 2026-06-08: this plan records the earlier pact/card direction. New work should follow `docs/superpowers/plans/2026-06-08-dream-qa-refactor.md`, where the target is Record -> Ask -> Interpret -> Today Tip.
+
+> **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 Dream Customs generate natural English demo cards by letting MiniCPM5-1B own briefing, drafting, and critique while MiniCPM-V-4.6 contributes richer visual witness evidence.
+
+**Architecture:** Keep the public Hugging Face Space and Modal-hosted MiniCPM endpoints unchanged. Add a model-led generation path that builds a structured `DreamBrief`, drafts a `PactCard`, asks the text model to critique and rewrite weak output, and uses deterministic guards only for schema, safety, grammar, and fallback resilience. Upgrade vision output from flat clues to a witness report that still feeds the existing `DreamIntake.visual_clues` fallback path.
+
+**Tech Stack:** Python, Pydantic, Gradio, pytest, MiniCPM5-1B hosted text route, MiniCPM-V-4.6 hosted vision route, existing Modal/HF Space deployment flow.
+
+---
+
+## File Structure
+
+- Modify `dream_customs/schema.py`: add `VisionWitness`, `DreamBrief`, and `PactCritique` models without breaking existing `DreamIntake`, `PactCard`, or `CustomsSession` serialization.
+- Modify `dream_customs/prompts.py`: add prompts for visual witness reports, dream briefs, pact drafts, pact critique, and pact rewrite.
+- Modify `dream_customs/models.py`: add generic JSON generation methods and optional model-led methods on `FakeTextClient`, `OllamaTextClient`, `HostedMiniCPMTextClient`, `FakeVisionClient`, `OllamaVisionClient`, and `HostedMiniCPMVisionClient`.
+- Modify `dream_customs/pipeline.py`: add the model-led pact flow, English grammar guards, and a fallback path that preserves the current text-only demo behavior.
+- Modify `dream_customs/app_logic.py` and `dream_customs/ui/actions.py` only if needed to route richer debug data; do not add visible developer jargon to the public mobile flow.
+- Create `tests/test_model_led_pact.py`: focused tests for brief, critique, rewrite, grammar cleanup, and the screenshot elevator regression.
+- Create `tests/test_vision_witness.py`: focused tests for MiniCPM-V witness parsing and fallback clues.
+- Create `tests/fixtures/demo_eval_cases.json`: ten English-demo quality cases used by a local evaluation script.
+- Create `scripts/evaluate_demo_quality.py`: deterministic quality checks for the ten demo cases.
+- Create `docs/smoke/2026-06-08-model-led-pact-v2-smoke.md`: record local and live Space acceptance evidence after implementation.
+
+## Task 0: Baseline And Branch Hygiene
+
+**Files:**
+- Read: `AGENTS.md`
+- Read: `PRODUCT.md`
+- Read: `docs/spec.md`
+- Read: `docs/handoff.md`
+- Read: `docs/superpowers/plans/2026-06-08-dream-customs-story-ux-polish.md`
+- Verify: git branch and remotes
+
+- [ ] **Step 1: Confirm repository and branch**
+
+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
+```
+
+- [ ] **Step 2: Sync latest code**
+
+Run:
+
+```bash
+git pull
+```
+
+Expected:
+
+```text
+Already up to date.
+```
+
+- [ ] **Step 3: Run baseline tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all existing tests pass before the model-led changes begin.
+
+## Task 1: Add Model-Led Data Contracts
+
+**Files:**
+- Modify: `dream_customs/schema.py`
+- Modify: `tests/test_schema.py`
+
+- [ ] **Step 1: Add failing schema tests**
+
+Append to `tests/test_schema.py`:
+
+```python
+from dream_customs.schema import DreamBrief, PactCritique, VisionWitness
+
+
+def test_vision_witness_flattens_report_into_demo_clues():
+    witness = VisionWitness(
+        scene_summary="A hand-drawn elevator panel is stuck on floor 14.",
+        objects=["elevator button", "wax"],
+        visible_text=["14"],
+        spatial_relations=["button below the frozen number"],
+        mood_cues=["stuck", "cold"],
+        uncertain_details=["whether the floor is a basement"],
+        surprising_detail="The buttons look melted rather than broken.",
+    )
+
+    clues = witness.to_visual_clues()
+
+    assert clues[0] == "Scene: A hand-drawn elevator panel is stuck on floor 14."
+    assert "Object: elevator button" in clues
+    assert "Visible text: 14" in clues
+    assert "Surprising detail: The buttons look melted rather than broken." in clues
+
+
+def test_dream_brief_carries_evidence_and_demo_language():
+    brief = DreamBrief(
+        anchors=["elevator", "melted wax", "floor 14"],
+        emotional_hypothesis="The dream may be protecting a fear of getting stuck.",
+        today_bridge="Choose one stalled task and name the next small movement.",
+        visual_evidence=["Visible text: 14"],
+        safety_flags=[],
+        language="en",
+    )
+
+    assert brief.language == "en"
+    assert "floor 14" in brief.anchors
+    assert brief.visual_evidence == ["Visible text: 14"]
+
+
+def test_pact_critique_flags_template_and_grammar_failures():
+    critique = PactCritique(
+        passes=False,
+        issues=["repeated article", "template fallback"],
+        rewrite_instruction="Rewrite in natural English using elevator, wax, and floor 14.",
+    )
+
+    assert not critique.passes
+    assert "repeated article" in critique.issues
+    assert "natural English" in critique.rewrite_instruction
+```
+
+- [ ] **Step 2: Run schema tests and verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_schema.py::test_vision_witness_flattens_report_into_demo_clues tests/test_schema.py::test_dream_brief_carries_evidence_and_demo_language tests/test_schema.py::test_pact_critique_flags_template_and_grammar_failures -q
+```
+
+Expected: FAIL with import errors for `VisionWitness`, `DreamBrief`, and `PactCritique`.
+
+- [ ] **Step 3: Implement schema models**
+
+Add to `dream_customs/schema.py` after `DreamIntake`:
+
+```python
+class VisionWitness(BaseModel):
+    scene_summary: str = ""
+    objects: list[str] = Field(default_factory=list)
+    visible_text: list[str] = Field(default_factory=list)
+    spatial_relations: list[str] = Field(default_factory=list)
+    mood_cues: list[str] = Field(default_factory=list)
+    uncertain_details: list[str] = Field(default_factory=list)
+    surprising_detail: str = ""
+
+    def to_visual_clues(self) -> list[str]:
+        clues: list[str] = []
+        if self.scene_summary.strip():
+            clues.append(f"Scene: {self.scene_summary.strip()}")
+        for label, values in [
+            ("Object", self.objects),
+            ("Visible text", self.visible_text),
+            ("Spatial relation", self.spatial_relations),
+            ("Mood cue", self.mood_cues),
+            ("Uncertain detail", self.uncertain_details),
+        ]:
+            clues.extend(f"{label}: {value.strip()}" for value in values if value.strip())
+        if self.surprising_detail.strip():
+            clues.append(f"Surprising detail: {self.surprising_detail.strip()}")
+        return clues[:12]
+
+
+class DreamBrief(BaseModel):
+    anchors: list[str] = Field(default_factory=list)
+    emotional_hypothesis: str = ""
+    today_bridge: str = ""
+    visual_evidence: list[str] = Field(default_factory=list)
+    safety_flags: list[str] = Field(default_factory=list)
+    language: str = "en"
+
+
+class PactCritique(BaseModel):
+    passes: bool = True
+    issues: list[str] = Field(default_factory=list)
+    rewrite_instruction: str = ""
+```
+
+- [ ] **Step 4: Run schema tests and verify pass**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_schema.py::test_vision_witness_flattens_report_into_demo_clues tests/test_schema.py::test_dream_brief_carries_evidence_and_demo_language tests/test_schema.py::test_pact_critique_flags_template_and_grammar_failures -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit schema contracts**
+
+Run:
+
+```bash
+git add dream_customs/schema.py tests/test_schema.py
+git commit -m "feat: add model-led pact schemas"
+```
+
+Expected: commit succeeds.
+
+## Task 2: Add English Demo Prompt Contracts
+
+**Files:**
+- Modify: `dream_customs/prompts.py`
+- Create: `tests/test_model_led_pact.py`
+- Create: `tests/test_vision_witness.py`
+
+- [ ] **Step 1: Add failing prompt tests**
+
+Create `tests/test_model_led_pact.py` with:
+
+```python
+from dream_customs.pipeline import build_intake
+from dream_customs.prompts import dream_brief_prompt, pact_critique_prompt, pact_draft_prompt, pact_rewrite_prompt
+from dream_customs.schema import DreamBrief, PactCard, PactCritique
+
+
+def test_dream_brief_prompt_requires_english_demo_brief():
+    intake = build_intake(
+        dream_text="I kept missing an elevator. The buttons melted like wax, and floor 14 froze.",
+        visual_clues=["Visible text: 14", "Object: melted button"],
+        mood="Uneasy",
+    )
+
+    prompt = dream_brief_prompt(intake)
+
+    assert "English demo" in prompt
+    assert "anchors" in prompt
+    assert "visual_evidence" in prompt
+    assert "Do not diagnose" in prompt
+
+
+def test_pact_draft_prompt_uses_brief_not_template_fallback():
+    brief = DreamBrief(
+        anchors=["elevator", "melted wax", "floor 14"],
+        emotional_hypothesis="The dream may be protecting a fear of getting stuck.",
+        today_bridge="Choose one stalled task and name the next small movement.",
+        visual_evidence=["Visible text: 14"],
+    )
+
+    prompt = pact_draft_prompt(brief, "I want to stop freezing before a task.")
+
+    assert "Write natural English" in prompt
+    assert "Use at least two anchors" in prompt
+    assert "Do not use template phrases" in prompt
+    assert "elevator" in prompt
+
+
+def test_pact_critique_prompt_checks_screenshot_regression():
+    card = PactCard(
+        visitor_name="An Elevator",
+        permit_id="DREAM20260608-015",
+        contraband=["melted buttons", "froze at 14"],
+        risk_level="medium: handle gently, without treating it as a warning sign",
+        alliance_reading="I am safe, but the wax is sticky and the floor is cold.",
+        practical_suggestion="Pick one real task that feels like the an elevator.",
+        weird_task="I will try to push the floor button with my hand instead of the lever.",
+        bedtime_release="Tonight, the an elevator and the the button are logged.",
+    )
+    brief = DreamBrief(anchors=["elevator", "melted wax", "floor 14"])
+
+    prompt = pact_critique_prompt(brief, card)
+
+    assert "the an" in prompt
+    assert "the the" in prompt
+    assert "invented details" in prompt
+    assert "natural English" in prompt
+
+
+def test_pact_rewrite_prompt_uses_critique_instruction():
+    card = PactCard(
+        visitor_name="An Elevator",
+        permit_id="DREAM20260608-015",
+        contraband=["melted buttons", "froze at 14"],
+        risk_level="medium: handle gently, without treating it as a warning sign",
+        alliance_reading="I am safe, but the wax is sticky and the floor is cold.",
+        practical_suggestion="Pick one real task that feels like the an elevator.",
+        weird_task="I will try to push the floor button with my hand instead of the lever.",
+        bedtime_release="Tonight, the an elevator and the the button are logged.",
+    )
+    brief = DreamBrief(anchors=["elevator", "melted wax", "floor 14"])
+    critique = PactCritique(
+        passes=False,
+        issues=["repeated article", "invented lever"],
+        rewrite_instruction="Rewrite without repeated articles or invented lever details.",
+    )
+
+    prompt = pact_rewrite_prompt(brief, card, critique)
+
+    assert "Rewrite without repeated articles" in prompt
+    assert "Return strict JSON" in prompt
+    assert "floor 14" in prompt
+```
+
+Create `tests/test_vision_witness.py` with:
+
+```python
+from dream_customs.prompts import visual_witness_prompt
+
+
+def test_visual_witness_prompt_requests_structured_report():
+    prompt = visual_witness_prompt()
+
+    assert "MiniCPM-V-4.6" in prompt
+    assert "scene_summary" in prompt
+    assert "spatial_relations" in prompt
+    assert "surprising_detail" in prompt
+    assert "Do not diagnose" in prompt
+```
+
+- [ ] **Step 2: Run prompt tests and verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py tests/test_vision_witness.py -q
+```
+
+Expected: FAIL with import errors for the new prompt functions.
+
+- [ ] **Step 3: Implement new prompt functions**
+
+Add to `dream_customs/prompts.py`:
+
+```python
+from dream_customs.schema import DreamBrief, PactCard, PactCritique
+
+
+def visual_witness_prompt() -> str:
+    return """
+You are MiniCPM-V-4.6 acting as the witness clerk at Dream Customs.
+Read the image as dream evidence: a sketch, bedside note, screenshot, or photo.
+Do not diagnose the user. Do not infer a fixed symbolic meaning.
+Return strict JSON with:
+scene_summary, objects, visible_text, spatial_relations, mood_cues,
+uncertain_details, surprising_detail.
+Keep each list item short, concrete, and visibly grounded in the image.
+""".strip()
+
+
+def dream_brief_prompt(intake: DreamIntake) -> str:
+    return f"""
+You are MiniCPM5-1B preparing an English demo brief for Dream Customs.
+Do not diagnose. Do not claim the dream has one certain meaning.
+Turn the intake into a compact reasoning brief that a later writer can use.
+Return strict JSON with:
+anchors, emotional_hypothesis, today_bridge, visual_evidence, safety_flags, language.
+
+Rules:
+- language must be "en".
+- anchors must be concrete dream details, not generic feelings.
+- visual_evidence must reuse image clues when present.
+- today_bridge must connect the dream to one realistic action for today.
+- safety_flags is empty unless the user mentions self-harm, harming others,
+  severe distress, severe insomnia, panic, or inability to function.
+
+Dream intake:
+{intake.merged_text()}
+""".strip()
+
+
+def pact_draft_prompt(brief: DreamBrief, answers: str) -> str:
+    return f"""
+You are the Dream Customs diplomat writing an English demo clearance pass.
+Write natural English. Keep the tone gentle, playful, and useful.
+Do not use template phrases such as "feels like the", "logged and cleared",
+or "the dream may be pointing to" unless they fit naturally.
+Use at least two anchors from the brief. Use at least one visual_evidence item
+when visual evidence is present. Do not invent objects or actions.
+Return strict JSON with:
+visitor_name, permit_id, contraband, risk_level, alliance_reading,
+practical_suggestion, weird_task, bedtime_release, safety_note.
+
+Dream brief:
+{brief.model_dump_json()}
+
+User answers:
+{answers or "No answers filed."}
+""".strip()
+
+
+def pact_critique_prompt(brief: DreamBrief, card: PactCard) -> str:
+    return f"""
+You are the Dream Customs quality critic for an English demo card.
+Check for repeated articles such as "the an" and "the the", awkward grammar,
+template fallback language, invented details, diagnosis, frightening certainty,
+generic wellness advice, and missing dream anchors.
+Return strict JSON with:
+passes, issues, rewrite_instruction.
+If the card is already natural, specific, safe, and grounded, passes must be true
+and rewrite_instruction must be an empty string.
+
+Dream brief:
+{brief.model_dump_json()}
+
+Draft card:
+{card.model_dump_json()}
+""".strip()
+
+
+def pact_rewrite_prompt(brief: DreamBrief, card: PactCard, critique: PactCritique) -> str:
+    return f"""
+You are the Dream Customs diplomat revising an English demo clearance pass.
+Follow the critique exactly while preserving safe, playful, non-diagnostic tone.
+Use at least two real anchors from the brief. Do not add objects that are not in
+the brief or current card. Return strict JSON with:
+visitor_name, permit_id, contraband, risk_level, alliance_reading,
+practical_suggestion, weird_task, bedtime_release, safety_note.
+
+Dream brief:
+{brief.model_dump_json()}
+
+Current card:
+{card.model_dump_json()}
+
+Critique:
+{critique.model_dump_json()}
+""".strip()
+```
+
+- [ ] **Step 4: Run prompt tests and verify pass**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py tests/test_vision_witness.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit prompt contracts**
+
+Run:
+
+```bash
+git add dream_customs/prompts.py tests/test_model_led_pact.py tests/test_vision_witness.py
+git commit -m "feat: add model-led pact prompts"
+```
+
+Expected: commit succeeds.
+
+## Task 3: Add Model-Led Client Methods
+
+**Files:**
+- Modify: `dream_customs/models.py`
+- Modify: `tests/test_ollama_models.py`
+- Modify: `tests/test_model_led_pact.py`
+- Modify: `tests/test_vision_witness.py`
+
+- [ ] **Step 1: Add failing client tests**
+
+Append to `tests/test_model_led_pact.py`:
+
+```python
+from dream_customs.models import FakeTextClient
+
+
+def test_fake_text_client_supports_model_led_methods():
+    client = FakeTextClient()
+
+    brief = client.generate_brief("brief prompt")
+    card = client.generate_pact_draft("draft prompt")
+    critique = client.critique_pact("critique prompt")
+
+    assert brief.language == "en"
+    assert brief.anchors
+    assert card.visitor_name
+    assert critique.passes
+```
+
+Append to `tests/test_vision_witness.py`:
+
+```python
+from dream_customs.models import FakeVisionClient
+
+
+def test_fake_vision_client_returns_witness_report():
+    witness = FakeVisionClient().extract_witness("demo.png")
+
+    assert witness.scene_summary
+    assert "blue hallway" in " ".join(witness.to_visual_clues()).lower()
+```
+
+Append to `tests/test_ollama_models.py`:
+
+```python
+from dream_customs.schema import DreamBrief, PactCritique, VisionWitness
+
+
+def test_hosted_text_client_parses_model_led_brief():
+    class StubHostedBriefClient(HostedMiniCPMTextClient):
+        def _post_json(self, prompt, max_tokens=700):
+            return {
+                "response": (
+                    '{"anchors":["elevator","melted wax","floor 14"],'
+                    '"emotional_hypothesis":"The dream may be protecting a stuck feeling.",'
+                    '"today_bridge":"Name one next movement.",'
+                    '"visual_evidence":["Visible text: 14"],'
+                    '"safety_flags":[],"language":"en"}'
+                )
+            }
+
+    brief = StubHostedBriefClient(endpoint="https://example.test").generate_brief("prompt")
+
+    assert isinstance(brief, DreamBrief)
+    assert brief.anchors == ["elevator", "melted wax", "floor 14"]
+
+
+def test_hosted_text_client_parses_pact_critique():
+    class StubHostedCritiqueClient(HostedMiniCPMTextClient):
+        def _post_json(self, prompt, max_tokens=700):
+            return {
+                "response": (
+                    '{"passes":false,'
+                    '"issues":["repeated article"],'
+                    '"rewrite_instruction":"Fix repeated articles."}'
+                )
+            }
+
+    critique = StubHostedCritiqueClient(endpoint="https://example.test").critique_pact("prompt")
+
+    assert isinstance(critique, PactCritique)
+    assert not critique.passes
+
+
+def test_hosted_vision_client_parses_witness_report():
+    class StubHostedVisionWitnessClient(HostedMiniCPMVisionClient):
+        def _post_image(self, image_path):
+            return {
+                "response": (
+                    '{"scene_summary":"A blue hallway with a frozen elevator panel.",'
+                    '"objects":["elevator button"],'
+                    '"visible_text":["14"],'
+                    '"spatial_relations":["button below number"],'
+                    '"mood_cues":["cold"],'
+                    '"uncertain_details":[],' 
+                    '"surprising_detail":"The button looks waxy."}'
+                )
+            }
+
+    witness = StubHostedVisionWitnessClient(endpoint="https://example.test").extract_witness("demo.png")
+
+    assert isinstance(witness, VisionWitness)
+    assert "Visible text: 14" in witness.to_visual_clues()
+```
+
+- [ ] **Step 2: Run client tests and verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py::test_fake_text_client_supports_model_led_methods tests/test_vision_witness.py::test_fake_vision_client_returns_witness_report tests/test_ollama_models.py::test_hosted_text_client_parses_model_led_brief tests/test_ollama_models.py::test_hosted_text_client_parses_pact_critique tests/test_ollama_models.py::test_hosted_vision_client_parses_witness_report -q
+```
+
+Expected: FAIL because the client methods are not implemented.
+
+- [ ] **Step 3: Implement fake client methods**
+
+In `dream_customs/models.py`, import the new schemas:
+
+```python
+from dream_customs.schema import DreamBrief, PactCard, PactCritique, VisionWitness
+```
+
+Add to `FakeTextClient`:
+
+```python
+    def generate_brief(self, prompt: str) -> DreamBrief:
+        return DreamBrief(
+            anchors=["elevator", "melted buttons", "floor 14"],
+            emotional_hypothesis="The dream may be protecting the user from freezing at the start of a task.",
+            today_bridge="Choose one stalled task and name the next small movement.",
+            visual_evidence=["Visible text: 14"],
+            safety_flags=[],
+            language="en",
+        )
+
+    def generate_pact_draft(self, prompt: str) -> PactCard:
+        return self.generate_pact(prompt)
+
+    def critique_pact(self, prompt: str) -> PactCritique:
+        return PactCritique(passes=True, issues=[], rewrite_instruction="")
+
+    def rewrite_pact(self, prompt: str) -> PactCard:
+        return self.generate_pact(prompt)
+```
+
+Add to `FakeVisionClient`:
+
+```python
+    def extract_witness(self, image_path: Optional[str]) -> VisionWitness:
+        if not image_path:
+            return VisionWitness()
+        return VisionWitness(
+            scene_summary="A blue hallway with a melted elevator button.",
+            objects=["elevator button", "blue hallway"],
+            visible_text=["14"],
+            spatial_relations=["button near the frozen floor number"],
+            mood_cues=["stuck", "uncertain"],
+            uncertain_details=[],
+            surprising_detail="The button looks soft, almost waxy.",
+        )
+```
+
+- [ ] **Step 4: Implement hosted and Ollama model-led text parsing**
+
+Add helper methods to `HostedMiniCPMTextClient` and mirror the same signatures in `OllamaTextClient`:
+
+```python
+    def generate_brief(self, prompt: str) -> DreamBrief:
+        parsed = self._generate_json(
+            prompt,
+            (
+                '{"anchors":["string"],"emotional_hypothesis":"string",'
+                '"today_bridge":"string","visual_evidence":["string"],'
+                '"safety_flags":["string"],"language":"en"}'
+            ),
+            max_tokens=520,
+        )
+        if not parsed:
+            return self.fallback.generate_brief(prompt)
+        try:
+            return DreamBrief(
+                anchors=_as_string_list(parsed.get("anchors")),
+                emotional_hypothesis=str(parsed.get("emotional_hypothesis", "")).strip(),
+                today_bridge=str(parsed.get("today_bridge", "")).strip(),
+                visual_evidence=_as_string_list(parsed.get("visual_evidence")),
+                safety_flags=_as_string_list(parsed.get("safety_flags")),
+                language=str(parsed.get("language", "en")).strip() or "en",
+            )
+        except (TypeError, ValueError):
+            return self.fallback.generate_brief(prompt)
+
+    def generate_pact_draft(self, prompt: str) -> PactCard:
+        return self.generate_pact(prompt)
+
+    def critique_pact(self, prompt: str) -> PactCritique:
+        parsed = self._generate_json(
+            prompt,
+            '{"passes":true,"issues":["string"],"rewrite_instruction":"string"}',
+            max_tokens=360,
+        )
+        if not parsed:
+            return self.fallback.critique_pact(prompt)
+        return PactCritique(
+            passes=bool(parsed.get("passes", True)),
+            issues=_as_string_list(parsed.get("issues")),
+            rewrite_instruction=str(parsed.get("rewrite_instruction", "")).strip(),
+        )
+
+    def rewrite_pact(self, prompt: str) -> PactCard:
+        return self.generate_pact(prompt)
+```
+
+For `OllamaTextClient`, use the same body but pass `num_predict` instead of `max_tokens` in `_generate_json()` calls.
+
+- [ ] **Step 5: Implement hosted and Ollama vision witness parsing**
+
+Add to `HostedMiniCPMVisionClient` and mirror the same method in `OllamaVisionClient`:
+
+```python
+    def extract_witness(self, image_path: Optional[str]) -> VisionWitness:
+        if not image_path:
+            return VisionWitness()
+        payload = self._post_image(image_path)
+        if not payload:
+            return self.fallback.extract_witness(image_path)
+        parsed = _extract_json_object(_hosted_text_from_response(payload))
+        if not parsed:
+            text = _hosted_text_from_response(payload)
+            clues = [part.strip() for part in re.split(r"[,，\n]", _strip_markdown_and_thinking(text)) if part.strip()]
+            return VisionWitness(scene_summary="; ".join(clues[:2]), objects=clues[2:6])
+        return VisionWitness(
+            scene_summary=str(parsed.get("scene_summary", "")).strip(),
+            objects=_as_string_list(parsed.get("objects")),
+            visible_text=_as_string_list(parsed.get("visible_text")),
+            spatial_relations=_as_string_list(parsed.get("spatial_relations")),
+            mood_cues=_as_string_list(parsed.get("mood_cues")),
+            uncertain_details=_as_string_list(parsed.get("uncertain_details")),
+            surprising_detail=str(parsed.get("surprising_detail", "")).strip(),
+        )
+```
+
+Update `extract_clues()` to call `extract_witness(image_path).to_visual_clues()` first, then fall back to the old flat parsing if the witness is empty.
+
+- [ ] **Step 6: Run client tests and verify pass**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py::test_fake_text_client_supports_model_led_methods tests/test_vision_witness.py::test_fake_vision_client_returns_witness_report tests/test_ollama_models.py::test_hosted_text_client_parses_model_led_brief tests/test_ollama_models.py::test_hosted_text_client_parses_pact_critique tests/test_ollama_models.py::test_hosted_vision_client_parses_witness_report -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit client methods**
+
+Run:
+
+```bash
+git add dream_customs/models.py tests/test_model_led_pact.py tests/test_vision_witness.py tests/test_ollama_models.py
+git commit -m "feat: add model-led MiniCPM clients"
+```
+
+Expected: commit succeeds.
+
+## Task 4: Route The Model-Led Pact Flow
+
+**Files:**
+- Modify: `dream_customs/pipeline.py`
+- Modify: `tests/test_model_led_pact.py`
+- Modify: `tests/test_pipeline.py`
+
+- [ ] **Step 1: Add failing model-led flow regression**
+
+Append to `tests/test_model_led_pact.py`:
+
+```python
+from dream_customs.pipeline import build_intake, generate_model_led_pact
+
+
+def test_model_led_pact_rewrites_screenshot_elevator_regression():
+    class CriticTextClient(FakeTextClient):
+        def generate_pact_draft(self, prompt):
+            return PactCard(
+                visitor_name="An Elevator",
+                permit_id="DREAM20260608-015",
+                contraband=["melted buttons", "froze at 14"],
+                risk_level="medium: handle gently, without treating it as a warning sign",
+                alliance_reading="I am safe, but the wax is sticky and the floor is cold.",
+                practical_suggestion="Pick one real task that feels like the an elevator.",
+                weird_task="I will try to push the floor button with my hand instead of the lever.",
+                bedtime_release="Tonight, the an elevator and the the button are logged.",
+            )
+
+        def critique_pact(self, prompt):
+            return PactCritique(
+                passes=False,
+                issues=["repeated article", "invented lever"],
+                rewrite_instruction="Rewrite without repeated articles or the invented lever.",
+            )
+
+        def rewrite_pact(self, prompt):
+            return PactCard(
+                visitor_name="The Elevator Stuck at 14",
+                permit_id="DREAM20260608-015",
+                contraband=["melted buttons", "floor 14", "the urge to freeze before starting"],
+                risk_level="medium: handle gently, without treating it as a warning sign",
+                alliance_reading=(
+                    "The elevator, wax-soft buttons, and frozen 14 can be treated as a small scene "
+                    "about getting stuck before the first move."
+                ),
+                practical_suggestion="Choose one stalled task and write only the next button-sized action.",
+                weird_task="Draw floor 14 on a sticky note, tap it once, and spend five minutes on the first step.",
+                bedtime_release="Tonight, the elevator can stay on floor 14 while tomorrow's first button waits quietly.",
+            )
+
+    intake = build_intake(
+        dream_text="I kept missing an elevator. The buttons melted like wax, and the floor number froze at 14.",
+        visual_clues=["Visible text: 14", "Object: melted elevator button"],
+        mood="Uneasy",
+    )
+
+    card, html = generate_model_led_pact(intake, "", CriticTextClient())
+    joined = card.to_plain_text().lower()
+
+    assert "the an" not in joined
+    assert "the the" not in joined
+    assert "lever" not in joined
+    assert "floor 14" in joined
+    assert "melted" in joined or "wax" in joined
+    assert "Today's Clearance Pass" in html or "Today's Pact" in html
+```
+
+- [ ] **Step 2: Run model-led flow test and verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py::test_model_led_pact_rewrites_screenshot_elevator_regression -q
+```
+
+Expected: FAIL because `generate_model_led_pact` does not exist.
+
+- [ ] **Step 3: Implement grammar guard helpers**
+
+Add to `dream_customs/pipeline.py`:
+
+```python
+def _clean_repeated_articles(text: str) -> str:
+    clean = re.sub(r"\bthe\s+an\s+", "an ", text, flags=re.IGNORECASE)
+    clean = re.sub(r"\bthe\s+the\s+", "the ", clean, flags=re.IGNORECASE)
+    clean = re.sub(r"\ban\s+an\s+", "an ", clean, flags=re.IGNORECASE)
+    clean = re.sub(r"\ba\s+a\s+", "a ", clean, flags=re.IGNORECASE)
+    return re.sub(r"\s+", " ", clean).strip()
+
+
+def _clean_card_grammar(card: PactCard) -> PactCard:
+    cleaned = card.model_copy(deep=True)
+    cleaned.visitor_name = _clean_repeated_articles(cleaned.visitor_name)
+    cleaned.risk_level = _clean_repeated_articles(cleaned.risk_level)
+    cleaned.alliance_reading = _clean_repeated_articles(cleaned.alliance_reading)
+    cleaned.practical_suggestion = _clean_repeated_articles(cleaned.practical_suggestion)
+    cleaned.weird_task = _clean_repeated_articles(cleaned.weird_task)
+    cleaned.bedtime_release = _clean_repeated_articles(cleaned.bedtime_release)
+    cleaned.contraband = [_clean_repeated_articles(item) for item in cleaned.contraband]
+    return cleaned
+```
+
+- [ ] **Step 4: Implement `generate_model_led_pact`**
+
+Add imports to `dream_customs/pipeline.py`:
+
+```python
+from dream_customs.prompts import (
+    dream_brief_prompt,
+    followup_question_prompt,
+    negotiation_prompt,
+    pact_critique_prompt,
+    pact_draft_prompt,
+    pact_prompt,
+    pact_revision_prompt,
+    pact_rewrite_prompt,
+)
+```
+
+Add the function:
+
+```python
+def generate_model_led_pact(intake: DreamIntake, answers: str, text_client) -> Tuple[PactCard, str]:
+    brief = text_client.generate_brief(dream_brief_prompt(intake))
+    card = text_client.generate_pact_draft(pact_draft_prompt(brief, answers))
+    critique = text_client.critique_pact(pact_critique_prompt(brief, card))
+    if not critique.passes and critique.rewrite_instruction.strip():
+        card = text_client.rewrite_pact(pact_rewrite_prompt(brief, card, critique))
+    card = _clean_card_grammar(card)
+    card = _polish_card_for_daily_use(card, intake, answers)
+    merged = intake.merged_text() + "\n" + answers
+    if needs_escalation(merged):
+        card.safety_note = safety_note()
+    elif not needs_escalation(merged):
+        card.safety_note = ""
+    card = _stamp_card_for_today(card)
+    return card, render_pact_card(card)
+```
+
+- [ ] **Step 5: Route draft generation through model-led flow with fallback**
+
+Find the existing `draft_pact()` code path in `dream_customs/pipeline.py`. Replace its direct `generate_pact()` call with:
+
+```python
+    try:
+        card, _html = generate_model_led_pact(next_session.intake, next_session.answers_text(), text_client)
+    except AttributeError:
+        card, _html = generate_pact(next_session.intake, next_session.answers_text(), text_client)
+```
+
+Keep the existing session phase, events, and safety behavior unchanged around this block.
+
+- [ ] **Step 6: Run focused flow tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_model_led_pact.py::test_model_led_pact_rewrites_screenshot_elevator_regression tests/test_pipeline.py::test_ask_answer_skip_draft_revise_and_seal_actions -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Run all pipeline tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_pipeline.py tests/test_model_led_pact.py -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 8: Commit model-led flow**
+
+Run:
+
+```bash
+git add dream_customs/pipeline.py tests/test_model_led_pact.py tests/test_pipeline.py
+git commit -m "feat: route model-led pact generation"
+```
+
+Expected: commit succeeds.
+
+## Task 5: Upgrade Vision Intake To Witness Reports
+
+**Files:**
+- Modify: `dream_customs/pipeline.py`
+- Modify: `dream_customs/models.py`
+- Modify: `tests/test_vision_witness.py`
+- Modify: `tests/test_pipeline.py`
+
+- [ ] **Step 1: Add failing intake witness test**
+
+Append to `tests/test_vision_witness.py`:
+
+```python
+from dream_customs.models import FakeASRClient, FakeVisionClient
+from dream_customs.pipeline import intake_from_modalities
+
+
+def test_intake_from_modalities_uses_vision_witness_clues():
+    intake = intake_from_modalities(
+        dream_text="I was waiting for an elevator.",
+        image_path="demo.png",
+        audio_path=None,
+        mood="Uneasy",
+        vision_client=FakeVisionClient(),
+        asr_client=FakeASRClient(),
+    )
+
+    merged = intake.merged_text().lower()
+
+    assert "scene:" in merged
+    assert "visible text: 14" in merged
+    assert "surprising detail" in merged
+```
+
+- [ ] **Step 2: Run witness intake test and verify failure**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_vision_witness.py::test_intake_from_modalities_uses_vision_witness_clues -q
+```
+
+Expected: FAIL if `intake_from_modalities()` still calls only `extract_clues()`.
+
+- [ ] **Step 3: Add witness extraction helper**
+
+Add to `dream_customs/pipeline.py`:
+
+```python
+def _extract_visual_clues(vision_client, image_path: Optional[str]) -> List[str]:
+    if not image_path:
+        return []
+    try:
+        if hasattr(vision_client, "extract_witness"):
+            witness = vision_client.extract_witness(image_path)
+            clues = witness.to_visual_clues()
+            if clues:
+                return clues
+    except Exception:
+        pass
+    try:
+        return vision_client.extract_clues(image_path)
+    except Exception:
+        return []
+```
+
+Update `intake_from_modalities()`:
+
+```python
+    return build_intake(
+        dream_text=dream_text or "",
+        voice_transcript=asr_client.transcribe(audio_path),
+        visual_clues=_extract_visual_clues(vision_client, image_path),
+        mood=mood or "",
+        user_context=user_context,
+    )
+```
+
+- [ ] **Step 4: Keep text path alive when witness extraction fails**
+
+Append to `tests/test_pipeline.py`:
+
+```python
+def test_witness_failure_keeps_text_path_alive():
+    class BrokenWitnessVision:
+        def extract_witness(self, image_path):
+            raise RuntimeError("vision offline")
+
+        def extract_clues(self, image_path):
+            return ["fallback clue"]
+
+    intake = intake_from_modalities(
+        dream_text="Text still works.",
+        image_path="demo.png",
+        audio_path=None,
+        mood="Foggy",
+        vision_client=BrokenWitnessVision(),
+        asr_client=FakeASRClient(),
+    )
+
+    assert "Text still works." in intake.merged_text()
+    assert "fallback clue" in intake.merged_text()
+```
+
+- [ ] **Step 5: Run vision tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_vision_witness.py tests/test_pipeline.py::test_witness_failure_keeps_text_path_alive -q
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit witness routing**
+
+Run:
+
+```bash
+git add dream_customs/pipeline.py dream_customs/models.py tests/test_vision_witness.py tests/test_pipeline.py
+git commit -m "feat: use MiniCPM vision witness reports"
+```
+
+Expected: commit succeeds.
+
+## Task 6: Add English Demo Quality Evaluation
+
+**Files:**
+- Create: `tests/fixtures/demo_eval_cases.json`
+- Create: `scripts/evaluate_demo_quality.py`
+- Create: `tests/test_demo_quality_eval.py`
+
+- [ ] **Step 1: Add demo fixture cases**
+
+Create `tests/fixtures/demo_eval_cases.json`:
+
+```json
+[
+  {
+    "id": "elevator_wax_floor14",
+    "dream_text": "I kept missing an elevator. The buttons melted like wax, and the floor number froze at 14.",
+    "visual_clues": ["Visible text: 14", "Object: melted elevator button"],
+    "mood": "Uneasy",
+    "required_terms": ["elevator", "14"],
+    "banned_terms": ["the an", "the the", "lever", "diagnosis"]
+  },
+  {
+    "id": "customs_wet_paper",
+    "dream_text": "I was at a customs window carrying a suitcase full of wet paper. The clerk asked me to declare every unfinished promise before sunrise.",
+    "visual_clues": [],
+    "mood": "Foggy",
+    "required_terms": ["customs", "paper"],
+    "banned_terms": ["hydrate", "fruit", "prophecy", "diagnosis"]
+  },
+  {
+    "id": "exam_without_pencil",
+    "dream_text": "I arrived at an exam with no pencil, but everyone else was already writing.",
+    "visual_clues": [],
+    "mood": "Restless",
+    "required_terms": ["exam", "pencil"],
+    "banned_terms": ["medical", "fate", "the an"]
+  },
+  {
+    "id": "locked_green_room",
+    "dream_text": "I found a small green room behind my kitchen, but the door kept locking itself.",
+    "visual_clues": ["Color: green", "Object: small door"],
+    "mood": "Curious",
+    "required_terms": ["green", "door"],
+    "banned_terms": ["diagnosis", "warning sign", "the the"]
+  },
+  {
+    "id": "train_arrives_silent",
+    "dream_text": "A silent train arrived with my name written on a ticket, but I could not read the destination.",
+    "visual_clues": ["Visible text: user name on ticket"],
+    "mood": "Uneasy",
+    "required_terms": ["train", "ticket"],
+    "banned_terms": ["destiny", "prophecy", "the an"]
+  },
+  {
+    "id": "phone_full_of_water",
+    "dream_text": "My phone was full of water, but it kept ringing from inside a drawer.",
+    "visual_clues": [],
+    "mood": "Tired",
+    "required_terms": ["phone", "water"],
+    "banned_terms": ["hydration", "diagnosis", "the the"]
+  },
+  {
+    "id": "missing_shoes_stairwell",
+    "dream_text": "I was in a stairwell without shoes, holding a map that only showed blank squares.",
+    "visual_clues": ["Object: blank map", "Place: stairwell"],
+    "mood": "Foggy",
+    "required_terms": ["stairwell", "map"],
+    "banned_terms": ["fate", "medical", "the an"]
+  },
+  {
+    "id": "bedside_note_rain",
+    "dream_text": "A note on my bedside table said 'bring the rain inside', and the window was already open.",
+    "visual_clues": ["Visible text: bring the rain inside", "Object: open window"],
+    "mood": "Calm",
+    "required_terms": ["rain", "window"],
+    "banned_terms": ["diagnosis", "prophecy", "the the"]
+  },
+  {
+    "id": "voice_fragment_buttons",
+    "dream_text": "",
+    "voice_transcript": "The hallway was blue, and the elevator buttons were warm.",
+    "visual_clues": ["Color: blue"],
+    "mood": "Uneasy",
+    "required_terms": ["hallway", "buttons"],
+    "banned_terms": ["the an", "the the", "diagnosis"]
+  },
+  {
+    "id": "abstract_sketch_moon_key",
+    "dream_text": "I drew the dream because I only remember a moon-shaped key and a red square.",
+    "visual_clues": ["Object: moon-shaped key", "Color: red square"],
+    "mood": "Curious",
+    "required_terms": ["key", "red"],
+    "banned_terms": ["medical", "fate", "the an"]
+  }
+]
+```
+
+- [ ] **Step 2: Add evaluator tests**
+
+Create `tests/test_demo_quality_eval.py`:
+
+```python
+from scripts.evaluate_demo_quality import evaluate_text
+
+
+def test_evaluate_text_passes_grounded_english_card():
+    text = (
+        "The Elevator Stuck at 14. The melted buttons and frozen floor 14 can stand for "
+        "one stalled beginning. Choose one task and write the next button-sized action."
+    )
+
+    result = evaluate_text(text, required_terms=["elevator", "14"], banned_terms=["the an", "the the"])
+
+    assert result["passes"]
+    assert result["issues"] == []
+
+
+def test_evaluate_text_fails_repeated_articles_and_missing_anchor():
+    text = "Pick one real task that feels like the an elevator."
+
+    result = evaluate_text(text, required_terms=["floor 14"], banned_terms=["the an"])
+
+    assert not result["passes"]
+    assert "banned term: the an" in result["issues"]
+    assert "missing required term: floor 14" in result["issues"]
+```
+
+- [ ] **Step 3: Implement evaluator script**
+
+Create `scripts/evaluate_demo_quality.py`:
+
+```python
+import json
+from pathlib import Path
+from typing import Iterable
+
+
+def evaluate_text(text: str, required_terms: Iterable[str], banned_terms: Iterable[str]) -> dict:
+    lowered = text.lower()
+    issues: list[str] = []
+    for term in required_terms:
+        if term.lower() not in lowered:
+            issues.append(f"missing required term: {term}")
+    for term in banned_terms:
+        if term.lower() in lowered:
+            issues.append(f"banned term: {term}")
+    if any(marker in lowered for marker in ["you have depression", "this means you will", "certainly predicts"]):
+        issues.append("unsafe certainty or diagnosis")
+    return {"passes": not issues, "issues": issues}
+
+
+def load_cases(path: str = "tests/fixtures/demo_eval_cases.json") -> list[dict]:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def main() -> int:
+    cases = load_cases()
+    print(json.dumps({"case_count": len(cases), "ids": [case["id"] for case in cases]}, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+```
+
+- [ ] **Step 4: Run evaluator tests**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest tests/test_demo_quality_eval.py -q
+.venv/bin/python scripts/evaluate_demo_quality.py
+```
+
+Expected: pytest PASS; script prints `case_count` as `10`.
+
+- [ ] **Step 5: Commit evaluator**
+
+Run:
+
+```bash
+git add tests/fixtures/demo_eval_cases.json scripts/evaluate_demo_quality.py tests/test_demo_quality_eval.py
+git commit -m "test: add english demo quality eval cases"
+```
+
+Expected: commit succeeds.
+
+## Task 7: Full Verification, Local Smoke, And HF Space Sync
+
+**Files:**
+- Verify: all modified files
+- Create: `docs/smoke/2026-06-08-model-led-pact-v2-smoke.md`
+
+- [ ] **Step 1: Run full test suite**
+
+Run:
+
+```bash
+.venv/bin/python -m pytest -q
+```
+
+Expected: all tests pass.
+
+- [ ] **Step 2: Run whitespace check**
+
+Run:
+
+```bash
+git diff --check
+```
+
+Expected: no output.
+
+- [ ] **Step 3: Run local app smoke**
+
+Run:
+
+```bash
+GRADIO_SERVER_PORT=7862 .venv/bin/python app.py
+```
+
+Open `http://127.0.0.1:7862` and submit:
+
+```text
+I kept missing an elevator. The buttons melted like wax, and the floor number froze at 14.
+```
+
+Attach an image only if a local sketch is available. Seal the pass and verify:
+
+- The card is in polished English.
+- The card does not contain `the an`, `the the`, or invented `lever`.
+- The card mentions at least two of `elevator`, `melted buttons`, `wax`, and `floor 14`.
+- The practical suggestion is one real next step for today.
+- The weird task is playful, harmless, and grounded in the elevator or floor-14 image.
+- Mobile width remains readable.
+
+- [ ] **Step 4: Record smoke evidence**
+
+Create `docs/smoke/2026-06-08-model-led-pact-v2-smoke.md`:
+
+```markdown
+# Model-Led Pact V2 Smoke
+
+Date: 2026-06-08
+Branch: feature/dream-customs-ui-voice-settings
+
+## Local
+
+- Command: `.venv/bin/python -m pytest -q`
+- Result: PASS
+- Command: `git diff --check`
+- Result: PASS
+- Command: `GRADIO_SERVER_PORT=7862 .venv/bin/python app.py`
+- Result: PASS
+
+## Manual Demo Case
+
+Input:
+
+```text
+I kept missing an elevator. The buttons melted like wax, and the floor number froze at 14.
+```
+
+Acceptance:
+
+- Natural English card: PASS
+- No repeated article regression: PASS
+- No invented lever detail: PASS
+- Uses at least two dream details: PASS
+- Practical suggestion is actionable: PASS
+- Weird task is harmless and dream-grounded: PASS
+- Mobile readable: PASS
+
+## Hugging Face Space
+
+- Push target checked: `space https://huggingface.co/spaces/build-small-hackathon/dream-customs`
+- Live Space config checked:
+- Live Space manual case checked:
+- Notes:
+```
+
+- [ ] **Step 5: Commit smoke doc**
+
+Run:
+
+```bash
+git add docs/smoke/2026-06-08-model-led-pact-v2-smoke.md
+git commit -m "docs: record model-led pact smoke"
+```
+
+Expected: commit succeeds.
+
+- [ ] **Step 6: Push GitHub branch**
+
+Run:
+
+```bash
+git push origin feature/dream-customs-ui-voice-settings
+```
+
+Expected: push succeeds.
+
+- [ ] **Step 7: Sync Hugging Face Space**
+
+Before pushing, verify the remote:
+
+```bash
+git remote -v | grep '^space'
+```
+
+Expected:
+
+```text
+space https://huggingface.co/spaces/build-small-hackathon/dream-customs (fetch)
+space https://huggingface.co/spaces/build-small-hackathon/dream-customs (push)
+```
+
+Then push or create a Space PR according to the current auth state. If the operation requires a token, secret value, billing confirmation, force push to public `main`, or manual PR merge, stop and ask the user with the exact blocker. Do not print or save tokens.
+
+## Self-Review
+
+- Spec coverage: The plan covers English demo quality, MiniCPM5 brief/draft/critique/rewrite, MiniCPM-V witness reports, screenshot elevator regression, fallback resilience, local tests, local smoke, and HF Space sync.
+- Placeholder scan: No unresolved placeholder strings are present in the task instructions.
+- Type consistency: `VisionWitness`, `DreamBrief`, `PactCritique`, and `PactCard` names are used consistently across schema, prompts, clients, pipeline, and tests.
+- Scope check: The plan is one coherent generation-quality pass. It does not redesign the UI, change Modal deployment architecture, or broaden beyond the MiniCPM family.