@capagents/forgeqe 1.0.8 → 1.0.9

package/HOW_TO_USE.md

@@ -385,6 +385,30 @@ The chat gets a short summary and a card with both paths as links, and **Open th
 
 ### The screen
 
+**The start screen.** Before your first request, the screen is one column under the logo:
+
+```
+  playwright-csharp-pom-framework  ·  .NET  ·  Azure DevOps  ·  azure/gpt-5.4
+
+  ┃ Describe what you want to test…
+  ✦ Refine ctrl+r   ⌕ Search ctrl+p                          ? shortcuts  ctrl+c close
+
+  Start with
+    ▸ Run test cases            Run test plan 12 suite 34 from Azure DevOps…   alt+1
+    ▸ Check release readiness   Are we ready to release?                       alt+2
+  Continue
+    ▤ Report  QI-Payments pipeline status report           18 min ago   open
+    ✓ Run     Search hotels in Mumbai on booking.com       2 days ago   open  rerun
+  Setup  ▰▰▰▱▱  3 of 5 · Domain and Notifications are not set up   ▸ how to set up
+```
+
+- The line under the logo is what ForgeQE works with here: the folder, what it is built with (from its files, such as a `.sln` or `playwright.config.ts`), the systems that are set up, and the model.
+- The prompt starts five rows high and grows with a long request, up to nearly half the screen, before it scrolls; the sections below give way, last first, to make room.
+- **Start with** offers up to four things to ask, from the capabilities that work in this setup, each with an example in the words of your setup. Click one, or press Alt-1 to Alt-4, to put it in the prompt to adjust and send.
+- **Continue** lists the newest reports and runs in the reports folder: **open** opens the report, **rerun** puts the run's goal in the prompt.
+- **Setup** shows how much is set up and what is missing (see the setup checklist below); it goes away once everything is set up.
+- The tip in the footer changes every few seconds. Press **?** on an empty prompt for every key; Esc closes the list.
+
 On a terminal 120 columns wide or more, the shell splits in two once you send a request:
 
 - **Left (40%)**: the **Session** panel (model and profile, folder, domain, requests so far), the conversation, and the prompt.
@@ -408,7 +432,7 @@ On a narrower terminal the chat fills the screen, and Ctrl-O switches between th
 
 **Links.** Report folders, report files, and web addresses in the chat are links: Cmd-click (Ctrl-click on Windows and Linux) opens them in terminals that support links, such as VS Code, iTerm2, Windows Terminal, and recent GNOME Terminal. A path that no longer exists stays plain text.
 
-**Setup checklist.** Until everything is set up, the start screen shows what most features rest on: **Model** (a live model profile), **Coding agent**, **Work items** (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), **Domain**, and **Notifications**, each ✓ or ○. Click an open item to see how to set it up; **Work items** starts `/auth`. The checks are the same ones `/features` uses, so the two always agree.
+**Setup checklist.** Until everything is set up, the start screen's **Setup** line shows how many of the five things most features rest on are set up, and names the ones that are not: **Model** (a live model profile), **Coding agent**, **Work items** (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), **Domain**, and **Notifications**. **▸ how to set up** puts the steps for each missing one in the chat (for **Work items**, type `/auth`). The checks are the same ones `/features` uses, so the two always agree.
 
 **Command palette.** Ctrl-P opens a palette of every action, command, profile, and example request; type a few letters to find one ("rr" finds *Refine my request*, "auth" finds the sign-in commands), ↑/↓ to choose, Enter to run it. Example requests are put in the prompt for you to edit, never sent straight away.
 
@@ -444,6 +468,8 @@ A read-only agent writes it. It starts knowing every capability and whether it w
 | Ctrl-R | Refine the request in the prompt |
 | Ctrl-O | Chat or details, on a terminal narrower than 120 columns |
 | Alt-1 to Alt-3 | Take a suggested next step |
+| Alt-1 to Alt-4 | On the start screen: put a **Start with** action in the prompt |
+| ? | On an empty prompt: every key, in one list |
 | Esc | Ask to stop the run: **Stop run**, **Stop and close ForgeQE**, or **Keep running**. In a panel, back to the prompt |
 | Ctrl-C | Ask to close ForgeQE: **Close** or **Cancel**. A second Ctrl-C closes straight away |
 

package/docs/user-guide.html

@@ -547,7 +547,29 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 </code></pre>
 <p>The text is the agent's own result. Failed runs show <code>✗ Task failed</code> with the reason, and stopped runs show <code>■ Run stopped</code>. <code>forgeqe run</code> prints the same summary at the end.</p>
 </div>
