@capagents/forgeqe 1.0.4 → 1.0.7

package/src/tui/App.tsx

@@ -1,11 +1,13 @@
 import type { ScrollBoxRenderable, Selection } from "@opentui/core"
 import { useKeyboard, usePaste, useRenderer, useTerminalDimensions } from "@opentui/react"
+import { existsSync } from "node:fs"
 import path from "node:path"
 import { useEffect, useRef, useState } from "react"
 
 import { NO_MODEL_SET_UP } from "../llm.ts"
 import type { CodeEvent, ReplayMode } from "../types.ts"
 import { brainUnavailable, carryOver, openBrain, sessionSetup, type Brain, type BrainOptions } from "../brain/index.ts"
+import type { FollowUp } from "../brain/prompt.ts"
 import { INSTALL_HINT } from "../code/runtime.ts"
 import { briefText, detailFrom, shows, showsAgentTool, stepIntent, type Detail } from "../detail.ts"
 import { stepVerdictLines } from "../cases/types.ts"
@@ -22,22 +24,46 @@ import { counts } from "../suite/report.ts"
 import { buildSummary, shortPath } from "../summary.ts"
 import { meterSnapshot, requestLine } from "../usage.ts"
 import { cleanSelection, copyText } from "./clipboard.ts"
-import { ChoicePanel, Footer, Hints, Logo, Prompt, Spinner, type Hint } from "./components.tsx"
+import { ButtonBar, ChoicePanel, Footer, Hints, Logo, Prompt, Spinner, type Button, type Hint } from "./components.tsx"
+import { setupChecklist, type SetupItem } from "./setup.ts"
 import { EXAMPLES, TIPS, formatDuration, formatTokens, packageVersion, pick, shortCwd, theme } from "./theme.ts"
 import { emptyProduced, Line, Produced, producedCard, TestsSetting, TranscriptLine } from "./transcript.tsx"
 import { Dialog, dialogSpec } from "./dialogs.ts"
 import { activityFromLog, clip, hostOf, modelLabel } from "./text.ts"
 import { featuresText } from "../capabilities/render.ts"
+import { Palette, paletteItems, searchPalette, SuggestList, type PaletteItem } from "./palette.tsx"
+import { commandSuggestions, complete, lookupWorkItem, recentRuns, referenceSuggestions, repoFiles, triggerAt, type Suggestion, type WorkItem } from "./suggest.ts"
+import { REFINE_CHOICES, RefinePanel, type RefineChoice, type RefineState } from "./refine-panel.tsx"
+import { refine } from "../refine.ts"
+import { nextSteps, type NextStep } from "./next.ts"
 import { CAPABILITIES } from "../capabilities/registry.ts"
 import { CONTEXT_LIMIT } from "../code/runtime.ts"
 import { readKnowledge } from "../knowledge.ts"
 import { externalMcp } from "../mcp/external.ts"
 import { meterSince } from "../usage.ts"
