@capagents/forgeqe 1.0.9 → 1.1.1

package/HOW_TO_USE.md

@@ -405,24 +405,53 @@ The chat gets a short summary and a card with both paths as links, and **Open th
 - 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.
+- In a folder without `forgeqe.yaml`, or without a live model, the line under the logo says so and **Get started** takes its place: **Set up ForgeQE in this folder** (runs `/init`), **Add a model**, and **Sign in to Azure DevOps or Jira** (runs `/auth`). Start ForgeQE in your test project's folder to work with its settings.
 - **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:
+**The conversation.** Once you send a request, the screen is one column that reads top to bottom, as in Claude Code:
 
-- **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`).
+```
+> get the current release details from all projects
+
+⏺ Azure DevOps · pipelines build (action list, project QI-Payments, top 1)
+⏺ ForgeQE · query_api (azure_devops, vsrm.dev.azure.com/…/_apis/release/releases)
+  ⎿ No classic releases came back, so I will confirm on the Releases page.
+
+⏺ Browser: Open Autothon › Pipelines › Releases
+  ⎿ Step 1 · Open the Autothon project
+    ✓ navigate https://dev.azure.com/devcgazuredevops/Autothon
 
-On a narrower terminal the chat fills the screen, and Ctrl-O switches between the chat and the same panels.
+⏺ No classic releases exist in any of the seven projects.
+  …
+
+⠹ Thinking… (24s · 57.4K tokens · esc to interrupt)
+╭──────────────────────────────────────────────────────────╮
+│ > Ask ForgeQE… (/ for commands, @ to reference a run…)   │
+╰──────────────────────────────────────────────────────────╯
+ ✦ Refine ctrl+r   ⌕ Search ctrl+p   ▦ Panels ctrl+o              ctrl+c close
+ ~/playwright-csharp-pom-framework          azure/gpt-5.4  ·  57.4K tokens  ·  ForgeQE
+```
 
-**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.
+- `>` is what you asked. `⏺` starts each reply, tool call, browser run, test case, and result; calls in a row sit together, with the arguments dimmed. What came of a call is indented under it after `⎿`: the agent's notes, each browser step and its actions (✓ or ✗), and a result's details.
+- While a request runs, one line above the input says what is happening, for how long, and with how many tokens. The footer is the status line: the model and what the session used. Prices are not shown in the conversation; reports and `forgeqe models` have them.
+- A result that made nothing (a run that only looked something up) adds no card.
 
-**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.
+**The panels.** **▦ Panels** (Ctrl-O) opens the session, plan, activity, files, context, and tokens panels beside the conversation on a terminal 120 columns wide or more, or in its place on a narrower one; Ctrl-O again, or **✕ Close**, closes them:
+
+- the status line, with who is working, for how long, a progress bar for the plan or a suite's cases, and **■ Stop**;
+- **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;
+- **Tokens**: total, input, output, cached.
+
+**Buttons.** Under the input: **✦ Refine** (Ctrl-R; it fills in once there is text to refine), **⌕ Search** (Ctrl-P, the command palette), and **▦ Panels** (Ctrl-O); while a request runs, **■ Stop** (Esc) takes Refine's place. With the panels open, **▦ Focus panels** (Shift-Tab) and **✕ Close** (Ctrl-O) are in their status line. On a narrow terminal, **◧ Details** (Ctrl-O) and **⇄ Profile** (Tab) are under the input. Each is clickable.
 
 **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.
+**Moving between panels.** With the panels open, 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 |
 |-------|------|
@@ -438,23 +467,24 @@ On a narrower terminal the chat fills the screen, and Ctrl-O switches between th
 
 **`/` 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 task specification for ForgeQE's agent, in ASD-STE100 Simplified Technical English, before it is sent:
+**Refine.** Ctrl-R (or *Refine my request* in the palette) turns what you typed into a task specification for ForgeQE's agent, laid out as a system prompt and written in ASD-STE100 Simplified Technical English, before it is sent. It has these parts, in this order: **Role** (who the agent acts as), **Objective** (one instruction), **Context** (the facts, with names), **Steps** (only when they add something), **Rules** (your limits and the setup's), **Output format** (what comes back and how it is laid out), and **Summary** (what you get, in one sentence, read last):
 
 ```
-Goal: Check the Azure DevOps QI-Payments pipelines and make a shareable report for the manager.
+Role: A release analyst who reads Azure DevOps deployments.
+
+Objective: Get what is deployed now in each environment of each Azure DevOps project.
 
 Context:
-- Project: Azure DevOps project QI-Payments.
-- Pipeline: build definition 32, QI-Payments-CD.
-- Latest checked CD build: build 1021, failed, finished 2026-09-21.
+- System: Azure DevOps organization devcgazuredevops.
+- Projects: Autothon, CQube.AI, BlackBox_AI, QI-Payments, QI-MobileBanking, Atlas.Ai, QI-Claims.
 
-Steps:
-1. Review the recent runs of QI-Payments-CI and QI-Payments-CD.
-2. Make a shareable report with a short manager summary.
+Output format: One section for each project, with a line for each environment: the deployed build, its date, and its status.
 
