From b8fd6be2026352307d30d229fe618efd561a6584 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:15:29 +0800
Subject: [PATCH 01/30] refactor(app): drop 25-prompt rotation pool and
 collapse placeholder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

remove EXAMPLES array, 6.5s setInterval rotation, and random initial
index from prompt-input. promptPlaceholder() loses the suggest and
example parameters, returning a single static prompt.placeholder.home
key for the default branch. 25 prompt.example.* i18n keys and the now-
unused prompt.placeholder.normal / prompt.placeholder.simple keys are
removed.

Part of the first-time-visitor onboarding redesign — see
docs/superpowers/specs/2026-05-17-onboarding-design.md
---
 packages/app/src/components/prompt-input.tsx  | 55 +------------------
 .../prompt-input/placeholder.test.ts          | 41 ++------------
 .../components/prompt-input/placeholder.ts    |  7 +--
 .../components/prompt-input/store-types.ts    |  1 -
 packages/app/src/i18n/en.ts                   | 29 +---------
 packages/app/src/i18n/zh.ts                   | 28 +---------
 6 files changed, 12 insertions(+), 149 deletions(-)

diff --git a/packages/app/src/components/prompt-input.tsx b/packages/app/src/components/prompt-input.tsx
index 1ba2f618a..bfa9ed5ba 100644
--- a/packages/app/src/components/prompt-input.tsx
+++ b/packages/app/src/components/prompt-input.tsx
@@ -1,5 +1,5 @@
 import { useSpring } from "@opencode-ai/ui/motion-spring"
-import { createEffect, on, Component, For, Show, onCleanup, createMemo, createSignal } from "solid-js"
+import { createEffect, on, Component, For, Show, createMemo, createSignal } from "solid-js"
 import { createStore } from "solid-js/store"
 import { useLocal } from "@/context/local"
 import { useFile } from "@/context/file"
@@ -65,34 +65,6 @@ interface PromptInputProps {
   abortReady?: () => boolean
 }
 
-const EXAMPLES = [
-  "prompt.example.1",
-  "prompt.example.2",
-  "prompt.example.3",
-  "prompt.example.4",
-  "prompt.example.5",
-  "prompt.example.6",
-  "prompt.example.7",
-  "prompt.example.8",
-  "prompt.example.9",
-  "prompt.example.10",
-  "prompt.example.11",
-  "prompt.example.12",
-  "prompt.example.13",
-  "prompt.example.14",
-  "prompt.example.15",
-  "prompt.example.16",
-  "prompt.example.17",
-  "prompt.example.18",
-  "prompt.example.19",
-  "prompt.example.20",
-  "prompt.example.21",
-  "prompt.example.22",
-  "prompt.example.23",
-  "prompt.example.24",
-  "prompt.example.25",
-] as const
-
 export const PromptInput: Component<PromptInputProps> = (props) => {
   const sdk = useSDK()
   const sync = useSync()
@@ -153,7 +125,6 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     popover: null,
     historyIndex: -1,
     savedPrompt: null,
-    placeholder: Math.floor(Math.random() * EXAMPLES.length),
     draggingType: null,
     mode: "normal",
     applyingHistory: false,
@@ -206,14 +177,6 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     return items.filter((item) => !item.comment?.trim())
   })
 
-  const hasUserPrompt = createMemo(() => {
-    const sessionID = activeSessionID()
-    if (!sessionID) return false
-    const messages = sync.data.message[sessionID]
-    if (!messages) return false
-    return messages.some((m) => m.role === "user")
-  })
-
   const { addToHistory, navigateHistory } = createHistoryNavigation({
     store,
     setStore,
@@ -223,8 +186,6 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     queueScroll,
   })
 
-  const suggest = createMemo(() => !hasUserPrompt())
-
   createEffect(
     on(
       () => store.mode,
@@ -238,9 +199,7 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
       ? promptPlaceholder({
           mode: store.mode,
           commentCount: commentCount(),
-          example: suggest() ? language.t(EXAMPLES[store.placeholder]) : "",
-          suggest: suggest(),
-          t: (key, params) => language.t(key as Parameters<typeof language.t>[0], params as never),
+          t: (key) => language.t(key as Parameters<typeof language.t>[0]),
         })
       : language.t("prompt.loading"),
   )
@@ -300,16 +259,6 @@ export const PromptInput: Component<PromptInputProps> = (props) => {
     setStore("savedPrompt", null)
   }
 
-  createEffect(() => {
-    activeSessionID()
-    if (activeSessionID()) return
-    if (!suggest()) return
-    const interval = setInterval(() => {
-      setStore("placeholder", (prev) => (prev + 1) % EXAMPLES.length)
-    }, 6500)
-    onCleanup(() => clearInterval(interval))
-  })
-
   let popoversRef: PopoverControllers | null = null
   const popoversAccess = () => {
     if (!popoversRef) throw new Error("popoversRef accessed before initialization")
diff --git a/packages/app/src/components/prompt-input/placeholder.test.ts b/packages/app/src/components/prompt-input/placeholder.test.ts
index 5f6aa59e9..f4feb9f34 100644
--- a/packages/app/src/components/prompt-input/placeholder.test.ts
+++ b/packages/app/src/components/prompt-input/placeholder.test.ts
@@ -2,47 +2,18 @@ import { describe, expect, test } from "bun:test"
 import { promptPlaceholder } from "./placeholder"
 
 describe("promptPlaceholder", () => {
-  const t = (key: string, params?: Record<string, string>) => `${key}${params?.example ? `:${params.example}` : ""}`
+  const t = (key: string) => key
 
   test("returns shell placeholder in shell mode", () => {
-    const value = promptPlaceholder({
-      mode: "shell",
-      commentCount: 0,
-      example: "example",
-      suggest: true,
-      t,
-    })
-    expect(value).toBe("prompt.placeholder.shell")
+    expect(promptPlaceholder({ mode: "shell", commentCount: 0, t })).toBe("prompt.placeholder.shell")
   })
 
   test("returns summarize placeholders for comment context", () => {
-    expect(promptPlaceholder({ mode: "normal", commentCount: 1, example: "example", suggest: true, t })).toBe(
-      "prompt.placeholder.summarizeComment",
-    )
-    expect(promptPlaceholder({ mode: "normal", commentCount: 2, example: "example", suggest: true, t })).toBe(
-      "prompt.placeholder.summarizeComments",
-    )
+    expect(promptPlaceholder({ mode: "normal", commentCount: 1, t })).toBe("prompt.placeholder.summarizeComment")
+    expect(promptPlaceholder({ mode: "normal", commentCount: 2, t })).toBe("prompt.placeholder.summarizeComments")
   })
 
-  test("returns default placeholder with example when suggestions enabled", () => {
-    const value = promptPlaceholder({
-      mode: "normal",
-      commentCount: 0,
-      example: "translated-example",
-      suggest: true,
-      t,
-    })
-    expect(value).toBe("prompt.placeholder.normal:translated-example")
-  })
-
-  test("returns simple placeholder when suggestions disabled", () => {
-    const value = promptPlaceholder({
-      mode: "normal",
-      commentCount: 0,
-      example: "translated-example",
-      suggest: false,
-      t,
-    })
-    expect(value).toBe("prompt.placeholder.simple")
+  test("returns static home placeholder for normal mode with no comments", () => {
+    expect(promptPlaceholder({ mode: "normal", commentCount: 0, t })).toBe("prompt.placeholder.home")
   })
 })
diff --git a/packages/app/src/components/prompt-input/placeholder.ts b/packages/app/src/components/prompt-input/placeholder.ts
index 395fee51b..53b8a3c65 100644
--- a/packages/app/src/components/prompt-input/placeholder.ts
+++ b/packages/app/src/components/prompt-input/placeholder.ts
@@ -1,15 +1,12 @@
 type PromptPlaceholderInput = {
   mode: "normal" | "shell"
   commentCount: number
-  example: string
-  suggest: boolean
-  t: (key: string, params?: Record<string, string>) => string
+  t: (key: string) => string
 }
 
 export function promptPlaceholder(input: PromptPlaceholderInput) {
   if (input.mode === "shell") return input.t("prompt.placeholder.shell")
   if (input.commentCount > 1) return input.t("prompt.placeholder.summarizeComments")
   if (input.commentCount === 1) return input.t("prompt.placeholder.summarizeComment")
-  if (!input.suggest) return input.t("prompt.placeholder.simple")
-  return input.t("prompt.placeholder.normal", { example: input.example })
+  return input.t("prompt.placeholder.home")
 }
diff --git a/packages/app/src/components/prompt-input/store-types.ts b/packages/app/src/components/prompt-input/store-types.ts
index 8ef6ec840..e1dc7ceac 100644
--- a/packages/app/src/components/prompt-input/store-types.ts
+++ b/packages/app/src/components/prompt-input/store-types.ts
@@ -4,7 +4,6 @@ export interface PromptStore {
   popover: "at" | "slash" | null
   historyIndex: number
   savedPrompt: PromptHistoryEntry | null
-  placeholder: number
   draggingType: "image" | "@mention" | null
   mode: "normal" | "shell"
   applyingHistory: boolean
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 9bf1ed771..a5043b52b 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -258,8 +258,7 @@ export const dict = {
   "variant.max": "Max",
 
   "prompt.placeholder.shell": "Enter shell command...",
-  "prompt.placeholder.normal": 'Try... "{{example}}"',
-  "prompt.placeholder.simple": "Try...",
+  "prompt.placeholder.home": "Type your task, or @ to mention files",
   "prompt.placeholder.summarizeComments": "Summarize comments…",
   "prompt.placeholder.summarizeComment": "Summarize comment…",
   "prompt.mode.shell": "Shell",
@@ -268,32 +267,6 @@ export const dict = {
   "session.child.promptDisabled": "Subagent sessions cannot be prompted.",
   "session.child.backToParent": "Back to main session.",
 
-  "prompt.example.1": "Draft a project update email",
-  "prompt.example.2": "Write a first-pass weekly update",
-  "prompt.example.3": "Reply to a customer inquiry email",
-  "prompt.example.4": "Draft a short product description",
-  "prompt.example.5": "Write a polite decline to a meeting request",
-  "prompt.example.6": "Summarize this Excel into a chart",
-  "prompt.example.7": "Turn invoice data into a monthly report",
-  "prompt.example.8": "Pull the key sales numbers from this spreadsheet",
-  "prompt.example.9": "Compare two quarters of sales data",
-  "prompt.example.10": "Clean up this CSV into a readable table",
-  "prompt.example.11": "Merge these PDFs with a table of contents",
-  "prompt.example.12": "Extract the key clauses from this contract",
-  "prompt.example.13": "Split this PDF into separate chapters",
-  "prompt.example.14": "Convert this Word document into PDF",
-  "prompt.example.15": "Extract the text from this PDF report",
-  "prompt.example.16": "Turn these meeting notes into minutes",
-  "prompt.example.17": "Extract action items from the meeting notes",
-  "prompt.example.18": "Turn these interview notes into an insights list",
-  "prompt.example.19": "Break this memo into a task list",
-  "prompt.example.20": "Rewrite this passage more concisely",
-  "prompt.example.21": "Summarize this long document in a paragraph",
-  "prompt.example.22": "Translate this Chinese memo into English",
-  "prompt.example.23": "Extract the key takeaways from this article",
-  "prompt.example.24": "Summarize this long email in a few sentences",
-  "prompt.example.25": "Rewrite this technical document in plain English",
-
   "prompt.popover.emptyResults": "No matching results",
   "prompt.popover.emptyCommands": "No matching commands",
   "prompt.dropzone.label": "Drop images, PDFs, or text files here",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index b727bb318..42af4f5f0 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -276,8 +276,7 @@ export const dict = {
   "variant.max": "最高",
 
   "prompt.placeholder.shell": "输入 shell 命令...",
-  "prompt.placeholder.normal": '试试... "{{example}}"',
-  "prompt.placeholder.simple": "试试...",
+  "prompt.placeholder.home": "输入你的任务，或 @ 引用文件",
   "prompt.placeholder.summarizeComments": "总结评论…",
   "prompt.placeholder.summarizeComment": "总结该评论…",
   "prompt.mode.shell": "Shell",
@@ -285,31 +284,6 @@ export const dict = {
   "prompt.mode.shell.exit": "按 esc 退出",
   "session.child.promptDisabled": "子任务运行中，暂时无法输入。",
   "session.child.backToParent": "返回主会话",
-  "prompt.example.1": "起草一封项目进度邮件",
-  "prompt.example.2": "写一份周报初稿给领导",
-  "prompt.example.3": "回复这封客户咨询邮件",
-  "prompt.example.4": "帮我写一段产品介绍文案",
-  "prompt.example.5": "这封邮件怎么写才更礼貌？",
-  "prompt.example.6": "把这份 Excel 汇总成图表",
-  "prompt.example.7": "整理这份发票数据做成月报",
-  "prompt.example.8": "从表格里提取销售要点",
-  "prompt.example.9": "这份表格里哪个产品销售最好？",
-  "prompt.example.10": "把 CSV 整理成易读的表格",
-  "prompt.example.11": "合并几份 PDF 并生成目录",
-  "prompt.example.12": "从合同里提取关键条款",
-  "prompt.example.13": "把 PDF 拆成独立章节",
-  "prompt.example.14": "把 Word 文档转成 PDF",
-  "prompt.example.15": "这份 PDF 讲了什么？",
-  "prompt.example.16": "把这段会议记录整理成纪要",
-  "prompt.example.17": "从会议笔记里提取行动项",
-  "prompt.example.18": "帮我把这段客户访谈整理成洞察清单",
-  "prompt.example.19": "把这份备忘拆成任务清单",
-  "prompt.example.20": "这段文字怎么改更简练？",
-  "prompt.example.21": "给这篇长文写一段摘要",
-  "prompt.example.22": "把这份英文报告翻译成中文",
-  "prompt.example.23": "这篇文章的关键观点是什么？",
-  "prompt.example.24": "把这封长邮件总结成几句话",
-  "prompt.example.25": "把这份技术文档改写成通俗版",
   "prompt.popover.emptyResults": "没有匹配的结果",
   "prompt.popover.emptyCommands": "没有匹配的命令",
   "prompt.dropzone.label": "将图片、PDF 或文本文件拖放到此处",

From 54dc6591f5a7be2a8f6a3b4cf7104eea10b1d405 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:17:07 +0800
Subject: [PATCH 02/30] feat(app): add home suggestion settings keys and toggle
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

introduce general.homeSuggestionsEnabled (default true) and
general.homeSuggestionsDismissed (default empty array) on the
persisted settings.v3 store, with withFallback accessors for
migration safety. settings → general gains a toggle row with an
inline restore button visible only when all three rows are dismissed.
include a contract test for the row wiring so the localStorage-based
E2E does not silently mask broken UI bindings.

Part of the first-time-visitor onboarding redesign.
---
 .../settings-general.home-suggestions.test.ts | 24 ++++++++++++++
 .../app/src/components/settings-general.tsx   | 31 +++++++++++++++++++
 packages/app/src/context/settings.tsx         | 18 +++++++++++
 packages/app/src/i18n/en.ts                   |  3 ++
 packages/app/src/i18n/zh.ts                   |  3 ++
 5 files changed, 79 insertions(+)
 create mode 100644 packages/app/src/components/settings-general.home-suggestions.test.ts

diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
new file mode 100644
index 000000000..596ba1af4
--- /dev/null
+++ b/packages/app/src/components/settings-general.home-suggestions.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+
+describe("settings-general home suggestions row", () => {
+  const source = readFileSync("src/components/settings-general.tsx", "utf8")
+
+  test("renders the suggestion toggle row with the documented i18n title", () => {
+    expect(source).toContain("settings.general.homeSuggestions")
+  })
+
+  test("wires the Switch to settings.general.homeSuggestionsEnabled accessor", () => {
+    expect(source).toContain("settings.general.homeSuggestionsEnabled()")
+    expect(source).toContain("settings.general.setHomeSuggestionsEnabled(")
+  })
+
+  test("exposes a restore-all button gated by all-three-dismissed state", () => {
+    expect(source).toContain("settings.general.homeSuggestionsDismissed().length >= 3")
+    expect(source).toContain("settings.general.setHomeSuggestionsDismissed([])")
+  })
+
+  test("clears dismissed list when re-enabling and previously all-dismissed", () => {
+    expect(source).toMatch(/setHomeSuggestionsEnabled\(checked\)[\s\S]{0,400}setHomeSuggestionsDismissed\(\[\]\)/)
+  })
+})
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index c1e47ad20..b04cc573c 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -120,6 +120,37 @@ export const SettingsGeneral: Component = () => {
 
         <SettingsWebSearchRow />
 
+        <SettingsRow
+          title={language.t("settings.general.homeSuggestions")}
+          description={language.t("settings.general.homeSuggestions.description")}
+        >
+          <div class="flex items-center gap-3" data-action="settings-home-suggestions">
+            <Show
+              when={
+                settings.general.homeSuggestionsEnabled() &&
+                settings.general.homeSuggestionsDismissed().length >= 3
+              }
+            >
+              <button
+                type="button"
+                class="text-fg-muted hover:text-fg-strong text-sm"
+                onClick={() => settings.general.setHomeSuggestionsDismissed([])}
+              >
+                {language.t("settings.general.homeSuggestions.reset")}
+              </button>
+            </Show>
+            <Switch
+              checked={settings.general.homeSuggestionsEnabled()}
+              onChange={(checked) => {
+                settings.general.setHomeSuggestionsEnabled(checked)
+                if (checked && settings.general.homeSuggestionsDismissed().length >= 3) {
+                  settings.general.setHomeSuggestionsDismissed([])
+                }
+              }}
+            />
+          </div>
+        </SettingsRow>
+
         <SettingsRow
           title={language.t("settings.general.row.reasoningSummaries.title")}
           description={language.t("settings.general.row.reasoningSummaries.description")}
diff --git a/packages/app/src/context/settings.tsx b/packages/app/src/context/settings.tsx
index 38d46e73b..97f2c5685 100644
--- a/packages/app/src/context/settings.tsx
+++ b/packages/app/src/context/settings.tsx
@@ -33,6 +33,8 @@ export interface Settings {
     editToolPartsExpanded: boolean
     lspEnabled: boolean
     webSearchEnabled: boolean
+    homeSuggestionsEnabled: boolean
+    homeSuggestionsDismissed: string[]
   }
   updates: {
     startup: boolean
@@ -114,6 +116,8 @@ const defaultSettings: Settings = {
     editToolPartsExpanded: false,
     lspEnabled: false,
     webSearchEnabled: true,
+    homeSuggestionsEnabled: true,
+    homeSuggestionsDismissed: [],
   },
   updates: {
     startup: true,
@@ -285,6 +289,20 @@ export const { use: useSettings, provider: SettingsProvider } = createSimpleCont
         setWebSearchEnabled(value: boolean) {
           setStore("general", "webSearchEnabled", value)
         },
+        homeSuggestionsEnabled: withFallback(
+          () => store.general?.homeSuggestionsEnabled,
+          defaultSettings.general.homeSuggestionsEnabled,
+        ),
+        setHomeSuggestionsEnabled(value: boolean) {
+          setStore("general", "homeSuggestionsEnabled", value)
+        },
+        homeSuggestionsDismissed: withFallback(
+          () => store.general?.homeSuggestionsDismissed,
+          defaultSettings.general.homeSuggestionsDismissed,
+        ),
+        setHomeSuggestionsDismissed(value: string[]) {
+          setStore("general", "homeSuggestionsDismissed", value)
+        },
       },
       updates: {
         startup: withFallback(() => store.updates?.startup, defaultSettings.updates.startup),
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index a5043b52b..ce6090a59 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -878,6 +878,9 @@ export const dict = {
     "Show edit, write, and patch tool parts expanded by default in the timeline",
   "settings.general.row.lsp.title": "Language Server Protocol (LSP)",
   "settings.general.row.lsp.description": "Detect type errors and symbol references when editing code",
+  "settings.general.homeSuggestions": "Home prompt suggestions",
+  "settings.general.homeSuggestions.description": "Show 3 prompt suggestion rows under the composer for new visitors. Click a row to prefill the input.",
+  "settings.general.homeSuggestions.reset": "Restore all suggestions",
   "settings.general.webSearch.title": "Web search",
   "settings.general.webSearch.description": "Let agents look up fresh information online when needed",
   "settings.general.webSearch.chip.free": "Free (bundled)",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index 42af4f5f0..c583201d5 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -767,6 +767,9 @@ export const dict = {
   "settings.general.row.editToolPartsExpanded.description": "默认在时间线中展开 edit、write 和 patch 工具部分",
   "settings.general.row.lsp.title": "语言服务器协议（LSP）",
   "settings.general.row.lsp.description": "修改代码时识别项目类型错误和符号引用",
+  "settings.general.homeSuggestions": "首页提示词建议",
+  "settings.general.homeSuggestions.description": "新用户在首页 composer 下方显示 3 行提示词建议；点击预填到输入框",
+  "settings.general.homeSuggestions.reset": "恢复全部建议",
   "settings.general.webSearch.title": "网页搜索",
   "settings.general.webSearch.description": "联网获取最新资料",
   "settings.general.webSearch.chip.free": "内置免费额度",

From c75c16caadc7815545dee3d5c73a8aa133129fce Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:17:59 +0800
Subject: [PATCH 03/30] feat(app): add pure helper resolving visible home
 suggestion chips

introduces HOME_SUGGESTION_CHIPS (3 stable chip ids) and
resolveVisibleHomeSuggestions() which returns the visible id list
given firstTimeVisitor / enabled / dismissed state. pure function so
it can be unit-tested without dom or solid runtime.
---
 .../home/home-suggestions-state.test.ts       | 46 +++++++++++++++++++
 .../components/home/home-suggestions-state.ts | 25 ++++++++++
 2 files changed, 71 insertions(+)
 create mode 100644 packages/app/src/components/home/home-suggestions-state.test.ts
 create mode 100644 packages/app/src/components/home/home-suggestions-state.ts

diff --git a/packages/app/src/components/home/home-suggestions-state.test.ts b/packages/app/src/components/home/home-suggestions-state.test.ts
new file mode 100644
index 000000000..ed4e4b95f
--- /dev/null
+++ b/packages/app/src/components/home/home-suggestions-state.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, test } from "bun:test"
+import {
+  HOME_SUGGESTION_CHIPS,
+  resolveVisibleHomeSuggestions,
+  type HomeSuggestionChipID,
+} from "./home-suggestions-state"
+
+describe("resolveVisibleHomeSuggestions", () => {
+  const allIDs = HOME_SUGGESTION_CHIPS.map((chip) => chip.id)
+
+  test("returns all chips when first-time + enabled + nothing dismissed", () => {
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed: [] })).toEqual(allIDs)
+  })
+
+  test("returns empty when not a first-time visitor", () => {
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: false, enabled: true, dismissed: [] })).toEqual([])
+  })
+
+  test("returns empty when feature is disabled", () => {
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: false, dismissed: [] })).toEqual([])
+  })
+
+  test("filters dismissed chips while preserving original order", () => {
+    const dismissed: HomeSuggestionChipID[] = ["news-brief"]
+    expect(
+      resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed }),
+    ).toEqual(allIDs.filter((id) => id !== "news-brief"))
+  })
+
+  test("returns empty when all three chips are dismissed", () => {
+    expect(
+      resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed: allIDs }),
+    ).toEqual([])
+  })
+
+  test("HOME_SUGGESTION_CHIPS has stable IDs and three entries", () => {
+    expect(HOME_SUGGESTION_CHIPS).toHaveLength(3)
+    expect(allIDs).toEqual(["analyze-spreadsheet", "news-brief", "draft-email"])
+  })
+
+  test("each chip exposes a stable i18n key", () => {
+    for (const chip of HOME_SUGGESTION_CHIPS) {
+      expect(chip.i18nKey).toMatch(/^home\.suggestion\./)
+    }
+  })
+})
diff --git a/packages/app/src/components/home/home-suggestions-state.ts b/packages/app/src/components/home/home-suggestions-state.ts
new file mode 100644
index 000000000..12d7f1627
--- /dev/null
+++ b/packages/app/src/components/home/home-suggestions-state.ts
@@ -0,0 +1,25 @@
+export type HomeSuggestionChipID = "analyze-spreadsheet" | "news-brief" | "draft-email"
+
+export interface HomeSuggestionChip {
+  id: HomeSuggestionChipID
+  i18nKey: string
+}
+
+export const HOME_SUGGESTION_CHIPS: readonly HomeSuggestionChip[] = [
+  { id: "analyze-spreadsheet", i18nKey: "home.suggestion.analyze-spreadsheet" },
+  { id: "news-brief", i18nKey: "home.suggestion.news-brief" },
+  { id: "draft-email", i18nKey: "home.suggestion.draft-email" },
+]
+
+export interface ResolveHomeSuggestionsInput {
+  firstTimeVisitor: boolean
+  enabled: boolean
+  dismissed: readonly HomeSuggestionChipID[]
+}
+
+export function resolveVisibleHomeSuggestions(input: ResolveHomeSuggestionsInput): HomeSuggestionChipID[] {
+  if (!input.firstTimeVisitor) return []
+  if (!input.enabled) return []
+  const dismissedSet = new Set(input.dismissed)
+  return HOME_SUGGESTION_CHIPS.map((chip) => chip.id).filter((id) => !dismissedSet.has(id))
+}

From 678dcf5eec233b5b66fd7478896dcd094fc2d03c Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:19:47 +0800
Subject: [PATCH 04/30] feat(app): add home suggestion list component

renders three prompt suggestion rows under the home composer for
first-time visitors. clicking a row prefills the composer via
usePrompt().set and focuses the editor; per-row X writes the chip id
into settings.general.homeSuggestionsDismissed; section X dismisses
all three at once. component returns null when not a first-time
visitor, when feature is disabled, or when all chips are dismissed.
sync.ready gate avoids flashing during initial sync hydration.
---
 .../home/home-suggestion-list.test.ts         |  58 +++++++++
 .../components/home/home-suggestion-list.tsx  | 115 ++++++++++++++++++
 packages/app/src/i18n/en.ts                   |   6 +
 packages/app/src/i18n/zh.ts                   |   6 +
 4 files changed, 185 insertions(+)
 create mode 100644 packages/app/src/components/home/home-suggestion-list.test.ts
 create mode 100644 packages/app/src/components/home/home-suggestion-list.tsx

diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
new file mode 100644
index 000000000..611132836
--- /dev/null
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, test } from "bun:test"
+import { readFileSync } from "node:fs"
+
+describe("HomeSuggestionList source contract", () => {
+  const source = readFileSync("src/components/home/home-suggestion-list.tsx", "utf8")
+
+  test("wires the helper, prompt, settings, sync, and language contexts", () => {
+    expect(source).toContain("resolveVisibleHomeSuggestions")
+    expect(source).toContain("usePrompt")
+    expect(source).toContain("useSettings")
+    expect(source).toContain("useSync")
+    expect(source).toContain("useLanguage")
+  })
+
+  test("computes firstTimeVisitor from sync.data.session count", () => {
+    expect(source).toContain("sync.data.session")
+    expect(source).toMatch(/Object\.keys\([^)]*session[^)]*\)\.length/)
+  })
+
+  test("guards firstTimeVisitor on sync.ready to avoid flashing during hydration", () => {
+    expect(source).toContain("sync.ready")
+  })
+
+  test("exposes the documented data-component and data-action hooks for E2E", () => {
+    expect(source).toContain('data-component="home-suggestion-list"')
+    expect(source).toContain('data-action="home-suggestion-row"')
+    expect(source).toContain('data-action="home-suggestion-row-dismiss"')
+    expect(source).toContain('data-action="home-suggestion-section-dismiss"')
+  })
+
+  test("prefills the composer via prompt.set and focuses the editor", () => {
+    expect(source).toContain("prompt.set([")
+    expect(source).toContain('[data-component="prompt-input"]')
+  })
+
+  test("uses the settings accessor for read and write (not raw store)", () => {
+    expect(source).toContain("settings.general.homeSuggestionsEnabled()")
+    expect(source).toContain("settings.general.homeSuggestionsDismissed()")
+    expect(source).toContain("settings.general.setHomeSuggestionsDismissed(")
+    // negative: must NOT reach into the raw store or call setStore directly
+    expect(source).not.toContain("settings.store.general")
+    expect(source).not.toContain("settings.setStore(")
+  })
+
+  test("section dismiss writes all three chip ids", () => {
+    expect(source).toContain("HOME_SUGGESTION_CHIPS.map")
+  })
+
+  test("renders nothing when there are no visible chips", () => {
+    expect(source).toContain("visibleChips().length > 0")
+  })
+
+  test("uses i18n keys for chip text and aria-labels", () => {
+    expect(source).toContain("home.suggestion.section.label")
+    expect(source).toContain("home.suggestion.section.dismiss")
+    expect(source).toContain("home.suggestion.row.dismiss")
+  })
+})
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
new file mode 100644
index 000000000..86330eb42
--- /dev/null
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -0,0 +1,115 @@
+import { For, Show, createMemo, type Component } from "solid-js"
+import { Icon } from "@opencode-ai/ui/icon"
+import { useLanguage } from "@/context/language"
+import { usePrompt } from "@/context/prompt"
+import { useSettings } from "@/context/settings"
+import { useSync } from "@/context/sync"
+import {
+  HOME_SUGGESTION_CHIPS,
+  resolveVisibleHomeSuggestions,
+  type HomeSuggestionChipID,
+} from "./home-suggestions-state"
+
+const PROMPT_EDITOR_SELECTOR = '[data-component="prompt-input"]'
+
+function focusComposerEditor() {
+  if (typeof document === "undefined") return
+  const editor = document.querySelector<HTMLElement>(PROMPT_EDITOR_SELECTOR)
+  editor?.focus()
+}
+
+export const HomeSuggestionList: Component = () => {
+  const language = useLanguage()
+  const prompt = usePrompt()
+  const settings = useSettings()
+  const sync = useSync()
+
+  const sessionCount = createMemo(() => Object.keys(sync.data.session ?? {}).length)
+  // sync.ready guards against showing chips during the initial loading hydration —
+  // sync.data.session is an empty object while status === "loading", which would
+  // make every user (returning or new) momentarily look like a first-time visitor.
+  // sync.ready is a getter on the context (not a function).
+  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0)
+
+  const visibleIDs = createMemo(() =>
+    resolveVisibleHomeSuggestions({
+      firstTimeVisitor: firstTimeVisitor(),
+      enabled: settings.general.homeSuggestionsEnabled(),
+      dismissed: settings.general.homeSuggestionsDismissed() as HomeSuggestionChipID[],
+    }),
+  )
+
+  const visibleChips = createMemo(() => {
+    const ids = new Set(visibleIDs())
+    return HOME_SUGGESTION_CHIPS.filter((chip) => ids.has(chip.id))
+  })
+
+  type I18nKey = Parameters<typeof language.t>[0]
+
+  const prefill = (text: string) => {
+    prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
+    requestAnimationFrame(focusComposerEditor)
+  }
+
+  const dismissRow = (id: HomeSuggestionChipID) => {
+    const current = settings.general.homeSuggestionsDismissed() as HomeSuggestionChipID[]
+    if (current.includes(id)) return
+    settings.general.setHomeSuggestionsDismissed([...current, id])
+  }
+
+  const dismissAll = () => {
+    settings.general.setHomeSuggestionsDismissed(HOME_SUGGESTION_CHIPS.map((chip) => chip.id))
+  }
+
+  return (
+    <Show when={visibleChips().length > 0}>
+      <section
+        data-component="home-suggestion-list"
+        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col gap-1"
+      >
+        <header class="flex items-center justify-between px-1 text-fg-muted text-sm">
+          <div class="flex items-center gap-3 flex-1">
+            <span>{language.t("home.suggestion.section.label")}</span>
+            <div class="flex-1 border-t border-border-subtle" />
+          </div>
+          <button
+            type="button"
+            class="ml-3 text-fg-muted hover:text-fg-strong"
+            aria-label={language.t("home.suggestion.section.dismiss")}
+            onClick={dismissAll}
+            data-action="home-suggestion-section-dismiss"
+          >
+            <Icon name="close" class="size-4" />
+          </button>
+        </header>
+        <ul class="flex flex-col">
+          <For each={visibleChips()}>
+            {(chip) => (
+              <li class="group flex items-center justify-between px-1 py-2 hover:bg-row-hover-overlay">
+                <button
+                  type="button"
+                  class="flex-1 text-left text-fg-base hover:text-fg-strong"
+                  onClick={() => prefill(language.t(chip.i18nKey as I18nKey))}
+                  data-action="home-suggestion-row"
+                  data-chip-id={chip.id}
+                >
+                  {language.t(chip.i18nKey as I18nKey)}
+                </button>
+                <button
+                  type="button"
+                  class="ml-3 text-fg-muted opacity-0 group-hover:opacity-100 hover:text-fg-strong transition-opacity"
+                  aria-label={language.t("home.suggestion.row.dismiss")}
+                  onClick={() => dismissRow(chip.id)}
+                  data-action="home-suggestion-row-dismiss"
+                  data-chip-id={chip.id}
+                >
+                  <Icon name="close" class="size-4" />
+                </button>
+              </li>
+            )}
+          </For>
+        </ul>
+      </section>
+    </Show>
+  )
+}
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index ce6090a59..20e4117e0 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -570,6 +570,12 @@ export const dict = {
 
   "home.recentProjects": "Recent projects",
   "home.hero.title": "What should we work on?",
+  "home.suggestion.section.label": "Prompt suggestions",
+  "home.suggestion.section.dismiss": "Dismiss all prompt suggestions",
+  "home.suggestion.row.dismiss": "Dismiss this prompt",
+  "home.suggestion.analyze-spreadsheet": "Analyze a spreadsheet — surface key data and anomalies",
+  "home.suggestion.news-brief": "Summarize today's news worth following into a brief",
+  "home.suggestion.draft-email": "Draft a work email for me",
 
   "session.tab.session": "Session",
   "session.tab.review": "Review",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index c583201d5..0db7fd4a0 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -540,6 +540,12 @@ export const dict = {
 
   "home.recentProjects": "最近项目",
   "home.hero.title": "今天我们做点什么？",
+  "home.suggestion.section.label": "提示词建议",
+  "home.suggestion.section.dismiss": "关闭所有提示词建议",
+  "home.suggestion.row.dismiss": "关闭该提示词",
+  "home.suggestion.analyze-spreadsheet": "帮我分析一份表格，找出关键数据和异常",
+  "home.suggestion.news-brief": "查一下今天值得关注的新闻，整理一份简报",
+  "home.suggestion.draft-email": "帮我起草一封工作邮件",
 
   "session.tab.session": "会话",
   "session.tab.review": "审查",

From 82b6ba48a5f74bcf15c15805c4f6b27218569774 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:20:40 +0800
Subject: [PATCH 05/30] feat(app): render HomeSuggestionList under the home
 composer

wire the new suggestion list as a sibling of the composer container in
NewSessionView. visibility, dismissal, and prefill behavior are owned
by the component itself; NewSessionView only handles layout placement.
---
 packages/app/src/components/session/session-new-view.tsx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/app/src/components/session/session-new-view.tsx b/packages/app/src/components/session/session-new-view.tsx
index c0eac4636..f70656fcb 100644
--- a/packages/app/src/components/session/session-new-view.tsx
+++ b/packages/app/src/components/session/session-new-view.tsx
@@ -1,5 +1,6 @@
 import { Show, type JSX } from "solid-js"
 import { useLanguage } from "@/context/language"
+import { HomeSuggestionList } from "@/components/home/home-suggestion-list"
 
 type ComposerCtx = {
   onModeChange: (mode: "normal" | "shell") => void
@@ -23,6 +24,7 @@ export function NewSessionView(props: { composer?: (ctx: ComposerCtx) => JSX.Ele
           <div class="mt-20 flex w-full max-w-[640px] flex-col items-center">
             {props.composer!({ onModeChange: () => {} })}
           </div>
+          <HomeSuggestionList />
         </Show>
       </div>
     </div>

From 00934d3716f139138a7fad33ea217ecab1d2d26f Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:22:04 +0800
Subject: [PATCH 06/30] test(app): e2e for home suggestion chips onboarding

cover 10 paths from the spec: first-time visitor renders 3 rows,
clicking prefills + focuses the editor, per-row X persists across
reload, section X hides the whole section, placeholder is static (no
rotation), returning visitors see no suggestion list, hover reveals
per-row X, editing prefilled text preserves the edit on send,
settings toggle hides and restores the section, and language switch
preserves dismissed state. update the @smoke inventory for the new
@smoke titles.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 171 ++++++++++++++++++
 .../test/config/e2e-smoke-tagging.test.ts     |   5 +
 2 files changed, 176 insertions(+)
 create mode 100644 packages/app/e2e/onboarding/home-suggestion-chips.spec.ts

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
new file mode 100644
index 000000000..607b07830
--- /dev/null
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -0,0 +1,171 @@
+import { test, expect } from "../fixtures"
+import { promptSelector } from "../selectors"
+
+const suggestionListSelector = '[data-component="home-suggestion-list"]'
+const rowSelector = '[data-action="home-suggestion-row"]'
+const rowDismissSelector = '[data-action="home-suggestion-row-dismiss"]'
+const sectionDismissSelector = '[data-action="home-suggestion-section-dismiss"]'
+
+test("@smoke home shows 3 suggestion rows for a first-time visitor", async ({ page, project }) => {
+  await project.open()
+
+  const list = page.locator(suggestionListSelector)
+  await expect(list).toBeVisible()
+  await expect(list.locator(rowSelector)).toHaveCount(3)
+})
+
+test("@smoke clicking a suggestion row prefills the composer", async ({ page, project }) => {
+  await project.open()
+
+  const list = page.locator(suggestionListSelector)
+  const firstRow = list.locator(rowSelector).first()
+  const text = (await firstRow.innerText()).trim()
+  await firstRow.click()
+
+  const editor = page.locator(promptSelector)
+  await expect(editor).toBeFocused()
+  // contenteditable rendered via renderEditorWithCursor may include zero-width chars / wrapping
+  // spans, so toHaveText (strict equality) can be flaky. toContainText asserts substring after
+  // textContent normalization which is the right granularity here.
+  await expect(editor).toContainText(text)
+})
+
+test("@smoke per-row X dismisses one row and persists across reload", async ({ page, project }) => {
+  await project.open()
+
+  const list = page.locator(suggestionListSelector)
+  await expect(list.locator(rowSelector)).toHaveCount(3)
+
+  const firstRow = list.locator(rowSelector).first()
+  await firstRow.hover()
+  await list.locator(rowDismissSelector).first().click()
+
+  await expect(list.locator(rowSelector)).toHaveCount(2)
+
+  await page.reload()
+  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(2)
+})
+
+test("@smoke section X dismisses all three rows and hides the section", async ({ page, project }) => {
+  await project.open()
+
+  const list = page.locator(suggestionListSelector)
+  await expect(list.locator(rowSelector)).toHaveCount(3)
+  await list.locator(sectionDismissSelector).click()
+  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+})
+
+test("@smoke composer placeholder is the static home string and does not rotate", async ({ page, project }) => {
+  await project.open()
+
+  const editor = page.locator(promptSelector)
+  await expect(editor).toBeVisible()
+  const initialLabel = await editor.getAttribute("aria-label")
+  expect(initialLabel).toMatch(/(输入你的任务|Type your task)/)
+
+  // wait ~7s (longer than the deleted 6.5s rotation) and confirm the label is unchanged
+  await page.waitForTimeout(7000)
+  const labelAfter = await editor.getAttribute("aria-label")
+  expect(labelAfter).toBe(initialLabel)
+})
+
+test("returning visitor (sessions > 0) sees no suggestion list", async ({ page, project, assistant }) => {
+  await project.open()
+
+  // create a session by sending a prompt
+  await assistant.reply("reply to trigger a session")
+  await page.locator(promptSelector).click()
+  await page.keyboard.type("first prompt")
+  await page.keyboard.press("Enter")
+  await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
+
+  // navigate back to home — sessions now == 1
+  await project.open()
+  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+})
+
+test("hover reveals the per-row X (rest state hides it)", async ({ page, project }) => {
+  await project.open()
+
+  // disable CSS transitions to remove timing flakes between rest / hover state
+  await page.addStyleTag({ content: "* { transition: none !important; animation: none !important; }" })
+
+  const list = page.locator(suggestionListSelector)
+  const firstRow = list.locator(rowSelector).first()
+  const firstRowDismiss = list.locator(rowDismissSelector).first()
+
+  // rest state: per-row X is rendered but not visible (opacity-0)
+  await expect(firstRowDismiss).toHaveCSS("opacity", "0")
+
+  // hover the row → group-hover reveals the X (opacity-1)
+  await firstRow.hover()
+  await expect(firstRowDismiss).toHaveCSS("opacity", "1")
+})
+
+test("editing a prefilled suggestion preserves the user's edit on send", async ({ page, project, assistant }) => {
+  await project.open()
+  await assistant.reply("edited reply")
+
+  const editor = page.locator(promptSelector)
+  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
+  await expect(editor).toBeFocused()
+
+  // append a suffix
+  await page.keyboard.type(" — please be concise")
+  await page.keyboard.press("Enter")
+
+  await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
+  // the user message rendered should contain both the prefilled text and the suffix
+  await expect(page.getByText(/please be concise/)).toBeVisible()
+})
+
+test("settings toggle hides and restores the suggestion section", async ({ page, project }) => {
+  await project.open()
+  await expect(page.locator(suggestionListSelector)).toBeVisible()
+
+  // toggle off via localStorage write (Settings page navigation/click is covered by
+  // the contract test for settings-general.tsx; this E2E focuses on persisted-state
+  // behaviour — does the suggestion section actually disappear when the flag flips)
+  await page.evaluate(() => {
+    // settings.v3 lives in localStorage as the persisted store; flip the key directly
+    // to avoid full-flow navigation in this test.
+    const raw = localStorage.getItem("settings.v3")
+    const parsed = raw ? JSON.parse(raw) : {}
+    parsed.general = { ...(parsed.general ?? {}), homeSuggestionsEnabled: false }
+    localStorage.setItem("settings.v3", JSON.stringify(parsed))
+  })
+  await page.reload()
+  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+
+  await page.evaluate(() => {
+    const raw = localStorage.getItem("settings.v3")
+    const parsed = raw ? JSON.parse(raw) : {}
+    parsed.general = { ...(parsed.general ?? {}), homeSuggestionsEnabled: true }
+    localStorage.setItem("settings.v3", JSON.stringify(parsed))
+  })
+  await page.reload()
+  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(3)
+})
+
+test("language switch updates chip text without losing dismissed state", async ({ page, project }) => {
+  await project.open()
+
+  const list = page.locator(suggestionListSelector)
+  // dismiss the first row in current locale
+  await list.locator(rowSelector).first().hover()
+  await list.locator(rowDismissSelector).first().click()
+  await expect(list.locator(rowSelector)).toHaveCount(2)
+
+  // Confirmed via packages/app/src/context/language.tsx — persistence key is "language",
+  // shape is { locale: "zh" | "en" }, migrated from legacy "language.v1".
+  await page.evaluate(() => {
+    const raw = localStorage.getItem("language")
+    const parsed = raw ? JSON.parse(raw) : { locale: "zh" }
+    parsed.locale = parsed.locale?.startsWith?.("zh") ? "en" : "zh"
+    localStorage.setItem("language", JSON.stringify(parsed))
+  })
+  await page.reload()
+
+  // still 2 rows visible (dismissed state preserved across locale flip)
+  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(2)
+})
diff --git a/packages/opencode/test/config/e2e-smoke-tagging.test.ts b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
index 68a7e114a..4fb77d395 100644
--- a/packages/opencode/test/config/e2e-smoke-tagging.test.ts
+++ b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
@@ -14,6 +14,11 @@ const expectedSmokeTests = [
   "packages/app/e2e/app/session.spec.ts:@smoke session composer matches home structure without docktray or agent control",
   "packages/app/e2e/app/shell-frame.spec.ts:@smoke shell frame exposes stable desktop hooks",
   "packages/app/e2e/files/file-tree.spec.ts:@smoke review tab no longer renders the legacy file-tree sub-panel",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke clicking a suggestion row prefills the composer",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke composer placeholder is the static home string and does not rotate",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke home shows 3 suggestion rows for a first-time visitor",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke per-row X dismisses one row and persists across reload",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke section X dismisses all three rows and hides the section",
   "packages/app/e2e/prompt/first-message-reply.spec.ts:@smoke first replied message in a new session renders without page errors",
   "packages/app/e2e/prompt/prompt.spec.ts:@smoke can send a prompt and receive a reply",
   "packages/app/e2e/release-notes/release-notes-toast.spec.ts:@smoke shows subtle toast when stored version is older than current",

From 9366f4dc1e151bdf125798a8d0d0684f13589cb7 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:38:06 +0800
Subject: [PATCH 07/30] fix(app): harden home suggestion chips per code
 crosscheck

Round 1 fixes after multi-model code review:

- Persist a one-way `homeSuggestionsSeen` flag so returning users who
  delete every session do not re-enter onboarding when they revisit home.
- Replace bare `as HomeSuggestionChipID[]` cast with a known-id filter so
  stale persisted IDs from a renamed chip do not poison the visibility
  contract or block the settings restore action.
- Honor `prompt.dirty()` when a chip click would otherwise overwrite the
  user-typed message, appending the suggestion with a separator instead.
- Explicitly `setCursorPosition(editor, text.length)` after `focus()` so
  follow-up typing is not browser-selection dependent.
- Switch the rest-state row dismiss button to `pointer-events-none` and
  `tabIndex={-1}` so the invisible control cannot receive accidental
  clicks or stops in tab order, then restore both on group hover.
- Settings page: gate the restore button on any chip dismissed (not all
  three) and replace the hard-coded `>= 3` with
  `HOME_SUGGESTION_CHIPS.length` so the section count is not brittle.
- Tighten the E2E placeholder check to a single attribute snapshot
  against the actual i18n string and drop the 7s sleep; verify chip text
  re-renders on locale switch instead of just row count; exercise the
  real Settings switch flow rather than a localStorage poke.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 72 ++++++++++---------
 .../home/home-suggestion-list.test.ts         | 29 +++++++-
 .../components/home/home-suggestion-list.tsx  | 69 ++++++++++++++----
 .../settings-general.home-suggestions.test.ts |  9 ++-
 .../app/src/components/settings-general.tsx   |  8 ++-
 packages/app/src/context/settings.tsx         | 14 ++++
 .../test/config/e2e-smoke-tagging.test.ts     |  2 +-
 7 files changed, 153 insertions(+), 50 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 607b07830..eea795908 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -55,18 +55,16 @@ test("@smoke section X dismisses all three rows and hides the section", async ({
   await expect(page.locator(suggestionListSelector)).toHaveCount(0)
 })
 
-test("@smoke composer placeholder is the static home string and does not rotate", async ({ page, project }) => {
+test("@smoke composer placeholder is the static home string", async ({ page, project }) => {
   await project.open()
 
   const editor = page.locator(promptSelector)
   await expect(editor).toBeVisible()
-  const initialLabel = await editor.getAttribute("aria-label")
-  expect(initialLabel).toMatch(/(输入你的任务|Type your task)/)
-
-  // wait ~7s (longer than the deleted 6.5s rotation) and confirm the label is unchanged
-  await page.waitForTimeout(7000)
-  const labelAfter = await editor.getAttribute("aria-label")
-  expect(labelAfter).toBe(initialLabel)
+  // Match the single static home placeholder in either locale. The legacy 25-prompt
+  // rotation pool and its 6.5s interval were removed. The resource file is the only
+  // source of truth. See packages/app/src/components/prompt-input/placeholder.ts.
+  const label = await editor.getAttribute("aria-label")
+  expect(label).toMatch(/(输入你的任务，或 @ 引用文件|Type your task, or @ to mention files)/)
 })
 
 test("returning visitor (sessions > 0) sees no suggestion list", async ({ page, project, assistant }) => {
@@ -96,10 +94,13 @@ test("hover reveals the per-row X (rest state hides it)", async ({ page, project
 
   // rest state: per-row X is rendered but not visible (opacity-0)
   await expect(firstRowDismiss).toHaveCSS("opacity", "0")
+  // and not clickable (pointer-events-none keeps it out of the hit-test surface)
+  await expect(firstRowDismiss).toHaveCSS("pointer-events", "none")
 
-  // hover the row → group-hover reveals the X (opacity-1)
+  // hover the row → group-hover reveals the X (opacity-1) and re-enables clicks
   await firstRow.hover()
   await expect(firstRowDismiss).toHaveCSS("opacity", "1")
+  await expect(firstRowDismiss).toHaveCSS("pointer-events", "auto")
 })
 
 test("editing a prefilled suggestion preserves the user's edit on send", async ({ page, project, assistant }) => {
@@ -111,7 +112,7 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await expect(editor).toBeFocused()
 
   // append a suffix
-  await page.keyboard.type(" — please be concise")
+  await page.keyboard.type(" please be concise")
   await page.keyboard.press("Enter")
 
   await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
@@ -119,31 +120,29 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await expect(page.getByText(/please be concise/)).toBeVisible()
 })
 
-test("settings toggle hides and restores the suggestion section", async ({ page, project }) => {
+test("settings toggle hides and restores the suggestion section via the real Settings UI", async ({
+  page,
+  project,
+}) => {
   await project.open()
   await expect(page.locator(suggestionListSelector)).toBeVisible()
 
-  // toggle off via localStorage write (Settings page navigation/click is covered by
-  // the contract test for settings-general.tsx; this E2E focuses on persisted-state
-  // behaviour — does the suggestion section actually disappear when the flag flips)
-  await page.evaluate(() => {
-    // settings.v3 lives in localStorage as the persisted store; flip the key directly
-    // to avoid full-flow navigation in this test.
-    const raw = localStorage.getItem("settings.v3")
-    const parsed = raw ? JSON.parse(raw) : {}
-    parsed.general = { ...(parsed.general ?? {}), homeSuggestionsEnabled: false }
-    localStorage.setItem("settings.v3", JSON.stringify(parsed))
-  })
-  await page.reload()
+  // Open Settings (kbd shortcut path is project-wide; settings page is a full pane,
+  // not a dialog — see settings.spec.ts for the canonical opening behavior).
+  await page.goto("#/settings/general")
+  const switchEl = page.locator('[data-action="settings-home-suggestions"] [role="switch"]')
+  await expect(switchEl).toBeVisible()
+  // turn off
+  await switchEl.click()
+
+  await project.open()
   await expect(page.locator(suggestionListSelector)).toHaveCount(0)
 
-  await page.evaluate(() => {
-    const raw = localStorage.getItem("settings.v3")
-    const parsed = raw ? JSON.parse(raw) : {}
-    parsed.general = { ...(parsed.general ?? {}), homeSuggestionsEnabled: true }
-    localStorage.setItem("settings.v3", JSON.stringify(parsed))
-  })
-  await page.reload()
+  // turn it back on via the real Settings switch
+  await page.goto("#/settings/general")
+  await switchEl.click()
+
+  await project.open()
   await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(3)
 })
 
@@ -151,12 +150,15 @@ test("language switch updates chip text without losing dismissed state", async (
   await project.open()
 
   const list = page.locator(suggestionListSelector)
+  // capture text of the second row in the current locale (first row will be dismissed below)
+  const secondRowTextBefore = (await list.locator(rowSelector).nth(1).innerText()).trim()
+
   // dismiss the first row in current locale
   await list.locator(rowSelector).first().hover()
   await list.locator(rowDismissSelector).first().click()
   await expect(list.locator(rowSelector)).toHaveCount(2)
 
-  // Confirmed via packages/app/src/context/language.tsx — persistence key is "language",
+  // Confirmed via packages/app/src/context/language.tsx. Persistence key is "language",
   // shape is { locale: "zh" | "en" }, migrated from legacy "language.v1".
   await page.evaluate(() => {
     const raw = localStorage.getItem("language")
@@ -167,5 +169,11 @@ test("language switch updates chip text without losing dismissed state", async (
   await page.reload()
 
   // still 2 rows visible (dismissed state preserved across locale flip)
-  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(2)
+  const listAfter = page.locator(suggestionListSelector)
+  await expect(listAfter.locator(rowSelector)).toHaveCount(2)
+
+  // and chip text actually flipped to the other locale (key insight: the row text
+  // must NOT equal the pre-flip text — that would mean i18n didn't propagate)
+  const secondRowTextAfter = (await listAfter.locator(rowSelector).nth(0).innerText()).trim()
+  expect(secondRowTextAfter).not.toBe(secondRowTextBefore)
 })
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index 611132836..9aa68f40e 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -21,6 +21,14 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("sync.ready")
   })
 
+  test("uses homeSuggestionsSeen as a one-way bit so returning users do not re-enter onboarding", () => {
+    // firstTimeVisitor must factor in seen flag
+    expect(source).toContain("homeSuggestionsSeen")
+    expect(source).toContain("setHomeSuggestionsSeen(true)")
+    // session-count > 0 should flip seen=true via createEffect (one-way hydration latch)
+    expect(source).toMatch(/createEffect\([\s\S]{0,400}setHomeSuggestionsSeen\(true\)/)
+  })
+
   test("exposes the documented data-component and data-action hooks for E2E", () => {
     expect(source).toContain('data-component="home-suggestion-list"')
     expect(source).toContain('data-action="home-suggestion-row"')
@@ -33,11 +41,24 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain('[data-component="prompt-input"]')
   })
 
+  test("explicitly restores caret position after focus so follow-up typing works deterministically", () => {
+    expect(source).toContain("setCursorPosition")
+  })
+
+  test("respects user-typed content via prompt.dirty() before overwriting", () => {
+    expect(source).toContain("prompt.dirty()")
+  })
+
+  test("filters dismissed IDs against known chip IDs (no bare type cast)", () => {
+    expect(source).toContain("filterKnownIDs")
+    // negative: must NOT launder the persisted store value with a bare cast
+    expect(source).not.toMatch(/homeSuggestionsDismissed\(\) as HomeSuggestionChipID\[\]/)
+  })
+
   test("uses the settings accessor for read and write (not raw store)", () => {
     expect(source).toContain("settings.general.homeSuggestionsEnabled()")
     expect(source).toContain("settings.general.homeSuggestionsDismissed()")
     expect(source).toContain("settings.general.setHomeSuggestionsDismissed(")
-    // negative: must NOT reach into the raw store or call setStore directly
     expect(source).not.toContain("settings.store.general")
     expect(source).not.toContain("settings.setStore(")
   })
@@ -46,6 +67,12 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("HOME_SUGGESTION_CHIPS.map")
   })
 
+  test("rest-state dismiss button is not clickable (pointer-events-none) and not in tab order", () => {
+    expect(source).toContain("pointer-events-none")
+    expect(source).toContain("group-hover:pointer-events-auto")
+    expect(source).toContain("tabIndex={-1}")
+  })
+
   test("renders nothing when there are no visible chips", () => {
     expect(source).toContain("visibleChips().length > 0")
   })
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 86330eb42..81b408fd1 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -1,9 +1,10 @@
-import { For, Show, createMemo, type Component } from "solid-js"
+import { For, Show, createEffect, createMemo, type Component } from "solid-js"
 import { Icon } from "@opencode-ai/ui/icon"
 import { useLanguage } from "@/context/language"
 import { usePrompt } from "@/context/prompt"
 import { useSettings } from "@/context/settings"
 import { useSync } from "@/context/sync"
+import { setCursorPosition } from "@/components/prompt-input/editor-dom"
 import {
   HOME_SUGGESTION_CHIPS,
   resolveVisibleHomeSuggestions,
@@ -12,10 +13,24 @@ import {
 
 const PROMPT_EDITOR_SELECTOR = '[data-component="prompt-input"]'
 
-function focusComposerEditor() {
+function focusComposerEditor(caretAt: number) {
   if (typeof document === "undefined") return
   const editor = document.querySelector<HTMLElement>(PROMPT_EDITOR_SELECTOR)
-  editor?.focus()
+  if (!editor) return
+  editor.focus()
+  setCursorPosition(editor, caretAt)
+}
+
+const KNOWN_CHIP_IDS = new Set<HomeSuggestionChipID>(HOME_SUGGESTION_CHIPS.map((chip) => chip.id))
+
+function filterKnownIDs(raw: readonly string[]): HomeSuggestionChipID[] {
+  const out: HomeSuggestionChipID[] = []
+  for (const value of raw) {
+    if (KNOWN_CHIP_IDS.has(value as HomeSuggestionChipID)) {
+      out.push(value as HomeSuggestionChipID)
+    }
+  }
+  return out
 }
 
 export const HomeSuggestionList: Component = () => {
@@ -25,17 +40,26 @@ export const HomeSuggestionList: Component = () => {
   const sync = useSync()
 
   const sessionCount = createMemo(() => Object.keys(sync.data.session ?? {}).length)
-  // sync.ready guards against showing chips during the initial loading hydration —
-  // sync.data.session is an empty object while status === "loading", which would
-  // make every user (returning or new) momentarily look like a first-time visitor.
-  // sync.ready is a getter on the context (not a function).
-  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0)
+  const seen = createMemo(() => settings.general.homeSuggestionsSeen())
+
+  // Flip seen=true on first hydrated state with sessions. Returning users
+  // who clean up all sessions will never re-enter first-time onboarding.
+  createEffect(() => {
+    if (!sync.ready) return
+    if (seen()) return
+    if (sessionCount() > 0) settings.general.setHomeSuggestionsSeen(true)
+  })
+
+  // sync.ready guards against showing chips during initial hydration, where
+  // sync.data.session is briefly empty and every user looks like a new visitor.
+  // sync.ready is a reactive getter on the context, not a function call.
+  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0 && !seen())
 
   const visibleIDs = createMemo(() =>
     resolveVisibleHomeSuggestions({
       firstTimeVisitor: firstTimeVisitor(),
       enabled: settings.general.homeSuggestionsEnabled(),
-      dismissed: settings.general.homeSuggestionsDismissed() as HomeSuggestionChipID[],
+      dismissed: filterKnownIDs(settings.general.homeSuggestionsDismissed()),
     }),
   )
 
@@ -46,18 +70,38 @@ export const HomeSuggestionList: Component = () => {
 
   type I18nKey = Parameters<typeof language.t>[0]
 
+  const markSeen = () => {
+    if (!seen()) settings.general.setHomeSuggestionsSeen(true)
+  }
+
   const prefill = (text: string) => {
+    markSeen()
+    // Respect user-typed content. If they've already started a message, append
+    // the suggestion text with a space; otherwise replace.
+    if (prompt.dirty()) {
+      const existing = prompt
+        .current()
+        .map((part) => ("content" in part ? part.content : ""))
+        .join("")
+      const suffix = existing.endsWith(" ") || existing.length === 0 ? "" : " "
+      const merged = `${existing}${suffix}${text}`
+      prompt.set([{ type: "text", content: merged, start: 0, end: merged.length }], merged.length)
+      requestAnimationFrame(() => focusComposerEditor(merged.length))
+      return
+    }
     prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
-    requestAnimationFrame(focusComposerEditor)
+    requestAnimationFrame(() => focusComposerEditor(text.length))
   }
 
   const dismissRow = (id: HomeSuggestionChipID) => {
-    const current = settings.general.homeSuggestionsDismissed() as HomeSuggestionChipID[]
+    markSeen()
+    const current = filterKnownIDs(settings.general.homeSuggestionsDismissed())
     if (current.includes(id)) return
     settings.general.setHomeSuggestionsDismissed([...current, id])
   }
 
   const dismissAll = () => {
+    markSeen()
     settings.general.setHomeSuggestionsDismissed(HOME_SUGGESTION_CHIPS.map((chip) => chip.id))
   }
 
@@ -97,7 +141,8 @@ export const HomeSuggestionList: Component = () => {
                 </button>
                 <button
                   type="button"
-                  class="ml-3 text-fg-muted opacity-0 group-hover:opacity-100 hover:text-fg-strong transition-opacity"
+                  tabIndex={-1}
+                  class="ml-3 text-fg-muted opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto hover:text-fg-strong transition-opacity"
                   aria-label={language.t("home.suggestion.row.dismiss")}
                   onClick={() => dismissRow(chip.id)}
                   data-action="home-suggestion-row-dismiss"
diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
index 596ba1af4..426f46c27 100644
--- a/packages/app/src/components/settings-general.home-suggestions.test.ts
+++ b/packages/app/src/components/settings-general.home-suggestions.test.ts
@@ -13,11 +13,16 @@ describe("settings-general home suggestions row", () => {
     expect(source).toContain("settings.general.setHomeSuggestionsEnabled(")
   })
 
-  test("exposes a restore-all button gated by all-three-dismissed state", () => {
-    expect(source).toContain("settings.general.homeSuggestionsDismissed().length >= 3")
+  test("exposes a restore button whenever any chip is dismissed (not only all-dismissed)", () => {
+    expect(source).toContain("homeSuggestionsDismissed().length > 0")
     expect(source).toContain("settings.general.setHomeSuggestionsDismissed([])")
   })
 
+  test("uses HOME_SUGGESTION_CHIPS.length for the all-dismissed gate (not a hardcoded count)", () => {
+    expect(source).toContain("HOME_SUGGESTION_CHIPS.length")
+    expect(source).not.toMatch(/homeSuggestionsDismissed\(\)\.length\s*>=\s*3\b/)
+  })
+
   test("clears dismissed list when re-enabling and previously all-dismissed", () => {
     expect(source).toMatch(/setHomeSuggestionsEnabled\(checked\)[\s\S]{0,400}setHomeSuggestionsDismissed\(\[\]\)/)
   })
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index b04cc573c..9a736640b 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -22,6 +22,7 @@ import { decode64 } from "@/utils/base64"
 import { Link } from "./link"
 import { SettingsList } from "./settings-list"
 import { SettingsNotificationsSection } from "./settings-notifications-section"
+import { HOME_SUGGESTION_CHIPS } from "./home/home-suggestions-state"
 import { SettingsRow } from "./settings-row"
 import { SettingsSoundsSection } from "./settings-sounds-section"
 import { SettingsUpdatesSection } from "./settings-updates-section"
@@ -128,7 +129,7 @@ export const SettingsGeneral: Component = () => {
             <Show
               when={
                 settings.general.homeSuggestionsEnabled() &&
-                settings.general.homeSuggestionsDismissed().length >= 3
+                settings.general.homeSuggestionsDismissed().length > 0
               }
             >
               <button
@@ -143,7 +144,10 @@ export const SettingsGeneral: Component = () => {
               checked={settings.general.homeSuggestionsEnabled()}
               onChange={(checked) => {
                 settings.general.setHomeSuggestionsEnabled(checked)
-                if (checked && settings.general.homeSuggestionsDismissed().length >= 3) {
+                if (
+                  checked &&
+                  settings.general.homeSuggestionsDismissed().length >= HOME_SUGGESTION_CHIPS.length
+                ) {
                   settings.general.setHomeSuggestionsDismissed([])
                 }
               }}
diff --git a/packages/app/src/context/settings.tsx b/packages/app/src/context/settings.tsx
index 97f2c5685..9642b473b 100644
--- a/packages/app/src/context/settings.tsx
+++ b/packages/app/src/context/settings.tsx
@@ -35,6 +35,7 @@ export interface Settings {
     webSearchEnabled: boolean
     homeSuggestionsEnabled: boolean
     homeSuggestionsDismissed: string[]
+    homeSuggestionsSeen: boolean
   }
   updates: {
     startup: boolean
@@ -118,6 +119,7 @@ const defaultSettings: Settings = {
     webSearchEnabled: true,
     homeSuggestionsEnabled: true,
     homeSuggestionsDismissed: [],
+    homeSuggestionsSeen: false,
   },
   updates: {
     startup: true,
@@ -303,6 +305,18 @@ export const { use: useSettings, provider: SettingsProvider } = createSimpleCont
         setHomeSuggestionsDismissed(value: string[]) {
           setStore("general", "homeSuggestionsDismissed", value)
         },
+        // homeSuggestionsSeen is a one-way bit: once the user has any session
+        // hydrated, or clicks/dismisses a chip, this flips to true and never
+        // resets. Without it, a returning user who deletes all sessions would
+        // re-enter "first-time visitor" state and see the onboarding chips
+        // again, which the design explicitly rejects.
+        homeSuggestionsSeen: withFallback(
+          () => store.general?.homeSuggestionsSeen,
+          defaultSettings.general.homeSuggestionsSeen,
+        ),
+        setHomeSuggestionsSeen(value: boolean) {
+          setStore("general", "homeSuggestionsSeen", value)
+        },
       },
       updates: {
         startup: withFallback(() => store.updates?.startup, defaultSettings.updates.startup),
diff --git a/packages/opencode/test/config/e2e-smoke-tagging.test.ts b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
index 4fb77d395..e5d71cfe0 100644
--- a/packages/opencode/test/config/e2e-smoke-tagging.test.ts
+++ b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
@@ -15,7 +15,7 @@ const expectedSmokeTests = [
   "packages/app/e2e/app/shell-frame.spec.ts:@smoke shell frame exposes stable desktop hooks",
   "packages/app/e2e/files/file-tree.spec.ts:@smoke review tab no longer renders the legacy file-tree sub-panel",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke clicking a suggestion row prefills the composer",
-  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke composer placeholder is the static home string and does not rotate",
+  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke composer placeholder is the static home string",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke home shows 3 suggestion rows for a first-time visitor",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke per-row X dismisses one row and persists across reload",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke section X dismisses all three rows and hides the section",

From 8261193e2335b670621e8129b9b2bddfe4e3ea30 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:44:02 +0800
Subject: [PATCH 08/30] fix(app): per-row dismiss must not mark home onboarding
 seen

Round 2 crosscheck caught a regression in the previous round's fix:
markSeen() was firing from dismissRow, which flips firstTimeVisitor to
false and hides the whole section after the first dismiss. The expected
UX is that dismissing one row leaves the other two visible; the Settings
restore button then becomes a silent no-op because chips never re-render
even after the dismissed list clears.

Per-row dismiss is fine-grained curation, not an onboarding exit signal.
Reserve homeSuggestionsSeen for: hydration with sessions present, chip
click (prefill), or section-level dismiss (dismissAll). The persisted
comment is updated to spell this out, and three new contract tests pin
the per-handler markSeen behavior so a regression cannot land silently
again.

Also tighten the placeholder E2E to assert against the current locale's
i18n value rather than an either-or regex, so a regression in either
language fails the test.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 21 ++++++++++++++----
 .../home/home-suggestion-list.test.ts         | 22 +++++++++++++++++++
 .../components/home/home-suggestion-list.tsx  |  4 +++-
 packages/app/src/context/settings.tsx         |  9 ++++----
 4 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index eea795908..d1adf5a9c 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -60,11 +60,24 @@ test("@smoke composer placeholder is the static home string", async ({ page, pro
 
   const editor = page.locator(promptSelector)
   await expect(editor).toBeVisible()
-  // Match the single static home placeholder in either locale. The legacy 25-prompt
-  // rotation pool and its 6.5s interval were removed. The resource file is the only
-  // source of truth. See packages/app/src/components/prompt-input/placeholder.ts.
+
+  // Read the live locale and assert against the matching i18n value. A regression
+  // that swaps the placeholder to a wrong string in either locale must fail,
+  // not be masked by an either-or regex.
+  // Persistence key is "language" and shape is { locale: "zh" | "en" }; verified
+  // via packages/app/src/context/language.tsx.
+  const locale = await page.evaluate(() => {
+    const raw = localStorage.getItem("language")
+    const parsed = raw ? JSON.parse(raw) : { locale: "zh" }
+    return parsed.locale?.startsWith?.("zh") ? "zh" : "en"
+  })
   const label = await editor.getAttribute("aria-label")
-  expect(label).toMatch(/(输入你的任务，或 @ 引用文件|Type your task, or @ to mention files)/)
+  // i18n source: packages/app/src/i18n/{zh,en}.ts → prompt.placeholder.home
+  if (locale === "zh") {
+    expect(label).toBe("输入你的任务，或 @ 引用文件")
+  } else {
+    expect(label).toBe("Type your task, or @ to mention files")
+  }
 })
 
 test("returning visitor (sessions > 0) sees no suggestion list", async ({ page, project, assistant }) => {
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index 9aa68f40e..ec658a2db 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -29,6 +29,28 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toMatch(/createEffect\([\s\S]{0,400}setHomeSuggestionsSeen\(true\)/)
   })
 
+  test("per-row dismiss does NOT mark seen (would otherwise hide section after the first dismiss)", () => {
+    // The dismissRow body must not call markSeen() — confirmed by inspecting the
+    // dismissRow function body in source. Encoded as: there is a dismissRow
+    // definition, and within ~400 chars of its declaration, markSeen() is not
+    // called between the dismissRow line and its closing `}`.
+    const match = source.match(/const dismissRow = [\s\S]*?\n  \}/)
+    expect(match).not.toBeNull()
+    expect(match![0]).not.toContain("markSeen()")
+  })
+
+  test("section dismiss (dismissAll) DOES mark seen", () => {
+    const match = source.match(/const dismissAll = [\s\S]*?\n  \}/)
+    expect(match).not.toBeNull()
+    expect(match![0]).toContain("markSeen()")
+  })
+
+  test("chip click (prefill) DOES mark seen", () => {
+    const match = source.match(/const prefill = [\s\S]*?\n  \}/)
+    expect(match).not.toBeNull()
+    expect(match![0]).toContain("markSeen()")
+  })
+
   test("exposes the documented data-component and data-action hooks for E2E", () => {
     expect(source).toContain('data-component="home-suggestion-list"')
     expect(source).toContain('data-action="home-suggestion-row"')
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 81b408fd1..d665ea55a 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -94,7 +94,9 @@ export const HomeSuggestionList: Component = () => {
   }
 
   const dismissRow = (id: HomeSuggestionChipID) => {
-    markSeen()
+    // Per-row dismiss is fine-grained curation, not an onboarding exit signal.
+    // Do NOT mark seen here, or the section hides immediately after the first
+    // dismiss and the Settings restore button becomes a silent no-op.
     const current = filterKnownIDs(settings.general.homeSuggestionsDismissed())
     if (current.includes(id)) return
     settings.general.setHomeSuggestionsDismissed([...current, id])
diff --git a/packages/app/src/context/settings.tsx b/packages/app/src/context/settings.tsx
index 9642b473b..7c5a32809 100644
--- a/packages/app/src/context/settings.tsx
+++ b/packages/app/src/context/settings.tsx
@@ -305,10 +305,11 @@ export const { use: useSettings, provider: SettingsProvider } = createSimpleCont
         setHomeSuggestionsDismissed(value: string[]) {
           setStore("general", "homeSuggestionsDismissed", value)
         },
-        // homeSuggestionsSeen is a one-way bit: once the user has any session
-        // hydrated, or clicks/dismisses a chip, this flips to true and never
-        // resets. Without it, a returning user who deletes all sessions would
-        // re-enter "first-time visitor" state and see the onboarding chips
+        // homeSuggestionsSeen is a one-way bit: flips to true when the user
+        // has any session hydrated, clicks a chip, or dismisses the whole
+        // section. Per-row dismiss does NOT flip it (those are curation, not
+        // exit). Without this flag, a returning user who deletes all sessions
+        // would re-enter "first-time visitor" state and see onboarding chips
         // again, which the design explicitly rejects.
         homeSuggestionsSeen: withFallback(
           () => store.general?.homeSuggestionsSeen,

From 72cc3fa1651e28e84b950da5ebca1aa3e3b9f4f9 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:49:12 +0800
Subject: [PATCH 09/30] fix(app): settings restore must reset BOTH dismissed
 and seen

Both reviewers in Round 3 converged on the same P1: clicking "Restore"
in Settings only cleared the dismissed list, so after a section-level
dismiss (which also flips seen=true) the button was a silent no-op.
Chips never returned even though the UI promised they would.

Restore now resets BOTH state slots, and the gate widens to surface the
button whenever either slot is non-empty so users can recover from
either path (per-row dismissals or section dismiss). The dead auto-clear
branch on switch re-enable also went away: under the seen flag it could
never restore visibility on its own, and the dedicated restore button is
now the single source of truth for "bring chips back".
---
 .../settings-general.home-suggestions.test.ts | 22 +++++++++++++------
 .../app/src/components/settings-general.tsx   | 22 +++++++++----------
 2 files changed, 25 insertions(+), 19 deletions(-)

diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
index 426f46c27..14369eab5 100644
--- a/packages/app/src/components/settings-general.home-suggestions.test.ts
+++ b/packages/app/src/components/settings-general.home-suggestions.test.ts
@@ -13,17 +13,25 @@ describe("settings-general home suggestions row", () => {
     expect(source).toContain("settings.general.setHomeSuggestionsEnabled(")
   })
 
-  test("exposes a restore button whenever any chip is dismissed (not only all-dismissed)", () => {
+  test("restore button is visible whenever any chip is dismissed OR seen was set", () => {
+    // Either source slot indicates "chips are currently hidden because of past
+    // user action" and a restore should be offered. Gating only on dismissed
+    // would leave the button hidden after a section dismiss (which writes seen).
     expect(source).toContain("homeSuggestionsDismissed().length > 0")
-    expect(source).toContain("settings.general.setHomeSuggestionsDismissed([])")
+    expect(source).toContain("homeSuggestionsSeen()")
   })
 
-  test("uses HOME_SUGGESTION_CHIPS.length for the all-dismissed gate (not a hardcoded count)", () => {
-    expect(source).toContain("HOME_SUGGESTION_CHIPS.length")
-    expect(source).not.toMatch(/homeSuggestionsDismissed\(\)\.length\s*>=\s*3\b/)
+  test("restore action resets BOTH dismissed and seen", () => {
+    // The single most important invariant: clicking restore must clear BOTH
+    // state slots, otherwise the button is a silent no-op after section X.
+    expect(source).toContain("setHomeSuggestionsDismissed([])")
+    expect(source).toContain("setHomeSuggestionsSeen(false)")
   })
 
-  test("clears dismissed list when re-enabling and previously all-dismissed", () => {
-    expect(source).toMatch(/setHomeSuggestionsEnabled\(checked\)[\s\S]{0,400}setHomeSuggestionsDismissed\(\[\]\)/)
+  test("switch toggle is a plain on/off without auto-clear side effects", () => {
+    // The previous auto-clear-on-re-enable branch was dead code under the seen
+    // flag (clearing dismissed did not restore chips). The dedicated restore
+    // button now owns that responsibility; toggle stays simple.
+    expect(source).not.toMatch(/setHomeSuggestionsEnabled\(checked\)[\s\S]{0,200}setHomeSuggestionsDismissed\(\[\]\)/)
   })
 })
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index 9a736640b..a1b801736 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -22,7 +22,6 @@ import { decode64 } from "@/utils/base64"
 import { Link } from "./link"
 import { SettingsList } from "./settings-list"
 import { SettingsNotificationsSection } from "./settings-notifications-section"
-import { HOME_SUGGESTION_CHIPS } from "./home/home-suggestions-state"
 import { SettingsRow } from "./settings-row"
 import { SettingsSoundsSection } from "./settings-sounds-section"
 import { SettingsUpdatesSection } from "./settings-updates-section"
@@ -129,28 +128,27 @@ export const SettingsGeneral: Component = () => {
             <Show
               when={
                 settings.general.homeSuggestionsEnabled() &&
-                settings.general.homeSuggestionsDismissed().length > 0
+                (settings.general.homeSuggestionsDismissed().length > 0 ||
+                  settings.general.homeSuggestionsSeen())
               }
             >
               <button
                 type="button"
                 class="text-fg-muted hover:text-fg-strong text-sm"
-                onClick={() => settings.general.setHomeSuggestionsDismissed([])}
+                onClick={() => {
+                  // Restore must reset BOTH state slots. Dismissed alone won't
+                  // bring chips back if section dismiss already flipped seen,
+                  // since firstTimeVisitor would still be false.
+                  settings.general.setHomeSuggestionsDismissed([])
+                  settings.general.setHomeSuggestionsSeen(false)
+                }}
               >
                 {language.t("settings.general.homeSuggestions.reset")}
               </button>
             </Show>
             <Switch
               checked={settings.general.homeSuggestionsEnabled()}
-              onChange={(checked) => {
-                settings.general.setHomeSuggestionsEnabled(checked)
-                if (
-                  checked &&
-                  settings.general.homeSuggestionsDismissed().length >= HOME_SUGGESTION_CHIPS.length
-                ) {
-                  settings.general.setHomeSuggestionsDismissed([])
-                }
-              }}
+              onChange={(checked) => settings.general.setHomeSuggestionsEnabled(checked)}
             />
           </div>
         </SettingsRow>

From 7c68bf5a83436a8ffbb4e37386b81ed065e1e19f Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 15:56:49 +0800
Subject: [PATCH 10/30] fix(app): hide restore button when sessions exist,
 preserve dirty composer

Round 4 crosscheck surfaced two remaining issues:

- Claude P1: Restore in Settings was still a silent no-op for returning
  users (sessionCount > 0). Even after clearing both seen and dismissed,
  firstTimeVisitor stays false because of the sessionCount check. The
  button promised recovery that could not happen. Settings now consults
  useSync and hides the restore button once any session exists.
- Claude P2 #5: prefill merged user-typed content with the suggestion by
  joining text parts, which silently dropped file/agent @-mentions. When
  prompt.dirty() is true, prefill now leaves the composer untouched and
  only refocuses. No corruption path remains.

Also normalize sessionCount to sync.data.session.length (it is Session[],
not a record map, confirmed via use-session-blockers.ts:33).
---
 .../onboarding/home-suggestion-chips.spec.ts  | 14 ++++++++++++++
 .../home/home-suggestion-list.test.ts         | 10 ++++++++--
 .../components/home/home-suggestion-list.tsx  | 19 ++++++++-----------
 .../settings-general.home-suggestions.test.ts |  8 ++++++++
 .../app/src/components/settings-general.tsx   |  8 ++++++++
 5 files changed, 46 insertions(+), 13 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index d1adf5a9c..10c7534a3 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -133,6 +133,20 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await expect(page.getByText(/please be concise/)).toBeVisible()
 })
 
+test("clicking a chip with user-typed content does NOT overwrite the user content", async ({ page, project }) => {
+  await project.open()
+
+  const editor = page.locator(promptSelector)
+  await editor.click()
+  await page.keyboard.type("my own draft text")
+  await expect(editor).toContainText("my own draft text")
+
+  // click first chip — user content should be preserved (no merge, no overwrite)
+  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
+  await expect(editor).toBeFocused()
+  await expect(editor).toContainText("my own draft text")
+})
+
 test("settings toggle hides and restores the suggestion section via the real Settings UI", async ({
   page,
   project,
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index ec658a2db..0d4b50b92 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -14,7 +14,7 @@ describe("HomeSuggestionList source contract", () => {
 
   test("computes firstTimeVisitor from sync.data.session count", () => {
     expect(source).toContain("sync.data.session")
-    expect(source).toMatch(/Object\.keys\([^)]*session[^)]*\)\.length/)
+    expect(source).toMatch(/sync\.data\.session\??\.length/)
   })
 
   test("guards firstTimeVisitor on sync.ready to avoid flashing during hydration", () => {
@@ -67,8 +67,14 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("setCursorPosition")
   })
 
-  test("respects user-typed content via prompt.dirty() before overwriting", () => {
+  test("respects user-typed content via prompt.dirty() (does not overwrite)", () => {
+    // Behavior: if prompt is dirty, do NOT call prompt.set with the suggestion
+    // text. Just focus the editor. Otherwise, prefill normally. We verify the
+    // dirty-branch body does NOT contain prompt.set(.
     expect(source).toContain("prompt.dirty()")
+    const dirtyBranch = source.match(/if \(prompt\.dirty\(\)\)\s*\{[\s\S]*?\}/)
+    expect(dirtyBranch).not.toBeNull()
+    expect(dirtyBranch![0]).not.toContain("prompt.set(")
   })
 
   test("filters dismissed IDs against known chip IDs (no bare type cast)", () => {
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index d665ea55a..c301fa68d 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -5,6 +5,7 @@ import { usePrompt } from "@/context/prompt"
 import { useSettings } from "@/context/settings"
 import { useSync } from "@/context/sync"
 import { setCursorPosition } from "@/components/prompt-input/editor-dom"
+import { promptLength } from "@/components/prompt-input/history"
 import {
   HOME_SUGGESTION_CHIPS,
   resolveVisibleHomeSuggestions,
@@ -39,7 +40,7 @@ export const HomeSuggestionList: Component = () => {
   const settings = useSettings()
   const sync = useSync()
 
-  const sessionCount = createMemo(() => Object.keys(sync.data.session ?? {}).length)
+  const sessionCount = createMemo(() => sync.data.session?.length ?? 0)
   const seen = createMemo(() => settings.general.homeSuggestionsSeen())
 
   // Flip seen=true on first hydrated state with sessions. Returning users
@@ -76,17 +77,13 @@ export const HomeSuggestionList: Component = () => {
 
   const prefill = (text: string) => {
     markSeen()
-    // Respect user-typed content. If they've already started a message, append
-    // the suggestion text with a space; otherwise replace.
+    // If the user has already started typing (or @-mentioned a file), do not
+    // overwrite their work. Just focus the editor and leave the composer
+    // untouched. They can clear it and click the chip again if they really
+    // want the suggestion. Naively merging would lose non-text parts like
+    // file/agent mentions, which is a worse failure mode than no-op here.
     if (prompt.dirty()) {
-      const existing = prompt
-        .current()
-        .map((part) => ("content" in part ? part.content : ""))
-        .join("")
-      const suffix = existing.endsWith(" ") || existing.length === 0 ? "" : " "
-      const merged = `${existing}${suffix}${text}`
-      prompt.set([{ type: "text", content: merged, start: 0, end: merged.length }], merged.length)
-      requestAnimationFrame(() => focusComposerEditor(merged.length))
+      requestAnimationFrame(() => focusComposerEditor(promptLength(prompt.current())))
       return
     }
     prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
index 14369eab5..596713d3e 100644
--- a/packages/app/src/components/settings-general.home-suggestions.test.ts
+++ b/packages/app/src/components/settings-general.home-suggestions.test.ts
@@ -21,6 +21,14 @@ describe("settings-general home suggestions row", () => {
     expect(source).toContain("homeSuggestionsSeen()")
   })
 
+  test("restore button is hidden when sessions already exist (no-op recovery)", () => {
+    // Once any session is present, firstTimeVisitor is false regardless of
+    // dismissed/seen, so restoring would be a silent no-op. Settings must
+    // therefore consult sync.data.session length to decide whether to render.
+    expect(source).toContain("sync.data.session")
+    expect(source).toContain("sync.ready")
+  })
+
   test("restore action resets BOTH dismissed and seen", () => {
     // The single most important invariant: clicking restore must clear BOTH
     // state slots, otherwise the button is a silent no-op after section X.
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index a1b801736..688d6be65 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -18,6 +18,7 @@ import {
   sansInput,
   useSettings,
 } from "@/context/settings"
+import { useSync } from "@/context/sync"
 import { decode64 } from "@/utils/base64"
 import { Link } from "./link"
 import { SettingsList } from "./settings-list"
@@ -39,6 +40,7 @@ export const SettingsGeneral: Component = () => {
   const platform = usePlatform()
   const params = useParams()
   const settings = useSettings()
+  const sync = useSync()
 
   onMount(() => {
     void theme.loadThemes()
@@ -128,6 +130,12 @@ export const SettingsGeneral: Component = () => {
             <Show
               when={
                 settings.general.homeSuggestionsEnabled() &&
+                // Only meaningful while there are no sessions yet: that's the
+                // only state where chips can actually re-appear on home. Once
+                // any session exists, firstTimeVisitor is false regardless of
+                // dismissed/seen, so restoring would be a silent no-op.
+                sync.ready &&
+                (sync.data.session?.length ?? 0) === 0 &&
                 (settings.general.homeSuggestionsDismissed().length > 0 ||
                   settings.general.homeSuggestionsSeen())
               }

From f7582188c6057604b3c248c593fa942e4d8a7c4a Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 16:00:30 +0800
Subject: [PATCH 11/30] fix(app): defer markSeen until prefill actually accepts
 the chip

Round 5 P2: prefill flipped seen=true before the dirty-composer no-op
check, so clicking a chip while the composer already had user text
silently exited onboarding even though nothing happened. Move markSeen
after the dirty-branch return so seen only flips when a chip click
actually produced a prefill. Locked with an ordering assertion in the
contract test.

Round 5 was otherwise clean: Codex reported no findings, Claude reported
zero P0/P1. This is the iterate-to-zero terminal state per the user
directive.
---
 .../app/src/components/home/home-suggestion-list.test.ts | 9 ++++++++-
 .../app/src/components/home/home-suggestion-list.tsx     | 4 +++-
 2 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index 0d4b50b92..c7987f238 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -45,10 +45,17 @@ describe("HomeSuggestionList source contract", () => {
     expect(match![0]).toContain("markSeen()")
   })
 
-  test("chip click (prefill) DOES mark seen", () => {
+  test("chip click (prefill) DOES mark seen, but only AFTER the dirty no-op branch", () => {
     const match = source.match(/const prefill = [\s\S]*?\n  \}/)
     expect(match).not.toBeNull()
     expect(match![0]).toContain("markSeen()")
+    // Order: prompt.dirty() check must come before markSeen() so a chip click
+    // that becomes a no-op (because the composer was already dirty) does not
+    // silently exit onboarding.
+    const dirtyIndex = match![0].indexOf("prompt.dirty()")
+    const seenIndex = match![0].indexOf("markSeen()")
+    expect(dirtyIndex).toBeGreaterThan(-1)
+    expect(seenIndex).toBeGreaterThan(dirtyIndex)
   })
 
   test("exposes the documented data-component and data-action hooks for E2E", () => {
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index c301fa68d..965c36f82 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -76,16 +76,18 @@ export const HomeSuggestionList: Component = () => {
   }
 
   const prefill = (text: string) => {
-    markSeen()
     // If the user has already started typing (or @-mentioned a file), do not
     // overwrite their work. Just focus the editor and leave the composer
     // untouched. They can clear it and click the chip again if they really
     // want the suggestion. Naively merging would lose non-text parts like
     // file/agent mentions, which is a worse failure mode than no-op here.
+    // We also do NOT mark seen in this no-op path: the user hasn't actually
+    // engaged with onboarding, so flipping seen would silently exit them.
     if (prompt.dirty()) {
       requestAnimationFrame(() => focusComposerEditor(promptLength(prompt.current())))
       return
     }
+    markSeen()
     prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
     requestAnimationFrame(() => focusComposerEditor(text.length))
   }

From 98ef3b19187b744fe82081ccaf3db235ad5a93d4 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 16:09:33 +0800
Subject: [PATCH 12/30] fix(app): settings page must not depend on Sync
 provider

Manual dev:desktop verification surfaced a P0 I missed across five
crosscheck rounds: the Settings page renders outside the Sync provider,
so calling useSync() in SettingsGeneral throws "Sync context must be
used within a context provider" the moment the user opens Settings.

This was added in the previous fix as an extra gate that hid the restore
button for returning users. The right gate is simpler and does not need
sync at all: the dismissed list is non-empty exactly when chips were
hidden via either path (per-row or section), because dismissAll already
writes all chip ids. For a returning user the createEffect auto-latches
seen=true but leaves dismissed empty, so the button stays hidden and we
never surface a no-op recovery.

Restore still resets BOTH state slots so the section dismiss path
actually unwinds. Verified via dev:desktop after the patch: Settings
opens without crashing.

Lesson saved to memory: visual verification catches provider-boundary
bugs that source-substring contract tests cannot see.
---
 .../settings-general.home-suggestions.test.ts | 26 +++++++++----------
 .../app/src/components/settings-general.tsx   | 21 ++++++---------
 2 files changed, 20 insertions(+), 27 deletions(-)

diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
index 596713d3e..efbbd6d6a 100644
--- a/packages/app/src/components/settings-general.home-suggestions.test.ts
+++ b/packages/app/src/components/settings-general.home-suggestions.test.ts
@@ -13,25 +13,23 @@ describe("settings-general home suggestions row", () => {
     expect(source).toContain("settings.general.setHomeSuggestionsEnabled(")
   })
 
-  test("restore button is visible whenever any chip is dismissed OR seen was set", () => {
-    // Either source slot indicates "chips are currently hidden because of past
-    // user action" and a restore should be offered. Gating only on dismissed
-    // would leave the button hidden after a section dismiss (which writes seen).
+  test("restore button is gated on dismissed-non-empty (no useSync coupling)", () => {
+    // dismissAll writes all chip ids, so dismissed-non-empty is true exactly
+    // when chips were hidden via either path (per-row or section). For a
+    // returning user the createEffect auto-latches seen=true but leaves
+    // dismissed empty, so the button stays hidden and we never surface a
+    // no-op recovery. This keeps Settings independent of the Sync provider,
+    // which is critical because the Settings page renders outside it.
     expect(source).toContain("homeSuggestionsDismissed().length > 0")
-    expect(source).toContain("homeSuggestionsSeen()")
-  })
-
-  test("restore button is hidden when sessions already exist (no-op recovery)", () => {
-    // Once any session is present, firstTimeVisitor is false regardless of
-    // dismissed/seen, so restoring would be a silent no-op. Settings must
-    // therefore consult sync.data.session length to decide whether to render.
-    expect(source).toContain("sync.data.session")
-    expect(source).toContain("sync.ready")
+    // Settings page renders outside the Sync provider; importing useSync
+    // throws "Sync context must be used within a context provider".
+    expect(source).not.toContain("useSync")
   })
 
   test("restore action resets BOTH dismissed and seen", () => {
     // The single most important invariant: clicking restore must clear BOTH
-    // state slots, otherwise the button is a silent no-op after section X.
+    // state slots, otherwise the button is a silent no-op after section X
+    // (which writes both dismissed and seen).
     expect(source).toContain("setHomeSuggestionsDismissed([])")
     expect(source).toContain("setHomeSuggestionsSeen(false)")
   })
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index 688d6be65..01a9df1b0 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -18,7 +18,6 @@ import {
   sansInput,
   useSettings,
 } from "@/context/settings"
-import { useSync } from "@/context/sync"
 import { decode64 } from "@/utils/base64"
 import { Link } from "./link"
 import { SettingsList } from "./settings-list"
@@ -40,7 +39,6 @@ export const SettingsGeneral: Component = () => {
   const platform = usePlatform()
   const params = useParams()
   const settings = useSettings()
-  const sync = useSync()
 
   onMount(() => {
     void theme.loadThemes()
@@ -130,23 +128,20 @@ export const SettingsGeneral: Component = () => {
             <Show
               when={
                 settings.general.homeSuggestionsEnabled() &&
-                // Only meaningful while there are no sessions yet: that's the
-                // only state where chips can actually re-appear on home. Once
-                // any session exists, firstTimeVisitor is false regardless of
-                // dismissed/seen, so restoring would be a silent no-op.
-                sync.ready &&
-                (sync.data.session?.length ?? 0) === 0 &&
-                (settings.general.homeSuggestionsDismissed().length > 0 ||
-                  settings.general.homeSuggestionsSeen())
+                settings.general.homeSuggestionsDismissed().length > 0
               }
             >
+              {/* Gate on dismissed only: this is non-empty in exactly the two
+                  paths a Restore would actually help (per-row dismissal and
+                  section dismiss, since dismissAll writes all ids). For a
+                  returning user the createEffect auto-latches seen=true but
+                  leaves dismissed empty, so the button stays hidden and we
+                  do not surface a no-op recovery. Restore still resets BOTH
+                  state slots so the section dismiss path actually unwinds. */}
               <button
                 type="button"
                 class="text-fg-muted hover:text-fg-strong text-sm"
                 onClick={() => {
-                  // Restore must reset BOTH state slots. Dismissed alone won't
-                  // bring chips back if section dismiss already flipped seen,
-                  // since firstTimeVisitor would still be false.
                   settings.general.setHomeSuggestionsDismissed([])
                   settings.general.setHomeSuggestionsSeen(false)
                 }}

From 2a147f7308d066f6f3d21b820c4bbf3e1d4a647b Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 16:20:50 +0800
Subject: [PATCH 13/30] refactor(app): collapse home onboarding to 3 rows with
 per-row dismiss only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Strip everything that the three-question test could not justify:
- Section-level X (with header label and dismissAll handler): users who
  want all chips gone can X each of the three rows in seconds.
- Settings master toggle (homeSuggestionsEnabled) and its Restore button:
  no plausible user crosses two screens to reopen a one-shot onboarding
  affordance. The toggle was 4 i18n strings, a Settings row, a contract
  test, and (most painfully) a sync-provider dependency from a page that
  renders outside it.
- homeSuggestionsSeen one-way latch and its createEffect: defends only
  the edge case of a returning user who deletes every session and then
  reopens home. The harm in that case is "they see three onboarding
  rows again" — not worth a persisted flag, two interacting state slots,
  or the five rounds of crosscheck cascade that the flag triggered.

What remains is the minimum that actually carries the design intent:
one persisted field (homeSuggestionsDismissed: string[]), one component
that renders three rows when sync.ready && sessionCount === 0 && there
are undismissed chips, and a per-row X that hides on hover/focus only.
Three rows all dismissed naturally collapse the section to nothing.

Net: ~150 fewer lines, no provider-boundary bug, contract surface
shrinks from 30 assertions to 13.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 122 +++---------------
 .../home/home-suggestion-list.test.ts         |  67 ++--------
 .../components/home/home-suggestion-list.tsx  |  57 +-------
 .../home/home-suggestions-state.test.ts       |  20 +--
 .../components/home/home-suggestions-state.ts |   2 -
 .../settings-general.home-suggestions.test.ts |  43 ------
 .../app/src/components/settings-general.tsx   |  36 ------
 packages/app/src/context/settings.tsx         |  24 ----
 packages/app/src/i18n/en.ts                   |   7 +-
 packages/app/src/i18n/zh.ts                   |   5 -
 .../test/config/e2e-smoke-tagging.test.ts     |   1 -
 11 files changed, 47 insertions(+), 337 deletions(-)
 delete mode 100644 packages/app/src/components/settings-general.home-suggestions.test.ts

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 10c7534a3..a6ede568f 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -4,7 +4,6 @@ import { promptSelector } from "../selectors"
 const suggestionListSelector = '[data-component="home-suggestion-list"]'
 const rowSelector = '[data-action="home-suggestion-row"]'
 const rowDismissSelector = '[data-action="home-suggestion-row-dismiss"]'
-const sectionDismissSelector = '[data-action="home-suggestion-section-dismiss"]'
 
 test("@smoke home shows 3 suggestion rows for a first-time visitor", async ({ page, project }) => {
   await project.open()
@@ -24,9 +23,9 @@ test("@smoke clicking a suggestion row prefills the composer", async ({ page, pr
 
   const editor = page.locator(promptSelector)
   await expect(editor).toBeFocused()
-  // contenteditable rendered via renderEditorWithCursor may include zero-width chars / wrapping
-  // spans, so toHaveText (strict equality) can be flaky. toContainText asserts substring after
-  // textContent normalization which is the right granularity here.
+  // contenteditable rendered via renderEditorWithCursor may include zero-width
+  // chars or wrapping spans, so toHaveText (strict) is flaky. toContainText
+  // asserts substring after textContent normalization which is right here.
   await expect(editor).toContainText(text)
 })
 
@@ -46,25 +45,13 @@ test("@smoke per-row X dismisses one row and persists across reload", async ({ p
   await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(2)
 })
 
-test("@smoke section X dismisses all three rows and hides the section", async ({ page, project }) => {
-  await project.open()
-
-  const list = page.locator(suggestionListSelector)
-  await expect(list.locator(rowSelector)).toHaveCount(3)
-  await list.locator(sectionDismissSelector).click()
-  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
-})
-
 test("@smoke composer placeholder is the static home string", async ({ page, project }) => {
   await project.open()
 
   const editor = page.locator(promptSelector)
   await expect(editor).toBeVisible()
 
-  // Read the live locale and assert against the matching i18n value. A regression
-  // that swaps the placeholder to a wrong string in either locale must fail,
-  // not be masked by an either-or regex.
-  // Persistence key is "language" and shape is { locale: "zh" | "en" }; verified
+  // Persistence key is "language", shape is { locale: "zh" | "en" }, confirmed
   // via packages/app/src/context/language.tsx.
   const locale = await page.evaluate(() => {
     const raw = localStorage.getItem("language")
@@ -80,42 +67,36 @@ test("@smoke composer placeholder is the static home string", async ({ page, pro
   }
 })
 
+test("dismissing all 3 rows hides the section entirely", async ({ page, project }) => {
+  await project.open()
+  const list = page.locator(suggestionListSelector)
+  await expect(list.locator(rowSelector)).toHaveCount(3)
+
+  for (let i = 0; i < 3; i++) {
+    const firstRow = list.locator(rowSelector).first()
+    await firstRow.hover()
+    await list.locator(rowDismissSelector).first().click()
+  }
+
+  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+
+  await page.reload()
+  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+})
+
 test("returning visitor (sessions > 0) sees no suggestion list", async ({ page, project, assistant }) => {
   await project.open()
 
-  // create a session by sending a prompt
   await assistant.reply("reply to trigger a session")
   await page.locator(promptSelector).click()
   await page.keyboard.type("first prompt")
   await page.keyboard.press("Enter")
   await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
 
-  // navigate back to home — sessions now == 1
   await project.open()
   await expect(page.locator(suggestionListSelector)).toHaveCount(0)
 })
 
-test("hover reveals the per-row X (rest state hides it)", async ({ page, project }) => {
-  await project.open()
-
-  // disable CSS transitions to remove timing flakes between rest / hover state
-  await page.addStyleTag({ content: "* { transition: none !important; animation: none !important; }" })
-
-  const list = page.locator(suggestionListSelector)
-  const firstRow = list.locator(rowSelector).first()
-  const firstRowDismiss = list.locator(rowDismissSelector).first()
-
-  // rest state: per-row X is rendered but not visible (opacity-0)
-  await expect(firstRowDismiss).toHaveCSS("opacity", "0")
-  // and not clickable (pointer-events-none keeps it out of the hit-test surface)
-  await expect(firstRowDismiss).toHaveCSS("pointer-events", "none")
-
-  // hover the row → group-hover reveals the X (opacity-1) and re-enables clicks
-  await firstRow.hover()
-  await expect(firstRowDismiss).toHaveCSS("opacity", "1")
-  await expect(firstRowDismiss).toHaveCSS("pointer-events", "auto")
-})
-
 test("editing a prefilled suggestion preserves the user's edit on send", async ({ page, project, assistant }) => {
   await project.open()
   await assistant.reply("edited reply")
@@ -124,12 +105,10 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await page.locator(suggestionListSelector).locator(rowSelector).first().click()
   await expect(editor).toBeFocused()
 
-  // append a suffix
   await page.keyboard.type(" please be concise")
   await page.keyboard.press("Enter")
 
   await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
-  // the user message rendered should contain both the prefilled text and the suffix
   await expect(page.getByText(/please be concise/)).toBeVisible()
 })
 
@@ -141,66 +120,7 @@ test("clicking a chip with user-typed content does NOT overwrite the user conten
   await page.keyboard.type("my own draft text")
   await expect(editor).toContainText("my own draft text")
 
-  // click first chip — user content should be preserved (no merge, no overwrite)
   await page.locator(suggestionListSelector).locator(rowSelector).first().click()
   await expect(editor).toBeFocused()
   await expect(editor).toContainText("my own draft text")
 })
-
-test("settings toggle hides and restores the suggestion section via the real Settings UI", async ({
-  page,
-  project,
-}) => {
-  await project.open()
-  await expect(page.locator(suggestionListSelector)).toBeVisible()
-
-  // Open Settings (kbd shortcut path is project-wide; settings page is a full pane,
-  // not a dialog — see settings.spec.ts for the canonical opening behavior).
-  await page.goto("#/settings/general")
-  const switchEl = page.locator('[data-action="settings-home-suggestions"] [role="switch"]')
-  await expect(switchEl).toBeVisible()
-  // turn off
-  await switchEl.click()
-
-  await project.open()
-  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
-
-  // turn it back on via the real Settings switch
-  await page.goto("#/settings/general")
-  await switchEl.click()
-
-  await project.open()
-  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(3)
-})
-
-test("language switch updates chip text without losing dismissed state", async ({ page, project }) => {
-  await project.open()
-
-  const list = page.locator(suggestionListSelector)
-  // capture text of the second row in the current locale (first row will be dismissed below)
-  const secondRowTextBefore = (await list.locator(rowSelector).nth(1).innerText()).trim()
-
-  // dismiss the first row in current locale
-  await list.locator(rowSelector).first().hover()
-  await list.locator(rowDismissSelector).first().click()
-  await expect(list.locator(rowSelector)).toHaveCount(2)
-
-  // Confirmed via packages/app/src/context/language.tsx. Persistence key is "language",
-  // shape is { locale: "zh" | "en" }, migrated from legacy "language.v1".
-  await page.evaluate(() => {
-    const raw = localStorage.getItem("language")
-    const parsed = raw ? JSON.parse(raw) : { locale: "zh" }
-    parsed.locale = parsed.locale?.startsWith?.("zh") ? "en" : "zh"
-    localStorage.setItem("language", JSON.stringify(parsed))
-  })
-  await page.reload()
-
-  // still 2 rows visible (dismissed state preserved across locale flip)
-  const listAfter = page.locator(suggestionListSelector)
-  await expect(listAfter.locator(rowSelector)).toHaveCount(2)
-
-  // and chip text actually flipped to the other locale (key insight: the row text
-  // must NOT equal the pre-flip text — that would mean i18n didn't propagate)
-  const secondRowTextAfter = (await listAfter.locator(rowSelector).nth(0).innerText()).trim()
-  expect(secondRowTextAfter).not.toBe(secondRowTextBefore)
-})
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index c7987f238..1ce52d21b 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -12,57 +12,27 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("useLanguage")
   })
 
-  test("computes firstTimeVisitor from sync.data.session count", () => {
+  test("computes firstTimeVisitor from sync.data.session.length and sync.ready", () => {
     expect(source).toContain("sync.data.session")
     expect(source).toMatch(/sync\.data\.session\??\.length/)
-  })
-
-  test("guards firstTimeVisitor on sync.ready to avoid flashing during hydration", () => {
     expect(source).toContain("sync.ready")
   })
 
-  test("uses homeSuggestionsSeen as a one-way bit so returning users do not re-enter onboarding", () => {
-    // firstTimeVisitor must factor in seen flag
-    expect(source).toContain("homeSuggestionsSeen")
-    expect(source).toContain("setHomeSuggestionsSeen(true)")
-    // session-count > 0 should flip seen=true via createEffect (one-way hydration latch)
-    expect(source).toMatch(/createEffect\([\s\S]{0,400}setHomeSuggestionsSeen\(true\)/)
-  })
-
-  test("per-row dismiss does NOT mark seen (would otherwise hide section after the first dismiss)", () => {
-    // The dismissRow body must not call markSeen() — confirmed by inspecting the
-    // dismissRow function body in source. Encoded as: there is a dismissRow
-    // definition, and within ~400 chars of its declaration, markSeen() is not
-    // called between the dismissRow line and its closing `}`.
-    const match = source.match(/const dismissRow = [\s\S]*?\n  \}/)
-    expect(match).not.toBeNull()
-    expect(match![0]).not.toContain("markSeen()")
-  })
-
-  test("section dismiss (dismissAll) DOES mark seen", () => {
-    const match = source.match(/const dismissAll = [\s\S]*?\n  \}/)
-    expect(match).not.toBeNull()
-    expect(match![0]).toContain("markSeen()")
-  })
-
-  test("chip click (prefill) DOES mark seen, but only AFTER the dirty no-op branch", () => {
-    const match = source.match(/const prefill = [\s\S]*?\n  \}/)
-    expect(match).not.toBeNull()
-    expect(match![0]).toContain("markSeen()")
-    // Order: prompt.dirty() check must come before markSeen() so a chip click
-    // that becomes a no-op (because the composer was already dirty) does not
-    // silently exit onboarding.
-    const dirtyIndex = match![0].indexOf("prompt.dirty()")
-    const seenIndex = match![0].indexOf("markSeen()")
-    expect(dirtyIndex).toBeGreaterThan(-1)
-    expect(seenIndex).toBeGreaterThan(dirtyIndex)
-  })
-
   test("exposes the documented data-component and data-action hooks for E2E", () => {
     expect(source).toContain('data-component="home-suggestion-list"')
     expect(source).toContain('data-action="home-suggestion-row"')
     expect(source).toContain('data-action="home-suggestion-row-dismiss"')
-    expect(source).toContain('data-action="home-suggestion-section-dismiss"')
+  })
+
+  test("does NOT render a section-level dismiss (only per-row X remains)", () => {
+    expect(source).not.toContain("home-suggestion-section-dismiss")
+    expect(source).not.toContain("home.suggestion.section")
+  })
+
+  test("does NOT couple to homeSuggestionsEnabled or homeSuggestionsSeen (those were removed)", () => {
+    expect(source).not.toContain("homeSuggestionsEnabled")
+    expect(source).not.toContain("homeSuggestionsSeen")
+    expect(source).not.toContain("setHomeSuggestionsSeen")
   })
 
   test("prefills the composer via prompt.set and focuses the editor", () => {
@@ -75,9 +45,6 @@ describe("HomeSuggestionList source contract", () => {
   })
 
   test("respects user-typed content via prompt.dirty() (does not overwrite)", () => {
-    // Behavior: if prompt is dirty, do NOT call prompt.set with the suggestion
-    // text. Just focus the editor. Otherwise, prefill normally. We verify the
-    // dirty-branch body does NOT contain prompt.set(.
     expect(source).toContain("prompt.dirty()")
     const dirtyBranch = source.match(/if \(prompt\.dirty\(\)\)\s*\{[\s\S]*?\}/)
     expect(dirtyBranch).not.toBeNull()
@@ -86,22 +53,16 @@ describe("HomeSuggestionList source contract", () => {
 
   test("filters dismissed IDs against known chip IDs (no bare type cast)", () => {
     expect(source).toContain("filterKnownIDs")
-    // negative: must NOT launder the persisted store value with a bare cast
     expect(source).not.toMatch(/homeSuggestionsDismissed\(\) as HomeSuggestionChipID\[\]/)
   })
 
   test("uses the settings accessor for read and write (not raw store)", () => {
-    expect(source).toContain("settings.general.homeSuggestionsEnabled()")
     expect(source).toContain("settings.general.homeSuggestionsDismissed()")
     expect(source).toContain("settings.general.setHomeSuggestionsDismissed(")
     expect(source).not.toContain("settings.store.general")
     expect(source).not.toContain("settings.setStore(")
   })
 
-  test("section dismiss writes all three chip ids", () => {
-    expect(source).toContain("HOME_SUGGESTION_CHIPS.map")
-  })
-
   test("rest-state dismiss button is not clickable (pointer-events-none) and not in tab order", () => {
     expect(source).toContain("pointer-events-none")
     expect(source).toContain("group-hover:pointer-events-auto")
@@ -112,9 +73,7 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("visibleChips().length > 0")
   })
 
-  test("uses i18n keys for chip text and aria-labels", () => {
-    expect(source).toContain("home.suggestion.section.label")
-    expect(source).toContain("home.suggestion.section.dismiss")
+  test("uses i18n keys for chip text and aria-label", () => {
     expect(source).toContain("home.suggestion.row.dismiss")
   })
 })
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 965c36f82..d330a52c6 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -1,4 +1,4 @@
-import { For, Show, createEffect, createMemo, type Component } from "solid-js"
+import { For, Show, createMemo, type Component } from "solid-js"
 import { Icon } from "@opencode-ai/ui/icon"
 import { useLanguage } from "@/context/language"
 import { usePrompt } from "@/context/prompt"
@@ -41,25 +41,13 @@ export const HomeSuggestionList: Component = () => {
   const sync = useSync()
 
   const sessionCount = createMemo(() => sync.data.session?.length ?? 0)
-  const seen = createMemo(() => settings.general.homeSuggestionsSeen())
-
-  // Flip seen=true on first hydrated state with sessions. Returning users
-  // who clean up all sessions will never re-enter first-time onboarding.
-  createEffect(() => {
-    if (!sync.ready) return
-    if (seen()) return
-    if (sessionCount() > 0) settings.general.setHomeSuggestionsSeen(true)
-  })
-
-  // sync.ready guards against showing chips during initial hydration, where
-  // sync.data.session is briefly empty and every user looks like a new visitor.
-  // sync.ready is a reactive getter on the context, not a function call.
-  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0 && !seen())
+  // sync.ready guards against the brief hydration window where session is
+  // empty and every user looks new. sync.ready is a reactive getter.
+  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0)
 
   const visibleIDs = createMemo(() =>
     resolveVisibleHomeSuggestions({
       firstTimeVisitor: firstTimeVisitor(),
-      enabled: settings.general.homeSuggestionsEnabled(),
       dismissed: filterKnownIDs(settings.general.homeSuggestionsDismissed()),
     }),
   )
@@ -71,62 +59,27 @@ export const HomeSuggestionList: Component = () => {
 
   type I18nKey = Parameters<typeof language.t>[0]
 
-  const markSeen = () => {
-    if (!seen()) settings.general.setHomeSuggestionsSeen(true)
-  }
-
   const prefill = (text: string) => {
-    // If the user has already started typing (or @-mentioned a file), do not
-    // overwrite their work. Just focus the editor and leave the composer
-    // untouched. They can clear it and click the chip again if they really
-    // want the suggestion. Naively merging would lose non-text parts like
-    // file/agent mentions, which is a worse failure mode than no-op here.
-    // We also do NOT mark seen in this no-op path: the user hasn't actually
-    // engaged with onboarding, so flipping seen would silently exit them.
     if (prompt.dirty()) {
       requestAnimationFrame(() => focusComposerEditor(promptLength(prompt.current())))
       return
     }
-    markSeen()
     prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
     requestAnimationFrame(() => focusComposerEditor(text.length))
   }
 
   const dismissRow = (id: HomeSuggestionChipID) => {
-    // Per-row dismiss is fine-grained curation, not an onboarding exit signal.
-    // Do NOT mark seen here, or the section hides immediately after the first
-    // dismiss and the Settings restore button becomes a silent no-op.
     const current = filterKnownIDs(settings.general.homeSuggestionsDismissed())
     if (current.includes(id)) return
     settings.general.setHomeSuggestionsDismissed([...current, id])
   }
 
-  const dismissAll = () => {
-    markSeen()
-    settings.general.setHomeSuggestionsDismissed(HOME_SUGGESTION_CHIPS.map((chip) => chip.id))
-  }
-
   return (
     <Show when={visibleChips().length > 0}>
       <section
         data-component="home-suggestion-list"
-        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col gap-1"
+        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col"
       >
-        <header class="flex items-center justify-between px-1 text-fg-muted text-sm">
-          <div class="flex items-center gap-3 flex-1">
-            <span>{language.t("home.suggestion.section.label")}</span>
-            <div class="flex-1 border-t border-border-subtle" />
-          </div>
-          <button
-            type="button"
-            class="ml-3 text-fg-muted hover:text-fg-strong"
-            aria-label={language.t("home.suggestion.section.dismiss")}
-            onClick={dismissAll}
-            data-action="home-suggestion-section-dismiss"
-          >
-            <Icon name="close" class="size-4" />
-          </button>
-        </header>
         <ul class="flex flex-col">
           <For each={visibleChips()}>
             {(chip) => (
diff --git a/packages/app/src/components/home/home-suggestions-state.test.ts b/packages/app/src/components/home/home-suggestions-state.test.ts
index ed4e4b95f..6a9e4cbbc 100644
--- a/packages/app/src/components/home/home-suggestions-state.test.ts
+++ b/packages/app/src/components/home/home-suggestions-state.test.ts
@@ -8,29 +8,23 @@ import {
 describe("resolveVisibleHomeSuggestions", () => {
   const allIDs = HOME_SUGGESTION_CHIPS.map((chip) => chip.id)
 
-  test("returns all chips when first-time + enabled + nothing dismissed", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed: [] })).toEqual(allIDs)
+  test("returns all chips for a first-time visitor with nothing dismissed", () => {
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed: [] })).toEqual(allIDs)
   })
 
   test("returns empty when not a first-time visitor", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: false, enabled: true, dismissed: [] })).toEqual([])
-  })
-
-  test("returns empty when feature is disabled", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: false, dismissed: [] })).toEqual([])
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: false, dismissed: [] })).toEqual([])
   })
 
   test("filters dismissed chips while preserving original order", () => {
     const dismissed: HomeSuggestionChipID[] = ["news-brief"]
-    expect(
-      resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed }),
-    ).toEqual(allIDs.filter((id) => id !== "news-brief"))
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed })).toEqual(
+      allIDs.filter((id) => id !== "news-brief"),
+    )
   })
 
   test("returns empty when all three chips are dismissed", () => {
-    expect(
-      resolveVisibleHomeSuggestions({ firstTimeVisitor: true, enabled: true, dismissed: allIDs }),
-    ).toEqual([])
+    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed: allIDs })).toEqual([])
   })
 
   test("HOME_SUGGESTION_CHIPS has stable IDs and three entries", () => {
diff --git a/packages/app/src/components/home/home-suggestions-state.ts b/packages/app/src/components/home/home-suggestions-state.ts
index 12d7f1627..4c0479562 100644
--- a/packages/app/src/components/home/home-suggestions-state.ts
+++ b/packages/app/src/components/home/home-suggestions-state.ts
@@ -13,13 +13,11 @@ export const HOME_SUGGESTION_CHIPS: readonly HomeSuggestionChip[] = [
 
 export interface ResolveHomeSuggestionsInput {
   firstTimeVisitor: boolean
-  enabled: boolean
   dismissed: readonly HomeSuggestionChipID[]
 }
 
 export function resolveVisibleHomeSuggestions(input: ResolveHomeSuggestionsInput): HomeSuggestionChipID[] {
   if (!input.firstTimeVisitor) return []
-  if (!input.enabled) return []
   const dismissedSet = new Set(input.dismissed)
   return HOME_SUGGESTION_CHIPS.map((chip) => chip.id).filter((id) => !dismissedSet.has(id))
 }
diff --git a/packages/app/src/components/settings-general.home-suggestions.test.ts b/packages/app/src/components/settings-general.home-suggestions.test.ts
deleted file mode 100644
index efbbd6d6a..000000000
--- a/packages/app/src/components/settings-general.home-suggestions.test.ts
+++ /dev/null
@@ -1,43 +0,0 @@
-import { describe, expect, test } from "bun:test"
-import { readFileSync } from "node:fs"
-
-describe("settings-general home suggestions row", () => {
-  const source = readFileSync("src/components/settings-general.tsx", "utf8")
-
-  test("renders the suggestion toggle row with the documented i18n title", () => {
-    expect(source).toContain("settings.general.homeSuggestions")
-  })
-
-  test("wires the Switch to settings.general.homeSuggestionsEnabled accessor", () => {
-    expect(source).toContain("settings.general.homeSuggestionsEnabled()")
-    expect(source).toContain("settings.general.setHomeSuggestionsEnabled(")
-  })
-
-  test("restore button is gated on dismissed-non-empty (no useSync coupling)", () => {
-    // dismissAll writes all chip ids, so dismissed-non-empty is true exactly
-    // when chips were hidden via either path (per-row or section). For a
-    // returning user the createEffect auto-latches seen=true but leaves
-    // dismissed empty, so the button stays hidden and we never surface a
-    // no-op recovery. This keeps Settings independent of the Sync provider,
-    // which is critical because the Settings page renders outside it.
-    expect(source).toContain("homeSuggestionsDismissed().length > 0")
-    // Settings page renders outside the Sync provider; importing useSync
-    // throws "Sync context must be used within a context provider".
-    expect(source).not.toContain("useSync")
-  })
-
-  test("restore action resets BOTH dismissed and seen", () => {
-    // The single most important invariant: clicking restore must clear BOTH
-    // state slots, otherwise the button is a silent no-op after section X
-    // (which writes both dismissed and seen).
-    expect(source).toContain("setHomeSuggestionsDismissed([])")
-    expect(source).toContain("setHomeSuggestionsSeen(false)")
-  })
-
-  test("switch toggle is a plain on/off without auto-clear side effects", () => {
-    // The previous auto-clear-on-re-enable branch was dead code under the seen
-    // flag (clearing dismissed did not restore chips). The dedicated restore
-    // button now owns that responsibility; toggle stays simple.
-    expect(source).not.toMatch(/setHomeSuggestionsEnabled\(checked\)[\s\S]{0,200}setHomeSuggestionsDismissed\(\[\]\)/)
-  })
-})
diff --git a/packages/app/src/components/settings-general.tsx b/packages/app/src/components/settings-general.tsx
index 01a9df1b0..c1e47ad20 100644
--- a/packages/app/src/components/settings-general.tsx
+++ b/packages/app/src/components/settings-general.tsx
@@ -120,42 +120,6 @@ export const SettingsGeneral: Component = () => {
 
         <SettingsWebSearchRow />
 
-        <SettingsRow
-          title={language.t("settings.general.homeSuggestions")}
-          description={language.t("settings.general.homeSuggestions.description")}
-        >
-          <div class="flex items-center gap-3" data-action="settings-home-suggestions">
-            <Show
-              when={
-                settings.general.homeSuggestionsEnabled() &&
-                settings.general.homeSuggestionsDismissed().length > 0
-              }
-            >
-              {/* Gate on dismissed only: this is non-empty in exactly the two
-                  paths a Restore would actually help (per-row dismissal and
-                  section dismiss, since dismissAll writes all ids). For a
-                  returning user the createEffect auto-latches seen=true but
-                  leaves dismissed empty, so the button stays hidden and we
-                  do not surface a no-op recovery. Restore still resets BOTH
-                  state slots so the section dismiss path actually unwinds. */}
-              <button
-                type="button"
-                class="text-fg-muted hover:text-fg-strong text-sm"
-                onClick={() => {
-                  settings.general.setHomeSuggestionsDismissed([])
-                  settings.general.setHomeSuggestionsSeen(false)
-                }}
-              >
-                {language.t("settings.general.homeSuggestions.reset")}
-              </button>
-            </Show>
-            <Switch
-              checked={settings.general.homeSuggestionsEnabled()}
-              onChange={(checked) => settings.general.setHomeSuggestionsEnabled(checked)}
-            />
-          </div>
-        </SettingsRow>
-
         <SettingsRow
           title={language.t("settings.general.row.reasoningSummaries.title")}
           description={language.t("settings.general.row.reasoningSummaries.description")}
diff --git a/packages/app/src/context/settings.tsx b/packages/app/src/context/settings.tsx
index 7c5a32809..4a3bc9b5c 100644
--- a/packages/app/src/context/settings.tsx
+++ b/packages/app/src/context/settings.tsx
@@ -33,9 +33,7 @@ export interface Settings {
     editToolPartsExpanded: boolean
     lspEnabled: boolean
     webSearchEnabled: boolean
-    homeSuggestionsEnabled: boolean
     homeSuggestionsDismissed: string[]
-    homeSuggestionsSeen: boolean
   }
   updates: {
     startup: boolean
@@ -117,9 +115,7 @@ const defaultSettings: Settings = {
     editToolPartsExpanded: false,
     lspEnabled: false,
     webSearchEnabled: true,
-    homeSuggestionsEnabled: true,
     homeSuggestionsDismissed: [],
-    homeSuggestionsSeen: false,
   },
   updates: {
     startup: true,
@@ -291,13 +287,6 @@ export const { use: useSettings, provider: SettingsProvider } = createSimpleCont
         setWebSearchEnabled(value: boolean) {
           setStore("general", "webSearchEnabled", value)
         },
-        homeSuggestionsEnabled: withFallback(
-          () => store.general?.homeSuggestionsEnabled,
-          defaultSettings.general.homeSuggestionsEnabled,
-        ),
-        setHomeSuggestionsEnabled(value: boolean) {
-          setStore("general", "homeSuggestionsEnabled", value)
-        },
         homeSuggestionsDismissed: withFallback(
           () => store.general?.homeSuggestionsDismissed,
           defaultSettings.general.homeSuggestionsDismissed,
@@ -305,19 +294,6 @@ export const { use: useSettings, provider: SettingsProvider } = createSimpleCont
         setHomeSuggestionsDismissed(value: string[]) {
           setStore("general", "homeSuggestionsDismissed", value)
         },
-        // homeSuggestionsSeen is a one-way bit: flips to true when the user
-        // has any session hydrated, clicks a chip, or dismisses the whole
-        // section. Per-row dismiss does NOT flip it (those are curation, not
-        // exit). Without this flag, a returning user who deletes all sessions
-        // would re-enter "first-time visitor" state and see onboarding chips
-        // again, which the design explicitly rejects.
-        homeSuggestionsSeen: withFallback(
-          () => store.general?.homeSuggestionsSeen,
-          defaultSettings.general.homeSuggestionsSeen,
-        ),
-        setHomeSuggestionsSeen(value: boolean) {
-          setStore("general", "homeSuggestionsSeen", value)
-        },
       },
       updates: {
         startup: withFallback(() => store.updates?.startup, defaultSettings.updates.startup),
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 20e4117e0..4d54b03ad 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -570,10 +570,8 @@ export const dict = {
 
   "home.recentProjects": "Recent projects",
   "home.hero.title": "What should we work on?",
-  "home.suggestion.section.label": "Prompt suggestions",
-  "home.suggestion.section.dismiss": "Dismiss all prompt suggestions",
   "home.suggestion.row.dismiss": "Dismiss this prompt",
-  "home.suggestion.analyze-spreadsheet": "Analyze a spreadsheet — surface key data and anomalies",
+  "home.suggestion.analyze-spreadsheet": "Analyze a spreadsheet and surface key data",
   "home.suggestion.news-brief": "Summarize today's news worth following into a brief",
   "home.suggestion.draft-email": "Draft a work email for me",
 
@@ -884,9 +882,6 @@ export const dict = {
     "Show edit, write, and patch tool parts expanded by default in the timeline",
   "settings.general.row.lsp.title": "Language Server Protocol (LSP)",
   "settings.general.row.lsp.description": "Detect type errors and symbol references when editing code",
-  "settings.general.homeSuggestions": "Home prompt suggestions",
-  "settings.general.homeSuggestions.description": "Show 3 prompt suggestion rows under the composer for new visitors. Click a row to prefill the input.",
-  "settings.general.homeSuggestions.reset": "Restore all suggestions",
   "settings.general.webSearch.title": "Web search",
   "settings.general.webSearch.description": "Let agents look up fresh information online when needed",
   "settings.general.webSearch.chip.free": "Free (bundled)",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index 0db7fd4a0..f503c93f1 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -540,8 +540,6 @@ export const dict = {
 
   "home.recentProjects": "最近项目",
   "home.hero.title": "今天我们做点什么？",
-  "home.suggestion.section.label": "提示词建议",
-  "home.suggestion.section.dismiss": "关闭所有提示词建议",
   "home.suggestion.row.dismiss": "关闭该提示词",
   "home.suggestion.analyze-spreadsheet": "帮我分析一份表格，找出关键数据和异常",
   "home.suggestion.news-brief": "查一下今天值得关注的新闻，整理一份简报",
@@ -773,9 +771,6 @@ export const dict = {
   "settings.general.row.editToolPartsExpanded.description": "默认在时间线中展开 edit、write 和 patch 工具部分",
   "settings.general.row.lsp.title": "语言服务器协议（LSP）",
   "settings.general.row.lsp.description": "修改代码时识别项目类型错误和符号引用",
-  "settings.general.homeSuggestions": "首页提示词建议",
-  "settings.general.homeSuggestions.description": "新用户在首页 composer 下方显示 3 行提示词建议；点击预填到输入框",
-  "settings.general.homeSuggestions.reset": "恢复全部建议",
   "settings.general.webSearch.title": "网页搜索",
   "settings.general.webSearch.description": "联网获取最新资料",
   "settings.general.webSearch.chip.free": "内置免费额度",
diff --git a/packages/opencode/test/config/e2e-smoke-tagging.test.ts b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
index e5d71cfe0..01d8302fb 100644
--- a/packages/opencode/test/config/e2e-smoke-tagging.test.ts
+++ b/packages/opencode/test/config/e2e-smoke-tagging.test.ts
@@ -18,7 +18,6 @@ const expectedSmokeTests = [
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke composer placeholder is the static home string",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke home shows 3 suggestion rows for a first-time visitor",
   "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke per-row X dismisses one row and persists across reload",
-  "packages/app/e2e/onboarding/home-suggestion-chips.spec.ts:@smoke section X dismisses all three rows and hides the section",
   "packages/app/e2e/prompt/first-message-reply.spec.ts:@smoke first replied message in a new session renders without page errors",
   "packages/app/e2e/prompt/prompt.spec.ts:@smoke can send a prompt and receive a reply",
   "packages/app/e2e/release-notes/release-notes-toast.spec.ts:@smoke shows subtle toast when stored version is older than current",

From 72adb71b1fb72e2afa8172203a1c26466b2b25c9 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 16:34:02 +0800
Subject: [PATCH 14/30] style(app): tighten home suggestion list visuals per
 design review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three findings from dev:desktop manual verification:

- Row width: container max-w was 640px (same as composer), but composer
  has its own visual padding, so rows looked wider than the input. Tighten
  to max-w-[520px] so rows sit visually inside the composer's bounding
  box.
- Row hover: the full-width bg-row-hover-overlay highlight felt hollow on
  short text. Replace with a text-color hover (fg-muted → fg-strong) so
  the affordance reads as "this is interactive" without the loud band.
- Dismiss X: size-4 icon felt heavy. Drop to size-3 inside a 20px square
  affordance with rounded corners and its own hover bg+color, so the
  control has clear self-feedback when targeted.
---
 .../app/src/components/home/home-suggestion-list.tsx   | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index d330a52c6..b00ed6e35 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -78,15 +78,15 @@ export const HomeSuggestionList: Component = () => {
     <Show when={visibleChips().length > 0}>
       <section
         data-component="home-suggestion-list"
-        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col"
+        class="mx-auto mt-6 flex w-full max-w-[520px] flex-col"
       >
         <ul class="flex flex-col">
           <For each={visibleChips()}>
             {(chip) => (
-              <li class="group flex items-center justify-between px-1 py-2 hover:bg-row-hover-overlay">
+              <li class="group flex items-center justify-between gap-2 py-1.5">
                 <button
                   type="button"
-                  class="flex-1 text-left text-fg-base hover:text-fg-strong"
+                  class="flex-1 text-left text-fg-muted hover:text-fg-strong transition-colors"
                   onClick={() => prefill(language.t(chip.i18nKey as I18nKey))}
                   data-action="home-suggestion-row"
                   data-chip-id={chip.id}
@@ -96,13 +96,13 @@ export const HomeSuggestionList: Component = () => {
                 <button
                   type="button"
                   tabIndex={-1}
-                  class="ml-3 text-fg-muted opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto hover:text-fg-strong transition-opacity"
+                  class="flex size-5 items-center justify-center rounded text-fg-muted opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto hover:bg-row-hover-overlay hover:text-fg-strong transition-opacity"
                   aria-label={language.t("home.suggestion.row.dismiss")}
                   onClick={() => dismissRow(chip.id)}
                   data-action="home-suggestion-row-dismiss"
                   data-chip-id={chip.id}
                 >
-                  <Icon name="close" class="size-4" />
+                  <Icon name="close" class="size-3" />
                 </button>
               </li>
             )}

From cd954ce78553fcec3016abae2a00c023a5d22e72 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 16:54:26 +0800
Subject: [PATCH 15/30] style(app): align home suggestion rows with
 picker-family DNA
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the home-grown hover styling with the DESIGN.md picker-family /
session-row idiom that PawWork uses everywhere else (session row at
L399, picker contract at L415, settings nav row at L595, all share one
hover language). The previous "fg-muted to fg-strong on text only" was
imperceptible at 13px — confirmed live in dev:desktop.

Visual changes:
- Container width 520 to 640, aligned with the composer's outer edge so
  rows visually live inside the composer's bounding box rather than
  floating above as a separate, narrower strip.
- Row shell: h-30 + radius-sm + px-2 (sitting in DESIGN.md L77 30-system).
- Rest state: text-fg-weak (the quiet onboarding tone).
- Hover: bg-row-hover-overlay (4% black, the PawWork picker-family
  standard) + text-fg-strong. This is the hover signal the rest of the
  product trains on — list rows should feel the same here.
- Dismiss X: 30x30 ghost icon button + radius-md + 16px icon, hover
  uses bg-row-active-overlay (6%) per DESIGN.md L401 ("one tier deeper
  than the row to read separately"). 4px negative right margin lets it
  visually flush with the row edge.
- focus-within: row gets the same overlay as hover so keyboard users
  see the focus target without needing the brand outline ring.

No new tokens, no design deviations — pure reuse of established
patterns. Picked variant B from the side-by-side preview after manual
review.
---
 .../components/home/home-suggestion-list.tsx  | 22 +++++++++++++------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index b00ed6e35..aa4b819e6 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -41,8 +41,8 @@ export const HomeSuggestionList: Component = () => {
   const sync = useSync()
 
   const sessionCount = createMemo(() => sync.data.session?.length ?? 0)
-  // sync.ready guards against the brief hydration window where session is
-  // empty and every user looks new. sync.ready is a reactive getter.
+  // sync.ready guards the brief hydration window where session is empty and
+  // every user looks new. sync.ready is a reactive getter on the context.
   const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0)
 
   const visibleIDs = createMemo(() =>
@@ -60,6 +60,8 @@ export const HomeSuggestionList: Component = () => {
   type I18nKey = Parameters<typeof language.t>[0]
 
   const prefill = (text: string) => {
+    // Dirty composer: do not overwrite user-typed content (including @-mentions).
+    // Just focus the editor and leave it alone.
     if (prompt.dirty()) {
       requestAnimationFrame(() => focusComposerEditor(promptLength(prompt.current())))
       return
@@ -78,15 +80,18 @@ export const HomeSuggestionList: Component = () => {
     <Show when={visibleChips().length > 0}>
       <section
         data-component="home-suggestion-list"
-        class="mx-auto mt-6 flex w-full max-w-[520px] flex-col"
+        // Aligned with composer (max-w-[640px] in session-new-view.tsx:24) so
+        // rows live inside the composer's bounding box, matching the DESIGN.md
+        // picker-family / session-row idiom (DESIGN.md L399, L415, L595).
+        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col"
       >
         <ul class="flex flex-col">
           <For each={visibleChips()}>
             {(chip) => (
-              <li class="group flex items-center justify-between gap-2 py-1.5">
+              <li class="group flex h-[30px] items-center gap-2 rounded-sm px-2 transition-colors hover:bg-row-hover-overlay focus-within:bg-row-hover-overlay">
                 <button
                   type="button"
-                  class="flex-1 text-left text-fg-muted hover:text-fg-strong transition-colors"
+                  class="flex h-full flex-1 items-center text-left text-fg-weak transition-colors group-hover:text-fg-strong group-focus-within:text-fg-strong focus:outline-none"
                   onClick={() => prefill(language.t(chip.i18nKey as I18nKey))}
                   data-action="home-suggestion-row"
                   data-chip-id={chip.id}
@@ -96,13 +101,16 @@ export const HomeSuggestionList: Component = () => {
                 <button
                   type="button"
                   tabIndex={-1}
-                  class="flex size-5 items-center justify-center rounded text-fg-muted opacity-0 pointer-events-none group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto hover:bg-row-hover-overlay hover:text-fg-strong transition-opacity"
+                  // 30×30 ghost icon button per DESIGN.md L334: hover overlay is
+                  // --row-active-overlay (6%), "one tier deeper than the row to
+                  // read separately" (DESIGN.md L401, session-row action).
+                  class="-mr-1 flex size-[30px] shrink-0 items-center justify-center rounded-md text-fg-weak opacity-0 pointer-events-none transition-opacity hover:bg-row-active-overlay hover:text-fg-strong group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto"
                   aria-label={language.t("home.suggestion.row.dismiss")}
                   onClick={() => dismissRow(chip.id)}
                   data-action="home-suggestion-row-dismiss"
                   data-chip-id={chip.id}
                 >
-                  <Icon name="close" class="size-3" />
+                  <Icon name="close" class="size-4" />
                 </button>
               </li>
             )}

From 8e58682724bd1b3ced59d416e24f1d666cfb9de8 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 17:04:23 +0800
Subject: [PATCH 16/30] refactor(home): inset rows and add breathing gap to
 suggestion list

Composer is max-w-[640px] with 1px border + 16px inner padding, so its
text frame starts 17px inside the container. Insetting the row container
by 16px on each side (max-w-[608px]) keeps row hover-overlay inside the
composer's visible text frame instead of overshooting it.

Adds gap-1 (4px) between rows per DESIGN.md L548 list-items rhythm so
the three rows breathe instead of reading as a packed menu.
---
 .../app/src/components/home/home-suggestion-list.tsx  | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index aa4b819e6..cbd6ba063 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -80,12 +80,13 @@ export const HomeSuggestionList: Component = () => {
     <Show when={visibleChips().length > 0}>
       <section
         data-component="home-suggestion-list"
-        // Aligned with composer (max-w-[640px] in session-new-view.tsx:24) so
-        // rows live inside the composer's bounding box, matching the DESIGN.md
-        // picker-family / session-row idiom (DESIGN.md L399, L415, L595).
-        class="mx-auto mt-6 flex w-full max-w-[640px] flex-col"
+        // Composer is max-w-[640px] with 1px border + 16px inner padding, so
+        // its text frame starts 17px inside the container. Inset 16px on each
+        // side (640 - 32 = 608) so row hover-overlay lands inside the composer's
+        // visible text frame instead of overshooting it.
+        class="mx-auto mt-6 flex w-full max-w-[608px] flex-col"
       >
-        <ul class="flex flex-col">
+        <ul class="flex flex-col gap-1">
           <For each={visibleChips()}>
             {(chip) => (
               <li class="group flex h-[30px] items-center gap-2 rounded-sm px-2 transition-colors hover:bg-row-hover-overlay focus-within:bg-row-hover-overlay">

From 7fd6265ac30aa9290019b046ccc15c058cbdcff2 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 17:42:28 +0800
Subject: [PATCH 17/30] feat(home): split chip label and prefill prompt,
 refocus tasks on OfficeCLI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously each suggestion row showed the same text it prefilled into the
composer, so the chip had no room to be a short hook and the prefill had
no room to give the agent task context. Splits chip into a short labelKey
(what the user sees in the row) and a longer promptKey (what gets prefilled
on click).

Replaces the three demo tasks to lean on PawWork's bundled officecli
binary, which is the real local-agent differentiator:

- folder-organize: organize a folder, propose plan before acting
- excel-analysis: surface key data, outliers, trends via officecli
- ppt-outline: generate a PPT outline from Word/PDF/Markdown via officecli

Each prompt names the task, lists outputs, and points at officecli where
relevant, but does not over-prescribe how the agent should ask clarifying
questions — the agent will naturally ask for the file path on its own.

Labels are written as a substring of their prompts so the existing e2e
"row text appears in composer after click" assertion still holds.
---
 .../components/home/home-suggestion-list.tsx  |  4 +--
 .../home/home-suggestions-state.test.ts       | 11 ++++----
 .../components/home/home-suggestions-state.ts | 28 +++++++++++++++----
 packages/app/src/i18n/en.ts                   | 12 ++++++--
 packages/app/src/i18n/zh.ts                   | 12 ++++++--
 5 files changed, 49 insertions(+), 18 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index cbd6ba063..eeff23e91 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -93,11 +93,11 @@ export const HomeSuggestionList: Component = () => {
                 <button
                   type="button"
                   class="flex h-full flex-1 items-center text-left text-fg-weak transition-colors group-hover:text-fg-strong group-focus-within:text-fg-strong focus:outline-none"
-                  onClick={() => prefill(language.t(chip.i18nKey as I18nKey))}
+                  onClick={() => prefill(language.t(chip.promptKey as I18nKey))}
                   data-action="home-suggestion-row"
                   data-chip-id={chip.id}
                 >
-                  {language.t(chip.i18nKey as I18nKey)}
+                  {language.t(chip.labelKey as I18nKey)}
                 </button>
                 <button
                   type="button"
diff --git a/packages/app/src/components/home/home-suggestions-state.test.ts b/packages/app/src/components/home/home-suggestions-state.test.ts
index 6a9e4cbbc..96ee2abf4 100644
--- a/packages/app/src/components/home/home-suggestions-state.test.ts
+++ b/packages/app/src/components/home/home-suggestions-state.test.ts
@@ -17,9 +17,9 @@ describe("resolveVisibleHomeSuggestions", () => {
   })
 
   test("filters dismissed chips while preserving original order", () => {
-    const dismissed: HomeSuggestionChipID[] = ["news-brief"]
+    const dismissed: HomeSuggestionChipID[] = ["excel-analysis"]
     expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed })).toEqual(
-      allIDs.filter((id) => id !== "news-brief"),
+      allIDs.filter((id) => id !== "excel-analysis"),
     )
   })
 
@@ -29,12 +29,13 @@ describe("resolveVisibleHomeSuggestions", () => {
 
   test("HOME_SUGGESTION_CHIPS has stable IDs and three entries", () => {
     expect(HOME_SUGGESTION_CHIPS).toHaveLength(3)
-    expect(allIDs).toEqual(["analyze-spreadsheet", "news-brief", "draft-email"])
+    expect(allIDs).toEqual(["folder-organize", "excel-analysis", "ppt-outline"])
   })
 
-  test("each chip exposes a stable i18n key", () => {
+  test("each chip exposes stable label and prompt i18n keys", () => {
     for (const chip of HOME_SUGGESTION_CHIPS) {
-      expect(chip.i18nKey).toMatch(/^home\.suggestion\./)
+      expect(chip.labelKey).toMatch(/^home\.suggestion\..+\.label$/)
+      expect(chip.promptKey).toMatch(/^home\.suggestion\..+\.prompt$/)
     }
   })
 })
diff --git a/packages/app/src/components/home/home-suggestions-state.ts b/packages/app/src/components/home/home-suggestions-state.ts
index 4c0479562..55494b746 100644
--- a/packages/app/src/components/home/home-suggestions-state.ts
+++ b/packages/app/src/components/home/home-suggestions-state.ts
@@ -1,14 +1,32 @@
-export type HomeSuggestionChipID = "analyze-spreadsheet" | "news-brief" | "draft-email"
+export type HomeSuggestionChipID = "folder-organize" | "excel-analysis" | "ppt-outline"
 
 export interface HomeSuggestionChip {
   id: HomeSuggestionChipID
-  i18nKey: string
+  // Short text shown in the row. Should be a substring of the prompt so the
+  // existing e2e prefill assertion (editor contains row text) still holds.
+  labelKey: string
+  // Full prefilled prompt sent to the agent on click. Substantially longer
+  // than labelKey by design: gives the agent task verb, output spec, and tool
+  // hint, while showing the user what a good prompt looks like.
+  promptKey: string
 }
 
 export const HOME_SUGGESTION_CHIPS: readonly HomeSuggestionChip[] = [
-  { id: "analyze-spreadsheet", i18nKey: "home.suggestion.analyze-spreadsheet" },
-  { id: "news-brief", i18nKey: "home.suggestion.news-brief" },
-  { id: "draft-email", i18nKey: "home.suggestion.draft-email" },
+  {
+    id: "folder-organize",
+    labelKey: "home.suggestion.folder-organize.label",
+    promptKey: "home.suggestion.folder-organize.prompt",
+  },
+  {
+    id: "excel-analysis",
+    labelKey: "home.suggestion.excel-analysis.label",
+    promptKey: "home.suggestion.excel-analysis.prompt",
+  },
+  {
+    id: "ppt-outline",
+    labelKey: "home.suggestion.ppt-outline.label",
+    promptKey: "home.suggestion.ppt-outline.prompt",
+  },
 ]
 
 export interface ResolveHomeSuggestionsInput {
diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 4d54b03ad..5b5708380 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -571,9 +571,15 @@ export const dict = {
   "home.recentProjects": "Recent projects",
   "home.hero.title": "What should we work on?",
   "home.suggestion.row.dismiss": "Dismiss this prompt",
-  "home.suggestion.analyze-spreadsheet": "Analyze a spreadsheet and surface key data",
-  "home.suggestion.news-brief": "Summarize today's news worth following into a brief",
-  "home.suggestion.draft-email": "Draft a work email for me",
+  "home.suggestion.folder-organize.label": "Organize a folder",
+  "home.suggestion.folder-organize.prompt":
+    "Organize a folder: group similar files into subfolders, flag duplicates and stale files, rename messy names. Scan first and propose a plan for me to approve.",
+  "home.suggestion.excel-analysis.label": "Analyze an Excel spreadsheet",
+  "home.suggestion.excel-analysis.prompt":
+    "Analyze an Excel spreadsheet: surface key data points, outliers, trends worth noting, and a clear next step. Use officecli to read the file.",
+  "home.suggestion.ppt-outline.label": "Generate a PPT outline",
+  "home.suggestion.ppt-outline.prompt":
+    "Generate a PPT outline from a source doc: sections, each slide's title and 3-5 bullets, plus key chart/data suggestions. Use officecli for Word/PDF/Markdown.",
 
   "session.tab.session": "Session",
   "session.tab.review": "Review",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index f503c93f1..954095437 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -541,9 +541,15 @@ export const dict = {
   "home.recentProjects": "最近项目",
   "home.hero.title": "今天我们做点什么？",
   "home.suggestion.row.dismiss": "关闭该提示词",
-  "home.suggestion.analyze-spreadsheet": "帮我分析一份表格，找出关键数据和异常",
-  "home.suggestion.news-brief": "查一下今天值得关注的新闻，整理一份简报",
-  "home.suggestion.draft-email": "帮我起草一封工作邮件",
+  "home.suggestion.folder-organize.label": "整理一个文件夹",
+  "home.suggestion.folder-organize.prompt":
+    "帮我整理一个文件夹：把同类文件归到子目录、标记重复或过时的文件、给命名乱的提新名字。先扫描内容，输出一份方案让我确认再动手。",
+  "home.suggestion.excel-analysis.label": "分析一份 Excel 表格",
+  "home.suggestion.excel-analysis.prompt":
+    "帮我分析一份 Excel 表格：找出关键数据点、异常值和趋势，给我一条清晰的下一步建议。用 officecli 读取。",
+  "home.suggestion.ppt-outline.label": "从一份资料生成 PPT 大纲",
+  "home.suggestion.ppt-outline.prompt":
+    "帮我从一份资料生成 PPT 大纲：章节结构、每页标题和 3-5 条要点、关键图表或数据建议。用 officecli 读取 Word/PDF/Markdown。",
 
   "session.tab.session": "会话",
   "session.tab.review": "审查",

From 72432b7492afb3a877eae3d97bc759e3d54e2393 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 18:08:43 +0800
Subject: [PATCH 18/30] fix(home): let chip clicks always replace composer
 content
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous dirty-guard treated any non-empty composer as user-owned,
which blocked the obvious onboarding flow: click chip A to see it, click
chip B to switch. The composer just focused with no visible change, and
first-time visitors couldn't tell whether the second click registered.

Drop the guard. First-time visitor's home composer has no ownership
semantics — chip content is a system suggestion, not user-authored, so
freely swapping between chips is the right exploration affordance.
The cost of "user typed then misclicked a chip" is a 50-80 char prompt,
not real work; the gain is the explore-by-clicking flow finally working.

Replaces the "does NOT overwrite user-typed content" e2e test with one
that asserts the now-desired behavior: clicking another suggestion
replaces the previous prefill.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 19 ++++++++++++-------
 .../components/home/home-suggestion-list.tsx  | 11 ++++-------
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index a6ede568f..3c98bfc91 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -112,15 +112,20 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await expect(page.getByText(/please be concise/)).toBeVisible()
 })
 
-test("clicking a chip with user-typed content does NOT overwrite the user content", async ({ page, project }) => {
+test("clicking another suggestion replaces the previous prefill", async ({ page, project }) => {
   await project.open()
 
+  const list = page.locator(suggestionListSelector)
   const editor = page.locator(promptSelector)
-  await editor.click()
-  await page.keyboard.type("my own draft text")
-  await expect(editor).toContainText("my own draft text")
+  const rows = list.locator(rowSelector)
 
-  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
-  await expect(editor).toBeFocused()
-  await expect(editor).toContainText("my own draft text")
+  const firstText = (await rows.first().innerText()).trim()
+  const secondText = (await rows.nth(1).innerText()).trim()
+
+  await rows.first().click()
+  await expect(editor).toContainText(firstText)
+
+  await rows.nth(1).click()
+  await expect(editor).toContainText(secondText)
+  await expect(editor).not.toContainText(firstText)
 })
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index eeff23e91..1763c9a03 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -5,7 +5,6 @@ import { usePrompt } from "@/context/prompt"
 import { useSettings } from "@/context/settings"
 import { useSync } from "@/context/sync"
 import { setCursorPosition } from "@/components/prompt-input/editor-dom"
-import { promptLength } from "@/components/prompt-input/history"
 import {
   HOME_SUGGESTION_CHIPS,
   resolveVisibleHomeSuggestions,
@@ -60,12 +59,10 @@ export const HomeSuggestionList: Component = () => {
   type I18nKey = Parameters<typeof language.t>[0]
 
   const prefill = (text: string) => {
-    // Dirty composer: do not overwrite user-typed content (including @-mentions).
-    // Just focus the editor and leave it alone.
-    if (prompt.dirty()) {
-      requestAnimationFrame(() => focusComposerEditor(promptLength(prompt.current())))
-      return
-    }
+    // Always replace. First-time visitor's home composer has no ownership
+    // semantics: chip content is a system suggestion, not user-authored.
+    // Letting subsequent chip clicks swap freely makes the "try A, then B"
+    // exploration that onboarding chips invite actually work.
     prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
     requestAnimationFrame(() => focusComposerEditor(text.length))
   }

From 94529949209ff7f0d8dc72c72615c6ea89ec9134 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 18:32:25 +0800
Subject: [PATCH 19/30] feat(home): track chip source, auto-dismiss on send for
 capability discovery

Previously chip visibility was a single gate (per-project sessionCount === 0),
so switching to a new workspace re-pitched chips users had already engaged
with. The fix is to recognize that these chips are capability discovery
(each highlighting a distinct officecli use case) rather than a one-shot
onboarding tour: each chip should "graduate" on use and stay off, while
unused chips can still reappear in fresh workspaces.

Adds a currentChipSource signal in HomeSuggestionList that tracks "which
chip the composer content came from." Set on chip click, cleared when the
composer drains, sticky through user edits. A combined lifecycle effect
observes sessionCount + prompt.dirty in a single tick so session-create
and composer-empty resolve in a defined order: when a session is created
while source is set, that chip is added to homeSuggestionsDismissed
globally.

The dismissed list semantic widens to "reasons this chip no longer shows"
(user-X'd plus auto-graduated). Per-row X behavior unchanged.

Adds 3 e2e cases covering the new state machine: chip-used auto-dismiss,
switch-then-send only dismisses the last selection, and discard-then-type
does not credit any chip. Source-contract unit test for the old dirty
guard is replaced with assertions that pin the new tracking shape.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 73 +++++++++++++++++++
 .../home/home-suggestion-list.test.ts         | 17 +++--
 .../components/home/home-suggestion-list.tsx  | 51 ++++++++++---
 3 files changed, 126 insertions(+), 15 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 3c98bfc91..648621db4 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -1,3 +1,4 @@
+import type { Page } from "@playwright/test"
 import { test, expect } from "../fixtures"
 import { promptSelector } from "../selectors"
 
@@ -5,6 +6,21 @@ const suggestionListSelector = '[data-component="home-suggestion-list"]'
 const rowSelector = '[data-action="home-suggestion-row"]'
 const rowDismissSelector = '[data-action="home-suggestion-row-dismiss"]'
 
+async function readDismissedFromStorage(page: Page): Promise<string[]> {
+  // settings.v3 is persisted via the settings store (utils/persist.ts) — in the
+  // e2e web context this hits localStorage directly with key "settings.v3".
+  return await page.evaluate(() => {
+    try {
+      const raw = localStorage.getItem("settings.v3")
+      if (!raw) return []
+      const parsed = JSON.parse(raw)
+      return parsed?.general?.homeSuggestionsDismissed ?? []
+    } catch {
+      return []
+    }
+  })
+}
+
 test("@smoke home shows 3 suggestion rows for a first-time visitor", async ({ page, project }) => {
   await project.open()
 
@@ -129,3 +145,60 @@ test("clicking another suggestion replaces the previous prefill", async ({ page,
   await expect(editor).toContainText(secondText)
   await expect(editor).not.toContainText(firstText)
 })
+
+test("using a chip via send auto-dismisses it for capability discovery", async ({ page, project, assistant }) => {
+  await project.open()
+  await assistant.reply("auto-dismiss reply")
+
+  const firstRow = page.locator(suggestionListSelector).locator(rowSelector).first()
+  const firstChipID = await firstRow.getAttribute("data-chip-id")
+  expect(firstChipID).toBeTruthy()
+
+  await firstRow.click()
+  await page.keyboard.press("Enter")
+  await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
+
+  const dismissed = await readDismissedFromStorage(page)
+  expect(dismissed).toContain(firstChipID!)
+})
+
+test("switching chips before send dismisses only the last selection", async ({ page, project, assistant }) => {
+  await project.open()
+  await assistant.reply("only-last reply")
+
+  const rows = page.locator(suggestionListSelector).locator(rowSelector)
+  const firstChipID = await rows.first().getAttribute("data-chip-id")
+  const secondChipID = await rows.nth(1).getAttribute("data-chip-id")
+
+  await rows.first().click()
+  await rows.nth(1).click()
+  await page.keyboard.press("Enter")
+  await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
+
+  const dismissed = await readDismissedFromStorage(page)
+  expect(dismissed).toContain(secondChipID!)
+  expect(dismissed).not.toContain(firstChipID!)
+})
+
+test("discarding chip prefill and typing own prompt does not auto-dismiss", async ({ page, project, assistant }) => {
+  await project.open()
+  await assistant.reply("discard reply")
+
+  const editor = page.locator(promptSelector)
+  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
+  await expect(editor).toBeFocused()
+
+  // Drain composer so the lifecycle effect clears currentChipSource.
+  await page.evaluate(() => {
+    document.execCommand("selectAll")
+  })
+  await page.keyboard.press("Backspace")
+
+  // Type fresh user content — source stays null (typing into empty does not set it).
+  await page.keyboard.type("my own prompt content")
+  await page.keyboard.press("Enter")
+  await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
+
+  const dismissed = await readDismissedFromStorage(page)
+  expect(dismissed).toEqual([])
+})
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index 1ce52d21b..eab38ba76 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -44,11 +44,18 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("setCursorPosition")
   })
 
-  test("respects user-typed content via prompt.dirty() (does not overwrite)", () => {
-    expect(source).toContain("prompt.dirty()")
-    const dirtyBranch = source.match(/if \(prompt\.dirty\(\)\)\s*\{[\s\S]*?\}/)
-    expect(dirtyBranch).not.toBeNull()
-    expect(dirtyBranch![0]).not.toContain("prompt.set(")
+  test("prefill unconditionally replaces composer content (no dirty-guard skip)", () => {
+    // Chip clicks must always overwrite so the click-A-then-B exploration works.
+    // The previous "respect user-typed content" guard was replaced by per-chip
+    // currentChipSource tracking + auto-dismiss on send (see spec § Chip Lifecycle).
+    expect(source).not.toMatch(/if \(prompt\.dirty\(\)\)\s*\{[\s\S]{0,200}return/)
+  })
+
+  test("tracks chip source and auto-dismisses on session create", () => {
+    expect(source).toContain("currentChipSource")
+    expect(source).toContain("setCurrentChipSource")
+    expect(source).toMatch(/sessionCount\(\)/)
+    expect(source).toMatch(/dismissRow\(source\)/)
   })
 
   test("filters dismissed IDs against known chip IDs (no bare type cast)", () => {
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 1763c9a03..f85e92e40 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -1,4 +1,4 @@
-import { For, Show, createMemo, type Component } from "solid-js"
+import { For, Show, createEffect, createMemo, createSignal, type Component } from "solid-js"
 import { Icon } from "@opencode-ai/ui/icon"
 import { useLanguage } from "@/context/language"
 import { usePrompt } from "@/context/prompt"
@@ -58,14 +58,20 @@ export const HomeSuggestionList: Component = () => {
 
   type I18nKey = Parameters<typeof language.t>[0]
 
-  const prefill = (text: string) => {
-    // Always replace. First-time visitor's home composer has no ownership
-    // semantics: chip content is a system suggestion, not user-authored.
-    // Letting subsequent chip clicks swap freely makes the "try A, then B"
-    // exploration that onboarding chips invite actually work.
-    prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
-    requestAnimationFrame(() => focusComposerEditor(text.length))
-  }
+  // ─── Chip lifecycle state machine (see spec § Chip Lifecycle) ───
+  // currentChipSource tracks "the chip this composer content came from."
+  //   null  → composer is empty, or content was typed by user with no chip origin
+  //   X     → composer was prefilled by chip X (user edits don't reset — "edited
+  //           still counts as using chip X")
+  // Transitions:
+  //   chip X click          → setSource(X)
+  //   composer becomes empty → setSource(null)   (handled in the lifecycle effect)
+  //   user edits non-empty   → no change (sticky through edits)
+  // Side effect: when sessionCount transitions upward with source set, the chip
+  // graduated into a real task — dismiss it globally so capability discovery
+  // doesn't re-pitch it on the next visit or workspace.
+  // ────────────────────────────────────────────────────────────────
+  const [currentChipSource, setCurrentChipSource] = createSignal<HomeSuggestionChipID | null>(null)
 
   const dismissRow = (id: HomeSuggestionChipID) => {
     const current = filterKnownIDs(settings.general.homeSuggestionsDismissed())
@@ -73,6 +79,31 @@ export const HomeSuggestionList: Component = () => {
     settings.general.setHomeSuggestionsDismissed([...current, id])
   }
 
+  type LifecycleSnapshot = { count: number; dirty: boolean }
+  // Combined effect so session-create and composer-empty observed in the same
+  // tick resolve in a defined order: session-create wins (dismiss before clear).
+  createEffect<LifecycleSnapshot | undefined>((prev) => {
+    const count = sessionCount()
+    const dirty = prompt.dirty()
+    if (prev !== undefined) {
+      if (count > prev.count) {
+        const source = currentChipSource()
+        if (source) dismissRow(source)
+        setCurrentChipSource(null)
+      } else if (prev.dirty && !dirty) {
+        // Composer drained without a new session (user discarded the prefill).
+        setCurrentChipSource(null)
+      }
+    }
+    return { count, dirty }
+  }, undefined)
+
+  const prefill = (chipID: HomeSuggestionChipID, text: string) => {
+    prompt.set([{ type: "text", content: text, start: 0, end: text.length }], text.length)
+    setCurrentChipSource(chipID)
+    requestAnimationFrame(() => focusComposerEditor(text.length))
+  }
+
   return (
     <Show when={visibleChips().length > 0}>
       <section
@@ -90,7 +121,7 @@ export const HomeSuggestionList: Component = () => {
                 <button
                   type="button"
                   class="flex h-full flex-1 items-center text-left text-fg-weak transition-colors group-hover:text-fg-strong group-focus-within:text-fg-strong focus:outline-none"
-                  onClick={() => prefill(language.t(chip.promptKey as I18nKey))}
+                  onClick={() => prefill(chip.id, language.t(chip.promptKey as I18nKey))}
                   data-action="home-suggestion-row"
                   data-chip-id={chip.id}
                 >

From 3895bd6f6f89117914b92548d469fae9df10cd10 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 18:44:48 +0800
Subject: [PATCH 20/30] fix(home): decouple chip visibility from per-project
 session count
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous design coupled chip visibility to the current project having
zero sessions, which meant switching workspaces caused the entire chip
section to disappear for one project and reappear for another — even though
the user had already engaged with chips globally.

This contradicts the capability-discovery framing: each chip is an
independent reminder of one differentiator (officecli on folders, Excel,
PPT). It should disappear globally when used or X'd, and otherwise show
regardless of where the user is working.

Drops sessionCount from the visibility computation. The resolver now only
filters against the global dismissed list. sync.ready is kept as a
hydration guard so the dismissed list doesn't briefly read as [] mid-load.
sessionCount stays in the component but is consumed exclusively by the
auto-dismiss lifecycle effect (detect new session → dismiss source chip).

Replaces the now-wrong "returning visitor (sessions > 0) sees no
suggestion list" e2e with one that asserts the correct semantic: after
using one chip and creating a session, the home shows the remaining two
chips (not zero).
---
 .../onboarding/home-suggestion-chips.spec.ts  | 25 +++++++++++++++----
 .../home/home-suggestion-list.test.ts         |  5 +++-
 .../components/home/home-suggestion-list.tsx  | 19 ++++++++------
 .../home/home-suggestions-state.test.ts       | 14 +++--------
 .../components/home/home-suggestions-state.ts |  5 ++--
 5 files changed, 42 insertions(+), 26 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 648621db4..2c997f7fb 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -100,17 +100,32 @@ test("dismissing all 3 rows hides the section entirely", async ({ page, project
   await expect(page.locator(suggestionListSelector)).toHaveCount(0)
 })
 
-test("returning visitor (sessions > 0) sees no suggestion list", async ({ page, project, assistant }) => {
+test("used chip is gone but unused chips still appear on home after session creation", async ({
+  page,
+  project,
+  assistant,
+}) => {
   await project.open()
+  await assistant.reply("unused chips remain reply")
 
-  await assistant.reply("reply to trigger a session")
-  await page.locator(promptSelector).click()
-  await page.keyboard.type("first prompt")
+  const list = page.locator(suggestionListSelector)
+  const rows = list.locator(rowSelector)
+  await expect(rows).toHaveCount(3)
+
+  const firstChipID = await rows.first().getAttribute("data-chip-id")
+  expect(firstChipID).toBeTruthy()
+
+  await rows.first().click()
   await page.keyboard.press("Enter")
   await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
 
+  // Back to home: chips are NOT gated by sessionCount, so the unused two remain.
   await project.open()
-  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+  await expect(list.locator(rowSelector)).toHaveCount(2)
+  const remainingIDs = await list
+    .locator(rowSelector)
+    .evaluateAll((els) => els.map((el) => el.getAttribute("data-chip-id")))
+  expect(remainingIDs).not.toContain(firstChipID)
 })
 
 test("editing a prefilled suggestion preserves the user's edit on send", async ({ page, project, assistant }) => {
diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index eab38ba76..fc6a8b7c4 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -12,10 +12,13 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).toContain("useLanguage")
   })
 
-  test("computes firstTimeVisitor from sync.data.session.length and sync.ready", () => {
+  test("observes sessionCount only for the auto-dismiss effect, not as visibility gate", () => {
     expect(source).toContain("sync.data.session")
     expect(source).toMatch(/sync\.data\.session\??\.length/)
+    // sync.ready stays as a hydration guard so dismissed isn't read as [] mid-load.
     expect(source).toContain("sync.ready")
+    // No per-project gate: visibility no longer derives from sessionCount === 0.
+    expect(source).not.toMatch(/firstTimeVisitor/)
   })
 
   test("exposes the documented data-component and data-action hooks for E2E", () => {
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index f85e92e40..8ee086b0c 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -39,17 +39,20 @@ export const HomeSuggestionList: Component = () => {
   const settings = useSettings()
   const sync = useSync()
 
+  // sessionCount is observed only for the auto-dismiss side effect below —
+  // it does NOT gate visibility. Chips are pure capability discovery: shown
+  // until each is individually dismissed, regardless of current workspace.
   const sessionCount = createMemo(() => sync.data.session?.length ?? 0)
-  // sync.ready guards the brief hydration window where session is empty and
-  // every user looks new. sync.ready is a reactive getter on the context.
-  const firstTimeVisitor = createMemo(() => sync.ready && sessionCount() === 0)
 
-  const visibleIDs = createMemo(() =>
-    resolveVisibleHomeSuggestions({
-      firstTimeVisitor: firstTimeVisitor(),
+  const visibleIDs = createMemo(() => {
+    // sync.ready guards the brief hydration window where settings may not be
+    // fully loaded yet. Without this, the dismissed list may read as [] for a
+    // frame before its real value, causing chips to flash.
+    if (!sync.ready) return []
+    return resolveVisibleHomeSuggestions({
       dismissed: filterKnownIDs(settings.general.homeSuggestionsDismissed()),
-    }),
-  )
+    })
+  })
 
   const visibleChips = createMemo(() => {
     const ids = new Set(visibleIDs())
diff --git a/packages/app/src/components/home/home-suggestions-state.test.ts b/packages/app/src/components/home/home-suggestions-state.test.ts
index 96ee2abf4..7f561c614 100644
--- a/packages/app/src/components/home/home-suggestions-state.test.ts
+++ b/packages/app/src/components/home/home-suggestions-state.test.ts
@@ -8,23 +8,17 @@ import {
 describe("resolveVisibleHomeSuggestions", () => {
   const allIDs = HOME_SUGGESTION_CHIPS.map((chip) => chip.id)
 
-  test("returns all chips for a first-time visitor with nothing dismissed", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed: [] })).toEqual(allIDs)
-  })
-
-  test("returns empty when not a first-time visitor", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: false, dismissed: [] })).toEqual([])
+  test("returns all chips when nothing is dismissed", () => {
+    expect(resolveVisibleHomeSuggestions({ dismissed: [] })).toEqual(allIDs)
   })
 
   test("filters dismissed chips while preserving original order", () => {
     const dismissed: HomeSuggestionChipID[] = ["excel-analysis"]
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed })).toEqual(
-      allIDs.filter((id) => id !== "excel-analysis"),
-    )
+    expect(resolveVisibleHomeSuggestions({ dismissed })).toEqual(allIDs.filter((id) => id !== "excel-analysis"))
   })
 
   test("returns empty when all three chips are dismissed", () => {
-    expect(resolveVisibleHomeSuggestions({ firstTimeVisitor: true, dismissed: allIDs })).toEqual([])
+    expect(resolveVisibleHomeSuggestions({ dismissed: allIDs })).toEqual([])
   })
 
   test("HOME_SUGGESTION_CHIPS has stable IDs and three entries", () => {
diff --git a/packages/app/src/components/home/home-suggestions-state.ts b/packages/app/src/components/home/home-suggestions-state.ts
index 55494b746..9c7b016a1 100644
--- a/packages/app/src/components/home/home-suggestions-state.ts
+++ b/packages/app/src/components/home/home-suggestions-state.ts
@@ -30,12 +30,13 @@ export const HOME_SUGGESTION_CHIPS: readonly HomeSuggestionChip[] = [
 ]
 
 export interface ResolveHomeSuggestionsInput {
-  firstTimeVisitor: boolean
   dismissed: readonly HomeSuggestionChipID[]
 }
 
+// Pure capability-discovery: chips show until each is individually dismissed
+// (user-X'd or auto-marked after use). No per-project gating — switching
+// workspaces does not reset what the user has already engaged with.
 export function resolveVisibleHomeSuggestions(input: ResolveHomeSuggestionsInput): HomeSuggestionChipID[] {
-  if (!input.firstTimeVisitor) return []
   const dismissedSet = new Set(input.dismissed)
   return HOME_SUGGESTION_CHIPS.map((chip) => chip.id).filter((id) => !dismissedSet.has(id))
 }

From 4170dce9eca9f9e2a2bba819d07c6d6e676e4db1 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:11:55 +0800
Subject: [PATCH 21/30] feat(prompt): tell agents about bundled officecli
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PawWork ships an AI-friendly Office CLI on PATH, but nothing in the
system prompt or chip text told the model it exists. Two Excel/PPT
home chips quietly leaked the tool name ("用 officecli 读取") into
the prefill prompts to compensate, which both broke the "non-tech
user" framing and only helped when the user clicked the chip — not
when they typed "look at the budget spreadsheet on my desktop".

Move the awareness to where it belongs: a new `# Bundled
capabilities` section in pawwork.txt, placed after `# Tool
collaboration` so it reads as part of PawWork's identity rather
than an external dependency. Drop the implementation-detail
sentences from the zh/en chip prompts now that the awareness lives
in the system prompt.

The new section names officecli, points the model at `officecli
help` for syntax discovery, and locks the trigger to "reading or
modifying a real local Office file" so abstract topics like layout
advice don't accidentally invoke the CLI.
---
 packages/app/src/i18n/en.ts                      | 4 ++--
 packages/app/src/i18n/zh.ts                      | 4 ++--
 packages/opencode/src/session/prompt/pawwork.txt | 4 ++++
 3 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 5b5708380..69910fc52 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -576,10 +576,10 @@ export const dict = {
     "Organize a folder: group similar files into subfolders, flag duplicates and stale files, rename messy names. Scan first and propose a plan for me to approve.",
   "home.suggestion.excel-analysis.label": "Analyze an Excel spreadsheet",
   "home.suggestion.excel-analysis.prompt":
-    "Analyze an Excel spreadsheet: surface key data points, outliers, trends worth noting, and a clear next step. Use officecli to read the file.",
+    "Analyze an Excel spreadsheet: surface key data points, outliers, trends worth noting, and a clear next step.",
   "home.suggestion.ppt-outline.label": "Generate a PPT outline",
   "home.suggestion.ppt-outline.prompt":
-    "Generate a PPT outline from a source doc: sections, each slide's title and 3-5 bullets, plus key chart/data suggestions. Use officecli for Word/PDF/Markdown.",
+    "Generate a PPT outline from a source doc: sections, each slide's title and 3-5 bullets, plus key chart/data suggestions. Source can be Word, PDF, or Markdown.",
 
   "session.tab.session": "Session",
   "session.tab.review": "Review",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index 954095437..1b6ddc77e 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -546,10 +546,10 @@ export const dict = {
     "帮我整理一个文件夹：把同类文件归到子目录、标记重复或过时的文件、给命名乱的提新名字。先扫描内容，输出一份方案让我确认再动手。",
   "home.suggestion.excel-analysis.label": "分析一份 Excel 表格",
   "home.suggestion.excel-analysis.prompt":
-    "帮我分析一份 Excel 表格：找出关键数据点、异常值和趋势，给我一条清晰的下一步建议。用 officecli 读取。",
+    "帮我分析一份 Excel 表格：找出关键数据点、异常值和趋势，给我一条清晰的下一步建议。",
   "home.suggestion.ppt-outline.label": "从一份资料生成 PPT 大纲",
   "home.suggestion.ppt-outline.prompt":
-    "帮我从一份资料生成 PPT 大纲：章节结构、每页标题和 3-5 条要点、关键图表或数据建议。用 officecli 读取 Word/PDF/Markdown。",
+    "帮我从一份资料生成 PPT 大纲：章节结构、每页标题和 3-5 条要点、关键图表或数据建议。支持从 Word、PDF 或 Markdown 资料抽取。",
 
   "session.tab.session": "会话",
   "session.tab.review": "审查",
diff --git a/packages/opencode/src/session/prompt/pawwork.txt b/packages/opencode/src/session/prompt/pawwork.txt
index 5390ebd25..e5d7dd439 100644
--- a/packages/opencode/src/session/prompt/pawwork.txt
+++ b/packages/opencode/src/session/prompt/pawwork.txt
@@ -49,6 +49,10 @@ Pick the right helper before acting:
 
 If the user has already specified a path, execute it directly without re-asking. Otherwise reach for these helpers only when their specific trigger applies — handle ordinary work in this thread.
 
+# Bundled capabilities
+
+PawWork ships with `officecli`, a CLI built for AI agents to read and write Microsoft Office files on the user's machine: `.docx`, `.xlsx`, and `.pptx`. It is already on PATH inside the bash tool. When a task requires reading or modifying one of these file types on the local disk, prefer `officecli` over Python libraries (`python-docx`, `openpyxl`, `python-pptx`) or generic file reads. Run `officecli help` or `officecli <subcommand> --help` to discover subcommands and arguments before assuming syntax. Do not invoke it for tasks that are about Office topics in the abstract (e.g. layout advice) rather than operating on a real file.
+
 # Communication
 
 Use the user's language. Be concise, direct, and specific.

From 20bc61d4020800743b58516c785f27c66375715f Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:12:05 +0800
Subject: [PATCH 22/30] fix(shell): prepend bundled tools dir to PATH for shell
 mode and PTY
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The bash tool prepends PawWork's bundled tools directory (containing
officecli) to PATH so the agent can call those CLIs by bare name.
The same was missing from two other surfaces a user can reach:

- Prompt shell mode (`! <command>` in the composer) — running
  `! officecli help` in a packaged build still reported
  "command not found" because shellImpl built env from
  process.env directly.
- The PTY terminal panel — same root cause.

Extract `bundledToolsDir()` and `prependBundledTools()` helpers in
util/env.ts so the three surfaces share one source of truth, and
add unit coverage for the edge cases that matter most: the no-op
branch when resourcesPath is missing, the guard against an empty
resourcesPath leaking a relative "tools" entry into PATH, and the
empty-currentPath case.

Shell mode also gets `OFFICECLI_SKIP_UPDATE=1` matching the bash
tool — the prompt `!` path is agent-adjacent, not the user's
"native" terminal. PTY intentionally does not set that flag so
`officecli update` in the terminal panel behaves like any other
local shell.
---
 packages/opencode/src/pty/index.ts      | 10 ++++--
 packages/opencode/src/session/prompt.ts |  8 +++--
 packages/opencode/src/tool/bash.ts      |  7 ++--
 packages/opencode/src/util/env.ts       | 20 +++++++++++
 packages/opencode/test/util/env.test.ts | 48 +++++++++++++++++++++++--
 5 files changed, 81 insertions(+), 12 deletions(-)

diff --git a/packages/opencode/src/pty/index.ts b/packages/opencode/src/pty/index.ts
index 79d120f72..f0a104078 100644
--- a/packages/opencode/src/pty/index.ts
+++ b/packages/opencode/src/pty/index.ts
@@ -9,7 +9,7 @@ import { Log } from "@opencode-ai/core/util/log"
 import { lazy } from "@opencode-ai/util/lazy"
 import { Shell } from "@/shell/shell"
 import { Plugin } from "@/plugin"
-import { envValueCaseInsensitive, withoutInternalServerAuthEnv } from "@/util/env"
+import { envValueCaseInsensitive, prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
 import { Process } from "@/util/process"
 import { PtyID } from "./schema"
 import { Effect, Layer, Context } from "effect"
@@ -257,12 +257,16 @@ export namespace Pty {
 
         const cwd = input.cwd || s.dir
         const shell = yield* plugin.trigger("shell.env", { cwd }, { env: {} })
+        const shellEnvRecord = shell.env as Record<string, string>
+        const inputEnvRecord = (input.env ?? {}) as Record<string, string>
+        const currentPath = shellEnvRecord.PATH || inputEnvRecord.PATH || process.env.PATH || ""
         const env = withoutInternalServerAuthEnv({
           ...process.env,
-          ...input.env,
-          ...shell.env,
+          ...inputEnvRecord,
+          ...shellEnvRecord,
           TERM: "xterm-256color",
           OPENCODE_TERMINAL: "1",
+          PATH: prependBundledTools(currentPath),
         } as Record<string, string>)
         // bun-pty merges with the parent process environment internally, so
         // deleting these keys is not enough for PTY sessions. Override with
diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
index a64678bc3..3464f93b2 100644
--- a/packages/opencode/src/session/prompt.ts
+++ b/packages/opencode/src/session/prompt.ts
@@ -48,7 +48,7 @@ import { AppFileSystem } from "@opencode-ai/core/filesystem"
 import { Truncate } from "@/tool/truncate"
 import { decodeDataUrl } from "@/util/data-url"
 import { Process } from "@/util/process"
-import { withoutInternalServerAuthEnv } from "@/util/env"
+import { prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
 import { Cause, Deferred, Effect, Exit, Layer, Option, Scope, Context } from "effect"
 import { EffectLogger } from "@/effect"
 import { InstanceState } from "@/effect"
@@ -1209,10 +1209,14 @@ NOTE: At any point in time through this workflow you should feel free to ask the
             plugin.trigger("shell.env", { cwd, sessionID: input.sessionID, callID: part.callID }, { env: {} }),
           )
 
+          const shellEnvRecord = shellEnv.env as Record<string, string>
+          const currentPath = shellEnvRecord.PATH || process.env.PATH || ""
           const env = withoutInternalServerAuthEnv({
             ...process.env,
-            ...shellEnv.env,
+            ...shellEnvRecord,
             TERM: "dumb",
+            OFFICECLI_SKIP_UPDATE: "1",
+            PATH: prependBundledTools(currentPath),
             ...(shellName === "zsh" || shellName === "bash" ? { OPENCODE_SHELL_CWD: cwd } : {}),
           })
 
diff --git a/packages/opencode/src/tool/bash.ts b/packages/opencode/src/tool/bash.ts
index fd54433de..250f85dd3 100644
--- a/packages/opencode/src/tool/bash.ts
+++ b/packages/opencode/src/tool/bash.ts
@@ -23,7 +23,7 @@ import { Plugin } from "@/plugin"
 import { Effect, Stream } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
-import { withoutInternalServerAuthEnv } from "@/util/env"
+import { prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
 import { Global } from "@opencode-ai/core/global"
 import { assertExternalDirectoryEffect, resolveExternalPathForPermission } from "./external-directory"
 import { InstanceState } from "@/effect/instance-state"
@@ -468,16 +468,13 @@ export const BashTool = Tool.define(
         { cwd, sessionID: ctx.sessionID, callID: ctx.callID },
         { env: {} },
       )
-      // Prepend bundled tools directory to PATH so the agent can call them
-      const resourcesPath = (process as any).resourcesPath as string | undefined
-      const bundledToolsDir = resourcesPath ? path.join(resourcesPath, "tools") : ""
       const extraEnv = extra.env as Record<string, string>
       const currentPath = extraEnv.PATH || process.env.PATH || ""
       return withoutInternalServerAuthEnv({
         ...process.env,
         ...extraEnv,
         OFFICECLI_SKIP_UPDATE: "1",
-        PATH: bundledToolsDir ? `${bundledToolsDir}${path.delimiter}${currentPath}` : currentPath,
+        PATH: prependBundledTools(currentPath),
       })
     })
 
diff --git a/packages/opencode/src/util/env.ts b/packages/opencode/src/util/env.ts
index 456d9eb3d..6224fa954 100644
--- a/packages/opencode/src/util/env.ts
+++ b/packages/opencode/src/util/env.ts
@@ -1,3 +1,5 @@
+import path from "path"
+
 const INTERNAL_SERVER_AUTH_ENV = new Set(["opencode_server_password", "opencode_server_username"])
 
 export function withoutInternalServerAuthEnv<T extends Record<string, string | undefined>>(env: T): T {
@@ -12,3 +14,21 @@ export function envValueCaseInsensitive(env: Record<string, string | undefined>
   const normalized = name.toLowerCase()
   return Object.entries(env ?? {}).find(([key]) => key.toLowerCase() === normalized)?.[1]
 }
+
+// Returns the directory holding PawWork's bundled CLI tools (officecli, ...),
+// or "" when not running inside the packaged Electron app (e.g. plain `bun dev`).
+// In dev:desktop, process.resourcesPath points to the Electron framework's
+// Resources, not PawWork's — there's no tools/ subdir there, so the prepend
+// is a no-op (the directory simply doesn't exist on disk).
+export function bundledToolsDir(): string {
+  const resourcesPath = (process as unknown as { resourcesPath?: string }).resourcesPath
+  return resourcesPath ? path.join(resourcesPath, "tools") : ""
+}
+
+// Prepends bundledToolsDir to a PATH string so child processes can resolve
+// PawWork's bundled CLIs (e.g. `officecli`) by bare name. Pass the PATH that
+// will end up in the spawned env; pass "" if unknown.
+export function prependBundledTools(currentPath: string): string {
+  const dir = bundledToolsDir()
+  return dir ? `${dir}${path.delimiter}${currentPath}` : currentPath
+}
diff --git a/packages/opencode/test/util/env.test.ts b/packages/opencode/test/util/env.test.ts
index d0b43db60..103959979 100644
--- a/packages/opencode/test/util/env.test.ts
+++ b/packages/opencode/test/util/env.test.ts
@@ -1,5 +1,18 @@
-import { describe, expect, test } from "bun:test"
-import { withoutInternalServerAuthEnv } from "../../src/util/env"
+import { afterEach, describe, expect, test } from "bun:test"
+import path from "path"
+import { bundledToolsDir, prependBundledTools, withoutInternalServerAuthEnv } from "../../src/util/env"
+
+type ResourcesPathBag = { resourcesPath?: string }
+
+function setResourcesPath(value: string | undefined) {
+  const bag = process as unknown as ResourcesPathBag
+  if (value === undefined) delete bag.resourcesPath
+  else bag.resourcesPath = value
+}
+
+function getResourcesPath(): string | undefined {
+  return (process as unknown as ResourcesPathBag).resourcesPath
+}
 
 describe("util.env", () => {
   test("does not mutate caller-owned env objects", () => {
@@ -38,3 +51,34 @@ describe("util.env", () => {
     expect(sanitized).not.toBe(env)
   })
 })
+
+describe("util.env.bundledTools", () => {
+  const original = getResourcesPath()
+  afterEach(() => setResourcesPath(original))
+
+  test("returns empty string when resourcesPath is unset (e.g. plain node/bun)", () => {
+    setResourcesPath(undefined)
+    expect(bundledToolsDir()).toBe("")
+    expect(prependBundledTools("/usr/bin")).toBe("/usr/bin")
+  })
+
+  test("treats empty resourcesPath as unset so PATH is not poisoned with a relative 'tools'", () => {
+    // path.join("", "tools") returns the relative string "tools"; if that
+    // leaked into PATH, the shell would resolve `tools` against cwd. Guard.
+    setResourcesPath("")
+    expect(bundledToolsDir()).toBe("")
+    expect(prependBundledTools("/usr/bin")).toBe("/usr/bin")
+  })
+
+  test("prepends bundled tools dir to PATH, preserving the rest", () => {
+    setResourcesPath("/Applications/PawWork.app/Contents/Resources")
+    const expectedDir = path.join("/Applications/PawWork.app/Contents/Resources", "tools")
+    expect(bundledToolsDir()).toBe(expectedDir)
+    expect(prependBundledTools("/usr/bin:/bin")).toBe(`${expectedDir}${path.delimiter}/usr/bin:/bin`)
+  })
+
+  test("prepend with empty currentPath still yields a valid PATH (no trailing delimiter weirdness)", () => {
+    setResourcesPath("/r")
+    expect(prependBundledTools("")).toBe(`${path.join("/r", "tools")}${path.delimiter}`)
+  })
+})

From 65ed18ee736d34b70a8a73e3ea6d6d439897624e Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:23:46 +0800
Subject: [PATCH 23/30] fix(env): drop trailing PATH delimiter when currentPath
 is empty

POSIX treats an empty PATH segment (leading, trailing, or doubled
colon) as the current directory. When prependBundledTools was called
with an empty currentPath it emitted "<dir>:" - PawWork's bundled
tools followed by an implicit cwd-shadowing entry. A malicious file
in cwd named officecli would then shadow the bundled binary.

Return the bundled dir alone instead, and add a regression test.
---
 packages/opencode/src/util/env.ts       | 6 +++++-
 packages/opencode/test/util/env.test.ts | 7 +++++--
 2 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/packages/opencode/src/util/env.ts b/packages/opencode/src/util/env.ts
index 6224fa954..4164e81c1 100644
--- a/packages/opencode/src/util/env.ts
+++ b/packages/opencode/src/util/env.ts
@@ -30,5 +30,9 @@ export function bundledToolsDir(): string {
 // will end up in the spawned env; pass "" if unknown.
 export function prependBundledTools(currentPath: string): string {
   const dir = bundledToolsDir()
-  return dir ? `${dir}${path.delimiter}${currentPath}` : currentPath
+  if (!dir) return currentPath
+  // Don't append a trailing delimiter when currentPath is empty: on POSIX an
+  // empty PATH segment is interpreted as the current directory, which weakens
+  // command-resolution safety (cwd-shadowing of system commands).
+  return currentPath ? `${dir}${path.delimiter}${currentPath}` : dir
 }
diff --git a/packages/opencode/test/util/env.test.ts b/packages/opencode/test/util/env.test.ts
index 103959979..bb9ee9245 100644
--- a/packages/opencode/test/util/env.test.ts
+++ b/packages/opencode/test/util/env.test.ts
@@ -77,8 +77,11 @@ describe("util.env.bundledTools", () => {
     expect(prependBundledTools("/usr/bin:/bin")).toBe(`${expectedDir}${path.delimiter}/usr/bin:/bin`)
   })
 
-  test("prepend with empty currentPath still yields a valid PATH (no trailing delimiter weirdness)", () => {
+  test("prepend with empty currentPath returns bundled dir alone, never a trailing-delimiter PATH (cwd-shadowing guard)", () => {
+    // POSIX treats an empty PATH segment (leading/trailing/double colon) as
+    // the current directory, so emitting "/r/tools:" would let a malicious
+    // file in cwd shadow officecli. The helper must drop the delimiter.
     setResourcesPath("/r")
-    expect(prependBundledTools("")).toBe(`${path.join("/r", "tools")}${path.delimiter}`)
+    expect(prependBundledTools("")).toBe(path.join("/r", "tools"))
   })
 })

From 6608d6b60518a15422303d896aa133518a6f0cf2 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:23:52 +0800
Subject: [PATCH 24/30] fix(a11y): keep home suggestion dismiss button
 keyboard-reachable

The dismiss button was hidden at rest via opacity-0 plus
pointer-events-none, but it remained in the tab order. Restoring
the rest-state guard would have excluded keyboard-only users from
dismissing a chip. Reveal on focus-visible instead so Tab brings
the button into view and re-enables pointer events, while pointer
users still see the chip hover behavior unchanged.
---
 .../app/src/components/home/home-suggestion-list.test.ts   | 7 +++++--
 packages/app/src/components/home/home-suggestion-list.tsx  | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index fc6a8b7c4..3b3597949 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -73,10 +73,13 @@ describe("HomeSuggestionList source contract", () => {
     expect(source).not.toContain("settings.setStore(")
   })
 
-  test("rest-state dismiss button is not clickable (pointer-events-none) and not in tab order", () => {
+  test("rest-state dismiss button is not clickable (pointer-events-none) but stays keyboard-reachable", () => {
     expect(source).toContain("pointer-events-none")
     expect(source).toContain("group-hover:pointer-events-auto")
-    expect(source).toContain("tabIndex={-1}")
+    expect(source).toContain("focus-visible:pointer-events-auto")
+    // Must NOT be excluded from the tab order: keyboard-only users need a path
+    // to dismiss a chip. Reveal-on-focus handles the visual hiding.
+    expect(source).not.toContain("tabIndex={-1}")
   })
 
   test("renders nothing when there are no visible chips", () => {
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 8ee086b0c..b45d4ec36 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -132,11 +132,14 @@ export const HomeSuggestionList: Component = () => {
                 </button>
                 <button
                   type="button"
-                  tabIndex={-1}
                   // 30×30 ghost icon button per DESIGN.md L334: hover overlay is
                   // --row-active-overlay (6%), "one tier deeper than the row to
                   // read separately" (DESIGN.md L401, session-row action).
-                  class="-mr-1 flex size-[30px] shrink-0 items-center justify-center rounded-md text-fg-weak opacity-0 pointer-events-none transition-opacity hover:bg-row-active-overlay hover:text-fg-strong group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto"
+                  // Keyboard-reachable via Tab so a keyboard-only user can
+                  // dismiss a chip without a pointer; visually hidden at rest
+                  // and revealed only when the row is hovered or anything inside
+                  // the row has focus.
+                  class="-mr-1 flex size-[30px] shrink-0 items-center justify-center rounded-md text-fg-weak opacity-0 pointer-events-none transition-opacity hover:bg-row-active-overlay hover:text-fg-strong focus-visible:opacity-100 focus-visible:pointer-events-auto group-hover:opacity-100 group-hover:pointer-events-auto group-focus-within:opacity-100 group-focus-within:pointer-events-auto"
                   aria-label={language.t("home.suggestion.row.dismiss")}
                   onClick={() => dismissRow(chip.id)}
                   data-action="home-suggestion-row-dismiss"

From a24f84006bac83ef5196c3c5c9ba07c56a332569 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:44:04 +0800
Subject: [PATCH 25/30] fix(e2e): read language from the real LanguageProvider
 storage key

The composer-placeholder test read localStorage["language"] which never
exists; the LanguageProvider persists under "pawwork.global.dat:language"
(see other e2e tests already using that key). The wrong key always missed,
fell back to the test's "zh" default, and asserted the Chinese placeholder
against whatever the CI runner's navigator.language detection produced -
en-US in GitHub Actions, so the test deterministically failed.

Use the same key the provider writes, and fall back to "en" to match
detectLocale()'s final return when nothing is stored.
---
 .../onboarding/home-suggestion-chips.spec.ts    | 17 ++++++++++++-----
 1 file changed, 12 insertions(+), 5 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 2c997f7fb..735f22d18 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -67,12 +67,19 @@ test("@smoke composer placeholder is the static home string", async ({ page, pro
   const editor = page.locator(promptSelector)
   await expect(editor).toBeVisible()
 
-  // Persistence key is "language", shape is { locale: "zh" | "en" }, confirmed
-  // via packages/app/src/context/language.tsx.
+  // LanguageProvider persists under "pawwork.global.dat:language" with shape
+  // { locale: "zh" | "en" } (see packages/app/src/context/language.tsx). Falls
+  // back to "en" when unset, matching detectLocale()'s final return in a
+  // CI runner where navigator.language is "en-US".
   const locale = await page.evaluate(() => {
-    const raw = localStorage.getItem("language")
-    const parsed = raw ? JSON.parse(raw) : { locale: "zh" }
-    return parsed.locale?.startsWith?.("zh") ? "zh" : "en"
+    const raw = localStorage.getItem("pawwork.global.dat:language")
+    if (!raw) return "en"
+    try {
+      const parsed = JSON.parse(raw) as { locale?: string }
+      return parsed.locale?.startsWith?.("zh") ? "zh" : "en"
+    } catch {
+      return "en"
+    }
   })
   const label = await editor.getAttribute("aria-label")
   // i18n source: packages/app/src/i18n/{zh,en}.ts → prompt.placeholder.home

From c416e5e8b7e1ec7e54407bed361c64a3efbc9450 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 20:46:33 +0800
Subject: [PATCH 26/30] perf(home): defer suggestion list mount and drop
 dirty() subscription

Two cuts to fix perf-probe-baseline regression. The Compare-confirmed
run showed +183 to +267ms frame_gap_max on homepage-cold and
tool-default-open-heavy-bash (both scenarios start with project.open()
landing on home). Hard gate per the team: new features must not
regress perf or any regression must be imperceptible.

1. Lazy-import HomeSuggestionList from session-new-view so the module
   load + reactive setup runs after the home pays its first paint. The
   chip rows appear within one frame of the import resolving; users
   never see the gap.

2. Drop prompt.dirty() from the lifecycle effect. It was there to clear
   currentChipSource when the user emptied the composer, but every
   keystroke flipped dirty(), making the effect a hot-path subscriber
   on the composer typing loop. The replacement behavior is simpler
   and explained in the source comment: chip source is sticky once
   clicked, so click-then-type-your-own-thing still dismisses the chip.

The e2e "discarding chip prefill" test asserted the old reactive
behavior and is replaced by a test that pins the new sticky-source
semantics.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 19 +++++----
 .../components/home/home-suggestion-list.tsx  | 40 +++++++++----------
 .../components/session/session-new-view.tsx   | 16 ++++++--
 3 files changed, 44 insertions(+), 31 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 735f22d18..6eefd2449 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -202,25 +202,30 @@ test("switching chips before send dismisses only the last selection", async ({ p
   expect(dismissed).not.toContain(firstChipID!)
 })
 
-test("discarding chip prefill and typing own prompt does not auto-dismiss", async ({ page, project, assistant }) => {
+test("clicking a chip then sending any content dismisses it (sticky source)", async ({ page, project, assistant }) => {
   await project.open()
-  await assistant.reply("discard reply")
+  await assistant.reply("sticky source reply")
 
   const editor = page.locator(promptSelector)
-  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
+  const firstRow = page.locator(suggestionListSelector).locator(rowSelector).first()
+  const firstChipID = await firstRow.getAttribute("data-chip-id")
+  expect(firstChipID).toBeTruthy()
+
+  await firstRow.click()
   await expect(editor).toBeFocused()
 
-  // Drain composer so the lifecycle effect clears currentChipSource.
+  // Drain the prefill, then type user-authored content. The chip source is
+  // sticky once clicked — sending any prompt afterwards still dismisses it
+  // (the user engaged with the suggestion and chose a direction, no need to
+  // keep pitching it).
   await page.evaluate(() => {
     document.execCommand("selectAll")
   })
   await page.keyboard.press("Backspace")
-
-  // Type fresh user content — source stays null (typing into empty does not set it).
   await page.keyboard.type("my own prompt content")
   await page.keyboard.press("Enter")
   await expect.poll(() => page.url(), { timeout: 30_000 }).toContain("/session/")
 
   const dismissed = await readDismissedFromStorage(page)
-  expect(dismissed).toEqual([])
+  expect(dismissed).toContain(firstChipID!)
 })
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index b45d4ec36..144e7ac6e 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -63,16 +63,23 @@ export const HomeSuggestionList: Component = () => {
 
   // ─── Chip lifecycle state machine (see spec § Chip Lifecycle) ───
   // currentChipSource tracks "the chip this composer content came from."
-  //   null  → composer is empty, or content was typed by user with no chip origin
-  //   X     → composer was prefilled by chip X (user edits don't reset — "edited
-  //           still counts as using chip X")
+  //   null  → no chip has been clicked yet on this mount
+  //   X     → composer was last prefilled by chip X (sticks through user edits
+  //           and clears; replaced when another chip is clicked)
   // Transitions:
-  //   chip X click          → setSource(X)
-  //   composer becomes empty → setSource(null)   (handled in the lifecycle effect)
-  //   user edits non-empty   → no change (sticky through edits)
+  //   chip X click           → setSource(X)
+  //   chip Y click after X   → setSource(Y)
+  //   user edits / clears    → no change (sticky)
   // Side effect: when sessionCount transitions upward with source set, the chip
   // graduated into a real task — dismiss it globally so capability discovery
   // doesn't re-pitch it on the next visit or workspace.
+  //
+  // The previous "drain composer also clears source" branch was removed because
+  // it forced the effect to subscribe to prompt.dirty(), which emits on every
+  // keystroke. On the home cold path that turned the effect into a hot loop
+  // visible in perf-probe-baseline (frame_gap_max jump). The only behavior
+  // difference: a user who clicks a chip, then types their own thing and sends,
+  // now sees that chip dismissed too — acceptable since they engaged with it.
   // ────────────────────────────────────────────────────────────────
   const [currentChipSource, setCurrentChipSource] = createSignal<HomeSuggestionChipID | null>(null)
 
@@ -82,23 +89,14 @@ export const HomeSuggestionList: Component = () => {
     settings.general.setHomeSuggestionsDismissed([...current, id])
   }
 
-  type LifecycleSnapshot = { count: number; dirty: boolean }
-  // Combined effect so session-create and composer-empty observed in the same
-  // tick resolve in a defined order: session-create wins (dismiss before clear).
-  createEffect<LifecycleSnapshot | undefined>((prev) => {
+  createEffect<number | undefined>((prev) => {
     const count = sessionCount()
-    const dirty = prompt.dirty()
-    if (prev !== undefined) {
-      if (count > prev.count) {
-        const source = currentChipSource()
-        if (source) dismissRow(source)
-        setCurrentChipSource(null)
-      } else if (prev.dirty && !dirty) {
-        // Composer drained without a new session (user discarded the prefill).
-        setCurrentChipSource(null)
-      }
+    if (prev !== undefined && count > prev) {
+      const source = currentChipSource()
+      if (source) dismissRow(source)
+      setCurrentChipSource(null)
     }
-    return { count, dirty }
+    return count
   }, undefined)
 
   const prefill = (chipID: HomeSuggestionChipID, text: string) => {
diff --git a/packages/app/src/components/session/session-new-view.tsx b/packages/app/src/components/session/session-new-view.tsx
index f70656fcb..03d670795 100644
--- a/packages/app/src/components/session/session-new-view.tsx
+++ b/packages/app/src/components/session/session-new-view.tsx
@@ -1,6 +1,14 @@
-import { Show, type JSX } from "solid-js"
+import { Show, Suspense, lazy, type JSX } from "solid-js"
 import { useLanguage } from "@/context/language"
-import { HomeSuggestionList } from "@/components/home/home-suggestion-list"
+
+// Lazy-loaded so the module + its reactive setup (4 contexts, createEffect with
+// prompt.dirty + sessionCount tracking, For-loop chip render) doesn't run on
+// the home's cold paint path. perf-probe-baseline showed +183ms frame_gap_max
+// on homepage-cold and +267ms on tool-default-open-heavy-bash (both go through
+// project.open() → home first) when this was mounted eagerly.
+const HomeSuggestionList = lazy(() =>
+  import("@/components/home/home-suggestion-list").then((module) => ({ default: module.HomeSuggestionList })),
+)
 
 type ComposerCtx = {
   onModeChange: (mode: "normal" | "shell") => void
@@ -24,7 +32,9 @@ export function NewSessionView(props: { composer?: (ctx: ComposerCtx) => JSX.Ele
           <div class="mt-20 flex w-full max-w-[640px] flex-col items-center">
             {props.composer!({ onModeChange: () => {} })}
           </div>
-          <HomeSuggestionList />
+          <Suspense>
+            <HomeSuggestionList />
+          </Suspense>
         </Show>
       </div>
     </div>

From a6b8ed5fdd492999e8e34b3d533fb8226866e9b1 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 21:16:53 +0800
Subject: [PATCH 27/30] fix(home): also gate suggestion visibility on
 settings.ready()

On desktop, sync and settings are independent async hydrations
backed by AsyncStorage (see packages/app/src/utils/persist.ts). The
previous single guard on sync.ready let the dismissed-list accessor
fall through to its withFallback([]) default during the gap before
settings finished hydrating, which briefly re-showed chips the user
had already dismissed.

Require both stores ready before computing visibility. Web is
unaffected (both stores are sync there). The unit test now pins the
double guard so a refactor can't silently drop it.
---
 .../src/components/home/home-suggestion-list.test.ts   |  5 ++++-
 .../app/src/components/home/home-suggestion-list.tsx   | 10 ++++++----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/packages/app/src/components/home/home-suggestion-list.test.ts b/packages/app/src/components/home/home-suggestion-list.test.ts
index 3b3597949..879d97821 100644
--- a/packages/app/src/components/home/home-suggestion-list.test.ts
+++ b/packages/app/src/components/home/home-suggestion-list.test.ts
@@ -15,8 +15,11 @@ describe("HomeSuggestionList source contract", () => {
   test("observes sessionCount only for the auto-dismiss effect, not as visibility gate", () => {
     expect(source).toContain("sync.data.session")
     expect(source).toMatch(/sync\.data\.session\??\.length/)
-    // sync.ready stays as a hydration guard so dismissed isn't read as [] mid-load.
+    // BOTH stores must gate visibility on desktop because sync and settings
+    // are independent async hydrations; reading dismissed before settings is
+    // ready returns the withFallback([]) default and re-shows dismissed chips.
     expect(source).toContain("sync.ready")
+    expect(source).toContain("settings.ready()")
     // No per-project gate: visibility no longer derives from sessionCount === 0.
     expect(source).not.toMatch(/firstTimeVisitor/)
   })
diff --git a/packages/app/src/components/home/home-suggestion-list.tsx b/packages/app/src/components/home/home-suggestion-list.tsx
index 144e7ac6e..d71b84351 100644
--- a/packages/app/src/components/home/home-suggestion-list.tsx
+++ b/packages/app/src/components/home/home-suggestion-list.tsx
@@ -45,10 +45,12 @@ export const HomeSuggestionList: Component = () => {
   const sessionCount = createMemo(() => sync.data.session?.length ?? 0)
 
   const visibleIDs = createMemo(() => {
-    // sync.ready guards the brief hydration window where settings may not be
-    // fully loaded yet. Without this, the dismissed list may read as [] for a
-    // frame before its real value, causing chips to flash.
-    if (!sync.ready) return []
+    // Wait for BOTH stores. On desktop, sync and settings are separate async
+    // hydrations (see packages/app/src/utils/persist.ts AsyncStorage branch),
+    // so sync.ready alone does not imply settings.ready(). The dismissed
+    // accessor uses a withFallback([]) default, which would briefly read as
+    // an empty list and re-show chips the user has already dismissed.
+    if (!sync.ready || !settings.ready()) return []
     return resolveVisibleHomeSuggestions({
       dismissed: filterKnownIDs(settings.general.homeSuggestionsDismissed()),
     })

From 9116d6e5bde0f3f85a55cc62998c7416e10b36fb Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 22:14:02 +0800
Subject: [PATCH 28/30] fix(i18n): rename home suggestion dismiss copy to
 "suggestion"
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The aria-label said "Dismiss this prompt" / "关闭该提示词", but the
feature is named "suggestion" everywhere else (home-suggestion-list,
home-suggestion-row, homeSuggestionsDismissed, home.suggestion.*).
"prompt" collides with the composer terminology (prompt-input, the
prompt context). Use the feature noun in both locales.
---
 packages/app/src/i18n/en.ts | 2 +-
 packages/app/src/i18n/zh.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/app/src/i18n/en.ts b/packages/app/src/i18n/en.ts
index 69910fc52..4ec8b7eae 100644
--- a/packages/app/src/i18n/en.ts
+++ b/packages/app/src/i18n/en.ts
@@ -570,7 +570,7 @@ export const dict = {
 
   "home.recentProjects": "Recent projects",
   "home.hero.title": "What should we work on?",
-  "home.suggestion.row.dismiss": "Dismiss this prompt",
+  "home.suggestion.row.dismiss": "Dismiss this suggestion",
   "home.suggestion.folder-organize.label": "Organize a folder",
   "home.suggestion.folder-organize.prompt":
     "Organize a folder: group similar files into subfolders, flag duplicates and stale files, rename messy names. Scan first and propose a plan for me to approve.",
diff --git a/packages/app/src/i18n/zh.ts b/packages/app/src/i18n/zh.ts
index 1b6ddc77e..8084afe53 100644
--- a/packages/app/src/i18n/zh.ts
+++ b/packages/app/src/i18n/zh.ts
@@ -540,7 +540,7 @@ export const dict = {
 
   "home.recentProjects": "最近项目",
   "home.hero.title": "今天我们做点什么？",
-  "home.suggestion.row.dismiss": "关闭该提示词",
+  "home.suggestion.row.dismiss": "关闭该建议",
   "home.suggestion.folder-organize.label": "整理一个文件夹",
   "home.suggestion.folder-organize.prompt":
     "帮我整理一个文件夹：把同类文件归到子目录、标记重复或过时的文件、给命名乱的提新名字。先扫描内容，输出一份方案让我确认再动手。",

From a78a35c4236c499d31c87cfba0f19f89b5c31989 Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 22:14:13 +0800
Subject: [PATCH 29/30] fix(env): resolve PATH case-insensitively and strip
 duplicates on merge

On Windows process.env exposes the path under "Path" (or any other
casing the OS chose), and shell.env plugins are free to emit "Path"
or "path". The previous code at three spawn sites read shellEnv.PATH
and process.env.PATH directly, so the lookup missed Windows values
and fell through to "". The merge then carried the inherited "Path"
from the process env into the spread, and we wrote a separate "PATH"
on top. The spawned child received both keys with implementation-
defined precedence, which could drop the inherited system path.

Add stripPathKeys to packages/opencode/src/util/env.ts, alongside
the existing envValueCaseInsensitive read helper, and use the pair
at every prependBundledTools call site:

- packages/opencode/src/tool/bash.ts
- packages/opencode/src/session/prompt.ts
- packages/opencode/src/pty/index.ts

After the change each call resolves currentPath case-insensitively
from the available env sources, strips every PATH casing from the
merged env, then writes back a single canonical PATH. New unit tests
in test/util/env.test.ts pin the strip behavior.
---
 packages/opencode/src/pty/index.ts      | 14 ++++++++++---
 packages/opencode/src/session/prompt.ts | 13 ++++++++----
 packages/opencode/src/tool/bash.ts      | 19 ++++++++++++-----
 packages/opencode/src/util/env.ts       | 11 ++++++++++
 packages/opencode/test/util/env.test.ts | 27 ++++++++++++++++++++++++-
 5 files changed, 71 insertions(+), 13 deletions(-)

diff --git a/packages/opencode/src/pty/index.ts b/packages/opencode/src/pty/index.ts
index f0a104078..82c13ca31 100644
--- a/packages/opencode/src/pty/index.ts
+++ b/packages/opencode/src/pty/index.ts
@@ -9,7 +9,7 @@ import { Log } from "@opencode-ai/core/util/log"
 import { lazy } from "@opencode-ai/util/lazy"
 import { Shell } from "@/shell/shell"
 import { Plugin } from "@/plugin"
-import { envValueCaseInsensitive, prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
+import { envValueCaseInsensitive, prependBundledTools, stripPathKeys, withoutInternalServerAuthEnv } from "@/util/env"
 import { Process } from "@/util/process"
 import { PtyID } from "./schema"
 import { Effect, Layer, Context } from "effect"
@@ -259,15 +259,23 @@ export namespace Pty {
         const shell = yield* plugin.trigger("shell.env", { cwd }, { env: {} })
         const shellEnvRecord = shell.env as Record<string, string>
         const inputEnvRecord = (input.env ?? {}) as Record<string, string>
-        const currentPath = shellEnvRecord.PATH || inputEnvRecord.PATH || process.env.PATH || ""
+        // Resolve PATH case-insensitively (Windows exposes "Path") and strip
+        // every casing from the merged env before writing back a canonical
+        // PATH, so the spawned PTY does not receive duplicate keys.
+        const currentPath =
+          envValueCaseInsensitive(shellEnvRecord, "PATH") ??
+          envValueCaseInsensitive(inputEnvRecord, "PATH") ??
+          envValueCaseInsensitive(process.env, "PATH") ??
+          ""
         const env = withoutInternalServerAuthEnv({
           ...process.env,
           ...inputEnvRecord,
           ...shellEnvRecord,
           TERM: "xterm-256color",
           OPENCODE_TERMINAL: "1",
-          PATH: prependBundledTools(currentPath),
         } as Record<string, string>)
+        stripPathKeys(env)
+        env.PATH = prependBundledTools(currentPath)
         // bun-pty merges with the parent process environment internally, so
         // deleting these keys is not enough for PTY sessions. Override with
         // empty values to prevent PawWork's internal server credentials from
diff --git a/packages/opencode/src/session/prompt.ts b/packages/opencode/src/session/prompt.ts
index 3464f93b2..2f4620ef3 100644
--- a/packages/opencode/src/session/prompt.ts
+++ b/packages/opencode/src/session/prompt.ts
@@ -48,7 +48,7 @@ import { AppFileSystem } from "@opencode-ai/core/filesystem"
 import { Truncate } from "@/tool/truncate"
 import { decodeDataUrl } from "@/util/data-url"
 import { Process } from "@/util/process"
-import { prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
+import { envValueCaseInsensitive, prependBundledTools, stripPathKeys, withoutInternalServerAuthEnv } from "@/util/env"
 import { Cause, Deferred, Effect, Exit, Layer, Option, Scope, Context } from "effect"
 import { EffectLogger } from "@/effect"
 import { InstanceState } from "@/effect"
@@ -1210,15 +1210,20 @@ NOTE: At any point in time through this workflow you should feel free to ask the
           )
 
           const shellEnvRecord = shellEnv.env as Record<string, string>
-          const currentPath = shellEnvRecord.PATH || process.env.PATH || ""
+          // Resolve PATH case-insensitively (Windows uses "Path") and strip
+          // every casing from the merged env before writing back a canonical
+          // PATH, so the spawned child does not receive duplicate keys.
+          const currentPath =
+            envValueCaseInsensitive(shellEnvRecord, "PATH") ?? envValueCaseInsensitive(process.env, "PATH") ?? ""
           const env = withoutInternalServerAuthEnv({
             ...process.env,
             ...shellEnvRecord,
             TERM: "dumb",
             OFFICECLI_SKIP_UPDATE: "1",
-            PATH: prependBundledTools(currentPath),
             ...(shellName === "zsh" || shellName === "bash" ? { OPENCODE_SHELL_CWD: cwd } : {}),
-          })
+          } as Record<string, string>)
+          stripPathKeys(env)
+          env.PATH = prependBundledTools(currentPath)
 
           const cmd = ChildProcess.make(sh, args, {
             cwd,
diff --git a/packages/opencode/src/tool/bash.ts b/packages/opencode/src/tool/bash.ts
index 250f85dd3..956302a38 100644
--- a/packages/opencode/src/tool/bash.ts
+++ b/packages/opencode/src/tool/bash.ts
@@ -23,7 +23,7 @@ import { Plugin } from "@/plugin"
 import { Effect, Stream } from "effect"
 import { ChildProcess } from "effect/unstable/process"
 import { ChildProcessSpawner } from "effect/unstable/process/ChildProcessSpawner"
-import { prependBundledTools, withoutInternalServerAuthEnv } from "@/util/env"
+import { envValueCaseInsensitive, prependBundledTools, stripPathKeys, withoutInternalServerAuthEnv } from "@/util/env"
 import { Global } from "@opencode-ai/core/global"
 import { assertExternalDirectoryEffect, resolveExternalPathForPermission } from "./external-directory"
 import { InstanceState } from "@/effect/instance-state"
@@ -469,13 +469,22 @@ export const BashTool = Tool.define(
         { env: {} },
       )
       const extraEnv = extra.env as Record<string, string>
-      const currentPath = extraEnv.PATH || process.env.PATH || ""
-      return withoutInternalServerAuthEnv({
+      // Read PATH case-insensitively: a shell plugin may emit "Path" on
+      // Windows, and process.env preserves the OS casing during spread.
+      // After the merge, strip every case-variant of PATH before writing
+      // back a single canonical PATH so the spawned child does not receive
+      // both `Path` and `PATH` (the latter would otherwise win and drop
+      // the inherited system path).
+      const currentPath =
+        envValueCaseInsensitive(extraEnv, "PATH") ?? envValueCaseInsensitive(process.env, "PATH") ?? ""
+      const env = withoutInternalServerAuthEnv({
         ...process.env,
         ...extraEnv,
         OFFICECLI_SKIP_UPDATE: "1",
-        PATH: prependBundledTools(currentPath),
-      })
+      } as Record<string, string>)
+      stripPathKeys(env)
+      env.PATH = prependBundledTools(currentPath)
+      return env
     })
 
     const readTrackedState = Effect.fn("BashTool.readTrackedState")((file: string) =>
diff --git a/packages/opencode/src/util/env.ts b/packages/opencode/src/util/env.ts
index 4164e81c1..cd3e76e1d 100644
--- a/packages/opencode/src/util/env.ts
+++ b/packages/opencode/src/util/env.ts
@@ -36,3 +36,14 @@ export function prependBundledTools(currentPath: string): string {
   // command-resolution safety (cwd-shadowing of system commands).
   return currentPath ? `${dir}${path.delimiter}${currentPath}` : dir
 }
+
+// Removes every case-variant of the PATH key from an env record in place.
+// Use before writing back a canonical `PATH` to a merged env, otherwise on
+// Windows the result can carry both `Path` (inherited from process.env) and
+// `PATH` (added explicitly); spawn then forwards both to the child with
+// implementation-defined precedence.
+export function stripPathKeys(env: Record<string, string | undefined>): void {
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === "path") delete env[key]
+  }
+}
diff --git a/packages/opencode/test/util/env.test.ts b/packages/opencode/test/util/env.test.ts
index bb9ee9245..4ab05e4fc 100644
--- a/packages/opencode/test/util/env.test.ts
+++ b/packages/opencode/test/util/env.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test"
 import path from "path"
-import { bundledToolsDir, prependBundledTools, withoutInternalServerAuthEnv } from "../../src/util/env"
+import { bundledToolsDir, prependBundledTools, stripPathKeys, withoutInternalServerAuthEnv } from "../../src/util/env"
 
 type ResourcesPathBag = { resourcesPath?: string }
 
@@ -85,3 +85,28 @@ describe("util.env.bundledTools", () => {
     expect(prependBundledTools("")).toBe(path.join("/r", "tools"))
   })
 })
+
+describe("util.env.stripPathKeys", () => {
+  test("removes every case-variant of PATH while leaving the rest untouched", () => {
+    // Windows ships `Path`, some shells emit `path`, our code adds `PATH`.
+    // After spreading process.env into a child env all three can co-exist,
+    // and spawn forwards them with implementation-defined precedence.
+    const env: Record<string, string | undefined> = {
+      Path: "/system/path",
+      PATH: "/our/override",
+      path: "/lowercase",
+      TERM: "xterm",
+      OFFICECLI_SKIP_UPDATE: "1",
+    }
+
+    stripPathKeys(env)
+
+    expect(env).toEqual({ TERM: "xterm", OFFICECLI_SKIP_UPDATE: "1" })
+  })
+
+  test("is safe on an env that has no path keys at all", () => {
+    const env: Record<string, string | undefined> = { TERM: "xterm" }
+    stripPathKeys(env)
+    expect(env).toEqual({ TERM: "xterm" })
+  })
+})

From e72fda283e30ff7e4953182456080bb9160fba8b Mon Sep 17 00:00:00 2001
From: Yuhan Lei <lei.yuhan@outlook.com>
Date: Sun, 17 May 2026 22:18:05 +0800
Subject: [PATCH 30/30] chore(e2e): conform home suggestion spec to coding
 conventions

Two nitpick fixes for this file:
- Selector constants now use SCREAMING_SNAKE_CASE, matching the
  convention documented for e2e specs and the surrounding files.
- The drain-the-prefill step replaces document.execCommand("selectAll")
  with the cross-platform modKey helper from packages/app/e2e/utils.ts;
  execCommand is the brittle path and modKey is what every other spec
  uses for Meta-on-Mac / Control-elsewhere shortcuts.

No behavior change; renames are local to this file.
---
 .../onboarding/home-suggestion-chips.spec.ts  | 63 +++++++++----------
 1 file changed, 31 insertions(+), 32 deletions(-)

diff --git a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
index 6eefd2449..2f9aeadd1 100644
--- a/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
+++ b/packages/app/e2e/onboarding/home-suggestion-chips.spec.ts
@@ -1,10 +1,11 @@
 import type { Page } from "@playwright/test"
 import { test, expect } from "../fixtures"
 import { promptSelector } from "../selectors"
+import { modKey } from "../utils"
 
-const suggestionListSelector = '[data-component="home-suggestion-list"]'
-const rowSelector = '[data-action="home-suggestion-row"]'
-const rowDismissSelector = '[data-action="home-suggestion-row-dismiss"]'
+const SUGGESTION_LIST_SELECTOR = '[data-component="home-suggestion-list"]'
+const ROW_SELECTOR = '[data-action="home-suggestion-row"]'
+const ROW_DISMISS_SELECTOR = '[data-action="home-suggestion-row-dismiss"]'
 
 async function readDismissedFromStorage(page: Page): Promise<string[]> {
   // settings.v3 is persisted via the settings store (utils/persist.ts) — in the
@@ -24,16 +25,16 @@ async function readDismissedFromStorage(page: Page): Promise<string[]> {
 test("@smoke home shows 3 suggestion rows for a first-time visitor", async ({ page, project }) => {
   await project.open()
 
-  const list = page.locator(suggestionListSelector)
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
   await expect(list).toBeVisible()
-  await expect(list.locator(rowSelector)).toHaveCount(3)
+  await expect(list.locator(ROW_SELECTOR)).toHaveCount(3)
 })
 
 test("@smoke clicking a suggestion row prefills the composer", async ({ page, project }) => {
   await project.open()
 
-  const list = page.locator(suggestionListSelector)
-  const firstRow = list.locator(rowSelector).first()
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
+  const firstRow = list.locator(ROW_SELECTOR).first()
   const text = (await firstRow.innerText()).trim()
   await firstRow.click()
 
@@ -48,17 +49,17 @@ test("@smoke clicking a suggestion row prefills the composer", async ({ page, pr
 test("@smoke per-row X dismisses one row and persists across reload", async ({ page, project }) => {
   await project.open()
 
-  const list = page.locator(suggestionListSelector)
-  await expect(list.locator(rowSelector)).toHaveCount(3)
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
+  await expect(list.locator(ROW_SELECTOR)).toHaveCount(3)
 
-  const firstRow = list.locator(rowSelector).first()
+  const firstRow = list.locator(ROW_SELECTOR).first()
   await firstRow.hover()
-  await list.locator(rowDismissSelector).first().click()
+  await list.locator(ROW_DISMISS_SELECTOR).first().click()
 
-  await expect(list.locator(rowSelector)).toHaveCount(2)
+  await expect(list.locator(ROW_SELECTOR)).toHaveCount(2)
 
   await page.reload()
-  await expect(page.locator(suggestionListSelector).locator(rowSelector)).toHaveCount(2)
+  await expect(page.locator(SUGGESTION_LIST_SELECTOR).locator(ROW_SELECTOR)).toHaveCount(2)
 })
 
 test("@smoke composer placeholder is the static home string", async ({ page, project }) => {
@@ -92,19 +93,19 @@ test("@smoke composer placeholder is the static home string", async ({ page, pro
 
 test("dismissing all 3 rows hides the section entirely", async ({ page, project }) => {
   await project.open()
-  const list = page.locator(suggestionListSelector)
-  await expect(list.locator(rowSelector)).toHaveCount(3)
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
+  await expect(list.locator(ROW_SELECTOR)).toHaveCount(3)
 
   for (let i = 0; i < 3; i++) {
-    const firstRow = list.locator(rowSelector).first()
+    const firstRow = list.locator(ROW_SELECTOR).first()
     await firstRow.hover()
-    await list.locator(rowDismissSelector).first().click()
+    await list.locator(ROW_DISMISS_SELECTOR).first().click()
   }
 
-  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+  await expect(page.locator(SUGGESTION_LIST_SELECTOR)).toHaveCount(0)
 
   await page.reload()
-  await expect(page.locator(suggestionListSelector)).toHaveCount(0)
+  await expect(page.locator(SUGGESTION_LIST_SELECTOR)).toHaveCount(0)
 })
 
 test("used chip is gone but unused chips still appear on home after session creation", async ({
@@ -115,8 +116,8 @@ test("used chip is gone but unused chips still appear on home after session crea
   await project.open()
   await assistant.reply("unused chips remain reply")
 
-  const list = page.locator(suggestionListSelector)
-  const rows = list.locator(rowSelector)
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
+  const rows = list.locator(ROW_SELECTOR)
   await expect(rows).toHaveCount(3)
 
   const firstChipID = await rows.first().getAttribute("data-chip-id")
@@ -128,9 +129,9 @@ test("used chip is gone but unused chips still appear on home after session crea
 
   // Back to home: chips are NOT gated by sessionCount, so the unused two remain.
   await project.open()
-  await expect(list.locator(rowSelector)).toHaveCount(2)
+  await expect(list.locator(ROW_SELECTOR)).toHaveCount(2)
   const remainingIDs = await list
-    .locator(rowSelector)
+    .locator(ROW_SELECTOR)
     .evaluateAll((els) => els.map((el) => el.getAttribute("data-chip-id")))
   expect(remainingIDs).not.toContain(firstChipID)
 })
@@ -140,7 +141,7 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
   await assistant.reply("edited reply")
 
   const editor = page.locator(promptSelector)
-  await page.locator(suggestionListSelector).locator(rowSelector).first().click()
+  await page.locator(SUGGESTION_LIST_SELECTOR).locator(ROW_SELECTOR).first().click()
   await expect(editor).toBeFocused()
 
   await page.keyboard.type(" please be concise")
@@ -153,9 +154,9 @@ test("editing a prefilled suggestion preserves the user's edit on send", async (
 test("clicking another suggestion replaces the previous prefill", async ({ page, project }) => {
   await project.open()
 
-  const list = page.locator(suggestionListSelector)
+  const list = page.locator(SUGGESTION_LIST_SELECTOR)
   const editor = page.locator(promptSelector)
-  const rows = list.locator(rowSelector)
+  const rows = list.locator(ROW_SELECTOR)
 
   const firstText = (await rows.first().innerText()).trim()
   const secondText = (await rows.nth(1).innerText()).trim()
@@ -172,7 +173,7 @@ test("using a chip via send auto-dismisses it for capability discovery", async (
   await project.open()
   await assistant.reply("auto-dismiss reply")
 
-  const firstRow = page.locator(suggestionListSelector).locator(rowSelector).first()
+  const firstRow = page.locator(SUGGESTION_LIST_SELECTOR).locator(ROW_SELECTOR).first()
   const firstChipID = await firstRow.getAttribute("data-chip-id")
   expect(firstChipID).toBeTruthy()
 
@@ -188,7 +189,7 @@ test("switching chips before send dismisses only the last selection", async ({ p
   await project.open()
   await assistant.reply("only-last reply")
 
-  const rows = page.locator(suggestionListSelector).locator(rowSelector)
+  const rows = page.locator(SUGGESTION_LIST_SELECTOR).locator(ROW_SELECTOR)
   const firstChipID = await rows.first().getAttribute("data-chip-id")
   const secondChipID = await rows.nth(1).getAttribute("data-chip-id")
 
@@ -207,7 +208,7 @@ test("clicking a chip then sending any content dismisses it (sticky source)", as
   await assistant.reply("sticky source reply")
 
   const editor = page.locator(promptSelector)
-  const firstRow = page.locator(suggestionListSelector).locator(rowSelector).first()
+  const firstRow = page.locator(SUGGESTION_LIST_SELECTOR).locator(ROW_SELECTOR).first()
   const firstChipID = await firstRow.getAttribute("data-chip-id")
   expect(firstChipID).toBeTruthy()
 
@@ -218,9 +219,7 @@ test("clicking a chip then sending any content dismisses it (sticky source)", as
   // sticky once clicked — sending any prompt afterwards still dismisses it
   // (the user engaged with the suggestion and chose a direction, no need to
   // keep pitching it).
-  await page.evaluate(() => {
-    document.execCommand("selectAll")
-  })
+  await page.keyboard.press(`${modKey}+A`)
   await page.keyboard.press("Backspace")
   await page.keyboard.type("my own prompt content")
   await page.keyboard.press("Enter")