@validate.qa/mcp 1.0.1 → 1.2.0

package/dist/index.js

@@ -1,21 +1,81 @@
 #!/usr/bin/env node
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
 
+// src/token-store.ts
+import { chmodSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+function defaultTokenStoreDir() {
+  return join(homedir(), ".validateqa");
+}
+function tokenStorePath(dir = defaultTokenStoreDir()) {
+  return join(dir, "credentials.json");
+}
+function storeKey(apiUrl, projectId) {
+  try {
+    return `${new URL(apiUrl).origin} ${projectId}`;
+  } catch {
+    return null;
+  }
+}
+function readTokenFile(dir) {
+  try {
+    const parsed = JSON.parse(readFileSync(tokenStorePath(dir), "utf-8"));
+    if (parsed && typeof parsed.tokens === "object" && parsed.tokens !== null) {
+      return { version: 1, tokens: parsed.tokens };
+    }
+  } catch {
+  }
+  return { version: 1, tokens: {} };
+}
+function readStoredToken(apiUrl, projectId, dir = defaultTokenStoreDir()) {
+  const key = storeKey(apiUrl, projectId);
+  if (!key) return void 0;
+  const token = readTokenFile(dir).tokens[key];
+  return typeof token === "string" && token ? token : void 0;
+}
+function saveToken(apiUrl, projectId, token, dir = defaultTokenStoreDir()) {
+  const key = storeKey(apiUrl, projectId);
+  if (!key) throw new Error(`Invalid API URL: ${apiUrl}`);
+  mkdirSync(dir, { recursive: true, mode: 448 });
+  const file = readTokenFile(dir);
+  file.tokens[key] = token;
+  const path = tokenStorePath(dir);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(file, null, 2) + "\n", { encoding: "utf-8", mode: 384 });
+  renameSync(tmp, path);
+  chmodSync(path, 384);
+  return path;
+}
+var init_token_store = __esm({
+  "src/token-store.ts"() {
+    "use strict";
+  }
+});
+
 // src/init.ts
 var init_exports = {};
 __export(init_exports, {
+  buildMcpEntry: () => buildMcpEntry,
+  initProject: () => initProject,
+  parseInitArgs: () => parseInitArgs,
   runInit: () => runInit
 });