-Result: A shareable report file with a short summary for the manager.
+Summary: Show the deployed build in each environment, and why each deployment failed.
 ```
 
+Refine is one model session of its own, separate from the conversation: a few model steps (usually two) and read-only tool calls, typically 15K–25K tokens and 20–30 seconds. The panel title shows what it cost and how much of the request keeps the ASD-STE100 rules (*✦ Refined request · STE 100% · 20.8K tokens · 21s*), and its tokens count in the session total in the footer.
+
 A read-only agent writes it. It starts knowing every capability and whether it works in this setup, and the domain; it checks names and ids in the systems that are set up (work items, test plans, pipelines, sprints, recent runs). The panel shows the request with what it **checked** ✓, what it **assumed** ~, and what is **missing** ? (for example "Which story? Give the work item id"); a capability that is not set up shows as missing too. Enter sends it, `e` puts it in the prompt to edit, Esc keeps yours. Refine never runs anything, writes files, or changes a work item; it never invents an id, URL, project, or file.
 
 **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.
@@ -466,7 +496,7 @@ A read-only agent writes it. It starts knowing every capability and whether it w
 | 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 |
+| Ctrl-O | Open or close the panels (beside the conversation, or in its place on a narrow terminal) |
 | 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 |
@@ -1366,7 +1396,7 @@ You can also ask ForgeQE's agent. In the shell, "check the smoke cases once" run
 
 When ForgeQE's agent starts, it connects to an MCP server for each system set up under `sources:`. The server settings come from the same place as everything else: the organization and project, the site URL, and the names of the environment variables that hold the tokens. You don't write MCP config for these.
 
-**Azure DevOps.** Microsoft's [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp), run as `npx -y @azure-devops/mcp <org> -a pat -d all`, with every tool group the server has. The organization comes from `org_url` (`https://dev.azure.com/acme` or `https://acme.visualstudio.com`). ForgeQE passes the PAT from `token_env` (default `ADO_PAT`) the way the server wants it; without a PAT it uses your `az login` session. Its tools are `azure_devops_*`: work items and comments, queries, backlogs, iterations, test plans, pipelines and their logs, repos, branches, pull requests, wiki pages (read, create, and update), search across code, wikis, and work items, and Advanced Security alerts. `mcp_domains` limits them to some groups. It needs Node.js. Azure DevOps Server (on-premises) isn't supported by Microsoft's server, so it uses ForgeQE's API.
+**Azure DevOps.** Microsoft's [Azure DevOps MCP server](https://github.com/microsoft/azure-devops-mcp), run as `npx -y @azure-devops/mcp <org> -a pat -d core work work-items pipelines`: projects and teams, iterations and boards, work items, and pipelines. Every tool's definition goes to the model with each request, so ForgeQE loads only these groups (about 19 tools, roughly 9.5K tokens, against about 18K for all of them); its own tools cover test plans, wiki pages, dashboards, and pull request reviews, and `query_api` reads anything else, such as classic releases. The organization comes from `org_url` (`https://dev.azure.com/acme` or `https://acme.visualstudio.com`). ForgeQE passes the PAT from `token_env` (default `ADO_PAT`) the way the server wants it; without a PAT it uses your `az login` session. Its tools are `azure_devops_*`. `mcp_domains` adds groups: `test-plans`, `repositories` (repos, branches, pull requests), `wiki`, `search` (code, wikis, and work items), `advanced-security`, or `[all]`. It needs Node.js. Azure DevOps Server (on-premises) isn't supported by Microsoft's server, so it uses ForgeQE's API.
 
 ```yaml
 sources:
@@ -1375,7 +1405,7 @@ sources:
     # project: Shop                       # optional: limit ForgeQE's own API calls to one project
     token_env: ADO_PAT
     mcp: true                     # false: API only
-    mcp_domains: [core, work-items, test-plans, pipelines]   # optional: fewer tool groups
+    mcp_domains: [core, work, work-items, pipelines, repositories]   # optional: the default four, plus repos
 ```
 
 Microsoft's server has no dashboard tools and can't save queries. Ask for a dashboard ("create a dashboard in QI-Payments with all defects in every state and the current sprint's stories") and ForgeQE's own `create_ado_dashboard` tool does it through the REST API with `ADO_PAT`: it runs each WIQL query once to check it, saves it as a shared query under `Shared Queries/ForgeQE` (updating one of the same name), and creates a team or project dashboard with a work item list or count tile per query, plus optional markdown text. The PAT needs Work Items (read and write) and permission to edit dashboards. Chart widgets are not made through the API; for those the agent uses the browser, which has to be signed in to `dev.azure.com` (`forgeqe login <name>` with a login for it under `logins:`).
@@ -1628,6 +1658,7 @@ Start with `--debug` (or set `FORGEQE_DEBUG=1`) for more: the browser engine log
 | `/profile <name>` or Tab | Switch the model profile |
 | `/logs [shots]` | Save this session's log and runs in one archive to share |
 | `/features` | What ForgeQE can do here: ✓ ready, ◐ works with some parts to set up, ○ needs setup, with the fix (works without a model) |
