@validate.qa/mcp 1.0.0 → 1.1.0

package/dist/index.js

@@ -24,7 +24,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) {
@@ -80,7 +80,7 @@ function runInit() {
   const entry = buildMcpEntry(config2);
   const cwd = process.cwd();
   console.log("");
-  console.log("  Validate.QA \u2014 MCP Setup");
+  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;
@@ -91,9 +91,9 @@ function runInit() {
     }
     const file = join(target.configDir, target.configFile);
     if (result === "created") {
-      console.log(`  \u2713 ${target.name} \u2014 created ${file}`);
+      console.log(`  \u2713 ${target.name} - created ${file}`);
     } else {
-      console.log(`  \u2713 ${target.name} \u2014 updated ${file}`);
+      console.log(`  \u2713 ${target.name} - updated ${file}`);
     }
     anyWritten = true;
   }
@@ -174,6 +174,24 @@ function resolveConfig() {
 }
 
 // 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;
@@ -199,11 +217,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`, {
@@ -227,7 +262,49 @@ 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
+      };
+    }
+  };
+  if (annotations) {
+    server2.tool(name, description, schema, annotations, handler);
+  } else {
+    server2.tool(name, description, schema, handler);
+  }
+}
+var SERVER_WAIT_MAX_SECONDS = 55;
+var WAIT_DEFAULT_SECONDS = 50;
+var WAIT_MAX_SECONDS = 120;
+function isRecord(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_SECONDS);
+  let result = await client2.executeTool(name, { ...args, [waitKey]: first });
+  for (; ; ) {
+    if (!isRecord(result) || result.timedOut !== true) return result;
+    const id = result[kind.idKey];
+    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_SECONDS) });
+  }
+}
+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
       };
     }
@@ -243,7 +320,7 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "list_tests",
-    "List tests in the current project. Returns test name, status, suite, tags, confidence, and the last run result. Paginated \u2014 use limit/offset to page through all 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"),
@@ -258,16 +335,24 @@ function registerAllTools(server2, client2) {
     server2,
     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 \u2014 use get_test_code for the full Playwright code.",
+    "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") },
     { 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: z.string().describe("The test case ID to run"),
+      platform: z.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: z.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."),
+      waitSeconds: z.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,
@@ -288,10 +373,11 @@ function registerAllTools(server2, client2) {
     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 \u2014 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)"),
+      playwrightCode: z.string().optional().describe("Web tests only: new Playwright test code (full file replacement)"),
+      steps: z.array(z.record(z.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: z.string().optional().describe("New test name"),
       tags: z.array(z.string()).optional().describe('New tags array (e.g. ["@regression", "@smoke"])')
     }
@@ -300,7 +386,7 @@ function registerAllTools(server2, client2) {
     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.",
     {
       testIds: z.array(z.string()).describe("Test IDs to update"),
       status: z.enum(["DRAFT", "ACTIVE", "DISABLED", "QUARANTINED"]).describe("New status to set")
@@ -310,13 +396,65 @@ function registerAllTools(server2, client2) {
     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: z.string().optional().describe("The test run ID"),
       testId: z.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: z.string().describe("The test run ID to wait for"),
+      timeoutSeconds: z.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: z.string().describe("The batch ID returned by batch_run_tests"),
+      timeoutSeconds: z.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.",
+    {
+      mode: z.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: z.string().optional().describe("Required for deep mode: the feature name to generate tests for."),
+      focusAreas: z.array(z.string()).optional().describe("Optional routes, screens, or areas to focus discovery on."),
+      platform: z.enum(["IOS", "ANDROID"]).optional().describe("Mobile only: target platform. Requires appId."),
+      appId: z.string().optional().describe("Mobile only: bundle id/package id to explore. Requires platform."),
+      resetPolicy: z.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.",
+    {
+      discoveryRunId: z.string().optional().describe("Specific discovery run ID. Omit for latest.")
+    },
+    { readOnlyHint: true }
+  );
   server2.tool(
     "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.",
@@ -339,7 +477,7 @@ function registerAllTools(server2, client2) {
         const content = [
           {
             type: "text",
-            text: `Run ${result.runId} \u2014 status: ${result.status} \u2014 showing ${result.returned} of ${result.total} screenshot(s)`
+            text: `Run ${result.runId} - status: ${result.status} - showing ${result.returned} of ${result.total} screenshot(s)`
           }
         ];
         for (const shot of result.screenshots) {
@@ -348,7 +486,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
         };
       }
@@ -364,15 +502,19 @@ function registerAllTools(server2, client2) {
       cancelBatch: z.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")
-    }
+      suite: z.string().optional().describe("Run all active tests in this suite"),
+      waitSeconds: z.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,6 +524,16 @@ 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: z.string().optional().describe("Feature ID. Either featureId or featureName is required."),
+      featureName: z.string().optional().describe("Feature name. Either featureId or featureName is required.")
+    }
+  );
   tool(
     server2,
     client2,
@@ -416,6 +568,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,
@@ -434,7 +594,7 @@ function registerAllTools(server2, client2) {
       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"),
+      autoHeal: z.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: 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)")
     }
@@ -450,7 +610,7 @@ function registerAllTools(server2, client2) {
       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"),
+      autoHeal: z.boolean().optional().describe("Heal this schedule's failed runs. Takes effect only while the project's auto-heal (toggle_auto_heal) is on."),
       enabled: z.boolean().optional().describe("Enable or disable the schedule")
     }
   );
@@ -492,10 +652,11 @@ function registerAllTools(server2, client2) {
     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 \u2014 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 \u2014 Happy Path")'),
-      playwrightCode: z.string().describe("Full Playwright test code"),
+      name: z.string().describe('Test name (e.g. "Login - Happy Path")'),
+      playwrightCode: z.string().optional().describe("Web projects: full Playwright test code (required). Mobile projects: optional WebdriverIO export for humans - never executed."),
+      steps: z.array(z.record(z.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: 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"])')
     }
@@ -508,11 +669,22 @@ function registerAllTools(server2, client2) {
     { featureName: z.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: z.string().describe("The feature name (case-insensitive) - its suite holds the tests"),
+      specItems: z.array(z.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"),
@@ -539,7 +711,7 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "toggle_auto_heal",
-    "Enable or disable automatic AI healing when tests fail in batch or suite runs.",
+    "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: z.boolean().describe("true to enable auto-heal, false to disable") }
   );
   tool(
@@ -586,10 +758,17 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "archive_feature",
-    "Archive a feature (soft delete). Archived features are hidden from the dashboard but can be restored.",
+    "Archive a feature (soft delete). Archived features are hidden from the dashboard but can be restored with restore_feature.",
     { featureId: z.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: z.string().describe("The ID of the archived feature to restore") }
+  );
   tool(
     server2,
     client2,
@@ -602,15 +781,28 @@ function registerAllTools(server2, client2) {
     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 (quarantined tests with @bug-found), security findings, flaky tests, and visual issues flagged as bugs.",
     {},
     { 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: z.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: z.enum(["high", "medium", "low"]).optional().describe("Filter by severity"),
+      viewport: z.enum(["desktop", "phone"]).optional().describe("Filter by viewport"),
+      route: z.string().optional().describe("Only this page route, e.g. /pricing")
+    },
+    { readOnlyHint: true }
+  );
   tool(
     server2,
     client2,
     "flag_as_bug",
-    "Mark a failing test as a confirmed application bug \u2014 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 \u2014 use heal_test or edit_test_code for those.",
+    "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")')
@@ -620,7 +812,7 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "run_security_audit",
-    'Run an AI security audit on captured API traffic. Requires prior browser-based test execution (discovery or capture) \u2014 analyzes real network traffic, not just registered endpoints. If no traffic exists, the developer can trigger "Security Audit" from the Dashboard which launches a live browser to capture it.',
+    'Run an AI security audit on captured API traffic. Requires prior browser-based test execution (discovery or capture) - analyzes real network traffic, not just registered endpoints. If no traffic exists, the developer can trigger "Security Audit" from the Dashboard which launches a live browser to capture it.',
     {}
   );
   tool(
@@ -638,14 +830,14 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "set_app_brief",
-    "Set or update the project's application brief \u2014 a description of the app used by AI for better test generation.",
+    "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.") }
   );
   tool(
     server2,
     client2,
     "get_coverage_summary",
-    "Get feature-level test coverage: planned vs existing vs passing tests, plus API endpoint coverage. Shows uncoveredEndpoints per feature \u2014 use this to find which API endpoints still need tests.",
+    "Get feature-level test coverage: planned vs existing vs passing tests, plus API endpoint coverage. Shows uncoveredEndpoints per feature - use this to find which API endpoints still need tests.",
     {},
     { readOnlyHint: true }
   );
@@ -662,7 +854,7 @@ function registerAllTools(server2, client2) {
     server2,
     client2,
     "setup_project",
-    'One-shot project setup from codebase knowledge. Sets app brief, base URL, test credentials, and creates features with pages \u2014 all in one call. Use this when a developer says "set up test coverage for my app."',
+    '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")'),
@@ -719,7 +911,7 @@ 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 \u2014 AI-powered QA platform: generates, runs, and heals Playwright E2E tests.
+  { 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 +925,12 @@ 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.
 
 ## 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 \u2014 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.
 
@@ -747,34 +939,38 @@ DO call run_security_audit after UI tests to analyze captured API traffic. If it
 
 ## Triaging failures
 - App broken: flag_as_bug(testId, description). Selector/timing: heal_test. Bad test logic: edit_test_code.
-- Unsure: heal_test first \u2014 it detects app bugs automatically.
+- Unsure: heal_test first - it detects app bugs automatically.
 
 ## Using the codebase
 You have full source code access. Always READ before writing: routes for URLs, components for selectors, API handlers for endpoints.
 
-## Before writing any test \u2014 preflight check
+## Before writing any test - preflight check
 
 Read project://test-conventions first. Check the variables section:
 - BASE_URL must be set (the runner needs it). If missing, call setup_project or set_variable.
 - TEST_USER_EMAIL and TEST_USER_PASSWORD must be set if tests require login. If missing, ask the developer for credentials and call set_variable.
 - If starting fresh (no features, no variables), use workflow #1 (setup_project) before anything else.
 
-## Critical rules \u2014 see project://test-conventions for full details and code templates
-- URLs: relative only, never hardcoded domains \u2014 runner sets baseURL
-- Credentials: process.env.TEST_USER_EMAIL! (non-null assertion) \u2014 never ?? or || fallbacks
+## 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
 - 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
-- create_test/edit_test_code validate code \u2014 fix warnings before moving on
+- 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 \u2014 map ALL routes and features.
+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 \u2014 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.
+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_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.` }
 );