-<section class="doc sub" id="doc-how_to_use-the-screen"><h4>The screen</h4><div class="prose"><p>On a terminal 120 columns wide or more, the shell splits in two once you send a request:</p>
+<section class="doc sub" id="doc-how_to_use-the-screen"><h4>The screen</h4><div class="prose"><p><strong>The start screen.</strong> Before your first request, the screen is one column under the logo:</p>
+<pre><code>  playwright-csharp-pom-framework  ·  .NET  ·  Azure DevOps  ·  azure/gpt-5.4
+
+  ┃ Describe what you want to test…
+  ✦ Refine ctrl+r   ⌕ Search ctrl+p                          ? shortcuts  ctrl+c close
+
+  Start with
+    ▸ Run test cases            Run test plan 12 suite 34 from Azure DevOps…   alt+1
+    ▸ Check release readiness   Are we ready to release?                       alt+2
+  Continue
+    ▤ Report  QI-Payments pipeline status report           18 min ago   open
+    ✓ Run     Search hotels in Mumbai on booking.com       2 days ago   open  rerun
+  Setup  ▰▰▰▱▱  3 of 5 · Domain and Notifications are not set up   ▸ how to set up
+</code></pre>
+<ul>
+<li>The line under the logo is what ForgeQE works with here: the folder, what it is built with (from its files, such as a <code>.sln</code> or <code>playwright.config.ts</code>), the systems that are set up, and the model.</li>
+<li>The prompt starts five rows high and grows with a long request, up to nearly half the screen, before it scrolls; the sections below give way, last first, to make room.</li>
+<li><strong>Start with</strong> offers up to four things to ask, from the capabilities that work in this setup, each with an example in the words of your setup. Click one, or press Alt-1 to Alt-4, to put it in the prompt to adjust and send.</li>
+<li><strong>Continue</strong> lists the newest reports and runs in the reports folder: <strong>open</strong> opens the report, <strong>rerun</strong> puts the run's goal in the prompt.</li>
+<li><strong>Setup</strong> shows how much is set up and what is missing (see the setup checklist below); it goes away once everything is set up.</li>
+<li>The tip in the footer changes every few seconds. Press <strong>?</strong> on an empty prompt for every key; Esc closes the list.</li>
+</ul>
+<p>On a terminal 120 columns wide or more, the shell splits in two once you send a request:</p>
 <ul>
 <li><strong>Left (40%)</strong>: the <strong>Session</strong> panel (model and profile, folder, domain, requests so far), the conversation, and the prompt.</li>
 <li><strong>Right (60%)</strong>: a status line with who is working, for how long, and a <strong>■ Stop</strong> button (a running suite adds a progress bar, <code>██████░░░░░░ 5/8</code>); then <strong>Plan</strong> (the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running), <strong>Activity</strong> (every tool call, browser step, and the agents' reasoning), <strong>Files</strong> (each file read ◉, written ✚, or edited ✎, newest first), <strong>Context</strong> (how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it), and <strong>Tokens</strong> (total, input, output, cached; no prices, which are in reports and <code>forgeqe models</code>).</li>
@@ -568,7 +590,7 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 </tbody>
 </table></div>
 <p><strong>Links.</strong> Report folders, report files, and web addresses in the chat are links: Cmd-click (Ctrl-click on Windows and Linux) opens them in terminals that support links, such as VS Code, iTerm2, Windows Terminal, and recent GNOME Terminal. A path that no longer exists stays plain text.</p>
-<p><strong>Setup checklist.</strong> Until everything is set up, the start screen shows what most features rest on: <strong>Model</strong> (a live model profile), <strong>Coding agent</strong>, <strong>Work items</strong> (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), <strong>Domain</strong>, and <strong>Notifications</strong>, each ✓ or ○. Click an open item to see how to set it up; <strong>Work items</strong> starts <code>/auth</code>. The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
+<p><strong>Setup checklist.</strong> Until everything is set up, the start screen's <strong>Setup</strong> line shows how many of the five things most features rest on are set up, and names the ones that are not: <strong>Model</strong> (a live model profile), <strong>Coding agent</strong>, <strong>Work items</strong> (Azure DevOps, Jira, TestRail, Zephyr, qTest, or Xray), <strong>Domain</strong>, and <strong>Notifications</strong>. <strong>▸ how to set up</strong> puts the steps for each missing one in the chat (for <strong>Work items</strong>, type <code>/auth</code>). The checks are the same ones <code>/features</code> uses, so the two always agree.</p>
 <p><strong>Command palette.</strong> Ctrl-P opens a palette of every action, command, profile, and example request; type a few letters to find one (&quot;rr&quot; finds <em>Refine my request</em>, &quot;auth&quot; finds the sign-in commands), ↑/↓ to choose, Enter to run it. Example requests are put in the prompt for you to edit, never sent straight away.</p>
 <p><strong><code>/</code> and <code>@</code> in the prompt.</strong> Typing <code>/</code> lists the commands that match; typing <code>@</code> suggests references: recent runs (<em>last run</em>, then each by its folder), files in the repository by name or path (<code>@Login</code> finds <code>pages/Login.ts</code>), and, after <code>@</code> and a number such as <code>@1761</code>, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.</p>
 <p><strong>Refine.</strong> Ctrl-R (or <em>Refine my request</em> in the palette) turns what you typed into a task specification for ForgeQE's agent, in ASD-STE100 Simplified Technical English, before it is sent:</p>
@@ -599,6 +621,8 @@ Result: A shareable report file with a short summary for the manager.
 <tr><td>Ctrl-R</td><td>Refine the request in the prompt</td></tr>
 <tr><td>Ctrl-O</td><td>Chat or details, on a terminal narrower than 120 columns</td></tr>
 <tr><td>Alt-1 to Alt-3</td><td>Take a suggested next step</td></tr>
+<tr><td>Alt-1 to Alt-4</td><td>On the start screen: put a <strong>Start with</strong> action in the prompt</td></tr>
+<tr><td>?</td><td>On an empty prompt: every key, in one list</td></tr>
 <tr><td>Esc</td><td>Ask to stop the run: <strong>Stop run</strong>, <strong>Stop and close ForgeQE</strong>, or <strong>Keep running</strong>. In a panel, back to the prompt</td></tr>
 <tr><td>Ctrl-C</td><td>Ask to close ForgeQE: <strong>Close</strong> or <strong>Cancel</strong>. A second Ctrl-C closes straight away</td></tr>
 </tbody>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in Chrome and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/src/tui/App.tsx

@@ -26,7 +26,9 @@ import { meterSnapshot, requestLine } from "../usage.ts"
 import { cleanSelection, copyText } from "./clipboard.ts"
 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 { ShortcutsPanel } from "./shortcuts.tsx"
+import { ago, projectLine, setupSentence, recentWork, startActions, type RecentItem, type StartAction } from "./landing.ts"
+import { TIPS, formatDuration, formatTokens, packageVersion, 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"
@@ -154,6 +156,12 @@ export function App({ options }: { options: TuiOptions }) {
   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("")
+  // The rows the request in the prompt needs; the start screen gives a long one room by folding its other sections.
+  const [promptLines, setPromptLines] = useState(1)
+  const [tipIndex, setTipIndex] = useState(() => Math.floor(Math.random() * TIPS.length))
+  const [shortcuts, setShortcuts] = useState(false)
+  const shortcutsRef = useRef(false)
+  shortcutsRef.current = shortcuts
   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 })
@@ -171,7 +179,7 @@ export function App({ options }: { options: TuiOptions }) {
   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: [] })