+| `/init` | Set ForgeQE up in this folder, as `forgeqe init` does: `forgeqe.yaml`, `llms.json`, and editable prompts, skills, and knowledge; the session reads them at once |
 | `/skills [name]` | The skills each agent can use, or one skill's instructions |
 | `/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 |

package/docs/user-guide.html

@@ -565,20 +565,49 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 <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>In a folder without <code>forgeqe.yaml</code>, or without a live model, the line under the logo says so and <strong>Get started</strong> takes its place: <strong>Set up ForgeQE in this folder</strong> (runs <code>/init</code>), <strong>Add a model</strong>, and <strong>Sign in to Azure DevOps or Jira</strong> (runs <code>/auth</code>). Start ForgeQE in your test project's folder to work with its settings.</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>
+<p><strong>The conversation.</strong> Once you send a request, the screen is one column that reads top to bottom, as in Claude Code:</p>
+<pre><code>&gt; get the current release details from all projects
+
+⏺ Azure DevOps · pipelines build (action list, project QI-Payments, top 1)
+⏺ ForgeQE · query_api (azure_devops, vsrm.dev.azure.com/…/_apis/release/releases)
+  ⎿ No classic releases came back, so I will confirm on the Releases page.
+
+⏺ Browser: Open Autothon › Pipelines › Releases
+  ⎿ Step 1 · Open the Autothon project
+    ✓ navigate https://dev.azure.com/devcgazuredevops/Autothon
+
+⏺ No classic releases exist in any of the seven projects.
+  …
+
+⠹ Thinking… (24s · 57.4K tokens · esc to interrupt)
+╭──────────────────────────────────────────────────────────╮
+│ &gt; Ask ForgeQE… (/ for commands, @ to reference a run…)   │
+╰──────────────────────────────────────────────────────────╯
+ ✦ Refine ctrl+r   ⌕ Search ctrl+p   ▦ Panels ctrl+o              ctrl+c close
+ ~/playwright-csharp-pom-framework          azure/gpt-5.4  ·  57.4K tokens  ·  ForgeQE
+</code></pre>
+<ul>
+<li><code>&gt;</code> is what you asked. <code>⏺</code> starts each reply, tool call, browser run, test case, and result; calls in a row sit together, with the arguments dimmed. What came of a call is indented under it after <code>⎿</code>: the agent's notes, each browser step and its actions (✓ or ✗), and a result's details.</li>
+<li>While a request runs, one line above the input says what is happening, for how long, and with how many tokens. The footer is the status line: the model and what the session used. Prices are not shown in the conversation; reports and <code>forgeqe models</code> have them.</li>
+<li>A result that made nothing (a run that only looked something up) adds no card.</li>
+</ul>
+<p><strong>The panels.</strong> <strong>▦ Panels</strong> (Ctrl-O) opens the session, plan, activity, files, context, and tokens panels beside the conversation on a terminal 120 columns wide or more, or in its place on a narrower one; Ctrl-O again, or <strong>✕ Close</strong>, closes them:</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>
+<li>the status line, with who is working, for how long, a progress bar for the plan or a suite's cases, and <strong>■ Stop</strong>;</li>
+<li><strong>Plan</strong>: the agent's to-do list, then each browser step or suite case with ✓, ✗ and why, ◐ running;</li>
+<li><strong>Activity</strong>: every tool call, browser step, and the agents' reasoning;</li>
+<li><strong>Files</strong>: each file read ◉, written ✚, or edited ✎, newest first;</li>
+<li><strong>Context</strong>: how full the model's context window is, and the skills, product knowledge, domain, and MCP servers in it;</li>
+<li><strong>Tokens</strong>: total, input, output, cached.</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>Buttons.</strong> Under the input: <strong>✦ Refine</strong> (Ctrl-R; it fills in once there is text to refine), <strong>⌕ Search</strong> (Ctrl-P, the command palette), and <strong>▦ Panels</strong> (Ctrl-O); while a request runs, <strong>■ Stop</strong> (Esc) takes Refine's place. With the panels open, <strong>▦ Focus panels</strong> (Shift-Tab) and <strong>✕ Close</strong> (Ctrl-O) are in their status line. On a narrow terminal, <strong>◧ Details</strong> (Ctrl-O) and <strong>⇄ Profile</strong> (Tab) are under the input. Each is clickable.</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>
+<p><strong>Moving between panels.</strong> With the panels open, 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>
@@ -593,20 +622,20 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 <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>
-<pre><code>Goal: Check the Azure DevOps QI-Payments pipelines and make a shareable report for the manager.
+<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, laid out as a system prompt and written in ASD-STE100 Simplified Technical English, before it is sent. It has these parts, in this order: <strong>Role</strong> (who the agent acts as), <strong>Objective</strong> (one instruction), <strong>Context</strong> (the facts, with names), <strong>Steps</strong> (only when they add something), <strong>Rules</strong> (your limits and the setup's), <strong>Output format</strong> (what comes back and how it is laid out), and <strong>Summary</strong> (what you get, in one sentence, read last):</p>
+<pre><code>Role: A release analyst who reads Azure DevOps deployments.
+
+Objective: Get what is deployed now in each environment of each Azure DevOps project.
 
 Context:
-- Project: Azure DevOps project QI-Payments.
-- Pipeline: build definition 32, QI-Payments-CD.
-- Latest checked CD build: build 1021, failed, finished 2026-09-21.
+- System: Azure DevOps organization devcgazuredevops.
+- Projects: Autothon, CQube.AI, BlackBox_AI, QI-Payments, QI-MobileBanking, Atlas.Ai, QI-Claims.
 
-Steps:
-1. Review the recent runs of QI-Payments-CI and QI-Payments-CD.
-2. Make a shareable report with a short manager summary.
+Output format: One section for each project, with a line for each environment: the deployed build, its date, and its status.
 
-Result: A shareable report file with a short summary for the manager.
+Summary: Show the deployed build in each environment, and why each deployment failed.
 </code></pre>
+<p>Refine is one model session of its own, separate from the conversation: a few model steps (usually two) and read-only tool calls, typically 15K–25K tokens and 20–30 seconds. The panel title shows what it cost and how much of the request keeps the ASD-STE100 rules (<em>✦ Refined request · STE 100% · 20.8K tokens · 21s</em>), and its tokens count in the session total in the footer.</p>
 <p>A read-only agent writes it. It starts knowing every capability and whether it works in this setup, and the domain; it checks names and ids in the systems that are set up (work items, test plans, pipelines, sprints, recent runs). The panel shows the request with what it <strong>checked</strong> ✓, what it <strong>assumed</strong> ~, and what is <strong>missing</strong> ? (for example &quot;Which story? Give the work item id&quot;); a capability that is not set up shows as missing too. Enter sends 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; it never invents an id, URL, project, or file.</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>
@@ -619,7 +648,7 @@ Result: A shareable report file with a short summary for the manager.
 <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>Ctrl-O</td><td>Open or close the panels (beside the conversation, or in its place on a narrow terminal)</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>
@@ -1904,14 +1933,14 @@ agents: [browser]
 <h3>MCP</h3>
 <div class="prose"></div>
 <section class="doc sub" id="doc-how_to_use-servers-forgeqes-agent-connects-to"><h4>Servers ForgeQE's agent connects to</h4><div class="prose"><p>When ForgeQE's agent starts, it connects to an MCP server for each system set up under <code>sources:</code>. The server settings come from the same place as everything else: the organization and project, the site URL, and the names of the environment variables that hold the tokens. You don't write MCP config for these.</p>
-<p><strong>Azure DevOps.</strong> Microsoft's <a href="https://github.com/microsoft/azure-devops-mcp" rel="noopener">Azure DevOps MCP server</a>, run as <code>npx -y @azure-devops/mcp &lt;org&gt; -a pat -d all</code>, with every tool group the server has. The organization comes from <code>org_url</code> (<code>https://dev.azure.com/acme</code> or <code>https://acme.visualstudio.com</code>). ForgeQE passes the PAT from <code>token_env</code> (default <code>ADO_PAT</code>) the way the server wants it; without a PAT it uses your <code>az login</code> session. Its tools are <code>azure_devops_*</code>: work items and comments, queries, backlogs, iterations, test plans, pipelines and their logs, repos, branches, pull requests, wiki pages (read, create, and update), search across code, wikis, and work items, and Advanced Security alerts. <code>mcp_domains</code> limits them to some groups. It needs Node.js. Azure DevOps Server (on-premises) isn't supported by Microsoft's server, so it uses ForgeQE's API.</p>
+<p><strong>Azure DevOps.</strong> Microsoft's <a href="https://github.com/microsoft/azure-devops-mcp" rel="noopener">Azure DevOps MCP server</a>, run as <code>npx -y @azure-devops/mcp &lt;org&gt; -a pat -d core work work-items pipelines</code>: projects and teams, iterations and boards, work items, and pipelines. Every tool's definition goes to the model with each request, so ForgeQE loads only these groups (about 19 tools, roughly 9.5K tokens, against about 18K for all of them); its own tools cover test plans, wiki pages, dashboards, and pull request reviews, and <code>query_api</code> reads anything else, such as classic releases. The organization comes from <code>org_url</code> (<code>https://dev.azure.com/acme</code> or <code>https://acme.visualstudio.com</code>). ForgeQE passes the PAT from <code>token_env</code> (default <code>ADO_PAT</code>) the way the server wants it; without a PAT it uses your <code>az login</code> session. Its tools are <code>azure_devops_*</code>. <code>mcp_domains</code> adds groups: <code>test-plans</code>, <code>repositories</code> (repos, branches, pull requests), <code>wiki</code>, <code>search</code> (code, wikis, and work items), <code>advanced-security</code>, or <code>[all]</code>. It needs Node.js. Azure DevOps Server (on-premises) isn't supported by Microsoft's server, so it uses ForgeQE's API.</p>
 <pre><code class="language-yaml">sources:
   azure_devops:
     org_url: https://dev.azure.com/acme   # the MCP server takes the organization, not a project
     # project: Shop                       # optional: limit ForgeQE's own API calls to one project
     token_env: ADO_PAT
     mcp: true                     # false: API only
-    mcp_domains: [core, work-items, test-plans, pipelines]   # optional: fewer tool groups
+    mcp_domains: [core, work, work-items, pipelines, repositories]   # optional: the default four, plus repos
 </code></pre>
 <p>Microsoft's server has no dashboard tools and can't save queries. Ask for a dashboard (&quot;create a dashboard in QI-Payments with all defects in every state and the current sprint's stories&quot;) and ForgeQE's own <code>create_ado_dashboard</code> tool does it through the REST API with <code>ADO_PAT</code>: it runs each WIQL query once to check it, saves it as a shared query under <code>Shared Queries/ForgeQE</code> (updating one of the same name), and creates a team or project dashboard with a work item list or count tile per query, plus optional markdown text. The PAT needs Work Items (read and write) and permission to edit dashboards. Chart widgets are not made through the API; for those the agent uses the browser, which has to be signed in to <code>dev.azure.com</code> (<code>forgeqe login &lt;name&gt;</code> with a login for it under <code>logins:</code>).</p>
 <p>Microsoft's wiki tools (<code>azure_devops_wiki</code>, <code>azure_devops_wiki_upsert_page</code>) only work in a wiki that already exists. In a project without one they answer &quot;No wiki found&quot;. Ask for a wiki page and ForgeQE's <code>write_ado_wiki_page</code> tool writes it through the REST API instead. If the project has no wiki, the tool creates the project wiki (<code>&lt;Project&gt;.wiki</code>) first, then any missing parent pages (empty), then the page itself. A page that already exists is replaced. Code wikis are written on their published branch. The PAT needs Wiki (read and write). A login added to <code>forgeqe.yaml</code> while ForgeQE is running is picked up the next time the agent lists logins or signs in.</p>
@@ -2114,6 +2143,7 @@ agents: [browser]
 <tr><td><code>/profile &lt;name&gt;</code> or Tab</td><td>Switch the model profile</td></tr>
 <tr><td><code>/logs [shots]</code></td><td>Save this session's log and runs in one archive to share</td></tr>
 <tr><td><code>/features</code></td><td>What ForgeQE can do here: ✓ ready, ◐ works with some parts to set up, ○ needs setup, with the fix (works without a model)</td></tr>
+<tr><td><code>/init</code></td><td>Set ForgeQE up in this folder, as <code>forgeqe init</code> does: <code>forgeqe.yaml</code>, <code>llms.json</code>, and editable prompts, skills, and knowledge; the session reads them at once</td></tr>
 <tr><td><code>/skills [name]</code></td><td>The skills each agent can use, or one skill's instructions</td></tr>
 <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>

package/forgeqe.example.yaml

@@ -103,7 +103,7 @@ sources:
   #   # project: Shop                       # optional: limit ForgeQE's own test, sprint, and bug calls to one project. Or ADO_PROJECT. * or all means every project.
   #   token_env: ADO_PAT                    # PAT with Test Management + Work Items (read & write)
   #   mcp: true                             # Microsoft's Azure DevOps MCP server (needs npx); false: API only
-  #   # mcp_domains: [core, work, work-items, test-plans, pipelines, repositories, wiki, search, advanced-security]   # default: all
+  #   # mcp_domains: [core, work, work-items, pipelines]   # the default; add test-plans, repositories, wiki, search, advanced-security, or use [all]
   # jira:
   #   url: https://acme.atlassian.net       # or JIRA_URL; Server/Data Center URLs work too
   #   email_env: JIRA_EMAIL                 # Cloud only

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.0.9",
+  "version": "1.1.1",
   "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/brain.md

@@ -12,7 +12,7 @@ Find what the user wants from their message. Then do it with your tools. ForgeQE
 - A request to write or repair tests, or a CI pipeline task.
 - A question.
 
-A message can also be a task specification with the parts Goal, Context, Steps, Rules, and Result. Refine in the shell writes this type of message. Do the goal. Use the context as facts. Do the steps in sequence. Obey the rules. Give the result that it asks for.
+A message can also be a task specification with the parts Role, Objective, Context, Steps, Rules, Output format, and Summary. Refine in the shell writes this type of message. Take the role. Do the objective. Use the context as facts. Do the steps in sequence. Obey the rules. Give the answer in the output format.
 
 ForgeQE tools (the client adds the forgeqe_ prefix):
 - browser_run: does one goal in a real browser, and verifies it. Use it for all work that must occur on a website. Set purpose to test for a flow of the application under test. Set purpose to task for all other work, such as finding, linking, or checking work items, or reading data from a tool. A task never becomes an automated test.
@@ -72,8 +72,21 @@ Skills:
 Azure DevOps, Jira, Xray, and other systems:
 - To run test cases from these systems, files, or text, always use run_test_cases. It turns each case into a browser goal, writes the reports, and sends the results back.
 - To look at test cases before they run, use find_test_cases.
-- For all other data in those systems, use the MCP tools of the system when its server is connected. This includes bugs, stories, comments, queries, boards, pipeline runs, and pull requests.
-- If the server is not connected, or it has no tool for what you need, read with query_api.
+- Read data from these systems in this sequence:
+  1. The MCP tools of the system, when its server is connected. This includes bugs, stories, comments, queries, boards, pipeline runs, and pull requests.
+  2. query_api, when the server is not connected or has no tool for the data.
+  3. The browser, only when both cannot give the data, or when the user asks to see a page.
+- Do not use the browser to read data that an API gives. The browser is slow, and it needs a sign-in that a saved login may not have.
+- Do not call the APIs of these systems from the shell, with curl, Python, PowerShell, or a script. The shell does not have the credentials, and ForgeQE blocks these commands. Use query_api.
+- Azure DevOps classic releases are not in the MCP tools. Read them with query_api and the release host, for example https://vsrm.dev.azure.com/<organization>/<project>/_apis/release/releases?$top=10 or _apis/release/deployments.
+- When the user asks about releases in Azure DevOps, read both: the classic releases, and the runs of the deployment pipelines (the pipelines MCP tools). Say which of them each project uses.
+- For release details, find what is deployed now, not only the last run. Do these steps for each project:
+  1. Read the environments with query_api: <project>/_apis/distributedtask/environments.
+  2. Read the deployments of each environment: <project>/_apis/distributedtask/environments/<id>/environmentdeploymentrecords?top=5&api-version=7.1-preview.1.
+  3. Read the stages of each deployment run: <project>/_apis/build/builds/<id>/timeline. Give each stage with its result.
+  4. When a stage failed, give the cause from the timeline: the failed task, check, or approval, and its message.
+  5. Compare the newest CI build with the build that the environments have. Say when a newer build is not deployed.
+- Keep these cases apart: a project without a deployment pipeline, a pipeline without runs, and a run that failed.
 - Create or change items only when the user asks. Examples are to file a bug, add a comment, move an issue, or edit a work item. Say what you changed, with its id or key.
 - The only exception is to save test cases that you wrote from a story (see below).
 - Azure DevOps dashboards: use create_ado_dashboard, not the browser.
@@ -320,6 +333,7 @@ Rules:
   - Use bold only for the one word or number that is important in a line, such as a status or a count. Do not make full sentences bold.
   - Use a table only for two or three short columns.
 - Keep replies short and specific. Give in full the test cases, tests, and reviews that the user asked for. Keep only your own comments short.
+- A status alone is not an answer. When a result is "failed", empty, or "none found", find the cause with your tools before you reply. Give the cause and the next action that fixes it.
 - When the user asks for a report, a write-up, or a summary to share, collect the facts with your tools. Examples are "create a release report" and "write up the open defects".
 - Then save the report with write_report. Reply with three to five lines of summary. The shell shows the paths of the report as links, so do not repeat them.
 - Do not only paste a long report into the reply.

package/prompts/refine.md

@@ -5,33 +5,41 @@ used_by: "the shell's Refine (ctrl+r)"
 ---
 You refine a request that the user typed for ForgeQE, a test automation assistant. ForgeQE then sends the refined request to its agent. You do not do the request. You do not change data.
 
-Write the refined request as a short task specification for the agent. Write it in ASD-STE100 Simplified Technical English:
+Write the refined request in ASD-STE100 Simplified Technical English:
 - Use short sentences: 20 words or fewer in an instruction, 25 words or fewer in a description.
 - Give one instruction in each sentence. Start an instruction with a verb.
 - Use the active voice.
 - Use simple words with one meaning. For example, use "make sure", not "ensure", and "use", not "utilize".
 - Use the same name for the same thing each time.
 
-Fill in these parts:
-- goal: one instruction that says what the agent must do. Start with a verb. Example: "Run the test cases of Azure DevOps test plan 412, suite 77."
-- context: the facts that the agent needs. Give the system, the project, the work items, the files, and the runs with their exact names and ids. Give one fact for each line.
+Write the request as a system prompt for the agent. Fill in these parts, in this sequence:
+- role: the role that the agent takes for this task, as one short description. Examples: "A release analyst who reads Azure DevOps deployments." and "A test engineer who runs manual test cases in the browser."
+- objective: one instruction that says what the agent must do. Start with a verb. Name the exact thing to get or do, not a general word. Example: "Run the test cases of Azure DevOps test plan 412, suite 77." Example: "Get what is deployed now in each environment of each project, with the stages and the cause of each failed deployment."
+- context: the facts that the agent needs. Give the system, the project, the work items, the files, and the runs with their exact names. Give one fact for each line.
+- Give names, not internal ids such as GUIDs. Give an id only when it is the name that people use, for example a work item number, a test plan or suite number, or a build number.
+- Put a list of items of the same type on one line, for example "Projects: Autothon, CQube.AI, QI-Payments".
 - Give only the facts that this task needs. Do not give the working directory or the settings of forgeqe.yaml. The agent already has them.
-- steps: the actions, in sequence, when the request has more than one action. Give one action for each step. Leave this empty for a request with one action.
+- steps: the actions, in sequence, when the request has more than one action. Give one action for each step. Each step must add information that the objective does not give, for example which data to read or how to compare it. When the steps only say the objective again, leave steps empty.
 - rules: the limits that the user gave or that the setup sets. Examples are "Do not send results back to Azure DevOps", "Use 2 browsers at the same time", and "Show the browser". Give only rules that come from the user or from "This session".
-- result: what the agent must give back. Examples are a report saved as a file with a short summary, a test file and its run, or a list of test cases with links.
+- output: the output format. Say what the agent gives back and how it is laid out. Examples: "One section for each project, with a line for each environment: the deployed build, its date, and its status." and "A report file, with a summary of three lines in the chat."
+- summary: what the user gets, in one sentence of 15 words or fewer. The agent reads it last. Do not copy the objective. Example: "Show the deployed build in each environment, and why each deployment failed."
 
 Rules for your work:
 - Keep the intent and the scope of the user exactly. Do not add work that the user did not ask for. Do not remove work that the user asked for.
+- Keep each word that changes the result, such as "current", "all", "details", or "failed". For example, "current release" means what is deployed now, not the last run.
 - Use the names that ForgeQE uses, for example "Azure DevOps project QI-Payments", "test plan 412, suite 77", "story 1761", or "SHOP-12".
 - Use "This session" and "What ForgeQE can do here" to know the capabilities and the setup.
 - Describe each action in plain words, for example "run the test cases" or "write a Playwright test". Do not name the tools of ForgeQE or the capability ids.
 - Change references such as "the last run", "that story", or "the payments plan" into the item that they point to. Do this only when exactly one item fits.
 - Check facts with your read-only tools. For example, check that a work item, a test plan, a suite, or a run exists, what its name is, and how many cases it has.
-- Put each fact that you state in grounded, and say if you checked it.
+- Put each fact of context in grounded, with the same words, and say if you checked it. Do not add facts to grounded that are not in context.
+- A request can mean more than one thing. Then select the meaning that the capabilities of ForgeQE support best, and write the objective for it. Say the meaning that you selected in assumed.
+- Do not ask about a meaning that you selected in assumed. The user sees assumed and can change it.
+- Put a question in missing only when you cannot select a meaning and a wrong selection gives a different result. In the question, give the possible meanings, for example "Classic releases, deployment pipeline runs, or release readiness (GO / NO-GO)?".
 - Do not invent an id, a URL, a project, or a file.
 - If you cannot find or check an item, put a short question for the user in missing.
 - If a capability that the request needs is not set up, put this in missing. Say what the user must set up.
 - Keep the settings that the user gave, for example the number of browsers, a visible browser, or whether results go back. Do not add other settings.
 - Write in the language of the user.
 
-Finish with the structured result: goal, context, steps, rules, result, grounded, assumed, and missing.
+Finish with the structured result: role, objective, context, steps, rules, output, summary, grounded, assumed, and missing.

package/src/brain/index.ts

@@ -2,7 +2,7 @@ import { realpathSync } from "node:fs"
 import path from "node:path"
 
 import type { CodeEvent, Usage } from "../types.ts"
-import { findOpencode, openSession, type OpencodeSession } from "../code/runtime.ts"
+import { agentBashPermission, findOpencode, openSession, type OpencodeSession } from "../code/runtime.ts"
 import { privateEnvNames } from "../childEnv.ts"
 import type { AppConfig } from "../config.ts"
 import { externalMcp, externalNotes, type ExternalPlan } from "../mcp/external.ts"
@@ -144,7 +144,14 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
       secrets: Object.assign({}, ...external.servers.map((s) => s.secrets)),
       signal: opts.signal,
       onEvent,
-      agent: { name: BRAIN_AGENT, description: "ForgeQE: browser runs, test cases, tests, and CI pipelines", prompt: `${brainPrompt()}\n\nThis session:\n${notes}`, skills: "forgeqe" },
+      agent: {
+        name: BRAIN_AGENT,
+        description: "ForgeQE: browser runs, test cases, tests, and CI pipelines",
+        prompt: `${brainPrompt()}\n\nThis session:\n${notes}`,
+        skills: "forgeqe",
+        // Systems are read through MCP or query_api, never by scripts in the shell that handle tokens themselves.
+        permission: { bash: agentBashPermission(privateEnvNames(config)) },
+      },
       skills: loadSkills(config.skills, cwd).skills,
       schema: BRAIN_SCHEMA,
       mcp: {

package/src/code/runtime.ts

@@ -267,6 +267,18 @@ export const BASH_PERMISSION = {
   "*gh repo delete*": "deny",
 }
 
+/**
+ * ForgeQE's agent's shell: everything BASH_PERMISSION allows, except calling Azure DevOps, Jira, Xray, or Confluence
+ * APIs directly (their REST paths) or touching a secret by name. Those systems are read with their MCP tools or
+ * query_api, which hold the credentials; a script that builds its own auth header from a token is never needed.
+ */
+export function agentBashPermission(secretNames: string[]): Record<string, string> {
+  const bash: Record<string, string> = { ...BASH_PERMISSION }
+  for (const p of ["*_apis/*", "*/rest/api/*", "*/rest/raven/*", "*/wiki/rest/*", "*/wiki/api/v2/*"]) bash[p] = "deny"
+  for (const name of secretNames) if (/^[A-Z][A-Z0-9_]{2,}$/.test(name)) bash[`*${name}*`] = "deny"
+  return bash
+}
+
 /** Commands that throw away the user's uncommitted work, also when wrapped in another command. */
 const DISCARD_WORK = ["git clean*", "git reset --hard*", "git stash*", "git restore*", "git checkout -- *", "git checkout .*"].flatMap((c) => [c, `*${c}`])
 

package/src/commands.ts

@@ -10,6 +10,8 @@ export type ShellCommand =
   | { type: "logs"; shots: boolean }
   | { type: "skills"; name?: string }
   | { type: "features" }
+  /** forgeqe init in the current folder: forgeqe.yaml, llms.json, and editable prompts, skills, and knowledge. */
+  | { type: "init" }
   /** Sign in to a system (or save a secret by name), forget one, or show which are signed in. */
   | { type: "auth"; action: "status" | "login" | "logout"; system?: string }
   | { type: "text"; text: string }
@@ -33,6 +35,7 @@ export const HELP = [
   "  /profile <name>    switch LLM profile (or press tab)",
   "  /logs [shots]      save this session's log and runs in one archive to share (shots: with screenshots)",
   "  /features          what ForgeQE can do, and what each capability still needs here",
+  "  /init              set ForgeQE up in this folder: forgeqe.yaml, llms.json, editable prompts, skills, knowledge",
   "  /skills [name]     the skills each agent can use, or one skill's instructions",
   "  /auth [system]     sign in to Azure DevOps, GitHub, Jira, Confluence, TestRail, Zephyr, qTest or Xray in the browser",
   "                     (/auth alone: what is signed in; /auth logout <system>; /auth <ENV_NAME> saves one secret)",
@@ -43,7 +46,7 @@ export const HELP = [
   "Select text with the mouse to copy it.",
 ].join("\n")
 
-const COMMANDS = new Set(["help", "?", "exit", "quit", "q", "clear", "stop", "headed", "details", "verbose", "profile", "p", "logs", "skills", "features", "auth", "signin"])
+const COMMANDS = new Set(["help", "?", "exit", "quit", "q", "clear", "stop", "headed", "details", "verbose", "profile", "p", "logs", "skills", "features", "auth", "signin", "init"])
 
 /** Session controls; every other line, including one that starts with a path, goes to the agent as text. */
 export function parseCommand(raw: string): ShellCommand {
@@ -75,6 +78,8 @@ export function parseCommand(raw: string): ShellCommand {
       return arg ? { type: "skills", name: arg } : { type: "skills" }
     case "features":
       return { type: "features" }
+    case "init":
+      return { type: "init" }
     case "auth":
     case "signin": {
       const [first, ...rest] = arg.split(/\s+/).filter(Boolean)

package/src/mcp/external.ts

@@ -1,7 +1,26 @@
 import type { AppConfig } from "../config.ts"
 
-/** Azure DevOps MCP tool groups ForgeQE loads unless sources.azure_devops.mcp_domains says otherwise: every group the server has. */
-export const ADO_DOMAINS = ["all"]
+/**
+ * Azure DevOps MCP tool groups ForgeQE loads unless sources.azure_devops.mcp_domains says otherwise. Every tool's
+ * definition goes to the model with each request, so only the groups the agent reads through MCP are loaded (about 19
+ * tools, ~9.5K tokens, against ~18K for all): projects and teams, sprints and boards, work items, and pipelines.
+ * ForgeQE's own tools cover test plans (run_test_cases), wiki pages, dashboards, and pull request reviews; query_api
+ * reads anything else. Add repositories, wiki, test-plans, search, or advanced-security in forgeqe.yaml, or use all.
+ */
+export const ADO_DOMAINS = ["core", "work", "work-items", "pipelines"]
+
+/** What each Azure DevOps MCP tool group gives the agent, in its words. */
+const ADO_DOMAIN_WORDS: Record<string, string> = {
+  core: "projects and teams",
+  work: "iterations and boards",
+  "work-items": "work items",
+  pipelines: "build and pipeline runs",
+  repositories: "repos and pull requests",
+  wiki: "wiki pages",
+  "test-plans": "test plans",
+  search: "search across code, wikis and work items",
+  "advanced-security": "security alerts",
+}
 export const ROVO_URL = "https://mcp.atlassian.com/v2/mcp"
 /** Also the time allowed for the first start, when npx or uvx downloads the server. */
 const TIMEOUT_MS = 120_000
@@ -67,23 +86,27 @@ export function externalMcp(cfg: AppConfig, which: Which = Bun.which, env: NodeJ
     else if (!auth) skipped.push({ label, why: `set ${ado.tokenEnv}, or sign in with az login` })
     else {
       const signIn = auth === "pat" ? `PAT in ${ado.tokenEnv}` : "Azure CLI sign-in"
+      const domains = ado.mcpDomains || ADO_DOMAINS
+      const covers = domains.includes("all") ? Object.values(ADO_DOMAIN_WORDS).join(", ") : domains.map((d) => ADO_DOMAIN_WORDS[d] || d).join(", ")
       servers.push({
         name: "azure_devops",
         label,
         signIn,
         about:
-          `Microsoft's Azure DevOps MCP server: organization ${org}${ado.project ? `, project ${ado.project}` : ", every project"} (work items, boards, test plans, pipelines, repos, wiki pages, search across code, wikis and work items, security alerts). ` +
+          `Microsoft's Azure DevOps MCP server: organization ${org}${ado.project ? `, project ${ado.project}` : ", every project"} (${covers}). For what its tools do not cover (classic releases, and anything else), read with query_api. ` +
           (auth === "pat"
             ? `It signs in with the personal access token in ${ado.tokenEnv}. `
             : `${ado.tokenEnv} is not set, so it signs in as the Azure CLI's account (az login). When it answers TF400813 or "not authorized", that account has no access to ${org}: say so, and that setting ${ado.tokenEnv} (in .env, or /auth azure_devops with a token) or adding that account to the organization fixes it. `) +
           "Always pass project to its tools that take one: without it the server asks the client to pick a project, which this session cannot answer, so the call fails. " +
