@capagents/forgeqe 1.0.4 → 1.0.7

package/HOW_TO_USE.md

@@ -66,6 +66,7 @@ Everything ForgeQE can do, by area. ForgeQE's agent answers "can you…?" questi
 | Release | **Requirement coverage and release readiness**: Gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories, from test cases, results, bugs, and flaky tests; can publish it to the wiki. | `release_readiness` | [docs](#requirement-coverage-and-release-readiness) |
 | Operations | **Scheduled monitoring with alerts**: Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers. | `monitor` | [docs](#9-monitoring) |
 | Operations | **Teams and email notifications**: Tells the team in Microsoft Teams channels or by email when a suite fails or passes, when a release readiness verdict is in, and when the domain evaluation falls below its gate, with the failing cases, their bugs, and links to the report and the CI build. Each channel picks its events; the agent also posts a summary to a channel when asked. | `notify` | [docs](#17-notifications) |
+| Release | **Reports you can share**: Writes up what ForgeQE's agent found, such as release status across projects, open defects, or pipeline health, as a Markdown file and an HTML page in the reports folder, with a summary in the chat and links to open them. | `write_report` | [docs](#reports-from-the-agent) |
 | Operations | **CI pipelines**: Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green. | `push_branch`, `set_ci_secret` | [docs](#8-pipelines) |
 | Systems | **Work with Azure DevOps, Jira, and Confluence**: Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, and builds Azure DevOps dashboards and wiki pages. | `query_api`, `read_confluence`, `create_ado_dashboard`, `write_ado_wiki_page` | [docs](README.md#azure-devops-jira-and-other-systems) |
 | Setup | **Setup, skills, and documentation**: Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list. | `forgeqe_setup`, `capabilities` | [docs](#2-scaffold-config) |
@@ -366,12 +367,63 @@ While a run is going, the bar under the prompt shows a spinner, the tokens used,
 
 The text is the agent's own result. Failed runs show `✗ Task failed` with the reason, and stopped runs show `■ Run stopped`. `forgeqe run` prints the same summary at the end.
 
+### Reports from the agent
+
+Ask for a report and ForgeQE's agent writes one you can share: "create a release report for all projects", "write up the open defects", "summarise this sprint's test results as a report". It gathers the facts with its tools (Azure DevOps, Jira, the runs it made), then saves the report with `write_report` as a Markdown file and an HTML page in the reports folder (`export.out_dir`, `.forgeqe/reports/` by default):
+
+```
+.forgeqe/reports/release-status-all-projects-20261009-001512/
+  report.md     # to edit, paste into a wiki, or attach
+  report.html   # to open or share; light and dark, tables scroll on a phone
+```
+
+The chat gets a short summary and a card with both paths as links, and **Open the report** appears as a next step. The report holds only what the agent read in that request. To post it, ask for it ("post the report to the release channel") once `notify.channels` is set up; the reports folder is linked when it is served (`notify.report_url`).
+
+### The screen
+
+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.
+- **Right (60%)**: a status line with who is working, for how long, and a **■ Stop** button (a running suite adds a progress bar, `██████░░░░░░ 5/8`); then **Plan** (the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running), **Activity** (every tool call, browser step, and the agents' reasoning), **Files** (each file read ◉, written ✚, or edited ✎, newest first), **Context** (how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it), and **Tokens** (total, input, output, cached; no prices, which are in reports and `forgeqe models`).
+
+On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.
+
+**Buttons.** Under the prompt: **✦ Refine** (Ctrl-R; it fills in once there is text to refine) and **⌕ Search** (Ctrl-P, the command palette); while a request runs, **■ Stop** (Esc) takes Refine's place. In the status line above the panels: **▦ Panels** (Shift-Tab) and **⤢ Wide chat**, which gives the conversation the whole width for reading a long answer; **◧ Split view**, under the prompt, brings the panels back. On a narrow terminal, **◧ Details** (Ctrl-O) and **⇄ Profile** (Tab) are under the prompt. Each is clickable.
+
+**Progress.** While a request runs, the status line above the panels shows a bar for how far the agent's plan has got (`███████░░░░░ 2/3`), or the suite's cases while a suite runs.
+
+**Replies.** The agent's answers lead with the answer, then short headed sections; lists keep their bullets in a column, so a wrapped line stays under its text instead of running back to the margin.
+
+**Moving between panels.** Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.
+
+| Panel | Keys |
+|-------|------|
+| Plan | ↑/↓ select a step, Enter puts the whole step, with why it failed, in the chat |
+| Activity | ↑/↓, PgUp/PgDn scroll; `a` all, `e` errors, `s` steps (browser steps and reasoning), `t` tools (tool calls and files); the filter buttons are clickable too |
+| Files | ↑/↓ select, Enter (or a click) opens the file |
+
+**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.
+
+**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.
+
+**`/` and `@` in the prompt.** Typing `/` lists the commands that match; typing `@` suggests references: recent runs (*last run*, then each by its folder), files in the repository by name or path (`@Login` finds `pages/Login.ts`), and, after `@` and a number such as `@1761`, the Azure DevOps work item with its title (read-only). Tab completes, ↑/↓ choose, Esc closes the list.
+
+**Refine.** Ctrl-R (or *Refine my request* in the palette) turns what you typed into a precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it **checked** ✓, what it **assumed** ~, and what is **missing** ?. Enter uses it, `e` puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.
+
+**Next steps.** When a request finishes, up to three suggestions appear above the prompt: from what it produced (*Open the report*, *Write a test for this run*, *Why did it fail?*, *Rerun the cases that failed*) and from the agent's answer, which suggests the follow-ups you are likely to want (*Write a release report*, *Show the failed CD logs*). Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first, to adjust and send.
+
 | Key | Action |
 |-----|--------|
 | Enter | Send the message or command |
-| Tab | Next LLM profile from `llms.json`; the conversation carries over to the new model |
-| Ctrl-P | Show commands |
-| Esc | Ask to stop the run: **Stop run**, **Stop and close ForgeQE**, or **Keep running** |
+| Tab | Next LLM profile from `llms.json`; the conversation carries over to the new model. While `/` or `@` suggestions show, completes the selected one |
+| Shift-Tab | Move between the chat and the Plan, Activity, and Files panels |
+| Ctrl-P | Command palette |
+| 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 |
+| 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 |
 
 In the button prompt, ←/→ or Tab move between buttons, Enter confirms, Esc cancels, and a mouse click works too. `esc stop` and `ctrl+c close` in the bar under the prompt are also clickable. **Stop and close** waits until the browser has shut down and the run's files are saved, then closes ForgeQE.
@@ -1533,6 +1585,11 @@ Start with `--debug` (or set `FORGEQE_DEBUG=1`) for more: the browser engine log
 | `/auth [system]`, `/auth logout <system>` | Sign in to a system in the browser (the token is typed unseen), forget one; `/auth` alone shows what is signed in |
 | `/clear`, `/help`, `/exit` | Clear the transcript, show help, quit |
 | Drag with the mouse | Copy the selected text |
+| Ctrl-P | Command palette: actions, commands, profiles, example requests |
+| Ctrl-R | Refine the request before sending it |
+| `/`, `@` | Suggest commands; suggest runs, files, and work items to reference |
+| Shift-Tab | Move between the chat and the Plan, Activity, and Files panels |
+| Cmd/Ctrl-click a path | Open a report, file, or web address |
 
 ---
 

package/docs/user-guide.html

@@ -286,7 +286,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <div class="area"><a class="area-name" href="#area-pull-requests"><span class="mono">Pull requests</span></a><ul class="tiles"><li><a class="tile" href="#cap-pr-review"><b>Review pull requests</b><span>Review PR 42 and focus on error handling</span></a></li><li><a class="tile" href="#cap-pr-impact"><b>Pull request impact and test selection</b><span>What does PR 42 impact?</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-api"><span class="mono">API</span></a><ul class="tiles"><li><a class="tile" href="#cap-api-testing"><b>API and contract testing</b><span>Turn the last run's API calls into tests</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-quality"><span class="mono">Quality</span></a><ul class="tiles"><li><a class="tile" href="#cap-accessibility-performance"><b>Accessibility and page performance</b><span>Is the checkout page accessible?</span></a></li><li><a class="tile" href="#cap-visual-comparison"><b>Visual comparison with baselines</b><span>What changed visually since the last run?</span></a></li></ul></div>
-<div class="area"><a class="area-name" href="#area-release"><span class="mono">Release</span></a><ul class="tiles"><li><a class="tile" href="#cap-release-readiness"><b>Requirement coverage and release readiness</b><span>Are we ready to release?</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-release"><span class="mono">Release</span></a><ul class="tiles"><li><a class="tile" href="#cap-release-readiness"><b>Requirement coverage and release readiness</b><span>Are we ready to release?</span></a></li><li><a class="tile" href="#cap-reports"><b>Reports you can share</b><span>Create a release report for all projects</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-operations"><span class="mono">Operations</span></a><ul class="tiles"><li><a class="tile" href="#cap-monitoring"><b>Scheduled monitoring with alerts</b><span>Check the login flow every 15 minutes and alert Teams</span></a></li><li><a class="tile" href="#cap-notifications"><b>Teams and email notifications</b><span>Post the results to the QA channel</span></a></li><li><a class="tile" href="#cap-pipelines"><b>CI pipelines</b><span>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-systems"><span class="mono">Systems</span></a><ul class="tiles"><li><a class="tile" href="#cap-systems"><b>Work with Azure DevOps, Jira, and Confluence</b><span>Show the open bugs in this sprint</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-setup"><span class="mono">Setup</span></a><ul class="tiles"><li><a class="tile" href="#cap-setup-help"><b>Setup, skills, and documentation</b><span>What can you do?</span></a></li></ul></div>
@@ -543,20 +543,51 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 ┃  Saved     .forgeqe/reports/20260928-172700/  run.json · workflow.yaml · trace.md · report.html
 </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>
+<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>
+</ul>
+<p>On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.</p>
+<p><strong>Buttons.</strong> Under the prompt: <strong>✦ Refine</strong> (Ctrl-R; it fills in once there is text to refine) and <strong>⌕ Search</strong> (Ctrl-P, the command palette); while a request runs, <strong>■ Stop</strong> (Esc) takes Refine's place. In the status line above the panels: <strong>▦ Panels</strong> (Shift-Tab) and <strong>⤢ Wide chat</strong>, which gives the conversation the whole width for reading a long answer; <strong>◧ Split view</strong>, under the prompt, brings the panels back. On a narrow terminal, <strong>◧ Details</strong> (Ctrl-O) and <strong>⇄ Profile</strong> (Tab) are under the prompt. Each is clickable.</p>
+<p><strong>Progress.</strong> While a request runs, the status line above the panels shows a bar for how far the agent's plan has got (<code>███████░░░░░ 2/3</code>), or the suite's cases while a suite runs.</p>
+<p><strong>Replies.</strong> The agent's answers lead with the answer, then short headed sections; lists keep their bullets in a column, so a wrapped line stays under its text instead of running back to the margin.</p>
+<p><strong>Moving between panels.</strong> Shift-Tab (or a click) moves the keys from the prompt to Plan, Activity, then Files; the focused panel's border lights up and shows its keys. Esc, or typing, goes back to the prompt.</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Panel</th><th>Keys</th></tr>
+</thead>
+<tbody>
+<tr><td>Plan</td><td>↑/↓ select a step, Enter puts the whole step, with why it failed, in the chat</td></tr>
+<tr><td>Activity</td><td>↑/↓, PgUp/PgDn scroll; <code>a</code> all, <code>e</code> errors, <code>s</code> steps (browser steps and reasoning), <code>t</code> tools (tool calls and files); the filter buttons are clickable too</td></tr>
+<tr><td>Files</td><td>↑/↓ select, Enter (or a click) opens the file</td></tr>
+</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>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 precise request before it is sent. A read-only agent checks it against this setup: what ForgeQE can do here, the systems that are set up, the project's sprints and test cases, and recent runs. It shows the refined request with what it <strong>checked</strong> ✓, what it <strong>assumed</strong> ~, and what is <strong>missing</strong> ?. Enter uses it, <code>e</code> puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item.</p>
+<p><strong>Next steps.</strong> When a request finishes, up to three suggestions appear above the prompt: from what it produced (<em>Open the report</em>, <em>Write a test for this run</em>, <em>Why did it fail?</em>, <em>Rerun the cases that failed</em>) and from the agent's answer, which suggests the follow-ups you are likely to want (<em>Write a release report</em>, <em>Show the failed CD logs</em>). Click one or press Alt-1 to Alt-3; suggestions that start work are put in the prompt first, to adjust and send.</p>
 <div class="tbl"><table>
 <thead>
 <tr><th>Key</th><th>Action</th></tr>
 </thead>
 <tbody>
 <tr><td>Enter</td><td>Send the message or command</td></tr>
-<tr><td>Tab</td><td>Next LLM profile from <code>llms.json</code>; the conversation carries over to the new model</td></tr>
-<tr><td>Ctrl-P</td><td>Show commands</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></td></tr>
+<tr><td>Tab</td><td>Next LLM profile from <code>llms.json</code>; the conversation carries over to the new model. While <code>/</code> or <code>@</code> suggestions show, completes the selected one</td></tr>
+<tr><td>Shift-Tab</td><td>Move between the chat and the Plan, Activity, and Files panels</td></tr>
+<tr><td>Ctrl-P</td><td>Command palette</td></tr>
+<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>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>
 </table></div>
 <p>In the button prompt, ←/→ or Tab move between buttons, Enter confirms, Esc cancels, and a mouse click works too. <code>esc stop</code> and <code>ctrl+c close</code> in the bar under the prompt are also clickable. <strong>Stop and close</strong> waits until the browser has shut down and the run's files are saved, then closes ForgeQE.</p>
-</div>
+</div></section>
 </section>
 <section class="doc" id="doc-how_to_use-4-without-the-shell">
 <h3>Without the shell</h3>
@@ -1531,6 +1562,28 @@ forgeqe visual approve --page /home  # make this run's /home the baseline (asks
 </section>
 </div>
 </article>
+<article class="spec feat" id="cap-reports">
+<div class="hd"><span class="mono">Release</span><h3>Reports you can share</h3></div>
+<p class="ds">Writes up what ForgeQE's agent found, such as release status across projects, open defects, or pipeline health, as a Markdown file and an HTML page in the reports folder, with a summary in the chat and links to open them.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Create a release report for all projects</li><li>Write up the open defects as a report I can share</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>A live model profile in llms.json (an API key or Microsoft Entra ID sign-in)</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>The report holds what the agent read with its tools in this request; it does not invent figures, and it does not publish the page anywhere unless the reports folder is served (notify.report_url).</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>write_report</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-reports-from-the-agent">
+<h4>Reports from the agent</h4>
+<div class="prose"><p>Ask for a report and ForgeQE's agent writes one you can share: &quot;create a release report for all projects&quot;, &quot;write up the open defects&quot;, &quot;summarise this sprint's test results as a report&quot;. It gathers the facts with its tools (Azure DevOps, Jira, the runs it made), then saves the report with <code>write_report</code> as a Markdown file and an HTML page in the reports folder (<code>export.out_dir</code>, <code>.forgeqe/reports/</code> by default):</p>
+<pre><code>.forgeqe/reports/release-status-all-projects-20261009-001512/
+  report.md     # to edit, paste into a wiki, or attach
+  report.html   # to open or share; light and dark, tables scroll on a phone
+</code></pre>
+<p>The chat gets a short summary and a card with both paths as links, and <strong>Open the report</strong> appears as a next step. The report holds only what the agent read in that request. To post it, ask for it (&quot;post the report to the release channel&quot;) once <code>notify.channels</code> is set up; the reports folder is linked when it is served (<code>notify.report_url</code>).</p>
+</div>
+</section>
+</div>
+</article>
 </section>
 <section class="chapter" id="area-operations" aria-labelledby="area-operations-h">
 <header class="chead"><span class="mono">11</span><h2 id="area-operations-h">Operations</h2><p>Monitoring and CI pipelines</p></header>
@@ -2024,6 +2077,11 @@ agents: [browser]
 <tr><td><code>/auth [system]</code>, <code>/auth logout &lt;system&gt;</code></td><td>Sign in to a system in the browser (the token is typed unseen), forget one; <code>/auth</code> alone shows what is signed in</td></tr>
 <tr><td><code>/clear</code>, <code>/help</code>, <code>/exit</code></td><td>Clear the transcript, show help, quit</td></tr>
 <tr><td>Drag with the mouse</td><td>Copy the selected text</td></tr>
+<tr><td>Ctrl-P</td><td>Command palette: actions, commands, profiles, example requests</td></tr>
+<tr><td>Ctrl-R</td><td>Refine the request before sending it</td></tr>
+<tr><td><code>/</code>, <code>@</code></td><td>Suggest commands; suggest runs, files, and work items to reference</td></tr>
+<tr><td>Shift-Tab</td><td>Move between the chat and the Plan, Activity, and Files panels</td></tr>
+<tr><td>Cmd/Ctrl-click a path</td><td>Open a report, file, or web address</td></tr>
 </tbody>
 </table></div>
 <hr />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "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/prompts/README.md

@@ -16,6 +16,7 @@ project; leave it as it is to keep getting ForgeQE's improvements when you updat
 | api-scenarios.md | Plans API scenarios from test cases or plain English |
 | explore-charters.md | Plans exploratory charters for a story |
 | eval-judge.md | Scores the agent's test cases in `forgeqe eval domain` |
+| refine.md | Refine (ctrl+r) in the shell: makes what you typed precise, checked against what ForgeQE knows |
 | skill-rule.md | How agents use skills (included in most prompts) |
 | domain-rule.md | How agents apply the product's industry risks and regulations, declared or worked out (included in every agent that analyses requirements or designs, writes, reviews, or heals tests) |
 | browser-*.md | The browser agent: error recovery, when a goal counts as done, recording checks, clicking so runs become tests, step verdicts for test cases, picking skills |

package/prompts/brain.md

@@ -163,4 +163,7 @@ Rules:
 - Never ask for an API token, API key, or password for Azure DevOps, GitHub, Jira, Confluence, TestRail, Zephyr, qTest, Xray, or a model provider in the chat. When one of them is not set up, or rejects the credentials (401, 403, "needs <NAME> in the environment"), tell the user to type /auth <system> in the shell (or run forgeqe auth login <system> in a terminal): it signs in through the browser and saves the token, and you get it on the next message. /auth <ENV_NAME> saves any other secret the same way. Website logins for browser runs are different: those go through the logins tool.
 - Never push except with push_branch, never to the default branch, and never force.
 - Stay inside the working directory, except to read ForgeQE's run and memory folders.
-- Replies are shown as markdown: use short lists, bold, and links where they help, and a table only for a few short columns. Keep replies short and concrete; test cases, tests, and reviews you were asked for are given in full, and only your own commentary is kept short. End every turn with the structured answer: reply (what you did and found, or your question) and outcome.
+- Replies are shown as markdown in a narrow chat pane, so write for scanning: one or two plain sentences with the answer first, then a short `##` heading per group if there is more than one, bullets of one line each, and bold only for the one word or figure that matters in a line (a status, a count), never whole sentences. Use a table only for two or three short columns. Keep replies short and concrete; test cases, tests, and reviews you were asked for are given in full, and only your own commentary is kept short.
+- When the user asks for a report, a write-up, or a summary to share ("create a release report", "write up the open defects"), gather the facts with your tools, then save it with write_report and reply with three to five lines of summary; the shell shows the report's paths as links, so do not repeat them. Never only paste a long report into the reply.
+- Do not end a reply with "If you want, I can…" options: put up to three follow-ups the user is likely to want next in the structured answer's next (a short label, and the request as the user would type it). They are shown as buttons.
+- End every turn with the structured answer: reply (what you did and found, or your question), outcome, and next.

package/prompts/refine.md

@@ -0,0 +1,17 @@
+---
+name: refine
+description: "Turns what the user typed into a precise request for ForgeQE's agent, checked against what ForgeQE knows."
+used_by: "the shell's Refine (ctrl+r)"
+---
+You refine a request the user typed for ForgeQE, a test automation assistant, before it is sent to ForgeQE's agent. You do not carry the request out, and you do not change anything.
+
+Make it a request the agent can act on without guessing:
+- Keep the user's intent and scope exactly. Do not add work they did not ask for, and do not drop anything they did.
+- Name things the way ForgeQE knows them: the system and project ("Azure DevOps project QI-Payments"), ids ("test plan 412, suite 77", "story 1761", "SHOP-12"), files and folders, and the profile. Use "This session" and the capabilities tool to know what ForgeQE can do, but describe the action in plain words ("run the test cases", "write a Playwright test"): never name ForgeQE's tools or capability ids.
+- Resolve references from the session and the conversation ("the last run", "that story", "the payments plan") into what they point to, but only when exactly one thing fits.
+- Check what you can with your read-only tools: that a work item, test plan, suite, or run exists, what it is called, how many cases it has. Mark each fact you state as checked or assumed.
+- Never invent an id, a URL, a project, or a file. What you cannot resolve or check goes in missing, as a short question for the user.
+- Keep the user's settings when they give them (browsers at once, headed, whether results go back), and add none they did not.
+- Write the refined request as the user would say it, in one to four sentences, in their language.
+
+Finish with the structured result: refined (the request), grounded (each fact you state, and whether you checked it), assumed (what you took to be meant, in a few words each), and missing (questions, if any).

package/src/brain/index.ts

@@ -8,7 +8,7 @@ import type { AppConfig } from "../config.ts"
 import { externalMcp, externalNotes, type ExternalPlan } from "../mcp/external.ts"
 import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
 import { TOOLS, environmentNotes, type ToolContext } from "../mcp/tools.ts"
-import { brainPrompt, BRAIN_SCHEMA, type BrainReport } from "./prompt.ts"
+import { brainPrompt, BRAIN_SCHEMA, cleanFollowUps, type BrainReport, type FollowUp } from "./prompt.ts"
 import { redactSecrets } from "../sessionLogins.ts"
 import { logEvent } from "../sessionLog.ts"
 import { loadSkills } from "../skills/registry.ts"
@@ -16,7 +16,7 @@ import { domainNotes } from "../domain.ts"
 
 export const BRAIN_AGENT = "forgeqe"
 
-export type BrainAnswer = { reply: string; outcome: "done" | "failed" | "needs_input" | "stopped"; error?: string }
+export type BrainAnswer = { reply: string; outcome: "done" | "failed" | "needs_input" | "stopped"; error?: string; next?: FollowUp[] }
 
 export type Brain = {
   model: string
@@ -173,7 +173,8 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
       if (stopped || out.error === "stopped" || opts.signal?.aborted) return { reply: "", outcome: "stopped" }
       const reply = out.report?.reply?.trim() || out.text.trim()
       if (out.error && !out.report) return { reply, outcome: "failed", error: out.error }
-      return { reply, outcome: out.report?.outcome || (out.error ? "failed" : "done"), error: out.error }
+      const next = cleanFollowUps(out.report?.next)
+      return { reply, outcome: out.report?.outcome || (out.error ? "failed" : "done"), error: out.error, ...(next.length ? { next } : {}) }
     },
     abort: () => {
       stopped = true

package/src/brain/prompt.ts

@@ -6,14 +6,46 @@ export const brainPrompt = () => prompt("brain")
 export const BRAIN_SCHEMA = {
   type: "object",
   properties: {
-    reply: { type: "string", description: "What you did and found, or the question you need answered. Plain text, short." },
+    reply: { type: "string", description: "What you did and found, or the question you need answered: Markdown, answer first, short lines." },
     outcome: {
       type: "string",
       enum: ["done", "failed", "needs_input"],
       description: "done: the request was carried out and everything checked passed. failed: a run, test, or pipeline failed or could not be done. needs_input: you asked the user something.",
     },
+    next: {
+      type: "array",
+      maxItems: 3,
+      description: "Up to three follow-ups the user is likely to want next, shown as buttons; empty when there is no clear next step.",
+      items: {
+        type: "object",
+        properties: {
+          label: { type: "string", description: "Two to five words, e.g. Write a release report" },
+          request: { type: "string", description: "The request as the user would type it, complete on its own" },
+        },
+        required: ["label", "request"],
+      },
+    },
   },
   required: ["reply", "outcome"],
 } as const
 
-export type BrainReport = { reply?: string; outcome?: "done" | "failed" | "needs_input" }
+/** A follow-up the agent suggests: a button label, and the request it puts in the prompt. */
+export type FollowUp = { label: string; request: string }
+
+export type BrainReport = { reply?: string; outcome?: "done" | "failed" | "needs_input"; next?: FollowUp[] }
+
+/** The follow-ups worth showing: well-formed, short enough for a button, at most three, no repeats. */
+export function cleanFollowUps(next: unknown): FollowUp[] {
+  if (!Array.isArray(next)) return []
+  const seen = new Set<string>()
+  const out: FollowUp[] = []
+  for (const n of next) {
+    const label = typeof n?.label === "string" ? n.label.replace(/\s+/g, " ").trim() : ""
+    const request = typeof n?.request === "string" ? n.request.trim() : ""
+    if (!label || !request || label.length > 40 || seen.has(label.toLowerCase())) continue
+    seen.add(label.toLowerCase())
+    out.push({ label, request })
+    if (out.length === 3) break
+  }
+  return out
+}

package/src/capabilities/registry.ts

@@ -290,6 +290,18 @@ export const CAPABILITIES: Capability[] = [
     limits: ["Automatic notifications come from runs nobody is watching (forgeqe suite, forgeqe run, pipelines, the MCP server), not from the interactive shell, where the agent posts only when asked."],
     docs: [{ doc: "HOW_TO_USE.md", heading: "17. Notifications" }],
   },
+  {
+    id: "reports",
+    area: "Release",
+    title: "Reports you can share",
+    summary:
+      "Writes up what ForgeQE's agent found, such as release status across projects, open defects, or pipeline health, as a Markdown file and an HTML page in the reports folder, with a summary in the chat and links to open them.",
+    tools: ["write_report"],
+    examples: ["Create a release report for all projects", "Write up the open defects as a report I can share"],
+    requires: [{ kind: "live_model" }],
+    limits: ["The report holds what the agent read with its tools in this request; it does not invent figures, and it does not publish the page anywhere unless the reports folder is served (notify.report_url)."],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Reports from the agent" }],
+  },
   {
     id: "pipelines",
     area: "Operations",

package/src/capabilities/status.ts

@@ -56,7 +56,8 @@ export type CapabilityStatus = {
   inputs: string[]
 }
 
-function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "requirement" | "optional"> | null {
+/** What `r` is missing in this setup, and how to fix it; null when it is met. */
+export function requirementGap(r: Requirement, cfg: AppConfig, probes: Probes = MACHINE): Omit<Gap, "requirement" | "optional"> | null {
   switch (r.kind) {
     case "live_model":
       return cfg.llm.provider === "none" || cfg.llm.provider === "mock"
@@ -89,7 +90,7 @@ function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "require
     case "input":
       return null
     case "either": {
-      const gaps = r.of.map((alt) => gap(alt, cfg, probes))
+      const gaps = r.of.map((alt) => requirementGap(alt, cfg, probes))
       if (gaps.some((g) => !g)) return null
       return { missing: gaps.map((g) => g!.missing).join(", or "), fix: gaps.map((g) => g!.fix).join("; or ") }
     }
@@ -99,7 +100,7 @@ function gap(r: Requirement, cfg: AppConfig, probes: Probes): Omit<Gap, "require
 export function capabilityStatus(c: Capability, cfg: AppConfig, probes: Probes = MACHINE): CapabilityStatus {
   const gaps: Gap[] = []
   for (const r of c.requires) {
-    const g = gap(r, cfg, probes)
+    const g = requirementGap(r, cfg, probes)
     if (g) gaps.push({ requirement: r, optional: Boolean("optional" in r && r.optional), ...g })
   }
   const state = gaps.some((g) => !g.optional) ? "needs_setup" : gaps.length ? "partial" : "ready"

package/src/mcp/reporttools.ts

@@ -0,0 +1,101 @@
+import { mkdirSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { McpTool } from "./tools.ts"
+
+/**
+ * Reports the agent writes from what it found (release status, open defects, pipeline health): a Markdown file to
+ * edit or paste, and the same report as a page to open or share. The chat gets the summary and the links.
+ */
+
+/** "Release status: all projects" → "release-status-all-projects". */
+export function reportSlug(title: string): string {
+  return (
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .slice(0, 40)
+      .replace(/^-+|-+$/g, "") || "report"
+  )
+}
+
+const escapeHtml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+
+/** The report as a page: the Markdown rendered, with raw HTML in it shown as text so a report can never run script. */
+export function reportHtml(title: string, markdown: string, written: Date): string {
+  const safe = markdown.replace(/<(?=[A-Za-z/!?])/g, "&lt;")
+  const body = Bun.markdown.html(safe)
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>
+:root { --bg: #ffffff; --text: #1f2328; --muted: #59636e; --border: #d1d9e0; --accent: #0969da; --panel: #f6f8fa; }
+@media (prefers-color-scheme: dark) { :root { --bg: #0d1117; --text: #e6edf3; --muted: #8b949e; --border: #30363d; --accent: #4ea1ff; --panel: #161b22; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.6 -apple-system, "Segoe UI", Roboto, sans-serif; }
+main { max-width: 960px; margin: 0 auto; padding: 32px 16px 64px; }
+header { border-bottom: 1px solid var(--border); padding-bottom: 12px; margin-bottom: 24px; }
+header p { margin: 4px 0 0; color: var(--muted); font-size: 13px; }
+h1 { font-size: 28px; line-height: 1.25; margin: 0; }
+h2 { font-size: 20px; margin: 32px 0 8px; padding-bottom: 4px; border-bottom: 1px solid var(--border); }
+h3 { font-size: 16px; margin: 24px 0 8px; }
+a { color: var(--accent); }
+code { background: var(--panel); border-radius: 4px; padding: 1px 4px; font-size: 13px; }
+pre { background: var(--panel); border: 1px solid var(--border); border-radius: 6px; padding: 12px; overflow-x: auto; }
+pre code { background: none; padding: 0; }
+table { border-collapse: collapse; width: 100%; margin: 12px 0; display: block; overflow-x: auto; }
+th, td { border: 1px solid var(--border); padding: 6px 10px; text-align: left; vertical-align: top; }
+th { background: var(--panel); }
+blockquote { margin: 12px 0; padding: 4px 12px; border-left: 4px solid var(--border); color: var(--muted); }
+li { margin: 2px 0; }
+</style>
+</head>
+<body>
+<main>
+<header>
+<h1>${escapeHtml(title)}</h1>
+<p>Written by ForgeQE on ${escapeHtml(written.toLocaleString())}</p>
+</header>
+${body}
+</main>
+</body>
+</html>
+`
+}
+
+export const REPORT_TOOLS: McpTool[] = [
+  {
+    name: "write_report",
+    description:
+      'Save a report the user asks for ("create a release report", "write up the open defects", "give me a report I can share") as a Markdown file and an HTML page in the reports folder. Gather the facts with your other tools first, then pass the whole report as Markdown: a one-paragraph summary first, then ## sections, tables for per-item status (one row per project, case, or build), and links to builds, work items, and pull requests. Do not invent data you did not read. The user is shown the report paths as links, so reply with three to five lines of summary only: do not repeat the paths or paste the report.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        title: { type: "string", description: "The report's title, e.g. Release status: all projects, 9 October 2026" },
+        markdown: { type: "string", description: "The report body in Markdown, without the title (it is added as the heading)" },
+      },
+      required: ["title", "markdown"],
+    },
+    async run(args, ctx) {
+      const title = String(args.title || "Report").trim()
+      const markdown = String(args.markdown || "").trim()
+      if (!markdown) throw new Error("The report is empty: pass its body as markdown.")
+      const written = new Date()
+      const stamp = written.toISOString().replace(/[-:]/g, "").replace("T", "-").slice(0, 15)
+      // Beside the run reports, so the shell links it and outDir publishing (notify.report_url) serves it too.
+      const dir = path.resolve(ctx.config.export.outDir, `${reportSlug(title)}-${stamp}`)
+      mkdirSync(dir, { recursive: true })
+      const md = path.join(dir, "report.md")
+      const html = path.join(dir, "report.html")
+      writeFileSync(md, `# ${title}\n\n${markdown}\n`)
+      writeFileSync(html, reportHtml(title, markdown, written))
+      const show = (p: string) => path.relative(process.cwd(), p) || p
+      ctx.emit?.({ type: "report", title, html, markdown: md })
+      ctx.emit?.({ type: "card", card: { status: "ok", title: `Report: ${title}`, body: [`Page      ${show(html)}`, `Markdown  ${show(md)}`] } })
+      return { html: show(html), markdown: show(md) }
+    },
+  },
+]

package/src/mcp/tools.ts

@@ -29,6 +29,7 @@ import { EXPLORE_TOOLS } from "./exploretools.ts"
 import { QUALITY_TOOLS } from "./qualitytools.ts"
 import { CAPABILITY_TOOLS } from "./captools.ts"
 import { NOTIFY_TOOLS } from "./notifytools.ts"
+import { REPORT_TOOLS } from "./reporttools.ts"
 import { capabilityIndex } from "../capabilities/render.ts"
 import { domainNotes } from "../domain.ts"
 import { readNetwork } from "../api/traffic.ts"
@@ -95,6 +96,8 @@ export type ToolEvent =
   | { type: "code-done"; result?: CodeResult; error?: string; ms: number }
   /** A tool's result to show as a panel (a test written, tests healed, a monitoring round). */
   | { type: "card"; card: Card }
+  /** write_report saved a report: its page and its Markdown. */
+  | { type: "report"; title: string; html: string; markdown: string }
 
 export type ToolContext = {
   config: AppConfig
@@ -722,6 +725,7 @@ export const TOOLS: McpTool[] = [
   ...QUALITY_TOOLS,
   ...CAPABILITY_TOOLS,
   ...NOTIFY_TOOLS,
+  ...REPORT_TOOLS,
 ]
 
 /** The setup the agent should know about: where it works, which systems are configured, and the defaults. */