-import { ActivityPanel, ContextPanel, FilesPanel, PlanPanel, planRows, SessionPanel, StatusBar, TokensPanel, type ContextInfo, type SessionInfo } from "./inspector.tsx"
+import {
+  ACTIVITY_FILTERS,
+  ActivityPanel,
+  ContextPanel,
+  FilesPanel,
+  nextFocus,
+  planLines,
+  PlanPanel,
+  planProgress,
+  planRows,
+  SessionPanel,
+  StatusBar,
+  TokensPanel,
+  type ActivityFilter,
+  type ContextInfo,
+  type Focus,
+  type SessionInfo,
+} from "./inspector.tsx"
 import {
   addSkill,
   caseDone,
   caseStarted,
+  filesByUse,
   newInspector,
   newRequest,
   paneFor,
@@ -72,6 +98,8 @@ export type TuiOptions = {
   copy?: (text: string) => boolean
   /** Show everything the agents do (their reasoning, every file read, engine logs); /details toggles it. */
   verbose?: boolean
+  /** Replaces Refine's model session in tests. */
+  refine?: typeof refine
   /** Replaces opening a page in the browser (sign-in) in tests. */
   openUrl?: (url: string) => void
 }
@@ -89,6 +117,8 @@ export function App({ options }: { options: TuiOptions }) {
   const scrollRef = useRef<ScrollBoxRenderable>(null)
   const activityScroll = useRef<ScrollBoxRenderable>(null)
   const submitRef = useRef<(value: string) => void>(() => {})
+  /** Refines what is in the prompt (phase two of the palette work wires it). */
+  const refineRef = useRef<() => void>(() => {})
   const configRef = useRef<AppConfig | null>(null)
   const abortRef = useRef<AbortController | null>(null)
   const brainRef = useRef<Brain | null>(null)
@@ -110,6 +140,25 @@ export function App({ options }: { options: TuiOptions }) {
   const codeRunDir = useRef("")
   /** The right pane's live state: plan, steps or cases, files, context. */
   const inspRef = useRef(newInspector())
+  /** The command palette: open, what is typed in it, and which match is selected. */
+  const [palette, setPalette] = useState<{ query: string; selected: number } | null>(null)
+  const paletteRef = useRef(palette)
+  paletteRef.current = palette
+  /** Refine (ctrl+r): what the prompt holds, the panel's state, and how to cancel it. */
+  const promptTextRef = useRef("")
+  const [refining, setRefining] = useState<RefineState | null>(null)
+  const refiningRef = useRef(refining)
+  refiningRef.current = refining
+  const refineAbort = useRef<AbortController | null>(null)
+  /** One-click follow-ups after a request, from what it produced. */
+  const [next, setNext] = useState<NextStep[]>([])
+  /** What the prompt holds, for suggestions; and the suggestion state: which is selected, which word was dismissed. */
+  const [promptText, setPromptText] = useState("")
+  const [sugg, setSugg] = useState<{ selected: number; dismissed?: string }>({ selected: 0 })
+  const [workItem, setWorkItem] = useState<WorkItem | null | undefined>(undefined)
+  const suggRef = useRef<{ list: Suggestion[]; trigger: ReturnType<typeof triggerAt> }>({ list: [], trigger: null })
+  /** Text the prompt starts with on its next remount (an example from the palette, a refined request). */
+  const [draft, setDraft] = useState("")
   /** Set while a typed line is handled, so the shell's answers to it go to the chat. */
   const answeringRef = useRef(false)
   const [, setRev] = useState(0)
@@ -120,6 +169,17 @@ export function App({ options }: { options: TuiOptions }) {
   const requests = useRef(0)
   /** Under 120 columns there is room for one pane: ctrl+o switches between the chat and the details. */
   const [narrowView, setNarrowView] = useState<"chat" | "details">("chat")
+  // The split view's chat at the full width, for reading a long answer; the panels come back with Split view.
+  const [chatWide, setChatWide] = useState(false)
+  const setupRef = useRef<{ key: string; items: SetupItem[] }>({ key: "", items: [] })
+  // Which panel the keys go to (shift+tab moves on), the row selected in the plan and files, and the activity filter.
+  const [nav, setNavState] = useState<{ focus: Focus; plan: number; files: number; filter: ActivityFilter }>({ focus: "chat", plan: 0, files: 0, filter: "all" })
+  const navRef = useRef(nav)
+  // Keys can arrive faster than renders: each change builds on the ref, which the next key reads at once.
+  const setNav = (f: (n: typeof nav) => typeof nav) => {
+    navRef.current = f(navRef.current)
+    setNavState(navRef.current)
+  }
   const contextInfo = useRef<{ key: string; knowledge: number; mcp: string[] }>({ key: "", knowledge: 0, mcp: [] })
 
   const [lines, setLines] = useState<Line[]>([])
@@ -190,6 +250,19 @@ export function App({ options }: { options: TuiOptions }) {
   }
   /** An agent's tool call; files it writes or edits (the test script) stand out from reads and searches. */
   const pushTool = (text: string, ok: boolean) => push(!ok ? "err" : /^(Writing|Editing) /.test(text) ? "file" : "tool", text)
+  /** A short note in the hint row that clears itself: "opened report.html". */
+  const flashTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+  const flash = (text: string) => {
+    setCopied(text)
+    clearTimeout(flashTimer.current)
+    flashTimer.current = setTimeout(() => setCopied(""), 2500)
+  }
+  const openFile = (file: string) => {
+    const abs = path.resolve(file)
+    if (!existsSync(abs)) return flash(`${path.basename(file)} is no longer there`)
+    ;(options.openUrl || openInBrowser)(`file://${abs}`)
+    flash(`opened ${path.basename(file)}`)
+  }
   const pushProduced = () => {
     const card = producedCard(producedRef.current, testsRef.current)
     if (card) pushLine({ kind: "card", text: card.title, card })
@@ -200,6 +273,16 @@ export function App({ options }: { options: TuiOptions }) {
     setTokens([...usedRef.current.values()].reduce((a, b) => a + b, 0))
   }
 
+  // "@1761": look the work item up (once per id, after a pause in typing) so its title can be suggested.
+  useEffect(() => {
+    const t = triggerAt(promptText)
+    const cfg = configRef.current
+    if (!t || t.kind !== "@" || !/^\d{2,}$/.test(t.token) || !cfg?.sources.ado) return
+    const id = Number(t.token)
+    const timer = setTimeout(() => void lookupWorkItem(cfg, id).then((item) => setWorkItem(item)), 300)
+    return () => clearTimeout(timer)
+  }, [promptText])
+
   useEffect(() => {
     if (status !== "running") return
     const timer = setInterval(() => setTick((n) => n + 1), 1000)
@@ -392,6 +475,96 @@ export function App({ options }: { options: TuiOptions }) {
     }
   }
 
+  /** Everything the palette offers now, in its order. */
+  const paletteAll = (): PaletteItem[] =>
+    paletteItems({
+      running: abortRef.current !== null,
+      headed: headedRef.current,
+      detailsFull: detailRef.current === "full",
+      profiles: Object.keys(configRef.current?.profiles || {}),
+      active: configRef.current?.activeProfile || "",
+      narrow: widthRef.current < SPLIT_MIN,
+      view: narrowView,
+      chatWide,
+    })
+  const paletteMatches = (query: string) => searchPalette(query, paletteAll())
+
+  /** Puts text in the prompt to edit and send. */
+  const fillPrompt = (text: string) => {
+    promptTextRef.current = text
+    setPromptText(text)
+    setDraft(text)
+    setInputKey((k) => k + 1)
+  }
+
+  const setRefine = (next: RefineState | null) => {
+    refiningRef.current = next
+    setRefining(next)
+  }
+
+  /** Refines what is in the prompt; the user then decides what is sent. */
+  const startRefine = () => {
+    const text = promptTextRef.current.trim()
+    const cfg = configRef.current
+    if (!text) {
+      push("sys", "Type a request first, then press ctrl+r to refine it.", "chat")
+      return
+    }
+    const why = cfg ? brainUnavailable(cfg) : "Config is not loaded."
+    if (!cfg || why) {
+      push("err", `Refine needs ForgeQE's agent: ${why}`, "chat")
+      return
+    }
+    const controller = new AbortController()
+    refineAbort.current = controller
+    setRefine({ phase: "working", original: text })
+    void (options.refine || refine)({ config: cfg, cwd: sessionSetup(cfg, options.repo).cwd, text, recent: convoRef.current, signal: controller.signal })
+      .then((result) => {
+        if (controller.signal.aborted || refiningRef.current?.phase !== "working") return
+        setRefine({ phase: "done", original: text, result, choice: 0 })
+      })
+      .catch((err) => {
+        if (controller.signal.aborted) return
+        setRefine({ phase: "error", original: text, message: (err as Error).message })
+        fillPrompt(text)
+      })
+      .finally(() => {
+        if (refineAbort.current === controller) refineAbort.current = null
+      })
+  }
+  refineRef.current = startRefine
+
+  const chooseRefine = (id: RefineChoice) => {
+    const r = refiningRef.current
+    if (!r) return
+    setRefine(null)
+    if (r.phase !== "done") {
+      fillPrompt(r.original)
+      return
+    }
+    if (id === "use") submitRef.current(r.result.refined)
+    else fillPrompt(id === "edit" ? r.result.refined : r.original)
+  }
+
+  const takeNext = (step: NextStep) => {
+    setNext([])
+    if (step.run.kind === "insert") fillPrompt(step.run.text)
+    else (options.openUrl || openInBrowser)(`file://${path.resolve(step.run.path)}`)
+  }
+
+  const pickPalette = (item: PaletteItem) => {
+    paletteRef.current = null
+    setPalette(null)
+    const run = item.run
+    if (run.kind === "insert") fillPrompt(run.text)
+    else if (run.kind === "command") submitRef.current(run.text)
+    else if (run.id === "stop") openDialog("stop")
+    else if (run.id === "details" || run.id === "chat") setNarrowView(run.id)
+    else if (run.id === "refine") refineRef.current()
+    else if (run.id === "wide") setChatWide((w) => !w)
+    else if (run.id === "panels") setNav((n) => ({ ...n, focus: planLines(inspRef.current).length ? "plan" : "activity" }))
+  }
+
   const cycleProfile = () => {
     const cfg = configRef.current
     if (!cfg || abortRef.current) return
@@ -402,6 +575,51 @@ export function App({ options }: { options: TuiOptions }) {
   }
 
   useKeyboard((key) => {
+    const pal = paletteRef.current
+    if (pal) {
+      // Keys can arrive faster than renders: every change builds on the latest state, never on this render's copy.
+      const edit = (f: (p: { query: string; selected: number }) => { query: string; selected: number } | null) => {
+        setPalette((p) => {
+          const next = p ? f(p) : p
+          paletteRef.current = next
+          return next
+        })
+      }
+      if (key.name === "escape" || (key.name === "p" && key.ctrl)) edit(() => null)
+      else if (key.name === "up") edit((p) => ({ ...p, selected: Math.max(0, p.selected - 1) }))
+      else if (key.name === "down") edit((p) => ({ ...p, selected: Math.min(Math.max(0, paletteMatches(p.query).length - 1), p.selected + 1) }))
+      else if (key.name === "return" || key.name === "enter" || key.name === "kpenter") {
+        const current = paletteRef.current!
+        const item = paletteMatches(current.query)[current.selected]
+        if (item) pickPalette(item)
+        else {
+          edit(() => null)
+          if (current.query.trim()) fillPrompt(current.query.trim())
+        }
+      } else if (key.name === "backspace") edit((p) => ({ query: p.query.slice(0, -1), selected: 0 }))
+      else if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.sequence >= " ") {
+        const ch = key.sequence
+        edit((p) => ({ query: p.query + ch, selected: 0 }))
+      }
+      return
+    }
+    const r = refiningRef.current
+    if (r && !dialogRef.current && !(key.name === "c" && key.ctrl)) {
+      if (r.phase === "working") {
+        if (key.name === "escape") {
+          refineAbort.current?.abort()
+          setRefine(null)
+          fillPrompt(r.original)
+        }
+      } else if (r.phase === "error") {
+        if (key.name === "escape" || key.name === "return" || key.name === "enter") setRefine(null)
+      } else if (key.name === "left" || (key.name === "tab" && key.shift)) setRefine({ ...r, choice: (r.choice + REFINE_CHOICES.length - 1) % REFINE_CHOICES.length })
+      else if (key.name === "right" || key.name === "tab") setRefine({ ...r, choice: (r.choice + 1) % REFINE_CHOICES.length })
+      else if (key.name === "return" || key.name === "enter" || key.name === "kpenter") chooseRefine(REFINE_CHOICES[r.choice]!.id)
+      else if (key.name === "e") chooseRefine("edit")
+      else if (key.name === "escape") chooseRefine("keep")
+      return
+    }
     const open = dialogRef.current
     if (key.name === "c" && key.ctrl) {
       if (open === "quit") quit()
@@ -429,8 +647,68 @@ export function App({ options }: { options: TuiOptions }) {
       else if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.sequence >= " ") setSecret(secretRef.current + key.sequence)
       return
     }
+    // The panels: shift+tab moves focus through those on screen; a focused panel takes the arrows, enter, and esc.
+    const panes = (width >= SPLIT_MIN && !chatWide) || (width < SPLIT_MIN && narrowView === "details")
+    const insp = inspRef.current
+    const shown = (f: Focus) => f === "activity" || f === "files" || (f === "plan" && planLines(insp).length > 0) || (f === "chat" && width >= SPLIT_MIN)
+    if (panes && key.name === "tab" && key.shift && !entryRef.current) {
+      setNav((n) => ({ ...n, focus: nextFocus(n.focus, shown) }))
+      return
+    }
+    const at = navRef.current.focus
+    if (panes && at !== "chat" && shown(at)) {
+      const list = at === "plan" ? planLines(insp).length : at === "files" ? filesByUse(insp).length : 0
+      const move = (d: number) => setNav((n) => ({ ...n, [at]: Math.max(0, Math.min(list - 1, (n[at as "plan" | "files"] ?? 0) + d)) }))
+      const page = Math.max(3, Math.floor(height / 3))
+      if (key.name === "escape") return setNav((n) => ({ ...n, focus: width >= SPLIT_MIN ? "chat" : "activity" }))
+      if (at === "activity") {
+        const box = activityScroll.current
+        if (key.name === "up") return box?.scrollBy(-1)
+        if (key.name === "down") return box?.scrollBy(1)
+        if (key.name === "pageup") return box?.scrollBy(-page)
+        if (key.name === "pagedown") return box?.scrollBy(page)
+        const f = ACTIVITY_FILTERS.find((x) => x.key === key.name && !key.ctrl && !key.meta)
+        if (f) return setNav((n) => ({ ...n, filter: f.id }))
+      } else {
+        if (key.name === "up") return move(-1)
+        if (key.name === "down") return move(1)
+        if (key.name === "pageup") return move(-page)
+        if (key.name === "pagedown") return move(page)
+        if (key.name === "home") return move(-list)
+        if (key.name === "end") return move(list)
+        if (key.name === "return" || key.name === "enter" || key.name === "kpenter") {
+          if (at === "files") {
+            const f = filesByUse(insp)[Math.min(navRef.current.files, list - 1)]
+            if (f) openFile(f.path)
+          } else {
+            const l = planLines(insp)[Math.min(navRef.current.plan, list - 1)]
+            if (l) push("sys", `Plan  ${l.mark} ${l.text}`, "chat")
+          }
+          return
+        }
+      }
+      // Anything typed goes back to the chat, where the prompt is.
+      if (!key.ctrl && !key.meta && key.sequence && key.sequence.length === 1 && key.sequence > " " && width >= SPLIT_MIN) return setNav((n) => ({ ...n, focus: "chat" }))
+      if (!key.ctrl && !key.meta) return
+    }
+    if (suggRef.current.list.length && suggRef.current.trigger && !entryRef.current) {
+      const n = suggRef.current.list.length
+      if (key.name === "up") return setSugg((x) => ({ ...x, selected: (x.selected + n - 1) % n }))
+      if (key.name === "down") return setSugg((x) => ({ ...x, selected: (x.selected + 1) % n }))
+      if (key.name === "tab" && !key.shift) return acceptSuggestion(Math.min(sugg.selected, n - 1))
+      if (key.name === "escape") return setSugg({ selected: 0, dismissed: `${suggRef.current.trigger.kind}${suggRef.current.trigger.token}` })
+    }
     if (key.name === "tab" && !key.shift) cycleProfile()
-    if (key.name === "p" && key.ctrl) push("sys", HELP, "chat")
+    if (key.name === "p" && key.ctrl) {
+      paletteRef.current = { query: "", selected: 0 }
+      setPalette(paletteRef.current)
+    }
+    if (key.meta && /^[1-3]$/.test(key.name || "") && showNext) {
+      const step = next[Number(key.name) - 1]
+      if (step) takeNext(step)
+      return
+    }
+    if (key.name === "r" && key.ctrl && !entryRef.current) startRefine()
     if (key.name === "o" && key.ctrl && width < SPLIT_MIN) setNarrowView((v) => (v === "chat" ? "details" : "chat"))
     if (key.name === "escape" && abortRef.current) openDialog("stop")
   })
@@ -493,7 +771,9 @@ export function App({ options }: { options: TuiOptions }) {
           push(event.ok ? "ok" : "err", briefText(event.text, detailRef.current))
           // The action itself, without the result after a colon or the locator in brackets: "click "Search"".
           const action = event.text.split(/: | {2}\[/)[0]!.trim()
-          stepOutcome(inspRef.current, event.ok, event.ok ? undefined : clip(event.text, 80), clip(action, 60))
+          // The step is named by its action, so the failure detail is what follows it: "element not found".
+          const why = event.text.slice(action.length).replace(/^[\s:\[\]]+/, "").trim() || event.text
+          stepOutcome(inspRef.current, event.ok, event.ok ? undefined : clip(why, 80), clip(action, 60))
           bump()
         }
         return
@@ -643,6 +923,9 @@ export function App({ options }: { options: TuiOptions }) {
       case "card":
         pushLine({ kind: "card", text: e.card.title, card: e.card })
         return
+      case "report":
+        producedRef.current.reports.push({ title: e.title, html: e.html })
+        return
     }
   }
 
@@ -698,7 +981,8 @@ export function App({ options }: { options: TuiOptions }) {
     return controller
   }
 
-  const finish = (finalStatus: string) => {
+  const finish = (finalStatus: string, followUps: FollowUp[] = []) => {
+    setNext(nextSteps(producedRef.current, { testsOn: testsRef.current.on, followUps }))
     progressDone(inspRef.current, finalStatus === "stopped")
     bump()
     setStatus(finalStatus)
@@ -742,6 +1026,7 @@ export function App({ options }: { options: TuiOptions }) {
     const setup = sessionSetup(cfg, options.repo)
     testsRef.current = { on: setup.writeTests, why: "the session was started with --no-code" }
     let finalStatus = "fail"
+    let followUps: FollowUp[] = []
     let fresh = false
     try {
       if (!brainRef.current) {
@@ -769,6 +1054,7 @@ export function App({ options }: { options: TuiOptions }) {
         finalStatus = "stopped"
       } else {
         if (answer.reply) pushLine({ kind: "reply", text: answer.reply, outcome: answer.outcome })
+        followUps = answer.next || []
         if (answer.error && !answer.reply) push("err", answer.error, "chat")
         finalStatus = answer.outcome === "done" ? "done" : answer.outcome === "needs_input" ? "idle" : "fail"
       }
@@ -781,7 +1067,7 @@ export function App({ options }: { options: TuiOptions }) {
       // The split view's session and tokens panels show this; only the one-pane view needs it in the chat.
       const spent = widthRef.current < SPLIT_MIN ? requestLine(meterStart) : ""
       if (spent) push("sys", spent, "chat")
-      finish(finalStatus)
+      finish(finalStatus, followUps)
     }
   }
 
@@ -831,7 +1117,22 @@ export function App({ options }: { options: TuiOptions }) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
+  const acceptSuggestion = (i: number) => {
+    const { list, trigger } = suggRef.current
+    const pick = list[i]
+    if (!pick || !trigger) return
+    setSugg({ selected: 0 })
+    fillPrompt(complete(promptTextRef.current, trigger, pick.insert))
+  }
+
   const onSubmit = (value: string) => {
+    // Enter with suggestions open takes the selected one, as tab does; a second enter sends. A command typed in full
+    // ("/help") is sent at once.
+    const full = suggRef.current.list.some((x) => x.kind === "command" && x.insert === value.trim())
+    if (suggRef.current.list.length && suggRef.current.trigger && !full) {
+      acceptSuggestion(Math.min(sugg.selected, suggRef.current.list.length - 1))
+      return
+    }
     // What a command answers (/help, /skills, "busy") is for the chat, even while a request runs.
     answeringRef.current = true
     try {
@@ -842,6 +1143,10 @@ export function App({ options }: { options: TuiOptions }) {
   }
   const submit = (value: string) => {
     const text = value.replace(/\t/g, "").trim()
+    promptTextRef.current = ""
+    setPromptText("")
+    setDraft("")
+    setNext([])
     setInputKey((k) => k + 1)
     const pending = entryRef.current
     if (pending) {
@@ -966,41 +1271,77 @@ export function App({ options }: { options: TuiOptions }) {
           : ""
   const rightColor = running ? theme.warn : status === "done" ? theme.ok : status === "fail" ? theme.err : theme.muted
   const footerRight = VERSION ? `ForgeQE ${VERSION}` : "ForgeQE"
+  // Suggestions for what is being typed: "/" commands, "@" references (runs, files, an Azure DevOps item by id).
+  const suggTrigger = triggerAt(promptText)
+  const suggKey = suggTrigger ? `${suggTrigger.kind}${suggTrigger.token}` : ""
+  const suggList: Suggestion[] =
+    !suggTrigger || sugg.dismissed === suggKey || palette || refining || entry || dialog
+      ? []
+      : suggTrigger.kind === "/"
+        ? commandSuggestions(paletteAll(), suggTrigger.token).slice(0, 8)
+        : configRef.current
+          ? referenceSuggestions(suggTrigger.token, {
+              runs: recentRuns(configRef.current.export.outDir),
+              files: repoFiles(process.cwd()),
+              item: workItem && String(workItem.id) === suggTrigger.token ? workItem : null,
+              cwd: process.cwd(),
+            })
+          : []
+  suggRef.current = { list: suggList, trigger: suggTrigger }
+  const showNext = next.length > 0 && !running && !promptText.trim() && !palette && !refining && !dialog && !entry
   const home = lines.length === 0 && !running
+  const paletteList = palette ? paletteMatches(palette.query) : []
+  const paletteOverlay = palette ? (
+    <Palette width={width} height={height} query={palette.query} items={paletteList} selected={Math.min(palette.selected, Math.max(0, paletteList.length - 1))} onPick={pickPalette} onHover={(i) => setPalette({ ...palette, selected: i })} />
+  ) : null
 
   const closeHint: Hint = { key: "ctrl+c", label: "close", onPress: () => openDialog("quit") }
   const copiedHint: Hint[] = copied ? [{ key: `✓ ${copied}`, label: "" }] : []
-  // The split view's right pane shows tokens, time, and the last result, so the hints under the prompt leave them out.
+  // The split view's right pane shows tokens, time, and the last result, so the row under the prompt leaves them out.
   const wide = width >= SPLIT_MIN
-  const viewHint: Hint[] = wide ? [] : [{ key: "ctrl+o", label: "details", onPress: () => setNarrowView("details") }]
-  // While running, the row also holds the spinner and esc stop: below 95 columns the view hint does not fit beside them.
-  const runningViewHint: Hint[] = width >= 95 ? viewHint : []
-  const idleHints: Hint[] = [
-    ...copiedHint,
-    ...(lastStats && !wide ? [{ key: `last run ${lastStats}`, label: "" }] : []),
-    ...viewHint,
-    { key: "tab", label: "profiles" },
-    { key: "ctrl+p", label: "commands" },
-    closeHint,
-  ]
-  const runningHints: Hint[] = [
-    ...copiedHint,
-    ...(wide ? [] : [{ key: `${formatTokens(tokens)} tokens · ${elapsed}`, label: "" }, ...runningViewHint]),
-    // Beside the 40% pane's spinner and esc stop, only close fits from 120 columns.
-    ...(wide ? [] : [{ key: "ctrl+p", label: "commands" }]),
-    closeHint,
+  const openPalette = () => {
+    paletteRef.current = { query: "", selected: 0 }
+    setPalette(paletteRef.current)
+  }
+  const focusPanels = () => setNav((n) => ({ ...n, focus: planLines(inspRef.current).length ? "plan" : "activity" }))
+  // What can be done from here, as buttons: Refine fills with its colour once there is a request to refine.
+  // `drop`: the order they give way on a narrow row; Refine, Search, and Stop always stay.
+  const refineButton: Button = { icon: "✦", label: "Refine", keys: "ctrl+r", color: theme.memory, onPress: () => refineRef.current(), active: Boolean(promptText.trim()) }
+  const searchButton: Button = { icon: "⌕", label: "Search", keys: "ctrl+p", color: theme.accent, onPress: openPalette }
+  // The view: in the split view, Panels and Wide chat sit in the right pane's status line, where there is room;
+  // Split view comes back here when the chat is wide, and Details on a narrow terminal.
+  const toggleWide = () => setChatWide((w) => !w)
+  const paneButtons: Button[] = [
+    { icon: "▦", label: "Panels", keys: "shift+tab", color: theme.thought, onPress: focusPanels, drop: 2 },
+    { icon: "⤢", label: "Wide chat", color: theme.muted, onPress: toggleWide, drop: 1 },
   ]
+  const viewButtons: Button[] = wide
+    ? chatWide
+      ? [{ icon: "◧", label: "Split view", color: theme.thought, onPress: toggleWide, drop: 2 }]
+      : []
+    : [{ icon: "◧", label: "Details", keys: "ctrl+o", color: theme.thought, onPress: () => setNarrowView("details"), drop: 1 }]
+  const idleButtons: Button[] = [refineButton, searchButton, ...viewButtons, ...(wide ? [] : [{ icon: "⇄", label: "Profile", keys: "tab", color: theme.muted, onPress: cycleProfile, drop: 4 }])]
+  const runningButtons: Button[] = [{ icon: "■", label: "Stop", keys: "esc", color: theme.warn, onPress: () => openDialog("stop") }, searchButton, ...viewButtons]
+  const idleHints: Hint[] = [...copiedHint, ...(lastStats && !wide && !copied ? [{ key: `last run ${lastStats}`, label: "" }] : []), closeHint]
+  // The one-pane view has no tokens panel, so the tokens and time show here.
+  const runningHints: Hint[] = [...copiedHint, ...(wide || copied ? [] : [{ key: `${formatTokens(tokens)} tokens · ${elapsed}`, label: "" }]), closeHint]
   const runningLeft = (
-    <>
+    <box style={{ flexDirection: "row", marginRight: 1 }}>
       <Spinner kind="bar" />
-      <text onMouseDown={() => openDialog("stop")}>
-        <span fg={theme.text}>{"  esc"}</span>
-        <span fg={theme.muted}>{" stop"}</span>
-      </text>
-    </>
+    </box>
   )
 
   const renderControls = (promptWidth: number, placeholder: string, rows: [number, number]) => {
+    if (refining && !dialog) {
+      return (
+        <RefinePanel
+          state={refining}
+          width={promptWidth}
+          onChoose={chooseRefine}
+          onHover={(i) => refining.phase === "done" && setRefine({ ...refining, choice: i })}
+        />
+      )
+    }
     if (dialog) {
       const spec = dialogSpec(dialog, running, outDirLabel(), thinking, waitRef.current?.text, askRef.current?.q)
       const wide = spec.options.reduce((n, o) => n + o.label.length + 3, 0) > promptWidth - 36
@@ -1020,6 +1361,45 @@ export function App({ options }: { options: TuiOptions }) {
     }
     return (
       <>
+        {showNext && !suggList.length ? (
+          // One row when the chips fit beside "Next", else one per line: a ragged wrap reads as broken.
+          next.reduce((n, st) => n + st.label.length + 9, 6) <= promptWidth ? (
+            <box style={{ flexDirection: "row", width: promptWidth, flexShrink: 0, marginBottom: 1 }}>
+              <text fg={theme.muted}>{"Next  "}</text>
+              {next.map((step, i) => (
+                <box key={step.label} onMouseDown={() => takeNext(step)} style={{ flexDirection: "row", paddingLeft: 1, paddingRight: 1, marginRight: 1, backgroundColor: theme.button }}>
+                  <text>
+                    <span fg={theme.text}>{step.label}</span>
+                    <span fg={theme.faint}>{` alt+${i + 1}`}</span>
+                  </text>
+                </box>
+              ))}
+            </box>
+          ) : (
+            <box style={{ flexDirection: "column", width: promptWidth, flexShrink: 0, marginBottom: 1 }}>
+              {next.map((step, i) => (
+                <box key={step.label} onMouseDown={() => takeNext(step)} style={{ flexDirection: "row", justifyContent: "space-between", flexShrink: 0 }}>
+                  <text>
+                    <span fg={theme.muted}>{i ? "      " : "Next  "}</span>
+                    <span fg={theme.accent}>{"▸ "}</span>
+                    <span fg={theme.text}>{step.label}</span>
+                  </text>
+                  <text fg={theme.faint}>{`alt+${i + 1}`}</text>
+                </box>
+              ))}
+            </box>
+          )
+        ) : null}
+        {suggList.length && suggTrigger ? (
+          <SuggestList
+            title={suggTrigger.kind === "/" ? "Commands" : "References"}
+            width={promptWidth}
+            items={suggList.map((x) => ({ label: x.label, detail: x.detail, color: x.kind === "command" ? theme.accent : x.kind === "run" ? theme.thought : x.kind === "item" ? theme.ok : theme.memory }))}
+            selected={Math.min(sugg.selected, suggList.length - 1)}
+            onPick={acceptSuggestion}
+            onHover={(i) => setSugg((x) => ({ ...x, selected: i }))}
+          />
+        ) : null}
         <Prompt
           width={promptWidth}
           inputKey={inputKey}
@@ -1034,21 +1414,50 @@ export function App({ options }: { options: TuiOptions }) {
           right={right}
           rightColor={rightColor}
           compact={width >= SPLIT_MIN && !home}
+          focused={!palette && !refining && (nav.focus === "chat" || (width < SPLIT_MIN && narrowView === "chat"))}
+          initialValue={draft}
+          onText={(t) => {
+            promptTextRef.current = t
+            setPromptText(t)
+          }}
         />
-        <Hints width={promptWidth} items={running ? runningHints : idleHints} left={running ? runningLeft : undefined} />
+        <ButtonBar width={promptWidth} buttons={running ? runningButtons : idleButtons} hints={running ? runningHints : idleHints} left={running ? runningLeft : undefined} />
       </>
     )
   }
 
   if (home) {
     const promptWidth = Math.max(40, Math.min(width - 8, 120))
+    // What is set up, while something is not: each open item says how, or runs the command that does it.
+    const cfgHome = configRef.current
+    const setupKey = cfgHome ? `${cfgHome.configPath}|${cfgHome.activeProfile}` : ""
+    if (cfgHome && setupRef.current.key !== setupKey) setupRef.current = { key: setupKey, items: setupChecklist(cfgHome) }
+    const setup = setupRef.current.items
+    const open = setup.filter((i) => !i.done)
+    const pickSetup = (i: SetupItem) => (i.command ? submitRef.current(i.command) : i.fix && push("sys", i.fix, "chat"))
     return (
       <box style={{ flexDirection: "column", flexGrow: 1 }}>
         <box style={{ flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center" }}>
           <Logo />
           <box style={{ height: 2 }} />
           {renderControls(promptWidth, `Describe a goal… "${example}"`, [4, Math.max(4, Math.min(12, height - 22))])}
-          <box style={{ height: 3 }} />
+          <box style={{ height: open.length ? 2 : 3 }} />
+          {open.length ? (
+            <box style={{ flexDirection: "column", alignItems: "center", flexShrink: 0, marginBottom: 1 }}>
+              <box style={{ flexDirection: "row", flexShrink: 0 }}>
+                <text fg={theme.muted}>{"Setup  "}</text>
+                {(setup.reduce((n, i) => n + i.label.length + 5, 7) <= width - 4 ? setup : open).map((i) => (
+                  <box key={i.id} onMouseDown={i.done ? undefined : () => pickSetup(i)} style={{ flexDirection: "row", paddingLeft: 1, paddingRight: 1, marginRight: 1, backgroundColor: i.done ? undefined : theme.button }}>
+                    <text>
+                      <span fg={i.done ? theme.ok : theme.warn}>{i.done ? "✓ " : "○ "}</span>
+                      <span fg={i.done ? theme.muted : theme.text}>{i.label}</span>
+                    </text>
+                  </box>
+                ))}
+              </box>
+              <text fg={theme.faint}>{`${setup.length - open.length} of ${setup.length} set up · click one to see how · /features shows what each feature needs`}</text>
+            </box>
+          ) : null}
           <text>
             <span fg={theme.warn}>{"● "}</span>
             <span fg={theme.text}>{"Tip "}</span>
@@ -1056,6 +1465,7 @@ export function App({ options }: { options: TuiOptions }) {
           </text>
         </box>
         <Footer left={shortCwd()} right={footerRight} width={width} />
+        {paletteOverlay}
       </box>
     )
   }
@@ -1094,7 +1504,9 @@ export function App({ options }: { options: TuiOptions }) {
     ? coding
       ? "The coding agent is writing a test · esc to stop"
       : `${thinking ? "ForgeQE's agent" : "The browser agent"} is working · esc to stop`
-    : "Ask ForgeQE: a goal, test cases, a test, a pipeline…"
+    : width >= SPLIT_MIN
+      ? "Ask ForgeQE · / commands · @ references"
+      : "Ask ForgeQE: a goal, test cases, a test, a pipeline… (/ commands, @ references)"
   const chatLines = lines.filter((l) => l.pane !== "activity")
   const activityLines = lines.filter((l) => l.pane === "activity")
   const stop = () => openDialog("stop")
@@ -1108,14 +1520,25 @@ export function App({ options }: { options: TuiOptions }) {
     const plan = planRows(insp, Math.max(3, Math.min(8, Math.floor(rowsAvailable / 5))))
     const activityRows = Math.max(5, rowsAvailable - 2 - plan - bottom)
     const third = Math.floor(paneWidth / 3)
+    const focusOn = (f: Focus) => () => setNav((n) => ({ ...n, focus: f }))
+    const sel = (f: "plan" | "files") => (nav.focus === f ? Math.min(nav[f], Math.max(0, (f === "plan" ? planLines(insp) : filesByUse(insp)).length - 1)) : undefined)
     return (
       <box style={{ flexDirection: "column", width: paneWidth, height: rowsAvailable, flexShrink: 0 }}>
-        <StatusBar running={running} who={insp.who} activity={activity} elapsed={elapsed} status={status} width={paneWidth} onStop={stop} />
+        <StatusBar running={running} who={insp.who} activity={activity} elapsed={elapsed} status={status} width={paneWidth} onStop={stop} progress={suiteProgress || planProgress(insp)} actions={paneButtons} />
         <box style={{ height: 1, flexShrink: 0 }} />
-        {plan ? <PlanPanel s={insp} width={paneWidth} height={plan} /> : null}
-        <ActivityPanel lines={activityLines} scrollRef={activityScroll} width={paneWidth} height={activityRows} />
+        {plan ? <PlanPanel s={insp} width={paneWidth} height={plan} selected={sel("plan")} onFocus={focusOn("plan")} /> : null}
+        <ActivityPanel
+          lines={activityLines}
+          scrollRef={activityScroll}
+          width={paneWidth}
+          height={activityRows}
+          filter={nav.filter}
+          focused={nav.focus === "activity"}
+          onFocus={focusOn("activity")}
+          onFilter={(filter) => setNav((n) => ({ ...n, filter, focus: "activity" }))}
+        />
         <box style={{ flexDirection: "row", height: bottom, flexShrink: 0 }}>
-          <FilesPanel s={insp} width={third} height={bottom} />
+          <FilesPanel s={insp} width={third} height={bottom} selected={sel("files")} onFocus={focusOn("files")} onOpen={openFile} />
           <ContextPanel c={contextPanel} width={third} height={bottom} />
           <TokensPanel total={spent.total} width={paneWidth - 2 * third} height={bottom} />
         </box>
@@ -1128,7 +1551,7 @@ export function App({ options }: { options: TuiOptions }) {
       {all.map((line) => (
         <TranscriptLine key={line.id} line={line} />
       ))}
-      {running && !split ? (
+      {running && (!split || chatWide) ? (
         <box style={{ flexDirection: "row", marginTop: 1, paddingLeft: 2, flexShrink: 0 }}>
           <Spinner kind="dots" />
           <text fg={theme.text}>{` ${activity || "Working…"}`}</text>
@@ -1140,20 +1563,25 @@ export function App({ options }: { options: TuiOptions }) {
 
   const split = width >= SPLIT_MIN
   if (split) {
-    const leftWidth = Math.floor(width * 0.4)
+    // Wide chat: the conversation across the screen for reading, the panels hidden until Split view.
+    const leftWidth = chatWide ? width : Math.floor(width * 0.4)
     return (
       <box style={{ flexDirection: "column", flexGrow: 1 }}>
         <box style={{ flexDirection: "row", height: height - 1, flexShrink: 0, paddingTop: 1 }}>
-          <box style={{ flexDirection: "column", width: leftWidth, height: height - 2, paddingLeft: 2, paddingRight: 1 }}>
-            <SessionPanel info={sessionInfo} width={leftWidth - 3} />
-            {transcript(chatLines, {})}
-            <box style={{ flexDirection: "column", flexShrink: 0 }}>{controls(leftWidth - 3)}</box>
-          </box>
-          <box style={{ flexDirection: "column", width: width - leftWidth, height: height - 2, paddingLeft: 1, paddingRight: 2 }}>
-            {details(width - leftWidth - 3, height - 2)}
+          <box onMouseDown={() => navRef.current.focus !== "chat" && setNav((n) => ({ ...n, focus: "chat" }))} style={{ flexDirection: "column", width: leftWidth, height: height - 2, paddingLeft: 2, paddingRight: chatWide ? 2 : 1 }}>
+            <SessionPanel info={sessionInfo} width={leftWidth - (chatWide ? 4 : 3)} />
+            {/* Wide chat shows what the agents do in the conversation, as the one-pane view does. */}
+            {transcript(chatWide ? lines : chatLines, {})}
+            <box style={{ flexDirection: "column", flexShrink: 0 }}>{controls(leftWidth - (chatWide ? 4 : 3))}</box>
           </box>
+          {chatWide ? null : (
+            <box style={{ flexDirection: "column", width: width - leftWidth, height: height - 2, paddingLeft: 1, paddingRight: 2 }}>
+              {details(width - leftWidth - 3, height - 2)}
+            </box>
+          )}
         </box>
         <Footer left={shortCwd()} right={footerRight} width={width} />
+        {paletteOverlay}
       </box>
     )
   }
@@ -1168,10 +1596,11 @@ export function App({ options }: { options: TuiOptions }) {
             // Stop, a question, or "your turn": the same panel the chat view shows in place of the prompt.
             controls(promptWidth)
           ) : (
-            <Hints width={promptWidth} items={[{ key: "ctrl+o", label: "back to the chat", onPress: () => setNarrowView("chat") }, closeHint]} />
+            <Hints width={promptWidth} items={[{ key: "ctrl+o", label: "back to the chat", onPress: () => setNarrowView("chat") }, { key: "shift+tab", label: "panels", drop: 1 }, closeHint]} />
           )}
         </box>
         <Footer left={shortCwd()} right={footerRight} width={width} />
+        {paletteOverlay}
       </box>
     )
   }
@@ -1180,6 +1609,7 @@ export function App({ options }: { options: TuiOptions }) {
       {transcript(lines, { paddingLeft: 2, paddingRight: 2, paddingTop: 1 })}
       <box style={{ flexDirection: "column", paddingLeft: 2, paddingRight: 2, flexShrink: 0 }}>{controls(promptWidth)}</box>
       <Footer left={shortCwd()} right={footerRight} width={width} />
+      {paletteOverlay}
     </box>
   )
 }