@kamleshsk/claude-qa 1.0.1

package/templates/commands/qa-setup.md

@@ -0,0 +1,2990 @@
+---
+description: Bootstrap the QA e2e automation framework in this project from scratch
+allowed-tools: Bash, Read, Write
+---
+
+You are setting up the QA automation framework. This command is idempotent — it checks whether
+each file already exists before writing, so it is safe to re-run.
+
+Execute every numbered step below in order. Do not skip any step. Do not stop to ask questions.
+Track the status of each file (written / skipped / failed) and print the verification table at the end.
+
+---
+
+## STRICT SCOPE RULES — Read before doing anything
+
+You are ONLY allowed to:
+- Create brand new files that do not exist yet
+- Append a new route group to `routes/web.php` (QA routes only — add at the end, touch nothing else in the file)
+- Append new script entries and devDependency entries to `package.json` (merge only — do not reformat or remove anything)
+- Create `database/seeders/QAUserSeeder.php` if it does not exist
+
+You are STRICTLY FORBIDDEN from:
+- Modifying any existing controller, model, view, middleware, or service that is not inside `app/Http/Controllers/QA/`, `resources/views/qa/`, or `app/Http/Middleware/` (QA middleware only)
+- Touching any existing route in `routes/web.php` — only append the QA group at the bottom
+- Modifying any existing Blade template including `layouts/`, `welcome.blade.php`, any auth views, or any landing page
+- Changing any existing navigation, menu, header, footer, or sidebar
+- Removing, renaming, or reformatting anything that already exists in any file
+- Touching `bootstrap/app.php` beyond adding the `qa.auth` middleware alias — do not change any other middleware, exception handler, or routing configuration
+- Running `php artisan migrate` — only create migration files if columns are missing; the developer runs migrations manually
+- Touching `composer.json` or `composer.lock`
+
+If anything outside this scope seems necessary, note it as a warning in the verification table and stop — do not make the change.
+
+---
+
+## Step 1 — Read the environment
+
+Read `.env`. Extract:
+- `APP_URL` — use it if present; otherwise note that `http://127.0.0.1:8000` will be the default
+- All keys matching `QA_<ROLE>_EMAIL` — each one represents a role this project will test
+- `QA_EMAIL`/`QA_PASSWORD` as a fallback if no `QA_<ROLE>_EMAIL` keys are present
+
+Print a status summary:
+```
+APP_URL:    http://... (found) OR not set — will default to http://127.0.0.1:8000
+QA roles found:  <list every QA_<ROLE>_EMAIL key found, e.g. QA_ADMIN_EMAIL, QA_MANAGER_EMAIL>
+                 OR: only QA_EMAIL found — will map to 'admin' role slot
+                 OR: NONE — add QA_<ROLE>_EMAIL + QA_<ROLE>_PASSWORD to .env before running tests
+```
+
+---
+
+## Step 2 — Create directory structure
+
+```bash
+mkdir -p tests/e2e/js/modules tests/e2e/artifacts scripts
+```
+
+---
+
+## Step 3 — Write framework files
+
+For EACH file below:
+1. Run `test -f <path> && echo EXISTS || echo MISSING` to check current state
+2. If the file does not exist → write it with the content shown
+3. If the file already exists → skip (do not overwrite)
+4. Note the outcome (WRITTEN / SKIPPED) for the final table
+
+---
+
+### `tests/e2e/js/config.js`
+
+```javascript
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { config as dotenvConfig } from 'dotenv';
+import { existsSync } from 'fs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+
+export function load() {
+  const envPath = resolve(ROOT, '.env');
+  if (!existsSync(envPath)) {
+    throw new Error(
+      `.env not found at ${envPath}\n` +
+      'Copy .env.example → .env and fill in QA_EMAIL / QA_PASSWORD.'
+    );
+  }
+
+  dotenvConfig({ path: envPath });
+
+  const baseUrl = (process.env.APP_URL || 'http://127.0.0.1:8000').replace(/\/$/, '');
+
+  // Scan env for all QA_<ROLE>_EMAIL entries and build a credentials map.
+  // Supports any number of roles: QA_ADMIN_EMAIL, QA_DOCTOR_EMAIL, QA_MANAGER_EMAIL, etc.
+  const credentials = {};
+  for (const [key, val] of Object.entries(process.env)) {
+    const m = key.match(/^QA_([A-Z][A-Z0-9_]*)_EMAIL$/);
+    if (m && val) {
+      const roleKey = m[1].toLowerCase();
+      credentials[roleKey] = {
+        email:    val,
+        password: process.env[`QA_${m[1]}_PASSWORD`] || '',
+      };
+    }
+  }
+
+  // Backward-compat: plain QA_EMAIL → admin credential slot (if not already set by QA_ADMIN_EMAIL)
+  if (!credentials.admin && (process.env.QA_EMAIL || process.env.SUPER_ADMIN_EMAIL)) {
+    credentials.admin = {
+      email:    process.env.QA_EMAIL    || process.env.SUPER_ADMIN_EMAIL    || '',
+      password: process.env.QA_PASSWORD || process.env.SUPER_ADMIN_PASSWORD || '',
+    };
+  }
+
+  if (Object.keys(credentials).length === 0) {
+    throw new Error(
+      'No QA credentials found. Add at least one role to .env:\n' +
+      '  QA_<ROLE>_EMAIL=qa-role@example.local\n' +
+      '  QA_<ROLE>_PASSWORD=Password@1\n' +
+      'Pattern: QA_<ROLE>_EMAIL / QA_<ROLE>_PASSWORD for each role.'
+    );
+  }
+
+  return { base_url: baseUrl, credentials };
+}
+```
+
+---
+
+### `tests/e2e/js/runner.js`
+
+```javascript
+import { mkdirSync } from 'fs';
+import { resolve } from 'path';
+
+export const sleep = ms => new Promise(res => setTimeout(res, ms));
+
+export class TestRunner {
+  constructor(page, config, artifactDir, jsonMode = false) {
+    this.page        = page;
+    this.config      = config;
+    this.artifactDir = artifactDir;
+    this.jsonMode    = jsonMode;
+    this.results     = [];
+    mkdirSync(artifactDir, { recursive: true });
+  }
+
+  async step(description, fn) {
+    const start = Date.now();
+    if (this.jsonMode) {
+      process.stdout.write(JSON.stringify({ type: 'step_start', description }) + '\n');
+    }
+    try {
+      await fn();
+      const elapsed = (Date.now() - start) / 1000;
+      if (this.jsonMode) {
+        process.stdout.write(JSON.stringify({
+          type: 'step', status: 'pass', description, elapsed: +elapsed.toFixed(2),
+        }) + '\n');
+      } else {
+        const dots = '.'.repeat(Math.max(1, 52 - description.length));
+        console.log(`  \x1b[32m✅\x1b[0m ${description} ${dots} ${elapsed.toFixed(1)}s`);
+      }
+      this.results.push({ status: 'pass', description, duration: +((Date.now() - start) / 1000).toFixed(2) });
+    } catch (err) {
+      const elapsed = (Date.now() - start) / 1000;
+      const shot = await this.screenshot(`${this.results.length + 1}-fail`);
+      const msg = err?.message || String(err);
+      if (this.jsonMode) {
+        process.stdout.write(JSON.stringify({
+          type: 'step', status: 'fail', description, elapsed: +elapsed.toFixed(2), error: msg,
+        }) + '\n');
+      } else {
+        console.log(`  \x1b[31m❌\x1b[0m ${description}`);
+        console.log(`       \x1b[90m└─ ${msg}\x1b[0m`);
+        console.log(`       \x1b[90m└─ Screenshot: ${shot}\x1b[0m`);
+      }
+      this.results.push({ status: 'fail', description, duration: +elapsed.toFixed(2), error: msg, screenshot: shot });
+    }
+  }
+
+  skip(description, reason) {
+    if (this.jsonMode) {
+      process.stdout.write(JSON.stringify({ type: 'step', status: 'skip', description, reason }) + '\n');
+    } else {
+      console.log(`  \x1b[33m⏭️ \x1b[0m ${description} — skipped: ${reason}`);
+    }
+    this.results.push({ status: 'skip', description, reason });
+  }
+
+  async screenshot(name) {
+    const path = resolve(this.artifactDir, `${name}.png`);
+    try { await this.page.screenshot({ path }); } catch { /* ignore */ }
+    return path;
+  }
+
+  async login(role = 'admin') {
+    const roleKey = role.toLowerCase();
+    const creds   = this.config.credentials?.[roleKey];
+
+    if (!creds?.email || !creds?.password) {
+      const envKey = role.toUpperCase();
+      throw new Error(
+        `QA credentials for role '${role}' not set. Add to .env:\n` +
+        `  QA_${envKey}_EMAIL=qa-${roleKey}@example.local\n` +
+        `  QA_${envKey}_PASSWORD=Password@1`
+      );
+    }
+
+    // URL pattern after successful login — override per role via env:
+    //   QA_<ROLE>_URL_PATTERN=**/admin**
+    // Falls back to '**/<rolename>**' if not set.
+    const envKey = role.toUpperCase();
+    const urlPattern = process.env[`QA_${envKey}_URL_PATTERN`] || `**/${roleKey}**`;
+
+    await this.page.goto(`${this.config.base_url}/login`);
+    await this.page.fill("[name='email']", creds.email);
+    await this.page.fill("[name='password']", creds.password);
+    // [type="submit"] is more reliable than accessible-name matching when the app
+    // applies CSS text-transform (e.g. Tailwind "uppercase") — the browser accessibility
+    // tree may return the visual "LOG IN" instead of the source "Log in", making
+    // case-insensitive regex matching silently fail in certain Chromium versions.
+    await this.page.locator('[type="submit"]').first().click();
+    await this.page.waitForURL(urlPattern, { timeout: 10_000 });
+  }
+
+  assertUrlContains(fragment) {
+    if (!this.page.url().includes(fragment)) {
+      throw new Error(`URL ${this.page.url()} does not contain ${fragment}`);
+    }
+  }
+
+  async assertVisible(text, timeout = 6000) {
+    await this.page
+      .locator("body *:not([id^='phpdebugbar']):not([class*='phpdebugbar'])")
+      .filter({ hasText: text })
+      .first()
+      .waitFor({ state: 'visible', timeout });
+  }
+
+  async assertToast(fragment = null, timeout = 6000) {
+    const loc = this.page.locator(
+      "[id^='flash-'], [id^='notification-'], " +    // id-based flash (e.g. flash-success)
+      ".flash, .flash-message, " +                    // class-based flash
+      ".alert, .toast, [role='alert'], " +
+      ".swal2-popup .swal2-title, " +
+      ".swal2-toast .swal2-title, " +
+      ".toastr, #toast-container .toast-message"
+    ).first();
+    await loc.waitFor({ state: 'visible', timeout });
+    if (fragment) {
+      const content = await loc.textContent() || '';
+      if (!content.toLowerCase().includes(fragment.toLowerCase())) {
+        throw new Error(`Toast ${JSON.stringify(content)} does not contain ${JSON.stringify(fragment)}`);
+      }
+    }
+  }
+
+  async assertRowExists(text, timeout = 6000) {
+    await this.page.locator(`table td:has-text('${text}')`).first().waitFor({ state: 'visible', timeout });
+  }
+
+  async assertRowGone(text, timeout = 4000) {
+    try {
+      await this.page.locator(`table td:has-text('${text}')`).first().waitFor({ state: 'hidden', timeout });
+    } catch {
+      const count = await this.page.locator(`table td:has-text('${text}')`).count();
+      if (count !== 0) throw new Error(`Row with text "${text}" still visible in table`);
+    }
+  }
+}
+```
+
+---
+
+### `tests/e2e/js/report.js`
+
+```javascript
+import { writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+export function write(results, artifactDir, duration, module, angle) {
+  const passed  = results.filter(r => r.status === 'pass').length;
+  const failed  = results.filter(r => r.status === 'fail').length;
+  const skipped = results.filter(r => r.status === 'skip').length;
+  const ts = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+  const lines = [
+    '# QA Report',
+    '',
+    `**Module:** ${module}  `,
+    `**Angle:** ${angle}  `,
+    `**Run at:** ${ts}  `,
+    `**Duration:** ${duration.toFixed(1)}s  `,
+    '',
+    '| | Count |',
+    '|---|---|',
+    `| ✅ Passed | ${passed} |`,
+    `| ❌ Failed | ${failed} |`,
+    `| ⏭️ Skipped | ${skipped} |`,
+    `| **Total** | **${results.length}** |`,
+    '',
+    '## Assertions',
+    '',
+  ];
+
+  const icons = { pass: '✅', fail: '❌', skip: '⏭️' };
+  for (const r of results) {
+    lines.push(`${icons[r.status]} ${r.description}`);
+    if (r.status === 'fail') {
+      lines.push(`   - Error: \`${r.error || '—'}\``);
+      if (r.screenshot) lines.push(`   - Screenshot: \`${r.screenshot}\``);
+    } else if (r.status === 'skip') {
+      lines.push(`   - Reason: ${r.reason || '—'}`);
+    }
+  }
+
+  writeFileSync(resolve(artifactDir, 'report.md'), lines.join('\n'));
+  writeFileSync(resolve(artifactDir, 'summary.json'), JSON.stringify({
+    timestamp: ts,
+    module,
+    angle,
+    duration: +duration.toFixed(2),
+    passed,
+    failed,
+    skipped,
+    total: results.length,
+    results,
+  }, null, 2));
+
+  return { passed, failed, skipped };
+}
+```
+
+---
+
+### `tests/e2e/js/main.js`
+
+```javascript
+#!/usr/bin/env node
+import { createInterface } from 'readline/promises';
+import { execSync } from 'child_process';
+import { mkdirSync } from 'fs';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import { chromium } from 'playwright';
+
+import { load as loadConfig } from './config.js';
+import { write as writeReport } from './report.js';
+import { TestRunner } from './runner.js';
+import { MODULE_MAP, MODULE_LABELS, ANGLE_MAP } from './modules/index.js';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+
+function ts() {
+  const d = new Date();
+  return (
+    String(d.getFullYear()) +
+    String(d.getMonth() + 1).padStart(2, '0') +
+    String(d.getDate()).padStart(2, '0') + '_' +
+    String(d.getHours()).padStart(2, '0') +
+    String(d.getMinutes()).padStart(2, '0') +
+    String(d.getSeconds()).padStart(2, '0')
+  );
+}
+
+async function preflight(config) {
+  console.log('\nPre-flight checks...');
+  let ok = false;
+  try {
+    const res = await fetch(`${config.base_url}/login`, { signal: AbortSignal.timeout(5000) });
+    ok = res.ok || res.status === 302;
+  } catch { /* ignore */ }
+  if (!ok) {
+    console.log(`  ✗  Laravel server not responding on ${config.base_url}`);
+    console.log('     Run: php artisan serve --port=8000');
+    process.exit(1);
+  }
+  console.log(`  ✓  Laravel server responding on ${config.base_url}`);
+  try {
+    const dirty = execSync('git status --porcelain', { cwd: ROOT, stdio: 'pipe' }).toString().trim();
+    if (dirty) console.log('  ⚠  Working tree has uncommitted changes (continuing anyway)');
+  } catch { /* ignore */ }
+  console.log();
+}
+
+async function picker() {
+  const entries = Object.entries(MODULE_MAP).filter(([k]) => !/^\d+$/.test(k));
+  const allNum  = entries.length + 1;
+
+  let display = '\n  QA — pick your test\n\n';
+  display += '  Module         Angles (default=all)    Mode (default=headed)\n';
+  display += '  ──────         ────────────────────    ─────────────────────\n';
+  entries.forEach(([name], i) => {
+    const label = (MODULE_LABELS[name] ?? name.charAt(0).toUpperCase() + name.slice(1)).padEnd(15);
+    let row = `  ${i + 1} ${label}`;
+    if (i === 0)      row += 'a  Happy path           h  Headed  ← default';
+    else if (i === 1) row += 'b  Validation           x  Headless';
+    else if (i === 2) row += 'c  Hierarchy & UI';
+    display += row + '\n';
+  });
+  display += `  ${allNum} ALL\n\n  Press Enter for defaults.\n`;
+  console.log(display);
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const raw = await rl.question('  Your choice: ');
+  rl.close();
+  return raw.trim().split(/\s+/).filter(Boolean);
+}
+
+function parse(tokens) {
+  const modTok   = tokens[0] ?? null;
+  const angleTok = tokens[1] ?? 'all';
+  const modeTok  = tokens[2] ?? 'h';
+
+  const namedModules = Object.entries(MODULE_MAP).filter(([k]) => !/^\d+$/.test(k));
+  const allNumber    = String(namedModules.length + 1);
+
+  let modules;
+  if (modTok === allNumber || modTok === 'all') {
+    modules = namedModules;
+  } else {
+    if (!(modTok in MODULE_MAP)) {
+      console.error(`Unknown module: ${JSON.stringify(modTok)}. Options: ${namedModules.map(([k]) => k).join(', ')}`);
+      process.exit(1);
+    }
+    const mod     = MODULE_MAP[modTok];
+    const nameKey = namedModules.find(([k, v]) => v === mod)?.[0] ?? modTok;
+    modules = [[nameKey, mod]];
+  }
+
+  const angle  = ANGLE_MAP[angleTok] ?? 'all';
+  const headed = ['h', 'headed'].includes(modeTok.toLowerCase());
+  return { modules, angle, headed };
+}
+
+async function runModule(modName, mod, angle, headed, config, runTs, jsonMode = false) {
+  const label = MODULE_LABELS[modName] ?? modName.charAt(0).toUpperCase() + modName.slice(1);
+  const anglesToRun = angle === 'all' ? Object.keys(mod.ANGLES) : [angle];
+  const allResults = [];
+
+  for (const ang of anglesToRun) {
+    if (!(ang in mod.ANGLES)) {
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify({ type: 'warn', message: `Angle '${ang}' not in ${modName}` }) + '\n');
+      } else {
+        console.log(`  ⚠  Angle '${ang}' not defined in ${modName} — skipping`);
+      }
+      continue;
+    }
+
+    const artifactDir = resolve(ROOT, 'tests', 'e2e', 'artifacts', runTs, modName, ang);
+    mkdirSync(artifactDir, { recursive: true });
+
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({ type: 'angle_start', module: modName, angle: ang, label }) + '\n');
+    } else {
+      console.log(`\n\x1b[1m[${label} · ${ang.charAt(0).toUpperCase() + ang.slice(1)} path]\x1b[0m`);
+    }
+
+    const browser = await chromium.launch({ headless: !headed, slowMo: headed ? 400 : 0 });
+    const page = await browser.newPage();
+    await page.setViewportSize({ width: 1280, height: 800 });
+    page.setDefaultTimeout(12_000);
+
+    const runner = new TestRunner(page, config, artifactDir, jsonMode);
+    const t0 = Date.now();
+    try {
+      await mod.ANGLES[ang](runner);
+    } catch (err) {
+      const msg = err?.message || String(err);
+      if (jsonMode) {
+        process.stdout.write(JSON.stringify({ type: 'error', message: `Uncaught: ${msg}` }) + '\n');
+      } else {
+        console.log(`  \x1b[31m💥 Uncaught: ${msg}\x1b[0m`);
+      }
+      await runner.screenshot('uncaught');
+    }
+    const duration = (Date.now() - t0) / 1000;
+    await browser.close();
+
+    writeReport(runner.results, artifactDir, duration, label, ang);
+
+    const angPassed  = runner.results.filter(r => r.status === 'pass').length;
+    const angFailed  = runner.results.filter(r => r.status === 'fail').length;
+    const angSkipped = runner.results.filter(r => r.status === 'skip').length;
+
+    if (jsonMode) {
+      process.stdout.write(JSON.stringify({
+        type: 'angle_done', module: modName, angle: ang,
+        passed: angPassed, failed: angFailed, skipped: angSkipped,
+      }) + '\n');
+    }
+
+    allResults.push(...runner.results);
+  }
+
+  return allResults;
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const jsonMode    = args.includes('--json');
+  const headedFlag  = args.includes('--headed');
+  const baseUrlArg  = args.find(t => t.startsWith('--base-url='))?.split('=')[1] ?? null;
+  const tokens      = args.filter(t => t !== '--json' && t !== '--headed' && !t.startsWith('--base-url='));
+
+  if (jsonMode) {
+    if (!tokens.length) {
+      process.stdout.write(JSON.stringify({ type: 'error', message: 'No module specified' }) + '\n');
+      process.exit(1);
+    }
+    const config = loadConfig();
+    if (baseUrlArg) config.base_url = baseUrlArg;
+    process.stdout.write(JSON.stringify({ type: 'preflight_ok', url: config.base_url }) + '\n');
+
+    const { modules, angle } = parse(tokens);
+    const runTs = ts();
+    const allResults = [];
+    for (const [modName, mod] of modules) {
+      allResults.push(...await runModule(modName, mod, angle, headedFlag, config, runTs, true));
+    }
+
+    const passed  = allResults.filter(r => r.status === 'pass').length;
+    const failed  = allResults.filter(r => r.status === 'fail').length;
+    const skipped = allResults.filter(r => r.status === 'skip').length;
+    process.stdout.write(JSON.stringify({ type: 'summary', total: allResults.length, passed, failed, skipped }) + '\n');
+    process.exit(failed ? 1 : 0);
+  }
+
+  // ── Normal terminal mode ───────────────────────────────────────────────────
+  let toks = tokens;
+  if (!toks.length) toks = await picker();
+  if (!toks.length) { console.log('No module selected. Exiting.'); process.exit(0); }
+
+  const config = loadConfig();
+  await preflight(config);
+
+  const { modules, angle, headed } = parse(toks);
+  const runTs = ts();
+  const modeLabel = headed ? 'headed' : 'headless';
+  console.log(`\x1b[1mRunning: ${modules.map(([n]) => n).join(' | ')} · ${angle} · ${modeLabel}\x1b[0m`);
+
+  const allResults = [];
+  for (const [modName, mod] of modules) {
+    allResults.push(...await runModule(modName, mod, angle, headed, config, runTs));
+  }
+
+  const passed  = allResults.filter(r => r.status === 'pass').length;
+  const failed  = allResults.filter(r => r.status === 'fail').length;
+  const skipped = allResults.filter(r => r.status === 'skip').length;
+  const artifactRoot = resolve(ROOT, 'tests', 'e2e', 'artifacts', runTs);
+
+  console.log(`
+\x1b[1m─────────────────────────────
+SUMMARY
+─────────────────────────────\x1b[0m
+Total:    ${allResults.length} assertions
+Passed:   ${passed} \x1b[32m✅\x1b[0m
+Failed:   ${failed} \x1b[31m❌\x1b[0m
+Skipped:  ${skipped} \x1b[33m⏭️\x1b[0m
+Artifacts: ${artifactRoot}`);
+
+  if (failed) {
+    console.log('\n\x1b[31m❌ FAILURES:\x1b[0m');
+    for (const r of allResults.filter(r => r.status === 'fail')) {
+      console.log(`  • ${r.description}`);
+      console.log(`    └─ ${r.error || ''}`);
+    }
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  process.exit(1);
+});
+```
+
+---
+
+### `tests/e2e/js/register.js`
+
+```javascript
+#!/usr/bin/env node
+import { createInterface } from 'readline/promises';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+
+const ROOT         = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
+const REGISTRY     = resolve(ROOT, 'tests', 'e2e', 'registry.json');
+const TESTCASES_MD = resolve(ROOT, 'tests', 'e2e', 'TESTCASES.md');
+
+const ANGLES = ['happy', 'validation', 'hierarchy'];
+
+function toLabel(name) {
+  return name.replace(/-/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+}
+
+const STATUS_LABELS = {
+  implemented: '✅  implemented',
+  pending:     '⏳  pending',
+  skipped:     '⏭️   skipped',
+  broken:      '❌  broken',
+};
+
+// ── registry helpers ──────────────────────────────────────────────────────────
+
+function load() {
+  return existsSync(REGISTRY) ? JSON.parse(readFileSync(REGISTRY, 'utf8')) : {};
+}
+
+function save(reg) {
+  writeFileSync(REGISTRY, JSON.stringify(reg, null, 2));
+}
+
+function nextId(reg, module, angle) {
+  const entries = reg[module]?.[angle] ?? [];
+  const nums = entries
+    .map(c => { const m = c.id.match(/-(\d+)$/); return m ? parseInt(m[1]) : null; })
+    .filter(n => n !== null);
+  const next = (nums.length ? Math.max(...nums) : 0) + 1;
+  return `${module}-${angle.slice(0, 3)}-${String(next).padStart(3, '0')}`;
+}
+
+function rebuildMd(reg) {
+  const now = new Date();
+  const dateStr = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')} ${String(now.getHours()).padStart(2, '0')}:${String(now.getMinutes()).padStart(2, '0')}`;
+  const lines = [
+    '# QA Test Cases',
+    '',
+    `_Last updated: ${dateStr}_`,
+    '',
+    '## Running tests',
+    '```bash',
+    './scripts/qa <module> happy        # headless',
+    './scripts/qa <module> happy h      # headed',
+    './scripts/qa all                   # every module',
+    '```',
+    '',
+    '## Managing test cases',
+    '```bash',
+    './scripts/qa-register              # interactive',
+    './scripts/qa-register add <module> happy "Description"',
+    './scripts/qa-register list',
+    './scripts/qa-register status <id> implemented',
+    '```',
+    '',
+  ];
+  for (const module of Object.keys(reg).sort()) {
+    const cases = reg[module] ?? {};
+    if (!ANGLES.some(a => cases[a]?.length)) continue;
+    lines.push(`## ${toLabel(module)}`, '');
+    for (const angle of ANGLES) {
+      const entries = cases[angle] ?? [];
+      if (!entries.length) continue;
+      lines.push(`### ${angle.charAt(0).toUpperCase() + angle.slice(1)} path`, '');
+      for (const c of entries) {
+        const tick = c.status === 'implemented' ? 'x' : ' ';
+        lines.push(`- [${tick}] **${c.id}** — ${c.description}`);
+        if (c.notes) lines.push(`  > _${c.notes}_`);
+      }
+      lines.push('');
+    }
+  }
+  writeFileSync(TESTCASES_MD, lines.join('\n'));
+}
+
+// ── commands ──────────────────────────────────────────────────────────────────
+
+function cmdList(module = null) {
+  const reg = load();
+  const targets = module ? [module] : Object.keys(reg).sort();
+  let found = false;
+  for (const mod of targets) {
+    const cases = reg[mod] ?? {};
+    if (!ANGLES.some(a => cases[a]?.length)) continue;
+    found = true;
+    const total = ANGLES.reduce((s, a) => s + (cases[a]?.length ?? 0), 0);
+    const done  = ANGLES.reduce((s, a) => s + (cases[a]?.filter(c => c.status === 'implemented').length ?? 0), 0);
+    console.log(`\n  \x1b[1m${toLabel(mod)}\x1b[0m  (${done}/${total} implemented)`);
+    for (const angle of ANGLES) {
+      const entries = cases[angle] ?? [];
+      if (!entries.length) continue;
+      console.log(`  ─── ${angle.charAt(0).toUpperCase() + angle.slice(1)} path`);
+      for (const c of entries) {
+        const icon = (STATUS_LABELS[c.status ?? 'pending'] ?? '⏳').slice(0, 2);
+        console.log(`    ${icon}  ${c.id}  ${c.description}`);
+      }
+    }
+  }
+  if (!found) console.log('  No cases registered yet.');
+}
+
+function cmdAdd(module, angle, description, notes = null) {
+  if (!ANGLES.includes(angle)) { console.error(`  Unknown angle '${angle}'. Options: ${ANGLES.join(', ')}`); process.exit(1); }
+  const reg = load();
+  if (!reg[module]) reg[module] = {};
+  if (!reg[module][angle]) reg[module][angle] = [];
+  const cid = nextId(reg, module, angle);
+  const now = new Date();
+  const added = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  const entry = { id: cid, description, status: 'pending', added };
+  if (notes) entry.notes = notes;
+  reg[module][angle].push(entry);
+  save(reg);
+  rebuildMd(reg);
+  console.log(`\n  ✅  Registered \x1b[1m${cid}\x1b[0m`);
+  console.log(`      ${description}`);
+  console.log(`\n  Files updated:`);
+  console.log(`    tests/e2e/registry.json`);
+  console.log(`    tests/e2e/TESTCASES.md`);
+  console.log(`\n  Next steps:`);
+  console.log(`    1. Add function to tests/e2e/js/modules/${module}.js`);
+  console.log(`    2. ./scripts/qa-register status ${cid} implemented`);
+}
+
+function cmdStatus(cid, newStatus) {
+  if (!(newStatus in STATUS_LABELS)) {
+    console.error(`  Unknown status '${newStatus}'. Options: ${Object.keys(STATUS_LABELS).join(', ')}`);
+    process.exit(1);
+  }
+  const reg = load();
+  for (const module of Object.keys(reg)) {
+    for (const angle of Object.keys(reg[module])) {
+      for (const c of reg[module][angle]) {
+        if (c.id === cid) {
+          const old = c.status ?? '—';
+          c.status = newStatus;
+          save(reg);
+          rebuildMd(reg);
+          console.log(`\n  ✅  ${cid}  ${old} → ${newStatus}`);
+          return;
+        }
+      }
+    }
+  }
+  console.error(`  Case ID '${cid}' not found.`);
+  process.exit(1);
+}
+
+// ── interactive helpers ───────────────────────────────────────────────────────
+
+async function pick(rl, prompt, options, labels = null, allowAll = false) {
+  const display = labels ?? options;
+  if (allowAll) console.log('  0  All');
+  display.forEach((label, i) => console.log(`  ${i + 1}  ${label}`));
+  while (true) {
+    const raw = (await rl.question(`\n  ${prompt}: `)).trim();
+    if (allowAll && raw === '0') return null;
+    const idx = parseInt(raw) - 1;
+    if (!isNaN(idx) && idx >= 0 && idx < options.length) return options[idx];
+    console.log('  Invalid choice — try again.');
+  }
+}
+
+async function ask(rl, prompt, defaultVal = null) {
+  const suffix = defaultVal ? ` [${defaultVal}]` : '';
+  const raw = (await rl.question(`  ${prompt}${suffix}: `)).trim();
+  return raw || defaultVal;
+}
+
+// ── interactive flows ─────────────────────────────────────────────────────────
+
+async function interactiveList(rl) {
+  const reg  = load();
+  const mods = Object.keys(reg).sort();
+  if (!mods.length) { console.log('\n  No modules registered yet. Add a test case first.'); return; }
+  console.log('\n  Filter by module:\n  ──────────────────');
+  const module = await pick(rl, 'Module (0=All)', mods, mods.map(toLabel), true);
+  console.log();
+  cmdList(module);
+}
+
+async function interactiveAdd(rl) {
+  const reg      = load();
+  const existing = Object.keys(reg).sort();
+  let module;
+  if (existing.length) {
+    console.log('\n  Module (pick existing or type a new name):\n  ──────────────────────────────────────────');
+    existing.forEach((m, i) => console.log(`  ${i + 1}  ${toLabel(m)}`));
+    console.log('  n  New module name');
+    while (true) {
+      const raw = (await rl.question('\n  Module: ')).trim();
+      const idx = parseInt(raw) - 1;
+      if (!isNaN(idx) && idx >= 0 && idx < existing.length) { module = existing[idx]; break; }
+      if (raw && raw !== 'n') { module = raw.toLowerCase().replace(/\s+/g, '-'); break; }
+      if (raw === 'n') {
+        module = (await rl.question('  New module name: ')).trim().toLowerCase().replace(/\s+/g, '-');
+        break;
+      }
+      console.log('  Invalid — try again.');
+    }
+  } else {
+    module = (await rl.question('\n  Module name: ')).trim().toLowerCase().replace(/\s+/g, '-');
+  }
+  if (!module) { console.log('  Module name required.'); return; }
+  console.log('\n  Angle:\n  ──────\n  1  Happy path\n  2  Validation / edge cases\n  3  Hierarchy & UI logic');
+  const angle = await pick(rl, 'Angle', ANGLES, ['Happy path', 'Validation', 'Hierarchy']);
+  console.log();
+  const description = await ask(rl, 'Description (what does this test verify)');
+  if (!description) { console.log('  Description required.'); return; }
+  const notes = await ask(rl, 'Notes (optional, press Enter to skip)', '');
+  console.log();
+  cmdAdd(module, angle, description, notes || null);
+}
+
+async function interactiveStatus(rl) {
+  const reg = load();
+  const allCases = [];
+  for (const mod of Object.keys(reg)) {
+    for (const ang of ANGLES) {
+      for (const c of reg[mod]?.[ang] ?? []) allCases.push(c);
+    }
+  }
+  if (!allCases.length) { console.log('  No cases registered yet.'); return; }
+  console.log('\n  Select a case:\n');
+  allCases.forEach((c, i) => {
+    const icon = (STATUS_LABELS[c.status ?? 'pending'] ?? '⏳').slice(0, 2);
+    console.log(`  ${String(i + 1).padStart(2)}  ${icon}  ${c.id}  ${c.description}`);
+  });
+  let chosen;
+  while (true) {
+    const raw = (await rl.question('\n  Case number: ')).trim();
+    const idx = parseInt(raw) - 1;
+    if (!isNaN(idx) && idx >= 0 && idx < allCases.length) { chosen = allCases[idx]; break; }
+    console.log('  Invalid — try again.');
+  }
+  console.log(`\n  New status for \x1b[1m${chosen.id}\x1b[0m:\n  ${'─'.repeat(35)}`);
+  const newStatus = await pick(rl, 'Status', Object.keys(STATUS_LABELS), Object.values(STATUS_LABELS));
+  console.log();
+  cmdStatus(chosen.id, newStatus);
+}
+
+async function interactive() {
+  console.log(`
+\x1b[1mQA — Test Registry\x1b[0m
+
+  1  List cases
+  2  Add new case
+  3  Update case status
+  4  Exit
+`);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  while (true) {
+    const raw = (await rl.question('  Choose: ')).trim();
+    if (raw === '1') { await interactiveList(rl); break; }
+    else if (raw === '2') { await interactiveAdd(rl); break; }
+    else if (raw === '3') { await interactiveStatus(rl); break; }
+    else if (raw === '4' || raw === 'q' || raw === '') break;
+    else console.log('  Invalid — enter 1, 2, 3, or 4.');
+  }
+  rl.close();
+  console.log();
+}
+
+// ── entry ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (!args.length) { await interactive(); return; }
+
+  const cmd = args[0];
+  if (cmd === 'list') {
+    cmdList(args[1] ?? null);
+  } else if (cmd === 'add' || cmd === 'register') {
+    if (args.length < 4) { console.error('Usage: register add <module> <angle> <description>'); process.exit(1); }
+    cmdAdd(args[1], args[2], args[3], args[4] ?? null);
+  } else if (cmd === 'status') {
+    if (args.length < 3) { console.error('Usage: register status <id> <new-status>'); process.exit(1); }
+    cmdStatus(args[1], args[2]);
+  } else {
+    // Shorthand: qa-register <module> <angle> <description>
+    if (args.length < 3) { console.error(`  Usage: qa-register <module> <angle> "<description>"\n  Or run with no args for interactive mode.`); process.exit(1); }
+    cmdAdd(args[0], args[1], args[2], args[3] ?? null);
+  }
+}
+
+main().catch(err => { console.error(err); process.exit(1); });
+
+---
+
+### `scripts/qa`
+
+```bash
+#!/usr/bin/env bash
+# QA — terminal test runner
+#
+# Usage (from project root):
+#   ./scripts/qa                           # interactive picker
+#   ./scripts/qa <module>                  # all angles, headed
+#   ./scripts/qa <module> happy            # single angle, headed
+#   ./scripts/qa <module> happy h          # headed
+#   ./scripts/qa 1 a h                     # shorthand
+#   ./scripts/qa all                       # every module
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+exec node "$ROOT/tests/e2e/js/main.js" "$@"
+```
+
+---
+
+### `scripts/qa-register`
+
+```bash
+#!/usr/bin/env bash
+# QA — register / list test cases
+#
+# Add a new test case:
+#   ./scripts/qa-register <module> happy "Description of what this tests"
+#
+# List all cases:
+#   ./scripts/qa-register list
+#   ./scripts/qa-register list <module>
+#
+# Update a case status:
+#   ./scripts/qa-register status <module>-hap-001 implemented
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+exec node "$ROOT/tests/e2e/js/register.js" "$@"
+```
+
+---
+
+### `tests/e2e/js/modules/index.js`   ← SKIP IF FILE ALREADY EXISTS
+
+Only write this file if it does not already exist. Existing module registrations must never be overwritten.
+
+```javascript
+// ── Add module imports here as /qa creates them ───────────────────────────────
+// import * as <feature> from './<feature>.js';
+
+export const MODULE_MAP = {
+  // <feature>, '1': <feature>,
+};
+
+export const MODULE_LABELS = {
+  // <feature>: '<Feature Label>', '1': '<Feature Label>',
+};
+
+export const ANGLE_MAP = {
+  a: 'happy',       happy:      'happy',
+  b: 'validation',  validation: 'validation',
+  c: 'hierarchy',   hierarchy:  'hierarchy',
+  all: 'all',
+};
+```
+
+---
+
+## Step 3b — Create the QA portal
+
+The QA portal is a standalone web panel at `/qa` — login, dashboard, and live test runner.
+Create these files idempotently (skip if already exists).
+
+First, create the required directories:
+
+```bash
+mkdir -p app/Http/Controllers/QA resources/views/qa
+```
+
+For EACH file below:
+1. Run `test -f <path> && echo EXISTS || echo MISSING`
+2. If MISSING → write it with the content shown
+3. If EXISTS → skip (do not overwrite)
+4. Note the outcome (WRITTEN / SKIPPED) for the final table
+
+---
+
+### `app/Http/Controllers/QA/LoginController.php`
+
+```php
+<?php
+
+namespace App\Http\Controllers\QA;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+
+class LoginController extends Controller
+{
+    public function show()
+    {
+        if (session('qa_authenticated')) {
+            return redirect()->route('qa.index');
+        }
+
+        return view('qa.login');
+    }
+
+    public function login(Request $request)
+    {
+        $request->validate([
+            'email'    => 'required|email',
+            'password' => 'required',
+        ]);
+
+        $validEmail    = env('QA_EMAIL',    '');
+        $validPassword = env('QA_PASSWORD', '');
+
+        if ($request->email === $validEmail && $request->password === $validPassword) {
+            $request->session()->put('qa_authenticated', true);
+            $request->session()->put('qa_email', $request->email);
+            return redirect()->route('qa.index');
+        }
+
+        return back()
+            ->withInput($request->only('email'))
+            ->withErrors(['email' => 'Invalid QA credentials.']);
+    }
+
+    public function logout(Request $request)
+    {
+        $request->session()->forget([
+            'qa_authenticated', 'qa_email',
+            'qa_run_email', 'qa_run_password', 'qa_run_role',
+        ]);
+        return redirect('/');
+    }
+}
+```
+
+---
+
+### `app/Http/Controllers/QA/DashboardController.php`
+
+```php
+<?php
+
+namespace App\Http\Controllers\QA;
+
+use App\Http\Controllers\Controller;
+use App\Models\User;
+use Carbon\Carbon;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Hash;
+
+class DashboardController extends Controller
+{
+    private string $registryPath;
+
+    public function __construct()
+    {
+        $this->registryPath = base_path('tests/e2e/registry.json');
+    }
+
+    public function index()
+    {
+        $raw = file_exists($this->registryPath)
+            ? json_decode(file_get_contents($this->registryPath), true)
+            : [];
+
+        // Discover roles dynamically from the DB — no hardcoding.
+        $availableRoles = $this->discoverRoles();
+        $defaultRole    = $availableRoles[0] ?? '';
+
+        // Build module config dynamically from registry.json keys.
+        $moduleConfig = [];
+        foreach (array_keys($raw) as $key) {
+            $moduleConfig[$key] = [
+                'label' => ucwords(str_replace(['-', '_'], ' ', $key)),
+                'icon'  => 'layers',
+                'role'  => $defaultRole,
+            ];
+        }
+
+        $angleOrder = ['happy', 'validation', 'hierarchy'];
+        $stats      = ['total' => 0, 'implemented' => 0, 'pending' => 0, 'skipped' => 0, 'broken' => 0];
+        $modules    = [];
+
+        foreach ($moduleConfig as $key => $cfg) {
+            $angles = [];
+            $modTotal = $modImplemented = 0;
+
+            foreach ($angleOrder as $angle) {
+                $cases = $raw[$key][$angle] ?? [];
+                if (empty($cases)) {
+                    continue;
+                }
+                $angles[$angle] = $cases;
+                foreach ($cases as $case) {
+                    $status = $case['status'] ?? 'pending';
+                    $modTotal++;
+                    $stats['total']++;
+                    if ($status === 'implemented') {
+                        $modImplemented++;
+                        $stats['implemented']++;
+                    } else {
+                        $stats[$status] = ($stats[$status] ?? 0) + 1;
+                    }
+                }
+            }
+
+            if ($modTotal === 0) {
+                $modules[$key] = [
+                    'label'    => $cfg['label'],
+                    'icon'     => $cfg['icon'],
+                    'role'     => $cfg['role'],
+                    'scaffold' => true,
+                ];
+                continue;
+            }
+
+            $modules[$key] = [
+                'label'       => $cfg['label'],
+                'icon'        => $cfg['icon'],
+                'role'        => $cfg['role'],
+                'angles'      => $angles,
+                'total'       => $modTotal,
+                'implemented' => $modImplemented,
+                'coverage'    => (int) round($modImplemented / $modTotal * 100),
+            ];
+        }
+
+        $stats['coverage'] = $stats['total'] > 0
+            ? (int) round($stats['implemented'] / $stats['total'] * 100)
+            : 0;
+
+        $updatedAt = file_exists($this->registryPath)
+            ? Carbon::createFromTimestamp(filemtime($this->registryPath))->diffForHumans()
+            : 'never';
+
+        $verifiedRole = session('qa_run_role');
+
+        return view('qa.index', compact('modules', 'stats', 'updatedAt', 'verifiedRole', 'availableRoles'));
+    }
+
+    // ── Verify test-account credentials ──────────────────────────────────────
+
+    public function verifyCredentials(Request $request)
+    {
+        $email    = trim((string) $request->input('email', ''));
+        $password = (string) $request->input('password', '');
+        $role     = (string) $request->input('role', '');
+
+        if (! $email || ! $password || ! $role) {
+            return response()->json(['ok' => false, 'message' => 'Email, password, and role are required.'], 422);
+        }
+
+        $user = User::where('email', $email)->first();
+
+        if (! $user || ! Hash::check($password, $user->password)) {
+            return response()->json(['ok' => false, 'message' => 'Credentials do not match any account.'], 401);
+        }
+
+        // Role comparison — adjust the column/property name if your project stores role differently.
+        $userRole = $user->role ?? $user->type ?? null;
+        if ($userRole !== $role) {
+            return response()->json([
+                'ok'      => false,
+                'message' => "Account '{$email}' has role '{$userRole}', not '{$role}'.",
+            ], 403);
+        }
+
+        session([
+            'qa_run_email'    => $email,
+            'qa_run_password' => $password,
+            'qa_run_role'     => $role,
+        ]);
+
+        return response()->json([
+            'ok'      => true,
+            'message' => "Verified as {$email} · {$role}",
+        ]);
+    }
+
+    // ── Role discovery ────────────────────────────────────────────────────────
+
+    private function discoverRoles(): array
+    {
+        try {
+            $roles = DB::table('users')
+                ->select('role')
+                ->whereNotNull('role')
+                ->distinct()
+                ->pluck('role')
+                ->sort()
+                ->values()
+                ->toArray();
+
+            if (! empty($roles)) {
+                return $roles;
+            }
+        } catch (\Throwable $e) {}
+
+        try {
+            $cols = DB::select("SHOW COLUMNS FROM users WHERE Field = 'role'");
+            if (! empty($cols)) {
+                preg_match_all("/'([^']+)'/", $cols[0]->Type ?? '', $m);
+                if (! empty($m[1])) {
+                    return $m[1];
+                }
+            }
+        } catch (\Throwable $e) {}
+
+        return [];
+    }
+}
+```
+
+---
+
+### `app/Http/Controllers/QA/RunController.php`
+
+```php
+<?php
+
+namespace App\Http\Controllers\QA;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\StreamedResponse;
+
+class RunController extends Controller
+{
+    private const VALID_ANGLES = ['happy', 'validation', 'hierarchy', 'all'];
+
+    public function stream(Request $request): StreamedResponse
+    {
+        $module = $request->query('module', '');
+        $angle  = $request->query('angle', 'all');
+        $headed = $request->boolean('headed', false);
+
+        $validModules = $this->getValidModules();
+
+        if (! in_array($module, $validModules, true) || ! in_array($angle, self::VALID_ANGLES, true)) {
+            abort(400, 'Invalid module or angle.');
+        }
+
+        $runEmail    = session('qa_run_email', '');
+        $runPassword = session('qa_run_password', '');
+        $runRole     = session('qa_run_role', '');
+
+        session()->save();
+
+        return new StreamedResponse(function () use ($module, $angle, $headed, $runEmail, $runPassword, $runRole) {
+            set_time_limit(300);
+
+            [$testUrl, $testProc, $testPipes] = $this->startTestServer();
+
+            $script = base_path('tests/e2e/js/main.js');
+
+            $cmd = array_values(array_filter([
+                'node',
+                $script,
+                $module,
+                $angle === 'all' ? null : $angle,
+                '--json',
+                $headed ? '--headed' : null,
+                $testUrl ? "--base-url={$testUrl}" : null,
+            ]));
+
+            $env = $_ENV + $_SERVER;
+            if ($runEmail && $runPassword && $runRole) {
+                $envKey                       = strtoupper($runRole);
+                $env["QA_{$envKey}_EMAIL"]    = $runEmail;
+                $env["QA_{$envKey}_PASSWORD"] = $runPassword;
+            }
+
+            $proc = proc_open($cmd, [
+                0 => ['pipe', 'r'],
+                1 => ['pipe', 'w'],
+                2 => ['pipe', 'w'],
+            ], $pipes, base_path(), $env);
+
+            if (! is_resource($proc)) {
+                $this->emit(['type' => 'error', 'message' => 'Failed to start test runner. Ensure Node.js and Playwright are installed (npm install && npx playwright install chromium).']);
+                $this->stopTestServer($testProc, $testPipes);
+                return;
+            }
+
+            fclose($pipes[0]);
+            stream_set_blocking($pipes[1], false);
+            stream_set_blocking($pipes[2], false);
+
+            $buffer = '';
+
+            while (true) {
+                if (connection_aborted()) {
+                    proc_terminate($proc);
+                    break;
+                }
+
+                $status = proc_get_status($proc);
+                $chunk  = fread($pipes[1], 8192);
+
+                if ($chunk !== false && $chunk !== '') {
+                    $buffer .= $chunk;
+                    while (($pos = strpos($buffer, "\n")) !== false) {
+                        $line   = trim(substr($buffer, 0, $pos));
+                        $buffer = substr($buffer, $pos + 1);
+                        if ($line !== '') {
+                            echo "data: {$line}\n\n";
+                            ob_flush();
+                            flush();
+                        }
+                    }
+                }
+
+                if (! $status['running']) {
+                    $tail = stream_get_contents($pipes[1]);
+                    if ($tail) {
+                        $buffer .= $tail;
+                        while (($pos = strpos($buffer, "\n")) !== false) {
+                            $line   = trim(substr($buffer, 0, $pos));
+                            $buffer = substr($buffer, $pos + 1);
+                            if ($line !== '') {
+                                echo "data: {$line}\n\n";
+                                ob_flush();
+                                flush();
+                            }
+                        }
+                    }
+                    break;
+                }
+
+                usleep(40_000);
+            }
+
+            fclose($pipes[1]);
+            fclose($pipes[2]);
+            proc_close($proc);
+
+            $this->stopTestServer($testProc, $testPipes);
+            $this->emit(['type' => 'stream_end']);
+        }, 200, [
+            'Content-Type'      => 'text/event-stream',
+            'Cache-Control'     => 'no-cache',
+            'X-Accel-Buffering' => 'no',
+            'Connection'        => 'keep-alive',
+        ]);
+    }
+
+    // ── Valid-module list — read dynamically from registry.json ──────────────
+
+    private function getValidModules(): array
+    {
+        $registryPath = base_path('tests/e2e/registry.json');
+        $modules      = [];
+        if (file_exists($registryPath)) {
+            $reg     = json_decode(file_get_contents($registryPath), true);
+            $modules = is_array($reg) ? array_keys($reg) : [];
+        }
+        return array_merge($modules, ['all']);
+    }
+
+    // ── Test-server lifecycle ─────────────────────────────────────────────────
+
+    private function startTestServer(): array
+    {
+        $port = $this->findFreePort(8010, 8030);
+        if ($port === null) {
+            return [null, null, []];
+        }
+
+        $proc = proc_open(
+            [PHP_BINARY, 'artisan', 'serve', '--host=127.0.0.1', "--port={$port}"],
+            [0 => ['pipe', 'r'], 1 => ['pipe', 'w'], 2 => ['pipe', 'w']],
+            $pipes,
+            base_path()
+        );
+
+        if (! is_resource($proc)) {
+            return [null, null, []];
+        }
+
+        $ready = false;
+        for ($i = 0; $i < 50; $i++) {
+            usleep(100_000);
+            $sock = @fsockopen('127.0.0.1', $port, $errno, $errstr, 0.3);
+            if ($sock) {
+                fclose($sock);
+                $ready = true;
+                break;
+            }
+        }
+
+        if (! $ready) {
+            $this->stopTestServer($proc, $pipes);
+            return [null, null, []];
+        }
+
+        return ["http://127.0.0.1:{$port}", $proc, $pipes];
+    }
+
+    private function stopTestServer(mixed $proc, array $pipes): void
+    {
+        if (! is_resource($proc)) {
+            return;
+        }
+        proc_terminate($proc);
+        foreach ($pipes as $p) {
+            if (is_resource($p)) {
+                fclose($p);
+            }
+        }
+        proc_close($proc);
+    }
+
+    private function findFreePort(int $start, int $end): ?int
+    {
+        for ($port = $start; $port <= $end; $port++) {
+            $sock = @fsockopen('127.0.0.1', $port, $errno, $errstr, 0.1);
+            if (! $sock) {
+                return $port;
+            }
+            fclose($sock);
+        }
+        return null;
+    }
+
+    private function emit(array $payload): void
+    {
+        echo 'data: ' . json_encode($payload) . "\n\n";
+        ob_flush();
+        flush();
+    }
+}
+```
+
+---
+
+### `resources/views/qa/login.blade.php`
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>QA Portal</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.css" rel="stylesheet">
+    <style>
+        *, *::before, *::after { box-sizing: border-box; }
+        html, body {
+            margin: 0; height: 100%;
+            font-family: 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
+            background: #f1f5f9;
+            color: #1e293b;
+            -webkit-font-smoothing: antialiased;
+        }
+        body {
+            display: flex;
+            align-items: center;
+            justify-content: center;
+            min-height: 100vh;
+            padding: 1.5rem;
+        }
+
+        .qa-card {
+            background: #fff;
+            border-radius: 16px;
+            box-shadow: 0 8px 32px rgba(15,23,42,.10);
+            width: 100%;
+            max-width: 420px;
+            padding: 2.5rem 2.25rem 2rem;
+        }
+
+        .qa-brand {
+            display: flex;
+            align-items: center;
+            gap: .55rem;
+            margin-bottom: 1.75rem;
+        }
+        .qa-brand .badge {
+            font-size: .62rem;
+            font-weight: 700;
+            letter-spacing: .08em;
+            text-transform: uppercase;
+            background: rgba(115,103,240,.1);
+            color: #7367f0;
+            border-radius: 6px;
+            padding: .2rem .5rem;
+        }
+        .qa-brand .qa-icon {
+            width: 32px; height: 32px;
+            background: rgba(115,103,240,.1);
+            border-radius: 8px;
+            display: flex; align-items: center; justify-content: center;
+            color: #7367f0; font-size: 1rem;
+        }
+        .qa-brand .qa-title {
+            font-size: 1.1rem; font-weight: 700; color: #0f172a; letter-spacing: -.01em;
+        }
+
+        h1 {
+            font-size: 1.35rem;
+            font-weight: 700;
+            margin: 0 0 .25rem;
+            color: #0f172a;
+        }
+        .qa-sub { font-size: .88rem; color: #64748b; margin: 0 0 1.5rem; }
+
+        .field { display: flex; flex-direction: column; gap: .35rem; margin-bottom: .9rem; }
+        .field-label { font-size: .83rem; font-weight: 500; color: #1e293b; }
+
+        .input-wrap {
+            display: flex;
+            align-items: center;
+            background: #fff;
+            border: 1px solid #e2e8f0;
+            border-radius: 10px;
+            transition: border-color .15s, box-shadow .15s;
+        }
+        .input-wrap:hover { border-color: #cbd5e1; }
+        .input-wrap:focus-within {
+            border-color: #7367f0;
+            box-shadow: 0 0 0 4px rgba(115,103,240,.12);
+        }
+        .input-wrap.is-invalid { border-color: #ef4444; }
+        .input-wrap.is-invalid:focus-within { box-shadow: 0 0 0 4px rgba(239,68,68,.12); }
+        .input-wrap .lead-icon {
+            padding: 0 .5rem 0 .9rem;
+            color: #94a3b8;
+            font-size: 1rem;
+            pointer-events: none;
+            transition: color .2s;
+        }
+        .input-wrap:focus-within .lead-icon { color: #7367f0; }
+        .input-wrap input {
+            flex: 1; border: 0; outline: none; background: transparent;
+            font: inherit; font-size: .92rem; color: #0f172a;
+            padding: .78rem .9rem .78rem .35rem; min-width: 0;
+        }
+        .input-wrap input::placeholder { color: #94a3b8; }
+        .input-wrap input:-webkit-autofill,
+        .input-wrap input:-webkit-autofill:hover,
+        .input-wrap input:-webkit-autofill:focus {
+            -webkit-box-shadow: 0 0 0 1000px #fff inset !important;
+            -webkit-text-fill-color: #0f172a !important;
+        }
+        .input-wrap .trail-btn {
+            appearance: none; background: transparent; border: 0;
+            color: #94a3b8; padding: 0 .9rem; cursor: pointer;
+            font-size: 1rem; display: inline-flex; align-items: center;
+            transition: color .15s;
+        }
+        .input-wrap .trail-btn:hover { color: #475569; }
+
+        .field-error { font-size: .76rem; color: #dc2626; margin: 0; }
+
+        .submit-btn {
+            width: 100%; border: 0; cursor: pointer; color: #fff;
+            font: inherit; font-size: .95rem; font-weight: 600;
+            padding: .85rem 1rem; border-radius: 10px; margin-top: .5rem;
+            background: linear-gradient(135deg, #7367f0 0%, #9e95f5 100%);
+            box-shadow: 0 4px 14px rgba(115,103,240,.35);
+            transition: transform .2s, box-shadow .2s, filter .2s;
+        }
+        .submit-btn:hover {
+            transform: translateY(-1px);
+            box-shadow: 0 8px 20px rgba(115,103,240,.4);
+            filter: brightness(1.05);
+        }
+        .submit-btn:active { transform: none; }
+
+        .qa-footer {
+            margin-top: 1.5rem;
+            text-align: center;
+            font-size: .75rem;
+            color: #94a3b8;
+        }
+    </style>
+</head>
+<body>
+    <div class="qa-card">
+
+        <div class="qa-brand">
+            <div class="qa-icon"><i class="bi bi-clipboard2-check"></i></div>
+            <span class="qa-title">QA Portal</span>
+            <span class="badge">beta</span>
+        </div>
+
+        <h1>Sign in</h1>
+        <p class="qa-sub">Enter your QA credentials to access the test registry.</p>
+
+        <form method="POST" action="{{ route('qa.login') }}" novalidate>
+            @csrf
+
+            <div class="field">
+                <label for="email" class="field-label">Email</label>
+                <div class="input-wrap @error('email') is-invalid @enderror">
+                    <span class="lead-icon"><i class="bi bi-envelope"></i></span>
+                    <input id="email" name="email" type="email" autocomplete="email"
+                           placeholder="your@email.com" value="{{ old('email') }}" />
+                </div>
+                @error('email')
+                    <p class="field-error">{{ $message }}</p>
+                @enderror
+            </div>
+
+            <div class="field">
+                <label for="password" class="field-label">Password</label>
+                <div class="input-wrap @error('password') is-invalid @enderror">
+                    <span class="lead-icon"><i class="bi bi-lock"></i></span>
+                    <input id="password" name="password" type="password"
+                           autocomplete="current-password" placeholder="Your QA password" />
+                    <button type="button" class="trail-btn" aria-label="Toggle password"
+                            onclick="
+                                const p=document.getElementById('password');
+                                const i=this.querySelector('i');
+                                p.type=p.type==='password'?'text':'password';
+                                i.classList.toggle('bi-eye');
+                                i.classList.toggle('bi-eye-slash');
+                            ">
+                        <i class="bi bi-eye-slash"></i>
+                    </button>
+                </div>
+                @error('password')
+                    <p class="field-error">{{ $message }}</p>
+                @enderror
+            </div>
+
+            <button type="submit" class="submit-btn">Sign in to QA Portal</button>
+        </form>
+
+        <p class="qa-footer">QA Portal &mdash; Internal use only</p>
+    </div>
+</body>
+</html>
+```
+
+---
+
+### `resources/views/qa/index.blade.php`
+
+Write this file only if it does not already exist. The content is lengthy — write it exactly as shown below (do not truncate).
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>QA Registry</title>
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.css" rel="stylesheet">
+    <script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js"></script>
+    <style>
+        *, *::before, *::after { box-sizing: border-box; }
+        html, body {
+            margin: 0;
+            font-family: 'Inter', ui-sans-serif, system-ui, -apple-system, sans-serif;
+            background: #f1f5f9;
+            color: #1e293b;
+            -webkit-font-smoothing: antialiased;
+        }
+        .qa-topbar {
+            background: #fff; border-bottom: 1px solid #e8eaed;
+            padding: 0 2rem; height: 58px;
+            display: flex; align-items: center; justify-content: space-between;
+            position: sticky; top: 0; z-index: 100;
+            box-shadow: 0 1px 4px rgba(15,23,42,.05);
+        }
+        .qa-topbar-left { display: flex; align-items: center; gap: .6rem; }
+        .qa-topbar-icon {
+            width: 30px; height: 30px; background: rgba(115,103,240,.1);
+            border-radius: 7px; display: flex; align-items: center; justify-content: center;
+            color: #7367f0; font-size: .95rem;
+        }
+        .qa-topbar-title { font-size: 1rem; font-weight: 700; color: #0f172a; letter-spacing: -.01em; }
+        .qa-badge {
+            font-size: .6rem; font-weight: 700; letter-spacing: .1em; text-transform: uppercase;
+            background: rgba(115,103,240,.1); color: #7367f0; border-radius: 5px; padding: .15rem .45rem;
+        }
+        .qa-topbar-right { display: flex; align-items: center; gap: 1rem; font-size: .82rem; color: #64748b; }
+        .qa-topbar-right .qa-user { display: flex; align-items: center; gap: .4rem; }
+        .qa-logout-btn {
+            appearance: none; background: transparent; border: 1px solid #e2e8f0;
+            color: #64748b; font: inherit; font-size: .78rem;
+            padding: .3rem .75rem; border-radius: 6px; cursor: pointer;
+            display: flex; align-items: center; gap: .35rem;
+            transition: border-color .15s, color .15s, background .15s;
+        }
+        .qa-logout-btn:hover { border-color: #cbd5e1; color: #1e293b; background: #f8fafc; }
+        .qa-page { max-width: 1060px; margin: 0 auto; padding: 2rem 1.5rem 8rem; }
+        .qa-page-heading {
+            display: flex; align-items: flex-start; justify-content: space-between;
+            gap: 1rem; margin-bottom: 1.5rem; flex-wrap: wrap;
+        }
+        .qa-page-heading h1 { font-size: 1.35rem; font-weight: 700; margin: 0 0 .2rem; color: #0f172a; }
+        .qa-header-meta { display: flex; align-items: center; gap: .45rem; font-size: .8rem; color: #94a3b8; }
+        .qa-header-meta i { width: 13px; height: 13px; flex-shrink: 0; }
+        .btn-run {
+            display: inline-flex; align-items: center; gap: .35rem;
+            appearance: none; border: 1px solid #7367f0; background: transparent;
+            color: #7367f0; font: inherit; font-size: .75rem; font-weight: 600;
+            padding: .3rem .75rem; border-radius: 6px; cursor: pointer;
+            transition: background .15s, color .15s; white-space: nowrap;
+        }
+        .btn-run:hover:not(:disabled) { background: #7367f0; color: #fff; }
+        .btn-run:disabled { opacity: .38; cursor: not-allowed; border-color: #cbd5e1; color: #94a3b8; }
+        .btn-run i { width: 13px; height: 13px; }
+        .btn-run-primary {
+            display: inline-flex; align-items: center; gap: .45rem;
+            appearance: none; border: 0; background: #7367f0; color: #fff;
+            font: inherit; font-size: .82rem; font-weight: 600;
+            padding: .5rem 1.1rem; border-radius: 8px; cursor: pointer;
+            transition: filter .15s, transform .1s;
+            box-shadow: 0 2px 8px rgba(115,103,240,.3);
+        }
+        .btn-run-primary:hover:not(:disabled) { filter: brightness(1.08); transform: translateY(-1px); }
+        .btn-run-primary:disabled { opacity: .38; cursor: not-allowed; box-shadow: none; transform: none; background: #94a3b8; }
+        .btn-run-primary i { width: 15px; height: 15px; }
+        .qa-creds-panel {
+            background: #fff; border: 1px solid #e8eaed; border-radius: 12px;
+            box-shadow: 0 1px 4px rgba(15,23,42,.04); margin-bottom: 1.25rem;
+            overflow: hidden; transition: border-color .2s;
+        }
+        .qa-creds-panel.is-verified { border-color: rgba(40,199,111,.35); background: #f0fdf6; }
+        .qa-creds-header {
+            display: flex; align-items: center; gap: .6rem;
+            padding: .7rem 1.25rem; border-bottom: 1px solid #f1f5f9;
+            background: #fafbfc; cursor: pointer; user-select: none;
+        }
+        .qa-creds-panel.is-verified .qa-creds-header { background: #f0fdf6; border-bottom-color: rgba(40,199,111,.15); }
+        .qa-creds-header-icon { width: 16px; height: 16px; color: #7367f0; flex-shrink: 0; }
+        .qa-creds-panel.is-verified .qa-creds-header-icon { color: #28c76f; }
+        .qa-creds-header-label { font-size: .85rem; font-weight: 700; color: #0f172a; flex: 1; }
+        .qa-creds-verified-badge {
+            display: none; align-items: center; gap: .4rem;
+            font-size: .78rem; font-weight: 600; color: #28c76f;
+        }
+        .qa-creds-panel.is-verified .qa-creds-verified-badge { display: flex; }
+        .qa-creds-lock-hint {
+            font-size: .75rem; color: #ff9f43; font-weight: 600;
+            display: flex; align-items: center; gap: .3rem;
+        }
+        .qa-creds-panel.is-verified .qa-creds-lock-hint { display: none; }
+        .qa-creds-chevron {
+            width: 16px; height: 16px; color: #94a3b8;
+            transition: transform .22s ease; flex-shrink: 0;
+        }
+        .qa-creds-panel.collapsed .qa-creds-chevron { transform: rotate(-90deg); }
+        .qa-creds-body {
+            overflow: hidden; transition: max-height .3s ease, opacity .25s ease;
+            max-height: 220px; opacity: 1;
+        }
+        .qa-creds-panel.collapsed .qa-creds-body { max-height: 0; opacity: 0; }
+        .qa-creds-inner {
+            display: grid; grid-template-columns: 160px 1fr 1fr auto;
+            gap: .75rem; align-items: end; padding: 1rem 1.25rem;
+        }
+        @media (max-width: 700px) {
+            .qa-creds-inner { grid-template-columns: 1fr 1fr; }
+            .qa-creds-inner .qa-verify-btn { grid-column: 1 / -1; }
+        }
+        .qa-creds-field { display: flex; flex-direction: column; gap: .3rem; }
+        .qa-creds-field label { font-size: .76rem; font-weight: 600; color: #475569; }
+        .qa-creds-select, .qa-creds-input {
+            height: 36px; border: 1px solid #e2e8f0; border-radius: 8px;
+            font: inherit; font-size: .84rem; color: #0f172a;
+            padding: 0 .75rem; background: #fff; outline: none;
+            transition: border-color .15s, box-shadow .15s; width: 100%;
+        }
+        .qa-creds-select:focus, .qa-creds-input:focus {
+            border-color: #7367f0; box-shadow: 0 0 0 3px rgba(115,103,240,.12);
+        }
+        .qa-creds-select { appearance: none; background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='%2394a3b8' stroke-width='2'%3E%3Cpolyline points='6 9 12 15 18 9'/%3E%3C/svg%3E"); background-repeat: no-repeat; background-position: right .65rem center; padding-right: 2rem; }
+        .qa-verify-btn {
+            height: 36px; appearance: none; border: 0; cursor: pointer;
+            background: #7367f0; color: #fff; font: inherit; font-size: .82rem; font-weight: 600;
+            padding: 0 1.25rem; border-radius: 8px;
+            display: inline-flex; align-items: center; gap: .4rem;
+            transition: filter .15s, transform .1s; white-space: nowrap;
+            box-shadow: 0 2px 6px rgba(115,103,240,.28);
+        }
+        .qa-verify-btn:hover { filter: brightness(1.08); transform: translateY(-1px); }
+        .qa-verify-btn:disabled { opacity: .6; cursor: not-allowed; transform: none; }
+        .qa-verify-btn i { width: 14px; height: 14px; }
+        .qa-creds-msg {
+            padding: 0 1.25rem .9rem; font-size: .78rem; font-weight: 500;
+            display: none; align-items: center; gap: .4rem;
+        }
+        .qa-creds-msg.visible { display: flex; }
+        .qa-creds-msg.error { color: #ea5455; }
+        .qa-creds-msg.success { color: #28c76f; }
+        .qa-kpi-row { display: grid; grid-template-columns: repeat(4, 1fr); gap: 1rem; margin-bottom: 1.5rem; }
+        @media (max-width: 768px) { .qa-kpi-row { grid-template-columns: repeat(2, 1fr); } }
+        .qa-kpi {
+            background: #fff; border-radius: 12px; border: 1px solid #e8eaed;
+            padding: 1.1rem 1.25rem; display: flex; align-items: center;
+            gap: .9rem; box-shadow: 0 1px 4px rgba(15,23,42,.04);
+        }
+        .qa-kpi-icon {
+            width: 42px; height: 42px; border-radius: 10px;
+            display: flex; align-items: center; justify-content: center; flex-shrink: 0;
+        }
+        .qa-kpi-icon i { width: 20px; height: 20px; }
+        .qa-kpi-icon--primary { background: rgba(115,103,240,.1); color: #7367f0; }
+        .qa-kpi-icon--success { background: rgba(40,199,111,.1);  color: #28c76f; }
+        .qa-kpi-icon--warning { background: rgba(255,159,67,.1);  color: #ff9f43; }
+        .qa-kpi-icon--danger  { background: rgba(234,84,85,.1);   color: #ea5455; }
+        .qa-kpi-value { font-size: 1.5rem; font-weight: 700; line-height: 1.1; color: #0f172a; }
+        .qa-kpi-label { font-size: .75rem; color: #94a3b8; margin-top: .15rem; }
+        .qa-module-card {
+            background: #fff; border: 1px solid #e8eaed; border-radius: 12px;
+            box-shadow: 0 1px 4px rgba(15,23,42,.04); margin-bottom: 1rem; overflow: hidden;
+        }
+        .qa-module-header {
+            padding: .75rem 1.25rem; display: flex; align-items: center; gap: .55rem;
+            border-bottom: 1px solid #f1f5f9; background: #fafbfc; flex-wrap: wrap;
+            cursor: pointer; user-select: none;
+        }
+        .qa-module-header:hover { background: #f4f6f8; }
+        .qa-module-header h5 { font-size: .95rem; font-weight: 700; margin: 0; flex: 1; color: #0f172a; }
+        .qa-module-header > i.mod-icon { width: 17px; height: 17px; color: #7367f0; flex-shrink: 0; }
+        .qa-collapse-chevron {
+            width: 18px; height: 18px; color: #94a3b8; flex-shrink: 0;
+            transition: transform .22s ease; margin-left: .1rem;
+        }
+        .qa-module-card.collapsed .qa-collapse-chevron { transform: rotate(-90deg); }
+        .qa-module-card.collapsed .qa-module-header { border-bottom-color: transparent; }
+        .qa-module-body {
+            overflow: hidden; transition: max-height .28s ease, opacity .2s ease;
+            max-height: 2000px; opacity: 1;
+        }
+        .qa-module-card.collapsed .qa-module-body { max-height: 0; opacity: 0; }
+        .btn-collapse-all {
+            appearance: none; background: transparent; border: 1px solid #e2e8f0; color: #64748b;
+            font: inherit; font-size: .75rem; font-weight: 600;
+            padding: .35rem .8rem; border-radius: 6px; cursor: pointer;
+            display: inline-flex; align-items: center; gap: .3rem;
+            transition: border-color .15s, color .15s, background .15s; white-space: nowrap;
+        }
+        .btn-collapse-all:hover { border-color: #cbd5e1; color: #0f172a; background: #f8fafc; }
+        .btn-collapse-all i { width: 13px; height: 13px; }
+        .qa-progress-wrap { display: flex; align-items: center; gap: .45rem; }
+        .qa-progress { width: 72px; height: 5px; border-radius: 99px; background: #e8eaed; overflow: hidden; }
+        .qa-progress-bar { height: 100%; border-radius: 99px; }
+        .qa-progress-bar--success { background: #28c76f; }
+        .qa-progress-bar--warning { background: #ff9f43; }
+        .qa-progress-bar--danger  { background: #ea5455; }
+        .qa-coverage-pct { font-size: .7rem; font-weight: 700; color: #64748b; min-width: 28px; }
+        .qa-impl-badge {
+            font-size: .7rem; font-weight: 600; border-radius: 6px;
+            padding: .2rem .5rem; white-space: nowrap;
+            background: rgba(115,103,240,.08); color: #7367f0;
+        }
+        .qa-impl-badge--done { background: rgba(40,199,111,.1); color: #28c76f; }
+        .qa-angle-section { border-top: 1px solid #f1f5f9; }
+        .qa-angle-section:first-child { border-top: none; }
+        .qa-angle-header {
+            display: flex; align-items: center; gap: .45rem;
+            padding: .5rem 1.25rem .45rem; background: rgba(241,245,249,.5);
+        }
+        .qa-angle-header i { width: 12px; height: 12px; color: #94a3b8; }
+        .qa-angle-label {
+            font-size: .68rem; font-weight: 700; letter-spacing: .06em;
+            text-transform: uppercase; color: #64748b; flex: 1;
+        }
+        .qa-angle-count { font-size: .7rem; color: #94a3b8; margin-right: .5rem; }
+        .qa-case-table { width: 100%; border-collapse: collapse; margin: 0; }
+        .qa-case-table td {
+            padding: .55rem 1.25rem; vertical-align: middle;
+            border-bottom: 1px solid #f8fafc; font-size: .875rem;
+        }
+        .qa-case-table tbody tr:last-child td { border-bottom: none; }
+        .qa-case-table tbody tr:hover { background: rgba(115,103,240,.025); }
+        .qa-case-id {
+            font-family: 'SFMono-Regular', Consolas, monospace; font-size: .7rem;
+            color: #7367f0; background: rgba(115,103,240,.08);
+            padding: .15rem .4rem; border-radius: 4px; white-space: nowrap;
+        }
+        .qa-case-desc { color: #334155; }
+        .qa-case-notes { font-size: .73rem; color: #94a3b8; font-style: italic; }
+        .qa-status {
+            font-size: .7rem; font-weight: 600; padding: .22rem .55rem;
+            border-radius: 6px; white-space: nowrap;
+        }
+        .qa-status--implemented { background: rgba(40,199,111,.1);  color: #28c76f; }
+        .qa-status--pending     { background: rgba(255,159,67,.1);  color: #ff9f43; }
+        .qa-status--skipped     { background: rgba(115,103,240,.1); color: #7367f0; }
+        .qa-status--broken      { background: rgba(234,84,85,.1);   color: #ea5455; }
+        .qa-mode-seg {
+            display: inline-flex; border: 1px solid #e2e8f0; border-radius: 8px;
+            overflow: hidden; background: #fff; box-shadow: 0 1px 3px rgba(15,23,42,.06);
+        }
+        .qa-mode-btn {
+            appearance: none; background: transparent; border: none;
+            border-right: 1px solid #e2e8f0; color: #64748b;
+            font: inherit; font-size: .75rem; font-weight: 600;
+            padding: .38rem .85rem; cursor: pointer;
+            display: flex; align-items: center; gap: .3rem;
+            transition: background .15s, color .15s; white-space: nowrap;
+        }
+        .qa-mode-btn:last-child { border-right: none; }
+        .qa-mode-btn:hover:not(.active) { background: #f8fafc; color: #0f172a; }
+        .qa-mode-btn.active { background: #7367f0; color: #fff; }
+        .qa-mode-btn i { width: 12px; height: 12px; }
+        .qa-run-card {
+            background: #fff; border: 1px solid #e8eaed; border-radius: 12px;
+            box-shadow: 0 1px 4px rgba(15,23,42,.04); margin-bottom: 1rem; overflow: hidden;
+        }
+        .qa-run-card .card-header {
+            padding: .75rem 1.25rem; display: flex; align-items: center; gap: .5rem;
+            border-bottom: 1px solid #f1f5f9; background: #fafbfc;
+        }
+        .qa-run-card .card-header h5 { font-size: .95rem; font-weight: 700; margin: 0; color: #0f172a; }
+        .qa-run-card .card-header i { width: 17px; height: 17px; color: #7367f0; }
+        .qa-run-card .card-body { padding: 1rem 1.25rem; }
+        .qa-terminal-static {
+            background: #1e1e2e; border-radius: 8px; padding: 1rem 1.2rem;
+            font-family: 'SFMono-Regular', Consolas, monospace; font-size: .78rem;
+            line-height: 1.8; color: #cdd6f4; overflow-x: auto; margin: 0;
+        }
+        .t-comment { color: #6c7086; }
+        .t-cmd     { color: #89dceb; }
+        .t-arg     { color: #a6e3a1; }
+        .t-flag    { color: #f5c2e7; }
+        .qa-empty { text-align: center; padding: 3.5rem 1rem; color: #94a3b8; }
+        .qa-empty i { width: 48px; height: 48px; opacity: .25; margin: 0 auto .75rem; display: block; }
+        .qa-module-card--scaffold { border-style: dashed; border-color: #e2e8f0; opacity: .72; }
+        .qa-module-card--scaffold .qa-module-header { background: #f8fafc; }
+        .qa-module-card--scaffold .qa-module-header h5 { color: #94a3b8; }
+        .qa-scaffold-body { padding: 1rem 1.25rem; }
+        .qa-skeleton-row {
+            height: 11px; border-radius: 5px; margin-bottom: .6rem;
+            background: linear-gradient(90deg, #f1f5f9 25%, #e2e8f0 50%, #f1f5f9 75%);
+            background-size: 600px 100%; animation: qa-shimmer 1.6s ease-in-out infinite;
+        }
+        .qa-skeleton-row:last-child { margin-bottom: 0; width: 60%; }
+        @keyframes qa-shimmer {
+            0%   { background-position: -600px 0; }
+            100% { background-position:  600px 0; }
+        }
+        .qa-scaffold-hint {
+            margin-top: .85rem; font-size: .75rem; color: #94a3b8;
+            display: flex; align-items: center; gap: .35rem;
+        }
+        .qa-scaffold-hint code {
+            font-family: 'SFMono-Regular', Consolas, monospace;
+            background: #f1f5f9; color: #7367f0;
+            padding: .1rem .35rem; border-radius: 4px; font-size: .72rem;
+        }
+        .qa-live-panel {
+            position: fixed; bottom: 0; left: 0; right: 0; height: 340px;
+            background: #0f1117; border-top: 2px solid #7367f0;
+            display: flex; flex-direction: column; z-index: 200;
+            transform: translateY(100%); transition: transform .3s cubic-bezier(.2,.8,.2,1);
+            box-shadow: 0 -8px 32px rgba(0,0,0,.35);
+        }
+        .qa-live-panel.open { transform: translateY(0); }
+        .qa-live-panel__head {
+            display: flex; align-items: center; gap: .75rem;
+            padding: .65rem 1.25rem; border-bottom: 1px solid rgba(255,255,255,.07); flex-shrink: 0;
+        }
+        .qa-live-panel__spinner {
+            width: 14px; height: 14px; border: 2px solid rgba(115,103,240,.3);
+            border-top-color: #7367f0; border-radius: 50%;
+            animation: spin .7s linear infinite; flex-shrink: 0; display: none;
+        }
+        .qa-live-panel__spinner.active { display: block; }
+        @keyframes spin { to { transform: rotate(360deg); } }
+        .qa-live-panel__title {
+            flex: 1; font-size: .82rem; font-weight: 600;
+            color: #cdd6f4; font-family: 'SFMono-Regular', Consolas, monospace;
+        }
+        .qa-live-panel__actions { display: flex; align-items: center; gap: .5rem; }
+        .qa-panel-btn {
+            appearance: none; background: transparent; border: 1px solid rgba(255,255,255,.12);
+            color: #6c7086; font: inherit; font-size: .72rem; font-weight: 600;
+            padding: .25rem .6rem; border-radius: 5px; cursor: pointer;
+            transition: border-color .15s, color .15s;
+        }
+        .qa-panel-btn:hover { border-color: rgba(255,255,255,.25); color: #cdd6f4; }
+        .qa-panel-btn--close { font-size: .85rem; padding: .2rem .55rem; }
+        .qa-live-panel__resize {
+            position: absolute; top: -4px; left: 0; right: 0; height: 8px;
+            cursor: ns-resize; z-index: 10;
+        }
+        .qa-live-panel__summary {
+            display: none; align-items: center; gap: 1.25rem;
+            padding: .5rem 1.25rem; border-top: 1px solid rgba(255,255,255,.07);
+            font-family: 'SFMono-Regular', Consolas, monospace;
+            font-size: .76rem; flex-shrink: 0; background: rgba(255,255,255,.03);
+        }
+        .qa-live-panel__summary.visible { display: flex; }
+        .sum-pass { color: #28c76f; }
+        .sum-fail { color: #ea5455; }
+        .sum-skip { color: #ff9f43; }
+        .sum-label { color: #6c7086; font-size: .7rem; margin-left: auto; }
+        .qa-live-panel__output {
+            flex: 1; overflow-y: auto; overflow-x: auto; padding: .75rem 1.25rem;
+            font-family: 'SFMono-Regular', Consolas, monospace;
+            font-size: .78rem; line-height: 1.7; scroll-behavior: smooth;
+        }
+        .qa-live-panel__output::-webkit-scrollbar { width: 5px; }
+        .qa-live-panel__output::-webkit-scrollbar-track { background: transparent; }
+        .qa-live-panel__output::-webkit-scrollbar-thumb { background: rgba(255,255,255,.1); border-radius: 3px; }
+        .log-line { display: flex; align-items: baseline; gap: .6rem; padding: .05rem 0; }
+        .log-line--info     .log-text { color: #89dceb; }
+        .log-line--heading  .log-text { color: #cba6f7; font-weight: 700; }
+        .log-line--pass     .log-text { color: #a6e3a1; }
+        .log-line--fail     .log-text { color: #f38ba8; }
+        .log-line--skip     .log-text { color: #fab387; }
+        .log-line--error    .log-text { color: #f38ba8; font-weight: 600; }
+        .log-line--running  .log-text { color: #89dceb; font-style: italic; }
+        .log-line--summary  .log-text { color: #cdd6f4; }
+        .log-icon { font-size: .9rem; flex-shrink: 0; width: 16px; text-align: center; }
+        .log-text { flex: 1; }
+        .log-time { color: #45475a; font-size: .7rem; flex-shrink: 0; margin-left: auto; padding-left: .5rem; }
+        .log-line--running .log-icon::after {
+            content: ''; display: inline-block; width: 6px; height: 6px;
+            background: #89dceb; border-radius: 50%;
+            animation: pulse 1s ease-in-out infinite; vertical-align: middle;
+        }
+        @keyframes pulse { 0%, 100% { opacity: 1; } 50% { opacity: .3; } }
+        .qa-role-empty {
+            background: #fff; border: 1px solid #e8eaed; border-radius: 12px;
+            text-align: center; padding: 3rem 1rem; color: #94a3b8; display: none;
+        }
+        .qa-role-empty.visible { display: block; }
+        .qa-role-empty p { font-size: .88rem; margin: .4rem 0 0; }
+    </style>
+</head>
+<body>
+
+    <header class="qa-topbar">
+        <div class="qa-topbar-left">
+            <div class="qa-topbar-icon"><i class="bi bi-clipboard2-check"></i></div>
+            <span class="qa-topbar-title">QA Portal</span>
+            <span class="qa-badge">beta</span>
+        </div>
+        <div class="qa-topbar-right">
+            <span class="qa-user">
+                <i class="bi bi-person-circle"></i>
+                {{ session('qa_email', 'QA') }}
+            </span>
+            <form method="POST" action="{{ route('qa.logout') }}" style="margin:0">
+                @csrf
+                <button type="submit" class="qa-logout-btn">
+                    <i class="bi bi-box-arrow-right"></i> Sign out
+                </button>
+            </form>
+        </div>
+    </header>
+
+    <main class="qa-page">
+
+        <div class="qa-page-heading">
+            <div>
+                <h1>Test Registry</h1>
+                <div class="qa-header-meta">
+                    <i data-feather="refresh-cw"></i>
+                    Registry last updated <strong>{{ $updatedAt }}</strong>
+                    &nbsp;&middot;&nbsp;
+                    <i data-feather="file-text"></i>
+                    <span>tests/e2e/registry.json</span>
+                </div>
+            </div>
+            <div style="display:flex; align-items:center; gap:.65rem; flex-wrap:wrap;">
+                <button class="btn-collapse-all" id="collapseAllBtn" onclick="QACards.toggleAll()">
+                    <i data-feather="chevrons-up" id="collapseAllIcon"></i>
+                    <span id="collapseAllLabel">Collapse All</span>
+                </button>
+                <div class="qa-mode-seg" id="qaModeToggle">
+                    <button class="qa-mode-btn active" id="modeHeadless"
+                            onclick="QARunner.setMode('headless')"
+                            title="Console only — runs in background, output streams here">
+                        <i data-feather="terminal"></i> Console only
+                    </button>
+                    <button class="qa-mode-btn" id="modeHeaded"
+                            onclick="QARunner.setMode('headed')"
+                            title="Browser + Console — opens a visible browser on this machine">
+                        <i data-feather="monitor"></i> Browser + Console
+                    </button>
+                </div>
+                <button class="btn-run-primary qa-run-gated" disabled
+                        title="Verify test credentials first"
+                        id="btnRunAll"
+                        onclick="QARunner.run('all', 'all', 'Run All Modules')">
+                    <i data-feather="play"></i> Run All
+                </button>
+            </div>
+        </div>
+
+        <div class="qa-creds-panel {{ $verifiedRole ? 'is-verified collapsed' : '' }}" id="qaCredsPanel">
+            <div class="qa-creds-header" onclick="QACreds.togglePanel()">
+                <i class="qa-creds-header-icon" data-feather="{{ $verifiedRole ? 'shield' : 'lock' }}"></i>
+                <span class="qa-creds-header-label">Test Account Credentials</span>
+                <span class="qa-creds-verified-badge">
+                    <i class="bi bi-check-circle-fill"></i>
+                    <span id="qaVerifiedLabel">{{ $verifiedRole ? 'Verified · ' . session('qa_run_email') . ' · ' . $verifiedRole : '' }}</span>
+                </span>
+                <span class="qa-creds-lock-hint">
+                    <i class="bi bi-exclamation-circle"></i>
+                    Verify to unlock run buttons
+                </span>
+                <i class="qa-creds-chevron" data-feather="chevron-down"></i>
+            </div>
+            <div class="qa-creds-body">
+                <div class="qa-creds-inner">
+                    <div class="qa-creds-field">
+                        <label for="qaCredsRole">Role</label>
+                        <select id="qaCredsRole" class="qa-creds-select"
+                                onchange="QACreds.onRoleChange(this.value)">
+                            @forelse ($availableRoles as $availRole)
+                                <option value="{{ $availRole }}"
+                                        {{ ($verifiedRole ?? $availableRoles[0] ?? '') === $availRole ? 'selected' : '' }}>
+                                    {{ ucfirst(strtolower($availRole)) }}
+                                </option>
+                            @empty
+                                <option value="" disabled>No roles found in DB</option>
+                            @endforelse
+                        </select>
+                    </div>
+                    <div class="qa-creds-field">
+                        <label for="qaCredsEmail">Email</label>
+                        <input type="email" id="qaCredsEmail" class="qa-creds-input"
+                               placeholder="qa@example.com"
+                               value="{{ session('qa_run_email', '') }}" />
+                    </div>
+                    <div class="qa-creds-field">
+                        <label for="qaCredsPassword">Password</label>
+                        <input type="password" id="qaCredsPassword" class="qa-creds-input"
+                               placeholder="Password"
+                               value="{{ session('qa_run_password', '') }}" />
+                    </div>
+                    <button class="qa-verify-btn" id="qaVerifyBtn" onclick="QACreds.verify()">
+                        <i data-feather="shield"></i>
+                        Verify
+                    </button>
+                </div>
+                <div class="qa-creds-msg" id="qaCredsMsg"></div>
+            </div>
+        </div>
+
+        <div class="qa-kpi-row">
+            <div class="qa-kpi">
+                <div class="qa-kpi-icon qa-kpi-icon--primary"><i data-feather="list"></i></div>
+                <div><div class="qa-kpi-value">{{ $stats['total'] }}</div><div class="qa-kpi-label">Total Cases</div></div>
+            </div>
+            <div class="qa-kpi">
+                <div class="qa-kpi-icon qa-kpi-icon--success"><i data-feather="check-circle"></i></div>
+                <div><div class="qa-kpi-value">{{ $stats['implemented'] }}</div><div class="qa-kpi-label">Implemented</div></div>
+            </div>
+            <div class="qa-kpi">
+                <div class="qa-kpi-icon qa-kpi-icon--warning"><i data-feather="clock"></i></div>
+                <div><div class="qa-kpi-value">{{ $stats['pending'] ?? 0 }}</div><div class="qa-kpi-label">Pending</div></div>
+            </div>
+            <div class="qa-kpi">
+                @php $covTone = $stats['coverage'] >= 80 ? 'success' : ($stats['coverage'] >= 50 ? 'warning' : 'danger'); @endphp
+                <div class="qa-kpi-icon qa-kpi-icon--{{ $covTone }}"><i data-feather="bar-chart-2"></i></div>
+                <div><div class="qa-kpi-value">{{ $stats['coverage'] }}%</div><div class="qa-kpi-label">Coverage</div></div>
+            </div>
+        </div>
+
+        @php $angleIcons = ['happy' => 'smile', 'validation' => 'shield', 'hierarchy' => 'git-branch']; @endphp
+
+        <div class="qa-role-empty" id="qaRoleEmpty">
+            <i class="bi bi-inbox" style="font-size:2.5rem; opacity:.2"></i>
+            <p id="qaRoleEmptyMsg">No test modules registered for this role yet.</p>
+        </div>
+
+        @forelse ($modules as $modKey => $mod)
+
+        @if (!empty($mod['scaffold']))
+        <div class="qa-module-card qa-module-card--scaffold"
+             id="module-{{ $modKey }}"
+             data-role="{{ $mod['role'] }}">
+            <div class="qa-module-header" onclick="QACards.toggle('module-{{ $modKey }}')">
+                <i class="mod-icon" data-feather="{{ $mod['icon'] }}"></i>
+                <h5>{{ $mod['label'] }}</h5>
+                <span class="qa-impl-badge" style="margin-left:auto">0/0 implemented</span>
+                <button class="btn-run qa-run-gated" disabled
+                        title="Verify test credentials first"
+                        onclick="event.stopPropagation()">
+                    <i data-feather="play"></i> Run Module
+                </button>
+                <i class="qa-collapse-chevron" data-feather="chevron-down"></i>
+            </div>
+            <div class="qa-module-body">
+                <div class="qa-scaffold-body">
+                    <div class="qa-skeleton-row"></div>
+                    <div class="qa-skeleton-row" style="width:80%"></div>
+                    <div class="qa-skeleton-row"></div>
+                    <div class="qa-scaffold-hint">
+                        <i data-feather="plus-circle" style="width:13px;height:13px;flex-shrink:0"></i>
+                        No test cases registered yet —
+                        <code>qar add {{ $modKey }} happy "Description"</code>
+                    </div>
+                </div>
+            </div>
+        </div>
+
+        @else
+        <div class="qa-module-card" id="module-{{ $modKey }}" data-role="{{ $mod['role'] }}">
+            <div class="qa-module-header" onclick="QACards.toggle('module-{{ $modKey }}')">
+                <i class="mod-icon" data-feather="{{ $mod['icon'] }}"></i>
+                <h5>{{ $mod['label'] }}</h5>
+                <div class="qa-progress-wrap">
+                    @php $barTone = $mod['coverage'] >= 80 ? 'success' : ($mod['coverage'] >= 50 ? 'warning' : 'danger'); @endphp
+                    <div class="qa-progress">
+                        <div class="qa-progress-bar qa-progress-bar--{{ $barTone }}" style="width:{{ $mod['coverage'] }}%"></div>
+                    </div>
+                    <span class="qa-coverage-pct">{{ $mod['coverage'] }}%</span>
+                </div>
+                <span class="qa-impl-badge {{ $mod['implemented'] === $mod['total'] ? 'qa-impl-badge--done' : '' }}">
+                    {{ $mod['implemented'] }}/{{ $mod['total'] }} implemented
+                </span>
+                <button class="btn-run qa-run-gated" disabled
+                        title="Verify test credentials first"
+                        onclick="event.stopPropagation(); QARunner.run('{{ $modKey }}', 'all', '{{ $mod['label'] }} — all angles')">
+                    <i data-feather="play"></i> Run Module
+                </button>
+                <i class="qa-collapse-chevron" data-feather="chevron-down"></i>
+            </div>
+            <div class="qa-module-body">
+            @foreach ($mod['angles'] as $angleName => $cases)
+            <div class="qa-angle-section">
+                <div class="qa-angle-header">
+                    <i data-feather="{{ $angleIcons[$angleName] ?? 'circle' }}"></i>
+                    <span class="qa-angle-label">{{ ucfirst($angleName) }} path</span>
+                    <span class="qa-angle-count">{{ count($cases) }} {{ count($cases) === 1 ? 'case' : 'cases' }}</span>
+                    <button class="btn-run qa-run-gated" disabled
+                            title="Verify test credentials first"
+                            onclick="QARunner.run('{{ $modKey }}', '{{ $angleName }}', '{{ $mod['label'] }} / {{ ucfirst($angleName) }} path')">
+                        <i data-feather="play"></i> Run
+                    </button>
+                </div>
+                <div style="overflow-x:auto">
+                    <table class="qa-case-table">
+                        <tbody>
+                            @foreach ($cases as $case)
+                            @php $status = $case['status'] ?? 'pending'; @endphp
+                            <tr>
+                                <td style="width:175px"><span class="qa-case-id">{{ $case['id'] }}</span></td>
+                                <td>
+                                    <span class="qa-case-desc">{{ $case['description'] }}</span>
+                                    @if (!empty($case['notes']))<br><span class="qa-case-notes">{{ $case['notes'] }}</span>@endif
+                                </td>
+                                <td style="width:130px; text-align:right">
+                                    @php $statusIcons = ['implemented'=>'✅','pending'=>'⏳','skipped'=>'⏭️','broken'=>'❌']; @endphp
+                                    <span class="qa-status qa-status--{{ $status }}">{{ $statusIcons[$status] ?? '⏳' }} {{ $status }}</span>
+                                </td>
+                            </tr>
+                            @endforeach
+                        </tbody>
+                    </table>
+                </div>
+            </div>
+            @endforeach
+            </div>
+        </div>
+        @endif
+
+        @empty
+        <div class="qa-module-card">
+            <div class="qa-empty">
+                <i data-feather="inbox"></i>
+                <p style="font-size:.88rem; margin:.25rem 0">No test cases registered yet.</p>
+                <p style="font-size:.82rem; color:#94a3b8"><code>qar add [module] happy "Description"</code> to get started.</p>
+            </div>
+        </div>
+        @endforelse
+
+        <div class="qa-run-card">
+            <div class="card-header">
+                <i data-feather="terminal"></i>
+                <h5>Run from terminal</h5>
+            </div>
+            <div class="card-body">
+                <pre class="qa-terminal-static"><span class="t-cmd">/qa</span>                              <span class="t-comment"># generate a new test module (Claude)</span>
+<span class="t-cmd">qa</span>                               <span class="t-comment"># open QA main menu (terminal)</span>
+<span class="t-cmd">qa</span> <span class="t-arg">[module] happy</span>               <span class="t-comment"># happy path — browser opens (headed)</span>
+<span class="t-cmd">qa</span> <span class="t-arg">[module]</span>                     <span class="t-comment"># all angles</span>
+<span class="t-cmd">qa</span> <span class="t-arg">all</span>                           <span class="t-comment"># every module</span>
+<span class="t-cmd">qa</span> <span class="t-arg">[module] happy</span> <span class="t-flag">x</span>             <span class="t-comment"># headless</span>
+<span class="t-cmd">qar</span>                              <span class="t-comment"># interactive registry menu</span></pre>
+            </div>
+        </div>
+
+    </main>
+
+    <div class="qa-live-panel" id="qaLivePanel">
+        <div class="qa-live-panel__resize" id="qaResizeHandle"></div>
+        <div class="qa-live-panel__head">
+            <div class="qa-live-panel__spinner" id="qaSpinner"></div>
+            <span class="qa-live-panel__title" id="qaPanelTitle">Ready</span>
+            <div class="qa-live-panel__actions">
+                <button class="qa-panel-btn" id="qaClearBtn" onclick="QARunner.clear()">Clear</button>
+                <button class="qa-panel-btn qa-panel-btn--close" onclick="QARunner.close()">✕</button>
+            </div>
+        </div>
+        <div class="qa-live-panel__output" id="qaOutput"></div>
+        <div class="qa-live-panel__summary" id="qaSummaryBar">
+            <span class="sum-pass" id="sumPass">✅ 0 passed</span>
+            <span class="sum-fail" id="sumFail">❌ 0 failed</span>
+            <span class="sum-skip" id="sumSkip">⏭️ 0 skipped</span>
+            <span class="sum-label" id="sumLabel"></span>
+        </div>
+    </div>
+
+    <script>
+    if (typeof feather !== 'undefined') feather.replace();
+
+    const QACreds = (function () {
+        const panel      = document.getElementById('qaCredsPanel');
+        const msg        = document.getElementById('qaCredsMsg');
+        const verifyBtn  = document.getElementById('qaVerifyBtn');
+        const verifyLbl  = document.getElementById('qaVerifiedLabel');
+        const csrfToken  = document.querySelector('meta[name="csrf-token"]')?.content
+                           || '{{ csrf_token() }}';
+
+        let verified = {{ $verifiedRole ? 'true' : 'false' }};
+        if (verified) _enableRunButtons();
+
+        function togglePanel() {
+            panel.classList.toggle('collapsed');
+            if (typeof feather !== 'undefined') feather.replace();
+        }
+
+        function onRoleChange(role) {
+            QAModuleFilter.apply(role);
+        }
+
+        async function verify() {
+            const email    = document.getElementById('qaCredsEmail').value.trim();
+            const password = document.getElementById('qaCredsPassword').value;
+            const role     = document.getElementById('qaCredsRole').value;
+
+            if (!email || !password) {
+                _showMsg('error', '✕  Email and password are required.');
+                return;
+            }
+
+            verifyBtn.disabled = true;
+            verifyBtn.innerHTML = '<span style="display:inline-block;width:14px;height:14px;border:2px solid rgba(255,255,255,.4);border-top-color:#fff;border-radius:50%;animation:spin .7s linear infinite"></span> Verifying…';
+            _showMsg('', '');
+
+            try {
+                const res = await fetch('{{ route("qa.verify") }}', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Accept':       'application/json',
+                        'X-CSRF-TOKEN': csrfToken,
+                    },
+                    body: JSON.stringify({ email, password, role }),
+                });
+
+                const data = await res.json();
+
+                if (data.ok) {
+                    verified = true;
+                    panel.classList.add('is-verified');
+                    if (!panel.classList.contains('collapsed')) panel.classList.add('collapsed');
+                    verifyLbl.textContent = data.message;
+                    _showMsg('success', '✓  ' + data.message);
+                    _enableRunButtons();
+                    QAModuleFilter.apply(role);
+                    if (typeof feather !== 'undefined') feather.replace();
+                } else {
+                    verified = false;
+                    panel.classList.remove('is-verified');
+                    _showMsg('error', '✕  ' + (data.message || 'Verification failed.'));
+                    _disableRunButtons();
+                }
+            } catch (e) {
+                _showMsg('error', '✕  Network error — could not reach verify endpoint.');
+            } finally {
+                verifyBtn.disabled = false;
+                verifyBtn.innerHTML = '<i data-feather="shield"></i> Verify';
+                if (typeof feather !== 'undefined') feather.replace();
+            }
+        }
+
+        function _showMsg(type, text) {
+            msg.className = 'qa-creds-msg' + (type ? ' ' + type + ' visible' : '');
+            msg.textContent = text;
+        }
+
+        function _enableRunButtons() {
+            document.querySelectorAll('.qa-run-gated').forEach(function (btn) {
+                btn.disabled = false;
+                btn.removeAttribute('title');
+            });
+        }
+
+        function _disableRunButtons() {
+            document.querySelectorAll('.qa-run-gated').forEach(function (btn) {
+                btn.disabled = true;
+                btn.title = 'Verify test credentials first';
+            });
+        }
+
+        return { togglePanel, onRoleChange, verify };
+    })();
+
+    const QAModuleFilter = (function () {
+        const emptyState = document.getElementById('qaRoleEmpty');
+        const emptyMsg   = document.getElementById('qaRoleEmptyMsg');
+
+        function apply(role) {
+            const cards = document.querySelectorAll('.qa-module-card[data-role]');
+            let visible = 0;
+            cards.forEach(function (card) {
+                const matches = card.dataset.role === role;
+                card.style.display = matches ? '' : 'none';
+                if (matches) visible++;
+            });
+            if (emptyState) {
+                if (visible === 0) {
+                    emptyState.classList.add('visible');
+                    if (emptyMsg) emptyMsg.textContent =
+                        'No test modules registered for the ' + role + ' role yet. '
+                        + 'Use /qa to generate one.';
+                } else {
+                    emptyState.classList.remove('visible');
+                }
+            }
+        }
+
+        (function init() {
+            const roleEl = document.getElementById('qaCredsRole');
+            if (roleEl) apply(roleEl.value);
+        })();
+
+        return { apply };
+    })();
+
+    const QACards = (function () {
+        let allCollapsed = false;
+
+        function toggle(id) {
+            const card = document.getElementById(id);
+            if (card) card.classList.toggle('collapsed');
+            syncCollapseAllBtn();
+        }
+
+        function toggleAll() {
+            allCollapsed = !allCollapsed;
+            document.querySelectorAll('.qa-module-card').forEach(function (card) {
+                card.classList.toggle('collapsed', allCollapsed);
+            });
+            syncCollapseAllBtn();
+        }
+
+        function syncCollapseAllBtn() {
+            const cards     = document.querySelectorAll('.qa-module-card');
+            const collapsed = document.querySelectorAll('.qa-module-card.collapsed');
+            const icon  = document.getElementById('collapseAllIcon');
+            const label = document.getElementById('collapseAllLabel');
+            if (!icon || !label) return;
+            if (collapsed.length === cards.length) {
+                allCollapsed = true;
+                icon.setAttribute('data-feather', 'chevrons-down');
+                label.textContent = 'Expand All';
+            } else {
+                allCollapsed = false;
+                icon.setAttribute('data-feather', 'chevrons-up');
+                label.textContent = 'Collapse All';
+            }
+            if (typeof feather !== 'undefined') feather.replace();
+        }
+
+        return { toggle, toggleAll };
+    })();
+
+    const QARunner = (function () {
+        const panel      = document.getElementById('qaLivePanel');
+        const output     = document.getElementById('qaOutput');
+        const spinner    = document.getElementById('qaSpinner');
+        const title      = document.getElementById('qaPanelTitle');
+        const summaryBar = document.getElementById('qaSummaryBar');
+        const sumPass    = document.getElementById('sumPass');
+        const sumFail    = document.getElementById('sumFail');
+        const sumSkip    = document.getElementById('sumSkip');
+        const sumLabel   = document.getElementById('sumLabel');
+
+        let source = null;
+        let currentStepEl = null;
+        let currentMode = 'headless';
+
+        function open()  { panel.classList.add('open'); }
+        function close() {
+            if (source) { source.close(); source = null; }
+            panel.classList.remove('open');
+        }
+        function clear() { output.innerHTML = ''; summaryBar.classList.remove('visible'); }
+
+        function appendLine(icon, text, cls, time) {
+            const row = document.createElement('div');
+            row.className = `log-line log-line--${cls}`;
+            row.innerHTML =
+                `<span class="log-icon">${icon}</span>` +
+                `<span class="log-text">${esc(text)}</span>` +
+                (time != null ? `<span class="log-time">${time}s</span>` : '');
+            output.appendChild(row);
+            output.scrollTop = output.scrollHeight;
+            return row;
+        }
+
+        function appendSeparator(text) {
+            const row = document.createElement('div');
+            row.className = 'log-line log-line--heading';
+            row.innerHTML = `<span class="log-icon"></span><span class="log-text">── ${esc(text)} ──</span>`;
+            output.appendChild(row);
+            output.scrollTop = output.scrollHeight;
+        }
+
+        function esc(s) {
+            return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+        }
+
+        function handleEvent(data) {
+            switch (data.type) {
+                case 'preflight_ok':
+                    appendLine('✓', `Server OK  ${data.url}`, 'info', null);
+                    break;
+                case 'angle_start':
+                    appendSeparator(`${data.label}  ·  ${capitalize(data.angle)} path`);
+                    break;
+                case 'step_start':
+                    currentStepEl = appendLine('', data.description, 'running', null);
+                    break;
+                case 'step':
+                    if (currentStepEl && currentStepEl.parentNode) {
+                        currentStepEl.parentNode.removeChild(currentStepEl);
+                        currentStepEl = null;
+                    }
+                    if (data.status === 'pass') {
+                        appendLine('✅', data.description, 'pass', data.elapsed);
+                    } else if (data.status === 'fail') {
+                        appendLine('❌', data.description, 'fail', data.elapsed);
+                        if (data.error) {
+                            const err = document.createElement('div');
+                            err.className = 'log-line log-line--fail';
+                            err.innerHTML = `<span class="log-icon"></span><span class="log-text" style="padding-left:.5rem;color:#585b70">└─ ${esc(data.error)}</span>`;
+                            output.appendChild(err);
+                        }
+                    } else {
+                        appendLine('⏭️', data.description, 'skip', null);
+                    }
+                    output.scrollTop = output.scrollHeight;
+                    break;
+                case 'angle_done':
+                    appendLine('',
+                        `${data.passed} passed · ${data.failed} failed · ${data.skipped} skipped`,
+                        'summary', null);
+                    break;
+                case 'summary':
+                    spinner.classList.remove('active');
+                    title.textContent = data.failed ? `❌  Run complete — ${data.failed} failed` : `✅  Run complete`;
+                    sumPass.textContent = `✅ ${data.passed} passed`;
+                    sumFail.textContent = `❌ ${data.failed} failed`;
+                    sumSkip.textContent = `⏭️ ${data.skipped} skipped`;
+                    sumLabel.textContent = `${data.total} total`;
+                    summaryBar.classList.add('visible');
+                    if (source) { source.close(); source = null; }
+                    break;
+                case 'error':
+                    spinner.classList.remove('active');
+                    appendLine('🚨', data.message, 'error', null);
+                    title.textContent = '⚠  Error';
+                    if (source) { source.close(); source = null; }
+                    break;
+                case 'warn':
+                    appendLine('⚠', data.message, 'skip', null);
+                    break;
+                case 'stream_end':
+                    spinner.classList.remove('active');
+                    if (source) { source.close(); source = null; }
+                    break;
+            }
+        }
+
+        function setMode(mode) {
+            currentMode = mode;
+            document.getElementById('modeHeadless').classList.toggle('active', mode === 'headless');
+            document.getElementById('modeHeaded').classList.toggle('active', mode === 'headed');
+        }
+
+        function run(mod, angle, label) {
+            if (source) { source.close(); source = null; }
+            clear();
+            open();
+            spinner.classList.add('active');
+            summaryBar.classList.remove('visible');
+            const modeLabel = currentMode === 'headed' ? '  [browser]' : '';
+            title.textContent = `▶  ${label}${modeLabel}`;
+            currentStepEl = null;
+
+            const headedParam = currentMode === 'headed' ? '&headed=1' : '';
+            const url = `/qa/run/stream?module=${encodeURIComponent(mod)}&angle=${encodeURIComponent(angle)}${headedParam}`;
+            source = new EventSource(url);
+
+            source.onmessage = function(e) {
+                try { handleEvent(JSON.parse(e.data)); }
+                catch(_) { appendLine('⚠', e.data, 'error', null); }
+            };
+
+            source.onerror = function() {
+                spinner.classList.remove('active');
+                if (currentStepEl && currentStepEl.parentNode) {
+                    currentStepEl.parentNode.removeChild(currentStepEl);
+                    currentStepEl = null;
+                }
+                source.close(); source = null;
+                title.textContent = '⚠  Connection lost';
+            };
+        }
+
+        function capitalize(s) { return s.charAt(0).toUpperCase() + s.slice(1); }
+
+        (function () {
+            const handle = document.getElementById('qaResizeHandle');
+            let dragging = false, startY, startH;
+            handle.addEventListener('mousedown', function(e) {
+                dragging = true; startY = e.clientY; startH = panel.offsetHeight;
+                document.body.style.userSelect = 'none';
+            });
+            document.addEventListener('mousemove', function(e) {
+                if (!dragging) return;
+                const delta = startY - e.clientY;
+                const newH  = Math.min(Math.max(startH + delta, 160), window.innerHeight * 0.8);
+                panel.style.height = newH + 'px';
+            });
+            document.addEventListener('mouseup', function() {
+                dragging = false; document.body.style.userSelect = '';
+            });
+        })();
+
+        return { run, close, clear, open, setMode };
+    })();
+    </script>
+</body>
+</html>
+```
+
+---
+
+### Append QA routes to `routes/web.php`
+
+**Check if QA routes already exist:**
+
+```bash
+grep -q "qa.login" routes/web.php && echo "QA_ROUTES_EXIST" || echo "QA_ROUTES_MISSING"
+```
+
+If output is `QA_ROUTES_EXIST` → skip, routes are already registered.
+
+If output is `QA_ROUTES_MISSING` → read `routes/web.php` and append the following block at the very end of the file (after the last line):
+
+```php
+
+// ── QA Portal routes ────────────────────────────────────────────────────────
+Route::prefix('qa')->name('qa.')->group(function () {
+    Route::get('/login',   [\App\Http\Controllers\QA\LoginController::class,   'show'])->name('login');
+    Route::post('/login',  [\App\Http\Controllers\QA\LoginController::class,   'login']);
+    Route::post('/logout', [\App\Http\Controllers\QA\LoginController::class,   'logout'])->name('logout');
+    Route::middleware('qa.auth')->group(function () {
+        Route::get('/',           [\App\Http\Controllers\QA\DashboardController::class, 'index'])->name('index');
+        Route::post('/verify',    [\App\Http\Controllers\QA\DashboardController::class, 'verifyCredentials'])->name('verify');
+        Route::get('/run/stream', [\App\Http\Controllers\QA\RunController::class,       'stream'])->name('run.stream');
+    });
+});
+```
+
+**Verify routes were appended:**
+
+```bash
+grep -q "qa.login" routes/web.php && echo "  ✅  QA routes registered in routes/web.php" || echo "  ❌  QA routes MISSING — check routes/web.php"
+```
+
+---
+
+## Step 4 — Make scripts executable
+
+```bash
+chmod +x scripts/qa scripts/qa-register
+```
+
+---
+
+## Step 5 — Write (or validate and fix) the QA user seeder
+
+Check if `database/seeders/QAUserSeeder.php` exists:
+
+```bash
+test -f database/seeders/QAUserSeeder.php && echo EXISTS || echo MISSING
+```
+
+**If the file EXISTS** — do NOT skip. Read it, then run the model inspection below (5a). Compare the seeder against what you discover and check for these specific bugs:
+- `withTrashed()` or `restore()` called on a model that does not use the SoftDeletes trait → remove those calls
+- Any column set in the seeder (e.g. `is_active`, `status`, `role`) that does not exist on the actual table → remove or correct that column
+- Password hashing method in the seeder does not match what the model expects → fix to match
+
+If any of these bugs are present, rewrite only the affected lines. Print a list of every fix made. Then skip to the DatabaseSeeder registration check at the end of this step.
+
+If the file exists and has no bugs, print "QAUserSeeder ✅ no issues found" and skip to the DatabaseSeeder registration check at the end of this step.
+
+**If the file is MISSING** — do the following BEFORE writing a single line of PHP:
+
+**5a — Discover the auth structure of this project from scratch:**
+
+```bash
+# 1. Find the auth/user model — do NOT assume it is User.php
+grep -rn "implements.*Authenticatable\|extends.*Authenticatable\|HasFactory" app/Models/ --include="*.php" -l
+
+# 2. Read every model found above in full — extract:
+#    - actual $table name (or derive from class name if not set)
+#    - all fields in $fillable and $casts
+#    - password field name (password, password_hash, passwd, etc.)
+#    - whether SoftDeletes trait is used
+#    - whether there is a role/type/permission field on the model itself
+#      OR a relationship to a separate roles/permissions table
+
+# 3. Check migrations to understand schema reality
+ls database/migrations/ | grep -E "user|role|member|account|auth"
+
+# 4. Read those migration files to find:
+#    - the exact table name(s) for auth users
+#    - whether role is an inline column (enum, string, int) or a FK to another table
+#    - the exact enum values if role is an enum column
+#    - any active/status/verified columns
+
+# 5. If roles are in a separate table, find it
+php artisan tinker --execute="DB::select('SHOW TABLES')" 2>/dev/null | grep -i "role\|permiss\|type"
+
+# 6. Check what profile/related models exist that may need rows alongside the user
+ls app/Models/
+```
+
+**5b — From what you discovered, answer these questions before writing:**
+
+- What is the authenticatable model class and its table name?
+- How is role stored: inline column on users table, OR foreign key to a roles table?
+- If inline: what is the exact column name and what are the exact allowed values (with correct casing)?
+- If separate roles table: what is the table name, what column holds the role name, and how is it linked to users?
+- What is the password field name and does it use a hashed cast or does it expect a pre-hashed value?
+- Does the model use SoftDeletes?
+- Which profile models exist that need companion rows (e.g. Admin, Doctor, Profile, etc.)?
+
+**5c — Write the seeder using only what you discovered:**
+
+Roles come from the DATABASE — not from .env, not from assumptions. The seeder iterates every role value found in the DB and creates one QA user per role. The .env credentials are just the email/password to assign to those users.
+
+- Roles: query the actual role values from the DB (enum definition or distinct values in existing rows) — use every single one, with exact casing, exact spelling
+- Email per role: `env('QA_' . strtoupper($role) . '_EMAIL', env('QA_EMAIL'))` — reads role-specific key from .env, falls back to QA_EMAIL if not set
+- Password per role: `env('QA_' . strtoupper($role) . '_PASSWORD', env('QA_PASSWORD'))`
+- Password field: use the correct field and hashing method for this project
+- SoftDeletes: only call `withTrashed()` / `restore()` if the model actually uses it
+- Profile rows: only create companion rows if those tables/models actually exist in this project
+- Never hardcode a role name anywhere in the seeder — all role values come from DB discovery at write time
+
+Write `database/seeders/QAUserSeeder.php` with content fully adapted to this project's structure.
+
+After writing the file, check whether `DatabaseSeeder.php` already calls `QAUserSeeder::class`:
+
+```bash
+grep -q "QAUserSeeder" database/seeders/DatabaseSeeder.php && echo REGISTERED || echo NOT_REGISTERED
+```
+
+If NOT_REGISTERED, print this warning:
+```
+⚠️  Add QAUserSeeder to DatabaseSeeder.php:
+     $this->call([
+         ...
+         QAUserSeeder::class,   ← add this line
+         ...
+     ]);
+```
+
+---
+
+## Step 6 — Initialize test registry
+
+Check if `tests/e2e/registry.json` exists. If it does not, write it:
+
+```json
+{}
+```
+
+If it already exists, skip (never overwrite an existing registry).
+
+---
+
+## Step 7 — Update package.json
+
+Read `package.json`. If it exists, check whether these entries are already present:
+- `"type": "module"` at top level
+- `"qa": "node tests/e2e/js/main.js"` under scripts
+- `"qa:register": "node tests/e2e/js/register.js"` under scripts
+- `"playwright": "^1.60.0"` under devDependencies
+- `"dotenv": "^17.4.2"` under devDependencies
+
+Add any that are missing. Do not remove or overwrite existing keys.
+
+If `package.json` does not exist, create it:
+
+```json
+{
+  "type": "module",
+  "scripts": {
+    "qa": "node tests/e2e/js/main.js",
+    "qa:register": "node tests/e2e/js/register.js"
+  },
+  "devDependencies": {
+    "playwright": "^1.60.0",
+    "dotenv": "^17.4.2"
+  }
+}
+```
+
+---
+
+## Step 8 — Create EnsureQAAuth middleware and register qa.auth alias
+
+This step is mandatory. Missing it causes "Target class [qa.auth] does not exist" when the browser hits /qa.
+
+**8a — Check if the middleware file exists:**
+
+```bash
+find app/Http/Middleware -iname "*ensureqa*" -o -iname "*qa*auth*" 2>/dev/null
+```
+
+If no file is found, write `app/Http/Middleware/EnsureQAAuth.php`:
+
+```php
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class EnsureQAAuth
+{
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (!session('qa_authenticated')) {
+            return redirect('/qa/login');
+        }
+
+        return $next($request);
+    }
+}
+```
+
+If the file already exists, read it and confirm the class name so you use the exact namespace in 8d.
+
+**8b — Detect Laravel version:**
+
+```bash
+[ -f bootstrap/app.php ] && grep -q "withMiddleware" bootstrap/app.php && echo "Laravel 11+" || echo "Laravel 10 or below"
+```
+
+**8c — Check if qa.auth is already registered:**
+
+```bash
+grep -n "qa.auth" bootstrap/app.php 2>/dev/null || echo "NOT in bootstrap/app.php"
+[ -f app/Http/Kernel.php ] && grep -n "qa.auth" app/Http/Kernel.php 2>/dev/null || echo "NOT in Kernel.php (or file absent)"
+```
+
+If either grep returns a line number, the alias is already registered — skip 8d and go straight to 8e.
+
+**8d — Register the alias (only if missing):**
+
+Laravel 11+ (`bootstrap/app.php` has `withMiddleware`):
+- Run: `grep -n "alias" bootstrap/app.php` to check if a `$middleware->alias([...])` call already exists.
+- Case A — `alias([...])` call exists: add this line inside the existing array:
+  `'qa.auth' => \App\Http\Middleware\EnsureQAAuth::class,`
+- Case B — `withMiddleware` block exists but no `alias()` call: add this line inside the block body:
+  `$middleware->alias(['qa.auth' => \App\Http\Middleware\EnsureQAAuth::class]);`
+- Case C — `withMiddleware` block is completely absent: add this block before `->withExceptions(...)`:
+  ```php
+  ->withMiddleware(function (\Illuminate\Foundation\Configuration\Middleware $middleware): void {
+      $middleware->alias(['qa.auth' => \App\Http\Middleware\EnsureQAAuth::class]);
+  })
+  ```
+
+Laravel 10 and below (`app/Http/Kernel.php` exists): add to the `$routeMiddleware` array:
+`'qa.auth' => \App\Http\Middleware\EnsureQAAuth::class,`
+
+**8e — Verify the alias landed:**
+
+```bash
+grep -q "qa.auth" bootstrap/app.php 2>/dev/null && echo "  ✅  qa.auth registered in bootstrap/app.php" || \
+  { [ -f app/Http/Kernel.php ] && grep -q "qa.auth" app/Http/Kernel.php && echo "  ✅  qa.auth registered in Kernel.php" || echo "  ❌  qa.auth alias MISSING — 8d did not land, inspect the file and add manually"; }
+```
+
+Expected: one of the two ✅ lines. If ❌, stop and fix before continuing — the portal will not work without this.
+
+---
+
+## Step 9 — Verify installation
+
+Run this bash script to confirm every file is in place:
+
+```bash
+c() { [ -f "$1" ] && printf "  ✅  %-48s %s\n" "$1" "done" || printf "  ❌  %-48s %s\n" "$1" "MISSING — check Step $2"; }
+cx() { [ -x "$1" ] && printf "  ✅  %-48s %s\n" "$1" "done (executable)" || printf "  ❌  %-48s %s\n" "$1" "MISSING or not executable — check Step $2"; }
+
+echo ""
+echo "  ┌─────────────────────────────────────────────────────────────┐"
+echo "  │  QA Framework — Installation Check                          │"
+echo "  ├──────────────────────────────────────────────────────┬──────┤"
+echo "  │  File                                                │Status│"
+echo "  ├──────────────────────────────────────────────────────┼──────┤"
+c  "tests/e2e/js/config.js"                       "3"
+c  "tests/e2e/js/runner.js"                       "3"
+c  "tests/e2e/js/report.js"                       "3"
+c  "tests/e2e/js/main.js"                         "3"
+c  "tests/e2e/js/register.js"                     "3"
+c  "tests/e2e/js/modules/index.js"                "3"
+c  "tests/e2e/registry.json"                      "6"
+cx "scripts/qa"                                   "4"
+cx "scripts/qa-register"                          "4"
+c  "database/seeders/QAUserSeeder.php"            "5"
+c  "app/Http/Controllers/QA/LoginController.php"  "3b"
+c  "app/Http/Controllers/QA/DashboardController.php" "3b"
+c  "app/Http/Controllers/QA/RunController.php"    "3b"
+c  "resources/views/qa/login.blade.php"           "3b"
+c  "resources/views/qa/index.blade.php"           "3b"
+echo "  └──────────────────────────────────────────────────────┴──────┘"
+echo ""
+```
+
+Print the output of this script exactly as-is.
+
+Then run these three checks and print all outputs:
+
+```bash
+grep -q '"qa":' package.json && echo "  ✅  package.json qa scripts present" || echo "  ❌  package.json qa scripts MISSING — check Step 7"
+```
+
+```bash
+grep -q "qa.auth" bootstrap/app.php 2>/dev/null && echo "  ✅  qa.auth middleware alias registered" || \
+  { [ -f app/Http/Kernel.php ] && grep -q "qa.auth" app/Http/Kernel.php && echo "  ✅  qa.auth middleware alias registered (Kernel.php)" || echo "  ❌  qa.auth alias MISSING — check Step 8"; }
+```
+
+```bash
+grep -q "qa.login" routes/web.php && echo "  ✅  QA routes registered in routes/web.php" || echo "  ❌  QA routes MISSING in routes/web.php — check Step 3b"
+```
+
+---
+
+## Step 9 — Print next steps
+
+After printing the verification table, print:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  What to do next
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  1. Add to .env (if not already present):
+       QA_EMAIL=qa@example.local           # portal login + fallback credential
+       QA_PASSWORD=Password@1
+       QA_<ROLE>_EMAIL=qa-role@example.local   # one per role (e.g. QA_ADMIN_EMAIL)
+       QA_<ROLE>_PASSWORD=Password@1
+       APP_URL=http://127.0.0.1:8000
+
+  2. Seed the QA user accounts (run once):
+       php artisan db:seed --class=QAUserSeeder
+
+  3. Install Node dependencies (run once per machine):
+       npm install
+       npx playwright install chromium
+
+  4. Verify login selectors in tests/e2e/js/runner.js login():
+       Uses [name='email'], [name='password'], button 'Sign in',
+       waits for URL '**/<role>**'.
+       Update if your app's login form or post-login URL differs.
+
+  5. Visit the QA portal:
+       http://127.0.0.1:8000/qa
+
+  6. Generate your first test module:
+       /qa <module> "<what this module does>"
+
+  7. Run a test:
+       ./scripts/qa <module> happy h     # headed browser
+       ./scripts/qa all                  # all modules
+```