+  const setupRef = useRef<{ key: string; items: SetupItem[]; start: StartAction[]; recent: RecentItem[] }>({ key: "", items: [], start: [], recent: [] })
   // 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)
@@ -183,6 +191,8 @@ export function App({ options }: { options: TuiOptions }) {
   const contextInfo = useRef<{ key: string; knowledge: number; mcp: string[] }>({ key: "", knowledge: 0, mcp: [] })
 
   const [lines, setLines] = useState<Line[]>([])
+  const linesRef = useRef(0)
+  linesRef.current = lines.length
   const [headed, setHeaded] = useState(Boolean(options.headed))
   const [maxSteps, setMaxSteps] = useState(40)
   const [profile, setProfile] = useState(options.profile || "")
@@ -201,8 +211,6 @@ export function App({ options }: { options: TuiOptions }) {
   const [coding, setCoding] = useState(false)
   const [suiteProgress, setSuiteProgress] = useState<{ done: number; total: number } | null>(null)
   const [copied, setCopied] = useState("")
-  const [example] = useState(() => pick(EXAMPLES))
-  const [tip] = useState(() => pick(TIPS))
   const started = useRef<number | null>(null)
 
   const detailRef = useRef<Detail>(detailFrom(options.verbose))
@@ -289,6 +297,13 @@ export function App({ options }: { options: TuiOptions }) {
     return () => clearInterval(timer)
   }, [status])
 
+  // The start screen's tip changes every 8 seconds; only while it shows, so a session does not re-render for it.
+  useEffect(() => {
+    if (lines.length || status === "running") return
+    const timer = setInterval(() => setTipIndex((n) => n + 1), 8000)
+    return () => clearInterval(timer)
+  }, [lines.length, status])
+
   // The terminal hands mouse drags to the TUI, so text selected with the mouse is copied here when the drag ends.
   useEffect(() => {
     let timer: ReturnType<typeof setTimeout> | undefined
@@ -562,6 +577,7 @@ export function App({ options }: { options: TuiOptions }) {
     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 === "shortcuts") setShortcuts(true)
     else if (run.id === "panels") setNav((n) => ({ ...n, focus: planLines(inspRef.current).length ? "plan" : "activity" }))
   }
 
@@ -575,6 +591,8 @@ export function App({ options }: { options: TuiOptions }) {
   }
 
   useKeyboard((key) => {
+    // Esc is the shell's (stop, close a list or panel, cancel): the prompt never acts on it, or it would lose focus.
+    if (key.name === "escape") key.preventDefault()
     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.
@@ -652,11 +670,15 @@ export function App({ options }: { options: TuiOptions }) {
     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) {
+      // Consumed here: the prompt can take focus within this key press and must not also act on it.
+      key.preventDefault()
       setNav((n) => ({ ...n, focus: nextFocus(n.focus, shown) }))
       return
     }
     const at = navRef.current.focus
     if (panes && at !== "chat" && shown(at)) {
+      // Keys a panel takes are its own: the prompt, focused again by esc, must not see the same esc (it would blur).
+      if (key.name === "escape" || key.name === "return" || key.name === "enter" || key.name === "kpenter") key.preventDefault()
       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))
@@ -691,6 +713,23 @@ export function App({ options }: { options: TuiOptions }) {
       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
     }
+    // ? on an empty prompt: every key in one panel; esc or ? closes it.
+    if (shortcutsRef.current) {
+      if (key.name === "escape" || key.sequence === "?") setShortcuts(false)
+      return
+    }
+    if (key.sequence === "?" && !promptTextRef.current.trim() && !entryRef.current && !dialogRef.current) {
+      setShortcuts(true)
+      setDraft("")
+      setInputKey((k) => k + 1)
+      return
+    }
+    // The start screen's actions: alt+1 to alt+4 put one in the prompt.
+    if (key.meta && /^[1-4]$/.test(key.name || "") && linesRef.current === 0 && !abortRef.current) {
+      const a = setupRef.current.start[Number(key.name) - 1]
+      if (a) fillPrompt(a.request)
+      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 }))
@@ -1322,7 +1361,9 @@ export function App({ options }: { options: TuiOptions }) {
     : [{ 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]
+  const shortcutsHint: Hint = { key: "?", label: "shortcuts", onPress: () => setShortcuts(true) }
+  // ? is offered where there is room for it: the start screen of a terminal 110 columns or wider; it works everywhere.
+  const idleHints: Hint[] = [...copiedHint, ...(lastStats && !wide && !copied ? [{ key: `last run ${lastStats}`, label: "" }] : []), ...(home && width >= 110 ? [shortcutsHint] : []), 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 = (
@@ -1420,52 +1461,147 @@ export function App({ options }: { options: TuiOptions }) {
             promptTextRef.current = t
             setPromptText(t)
           }}
+          onLines={setPromptLines}
         />
         <ButtonBar width={promptWidth} buttons={running ? runningButtons : idleButtons} hints={running ? runningHints : idleHints} left={running ? runningLeft : undefined} />
       </>
     )
   }
 
+  // Back on the start screen after /clear, its sections are read again: new reports and runs show up.
+  if (!home) setupRef.current.key = ""
+  const shortcutsOverlay = shortcuts ? <ShortcutsPanel width={width} wide={width >= SPLIT_MIN} onClose={() => setShortcuts(false)} /> : null
+
   if (home) {
-    const promptWidth = Math.max(40, Math.min(width - 8, 120))
+    // One column, as wide as the prompt, every section on its left edge.
+    const promptWidth = Math.max(40, Math.min(width - 8, 140))
     // 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
+    if (cfgHome && setupRef.current.key !== setupKey) {
+      setupRef.current = {
+        key: setupKey,
+        items: setupChecklist(cfgHome),
+        start: startActions(cfgHome),
+        recent: recentWork(path.resolve(cfgHome.export.outDir)),
+      }
+    }
+    const { items: setup, start, recent } = setupRef.current
     const open = setup.filter((i) => !i.done)
-    const pickSetup = (i: SetupItem) => (i.command ? submitRef.current(i.command) : i.fix && push("sys", i.fix, "chat"))
+    // Each missing item with how to set it up, in the chat; the first that a command sets up (/auth) is offered last.
+    const explainSetup = (items: SetupItem[]) => push("sys", items.map((i) => `○ ${i.fix}${i.command ? ` Type ${i.command} to start.` : ""}`).join("\n"), "chat")
+    const facts = projectLine(cfgHome, process.cwd(), cfgHome ? modelLabel(cfgHome) : "")
+
+    // Rows: the logo, the project line, and the prompt always; then Start with, Continue, and Setup while they fit.
+    // A long request takes rows from them, last section first, so the box never scrolls while there is room.
+    const loading = !cfgHome
+    // Each section is a blank row and then its own rows: a heading and its items, or the setup line.
+    const startRows = loading ? 1 + 1 + 4 : start.length ? 1 + 1 + start.length : 0
+    const recentRows = recent.length ? 1 + 1 + recent.length : 0
+    const setupRows = loading || open.length ? 2 : 0
+    const fixed = 5 + 2 + 1 + 5 + 1 + 1 + 1 // logo, project line, gap, prompt chrome, buttons, footer, one row to spare
+    const room = height - fixed
+    const want = Math.max(5, Math.min(promptLines, room - 1))
+    let left = room - want
+    const showStart = startRows > 0 && left >= startRows
+    if (showStart) left -= startRows
+    const showRecent = recentRows > 0 && left >= recentRows
+    if (showRecent) left -= recentRows
+    const showSetup = setupRows > 0 && left >= setupRows
+    const maxRows = Math.max(5, room - (showStart ? startRows : 0) - (showRecent ? recentRows : 0) - (showSetup ? setupRows : 0))
+    const heading = (t: string) => <text fg={theme.muted}>{t}</text>
+    const keyCell = (k: string) => <span fg={theme.faint}>{k.padEnd(4)}</span>
+    const done = setup.length - open.length
     return (
       <box style={{ flexDirection: "column", flexGrow: 1 }}>
-        <box style={{ flexDirection: "column", flexGrow: 1, alignItems: "center", justifyContent: "center" }}>
+        {/* Clipped, never pushed: the footer stays on screen whatever the sections above it need. */}
+        <box style={{ flexDirection: "column", flexGrow: 1, flexShrink: 1, minHeight: 0, overflow: "hidden", 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: 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>
+          <box style={{ paddingTop: 1, height: 2, flexShrink: 0 }}>
+          <text>
+            {facts.length ? (
+              facts.map((f, i) => (
+                <span key={i} fg={i === 0 ? theme.text : theme.muted}>
+                  {`${i ? "  ·  " : ""}${f}`}
+                </span>
+              ))
+            ) : (
+              <span fg={theme.faint}>{" "}</span>
+            )}
+          </text>
+          </box>
+          <box style={{ height: 1, flexShrink: 0 }} />
+          <box style={{ flexDirection: "column", width: promptWidth, flexShrink: 0 }}>
+            {renderControls(promptWidth, "Describe what you want to test…", [5, maxRows])}
+            {showStart ? (
+              <box style={{ flexDirection: "column", marginTop: 1, height: startRows - 1, flexShrink: 0 }}>
+                {heading("Start with")}
+                {loading
+                  ? [0, 1, 2, 3].map((i) => <text key={i} fg={theme.faint}>{i ? " " : "  Loading what works in this setup…"}</text>)
+                  : start.map((a, i) => (
+                      <box key={a.id} onMouseDown={() => fillPrompt(a.request)} style={{ flexDirection: "row", justifyContent: "space-between", flexShrink: 0 }}>
+                        <text>
+                          <span fg={theme.accent}>{"  ▸ "}</span>
+                          <span fg={theme.text}>{a.label.padEnd(32)}</span>
+                          <span fg={theme.faint}>{clip(a.detail, Math.max(10, promptWidth - 50))}</span>
+                        </text>
+                        <text>{keyCell(`alt+${i + 1}`)}</text>
+                      </box>
+                    ))}
+              </box>
+            ) : null}
+            {showRecent ? (
+              <box style={{ flexDirection: "column", marginTop: 1, height: recentRows - 1, flexShrink: 0 }}>
+                {heading("Continue")}
+                {recent.map((r) => (
+                  <box key={r.dir} style={{ flexDirection: "row", justifyContent: "space-between", flexShrink: 0 }}>
+                    <text onMouseDown={() => openFile(r.open)}>
+                      <span fg={r.kind === "report" ? theme.memory : r.status === "complete" || r.status === "passed" ? theme.ok : r.status ? theme.err : theme.muted}>
+                        {r.kind === "report" ? "  ▤ " : r.status === "complete" || r.status === "passed" ? "  ✓ " : r.status ? "  ✗ " : "  ▸ "}
+                      </span>
+                      <span fg={theme.muted}>{r.kind === "report" ? "Report  " : "Run     "}</span>
+                      <span fg={theme.text}>{clip(r.title, Math.max(10, promptWidth - 40))}</span>
                     </text>
+                    <box style={{ flexDirection: "row" }}>
+                      <text fg={theme.faint}>{`${ago(r.when)}  `}</text>
+                      <text fg={theme.accent} onMouseDown={() => openFile(r.open)}>
+                        {"open"}
+                      </text>
+                      {r.kind === "run" ? (
+                        <text fg={theme.accent} onMouseDown={() => fillPrompt(`Run this goal again: ${r.title}`)}>
+                          {"  rerun"}
+                        </text>
+                      ) : null}
+                    </box>
                   </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>
-            <span fg={theme.muted}>{tip}</span>
-          </text>
+            ) : null}
+            {showSetup ? (
+              // Setup in one line: how far it is, what is missing in words, and one link that says how to set it up.
+              <box style={{ flexDirection: "row", height: 1, flexShrink: 0, marginTop: 1 }}>
+                <text>
+                  <span fg={theme.muted}>{"Setup  "}</span>
+                  <span fg={theme.ok}>{"▰".repeat(done)}</span>
+                  <span fg={theme.muted}>{"▱".repeat(open.length)}</span>
+                  <span fg={theme.muted}>{loading ? "  checking…" : `  ${done} of ${setup.length} · `}</span>
+                  {loading ? null : <span fg={theme.text}>{setupSentence(open.map((i) => i.label), promptWidth - 44)}</span>}
+                </text>
+                {loading ? null : (
+                  <box onMouseDown={() => explainSetup(open)} style={{ marginLeft: 2, paddingLeft: 1, paddingRight: 1, backgroundColor: theme.button }}>
+                    <text>
+                      <span fg={theme.warn}>{"▸ "}</span>
+                      <span fg={theme.text}>{"how to set up"}</span>
+                    </text>
+                  </box>
+                )}
+              </box>
+            ) : null}
+          </box>
         </box>
-        <Footer left={shortCwd()} right={footerRight} width={width} />
+        <Footer left={`● Tip  ${TIPS[tipIndex % TIPS.length]}`} right={footerRight} width={width} cut="end" />
         {paletteOverlay}
+        {shortcutsOverlay}
       </box>
     )
   }
@@ -1559,7 +1695,8 @@ export function App({ options }: { options: TuiOptions }) {
       ) : null}
     </scrollbox>
   )
-  const controls = (paneWidth: number) => renderControls(paneWidth, placeholder, [3, Math.max(3, Math.min(10, Math.floor(height / 3)))])
+  // A long request gets room: the box grows with the text up to nearly half the screen, then scrolls.
+  const controls = (paneWidth: number) => renderControls(paneWidth, placeholder, [3, Math.max(3, Math.floor(height * 0.45))])
 
   const split = width >= SPLIT_MIN
   if (split) {

package/src/tui/components.tsx

@@ -21,7 +21,7 @@ export function Logo() {
   const name = logoRows("forge")
   const suffix = logoRows("QE")
   return (
-    <box style={{ flexDirection: "column", alignItems: "flex-end" }}>
+    <box style={{ flexDirection: "column", alignItems: "flex-end", flexShrink: 0 }}>
       {name.map((row, i) => (
         <text key={i}>
           <span fg={theme.faint}>{row}</span>
@@ -56,6 +56,32 @@ export type PromptProps = {
   focused?: boolean
   /** Called with the text as it changes, for actions on what is being typed (Refine). */
   onText?: (text: string) => void
+  /** Called with the rows the text needs, so the screen around the box can make room for a long request. */
+  onLines?: (lines: number) => void
+}
+
+/** The rows `text` takes when word-wrapped at `width` columns, as the prompt wraps it. */
+export function wrappedLines(text: string, width: number): number {
+  if (width < 1) return 1
+  let rows = 0
+  for (const line of text.split("\n")) {
+    let used = 0
+    let count = 1
+    for (const word of line.split(/(\s+)/)) {
+      if (!word) continue
+      if (used + word.length <= width) used += word.length
+      else if (/^\s+$/.test(word)) used = width
+      else if (word.length > width) {
+        count += Math.ceil((used + word.length) / width) - 1
+        used = (used + word.length) % width
+      } else {
+        count++
+        used = word.length
+      }
+    }
+    rows += count
+  }
+  return Math.max(1, rows)
 }
 
 /** Enter sends; Shift+Enter, Alt+Enter or Ctrl+J start a new line. */
@@ -70,16 +96,31 @@ const PROMPT_KEYS: KeyBinding[] = [
 export function Prompt(props: PromptProps) {
   const edge = `╹${"▀".repeat(Math.max(0, props.width - 1))}`
   const ref = useRef<TextareaRenderable>(null)
-  const [rows, setRows] = useState(props.minRows)
-  useEffect(() => setRows(props.minRows), [props.inputKey, props.minRows])
+  // The rows the text needs; the box shows that many between minRows and maxRows, so it also grows when the screen
+  // around it makes more room (the start screen folds a section for a long request).
+  const [lines, setLines] = useState(1)
+  useEffect(() => setLines(1), [props.inputKey])
+  const rows = Math.min(props.maxRows, Math.max(props.minRows, lines))
+  // The text scrolled while the box was smaller: once it all fits, show it from the top.
+  useEffect(() => {
+    const t = ref.current
+    if (!t || lines > rows || t.scrollY === 0) return
+    // Going to the top scrolls the view there; going back to where the cursor was keeps it there, now that all fits.
+    const at = t.cursorOffset
+    t.gotoBufferHome()
+    t.cursorOffset = at
+  }, [rows, lines])
   // Inserted text (a completion, an example, a refined request) is continued from its end.
   useEffect(() => {
     if (props.initialValue) ref.current?.gotoBufferEnd()
   }, [props.inputKey])
   const fit = () => {
     props.onText?.(ref.current?.plainText ?? "")
-    const lines = ref.current?.virtualLineCount ?? 1
-    setRows(Math.min(props.maxRows, Math.max(props.minRows, lines)))
+    // virtualLineCount counts only the lines in view, so a box could never ask to grow: count the wrapped lines.
+    const t = ref.current
+    const needed = t ? wrappedLines(t.plainText, t.width || props.width - 5) : 1
+    props.onLines?.(needed)
+    setLines(needed)
   }
   return (
     <box style={{ flexDirection: "column", width: props.width, flexShrink: 0 }}>
@@ -328,9 +369,10 @@ export function ChoicePanel(props: ChoicePanelProps) {
   )
 }
 
-export function Footer({ left, right, width }: { left: string; right: string; width: number }) {
+/** `cut`: which end of `left` gives way when it is too long: the start of a path, the end of a sentence (the tip). */
+export function Footer({ left, right, width, cut = "start" }: { left: string; right: string; width: number; cut?: "start" | "end" }) {
   const room = Math.max(8, width - right.length - 8)
-  const shown = left.length <= room ? left : `…${left.slice(left.length - room + 1)}`
+  const shown = left.length <= room ? left : cut === "end" ? `${left.slice(0, room - 1)}…` : `…${left.slice(left.length - room + 1)}`
   return (
     <box
       style={{ flexDirection: "row", justifyContent: "space-between", paddingLeft: 2, paddingRight: 2, height: 1, flexShrink: 0 }}

package/src/tui/landing.ts

@@ -0,0 +1,128 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import path from "node:path"
+
+import type { AppConfig } from "../config.ts"
+import { CAPABILITIES } from "../capabilities/registry.ts"
+import { allStatuses, configuredSystems, SYSTEM_LABEL, type Probes, MACHINE } from "../capabilities/status.ts"
+
+/**
+ * What the start screen shows before the first request: the project it works on, the actions that work in this setup,
+ * and the reports and runs to pick up again. Everything comes from the config, the capability registry, and the files
+ * in the folder, so it changes as the setup changes.
+ */
+
+/** "C# · .NET solution · Playwright Test": what the folder's own files say it is built with. */
+export function projectStack(cwd: string): string[] {
+  let names: string[] = []
+  try {
+    names = readdirSync(cwd)
+  } catch {
+    return []
+  }
+  const has = (re: RegExp) => names.some((n) => re.test(n))
+  const out: string[] = []
+  if (has(/^playwright\.config\.(ts|js|mjs|cjs)$/)) out.push("Playwright Test")
+  if (has(/^cypress\.config\.(ts|js|mjs|cjs)$/)) out.push("Cypress")
+  if (has(/\.sln$/) || has(/\.csproj$/)) out.push(".NET")
+  if (has(/^pom\.xml$/)) out.push("Maven")
+  if (has(/^build\.gradle(\.kts)?$/)) out.push("Gradle")
+  if (has(/^(pytest\.ini|conftest\.py)$/) || (has(/^pyproject\.toml$/) && !out.length)) out.push("Python")
+  if (has(/^package\.json$/) && !out.some((s) => s === "Playwright Test" || s === "Cypress")) out.push("Node")
+  return out.slice(0, 2)
+}
+
+/** The project line: folder, stack, the systems ForgeQE works with here, and the model. */
+export function projectLine(cfg: AppConfig | null, cwd: string, model: string): string[] {
+  const parts = [path.basename(cwd), ...projectStack(cwd)]
+  if (cfg) parts.push(...[...configuredSystems(cfg)].filter((s) => s !== "xray" || !configuredSystems(cfg).has("jira")).map((s) => SYSTEM_LABEL[s]))
+  if (model) parts.push(model)
+  return parts.filter(Boolean)
+}
+
+const ALL_SYSTEMS = Object.values(SYSTEM_LABEL)
+
+export type StartAction = { id: string; label: string; detail: string; request: string }
+
+/**
+ * The first things worth asking, in this order, among the capabilities that work in this setup: work from the systems
+ * first, then what a team asks for most. Each puts its example request in the prompt to adjust.
+ */
+const START_ORDER = ["run-test-cases", "release-readiness", "reports", "exploratory-testing", "write-test-cases", "pr-review", "api-testing", "find-run-tests", "browser-goals"]
+
+const START_LABEL: Record<string, string> = {
+  "run-test-cases": "Run test cases",
+  "release-readiness": "Check release readiness",
+  reports: "Write a report to share",
+  "exploratory-testing": "Explore a story for bugs",
+  "write-test-cases": "Write test cases from a story",
+  "pr-review": "Review a pull request",
+  "api-testing": "Test an API",
+  "find-run-tests": "Run the repository's tests",
+  "browser-goals": "Try a flow in the browser",
+}
+
+export function startActions(cfg: AppConfig | null, limit = 4, probes: Probes = MACHINE): StartAction[] {
+  if (!cfg) return []
+  const statuses = allStatuses(cfg, probes)
+  const systems = [...configuredSystems(cfg)].map((x) => SYSTEM_LABEL[x])
+  const out: StartAction[] = []
+  for (const id of START_ORDER) {
+    const c = CAPABILITIES.find((x) => x.id === id)
+    if (!c || statuses.get(id)?.state === "needs_setup") continue
+    // An example in the words of this setup: one that names a system that is set up, else one that names none.
+    const named = c.examples.find((e) => systems.some((n) => e.includes(n)))
+    const neutral = c.examples.find((e) => !ALL_SYSTEMS.some((n) => e.includes(n)))
+    const example = named || neutral || c.examples[0] || c.title
+    out.push({ id, label: START_LABEL[id] || c.title, detail: example, request: example })
+    if (out.length === limit) break
+  }
+  return out
+}
+
+export type RecentItem = { kind: "report" | "run"; title: string; dir: string; open: string; when: Date; status?: string }
+
+/** The newest reports and runs in the reports folder: what a returning user picks up again. */
+export function recentWork(outDir: string, limit = 3): RecentItem[] {
+  if (!existsSync(outDir)) return []
+  const items: RecentItem[] = []
+  for (const name of readdirSync(outDir)) {
+    const dir = path.join(outDir, name)
+    try {
+      if (!statSync(dir).isDirectory()) continue
+      const when = statSync(dir).mtime
+      if (existsSync(path.join(dir, "run.json"))) {
+        const run = JSON.parse(readFileSync(path.join(dir, "run.json"), "utf8")) as { goal?: string; status?: string }
+        const report = path.join(dir, "report.html")
+        items.push({ kind: "run", title: String(run.goal || name), dir, open: existsSync(report) ? report : dir, when, status: run.status })
+      } else if (existsSync(path.join(dir, "report.md"))) {
+        const first = readFileSync(path.join(dir, "report.md"), "utf8").split("\n")[0] || ""
+        const html = path.join(dir, "report.html")
+        items.push({ kind: "report", title: first.replace(/^#\s*/, "").trim() || name, dir, open: existsSync(html) ? html : path.join(dir, "report.md"), when })
+      }
+    } catch {}
+  }
+  return items.sort((a, b) => b.when.getTime() - a.when.getTime()).slice(0, limit)
+}
+
+/** "just now", "12 min ago", "3 h ago", "yesterday", "4 days ago", then the date. */
+export function ago(when: Date, now = new Date()): string {
+  const s = Math.max(0, (now.getTime() - when.getTime()) / 1000)
+  if (s < 60) return "just now"
+  if (s < 3600) return `${Math.floor(s / 60)} min ago`
+  if (s < 86400) return `${Math.floor(s / 3600)} h ago`
+  if (s < 2 * 86400) return "yesterday"
+  if (s < 7 * 86400) return `${Math.floor(s / 86400)} days ago`
+  return when.toISOString().slice(0, 10)
+}
+
+/** "Domain", "Domain and Notifications", "Model, Domain, and Notifications". */
+export function listWords(words: string[]): string {
+  if (words.length < 3) return words.join(" and ")
+  return `${words.slice(0, -1).join(", ")}, and ${words.at(-1)}`
+}
+
+/** "Domain and Notifications are not set up", or, when the names do not fit in `room`, "5 items are not set up". */
+export function setupSentence(missing: string[], room: number): string {
+  const named = `${listWords(missing)} ${missing.length === 1 ? "is" : "are"} not set up`
+  return named.length <= room ? named : `${missing.length} ${missing.length === 1 ? "item is" : "items are"} not set up`
+}

package/src/tui/palette.tsx

@@ -15,7 +15,7 @@ export type PaletteRun =
   /** Put in the prompt to edit and send: an example request. */
   | { kind: "insert"; text: string }
   /** Something the shell does itself. */
-  | { kind: "action"; id: "refine" | "stop" | "details" | "chat" | "wide" | "panels" }
+  | { kind: "action"; id: "refine" | "stop" | "details" | "chat" | "wide" | "panels" | "shortcuts" }
 
 export type PaletteItem = { id: string; group: PaletteGroup; title: string; detail?: string; keys?: string; run: PaletteRun }
 
@@ -31,6 +31,7 @@ export function paletteItems(opts: { running: boolean; headed: boolean; detailsF
     if (!opts.chatWide) items.push({ id: "panels", group: "Action", title: "Move to the panels: plan, activity, files", keys: "shift+tab", run: { kind: "action", id: "panels" } })
   }
   if (opts.narrow) items.push({ id: "view", group: "Action", title: opts.view === "chat" ? "Show the details view" : "Back to the chat", keys: "ctrl+o", run: { kind: "action", id: opts.view === "chat" ? "details" : "chat" } })
+  items.push({ id: "shortcuts", group: "Action", title: "Keyboard shortcuts", keys: "?", run: { kind: "action", id: "shortcuts" } })
   command("features", "What ForgeQE can do here", "/features", "and what each feature still needs")
   command("auth", "Sign in to a system", "/auth", "Azure DevOps, GitHub, Jira, Confluence, TestRail, Zephyr, qTest, Xray")
   command("auth-status", "What is signed in", "/auth status")

package/src/tui/shortcuts.tsx

@@ -0,0 +1,66 @@
+import { theme } from "./theme.ts"
+
+/** Every key the shell answers to, in one panel (? on an empty prompt); esc or ? closes it. */
+export const SHORTCUTS: { group: string; keys: [string, string][] }[] = [
+  {
+    group: "Prompt",
+    keys: [
+      ["enter", "send the request"],
+      ["shift+enter, ctrl+j", "new line"],
+      ["ctrl+r", "refine the request before it is sent"],
+      ["/  @", "commands; runs, files, and work items to reference"],
+      ["tab", "complete a suggestion, or the next model profile"],
+    ],
+  },
+  {
+    group: "Find and move",
+    keys: [
+      ["ctrl+p", "search: actions, commands, profiles, examples"],
+      ["shift+tab", "move between the chat and the plan, activity, and files panels"],
+      ["ctrl+o", "chat or details, on a narrow terminal"],
+      ["alt+1 to alt+4", "a start action, or a next step"],
+    ],
+  },
+  {
+    group: "Run",
+    keys: [
+      ["esc", "stop the request (asks first)"],
+      ["ctrl+c", "close ForgeQE (asks first; twice closes)"],
+      ["drag", "copy the selected text"],
+    ],
+  },
+]
+
+export function ShortcutsPanel(props: { width: number; wide: boolean; onClose: () => void }) {
+  const boxWidth = Math.min(84, props.width - 8)
+  const keyWidth = 22
+  return (
+    <box
+      position="absolute"
+      zIndex={100}
+      border
+      borderStyle="rounded"
+      borderColor={theme.accent}
+      title=" Keyboard shortcuts "
+      titleColor={theme.accent}
+      bottomTitle=" esc close "
+      bottomTitleAlignment="right"
+      onMouseDown={props.onClose}
+      style={{ top: 2, left: Math.floor((props.width - boxWidth) / 2), width: boxWidth, flexDirection: "column", backgroundColor: theme.panel, paddingLeft: 2, paddingRight: 2, paddingTop: 1 }}
+    >
+      {SHORTCUTS.map((g) => (
+        <box key={g.group} style={{ flexDirection: "column", marginBottom: 1, flexShrink: 0 }}>
+          <text fg={theme.muted}>{g.group}</text>
+          {g.keys
+            .filter(([k]) => props.wide || k !== "shift+tab")
+            .map(([k, what]) => (
+              <text key={k}>
+                <span fg={theme.text}>{`  ${k.padEnd(keyWidth)}`}</span>
+                <span fg={theme.muted}>{what}</span>
+              </text>
+            ))}
+        </box>
+      ))}
+    </box>
+  )
+}