@capagents/forgeqe 1.3.2 → 2.0.0

package/README.md

@@ -1,6 +1,6 @@
 # ForgeQE
 
-Browser agent CLI. Say what you want in plain language: a goal to carry out in a browser, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs and calls ForgeQE's tools. The ForgeQE engine drives Chrome locally, or BrowserStack and TestMu AI/LambdaTest through their Chrome DevTools Protocol (CDP) endpoints, and a run that passes becomes a test in your repo's own language and framework, written by **Scribe**, ForgeQE's coding agent. Skills (`SKILL.md` folders, built in or in `.forgeqe/skills`) teach the agents your repo's conventions and the apps you test.
+Test agent CLI for web, Windows desktop and mobile apps. Say what you want in plain language: a goal to carry out in a browser, a Windows app or an Android or iOS app, test cases to run from Jira, Azure DevOps, Xray or a file, a test to write, or a CI pipeline to set up. ForgeQE's agent works out what that needs and calls ForgeQE's tools. The ForgeQE engine drives Chrome locally, or BrowserStack and TestMu AI/LambdaTest through their Chrome DevTools Protocol (CDP) endpoints, and a run that passes becomes a test in your repo's own language and framework, written by **Scribe**, ForgeQE's coding agent. Skills (`SKILL.md` folders, built in or in `.forgeqe/skills`) teach the agents your repo's conventions and the apps you test.
 
 The engine is the browser service from test-agent-nexus, copied into this package (`py/forgeqe_engine`). It keeps the nexus behaviour: error-recovery system prompt, fast-mode agent tuning, Chrome launch flags, the search/select loop breaker, the 600 s run timeout, compact workflow YAML with semantic locators. There is no dependency on test-agent-nexus, FastAPI, or a database.
 
@@ -60,10 +60,11 @@ ForgeQE sends no telemetry and turns it off in everything it starts:
 | File | Purpose |
 |------|---------|
 | `forgeqe.yaml` | Browser, prompts, export, active profile |
-| `llms.json` | Named LLM profiles (azure, openai, ollama, openai_compatible) |
+| `llms.json` | Named LLM profiles (azure, openai, ollama, openai_compatible, github_copilot) |
 | `.forgeqe/prompts/` | Every agent prompt as a markdown file, to change how an agent works (`forgeqe prompts` lists them) |
 | `.forgeqe/skills/` | The built-in skills, to adapt; add your own beside them |
 | `.forgeqe/knowledge/` | Product knowledge templates: product, roles, glossary, business rules, test data, environments |
+| `.forgeqe/guardrails/` | Your guardrails: rules every agent must follow, one `- rule` line each (`forgeqe guardrails` lists them, `forgeqe guardrails add "…"` adds one) |
 | `.forgeqe/browserstack.yaml` / `.forgeqe/testmu.yaml` | Sample remote-browser provider configs, ready to point `browser.providers` at |
 
 An unchanged copy keeps following ForgeQE's updates; once you edit it, yours wins.
@@ -77,6 +78,8 @@ forgeqe run "Read the homepage of example.com" --plain
 
 The active profile is `llm.active` in `forgeqe.yaml`, else `default` in `llms.json`, else the first profile; Tab switches in the shell. With none set up, ForgeQE says so and how to add one.
 
+**GitHub Copilot.** With Copilot licences, a `github_copilot` profile runs ForgeQE's agent and Scribe on the Copilot seat through the agent runtime's GitHub Copilot sign-in (`forgeqe auth login copilot`, GitHub.com or GitHub Enterprise). The browser engine uses GitHub Models with your GitHub sign-in (`forgeqe auth login github`, or `GITHUB_TOKEN`), optionally billed to an organization with `github_org`. See HOW_TO_USE.md, *GitHub Copilot seats as the model*.
+
 ## CLI
 
 ```bash
@@ -93,6 +96,8 @@ forgeqe run --direct "Read the homepage" --url https://example.com --out ./.forg
 
 There are no commands to pick a source or a mode. ForgeQE's agent reads the request and decides: a browser goal, test cases (Jira keys, Azure DevOps ids or test plans, Xray, TestRail, Zephyr Scale or qTest cases, files in the working directory, or cases pasted into the message), requirements to turn into cases (a Confluence page, a story), a test, or a pipeline. When a reference could mean more than one thing, it asks. The agent picks the site to open; `--url` only pins a start page.
 
+**Tools per turn.** ForgeQE's agent does not carry every tool on every turn. Each turn gets the core (help, setup, the environments) and the capabilities the request is about, picked from its words, the apps it names and its links, plus those used in the last few turns. When it needs another, it calls `use_capabilities` and carries on with the same request. Fewer tools mean a smaller prompt and no mix-ups between similar ones (`browser_run`, `desktop_explore`, `mobile_explore`). `agent.capabilities.always` and `off` in `forgeqe.yaml` pin or remove capabilities, and `FORGEQE_TOOL_SCOPE=off` gives every tool. See [HOW_TO_USE.md](HOW_TO_USE.md#which-tools-forgeqes-agent-gets).
+
 Inside the shell, type the request and press Enter (Ctrl+J starts a new line). The only commands are for the session: `/stop`, `/headed`, `/details`, `/profile`, `/logs`, `/skills`, `/clear`, `/help`, `/exit`. Everything the other commands do can be asked for in the shell too, since each one is a tool the agent calls: "heal the checkout tests", "check the smoke cases once", "monitor them every 10 minutes", "sign in to shop", "forget the shop session", "which profiles do I have?". While the agents work, the shell shows each step's result, the files the coding agent writes, test results, and problems, with what is happening now on the activity line; `/details on` (or `--verbose`) adds the browser agent's reasoning, page memory, engine logs, and every file the coding agent reads. Results appear as cards in the transcript, and when a step needs you (signing in by hand), a **Your turn** prompt waits until you pick **Done, continue** or **Cancel**.
 
 ForgeQE's agent needs the agent runtime (downloaded automatically, see Install) and a live profile. It uses the active `llms.json` profile, or `code.model: provider/model`. Without the agent runtime, the request runs as one browser goal.
@@ -116,7 +121,7 @@ forgeqe run "..." --replay trust       # or --replay off, --no-memory
 
 ## Skills
 
-Skills teach the agents what a prompt can't know: your repo's test conventions, a framework, or how to drive an app. A skill is a folder with a `SKILL.md` (the Agent Skills format: `name`, `description`, then instructions), plus ForgeQE's `agents: [forgeqe, scribe, browser]` to say who uses it. ForgeQE ships `playwright-typescript` and `dotnet-nunit-playwright` for Scribe, `dynamics-365` for the browser agent, and `writing-skills` for ForgeQE's agent. Your own go in `.forgeqe/skills` next to `forgeqe.yaml` (commit them) or `~/.forgeqe/skills`; a project skill replaces a built-in one with the same name. Skills in `~/.claude/skills` and `~/.agents/skills` are used only with `skills.external: true`.
+Skills teach the agents what a prompt can't know: your repo's test conventions, a framework, or how to drive an app. A skill is a folder with a `SKILL.md` (the Agent Skills format: `name`, `description`, then instructions), plus ForgeQE's `agents: [forgeqe, scribe, browser]` to say who uses it. ForgeQE ships `playwright-typescript`, `dotnet-nunit-playwright` and `testcontainers` for Scribe, `dynamics-365` for the browser agent, and `writing-skills` for ForgeQE's agent. Your own go in `.forgeqe/skills` next to `forgeqe.yaml` (commit them) or `~/.forgeqe/skills`; a project skill replaces a built-in one with the same name. Skills in `~/.claude/skills` and `~/.agents/skills` are used only with `skills.external: true`.
 
 Each agent sees the skills meant for it and loads the ones whose description fits the job. For browser runs, ForgeQE's agent passes the skills a goal needs; in `forgeqe suite`, `monitor` and `run --direct` the engine picks them from the goal once, and `--skill NAME` (or `--skill none`) fixes the list. Reports and `run.json` show which skills a run used.
 
@@ -182,6 +187,52 @@ forgeqe api scenarios --text "create a user, add two items, check out" --spec op
 forgeqe api run-scenarios --allow-writes
 ```
 