@@ -807,22 +1003,26 @@ 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 || {});
       const hasAuth = varNames.includes("TEST_USER_EMAIL") && varNames.includes("TEST_USER_PASSWORD");
       const conventions = {
         codeReadingRequirements: {
-          CRITICAL: "Templates below are STRUCTURE GUIDES \u2014 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 \u2014 is it getByLabel, getByPlaceholder, or input[type=password]?), (4) exact submit button text, (5) post-login redirect URL. Every app is different \u2014 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 \u2014 do not guess.",
+          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) 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."
         },
         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 \u2014 set TEST_USER_EMAIL and TEST_USER_PASSWORD via set_variable",
-          registrationFields: 'MUST use unique email per run: `testuser-${Date.now()}@example.com` \u2014 reusing emails causes "already registered" failures',
+          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',
           registrationPassword: "Use 'TestPass123!' for new account passwords (meets typical strength rules)"
         },
         variables: {
@@ -831,10 +1031,10 @@ server.resource(
         },
         tags: {
           "@auth": "Tests the login/auth flow itself. MUST NOT combine with @smoke, @regression, @needs-auth, @critical. CAN include @discovered.",
-          "@needs-auth": "Tests for authenticated pages \u2014 MUST include inline login block. CAN combine with @smoke, @regression, @critical.",
-          "@smoke": "Quick sanity checks \u2014 run on every deploy",
+          "@needs-auth": "Tests for authenticated pages - MUST include inline login block. CAN combine with @smoke, @regression, @critical.",
+          "@smoke": "Quick sanity checks - run on every deploy",
           "@regression": "Full regression suite tests",
-          "@critical": "Business-critical paths (informational label \u2014 no special suite filtering)",
+          "@critical": "Business-critical paths (informational label - no special suite filtering)",
           "@api": "API-level tests. Runs in its own project, excluded from suite/smoke/regression runs",
           "@discovered": "Auto-added to tests generated by AI discovery",
           "@generated": "Auto-added by AI discovery and API test generation",
@@ -842,75 +1042,80 @@ server.resource(
           "@flaky": "Auto-added after repeated failures. Excluded from suite/smoke/regression runs",
           "@bug-found": "Added when healer detects an app bug. Test is auto-quarantined",
           "@needs-review": "Added when DRAFT test fails healing. Requires human attention",
-          "@heal-skip": "Added by healer when test is permanently unfixable. Prevents future auto-heal"
+          "@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 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: {
           isolation: "Each test runs as its own separate Playwright process in a fresh browser. No shared state, no storageState, no global setup.",
-          authRequired: "Every @needs-auth test MUST include its own login block. Do NOT suggest storageState or performLogin() \u2014 those only work in the regression suite.",
-          concurrency: "Tests run in parallel \u2014 runner claims up to 10 per poll, launched 3s apart (~30s per batch). Multiple batches can overlap. Use test.setTimeout(120_000) if the target app is slow under concurrent login load."
+          authRequired: "Every @needs-auth test MUST include its own login block. Do NOT suggest storageState or performLogin() - those only work in the regression suite.",
+          concurrency: "Tests run in parallel - runner claims up to 10 per poll, launched 3s apart (~30s per batch). Multiple batches can overlap. Use test.setTimeout(120_000) if the target app is slow under concurrent login load."
         },
         lifecycle: {
-          DRAFT: "New or unverified test \u2014 not included in scheduled runs",
-          ACTIVE: "Verified and running \u2014 included in batch/suite executions",
-          DISABLED: "Manually paused \u2014 excluded from all runs",
+          DRAFT: "New or unverified test - not included in scheduled runs",
+          ACTIVE: "Verified and running - included in batch/suite executions",
+          DISABLED: "Manually paused - excluded from all runs",
           QUARANTINED: "Auto-quarantined after repeated failures"
         },
         logging: {
           CRITICAL: "EVERY request.get/post/put/patch/delete call MUST be followed by a __QA_HTTP__ log line. This is how the platform surfaces request/response data in the Network panel. Missing this = invisible API calls.",
           apiPattern: "const body = await res.json();\nconsole.log('__QA_HTTP__:' + JSON.stringify({ method: 'POST', url: '/api/path', status: res.status(), requestBody: { field: value, password: '[REDACTED]' }, responseBody: body }));",
           rules: [
-            "Call res.json() ONCE, store in body variable \u2014 reuse for log and assertions (calling twice throws)",
+            "Call res.json() ONCE, store in body variable - reuse for log and assertions (calling twice throws)",
             "Log AFTER the request, BEFORE assertions",
             'Redact sensitive fields: password: "[REDACTED]", token: "[REDACTED]"',
             "Use the literal URL string (same as the request call), not a variable",
-            "UI tests using page fixture do NOT need __QA_HTTP__ \u2014 only request fixture tests"
+            "UI tests using page fixture do NOT need __QA_HTTP__ - only request fixture tests"
           ],
-          uiMilestones: "UI tests (page fixture): add plain console.log() at key milestones \u2014 e.g. console.log('Navigated to login page') after page.goto(). These appear in the Console Output panel.",
+          uiMilestones: "UI tests (page fixture): add plain console.log() at key milestones - e.g. console.log('Navigated to login page') after page.goto(). These appear in the Console Output panel.",
           uiLoggingRules: [
-            "Log AFTER the action, not before \u2014 confirms the action succeeded",
+            "Log AFTER the action, not before - confirms the action succeeded",
             'Include dynamic values where useful: console.log("Current URL:", page.url())',
-            "Keep messages short and human-readable \u2014 they show verbatim in the UI",
+            "Keep messages short and human-readable - they show verbatim in the UI",
             "Do NOT log sensitive values (passwords, tokens)"
           ],
-          apiTestStructure: "Use test.describe.serial() for API tests sharing auth. Independent validation tests (401, 404 checks) go in a SEPARATE non-serial describe block \u2014 do not mix them with the auth-dependent serial flow."
+          apiTestStructure: "Use test.describe.serial() for API tests sharing auth. Independent validation tests (401, 404 checks) go in a SEPARATE non-serial describe block - do not mix them with the auth-dependent serial flow."
         },
         bestPractices: [
           "Every @needs-auth test must start with a login block (goto login, fill creds, click submit, waitForURL)",
-          "Use { timeout: 30000 } on waitForURL after login \u2014 target apps can be slow under concurrent test load",
-          "Keep login blocks minimal \u2014 no assertions on the login page (that is what @auth tests are for)",
-          "After login, page.goto() directly to the page being tested \u2014 do not navigate via UI clicks",
-          "Use role-based selectors (getByRole, getByLabel) over CSS selectors",
+          "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",
+          "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 \u2014 those only work in the regression suite",
-          "EVERY API test (request fixture) MUST include __QA_HTTP__ log after each request call \u2014 see logging section above",
-          'Avoid waitForLoadState("networkidle") \u2014 apps with SSE, WebSocket, or analytics connections may never reach idle, causing 60s timeouts. Wait for specific elements instead.',
-          'For headings, use exact: true or level: 1 \u2014 getByRole("heading", { name: "X" }) matches ALL h1-h6 containing "X", causing strict mode violations'
+          "Do NOT suggest storageState or performLogin() for create_test - those only work in the regression suite",
+          "EVERY API test (request fixture) MUST include __QA_HTTP__ log after each request call - see logging section above",
+          'Avoid waitForLoadState("networkidle") - apps with SSE, WebSocket, or analytics connections may never reach idle, causing 60s timeouts. Wait for specific elements instead.',
+          'For headings, use exact: true or level: 1 - getByRole("heading", { name: "X" }) matches ALL h1-h6 containing "X", causing strict mode violations'
         ],
         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')).`,
-          networkIdle: "NEVER use waitForLoadState('networkidle') \u2014 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.",
-          postLoginRedirect: "NEVER assert exact URL after login (e.g. expect(page).toHaveURL('/dashboard')) \u2014 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 \u2014 calling it twice throws. Store result: const body = await res.json(); then reuse body for logging and assertions.",
+          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 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()",
-          apiResponseShapes: "API endpoints often wrap data in a property ({ user: {...} }, { data: [...] }). Read the route handler's res.json() call to see the actual shape. If the handler does res.json({ ticket }), then body is { ticket: { id, ... } } \u2014 NOT { id, ... }.",
-          invalidIds: "Not all routes validate ID format before querying the database. If a route passes the raw ID to an ORM query and gets null back, it returns 404 'not found' \u2014 not 400 'bad request'. If unsure, expect either: expect([400, 404]).toContain(res.status())",
-          hardcodedUrls: "NEVER hardcode full URLs in test code. For UI tests: always use relative paths \u2014 page.goto('/login'). The runner sets baseURL from the project's BASE_URL variable. For API tests: use relative paths if the API is on the same domain as the frontend (request.post('/api/auth/login')). If the API is on a SEPARATE domain, use process.env.BASE_API_URL! as a test variable (set via set_variable) and construct URLs: request.post(process.env.BASE_API_URL! + '/auth/login'). NEVER hardcode 'https://example.com/...' in test code \u2014 use env vars or relative paths.",
+          apiResponseShapes: "API endpoints often wrap data in a property ({ user: {...} }, { data: [...] }). Read the route handler's res.json() call to see the actual shape. If the handler does res.json({ ticket }), then body is { ticket: { id, ... } } - NOT { id, ... }.",
+          invalidIds: "Not all routes validate ID format before querying the database. If a route passes the raw ID to an ORM query and gets null back, it returns 404 'not found' - not 400 'bad request'. If unsure, expect either: expect([400, 404]).toContain(res.status())",
+          hardcodedUrls: "NEVER hardcode full URLs in test code. For UI tests: always use relative paths - page.goto('/login'). The runner sets baseURL from the project's BASE_URL variable. For API tests: use relative paths if the API is on the same domain as the frontend (request.post('/api/auth/login')). If the API is on a SEPARATE domain, use process.env.BASE_API_URL! as a test variable (set via set_variable) and construct URLs: request.post(process.env.BASE_API_URL! + '/auth/login'). NEVER hardcode 'https://example.com/...' in test code - use env vars or relative paths.",
           credentialFallbacks: "NEVER use process.env.TEST_USER_EMAIL ?? 'fallback' or || 'fallback'. Use ! (non-null assertion). Missing variable = test should fail immediately, not silently use hardcoded value."
         },
         templates: {
-          needsAuth: `test('Feature Name \u2014 Test Name', {
+          needsAuth: `test('Feature Name - Test Name', {
   tag: ['@needs-auth', '@smoke'],
 }, async ({ page }) => {
-  // Login block \u2014 ADAPTED from reading the app's login page component
+  // 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());
 
@@ -919,7 +1124,7 @@ server.resource(
   console.log('On feature page');
   await expect(page.getByRole('heading', { name: /feature name/i })).toBeVisible();
 });`,
-          authTest: "test('Login \u2014 Happy Path', {\n  tag: ['@auth'],\n}, async ({ page }) => {\n  await page.goto('/auth/login');\n  // test the login form itself \u2014 selectors from reading the actual component\n});",
+          authTest: "test('Login - Happy Path', {\n  tag: ['@auth'],\n}, async ({ page }) => {\n  await page.goto('/auth/login');\n  // test the login form itself - selectors from reading the actual component\n});",
           apiSerial: "test.describe.serial('Feature Name', () => {\n  let token: string;\n  test('authenticate', async ({ request }) => {\n    const res = await request.post('/api/auth/login', {\n      data: { email: process.env.TEST_USER_EMAIL!, password: process.env.TEST_USER_PASSWORD! }\n    });\n    const body = await res.json();\n    console.log('__QA_HTTP__:' + JSON.stringify({\n      method: 'POST', url: '/api/auth/login', status: res.status(),\n      requestBody: { email: process.env.TEST_USER_EMAIL!, password: '[REDACTED]' },\n      responseBody: body,\n    }));\n    expect(res.status()).toBe(200);\n    token = body.access_token; // \u2190 adapt to your API (e.g. body.token, body.jwt)\n  });\n  test('get profile', async ({ request }) => {\n    const res = await request.get('/api/users/profile', {\n      headers: { Authorization: `Bearer ${token}` }\n    });\n    const body = await res.json();\n    console.log('__QA_HTTP__:' + JSON.stringify({\n      method: 'GET', url: '/api/users/profile', status: res.status(),\n      responseBody: body,\n    }));\n    expect(res.status()).toBe(200);\n  });\n});",
           apiEndpointMapping: `// After reading an Express route handler like:
 // router.post('/api/auth/login', async (req, res) => { ... })
@@ -934,24 +1139,10 @@ server.resource(
     responseShapes: { "200": { "token": "string", "user": "object" }, "401": { "error": "string" } }
   }]
 }`,
-          uiWithMilestones: `test('Feature \u2014 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" \u2014 a test that only checks goto + heading visible is nearly worthless',
+          'Test actual user flows, not just "page loads" - a test that only checks goto + heading visible is nearly worthless',
           "Test form submission: fill fields, submit, verify success/redirect",
           "Test validation: leave required fields empty, enter invalid data, verify error messages",
           "Test error states: wrong password, expired session, invalid IDs",
@@ -960,14 +1151,14 @@ server.resource(
         ],
         securityAudit: {
           workflow: "After creating UI tests for a feature, call run_security_audit to analyze captured API traffic for auth issues, data exposure, and vulnerabilities.",
-          prerequisite: 'Requires prior browser-based test execution (the auto-verification run from create_test counts). If run_security_audit errors about missing data, tell the developer to click "Security Audit" in the Tests dropdown on the Dashboard \u2014 this launches a live browser to capture real network traffic (HAR) and runs analysis automatically.',
+          prerequisite: 'Requires prior browser-based test execution (the auto-verification run from create_test counts). If run_security_audit errors about missing data, tell the developer to click "Security Audit" in the Tests dropdown on the Dashboard - this launches a live browser to capture real network traffic (HAR) and runs analysis automatically.',
           reviewing: "Use list_security_findings to review results. Filter by severity (critical/high/medium/low/info) or status (open/acknowledged/resolved/false-positive). Critical and high findings should be flagged to the developer immediately."
         },
         keyConcepts: {
           features: 'Group related pages and tests (e.g., "Authentication" covers /auth/login, /auth/register). MUST include page routes.',
-          pages: 'Route URLs on a feature \u2014 used for coverage tracking and site map (e.g., ["/login", "/register"])',
-          suites: "Group tests for batch execution \u2014 suite name MUST match feature name exactly (case-sensitive)",
-          runner: "Executes tests \u2014 can be local (developer machine) or cloud",
+          pages: 'Route URLs on a feature - used for coverage tracking and site map (e.g., ["/login", "/register"])',
+          suites: "Group tests for batch execution - suite name MUST match feature name exactly (case-sensitive)",
+          runner: "Executes tests - can be local (developer machine) or cloud",
           testData: "Key-value variables injected into tests (e.g., credentials, URLs)"
         },
         retrievedAt: (/* @__PURE__ */ new Date()).toISOString()