-import { existsSync, mkdirSync, readFileSync as readFileSync2, writeFileSync } from "fs";
-import { resolve as resolve2, join } from "path";
+import { appendFileSync, existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { resolve as resolve2, join as join2 } from "path";
 function parseInitArgs(argv) {
   const args = {};
   for (let i = 0; i < argv.length; i++) {
@@ -24,7 +84,7 @@ function parseInitArgs(argv) {
       args[arg.slice(2)] = argv[++i];
     }
   }
-  const apiUrl = args["api-url"] ?? process.env.VALIDATEQA_API_URL ?? "https://shared-server.up.railway.app";
+  const apiUrl = args["api-url"] ?? process.env.VALIDATEQA_API_URL ?? "https://shared.validate.qa";
   const token = args["token"] ?? process.env.VALIDATEQA_TOKEN;
   const projectId = args["project-id"] ?? process.env.VALIDATEQA_PROJECT_ID;
   if (!token) {
@@ -37,7 +97,7 @@ function parseInitArgs(argv) {
   }
   return { apiUrl: apiUrl.replace(/\/$/, ""), token, projectId };
 }
-function buildMcpEntry(config2) {
+function buildMcpEntry(config2, opts) {
   return {
     command: "npx",
     args: [
@@ -45,8 +105,7 @@ function buildMcpEntry(config2) {
       "@validate.qa/mcp@latest",
       "--api-url",
       config2.apiUrl,
-      "--token",
-      config2.token,
+      ...opts.withToken ? ["--token", config2.token] : [],
       "--project-id",
       config2.projectId
     ]
@@ -61,7 +120,7 @@ function writeConfigForIDE(cwd, target, entry) {
   let existing = {};
   if (existsSync(filePath)) {
     try {
-      existing = JSON.parse(readFileSync2(filePath, "utf-8"));
+      existing = JSON.parse(readFileSync3(filePath, "utf-8"));
     } catch {
     }
   }
@@ -70,39 +129,61 @@ function writeConfigForIDE(cwd, target, entry) {
   servers["validate.qa"] = entry;
   existing[target.serversKey] = servers;
   if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true });
+    mkdirSync2(dir, { recursive: true });
   }
-  writeFileSync(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+  writeFileSync2(filePath, JSON.stringify(existing, null, 2) + "\n", "utf-8");
   return hadEntry ? "updated" : "created";
 }
+function ignoreInGit(cwd, file) {
+  const gitignore = resolve2(cwd, ".gitignore");
+  const line = "/" + file.replace(/\\/g, "/").replace(/^\.\//, "");
+  const current = existsSync(gitignore) ? readFileSync3(gitignore, "utf-8") : "";
+  if (current.split(/\r?\n/).includes(line)) return;
+  appendFileSync(gitignore, `${current && !current.endsWith("\n") ? "\n" : ""}${line}
+`, "utf-8");
+}
+function initProject(cwd, config2, storeDir = defaultTokenStoreDir()) {
+  let tokenFile = null;
+  let tokenStoreError;
+  try {
+    tokenFile = saveToken(config2.apiUrl, config2.projectId, config2.token, storeDir);
+  } catch (err) {
+    tokenStoreError = err instanceof Error ? err.message : String(err);
+  }
+  const entry = buildMcpEntry(config2, { withToken: tokenFile === null });
+  const written = [];
+  for (const target of IDE_TARGETS) {
+    const result = writeConfigForIDE(cwd, target, entry);
+    if (result === "skipped") continue;
+    written.push({ name: target.name, file: join2(target.configDir, target.configFile), result });
+  }
+  if (written.length === 0) {
+    const target = IDE_TARGETS[0];
+    const result = writeConfigForIDE(cwd, target, entry);
+    if (result !== "skipped") written.push({ name: target.name, file: target.configFile, result });
+  }
+  if (tokenFile === null) {
+    for (const { file } of written) ignoreInGit(cwd, file);
+  }
+  return { written, tokenFile, ...tokenStoreError ? { tokenStoreError } : {} };
+}
 function runInit() {
   const config2 = parseInitArgs(process.argv.slice(3));
-  const entry = buildMcpEntry(config2);
-  const cwd = process.cwd();
   console.log("");
   console.log("  Validate.QA - MCP Setup");
   console.log("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   console.log("");
-  let anyWritten = false;
-  for (const target of IDE_TARGETS) {
-    const result = writeConfigForIDE(cwd, target, entry);
-    if (result === "skipped") {
-      continue;
-    }
-    const file = join(target.configDir, target.configFile);
-    if (result === "created") {
-      console.log(`  \u2713 ${target.name} - created ${file}`);
-    } else {
-      console.log(`  \u2713 ${target.name} - updated ${file}`);
-    }
-    anyWritten = true;
+  const { written, tokenFile, tokenStoreError } = initProject(process.cwd(), config2);
+  for (const { name, file, result } of written) {
+    console.log(`  \u2713 ${name} - ${result} ${file}`);
   }
-  if (!anyWritten) {
-    const target = IDE_TARGETS[0];
-    writeConfigForIDE(cwd, target, entry);
-    console.log(`  \u2713 Created ${target.configFile} (works with Claude Code)`);
-    console.log("");
-    console.log("  Tip: Create a .cursor/ or .windsurf/ directory and re-run to set up those IDEs too.");
+  console.log("");
+  if (tokenFile) {
+    console.log(`  Your token is saved in ${tokenFile} (only you can read it), not in these files,`);
+    console.log("  so they are safe to commit. Teammates run their own init command.");
+  } else {
+    console.log(`  \u26A0 Could not save your token outside the repo (${tokenStoreError}).`);
+    console.log("    The config files above hold it, so they were added to .gitignore. Do not commit them.");
   }
   console.log("");
   console.log("  Next: restart your IDE or reload MCP servers.");
@@ -113,6 +194,7 @@ var IDE_TARGETS;
 var init_init = __esm({
   "src/init.ts"() {
     "use strict";
+    init_token_store();
     IDE_TARGETS = [
       { name: "Claude Code", configDir: ".", configFile: ".mcp.json", serversKey: "mcpServers" },
       { name: "Cursor", configDir: ".cursor", configFile: "mcp.json", serversKey: "mcpServers" },
@@ -122,12 +204,292 @@ var init_init = __esm({
   }
 });
 
+// src/agent-rules.ts
+var AGENT_RULES;
+var init_agent_rules = __esm({
+  "src/agent-rules.ts"() {
+    "use strict";
+    AGENT_RULES = `## Validate.QA Rules
+
+Use the \`validate.qa\` MCP server alongside Playwright so explored flows and saved regression tests run and stay verified in Validate.QA.
+
+### Loop Workflow
+1. Call \`start_here\` first (\`start_here({ feature })\`, or \`start_here({})\` to list features) to read the feature's pages, existing tests, \`knownSelectors\`, credential readiness, and \`openBugs\`. Skip bugs already listed in \`openBugs\`.
+2. Save each bug or regression test with \`save_regression_test\` using Playwright code that asserts the **correct** behaviour (fails while the bug exists, passes once fixed). \`save_regression_test\` returns immediately while the run executes in the cloud \u2014 keep exploring without waiting.
+3. Call \`collect_verdicts\` at the end of the session. \`reproduces\` (the test fails on its check) means the bug is locked in: keep that test as it is. \`passes\` means the test misses the bug: check again in your browser and fix its assertion. \`test_problem\` means it broke before its check: fix the steps and keep the expected value. Fix with \`edit_test_code\`, then call \`collect_verdicts\` again.
+
+### Test Code Rules
+- Never weaken an assertion to make a test pass; always assert the exact correct behaviour.
+- One deterministic \`expect()\` per outcome: cover one bug or outcome per test and end with a deterministic \`expect()\` on the exact value or state the app should produce.
+- Relative URLs only (\`await page.goto('/orders')\`, path-only URL checks) \u2014 never hardcode a host or scheme; the runner sets \`baseURL\`.
+- Read credentials from \`process.env\` (\`process.env.TEST_USER_EMAIL!\` and \`process.env.TEST_USER_PASSWORD!\` with non-null assertions) \u2014 never hardcode literals or add \`??\` / \`||\` fallbacks.
+- Prefer verified locators from \`knownSelectors\`, \`getByRole(role, { name, exact: true })\`, \`getByLabel\`, and \`getByTestId\`; never use \`waitForLoadState('networkidle')\`.
+
+### Healer
+- A heal may change locators and waits, but never removes or loosens an \`expect()\`.
+- If the app is wrong, do not alter the expected value or silence the test with \`test.fixme()\` \u2014 flag it as a bug with \`flag_as_bug\` instead.`;
+  }
+});
+
+// src/init-agents.ts
+var init_agents_exports = {};
+__export(init_agents_exports, {
+  RULES_END_MARKER: () => RULES_END_MARKER,
+  RULES_START_MARKER: () => RULES_START_MARKER,
+  VALID_LOOPS: () => VALID_LOOPS,
+  applyRulesSection: () => applyRulesSection,
+  initAgents: () => initAgents,
+  parseInitAgentsArgs: () => parseInitAgentsArgs,
+  runInitAgents: () => runInitAgents,
+  spawnPlaywrightInitAgents: () => spawnPlaywrightInitAgents,
+  validateLoop: () => validateLoop
+});
+import { spawn } from "child_process";
+import { existsSync as existsSync2, mkdirSync as mkdirSync3, readdirSync, readFileSync as readFileSync4, statSync, writeFileSync as writeFileSync3 } from "fs";
+import { dirname, join as join3, resolve as resolve3 } from "path";
+function validateLoop(loop) {
+  if (VALID_LOOPS.includes(loop)) {
+    return loop;
+  }
+  throw new Error(`Unknown --loop "${loop}". Expected one of: ${VALID_LOOPS.join(", ")}.`);
+}
+function parseInitAgentsArgs(argv, cwd = process.cwd()) {
+  let rawLoop;
+  let rawDir;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--loop") {
+      const next = argv[i + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        throw new Error(`Missing value for --loop. Expected one of: ${VALID_LOOPS.join(", ")}.`);
+      }
+      rawLoop = next;
+      i++;
+    } else if (arg.startsWith("--loop=")) {
+      rawLoop = arg.slice("--loop=".length);
+    } else if (arg === "--dir") {
+      const next = argv[i + 1];
+      if (next === void 0 || next.startsWith("--")) {
+        throw new Error("Missing value for --dir.");
+      }
+      rawDir = next;
+      i++;
+    } else if (arg.startsWith("--dir=")) {
+      rawDir = arg.slice("--dir=".length);
+      if (!rawDir) throw new Error("Missing value for --dir.");
+    } else {
+      throw new Error(`Unknown argument "${arg}". Usage: init-agents [--loop claude|vscode|opencode] [--dir <repo>]`);
+    }
+  }
+  return {
+    loop: validateLoop(rawLoop ?? "claude"),
+    dir: rawDir ? resolve3(cwd, rawDir) : resolve3(cwd)
+  };
+}
+function spawnPlaywrightInitAgents({ dir, loop }) {
+  const command = process.platform === "win32" ? "npx.cmd" : "npx";
+  const args = ["playwright", "init-agents", `--loop=${loop}`];
+  return new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, { cwd: dir, stdio: "inherit", shell: process.platform === "win32" });
+    child.on("error", (err) => {
+      rejectPromise(new Error(`Failed to run npx playwright init-agents --loop=${loop}: ${err.message}`));
+    });
+    child.on("close", (code, signal) => {
+      if (code === 0) {
+        resolvePromise();
+      } else {
+        const detail = code !== null ? `exit code ${code}` : `signal ${signal}`;
+        rejectPromise(new Error(`npx playwright init-agents --loop=${loop} failed (${detail}).`));
+      }
+    });
+  });
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function applyRulesSection(content, rules = AGENT_RULES) {
+  const block = `${RULES_START_MARKER}
+${rules.trim()}
+${RULES_END_MARKER}`;
+  const delimitedPattern = new RegExp(
+    `${escapeRegExp(RULES_START_MARKER)}[\\s\\S]*?${escapeRegExp(RULES_END_MARKER)}`,
+    "g"
+  );
+  if (delimitedPattern.test(content)) {
+    let replacedFirst = false;
+    const updated = content.replace(delimitedPattern, () => {
+      if (replacedFirst) return "";
+      replacedFirst = true;
+      return block;
+    });
+    return `${updated.replace(/\s+$/, "")}
+`;
+  }
+  if (content.includes(RULES_START_MARKER)) {
+    const start = content.indexOf(RULES_START_MARKER);
+    const before = content.slice(0, start).replace(/\s+$/, "");
+    return before ? `${before}
+
+${block}
+` : `${block}
+`;
+  }
+  const trimmed = content.replace(/\s+$/, "");
+  return trimmed ? `${trimmed}
+
+${block}
+` : `${block}
+`;
+}
+function candidateAgentDirs(loop) {
+  switch (loop) {
+    case "claude":
+      return [".claude/agents"];
+    case "vscode":
+      return [".github/agents", ".github/chatmodes"];
+    case "opencode":
+      return [".opencode/prompts", ".opencode/agents"];
+  }
+}
+function findAgentFiles(dir, loop) {
+  for (const relDir of candidateAgentDirs(loop)) {
+    const fullDir = resolve3(dir, relDir);
+    if (!existsSync2(fullDir) || !statSync(fullDir).isDirectory()) continue;
+    const matches = readdirSync(fullDir).filter((entry) => entry.endsWith(".md") && AGENT_FILE_RE.test(entry)).sort().map((entry) => join3(fullDir, entry));
+    if (matches.length > 0) return matches;
+  }
+  return [];
+}
+function mcpTargetForLoop(loop) {
+  switch (loop) {
+    case "claude":
+      return {
+        relativePath: ".mcp.json",
+        serversKey: "mcpServers",
+        entry: {
+          command: "npx",
+          args: ["-y", "@validate.qa/mcp"],
+          env: { VALIDATEQA_TOOLSET: "agent" }
+        }
+      };
+    case "vscode":
+      return {
+        relativePath: join3(".vscode", "mcp.json"),
+        serversKey: "servers",
+        entry: {
+          type: "stdio",
+          command: "npx",
+          args: ["-y", "@validate.qa/mcp"],
+          env: { VALIDATEQA_TOOLSET: "agent" }
+        }
+      };
+    case "opencode":
+      return {
+        relativePath: "opencode.json",
+        serversKey: "mcp",
+        entry: {
+          type: "local",
+          command: ["npx", "-y", "@validate.qa/mcp"],
+          environment: { VALIDATEQA_TOOLSET: "agent" },
+          enabled: true
+        }
+      };
+  }
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readJsonObject(filePath) {
+  if (!existsSync2(filePath)) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync4(filePath, "utf-8"));
+  } catch {
+    parsed = void 0;
+  }
+  if (!isPlainObject(parsed)) {
+    throw new Error(
+      `${filePath} is not a plain JSON object (comments and trailing commas are not supported), so init-agents left it untouched. Make it plain JSON, or move it aside, and run init-agents again.`
+    );
+  }
+  return parsed;
+}
+async function initAgents(options = {}) {
+  const loop = validateLoop(options.loop ?? "claude");
+  const dir = options.dir ? resolve3(options.dir) : resolve3(process.cwd());
+  const runPlaywright = options.runPlaywright ?? spawnPlaywrightInitAgents;
+  const log = options.log ?? console.log;
+  if (!existsSync2(dir) || !statSync(dir).isDirectory()) {
+    throw new Error(`Target directory does not exist: ${dir}`);
+  }
+  const mcpTarget = mcpTargetForLoop(loop);
+  const mcpConfigFile = join3(dir, mcpTarget.relativePath);
+  const beforeDoc = readJsonObject(mcpConfigFile);
+  const beforeServers = isPlainObject(beforeDoc[mcpTarget.serversKey]) ? { ...beforeDoc[mcpTarget.serversKey] } : {};
+  await runPlaywright({ dir, loop });
+  const agentFiles = findAgentFiles(dir, loop);
+  if (agentFiles.length === 0) {
+    throw new Error(`No Playwright agent files (planner, generator, healer) found in ${dir} for loop "${loop}".`);
+  }
+  for (const filePath of agentFiles) {
+    const current = readFileSync4(filePath, "utf-8");
+    writeFileSync3(filePath, applyRulesSection(current, AGENT_RULES), "utf-8");
+  }
+  const afterDoc = readJsonObject(mcpConfigFile);
+  const afterServers = isPlainObject(afterDoc[mcpTarget.serversKey]) ? afterDoc[mcpTarget.serversKey] : {};
+  const mergedServers = { ...beforeServers, ...afterServers };
+  if (Object.prototype.hasOwnProperty.call(beforeServers, "validate.qa")) {
+    mergedServers["validate.qa"] = beforeServers["validate.qa"];
+  }
+  const hadValidateQa = Object.prototype.hasOwnProperty.call(mergedServers, "validate.qa");
+  if (!hadValidateQa) {
+    mergedServers["validate.qa"] = mcpTarget.entry;
+  }
+  const mergedDoc = {
+    ...beforeDoc,
+    ...afterDoc,
+    [mcpTarget.serversKey]: mergedServers
+  };
+  mkdirSync3(dirname(mcpConfigFile), { recursive: true });
+  writeFileSync3(mcpConfigFile, `${JSON.stringify(mergedDoc, null, 2)}
+`, "utf-8");
+  log("No token was written. The server reads its project from .validateqa.json and its token from your token store: run the init command from your Validate.QA dashboard once, or set VALIDATEQA_TOKEN, VALIDATEQA_PROJECT_ID and VALIDATEQA_API_URL.");
+  return {
+    loop,
+    dir,
+    agentFiles,
+    mcpConfigFile,
+    mcpEntryStatus: hadValidateQa ? "preserved" : "added"
+  };
+}
+async function runInitAgents(argv = process.argv.slice(3)) {
+  try {
+    const parsed = parseInitAgentsArgs(argv);
+    await initAgents(parsed);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+}
+var VALID_LOOPS, RULES_START_MARKER, RULES_END_MARKER, AGENT_FILE_RE;
+var init_init_agents = __esm({
+  "src/init-agents.ts"() {
+    "use strict";
+    init_agent_rules();
+    VALID_LOOPS = ["claude", "vscode", "opencode"];
+    RULES_START_MARKER = "<!-- validate.qa:start -->";
+    RULES_END_MARKER = "<!-- validate.qa:end -->";
+    AGENT_FILE_RE = /(?:^|[^a-z])(planner|generator|healer)(?:[^a-z]|$)/i;
+  }
+});
+
 // src/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/config.ts
-import { readFileSync } from "fs";
+init_token_store();
+import { readFileSync as readFileSync2 } from "fs";
 import { resolve } from "path";
 function parseArgs(argv) {
   const args = {};
@@ -142,7 +504,7 @@ function parseArgs(argv) {
 }
 function loadDotFile() {
   try {
-    const content = readFileSync(resolve(process.cwd(), ".validateqa.json"), "utf-8");
+    const content = readFileSync2(resolve(process.cwd(), ".validateqa.json"), "utf-8");
     const json = JSON.parse(content);
     return {
       apiUrl: typeof json.apiUrl === "string" ? json.apiUrl : void 0,
@@ -152,34 +514,62 @@ function loadDotFile() {
     return {};
   }
 }
+function toolsetFrom(value) {
+  if (value === void 0 || value === "" || value === "full") return "full";
+  if (value === "agent") return "agent";
+  console.error(`Unknown toolset "${value}" (--toolset, VALIDATEQA_TOOLSET): expected "agent" or "full". Serving every tool.`);
+  return "full";
+}
 function resolveConfig() {
   const cliArgs = parseArgs(process.argv.slice(2));
   const dotFile = loadDotFile();
   const apiUrl = cliArgs["api-url"] ?? process.env.VALIDATEQA_API_URL ?? dotFile.apiUrl;
-  const token = cliArgs["token"] ?? process.env.VALIDATEQA_TOKEN;
   const projectId = cliArgs["project-id"] ?? process.env.VALIDATEQA_PROJECT_ID ?? dotFile.projectId;
+  const token = cliArgs["token"] ?? process.env.VALIDATEQA_TOKEN ?? (apiUrl && projectId ? readStoredToken(apiUrl, projectId) : void 0);
   if (!apiUrl) {
     console.error("Missing required config: api-url (--api-url, VALIDATEQA_API_URL, or .validateqa.json)");
     process.exit(1);
   }
   if (!token) {
-    console.error("Missing required config: token (--token or VALIDATEQA_TOKEN)");
+    console.error("Missing required config: token (--token, VALIDATEQA_TOKEN, or run the init command from your Validate.QA dashboard again)");
     process.exit(1);
   }
   if (!projectId) {
     console.error("Missing required config: project-id (--project-id, VALIDATEQA_PROJECT_ID, or .validateqa.json)");
     process.exit(1);
   }
-  return { apiUrl: apiUrl.replace(/\/$/, ""), token, projectId };
+  const toolset = toolsetFrom(cliArgs["toolset"] ?? process.env.VALIDATEQA_TOOLSET);
+  return { apiUrl: apiUrl.replace(/\/$/, ""), token, projectId, toolset };
 }
 
 // src/api-client.ts
+var PLAN_FEATURE_LOCKED_CODE = "PLAN_FEATURE_LOCKED";
+var ApiResponseError = class extends Error {
+  status;
+  body;
+  constructor(status, body) {
+    const message = typeof body.error === "string" && body.error.length > 0 ? body.error : `API error ${status}`;
+    super(message);
+    this.name = "ApiResponseError";
+    this.status = status;
+    this.body = body;
+  }
+};
+function toolErrorText(err) {
+  if (err instanceof ApiResponseError && err.body.code === PLAN_FEATURE_LOCKED_CODE) {
+    return JSON.stringify(err.body);
+  }
+  return `Error: ${err instanceof Error ? err.message : String(err)}`;
+}
 var ValidateQAClient = class {
   constructor(baseUrl, token, projectId) {
     this.baseUrl = baseUrl;
     this.token = token;
     this.projectId = projectId;
   }
+  baseUrl;
+  token;
+  projectId;
   async executeTool(tool2, args = {}) {
     let res;
     try {
@@ -199,11 +589,28 @@ var ValidateQAClient = class {
       throw new Error(`Connection failed: ${msg}${cause ? ` (${cause})` : ""}`);
     }
     if (!res.ok) {
-      const body = await res.json().catch(() => ({ error: res.statusText }));
-      throw new Error(body.error || `API error ${res.status}`);
+      const parsed = await res.json().catch(() => ({ error: res.statusText }));
+      const body = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : { error: res.statusText };
+      throw new ApiResponseError(res.status, body);
     }
     return res.json();
   }
+  /** project://test-conventions from the server (GET /api/mcp/test-conventions); null when the server predates it. */
+  async getTestConventions() {
+    try {
+      const res = await fetch(`${this.baseUrl}/api/mcp/test-conventions`, {
+        headers: {
+          "Authorization": `Bearer ${this.token}`,
+          "X-Project-Id": this.projectId
+        },
+        signal: AbortSignal.timeout(3e4)
+      });
+      if (!res.ok) return null;
+      return await res.json();
+    } catch {
+      return null;
+    }
+  }
   async healthCheck() {
     try {
       const res = await fetch(`${this.baseUrl}/health`, {
@@ -217,7 +624,397 @@ var ValidateQAClient = class {
 };
 
 // src/tools/index.ts
+import { z as z2 } from "zod";
+
+// src/tools/agent-tools.ts
 import { z } from "zod";
+var AGENT_TOOL_NAMES = /* @__PURE__ */ new Set([
+  "start_here",
+  "get_feature",
+  "save_regression_test",
+  "collect_verdicts",
+  "edit_test_code",
+  "get_test_code",
+  "list_tests",
+  "get_test_run",
+  "get_test_screenshots",
+  "list_bugs",
+  "flag_as_bug",
+  "delete_test"
+]);
+function limitTools(server2, names) {
+  return new Proxy(server2, {
+    get(target, prop, receiver) {
+      if (prop !== "tool") return Reflect.get(target, prop, receiver);
+      return (name, ...rest) => names.has(name) ? target.tool.call(target, name, ...rest) : void 0;
+    }
+  });
+}
+var AgentSession = class {
+  saved = /* @__PURE__ */ new Map();
+  remember(test) {
+    this.saved.set(test.testId, test);
+  }
+  /** An edited test's last run checked the old code: collect_verdicts runs it again. */
+  markEdited(testId) {
+    const test = this.saved.get(testId);
+    if (test) test.edited = true;
+  }
+  /**
+   * `client`, noting each edit_test_code call so collect_verdicts knows which runs are out of date. An edit of a
+   * test saved with save_regression_test is linted as a bug test, like its save (assertsBug).
+   */
+  track(client2) {
+    return new Proxy(client2, {
+      get: (target, prop, receiver) => {
+        if (prop !== "executeTool") return Reflect.get(target, prop, receiver);
+        return async (tool2, args) => {
+          const edited = tool2 === "edit_test_code" && typeof args?.testId === "string" ? args.testId : void 0;
+          const result = await target.executeTool(tool2, edited && this.saved.has(edited) ? { ...args, assertsBug: true } : args);
+          if (edited) this.markEdited(edited);
+          return result;
+        };
+      }
+    });
+  }
+};
+var ANSI = /\u001b\[[0-9;]*m/g;
+var NOT_FOUND = /element\(s\) not found|resolved to 0 elements/i;
+var ACTION_TIMEOUT = /Test timeout of \d+ms exceeded|\b(locator|page)\.\w+: Timeout \d+ms exceeded/;
+var INFRA = /net::ERR_|ECONNREFUSED|ECONNRESET|ENOTFOUND|browserType\.launch|Target (page, context or browser|closed)|runner (lost|disconnected)/i;
+var CHECK_MAX = 300;
+function clip(text, max = CHECK_MAX) {
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
+function checkLine(error) {
+  const lines = error.replace(ANSI, "").split("\n").map((line) => line.trim()).filter(Boolean);
+  const check = lines.find((line) => /\bexpect\(/.test(line)) ?? lines[0] ?? "";
+  const expected = lines.find((line) => /^Expected\b/.test(line) && line !== check);
+  const received = lines.find((line) => /^Received\b/.test(line));
+  return clip([check, expected, received].filter(Boolean).join(" | "));
+}
+function failedMatcher(error) {
+  const m = /\bexpect\([^)]*\)\.(not\.)?(to\w+)\(/.exec(error.replace(ANSI, ""));
+  return m ? `${m[1] ?? ""}${m[2]}` : null;
+}
+var MATCHER = /\.\s*(not\s*\.\s*)?(to(?:Be|Have|Equal|StrictEqual|Contain|Match|Throw|Pass)\w*)\s*\(/g;
+function stripComments(code) {
+  let out = "";
+  let from = 0;
+  for (let at = 0; at < code.length; ) {
+    const c = code[at];
+    if (c === '"' || c === "'" || c === "`") {
+      at++;
+      while (at < code.length && code[at] !== c && (c === "`" || code[at] !== "\n")) at += code[at] === "\\" ? 2 : 1;
+      at++;
+    } else if (c === "/" && (code[at + 1] === "/" || code[at + 1] === "*") && code[at - 1] !== "\\") {
+      out += code.slice(from, at);
+      const end = code[at + 1] === "/" ? code.indexOf("\n", at) : code.indexOf("*/", at + 2);
+      if (end < 0) return out;
+      at = from = code[at + 1] === "/" ? end : end + 2;
+    } else {
+      at++;
+    }
+  }
+  return out + code.slice(from);
+}
+function lastMatcher(code) {
+  let last = null;
+  for (const m of stripComments(code).matchAll(MATCHER)) last = `${m[1] ? "not." : ""}${m[2]}`;
+  return last;
+}
+var PRESENCE = /* @__PURE__ */ new Set(["toBeGreaterThan", "toBeGreaterThanOrEqual", "toBeTruthy", "toBeDefined", "not.toBeNull", "not.toBeUndefined", "not.toBeFalsy"]);
+function classifyRun(run, code) {
+  const status = String(run.status ?? "");
+  const error = typeof run.error === "string" ? run.error.replace(ANSI, "") : "";
+  if (status === "PASSED") return { verdict: "passes", check: "" };
+  if (status !== "FAILED" && status !== "ERROR") return { verdict: "pending", check: "" };
+  const check = error ? checkLine(error) : "";
+  if (INFRA.test(error)) return { verdict: "infra_error", check };
+  const assertion = /\bexpect\(/.test(error) && /Expected/.test(error) && /Received/.test(error);
+  if (status === "FAILED" && assertion && !NOT_FOUND.test(error) && !ACTION_TIMEOUT.test(error)) {
+    const failed = failedMatcher(error);
+    const last = code ? lastMatcher(code) : null;
+    if (failed && last && failed !== last && PRESENCE.has(failed)) {
+      return { verdict: "test_problem", check: clip(`Failed on an earlier check (${failed}), not the last one (${last}): ${check}`) };
+    }
+    return { verdict: "reproduces", check };
+  }
+  if (!error && status === "ERROR") return { verdict: "infra_error", check };
+  return { verdict: "test_problem", check };
+}
+var VERDICT_NEXT = {
+  reproduces: "Locked in: the test fails on the bug and will pass once it is fixed.",
+  passes: "The test passed, so it does not show the bug yet; that does not mean the bug is gone. Check it again in your browser: if you still see it, the test checks the wrong thing (assert the rule you saw broken over all the rows, not one record), fix it with edit_test_code and collect again. delete_test only when you can no longer see the bug.",
+  test_problem: "The test broke before its last check (timeout, locator not found, a failed precondition, script error), so it never compared the value. Fix how it reaches and reads the value: look at the page in your browser, use the exact label or text you see there, and keep the compared value inside expect(), not in an await that can throw first. Keep the expected value as it is: it states what a correct app must show. Fix with edit_test_code, then collect_verdicts again.",
+  pending: "Still queued or running: call collect_verdicts again in a minute.",
+  infra_error: "The run could not reach the app or the browser died: call collect_verdicts with rerun for this test."
+};
+function ok(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+function fail(err) {
+  return { content: [{ type: "text", text: toolErrorText(err) }], isError: true };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function list(value) {
+  return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+var SERVER_WAIT_MAX_SECONDS = 55;
+var COLLECT_DEFAULT_SECONDS = 90;
+var COLLECT_MAX_SECONDS = 120;
+var TERMINAL = /* @__PURE__ */ new Set(["PASSED", "FAILED", "ERROR"]);
+var CONVENTION_WARNING = /console\.log\(\) milestones|__QA_HTTP__|but has no request guard/;
+var CODE_RULES = [
+  "Assert the CORRECT behaviour, so the test fails now and passes once the bug is fixed; one bug per test",
+  "Relative URLs only (page.goto('/orders')): the runner sets the base URL",
+  "Sign in inside the test with process.env.TEST_USER_EMAIL! and process.env.TEST_USER_PASSWORD!, never literal values",
+  "Locators you saw in your browser: getByRole(role, { name, exact: true }), getByLabel, getByTestId; prefer knownSelectors",
+  "End with an expect() on the value the app gets wrong, with the exact expected value",
+  "The test runs later on its own, on an account that has none of what your browser did: from sign-in, redo every step that made the state you saw (a report you generated, a check you started, a record you created or booked first) and then assert on the value the bug gets wrong, not on something that only exists after your earlier steps"
+];
+function featurePages(feature) {
+  const plans = isRecord(feature.testPlans) ? list(feature.testPlans.pages) : [];
+  const routes = Array.isArray(feature.pages) ? feature.pages.filter((p) => typeof p === "string") : [];
+  for (const plan of plans) {
+    const route = String(plan.route ?? "");
+    if (route && !routes.includes(route)) routes.push(route);
+  }
+  return routes;
+}
+async function startHere(client2, featureName) {
+  const warnings = [];
+  const [features, variables, bugs] = await Promise.all([
+    client2.executeTool("list_features"),
+    client2.executeTool("get_variables").catch((err) => {
+      warnings.push(`get_variables failed (${toolErrorText(err)}): credentials and baseUrl below are unknown, not missing. Call start_here again.`);
+      return null;
+    }),
+    client2.executeTool("list_bugs", { limit: 200 }).catch((err) => {
+      warnings.push(`list_bugs failed (${toolErrorText(err)}): openBugs below is unknown, not empty. Call start_here again before filing bugs.`);
+      return null;
+    })
+  ]);
+  if (isRecord(bugs) && bugs.appBugsTruncated === true) {
+    warnings.push("list_bugs returned only part of the open bugs: openBugs below may be missing some.");
+  }
+  const featureList = isRecord(features) ? list(features.features) : [];
+  const chosen = featureName?.trim() || (featureList.length === 1 ? String(featureList[0].name) : void 0);
+  const vars = isRecord(variables) && isRecord(variables.variables) ? variables.variables : {};
+  const names = Object.keys(vars);
+  const baseUrl = isRecord(vars.BASE_URL) && vars.BASE_URL.secret !== true && typeof vars.BASE_URL.value === "string" ? vars.BASE_URL.value : null;
+  const credentials = {
+    baseUrl,
+    loginReady: names.includes("TEST_USER_EMAIL") && names.includes("TEST_USER_PASSWORD"),
+    variables: names.map((name) => ({ name, secret: isRecord(vars[name]) && vars[name].secret === true }))
+  };
+  let feature = null;
+  if (chosen) {
+    try {
+      const detail = await client2.executeTool("get_feature", { featureName: chosen });
+      if (isRecord(detail)) feature = detail;
+    } catch (err) {
+      warnings.push(`get_feature("${chosen}") failed (${toolErrorText(err)}): the feature's pages, tests and selectors are missing below. Check the name against project.features and call start_here again.`);
+    }
+  }
+  const suite = feature ? String(feature.name) : void 0;
+  const openBugs = (isRecord(bugs) ? list(bugs.appBugs) : []).filter((bug) => !suite || String(bug.suite ?? "").toLowerCase() === suite.toLowerCase()).map((bug) => ({
+    testId: bug.id,
+    name: bug.name,
+    reviewStatus: bug.reviewStatus,
+    check: isRecord(bug.evidence) ? bug.evidence.failingCheck ?? null : null
+  }));
+  return {
+    project: {
+      features: featureList.map((f) => ({
+        name: f.name,
+        pages: f.pages,
+        criticality: f.criticality,
+        tests: f.existingTests,
+        failing: f.failingTests
+      }))
+    },
+    credentials,
+    ...warnings.length > 0 ? { warnings } : {},
+    ...feature ? {
+      feature: {
+        name: feature.name,
+        description: feature.description,
+        pages: featurePages(feature),
+        tests: list(feature.tests).map((t) => ({ id: t.id, name: t.name, status: t.status, lastRunStatus: t.lastRunStatus ?? null })),
+        knownSelectors: Array.isArray(feature.knownSelectors) ? feature.knownSelectors : [],
+        ...typeof feature.surveyNotes === "string" ? { surveyNotes: feature.surveyNotes } : {}
+      }
+    } : {},
+    openBugs,
+    codeRules: CODE_RULES,
+    next: [
+      credentials.loginReady || !variables ? null : "TEST_USER_EMAIL / TEST_USER_PASSWORD are not set: saved tests cannot sign in. Ask the developer for a test account.",
+      "Explore each page with your browser. Skip bugs already in openBugs.",
+      "For each bug: save_regression_test right away, then keep exploring. Do not wait for its run.",
+      "When you are done exploring: collect_verdicts. Fix test_problem tests with edit_test_code and collect again."
+    ].filter(Boolean)
+  };
+}
+async function waitForRun(client2, runId, deadline) {
+  let view = null;
+  for (; ; ) {
+    const left = Math.floor((deadline - Date.now()) / 1e3);
+    view = left >= 1 ? await client2.executeTool("wait_for_run", { runId, timeoutSeconds: Math.min(left, SERVER_WAIT_MAX_SECONDS) }) : await client2.executeTool("get_test_run", { runId });
+    if (!isRecord(view)) return {};
+    if (TERMINAL.has(String(view.status)) || view.timedOut !== true || left < 1) return view;
+  }
+}
+async function collectVerdicts(client2, session, args) {
+  const seconds = Math.min(Math.max(args.timeoutSeconds ?? COLLECT_DEFAULT_SECONDS, 0), COLLECT_MAX_SECONDS);
+  const deadline = Date.now() + seconds * 1e3;
+  const ids = args.testIds?.length ? args.testIds : [...session.saved.keys()];
+  if (ids.length === 0) {
+    return { summary: {}, verdicts: [], next: "Nothing saved in this session yet: save_regression_test first, or pass testIds." };
+  }
+  const rerun = new Set(args.rerun ?? []);
+  const targets = [];
+  for (const testId of ids) {
+    const saved = session.saved.get(testId);
+    try {
+      if (rerun.has(testId) || saved?.edited) {
+        const queued = await client2.executeTool("run_test", { testId });
+        const runId = isRecord(queued) && typeof queued.runId === "string" ? queued.runId : void 0;
+        if (saved) {
+          saved.edited = false;
+          saved.runId = runId;
+        }
+        targets.push({ testId, runId });
+      } else if (saved?.runId) {
+        targets.push({ testId, runId: saved.runId });
+      } else {
+        const latest = await client2.executeTool("get_test_run", { testId });
+        targets.push({ testId, runId: isRecord(latest) && typeof latest.id === "string" ? latest.id : void 0 });
+      }
+    } catch (err) {
+      targets.push({ testId, error: toolErrorText(err) });
+    }
+  }
+  const verdicts = [];
+  const summary = { reproduces: 0, passes: 0, test_problem: 0, pending: 0, infra_error: 0 };
+  for (const { testId, runId, error } of targets) {
+    const saved = session.saved.get(testId);
+    if (!runId) {
+      summary.pending++;
+      verdicts.push({ testId, name: saved?.name, verdict: "pending", check: error ?? "no run yet", next: VERDICT_NEXT.pending });
+      continue;
+    }
+    let view;
+    try {
+      view = await waitForRun(client2, runId, deadline);
+    } catch (err) {
+      summary.infra_error++;
+      verdicts.push({ testId, name: saved?.name, runId, verdict: "infra_error", check: toolErrorText(err), next: VERDICT_NEXT.infra_error });
+      continue;
+    }
+    let test = {};
+    if (TERMINAL.has(String(view.status))) {
+      test = await client2.executeTool("get_test_code", { testId }).then((t) => isRecord(t) ? t : {}, () => ({}));
+    }
+    const { verdict, check } = classifyRun(view, typeof test.playwrightCode === "string" ? test.playwrightCode : void 0);
+    summary[verdict]++;
+    const tags = Array.isArray(test.tags) ? test.tags : [];
+    verdicts.push({
+      testId,
+      name: saved?.name ?? view.testName ?? test.name,
+      ...saved?.bug ? { bug: saved.bug } : {},
+      runId,
+      verdict,
+      ...check ? { check } : {},
+      ...typeof test.status === "string" ? { testStatus: test.status } : {},
+      ...tags.includes("@bug-found") ? { triagedAsAppBug: true } : {},
+      next: VERDICT_NEXT[verdict]
+    });
+  }
+  const next = summary.pending > 0 ? "Some runs are still going: call collect_verdicts again." : summary.test_problem + summary.passes + summary.infra_error > 0 ? "Keep the reproduces tests as they are. Fix the others (see each next), then collect_verdicts again." : "Every saved test reproduces its bug.";
+  return { summary, verdicts, next };
+}
+function registerAgentTools(server2, client2, session) {
+  server2.tool(
+    "start_here",
+    "START HERE when asked to test, find bugs in or lock in a feature. One read with everything to begin: the project's features, the feature's pages, its existing tests and knownSelectors (verified locators), whether test credentials are set, open bugs, and the rules for saved test code.",
+    { feature: z.string().optional().describe("The feature to work on (case-insensitive). Leave out to list the features.") },
+    { readOnlyHint: true },
+    async (args) => {
+      try {
+        return ok(await startHere(client2, args.feature));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  server2.tool(
+    "save_regression_test",
+    "Save a bug you found as a Playwright test that asserts the CORRECT behaviour (it fails now and passes once fixed). Returns at once: the test runs in the cloud while you keep exploring. Call collect_verdicts at the end to learn which tests reproduce their bug. It runs later on an account with none of your browser's changes, so it redoes every step from sign-in. Same code rules as create_test (see start_here codeRules).",
+    {
+      name: z.string().describe('What should happen, e.g. "Orders - status filter shows only Paid orders"'),
+      feature: z.string().describe("The feature name exactly as start_here lists it (becomes the suite)"),
+      playwrightCode: z.string().describe("Full Playwright test file"),
+      bug: z.string().optional().describe("One line: what the app does wrong"),
+      tags: z.array(z.string()).optional().describe("Extra tags; @regression is added")
+    },
+    async (args) => {
+      try {
+        const extra = args.tags ?? [];
+        const tags = extra.includes("@auth") ? extra : [.../* @__PURE__ */ new Set([...extra, "@regression"])];
+        const created = await client2.executeTool("create_test", {
+          name: args.name,
+          playwrightCode: args.playwrightCode,
+          suite: args.feature,
+          tags,
+          assertsBug: true
+        });
+        if (!isRecord(created) || typeof created.id !== "string") return ok(created);
+        const runId = isRecord(created.verification) && typeof created.verification.runId === "string" ? created.verification.runId : void 0;
+        session.remember({ testId: created.id, name: args.name, bug: args.bug, runId, edited: false });
+        const warnings = (Array.isArray(created.warnings) ? created.warnings : []).filter((w) => typeof w === "string" && !CONVENTION_WARNING.test(w));
+        return ok({
+          testId: created.id,
+          name: created.name ?? args.name,
+          status: created.status,
+          ...runId ? { runId } : {},
+          ...warnings.length ? { warnings } : {},
+          next: warnings.length ? "Saved; its run is queued. Fix the warnings with edit_test_code, then keep exploring. collect_verdicts at the end." : "Saved; its run is queued. Keep exploring. collect_verdicts at the end."
+        });
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+  server2.tool(
+    "collect_verdicts",
+    "After exploring: wait for the runs of the tests you saved this session (or testIds) and say for each whether it reproduces its bug (fails on its check), passes (does not show the bug), has a test problem (broke before its check), is still pending, or hit an infrastructure error. Tests changed with edit_test_code since their run are run again first. Waits up to timeoutSeconds in total. A test that fails on its last check is the goal: it reproduces the bug, so keep it as it is. A test that passes is the one to question.",
+    {
+      testIds: z.array(z.string()).optional().describe("Tests to check (default: every test saved this session)"),
+      rerun: z.array(z.string()).optional().describe("Tests to run again before checking"),
+      timeoutSeconds: z.number().optional().describe(`Total wait (default ${COLLECT_DEFAULT_SECONDS}, max ${COLLECT_MAX_SECONDS})`)
+    },
+    async (args) => {
+      try {
+        return ok(await collectVerdicts(client2, session, args));
+      } catch (err) {
+        return fail(err);
+      }
+    }
+  );
+}
+var AGENT_INSTRUCTIONS = `Validate.QA saves the bugs you find as Playwright tests that run in its cloud and keep running.
+
+Finding and locking in bugs in a feature:
+1. start_here({ feature }): its pages, existing tests, knownSelectors, credentials, and open bugs.
+2. Explore the pages with your browser tools.
+3. Each bug: save_regression_test with code that asserts the CORRECT behaviour. It runs later on an account with none of your browser's changes, so from sign-in it redoes every click that made the state you saw. It returns at once; keep exploring.
+4. At the end: collect_verdicts. reproduces (the test fails on its check) = the bug is locked in: keep that test as it is. passes = the test misses the bug: check again in your browser and fix its assertion. test_problem = it broke before its check: fix the steps. Fix with edit_test_code, then collect_verdicts again.
+Rate limit: 50 calls a minute.`;
+
+// src/tools/index.ts
 function tool(server2, client2, name, description, schema, annotations) {
   const handler = async (args) => {
     try {
@@ -227,7 +1024,7 @@ function tool(server2, client2, name, description, schema, annotations) {
       };
     } catch (err) {
       return {
-        content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+        content: [{ type: "text", text: toolErrorText(err) }],
         isError: true
       };
     }
@@ -238,19 +1035,66 @@ function tool(server2, client2, name, description, schema, annotations) {
     server2.tool(name, description, schema, handler);
   }
 }
-function registerAllTools(server2, client2) {
+var SERVER_WAIT_MAX_SECONDS2 = 55;
+var WAIT_DEFAULT_SECONDS = 50;
+var WAIT_MAX_SECONDS = 120;
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function waitSecondsFrom(raw, fallback) {
+  const n = typeof raw === "number" ? raw : Number.NaN;
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, 0), WAIT_MAX_SECONDS);
+}
+async function executeWithWait(client2, name, args, waitKey, totalSeconds, kind) {
+  const deadline = Date.now() + totalSeconds * 1e3;
+  const first = Math.min(totalSeconds, SERVER_WAIT_MAX_SECONDS2);
+  let result = await client2.executeTool(name, { ...args, [waitKey]: first });
+  let id = args[kind.idKey];
+  for (; ; ) {
+    if (!isRecord2(result) || result.timedOut !== true) return result;
+    id = result[kind.idKey] ?? id;
+    const left = Math.floor((deadline - Date.now()) / 1e3);
+    if (typeof id !== "string" || left < 1) return result;
+    result = await client2.executeTool(kind.tool, { [kind.idKey]: id, timeoutSeconds: Math.min(left, SERVER_WAIT_MAX_SECONDS2) });
+  }
+}
+function waitTool(server2, client2, name, description, schema, waitKey, defaultSeconds, kind, annotations) {
+  const handler = async (args) => {
+    try {
+      const seconds = waitSecondsFrom(args[waitKey], defaultSeconds);
+      const result = seconds > 0 ? await executeWithWait(client2, name, args, waitKey, seconds, kind) : await client2.executeTool(name, args);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: toolErrorText(err) }],
+        isError: true
+      };
+    }
+  };
+  if (annotations) {
+    server2.tool(name, description, schema, annotations, handler);
+  } else {
+    server2.tool(name, description, schema, handler);
+  }
+}
+function registerAllTools(server2, client2, toolset = "full") {
+  const session = new AgentSession();
+  if (toolset === "agent") server2 = limitTools(server2, AGENT_TOOL_NAMES);
+  client2 = session.track(client2);
+  registerAgentTools(server2, client2, session);
   tool(
     server2,
     client2,
     "list_tests",
     "List tests in the current project. Returns test name, status, suite, tags, confidence, and the last run result. Paginated - use limit/offset to page through all tests.",
     {
-      status: z.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).optional().describe("Filter by test lifecycle status"),
-      suite: z.string().optional().describe("Filter by suite name"),
-      search: z.string().optional().describe("Search test names (case-insensitive substring match)"),
-      tag: z.string().optional().describe("Filter by tag (e.g. @regression, @smoke, @auth)"),
-      limit: z.number().optional().describe("Max results to return (default: 50, max: 200)"),
-      offset: z.number().optional().describe("Number of results to skip for pagination (default: 0)")
+      status: z2.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).optional().describe("Filter by test lifecycle status"),
+      suite: z2.string().optional().describe("Filter by suite name"),
+      search: z2.string().optional().describe("Search test names (case-insensitive substring match)"),
+      tag: z2.string().optional().describe("Filter by tag (e.g. @regression, @smoke, @auth)"),
+      limit: z2.number().optional().describe("Max results to return (default: 50, max: 200)"),
+      offset: z2.number().optional().describe("Number of results to skip for pagination (default: 0)")
     },
     { readOnlyHint: true }
   );
@@ -259,22 +1103,31 @@ function registerAllTools(server2, client2) {
     client2,
     "get_test",
     "Get details of a specific test: name, status, tags, steps, session, and the 5 most recent run results. Code is truncated to 200 lines - use get_test_code for the full Playwright code.",
-    { testId: z.string().describe("The test case ID") },
+    { testId: z2.string().describe("The test case ID") },
     { readOnlyHint: true }
   );
-  tool(
+  waitTool(
     server2,
     client2,
     "run_test",
-    "Queue a test for execution. Creates a PENDING test run that will be picked up by an online runner. Returns the run ID.",
-    { testId: z.string().describe("The test case ID to run") }
+    "Queue a test for execution. Creates a PENDING test run that will be picked up by an online runner. Returns the run ID; with waitSeconds, the finished run (as wait_for_run). For a mobile (Appium) test, pass platform to run it on the OTHER platform than it was authored on - if some steps lack a native locator for that platform, a one-time locator-discovery pass runs first (supply appId once for the target-platform build), then the test runs automatically.",
+    {
+      testId: z2.string().describe("The test case ID to run"),
+      platform: z2.enum(["IOS", "ANDROID"]).optional().describe("Mobile only: run this test on the given platform (cross-platform run). Omit to run on the authoring platform."),
+      appId: z2.string().optional().describe("Mobile cross-platform only: the target-platform app id (bundleId/appPackage). Only needed the first time this project runs on the other platform."),
+      deeplink: z2.string().optional().describe("Mobile cross-platform only: target-platform deep link URL. Required when the authored test uses a custom app scheme that may differ between iOS and Android (the server answers need_deeplink); http/https App Links are reused automatically."),
+      waitSeconds: z2.number().min(0).max(WAIT_MAX_SECONDS).optional().describe(`Optional. Wait up to this many seconds (max ${WAIT_MAX_SECONDS}) for the run to finish and return its final result, like wait_for_run (timedOut: true if still going). 0 or omitted: return at once with the run ID.`)
+    },
+    "waitSeconds",
+    0,
+    { tool: "wait_for_run", idKey: "runId" }
   );
   tool(
     server2,
     client2,
     "delete_test",
     "Permanently delete a test case and all its run history. Cannot be undone.",
-    { testId: z.string().describe("The test case ID to delete") },
+    { testId: z2.string().describe("The test case ID to delete") },
     { destructiveHint: true }
   );
   tool(
@@ -282,38 +1135,93 @@ function registerAllTools(server2, client2) {
     client2,
     "heal_test",
     "Queue an AI healing run for a failing test. The AI agent replays the test in a real browser, analyzes the failure, and either fixes the Playwright code OR detects an application bug (quarantines the test with @bug-found if the app itself is broken, not the test).",
-    { testId: z.string().describe("The failing test case ID") }
+    { testId: z2.string().describe("The failing test case ID") }
   );
   tool(
     server2,
     client2,
     "edit_test_code",
-    "Update the Playwright code, name, or tags of an existing test case. Read project://test-conventions for patterns and pitfalls. Code is validated - fix any warnings returned.",
+    "Update an existing test case. WEB (Playwright) tests: provide the full replacement playwrightCode (read project://test-conventions for patterns; code is validated - fix any warnings returned). MOBILE (Appium) tests: provide the FULL replacement steps array (playwrightCode is rejected - mobile tests execute structured steps, not code). Read the current form first with get_test_code.",
     {
-      testId: z.string().describe("The test case ID to edit"),
-      playwrightCode: z.string().optional().describe("New Playwright test code (full file replacement)"),
-      name: z.string().optional().describe("New test name"),
-      tags: z.array(z.string()).optional().describe('New tags array (e.g. ["@regression", "@smoke"])')
+      testId: z2.string().describe("The test case ID to edit"),
+      playwrightCode: z2.string().optional().describe("Web tests only: new Playwright test code (full file replacement)"),
+      steps: z2.array(z2.record(z2.string(), z2.unknown())).optional().describe("Mobile (Appium) tests only: FULL replacement structured step array (same shape as create_test steps). Include every step, not just the changed ones."),
+      name: z2.string().optional().describe("New test name"),
+      description: z2.string().optional().describe("New short description of what the test verifies"),
+      tags: z2.array(z2.string()).optional().describe('New tags array (e.g. ["@regression", "@smoke"])'),
+      status: z2.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).optional().describe("New test status. Re-activating a bug-found test (QUARANTINED\u2192ACTIVE) also queues a verification run and returns its testRunId.")
     }
   );
   tool(
     server2,
     client2,
     "update_test_status",
-    "Change the lifecycle status of one or more tests (e.g. promote DRAFT\u2192ACTIVE, disable a flaky test).",
+    "Change the lifecycle status of one or more tests (e.g. promote DRAFT\u2192ACTIVE, disable a flaky test). Re-activating exactly ONE bug-found test (QUARANTINED\u2192ACTIVE) also queues a verification run and returns its testRunId; with several ids no run is queued: any bug-found tests among them come back as unverifiedTestIds, to check with batch_run_tests.",
     {
-      testIds: z.array(z.string()).describe("Test IDs to update"),
-      status: z.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).describe("New status to set")
+      testIds: z2.array(z2.string()).describe("Test IDs to update"),
+      status: z2.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).describe("New status to set")
     }
   );
   tool(
     server2,
     client2,
     "get_test_run",
-    "Get the status and result of a specific test run, including error details if it failed. Can look up by runId or get the latest run for a testId.",
+    "Get the status and result of a specific test run once (to wait for it to finish, use wait_for_run, not a loop of this). Look up by runId, or the latest run for a testId. A FAILED or ERROR run also carries its failure evidence: error (up to 4 KB), consoleLog (the last 200 lines, at most 20 KB), failedSteps, and for a mobile run domSnapshot (the page source at the failure). Screenshots: get_test_screenshots. No Playwright trace is recorded.",
+    {
+      runId: z2.string().optional().describe("The test run ID"),
+      testId: z2.string().optional().describe("Get the most recent run for this test case ID")
+    },
+    { readOnlyHint: true }
+  );
+  waitTool(
+    server2,
+    client2,
+    "wait_for_run",
+    `Wait until a test run (run_test, heal_test, a verification run) is PASSED, FAILED or ERROR, then return it in the get_test_run shape, failure evidence included. Returns after at most timeoutSeconds (default ${WAIT_DEFAULT_SECONDS}, max ${WAIT_MAX_SECONDS}) with timedOut: true and the current status if it is still pending or running; call it again to keep waiting. Use this instead of polling get_test_run.`,
+    {
+      runId: z2.string().describe("The test run ID to wait for"),
+      timeoutSeconds: z2.number().min(0).max(WAIT_MAX_SECONDS).optional().describe(`How long to wait, in seconds (default ${WAIT_DEFAULT_SECONDS}, max ${WAIT_MAX_SECONDS})`)
+    },
+    "timeoutSeconds",
+    WAIT_DEFAULT_SECONDS,
+    { tool: "wait_for_run", idKey: "runId" },
+    { readOnlyHint: true }
+  );
+  waitTool(
+    server2,
+    client2,
+    "wait_for_batch",
+    `Wait until a batch from batch_run_tests is COMPLETED, then return its counts (total, completed, passed, failed, errored) and, when tests failed, up to 20 failures with their runId and error. Returns after at most timeoutSeconds (default ${WAIT_DEFAULT_SECONDS}, max ${WAIT_MAX_SECONDS}) with timedOut: true and the current counts if it is still running; call it again to keep waiting. Use get_test_run on a failure's runId for its console log.`,
+    {
+      batchId: z2.string().describe("The batch ID returned by batch_run_tests"),
+      timeoutSeconds: z2.number().min(0).max(WAIT_MAX_SECONDS).optional().describe(`How long to wait, in seconds (default ${WAIT_DEFAULT_SECONDS}, max ${WAIT_MAX_SECONDS})`)
+    },
+    "timeoutSeconds",
+    WAIT_DEFAULT_SECONDS,
+    { tool: "wait_for_batch", idKey: "batchId" },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "run_discovery",
+    "Start AI discovery for this project. For web, discovery uses the configured base URL. For mobile, pass platform and appId to explore a native app on a connected runner/device. Use survey to map features, deep with featureName to generate tests for one feature, or full for broad generation. On a project with no platform yet, a workspace owner must choose Mobile first; tokens can't make that first choice.",
+    {
+      mode: z2.enum(["survey", "deep", "full"]).optional().describe("Discovery mode. survey maps features/screens and generates no tests; deep generates tests for one feature; full explores and generates broadly."),
+      featureName: z2.string().optional().describe("Required for deep mode: the feature name to generate tests for."),
+      focusAreas: z2.array(z2.string()).optional().describe("Optional routes, screens, or areas to focus discovery on."),
+      platform: z2.enum(["IOS", "ANDROID"]).optional().describe("Mobile only: target platform. Requires appId."),
+      appId: z2.string().optional().describe("Mobile only: bundle id/package id to explore. Requires platform."),
+      resetPolicy: z2.enum(["AUTO", "CLEAR_APP_DATA", "PRESERVE_APP_DATA"]).optional().describe("Mobile only: app-state policy for discovery/replay. AUTO uses default safe reset behavior.")
+    }
+  );
+  tool(
+    server2,
+    client2,
+    "get_discovery_status",
+    "Check progress for a discovery run. Omit discoveryRunId to get the latest discovery run for this project.",
     {
-      runId: z.string().optional().describe("The test run ID"),
-      testId: z.string().optional().describe("Get the most recent run for this test case ID")
+      discoveryRunId: z2.string().optional().describe("Specific discovery run ID. Omit for latest.")
     },
     { readOnlyHint: true }
   );
@@ -321,8 +1229,8 @@ function registerAllTools(server2, client2) {
     "get_test_screenshots",
     "Get screenshots from a specific test run as images the AI can actually see. Use this to visually inspect what happened during a failed or passing run.",
     {
-      runId: z.string().describe("The test run ID to fetch screenshots from"),
-      limit: z.number().optional().describe("Max screenshots to return (default: 5, max: 10)")
+      runId: z2.string().describe("The test run ID to fetch screenshots from"),
+      limit: z2.number().optional().describe("Max screenshots to return (default: 5, max: 10)")
     },
     { readOnlyHint: true },
     async (args) => {
@@ -348,7 +1256,7 @@ function registerAllTools(server2, client2) {
         return { content };
       } catch (err) {
         return {
-          content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }],
+          content: [{ type: "text", text: toolErrorText(err) }],
           isError: true
         };
       }
@@ -360,19 +1268,23 @@ function registerAllTools(server2, client2) {
     "cancel_test_run",
     "Cancel a pending or running test run. Can cancel by run ID or cancel the latest running batch.",
     {
-      runId: z.string().optional().describe("The specific test run ID to cancel"),
-      cancelBatch: z.boolean().optional().describe("If true, cancel the latest batch run instead")
+      runId: z2.string().optional().describe("The specific test run ID to cancel"),
+      cancelBatch: z2.boolean().optional().describe("If true, cancel the latest batch run instead")
     }
   );
-  tool(
+  waitTool(
     server2,
     client2,
     "batch_run_tests",
-    "Run multiple tests from the database individually. Filter by test IDs or suite name; omit both to run all ACTIVE tests. Each test executes in its own browser.",
+    "Run multiple tests from the database individually. Filter by test IDs or suite name; omit both to run all ACTIVE tests. Each test executes in its own browser. Returns the batchId; follow it with wait_for_batch, or pass waitSeconds.",
     {
-      testIds: z.array(z.string()).optional().describe("Specific test IDs to run"),
-      suite: z.string().optional().describe("Run all active tests in this suite")
-    }
+      testIds: z2.array(z2.string()).optional().describe("Specific test IDs to run"),
+      suite: z2.string().optional().describe("Run all active tests in this suite"),
+      waitSeconds: z2.number().min(0).max(WAIT_MAX_SECONDS).optional().describe(`Optional. Wait up to this many seconds (max ${WAIT_MAX_SECONDS}) for the batch to complete and return the wait_for_batch result (timedOut: true if still running). 0 or omitted: return at once with the batchId.`)
+    },
+    "waitSeconds",
+    0,
+    { tool: "wait_for_batch", idKey: "batchId" }
   );
   tool(
     server2,
@@ -382,13 +1294,23 @@ function registerAllTools(server2, client2) {
     {},
     { readOnlyHint: true }
   );
+  tool(
+    server2,
+    client2,
+    "generate_tests_for_feature",
+    "Start test generation for an existing feature by id or name. For mobile, run_discovery with mode=deep, featureName, platform, and appId gives explicit device/platform control.",
+    {
+      featureId: z2.string().optional().describe("Feature ID. Either featureId or featureName is required."),
+      featureName: z2.string().optional().describe("Feature name. Either featureId or featureName is required.")
+    }
+  );
   tool(
     server2,
     client2,
     "list_api_endpoints",
     "List captured API endpoints for the current project. Optionally scope to a specific feature name.",
     {
-      featureName: z.string().optional().describe("Optional feature name to scope the endpoint list")
+      featureName: z2.string().optional().describe("Optional feature name to scope the endpoint list")
     },
     { readOnlyHint: true }
   );
@@ -416,6 +1338,14 @@ function registerAllTools(server2, client2) {
     {},
     { readOnlyHint: true }
   );
+  tool(
+    server2,
+    client2,
+    "get_regression_stats",
+    "Get test counts by lifecycle status (active, quarantined, draft, disabled, total; API specs count their inner tests) and the 7-day pass rate, with rate-limit, config-issue and cancelled runs left out. The same numbers as the dashboard's regression stats.",
+    {},
+    { readOnlyHint: true }
+  );
   tool(
     server2,
     client2,
@@ -430,13 +1360,13 @@ function registerAllTools(server2, client2) {
     "create_schedule",
     "Create a new recurring test schedule. Runs all matching tests from the database on the configured interval.",
     {
-      name: z.string().describe('Name for the schedule (e.g. "Nightly smoke tests")'),
-      mode: z.enum(["batch"]).describe("Run mode: batch (runs project tests from the database)"),
-      intervalMinutes: z.union([z.literal(60), z.literal(360), z.literal(720), z.literal(1440), z.literal(2880), z.literal(10080)]).describe("Interval in minutes: 60 (hourly), 360 (6h), 720 (12h), 1440 (daily), 2880 (2 days), 10080 (weekly)"),
-      tags: z.array(z.string()).optional().describe('Tags to filter which tests run (e.g. ["@smoke"]). Omit to run all ACTIVE tests.'),
-      autoHeal: z.boolean().optional().describe("Automatically heal failing tests after each run"),
-      enabled: z.boolean().optional().describe("Whether the schedule is active (default: true)"),
-      runImmediately: z.boolean().optional().describe("Whether to trigger the first run immediately (default: true)")
+      name: z2.string().describe('Name for the schedule (e.g. "Nightly smoke tests")'),
+      mode: z2.enum(["batch"]).describe("Run mode: batch (runs project tests from the database)"),
+      intervalMinutes: z2.union([z2.literal(60), z2.literal(360), z2.literal(720), z2.literal(1440), z2.literal(2880), z2.literal(10080)]).describe("Interval in minutes: 60 (hourly), 360 (6h), 720 (12h), 1440 (daily), 2880 (2 days), 10080 (weekly)"),
+      tags: z2.array(z2.string()).optional().describe('Tags to filter which tests run (e.g. ["@smoke"]). Omit to run all ACTIVE tests.'),
+      autoHeal: z2.boolean().optional().describe("Heal this schedule's failed runs (default false). Takes effect only while the project's auto-heal (toggle_auto_heal) is on: a run is healed only when both are on."),
+      enabled: z2.boolean().optional().describe("Whether the schedule is active (default: true)"),
+      runImmediately: z2.boolean().optional().describe("Whether to trigger the first run immediately (default: true)")
     }
   );
   tool(
@@ -445,13 +1375,13 @@ function registerAllTools(server2, client2) {
     "update_schedule",
     "Update an existing test schedule.",
     {
-      scheduleId: z.string().describe("The schedule ID to update"),
-      name: z.string().optional().describe("New name for the schedule"),
-      intervalMinutes: z.union([z.literal(60), z.literal(360), z.literal(720), z.literal(1440), z.literal(2880), z.literal(10080)]).optional().describe("New interval in minutes"),
-      suite: z.string().optional().describe("New suite name to filter tests"),
-      tags: z.array(z.string()).optional().describe("New tag filter"),
-      autoHeal: z.boolean().optional().describe("Toggle auto-heal"),
-      enabled: z.boolean().optional().describe("Enable or disable the schedule")
+      scheduleId: z2.string().describe("The schedule ID to update"),
+      name: z2.string().optional().describe("New name for the schedule"),
+      intervalMinutes: z2.union([z2.literal(60), z2.literal(360), z2.literal(720), z2.literal(1440), z2.literal(2880), z2.literal(10080)]).optional().describe("New interval in minutes"),
+      suite: z2.string().optional().describe("New suite name to filter tests"),
+      tags: z2.array(z2.string()).optional().describe("New tag filter"),
+      autoHeal: z2.boolean().optional().describe("Heal this schedule's failed runs. Takes effect only while the project's auto-heal (toggle_auto_heal) is on."),
+      enabled: z2.boolean().optional().describe("Enable or disable the schedule")
     }
   );
   tool(
@@ -459,7 +1389,7 @@ function registerAllTools(server2, client2) {
     client2,
     "delete_schedule",
     "Delete (remove) a test schedule permanently.",
-    { scheduleId: z.string().describe("The schedule ID to delete") },
+    { scheduleId: z2.string().describe("The schedule ID to delete") },
     { destructiveHint: true }
   );
   tool(
@@ -467,7 +1397,7 @@ function registerAllTools(server2, client2) {
     client2,
     "run_schedule_now",
     "Trigger a scheduled run immediately instead of waiting for the next scheduled time.",
-    { scheduleId: z.string().describe("The schedule ID to trigger") }
+    { scheduleId: z2.string().describe("The schedule ID to trigger") }
   );
   tool(
     server2,
@@ -483,21 +1413,22 @@ function registerAllTools(server2, client2) {
     "set_variable",
     "Set or update a test variable (environment variable) for the project. Used to configure base URLs, credentials, etc.",
     {
-      key: z.string().describe("Variable name (e.g. BASE_URL, TEST_USER_EMAIL, API_KEY)"),
-      value: z.string().describe("Variable value. Set value to empty string to remove a variable."),
-      secret: z.boolean().optional().describe("Whether this variable is a secret (will be redacted in UI)")
+      key: z2.string().describe("Variable name (e.g. BASE_URL, TEST_USER_EMAIL, API_KEY)"),
+      value: z2.string().describe("Variable value. Set value to empty string to remove a variable."),
+      secret: z2.boolean().optional().describe("Whether this variable is a secret (will be redacted in UI)")
     }
   );
   tool(
     server2,
     client2,
     "create_test",
-    "Create a new test case with Playwright code. Read project://test-conventions for templates and pitfalls BEFORE writing code. The test starts as DRAFT - auto-runs and auto-promotes to ACTIVE on pass. IMPORTANT: (1) Set suite to the EXACT feature name. (2) After creating all tests for a feature, you MUST call add_api_endpoints.",
+    "Create a new test case. WEB projects: provide playwrightCode (read project://test-conventions for templates BEFORE writing code; on a production BASE_URL use its read-only guard template). The response may carry warnings (weak selectors, hardcoded hosts in URL assertions, vacuous checks, a missing read-only guard) - they never block, fix them with edit_test_code. MOBILE (Appium) projects: provide steps - a structured step array is the ONLY executable form for mobile (code is never executed). The test starts as DRAFT - auto-runs and auto-promotes to ACTIVE on pass. IMPORTANT: (1) Set suite to the EXACT feature name. (2) After creating all tests for a web feature, you MUST call add_api_endpoints.",
     {
-      name: z.string().describe('Test name (e.g. "Login - Happy Path")'),
-      playwrightCode: z.string().describe("Full Playwright test code"),
-      suite: z.string().optional().describe('MUST match an existing feature name exactly to link the test to that feature (e.g. "Authentication", not "Auth Tests")'),
-      tags: z.array(z.string()).optional().describe('Tags (e.g. ["@smoke", "@auth"])')
+      name: z2.string().describe('Test name (e.g. "Login - Happy Path")'),
+      playwrightCode: z2.string().optional().describe("Web projects: full Playwright test code (required). Mobile projects: optional WebdriverIO export for humans - never executed."),
+      steps: z2.array(z2.record(z2.string(), z2.unknown())).optional().describe('Mobile (Appium) projects ONLY - required. Ordered steps: { action: tap|type|clear|swipe|scroll|back|home|waitForElement|assertVisible|assertText, description, target?: { primary, fallbacks?, screenName? }, value? }. target.primary: "css=#domId" for WebView-rendered (hybrid) controls, resource-id/accessibility-id/text= only for genuinely native UI. type/assertText require value ({{TEST_VAR}} placeholders supported). Do not author OS permission-dialog taps. End with an assert step. Call get_feature first for mapped screens + known selectors.'),
+      suite: z2.string().optional().describe('MUST match an existing feature name exactly to link the test to that feature (e.g. "Authentication", not "Auth Tests")'),
+      tags: z2.array(z2.string()).optional().describe('Tags (e.g. ["@smoke", "@auth"])')
     }
   );
   tool(
@@ -505,19 +1436,30 @@ function registerAllTools(server2, client2) {
     client2,
     "get_feature",
     "Get detailed info about a feature including its pages, test plans, existing tests with lastRunStatus, and AI insights.",
-    { featureName: z.string().describe("The feature name (case-insensitive match)") },
+    { featureName: z2.string().describe("The feature name (case-insensitive match)") },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "get_spec_coverage",
+    `Map spec items to the existing tests of a feature (heuristic: test names, tags and the copy in their code) and list the items no test covers yet. Pass the spec you were given as one item per line item, scoped by page ("Sign up: malformed email shows an error"); without specItems it uses the feature's stored test plans. Call it before you stop writing tests for a feature, then cover every uncovered item.`,
+    {
+      featureName: z2.string().describe("The feature name (case-insensitive) - its suite holds the tests"),
+      specItems: z2.array(z2.string()).optional().describe("Spec items, one per behaviour and page (max 200)")
+    },
     { readOnlyHint: true }
   );
   tool(
     server2,
     client2,
     "create_feature",
-    "Create a new feature with page routes. Read the developer's route files to provide accurate page URLs. Pages are used for coverage tracking and site map.",
+    "Create a new feature with page routes. Read the developer's route files to provide accurate page URLs. Pages are used for coverage tracking and site map. Idempotent, not an upsert: if an active feature with this name already exists it is returned unchanged with existing: true (use update_feature with its id to change it). Fails only when the name belongs to an archived feature (restore it with restore_feature, or pick another name).",
     {
-      name: z.string().describe('Feature name (e.g. "Checkout Flow")'),
-      description: z.string().optional().describe("What the feature does and what to test"),
-      pages: z.array(z.string()).describe('Page routes this feature covers (e.g. ["/checkout", "/checkout/payment"]). Required for test generation.'),
-      criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level (default: medium)")
+      name: z2.string().describe('Feature name (e.g. "Checkout Flow")'),
+      description: z2.string().optional().describe("What the feature does and what to test"),
+      pages: z2.array(z2.string()).describe('Page routes this feature covers (e.g. ["/checkout", "/checkout/payment"]). Required for test generation.'),
+      criticality: z2.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level (default: medium)")
     }
   );
   tool(
@@ -525,22 +1467,22 @@ function registerAllTools(server2, client2) {
     client2,
     "get_test_code",
     "Get the full (untruncated) Playwright test code for a test case. Use this when you need to read, analyze, or prepare edits for the complete test code.",
-    { testId: z.string().describe("The test case ID") },
+    { testId: z2.string().describe("The test case ID") },
     { readOnlyHint: true }
   );
   tool(
     server2,
     client2,
     "set_runner_preference",
-    "Switch between cloud and local runner for test execution.",
-    { preference: z.enum(["cloud", "local"]).describe("Runner type: cloud (shared infrastructure) or local (runs on your machine)") }
+    "Switch between cloud and local runner for test execution. Copilot (browser session) only; access tokens and MCP connectors get 403 \u2014 change the runner in Project Settings.",
+    { preference: z2.enum(["cloud", "local"]).describe("Runner type: cloud (shared infrastructure) or local (runs on your machine)") }
   );
   tool(
     server2,
     client2,
     "toggle_auto_heal",
-    "Enable or disable automatic AI healing when tests fail in batch or suite runs.",
-    { enabled: z.boolean().describe("true to enable auto-heal, false to disable") }
+    "Enable or disable automatic AI healing when tests fail: the verification run after create_test, batch and suite runs. When off, no heal is queued automatically; heal_test still works.",
+    { enabled: z2.boolean().describe("true to enable auto-heal, false to disable") }
   );
   tool(
     server2,
@@ -556,9 +1498,9 @@ function registerAllTools(server2, client2) {
     "create_test_data",
     "Create a new test data set with key-value pairs. Max 200 entries per set.",
     {
-      name: z.string().describe("Name of the test data set (max 100 chars)"),
-      description: z.string().optional().describe("Optional description (max 1000 chars)"),
-      data: z.record(z.string()).describe('Key-value pairs (e.g. {"email": "test@example.com", "password": "secret"})')
+      name: z2.string().describe("Name of the test data set (max 100 chars)"),
+      description: z2.string().optional().describe("Optional description (max 1000 chars)"),
+      data: z2.record(z2.string(), z2.string()).describe('Key-value pairs (e.g. {"email": "test@example.com", "password": "secret"})')
     }
   );
   tool(
@@ -566,7 +1508,7 @@ function registerAllTools(server2, client2) {
     client2,
     "delete_test_data",
     "Delete a test data set by ID.",
-    { dataSetId: z.string().describe("The test data set ID to delete") },
+    { dataSetId: z2.string().describe("The test data set ID to delete") },
     { destructiveHint: true }
   );
   tool(
@@ -575,21 +1517,28 @@ function registerAllTools(server2, client2) {
     "update_feature",
     "Update a feature's name, description, pages, or criticality.",
     {
-      featureId: z.string().describe("The feature ID to update"),
-      name: z.string().optional().describe("New feature name"),
-      description: z.string().optional().describe("New description"),
-      pages: z.array(z.string()).optional().describe("Updated page routes"),
-      criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level")
+      featureId: z2.string().describe("The feature ID to update"),
+      name: z2.string().optional().describe("New feature name"),
+      description: z2.string().optional().describe("New description"),
+      pages: z2.array(z2.string()).optional().describe("Updated page routes"),
+      criticality: z2.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality level")
     }
   );
   tool(
     server2,
     client2,
     "archive_feature",
-    "Archive a feature (soft delete). Archived features are hidden from the dashboard but can be restored.",
-    { featureId: z.string().describe("The feature ID to archive") },
+    "Archive a feature (soft delete). Archived features are hidden from the dashboard but can be restored with restore_feature.",
+    { featureId: z2.string().describe("The feature ID to archive") },
     { destructiveHint: true }
   );
+  tool(
+    server2,
+    client2,
+    "restore_feature",
+    "Restore an archived feature so it shows in the dashboard again. Does nothing for a feature that is already active. Fails if an active feature now holds the same name.",
+    { featureId: z2.string().describe("The ID of the archived feature to restore") }
+  );
   tool(
     server2,
     client2,
@@ -598,12 +1547,33 @@ function registerAllTools(server2, client2) {
     {},
     { readOnlyHint: true }
   );
+  tool(
+    server2,
+    client2,
+    "get_app_map",
+    'Get the app map: the features, sub-features, user journeys and page states found for this project, each with its routes, sign-in need, what it writes (orders, bookings, sign-ups, payments, messages), where it came from (survey, code, bundle, network, the customer) and whether the customer ticked it. Returns { map: null } before the first build. Use format "eval" for the compact features/journeys/states export.',
+    { format: z2.enum(["eval"]).optional().describe('"eval" returns the compact features/journeys/states export instead of the full map') },
+    { readOnlyHint: true }
+  );
   tool(
     server2,
     client2,
     "list_bugs",
-    "Get all detected bugs: app bugs (quarantined tests with @bug-found), security findings, and flaky tests.",
-    {},
+    "Get all detected bugs: app bugs (confirmed, and waiting for a person), security findings, flaky tests, and visual issues flagged as bugs. appBugs holds at most `limit` bugs (default 50, max 200); appBugsTruncated says when the project has more, summary.totalBugs is the full count.",
+    { limit: z2.number().int().min(1).max(200).optional().describe("Max app bugs to return (default 50, max 200). When appBugsTruncated is true, ask again with a higher limit.") },
+    { readOnlyHint: true }
+  );
+  tool(
+    server2,
+    client2,
+    "list_visual_issues",
+    "List visual issues found on the app's pages by the layout checks that run during surveys and discovery (clipped or overflowing text, covered or cut-off controls, broken images, sideways scrolling on phones, small tap targets, low contrast). Each has the page route, viewport, CSS selector, element box and a description, so you can find and fix the element in the code. Visual issues never fail tests.",
+    {
+      status: z2.enum(["OPEN", "ACCEPTED", "DISMISSED", "GONE"]).optional().describe("Filter by status (default OPEN). ACCEPTED = flagged as a bug; GONE = no longer seen on the page"),
+      severity: z2.enum(["high", "medium", "low"]).optional().describe("Filter by severity"),
+      viewport: z2.enum(["desktop", "phone"]).optional().describe("Filter by viewport"),
+      route: z2.string().optional().describe("Only this page route, e.g. /pricing")
+    },
     { readOnlyHint: true }
   );
   tool(
@@ -612,8 +1582,8 @@ function registerAllTools(server2, client2) {
     "flag_as_bug",
     "Mark a failing test as a confirmed application bug - quarantines it with @bug-found and records the bug description. Use when the failure is caused by broken app behaviour, NOT a test script issue. Do NOT use for selector changes or timeout failures - use heal_test or edit_test_code for those.",
     {
-      testId: z.string().describe("The failing test case ID"),
-      description: z.string().describe('What is broken in the application (e.g. "POST /api/checkout returns 500 when payment method is valid")')
+      testId: z2.string().describe("The failing test case ID"),
+      description: z2.string().describe('What is broken in the application (e.g. "POST /api/checkout returns 500 when payment method is valid")')
     }
   );
   tool(
@@ -629,8 +1599,9 @@ function registerAllTools(server2, client2) {
     "list_security_findings",
     "List security audit findings with optional filters. Returns severity, category, status, and affected endpoints.",
     {
-      severity: z.enum(["critical", "high", "medium", "low", "info"]).optional().describe("Filter by severity"),
-      status: z.enum(["open", "acknowledged", "resolved", "false-positive"]).optional().describe("Filter by status")
+      severity: z2.enum(["critical", "high", "medium", "low", "info"]).optional().describe("Filter by severity"),
+      status: z2.enum(["open", "acknowledged", "resolved", "false-positive", "false-positive-auto"]).optional().describe("Filter by status"),
+      verificationStatus: z2.enum(["confirmed", "false-positive-auto", "unverifiable", "error"]).optional().describe("Filter by verification probe result")
     },
     { readOnlyHint: true }
   );
@@ -639,7 +1610,7 @@ function registerAllTools(server2, client2) {
     client2,
     "set_app_brief",
     "Set or update the project's application brief - a description of the app used by AI for better test generation.",
-    { appBrief: z.string().describe("Application description. Set empty to clear.") }
+    { appBrief: z2.string().describe("Application description. Set empty to clear.") }
   );
   tool(
     server2,
@@ -653,9 +1624,9 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "run_draft_tests",
-    "Run all DRAFT tests to verify them. Tests that pass auto-promote to ACTIVE. Optionally scope to a feature.",
+    "Run DRAFT tests to verify them, 50 at most per call (oldest first; hasMore says when more remain). Tests that pass auto-promote to ACTIVE. Optionally scope to a feature. Returns a batchId: wait with wait_for_batch.",
     {
-      featureName: z.string().optional().describe("Only run drafts for this feature (optional)")
+      featureName: z2.string().optional().describe("Only run drafts for this feature (optional)")
     }
   );
   tool(
@@ -664,17 +1635,17 @@ function registerAllTools(server2, client2) {
     "setup_project",
     'One-shot project setup from codebase knowledge. Sets app brief, base URL, test credentials, and creates features with pages - all in one call. Use this when a developer says "set up test coverage for my app."',
     {
-      appBrief: z.string().optional().describe("Description of the application (what it does, key features, tech stack)"),
-      baseUrl: z.string().describe('Application base URL (e.g. "https://myapp.com" or "http://localhost:3000")'),
-      testCredentials: z.object({
-        email: z.string().optional().describe("Test user email"),
-        password: z.string().optional().describe("Test user password")
+      appBrief: z2.string().optional().describe("Description of the application (what it does, key features, tech stack)"),
+      baseUrl: z2.string().describe('Application base URL (e.g. "https://myapp.com" or "http://localhost:3000")'),
+      testCredentials: z2.object({
+        email: z2.string().optional().describe("Test user email"),
+        password: z2.string().optional().describe("Test user password")
       }).optional().describe("Login credentials for test execution"),
-      features: z.array(z.object({
-        name: z.string().describe("Feature name"),
-        description: z.string().optional().describe("What the feature does"),
-        pages: z.array(z.string()).describe('Page routes (e.g. ["/login", "/register"])'),
-        criticality: z.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality")
+      features: z2.array(z2.object({
+        name: z2.string().describe("Feature name"),
+        description: z2.string().optional().describe("What the feature does"),
+        pages: z2.array(z2.string()).describe('Page routes (e.g. ["/login", "/register"])'),
+        criticality: z2.enum(["critical", "high", "medium", "low"]).optional().describe("Feature criticality")
       })).describe("Features to create with their page routes")
     }
   );
@@ -684,13 +1655,13 @@ function registerAllTools(server2, client2) {
     "add_api_endpoints",
     "Register API endpoints for a feature from codebase knowledge. Read the developer's route handlers to extract methods, paths, request/response shapes. Populates the API intelligence dashboard.",
     {
-      featureName: z.string().describe("Feature name to link these endpoints to"),
-      endpoints: z.array(z.object({
-        method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
-        path: z.string().describe('API path (e.g. "/api/auth/login")'),
-        requestShape: z.record(z.string()).optional().describe('Request body fields with types (e.g. { "email": "string" })'),
-        responseShapes: z.record(z.record(z.string())).optional().describe('Response shapes by status code (e.g. { "200": { "token": "string" } })'),
-        requiresAuth: z.boolean().optional().describe("Whether endpoint requires authentication")
+      featureName: z2.string().describe("Feature name to link these endpoints to"),
+      endpoints: z2.array(z2.object({
+        method: z2.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).describe("HTTP method"),
+        path: z2.string().describe('API path (e.g. "/api/auth/login")'),
+        requestShape: z2.record(z2.string(), z2.string()).optional().describe('Request body fields with types (e.g. { "email": "string" })'),
+        responseShapes: z2.record(z2.string(), z2.record(z2.string(), z2.string())).optional().describe('Response shapes by status code (e.g. { "200": { "token": "string" } })'),
+        requiresAuth: z2.boolean().optional().describe("Whether endpoint requires authentication")
       })).describe("API endpoints to register")
     }
   );
@@ -700,10 +1671,10 @@ function registerAllTools(server2, client2) {
     "get_test_failures",
     "Get recent test failures with full error messages, Playwright code, step-level failures, and heal context. Use this to understand why tests are failing.",
     {
-      limit: z.number().optional().describe("Max failures to return (default: 50, max: 100)"),
-      suite: z.string().optional().describe("Filter by feature/suite name"),
-      mode: z.enum(["run", "heal", "all"]).optional().describe("run = regular failures, heal = heal attempt failures, all = both (default)"),
-      sinceHours: z.number().optional().describe("Only failures from the last N hours (default: 24)")
+      limit: z2.number().optional().describe("Max failures to return (default: 50, max: 100)"),
+      suite: z2.string().optional().describe("Filter by feature/suite name"),
+      mode: z2.enum(["run", "heal", "all"]).optional().describe("run = regular failures, heal = heal attempt failures, all = both (default)"),
+      sinceHours: z2.number().optional().describe("Only failures from the last N hours (default: 24)")
     },
     { readOnlyHint: true }
   );
@@ -715,11 +1686,16 @@ if (process.argv[2] === "init") {
   runInit2();
   process.exit(0);
 }
+if (process.argv[2] === "init-agents") {
+  const { runInitAgents: runInitAgents2 } = await Promise.resolve().then(() => (init_init_agents(), init_agents_exports));
+  await runInitAgents2();
+  process.exit(0);
+}
 var config = resolveConfig();
 var client = new ValidateQAClient(config.apiUrl, config.token, config.projectId);
 var server = new McpServer(
-  { name: "validate.qa", version: "1.0.0" },
-  { instructions: `Validate.QA - AI-powered QA platform: generates, runs, and heals Playwright E2E tests.
+  { name: "validate.qa", version: "1.2.0" },
+  { instructions: config.toolset === "agent" ? AGENT_INSTRUCTIONS : `Validate.QA - AI-powered QA platform: generates, runs, and heals Playwright E2E tests.
 
 ## Capabilities
 - Setup projects via setup_project (read source code first)
@@ -733,12 +1709,13 @@ var server = new McpServer(
 2. Check health: list_features (failingTests > 0), get_test_failures per feature, edit_test_code or heal_test.
 3. Add coverage: READ code, create_feature, create_test x N (suite = feature name), add_api_endpoints.
 4. Nightly automation: create_schedule (daily, autoHeal: true).
-5. After code change: batch_run_tests, then list_features + get_test_failures.
+5. After code change: batch_run_tests (waitSeconds: 120, or then wait_for_batch), then list_features + get_test_failures.
+6. Find and lock in bugs in a feature: start_here({ feature }), explore with your browser, save_regression_test for each bug (returns at once, keep exploring), then collect_verdicts.
 
 ## Automatic lifecycle
-Do NOT call run_test after create_test (auto-queued) or heal_test after failures (auto-heals).
-Do NOT check run status in a loop - call get_test_failures after a reasonable wait to see what failed.
-Lifecycle: create > auto-run > pass=ACTIVE, fail=auto-heal > heal fail=@needs-review.
+Do NOT call run_test after create_test (auto-queued) or heal_test after failures (auto-heals, unless toggle_auto_heal turned it off).
+Do NOT poll get_test_run in a loop. To wait for a run, call wait_for_run(runId) (or wait_for_batch(batchId)); it blocks until the run finishes or timeoutSeconds passes (max 120) and returns timedOut: true if it is still going - then call it again. run_test and batch_run_tests also take waitSeconds to queue and wait in one call. A FAILED run comes back with its error, consoleLog and failedSteps.
+Lifecycle: create > auto-run > pass=ACTIVE, fail=auto-heal > heal fail=@needs-review. With toggle_auto_heal(false), no failure is auto-healed; call heal_test yourself when you want one.
 DO call add_api_endpoints per feature (not automatic).
 DO call run_security_audit after UI tests to analyze captured API traffic. If it errors about missing data, tell the developer to click "Security Audit" in the Dashboard to run a live browser capture first. Use list_security_findings to review results.
 
@@ -762,23 +1739,27 @@ Read project://test-conventions first. Check the variables section:
 ## Critical rules - see project://test-conventions for full details and code templates
 - URLs: relative only, never hardcoded domains - runner sets baseURL
 - Credentials: process.env.TEST_USER_EMAIL! (non-null assertion) - never ?? or || fallbacks
-- Registration: testuser-\${Date.now()}@example.com
+- Registration: testuser-\${Date.now()}@example.test when the sign-up sends no email; if it emails a code or link, register with process.env.VQA_TEST_INBOX_EMAIL! / process.env.VQA_TEST_ACCOUNT_PASSWORD! and read it with await __vqaWaitForEmail('code' | 'link'), first asserting the app's 'email sent' state (code field visible / 'check your email') before each call (runner-injected; see test-conventions)
 - Suite name must match feature name exactly (case-sensitive)
 - @auth must NOT combine with @smoke/@regression/@needs-auth/@critical
 - Each test = own browser process; @needs-auth tests MUST login inline
 - API tests: test.describe.serial() with __QA_HTTP__ log after every request
 - UI tests: console.log() milestones after key actions
+- Selectors: getByRole(role, { name, exact: true }), getByLabel(label, { exact: true }), getByText(text, { exact: true }); CSS ids only for nodes with no accessible name
+- URL assertions: path only - await expect(page).toHaveURL(/\\/dashboard$/) - never a host
+- Production BASE_URL: read-only tests get the read-only guard (page.route aborts auth/mutation requests and fails the test) - template in project://test-conventions
+- Every assertion must be able to fail: no toHaveCount(0) on transient text, no toBeHidden on an element never shown, full message text instead of a toContainText fragment
 - create_test/edit_test_code validate code - fix warnings before moving on
 
 ## Setting up coverage
 1. SCAN: Read router, nav, pages, API handlers - map ALL routes and features.
 2. SETUP: setup_project with features, pages, baseUrl, testCredentials, appBrief.
 3. WRITE: One feature at a time. For EACH test, read the SPECIFIC source code first (see codeReadingRequirements in test-conventions). For login blocks: read the login component. For UI tests: read the page component. For API tests: read the route handler. Templates are structure guides - selectors MUST come from the real code. Use create_test for BOTH UI and API tests. Then call add_api_endpoints.
-4. VERIFY: get_coverage_summary + list_features for failures + get_test_failures.
+4. VERIFY: get_spec_coverage(featureName, specItems) - write tests for every uncovered item - then get_coverage_summary + list_features for failures + get_test_failures.
 
 Test real user flows (forms, validation, errors). "Page loads" tests are worthless.` }
 );
-registerAllTools(server, client);
+registerAllTools(server, client, config.toolset);
 server.resource(
   "Project Overview",
   "project://overview",
@@ -807,6 +1788,10 @@ server.resource(
   "project://test-conventions",
   { description: "Project-specific test conventions: environment variables, credential patterns, tag meanings, and registration email rules. Read this before writing or editing any test." },
   async () => {
+    const served = await client.getTestConventions();
+    if (served && typeof served === "object") {
+      return { contents: [{ uri: "project://test-conventions", mimeType: "application/json", text: JSON.stringify(served, null, 2) }] };
+    }
     try {
       const vars = await client.executeTool("get_variables");
       const varNames = Object.keys(vars.variables || {});
@@ -814,7 +1799,7 @@ server.resource(
       const conventions = {
         codeReadingRequirements: {
           CRITICAL: "Templates below are STRUCTURE GUIDES - every selector, route, and endpoint MUST come from reading the actual source code. Never copy a template verbatim.",
-          forLogin: "BEFORE writing any @needs-auth login block: READ the login/auth page component. Find: (1) the login route (/login, /auth/login, /signin?), (2) the flow type (single-step or multi-step with Continue/Next button?), (3) exact input selectors (labels, placeholders, input types - is it getByLabel, getByPlaceholder, or input[type=password]?), (4) exact submit button text, (5) post-login redirect URL. Every app is different - single-step, multi-step, OAuth buttons, magic links.",
+          forLogin: "BEFORE writing any @needs-auth login block: READ the login/auth page component. Find: (1) the login route (/login, /auth/login, /signin?), (2) the flow type (single-step or multi-step with Continue/Next button?), (3) each field's label text for getByLabel(label, { exact: true }) - fall back to the placeholder or input[type=password] only when the field has no label, (4) the submit button's accessible name for getByRole('button', { name, exact: true }), (5) post-login redirect URL. Every app is different - single-step, multi-step, OAuth buttons, magic links.",
           forUITests: "BEFORE writing a UI test for a page: READ the page component. Find: headings (text + level), form fields (labels, placeholders, types), buttons (text, role), navigation elements, validation error messages, success/error states. Use the exact text from the component - do not guess.",
           forAPITests: "BEFORE writing an API test: READ the route handler. Find: the endpoint path, HTTP method, request body schema (what fields, what types), response body shape (is it flat or wrapped in { data: {...} }?), auth requirements (Bearer token? Cookie? API key?), error response shapes.",
           forAPIMapping: "BEFORE calling add_api_endpoints: READ ALL route handlers for the feature. Register every endpoint with accurate method, path, requestShape, responseShapes, requiresAuth."
@@ -822,7 +1807,8 @@ server.resource(
         credentials: {
           rule: "Never hardcode credentials in test code",
           loginFields: hasAuth ? "Use process.env.TEST_USER_EMAIL! and process.env.TEST_USER_PASSWORD!" : "No credentials configured - set TEST_USER_EMAIL and TEST_USER_PASSWORD via set_variable",
-          registrationFields: 'MUST use unique email per run: `testuser-${Date.now()}@example.com` - reusing emails causes "already registered" failures',
+          registrationFields: 'MUST use unique email per run: `testuser-${Date.now()}@example.test` - reusing emails causes "already registered" failures. When the sign-up emails a verification code or link, register with `process.env.VQA_TEST_INBOX_EMAIL!` / `process.env.VQA_TEST_ACCOUNT_PASSWORD!` (a fresh real inbox address the runner injects per run) instead',
+          emailedCodesAndLinks: "Read emails at runtime with the runner-injected helpers (never define them): `const code = await __vqaWaitForEmail('code'); await __vqaEnterVerificationCode(page, code);` or `await page.goto(await __vqaWaitForEmail('link'));` for the run's sign-up identity; `await __vqaWaitForEmail('code', { to: process.env.TEST_USER_EMAIL })` for the saved account's sign-in code or magic link (works only when TEST_USER_EMAIL is the project's Validate.QA inbox address). Each call returns an email no earlier call returned. Assert the app's 'email sent' state (code field visible / 'check your email') before each __vqaWaitForEmail call, so a send error fails at once instead of after the inbox wait. Never hardcode or guess a code.",
           registrationPassword: "Use 'TestPass123!' for new account passwords (meets typical strength rules)"
         },
         variables: {
@@ -845,7 +1831,7 @@ server.resource(
           "@heal-skip": "Added by healer when test is permanently unfixable. Prevents future auto-heal",
           "@rate-limit-blocked": "Auto-added by pre-heal classifier when test failure was a rate-limit (HTTP 429). Test skips heal until next pass clears the tag. NOT for use by test authors.",
           "@quota-exceeded": "Auto-added when failure is a quota/daily-limit response. Skips heal; clears on next pass.",
-          "@auth-lost": "Auto-added when failure is a 401/403. Skips heal; clears after re-auth + pass.",
+          "@auth-lost": "Auto-added when a signed-in test (@needs-auth, authed @api, or a stored-login body) fails on a 401/403 or falls back to the login page. Never on @auth / login-form tests. Skips heal; clears after re-auth + pass.",
           "@rate-limit-expected": 'OPT-OUT tag for tests that intentionally exercise rate-limit behavior (e.g., "POST /api/login 6 times to trigger lockout"). Add this tag to ANY @api test that asserts rate-limit responses, otherwise the rate-limit detector will silently downgrade your failure to ERROR. Distinct from auto-pushed @rate-limit-blocked.'
         },
         executionModel: {
@@ -883,7 +1869,8 @@ server.resource(
           "Use { timeout: 30000 } on waitForURL after login - target apps can be slow under concurrent test load",
           "Keep login blocks minimal - no assertions on the login page (that is what @auth tests are for)",
           "After login, page.goto() directly to the page being tested - do not navigate via UI clicks",
-          "Use role-based selectors (getByRole, getByLabel) over CSS selectors",
+          "Selectors: getByRole(role, { name, exact: true }) for buttons/links/headings, getByLabel(label, { exact: true }) for form fields, getByText(text, { exact: true }) for static copy. CSS ids/classes only for nodes with no accessible name",
+          "URL assertions: path only - await expect(page).toHaveURL(/\\/dashboard$/) - never a host",
           "Registration tests must generate unique email with Date.now()",
           "Group tests into suites matching feature names exactly (case-sensitive)",
           "Do NOT suggest storageState or performLogin() for create_test - those only work in the regression suite",
@@ -893,9 +1880,9 @@ server.resource(
         ],
         pitfalls: {
           CRITICAL: "These are the top causes of test failures. Read before writing ANY test.",
-          strictModeViolations: `Playwright throws when a locator resolves to 2+ elements. Common causes: getByLabel('Password') matches input AND 'Show password' toggle; getByRole('button', { name: 'Continue' }) matches 'Continue' AND 'Continue with GitHub'. Prevention: use input[type="password"] for password fields, use { exact: true } for ambiguous button text, scope to a parent container (page.locator('form#login').getByLabel('Email')).`,
+          strictModeViolations: `Playwright throws when a locator resolves to 2+ elements. Common causes: getByLabel('Password') matches input AND 'Show password' toggle; getByRole('button', { name: 'Continue' }) matches 'Continue' AND 'Continue with GitHub'. Prevention: getByLabel('Password', { exact: true }) (exact keeps it from matching 'Show password'), { exact: true } for ambiguous button text, scope to a parent container (page.locator('form#login').getByLabel('Email', { exact: true })). Use input[type="password"] only when the field has no label.`,
           networkIdle: "NEVER use waitForLoadState('networkidle') - waits for 500ms of zero network activity, which is fragile and causes 30s+ timeouts in apps with polling, analytics, or WebSockets. Use waitForURL() or wait for a specific element instead.",
-          headingStrictMode: "getByRole('heading', { name: 'Dashboard' }) can match multiple headings (h1 + h2 + breadcrumb). Add { level: 1 } or { exact: true } to disambiguate. Same for getByLabel('Password') matching input AND 'Show password' toggle.",
+          headingStrictMode: "getByRole('heading', { name: 'Dashboard' }) can match multiple headings (h1 + h2 + breadcrumb). Add { level: 1 } or { exact: true } to disambiguate. Same fix for getByLabel('Password') matching the input AND a 'Show password' toggle: getByLabel('Password', { exact: true }).",
           postLoginRedirect: "NEVER assert exact URL after login (e.g. expect(page).toHaveURL('/dashboard')) - apps redirect to different routes per user/role. Use: await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 30000 })",
           resJsonOnce: "res.json() consumes the response body stream - calling it twice throws. Store result: const body = await res.json(); then reuse body for logging and assertions.",
           hiddenInputs: "Many UI frameworks use visually hidden <input> with custom overlays. page.check() fails because the overlay intercepts clicks. Click the <label> or visible wrapper: page.getByText('Remember me').click()",
@@ -911,10 +1898,10 @@ server.resource(
   // Login block - ADAPTED from reading the app's login page component
   // YOU MUST READ the login page component BEFORE writing this block
   await page.goto('/login'); // read the router for actual login route
-  await page.getByRole('textbox', { name: /email/i }).fill(process.env.TEST_USER_EMAIL!);
-  await page.locator('input[type="password"]').waitFor({ state: 'visible', timeout: 10000 });
-  await page.locator('input[type="password"]').fill(process.env.TEST_USER_PASSWORD!);
-  await page.getByRole('button', { name: /sign in|log in|submit/i }).click();
+  await page.getByLabel('Email', { exact: true }).fill(process.env.TEST_USER_EMAIL!); // label text from the component
+  await page.getByLabel('Password', { exact: true }).waitFor({ state: 'visible', timeout: 10000 });
+  await page.getByLabel('Password', { exact: true }).fill(process.env.TEST_USER_PASSWORD!); // input[type="password"] only if the field has no label
+  await page.getByRole('button', { name: 'Sign in', exact: true }).click(); // the button's accessible name
   await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 30000 });
   console.log('Logged in, current URL:', page.url());
 
@@ -938,21 +1925,7 @@ server.resource(
     responseShapes: { "200": { "token": "string", "user": "object" }, "401": { "error": "string" } }
   }]
 }`,
-          uiWithMilestones: `test('Feature - Happy Path', async ({ page }) => {
-  await page.goto('/login');
-  console.log('Navigated to login page');
-
-  await page.getByRole('textbox', { name: /email/i }).fill(process.env.TEST_USER_EMAIL!);
-  await page.locator('input[type="password"]').fill(process.env.TEST_USER_PASSWORD!);
-  await page.getByRole('button', { name: /sign in/i }).click();
-  console.log('Credentials submitted');
-
-  await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 15000 });
-  console.log('Logged in, current URL:', page.url());
-
-  await page.goto('/feature-path');
-  console.log('On feature page');
-});`
+          uiWithMilestones: "test('Feature - Happy Path', async ({ page }) => {\n  await page.goto('/login');\n  console.log('Navigated to login page');\n\n  await page.getByLabel('Email', { exact: true }).fill(process.env.TEST_USER_EMAIL!);\n  await page.getByLabel('Password', { exact: true }).fill(process.env.TEST_USER_PASSWORD!);\n  await page.getByRole('button', { name: 'Sign in', exact: true }).click();\n  console.log('Credentials submitted');\n\n  await page.waitForURL(url => !url.pathname.startsWith('/login'), { timeout: 15000 });\n  console.log('Logged in, current URL:', page.url());\n\n  await page.goto('/feature-path');\n  console.log('On feature page');\n});"
         },
         testQuality: [
           'Test actual user flows, not just "page loads" - a test that only checks goto + heading visible is nearly worthless',