@capagents/forgeqe 1.3.0 → 1.3.2

package/HOW_TO_USE.md

@@ -71,7 +71,7 @@ Everything ForgeQE can do, by area. ForgeQE's agent answers "can you…?" questi
 | Release | **Reports you can share**: Writes up what ForgeQE's agent found, such as open defects across projects, release status, or pipeline health, as a page with filters (project, state, priority, assignee, …), charts, and a sortable table, plus Markdown and CSV. Every table is built from evidence: the results of the tool calls the agent made, or a read-only query ForgeQE runs itself, listed on the page's Sources with each raw result kept beside the report. | `write_report` | [docs](#reports-from-the-agent) |
 | Operations | **CI pipelines**: Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green. | `push_branch`, `set_ci_secret` | [docs](#8-pipelines) |
 | Systems | **Work with Azure DevOps, Jira, GitHub, and Confluence**: 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. | `query_api`, `read_confluence`, `create_ado_dashboard`, `write_ado_wiki_page`, `attach_to_work_item` | [docs](README.md#azure-devops-jira-and-other-systems) |
-| Setup | **Setup, skills, and documentation**: Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list. | `forgeqe_setup`, `capabilities` | [docs](#2-scaffold-config) |
+| Setup | **Setup, skills, and documentation**: Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list. | `forgeqe_setup`, `capabilities`, `playbook` | [docs](#2-scaffold-config) |
 
 Not supported: Native mobile apps (iOS, Android) and desktop applications (instead: web applications in local Chrome or Chromium, or configured remote web grids such as BrowserStack and TestMu AI/LambdaTest); Load, stress, or soak testing with many simultaneous users (instead: per-page Core Web Vitals with budgets); Penetration testing or dynamic security scanning (instead: security findings in pull request reviews).
 <!-- capabilities:end -->

package/docs/user-guide.html

@@ -2124,7 +2124,7 @@ mcp:
 <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></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>

package/evals/prompts/brain/route-api-scenarios.yaml

@@ -0,0 +1,9 @@
+id: route-api-scenarios
+title: End-to-end API scenarios come from api_scenarios, without a browser
+input: Make end-to-end API scenarios for the pet store API described at https://petstore3.swagger.io/api/v3/openapi.json.
+needs: []
+checks:
+  - id: uses-api-scenarios
+    tools_any: ["forgeqe_api_scenarios"]
+  - id: no-browser-or-scripts
+    tools_none: ["forgeqe_browser_run", "bash"]

package/evals/prompts/brain/route-e2e.yaml

@@ -0,0 +1,10 @@
+id: route-e2e
+title: An end-to-end case is built from the story's existing cases, not written again
+input: Build an end-to-end test case from the existing cases of Azure DevOps story 2211. Show it to me; don't save or run it.
+needs: [azure_devops]
+allow: [capabilities, find_test_cases, story_test_cases, e2e_journey, query_api, tool_help]
+checks:
+  - id: uses-journey
+    tools_any: ["forgeqe_e2e_journey"]
+  - id: saves-nothing
+    tools_none: ["forgeqe_save_test_cases", "forgeqe_run_test_cases", "forgeqe_browser_run"]

package/evals/prompts/brain/route-flaky.yaml

@@ -0,0 +1,9 @@
+id: route-flaky
+title: Flaky tests come from the test history
+input: Which of our tests are flaky, and why?
+needs: []
+checks:
+  - id: reads-history
+    tools_any: ["forgeqe_flaky_tests"]
+  - id: no-browser
+    tools_none: ["forgeqe_browser_run"]

package/evals/prompts/brain/route-heal.yaml

@@ -0,0 +1,9 @@
+id: route-heal
+title: Tests that broke after a release go to heal_tests
+input: Our automated UI tests in this repository started failing after yesterday's release. Repair them.
+needs: []
+checks:
+  - id: heals
+    tools_any: ["forgeqe_heal_tests"]
+  - id: no-hand-edits-first
+    tools_before: [["forgeqe_heal_tests"], ["edit", "write"]]

package/evals/prompts/brain/route-regression-pack.yaml

@@ -0,0 +1,9 @@
+id: route-regression-pack
+title: Which tests to run for a sprint's release is a regression pack
+input: Which automated tests should we run before releasing the current sprint?
+needs: [azure_devops]
+checks:
+  - id: builds-pack
+    tools_any: ["forgeqe_build_regression_pack"]
+  - id: no-browser
+    tools_none: ["forgeqe_browser_run"]

package/evals/prompts/brain/route-review-update.yaml

@@ -0,0 +1,10 @@
+id: route-review-update
+title: A change after review updates the same case in place, never saves a new one
+input: I reviewed test case 2279 of story 2271. Step 2 must also check that the password field shows dots, not the typed characters. Update the case.
+needs: [azure_devops]
+allow: [capabilities, find_test_cases, story_test_cases, query_api, tool_help]
+checks:
+  - id: updates-in-place
+    tools_any: ["forgeqe_update_test_case"]
+  - id: no-new-case
+    tools_none: ["forgeqe_save_test_cases", "forgeqe_browser_run"]

package/evals/prompts/brain/route-run-cases.yaml

@@ -0,0 +1,9 @@
+id: route-run-cases
+title: Running test cases goes through run_test_cases, not one browser run per case
+input: Run Azure DevOps test cases 2272 and 2273.
+needs: [azure_devops]
+checks:
+  - id: runs-cases
+    tools_any: ["forgeqe_run_test_cases"]
+  - id: not-browser-per-case
+    tools_none: ["forgeqe_browser_run"]

package/evals/prompts/brain/route-story-cases.yaml

@@ -0,0 +1,12 @@
+id: route-story-cases
+title: Asking for a story's test cases reads the linked cases before writing or saving any
+input: Write test cases for Azure DevOps story 2211.
+needs: [azure_devops]
+allow: [capabilities, find_test_cases, story_test_cases, query_api, read_confluence, tool_help]
+checks:
+  - id: reads-linked-cases
+    tools_any: ["forgeqe_story_test_cases"]
+  - id: reads-before-saving
+    tools_before: [["forgeqe_story_test_cases"], ["forgeqe_save_test_cases"]]
+  - id: no-browser
+    tools_none: ["forgeqe_browser_run", "bash", "webfetch"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capagents/forgeqe",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "ForgeQE: a browser agent CLI that runs goals and test cases in local Chrome or Chromium, or BrowserStack and TestMu AI/LambdaTest when configured, and turns passing runs into tests in your repo",
   "license": "MIT",
   "type": "module",

package/prompts/README.md

@@ -60,3 +60,33 @@ How it works:
   replaces ForgeQE's). Cases can run for brain, refine, and explore-charters.
 - Changes to these prompts change how the agents behave: run `forgeqe prompts eval` before and after a change, and
   commit it only when the pass rates hold.
+
+## What each agent loads, and what it costs
+
+Every model call sends an agent's fixed context again: its system prompt and, for ForgeQE's agent, its tool list. A
+request takes several calls, so a line added here is paid for many times. ForgeQE keeps it small, and checks it.
+
+- **One list of agents**: `src/agents.ts` names every agent, the prompt files it loads, the skills it may use, and a
+  budget for its fixed context. `forgeqe context` shows each agent against its budget (exit 1 when one is over).
+- **ForgeQE's agent loads what the task needs** (`src/mcp/routing.ts`):
+  - A capability's `playbook` sections of brain.md (`src/capabilities/registry.ts`) leave the system prompt. The prompt
+    keeps an index of them; the first result of the capability's tools in a session carries the section, and the agent
+    can read one first with the `playbook` tool. A section no capability owns stays in the prompt, so a section you
+    rename in your copy of brain.md is never lost.
+  - Tools stay listed in full. Listing tools in one line was measured and cost more: the agent then needs an extra
+    model call to get a tool's arguments, and it plans worse without the full description.
+  - `FORGEQE_ROUTING=off` sends everything, as before: use it to compare, or to rule routing out when something fails.
+- **Skills and product knowledge** load on demand already: an agent sees each skill's name and description and reads
+  the skill when it needs it; knowledge sections are picked by relevance to the task.
+
+When you add or change something:
+
+| You add | Also do |
+|---------|---------|
+| a tool | put it in one capability's `tools`, with a description that says when to use it |
+| a section in brain.md | give it to a capability's `playbook` with a `when` line, unless every request needs it |
+| a prompt file | name it under its agent in `src/agents.ts` (or include it from a prompt that is) |
+| an agent | add it to `src/agents.ts` with a budget |
+
+Then run `forgeqe context` and `forgeqe prompts eval brain` before and after: `bun test` fails when something is not
+in the lists or an agent is over budget, and the evaluation cases show whether the agent still picks the right tools.

package/prompts/brain.md

@@ -24,58 +24,12 @@ A message can also be a task specification with the parts Role, Objective, Conte
 **Preconditions**: "This session" below gives the setup: the systems, the project, the logins, the domain, the capabilities, and the defaults. You MUST use it, and MUST NOT ask the user for what it gives.
 
 **Tools** (ForgeQE tools; the client adds the forgeqe_ prefix):
-- browser_run: does one goal in a real browser, and verifies it. Use it for all work on a website. Set purpose to test for a flow of the application under test. Set purpose to task for all other work, such as finding, linking, or checking work items, or reading data from a tool. A task never becomes an automated test.
-- find_test_cases: reads test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, GitHub issues, files, or text. It does not run them.
-- story_test_cases: gives the test cases already linked to an Azure DevOps or Jira story, with their steps. It changes nothing.
-- save_test_cases: saves test cases that you wrote from a story into Azure DevOps (Test Case work items) or Jira, linked to the story. It never duplicates a linked case: it gives each case a status (created, unchanged, differs, similar, failed) and a link.
-- check_test_cases: checks test cases before they run. It finds expected results that are missing or not clear, missing test data, placeholders, and duplicates. It runs nothing.
-- update_test_case: writes the steps of an Azure DevOps Test Case or a Jira test issue again, in place, after the user agrees. It asks the user.
-- e2e_journey: plans end-to-end journeys from test cases that exist (the cases of a story, or any sources). It keeps the steps they share once, and gives each case as a section. It changes nothing.
-- release_readiness: gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories. It uses test cases, their results, bugs, and flaky tests. It can publish to the wiki. Examples: "are we ready to release?", "coverage of sprint 12".
-- run_test_cases: runs test cases in real browsers, with a verdict for each step. It writes report.html (steps, screenshots, timings) and junit.xml. It sends results back to the source system. It files or updates bugs for failures when bugs are set up. When this session writes tests, it gives each passed case to the coding agent immediately after the browser run of that case, before the next case starts. It gives the test of each case.
-- read_confluence: reads Confluence pages (requirements, specifications) as text, by id, link, or CQL.
-- browser_devices: lists, saves, and removes named remote browsers (devices) on BrowserStack or TestMu AI, kept in the provider's YAML file. When the user describes devices or browsers to test on, save each one, then pass their names as devices to browser_run or run_test_cases: every device runs at the same time and is reported on its own.
-- attach_to_work_item: puts files from a run (the last or failure screenshot, report.html, junit.xml, trace.md) on an existing Azure DevOps work item or Jira issue, as attachments, in a comment (images shown inline), or both. The Azure DevOps MCP server cannot upload files, so use this tool for any file on a work item.
-- run_details: gives the full record of a browser run: steps, values, ranked locators, and the generated spec.
-- run_test: ForgeQE runs a test command. A test passes only when this tool, write_test, or heal_tests says so.
-- write_test: the coding agent of ForgeQE turns a passed run into a test in a repository. ForgeQE runs the test until it passes.
-- heal_tests: ForgeQE runs the tests of a repository and heals the tests that fail against the live application, or reports application bugs.
-- find_tests: Scribe, the coding agent, finds the automated tests in a repository that match a request. A request can be a feature, tags or ids, a folder, or tests added in a date range or sprint. ForgeQE confirms the selection with the list command of the framework. It runs nothing.
-- run_tests: runs a find_tests selection after the user confirms, with a pass or fail for each test. A test that fails runs one more time. A test that then passes is flaky, not failing. The results of each run go into the test history of the repository.
-- flaky_tests: gives the flaky tests from that history, with their probable cause.
-- defect_trends: gives how the defects of the saved suites went over time: still there, gone, or back after a fix, the time to fix, the most seen, and defects by area. It runs nothing.
-- predict_defects: gives the areas where a change in the product repository can cause defects, with the reasons and the cases to run first. It is a heuristic from the history. It runs nothing.
-- build_regression_pack: builds a regression pack for a release from an Azure DevOps sprint or work items, a commit range, pull requests, or changes you read from other connected tools: the tests the changes can break, each with why, and the changes no test covers. It runs nothing.
-- run_regression_pack: runs a saved pack after the user confirms, on this machine, on TestMu AI, or in a pipeline, and compares the run with the last one.
-- list_regression_packs: gives the saved packs and their last runs.
-- quarantine_tests: puts flaky tests in quarantine, or takes them out, after the user agrees. The failures of a test in quarantine do not fail runs or CI.
-- review_pull_request: Scribe reviews an Azure DevOps or GitHub pull request from the local clone (bugs, security, requirements, tests). The user sees the findings. It posts nothing.
-- post_pr_review: posts a review_pull_request review to the pull request after the user confirms.
-- select_pr_tests: selects the automated tests that a pull request, or the commits since a base branch, can break. It uses what the change does and the linked work items. Run the tests with run_tests.
-- post_pr_test_results: posts a run_tests result on the pull request after the user confirms.
-- analyze_pr_impact: finds the product areas, pages, requirements, and tests that a pull request touches. This works also when the code of the product is in a different repository than the tests.
-- comment_on_pr: posts a comment, such as an impact report, on a pull request after the user confirms.
-- api_contracts: makes API contracts (status, schema, and key fields for each operation). It uses the calls that a browser run saw the application make, or an API description. Descriptions are an OpenAPI or Swagger link or file, WSDL, a GraphQL endpoint or schema, .proto, or grpc:// with reflection. It supports REST, GraphQL, SOAP, and gRPC.
-- run_api_contracts: runs a contract set directly against the API, without a browser. This is fast. It runs calls that change data only after the user agrees.
-- write_api_tests: Scribe writes a contract set as API tests in the framework of the repository. ForgeQE runs them until they pass. With scenarios, it writes end-to-end scenario tests on the API helpers of the repository.
-- api_scenarios: makes end-to-end API scenarios. These are calls in sequence, where values go from an answer to a later request. It makes them from a browser run, from an API description (lifecycles, browsing, links, negative cases), or from test cases or plain English.
-- run_api_scenarios: runs the scenarios against the API, without a browser. It asks before it runs a scenario that changes data.
-- explore_story: does exploratory testing of a story in real browsers, past its scripted cases. It examines edge cases, input that is not valid, boundaries, roles, and state. It confirms each defect with two runs. It proposes test cases. It files bugs for confirmed defects after the user agrees.
-- quality_report: gives the WCAG rules that a browser run passed and failed (axe-core, with the standard in forgeqe.yaml). It also gives the Core Web Vitals of each page, against the budgets.
-- quality_trends: gives the accessibility and performance of each page over time, with what became worse or better.
-- list_sprints: gives recent sprints from Azure DevOps and Jira, with their dates.
-- monitor: runs checks on a schedule, with Teams and email alerts. It can run one round now, start or stop rounds in the background, give status, and send test alerts.
-- logins: manages saved logins. It lists them. It lets the user sign in by hand in a browser (sign_in). It removes a session.
-- page_memory: gives what ForgeQE knows about the pages, locators, and recorded flows of a site. Clear it only when the user asks.
-- notify: posts a message to the Teams or email channels of the team. Use it only when the user asks. Suites, release verdicts, and failed evaluations go to their channels automatically from runs outside the shell.
-- write_report: saves a report that the user asks for as a page (filters, charts, the sources of its data) and a Markdown file. ForgeQE builds its tables from evidence: the results of tool calls in this session, or a read-only query that it runs itself. You write only the summary.
-- capabilities: tells what ForgeQE can do, and whether each capability works in this setup. It gives what to set up, example requests, limits, and the documentation.
-- forgeqe_setup: gives model profiles, the MCP servers that ForgeQE sets up, and the documentation of ForgeQE (docs). It installs or repairs the browser engine. It creates a forgeqe.yaml (init).
-- push_branch: the only way to push. It refuses the default branch, and it never forces.
-- set_ci_secret: stores one environment variable of ForgeQE as a pipeline secret. You give the name, never the value.
-- query_api: reads data from Azure DevOps, Jira, Xray, or Confluence through their APIs, with the credentials of ForgeQE. It only reads.
-- create_ado_dashboard: creates an Azure DevOps dashboard with work item lists, count tiles, and text. A saved shared query supplies each list or count.
-- write_ado_wiki_page: creates or updates an Azure DevOps wiki page. It creates the project wiki first when the project has none.
+- Each ForgeQE tool comes with its own description. Read it to select the tool.
+- Some playbooks are not in this prompt. The index under "Playbooks" names them. The first result of their tools gives each one, and you MUST obey it.
+- browser_run: set purpose to test for a flow of the application under test. Set purpose to task for all other work, such as finding, linking, or checking work items, or reading data from a tool. A task never becomes an automated test.
+- attach_to_work_item: the only way to put a file from a run on a work item or an issue. The Azure DevOps MCP server cannot upload files.
+- A test passes only when run_test, write_test, or heal_tests says so.
+- query_api only reads. set_ci_secret takes the name of a variable, never its value.
 
 Each action of the forgeqe command line is one of these tools. You MUST do the action with the tool, not tell the user to run a command.
 You also have your own tools to read and edit files and to run shell commands in the working directory. You also have the tools of the MCP servers under "This session", for example azure_devops_* for Azure DevOps and atlassian_* for Jira and Confluence.

package/py/forgeqe_engine/cli.py

@@ -171,8 +171,18 @@ def _token(out: TextIO) -> int:
         return 1
 
 
+def _utf8_stdio() -> None:
+    """The CLI speaks UTF-8 on every pipe; on Windows a pipe defaults to the ANSI code page, which turns a curly quote into a lone surrogate."""
+    for stream in (sys.stdin, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8", errors="replace")
+        except (AttributeError, ValueError):
+            pass
+
+
 def main(argv: list[str] | None = None) -> int:
     args = list(sys.argv[1:] if argv is None else argv)
+    _utf8_stdio()
     out = _event_stream()
     _configure_env()
     cmd = args[0] if args else "run"

package/py/forgeqe_engine/summary.py

@@ -81,6 +81,12 @@ def _error_summary_from_history(history: Any) -> str:
         n = len(errs)
         if len(distinct) == 1:
             msg = distinct[0]
+            if n > 1 and "surrogates not allowed" in msg:
+                return (
+                    f"Run stopped after {n} identical errors: {msg}. "
+                    "The request to the model held text that was decoded in the wrong encoding, so it was never sent; "
+                    "the LLM provider is not at fault. Update ForgeQE; the engine now reads its input as UTF-8."
+                )
             if n > 1:
                 return (
                     f"Run stopped after {n} identical errors: {msg}. "

package/src/agents.ts

@@ -0,0 +1,52 @@
+import type { SkillAgent } from "./skills/registry.ts"
+
+/**
+ * Every agent ForgeQE runs, what it loads on every model call, and how much that may be.
+ *
+ * This is the one list to change when an agent, a prompt, or a skill audience is added: tests/agents.test.ts checks it
+ * against the code (every prompt file is loaded by an agent, every agent the code defines is here) and checks each
+ * agent's fixed context against its budget, so the cost of a change shows in the build and in `forgeqe context`.
+ */
+export type AgentEntry = {
+  /** The agent runtime's name for it (AgentSpec name), or "engine" for the browser agent. */
+  name: string
+  title: string
+  /** agent-runtime: a session with tools; engine: the Python browser agent. */
+  kind: "agent-runtime" | "engine"
+  /** The prompt files it loads (prompts/<name>.md); the fragments they include count too. */
+  prompts: string[]
+  /** Skills it may load (by their `agents` audience); loaded on demand, so they are not in the fixed context. */
+  skills?: SkillAgent
+  /** Where the code defines it. */
+  defined: string
+  /** Most tokens its fixed context (system prompt, and for ForgeQE's agent its tool list) may take. */
+  budget: number
+}
+
+export const AGENTS: AgentEntry[] = [
+  { name: "forgeqe", title: "ForgeQE's agent (shell, forgeqe run, forgeqe mcp)", kind: "agent-runtime", prompts: ["brain"], skills: "forgeqe", defined: "src/brain/index.ts", budget: 26000 },
+  { name: "forgeqe-test", title: "Scribe: writes a test from a verified run", kind: "agent-runtime", prompts: ["test-agent"], skills: "scribe", defined: "src/code/runtime.ts", budget: 4900 },
+  { name: "forgeqe-read", title: "Scribe, reading the repository before the run arrives", kind: "agent-runtime", prompts: ["test-agent"], skills: "scribe", defined: "src/code/runtime.ts", budget: 4900 },
+  { name: "forgeqe-review", title: "Reviewer of Scribe's tests", kind: "agent-runtime", prompts: ["test-reviewer"], skills: "scribe", defined: "src/code/review.ts", budget: 4900 },
+  { name: "forgeqe-heal", title: "Scribe healing tests the application outgrew", kind: "agent-runtime", prompts: ["heal"], skills: "scribe", defined: "src/heal/loop.ts", budget: 4200 },
+  { name: "forgeqe-find", title: "Finds the repository tests a request means", kind: "agent-runtime", prompts: ["find-tests"], skills: "scribe", defined: "src/code/find.ts", budget: 1700 },
+  { name: "forgeqe-pr-review", title: "Reviews pull requests", kind: "agent-runtime", prompts: ["pr-review"], skills: "scribe", defined: "src/code/prreview.ts", budget: 1700 },
+  { name: "forgeqe-api", title: "Writes API and contract tests", kind: "agent-runtime", prompts: ["api-tests"], skills: "scribe", defined: "src/api/write.ts", budget: 2450 },
+  { name: "forgeqe-api-plan", title: "Plans end-to-end API scenarios", kind: "agent-runtime", prompts: ["api-scenarios"], defined: "src/api/plan.ts", budget: 1600 },
+  { name: "forgeqe-explore-plan", title: "Plans exploratory charters", kind: "agent-runtime", prompts: ["explore-charters"], defined: "src/explore/charters.ts", budget: 1650 },
+  { name: "forgeqe-defect-rca", title: "Finds the root cause of a defect", kind: "agent-runtime", prompts: ["defect-rca"], defined: "src/cases/rca.ts", budget: 950 },
+  { name: "forgeqe-refine", title: "Refine: turns a request into a task specification", kind: "agent-runtime", prompts: ["refine"], defined: "src/refine.ts", budget: 1450 },
+  { name: "forgeqe-judge", title: "Judges domain evaluations", kind: "agent-runtime", prompts: ["eval-judge"], defined: "src/evals/domain.ts", budget: 750 },
+  {
+    name: "engine",
+    title: "The browser agent (every browser run and test case)",
+    kind: "engine",
+    prompts: ["browser-api", "browser-capture", "browser-case-report", "browser-checks", "browser-efficiency", "browser-error-recovery", "browser-extra", "browser-goal-verification", "browser-skill-select", "conventions"],
+    skills: "browser",
+    defined: "py/forgeqe_engine/service.py",
+    budget: 2700,
+  },
+]
+
+/** Prompt files that are documentation, not loaded by any agent. */
+export const NOT_LOADED = ["README"]

package/src/brain/index.ts

@@ -8,6 +8,7 @@ import type { AppConfig } from "../config.ts"
 import { externalMcp, externalNotes, type ExternalPlan } from "../mcp/external.ts"
 import { MCP_NAME, TOOL_TIMEOUT_MS, localToolServer } from "../mcp/server.ts"
 import { TOOLS, environmentNotes, type ToolContext } from "../mcp/tools.ts"
+import { createRouter } from "../mcp/routing.ts"
 import { brainPrompt, BRAIN_SCHEMA, cleanFollowUps, type BrainReport, type FollowUp } from "./prompt.ts"
 import { redactSecrets } from "../sessionLogins.ts"
 import { logEvent } from "../sessionLog.ts"
@@ -115,11 +116,16 @@ export function carryOver(turns: { user: string; reply: string }[], text: string
   ].join("\n")
 }
 
+/** Routing (src/mcp/routing.ts) is on unless FORGEQE_ROUTING=off, kept for comparing and for finding a routing fault. */
+export const routingOn = (env: Record<string, string | undefined> = process.env) => !/^(off|0|false|no)$/i.test(env.FORGEQE_ROUTING || "")
+
 export async function openBrain(opts: BrainOptions): Promise<Brain> {
   const { config } = opts
   const cwd = realpathOr(opts.cwd)
   const context = (): ToolContext => ({ ...opts.context(), config, cwd })
-  const tools = localToolServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
+  // Tools listed in one line and playbooks on demand keep every model call small; FORGEQE_ROUTING=off sends it all.
+  const router = routingOn() ? createRouter(TOOLS) : undefined
+  const tools = localToolServer({ tools: TOOLS, context, router, instructions: () => environmentNotes(context()), timeoutMs: TOOL_TIMEOUT_MS })
   const external = opts.external || externalMcp(config, Bun.which, process.env, { cwd })
   const notes = [environmentNotes(context()), ...externalNotes(external), ...(opts.notes || [])].filter(Boolean).join("\n")
   const readDirs = [...new Set([config.export.outDir, config.memory.dir, cwd].flatMap((d) => [path.resolve(d), realpathOr(d)]))]
@@ -147,7 +153,7 @@ export async function openBrain(opts: BrainOptions): Promise<Brain> {
       agent: {
         name: BRAIN_AGENT,
         description: "ForgeQE: browser runs, test cases, tests, and CI pipelines",
-        prompt: `${brainPrompt()}\n\nThis session:\n${notes}`,
+        prompt: `${router ? router.parts.core : brainPrompt()}\n\nThis session:\n${notes}`,
         skills: "forgeqe",
         // Systems are read through MCP or query_api, never by scripts in the shell that handle tokens themselves.
         permission: { bash: agentBashPermission(privateEnvNames(config)) },

package/src/capabilities/registry.ts

@@ -53,6 +53,13 @@ export type Capability = {
   /** What it does not do, so the agent never promises it. */
   limits?: string[]
   docs: DocRef[]
+  /**
+   * The sections of brain.md (### headings) this capability owns: they leave the system prompt and come on demand, with
+   * `when` in the index of playbooks that stays in it. A section no capability owns stays in the system prompt.
+   */
+  playbook?: { heading: string; when: string }[]
+  /** Tools of other capabilities whose first result also carries this capability's playbook. */
+  alsoAfter?: string[]
 }
 
 export const CAPABILITIES: Capability[] = [
@@ -127,6 +134,10 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Write test cases for story 1234 and save them", "Build an end-to-end journey from story 1234's cases"],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira"] }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Where cases come from" }],
+    playbook: [
+      { heading: "Testing from requirements", when: "write test cases from a story, a Confluence page, or a specification" },
+      { heading: "End-to-end journeys from test cases", when: "an end-to-end case or flow from test cases that exist" },
+    ],
   },
   {
     id: "domain-compliance",
@@ -150,6 +161,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Explore story 1234 and find bugs", "Test this feature beyond the test cases"],
     requires: [{ kind: "live_model" }, { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to read the story and file bugs" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Exploratory testing from a story" }],
+    playbook: [{ heading: "Exploratory testing", when: "explore a story or feature past its scripted cases, or find bugs in it" }],
   },
   {
     id: "write-tests",
@@ -161,6 +173,8 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Write a Playwright test for that run in ../app"],
     requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository to write the test in (default: the working directory)" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "6. Tests" }],
+    playbook: [{ heading: "Writing tests", when: "write an automated test from a run, or a session where passed runs become tests" }],
+    alsoAfter: ["browser_run", "run_test_cases"],
   },
   {
     id: "heal-tests",
@@ -171,6 +185,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Heal the failing tests in ../app"],
     requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository with tests" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Fixing broken tests" }],
+    playbook: [{ heading: "Repairing broken tests", when: "automated tests that fail, broke after a release, or need healing" }],
   },
   {
     id: "find-run-tests",
@@ -185,6 +200,7 @@ export const CAPABILITIES: Capability[] = [
       { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to pick tests by sprint" },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Finding and running existing tests" }],
+    playbook: [{ heading: "Repository tests", when: "find, list, or run the automated tests of the repository" }],
   },
   {
     id: "regression-packs",
@@ -198,6 +214,7 @@ export const CAPABILITIES: Capability[] = [
       { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to read a sprint's or release's work items" },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Regression packs for a release" }],
+    playbook: [{ heading: "Regression packs", when: "a regression pack, or which tests to run for a release, sprint, or pull requests" }],
   },
   {
     id: "flaky-tests",
@@ -222,6 +239,8 @@ export const CAPABILITIES: Capability[] = [
       { kind: "either", of: [{ kind: "system", anyOf: ["azure_devops"], why: "for Azure DevOps pull requests" }, { kind: "command", command: "gh", why: "for GitHub pull requests" }] },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Reviewing pull requests" }],
+    playbook: [{ heading: "Pull requests", when: "review a pull request, its impact, or the tests it can break" }],
+    alsoAfter: ["analyze_pr_impact", "select_pr_tests", "post_pr_test_results", "comment_on_pr"],
   },
   {
     id: "pr-impact",
@@ -254,6 +273,7 @@ export const CAPABILITIES: Capability[] = [
       { doc: "HOW_TO_USE.md", heading: "API and contract tests" },
       { doc: "HOW_TO_USE.md", heading: "End-to-end API scenarios" },
     ],
+    playbook: [{ heading: "API testing", when: "API contracts, API tests, or end-to-end API scenarios (REST, GraphQL, SOAP, gRPC)" }],
   },
   {
     id: "accessibility-performance",
@@ -265,6 +285,8 @@ export const CAPABILITIES: Capability[] = [
     requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
     limits: ["Per-page Core Web Vitals, not load testing under many users."],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Accessibility and performance budgets" }],
+    playbook: [{ heading: "Accessibility, performance, and visual changes", when: "accessibility, Core Web Vitals, performance budgets, or visual changes of pages" }],
+    alsoAfter: ["visual_compare", "visual_approve"],
   },
   {
     id: "visual-comparison",
@@ -313,6 +335,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Check the login flow every 15 minutes and alert Teams"],
     requires: [{ kind: "live_model" }, { kind: "monitor_alerts", optional: true }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "9. Monitoring" }],
+    playbook: [{ heading: "Monitoring", when: "checks on a schedule, with alerts" }],
   },
   {
     id: "notifications",
@@ -354,6 +377,7 @@ export const CAPABILITIES: Capability[] = [
       { kind: "either", of: [{ kind: "command", command: "gh", why: "for GitHub Actions" }, { kind: "command", command: "az", why: "for Azure Pipelines" }] },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "8. Pipelines" }],
+    playbook: [{ heading: "CI pipelines", when: "a GitHub Actions or Azure DevOps pipeline that runs ForgeQE or the tests" }],
   },
   {
     id: "systems",
@@ -370,13 +394,17 @@ export const CAPABILITIES: Capability[] = [
     ],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira", "xray", "confluence"] }],
     docs: [{ doc: "README.md", heading: "Azure DevOps, Jira, and other systems" }],
+    playbook: [
+      { heading: "Releases and pipelines in Azure DevOps", when: "releases, deployments, environments, or pipeline runs in Azure DevOps" },
+      { heading: "Dashboards and wiki pages in Azure DevOps", when: "an Azure DevOps dashboard or wiki page" },
+    ],
   },
   {
     id: "setup-help",
     area: "Setup",
     title: "Setup, skills, and documentation",
     summary: "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.",
-    tools: ["forgeqe_setup", "capabilities"],
+    tools: ["forgeqe_setup", "capabilities", "playbook"],
     examples: ["What can you do?", "Which model am I using?", "How do I set up email alerts?"],
     requires: [],
     docs: [

package/src/cases/defects.ts

@@ -196,7 +196,8 @@ export class DefectBook {
       .filter(({ p }) => !this.noise.has(problemKey(p)))
       // The strongest kind; of those, the one nearest the failure (the latest step).
       .sort((a, b) => rank(a.p) - rank(b.p) || b.step - a.step)[0]?.p
-    const page = r.finalUrl ? pageKey(r.finalUrl) : undefined
+    // about:blank and other non-web pages are no page: their key would read "nullblank".
+    const page = r.finalUrl && /^https?:/i.test(r.finalUrl) ? pageKey(r.finalUrl) : undefined
     if (evidence) {
       const key = problemKey(evidence)
       const term = problemTerm(evidence)

package/src/cli/help.ts

@@ -12,6 +12,7 @@ Usage:
   forgeqe setup [--force]
   forgeqe models [--config forgeqe.yaml]
   forgeqe features [--config forgeqe.yaml]   what ForgeQE can do, and what each capability still needs here
+  forgeqe context                             what each agent loads on every model call, against its budget (exits 1 over budget)
   forgeqe docs [--guide|--open] [--copy DIR]  the guides and the architecture page (--guide: the user guide in the browser; --open: the architecture page)
   forgeqe start [--profile name] [--url URL] [--goal TEXT] [--headed] [--replay MODE] [--no-memory]
                  [--repo DIR] [--no-code] [--browser-provider local|browserstack|testmu] [--devices a,b]

package/src/cli/index.ts

@@ -171,6 +171,13 @@ export async function main(argv: string[]): Promise<number> {
         return cmdModels(flags)
       case "docs":
         return cmdDocs(flags)
+      case "context": {
+        // What each agent carries on every model call, against its budget in src/agents.ts.
+        const { agentContexts, contextReport } = await import("../context.ts")
+        const rows = agentContexts()
+        console.log(contextReport(rows).join("\n"))
+        return rows.some((r) => r.over) ? 1 : 0
+      }
       case "features":
         // What ForgeQE can do, and whether each capability works with this config and machine.
         console.log(featuresText(loadConfig(configOpts(flags))))

package/src/context.ts

@@ -0,0 +1,75 @@
+import { AGENTS, type AgentEntry } from "./agents.ts"
+import { createRouter, tokens } from "./mcp/routing.ts"
+import { TOOLS } from "./mcp/tools.ts"
+import { prompt } from "./prompts.ts"
+
+/** One agent's fixed context: what it carries on every model call. */
+export type AgentContext = {
+  agent: AgentEntry
+  /** The system prompt as sent (ForgeQE's agent: the core, without its on-demand playbooks). */
+  prompt: number
+  /** ForgeQE's agent only: its tool list as sent. */
+  tools?: number
+  total: number
+  over: boolean
+  /** ForgeQE's agent only: what it gets on demand, and what the fixed context would be with everything always on. */
+  onDemand?: { playbooks: number; playbookTokens: number; everything: number }
+}
+
+const expanded = (name: string) => {
+  try {
+    return prompt(name)
+  } catch {
+    return ""
+  }
+}
+
+/** The fixed context of each agent, from the prompts and tools as they are now (a team's own prompt copies included). */
+export function agentContexts(): AgentContext[] {
+  return AGENTS.map((agent) => {
+    if (agent.name !== "forgeqe") {
+      const p = agent.prompts.reduce((sum, n) => sum + tokens(expanded(n)), 0)
+      return { agent, prompt: p, total: p, over: p > agent.budget }
+    }
+    const router = createRouter(TOOLS)
+    const p = tokens(router.parts.core)
+    const t = tokens(JSON.stringify(TOOLS.map((x) => ({ name: x.name, description: x.description, inputSchema: x.inputSchema }))))
+    const full = tokens(expanded("brain")) + t
+    return {
+      agent,
+      prompt: p,
+      tools: t,
+      total: p + t,
+      over: p + t > agent.budget,
+      onDemand: {
+        playbooks: router.parts.playbooks.length,
+        playbookTokens: router.parts.playbooks.reduce((s, b) => s + tokens(b.text), 0),
+        everything: full,
+      },
+    }
+  })
+}
+
+const k = (n: number) => (n >= 1000 ? `${(n / 1000).toFixed(1)}K` : String(n))
+
+/** `forgeqe context`: each agent's fixed context against its budget, and what ForgeQE's agent loads on demand. */
+export function contextReport(rows = agentContexts()): string[] {
+  const out = ["Fixed context of each agent: sent again on every model call (~tokens).", ""]
+  const w = Math.max(...rows.map((r) => r.agent.name.length))
+  for (const r of rows) {
+    const parts = r.tools !== undefined ? `prompt ${k(r.prompt)} + tools ${k(r.tools)}` : `prompt ${k(r.prompt)}`
+    out.push(`${r.over ? "✗" : "✓"} ${r.agent.name.padEnd(w)}  ${k(r.total).padStart(6)} of ${k(r.agent.budget).padStart(6)}  ${parts}`)
+  }
+  const f = rows.find((r) => r.onDemand)
+  if (f?.onDemand) {
+    const d = f.onDemand
+    out.push(
+      "",
+      `ForgeQE's agent loads on demand: ${d.playbooks} playbooks (${k(d.playbookTokens)}), each with the first result of its tools or through the playbook tool.`,
+      `With everything always loaded it would carry ${k(d.everything)} on every call; it carries ${k(f.total)}.`,
+    )
+  }
+  const over = rows.filter((r) => r.over)
+  if (over.length) out.push("", `Over budget: ${over.map((r) => r.agent.name).join(", ")}. Shorten what they load, or raise the budget in src/agents.ts with the reason.`)
+  return out
+}

package/src/engine/setup.ts

@@ -68,6 +68,9 @@ export function engineEnv(extra?: Record<string, string>, allow: string[] = []):
   const env = allowListEnv(process.env, allow)
   env.PYTHONPATH = [ENGINE_SOURCE, env.PYTHONPATH].filter(Boolean).join(path.delimiter)
   env.PYTHONUNBUFFERED = "1"
+  // Requests, prompts and logs are UTF-8; Windows would otherwise read pipes and files in its ANSI code page.
+  env.PYTHONUTF8 = "1"
+  env.PYTHONIOENCODING = "utf-8"
   return { ...env, ...extra }
 }
 

package/src/mcp/captools.ts

@@ -22,4 +22,23 @@ export const CAPABILITY_TOOLS: McpTool[] = [
       return { capabilities: ids.map((id) => capabilityDetail(capability(id)!, ctx.config)) }
     },
   },
+  {
+    name: "playbook",
+    description:
+      "Read a playbook that is not in your prompt (the index under Playbooks names them), by its name, its capability id, or one of its tools. The first result of a playbook's tools carries it anyway: read it first only when you need its rules before that call. Nothing runs.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        names: { type: "array", items: { type: "string" }, description: "Playbook names (e.g. Testing from requirements), capability ids, or tool names" },
+      },
+      required: ["names"],
+    },
+    async run(args, ctx) {
+      const names = Array.isArray(args.names) ? args.names.map(String).filter(Boolean) : []
+      if (!names.length) throw new Error("names is empty.")
+      if (ctx.router) return ctx.router.help(names)
+      const [{ TOOLS }, { createRouter }] = await Promise.all([import("./tools.ts"), import("./routing.ts")])
+      return createRouter(TOOLS).help(names)
+    },
+  },
 ]

package/src/mcp/routing.ts

@@ -0,0 +1,145 @@
+import { CAPABILITIES, type Capability } from "../capabilities/registry.ts"
+import { prompt } from "../prompts.ts"
+import type { McpTool } from "./tools.ts"
+
+/**
+ * What ForgeQE's agent carries on every model call, and what it gets only when a task needs it.
+ *
+ * Every model call sends the system prompt and the tool definitions again. Tools stay listed in full: their
+ * descriptions are how the agent chooses a tool and plans the task, and their arguments are needed for any call, so a
+ * tool listed in one line cost an extra model call each time (measured: more tokens, not fewer). The playbook is
+ * what moves: the sections of brain.md that a capability owns (`playbook`) leave the system prompt, an index of them
+ * stays, and the first result of one of the capability's tools in a session (or of a tool in `alsoAfter`) carries the
+ * section. The `playbook` tool reads one before that. A section no capability owns stays in the system prompt, so a
+ * section renamed in a team's own copy of brain.md is never lost.
+ */
+
+/** Rough tokens of a text: the budgets and `forgeqe context` use it, not billing. */
+export const tokens = (text: string) => Math.ceil(text.length / 4)
+
+const norm = (s: string) => s.trim().toLowerCase()
+
+/** The capability each tool belongs to. */
+export function capabilityOfTool(name: string, caps: Capability[] = CAPABILITIES): Capability | undefined {
+  return caps.find((c) => c.tools.includes(name))
+}
+
+// ---------------------------------------------------------------------------------------------
+// The playbook
+// ---------------------------------------------------------------------------------------------
+
+export type Playbook = { heading: string; when: string; capability: string; tools: string[]; text: string }
+
+/** brain.md split: the system prompt without the owned sections (with an index of them), and those sections. */
+export type BrainParts = { core: string; playbooks: Playbook[] }
+
+const SECTION = /^###\s+(.+?)\s*$/
+
+/** Split the agent's prompt by the capabilities' playbook sections. Unowned sections stay in `core`. */
+export function splitBrain(text: string, caps: Capability[] = CAPABILITIES): BrainParts {
+  const owned = new Map(caps.flatMap((c) => (c.playbook || []).map((p) => [norm(p.heading), { ...p, capability: c.id, tools: c.tools }] as const)))
+  const lines = text.split("\n")
+  const keep: string[] = []
+  const playbooks: Playbook[] = []
+  let current: { entry: Omit<Playbook, "text">; lines: string[] } | null = null
+  const close = () => {
+    if (current) playbooks.push({ ...current.entry, text: current.lines.join("\n").trim() })
+    current = null
+  }
+  for (const line of lines) {
+    const h = SECTION.exec(line)
+    if (h || /^##\s/.test(line)) {
+      close()
+      const entry = h ? owned.get(norm(h[1])) : undefined
+      if (entry) {
+        current = { entry: { heading: h![1].trim(), when: entry.when, capability: entry.capability, tools: entry.tools }, lines: [line] }
+        continue
+      }
+    }
+    if (current) current.lines.push(line)
+    else keep.push(line)
+  }
+  close()
+  let core = keep.join("\n").replace(/\n{3,}/g, "\n\n")
+  if (playbooks.length) {
+    const index = [
+      "",
+      "These playbooks are not in this prompt. The first result of their tools carries each one: obey it. To read one before you start, call playbook with its name.",
+      ...playbooks.map((p) => `- "${p.heading}": ${p.when}. Tools: ${p.tools.join(", ")}.`),
+      "",
+    ].join("\n")
+    core = /^## Playbooks\s*$/m.test(core) ? core.replace(/^## Playbooks\s*$/m, (m) => `${m}\n${index}`) : `${core.trimEnd()}\n\n## Playbooks\n${index}`
+  }
+  return { core: core.trim(), playbooks }
+}
+
+/** ForgeQE's agent's prompt as it is sent: the core, with the index of the playbooks it gets on demand. */
+export const brainParts = (): BrainParts => splitBrain(prompt("brain"))
+
+// ---------------------------------------------------------------------------------------------
+// One session of ForgeQE's agent
+// ---------------------------------------------------------------------------------------------
+
+/**
+ * Routing for one agent session: which playbooks it was given, and what goes with a result. The playbook text is read
+ * once, when the session starts, like the system prompt.
+ */
+export function createRouter(tools: McpTool[], opts: { caps?: Capability[]; brain?: string } = {}) {
+  const caps = opts.caps || CAPABILITIES
+  const parts = splitBrain(opts.brain ?? prompt("brain"), caps)
+  const given = new Set<string>()
+  const names = new Set(tools.map((t) => t.name))
+
+  const playbooksFor = (tool: string) => parts.playbooks.filter((p) => p.tools.includes(tool) || caps.find((c) => c.id === p.capability)?.alsoAfter?.includes(tool))
+  const give = (books: Playbook[]) => {
+    const fresh = books.filter((b) => !given.has(b.heading))
+    for (const b of fresh) given.add(b.heading)
+    return fresh
+  }
+  const block = (books: Playbook[]) => (books.length ? `\n\nPlaybook (obey it for this task):\n\n${books.map((b) => b.text).join("\n\n")}` : "")
+
+  return {
+    parts,
+    /** What goes after an error of a tool: the playbooks of its capability this session has not had yet. */
+    after(name: string): string {
+      return block(give(playbooksFor(name)))
+    },
+    /**
+     * A result with the playbooks it should carry: in a `playbook` field of a JSON object, so the result stays JSON for
+     * whatever reads it; appended to any other text.
+     */
+    attach(name: string, text: string): string {
+      const books = give(playbooksFor(name))
+      if (!books.length) return text
+      const playbook = `Obey it for this task:\n\n${books.map((b) => b.text).join("\n\n")}`
+      try {
+        const parsed = JSON.parse(text)
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return JSON.stringify({ ...parsed, playbook }, null, 2)
+      } catch {}
+      return text + block(books)
+    },
+    /** The playbook tool: playbooks by name, by capability id, or of a tool's capability. */
+    help(asked: string[]): string {
+      const books: Playbook[] = []
+      const unknown: string[] = []
+      for (const raw of asked) {
+        const exact = norm(raw)
+        // The client shows ForgeQE's tools with a forgeqe_ prefix; forgeqe_setup is that tool's own name.
+        const tool = names.has(exact) ? exact : names.has(exact.replace(/^forgeqe_/, "")) ? exact.replace(/^forgeqe_/, "") : ""
+        const found = tool ? playbooksFor(tool) : parts.playbooks.filter((p) => norm(p.heading) === exact || p.capability === exact)
+        if (found.length) books.push(...found)
+        else unknown.push(raw)
+      }
+      const unique = [...new Map(books.map((b) => [b.heading, b])).values()]
+      for (const b of unique) given.add(b.heading)
+      return [
+        ...(unique.length ? ["Playbook (obey it for this task):", "", ...unique.map((b) => b.text)] : []),
+        ...(unknown.length ? ["", `No playbook for: ${unknown.join(", ")}. Playbooks: ${parts.playbooks.map((p) => `"${p.heading}"`).join(", ")}. A tool not under one of them has its rules in its own description and in the prompt.`] : []),
+      ]
+        .join("\n")
+        .trim()
+    },
+  }
+}
+
+export type Router = ReturnType<typeof createRouter>

package/src/mcp/server.ts

@@ -2,6 +2,7 @@ import { createHash, randomBytes, timingSafeEqual } from "node:crypto"
 
 import { EvidenceLog } from "../report/evidence.ts"
 import { logEvent } from "../sessionLog.ts"
+import type { Router } from "./routing.ts"
 import type { McpTool, ToolContext, ToolEvent } from "./tools.ts"
 
 type Json = Record<string, any>
@@ -21,6 +22,8 @@ export type McpServerOptions = {
   /** Read on every call, so the shell's current profile and headed setting apply. */
   context: () => ToolContext
   instructions?: () => string
+  /** ForgeQE's agent: playbooks given with the first result of their tools. Other clients get results as they are. */
+  router?: Router
   version?: string
   progressMs?: number
 }
@@ -41,7 +44,7 @@ export function createMcpServer(opts: McpServerOptions) {
   async function callTool(params: Json, id: string | number, send: Send, outer?: AbortSignal): Promise<Json> {
     const tool = opts.tools.find((t) => t.name === params.name)
     if (!tool) return { content: [{ type: "text", text: `Unknown tool ${params.name}` }], isError: true }
-    const base = { evidence, ...opts.context() }
+    const base = { evidence, ...opts.context(), ...(opts.router ? { router: opts.router } : {}) }
     const controller = new AbortController()
     const abort = () => controller.abort()
     base.signal?.addEventListener("abort", abort, { once: true })
@@ -91,9 +94,10 @@ export function createMcpServer(opts: McpServerOptions) {
       said(true)
       const text = typeof out === "string" ? out : JSON.stringify(out, null, 2)
       base.evidence.record(tool.name, args, text)
-      return finish({ content: [{ type: "text", text }] })
+      return finish({ content: [{ type: "text", text: opts.router ? opts.router.attach(tool.name, text) : text }] })
     } catch (err) {
-      return finish({ content: [{ type: "text", text: controller.signal.aborted ? "Stopped by the user." : (err as Error).message || String(err) }], isError: true })
+      const message = controller.signal.aborted ? "Stopped by the user." : (err as Error).message || String(err)
+      return finish({ content: [{ type: "text", text: message + (controller.signal.aborted ? "" : opts.router?.after(tool.name) || "") }], isError: true })
     } finally {
       if (timer) clearInterval(timer)
       running.delete(id)

package/src/mcp/tools.ts

@@ -36,6 +36,7 @@ import { API_TOOLS } from "./apitools.ts"
 import { EXPLORE_TOOLS } from "./exploretools.ts"
 import { QUALITY_TOOLS } from "./qualitytools.ts"
 import { CAPABILITY_TOOLS } from "./captools.ts"
+import type { Router } from "./routing.ts"
 import { NOTIFY_TOOLS } from "./notifytools.ts"
 import { REPORT_TOOLS } from "./reporttools.ts"
 import { DEVICE_TOOLS } from "./devicetools.ts"
@@ -140,6 +141,8 @@ export function queryLine(args: Record<string, any>): string {
 
 export type ToolContext = {
   config: AppConfig
+  /** ForgeQE's agent's session: which tools and playbooks it gets on demand (src/mcp/routing.ts). */
+  router?: Router
   /** The repository or folder the agent works in. */
   cwd: string
   headed?: boolean

package/src/update.ts

@@ -1,5 +1,6 @@
-import { spawnSync } from "node:child_process"
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs"
+import { spawn, spawnSync } from "node:child_process"
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
 import path from "node:path"
 import { packageVersion } from "./tui/theme.ts"
 
@@ -28,19 +29,50 @@ export interface UpdateDeps {
   platform: NodeJS.Platform
   sleep: (ms: number) => Promise<void>
   now: () => number
+  /**
+   * Windows: starts `script` (a .cmd) detached, to run once this process has exited, and returns its log file.
+   * A running ForgeQE keeps files of its own install open (its launcher, native libraries), and Windows does not
+   * let an installer replace a file that is in use, so the update cannot run from inside ForgeQE.
+   */
+  defer?: (script: string) => string
+}
+
+/**
+ * How to start `cmd` on `platform`. Windows runs .cmd and .bat files (npm, pyenv-win) only through a shell, which Node
+ * refuses to do on its own (EINVAL), so those go through cmd.exe with each argument quoted.
+ */
+export function spawnPlan(cmd: string, args: string[], platform: NodeJS.Platform): { cmd: string; args: string[]; shell: boolean } {
+  if (platform !== "win32" || /\.exe$/i.test(cmd)) return { cmd, args, shell: false }
+  return { cmd: winQuote(cmd), args: args.map(winQuote), shell: true }
+}
+
+/** One argument for cmd.exe: quoted when it has a space or a character cmd.exe would read. */
+export function winQuote(a: string): string {
+  return /[\s&|<>^()%!"]/.test(a) ? `"${a.replace(/"/g, '""')}"` : a
 }
 
 export function defaultDeps(): UpdateDeps {
   return {
     fetch,
     run: (cmd, args) => {
-      const r = spawnSync(cmd, args, { encoding: "utf8" })
+      const plan = spawnPlan(cmd, args, process.platform)
+      const r = spawnSync(plan.cmd, plan.args, { encoding: "utf8", shell: plan.shell, windowsHide: true })
       return { status: r.error ? null : r.status, stdout: r.stdout || "", stderr: r.stderr || (r.error ? String(r.error.message) : "") }
     },
     env: process.env,
     platform: process.platform,
     sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
     now: () => Date.now(),
+    defer: (script) => {
+      const dir = path.join(tmpdir(), "forgeqe-update")
+      mkdirSync(dir, { recursive: true })
+      const stamp = new Date().toISOString().replace(/[:.]/g, "-")
+      const file = path.join(dir, `update-${stamp}.cmd`)
+      const log = path.join(dir, `update-${stamp}.log`)
+      writeFileSync(file, script.replace(/\{LOG\}/g, log).replace(/\n/g, "\r\n"))
+      spawn("cmd.exe", ["/d", "/c", file], { detached: true, stdio: "ignore", windowsHide: true }).unref()
+      return log
+    },
   }
 }
 
@@ -142,12 +174,33 @@ function packageDirOf(file: string): string | undefined {
   return undefined
 }
 
+/**
+ * The package a `forgeqe` on PATH belongs to when it is a copy or a wrapper, not a link: npm on Windows writes
+ * forgeqe.cmd next to node_modules; bun on Windows writes forgeqe.exe in ~/.bun/bin for ~/.bun/install/global; an npm
+ * prefix elsewhere keeps packages in <prefix>/lib/node_modules.
+ */
+function packageOfShim(binDir: string): string | undefined {
+  const parts = NPM_PACKAGE.split("/")
+  for (const dir of [path.join(binDir, "node_modules", ...parts), path.join(binDir, "..", "install", "global", "node_modules", ...parts), path.join(binDir, "..", "lib", "node_modules", ...parts)]) {
+    const found = packageDirOf(path.join(dir, "package.json"))
+    if (found) return path.resolve(found)
+  }
+  return undefined
+}
+
 function pythonOfScript(script: string, platform: NodeJS.Platform): string | undefined {
   if (platform === "win32") {
     const dir = path.dirname(script)
-    if (path.basename(dir).toLowerCase() !== "scripts") return undefined
     const python = path.join(path.dirname(dir), "python.exe")
-    return existsSync(python) ? python : undefined
+    if (path.basename(dir).toLowerCase() === "scripts" && existsSync(python)) return python
+    // pip's forgeqe.exe carries the Python it was installed for (`#!C:\...\python.exe` near its end): the way to find
+    // it for `pip install --user`, whose Scripts folder is not next to python.exe.
+    try {
+      const text = readFileSync(script).toString("latin1")
+      const m = [...text.matchAll(/#!\s*"?([^"\r\n]*?pythonw?\.exe)"?/gi)].pop()
+      if (m && existsSync(m[1])) return m[1]
+    } catch {}
+    return undefined
   }
   let first = ""
   try {
@@ -182,7 +235,10 @@ export function findInstalls(deps: UpdateDeps): Install[] {
       }
       if (seen.has(target)) continue
       seen.add(target)
-      const pkgDir = packageDirOf(target)
+      const pkgDir = packageDirOf(target) || packageOfShim(dir)
+      // npm on Windows writes forgeqe, forgeqe.cmd and forgeqe.ps1 for one install.
+      if (pkgDir && seen.has(`pkg:${pkgDir}`)) continue
+      if (pkgDir) seen.add(`pkg:${pkgDir}`)
       if (pkgDir) {
         let version = ""
         try {
@@ -233,6 +289,47 @@ export function commandLine([cmd, args]: [string, string[]]): string {
   return [cmd, ...args].map((a) => (/\s/.test(a) ? JSON.stringify(a) : a)).join(" ")
 }
 
+/** What to do when an installer refuses for a reason the machine sets, not ForgeQE (Linux: root-owned npm, PEP 668). */
+export function failureHint(kind: InstallKind, output: string, platform: NodeJS.Platform): string {
+  if (/EACCES|permission denied/i.test(output) && kind === "npm") {
+    return platform === "win32"
+      ? "npm's global folder is not writable: run the terminal as administrator, or install with bun (bun add -g @capagents/forgeqe)."
+      : "npm's global folder belongs to root: run sudo npm install -g @capagents/forgeqe, or give npm a folder of your own (npm config set prefix ~/.npm-global)."
+  }
+  if (/externally-managed-environment/i.test(output)) {
+    return "This Python is managed by the system and pip will not change it: install with pipx install forgeqe-cli, or in a virtual environment."
+  }
+  if (/EBUSY|EPERM|being used by another process/i.test(output)) {
+    return "A file of the install is in use: close every ForgeQE window and run forgeqe update again."
+  }
+  return ""
+}
+
+/**
+ * The .cmd that updates Windows installs after the ForgeQE that started it has exited: it waits for these processes
+ * (ForgeQE and its launcher), runs each install's commands, and writes everything to {LOG}.
+ */
+export function windowsUpdateScript(steps: { kind: InstallKind; bin: string; commands: Array<[string, string[]]> }[], pids: number[], version: string): string {
+  const lines = ["@echo off", "setlocal", ":wait"]
+  for (const pid of pids.filter((p) => Number.isInteger(p) && p > 0)) {
+    // ping waits a second where timeout cannot (a detached script has no console); System32 paths, so Git's find
+    // or another tasklist on PATH is never the one that runs.
+    lines.push(`"%SystemRoot%\\System32\\tasklist.exe" /FI "PID eq ${pid}" 2>nul | "%SystemRoot%\\System32\\find.exe" " ${pid} " >nul && (ping -n 2 127.0.0.1 >nul & goto wait)`)
+  }
+  lines.push(`echo Updating ForgeQE to ${version} > "{LOG}"`)
+  for (const step of steps) {
+    lines.push(`echo. >> "{LOG}"`, `echo Updating the ${step.kind} install (${step.bin}) >> "{LOG}"`)
+    for (const [cmd, args] of step.commands) {
+      const line = [cmd, ...args].map(winQuote).join(" ")
+      const cacheStep = args[0] === "pm" && args[1] === "cache"
+      lines.push(`echo $ ${line.replace(/[&|<>^]/g, "^$&")} >> "{LOG}"`)
+      lines.push(`call ${line} >> "{LOG}" 2>&1${cacheStep ? "" : ` || echo FAILED: ${step.kind} install >> "{LOG}"`}`)
+    }
+  }
+  lines.push(`echo. >> "{LOG}"`, `echo Done. Open a new terminal and run: forgeqe --version >> "{LOG}"`)
+  return `${lines.join("\n")}\n`
+}
+
 export interface UpdateOptions {
   /** A version to install instead of the latest. */
   version?: string
@@ -283,6 +380,16 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     }
   }
 
+  if (deps.platform === "win32" && deps.defer) {
+    // Windows will not replace files the running ForgeQE holds open, so the installs update once it has exited.
+    const steps = stale.map((inst) => ({ kind: inst.kind, bin: inst.bin, commands: updateCommands(inst, target, deps.env) }))
+    for (const step of steps) for (const c of step.commands) log(`  $ ${commandLine(c)}`)
+    const logFile = deps.defer(windowsUpdateScript(steps, [process.pid, process.ppid], target))
+    log(`\nThe update to ${target} starts as soon as this command exits (Windows locks the files a running ForgeQE uses).`)
+    log(`It writes what it does to ${logFile}. Then open a new terminal and run forgeqe --version.`)
+    return 0
+  }
+
   let failed = 0
   for (const inst of stale) {
     log(`\nUpdating the ${inst.kind} install (${inst.bin})`)
@@ -293,7 +400,10 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
         const cacheStep = c[1][0] === "pm" && c[1][1] === "cache"
         if (cacheStep) continue
         failed++
-        log((r.stderr || r.stdout).trim().split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const output = (r.stderr || r.stdout).trim()
+        log(output.split("\n").slice(-5).map((l) => `  ${l}`).join("\n"))
+        const hint = failureHint(inst.kind, output, deps.platform)
+        if (hint) log(`  ${hint}`)
         break
       }
     }
@@ -306,6 +416,6 @@ export async function update(opts: UpdateOptions = {}, deps: UpdateDeps = defaul
     log(`\n${behind.length || failed} install(s) are still behind ${target}; the output above says why.`)
     return 1
   }
-  log(`\nforgeqe ${target} is installed. Open a new terminal (or run hash -r) if the shell still finds the old one.`)
+  log(`\nforgeqe ${target} is installed. Open a new terminal${deps.platform === "win32" ? "" : " (or run hash -r)"} if the shell still finds the old one.`)
   return 0
 }