@capagents/forgeqe 1.3.2 → 2.0.1

package/docs/user-guide.html

@@ -322,20 +322,22 @@ a:hover{text-decoration-color:var(--guide-accent)}
 <ol class="chapters">
 <li><a href="#area-browser"><span class="n">04</span><span class="t">Browser</span><span class="d">Goals carried out in a real browser, and the logins they use</span></a></li>
 <li><a href="#area-test-cases"><span class="n">05</span><span class="t">Test cases</span><span class="d">Run, check, write, and explore manual test cases</span></a></li>
-<li><a href="#area-automated-tests"><span class="n">06</span><span class="t">Automated tests</span><span class="d">Write, heal, find, run, and stabilise tests in your repository</span></a></li>
-<li><a href="#area-pull-requests"><span class="n">07</span><span class="t">Pull requests</span><span class="d">Reviews, impact, and the tests a change can break</span></a></li>
-<li><a href="#area-api"><span class="n">08</span><span class="t">API</span><span class="d">Contracts and end-to-end scenarios, without a browser</span></a></li>
-<li><a href="#area-quality"><span class="n">09</span><span class="t">Quality</span><span class="d">Accessibility, page performance, and visual changes</span></a></li>
-<li><a href="#area-release"><span class="n">10</span><span class="t">Release</span><span class="d">Requirement coverage and a release verdict</span></a></li>
-<li><a href="#area-operations"><span class="n">11</span><span class="t">Operations</span><span class="d">Monitoring and CI pipelines</span></a></li>
-<li><a href="#area-systems"><span class="n">12</span><span class="t">Systems</span><span class="d">Azure DevOps, Jira, and Confluence</span></a></li>
-<li><a href="#area-setup"><span class="n">13</span><span class="t">Setup</span><span class="d">Configuration, skills, and help</span></a></li>
+<li><a href="#area-setup"><span class="n">06</span><span class="t">Setup</span><span class="d">Configuration, skills, and help</span></a></li>
+<li><a href="#area-desktop"><span class="n">07</span><span class="t">Desktop</span><span class="d">Windows thick-client apps: explore a goal, record by hand, replay the saved workflow</span></a></li>
+<li><a href="#area-mobile"><span class="n">08</span><span class="t">Mobile</span><span class="d">Android and iOS apps through Appium or Maestro: explore a goal, replay, run the team's flows</span></a></li>
+<li><a href="#area-operations"><span class="n">09</span><span class="t">Operations</span><span class="d">Monitoring and CI pipelines</span></a></li>
+<li><a href="#area-automated-tests"><span class="n">10</span><span class="t">Automated tests</span><span class="d">Write, heal, find, run, and stabilise tests in your repository</span></a></li>
+<li><a href="#area-pull-requests"><span class="n">11</span><span class="t">Pull requests</span><span class="d">Reviews, impact, and the tests a change can break</span></a></li>
+<li><a href="#area-api"><span class="n">12</span><span class="t">API</span><span class="d">Contracts and end-to-end scenarios, without a browser</span></a></li>
+<li><a href="#area-quality"><span class="n">13</span><span class="t">Quality</span><span class="d">Accessibility, page performance, and visual changes</span></a></li>
+<li><a href="#area-release"><span class="n">14</span><span class="t">Release</span><span class="d">Requirement coverage and a release verdict</span></a></li>
+<li><a href="#area-systems"><span class="n">15</span><span class="t">Systems</span><span class="d">Azure DevOps, Jira, and Confluence</span></a></li>
 </ol>
 </section>
 <section class="rail-group">
 <h2 class="rail-title mono">Reference</h2>
 <ol class="chapters">
-<li><a href="#reference"><span class="n">14</span><span class="t">Reference</span><span class="d">MCP, tuning, logs, environment variables, and every command</span></a></li>
+<li><a href="#reference"><span class="n">16</span><span class="t">Reference</span><span class="d">MCP, tuning, logs, environment variables, and every command</span></a></li>
 </ol>
 </section>
 </div>
@@ -378,14 +380,16 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <h3 class="band-title">Every feature</h3>
 <div class="area"><a class="area-name" href="#area-browser"><span class="mono">Browser</span></a><ul class="tiles"><li><a class="tile" href="#cap-browser-goals"><b>Run any goal in a real browser</b><span>Go to booking.com and search hotels in Mumbai for next weekend</span></a></li><li><a class="tile" href="#cap-logins"><b>Saved logins for the application under test</b><span>Sign in to the admin site and keep the session</span></a></li></ul></div>
 <div class="area"><a class="area-name" href="#area-test-cases"><span class="mono">Test cases</span></a><ul class="tiles"><li><a class="tile" href="#cap-run-test-cases"><b>Run manual test cases in browsers</b><span>Run SHOP-12 and SHOP-14 from Jira, two browsers at once</span></a></li><li><a class="tile" href="#cap-test-case-quality"><b>Check and improve test cases</b><span>Are the cases in test plan 12 good enough to run?</span></a></li><li><a class="tile" href="#cap-write-test-cases"><b>Write test cases from a story</b><span>Write test cases for story 1234 and save them</span></a></li><li><a class="tile" href="#cap-domain-compliance"><b>Domain and regulatory test design</b><span>Write test cases for story 1234, covering our DORA and PSD2 obligations</span></a></li><li><a class="tile" href="#cap-exploratory-testing"><b>Exploratory testing of a story</b><span>Explore story 1234 and find bugs</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-test-apps"><b>Test environments and their apps</b><span>Place an order in the shop, then check its invoice in Billing, in UAT</span></a></li><li><a class="tile" href="#cap-setup-help"><b>Setup, skills, and documentation</b><span>What can you do?</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-desktop"><span class="mono">Desktop</span></a><ul class="tiles"><li><a class="tile" href="#cap-desktop-apps"><b>Automate Windows desktop apps</b><span>Create an invoice for Contoso in the Billing app and save it as a test</span></a></li></ul></div>
+<div class="area"><a class="area-name" href="#area-mobile"><span class="mono">Mobile</span></a><ul class="tiles"><li><a class="tile" href="#cap-mobile-apps"><b>Automate Android and iOS apps</b><span>Sign in to the courier app and accept the first delivery, and save it as a test</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-containers"><b>Services and mocks in Docker or Podman</b><span>Start the database and the queue in Docker</span></a></li><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-automated-tests"><span class="mono">Automated tests</span></a><ul class="tiles"><li><a class="tile" href="#cap-write-tests"><b>Turn a passed run into an automated test</b><span>Write a Playwright test for that run in ../app</span></a></li><li><a class="tile" href="#cap-heal-tests"><b>Heal failing tests</b><span>Heal the failing tests in ../app</span></a></li><li><a class="tile" href="#cap-find-run-tests"><b>Find and run existing tests</b><span>Run the checkout tests</span></a></li><li><a class="tile" href="#cap-regression-packs"><b>Regression packs for a release</b><span>Build a regression pack for sprint 12 and run it on TestMu</span></a></li><li><a class="tile" href="#cap-flaky-tests"><b>Flaky test detection and quarantine</b><span>Which tests are flaky?</span></a></li></ul></div>
 <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><li><a class="tile" href="#cap-defect-intelligence"><b>Defect intelligence: trends and prediction</b><span>Which defects keep coming back?</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, GitHub, 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>
 <h3 class="band-title">Not supported</h3>
 <ul class="plainlist"><li><b>Native mobile apps (iOS, Android) and desktop applications</b>. Instead: web applications in local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest.</li><li><b>Load, stress, or soak testing with many simultaneous users</b>. Instead: per-page Core Web Vitals with budgets.</li><li><b>Penetration testing or dynamic security scanning</b>. Instead: security findings in pull request reviews.</li></ul>
 </section>
@@ -401,7 +405,7 @@ forgeqe docs --copy ./docs   # copy the guide, the architecture page, and the re
 <tbody>
 <tr><td><strong>npm (Node.js 18+) or pip (Python 3.9+)</strong></td><td>To install <code>@capagents/forgeqe</code> or <code>forgeqe-cli</code>; either one gives the same <code>forgeqe</code> command</td></tr>
 <tr><td><strong>A terminal</strong></td><td>macOS Terminal, iTerm2, VS Code or Cursor's terminal, Windows Terminal</td></tr>
-<tr><td><strong>A model</strong></td><td>A profile in <code>llms.json</code> with a working key, or Microsoft Entra ID sign-in for Azure (Azure OpenAI, OpenAI, an OpenAI-compatible gateway, or Ollama)</td></tr>
+<tr><td><strong>A model</strong></td><td>A profile in <code>llms.json</code> with a working key, or Microsoft Entra ID sign-in for Azure (Azure OpenAI, OpenAI, an OpenAI-compatible gateway, or Ollama), or a GitHub Copilot seat (see <a href="../#github-copilot-seats-as-the-model">GitHub Copilot seats as the model</a>)</td></tr>
 <tr><td><strong>Internet access on first use</strong></td><td>ForgeQE downloads Bun, the agent runtime, uv, Python, and the engine into <code>~/.forgeqe</code> once</td></tr>
 </tbody>
 </table></div>
@@ -434,6 +438,11 @@ export WP_AZURE_API_KEY=...            # the key your llms.json profile names
 forgeqe models                        # check the profiles
 forgeqe start                         # the shell
 </code></pre>
+<p>With GitHub Copilot licences instead of a model key, sign in rather than exporting one, and set <code>llm.active: copilot</code> in <code>forgeqe.yaml</code> (or <code>&quot;default&quot;: &quot;copilot&quot;</code> in <code>llms.json</code>):</p>
+<pre><code class="language-bash">forgeqe auth login copilot            # ForgeQE's agent and Scribe on your Copilot seat
+forgeqe auth login github             # the browser engine, through GitHub Models
+forgeqe models                        # the copilot profile is active
+</code></pre>
 <p>In the shell, type a request and press Enter:</p>
 <pre><code>Go to booking.com and search for hotels in Mumbai for next weekend
 Run SHOP-12 and SHOP-14 from Jira, two browsers at once