+### Environments
+
+`env.yaml` lists your test environments (dev, qa, uat, …) and the apps in each: web apps by URL, APIs by base URL, Windows apps by `.exe`, and mobile apps by package or bundle id. Its layout is up to you; ForgeQE reads any shape. The same test cases run in every environment: "run the smoke cases on uat" picks it for one request, and `--env NAME` (or `FORGEQE_ENV`) for a command. Secrets are listed by the name of the environment variable that holds them, never by value. `forgeqe apps` shows the environments and their apps. See [HOW_TO_USE.md](HOW_TO_USE.md#environments-and-apps).
+
+### Windows desktop apps
+
+ForgeQE drives Windows apps with Microsoft's UFO² (explore a goal with the model) and pywinauto (replay with no model). A run that passes is saved as a `forgeqe-desktop-v1` workflow you can read and edit.
+
+- **Replay** with timeouts, retries, `wait_for` (a control gone, or showing some text), and `dismiss` for dialogs that get in the way. A control that moved is healed with one model call and reported for review.
+- **Visual checks:** `expect_image` compares a control or the window with a baseline next to the workflow.
+- **Record by hand:** `forgeqe desktop record` saves the steps you do yourself as a workflow.
+- **Edit from chat:** "make step 4 wait for the Save button" changes the workflow with `desktop_edit_workflow`, after showing you the diff.
+- **CI:** `forgeqe desktop doctor` checks the machine (a signed-in, unlocked desktop session; Windows services run in session 0, which has none), and `--junit` writes results for the pipeline.
+
+```bash
+forgeqe desktop explore "Create an invoice for Contoso" --app erp
+forgeqe desktop record --app erp --name "New invoice"
+forgeqe desktop replay desktop-tests/ --junit results.xml
+```
+
+See [docs/DESKTOP.md](docs/DESKTOP.md) and [docs/DESKTOP-CI.md](docs/DESKTOP-CI.md).
+
+### Mobile apps (Android, iOS)
+
+One workflow format (`forgeqe-mobile-v1`) runs on **Appium** (explore with the model, replay step by step, healing, visual checks) and on **Maestro** (the workflow becomes a Maestro flow). Your team's own Maestro flows run too, after an allowlist check that refuses scripts, AI commands and file access. Both run on a local emulator or device, or on TestMu AI's devices: `forgeqe mobile upload app.apk` uploads a build and returns its `lt://` id, and Maestro runs there through HyperExecute. `samples/mobile-testmu/` is a ready project that reads `LT_USERNAME` and `LT_ACCESS_KEY` from a `.env` file.
+
+```bash
+forgeqe mobile explore "Sign in as the courier and accept the first delivery" --app courier
+forgeqe mobile replay workflow.yaml --driver maestro
+forgeqe mobile maestro .maestro/
+```
+
+See [docs/MOBILE.md](docs/MOBILE.md).
+
+### Services and mocks in Docker
+
+With Docker or Podman installed, ForgeQE starts the services a test run needs (a database, a queue, the API under test) as `containers.services` in `forgeqe.yaml` declares them, waits until each is ready, and stops them when the session ends. `mock_service` runs a WireMock mock of an API, built from the calls a browser run recorded or from an OpenAPI description, and can point an API app of the environment at it. ForgeQE builds every container command itself: ports bind to 127.0.0.1, mounts are read-only and inside the project, and privileged containers, the host network and the runtime's socket are refused. `docker` and `podman` are blocked in the agents' own shell.
+
+```bash
+forgeqe services up db         # start and wait until ready
+forgeqe services               # what runs
+forgeqe services down
+```
+
+Services can also come from a docker-compose file (`containers.compose`), checked by the same rules. With `containers.tests`, `run_tests` runs the repository's tests in a container, after starting the services they need, which the tests reach by name. Scribe's `testcontainers` skill writes tests that start their own services from code. Or ask: "mock the payments API from the last run and point payments at it". See [docs/CONTAINERS.md](docs/CONTAINERS.md).
+
 ## Test cases and suites
 
 Run existing test cases instead of typing goals: ask for them by name ("run SHOP-12", "run test plan 12 suite 34", "run the cases in smoke.yaml") or paste them into the message. Each case becomes one goal: its steps are what the browser agent does and its expected results are what it checks, and the agent's own verdict decides pass or fail. With a repo set, every passed case also gets a test.
@@ -367,4 +418,4 @@ Rounds go to `.forgeqe/reports/monitor/<time>/`, the same as suites, so the repo
 { "mcpServers": { "forgeqe": { "command": "forgeqe", "args": ["mcp", "--repo", "/path/to/app"] } } }
 ```
 
-Tools: `browser_run`, `find_test_cases`, `save_test_cases`, `run_test_cases`, `run_details`, `run_test`, `page_memory`, `read_confluence`, `query_api`, `push_branch`, `set_ci_secret`, `find_tests`, `run_tests` (runs only with `confirmed: true`, once the user agreed), `review_pull_request`, `post_pr_review` (posts only with `confirmed: true`), `list_sprints`, and one tool per command: `write_test`, `heal_tests`, `monitor`, `logins`, `forgeqe_setup`. Browser runs and suites log their progress to stderr, and long calls send progress notifications.
+Tools: `browser_run`, `find_test_cases`, `save_test_cases`, `run_test_cases`, `run_details`, `run_test`, `page_memory`, `read_confluence`, `query_api`, `push_branch`, `set_ci_secret`, `find_tests`, `run_tests` (runs only with `confirmed: true`, once the user agreed), `review_pull_request`, `post_pr_review` (posts only with `confirmed: true`), `list_sprints`, and one tool per command: `write_test`, `heal_tests`, `monitor`, `logins`, `forgeqe_setup`. Browser runs and suites log their progress to stderr, and long calls send progress notifications. Desktop (`desktop_explore`, `desktop_replay`, `desktop_record`, `desktop_edit_workflow`) and mobile (`mobile_explore`, `mobile_replay`, `mobile_maestro`) tools are listed when the environment has such apps. The client gets the tools this project can use; `use_capabilities` adds others and sends `notifications/tools/list_changed`, and `forgeqe mcp --all-tools` lists every tool.

package/docs/ARCHITECTURE.md

@@ -1,6 +1,6 @@
 # ForgeQE CLI architecture
 
-Three processes. The Bun CLI owns the shell, config, profiles, and ForgeQE's tools. ForgeQE's agent runs on the agent runtime, reads each request, and calls those tools over MCP. Scribe, the coding agent, runs on the same runtime and writes, heals, and reviews tests. A Python engine drives Chrome. There is no FastAPI server and no database.
+Three processes. The Bun CLI owns the shell, config, profiles, and ForgeQE's tools. ForgeQE's agent runs on the agent runtime, reads each request, and calls those tools over MCP. Scribe, the coding agent, runs on the same runtime and writes, heals, and reviews tests. A Python engine drives Chrome; two more drive Windows apps (`py/forgeqe_desktop`, on UFO² and pywinauto) and Android and iOS apps (`py/forgeqe_mobile`, on Appium and Maestro). There is no FastAPI server and no database.
 
 The single-view map of subagents, tools, and capabilities is [`forgeqe-architecture.html`](../forgeqe-architecture.html) (`forgeqe docs --open`). Suite `report.html` includes the browser agent's token counts, and a cost in the machine's currency when the profile has a price.
 
@@ -182,6 +182,21 @@ Tools take structured arguments. `run_test_cases` and `find_test_cases` get a li
 
 **Callers.** The TUI opens the brain on the first message and keeps it for the session, so follow-up answers and "write a test for that run" have context; `/profile` (or Tab) closes it and keeps the turns so far: the next agent session's first prompt is `carryOver(turns, text)`, the last 20 turns with remembered secrets redacted, so switching models does not lose the conversation. It renders `card` events as result panels and `agent` events as `⚙` and test lines with their own token counter, and its `waitForUser` pushes the prompt into the transcript and opens a **Your turn** dialog (Done, continue / Cancel); opening another dialog or Esc settles it as cancelled. `forgeqe run` opens the brain for one request, prints tool events (cards as `cardText`) and the reply as plain lines, waits for Enter in `waitForUser` when stdin is a terminal, and exits 0 done, 1 failed, 2 stopped, 3 needs input. `forgeqe run --direct` and a missing agent runtime run `browser_run` directly. `forgeqe mcp` serves the same `TOOLS` on stdio and logs `ToolEvent`s to stderr; it has no `waitForUser`. `forgeqe start` and `forgeqe mcp` stop background monitors when they return, because `src/index.ts` calls `process.exit`.
 
+## Tool scope (`src/mcp/scope.ts`, `src/capabilities`)
+
+Every model call carries the definitions of the tools the agent has, so the agent does not get every tool on every turn. The registry (`capabilities/registry.ts`) groups the tools into capabilities. Each capability has its tools, the requirements it needs (a model, a runtime, an app kind, a tracker), and keywords.
+
+| Module | Contents |
+|--------|----------|
+| `mcp/scope.ts` | `CapabilityScope`, one per agent session. `beginTurn(text)` picks the turn's capabilities and returns the per-prompt `tools` switches (`forgeqe_<tool>: true\|false`). The picks are: the core (`setup-help`, `test-apps`), `agent.capabilities.always`, the ones `use_capabilities` asked for, those used in the last `STICKY_TURNS` (3) turns, and up to `MAX_PICKED` (4) from `scoreRequest`. `scoreRequest` makes no model call: it matches keywords and tool names, URLs (the browser), issue keys (test cases), and the names of the active environment's apps (by kind). A capability whose required apps or system are missing (`usableCapabilities`) is not picked from words alone, and nothing is picked from `agent.capabilities.off`. When nothing matches, `browser-goals` is the fallback. `request` (from `use_capabilities`) refuses unknown and switched-off ids and queues the added ones in `takePending`. `listedTools` is the list for MCP clients. `capabilityIndex` is the short list of capabilities in the agent's prompt |
+| `mcp/captools.ts` | `use_capabilities`: adds capabilities for the rest of the session |
+| `mcp/routing.ts` | `createRouter` passes every ForgeQE tool that runs to `scope.used` |
+| `brain/index.ts` | `ask` starts each turn with `beginTurn` and prompts with its switches. When `use_capabilities` added capabilities during the turn, it continues the same request with them, at most `MAX_SCOPE_CONTINUATIONS` (2) times. `FORGEQE_TOOL_SCOPE=off` turns the scope off |
+| `mcp/server.ts` | With a scope, `tools/list` returns `listedTools`, the server advertises `listChanged`, and after a call that added capabilities it sends `notifications/tools/list_changed`. `forgeqe mcp --all-tools` serves without a scope |
+| `context.ts`, `agents.ts` | `forgeqe context`: the fixed context and what each capability adds. Budgets: 10000 tokens for the forgeqe agent's fixed context, 2500 per capability (`CAPABILITY_TOOL_BUDGET`) |
+
+The tools stay registered with the agent runtime for the whole session; only the switches change, so the conversation is never restarted. `tests/scope.test.ts` covers routing, gating, sticky turns, config, hostile ids, and the MCP list change. `tests/brain.e2e.test.ts` checks against the real agent runtime that a turn sees only its tools and that `use_capabilities` continues the request.
+
 ## Scribe, the coding agent (`src/code`)
 
 The test-writing loop used by `forgeqe code`, by `forgeqe suite` with a repo, and by the `write_test` tool, which is how ForgeQE's agent writes tests in the shell and `forgeqe run`. It uses the agent runtime SDK and the runtime binary that `code/runtime.ts` finds.
@@ -330,6 +345,51 @@ Every write-back includes the step verdicts, and retries once without the step d
 
 `runSuite` gives each case a run folder `NN-<id>` and runs `executeRun` with a pool of `parallel` workers. With a repo, a passed case is queued for the coding agent as soon as its browser run ends and its worker awaits that job before taking the next case, so each case is explored, handed off, and coded before the next one starts; the queue is one promise, so coding jobs never overlap. A case that is not coded records `codeSkipped` with the reason. Write-back and `fileBugs` run after every case finishes and skip stopped cases. `report.ts` writes `junit.xml` (failed → `<failure>`, error → `<error>`, stopped → `<skipped>`, step verdicts and posted links in `system-out`), `report.html` (`src/report/data.ts` turns the results into `ReportData`: step verdicts, the `steps.json` timeline with screenshots as data URIs up to a 40 MB budget, failed cases first, small text files such as the trace and workflow, posted records, each run folder's `run.json` (page memory with heals and repairs, browser diagnostics) and `accessibility.json`, the case's group and requirements, usage and cost, and history from the sibling `.forgeqe/reports/suites/*/suite.json`. From that history it also finds each failed case's last passing run folder (next to its `suite.json`, else where it was written) for the "last good vs now" screenshot of the same URL path, and each memory-replayed case's last run with no replay, as the baseline for page memory savings; `src/report/html.ts` injects it as `window.__FORGEQE_REPORT__` into `src/report/template.html`, a React app from `report-ui/` built into one file by `bun run build:report`; every single run writes one too), `suite.json`, the terminal summary, and the GitHub job summary (appended to `GITHUB_STEP_SUMMARY` when set). The `run_test_cases` tool calls the same `runSuite`, passing the working directory and `runCodeAgent` as the coder when the session writes tests (so the agent never calls `write_test` for those cases afterwards), and the shell renders a suite card. There is no pipeline template: the agent writes pipelines to fit each repository, and they call `forgeqe suite`.
 
+## Environments (`src/environments.ts`)
+
+`env.yaml` (named by `environments.file`) lists the environments and their apps, in any layout: `environments:` maps, top-level maps, or lists. They are all read into the same `Environment` (`apps` by kind: web, api, desktop, mobile; `variables`; `secrets` as names of environment variables). `activeEnvironment` picks one: `--env`, `FORGEQE_ENV`, `use_environment`, or the default. `withEnvironment` gives a config for one tool call's `env`. `exportEnvironment` puts the environment's `FORGEQE_APP_*` and variables into the environment of the tests ForgeQE runs. `environmentBrief` is what each agent is told: ForgeQE's agent gets every app, the browser agent its hosts, and Scribe the names to read so a test runs in every environment.
+
+## Desktop apps (`src/desktop`, `py/forgeqe_desktop`)
+
+`python -m forgeqe_desktop serve` takes JSON-lines requests from `src/desktop/bridge.ts`, as the browser engine does.
+
+- **Explore** runs UFO² in-process (`ufo_runner.py`, at a pinned commit) with the profile's model. Only UI actions are allowed, Win-key chords are refused, and the action trace becomes a `forgeqe-desktop-v1` workflow (`record.py`).
+- **Replay** (`replay.py` on `pywinauto_driver.py`) needs no model. It handles timeouts, retries, `wait_for` and `dismiss`, `expect_image` (`visual.py`), heal by numbered choice (`heal.py`), and checks of the outcome (`checks.py`).
+- **Recording by hand** (`handrecord.py`, `handhooks.py`) uses Windows hooks and UI Automation.
+- **Changes from chat:** `src/desktop/edit.ts` makes fixed-shape changes, validates them, shows the diff, and keeps a backup.
+- **Before a run:** `session.py` refuses a session that cannot be driven (session 0, locked, no screen), and `forgeqe desktop doctor` reports it.
+
+The full file list is in [DESKTOP.md](DESKTOP.md#code), and unattended runs are in [DESKTOP-CI.md](DESKTOP-CI.md).
+
+## Mobile apps (`src/mobile`, `py/forgeqe_mobile`)
+
+`forgeqe-mobile-v1` shares the desktop engine's workflow validation, replay, heal, checks and visual code.
+
+- **Appium:** `appium_driver.py` is a W3C WebDriver client over HTTP, with locators quoted as XPath literals. It drives replay and the model's explore loop (`explore.py`).
+- **Maestro:** `maestro.py` turns a workflow into a Maestro flow, with secrets as `MAESTRO_<NAME>` environment variables. It checks a team's own flows against an allowlist and runs `maestro test` with an argument list.
+- **TestMu AI:** `hyperexecute.py` writes a HyperExecute project and runs its CLI, scrubbing the access key from the output and the run folder. `src/mobile/run.ts` uploads builds (`forgeqe mobile upload`).
+
+The full file list is in [MOBILE.md](MOBILE.md#code).
+
+## Containers (`src/containers`)
+
+`containers:` in forgeqe.yaml declares services (`config.ts`). It refuses any setting outside the fixed list, an image without an exact version, a port bound to an address other than 127.0.0.1, and a mount option.
+
+- **`run.ts`** finds docker or podman and builds `run` arguments:
+  - ForgeQE's labels;
+  - `--security-opt no-new-privileges` and `--pids-limit`;
+  - `--publish 127.0.0.1:…`;
+  - `--env NAME` for secrets;
+  - `:ro` mounts.
+
+  It checks mounts as uploads are checked (inside the project; nothing hidden, key-named or linked). It waits for a TCP or HTTP ready check. Docker's port proxy accepts connections before the service listens, so a TCP connection counts only when it stays open. It scrubs secrets from logs and errors, and tracks the containers it started, which the CLI removes on exit.
+- **`mock.ts`** makes WireMock stubs from `network.json` or a contract set.
+- **`compose.ts`** translates docker-compose services into forgeqe.yaml services, refusing settings that widen what a container reaches. `startOrder` (`config.ts`) orders services by `depends_on`. Every container joins the project network `forgeqe-<key>` under its service name.
+- **`tests.ts`** is a `runTestCommand` for `run_tests` with `containers.tests`. It runs the confirmed command with `sh -c` in the image, with the repository mounted at its own path, `--user` this machine's user, and only the environment's FORGEQE_* variables, the saved-login variables, and the listed env and secrets, by name.
+- **The agent's tools** are `services` and `mock_service` in `src/mcp/containertools.ts`, and the CLI is `forgeqe services` (`command.ts`).
+- **The agents' shell:** `BASH_PERMISSION` denies docker, podman, nerdctl and compose commands for the agent and Scribe.
+- **Tests:** `tests/containers.test.ts` uses a fake runtime. `tests/containers.live.test.ts` uses real Docker and is skipped without it.
+
 ## Monitoring (`src/monitor`)
 
 `forgeqe monitor` is `runSuite` on a timer, plus memory between rounds of which checks are failing, plus alerts.
@@ -405,4 +465,5 @@ Rounds are ordinary suite folders, so `report.html` gets trends and flaky checks
 - `tests/heal.test.ts`: the healing loop with a scripted session that calls ForgeQE's tools over the real MCP server (only the four heal tools are listed; the browser run lands in the heal folder): nothing to heal, healed and confirmed, an app bug left failing, a healed test that still fails or has no command, finding the command, `code.test_command`, a missing report, a fatal error, and stop. `tests/monitor.test.ts`: `decide` sequences (fail_after, flaky, reminders, recovery, stopped, a round that could not run), duration and `monitor:` parsing, rounds through the real `runSuite` with state carried over, report links, attachments, `alerts.json`, pruning, the loop and `--once` exit codes, the lock against a live pid, the Teams card against a fake webhook, email through nodemailer to a local fake SMTP server (login, recipients, subject, screenshot), and secrets scrubbed from errors. `tests/cli.test.ts` runs `forgeqe monitor --test-alerts` and `--once` with the mock profile against a fake Teams webhook.
 - `tests/commands.test.ts`: the command tools called as the agent calls them: `write_test` with a scripted session (agent events, the card, the mock profile refused), `heal_tests` clean and healed, `monitor` round and status, `start` refused in a `once` session, start/status/stop in a `shell` session (a round card, a second start and a one-off round refused, the lock released), `test_alerts` against a fake webhook, `logins` list/clear and `sign_in` without a person, `page_memory` flows and clear, and `forgeqe_setup` profiles, MCP servers, docs by topic, and init. `tests/repotests.test.ts`: `parseResults` on JUnit and TRX; `find_tests` with a scripted Scribe (the read-only agent, the listing fed back, a corrected list command listed again, nothing found, mock profile and bad dates refused); `run_tests` declined (nothing runs), confirmed (per-test card from JUnit, the heal suggestion), and without `ask` (`needs_confirmation`, then `confirmed: true`, exit code only); sprints from fake Azure DevOps and Jira APIs (paging, the pick through `ask`, cancel, `needs_choice`, a name matched). `tests/engine/test_step_notes.py`: the agent's note built from its own fields and stored on the flow steps a step recorded, `evaluate` steps with their code. `tests/code.test.ts` (handoff): notes before each group of steps, once per step, and the JavaScript shown. `tests/update.test.ts`: bun and pip installs found in PATH order; waiting while the registry 404s, then the cache-skipping commands per install; `--check` running nothing; a release never served failing with a retry hint. `tests/sessionLog.test.ts`: the session header and events with remembered passwords, secret environment variables, and inline API keys replaced; tool calls and results; the bundle's contents without screenshots or keys; `/logs`. `tests/engine/test_page_settle.py`: the judge off by default and on by setting, `page_settled`, `settle_page` waiting for a new tab and giving up on one that stays blank, and note actions as read-only. `tests/resume.test.ts`: resume steps in the run result, `loadResume` by folder or run name, and `browser_run` returning the retry and passing `resume_from`. `tests/engine/test_resume.py`: `resume_point`, `resume_steps`, the loop start and nudge text, `_install_nudges` draining after the library's hook, resume steps in the flow file, the resume hand-off, checkpoints (kept apart from flows, cleared only by their own run, kept by a stopped run), and the hand-off after a cut-off run. `tests/code.test.ts` (resuming): a stopped job keeps `scribe-session.json` and a finished one removes it, a rerun reopens the session with the saved replay and a carry-on prompt, and a gone session starts fresh; `tests/code.e2e.test.ts` reopens a session by id after the runtime restarted and finds its earlier messages. `tests/engine.e2e.test.ts` runs a page where clicking "One way" resets the date: a model that takes the nudge finishes; one that ignores it is stopped with its resume steps saved, and a retry with `resume_from` replays the cookie click and needs two model calls. `tests/sessionLogins.test.ts`: remembered logins (domains from a URL, hosts, and wildcards; the engine payload with values; no process env), redaction next to punctuation and in carried-over turns, a remembered login replacing a configured one in the notes, ForgeQE's test runs getting the env names with the output redacted, and the `logins` tool's remember/list/clear without the password in any result. `tests/engine/test_session_logins.py`: remembered values as placeholders on every sign-in domain, env values still working, `step_outcomes`, and `making_progress`. `tests/tui.test.tsx` renders a monitor round's card in the transcript and checks the **Your turn** dialog holds a tool until **Done, continue**.
 - `tests/skills.test.ts`: `skills:` parsing; the prebuilt skills loading cleanly; precedence and `overrides` across user, project, the repo's own folder, and `dirs`; the repo's `.claude` skills only with `external`; the default and opt-in `agents`; `disable` and unknown names; every validation problem (including the unquoted `: ` hint); the per-agent `skill` permission and `skills.paths` in the runtime config; links readable through and removed without touching the skill; `browserSkills` given and choose, unknown names, and the remembered choice; the engine request through a stub engine and `skills` back on the result; the skills catalogue in the environment notes; `newSkill`, `setSkillDisabled` keeping comments, and `ignoredNote`; the overview and `/skills`; and `forgeqe skills new/show/disable/enable/check` end to end. `tests/code.e2e.test.ts` checks, against the real agent runtime, that Scribe's skill listing has only the registry's skills for it, an allowed skill's text arrives, and a disabled skill, the repo's `.opencode` and `.claude` skills, the runtime's built-in skill, and `~/.claude/skills` stay out unless `external` adds them through the registry. `tests/engine/test_skills.py`: `choose_skills` order, the cap of 3, errors and an empty catalogue without a model call; `skills_block` within `skills_max_chars`; the request fields.
+- `tests/desktop.test.ts`, `tests/mobile.test.ts`, `tests/scope.test.ts`, `tests/capabilities.test.ts`: the desktop and mobile commands and tools, workflow edits, uploads, and the tool scope. `<engine-python> -m pytest tests/desktop`: the desktop and mobile engines against fake drivers, a fake Appium server and a stand-in Maestro (any OS). The `*_live` tests need Windows or an emulator, and run in `.github/workflows/forgeqe-desktop-windows.yml` and `forgeqe-mobile-android.yml`.
 - `<engine-python> -m pytest tests/engine`: the engine directly, with a scripted model, including `test_memory.py` (locators, confidence, identity, flows, secrets) and replay, trust mode, and self-healing against real Chrome. `test_brand.py` checks the overlay in real Chrome: the start page, trusted CDP clicks and keys dropped while locked and let through while acting, the unlocked state and step text on a page loaded mid-step, and a clean screenshot and DOM for the model. `WP_E2E_HEADED=1` runs the bun e2e test in a visible browser, with the overlay on.

package/docs/CONTAINERS.md

@@ -0,0 +1,227 @@
+# ForgeQE containers: services and mocks in Docker or Podman
+
+Status: the tests run against a fake runtime on any OS. They check the commands ForgeQE builds, the checks on config,
+compose files, mounts and secrets, the mock stubs, and tests in a container. `tests/containers.live.test.ts` runs on
+real Docker (and is skipped without it):
+- Postgres from forgeqe.yaml and from a compose file.
+- A WireMock mock that answers a recorded run's calls.
+- A tests container that reaches the database by name and writes its results into the repository as this machine's
+  user.
+
+`.github/workflows/forgeqe-containers.yml` runs both on GitHub's Docker. There, a skipped live test fails the job.
+
+ForgeQE uses Docker or Podman, when one is installed, for three jobs:
+
+- **Services a test run needs:** a database, a queue, a cache, or the API under test. The project declares them in
+  forgeqe.yaml, or in a docker-compose file that forgeqe.yaml names.
+- **Mocks of an API:** WireMock stubs made from the calls a browser run recorded, or from an OpenAPI description, so
+  the tests can run without the real service.
+- **The repository's tests in a container:** `run_tests` runs the command the user confirmed in an image, instead of
+  on this machine, after starting the services the tests need.
+
+Scribe also has a `testcontainers` skill, for tests that start their own services from code (below).
+
+ForgeQE's agent uses them through two tools, `services` and `mock_service`. The CLI has `forgeqe services`. When
+neither Docker nor Podman is on PATH, the agent isn't offered these tools.
+
+## Use
+
+```bash
+forgeqe services                     # the declared services, what runs, whether the runtime answers
+forgeqe services up                  # start every declared service and wait until each is ready
+forgeqe services up db queue         # just these
+forgeqe services logs db --lines 50  # last lines, secrets removed
+forgeqe services down                # stop and remove this project's containers (mocks included)
+```
+
+In the shell or `forgeqe run`, you can ask, for example:
+- "start the database"
+- "is the queue up?"
+- "mock the payments API from the last run"
+- "make a mock service from openapi.yaml and point order-api at it"
+- "stop the services"
+
+The agent asks before it starts anything.
+
+## Declaring services
+
+```yaml
+# forgeqe.yaml
+containers:
+  runtime: docker                       # docker | podman; default: docker, else podman, on PATH
+  services:
+    db:
+      description: Orders database for the API tests
+      image: postgres:16.4              # an exact version, or name@sha256:<digest>
+      ports: [5432]                     # 127.0.0.1:5432 -> 5432; "15432:5432" maps another port of this machine
+      env:                              # plain values only
+        POSTGRES_DB: shop
+        POSTGRES_USER: shop
+      secrets: [POSTGRES_PASSWORD]      # environment variable names; their values come from the environment or .env
+      volumes:
+        - ./db/init:/docker-entrypoint-initdb.d    # read-only; a folder or file inside the project
+      command: ["-c", "log_statement=all"]         # arguments for the image's entrypoint
+      ready: { tcp: 5432 }              # or { http: /health, port: 8080 }; without it: the container runs
+      timeout: 90                       # seconds to wait until ready (default 60)
+    queue:
+      image: rabbitmq:3.13.7-management
+      ports: [5672, 15672]
+      ready: { http: /, port: 15672 }
+  mock:
+    image: wiremock/wiremock:3.9.1      # the default
+```
+
+| Setting | Rule |
+|---|---|
+| Service name | Lower-case letters, digits and `-`, starting with a letter. Names starting with `mock-` are kept for mocks. |
+| `image` | Must have an exact tag or a digest. An untagged image or `latest` is refused, because it changes under the same name. |
+| `ports` | Always bound to 127.0.0.1. An address such as `0.0.0.0:5432:5432` is refused. |
+| `env` | Plain values on one line. Secrets go under `secrets`. |
+| `secrets` | Variable names. They are passed to the runtime by name (`--env NAME`), so the value is never on a command line. One of ForgeQE's own keys (a model key, a tracker token) is refused. |
+| `volumes` | Always read-only. Must be inside the folder of forgeqe.yaml, and can't be the whole folder. |
+| `command` | A list of arguments, never one command string. |
+| `depends_on` | Services to start first. |
+| Anything else | Refused with an error, not ignored. That includes `privileged`, `network`, `cap_add`, `devices`, `user`, `pid` and the socket. |
+
+Every service, whether from forgeqe.yaml or a compose file, can list `depends_on`. `up` starts a service after the
+ones it depends on; a circle is refused.
+
+## Compose files
+
+```yaml
+containers:
+  compose: docker-compose.yml          # or a list; inside the project
+```
+
+ForgeQE reads each service of the file and translates it into a forgeqe.yaml service. The same rules then check it,
+and a service declared in forgeqe.yaml wins over the compose file's service of the same name. Compose itself never
+runs.
+
+| Compose | ForgeQE |
+|---|---|
+| `image` | Required; an exact version or a digest. `build` is refused: build and tag the image first. |
+| `ports` | `"5432"`, `"15432:5432"`, `"127.0.0.1:15432:5432"`, or the long form; always bound to 127.0.0.1. Any other address, and UDP, are refused. |
+| `environment` | Plain values are passed as they are. `KEY: ${KEY}`, `KEY` alone in the list form, and `KEY: ${KEY:-default}` pass the variable by name as a secret. `${OTHER}` under another name, and values that mix text and `${…}`, are refused. |
+| `volumes` | Bind mounts (`./db/init:/docker-entrypoint-initdb.d`) are mounted read-only, and `:rw` is noted. Named and anonymous volumes are left out, so the container keeps no data between runs. A path outside the project is refused when the service starts. |
+| `command` | A list, or a string split into arguments (compose uses no shell, and neither does ForgeQE). |
+| `depends_on` | List or map form: the start order. `condition` is not used; ForgeQE waits until each service is ready. |
+| `x-forgeqe` | `ready`, `timeout`, `description`, as in forgeqe.yaml. Without `ready`, a service with ports is ready when its first port takes connections. |
+| `container_name`, `restart`, `labels`, `healthcheck`, `networks`, `expose`, `deploy`, `profiles`, … | Ignored: ForgeQE names, labels and networks the containers itself. |
+| `privileged`, `network_mode`, `cap_add`, `devices`, `pid`, `ipc`, `user`, `security_opt`, `volumes_from`, `env_file`, `entrypoint`, `extends`, … | Refused, and the error names the setting. |
+
+What was left out (a named volume, a mount made read-only) is listed in `notes`.
+
+## The project network
+
+Each project's containers join their own network, `forgeqe-<project>`, under their service name. So the API container
+reaches the database as `db:5432`, and the tests container reaches both. No other container joins the network, and no
+container is on the host's network. `forgeqe services down` with no names also removes the network.
+
+## Tests in a container
+
+```yaml
+containers:
+  tests:
+    image: mcr.microsoft.com/playwright:v1.48.2-jammy   # an exact version; the tests' toolchain
+    services: [db, order-api]          # started first (when not running yet); the tests reach them by name
+    env: { DB_HOST: db }
+    secrets: [TEST_DB_PASSWORD]
+```
+
+With `containers.tests` set, `run_tests` runs the tests in that image unless it is called with `in_container: false`.
+Its confirmation says where the tests will run. The container:
+
+- **Runs the command the user confirmed** with the image's own shell, `sh -c "<command>"`, inside the container,
+  never on this machine.
+- **Mounts the repository read-write at its own path** and works in it, so results land where ForgeQE reads them.
+  On this machine, the tests already have the whole disk. A folder outside the repository that the results go to is
+  mounted the same way.
+- **Runs as this machine's user** (`--user uid:gid`), so files it writes are yours. It also gets
+  `--security-opt no-new-privileges`, `--pids-limit 4096` and `--rm`, and it is removed by name when the run ends or is
+  stopped.
+- **Gets only these variables:** `CI=1`, `NO_COLOR`, `HOME=/tmp`, the environment's `FORGEQE_ACTIVE_ENV`,
+  `FORGEQE_APP_*` and `FORGEQE_VAR_*`, the saved logins' variables, and `containers.tests` `env` and `secrets`.
+  Secrets are passed by name. ForgeQE's own keys are never passed.
+- **Has secret values removed from its output**, as on this machine.
+
+This needs a Linux or macOS machine, because the repository is mounted at its own path.
+
+## Testcontainers (Scribe)
+
+When a test needs a real service, or the repository already uses Testcontainers (Java, .NET, Node, Python, Go), Scribe
+loads the `testcontainers` skill. It reuses the repository's containers and fixtures, pins images, waits for
+readiness, uses the mapped port, and sets the app's own configuration from it. It never uses privileged mode, the
+host network, the Docker socket, or a `docker` command from a test. These containers belong to the tests in the
+repository: the tests start and stop them, wherever they run.
+
+## Mocks
+
+`mock_service` builds WireMock stubs and runs WireMock on a free port of 127.0.0.1:
+
+- **From a run** (the default: the latest run, or `run_dir`):
+  - One stub per method, path and query of the app's own API calls, answering with the last status, content type
+    and body the app got.
+  - Other sites' calls are left out unless `third_party` is set.
+  - Failed calls are left out.
+  - Answers that were cut when recorded are listed under `skipped`.
+- **From a description** (`spec`: OpenAPI 3 or Swagger 2, a link or a file):
+  - One stub per REST operation.
+  - Each stub answers with the operation's first success status and a body from the schema's examples, or values
+    made from its types.
+  - A path parameter (`/orders/{id}`) matches any one path segment.
+  - Instead of a description, you can give a contract set from `api_contracts` (`set_id`).
+- **GraphQL, SOAP and gRPC** are listed under `skipped`, not mocked.
+
+A spec given as a link is fetched by ForgeQE itself, with no credentials, as `api_contracts` does. The stubs are written to `.forgeqe/mocks/<name>/mappings/`. You can read and edit them there. The folder is mounted
+read-only at `/home/wiremock/mappings`. WireMock runs with `--enable-stub-cors`, so a web app on another local port
+can call it.
+
+With `for_app: <api app>`, the active environment's API app points at the mock for the rest of the session. That
+covers the API tools, and the tests ForgeQE runs, which read `FORGEQE_APP_<APP>_URL`. env.yaml itself is not
+changed.
+
+## Lifetime
+
+- **Services and mocks the agent starts** are removed when the shell, `forgeqe run`, or `forgeqe mcp` ends.
+- **`forgeqe services up`** keeps its services running after the command ends, until `forgeqe services down`.
+- **Container names** are `forgeqe-<project>-<service>`. `<project>` is a hash of the project folder, so two projects
+  never share a container. Starting a service replaces its earlier container. Removing a container also removes the anonymous volumes its image declares (a database's data folder), so nothing is left on the machine. A container is never reused with old
+  settings.
+- **Labels:** each container carries `forgeqe=1`, `forgeqe.project`, `forgeqe.service` and `forgeqe.kind`.
+  `down` and `status` look only at this project's containers.
+
+## Security
+
+ForgeQE's agent reads text other people control: tickets, web pages, repositories. A container command built from that
+text could mount the whole disk or run privileged, so:
+
+- **No commands from the model.** The agent names services that forgeqe.yaml declares, and ForgeQE builds the
+  argument array (`docker run …`). It never uses a shell. Images, flags and mounts never come from a request.
+- **The same restrictions for every container:** `--security-opt no-new-privileges`, `--pids-limit 1024`, ports on
+  127.0.0.1, and read-only mounts. There is no setting to turn these off.
+- **Mounts are checked like uploads** (except a mock's stubs folder, which ForgeQE writes itself and mounts read-only). The path is resolved with `realpath` and must be inside the project. A mount
+  that is or holds a hidden file or folder (`.env`, `.git`, `.npmrc`), a file named like a key (`*.pem`, `id_rsa`,
+  `llms.json`) or a link is refused. A container can send what it reads anywhere.
+- **Environment:**
+  - The `docker` and `podman` programs see only the system settings and the variables they need to find their daemon
+    (`DOCKER_HOST`, `DOCKER_CONTEXT`, `CONTAINER_HOST`, …), plus the service's listed secrets.
+  - A container gets only its `env` and `secrets`.
+  - Logs and errors have secret values replaced with `***`.
+- **Not in the agents' shell:** `docker`, `podman`, `nerdctl`, `docker-compose` and `podman-compose` are denied in the
+  shell of ForgeQE's agent and of Scribe. So the only way to start a container is these tools.
+- **Asked first:** `services up` and `mock_service` ask the user before starting, as `run_tests` does.
+
+## Code
+
+| File | Contents |
+|---|---|
+| `src/containers/config.ts` | `containers:` in forgeqe.yaml: services, images, ports, env, secrets, mounts, ready checks |
+| `src/containers/run.ts` | The runtime (docker or podman), `run` arguments, mount and secret checks, start and wait, status, logs, stop, the session's containers |
+| `src/containers/mock.ts` | WireMock stubs from run traffic and from contract sets; values from JSON schemas |
+| `src/containers/compose.ts` | docker-compose files as services: what is translated, ignored, left out or refused |
+| `src/containers/tests.ts` | `run_tests` in a container: arguments, environment, mounts, output |
+| `src/containers/command.ts` | `forgeqe services` |
+| `skills/testcontainers/SKILL.md` | Scribe's Testcontainers skill |
+| `src/mcp/containertools.ts` | The agent's `services` and `mock_service` |
+
+Tests: `bun test tests/containers.test.ts`, which uses a fake runtime that records each command. `tests/containers.live.test.ts` uses real Docker.

package/docs/COST_ARCHITECTURE.md

@@ -278,3 +278,35 @@ different state. Flows like that stay with the agent until replay can repeat tho
 | **3** | Router (small model) plus Tier 1 adapt. Repo code tests run directly (`dotnet test` / `npx playwright test` with filters, results files parsed). | Reworded and new-data reruns at ≤5% |
 | **4** | Tool-result cache, context packs, history compaction. Release check as a fixed workflow. | The release check takes 0–1 agent calls; the agent's average context per call is down by half |
 | **5** | `forgeqe cost` report and the evaluation suite in CI | Metrics in section 7 reported per release |
+
+## 12. Per-turn tool scope (2026-10-17)
+
+Tool definitions are part of the fixed overhead in section 1, and they grew with the desktop, mobile and
+TestMu tools. The forgeqe agent's fixed context went past its budget. ForgeQE's agent now gets the tools of
+the capabilities a turn needs, not all of them (`src/mcp/scope.ts`; see
+[ARCHITECTURE.md](ARCHITECTURE.md#tool-scope-srcmcpscopets-srccapabilities)):
+
+- **Every turn:** the core (help and setup, `use_capabilities`, the test environments and their apps).
+- **Picked without a model call:** up to four capabilities matched from the request's words, the apps it
+  names, its links and issue keys. A capability the project has no apps or tracker for is not picked from
+  words alone.
+- **Sticky:** capabilities whose tools ran in the last three turns.
+- **On request:** `use_capabilities` adds one when the request turns out to need it, and ForgeQE continues the
+  same request.
+
+`forgeqe context`, measured on this repo:
+
+| | Tokens |
+|---|---|
+| The forgeqe agent's fixed context (prompt 6.2K + core tools 1.6K) | 7.8K of a 10K budget |
+| A turn with the four largest capabilities | 14.7K |
+| Every tool on every turn (`FORGEQE_TOOL_SCOPE=off`) | about 26.7K |
+| Largest single capability (`api-testing`, `systems`) | 1.8K of a 2.5K budget per capability |
+
+A typical turn ("replay the courier login on Maestro") adds one or two capabilities, around 1–3K. Beyond
+the cost, fewer tools in view keep the agent from mixing up similar ones (`browser_run`,
+`desktop_explore`, `mobile_explore`). The test `tests/agents.test.ts` fails when an agent or a capability passes its
+budget. That keeps new tools from bringing the fixed overhead back.
+
+**Still to measure:** live-model evaluations of the tool picks against `FORGEQE_TOOL_SCOPE=off`: the success
+rate, the `use_capabilities` calls per request, and tokens per request.

package/docs/DESKTOP-CI.md

@@ -0,0 +1,87 @@
+# Running desktop workflows unattended (nightly CI)
+
+Desktop replay clicks and types into real windows. It needs what a person at the machine would have: a signed-in
+Windows session, unlocked, with a screen. GitHub's hosted `windows-2022` runners have that, and ForgeQE's own CI runs
+Notepad there. Your own apps usually need a machine of your own, with the app installed, its test database, and a
+network route to its servers. This page sets one up as a GitHub Actions self-hosted runner. The same rules apply to
+Azure DevOps agents and Jenkins nodes.
+
+## What breaks a desktop run, and how ForgeQE tells you
+
+| Situation | Effect | Fix |
+|---|---|---|
+| The runner is a Windows service | Session 0 has no desktop; every control lookup times out | Run the runner in the user's session (below) |
+| The screen is locked | Windows sends no input to apps | No inactivity lock, no screen-saver lock |
+| A Remote Desktop session was disconnected | The session is locked | Leave Remote Desktop with `tscon` (below), or don't use it on the test machine |
+| The machine slept or the screen turned off | Input and screenshots stop | Power plan: never sleep, never turn off the screen |
+| After a restart nobody signs in | No session at all | Sysinternals Autologon |
+
+Before each replay or explore, the engine checks the session (`py/forgeqe_desktop/session.py`). On a session it cannot
+drive, the run fails at once with the reason, instead of timing out step by step. `forgeqe desktop doctor` runs the
+same check from a shell or a job:
+
+```text
+engine   ready (C:\Users\qa\.forgeqe\desktop\.venv\Scripts\python.exe)
+explore  not set up (forgeqe desktop setup --ufo)
+session  1, screen 1920x1080
+desktop  logged in and unlocked
+```
+
+It exits with 1 when the desktop cannot be driven, so a job stops before the suite runs.
+
+## Set up the test machine
+
+Use a test machine or VM, and a test account: the runner's jobs control its mouse and keyboard.
+
+1. **Sign in** as the account the tests will run as.
+2. **Install the runner** (GitHub: Settings → Actions → Runners → New self-hosted runner). Give it the label
+   `forgeqe-desktop`. When `config.cmd` asks whether to run as a service, answer **no**.
+3. **Run `ci/desktop-runner/prepare-runner.ps1`** in an elevated PowerShell (`-WhatIf` first to see the changes):
+
+   ```powershell
+   .\prepare-runner.ps1 -RunnerDir C:\actions-runner -WhatIf
+   .\prepare-runner.ps1 -RunnerDir C:\actions-runner
+   ```
+
+   It stops sleep, screen-off and the screen-saver lock. It turns the inactivity lock off and registers a logon task
+   that starts `run.cmd` in this account's session. It warns you if the runner is also installed as a service. It
+   never handles a password.
+4. **Sign in automatically after a restart** with
+   [Sysinternals Autologon](https://learn.microsoft.com/sysinternals/downloads/autologon), run as the test account.
+   It stores the password encrypted by Windows. Never put the password in a script, a registry value you write
+   yourself, or the repository.
+5. **Fix the screen size.** A visual check (`expect_image`) compares pixels, so the resolution and scale (100%, 125%)
+   must match the machine where its baselines were saved. Set them once and leave them.
+6. **Restart** and check that the runner shows as idle on GitHub. Then run `forgeqe desktop doctor` from a job.
+
+### Leaving Remote Desktop without locking the session
+
+Closing a Remote Desktop window disconnects the session, and Windows locks it. To leave it running instead, hand the
+session back to the machine's console. In an elevated prompt inside the Remote Desktop session:
+
+```bat
+for /f "skip=1 tokens=3" %s in ('query user %USERNAME%') do tscon %s /dest:console
+```
+
+On a VM, the hypervisor's console (Hyper-V, VMware, VirtualBox) needs no such step.
+
+## The nightly job
+
+`ci/desktop-runner/desktop-nightly.example.yml` is a ready workflow. Copy it into `.github/workflows/` in the
+repository that holds your desktop workflows. It:
+
+- runs at night on `[self-hosted, windows, forgeqe-desktop]`, one run at a time;
+- installs a pinned ForgeQE and runs `forgeqe desktop setup` and `forgeqe desktop doctor`;
+- replays every workflow in a folder: `forgeqe desktop replay desktop-tests/ --junit results/desktop.xml`;
+- keeps the reports, screenshots and image diffs as an artifact.
+
+`--junit` writes one test case per workflow (and per CSV row with `--data`), which CI servers show as test results.
+`runs.json` in the output folder has the same, with the path of each report.
+
+Secrets the workflows type (`{{secret:NAME}}`) come from the CI's secret store as environment variables, and must be
+listed in `desktop.secrets` or the environment's `secrets` in `env.yaml`. Pick the environment with `FORGEQE_ENV` or
+`--env`.
+
+Healing calls the model. In a nightly run, either give the job the model's key so moved controls are healed and
+reported in `heals.json` (never written into the workflow without `--accept-heals`), or pass `--no-heal` so a moved
+control fails the run.