@capagents/forgeqe 1.3.2 → 2.0.0

package/src/capabilities/registry.ts

@@ -30,13 +30,17 @@ export type Requirement =
   | { kind: "command"; command: "gh" | "az" | "git" | "npx"; optional?: boolean; why?: string }
   /** Something only the request can supply (a repository, a pull request); stated, never checked. */
   | { kind: "input"; what: string }
+  /** Apps of this kind in the active environment (env.yaml) or forgeqe.yaml (desktop: or mobile:). */
+  | { kind: "apps"; app: "desktop" | "mobile"; optional?: boolean }
+  /** Docker or Podman on PATH (containers.runtime picks one). */
+  | { kind: "containers"; optional?: boolean }
   /** Alternatives: met when any one of them is (GitHub through gh, or Azure DevOps). */
   | { kind: "either"; of: Requirement[]; optional?: boolean }
 
 /** A heading in README.md or HOW_TO_USE.md, by its exact text (### headings without their parent). */
 export type DocRef = { doc: "README.md" | "HOW_TO_USE.md"; heading: string }
 
-export type Area = "Browser" | "Test cases" | "Automated tests" | "Pull requests" | "API" | "Quality" | "Release" | "Operations" | "Systems" | "Setup"
+export type Area = "Browser" | "Desktop" | "Mobile" | "Test cases" | "Automated tests" | "Pull requests" | "API" | "Quality" | "Release" | "Operations" | "Systems" | "Setup"
 
 export type Capability = {
   /** Stable id the agent asks for details by. */
@@ -47,6 +51,11 @@ export type Capability = {
   summary: string
   /** The tools that carry it out (forgeqe_ prefix left off). */
   tools: string[]
+  /**
+   * Words and phrases in a request that mean this capability (lower case). ForgeQE's agent gets a capability's tools
+   * for a turn when the request matches them (src/mcp/scope.ts); its examples must match, a test checks it.
+   */
+  keywords: string[]
   /** How a user might ask for it, in their words. */
   examples: string[]
   requires: Requirement[]
@@ -70,6 +79,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Carries out a plain-language goal in a real browser one step at a time and verifies the outcome, with screenshots, a report, and the steps it took. The browser comes from forgeqe.yaml: local Chrome or Chromium by default, or BrowserStack or TestMu AI/LambdaTest when configured. Page memory replays steps that already worked on a site, so repeat runs are faster and cheaper.",
     tools: ["browser_run", "run_details", "page_memory", "browser_devices"],
+    keywords: ["browser", "website", "web site", "web app", "page", "url", "go to", "open the", "click", "search", "chrome", "edge", "firefox", "device", "testmu", "browserstack", "sign up", "checkout", "site", "form", "cart"],
     examples: [
       "Go to booking.com and search hotels in Mumbai for next weekend",
       "What does ForgeQE know about the checkout page?",
@@ -88,6 +98,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Saved logins for the application under test",
     summary: "Signs the browser agent in with saved credentials (including TOTP) and reuses the session; a user can also sign in by hand once in a browser.",
     tools: ["logins"],
+    keywords: ["login", "log in", "sign in", "signed in", "session", "credential", "password", "saved login", "forget the saved"],
     examples: ["Sign in to the admin site and keep the session", "Forget the saved session for shop.example.com"],
     requires: [],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Signing in" }],
@@ -99,6 +110,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Reads test cases from Azure DevOps, Jira, Xray, TestRail, Zephyr Scale, qTest, a file, or pasted text, runs each in a real browser with a verdict per step, writes report.html and junit.xml, posts results back, and files or updates bugs for failures.",
     tools: ["find_test_cases", "run_test_cases"],
+    keywords: ["test case", "cases", "test plan", "suite", "manual test", "run case", "execute case", "run the case"],
     examples: ["Run SHOP-12 and SHOP-14 from Jira, two browsers at once", "Run test plan 12 suite 34 from Azure DevOps and don't post results"],
     requires: [
       { kind: "live_model" },
@@ -120,6 +132,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps or Jira cases in place once the user agrees.",
     tools: ["check_test_cases", "update_test_case"],
+    keywords: ["good enough", "quality", "improve", "fix the expected", "expected result", "check the cases", "check cases", "review the cases", "rewrite"],
     examples: ["Are the cases in test plan 12 good enough to run?", "Fix the expected results of case 4512"],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to rewrite cases in place" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Checking test cases before they run" }],
@@ -131,6 +144,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story. Reads the cases already linked first, so asking again adds only what is missing and updates cases in place instead of duplicating them; plans end-to-end journeys from the existing cases.",
     tools: ["story_test_cases", "save_test_cases", "e2e_journey"],
+    keywords: ["write test cases", "test cases for", "story", "acceptance criteria", "journey", "end-to-end", "generate cases", "save them"],
     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" }],
@@ -146,6 +160,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Every agent works as an expert in the product's industry would, automatically: the risks the industry is known for and the obligations of its regulations and standards (for example DORA, PSD2, GDPR, ISO 27001), declared in forgeqe.yaml or worked out from the story and the application. It applies to analysing requirements, writing and checking test cases, exploration, writing, reviewing, and healing test code, API tests, finding tests, and pull request reviews, labelled so coverage can be traced and citing only the control ids in the team's compliance file. forgeqe eval domain measures how well the agent does it.",
     tools: [],
+    keywords: ["gdpr", "dora", "psd2", "hipaa", "pci", "sox", "iso 27001", "compliance", "regulation", "obligation"],
     examples: ["Write test cases for story 1234, covering our DORA and PSD2 obligations", "Which GDPR obligations do these cases miss?"],
     requires: [{ kind: "domain", optional: true }],
     limits: ["Designs and checks tests for regulatory obligations; it does not certify compliance or replace an audit.", "Cites control or article ids only from the team's compliance file, never from memory."],
@@ -158,11 +173,86 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Explores a story in real browsers beyond its scripted cases (edge cases, invalid input, boundaries, roles, state), confirms each defect by reproducing it, proposes test cases, and files bugs once the user agrees.",
     tools: ["explore_story"],
+    keywords: ["explore", "exploratory", "find bugs", "beyond the test cases", "charter"],
     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: "test-apps",
+    area: "Setup",
+    title: "Test environments and their apps",
+    summary:
+      "Knows the test environments in env.yaml (QA, UAT, …) and each one's apps: web apps and APIs by URL, Windows desktop apps, and mobile apps, with what each is for. Every agent works from the active one; switches environment on request, picks the apps a scenario needs, and carries values such as an order number from one app to the next.",
+    tools: ["test_apps", "use_environment"],
+    keywords: ["environment", "env", "qa", "uat", "staging", "apps", "which apps"],
+    examples: ["Place an order in the shop, then check its invoice in Billing, in UAT", "Which apps can you test in QA?", "From now on, use the UAT environment"],
+    requires: [{ kind: "input", what: "env.yaml with the environments and apps (forgeqe init writes one)" }],
+    limits: [],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Environments and apps" }],
+    playbook: [{ heading: "Apps and environments", when: "a request names an app or environment, or a scenario spans several apps" }],
+  },
+  {
+    id: "desktop-apps",
+    area: "Desktop",
+    title: "Automate Windows desktop apps",
+    summary:
+      "Carries out a plain-language goal in a Windows thick-client app with UFO² and saves it as a workflow with checks of the outcome, or records the steps a tester does by hand, with no model; replays saved workflows with no model, healing a step whose control moved, and fixes a workflow from chat (a timeout, a wait, a dialog to dismiss) after showing the change. Apps and the secrets they may type come from env.yaml or forgeqe.yaml desktop:.",
+    tools: ["desktop_explore", "desktop_record", "desktop_replay", "desktop_edit_workflow"],
+    keywords: ["desktop", "windows app", "thick client", "thick-client", ".exe", "record", "replay", "workflow", "ufo", "notepad", "win32", "wpf", "winforms"],
+    examples: [
+      "Create an invoice for Contoso in the Billing app and save it as a test",
+      "I'll show you the steps in Billing: record them",
+      "Replay the billing workflow with customer Fabrikam",
+      "Step 4 timed out while the list loaded: fix the workflow",
+    ],
+    requires: [
+      { kind: "live_model", optional: true },
+      { kind: "apps", app: "desktop" },
+      { kind: "input", what: "a Windows machine, and the app in forgeqe.yaml desktop.apps" },
+    ],
+    limits: ["Windows only, one run at a time per desktop", "Apps whose controls UI Automation cannot see (Citrix, some Java and custom-drawn apps) are not supported yet"],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Desktop apps (Windows)" }],
+    playbook: [{ heading: "Desktop apps", when: "automate or test a Windows desktop (thick-client) app" }],
+  },
+  {
+    id: "mobile-apps",
+    area: "Mobile",
+    title: "Automate Android and iOS apps",
+    summary:
+      "Carries out a plain-language goal in an Android or iOS app through Appium and saves it as a mobile workflow with checks of the outcome; replays workflows with no model on Appium (healing a moved control) or Maestro; runs the team's own Maestro flows after checking them against an allowlist. Apps come from env.yaml (kind: mobile) or forgeqe.yaml mobile:.",
+    tools: ["mobile_explore", "mobile_replay", "mobile_maestro"],
+    keywords: ["mobile", "android", "ios", "iphone", "ipad", "phone", "tablet", "apk", "ipa", "maestro", "appium", "emulator", "simulator", "app store", "play store"],
+    examples: ["Sign in to the courier app and accept the first delivery, and save it as a test", "Replay the courier login on Maestro", "Run our Maestro flows in .maestro/"],
+    requires: [
+      { kind: "live_model", optional: true },
+      { kind: "apps", app: "mobile" },
+      { kind: "input", what: "an Appium server with a device or emulator (or a device cloud), or Maestro installed; the app in env.yaml or forgeqe.yaml mobile.apps" },
+    ],
+    limits: ["Explore runs on Appium only", "Maestro replays do not heal moved controls or compare images (expect_image)", "On TestMu AI, Maestro (through HyperExecute) refuses workflows that type secrets; replay those there with --driver appium"],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Mobile apps (Android, iOS)" }],
+    playbook: [{ heading: "Mobile apps", when: "automate or test an Android or iOS app" }],
+  },
+  {
+    id: "containers",
+    area: "Operations",
+    title: "Services and mocks in Docker or Podman",
+    summary:
+      "Starts the services a test run needs (a database, a queue, the API under test) in Docker or Podman, as forgeqe.yaml declares them, and waits until each is ready; stops them, and shows their status and logs. Starts mocks of an API on WireMock, from the calls a browser run recorded or from an OpenAPI description, and can point an API app of the environment at the mock for the session.",
+    tools: ["services", "mock_service"],
+    keywords: ["docker", "podman", "container", "containers", "compose", "mock", "mocks", "mock service", "mock server", "mock api", "stub", "stubs", "wiremock", "testcontainers", "service up", "services up"],
+    examples: ["Start the database and the queue in Docker", "Start the services from our docker-compose file", "Mock the payments API from the last run", "Create a mock service from openapi.yaml and point order-api at it", "Show the logs of the db container"],
+    requires: [{ kind: "containers" }],
+    limits: [
+      "Starts only services declared in forgeqe.yaml containers.services; it never runs an image, flag or mount from a request",
+      "No privileged containers, host network, or access to the container runtime's socket; ports on 127.0.0.1 only; mounts read-only from inside the project",
+      "Mocks answer REST calls (WireMock); GraphQL, SOAP and gRPC are not mocked",
+      "Reads docker-compose files only for their services' image, ports, environment, bind mounts, command and depends_on; refuses build, privileged, network_mode, cap_add, devices and env_file; leaves named volumes out",
+    ],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Containers and mock services" }],
+    playbook: [{ heading: "Containers and mocks", when: "start, stop or inspect the project's services in Docker or Podman, or mock an API" }],
+  },
   {
     id: "write-tests",
     area: "Automated tests",
@@ -170,6 +260,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Scribe, the coding agent, writes a test for a passed browser run in the repository's own framework, page objects, and helpers; ForgeQE runs it until it passes and a reviewer approves it.",
     tools: ["write_test", "run_test"],
+    keywords: ["automated test", "automation", "automate", "playwright", "cypress", "selenium", "webdriverio", "write a test", "test code", "spec", "turn it into a test", "turn that run into", "scribe"],
     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" }],
@@ -182,6 +273,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Heal failing tests",
     summary: "Runs a repository's tests and updates the ones the application has outgrown against the live app, or reports a real application bug instead.",
     tools: ["heal_tests"],
+    keywords: ["heal", "failing test", "broken test", "fix the tests", "fix tests", "repair"],
     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" }],
@@ -193,6 +285,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Find and run existing tests",
     summary: "Finds the automated tests that match a feature, tags, ids, a folder, or a sprint, confirms the selection, and runs it once the user agrees, with a verdict per test.",
     tools: ["find_tests", "run_tests", "list_sprints"],
+    keywords: ["run the tests", "run tests", "run the", "existing tests", "tests in", "test suite", "npm test", "pytest", "added in sprint", "checkout tests", "tests added"],
     examples: ["Run the checkout tests", "Run the tests added in sprint 12"],
     requires: [
       { kind: "coding_agent" },
@@ -208,6 +301,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Regression packs for a release",
     summary: "Builds a regression pack from what goes into a release (an Azure DevOps sprint or work items, a commit range, pull requests, or changes read from any connected tool): the tests those changes can break, each with why, plus risk-area and smoke tests, and the changes no test covers. Runs it locally, on TestMu AI, or in a pipeline, and compares each run with the last.",
     tools: ["build_regression_pack", "run_regression_pack", "list_regression_packs"],
+    keywords: ["regression", "pack", "which tests should", "release candidate", "merged this week"],
     examples: ["Build a regression pack for sprint 12 and run it on TestMu", "Which tests should we run for the PRs merged this week?"],
     requires: [
       { kind: "input", what: "a repository with tests" },
@@ -222,6 +316,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Flaky test detection and quarantine",
     summary: "Finds tests that flip between passing and failing in the repository's run history, with their likely cause, and quarantines them once the user agrees.",
     tools: ["flaky_tests", "quarantine_tests"],
+    keywords: ["flaky", "quarantine", "intermittent", "unstable", "flakes"],
     examples: ["Which tests are flaky?", "Quarantine the flaky login test"],
     requires: [{ kind: "input", what: "a repository whose tests ForgeQE has run" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Flaky tests" }],
@@ -232,6 +327,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Review pull requests",
     summary: "Reviews an Azure DevOps or GitHub pull request from the local clone for bugs, security, requirements, and tests, and posts the review once the user agrees.",
     tools: ["review_pull_request", "post_pr_review"],
+    keywords: ["review pr", "review the pr", "review pull request", "pull request", "code review", "pr review", "review the change"],
     examples: ["Review PR 42 and focus on error handling"],
     requires: [
       { kind: "coding_agent" },
@@ -249,6 +345,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Works out which product areas, pages, requirements, and tests a pull request touches, picks the tests it can break, runs them, and posts the impact or results on the pull request once the user agrees.",
     tools: ["analyze_pr_impact", "select_pr_tests", "post_pr_test_results", "comment_on_pr"],
+    keywords: ["impact", "pr ", "pull request", "affected", "can break", "what does pr", "changed files"],
     examples: ["What does PR 42 impact?", "Run the tests PR 42 can break"],
     requires: [
       { kind: "input", what: "a local clone of the repository" },
@@ -266,6 +363,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Builds API contracts (status, schema, key fields) from the calls a browser run saw or from an API description (OpenAPI, Swagger, WSDL, GraphQL, .proto, gRPC reflection), and end-to-end API scenarios from runs, descriptions, test cases, or plain English. Runs them straight against the API without a browser, or writes them as tests in the repository. REST, GraphQL, SOAP, and gRPC.",
     tools: ["api_contracts", "run_api_contracts", "api_scenarios", "run_api_scenarios", "write_api_tests"],
+    keywords: ["api", "endpoint", "openapi", "swagger", "contract", "rest", "graphql", "postman", "request", "response"],
     examples: ["Turn the last run's API calls into tests", "Test the API in openapi.yaml", "Write API scenario tests for the order lifecycle"],
     requires: [{ kind: "coding_agent", optional: true }],
     limits: ["Functional API testing, not load or stress testing."],
@@ -281,6 +379,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Accessibility and page performance",
     summary: "Checks every page a run visits against WCAG rules (axe-core) and measures its Core Web Vitals, against budgets, with trends over time per page.",
     tools: ["quality_report", "quality_trends"],
+    keywords: ["accessible", "accessibility", "a11y", "wcag", "performance", "lighthouse", "slow", "page speed", "web vitals", "load time"],
     examples: ["Is the checkout page accessible?", "Did page performance get worse this week?"],
     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."],
@@ -294,6 +393,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Visual comparison with baselines",
     summary: "Compares each page a run captures with its approved baseline and shows what changed; intended changes become the new baseline once the user agrees.",
     tools: ["visual_compare", "visual_approve"],
+    keywords: ["visual", "visually", "baseline", "looks different", "approve the new", "pixel", "screenshot diff", "layout"],
     examples: ["What changed visually since the last run?", "Approve the new header"],
     requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Visual comparison" }],
@@ -305,6 +405,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Groups failures into defects, keeps their history across suites (new, known, gone, back again), and gives defect trends and where a change is likely to cause defects, with the cases to run first.",
     tools: ["defect_trends", "predict_defects"],
+    keywords: ["defect", "bugs keep", "trend", "predict", "coming back", "root cause", "rca", "hotspot", "since main", "changes since", "can the changes"],
     examples: ["Which defects keep coming back?", "What can the changes since main break?"],
     requires: [
       { kind: "input", what: "suites run into one folder (suite.out_dir)" },
@@ -322,6 +423,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Requirement coverage and release readiness",
     summary: "Gives requirement coverage and a GO / GO WITH RISKS / NO-GO verdict for a sprint, area, epic, or stories, from test cases, results, bugs, and flaky tests; can publish it to the wiki.",
     tools: ["release_readiness"],
+    keywords: ["release", "ready to release", "coverage", "go/no-go", "no-go", "readiness", "requirement coverage", "ship"],
     examples: ["Are we ready to release?", "Coverage of sprint 12"],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira"] }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Requirement coverage and release readiness" }],
@@ -332,6 +434,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Scheduled monitoring with alerts",
     summary: "Runs checks on a schedule and alerts Teams or email when one keeps failing, and again when it recovers.",
     tools: ["monitor"],
+    keywords: ["monitor", "every minute", "every hour", "every day", "every night", "every 5 minutes", "every 15 minutes", "every 30 minutes", "schedule", "uptime", "alert", "cron", "minutes", "hourly", "nightly"],
     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" }],
@@ -344,6 +447,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "Tells the team in Microsoft Teams channels or by email when a suite fails or passes, when a release readiness verdict is in, and when the domain evaluation falls below its gate, with the failing cases, their bugs, and links to the report and the CI build. Each channel picks its events; the agent also posts a summary to a channel when asked.",
     tools: ["notify"],
+    keywords: ["teams", "email", "notify", "post the results", "channel", "tell the", "send the"],
     examples: ["Post the results to the QA channel", "Tell the release channel the verdict is NO-GO"],
     requires: [{ kind: "notify_channels" }],
     limits: ["Automatic notifications come from runs nobody is watching (forgeqe suite, forgeqe run, pipelines, the MCP server), not from the interactive shell, where the agent posts only when asked."],
@@ -356,6 +460,7 @@ export const CAPABILITIES: Capability[] = [
     summary:
       "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.",
     tools: ["write_report"],
+    keywords: ["report", "write up", "write-up", "summary", "share", "pdf", "html report"],
     examples: ["Create a release report for all projects", "Write up the open defects as a report I can share"],
     requires: [{ kind: "live_model" }],
     limits: [
@@ -371,6 +476,7 @@ export const CAPABILITIES: Capability[] = [
     title: "CI pipelines",
     summary: "Writes a GitHub Actions or Azure Pipelines workflow that runs ForgeQE, stores the secrets it needs, pushes a branch, and makes the pipeline green.",
     tools: ["push_branch", "set_ci_secret"],
+    keywords: ["pipeline", "github actions", "azure pipelines", "ci", "gitlab", "jenkins", "make it green", "ci secret", "workflow file", "on every pr"],
     examples: ["Add a GitHub Actions workflow that runs tests/cases.yaml on every PR, and make it green"],
     requires: [
       { kind: "command", command: "git" },
@@ -385,6 +491,7 @@ export const CAPABILITIES: Capability[] = [
     title: "Work with Azure DevOps, Jira, GitHub, and Confluence",
     summary: "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.",
     tools: ["query_api", "read_confluence", "create_ado_dashboard", "write_ado_wiki_page", "attach_to_work_item"],
+    keywords: ["jira", "azure devops", "ado", "confluence", "system", "github issue", "work item", "bug", "sprint", "dashboard", "wiki", "comment", "backlog", "issue", "ticket", "requirement"],
     examples: [
       "Show the open bugs in this sprint",
       "Read the checkout requirements from Confluence",
@@ -404,7 +511,8 @@ export const CAPABILITIES: Capability[] = [
     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", "playbook"],
+    tools: ["forgeqe_setup", "capabilities", "playbook", "use_capabilities"],
+    keywords: ["help", "what can you", "how do i", "set up", "setup", "configure", "model", "profile", "skill", "install"],
     examples: ["What can you do?", "Which model am I using?", "How do I set up email alerts?"],
     requires: [],
     docs: [

package/src/capabilities/status.ts

@@ -1,6 +1,7 @@
 import type { AppConfig } from "../config.ts"
 import { findOpencode } from "../code/runtime.ts"
 import { noAgentModel } from "../llm.ts"
+import { findRuntime } from "../containers/run.ts"
 import { CAPABILITIES, type Capability, type Requirement, type System } from "./registry.ts"
 
 /**
@@ -87,6 +88,16 @@ export function requirementGap(r: Requirement, cfg: AppConfig, probes: Probes =
       return cfg.domain ? null : { missing: "the product's industry and regulations", fix: "set domain: in forgeqe.yaml, and list your applicable controls in .forgeqe/knowledge/compliance.md" }
     case "command":
       return probes.which(r.command) ? null : { missing: `${r.command} on PATH${r.why ? ` (${r.why})` : ""}`, fix: `install ${r.command}` }
+    case "apps": {
+      const apps = r.app === "desktop" ? cfg.desktop?.apps : cfg.mobile?.apps
+      return Object.keys(apps || {}).length
+        ? null
+        : { missing: `a ${r.app} app to test`, fix: `add it to env.yaml (kind: ${r.app}) or to ${r.app}.apps in forgeqe.yaml` }
+    }
+    case "containers": {
+      const which = (c: string) => (probes.which(c) ? c : null)
+      return findRuntime(cfg, which) ? null : { missing: `${cfg.containers?.runtime || "Docker or Podman"} on PATH`, fix: "install Docker Desktop, Docker Engine or Podman (containers.runtime in forgeqe.yaml picks one)" }
+    }
     case "input":
       return null
     case "either": {
@@ -130,6 +141,10 @@ export function describeRequirement(r: Requirement): string {
       return "The product's industry and regulations: domain: in forgeqe.yaml, with your applicable controls in .forgeqe/knowledge/compliance.md"
     case "command":
       return `${r.command} on PATH${r.why ? `, ${r.why}` : ""}`
+    case "apps":
+      return `${r.app === "desktop" ? "Windows desktop" : "Mobile"} apps: env.yaml (kind: ${r.app}) or ${r.app}.apps in forgeqe.yaml`
+    case "containers":
+      return "Docker or Podman on PATH; the services to start in containers.services in forgeqe.yaml (mocks need none)"
     case "input":
       return `From your request: ${r.what}`
     case "either":

package/src/cases/rca.ts

@@ -13,6 +13,7 @@ import { lastPassed } from "./defectHistory.ts"
 import { routeOf, type DefectCluster } from "./defects.ts"
 import { reproText } from "./repro.ts"
 import type { CaseResult } from "./types.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 /**
  * Defect intelligence, part three (b): why a defect may happen. Always a hypothesis, never a verdict.
@@ -219,6 +220,7 @@ export async function analyzeCause(
       repo,
       profile: config.llm,
       domain: domainNotes(config),
+      guardrails: guardrailsNotes(config),
       model: config.code.model,
       bin: config.code.opencode,
       readDirs: [repo],

package/src/childEnv.ts

@@ -1,5 +1,6 @@
 import { savedSecrets } from "./auth/store.ts"
 import type { AppConfig } from "./config.ts"
+import { COPILOT_AUTH_ENV, MODELS_TOKEN_ENV, RUNTIME_AUTH_ENV } from "./copilot.ts"
 import { NO_TELEMETRY_ENV, withoutTelemetry } from "./privacy.ts"
 
 /**
@@ -72,7 +73,9 @@ function collectEnvNames(value: unknown, out: Set<string>, inLogins: boolean): v
  * (`*Env` settings), and variables `mcp:` servers reference. Saved-login variables are left out: tests read them.
  */
 export function privateEnvNames(cfg: AppConfig, extra: Iterable<string> = []): string[] {
-  const out = new Set<string>(extra)
+  const out = new Set<string>([...extra, COPILOT_AUTH_ENV, RUNTIME_AUTH_ENV, MODELS_TOKEN_ENV])
+  // A github_copilot profile without api_key_env reaches GitHub Models with GITHUB_TOKEN: a model key then.
+  if (cfg.llm?.provider === "github_copilot" && !cfg.llm.apiKeyEnv) out.add("GITHUB_TOKEN")
   collectEnvNames({ ...cfg, logins: undefined }, out, false)
   for (const name of envRefs(cfg.mcp)) out.add(name)
   // Secrets a saved sign-in put into the environment, including those saved by name (forgeqe auth login NAME).

package/src/cli/args.ts

@@ -8,8 +8,8 @@ export type Flags = Map<string, string | boolean>
 
 /** Flags that never take the next word as their value, so `run --direct "<goal>"` keeps the goal. `--headed=false` still works. */
 export const SWITCHES = new Set([
-  "all", "check", "debug", "direct", "force", "global", "guide", "headed", "help", "locators", "no-code", "no-memory", "no-write-back",
-  "once", "open", "plain", "shots", "steps", "test-alerts", "user", "verbose", "yes",
+  "accept-heals", "all", "all-tools", "check", "debug", "direct", "force", "global", "guide", "headed", "help", "locators", "no-code", "no-heal", "no-memory", "no-write-back",
+  "once", "open", "plain", "shots", "steps", "test-alerts", "ufo", "update-baselines", "user", "verbose", "virtual", "yes",
 ])
 
 export function parseArgs(argv: string[]): { positionals: string[]; flags: Flags } {
@@ -89,6 +89,7 @@ export function configOpts(flags: Flags) {
   return {
     configPath: strFlag(flags, "config"),
     profile: strFlag(flags, "profile"),
+    env: strFlag(flags, "env"),
   }
 }
 

package/src/cli/help.ts

@@ -13,6 +13,7 @@ Usage:
   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 guardrails [add "rule"]             the team's rules every agent must follow (.forgeqe/guardrails), or add one
   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]
@@ -26,6 +27,26 @@ Usage:
                  [--profile name] [--url URL] [--headed] [--plain] [--attempts N] [--skill NAME]
                  [--browser-provider local|browserstack|testmu] [--devices a,b]
                                                run test cases the same way every time (what pipelines call)
+  forgeqe apps [--env NAME]                   the test environments in env.yaml and the apps (web, desktop, mobile) of one;
+                                               every command takes --env NAME (or FORGEQE_ENV) to pick the environment
+  forgeqe desktop explore "<goal>" --app NAME [--name TEXT] [--out DIR] [--yes]
+                                               Windows thick clients: UFO² does the goal on the live app and the run is
+                                               saved as a YAML workflow (docs/DESKTOP.md)
+  forgeqe desktop record --app NAME [--name TEXT]  do the steps in a Windows app yourself; they are saved as a workflow
+  forgeqe desktop replay <workflow.yaml|folder> ... [name=value ...] [--no-heal] [--accept-heals] [--junit FILE]
+                                               replay desktop workflows with no model; moved controls are healed for review
+  forgeqe desktop setup [--ufo] | apps | doctor | validate <workflow.yaml>
+  forgeqe mobile explore "<goal>" --app NAME     Android and iOS apps through Appium: the model does the goal and the run
+                                               is saved as a mobile workflow (docs/MOBILE.md)
+  forgeqe mobile replay <workflow.yaml|folder> [--driver appium|maestro] [--junit FILE]
+                                               replay mobile workflows with no model, on Appium or Maestro
+  forgeqe mobile maestro <flow.yaml|folder>    run your team's Maestro flows (checked against an allowlist first)
+  forgeqe mobile upload <app> [--virtual]      upload a build to TestMu AI; prints the lt:// id for the app's app:
+  forgeqe mobile apps | doctor | flow <workflow.yaml> | validate <workflow.yaml>
+  forgeqe services [status|up|down|logs] [name ...]
+                                               the services forgeqe.yaml (containers.services) or its compose files
+                                               declare, in Docker or Podman: start in order and wait until ready,
+                                               stop, logs (docs/CONTAINERS.md)
   forgeqe cases <source...> [--goal]          list the test cases a source gives (--goal: the goal each runs)
   forgeqe code [run-dir] [--repo DIR] [--attempts N] [--code-model provider/model]
                                                write a test for a run (default: the latest) with Scribe
@@ -36,7 +57,7 @@ Usage:
                   [--browser-provider local|browserstack|testmu]
                                                check flows on a schedule and alert Teams or email when one breaks
   forgeqe monitor --test-alerts               send a sample alert to check the Teams and email settings
-  forgeqe mcp [--repo DIR] [--profile name] [--url URL] [--headed] [--browser-provider local|browserstack|testmu]
+  forgeqe mcp [--all-tools] [--repo DIR] [--profile name] [--url URL] [--headed] [--browser-provider local|browserstack|testmu]
                                                ForgeQE's tools as an MCP server on stdio, for other agents
   forgeqe mcp list                            the Azure DevOps, Jira and other MCP servers ForgeQE's agent gets
   forgeqe bi [build] [--evidence-dir DIR] [--data-dir DIR] [--build-dir DIR] [--static | --evidence]
@@ -90,8 +111,8 @@ Usage:
   forgeqe api tests [SET] --scenarios[=a,b] --repo DIR
                                                scenario tests on the repository's existing API helpers
   forgeqe api list                            saved contract sets
-  forgeqe auth login [system] [--no-browser]  sign in to azure_devops, github, jira, confluence, testrail, zephyr, qtest,
-                                               xray, browserstack, or testmu in the browser, and save the token in the system's credential store
+  forgeqe auth login [system] [--no-browser]  sign in to azure_devops, github, copilot, jira, confluence, testrail, zephyr,
+                                               qtest, xray, browserstack, or testmu in the browser, and save the token in the system's credential store
   forgeqe auth login <ENV_NAME>               save one secret (an LLM API key, a webhook URL) in the credential store
   forgeqe auth [status]                       which systems are signed in, and how
   forgeqe auth logout <system|ENV_NAME>       forget a saved sign-in

package/src/cli/index.ts

@@ -56,9 +56,15 @@ import { DOMAIN_CASES, gate, loadDomainCases, reportMarkdown, runDomainEval, sav
 import { evalNotice, notifiedLine, notify, notifySuite } from "../notify/events.ts"
 import { sendNotice, type Notice } from "../notify/notice.ts"
 import { buildBi, initBiProject, syncBiData } from "../bi.ts"
+import { cmdDesktop } from "../desktop/command.ts"
+import { cmdMobile } from "../mobile/command.ts"
+import { cmdServices } from "../containers/command.ts"
+import { startedContainers, stopStartedContainers } from "../containers/run.ts"
+import { CapabilityScope } from "../mcp/scope.ts"
+import { appsText } from "../environments.ts"
 
 const AGENT_COMMANDS = new Set(["start", "run", "code", "suite", "heal", "monitor", "explore"])
-const LOGGED_COMMANDS = new Set([...AGENT_COMMANDS, "mcp", "login", "setup", "bi"])
+const LOGGED_COMMANDS = new Set([...AGENT_COMMANDS, "mcp", "login", "setup", "bi", "desktop", "mobile", "services"])
 
 /** How much of the agents' work to print: brief unless --verbose. */
 const detailOf = (flags: Flags) => detailFrom(boolFlag(flags, "verbose"))
@@ -151,6 +157,9 @@ export async function main(argv: string[]): Promise<number> {
     return 0
   }
 
+  // --env picks the test environment (env.yaml) for everything this process loads: commands, the shell, MCP, suites.
+  const envFlag = strFlag(flags, "env")
+  if (envFlag) process.env.FORGEQE_ENV = envFlag
   // Sign-ins saved with forgeqe auth login, under the names the config reads; the terminal's own variables win.
   await applySavedCredentials().catch(() => [])
   // Models' list prices for costs: waited for only the first time, refreshed daily in the background after that.
@@ -176,8 +185,26 @@ export async function main(argv: string[]): Promise<number> {
         const { agentContexts, contextReport } = await import("../context.ts")
         const rows = agentContexts()
         console.log(contextReport(rows).join("\n"))
+        // The team's guardrails ride on top of every agent's fixed context.
+        const { guardrailsNotes, readGuardrails } = await import("../guardrails.ts")
+        const gcfg = loadConfig(configOpts(flags))
+        const block = guardrailsNotes(gcfg)
+        if (block) console.log(`\nGuardrails: ${readGuardrails(gcfg).length} rules add ~${Math.ceil(block.length / 4)} tokens to every agent above (forgeqe guardrails lists them).`)
         return rows.some((r) => r.over) ? 1 : 0
       }
+      case "guardrails": {
+        // The team's rules for every agent: list them, or add one (src/guardrails.ts).
+        const { addGuardrail, guardrailsText } = await import("../guardrails.ts")
+        const cfg = loadConfig(configOpts(flags))
+        if (positionals[1] === "add") {
+          const { added, file } = addGuardrail(cfg, positionals.slice(2).join(" "))
+          console.log(added ? `Added to ${file}. Every agent started from now on follows it (restart a running ForgeQE shell for its own agent).` : `That guardrail is already in force (${file}).`)
+          return 0
+        }
+        if (positionals[1]) throw new Error(`Unknown guardrails action "${positionals[1]}". Use: forgeqe guardrails [add "rule"]`)
+        console.log(guardrailsText(cfg))
+        return 0
+      }
       case "features":
         // What ForgeQE can do, and whether each capability works with this config and machine.
         console.log(featuresText(loadConfig(configOpts(flags))))
@@ -212,6 +239,15 @@ export async function main(argv: string[]): Promise<number> {
         return await withUsageLine(() => cmdExplore(positionals.slice(1), flags))
       case "bi":
         return await cmdBi(positionals.slice(1), flags)
+      case "desktop":
+        return await withUsageLine(() => cmdDesktop(positionals.slice(1), flags))
+      case "mobile":
+        return await withUsageLine(() => cmdMobile(positionals.slice(1), flags))
+      case "services":
+        return await withUsageLine(() => cmdServices(positionals.slice(1), flags))
+      case "apps":
+        console.log(appsText(loadConfig(configOpts(flags))))
+        return 0
       case "prompts":
         return positionals[1] === "eval" ? await withUsageLine(() => cmdPromptEval(positionals.slice(2), flags)) : cmdPrompts(positionals.slice(1), flags)
       case "eval":
@@ -897,6 +933,11 @@ async function cmdStart(flags: Flags): Promise<number> {
 
 /** Background monitors started by the agent live as long as this process; wind their rounds down before exiting. */
 async function stopMonitorsOnExit(log: (line: string) => void) {
+  // Services and mocks the agent started in this session end with it (forgeqe services up keeps its own).
+  if (startedContainers().length) {
+    log(`Stopping the containers this session started (${startedContainers().join(", ")})…`)
+    await stopStartedContainers()
+  }
   const running = backgroundMonitors()
   if (!running.length) return
   log(`Stopping ${running.length === 1 ? "the monitor" : `${running.length} monitors`}…`)
@@ -1062,6 +1103,7 @@ async function runAgent(cfg: AppConfig, flags: Flags, text: string, maxSteps: nu
   } finally {
     process.off("SIGINT", onSigint)
     await brain?.close()
+    if (startedContainers().length) await stopStartedContainers()
   }
 }
 
@@ -1105,8 +1147,10 @@ async function cmdMcp(args: string[], flags: Flags): Promise<number> {
     emit: log,
     session: "server",
   })
-  const server = createMcpServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), version: packageVersion() })
-  process.stderr.write(`ForgeQE MCP server on stdio (${TOOLS.length} tools, working in ${cwd})\n`)
+  // The client lists the core and the capabilities this project can use; use_capabilities adds more (--all-tools: every tool).
+  const scope = boolFlag(flags, "all-tools") ? undefined : new CapabilityScope(cfg, TOOLS.map((t) => t.name))
+  const server = createMcpServer({ tools: TOOLS, context, instructions: () => environmentNotes(context()), version: packageVersion(), ...(scope ? { scope } : {}) })
+  process.stderr.write(`ForgeQE MCP server on stdio (${scope ? `${scope.listedTools().length} of ${TOOLS.length}` : TOOLS.length} tools, working in ${cwd})\n`)
   await serveStdio(server)
   await stopMonitorsOnExit((line) => process.stderr.write(`${line}\n`))
   return 0

package/src/code/find.ts

@@ -13,11 +13,32 @@ import { CAUSE_TEXT, flakyReport, quarantined, recordResults, RELEASE_AFTER, set
 import { loadSkills } from "../skills/registry.ts"
 import { prompt } from "../prompts.ts"
 import { domainNotes } from "../domain.ts"
+import { guardrailsNotes } from "../guardrails.ts"
 
 const LIST_ROUNDS = 3
 const LIST_TIMEOUT_SECONDS = 180
 const OUTPUT_CHARS = 6_000
 
+/**
+ * ForgeQE runs Scribe's list command without asking, so it takes only a test framework's own listing: Scribe reads the
+ * repository, and a file in it could talk Scribe into any command. The run command is shown to the user first instead.
+ */
+const LIST_RUNNER =
+  /^(?:(?:(?:npx(?:\s+--no-install)?|pnpm(?:\s+exec)?|yarn|bunx|bun\s+x)\s+)?(?:playwright\s+test|jest|vitest|mocha)|(?:(?:python3?|py)\s+-m\s+|(?:uv|poetry)\s+run\s+)?pytest|dotnet\s+test)(?=\s|$)/i
+const LIST_FLAG = /(?:^|\s)(?:--list|--listTests|--list-tests|--collect-only|--co|--dry-run)(?=[\s=]|$)/
+/** Characters that chain, substitute, or redirect in sh or cmd.exe. */
+const SHELL_SYNTAX = /[;&|`$<>()\r\n%]/
+
+/** Whether ForgeQE may run `command` unasked as a list command: one test runner, a listing flag, no shell syntax. */
+export function listCommandAllowed(command: string): boolean {
+  const c = command.trim()
+  if (!c || SHELL_SYNTAX.test(c)) return false
+  const runner = LIST_RUNNER.exec(c)
+  if (!runner) return false
+  const rest = c.slice(runner[0].length)
+  return LIST_FLAG.test(rest) || (/vitest$/i.test(runner[0]) && /^\s+list(?=\s|$)/.test(rest))
+}
+
 export const findAgentPrompt = () => prompt("find-tests")
 
 export const FIND_AGENT: AgentSpec = {
@@ -176,6 +197,7 @@ export async function findTests(opts: {
     repo,
     profile: opts.config.llm,
     domain: domainNotes(opts.config),
+    guardrails: guardrailsNotes(opts.config),
     model: opts.config.code.model,
     bin: opts.config.code.opencode,
     readDirs: [repo],
@@ -195,6 +217,10 @@ export async function findTests(opts: {
     let report = reply.report
     let listed = false
     for (let round = 1; round <= LIST_ROUNDS && clean(report.tests).length && report.list_command?.trim() && !opts.signal?.aborted; round++) {
+      if (!listCommandAllowed(report.list_command!)) {
+        emit({ type: "code", kind: "info", text: `ForgeQE does not run this list command, which is not a test framework's own listing: ${report.list_command}` })
+        break
+      }
       emit({ type: "code", kind: "info", text: `ForgeQE lists the selected tests: ${report.list_command}` })
       const run = await runTest({ command: report.list_command!, cwd: repo, timeoutSeconds: LIST_TIMEOUT_SECONDS, signal: opts.signal, hide: privateEnvNames(opts.config) })
       if (opts.signal?.aborted) break