-          "Its wiki tools only work in a wiki that exists and cannot create one; write wiki pages with ForgeQE's write_ado_wiki_page, which creates the project wiki when there is none. " +
+          (domains.includes("all") || domains.includes("wiki")
+            ? "Its wiki tools only work in a wiki that exists and cannot create one; write wiki pages with ForgeQE's write_ado_wiki_page, which creates the project wiki when there is none. "
+            : "Write wiki pages with ForgeQE's write_ado_wiki_page. ") +
           (ado.project
             ? `Use ${ado.project} unless the user names another project.`
             : "Work item ids are unique in the organization, so getting a work item by id works with any project name (from azure_devops_core_list_projects); its System.TeamProject field says which project it is in, so use that project for follow-up calls on it."),
         config: {
           type: "local",
-          command: ["npx", "-y", "@azure-devops/mcp", org, "-a", auth, "-d", ...(ado.mcpDomains || ADO_DOMAINS)],
+          command: ["npx", "-y", "@azure-devops/mcp", org, "-a", auth, "-d", ...domains],
           ...(pat ? { environment: { PERSONAL_ACCESS_TOKEN: "{env:FORGEQE_ADO_MCP_TOKEN}" } } : {}),
           enabled: true,
           timeout: TIMEOUT_MS,

package/src/mcp/server.ts

@@ -54,8 +54,18 @@ export function createMcpServer(opts: McpServerOptions) {
             base.emit?.(e)
           }
         : undefined
-      const out = await tool.run(params.arguments || {}, { ...base, emit, signal: controller.signal })
+      const said = (ok: boolean) => {
+        if (tool.line && emit) emit({ type: "call", text: tool.line(params.arguments || {}), ok })
+      }
+      let out: unknown
+      try {
+        out = await tool.run(params.arguments || {}, { ...base, emit, signal: controller.signal })
+      } catch (err) {
+        if (!controller.signal.aborted) said(false)
+        throw err
+      }
       if (controller.signal.aborted) return finish({ content: [{ type: "text", text: "Stopped by the user." }], isError: true })
+      said(true)
       return finish({ content: [{ type: "text", text: typeof out === "string" ? out : JSON.stringify(out, null, 2) }] })
     } catch (err) {
       return finish({ content: [{ type: "text", text: controller.signal.aborted ? "Stopped by the user." : (err as Error).message || String(err) }], isError: true })