scenescout 1.0.0

package/dist/scan.js

@@ -0,0 +1,335 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * What marks a package.json as a frontend workspace.
+ *
+ * Meta-frameworks are listed explicitly rather than relying on the UI library
+ * underneath them: Nuxt supplies vue and Remix supplies react, so an app that
+ * depends only on the meta-framework has neither in its own manifest — and was
+ * therefore not recognised as a frontend at all, making the whole scan report
+ * "No frontend workspace found" for a perfectly ordinary project.
+ */
+const FRONTEND_DEPS = ["next", "nuxt", "@sveltejs/kit", "@remix-run/react", "@remix-run/node", "react", "vue", "svelte", "@angular/core", "vite"];
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "out", "docs", "examples", "e2e-tests"]);
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function isFrontendPackage(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return FRONTEND_DEPS.some((d) => d in deps);
+}
+/** Collect every frontend workspace: the root itself and child dirs (depth ≤ 2) with a React/Vue/etc package.json. */
+function findFrontendDirs(projectDir) {
+    const found = [];
+    const rootPkg = readJson(path.join(projectDir, "package.json"));
+    if (rootPkg && isFrontendPackage(rootPkg))
+        found.push(projectDir);
+    const queue = [{ dir: projectDir, depth: 0 }];
+    while (queue.length > 0) {
+        const { dir, depth } = queue.shift();
+        if (depth > 2)
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || SKIP_DIRS.has(entry.name) || entry.name.startsWith("."))
+                continue;
+            const sub = path.join(dir, entry.name);
+            const pkg = readJson(path.join(sub, "package.json"));
+            if (pkg && isFrontendPackage(pkg))
+                found.push(sub);
+            else
+                queue.push({ dir: sub, depth: depth + 1 });
+        }
+    }
+    return found;
+}
+const NAME_BONUS = ["frontend", "web", "app", "client", "ui"];
+/**
+ * A monorepo can hold several frontend apps (main app + admin panel + landing
+ * page). Pick the primary one: most routes wins, conventional names break ties.
+ */
+function pickPrimary(candidates) {
+    const scored = candidates.map((dir) => {
+        const routeCount = nextRoutes(dir).length;
+        const base = path.basename(dir).toLowerCase();
+        const nameBonus = NAME_BONUS.includes(base) ? NAME_BONUS.length - NAME_BONUS.indexOf(base) : 0;
+        return { dir, score: routeCount * 10 + nameBonus };
+    });
+    scored.sort((a, b) => b.score - a.score);
+    return { primary: scored[0].dir, others: scored.slice(1).map((s) => s.dir) };
+}
+/**
+ * Order matters: the most specific meta-framework wins. Nuxt and SvelteKit both
+ * depend on vite, and Nuxt depends on vue — checked later, they were reported as
+ * bare "vite"/"vue" with that ecosystem's default port instead of their own.
+ */
+function detectFramework(pkg) {
+    const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    if ("next" in deps)
+        return { framework: "next", port: 3000 };
+    if ("nuxt" in deps || "nuxt3" in deps)
+        return { framework: "nuxt", port: 3000 };
+    if ("@sveltejs/kit" in deps)
+        return { framework: "sveltekit", port: 5173 };
+    if ("@remix-run/react" in deps || "@remix-run/node" in deps)
+        return { framework: "remix", port: 3000 };
+    if ("@angular/core" in deps)
+        return { framework: "angular", port: 4200 };
+    if ("react-scripts" in deps)
+        return { framework: "create-react-app", port: 3000 };
+    if ("vite" in deps)
+        return { framework: deps.react ? "vite+react" : "vite", port: 5173 };
+    if ("vue" in deps)
+        return { framework: "vue", port: 5173 };
+    if ("react" in deps)
+        return { framework: "react", port: 3000 };
+    return { framework: null, port: null };
+}
+/**
+ * SvelteKit / Nuxt file-based routes.
+ *
+ * Both put pages under a conventional directory and both use bracket params,
+ * so one walker covers them. SvelteKit marks a page with `+page.svelte` and
+ * uses `(group)` directories exactly as Next's App Router does; Nuxt treats
+ * every `.vue` file as a page, with `index.vue` as the directory root.
+ */
+function fileRoutes(frontendDir, kind) {
+    const root = kind === "sveltekit" ? path.join(frontendDir, "src", "routes") : firstExisting([path.join(frontendDir, "pages"), path.join(frontendDir, "app", "pages")]);
+    if (!root || !fs.existsSync(root))
+        return [];
+    const routes = [];
+    const walk = (dir, base) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("_") || ROUTE_SKIP_DIRS.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // SvelteKit route groups, like Next's, are layout-only and contribute
+                // nothing to the URL.
+                const organisational = kind === "sveltekit" && /^\(.*\)$/.test(entry.name);
+                walk(full, organisational ? base : `${base}/${entry.name}`);
+            }
+            else if (kind === "sveltekit" && /^\+page\.(svelte|ts|js)$/.test(entry.name)) {
+                routes.push(base || "/");
+            }
+            else if (kind === "nuxt" && /\.vue$/.test(entry.name)) {
+                const name = entry.name.replace(/\.vue$/, "");
+                routes.push(name === "index" ? base || "/" : `${base}/${name}`);
+            }
+        }
+    };
+    walk(root, "");
+    // SvelteKit spells params [id] and [...rest]; Nuxt [id] and [...slug]. Both
+    // collapse to the same :param shape the rest of the engine speaks.
+    return [...new Set(routes.map((r) => r.replace(/\[\.\.\.([^\]]+)\]/g, ":$1").replace(/\[([^\]]+)\]/g, ":$1")))].sort();
+}
+function firstExisting(candidates) {
+    return candidates.find((c) => fs.existsSync(c)) ?? null;
+}
+/**
+ * Route-walk skip set — deliberately smaller than SKIP_DIRS: inside pages/ or
+ * app/, directories like docs/ or examples/ are REAL routes, not artifacts.
+ */
+const ROUTE_SKIP_DIRS = new Set(["node_modules", "api"]);
+/** Enumerate Next.js routes from pages/ or app/ directory structure. */
+function nextRoutes(frontendDir) {
+    const routes = [];
+    const pagesDir = path.join(frontendDir, "pages");
+    const appDir = path.join(frontendDir, "app");
+    const walk = (dir, base, mode) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith("_") || ROUTE_SKIP_DIRS.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                // App Router organisational directories contribute NOTHING to the URL:
+                // a route group `(marketing)` exists to share a layout, and a parallel
+                // slot `@modal` renders into a named outlet. Concatenating them
+                // produced routes like `/(marketing)/about` for a page that actually
+                // lives at `/about` — a "known route" no navigation could ever reach,
+                // which then sat in the completion contract forever.
+                const organisational = mode === "app" && (/^\(.*\)$/.test(entry.name) || entry.name.startsWith("@"));
+                walk(full, organisational ? base : `${base}/${entry.name}`, mode);
+            }
+            else if (mode === "pages" && /\.(tsx|jsx|ts|js)$/.test(entry.name)) {
+                const name = entry.name.replace(/\.(tsx|jsx|ts|js)$/, "");
+                routes.push(name === "index" ? base || "/" : `${base}/${name}`);
+            }
+            else if (mode === "app" && /^page\.(tsx|jsx|ts|js)$/.test(entry.name)) {
+                routes.push(base || "/");
+            }
+        }
+    };
+    if (fs.existsSync(pagesDir))
+        walk(pagesDir, "", "pages");
+    else if (fs.existsSync(appDir))
+        walk(appDir, "", "app");
+    return routes.map((r) => r.replace(/\[([^\]]+)\]/g, ":$1")).sort();
+}
+function findAuthStates(frontendDir) {
+    const authDir = path.join(frontendDir, "playwright", ".auth");
+    try {
+        return fs
+            .readdirSync(authDir)
+            .filter((f) => f.endsWith(".json"))
+            .map((f) => path.join(authDir, f));
+    }
+    catch {
+        return [];
+    }
+}
+function grepTestids(frontendDir) {
+    // Cheap sample: look for data-testid in a handful of component files.
+    const candidates = ["components", "src/components", "src", "app", "pages"];
+    for (const rel of candidates) {
+        const dir = path.join(frontendDir, rel);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir).slice(0, 40);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const file = path.join(dir, name);
+            try {
+                if (fs.statSync(file).isFile() && /\.(tsx|jsx)$/.test(name)) {
+                    if (fs.readFileSync(file, "utf8").includes("data-testid"))
+                        return true;
+                }
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+    return false;
+}
+export function scanProject(projectDir) {
+    const resolved = path.resolve(projectDir);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Project directory does not exist: ${resolved}`);
+    }
+    const notes = [];
+    const candidates = findFrontendDirs(resolved);
+    const picked = candidates.length > 0 ? pickPrimary(candidates) : null;
+    const frontendDir = picked?.primary ?? null;
+    if (picked && picked.others.length > 0) {
+        const others = picked.others.map((d) => path.relative(resolved, d) || ".");
+        notes.push(`Multiple frontend workspaces found — using the largest (${path.relative(resolved, frontendDir) || "."}). ` +
+            `Others: ${others.join(", ")}. Re-scan a specific one by passing its path directly.`);
+    }
+    if (!frontendDir) {
+        return {
+            projectDir: resolved,
+            frontendDir: null,
+            framework: null,
+            devCommand: null,
+            portGuess: null,
+            routes: [],
+            authStates: [],
+            hasPlaywright: false,
+            usesTestids: false,
+            readmeExcerpt: null,
+            notes: ["No frontend workspace found (no package.json with a known frontend dependency at depth ≤ 2)."],
+        };
+    }
+    if (frontendDir !== resolved)
+        notes.push(`Monorepo: frontend workspace is ${path.relative(resolved, frontendDir)}/`);
+    const pkg = readJson(path.join(frontendDir, "package.json")) ?? {};
+    const { framework, port } = detectFramework(pkg);
+    const scripts = (pkg.scripts ?? {});
+    const devCommand = scripts.dev ? "dev" : scripts.start ? "start" : null;
+    const routes = framework === "next"
+        ? nextRoutes(frontendDir)
+        : framework === "sveltekit"
+            ? fileRoutes(frontendDir, "sveltekit")
+            : framework === "nuxt"
+                ? fileRoutes(frontendDir, "nuxt")
+                : [];
+    // Say so when filesystem discovery cannot help. Returning [] silently left
+    // the agent to assume the app genuinely had no routes, when in fact nothing
+    // had looked — the completion contract then rested entirely on link
+    // harvesting without ever admitting it.
+    if (routes.length === 0 && framework !== null && !["next", "sveltekit", "nuxt"].includes(framework)) {
+        notes.push(`No filesystem route discovery for "${framework}" (routes are defined in code, not files) — ` +
+            `the route contract will be built from links harvested during exploration. Crawl breadth depends on what the UI links to.`);
+    }
+    const authStates = findAuthStates(frontendDir);
+    const hasPlaywright = fs.existsSync(path.join(frontendDir, "playwright.config.ts")) || fs.existsSync(path.join(frontendDir, "playwright.config.js"));
+    // Full-stack heuristics: launching the frontend alone probably isn't enough.
+    for (const marker of ["docker-compose.yml", "docker", "Makefile", "backend"]) {
+        if (fs.existsSync(path.join(resolved, marker))) {
+            notes.push(`Full-stack marker found (${marker}) — the app likely needs its backend running. Prefer attaching to an already-running instance with --url.`);
+            break;
+        }
+    }
+    if (authStates.length > 0) {
+        notes.push(`Playwright auth storage states found — pass one to scout_attach as storageStatePath to explore as that role.`);
+    }
+    let readmeExcerpt = null;
+    for (const candidate of [path.join(resolved, "README.md"), path.join(frontendDir, "README.md")]) {
+        try {
+            readmeExcerpt = fs.readFileSync(candidate, "utf8").split("\n").slice(0, 30).join("\n");
+            break;
+        }
+        catch {
+            /* keep looking */
+        }
+    }
+    return {
+        projectDir: resolved,
+        frontendDir,
+        framework,
+        devCommand,
+        portGuess: port,
+        routes,
+        authStates,
+        hasPlaywright,
+        usesTestids: grepTestids(frontendDir),
+        readmeExcerpt,
+        notes,
+    };
+}
+export function formatScan(result) {
+    const lines = [
+        `Project: ${result.projectDir}`,
+        `Frontend: ${result.frontendDir ?? "NOT FOUND"}`,
+        `Framework: ${result.framework ?? "unknown"}${result.devCommand ? ` · dev script: "${result.devCommand}"` : ""}${result.portGuess ? ` · likely port ${result.portGuess}` : ""}`,
+        `Playwright config: ${result.hasPlaywright ? "yes" : "no"} · data-testid convention: ${result.usesTestids ? "yes" : "not detected"}`,
+        `Auth storage states (${result.authStates.length}): ${result.authStates
+            .slice(0, 8)
+            .map((p) => path.basename(p))
+            .join(", ") || "none"}`,
+        `Routes (${result.routes.length}):`,
+        ...result.routes.slice(0, 60).map((r) => `  ${r}`),
+        ...(result.routes.length > 60 ? [`  … and ${result.routes.length - 60} more`] : []),
+        ...(result.notes.length > 0 ? ["Notes:", ...result.notes.map((n) => `  - ${n}`)] : []),
+    ];
+    return lines.join("\n");
+}

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "scenescout",
+  "version": "1.0.0",
+  "description": "SceneScout — AI-agent exploratory UI testing engine: an MCP server exposing Playwright browser tools with state-fingerprint memory, invariant oracles, structured findings and reports. Claude Code (or any MCP client) is the brain.",
+  "license": "MIT",
+  "author": "brunoboto96",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brunoboto96/SceneScout.git"
+  },
+  "homepage": "https://github.com/brunoboto96/SceneScout#readme",
+  "bugs": {
+    "url": "https://github.com/brunoboto96/SceneScout/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "exploratory-testing",
+    "ui-testing",
+    "playwright",
+    "claude-code",
+    "qa",
+    "ai-agent"
+  ],
+  "type": "module",
+  "bin": {
+    "scenescout": "dist/cli.js"
+  },
+  "main": "dist/mcp-server.js",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "setup": "node dist/cli.js install",
+    "doctor": "node dist/cli.js doctor",
+    "changeset": "changeset",
+    "version-packages": "changeset version && node scripts/sync-plugin-version.mjs && npm install --package-lock-only",
+    "release": "npm run build && changeset publish",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "demo": "npm run build && tsx scripts/demo.ts",
+    "demo:serve": "node demo-app/server.mjs",
+    "dev": "tsx src/cli.ts",
+    "serve": "node dist/mcp-server.js",
+    "smoke": "npm run build && npm run smoke:run",
+    "smoke:run": "tsx scripts/smoke.ts",
+    "mcp-check": "npm run build && npm run mcp-check:run",
+    "mcp-check:run": "tsx scripts/mcp-check.ts",
+    "test": "npm run build && npm run test:unit && npm run smoke:run && npm run mcp-check:run",
+    "test:unit": "npm run scan-test && npm run oracle-test && npm run policy-test && npm run fixture-test && npm run dispatch-test && npm run design-test && npm run contract-test && npm run memory-test && npm run install-test",
+    "scan-test": "tsx scripts/scan-test.ts",
+    "oracle-test": "tsx --test scripts/oracle-test.ts",
+    "policy-test": "tsx --test scripts/policy-test.ts",
+    "fixture-test": "tsx --test scripts/fixture-test.ts",
+    "dispatch-test": "tsx --test scripts/dispatch-test.ts",
+    "design-test": "tsx --test scripts/design-test.ts",
+    "contract-test": "tsx --test scripts/contract-test.ts",
+    "memory-test": "tsx --test scripts/memory-test.ts",
+    "install-test": "tsx --test scripts/install-test.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "playwright": "^1.63.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "3.0.3",
+    "@types/node": "^20.19.0",
+    "prettier": "3.9.8",
+    "tsx": "^4.23.13",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/scenescout/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: scenescout
+description: AI exploratory UI testing — drive the SceneScout MCP browser tools to explore a running web app like a real user, find bugs/UX issues via oracles and judgment, track coverage across runs, and produce a report. Use when the user asks to exploratory-test, "click around", stress or QA a web UI, or invokes /scenescout. Requires the SceneScout MCP server to be registered.
+---
+
+# SceneScout — exploratory UI testing agent
+
+You are the brain of an exploratory UI tester. The SceneScout MCP server gives you deterministic browser tools (the `scout_*` tools — listed as `mcp__scenescout__scout_*`, or `mcp__plugin_scenescout_scenescout__scout_*` when installed as a plugin); you provide intent, judgment, and curiosity. The engine gives you structured render-state (elements, geometry, oracles) — never parse pixels when text will do. Argument hint: `[--level minimal|medium|extensive] [--url URL] [--role NAME] [--safe-write | --allow-destructive]`.
+
+**The mission is wider than pass/fail.** Scripted e2e suites answer "does it still work?" as a binary and say nothing about what they don't cover; a human can't manually exercise a large app. You cover both gaps: find what's broken (oracles, dead ends, permission leaks) AND report how the product could be *better* — confusing flows, weak hierarchy, design-system drift, friction. Improvement feedback with concrete measurements is a first-class deliverable, not garnish; a run that finds no crashes but produces sharp `ux-polish`/`visual` suggestions is a successful run.
+
+## Setup (in order)
+
+1. **Check the tools exist.** Look for a `scout_scan` tool under either prefix above. If there is none, stop and tell the user how to get it, then to start a fresh session:
+   - as a plugin: `/plugin marketplace add brunoboto96/SceneScout` then `/plugin install scenescout@scenescout-marketplace`
+   - or by hand: `claude mcp add --scope user scenescout -- npx -y scenescout serve` (from a source checkout, register with an **absolute node path** instead — a bare `node` fails with "Executable not found in $PATH" under nvm/fnm: `claude mcp add --scope user scenescout -- "$(which node)" <checkout>/dist/mcp-server.js`)
+   If attach later reports that Chromium has not been downloaded, relay the one-time command it names.
+2. **`scout_scan`** the project's absolute path. Read routes, framework, auth states, notes.
+   - **No source here?** When the target is a remote URL (staging, a deployed site) and the scan reports no frontend workspace, that is a supported mode, not an error: you are a black-box QA tester. Skip step 3's launch logic and keep the current directory as `projectPath` (memory and the report still need a home). Link harvesting builds the route list, and `scout_crawl` has nothing to crawl until it does — so snapshot the landing page and main navigation first, then `scout_crawl`, and `scout_crawl` again to pick up what those pages linked to. With no scanned auth states, `--role` is a path to a Playwright storage-state JSON. A remote target is far more likely to hold real data: confirm the user is authorized to test it if that is not evident, never leave `read-only` unless they say the environment is disposable — and remember `read-only` still lets ordinary create/submit POSTs through, so do NOT submit forms that create real records (contact, order, signup, invite) without the user's okay; disclose the skipped forms as gaps instead. Claims that something is *absent* cannot be source-checked here: file them as behaviour-only and say so. `extensive` still needs ≥2 login states. The report cannot record where routes came from, so say it in your summary to the user and in an `scout_note`: routes were discovered from same-origin links only, and pages nothing links to are outside the contract.
+   - **Source available?** Use it beyond the scan: when you file a finding, read the component or handler behind it and name the file and the likely fix — that is the difference between "the save button does nothing" and a finding a developer can act on in one step.
+3. **Ensure the app is running.** Full-stack markers in the scan → do NOT launch the stack yourself; confirm the URL responds (you may curl it) or ask the user. Auto-launch only simple single-package frontends.
+4. **Pick auth.** `--role X` → pass that storage-state file. Unspecified → least-privileged role; say so.
+5. **`scout_attach`** with url, projectPath, storageStatePath, and the write **mode** — the DB behind the app may be live, so the engine enforces this at the network layer:
+   - `read-only` (default): destructive labels blocked in the UI AND all PUT/PATCH/DELETE + destructive POSTs blocked on the wire. Use unless told otherwise.
+   - `safe-write` (`--safe-write`, or the user asks to test creating/editing things): create freely — **prioritize testing CREATE flows** — then edit/delete ONLY the records you created (the engine tracks your creations and blocks mutations on anything else). Never attempt to clean up or modify pre-existing data.
+   - `destructive` (`--allow-destructive` only): everything allowed. Requires the user to explicitly confirm the environment is disposable/seeded. Never decide this yourself.
+   A `🛡 WRITE-POLICY blocked` notice in a tool result is the engine's safety net, NOT an app bug — never file a finding for the error UI it causes; note it and move on (or suggest the user re-run with a laxer mode if that flow matters).
+   **`⚠ AUTH FAILED` on attach means the storage state is stale** — its token has expired and the browser is sitting on a login page. Stop and ask the user to regenerate it (usually their Playwright auth-setup project); do not explore, and do not file findings from a logged-out session. Mid-run, `⚠ SESSION AUTH LOST` means the same thing happened after N navigations: everything since is meaningless, so re-attach rather than pressing on. Routes bounced this way are recorded as NOT covered, so the gap ledger will still show them.
+6. **`scout_note {action:'read'}` immediately after attaching.** ASSUMPTIONS.md is the run-over-run written memory: what the app is, who each role is FOR, constraints discovered the hard way ("an order can only ship once approved"). Starting without reading it means re-learning what a previous run already paid to find out. Throughout the run, `scout_note {action:'add'}` every DURABLE learning the moment you confirm it — app model, role personas, conventions, constraints, risks, glossary. Not session facts (ids, counts); knowledge a future run should start with.
+
+## The efficient loop (this is the core method)
+
+1. **`scout_crawl` first, always.** One call visits every known route (pass `paths` to sweep a specific subset instead), records coverage, and returns per-route health. This is the whole breadth pass — do not visit routes one-by-one with navigate+snapshot.
+2. **Investigate what the crawl flagged.** For each problem route (violations, dead-ends, auth-redirects): navigate there, `scout_snapshot`, reproduce, then `scout_finding`.
+3. **Run journeys with `scout_run_plan {steps}`.** Mechanical sequences (fill form → submit → check) go in ONE plan call — `steps` is an ordered list of `{action, target, value}` — with `testid=`/`text=`/`label=` targets — not one LLM turn per click. The plan aborts at the first violation and tells you where; that's your cue to investigate interactively.
+4. **Snapshot economics:** `scout_snapshot` after landing somewhere new; re-snapshots of the same route return *diffs* with stable refs — "No element changes" costs you almost nothing. `scout_screenshot` ONLY for suspected pixel-native issues (broken images, canvas); geometry problems (overlap, off-screen) are already in the snapshot as GEOMETRY issues.
+5. **Native-user behaviours.** `scout_type {ref, textValue}` (or its alias `value`, matching `scout_select` and a plan step) APPENDS when a field already has content (menu clicks often insert @-mention chips or commands into composers — appending preserves them; the result reports what was already there); pass `replace=true` only to deliberately clear, and `pressEnter=true` to submit from the field the way a user would. Before concluding a badge, icon, or "N errors" indicator *does nothing*, `scout_hover` it — tooltips and hover cards are invisible to snapshots and clicks, and hover output includes what appeared. In HEADED mode (`scout_attach {headed:true}`, which the user asks for when they want to watch) the user's physical mouse competes with the synthetic pointer: if a hover reveals nothing and the finding matters, ask the user to move their mouse off the browser window and retry before filing. **Scroll long pages with `scout_scroll`** — the design audit and snapshot measure at the current scroll position, so judge deep sections by scrolling then re-auditing; it refuses to scroll where a real user couldn't and reports SCROLL LOCKED (the leaked modal scroll-lock that silently amputates everything below the fold — snapshots also flag it passively as an OVERLAY line), and scrolling triggers lazy-loaded content whose failures surface as fresh oracle violations. Elements fully clipped inside an overflow-hidden container are flagged UNREACHABLE in GEOMETRY issues — no amount of scrolling reveals them; that's a high-value layout bug, distinct from merely below-the-fold content. **A page can hold SEVERAL independent scroll regions** and plain `scout_scroll` moves the largest one, so a sidebar nav beside a taller main pane never budges: pass `scout_scroll {target:"testid=…"}` to scroll one region. Never report a nav item, tab or list row as missing/truncated until you have scrolled ITS container — content scrolled out of a secondary pane looks exactly like content that was cut off.
+6. **The rest of the input vocabulary.** `scout_select` sets a `<select>` option by value or visible label — use it rather than clicking a native dropdown open, which does not render as page DOM. `scout_press` sends a real key to the focused element (`Escape` to dismiss a modal, `Tab` to walk focus order, `Enter` to submit from a field); it is also how the keyboard-only pass at `extensive` is performed, and it vets the focused control first so a destructive action cannot be triggered blind in read-only mode. **`scout_upload {ref}` attaches a file the way a user does** — `ref` is a visible `<input type=file>` (snapshots list these with role `file`; `scout_type` on one redirects here) OR the button/label/dropzone that opens the file chooser (the chooser is intercepted and answered — that is how the hidden input behind a styled "Choose file" control is reached); omit `ref` when the page has exactly one file input, hidden or not (snapshots disclose hidden ones on a FILE INPUTS line). Nothing needs to exist on disk: a small VALID fixture is generated in memory, its kind inferred from the input's `accept` attribute or chosen with `fixture` (`pdf`, `png`, `txt`, `csv`, `json`); `filePath` uploads a real file but must live inside the attached project (fenced, like navigation is fenced to the origin); `name` overrides the filename. The result flags a file that violates `accept` (a mismatch the app then ACCEPTS is a validation finding), warns when the app cleared the input after selection, and says whether a state-changing request fired on selection — if none did, either click the form's submit or read the next snapshot for a client-side rejection. Plans take `{action:"upload", target, value:"pdf"}` steps (`target` required). When the input or its trigger was addressed by `ref`, the gap ledger counts an attached-but-unsent file as filled-never-submitted; the ref-less path has no listed element to mark.
+7. **Design-connoisseur pass without pixels: `scout_design_audit`.** Run it once per representative page (dashboard, a form, a detail view, a data table). Its output has two tiers: **⚠ measurable defects** (WCAG contrast, tiny targets, clipped text, aspect-distorted images, horizontal overflow, keyboard tab stops with no visible focus indicator — sampled with real Tab presses) and **→ craft suggestions** (line measure and line-height rhythm, spacing-grid adherence, typography entropy, gray census and accent-hue count, pure-#000 body text, elevation/control consistency, heading structure, indistinguishable links, AI-slop tells like gradient text/glassmorphism/side-stripe borders/identical card grids), closing with a SYSTEM SUMMARY of design-system coherence. Judge every line with product context (dense tables legitimately have small targets; a chart page legitimately uses many hues). File ⚠ defects as `visual`/`a11y`, and genuine → opportunities as `ux-polish` findings **quoting the concrete numbers** — "~142 characters per line (65–75 ideal)" beats "text feels wide". Every audit ends with a **PAGE SCORE** (0–100 overall + a11y/craft/consistency/task-clarity subscores) persisted per route — the report ranks pages worst-first, so re-runs show whether pages got better or worse. Separately, every `scout_snapshot` runs an **overlay/modal probe** automatically: an empty dialog over a grayed page, a backdrop with no dialog, a far-off-centre dialog leaving a blank band, or a dialog extending unreachably below the viewport appear as OVERLAY lines in GEOMETRY issues — treat these as high-value findings (the user is visually stuck). This is where "how could this page be better" gets answered, not just "is it broken".
+8. **Measure task EASE with `scout_journey`, not just correctness.** Wrap each module's primary task (`{action:"start", goal:"Create an order"}` → do it → `{action:"end", completed:…}`). Navigate by CLICKING like a first-time user — typing a known deep URL shortcuts the very thing being measured (a route you can only reach by editing the address bar is itself a finding). The result gives interaction count, distinct screens, the path taken, and BACKTRACKS — returning to a screen already left is the clearest evidence the next step wasn't discoverable. An abandoned journey (`completed:false`) is a high-severity finding: the task is blocked or undiscoverable, which no passing e2e suite would ever reveal.
+9. **Walk the auth surface too — anonymously.** Attach a second session WITHOUT a storage-state file (a fresh logged-out profile) and exercise signup, login failure states, and forgot/reset-password **as far as they physically go**. The mailbox wall is expected — reaching "check your email" IS the success condition; everything before it is what you're testing: does submit actually fire (a dead signup button is a high finding), are errors specific and actionable, can the user resend or recover from a typo, does the flow dead-end. Use plausible synthetic identities only (invent `qa-<runid>@example.com`-style addresses, never a real person's), submit each form valid AND invalid, and judge the feedback. Two classic findings live here: a forgot-password that answers "no account with that email" is an **account-enumeration leak** (file as security; "if an account exists, we sent a link" is the correct shape), and a signup that accepts the form then lands on a blank or logged-out page with no guidance is a **journey dead-end**. Signup creates a record — run this pass in safe-write mode; the engine tracks the created account like any other creation.
+10. **`scout_coverage` decides what's next** — it lists unvisited routes and unexercised elements. Trust it over your memory. Prefer reaching routes by clicking real navigation; fall back to direct URLs for coverage completeness and re-verification, and say which you used when it affects the finding (see the provenance rule below).
+
+## Levels (completion contracts — the engine ENFORCES them via `scout_report {level}`)
+
+| Level | Contract (gate-checked at report time) | Typical shape |
+|---|---|---|
+| `minimal` | Every known route visited (crawl does this) + ≥1 design audit + 1–2 primary journeys as plans + crawl-flagged problems triaged. The report DISCLOSES remaining gaps in its Gap Ledger — minimal is honest-but-fast, not silent. | 1 crawl + 2–4 plans + a few snapshots |
+| `medium` (default) | minimal + design audits on several distinct routes (gate: ≥ min(3, visited/10)) + every unexercised interactable class exercised once + every form submitted valid AND invalid | + interactive passes per module |
+| `extensive` | medium + fuzzing (empty, 1000-char, unicode, `<script>`; for uploads, `scout_upload {name}` with a wrong extension against `accept`, a 255-char name, unicode), back/refresh/deep-link resilience, keyboard-only pass, **an `scout_journey` per module's primary task**, **the impatient-user pass** (below), **≥2 roles compared**, **the anonymous auth-surface pass** (signup / forgot-password walked to the mailbox wall, step 8 above), and source-grounding for every absence-claim. **`scout_report {level:'extensive'}` REFUSES while the Gap Ledger is non-empty** — that refusal IS the completeness guarantee: an extensive report can only exist when every known route is visited, exercised, audited, journey-measured, and role-compared. | budget-capped by user |
+
+**The Gap Ledger is the trust mechanism.** The engine tracks per-route facts (visited / exercised / audited / mutated / journeyed) and per-role access; the report enumerates everything NOT done. Work the ledger down (`scout_report` tells you exactly what's missing), don't argue with it. Never pass `force=true` unless the user explicitly capped the budget — a forced report still prints its gaps.
+
+Route knowledge is generic: scanned filesystem routes ∪ links harvested from every snapshot (including `?tab=` screens) form the contract — it works on any app, not just Next. For a responsive pass, re-attach with `viewportWidth: 390, viewportHeight: 844` and re-run the design audit on key pages.
+
+## Multi-role collaboration (named sessions)
+
+Some flows need a TEAM — a document one role submits and another approves, a review one role assigns and another completes, permission checks that only mean something side-by-side. `scout_attach {session: "admin", storageStatePath: …}` then `scout_attach {session: "qa", storageStatePath: …}` keeps BOTH browsers live and authenticated. Coverage and findings from all roles merge into one project memory.
+
+**Every per-session tool takes a `session` param — use it.** Calls targeting DIFFERENT sessions run genuinely CONCURRENTLY (issue several in one turn and they execute in parallel); calls targeting the SAME session still serialize, because one browser's ref table can't process overlapping actions. `scout_session {name}` only sets the default for calls that omit `session` — convenience for single-role stretches, not the mechanism for multi-role work. Once more than one session is live the default is genuinely unsafe to rely on: it points at whichever session attached most recently, so a *concurrent* attach elsewhere silently re-points your un-parameterized calls at another role's browser. The engine appends `⚠ AMBIGUOUS SESSION` when that happens — treat it as a mistake to fix, not a note.
+
+- **Parallel independent work** (the common case, and the fast one): give each role its own objective and dispatch in one turn — `scout_crawl {session:"admin"}` alongside `scout_crawl {session:"qa"}`, or each role auditing different modules. Two roles exploring different surfaces have no reason to take turns.
+- **Sequential handoff** (only where the flow genuinely requires it): role A performs its half (submits for approval), then `scout_snapshot {session:"qa"}` to SEE the handed-off state arrive, B performs its half, and re-snapshot as A to verify the outcome. The snapshot is the "wait for the other" step — if the state hasn't arrived, do other work as that role and re-check rather than idling.
+- Refs are per-session: `e12` from an admin snapshot means nothing in the qa session. Snapshot the session you're about to act on.
+- While roles are NOT collaborating, use each one productively where its permissions matter (admin in /admin surfaces, low-privilege probing for permission leaks) — same coverage contract, different vantage points.
+- **Infer the PERSONA behind each role, and write it down.** From what a role can see and do (its nav, its dashboard, the capability matrix in the report), state what this person is FOR: "qa = reviewer — approves orders, assigns reviewers, no admin" / "user = front-line user — reads documents, completes reviews, raises orders". Record it with `scout_note {section:'roles'}`. Then test the persona's WORLD, not just the permissions: does the operator's landing page serve an operator? Is anything they need N clicks deep? The capability matrix's divergent rows are questions, not verdicts — each is either a correct boundary or a gap ("should this role be able to do this?"); say which you believe it is and why.
+- `scout_close {all: true}` at the end of a multi-role run; `scout_close {session}` to drop one role early.
+
+## The impatient-user pass (extensive)
+
+Polite, precise testing misses how real users behave. Once per module's key flow, act like a hurried or inexperienced user:
+
+- **Double-submit probe:** `scout_click {clicks: 2}` on every important submit/create button. The result states explicitly whether the same state-changing request fired twice (unguarded — check for a duplicate record, file as `data-inconsistency`) or once (guarded). This is a top real-world bug class that polite single clicks can never reveal.
+- **Rage-click check:** an element that did nothing once (`ZERO network requests` note) — click it 3× (`clicks: 3`). Still nothing? That's a dead control users will hammer; file it with both signals.
+- **Wrong-order behaviour:** press Enter mid-form before required fields are filled; go `scout_back` mid-wizard and return; submit, then immediately back-button. State should survive all three without data loss or duplicate records.
+- Keep attribution honest: these are deliberate probes — say so in findings ("under rapid double-click…"), so a developer can reproduce exactly.
+
+The engine is self-healing (orphaned browsers reaped, wedged calls time out with guidance instead of hanging) and observable: `.scenescout/status.json` + `scenescout status <project>` show what it's doing right now — point the user there if they ask for live progress.
+
+## Judgment (what the engine can't do)
+
+- **Ground absence-claims in the source before filing.** Black-box behaviour tells you what happened, never *why*. Any finding asserting a control is MISSING ("no permission check", "no validation", "no segregation of duties", "not implemented") must be checked against the codebase first — you have Read/Grep/Bash, use them. Three outcomes, all valuable: (1) genuinely absent → file it with the file:line you checked, which makes it actionable instead of speculative; (2) implemented but not reached on your path → you found a *routing/config* bug, a different and often better finding; (3) implemented elsewhere in the same codebase but not here → **the strongest kind of finding**, an inconsistency against the team's own established pattern, with the reference implementation attached as the fix. A grep costs seconds and is the difference between "I think this is wrong" and "here is the line". Behaviour-only findings (a crash, a 500, a dead end) need no such check — the evidence is self-contained.
+- Oracle violations are *evidence* — reproduce/contextualize, then `scout_finding`. **Severity anchors:** crash, data loss, security/permission breach, or a flow the user cannot complete or escape (infinite spinner, no-way-out page, broken primary journey) = **high** — a dead end is high even without a crash. Broken but recoverable = medium. Polish/friction = low.
+- **Provenance for deep-link findings:** if you reached a state by direct URL (crawl or scout_navigate) and it looks broken (no app shell, dead end), check whether real users can reach it through the UI before filing — many apps render tab content at internal URLs that users only ever reach via `?tab=` links. Always state in the finding how the state was reached.
+- Tabs and views (`?tab=…`) are distinct states in coverage — prefer clicking the actual tab controls when testing a flow; deep-link only to re-verify.
+- **Lifecycle:** if the user says something is fixed, or the evidence no longer reproduces on a route you re-tested, mark it with `scout_resolve {id}` (spelled `findingId` if you prefer the long form). Historical findings in the report are unverified — don't re-report them as new.
+- **A `SHARED CHROME` block in a design audit is ONE finding, not one per page.** Those elements (sidebar, header, breadcrumb bar) are the app shell; the audit already excludes them from the page's score and reports them once. File a single finding for the shell and move on — filing per-page produced five separate tickets for two CSS declarations in a real run.
+- **`scout_finding` takes `severity`, `category`, `title`, `detail` and `evidence`.** `category` is the finding's kind — `http-error`, `console-error`, `dead-end`, `data-inconsistency`, `ux-confusing`, `ux-polish`, `visual`, `a11y`, `missing-testid`, `security`, `page-error`, `other` — and is what groups the report.
+- **Always pass `evidence`** to `scout_finding` — a canonical machine signature like `GET /api/reports/dashboard 403` or `widget dashboard-summary-widget shows 0`. It's what deduplicates the same bug across runs when titles get rephrased.
+- File judgment findings too: confusing flows, no-feedback actions, state lost on refresh, permission leaks (low-privilege role reaching admin surface), `missing-testid` (low), unnamed interactables (a11y, low).
+- Respect refusals — never retry or route around a policy refusal; note it and move on.
+- Duplicates are fine; `scout_finding` dedups across runs.
+
+## Finishing
+
+`scout_report` (satisfy the contract first) → `scout_close` → summarize in chat: worst findings first, coverage numbers, report path (`.scenescout/report.md`), and suggest promoting high findings to real Playwright regression tests (skeletons are in the report).