@@ -507,6 +516,61 @@ bun src/index.ts init --global --profile azure-gpt4o
 </table></div>
 <p>Give that identity the <strong>Cognitive Services OpenAI User</strong> role on the resource. Tokens are renewed before they expire, so long suites and coding sessions keep running. The browser engine signs in itself; the coding agent's runtime only takes a key, so ForgeQE gives it a gateway on <code>127.0.0.1</code> that accepts a one-time random key and passes each request on with a current token. No key is stored anywhere.</p>
 <p><code>auth: entra</code> also works on an <code>openai_compatible</code> profile, for a gateway such as API Management that checks Entra ID tokens: set <code>token_scope</code> to the scope it expects (for example <code>api://&lt;app id&gt;/.default</code>; the default is <code>https://cognitiveservices.azure.com/.default</code>). The engine needs the <code>azure-identity</code> package, which <code>forgeqe setup</code> installs (and adds to environments set up before it was needed); with <code>FORGEQE_PYTHON</code>, install it there yourself.</p>
+</div></section>
+<section class="doc sub" id="doc-how_to_use-github-copilot-seats-as-the-model"><h4>GitHub Copilot seats as the model</h4><div class="prose"><p>With GitHub Copilot licences (Pro, Pro+, Business or Enterprise), a <code>github_copilot</code> profile runs ForgeQE's agent and Scribe on the Copilot seat. They work through the agent runtime's own GitHub Copilot sign-in, <a href="https://github.blog/changelog/2026-01-16-github-copilot-now-supports-opencode/" rel="noopener">which GitHub supports</a>. Copilot gives other tools no model API of their own, so the browser engine and the desktop agent use <a href="https://docs.github.com/en/github-models" rel="noopener">GitHub Models</a> instead, with your GitHub sign-in:</p>
+<pre><code class="language-json">&quot;copilot&quot;: {
+  &quot;provider&quot;: &quot;github_copilot&quot;,
+  &quot;model&quot;: &quot;claude-sonnet-4.6&quot;,
+  &quot;engine_model&quot;: &quot;openai/gpt-4.1&quot;,
+  &quot;github_org&quot;: &quot;acme&quot;
+}
+</code></pre>
+<div class="tbl"><table>
+<thead>
+<tr><th>Field</th><th>What it is</th></tr>
+</thead>
+<tbody>
+<tr><td><code>model</code></td><td>The Copilot model for ForgeQE's agent and Scribe, as Copilot names it (<code>claude-sonnet-4.6</code>, <code>gpt-5.4</code>). The sign-in lists the ones your seat has.</td></tr>
+<tr><td><code>engine_model</code></td><td>The GitHub Models model for the browser engine and the desktop agent, as <code>publisher/model</code>. It must take images. Default <code>openai/gpt-4.1</code>.</td></tr>
+<tr><td><code>github_org</code></td><td>Optional. Bills the engine's GitHub Models calls to this organization and applies its policies, rather than your personal free allowance.</td></tr>
+<tr><td><code>api_key_env</code></td><td>Optional. The variable holding the GitHub Models token; default <code>GITHUB_TOKEN</code>, else the GitHub CLI's sign-in.</td></tr>
+</tbody>
+</table></div>
+<p>Sign in once per machine:</p>
+<pre><code class="language-bash">forgeqe auth login copilot   # Copilot, for ForgeQE's agent and Scribe (GitHub.com or GitHub Enterprise, e.g. acme.ghe.com)
+forgeqe auth login github    # the GitHub CLI, whose sign-in the browser engine uses for GitHub Models
+</code></pre>
+<p><code>forgeqe auth login copilot</code> shows a one-time code and opens GitHub's device page; authorize with the account that has the seat. The sign-in goes to your system's credential store like ForgeQE's other secrets. The agent runtime gets it in its environment for each session, never in a file, and the agent's shell commands never see it. A Copilot sign-in made with <code>opencode auth login</code> also works. In CI, set <code>GITHUB_TOKEN</code> to a token with the <code>models:read</code> permission for the engine.</p>
+<p><code>forgeqe auth</code> shows the sign-in on its <code>Copilot</code> line (<code>saved sign-in as dana</code>, or <code>agent runtime's own sign-in</code> for one made with <code>opencode auth login</code>); <code>forgeqe auth logout copilot</code> forgets it.</p>
+<p>Which part uses what:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Part</th><th>Model</th><th>Signs in with</th></tr>
+</thead>
+<tbody>
+<tr><td>ForgeQE's agent (the shell, <code>forgeqe run</code>)</td><td><code>model</code>, on the Copilot seat</td><td><code>forgeqe auth login copilot</code></td></tr>
+<tr><td>Scribe (writing, fixing and reviewing tests)</td><td><code>model</code>, on the Copilot seat</td><td><code>forgeqe auth login copilot</code></td></tr>
+<tr><td>The browser engine (every browser run: <code>run --direct</code>, suites, monitoring)</td><td><code>engine_model</code>, on GitHub Models</td><td><code>GITHUB_TOKEN</code>, or <code>forgeqe auth login github</code></td></tr>
+<tr><td>The desktop agent</td><td><code>engine_model</code>, on GitHub Models</td><td><code>GITHUB_TOKEN</code>, or <code>forgeqe auth login github</code></td></tr>
+</tbody>
+</table></div>
+<p><code>code.model</code> still overrides <code>model</code> for ForgeQE's agent and Scribe; <code>code.model: github-copilot/&lt;model&gt;</code> uses the Copilot sign-in too, with any other profile active.</p>
+<p>What each part costs: the agent's and Scribe's requests count against the seat's premium requests. The engine's GitHub Models calls are billed by GitHub Models: the free allowance is rate-limited, so for suites set <code>github_org</code> to an organization with paid GitHub Models usage turned on. If a Copilot model is refused, check that your organization's Copilot policies allow that model. ForgeQE shows no cost for a <code>github_copilot</code> profile unless you give it a <code>price</code>.</p>
+<p><strong>In pipelines.</strong> <code>forgeqe suite ... --no-code</code>, which pipelines run, uses only the browser engine, so it needs GitHub Models and no Copilot sign-in. In GitHub Actions, give the job <code>permissions: models: read</code> and pass the workflow's own token as <code>GITHUB_TOKEN</code>; on Azure Pipelines or elsewhere, store a fine-grained token with the <code>models:read</code> permission as the <code>GITHUB_TOKEN</code> secret. A Copilot seat belongs to one person, so keep ForgeQE's agent and Scribe on developers' machines rather than signing a shared pipeline in to someone's seat.</p>
+<p><strong>When something goes wrong.</strong></p>
+<div class="tbl"><table>
+<thead>
+<tr><th>ForgeQE says</th><th>What to do</th></tr>
+</thead>
+<tbody>
+<tr><td><code>The github_copilot profile for … needs a GitHub Copilot sign-in</code></td><td>Run <code>forgeqe auth login copilot</code> (or <code>/auth copilot</code> in the shell).</td></tr>
+<tr><td><code>The browser engine reaches GitHub Models with a GitHub sign-in, and there is none</code></td><td>Run <code>forgeqe auth login github</code>, or set <code>GITHUB_TOKEN</code> to a token with <code>models:read</code>.</td></tr>
+<tr><td><code>… must be a Copilot model id</code>, <code>engine_model must be a GitHub Models id</code>, <code>github_org must be a GitHub organization name</code></td><td>Fix that field in <code>llms.json</code>: the sign-in lists the seat's Copilot models, and <a href="https://github.com/marketplace?type=models" rel="noopener">the GitHub Models catalog</a> lists <code>publisher/model</code> ids.</td></tr>
+<tr><td>The agent's model is refused, or not found</td><td>The seat's plan or your organization's Copilot policies do not allow that model: pick one the sign-in listed, or ask a Copilot admin to enable it.</td></tr>
+<tr><td>The browser engine gets <code>429</code> / rate limit errors</td><td>The GitHub Models free allowance is used up: set <code>github_org</code> to an organization with paid GitHub Models usage, or wait for the limit to reset.</td></tr>
+<tr><td>The code page does not open, or the sign-in says <code>not a GitHub Enterprise domain</code></td><td>Give only the host of your GitHub Enterprise (<code>acme.ghe.com</code>). ForgeQE opens only GitHub's own <code>https</code> device page.</td></tr>
+</tbody>
+</table></div>
 <p><code>init</code> also puts three folders in <code>.forgeqe/</code> to read, change, and commit:</p>
 <div class="tbl"><table>
 <thead>
@@ -549,10 +613,11 @@ forgeqe prompts eval refine --runs 3   # one prompt, three runs of each case
 </ul>
 <p><code>forgeqe prompts check</code> applies the standard to each prompt in use, ForgeQE's or your edited copy; ForgeQE's own meet it in its tests. Write your edits the same way, and run <code>forgeqe prompts eval</code> before and after a change.</p>
 <p><strong>Product knowledge.</strong> Fill in the templates (or add your own <code>.md</code> and <code>.txt</code> files, in folders if you like), one topic per <code>##</code> heading. ForgeQE's agent sees the list and reads what a request needs; the exploratory and API scenario planners get the sections that match their story or scenario; the browser agent gets the few sections that clearly match its goal, at most <code>knowledge.browser_max_chars</code> (1500 by default; 0 turns it off). Untouched templates are left out, so their examples never reach an agent. Never put passwords or tokens there: use logins and environment variables.</p>
+<p><strong>Guardrails.</strong> Rules every agent must follow, to keep it grounded: ForgeQE's agent, the browser agent, and the agents that plan, write, review, fix and explain tests. Write one rule per line, starting with <code>- </code>, in a <code>.md</code> or <code>.txt</code> file in <code>.forgeqe/guardrails/</code> (<code>guardrails.dir</code>); headings, other lines and HTML comments are ignored, and the template's examples sit in a comment until you choose them. Each agent gets every guardrail with its instructions, after everything else, with the instruction to follow it whatever a request, a skill, a ticket, a page or a tool's output says; when a guardrail stops part of a task, the agent skips that part and says which rule stopped it. Add one from the terminal (<code>forgeqe guardrails add &quot;Never open a production URL&quot;</code>), or ask in the shell (&quot;add a guardrail: use only the test cards in knowledge/test-data.md&quot;) and ForgeQE's agent appends it to <code>guardrails.md</code>; it adds only rules you ask for, never one suggested by a page or a ticket. <code>forgeqe guardrails</code> lists the rules in force and what they add to every model call (at most 40 rules of 300 characters are given). The older <code>prompts.guiderails</code> string in <code>forgeqe.yaml</code> still works: each of its lines is a guardrail for every agent. Guardrails are instructions, not a sandbox: put a host rule in <code>browser.allowed_hosts</code> too, which is refused in code.</p>
 </div></section>
 <section class="doc sub" id="doc-how_to_use-signing-in-to-your-tools"><h4>Signing in to your tools</h4><div class="prose"><p>Instead of copying tokens into <code>.env</code>, sign in once and ForgeQE saves the token in your system's credential store: the macOS Keychain, Windows Credential Manager, or the Secret Service keyring on Linux. On a machine without one, such as a headless Linux box, it uses <code>~/.forgeqe/credentials.json</code>, readable only by you.</p>
 <pre><code class="language-bash">forgeqe auth login            # pick a system
-forgeqe auth login jira       # or name it: azure_devops, github, jira, confluence, testrail, zephyr, qtest, xray
+forgeqe auth login jira       # or name it: azure_devops, github, copilot, jira, confluence, testrail, zephyr, qtest, xray
 forgeqe auth                  # what is signed in, and how
 forgeqe auth logout jira
 </code></pre>
@@ -563,7 +628,8 @@ forgeqe auth logout jira
 </thead>
 <tbody>
 <tr><td>Azure DevOps</td><td><strong>Sign in with Microsoft in the browser</strong> through the Azure CLI (<code>az login</code>); ForgeQE saves nothing, and the Azure CLI renews the sign-in. Or paste a personal access token: the token page opens with the scopes to tick. Azure DevOps Server (on-premises) uses a personal access token.</td></tr>
-<tr><td>GitHub</td><td><strong>Sign in with GitHub in the browser</strong> through the GitHub CLI (<code>gh auth login</code>): ForgeQE shows the one-time code and opens the page. Or paste a token. Needs <code>gh</code> installed.</td></tr>
+<tr><td>GitHub</td><td><strong>Sign in with GitHub in the browser</strong> through the GitHub CLI (<code>gh auth login</code>): ForgeQE shows the one-time code and opens the page. Or paste a token. Needs <code>gh</code> installed. A <code>github_copilot</code> profile's browser engine uses this sign-in for GitHub Models.</td></tr>
+<tr><td>GitHub Copilot</td><td><code>forgeqe auth login copilot</code>: <strong>Sign in with GitHub in the browser</strong> through the agent runtime's Copilot sign-in, on GitHub.com or GitHub Enterprise (<code>acme.ghe.com</code>). ForgeQE shows the one-time code, opens GitHub's device page, and lists the Copilot models your seat has. For a <code>github_copilot</code> profile; see <a href="../#github-copilot-seats-as-the-model">GitHub Copilot seats as the model</a>.</td></tr>
 <tr><td>Jira, Confluence</td><td>Your Atlassian API tokens page opens (Cloud) or your personal access tokens page (Server/Data Center); create one and paste it. Confluence on the same Cloud site as Jira reuses the Jira sign-in.</td></tr>
 <tr><td>TestRail, Zephyr Scale, qTest, Xray Cloud</td><td>The page with your API key opens, or ForgeQE says where to find it; paste it.</td></tr>
 <tr><td>Anything else</td><td><code>forgeqe auth login OPENAI_API_KEY</code> (any variable name) saves that one secret: a model key, a Teams webhook URL, an SMTP or saved-login password.</td></tr>
@@ -572,6 +638,7 @@ forgeqe auth logout jira
 <p>Atlassian's OAuth sign-in needs a client secret, which a command-line tool cannot keep secret, so Jira and Confluence use API tokens: they are what Atlassian recommends for scripts and tools.</p>
 <p>Each token is checked against the system before it is saved, and the system is switched on: a saved Jira sign-in sets the site URL too, so <code>sources.jira</code> is not needed in <code>forgeqe.yaml</code>. Saved values go in under the variable names the config already reads (<code>JIRA_API_TOKEN</code>, <code>ADO_PAT</code>, ...). A variable exported in the terminal is used before a saved sign-in, and a saved sign-in before a <code>.env</code> file, so pipelines keep using their secrets. The shell commands the agents run never see the saved secrets.</p>
 <p><strong>Prices.</strong> ForgeQE prices every model call at the model's <strong>list price</strong>, from two public price lists: <a href="https://models.dev" rel="noopener">models.dev</a> (the list the agent runtime uses) and LiteLLM's model price list, which also has Azure's Data Zone prices. It keeps the few fields it needs in <code>~/.forgeqe/prices.json</code>, waits a few seconds for it the first time, refreshes it once a day in the background, and uses the last copy offline; only the public lists are downloaded, nothing about your runs is sent (<code>FORGEQE_PRICES=off</code> stops the downloads). Costs at list price say so: <code>$1.73 (list price of gpt-5.4 (Azure Global) from models.dev, 2026-10-06)</code>. For an Azure Data Zone deployment, which costs about 10% more, set <code>&quot;deployment_type&quot;: &quot;data_zone&quot;</code> on the profile.</p>
+<p><strong>Model parameters.</strong> Models differ in what a request may carry: reasoning models (o1, o3, o4, gpt-5) take <code>max_completion_tokens</code> instead of <code>max_tokens</code> and only the default temperature, and some OpenAI-compatible servers refuse <code>max_completion_tokens</code>, <code>reasoning_effort</code> or <code>response_format</code>. ForgeQE works this out by itself. A profile is a reasoning model when its <code>model</code> or <code>deployment</code> name says so (an Azure deployment called <code>chat-prod</code> with <code>&quot;model&quot;: &quot;gpt-5.4&quot;</code> counts), or when it sets <code>&quot;reasoning&quot;: true</code>; <code>&quot;reasoning&quot;: false</code> says it is not. When the API still refuses a parameter, the browser, desktop and mobile agents send the call again without it and leave it out of later calls to that model. Nothing needs setting for a new model.</p>
 <p>A profile's own <code>&quot;price&quot;: { &quot;input&quot;: 2.5, &quot;output&quot;: 15, &quot;cached_input&quot;: 0.25 }</code> (per million tokens) wins, for a negotiated or enterprise rate. Leave <code>currency</code> out and reports use this machine's currency, or set <code>&quot;currency&quot;: &quot;USD&quot;</code>. Without <code>cached_input</code>, cached input gets the model's cache discount from its list price, and the cost is marked as an estimate (<code>≈$1.52</code>); with no list price for the model either, cached input is charged at the full rate and the cost is an upper bound (<code>up to $6.11</code>). When your price differs from the list price, ForgeQE says so (<code>forgeqe models</code>, the shell, and the start of each command), since that is usually a typo or an old price. Anthropic's cache writes are priced at their own rate. A provisioned (PTU) deployment is billed per hour, not per token, so its costs are what the tokens would cost at list price. Requests over a model's long-context threshold (272K tokens for GPT-5.4) cost more and are priced at the normal rate.</p>
 <p><strong>Usage after every job.</strong> Every browser run, Scribe job, heal, suite, and monitor round ends with a <code>Usage</code> line: tokens in (and how many of them were cached), tokens out, and the cost at the profile's price. A request to ForgeQE's agent in the shell, and every <code>forgeqe run</code>, <code>code</code>, <code>suite</code>, and <code>heal</code> command, ends with the total for everything it started, by role:</p>
 <pre><code>This request used 1.1M tokens (1.1M in, 30.0K of it cached · 34.7K out) · $3.07 — ForgeQE's agent 42.0K · $0.12, browser agent 52.7K · $0.15, Scribe 1.0M · $2.80
@@ -611,7 +678,7 @@ browser:
 <p><code>judge</code> is off by default. When it is on, one more model call reads the finished run's steps and screenshots and can fail a run the agent completed, for example when five scores were read off one results page rather than one step per item. That strictness sent runs into loops of re-checking, so turn it on only when you want that second opinion.</p>
 <p>Each step waits for the tab the agent is on to finish loading (up to 8 seconds, 3 for a tab that stays blank) before the page is read, so a result that opens in a new tab is not mistaken for a blank page.</p>
 <p>With a visible browser (<code>headless: false</code> or <code>--headed</code>), ForgeQE opens on its own start page, and every page it drives gets a glowing edge and a bar along the bottom showing, in plain words, what the step is for and what the agent is doing (&quot;Step 19 · Check whether the results can be sorted by Fastest · Looking through the page's buttons&quot;). Your mouse and keyboard are locked while the agent thinks and unlocked while it clicks and types, so a stray click can't change the test. None of this appears in the screenshots the model sees or in the report. <code>overlay: false</code> turns it off. <code>forgeqe login &lt;name&gt;</code> shows the same bar without the lock, since you are the one signing in.</p>
-<p><code>start_url</code> is optional. Leave it out and the agent picks the site from the goal; ForgeQE never guesses a URL from the goal text. <code>allowed_hosts</code> empty allows every host. Set <code>[&quot;example.com&quot;]</code> to keep the browser on that domain and its subdomains. <code>prompts.guiderails</code> and <code>prompts.step_instruction</code> are appended to the engine's system prompt.</p>
+<p><code>start_url</code> is optional. Leave it out and the agent picks the site from the goal; ForgeQE never guesses a URL from the goal text. <code>allowed_hosts</code> empty allows every host. Set <code>[&quot;example.com&quot;]</code> to keep the browser on that domain and its subdomains. <code>prompts.step_instruction</code> is appended to the engine's system prompt; the lines of <code>prompts.guiderails</code> are guardrails for every agent (see Guardrails above).</p>
 <p>List profiles:</p>
 <pre><code class="language-bash">bun src/index.ts models
 </code></pre>
@@ -667,7 +734,7 @@ Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make i
 </tbody>
 </table></div>
 <p><code>start_url</code> in <code>forgeqe.yaml</code> or <code>--url</code> pins a start page for browser runs, such as a staging app. Passed runs become tests in the current folder; <code>forgeqe start --repo ../app</code> puts them in that repo instead, and <code>--no-code</code> turns tests off.</p>
-<p>ForgeQE's agent runs on the agent runtime with the active profile's model (or <code>code.model</code>). ForgeQE downloads the agent runtime into <code>~/.forgeqe/tools</code> when it is not installed. When the agent runtime cannot be downloaded, ForgeQE says the agent is off and runs each message as one browser goal.</p>
+<p>ForgeQE's agent runs on the agent runtime with the active profile's model (or <code>code.model</code>); a <code>github_copilot</code> profile runs it on your Copilot seat. ForgeQE downloads the agent runtime into <code>~/.forgeqe/tools</code> when it is not installed. When the agent runtime cannot be downloaded, ForgeQE says the agent is off and runs each message as one browser goal.</p>
 <p>While a run is going, the bar under the prompt shows a spinner, the tokens used, and the elapsed time, and the transcript ends with what the agent is doing now (<code>Thinking about step 3…</code>, <code>Acting in the browser (step 3)…</code>). Each step starts with <code>+ Thought: 4.2s</code>, the time the model took to decide. When the run ends, a summary card closes the transcript:</p>
 <pre><code>┃  ✓ Task complete                                   10 steps · 1m 42s · 65.3K tokens
 ┃
@@ -1276,187 +1343,700 @@ Acceptance criteria:
 </div>
 </article>
 </section>
-<section class="chapter" id="area-automated-tests" aria-labelledby="area-automated-tests-h">
-<header class="chead"><span class="mono">06</span><h2 id="area-automated-tests-h">Automated tests</h2><p>Write, heal, find, run, and stabilise tests in your repository</p></header>
-<article class="spec feat" id="cap-write-tests">
-<div class="hd"><span class="mono">Automated tests</span><h3>Turn a passed run into an automated test</h3></div>
-<p class="ds">Scribe, the coding agent, writes a test for a passed browser run in the repository's own framework, page objects, and helpers; ForgeQE runs it until it passes and a reviewer approves it.</p>
+<section class="chapter" id="area-setup" aria-labelledby="area-setup-h">
+<header class="chead"><span class="mono">06</span><h2 id="area-setup-h">Setup</h2><p>Configuration, skills, and help</p></header>
+<article class="spec feat" id="cap-test-apps">
+<div class="hd"><span class="mono">Setup</span><h3>Test environments and their apps</h3></div>
+<p class="ds">Knows the test environments in env.yaml (QA, UAT, …) and each one's apps: web apps and APIs by URL, Windows desktop apps, and mobile apps, with what each is for. Every agent works from the active one; switches environment on request, picks the apps a scenario needs, and carries values such as an order number from one app to the next.</p>
 <div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Write a Playwright test for that run in ../app</li></ul></div>
-<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs</span></li><li><span class="need input">You give</span><span>a repository to write the test in (default: the working directory)</span></li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>write_test</code> <code>run_test</code></p></div>
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Place an order in the shop, then check its invoice in Billing, in UAT</li><li>Which apps can you test in QA?</li><li>From now on, use the UAT environment</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need input">You give</span><span>env.yaml with the environments and apps (forgeqe init writes one)</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>test_apps</code> <code>use_environment</code></p></div>
 </div>
 <div class="detail"><span class="mono">In detail</span>
-<section class="doc" id="doc-how_to_use-6-tests">
-<h4>Tests</h4>
-<div class="prose"><p>After a run passes, <strong>Scribe</strong>, ForgeQE's coding agent, turns it into a test in your repo.</p>
-<p>In the shell and <code>forgeqe run</code>, every passed run then becomes a test, and so does each test case that passes when you ask the shell to run test cases: in the current folder, or in the repo you give per run or in <code>forgeqe.yaml</code>. <code>--no-code</code> turns it off; you can still ask for a test (&quot;write a Playwright test for that run&quot;).</p>
-<pre><code class="language-bash">forgeqe run &quot;Log in and open the invoices page on staging.app.test&quot; --repo ../app
-</code></pre>
-<pre><code class="language-yaml">code:
-  repo: ../app              # relative to forgeqe.yaml
-  max_attempts: 5           # test runs before giving up
-  test_timeout_seconds: 600 # per test run
-  stall_after: 5            # stop the agent's turn when one command it runs has failed this many times
-  replay: true              # before the agent starts, run the steps as a Playwright script and hand over what worked
-  live_browser: true        # once a step fails, the agent looks at that page in a Playwright browser
-  graph: true               # the code graph: find page objects without reading files, and reuse what already locates an element
-  # model: anthropic/claude-sonnet-4-5
-  # runtime: /path/to/agent-runtime   # default: the runtime ForgeQE downloads
-</code></pre>
-<p>What happens after the run passes:</p>
-<ol>
-<li>
-<p>ForgeQE writes <code>handoff.md</code> into the run directory: the goal and result, how ForgeQE's browser was set up (browser and version, headless or headed, user agent, <code>navigator.webdriver</code>, launch switches, extra headers, language, time zone, viewport), every step in order with the value typed (secrets as <code>process.env.NAME</code>) and the JavaScript the browser agent ran, the browser agent's own note before each group of steps (what it saw and why it acted, so a sign-in pop-up it closed or steps it redid after a banner covered the page read as such), each element's best locator and the others with their confidence %, and a short table of each visited page's other elements for assertions (weak locators under 30% are left out, and elements the steps already use are listed with the steps, so the handoff stays small; the full lists are in the page-memory files it points to). The agent's result and the final URL are marked as coming from one run on live data, to be checked as rules (the results load, the order holds, the fields have the right format), not copied as expected values. Pop-ups and banners the run met are handled wherever they appear (Playwright's locator handlers or the repository's helper), since the next run can show them at another moment or not at all; the agent's retries are not copied. A site can also serve different versions of a page to different visits (A/B tests, such as a classic search box or a free-text one), so the test handles every version the run or the agent saw, or waits for one control from either version.</p>
-<p>The handoff also lists the browser agent's <strong>checks</strong>: before it finishes, the browser agent records each result the goal asks to verify with the exact text the page showed (<code>record_check</code>; a text the page does not show is refused). They are saved in <code>workflow.yaml</code> under <code>checks:</code>. The test asserts these and nothing else.</p>
-</li>
-<li>
-<p>ForgeQE replays the run's steps as a Playwright script (<code>&lt;run&gt;/replay/flow.mjs</code>), in the run's browser setup (channel, headless or headed, user agent, language, time zone, viewport), with 10 seconds per step. Text is typed key by key, as the browser agent typed it, so search suggestions and other typing handlers fire. If the replay does not reach the run's final page, it runs again without Playwright's automation switches (<code>navigator.webdriver</code> false, as in ForgeQE's browser). The handoff gets the result: which steps worked, and for each failed step, Playwright's reason (for example a dialog that intercepts the click), the page, the dialogs open on it, how many elements each of the element's other locators matched, and a screenshot and page snapshot. It also saves Playwright's page snapshot of each page the replay visited (roles, accessible names, and text, as the replay left the page; the last page once it stops changing), so Scribe takes locators for its steps and assertions from real pages instead of guessing them. On the last page it looks up each of the browser agent's checks and puts the Playwright locator that matched its text into the handoff (a heading or text match, the container it sits in when there are several, or the form field that holds it), so assertions come with a locator that worked. For a heading it also gives the part of the page the heading names (an element labelled by it, the section it heads, or the element right after it), with its locator and how many links and list items it holds, so a check such as &quot;an In the news section with at least one item&quot; is asserted inside that part, not on the heading alone. A step that fails while every step after it still works and the replay reaches the final page (a click that did nothing on the run, or a control this version of the page doesn't have) doesn't count as a failed replay: Scribe decides from the step whether the goal needs it and ports the rest as it is. When only the second launch got through, the handoff says the browser setup is the difference and which launch settings fix it. The first time, Playwright (about 13 MB) is downloaded into <code>~/.forgeqe/tools</code>; it drives the installed Chrome. A run that only opened a page still replays when it recorded checks, to look them up; with neither it skips this, and <code>replay: false</code> turns it off.</p>
-<p>Scribe first reads the repo (as a read-only agent: it cannot change files or use the live browser yet), while the replay runs when there is one, so the two overlap. What it learns (the framework, the command that runs one test, where page objects and config live, the conventions) is saved with page memory in <code>scribe-notes.json</code>, with the tests each job writes there. The next job in the same repo starts from those notes and that list instead of reading the repo again, and extends those tests' page objects when its flow overlaps; notes older than 30 days are read again.</p>
-</li>
-<li>
-<p>Scribe starts in the repo. It reads <code>AGENTS.md</code>, the test framework config, run scripts, page objects, fixtures, and helpers, and follows the imports between them. It writes the test in the repo's language and framework (a C# NUnit repo gets a C# NUnit test) and to fit its code: it extends an existing page object instead of duplicating it and reuses the login flow, test data, and config. A repo with no tests gets Playwright Test in TypeScript. It may change anything the test needs, including dependencies and config.</p>
-<p>Before Scribe starts, ForgeQE reads the repo into a <strong>code graph</strong>, without a model: every class, page object, method, property, and test (TypeScript, JavaScript, C#, Java, Python), the calls between them, and the locators each one builds, in any framework's spelling (Playwright, Selenium, Cypress, WebdriverIO, Testing Library). It is kept in <code>~/.forgeqe/cache/code-graph</code>, nothing leaves the machine, and the next job reads again only the files that changed. The graph is tied to page memory, which knows each element by all its locators (its id, role and name, text, test id): so when the run clicked <code>getByRole('button', { name: 'Login' })</code> and the repo's <code>LoginPage.LoginButton</code> uses <code>#login-button</code>, the handoff says under that step &quot;in this repository: LoginPage.LoginButton … used by LoginPage.SignInAsync&quot;, and Scribe calls the existing method instead of writing a second locator. Scribe also gets tools that answer from the graph instead of grep and whole-file reads: <code>code_find</code> (classes, methods, and tests by name, or by the text a locator uses), <code>code_outline</code> (a file's or class's signatures and locators, or the source of one member), <code>code_element</code> (which member already locates an element), <code>code_references</code> (what calls a member, before it is changed), and <code>code_impact</code> (the tests a change reaches, through flows and base classes, whatever the test files are called). <code>graph: false</code> turns it off. The handoff also outlines the page objects its steps use and includes the repo's test that uses the most of them, so Scribe takes the test conventions from that test instead of reading other tests, and reads a settings file only to change it.</p>
-</li>
-<li>
-<p>It writes the test from the handoff and the replay script: steps that worked are ported with their locators, steps that failed are fixed first. Every locator, including those for assertions, comes from the replay script, the page snapshots, page memory, or a check on the page; steps where the browser agent ran JavaScript to look around are left out. It does not walk the flow again or build tests to explore. Once a step fails (in the replay, or in its test), ForgeQE switches on its live browser: a Chrome that Playwright drives, set up like ForgeQE's, where it looks at the failing step's page one tool call per action (open, snapshot, click, type, wait, screenshot, run JavaScript, console errors, failed requests). Until then the live browser tools are off, so no tokens go into looking at pages that work. The live browser needs Node.js (<code>npx</code>), and Microsoft's Playwright MCP server is downloaded on first use; with <code>live_browser: false</code>, or without <code>npx</code>, it looks with a small throwaway script instead. When its browser gets a different page than ForgeQE's did (an error, a challenge, a control that will not open), it compares the two browsers (user agent, <code>navigator.webdriver</code>, headless, failed requests and CORS errors, headers the framework adds, console errors) and fixes the difference in the repo's browser configuration. It never judges the site with <code>curl</code> or <code>webfetch</code>.</p>
-</li>
-<li>
-<p>Scribe does not run the test itself: it may build or compile, then reports the test file and the command that runs only that test, and ForgeQE runs it. If one command it runs fails <code>stall_after</code> times in a row within its work (the same build again and again, say), ForgeQE stops that turn and sends the command and its last output back, asking it to change approach. If the same command stalls again, the job stops as a failure with that output in the notes.</p>
-</li>
-<li>
-<p>ForgeQE runs that command (with <code>CI=1</code>) and checks the exit code, and it watches the processes the command starts for a browser launched by Playwright, Puppeteer, Selenium, or Cypress. On a failure it sends the command, exit code, and output back to Scribe. The output is kept short so the error is never cut off: the page dump Playwright puts into a failed assertion (&quot;Aria snapshot:&quot;, often thousands of lines) is taken out and saved as <code>&lt;run&gt;/test-runs/attempt-N-page.aria.yml</code>, then the start (where the first error and its stack trace are) and the end (the summary) are sent; the full output is in <code>&lt;run&gt;/test-runs/attempt-N.log</code>, and the prompt names both files. A command that exits 0 without starting a browser also goes back: the test must drive the app in a browser. If the repo's browser runs on another machine (Selenium Grid, a cloud service, a container), the agent says where and the check is skipped.</p>
-</li>
-<li>
-<p>A passing test then goes to a separate reviewer agent, which can read files and <code>git diff</code> but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (<code>.forgeqe/</code>, <code>forgeqe.yaml</code>, <code>llms.json</code>) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same <code>code_*</code> tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt. The terminal shows the exchange as it happens, in order: the reviewer's verdict with its reason and each issue (✗ correctness, ~ coding standard) with the file and the fix it asks for; then why Scribe tries again and what it is fixing (the reviewer's issues, or the test's first error); then what Scribe says it did and which files it changed; then the next verdict:</p>
-</li>
-</ol>
-<pre><code>⏺ Reviewer asked for changes  attempt 1 of 5 · 1 to fix, 1 coding-standard
-  ⎿ The test never checks that the pie chart is shown.
-    ✗ Correctness · tests/PracticeTests.cs: No assertion on the SVG pie chart.
-        Fix: Assert the chart's heading and SVG are visible.
-    ~ Coding standard · tests/PracticeTests.cs: Test data is inline.
-        Fix: Move it to the page object.
-⏺ Scribe tries again · attempt 2 of 5  the reviewer asked for changes
-  ⎿ → tests/PracticeTests.cs: No assertion on the SVG pie chart. — fix: Assert the chart's heading and SVG are visible.
-  ⎿ Scribe (attempt 2): Added the pie chart assertion · changed tests/PracticeTests.cs, Pages/PracticePage.cs
-⏺ Reviewer approved the test  attempt 2 of 5
-</code></pre>
-<p>The Activities panel has one line for each verdict and attempt, and <code>forgeqe</code> commands outside the terminal UI print the same blocks.</p>
-<p>Scribe cannot edit ForgeQE's files or run folders, and cannot run <code>git clean</code>, <code>git reset --hard</code>, <code>git stash</code>, <code>git restore</code>, or <code>git checkout -- &lt;path&gt;</code>. If it still removes a file that existed before the job, or reverts your uncommitted edits, ForgeQE puts the file back after that attempt and tells the agent.
-8. The job is done when ForgeQE's run passes with a browser and the reviewer approves. It stops as a failure after <code>max_attempts</code> attempts, when the job passes <code>code.max_tokens</code>, when the reviewer rejects a passing test twice, if the review cannot finish, when the test fails the same way three times in a row (the same output apart from numbers such as timings and line numbers; the second time, Scribe is told its change did not change the failure and to look at the failing step before changing code), or straight away on an auth, API, or context-limit error from the model.</p>
-<p><code>blocked</code> is a last resort. The first time the agent reports that the app blocks it, ForgeQE sends it back to compare its browser with ForgeQE's and fix the difference; only a second blocked report, with what it compared, ends the job as blocked.</p>
-<p>The transcript shows the handover and Scribe's work as it goes; files it writes or edits are marked ✎:</p>
-<pre><code>┃
-┃  ▸ Handing over to the coding agent                         browser agent → coding agent
-┃
-┃  Flow      Log in and open the invoices page on staging.app.test
-┃  Run       .forgeqe/reports/20260928-172700/
-┃  Repo      ../app
-┃
-  ▸ Handoff written: .forgeqe/reports/20260928-172700/handoff.md (7 steps, 3 pages from page memory)
-  ▸ Scribe, the coding agent (azure/gpt-5.4), reads the handoff and writes a test in /work/app
-    ⚙ Reading .forgeqe/reports/20260928-172700/handoff.md
-    ⚙ Reading tests/pages/LoginPage.ts
-    ✎ Editing tests/invoices.spec.ts
-    ⚙ Running npx playwright test tests/invoices.spec.ts
-  ▸ ForgeQE runs the test: npx playwright test tests/invoices.spec.ts
-  ✗ tests/invoices.spec.ts failed, exit 1 (attempt 1/5)
-  ▸ tests/invoices.spec.ts passed in 9s in Google Chrome; a reviewer checks it against the goal
-  ✓ tests/invoices.spec.ts passed and was approved (attempt 2/5)
-┃
-┃  ✓ Test passed                          2/5 attempts · 3m 12s · 88.4K tokens · azure/gpt-5.4
-┃
-┃  Added openInvoices() to DashboardPage and reused the loginAs fixture.
-┃
-┃  Test      tests/invoices.spec.ts  (in ../app)
-┃  Command   npx playwright test tests/invoices.spec.ts
-┃  Reused    LoginPage, fixtures/auth.ts
-┃  Changed   tests/invoices.spec.ts, tests/pages/DashboardPage.ts
-┃  Browser   Google Chrome
-┃  Review    approved: Opens the invoices page through the dashboard and checks the table columns.
-</code></pre>
-<p>After ForgeQE's reply, the request ends with the files it produced:</p>
-<pre><code>┃  ✓ What this produced
-┃
-┃    Report    .forgeqe/reports/20260928-172700/report.html
-┃  ✓ Test      ../app/tests/invoices.spec.ts  passed when ForgeQE ran it
-┃    Command   npx playwright test tests/invoices.spec.ts
-┃    Handoff   .forgeqe/reports/20260928-172700/handoff.md
-</code></pre>
-<p>When no test was written, the Test row says why: the run did not pass, the session has <code>--no-code</code>, or the run was not handed to the coding agent.</p>
-<p>Scribe uses the active <code>llms.json</code> profile. The key stays in your environment: the agent runtime's config refers to it as <code>{env:WP_AZURE_API_KEY}</code> and never contains the value. An <code>auth: entra</code> profile reaches the model through ForgeQE's local token gateway (see <a href="../#signing-in-to-the-model-without-a-key-microsoft-entra-id">Signing in to the model without a key</a>). An Azure profile goes through the agent runtime's <code>azure</code> provider on <code>&lt;endpoint&gt;/openai/v1</code> (the Responses API, with the deployment as the model). <code>openai_compatible</code> and <code>ollama</code> profiles use their <code>base_url</code>. <code>code.model: provider/model</code> (or <code>--code-model</code>) uses one of the agent runtime's built-in providers instead, with that provider's usual key variable (for example <code>ANTHROPIC_API_KEY</code> for <code>anthropic/...</code>).</p>
-<p>Scribe may edit files and run commands anywhere in the repo without asking. <code>git push</code> in any form is denied (pushing goes through ForgeQE's guarded <code>push_branch</code> tool, section 8), and it cannot touch files outside the repo except the run and memory directories, which it may read.</p>
-<p>More ways to run it:</p>
-<pre><code class="language-bash">forgeqe code --repo ../app                                 # the latest run in .forgeqe/reports/
-forgeqe code .forgeqe/reports/20260928-172700 --repo ../app --attempts 3
-forgeqe run &quot;...&quot; --no-code                                # no tests for this request
-</code></pre>
-<p>In the shell, <code>forgeqe start --repo ../app</code> writes the tests in that repo instead of the current folder and <code>--no-code</code> turns them off; you can also just ask (&quot;write a test for the last run in ../app&quot;). Esc stops the agent the same way it stops a run.</p>
-<p>Exit codes for <code>forgeqe code</code> and for <code>forgeqe run --direct</code> with a repo: <code>0</code> test passed, <code>1</code> run or test failed, <code>2</code> stopped. The result (status, attempts, test file, command, what was reused and changed, the browsers ForgeQE saw, the review, the last test output, tokens) is saved as <code>code.json</code> in the run directory, next to <code>handoff.md</code>.</p>
-<p>If Scribe's job is cut off (ForgeQE closed, the machine restarted, you stopped it, or the model could not be reached), run it again for the same run and repo, for example <code>forgeqe code .forgeqe/reports/20260928-172700 --repo ../app</code>. Scribe reopens the same session, with everything it read and said, and carries on with the files it already wrote; it doesn't read the repo again, and ForgeQE uses the Playwright replay it already finished. The session is kept in <code>scribe-session.json</code> in the run folder until the job ends with a result.</p>
+<section class="doc" id="doc-how_to_use-environments-and-apps">
+<h4>Environments and apps</h4>
+<div class="prose"><p><code>env.yaml</code> (written by <code>forgeqe init</code>, named in forgeqe.yaml <code>environments.file</code>) lists your test environments and the
+apps in each: web apps by URL, APIs by base URL, Windows desktop apps by <code>.exe</code>, and mobile apps by package id, each
+with a short description of what it is for. Plain values go under <code>variables</code>; secrets never do, only the names of the
+environment variables that hold them, under <code>secrets</code>.</p>
+<pre><code class="language-yaml">default: qa
+environments:
+  qa:
+    start_app: shop
+    apps:
+      shop:    { kind: web, url: &quot;https://qa.shop.example.com&quot;, description: Customer web shop where orders are placed }
+      orders:  { kind: api, url: &quot;https://qa.api.example.com/v1&quot;, description: Orders REST API }
+      billing: { kind: desktop, path: 'C:\Program Files\Contoso\Billing\Billing.exe', args: [&quot;--server&quot;, &quot;qa-db01&quot;], description: Back-office invoicing }
+    variables: { company: Contoso QA }
+    secrets: [BILLING_PASSWORD_QA]
+  uat:
+    apps: { ... }
+</code></pre>
+<p>Your test cases stay the same in every environment; only where they run changes. The environment supplies the URLs,
+executables, accounts and values, and the same test, workflow or scenario runs against QA or UAT.</p>
+<p><strong>Any layout works.</strong> The layout above is ForgeQE's own, but an <code>env.yaml</code> your team already keeps is read as it is:</p>
+<ul>
+<li>environments under <code>environments:</code> / <code>envs:</code>, as a list with a <code>name</code> each, or as top-level keys (<code>qa:</code>, <code>uat:</code>);
+or one file per environment with <code>environments.dir</code> in forgeqe.yaml</li>
+<li>a <code>common:</code> / <code>defaults:</code> / <code>shared:</code> block merged into each environment</li>
+<li>any <code>http(s)</code> URL becomes a web app (an API when its key or path says api); an absolute <code>.exe</code> becomes a desktop app
+(with a sibling <code>args</code>); other values become variables</li>
+<li>secrets: keys like <code>password</code>, <code>token</code> or <code>api_key</code> are never shown to a model. A reference (<code>${BILLING_PW}</code>,
+<code>env:BILLING_PW</code>, <code>%BILLING_PW%</code>) is recorded as a secret name; a literal value is replaced with <code>&lt;redacted&gt;</code></li>
+</ul>
+<pre><code class="language-yaml">common: { company: Contoso }
+qa:
+  url: https://qa.shop.example.com
+  orders_api: https://qa.api.example.com/v1
+  billing_exe: 'C:\Program Files\Contoso\Billing\Billing.exe'
+  db_password: ${BILLING_DB_PW_QA}
+uat:
+  url: https://uat.shop.example.com
+</code></pre>
+<p>ForgeQE's agent also sees the environment as written (secrets replaced), so a request can name anything in it (&quot;log in
+as the <code>admin_user</code> of UAT&quot;).</p>
+<p>Pick the environment with <code>--env uat</code> on any command (<code>forgeqe start</code>, <code>run</code>, <code>suite</code>, <code>monitor</code>, <code>mcp</code>, …) or
+<code>FORGEQE_ENV=uat</code>; otherwise <code>default</code> is used. In the shell, <code>/env</code> lists them and <code>/env uat</code> switches; asked in plain
+language (&quot;from now on, use UAT&quot;), ForgeQE's agent switches with <code>use_environment</code>, and any single request can name an
+environment (&quot;run the checkout tests in UAT&quot;): each test tool takes an <code>env</code> for that call only. <code>forgeqe apps</code> lists the environments and the active one's apps.</p>
+<p>What each agent gets from the active environment:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Agent</th><th>What it uses</th></tr>
+</thead>
+<tbody>
+<tr><td>ForgeQE's agent</td><td>The environment, its apps (with descriptions) and values in its session notes; plans scenarios across apps from them and carries values (an order number) between them</td></tr>
+<tr><td>Browser agent</td><td>Starts at <code>start_app</code> when no URL is given; knows the environment's web apps by name and stays on their hosts; its values</td></tr>
+<tr><td>API tests</td><td>Call <code>api_app</code>'s URL</td></tr>
+<tr><td>Desktop agent</td><td>Starts the environment's desktop apps; types only its <code>secrets</code></td></tr>
+<tr><td>Scribe, the healer, the reviewer</td><td>Write tests that read <code>FORGEQE_APP_&lt;APP&gt;_URL</code> (or the repository's own settings), never a fixed environment URL; the reviewer flags one</td></tr>
+<tr><td>Tests ForgeQE runs, pack pipelines</td><td><code>FORGEQE_ACTIVE_ENV</code>, <code>FORGEQE_APP_&lt;APP&gt;_URL</code> / <code>_PATH</code> / <code>_ID</code>, <code>FORGEQE_VAR_&lt;NAME&gt;</code> (pipelines written by <code>forgeqe pack pipeline init</code> take them as the <code>env_vars</code> input)</td></tr>
+<tr><td>Reports</td><td>Every run's report names the test environment</td></tr>
+</tbody>
+</table></div>
+<p>There is no scenario file to write: ask in plain language (&quot;place an order in the shop, then check its invoice in
+Billing, in UAT&quot;) and ForgeQE's agent picks the apps from their descriptions, shows the plan, runs each step with the
+right engine, and carries values from one app to the next.</p>
 </div>
 </section>
 </div>
 </article>
-<article class="spec feat" id="cap-heal-tests">
-<div class="hd"><span class="mono">Automated tests</span><h3>Heal failing tests</h3></div>
-<p class="ds">Runs a repository's tests and updates the ones the application has outgrown against the live app, or reports a real application bug instead.</p>
+<article class="spec feat" id="cap-setup-help">
+<div class="hd"><span class="mono">Setup</span><h3>Setup, skills, and documentation</h3></div>
+<p class="ds">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.</p>
 <div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Heal the failing tests in ../app</li></ul></div>
-<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs</span></li><li><span class="need input">You give</span><span>a repository with tests</span></li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>heal_tests</code></p></div>
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>What can you do?</li><li>Which model am I using?</li><li>How do I set up email alerts?</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><p class="muted">Nothing beyond ForgeQE itself.</p></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>forgeqe_setup</code> <code>capabilities</code> <code>playbook</code> <code>use_capabilities</code></p></div>
 </div>
 <div class="detail"><span class="mono">In detail</span>
-<section class="doc" id="doc-how_to_use-fixing-broken-tests">
-<h4>Fixing broken tests</h4>
-<div class="prose"><p>When a redesign or a renamed button breaks tests, <code>forgeqe heal</code> fixes them, or tells you the app is what broke:</p>
-<pre><code class="language-bash">forgeqe heal --repo ../app                               # the command from code.test_command, or the agent finds it
-forgeqe heal &quot;npx playwright test tests/checkout&quot; --repo ../app
-forgeqe heal -- npx playwright test --project=chromium   # everything after -- is the command
-</code></pre>
-<pre><code class="language-yaml">code:
-  repo: ../app
-  test_command: npx playwright test   # optional
+<p class="see">See <a href="#doc-how_to_use-2-scaffold-config">2. Scaffold config</a>.</p>
+<section class="doc" id="doc-how_to_use-11-skills">
+<h4>Skills</h4>
+<div class="prose"><p>A skill is a folder with a <code>SKILL.md</code>: instructions that teach ForgeQE's agents something a prompt can't know, like your repo's test conventions, a framework, or how to drive an app such as Dynamics 365. The format is the Agent Skills one (Claude Code and others use it), with one ForgeQE field, <code>agents</code>:</p>
+<pre><code class="language-markdown">---
+name: contoso-erp
+description: &quot;Use when the site is the Contoso ERP (erp.contoso.com): the order grid, the customer lookup, and saving orders.&quot;
+agents: [browser]
+---
+
+- The customer lookup opens a list after three letters; click the row whose name matches exactly.
+- Save with the floppy icon in the toolbar; wait until &quot;Saved&quot; shows in the status bar.
 </code></pre>
-<ol>
-<li>ForgeQE runs the command. If it passes, there is nothing to heal and no model is called.</li>
-<li>Scribe starts in the repo as a healing agent, with the failing output. For each failing test it reads the test and the page objects it uses, then re-runs the test's flow in the real browser with ForgeQE's <code>browser_run</code> (the goal in plain words, not the old selectors).</li>
-<li>If the browser run passes, the test is out of date. The agent reads that run's steps and locators with <code>run_details</code>, updates the test (in the page object when the locators live there), and runs it with <code>run_test</code>.</li>
-<li>If the browser run fails at the step where the test fails, the app is broken there. The test is left as it is and the failure is reported as an app bug.</li>
-<li>It never deletes or skips a test, loosens an assertion, or raises a timeout to make a test pass.</li>
-<li>ForgeQE runs each healed test's own command, then the whole command. A healed test that still fails goes back to the agent with the output, and so does any other failure left in the whole run, until everything passes or <code>code.max_attempts</code> rounds are used.</li>
-</ol>
-<pre><code>  ▸ ForgeQE runs the tests: npx playwright test
-  ✗ Tests failed, exit 1 (41s)
-  ▸ Scribe (azure/gpt-5.4) is healing the failing tests in app
-    ⚙ read tests/pages/LoginPage.ts
-  ▸ Browser: Sign in to staging.app.test and open the invoices page
-  ✓ Task complete · 9 steps
-    ⚙ edit tests/pages/LoginPage.ts
-  ▸ ForgeQE runs: npx playwright test tests/login.spec.ts
-  ✓ login › signs in passed in 6s
-  ▸ ForgeQE runs the tests: npx playwright test
-  ✗ Tests still fail, exit 1 (39s)
-┃
-┃  ✗ Tests still failing                   2/5 attempts · 2m 40s · 61.2K tokens · azure/gpt-5.4
-┃
-┃  ✓ login › signs in  healed
-┃      The Sign in button is now &quot;Log in&quot;; LoginPage uses the new label
-┃  ! invoices › totals  app bug
-┃      The total column is empty; the browser run failed at the same step
-┃
-┃  1 failure is in the app, not the tests; the tests were left as they are.
-┃  Command   npx playwright test  (exit 1 after 39s)
-┃  Changed   tests/pages/LoginPage.ts
-┃  Report    .forgeqe/reports/heal/20260929-101500/heal.md
+<p><code>name</code> is lowercase words joined by hyphens, the same as the folder. Agents choose skills by <code>description</code> alone, so name the concrete signs it applies (a framework, a config file, a host, a product). Quote it when it contains <code>: </code>.</p>
+<p><strong>Who uses it.</strong> <code>agents</code> lists <code>forgeqe</code> (ForgeQE's agent: how to handle a kind of request), <code>scribe</code> (writing, healing, finding and reviewing tests), and <code>browser</code> (the browser agent). Without <code>agents</code>, a skill is for <code>forgeqe</code> and <code>scribe</code>; a browser skill must ask for <code>browser</code>.</p>
+<p><strong>How skills are used.</strong></p>
+<ul>
+<li>ForgeQE's agent and Scribe see the name and description of each skill meant for them, and load the ones that fit the job through the agent runtime's skill tool. A skill adds to their instructions and never overrides them. Scribe can also read files next to <code>SKILL.md</code> (for example <code>references/locators.md</code>) when the skill points to them.</li>
+<li>Browser runs: ForgeQE's agent passes the browser skills a goal needs to <code>browser_run</code> and <code>run_test_cases</code>. For <code>forgeqe suite</code>, <code>forgeqe monitor</code> and <code>forgeqe run --direct</code>, the engine picks them from the goal with one short model call (at most three), and remembers the choice for that goal, so a monitor's later rounds and repeated cases skip it. <code>--skill NAME</code> (repeatable) fixes the list; <code>--skill none</code> runs without any. The chosen skills' text is added to the browser agent's prompt, at most <code>skills.browser_max_chars</code> (6,000) characters in total; the browser agent reads only <code>SKILL.md</code>.</li>
+<li><code>run.json</code>, the <code>run.done</code> log line and the report list the skills a run used.</li>
+</ul>
+<p><strong>Where skills come from</strong>, lowest to highest precedence; a later source replaces a skill of the same name:</p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Source</th><th>Folder</th></tr>
+</thead>
+<tbody>
+<tr><td>Built-in</td><td>the <code>skills/</code> folder ForgeQE ships: <code>playwright-typescript</code> and <code>dotnet-nunit-playwright</code> (Scribe), <code>dynamics-365</code> (browser), <code>writing-skills</code> (ForgeQE's agent)</td></tr>
+<tr><td>Global, only with <code>skills.external: true</code></td><td><code>~/.claude/skills</code>, <code>~/.agents/skills</code>, and the repo's <code>.claude/skills</code> and <code>.agents/skills</code></td></tr>
+<tr><td>User</td><td><code>~/.forgeqe/skills</code> (or <code>$FORGEQE_HOME/skills</code>)</td></tr>
+<tr><td>Project</td><td><code>.forgeqe/skills</code> next to <code>forgeqe.yaml</code>, and the repo's own <code>.forgeqe/skills</code></td></tr>
+<tr><td>Extra</td><td>each folder in <code>skills.dirs</code></td></tr>
+</tbody>
+</table></div>
+<p>Commit <code>.forgeqe/skills</code> so the team and CI share it. ForgeQE only ignores <code>.forgeqe/reports/</code>; if your <code>.gitignore</code> has <code>.forgeqe/</code>, replace it with <code>.forgeqe/*</code> and <code>!.forgeqe/skills/</code> (<code>forgeqe skills new</code> warns when git would ignore the new skill). To change a built-in skill, make a project skill with the same name.</p>
+<p>Skills from anywhere else stay out: the agent runtime's own discovery (<code>~/.claude/skills</code>, a repo's <code>.opencode/skills</code>, its built-in skills) is off, and each agent may load only the skills ForgeQE's registry gives it. Skill text is trusted like the repo's own files, so global skills are opt-in.</p>
+<pre><code class="language-yaml">skills:
+  enabled: true              # false (or skills: false) turns skills off
+  dirs: [../shared-skills]   # more folders, read last
+  disable: [dynamics-365]    # leave these out
+  external: false            # true: also the global folders above
+  browser_max_chars: 6000    # most skill text added to one browser run
 </code></pre>
-<p>The report is <code>heal.md</code> and <code>heal.json</code> in <code>.forgeqe/reports/heal/&lt;time&gt;/</code>: each test's verdict and reason, the files changed, the browser runs (their folders sit next to the report), and the test output before and after. Exit codes: <code>0</code> the tests pass (or nothing needed healing), <code>1</code> some still fail, <code>2</code> stopped. In the shell or with <code>forgeqe run</code>, &quot;the checkout tests are failing after the redesign, fix them&quot; does the same through ForgeQE's agent.</p>
+<p><strong>Commands.</strong></p>
+<div class="tbl"><table>
+<thead>
+<tr><th>Command</th><th>What it does</th></tr>
+</thead>
+<tbody>
+<tr><td><code>forgeqe skills</code></td><td>The skills each agent can use, where each comes from (and what it replaces), disabled skills, problems, and the folders read</td></tr>
+<tr><td><code>forgeqe skills show &lt;name&gt;</code></td><td>One skill's instructions</td></tr>
+<tr><td><code>forgeqe skills new &lt;name&gt; --description &quot;Use when …&quot; [--agent browser] [--user]</code></td><td>Start a skill in <code>.forgeqe/skills</code> (<code>--user</code>: <code>~/.forgeqe/skills</code>)</td></tr>
+<tr><td><code>forgeqe skills check</code></td><td>Validate every skill; exit 1 when one has a problem</td></tr>
+<tr><td><code>forgeqe skills enable|disable &lt;name&gt;</code></td><td>Edit <code>skills.disable</code> in <code>forgeqe.yaml</code>, keeping its comments</td></tr>
+<tr><td><code>/skills [name]</code></td><td>The same list, or one skill, in the shell</td></tr>
+</tbody>
+</table></div>
+<p>In the shell you can also ask: &quot;make a skill for our Dynamics date picker&quot; or &quot;teach Scribe our test conventions&quot;. ForgeQE's agent gathers the facts, writes the skill into <code>.forgeqe/skills</code> with <code>forgeqe_setup</code>, and it applies from the next session. It writes skills only when you ask.</p>
 </div>
 </section>
 </div>
 </article>
-<article class="spec feat" id="cap-find-run-tests">
+</section>
+<section class="chapter" id="area-desktop" aria-labelledby="area-desktop-h">
+<header class="chead"><span class="mono">07</span><h2 id="area-desktop-h">Desktop</h2><p>Windows thick-client apps: explore a goal, record by hand, replay the saved workflow</p></header>
+<article class="spec feat" id="cap-desktop-apps">
+<div class="hd"><span class="mono">Desktop</span><h3>Automate Windows desktop apps</h3></div>
+<p class="ds">Carries out a plain-language goal in a Windows thick-client app with UFO² and saves it as a workflow with checks of the outcome, or records the steps a tester does by hand, with no model; replays saved workflows with no model, healing a step whose control moved, and fixes a workflow from chat (a timeout, a wait, a dialog to dismiss) after showing the change. Apps and the secrets they may type come from env.yaml or forgeqe.yaml desktop:.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Create an invoice for Contoso in the Billing app and save it as a test</li><li>I'll show you the steps in Billing: record them</li><li>Replay the billing workflow with customer Fabrikam</li><li>Step 4 timed out while the list loaded: fix the workflow</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>A live model profile in llms.json (an API key or Microsoft Entra ID sign-in)</span></li><li><span class="need req">Required</span><span>Windows desktop apps: env.yaml (kind: desktop) or desktop.apps in forgeqe.yaml</span></li><li><span class="need input">You give</span><span>a Windows machine, and the app in forgeqe.yaml desktop.apps</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>Windows only, one run at a time per desktop</li><li>Apps whose controls UI Automation cannot see (Citrix, some Java and custom-drawn apps) are not supported yet</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>desktop_explore</code> <code>desktop_record</code> <code>desktop_replay</code> <code>desktop_edit_workflow</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-desktop-apps-windows">
+<h4>Desktop apps (Windows)</h4>
+<div class="prose"><p>ForgeQE also automates Windows thick-client apps (Win32, WinForms, WPF). In the shell, ask for a goal in the app
+(&quot;create an invoice for Contoso in Billing&quot;) and ForgeQE's agent uses UFO² to do it, saves the run as a workflow with
+checks of the outcome, and can replay it with no model. The same from the command line:</p>
+<pre><code class="language-bash">forgeqe desktop setup --ufo
+forgeqe desktop explore &quot;Create an invoice for Contoso, net 30&quot; --app billing
+forgeqe desktop record --app billing                           # or do the steps yourself; no model
+forgeqe desktop replay &lt;run folder&gt;/workflow.yaml customer=Fabrikam
+forgeqe desktop replay workflow.yaml --data customers.csv     # once per row; columns are variable names
+forgeqe desktop replay desktop-tests/ --junit results.xml      # every workflow in a folder, results for CI
+forgeqe desktop doctor                                         # can this machine replay unattended?
+</code></pre>
+<p>Workflows wait for slow apps without fixed sleeps: a <code>timeout</code> and <code>retries</code> for the workflow or a step, <code>wait_for</code> a
+control to appear, show a text or go away (a splash screen), and a <code>dismiss</code> list of dialog buttons to click whenever
+they are in the way. <code>expect_image</code> compares a control or window with a baseline image (saved on the first run, kept
+next to the workflow), with a tolerance and regions to ignore. When you know the steps, <code>forgeqe desktop record</code> (or
+&quot;I'll show you, record it&quot; in the shell) saves what you do by hand: Ctrl+Shift+F11 over a control adds a check of its
+text, Ctrl+Shift+F12 finishes. After a failed replay, ForgeQE's agent can fix the workflow (a longer timeout, a
+<code>wait_for</code>, a dialog to dismiss): it shows the diff and writes it only when you agree. For nightly runs on a machine
+of your own, see <a href="../docs/DESKTOP-CI.md">docs/DESKTOP-CI.md</a>.</p>
+<p>Apps come from <code>desktop.apps</code> in forgeqe.yaml (an absolute <code>.exe</code> and an argument list), and <code>{{secret:NAME}}</code> reads
+only the variables listed in <code>desktop.secrets</code>. Explore and replay take over the desktop's mouse and keyboard and ask
+first; use a test machine and a test account. Details: <a href="../docs/DESKTOP.md">docs/DESKTOP.md</a>.</p>
+</div>
+</section>
+</div>
+</article>
+</section>
+<section class="chapter" id="area-mobile" aria-labelledby="area-mobile-h">
+<header class="chead"><span class="mono">08</span><h2 id="area-mobile-h">Mobile</h2><p>Android and iOS apps through Appium or Maestro: explore a goal, replay, run the team's flows</p></header>
+<article class="spec feat" id="cap-mobile-apps">
+<div class="hd"><span class="mono">Mobile</span><h3>Automate Android and iOS apps</h3></div>
+<p class="ds">Carries out a plain-language goal in an Android or iOS app through Appium and saves it as a mobile workflow with checks of the outcome; replays workflows with no model on Appium (healing a moved control) or Maestro; runs the team's own Maestro flows after checking them against an allowlist. Apps come from env.yaml (kind: mobile) or forgeqe.yaml mobile:.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Sign in to the courier app and accept the first delivery, and save it as a test</li><li>Replay the courier login on Maestro</li><li>Run our Maestro flows in .maestro/</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need opt">Optional</span><span>A live model profile in llms.json (an API key or Microsoft Entra ID sign-in)</span></li><li><span class="need req">Required</span><span>Mobile apps: env.yaml (kind: mobile) or mobile.apps in forgeqe.yaml</span></li><li><span class="need input">You give</span><span>an Appium server with a device or emulator (or a device cloud), or Maestro installed; the app in env.yaml or forgeqe.yaml mobile.apps</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>Explore runs on Appium only</li><li>Maestro replays do not heal moved controls or compare images (expect_image)</li><li>On TestMu AI, Maestro (through HyperExecute) refuses workflows that type secrets; replay those there with --driver appium</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>mobile_explore</code> <code>mobile_replay</code> <code>mobile_maestro</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-mobile-apps-android-ios">
+<h4>Mobile apps (Android, iOS)</h4>
+<div class="prose"><p>ForgeQE drives Android and iOS apps two ways: through <strong>Appium</strong>, step by step (it can explore a goal with the model,
+and heals a control that moved), and through <strong>Maestro</strong> (fast replays, and your team's own Maestro flows). In the shell,
+ask for a goal in the app (&quot;sign in to the courier app and accept the first delivery&quot;) and ForgeQE's agent explores it
+on your device or emulator and saves a workflow with checks of the outcome. The same from the command line:</p>
+<pre><code class="language-bash">forgeqe mobile doctor                                         # does the Appium server answer, is maestro installed?
+forgeqe mobile explore &quot;Sign in and accept the first delivery&quot; --app courier
+forgeqe mobile replay &lt;run folder&gt;/workflow.yaml              # on Appium (mobile.driver), healing moved controls
+forgeqe mobile replay workflow.yaml --driver maestro          # the same workflow as a Maestro flow
+forgeqe mobile replay mobile-tests/ --junit results.xml       # every workflow in a folder, results for CI
+forgeqe mobile maestro .maestro/                              # your team's Maestro flows, checked first
+forgeqe mobile flow workflow.yaml &gt; login.flow.yaml           # a workflow as a Maestro flow, to keep
+</code></pre>
+<p>Apps come from env.yaml (<code>kind: mobile</code>, <code>platform: android</code> or <code>ios</code>, <code>app_id</code>, and optionally <code>activity</code> and an
+<code>app</code> build to install) or <code>mobile.apps</code> in forgeqe.yaml. <code>mobile.appium</code> names the Appium server (default
+<code>http://127.0.0.1:4723</code>, or a device cloud's hub with its user and key in environment variables), and <code>{{secret:NAME}}</code>
+reads only <code>mobile.secrets</code> (and the environment's secrets). Team Maestro flows run only with UI commands: scripts,
+JavaScript in <code>${…}</code>, Maestro's AI commands and file writes are refused. Details: <a href="../docs/MOBILE.md">docs/MOBILE.md</a>.</p>
+<h5>On TestMu AI (formerly LambdaTest)</h5>
+<p>Both drivers run on TestMu AI's devices. Upload the app build once, then use the <code>lt://</code> id it prints as the app's <code>app</code>
+(in env.yaml or <code>mobile.apps</code>; ForgeQE adds it to Appium's <code>LT:Options</code> itself):</p>
+<pre><code class="language-bash">forgeqe mobile upload courier.apk                             # prints lt://APP…, for TestMu's real devices
+forgeqe mobile upload courier.apk --virtual                   # for TestMu's emulators and simulators instead
+forgeqe mobile upload courier.apk --name courier-nightly      # the name TestMu shows for the build
+</code></pre>
+<p>The user name and access key come from <code>LT_USERNAME</code> and <code>LT_ACCESS_KEY</code> (or the variables <code>username_env</code> and
+<code>access_key_env</code> name), for example in a <code>.env</code> file in the project folder. They go only to the mobile engine, never to
+a flow or a model, and a user or key in the hub URL is refused.</p>
+<pre><code class="language-yaml">mobile:
+  apps:
+    courier: { platform: android, app_id: com.contoso.courier, app: &quot;lt://APP1016…&quot; }
+  appium:                                   # Appium on TestMu's mobile hub
+    url: https://mobile-hub.lambdatest.com/wd/hub
+    username_env: LT_USERNAME
+    access_key_env: LT_ACCESS_KEY
+    capabilities:
+      &quot;LT:Options&quot;: { w3c: true, isRealMobile: true, deviceName: &quot;Pixel 6&quot;, platformVersion: &quot;14&quot; }
+  maestro:
+    testmu:                                 # Maestro on TestMu, through HyperExecute
+      cli: ./hyperexecute                   # TestMu's hyperexecute CLI
+      devices: [&quot;Pixel 6-14&quot;]               # name-version, or a pattern such as &quot;.*-.*&quot;
+      real_device: true                     # false: TestMu's emulators
+</code></pre>
+<ul>
+<li><strong>Appium</strong> needs nothing else: it talks to the hub with the user and key from the two variables.</li>
+<li><strong>Maestro runs through HyperExecute.</strong> <code>mobile.maestro.testmu</code> names TestMu's <code>hyperexecute</code> CLI (<code>cli</code>), the devices
+to run on (<code>devices</code>), and real devices or emulators (<code>real_device</code>). ForgeQE writes a HyperExecute project in the run
+folder (the flows in their folder layout, so <code>runFlow</code> still works, the app, fixed setup and run scripts, and
+<code>hyperexecute.yaml</code>) and starts the CLI. Team flows are checked against the allowlist first, as always. The access key
+is removed from the CLI's output and from every file in the run folder; the run prints the HyperExecute job link.</li>
+<li><strong>Secrets:</strong> a workflow that types a secret is refused on Maestro on TestMu (HyperExecute would need the value in its
+own vault). Replay it on TestMu with <code>--driver appium</code> instead. Maestro on TestMu runs Android apps; run iOS apps
+there through Appium.</li>
+</ul>
+<p><a href="../samples/mobile-testmu/README.md">samples/mobile-testmu</a> is a ready project with TestMu's Wikipedia sample app: copy
+<code>.env.example</code> to <code>.env</code>, upload the app with <code>forgeqe mobile upload sample.apk</code>, put the id in its <code>forgeqe.yaml</code>,
+download the <code>hyperexecute</code> CLI into the folder, then run <code>forgeqe mobile replay wiki.yaml --driver appium</code>,
+<code>--driver maestro</code>, and <code>forgeqe mobile maestro .maestro</code>. Details: <a href="../docs/MOBILE.md#testmu-ai-formerly-lambdatest">docs/MOBILE.md</a>.</p>
+</div>
+</section>
+</div>
+</article>
+</section>
+<section class="chapter" id="area-operations" aria-labelledby="area-operations-h">
+<header class="chead"><span class="mono">09</span><h2 id="area-operations-h">Operations</h2><p>Monitoring and CI pipelines</p></header>
+<article class="spec feat" id="cap-containers">
+<div class="hd"><span class="mono">Operations</span><h3>Services and mocks in Docker or Podman</h3></div>
+<p class="ds">Starts the services a test run needs (a database, a queue, the API under test) in Docker or Podman, as forgeqe.yaml declares them, and waits until each is ready; stops them, and shows their status and logs. Starts mocks of an API on WireMock, from the calls a browser run recorded or from an OpenAPI description, and can point an API app of the environment at the mock for the session.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Start the database and the queue in Docker</li><li>Start the services from our docker-compose file</li><li>Mock the payments API from the last run</li><li>Create a mock service from openapi.yaml and point order-api at it</li><li>Show the logs of the db container</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>Docker or Podman on PATH; the services to start in containers.services in forgeqe.yaml (mocks need none)</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>Starts only services declared in forgeqe.yaml containers.services; it never runs an image, flag or mount from a request</li><li>No privileged containers, host network, or access to the container runtime's socket; ports on 127.0.0.1 only; mounts read-only from inside the project</li><li>Mocks answer REST calls (WireMock); GraphQL, SOAP and gRPC are not mocked</li><li>Reads docker-compose files only for their services' image, ports, environment, bind mounts, command and depends_on; refuses build, privileged, network_mode, cap_add, devices and env_file; leaves named volumes out</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>services</code> <code>mock_service</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-containers-and-mock-services">
+<h4>Containers and mock services</h4>
+<div class="prose"><p>When Docker or Podman is installed, ForgeQE can start the services a test run needs, and mock an API the tests should
+not call. Ask in the shell: &quot;start the database and the queue&quot;, &quot;mock the payments API from the last run&quot;, &quot;make a mock
+from openapi.yaml and point order-api at it&quot;, &quot;show the db logs&quot;. Full reference: <a href="../docs/CONTAINERS.md">docs/CONTAINERS.md</a>.</p>
+<p>The project declares its services in forgeqe.yaml. ForgeQE starts only these, and builds each command itself:</p>
+<pre><code class="language-yaml">containers:
+  # runtime: podman                     # default: docker, else podman, on PATH
+  services:
+    db:
+      image: postgres:16.4              # an exact version or a digest; never latest
+      ports: [5432]                     # or &quot;15432:5432&quot; (this machine:container); always 127.0.0.1
+      env: { POSTGRES_DB: shop, POSTGRES_USER: shop }
+      secrets: [POSTGRES_PASSWORD]      # names of environment variables (.env works), passed by name
+      volumes: [&quot;./db/init:/docker-entrypoint-initdb.d&quot;]   # read-only, inside the project
+      ready: { tcp: 5432 }              # or { http: /health, port: 8080 }
+      timeout: 90
+</code></pre>
+<pre><code class="language-bash">forgeqe services                 # declared services, what runs, whether Docker answers
+forgeqe services up db           # start and wait until ready; keeps running after the command
+forgeqe services logs db --lines 50
+forgeqe services down            # stop this project's containers, mocks included
+</code></pre>
+<ul>
+<li><strong>Mocks:</strong> <code>mock_service</code> builds WireMock stubs. From a run, they answer what the app really got. From an
+OpenAPI or Swagger description, or a contract set, they answer with its examples, or values made from its schemas. The mock
+runs on a free port of 127.0.0.1 (<code>wiremock/wiremock:3.9.1</code>, or <code>containers.mock.image</code>), and its stubs are in
+<code>.forgeqe/mocks/&lt;name&gt;/mappings</code>. With <code>for_app</code>, an API app of the active environment points at the mock for the
+rest of the session, so API tests and the tests ForgeQE runs (<code>FORGEQE_APP_&lt;APP&gt;_URL</code>) use it.</li>
+<li><strong>Session:</strong> what the agent starts (services or mocks) stops when the shell, <code>forgeqe run</code>, or <code>forgeqe mcp</code> ends.
+<code>forgeqe services up</code> keeps its services running until <code>forgeqe services down</code>.</li>
+<li><strong>Asked first:</strong> <code>services up</code> and <code>mock_service</code> ask before they start anything.</li>
+</ul>
+<p>Guard rails:</p>
+<ul>
+<li><strong>Fixed run settings:</strong> every container gets no new privileges, a process limit, ports on 127.0.0.1, read-only
+mounts, and labels with the project, so ForgeQE stops only its own containers.</li>
+<li><strong>Refused service settings:</strong> <code>privileged</code>, <code>network</code>, <code>cap_add</code>, <code>devices</code>, <code>user</code>, and anything else that is
+not a service setting. Also refused: a port bound to another address, an image without an exact version, and a
+secret that is one of ForgeQE's own keys.</li>
+<li><strong>Mounts:</strong> inside the project only. A mount that is or holds a hidden file (<code>.env</code>, <code>.git</code>), a file named like a key,
+or a link is refused, because a container can send what it reads anywhere.</li>
+<li><strong>The docker, podman and compose programs only see</strong> the variables they need to find their daemon, plus the service's
+listed secrets.</li>
+<li><strong>Not in the agents' shell:</strong> <code>docker</code>, <code>podman</code>, <code>nerdctl</code> and compose commands are refused for ForgeQE's agent and
+Scribe. Containers start only through these tools.</li>
+</ul>
+<p><strong>Compose files.</strong> <code>containers.compose: docker-compose.yml</code> reads the file's services into the same list, checked by the
+same rules (forgeqe.yaml's own declaration of a service wins):</p>
+<ul>
+<li><strong>Translated:</strong> <code>image</code>, <code>ports</code>, <code>environment</code>, bind mounts, <code>command</code> and <code>depends_on</code>. A <code>${NAME}</code> value becomes a
+secret passed by name.</li>
+<li><strong>Left out:</strong> named volumes. Mounts made read-only are listed in the notes.</li>
+<li><strong>Ignored:</strong> <code>container_name</code>, <code>restart</code>, <code>healthcheck</code> and <code>networks</code>.</li>
+<li><strong>Refused:</strong> <code>build</code>, <code>privileged</code>, <code>network_mode</code>, <code>cap_add</code>, <code>devices</code>, <code>pid</code> and <code>env_file</code>.</li>
+</ul>
+<p><code>x-forgeqe: { ready: … }</code> sets the ready check. Without it, a service is ready when its first port takes connections.
+The project's containers share their own network, so services reach each other by name (<code>db:5432</code>).</p>
+<p><strong>Tests in a container.</strong> With <code>containers.tests</code>, <code>run_tests</code> runs the repository's tests in that image instead of
+on this machine, after starting the services it lists:</p>
+<pre><code class="language-yaml">containers:
+  tests:
+    image: mcr.microsoft.com/playwright:v1.48.2-jammy
+    services: [db]
+    secrets: [TEST_DB_PASSWORD]
+</code></pre>
+<ul>
+<li><strong>What runs:</strong> the command you confirmed, inside the container, in the repository (mounted at its own path, so the
+result files land where ForgeQE reads them).</li>
+<li><strong>User:</strong> your user.</li>
+<li><strong>Variables:</strong> only the environment's <code>FORGEQE_*</code> variables, the saved logins' variables, and the listed env and
+secrets.</li>
+<li><strong>To run on this machine instead:</strong> ask to run the tests on this machine (<code>in_container: false</code>).</li>
+<li><strong>Machines:</strong> Linux and macOS.</li>
+</ul>
+<p><strong>Testcontainers.</strong> When a test needs a real database or queue, or the repository already uses Testcontainers, Scribe's
+<code>testcontainers</code> skill writes the test to start it from code. It reuses the repository's fixtures, pins images, waits
+for readiness, and uses the mapped port. It never uses privileged mode, the host network, or the Docker socket.</p>
+</div>
+</section>
+</div>
+</article>
+<article class="spec feat" id="cap-monitoring">
+<div class="hd"><span class="mono">Operations</span><h3>Scheduled monitoring with alerts</h3></div>
+<p class="ds">Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Check the login flow every 15 minutes and alert Teams</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><li><span class="need opt">Optional</span><span>Alert channels: monitor.alerts.teams or monitor.alerts.email in forgeqe.yaml</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>monitor</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-9-monitoring">
+<h4>Monitoring</h4>
+<div class="prose"><p><code>forgeqe monitor</code> runs a set of checks on a schedule and alerts Microsoft Teams and email when one breaks. A check is any test case <code>forgeqe suite</code> takes (section 7): a YAML or Gherkin file, a folder, Jira keys or JQL, an Azure DevOps plan, TestRail, and so on.</p>
+<pre><code class="language-yaml">monitor:
+  checks: [checks/smoke.yaml]
+  every: 15m                  # 30s, 15m, 1h, 1h30m; at least 10s
+  replay: verify              # verify | trust | off
+  parallel: 1
+  fail_after: 1               # failing rounds in a row before the first alert
+  remind_every: 2h            # repeat while it keeps failing; default: never
+  keep: 100                   # round folders kept
+  write_back: false           # post each round's results to the source system
+  # out_dir: ./.forgeqe/reports/monitor
+  # report_url: https://reports.example.com/monitor
+  alerts:
+    teams:
+      webhook_env: TEAMS_WEBHOOK_URL
+    email:
+      host: smtp.office365.com  # or SMTP_HOST
+      port: 587                 # STARTTLS; 465 is TLS from the start (secure: true)
+      username_env: SMTP_USERNAME
+      password_env: SMTP_PASSWORD
+      # from: ForgeQE &lt;qa-bot@example.com&gt;
+      to: [qa-team@example.com, oncall@example.com]
+</code></pre>
+<pre><code class="language-bash">forgeqe monitor --test-alerts                  # send a sample alert through every channel
+forgeqe monitor                                # monitor.checks every monitor.every, until Ctrl+C
+forgeqe monitor checks/checkout.yaml --every 5m
+forgeqe monitor --once                         # one round, then exit (cron, scheduled pipelines)
+</code></pre>
+<p><strong>Each round</strong> runs the checks like a suite, without writing tests, and replays the flows from page memory (section 5). A flow that passed before costs one model call to confirm the expected results (<code>replay: verify</code>), or none (<code>replay: trust</code>, which trusts the replay without checking). A new or changed flow falls back to the full agent. Rounds start <code>every</code> apart; a round that overruns is followed by the next one straight away.</p>
+<p><strong>Alerts</strong> go out when something changes, not every round:</p>
+<ul>
+<li>A check that fails <code>fail_after</code> rounds in a row gets an alert. With <code>fail_after: 2</code> a single flaky failure is never reported.</li>
+<li>While it keeps failing, nothing more is sent, unless <code>remind_every</code> is set.</li>
+<li>When it passes again, a recovery alert says how long it was down.</li>
+<li>A round that cannot run at all (a test system is down, a source is empty, the engine will not start) alerts as the check &quot;ForgeQE monitor&quot;, and the other checks keep their state.</li>
+</ul>
+<p>All changes in one round go out as one message. Teams gets an Adaptive Card with each check, why it failed and at which step, a link to the test case, and an &quot;Open report&quot; button. Email gets the same as text and HTML, with the failing checks' last screenshots attached (up to five).</p>
+<p>For Teams, create an incoming webhook on the channel, or a Workflows flow with the trigger &quot;When a Teams webhook request is received&quot; and the action &quot;Post card in a chat or channel&quot;; both take the card as it is. Put the URL in <code>TEAMS_WEBHOOK_URL</code>. For email, any SMTP server works: Office 365 (<code>smtp.office365.com:587</code>, with SMTP AUTH allowed for the mailbox), Gmail with an app password, SendGrid, or a relay on your network (no username needed). The webhook URL and the SMTP password stay in the environment; if a send fails, the error never contains them.</p>
+<p>The terminal shows one block per round:</p>
+<pre><code>Monitoring checks/smoke.yaml every 15m · replay verify · alerts: Teams, email to qa-team@example.com · Ctrl+C stops
+[14:15] ✗ 4/5 passing · 38s · 6.2K tokens
+    ✗ SHOP-12 Checkout: failing since 14:15
+        The Pay button is missing on the payment page
+    ↑ Alert sent: Teams, email
+    Report  .forgeqe/reports/monitor/20260929-141500/report.html
+    Next round at 14:30
+[14:30] ✗ 4/5 passing · 35s · 5.9K tokens
+    ✗ SHOP-12 Checkout: failing since 14:15 (2 rounds, already alerted)
+    Report  .forgeqe/reports/monitor/20260929-143000/report.html
+    Next round at 14:45
+</code></pre>
+<p><strong>Files.</strong> Each round is a suite folder in <code>.forgeqe/reports/monitor/&lt;time&gt;/</code> (<code>report.html</code>, <code>junit.xml</code>, <code>suite.json</code>, the runs, and <code>alerts.json</code> when it alerted), so the report's trends and flaky tests cover the rounds. Folders beyond <code>keep</code> are deleted. <code>state.json</code> in <code>.forgeqe/reports/monitor/</code> remembers which checks are failing, since when, and when they were last alerted; delete it to start fresh. Set <code>report_url</code> to where you publish <code>.forgeqe/reports/monitor/</code> and alerts link <code>&lt;report_url&gt;/&lt;round&gt;/report.html</code>; without it they name the local file.</p>
+<p><strong>Scheduling.</strong> Run <code>forgeqe monitor</code> in a long-lived session (tmux, a service, a container), or <code>forgeqe monitor --once</code> from cron or a scheduled pipeline. <code>--once</code> exits <code>0</code> when every check passed, <code>1</code> when any failed, and <code>2</code> when stopped. In a pipeline, cache <code>.forgeqe/reports/monitor/state.json</code> between runs; without it every run starts fresh, and a failure alerts every time. Only one monitor can use an <code>out_dir</code> at a time, so an overlapping cron run exits instead of racing.</p>
+<p>You can also ask ForgeQE's agent. In the shell, &quot;check the smoke cases once&quot; runs one round and shows it as a card, and &quot;monitor the smoke cases every 10 minutes&quot; starts a monitor in the background: you keep working, each round appears as a card, &quot;is anything failing?&quot; shows the state, and &quot;stop monitoring&quot; ends it. A background monitor lives as long as the shell (or <code>forgeqe mcp</code>) and stops when it closes; <code>forgeqe run</code> refuses to start one, because it would stop when the command exits. While one is running, a one-off round on the same <code>out_dir</code> is refused rather than run twice. For monitoring that keeps going after you close the shell, &quot;monitor the smoke cases every 10 minutes and alert the QA channel in Teams, always on&quot; makes the agent set up <code>monitor:</code> in <code>forgeqe.yaml</code>, send a test alert, and tell you how to keep <code>forgeqe monitor</code> running (or add a scheduled pipeline).</p>
+</div>
+</section>
+</div>
+</article>
+<article class="spec feat" id="cap-notifications">
+<div class="hd"><span class="mono">Operations</span><h3>Teams and email notifications</h3></div>
+<p class="ds">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.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Post the results to the QA channel</li><li>Tell the release channel the verdict is NO-GO</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 notification channel: notify.channels in forgeqe.yaml, each a Teams Workflows webhook (in an environment variable) or email</span></li></ul></div>
+<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>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.</li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>notify</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-17-notifications">
+<h4>Notifications</h4>
+<div class="prose"><p>ForgeQE tells the team in Microsoft Teams channels, or by email, when something they should know happens. Each channel picks its events:</p>
+<pre><code class="language-yaml">notify:
+  report_url: https://reports.example.com/forgeqe   # where .forgeqe/reports is published, so cards link to each report
+  channels:
+    qa:
+      teams: { webhook_env: TEAMS_WEBHOOK_URL }
+      on: [suite_failed, eval_failed]
+    release:
+      teams: { webhook_env: TEAMS_RELEASE_WEBHOOK }
+      on: [release]
+    leads:
+      email: { host: smtp.office365.com, port: 587, username_env: SMTP_USERNAME, password_env: SMTP_PASSWORD, to: [qa-leads@example.com] }
+      on: [suite_failed, release]
+</code></pre>
+<div class="tbl"><table>
+<thead>
+<tr><th>Event</th><th>When</th><th>The card shows</th></tr>
+</thead>
+<tbody>
+<tr><td><code>suite_failed</code></td><td>A suite ends with a case that did not pass, or a test that did not</td><td>Each failing case (up to 10) with its kind of failure, the test case and bug links, tests written, and the report and build</td></tr>
+<tr><td><code>suite_passed</code></td><td>Every case passed</td><td>The count, how long it took, where it ran</td></tr>
+<tr><td><code>release</code></td><td>A release readiness verdict</td><td>GO, GO WITH RISKS, or NO-GO, the counts, every blocker and risk, and the wiki page when published</td></tr>
+<tr><td><code>eval_failed</code></td><td><code>forgeqe eval domain --min</code> falls below its gate</td><td>Coverage for each variant and invented ids</td></tr>
+</tbody>
+</table></div>
+<p>A channel without <code>on</code> gets <code>suite_failed</code>, <code>release</code>, and <code>eval_failed</code>. Email adds the failure screenshots. A stopped suite is not announced. Monitoring keeps its own <code>monitor.alerts</code>, with the same cards.</p>
+<p>Events are sent from runs nobody is watching: <code>forgeqe suite</code> in a pipeline or on a schedule, <code>forgeqe run</code>, and the MCP server. In the shell, where people try things out, nothing is sent on its own; ask instead (&quot;post the results to the QA channel&quot;, &quot;tell the release channel the verdict&quot;), and ForgeQE's agent posts a card with <code>notify</code>.</p>
+<p>Links: with <code>report_url</code>, cards open the report where the reports folder is published. In Azure Pipelines and GitHub Actions they also open the build, where the report is an artifact. Without either, the card names the report's path.</p>
+<p><strong>Setting up a Teams channel:</strong></p>
+<ol>
+<li>In the channel, open <strong>Workflows</strong> and choose <strong>Post to a channel when a webhook request is received</strong>, then copy the URL it gives you. Microsoft is retiring the older Office 365 &quot;Incoming Webhook&quot; connectors; Workflows webhooks take the same cards.</li>
+<li>The URL is the secret (anyone with it can post): keep it in the environment, the system's credential store (<code>forgeqe auth login TEAMS_WEBHOOK_URL</code>), or a pipeline secret, never in <code>forgeqe.yaml</code>.</li>
+<li>Create the workflow with a shared or service account: a workflow belongs to whoever made it and stops when they leave. Your tenant must allow the Workflows app.</li>
+<li><code>forgeqe notify test [channel]</code> sends a test card to check it arrives.</li>
+</ol>
+</div>
+</section>
+</div>
+</article>
+<article class="spec feat" id="cap-pipelines">
+<div class="hd"><span class="mono">Operations</span><h3>CI pipelines</h3></div>
+<p class="ds">Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>git on PATH</span></li><li><span class="need req">Required</span><span>gh on PATH, for GitHub Actions; or az on PATH, for Azure Pipelines</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>push_branch</code> <code>set_ci_secret</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-8-pipelines">
+<h4>Pipelines</h4>
+<div class="prose"><p>ForgeQE's agent writes, runs, and fixes GitHub Actions and Azure Pipelines. Run it in the repo (or pass <code>--repo</code>) and ask:</p>
+<pre><code class="language-bash">forgeqe run &quot;Add a GitHub Actions workflow that runs the smoke cases in cases.yaml on every pull request&quot;
+forgeqe run &quot;Set up an Azure DevOps pipeline that runs test plan 12 every night and posts results back&quot;
+forgeqe run &quot;The ForgeQE workflow is failing, fix it&quot;
+</code></pre>
+<p>What it does:</p>
+<ol>
+<li>Works out the platform from the git remote (github.com, or dev.azure.com / visualstudio.com) and reads the repo's existing CI, so it can add a job to it or write a new file.</li>
+<li>Writes the pipeline so it installs Bun and uv, runs <code>npm install -g @capagents/forgeqe</code> and <code>forgeqe setup</code>, then <code>forgeqe suite &lt;source...&gt; --no-code --plain --out &lt;dir&gt;</code>, and publishes <code>junit.xml</code> and the report folder. On GitHub the suite adds a results table to the job summary.</li>
+<li>Validates it (actionlint when installed, otherwise by parsing the YAML) and commits it.</li>
+<li>Pushes to a new branch named <code>forgeqe/ci-&lt;topic&gt;</code> with ForgeQE's <code>push_branch</code> tool. That tool refuses the default branch, <code>main</code>, and <code>master</code>, and never forces; <code>git push</code> itself is blocked for the agent. Merging stays with you.</li>
+<li>Stores the keys the pipeline needs (the model's key from <code>llms.json</code>, and <code>ADO_PAT</code>, <code>JIRA_EMAIL</code> and <code>JIRA_API_TOKEN</code>, or <code>XRAY_CLIENT_ID</code> and <code>XRAY_CLIENT_SECRET</code>) with ForgeQE's <code>set_ci_secret</code> tool. The agent only names the variable; ForgeQE passes the value from its own environment to <code>gh secret set</code> (on stdin) or <code>az pipelines variable</code> (through the environment), and never shows it. A variable that is not set in ForgeQE's environment is reported, not guessed.</li>
+<li>Triggers the run with <code>gh workflow run</code> or <code>az pipelines run</code>, watches it, reads the logs of failed steps, fixes the pipeline (or the code), pushes again, and repeats until the run passes or <code>code.max_attempts</code> runs have failed. It reports the run link and the result.</li>
+</ol>
+<p>It needs <code>gh</code> logged in for GitHub, or <code>az</code> with the <code>azure-devops</code> extension logged in for Azure DevOps. Without them it still writes, validates, and commits the pipeline, then tells you the commands to run. Set <code>llm.active</code> to a live profile in the committed <code>forgeqe.yaml</code>. With a <code>github_copilot</code> profile the pipeline needs only a GitHub Models token: in GitHub Actions, <code>permissions: models: read</code> and the workflow's <code>GITHUB_TOKEN</code> (see <a href="../#github-copilot-seats-as-the-model">In pipelines</a>).</p>
+</div>
+</section>
+</div>
+</article>
+</section>
+<section class="chapter" id="area-automated-tests" aria-labelledby="area-automated-tests-h">
+<header class="chead"><span class="mono">10</span><h2 id="area-automated-tests-h">Automated tests</h2><p>Write, heal, find, run, and stabilise tests in your repository</p></header>
+<article class="spec feat" id="cap-write-tests">
+<div class="hd"><span class="mono">Automated tests</span><h3>Turn a passed run into an automated test</h3></div>
+<p class="ds">Scribe, the coding agent, writes a test for a passed browser run in the repository's own framework, page objects, and helpers; ForgeQE runs it until it passes and a reviewer approves it.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Write a Playwright test for that run in ../app</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs</span></li><li><span class="need input">You give</span><span>a repository to write the test in (default: the working directory)</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>write_test</code> <code>run_test</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-6-tests">
+<h4>Tests</h4>
+<div class="prose"><p>After a run passes, <strong>Scribe</strong>, ForgeQE's coding agent, turns it into a test in your repo.</p>
+<p>In the shell and <code>forgeqe run</code>, every passed run then becomes a test, and so does each test case that passes when you ask the shell to run test cases: in the current folder, or in the repo you give per run or in <code>forgeqe.yaml</code>. <code>--no-code</code> turns it off; you can still ask for a test (&quot;write a Playwright test for that run&quot;).</p>
+<pre><code class="language-bash">forgeqe run &quot;Log in and open the invoices page on staging.app.test&quot; --repo ../app
+</code></pre>
+<pre><code class="language-yaml">code:
+  repo: ../app              # relative to forgeqe.yaml
+  max_attempts: 5           # test runs before giving up
+  test_timeout_seconds: 600 # per test run
+  stall_after: 5            # stop the agent's turn when one command it runs has failed this many times
+  replay: true              # before the agent starts, run the steps as a Playwright script and hand over what worked
+  live_browser: true        # once a step fails, the agent looks at that page in a Playwright browser
+  graph: true               # the code graph: find page objects without reading files, and reuse what already locates an element
+  # model: anthropic/claude-sonnet-4-5
+  # runtime: /path/to/agent-runtime   # default: the runtime ForgeQE downloads
+</code></pre>
+<p>What happens after the run passes:</p>
+<ol>
+<li>
+<p>ForgeQE writes <code>handoff.md</code> into the run directory: the goal and result, how ForgeQE's browser was set up (browser and version, headless or headed, user agent, <code>navigator.webdriver</code>, launch switches, extra headers, language, time zone, viewport), every step in order with the value typed (secrets as <code>process.env.NAME</code>) and the JavaScript the browser agent ran, the browser agent's own note before each group of steps (what it saw and why it acted, so a sign-in pop-up it closed or steps it redid after a banner covered the page read as such), each element's best locator and the others with their confidence %, and a short table of each visited page's other elements for assertions (weak locators under 30% are left out, and elements the steps already use are listed with the steps, so the handoff stays small; the full lists are in the page-memory files it points to). The agent's result and the final URL are marked as coming from one run on live data, to be checked as rules (the results load, the order holds, the fields have the right format), not copied as expected values. Pop-ups and banners the run met are handled wherever they appear (Playwright's locator handlers or the repository's helper), since the next run can show them at another moment or not at all; the agent's retries are not copied. A site can also serve different versions of a page to different visits (A/B tests, such as a classic search box or a free-text one), so the test handles every version the run or the agent saw, or waits for one control from either version.</p>
+<p>The handoff also lists the browser agent's <strong>checks</strong>: before it finishes, the browser agent records each result the goal asks to verify with the exact text the page showed (<code>record_check</code>; a text the page does not show is refused). They are saved in <code>workflow.yaml</code> under <code>checks:</code>. The test asserts these and nothing else.</p>
+</li>
+<li>
+<p>ForgeQE replays the run's steps as a Playwright script (<code>&lt;run&gt;/replay/flow.mjs</code>), in the run's browser setup (channel, headless or headed, user agent, language, time zone, viewport), with 10 seconds per step. Text is typed key by key, as the browser agent typed it, so search suggestions and other typing handlers fire. If the replay does not reach the run's final page, it runs again without Playwright's automation switches (<code>navigator.webdriver</code> false, as in ForgeQE's browser). The handoff gets the result: which steps worked, and for each failed step, Playwright's reason (for example a dialog that intercepts the click), the page, the dialogs open on it, how many elements each of the element's other locators matched, and a screenshot and page snapshot. It also saves Playwright's page snapshot of each page the replay visited (roles, accessible names, and text, as the replay left the page; the last page once it stops changing), so Scribe takes locators for its steps and assertions from real pages instead of guessing them. On the last page it looks up each of the browser agent's checks and puts the Playwright locator that matched its text into the handoff (a heading or text match, the container it sits in when there are several, or the form field that holds it), so assertions come with a locator that worked. For a heading it also gives the part of the page the heading names (an element labelled by it, the section it heads, or the element right after it), with its locator and how many links and list items it holds, so a check such as &quot;an In the news section with at least one item&quot; is asserted inside that part, not on the heading alone. A step that fails while every step after it still works and the replay reaches the final page (a click that did nothing on the run, or a control this version of the page doesn't have) doesn't count as a failed replay: Scribe decides from the step whether the goal needs it and ports the rest as it is. When only the second launch got through, the handoff says the browser setup is the difference and which launch settings fix it. The first time, Playwright (about 13 MB) is downloaded into <code>~/.forgeqe/tools</code>; it drives the installed Chrome. A run that only opened a page still replays when it recorded checks, to look them up; with neither it skips this, and <code>replay: false</code> turns it off.</p>
+<p>Scribe first reads the repo (as a read-only agent: it cannot change files or use the live browser yet), while the replay runs when there is one, so the two overlap. What it learns (the framework, the command that runs one test, where page objects and config live, the conventions) is saved with page memory in <code>scribe-notes.json</code>, with the tests each job writes there. The next job in the same repo starts from those notes and that list instead of reading the repo again, and extends those tests' page objects when its flow overlaps; notes older than 30 days are read again.</p>
+</li>
+<li>
+<p>Scribe starts in the repo. It reads <code>AGENTS.md</code>, the test framework config, run scripts, page objects, fixtures, and helpers, and follows the imports between them. It writes the test in the repo's language and framework (a C# NUnit repo gets a C# NUnit test) and to fit its code: it extends an existing page object instead of duplicating it and reuses the login flow, test data, and config. A repo with no tests gets Playwright Test in TypeScript. It may change anything the test needs, including dependencies and config.</p>
+<p>Before Scribe starts, ForgeQE reads the repo into a <strong>code graph</strong>, without a model: every class, page object, method, property, and test (TypeScript, JavaScript, C#, Java, Python), the calls between them, and the locators each one builds, in any framework's spelling (Playwright, Selenium, Cypress, WebdriverIO, Testing Library). It is kept in <code>~/.forgeqe/cache/code-graph</code>, nothing leaves the machine, and the next job reads again only the files that changed. The graph is tied to page memory, which knows each element by all its locators (its id, role and name, text, test id): so when the run clicked <code>getByRole('button', { name: 'Login' })</code> and the repo's <code>LoginPage.LoginButton</code> uses <code>#login-button</code>, the handoff says under that step &quot;in this repository: LoginPage.LoginButton … used by LoginPage.SignInAsync&quot;, and Scribe calls the existing method instead of writing a second locator. Scribe also gets tools that answer from the graph instead of grep and whole-file reads: <code>code_find</code> (classes, methods, and tests by name, or by the text a locator uses), <code>code_outline</code> (a file's or class's signatures and locators, or the source of one member), <code>code_element</code> (which member already locates an element), <code>code_references</code> (what calls a member, before it is changed), and <code>code_impact</code> (the tests a change reaches, through flows and base classes, whatever the test files are called). <code>graph: false</code> turns it off. The handoff also outlines the page objects its steps use and includes the repo's test that uses the most of them, so Scribe takes the test conventions from that test instead of reading other tests, and reads a settings file only to change it.</p>
+</li>
+<li>
+<p>It writes the test from the handoff and the replay script: steps that worked are ported with their locators, steps that failed are fixed first. Every locator, including those for assertions, comes from the replay script, the page snapshots, page memory, or a check on the page; steps where the browser agent ran JavaScript to look around are left out. It does not walk the flow again or build tests to explore. Once a step fails (in the replay, or in its test), ForgeQE switches on its live browser: a Chrome that Playwright drives, set up like ForgeQE's, where it looks at the failing step's page one tool call per action (open, snapshot, click, type, wait, screenshot, run JavaScript, console errors, failed requests). Until then the live browser tools are off, so no tokens go into looking at pages that work. The live browser needs Node.js (<code>npx</code>), and Microsoft's Playwright MCP server is downloaded on first use; with <code>live_browser: false</code>, or without <code>npx</code>, it looks with a small throwaway script instead. When its browser gets a different page than ForgeQE's did (an error, a challenge, a control that will not open), it compares the two browsers (user agent, <code>navigator.webdriver</code>, headless, failed requests and CORS errors, headers the framework adds, console errors) and fixes the difference in the repo's browser configuration. It never judges the site with <code>curl</code> or <code>webfetch</code>.</p>
+</li>
+<li>
+<p>Scribe does not run the test itself: it may build or compile, then reports the test file and the command that runs only that test, and ForgeQE runs it. If one command it runs fails <code>stall_after</code> times in a row within its work (the same build again and again, say), ForgeQE stops that turn and sends the command and its last output back, asking it to change approach. If the same command stalls again, the job stops as a failure with that output in the notes.</p>
+</li>
+<li>
+<p>ForgeQE runs that command (with <code>CI=1</code>) and checks the exit code, and it watches the processes the command starts for a browser launched by Playwright, Puppeteer, Selenium, or Cypress. On a failure it sends the command, exit code, and output back to Scribe. The output is kept short so the error is never cut off: the page dump Playwright puts into a failed assertion (&quot;Aria snapshot:&quot;, often thousands of lines) is taken out and saved as <code>&lt;run&gt;/test-runs/attempt-N-page.aria.yml</code>, then the start (where the first error and its stack trace are) and the end (the summary) are sent; the full output is in <code>&lt;run&gt;/test-runs/attempt-N.log</code>, and the prompt names both files. A command that exits 0 without starting a browser also goes back: the test must drive the app in a browser. If the repo's browser runs on another machine (Selenium Grid, a cloud service, a container), the agent says where and the check is skipped.</p>
+</li>
+<li>
+<p>A passing test then goes to a separate reviewer agent, which can read files and <code>git diff</code> but not change anything. It checks the change against the goal and the test rules: every part of the goal done through the page and asserted, generic page objects with data in the test, no values or URLs copied from the run, browser settings in the repo's configuration, no leftover files. The changed files come inline in its prompt, so it reads nothing again, and it does not ask to replace locators or texts that came from the replay or the checks, since those matched the live site. It judges only what this job changed: ForgeQE records the working tree before the job, so your uncommitted edits, your untracked files, and ForgeQE's own files (<code>.forgeqe/</code>, <code>forgeqe.yaml</code>, <code>llms.json</code>) are never part of the review. It checks the diff of every file that existed before the job: removing or rewriting an existing test, even a commented-out one, is a correctness problem. Credentials come from the environment, except a public demo login that the application itself shows to anyone (such as the logins on saucedemo.com's sign-in page), which may stay in the repo's test data. It gets the outlines of the classes the changed code uses, the repo's browser settings, and the same <code>code_*</code> tools, so it checks reuse and settings without reading those files. The code graph also tells it what the job added that it can check in the code: a new member that locates an element an existing member already locates (to reuse instead), and new XPath or position-based locators. If it finds problems, they go back to Scribe as the next attempt. The terminal shows the exchange as it happens, in order: the reviewer's verdict with its reason and each issue (✗ correctness, ~ coding standard) with the file and the fix it asks for; then why Scribe tries again and what it is fixing (the reviewer's issues, or the test's first error); then what Scribe says it did and which files it changed; then the next verdict:</p>
+</li>
+</ol>
+<pre><code>⏺ Reviewer asked for changes  attempt 1 of 5 · 1 to fix, 1 coding-standard
+  ⎿ The test never checks that the pie chart is shown.
+    ✗ Correctness · tests/PracticeTests.cs: No assertion on the SVG pie chart.
+        Fix: Assert the chart's heading and SVG are visible.
+    ~ Coding standard · tests/PracticeTests.cs: Test data is inline.
+        Fix: Move it to the page object.
+⏺ Scribe tries again · attempt 2 of 5  the reviewer asked for changes
+  ⎿ → tests/PracticeTests.cs: No assertion on the SVG pie chart. — fix: Assert the chart's heading and SVG are visible.
+  ⎿ Scribe (attempt 2): Added the pie chart assertion · changed tests/PracticeTests.cs, Pages/PracticePage.cs
+⏺ Reviewer approved the test  attempt 2 of 5
+</code></pre>
+<p>The Activities panel has one line for each verdict and attempt, and <code>forgeqe</code> commands outside the terminal UI print the same blocks.</p>
+<p>Scribe cannot edit ForgeQE's files or run folders, and cannot run <code>git clean</code>, <code>git reset --hard</code>, <code>git stash</code>, <code>git restore</code>, or <code>git checkout -- &lt;path&gt;</code>. If it still removes a file that existed before the job, or reverts your uncommitted edits, ForgeQE puts the file back after that attempt and tells the agent.
+8. The job is done when ForgeQE's run passes with a browser and the reviewer approves. It stops as a failure after <code>max_attempts</code> attempts, when the job passes <code>code.max_tokens</code>, when the reviewer rejects a passing test twice, if the review cannot finish, when the test fails the same way three times in a row (the same output apart from numbers such as timings and line numbers; the second time, Scribe is told its change did not change the failure and to look at the failing step before changing code), or straight away on an auth, API, or context-limit error from the model.</p>
+<p><code>blocked</code> is a last resort. The first time the agent reports that the app blocks it, ForgeQE sends it back to compare its browser with ForgeQE's and fix the difference; only a second blocked report, with what it compared, ends the job as blocked.</p>
+<p>The transcript shows the handover and Scribe's work as it goes; files it writes or edits are marked ✎:</p>
+<pre><code>┃
+┃  ▸ Handing over to the coding agent                         browser agent → coding agent
+┃
+┃  Flow      Log in and open the invoices page on staging.app.test
+┃  Run       .forgeqe/reports/20260928-172700/
+┃  Repo      ../app
+┃
+  ▸ Handoff written: .forgeqe/reports/20260928-172700/handoff.md (7 steps, 3 pages from page memory)
+  ▸ Scribe, the coding agent (azure/gpt-5.4), reads the handoff and writes a test in /work/app
+    ⚙ Reading .forgeqe/reports/20260928-172700/handoff.md
+    ⚙ Reading tests/pages/LoginPage.ts
+    ✎ Editing tests/invoices.spec.ts
+    ⚙ Running npx playwright test tests/invoices.spec.ts
+  ▸ ForgeQE runs the test: npx playwright test tests/invoices.spec.ts
+  ✗ tests/invoices.spec.ts failed, exit 1 (attempt 1/5)
+  ▸ tests/invoices.spec.ts passed in 9s in Google Chrome; a reviewer checks it against the goal
+  ✓ tests/invoices.spec.ts passed and was approved (attempt 2/5)
+┃
+┃  ✓ Test passed                          2/5 attempts · 3m 12s · 88.4K tokens · azure/gpt-5.4
+┃
+┃  Added openInvoices() to DashboardPage and reused the loginAs fixture.
+┃
+┃  Test      tests/invoices.spec.ts  (in ../app)
+┃  Command   npx playwright test tests/invoices.spec.ts
+┃  Reused    LoginPage, fixtures/auth.ts
+┃  Changed   tests/invoices.spec.ts, tests/pages/DashboardPage.ts
+┃  Browser   Google Chrome
+┃  Review    approved: Opens the invoices page through the dashboard and checks the table columns.
+</code></pre>
+<p>After ForgeQE's reply, the request ends with the files it produced:</p>
+<pre><code>┃  ✓ What this produced
+┃
+┃    Report    .forgeqe/reports/20260928-172700/report.html
+┃  ✓ Test      ../app/tests/invoices.spec.ts  passed when ForgeQE ran it
+┃    Command   npx playwright test tests/invoices.spec.ts
+┃    Handoff   .forgeqe/reports/20260928-172700/handoff.md
+</code></pre>
+<p>When no test was written, the Test row says why: the run did not pass, the session has <code>--no-code</code>, or the run was not handed to the coding agent.</p>
+<p>Scribe uses the active <code>llms.json</code> profile. The key stays in your environment: the agent runtime's config refers to it as <code>{env:WP_AZURE_API_KEY}</code> and never contains the value. An <code>auth: entra</code> profile reaches the model through ForgeQE's local token gateway (see <a href="../#signing-in-to-the-model-without-a-key-microsoft-entra-id">Signing in to the model without a key</a>). An Azure profile goes through the agent runtime's <code>azure</code> provider on <code>&lt;endpoint&gt;/openai/v1</code> (the Responses API, with the deployment as the model). <code>openai_compatible</code> and <code>ollama</code> profiles use their <code>base_url</code>. A <code>github_copilot</code> profile goes through the agent runtime's <code>github-copilot</code> provider with the profile's <code>model</code>, signed in with <code>forgeqe auth login copilot</code>. <code>code.model: provider/model</code> (or <code>--code-model</code>) uses one of the agent runtime's built-in providers instead, with that provider's usual key variable (for example <code>ANTHROPIC_API_KEY</code> for <code>anthropic/...</code>).</p>
+<p>Scribe may edit files and run commands anywhere in the repo without asking. <code>git push</code> in any form is denied (pushing goes through ForgeQE's guarded <code>push_branch</code> tool, section 8), and it cannot touch files outside the repo except the run and memory directories, which it may read.</p>
+<p>More ways to run it:</p>
+<pre><code class="language-bash">forgeqe code --repo ../app                                 # the latest run in .forgeqe/reports/
+forgeqe code .forgeqe/reports/20260928-172700 --repo ../app --attempts 3
+forgeqe run &quot;...&quot; --no-code                                # no tests for this request
+</code></pre>
+<p>In the shell, <code>forgeqe start --repo ../app</code> writes the tests in that repo instead of the current folder and <code>--no-code</code> turns them off; you can also just ask (&quot;write a test for the last run in ../app&quot;). Esc stops the agent the same way it stops a run.</p>
+<p>Exit codes for <code>forgeqe code</code> and for <code>forgeqe run --direct</code> with a repo: <code>0</code> test passed, <code>1</code> run or test failed, <code>2</code> stopped. The result (status, attempts, test file, command, what was reused and changed, the browsers ForgeQE saw, the review, the last test output, tokens) is saved as <code>code.json</code> in the run directory, next to <code>handoff.md</code>.</p>
+<p>If Scribe's job is cut off (ForgeQE closed, the machine restarted, you stopped it, or the model could not be reached), run it again for the same run and repo, for example <code>forgeqe code .forgeqe/reports/20260928-172700 --repo ../app</code>. Scribe reopens the same session, with everything it read and said, and carries on with the files it already wrote; it doesn't read the repo again, and ForgeQE uses the Playwright replay it already finished. The session is kept in <code>scribe-session.json</code> in the run folder until the job ends with a result.</p>
+</div>
+</section>
+</div>
+</article>
+<article class="spec feat" id="cap-heal-tests">
+<div class="hd"><span class="mono">Automated tests</span><h3>Heal failing tests</h3></div>
+<p class="ds">Runs a repository's tests and updates the ones the application has outgrown against the live app, or reports a real application bug instead.</p>
+<div class="facts">
+<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Heal the failing tests in ../app</li></ul></div>
+<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>The coding agent, Scribe: a live model profile (or code.model) and the agent runtime, which forgeqe setup installs</span></li><li><span class="need input">You give</span><span>a repository with tests</span></li></ul></div>
+<div class="fact"><span class="mono">Tools</span><p class="tools"><code>heal_tests</code></p></div>
+</div>
+<div class="detail"><span class="mono">In detail</span>
+<section class="doc" id="doc-how_to_use-fixing-broken-tests">
+<h4>Fixing broken tests</h4>
+<div class="prose"><p>When a redesign or a renamed button breaks tests, <code>forgeqe heal</code> fixes them, or tells you the app is what broke:</p>
+<pre><code class="language-bash">forgeqe heal --repo ../app                               # the command from code.test_command, or the agent finds it
+forgeqe heal &quot;npx playwright test tests/checkout&quot; --repo ../app
+forgeqe heal -- npx playwright test --project=chromium   # everything after -- is the command
+</code></pre>
+<pre><code class="language-yaml">code:
+  repo: ../app
+  test_command: npx playwright test   # optional
+</code></pre>
+<ol>
+<li>ForgeQE runs the command. If it passes, there is nothing to heal and no model is called.</li>
+<li>Scribe starts in the repo as a healing agent, with the failing output. For each failing test it reads the test and the page objects it uses, then re-runs the test's flow in the real browser with ForgeQE's <code>browser_run</code> (the goal in plain words, not the old selectors).</li>
+<li>If the browser run passes, the test is out of date. The agent reads that run's steps and locators with <code>run_details</code>, updates the test (in the page object when the locators live there), and runs it with <code>run_test</code>.</li>
+<li>If the browser run fails at the step where the test fails, the app is broken there. The test is left as it is and the failure is reported as an app bug.</li>
+<li>It never deletes or skips a test, loosens an assertion, or raises a timeout to make a test pass.</li>
+<li>ForgeQE runs each healed test's own command, then the whole command. A healed test that still fails goes back to the agent with the output, and so does any other failure left in the whole run, until everything passes or <code>code.max_attempts</code> rounds are used.</li>
+</ol>
+<pre><code>  ▸ ForgeQE runs the tests: npx playwright test
+  ✗ Tests failed, exit 1 (41s)
+  ▸ Scribe (azure/gpt-5.4) is healing the failing tests in app
+    ⚙ read tests/pages/LoginPage.ts
+  ▸ Browser: Sign in to staging.app.test and open the invoices page
+  ✓ Task complete · 9 steps
+    ⚙ edit tests/pages/LoginPage.ts
+  ▸ ForgeQE runs: npx playwright test tests/login.spec.ts
+  ✓ login › signs in passed in 6s
+  ▸ ForgeQE runs the tests: npx playwright test
+  ✗ Tests still fail, exit 1 (39s)
+┃
+┃  ✗ Tests still failing                   2/5 attempts · 2m 40s · 61.2K tokens · azure/gpt-5.4
+┃
+┃  ✓ login › signs in  healed
+┃      The Sign in button is now &quot;Log in&quot;; LoginPage uses the new label
+┃  ! invoices › totals  app bug
+┃      The total column is empty; the browser run failed at the same step
+┃
+┃  1 failure is in the app, not the tests; the tests were left as they are.
+┃  Command   npx playwright test  (exit 1 after 39s)
+┃  Changed   tests/pages/LoginPage.ts
+┃  Report    .forgeqe/reports/heal/20260929-101500/heal.md
+</code></pre>
+<p>The report is <code>heal.md</code> and <code>heal.json</code> in <code>.forgeqe/reports/heal/&lt;time&gt;/</code>: each test's verdict and reason, the files changed, the browser runs (their folders sit next to the report), and the test output before and after. Exit codes: <code>0</code> the tests pass (or nothing needed healing), <code>1</code> some still fail, <code>2</code> stopped. In the shell or with <code>forgeqe run</code>, &quot;the checkout tests are failing after the redesign, fix them&quot; does the same through ForgeQE's agent.</p>
+</div>
+</section>
+</div>
+</article>
+<article class="spec feat" id="cap-find-run-tests">
 <div class="hd"><span class="mono">Automated tests</span><h3>Find and run existing tests</h3></div>
 <p class="ds">Finds the automated tests that match a feature, tags, ids, a folder, or a sprint, confirms the selection, and runs it once the user agrees, with a verdict per test.</p>
 <div class="facts">
@@ -1586,7 +2166,7 @@ Build a pack for Jira fix version 2.4 and the commits since release/2.3 in ../sh
 </article>
 </section>
 <section class="chapter" id="area-pull-requests" aria-labelledby="area-pull-requests-h">
-<header class="chead"><span class="mono">07</span><h2 id="area-pull-requests-h">Pull requests</h2><p>Reviews, impact, and the tests a change can break</p></header>
+<header class="chead"><span class="mono">11</span><h2 id="area-pull-requests-h">Pull requests</h2><p>Reviews, impact, and the tests a change can break</p></header>
 <article class="spec feat" id="cap-pr-review">
 <div class="hd"><span class="mono">Pull requests</span><h3>Review pull requests</h3></div>
 <p class="ds">Reviews an Azure DevOps or GitHub pull request from the local clone for bugs, security, requirements, and tests, and posts the review once the user agrees.</p>
@@ -1658,7 +2238,7 @@ forgeqe pr-tests 42 --run --post                     # and post the results on p
 </article>
 </section>
 <section class="chapter" id="area-api" aria-labelledby="area-api-h">
-<header class="chead"><span class="mono">08</span><h2 id="area-api-h">API</h2><p>Contracts and end-to-end scenarios, without a browser</p></header>
+<header class="chead"><span class="mono">12</span><h2 id="area-api-h">API</h2><p>Contracts and end-to-end scenarios, without a browser</p></header>
 <article class="spec feat" id="cap-api-testing">
 <div class="hd"><span class="mono">API</span><h3>API and contract testing</h3></div>
 <p class="ds">Builds API contracts (status, schema, key fields) from the calls a browser run saw or from an API description (OpenAPI, Swagger, WSDL, GraphQL, .proto, gRPC reflection), and end-to-end API scenarios from runs, descriptions, test cases, or plain English. Runs them straight against the API without a browser, or writes them as tests in the repository. REST, GraphQL, SOAP, and gRPC.</p>
@@ -1736,7 +2316,7 @@ forgeqe api tests --scenarios --repo ../api-tests            # on the repo's exi
 </article>
 </section>
 <section class="chapter" id="area-quality" aria-labelledby="area-quality-h">
-<header class="chead"><span class="mono">09</span><h2 id="area-quality-h">Quality</h2><p>Accessibility, page performance, and visual changes</p></header>
+<header class="chead"><span class="mono">13</span><h2 id="area-quality-h">Quality</h2><p>Accessibility, page performance, and visual changes</p></header>
 <article class="spec feat" id="cap-accessibility-performance">
 <div class="hd"><span class="mono">Quality</span><h3>Accessibility and page performance</h3></div>
 <p class="ds">Checks every page a run visits against WCAG rules (axe-core) and measures its Core Web Vitals, against budgets, with trends over time per page.</p>
@@ -1854,7 +2434,7 @@ forgeqe visual approve --page /home  # make this run's /home the baseline (asks
 </article>
 </section>
 <section class="chapter" id="area-release" aria-labelledby="area-release-h">
-<header class="chead"><span class="mono">10</span><h2 id="area-release-h">Release</h2><p>Requirement coverage and a release verdict</p></header>
+<header class="chead"><span class="mono">14</span><h2 id="area-release-h">Release</h2><p>Requirement coverage and a release verdict</p></header>
 <article class="spec feat" id="cap-release-readiness">
 <div class="hd"><span class="mono">Release</span><h3>Requirement coverage and release readiness</h3></div>
 <p class="ds">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.</p>
@@ -1917,161 +2497,8 @@ forgeqe visual approve --page /home  # make this run's /home the baseline (asks
 </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>
-<article class="spec feat" id="cap-monitoring">
-<div class="hd"><span class="mono">Operations</span><h3>Scheduled monitoring with alerts</h3></div>
-<p class="ds">Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers.</p>
-<div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Check the login flow every 15 minutes and alert Teams</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><li><span class="need opt">Optional</span><span>Alert channels: monitor.alerts.teams or monitor.alerts.email in forgeqe.yaml</span></li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>monitor</code></p></div>
-</div>
-<div class="detail"><span class="mono">In detail</span>
-<section class="doc" id="doc-how_to_use-9-monitoring">
-<h4>Monitoring</h4>
-<div class="prose"><p><code>forgeqe monitor</code> runs a set of checks on a schedule and alerts Microsoft Teams and email when one breaks. A check is any test case <code>forgeqe suite</code> takes (section 7): a YAML or Gherkin file, a folder, Jira keys or JQL, an Azure DevOps plan, TestRail, and so on.</p>
-<pre><code class="language-yaml">monitor:
-  checks: [checks/smoke.yaml]
-  every: 15m                  # 30s, 15m, 1h, 1h30m; at least 10s
-  replay: verify              # verify | trust | off
-  parallel: 1
-  fail_after: 1               # failing rounds in a row before the first alert
-  remind_every: 2h            # repeat while it keeps failing; default: never
-  keep: 100                   # round folders kept
-  write_back: false           # post each round's results to the source system
-  # out_dir: ./.forgeqe/reports/monitor
-  # report_url: https://reports.example.com/monitor
-  alerts:
-    teams:
-      webhook_env: TEAMS_WEBHOOK_URL
-    email:
-      host: smtp.office365.com  # or SMTP_HOST
-      port: 587                 # STARTTLS; 465 is TLS from the start (secure: true)
-      username_env: SMTP_USERNAME
-      password_env: SMTP_PASSWORD
-      # from: ForgeQE &lt;qa-bot@example.com&gt;
-      to: [qa-team@example.com, oncall@example.com]
-</code></pre>
-<pre><code class="language-bash">forgeqe monitor --test-alerts                  # send a sample alert through every channel
-forgeqe monitor                                # monitor.checks every monitor.every, until Ctrl+C
-forgeqe monitor checks/checkout.yaml --every 5m
-forgeqe monitor --once                         # one round, then exit (cron, scheduled pipelines)
-</code></pre>
-<p><strong>Each round</strong> runs the checks like a suite, without writing tests, and replays the flows from page memory (section 5). A flow that passed before costs one model call to confirm the expected results (<code>replay: verify</code>), or none (<code>replay: trust</code>, which trusts the replay without checking). A new or changed flow falls back to the full agent. Rounds start <code>every</code> apart; a round that overruns is followed by the next one straight away.</p>
-<p><strong>Alerts</strong> go out when something changes, not every round:</p>
-<ul>
-<li>A check that fails <code>fail_after</code> rounds in a row gets an alert. With <code>fail_after: 2</code> a single flaky failure is never reported.</li>
-<li>While it keeps failing, nothing more is sent, unless <code>remind_every</code> is set.</li>
-<li>When it passes again, a recovery alert says how long it was down.</li>
-<li>A round that cannot run at all (a test system is down, a source is empty, the engine will not start) alerts as the check &quot;ForgeQE monitor&quot;, and the other checks keep their state.</li>
-</ul>
-<p>All changes in one round go out as one message. Teams gets an Adaptive Card with each check, why it failed and at which step, a link to the test case, and an &quot;Open report&quot; button. Email gets the same as text and HTML, with the failing checks' last screenshots attached (up to five).</p>
-<p>For Teams, create an incoming webhook on the channel, or a Workflows flow with the trigger &quot;When a Teams webhook request is received&quot; and the action &quot;Post card in a chat or channel&quot;; both take the card as it is. Put the URL in <code>TEAMS_WEBHOOK_URL</code>. For email, any SMTP server works: Office 365 (<code>smtp.office365.com:587</code>, with SMTP AUTH allowed for the mailbox), Gmail with an app password, SendGrid, or a relay on your network (no username needed). The webhook URL and the SMTP password stay in the environment; if a send fails, the error never contains them.</p>
-<p>The terminal shows one block per round:</p>
-<pre><code>Monitoring checks/smoke.yaml every 15m · replay verify · alerts: Teams, email to qa-team@example.com · Ctrl+C stops
-[14:15] ✗ 4/5 passing · 38s · 6.2K tokens
-    ✗ SHOP-12 Checkout: failing since 14:15
-        The Pay button is missing on the payment page
-    ↑ Alert sent: Teams, email
-    Report  .forgeqe/reports/monitor/20260929-141500/report.html
-    Next round at 14:30
-[14:30] ✗ 4/5 passing · 35s · 5.9K tokens
-    ✗ SHOP-12 Checkout: failing since 14:15 (2 rounds, already alerted)
-    Report  .forgeqe/reports/monitor/20260929-143000/report.html
-    Next round at 14:45
-</code></pre>
-<p><strong>Files.</strong> Each round is a suite folder in <code>.forgeqe/reports/monitor/&lt;time&gt;/</code> (<code>report.html</code>, <code>junit.xml</code>, <code>suite.json</code>, the runs, and <code>alerts.json</code> when it alerted), so the report's trends and flaky tests cover the rounds. Folders beyond <code>keep</code> are deleted. <code>state.json</code> in <code>.forgeqe/reports/monitor/</code> remembers which checks are failing, since when, and when they were last alerted; delete it to start fresh. Set <code>report_url</code> to where you publish <code>.forgeqe/reports/monitor/</code> and alerts link <code>&lt;report_url&gt;/&lt;round&gt;/report.html</code>; without it they name the local file.</p>
-<p><strong>Scheduling.</strong> Run <code>forgeqe monitor</code> in a long-lived session (tmux, a service, a container), or <code>forgeqe monitor --once</code> from cron or a scheduled pipeline. <code>--once</code> exits <code>0</code> when every check passed, <code>1</code> when any failed, and <code>2</code> when stopped. In a pipeline, cache <code>.forgeqe/reports/monitor/state.json</code> between runs; without it every run starts fresh, and a failure alerts every time. Only one monitor can use an <code>out_dir</code> at a time, so an overlapping cron run exits instead of racing.</p>
-<p>You can also ask ForgeQE's agent. In the shell, &quot;check the smoke cases once&quot; runs one round and shows it as a card, and &quot;monitor the smoke cases every 10 minutes&quot; starts a monitor in the background: you keep working, each round appears as a card, &quot;is anything failing?&quot; shows the state, and &quot;stop monitoring&quot; ends it. A background monitor lives as long as the shell (or <code>forgeqe mcp</code>) and stops when it closes; <code>forgeqe run</code> refuses to start one, because it would stop when the command exits. While one is running, a one-off round on the same <code>out_dir</code> is refused rather than run twice. For monitoring that keeps going after you close the shell, &quot;monitor the smoke cases every 10 minutes and alert the QA channel in Teams, always on&quot; makes the agent set up <code>monitor:</code> in <code>forgeqe.yaml</code>, send a test alert, and tell you how to keep <code>forgeqe monitor</code> running (or add a scheduled pipeline).</p>
-</div>
-</section>
-</div>
-</article>
-<article class="spec feat" id="cap-notifications">
-<div class="hd"><span class="mono">Operations</span><h3>Teams and email notifications</h3></div>
-<p class="ds">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.</p>
-<div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Post the results to the QA channel</li><li>Tell the release channel the verdict is NO-GO</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 notification channel: notify.channels in forgeqe.yaml, each a Teams Workflows webhook (in an environment variable) or email</span></li></ul></div>
-<div class="fact"><span class="mono">Limits</span><ul class="plainlist"><li>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.</li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>notify</code></p></div>
-</div>
-<div class="detail"><span class="mono">In detail</span>
-<section class="doc" id="doc-how_to_use-17-notifications">
-<h4>Notifications</h4>
-<div class="prose"><p>ForgeQE tells the team in Microsoft Teams channels, or by email, when something they should know happens. Each channel picks its events:</p>
-<pre><code class="language-yaml">notify:
-  report_url: https://reports.example.com/forgeqe   # where .forgeqe/reports is published, so cards link to each report
-  channels:
-    qa:
-      teams: { webhook_env: TEAMS_WEBHOOK_URL }
-      on: [suite_failed, eval_failed]
-    release:
-      teams: { webhook_env: TEAMS_RELEASE_WEBHOOK }
-      on: [release]
-    leads:
-      email: { host: smtp.office365.com, port: 587, username_env: SMTP_USERNAME, password_env: SMTP_PASSWORD, to: [qa-leads@example.com] }
-      on: [suite_failed, release]
-</code></pre>
-<div class="tbl"><table>
-<thead>
-<tr><th>Event</th><th>When</th><th>The card shows</th></tr>
-</thead>
-<tbody>
-<tr><td><code>suite_failed</code></td><td>A suite ends with a case that did not pass, or a test that did not</td><td>Each failing case (up to 10) with its kind of failure, the test case and bug links, tests written, and the report and build</td></tr>
-<tr><td><code>suite_passed</code></td><td>Every case passed</td><td>The count, how long it took, where it ran</td></tr>
-<tr><td><code>release</code></td><td>A release readiness verdict</td><td>GO, GO WITH RISKS, or NO-GO, the counts, every blocker and risk, and the wiki page when published</td></tr>
-<tr><td><code>eval_failed</code></td><td><code>forgeqe eval domain --min</code> falls below its gate</td><td>Coverage for each variant and invented ids</td></tr>
-</tbody>
-</table></div>
-<p>A channel without <code>on</code> gets <code>suite_failed</code>, <code>release</code>, and <code>eval_failed</code>. Email adds the failure screenshots. A stopped suite is not announced. Monitoring keeps its own <code>monitor.alerts</code>, with the same cards.</p>
-<p>Events are sent from runs nobody is watching: <code>forgeqe suite</code> in a pipeline or on a schedule, <code>forgeqe run</code>, and the MCP server. In the shell, where people try things out, nothing is sent on its own; ask instead (&quot;post the results to the QA channel&quot;, &quot;tell the release channel the verdict&quot;), and ForgeQE's agent posts a card with <code>notify</code>.</p>
-<p>Links: with <code>report_url</code>, cards open the report where the reports folder is published. In Azure Pipelines and GitHub Actions they also open the build, where the report is an artifact. Without either, the card names the report's path.</p>
-<p><strong>Setting up a Teams channel:</strong></p>
-<ol>
-<li>In the channel, open <strong>Workflows</strong> and choose <strong>Post to a channel when a webhook request is received</strong>, then copy the URL it gives you. Microsoft is retiring the older Office 365 &quot;Incoming Webhook&quot; connectors; Workflows webhooks take the same cards.</li>
-<li>The URL is the secret (anyone with it can post): keep it in the environment, the system's credential store (<code>forgeqe auth login TEAMS_WEBHOOK_URL</code>), or a pipeline secret, never in <code>forgeqe.yaml</code>.</li>
-<li>Create the workflow with a shared or service account: a workflow belongs to whoever made it and stops when they leave. Your tenant must allow the Workflows app.</li>
-<li><code>forgeqe notify test [channel]</code> sends a test card to check it arrives.</li>
-</ol>
-</div>
-</section>
-</div>
-</article>
-<article class="spec feat" id="cap-pipelines">
-<div class="hd"><span class="mono">Operations</span><h3>CI pipelines</h3></div>
-<p class="ds">Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green.</p>
-<div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green</li></ul></div>
-<div class="fact"><span class="mono">What it needs</span><ul class="needs"><li><span class="need req">Required</span><span>git on PATH</span></li><li><span class="need req">Required</span><span>gh on PATH, for GitHub Actions; or az on PATH, for Azure Pipelines</span></li></ul></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>push_branch</code> <code>set_ci_secret</code></p></div>
-</div>
-<div class="detail"><span class="mono">In detail</span>
-<section class="doc" id="doc-how_to_use-8-pipelines">
-<h4>Pipelines</h4>
-<div class="prose"><p>ForgeQE's agent writes, runs, and fixes GitHub Actions and Azure Pipelines. Run it in the repo (or pass <code>--repo</code>) and ask:</p>
-<pre><code class="language-bash">forgeqe run &quot;Add a GitHub Actions workflow that runs the smoke cases in cases.yaml on every pull request&quot;
-forgeqe run &quot;Set up an Azure DevOps pipeline that runs test plan 12 every night and posts results back&quot;
-forgeqe run &quot;The ForgeQE workflow is failing, fix it&quot;
-</code></pre>
-<p>What it does:</p>
-<ol>
-<li>Works out the platform from the git remote (github.com, or dev.azure.com / visualstudio.com) and reads the repo's existing CI, so it can add a job to it or write a new file.</li>
-<li>Writes the pipeline so it installs Bun and uv, runs <code>npm install -g @capagents/forgeqe</code> and <code>forgeqe setup</code>, then <code>forgeqe suite &lt;source...&gt; --no-code --plain --out &lt;dir&gt;</code>, and publishes <code>junit.xml</code> and the report folder. On GitHub the suite adds a results table to the job summary.</li>
-<li>Validates it (actionlint when installed, otherwise by parsing the YAML) and commits it.</li>
-<li>Pushes to a new branch named <code>forgeqe/ci-&lt;topic&gt;</code> with ForgeQE's <code>push_branch</code> tool. That tool refuses the default branch, <code>main</code>, and <code>master</code>, and never forces; <code>git push</code> itself is blocked for the agent. Merging stays with you.</li>
-<li>Stores the keys the pipeline needs (the model's key from <code>llms.json</code>, and <code>ADO_PAT</code>, <code>JIRA_EMAIL</code> and <code>JIRA_API_TOKEN</code>, or <code>XRAY_CLIENT_ID</code> and <code>XRAY_CLIENT_SECRET</code>) with ForgeQE's <code>set_ci_secret</code> tool. The agent only names the variable; ForgeQE passes the value from its own environment to <code>gh secret set</code> (on stdin) or <code>az pipelines variable</code> (through the environment), and never shows it. A variable that is not set in ForgeQE's environment is reported, not guessed.</li>
-<li>Triggers the run with <code>gh workflow run</code> or <code>az pipelines run</code>, watches it, reads the logs of failed steps, fixes the pipeline (or the code), pushes again, and repeats until the run passes or <code>code.max_attempts</code> runs have failed. It reports the run link and the result.</li>
-</ol>
-<p>It needs <code>gh</code> logged in for GitHub, or <code>az</code> with the <code>azure-devops</code> extension logged in for Azure DevOps. Without them it still writes, validates, and commits the pipeline, then tells you the commands to run. Set <code>llm.active</code> to a live profile in the committed <code>forgeqe.yaml</code>.</p>
-</div>
-</section>
-</div>
-</article>
-</section>
 <section class="chapter" id="area-systems" aria-labelledby="area-systems-h">
-<header class="chead"><span class="mono">12</span><h2 id="area-systems-h">Systems</h2><p>Azure DevOps, Jira, and Confluence</p></header>
+<header class="chead"><span class="mono">15</span><h2 id="area-systems-h">Systems</h2><p>Azure DevOps, Jira, and Confluence</p></header>
 <article class="spec feat" id="cap-systems">
 <div class="hd"><span class="mono">Systems</span><h3>Work with Azure DevOps, Jira, GitHub, and Confluence</h3></div>
 <p class="ds">Reads anything in the configured systems (work items, issues, queries, boards, pages), makes changes the user asks for, puts run evidence (screenshots, reports) on work items and issues as attachments or comments, and builds Azure DevOps dashboards and wiki pages.</p>
@@ -2116,82 +2543,8 @@ mcp:
 </div>
 </article>
 </section>
-<section class="chapter" id="area-setup" aria-labelledby="area-setup-h">
-<header class="chead"><span class="mono">13</span><h2 id="area-setup-h">Setup</h2><p>Configuration, skills, and help</p></header>
-<article class="spec feat" id="cap-setup-help">
-<div class="hd"><span class="mono">Setup</span><h3>Setup, skills, and documentation</h3></div>
-<p class="ds">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.</p>
-<div class="facts">
-<div class="fact"><span class="mono">Ask it</span><ul class="asks"><li>What can you do?</li><li>Which model am I using?</li><li>How do I set up email alerts?</li></ul></div>
-<div class="fact"><span class="mono">What it needs</span><p class="muted">Nothing beyond ForgeQE itself.</p></div>
-<div class="fact"><span class="mono">Tools</span><p class="tools"><code>forgeqe_setup</code> <code>capabilities</code> <code>playbook</code></p></div>
-</div>
-<div class="detail"><span class="mono">In detail</span>
-<p class="see">See <a href="#doc-how_to_use-2-scaffold-config">2. Scaffold config</a>.</p>
-<section class="doc" id="doc-how_to_use-11-skills">
-<h4>Skills</h4>
-<div class="prose"><p>A skill is a folder with a <code>SKILL.md</code>: instructions that teach ForgeQE's agents something a prompt can't know, like your repo's test conventions, a framework, or how to drive an app such as Dynamics 365. The format is the Agent Skills one (Claude Code and others use it), with one ForgeQE field, <code>agents</code>:</p>
-<pre><code class="language-markdown">---
-name: contoso-erp
-description: &quot;Use when the site is the Contoso ERP (erp.contoso.com): the order grid, the customer lookup, and saving orders.&quot;
-agents: [browser]
----
-
-- The customer lookup opens a list after three letters; click the row whose name matches exactly.
-- Save with the floppy icon in the toolbar; wait until &quot;Saved&quot; shows in the status bar.
-</code></pre>
-<p><code>name</code> is lowercase words joined by hyphens, the same as the folder. Agents choose skills by <code>description</code> alone, so name the concrete signs it applies (a framework, a config file, a host, a product). Quote it when it contains <code>: </code>.</p>
-<p><strong>Who uses it.</strong> <code>agents</code> lists <code>forgeqe</code> (ForgeQE's agent: how to handle a kind of request), <code>scribe</code> (writing, healing, finding and reviewing tests), and <code>browser</code> (the browser agent). Without <code>agents</code>, a skill is for <code>forgeqe</code> and <code>scribe</code>; a browser skill must ask for <code>browser</code>.</p>
-<p><strong>How skills are used.</strong></p>
-<ul>
-<li>ForgeQE's agent and Scribe see the name and description of each skill meant for them, and load the ones that fit the job through the agent runtime's skill tool. A skill adds to their instructions and never overrides them. Scribe can also read files next to <code>SKILL.md</code> (for example <code>references/locators.md</code>) when the skill points to them.</li>
-<li>Browser runs: ForgeQE's agent passes the browser skills a goal needs to <code>browser_run</code> and <code>run_test_cases</code>. For <code>forgeqe suite</code>, <code>forgeqe monitor</code> and <code>forgeqe run --direct</code>, the engine picks them from the goal with one short model call (at most three), and remembers the choice for that goal, so a monitor's later rounds and repeated cases skip it. <code>--skill NAME</code> (repeatable) fixes the list; <code>--skill none</code> runs without any. The chosen skills' text is added to the browser agent's prompt, at most <code>skills.browser_max_chars</code> (6,000) characters in total; the browser agent reads only <code>SKILL.md</code>.</li>
-<li><code>run.json</code>, the <code>run.done</code> log line and the report list the skills a run used.</li>
-</ul>
-<p><strong>Where skills come from</strong>, lowest to highest precedence; a later source replaces a skill of the same name:</p>
-<div class="tbl"><table>
-<thead>
-<tr><th>Source</th><th>Folder</th></tr>
-</thead>
-<tbody>
-<tr><td>Built-in</td><td>the <code>skills/</code> folder ForgeQE ships: <code>playwright-typescript</code> and <code>dotnet-nunit-playwright</code> (Scribe), <code>dynamics-365</code> (browser), <code>writing-skills</code> (ForgeQE's agent)</td></tr>
-<tr><td>Global, only with <code>skills.external: true</code></td><td><code>~/.claude/skills</code>, <code>~/.agents/skills</code>, and the repo's <code>.claude/skills</code> and <code>.agents/skills</code></td></tr>
-<tr><td>User</td><td><code>~/.forgeqe/skills</code> (or <code>$FORGEQE_HOME/skills</code>)</td></tr>
-<tr><td>Project</td><td><code>.forgeqe/skills</code> next to <code>forgeqe.yaml</code>, and the repo's own <code>.forgeqe/skills</code></td></tr>
-<tr><td>Extra</td><td>each folder in <code>skills.dirs</code></td></tr>
-</tbody>
-</table></div>
-<p>Commit <code>.forgeqe/skills</code> so the team and CI share it. ForgeQE only ignores <code>.forgeqe/reports/</code>; if your <code>.gitignore</code> has <code>.forgeqe/</code>, replace it with <code>.forgeqe/*</code> and <code>!.forgeqe/skills/</code> (<code>forgeqe skills new</code> warns when git would ignore the new skill). To change a built-in skill, make a project skill with the same name.</p>
-<p>Skills from anywhere else stay out: the agent runtime's own discovery (<code>~/.claude/skills</code>, a repo's <code>.opencode/skills</code>, its built-in skills) is off, and each agent may load only the skills ForgeQE's registry gives it. Skill text is trusted like the repo's own files, so global skills are opt-in.</p>
-<pre><code class="language-yaml">skills:
-  enabled: true              # false (or skills: false) turns skills off
-  dirs: [../shared-skills]   # more folders, read last
-  disable: [dynamics-365]    # leave these out
-  external: false            # true: also the global folders above
-  browser_max_chars: 6000    # most skill text added to one browser run
-</code></pre>
-<p><strong>Commands.</strong></p>
-<div class="tbl"><table>
-<thead>
-<tr><th>Command</th><th>What it does</th></tr>
-</thead>
-<tbody>
-<tr><td><code>forgeqe skills</code></td><td>The skills each agent can use, where each comes from (and what it replaces), disabled skills, problems, and the folders read</td></tr>
-<tr><td><code>forgeqe skills show &lt;name&gt;</code></td><td>One skill's instructions</td></tr>
-<tr><td><code>forgeqe skills new &lt;name&gt; --description &quot;Use when …&quot; [--agent browser] [--user]</code></td><td>Start a skill in <code>.forgeqe/skills</code> (<code>--user</code>: <code>~/.forgeqe/skills</code>)</td></tr>
-<tr><td><code>forgeqe skills check</code></td><td>Validate every skill; exit 1 when one has a problem</td></tr>
-<tr><td><code>forgeqe skills enable|disable &lt;name&gt;</code></td><td>Edit <code>skills.disable</code> in <code>forgeqe.yaml</code>, keeping its comments</td></tr>
-<tr><td><code>/skills [name]</code></td><td>The same list, or one skill, in the shell</td></tr>
-</tbody>
-</table></div>
-<p>In the shell you can also ask: &quot;make a skill for our Dynamics date picker&quot; or &quot;teach Scribe our test conventions&quot;. ForgeQE's agent gathers the facts, writes the skill into <code>.forgeqe/skills</code> with <code>forgeqe_setup</code>, and it applies from the next session. It writes skills only when you ask.</p>
-</div>
-</section>
-</div>
-</article>
-</section>
 <section class="chapter" id="reference" aria-labelledby="reference-h">
-<header class="chead"><span class="mono">14</span><h2 id="reference-h">Reference</h2><p>MCP, tuning, logs, environment variables, and every command</p></header>
+<header class="chead"><span class="mono">16</span><h2 id="reference-h">Reference</h2><p>MCP, tuning, logs, environment variables, and every command</p></header>
 <section class="doc" id="doc-how_to_use-10-mcp">
 <h3>MCP</h3>
 <div class="prose"></div>
@@ -2295,6 +2648,31 @@ agents: [browser]
 <p>To share a session, type <code>/logs</code> in the shell (<code>/logs shots</code> adds screenshots), or run <code>forgeqe logs bundle</code> afterwards. Either writes one <code>.tar.gz</code> with the session log, the run folders it mentions (<code>run.json</code>, <code>steps.json</code>, <code>trace.md</code>, <code>resume.json</code>, <code>workflow.yaml</code>, the failure screenshot), your <code>forgeqe.yaml</code>, your profiles without keys, and the versions. <code>forgeqe logs</code> lists recent logs.</p>
 <p>Start with <code>--debug</code> (or set <code>FORGEQE_DEBUG=1</code>) for more: the browser engine logs at debug level, and long values such as tool results are kept whole instead of cut at 8,000 characters.</p>
 </div>
+<section class="doc sub" id="doc-how_to_use-which-tools-forgeqes-agent-gets"><h4>Which tools ForgeQE's agent gets</h4><div class="prose"><p>Every model call carries the definitions of the tools the agent has, so it does not get all of them. Each turn gets:</p>
+<ul>
+<li><strong>the core:</strong> help, setup, <code>use_capabilities</code>, and the test environments and their apps;</li>
+<li><strong>the capabilities the request is about</strong>, picked without a model call from its words (each capability's keywords
+in <code>src/capabilities/registry.ts</code>), the apps of the environment it names (a mobile app means the mobile tools), and
+links (the browser);</li>
+<li><strong>capabilities used in the last few turns</strong>, so a conversation keeps its tools.</li>
+</ul>
+<p>A capability this project cannot use yet (no mobile apps, no Jira) is not picked from words alone. When a request
+needs a capability the turn did not get, the agent calls <code>use_capabilities</code>, and ForgeQE continues the same request
+with its tools. With fewer tools in view, the agent also cannot mix up similar ones (<code>browser_run</code>, <code>desktop_explore</code>,
+<code>mobile_explore</code>). <code>forgeqe context</code> shows what a turn carries, and what each capability adds. The session log
+(<code>/logs</code>) records which capabilities each turn got and why (<code>agent.scope</code>).</p>
+<p>Pin capabilities on, or switch them off for a project, in forgeqe.yaml (ids from <code>forgeqe features</code>):</p>
+<pre><code class="language-yaml">agent:
+  capabilities:
+    always: [regression-packs]
+    off: [desktop-apps]
+</code></pre>
+<p><code>FORGEQE_TOOL_SCOPE=off</code> gives every tool on every turn.</p>
+<p>MCP clients of <code>forgeqe mcp</code> (Claude Desktop, Cursor, Claude Code) list tools once rather than per turn, so they get
+the core and every capability this project can use (no desktop tools without desktop apps, no tracker tools without a
+tracker). <code>use_capabilities</code> adds others and sends <code>notifications/tools/list_changed</code>, which tells the client to read
+the list again. For a client that ignores it, <code>forgeqe mcp --all-tools</code> lists every tool.</p>
+</div></section>
 </section>
 <section class="doc" id="doc-how_to_use-14-env-overrides">
 <h3>Env overrides</h3>
@@ -2307,9 +2685,13 @@ agents: [browser]
 <tr><td><code>WP_LLMS_JSON</code></td><td>Path to <code>llms.json</code></td></tr>
 <tr><td><code>WP_LLM_PROFILE</code></td><td>Active profile, unless <code>--profile</code> is set</td></tr>
 <tr><td><code>WP_AZURE_API_KEY</code> / <code>OPENAI_API_KEY</code> / <code>WP_API_KEY</code></td><td>Keys referenced by profiles</td></tr>
+<tr><td><code>GITHUB_TOKEN</code></td><td>A <code>github_copilot</code> profile's GitHub Models token for the browser engine (needs <code>models:read</code>), unless the profile's <code>api_key_env</code> names another; else the GitHub CLI's sign-in</td></tr>
+<tr><td><code>FORGEQE_COPILOT_AUTH</code></td><td>The Copilot sign-in <code>forgeqe auth login copilot</code> saves; set by ForgeQE from the credential store, not by hand</td></tr>
 <tr><td><code>FORGEQE_CONFIG_DIR</code></td><td>Global config folder (default <code>~/.config/forgeqe</code>): <code>forgeqe.yaml</code>, <code>llms.json</code> and <code>.env</code> used when a project has none</td></tr>
 <tr><td><code>FORGEQE_PYTHON</code></td><td>A Python that already has the engine's libraries, used instead of the managed venv (skipped, with a note, when it cannot run the engine)</td></tr>
 <tr><td><code>FORGEQE_DEBUG</code></td><td><code>1</code> logs at debug level, like <code>--debug</code></td></tr>
+<tr><td><code>FORGEQE_TOOL_SCOPE</code></td><td><code>off</code> gives ForgeQE's agent every tool on every turn, instead of the tools of the capabilities each request is about</td></tr>
+<tr><td><code>FORGEQE_ROUTING</code></td><td><code>off</code> also puts every playbook in the agent's prompt (for comparing, or ruling out a routing fault)</td></tr>
 <tr><td><code>FORGEQE_HOME</code></td><td>Where the managed engine lives, user skills (<code>skills/</code>), and page memory when there is no config file (default <code>~/.forgeqe</code>)</td></tr>
 <tr><td><code>ADO_ORG_URL</code> / <code>ADO_PROJECT</code> / <code>ADO_PAT</code></td><td>Azure DevOps organization, project, and token when <code>sources.azure_devops</code> doesn't set them</td></tr>
 <tr><td><code>JIRA_URL</code> / <code>JIRA_EMAIL</code> / <code>JIRA_API_TOKEN</code></td><td>Jira site and credentials when <code>sources.jira</code> doesn't set them</td></tr>
@@ -2338,7 +2720,7 @@ agents: [browser]
 <tr><td><code>forgeqe features</code></td><td>What ForgeQE can do, and what each capability still needs in this setup (works without a model)</td></tr>
 <tr><td><code>forgeqe docs [--guide|--open] [--copy DIR]</code></td><td>The bundled docs; <code>--guide</code> opens the user guide, <code>--open</code> the architecture page</td></tr>
 <tr><td><code>forgeqe mcp list</code></td><td>The MCP servers ForgeQE's agent gets from your settings</td></tr>
-<tr><td><code>forgeqe auth login [system|NAME]</code></td><td>Sign in to Azure DevOps, GitHub, Jira, Confluence, TestRail, Zephyr, qTest, or Xray in the browser, or save one secret, in the system's credential store</td></tr>
+<tr><td><code>forgeqe auth login [system|NAME]</code></td><td>Sign in to Azure DevOps, GitHub, GitHub Copilot (<code>copilot</code>), Jira, Confluence, TestRail, Zephyr, qTest, or Xray in the browser, or save one secret, in the system's credential store</td></tr>
 <tr><td><code>forgeqe auth [status]</code>, <code>forgeqe auth logout &lt;system&gt;</code></td><td>What is signed in; forget a sign-in</td></tr>
 </tbody>
 </table></div>