scenescout 1.0.0 → 1.2.0

package/dist/engine/policy.js

@@ -77,8 +77,60 @@ export const AUTH_FLOW_RE = /\/(auth|login|logout|signin|sign-in|signup|sign-up|
 export function isDestructive(...labels) {
     return labels.some((label) => typeof label === "string" && label.length > 0 && DESTRUCTIVE_PATTERNS.some((re) => re.test(label)));
 }
-export function destructiveRefusal(label) {
-    return (`REFUSED by read-only policy: "${label}" matches a destructive-action pattern. ` +
-        `This run is read-only; do not attempt this element again. If destructive flows must be tested, ` +
+export function destructiveRefusal(label, mode = "read-only") {
+    return (`REFUSED by ${mode} policy: "${label}" matches a destructive-action pattern. ` +
+        `This run is ${mode}; do not attempt this element again. If destructive flows must be tested, ` +
         `the user has to re-attach with mode="destructive" against a disposable/seeded environment.`);
 }
+export const WRITE_MODES = ["observe", "read-only", "safe-write", "destructive"];
+/**
+ * May this non-GET request leave the page? Auth-flow requests are let through
+ * before this is asked. `owned` means the request addresses a record this run
+ * created (always false outside safe-write, where nothing is tracked).
+ */
+/**
+ * In observe mode, the only auth requests let through are the ones a session
+ * needs in order to exist: logging in, logging out, refreshing a token. Whole
+ * path SEGMENTS, never substrings — `/users/login-history/clear` and
+ * `/api/tokens` (mint an API token) are not logins — and `session(s)` only as
+ * the last segment, where a POST means "log in", not "act on session 123".
+ */
+const OBSERVE_AUTH_SEGMENT_RE = /^(login|log-in|signin|sign-in|logout|log-out|signout|sign-out|refresh|token|oauth|oauth2|sso|callback|authorize|authenticate)$/i;
+/**
+ * Is this request an auth flow that must work even though the mode would
+ * otherwise block it?
+ *
+ * Never for a destructive-looking request, in any mode: the exemption used to
+ * be tested first, so `POST /api/session/123/delete` went through in read-only
+ * because its path contains "session".
+ *
+ * In observe mode the exemption is much narrower than elsewhere. Signing up,
+ * changing or resetting a password, verifying an email and creating a user all
+ * change data on the target, and observe promises that nothing is created.
+ */
+export function isAuthExempt(mode, method, pathname, destructiveWire) {
+    if (method !== "POST" || destructiveWire)
+        return false;
+    if (mode !== "observe")
+        return AUTH_FLOW_RE.test(pathname);
+    const segments = pathname.split("/").filter(Boolean);
+    if (segments.length === 0)
+        return false;
+    const last = segments[segments.length - 1];
+    if (/^sessions?$/i.test(last))
+        return true;
+    // The matching segment must be at, or next to, the end: /auth/token/refresh, /oauth/token, /login.
+    return (segments.slice(-2).some((seg) => OBSERVE_AUTH_SEGMENT_RE.test(seg)) &&
+        !/^(users?|accounts?|members?|password|signup|sign-up|register|verify|invite|invitations?)$/i.test(last));
+}
+export function allowsWrite(mode, method, destructiveWire, owned) {
+    if (mode === "destructive")
+        return true;
+    if (mode === "observe")
+        return false;
+    // POST: creation/RPC passes unless it looks destructive and is not ours.
+    if (method === "POST")
+        return !destructiveWire || owned;
+    // PUT/PATCH/DELETE: only in safe-write, only on this run's own records.
+    return mode === "safe-write" && owned;
+}

package/dist/engine/probes.js

@@ -1,4 +1,5 @@
 import { DIALOG_LIKE_SEL } from "./collector.js";
+import { focusAdvanceKey, isBrowserEngine } from "../browsers.js";
 /** Per-action Playwright timeout, shared with the engine so a scroll into view fails as fast as a click would. */
 export const ACTION_TIMEOUT_MS = 5000;
 /**
@@ -252,11 +253,13 @@ export async function probeOverlays(page) {
  * than failing the audit.
  */
 export async function probeFocusIndicators(page) {
+    const name = page.context().browser()?.browserType().name();
+    const advanceKey = focusAdvanceKey(name && isBrowserEngine(name) ? name : "chromium", process.platform);
     const styleSig = "s.outlineStyle + '|' + s.outlineWidth + '|' + s.outlineColor + '|' + s.boxShadow + '|' + s.borderColor + '|' + s.backgroundColor";
     const stops = [];
     try {
         for (let i = 0; i < 15; i++) {
-            await page.keyboard.press("Tab");
+            await page.keyboard.press(advanceKey);
             const info = (await page.evaluate(`(() => {
         const el = document.activeElement;
         if (!el || el === document.body || el === document.documentElement) return null;

package/dist/engine/report.js

@@ -289,7 +289,12 @@ export function computeGaps(memory, extras) {
     // and let a mutation anywhere in a wizard clear its sibling steps.
     const { unsubmitted } = classifyFilledStates(memory, facts);
     if (unsubmitted.length > 0) {
-        gaps.push(`${unsubmitted.length} route(s) had a form filled but NEVER submitted (no state-changing request left the page): ${unsubmitted.slice(0, 8).join(", ")}${unsubmitted.length > 8 ? " …" : ""}`);
+        gaps.push(`${unsubmitted.length} route(s) had a form filled but NEVER submitted (no state-changing request left the page): ${unsubmitted.slice(0, 8).join(", ")}${unsubmitted.length > 8 ? " …" : ""}` +
+            // In observe mode this is the mode working, not the run falling short —
+            // but it is still untested surface, so it stays in the ledger, explained.
+            (extras?.mode === "observe"
+                ? ` — expected in observe mode, which blocks every form submission by design; what the server does with these forms is untested. Cover them in read-only mode against an environment where creating records is acceptable.`
+                : ""));
     }
     const journeyTotal = Object.values(facts).reduce((a, f) => a + (f.journeysCompleted ?? 0), 0);
     if (journeyTotal === 0) {

package/dist/installer.js

@@ -9,6 +9,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import { engineOf } from "./browsers.js";
 export const SKILL_NAME = "scenescout";
 export const MCP_NAME = "scenescout";
 /** Names this tool's skill and MCP server had before renames; cleaned up on install so the old slash command and a duplicate tool set do not linger. */
@@ -17,7 +18,11 @@ const LEGACY_MCP_NAMES = ["scenecraft"];
 /** Real runner. `missing` separates "the binary is not installed" from "it ran and failed". */
 export const spawnRunner = (command, args) => {
     const r = spawnSync(command, args, { encoding: "utf8", timeout: 60_000 });
-    const missing = r.error?.code === "ENOENT";
+    const code = r.error?.code;
+    // On Windows node refuses to start a .cmd or .bat file directly (EINVAL). For
+    // the caller that is the same situation as a missing binary: nothing ran, and
+    // the command has to be handed to the person instead.
+    const missing = code === "ENOENT" || (process.platform === "win32" && code === "EINVAL");
     return { status: r.status, stdout: r.stdout ?? "", stderr: r.stderr ?? (r.error ? String(r.error.message) : ""), missing };
 };
 /** Written into a copy-mode install so a later install can tell its own copy from a user's directory. */
@@ -243,24 +248,47 @@ export function parseRegistration(listing) {
     const field = (name) => new RegExp(`^[ \\t]*${name}:[ \\t]*(\\S.*?)[ \\t]*$`, "m").exec(listing)?.[1] ?? null;
     return { command: field("Command"), serverPath: field("Args") };
 }
+/**
+ * The command that repairs a setup, for THIS kind of install. A source checkout
+ * has `npm run setup`; someone who installed from npm has no such script, and
+ * telling them to run it sends them looking for a package.json they never had.
+ */
+export function repairCommands(packageRoot) {
+    const isCheckout = fs.existsSync(path.join(packageRoot, "tsconfig.json")) && fs.existsSync(path.join(packageRoot, "src"));
+    // Installing "chromium" brings the headless shell with it, so the plain
+    // setup command already repairs either Chromium build.
+    const browserFlags = (target) => (engineOf(target) === "chromium" ? "" : ` --browser-only --browsers ${target}`);
+    return isCheckout
+        ? {
+            setup: "npm run setup",
+            build: "npm run build",
+            browser: (target) => (browserFlags(target) ? `node dist/cli.js install${browserFlags(target)}` : "npm run setup"),
+        }
+        : {
+            setup: "npx -y scenescout install",
+            build: "npx -y scenescout@latest install   (the installed package is incomplete; fetch it again)",
+            browser: (target) => `npx -y scenescout install${browserFlags(target)}`,
+        };
+}
 /** Everything a working setup needs, each with the command that repairs it. */
 export function diagnose(opts) {
     const checks = [];
+    const repair = repairCommands(opts.packageRoot);
     const major = Number(opts.nodeVersion.replace(/^v/, "").split(".")[0]);
     checks.push({ name: "node >= 20", ok: major >= 20, detail: opts.nodeVersion, fix: "install Node 20 or newer" });
     const server = path.join(opts.packageRoot, "dist", "mcp-server.js");
-    checks.push({ name: "engine built", ok: fs.existsSync(server), detail: server, fix: "npm run build" });
-    const chromiumOk = !!opts.chromiumPath && fs.existsSync(opts.chromiumPath);
+    checks.push({ name: "engine built", ok: fs.existsSync(server), detail: server, fix: repair.build });
+    const browser = opts.defaultBrowser;
     checks.push({
-        name: "chromium downloaded",
-        ok: chromiumOk,
-        detail: opts.chromiumPath ?? "playwright could not name a browser path",
-        fix: "npm run setup   (or: npx playwright install chromium)",
+        name: `browser downloaded (${browser.target})`,
+        ok: browser.path !== null,
+        detail: browser.path ?? (browser.expected ? `not found at ${browser.expected}` : "playwright could not name a browser path"),
+        fix: `${repair.browser(browser.target)}   (or: npx playwright install ${browser.target})`,
     });
     if (opts.scope === "engine")
         return checks;
     const skill = path.join(opts.claudeDir, "skills", SKILL_NAME, "SKILL.md");
-    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: "npm run setup" });
+    checks.push({ name: "skill installed", ok: fs.existsSync(skill), detail: skill, fix: repair.setup });
     const got = opts.run("claude", ["mcp", "get", MCP_NAME]);
     if (got.missing) {
         checks.push({
@@ -273,7 +301,7 @@ export function diagnose(opts) {
     else {
         const listing = got.stdout + got.stderr;
         if (got.status !== 0) {
-            checks.push({ name: "MCP server registered", ok: false, detail: "no server named scenescout", fix: "npm run setup" });
+            checks.push({ name: "MCP server registered", ok: false, detail: "no server named scenescout", fix: repair.setup });
         }
         else {
             const { command, serverPath } = parseRegistration(listing);
@@ -289,12 +317,12 @@ export function diagnose(opts) {
                     name: "MCP server registered",
                     ok: absolute,
                     detail: absolute ? `via ${command} ${serverPath}` : `registered with a bare \`${command}\` command, which Claude Code may not find on its PATH`,
-                    fix: "scenescout install",
+                    fix: repair.setup,
                 });
             }
             else if (!samePath(serverPath, server)) {
                 // The usual aftermath of moving or deleting a checkout.
-                checks.push({ name: "MCP server registered", ok: false, detail: `registered, but pointing at ${serverPath} — not this install`, fix: "npm run setup" });
+                checks.push({ name: "MCP server registered", ok: false, detail: `registered, but pointing at ${serverPath} — not this install`, fix: repair.setup });
             }
             else if (command !== null && !path.isAbsolute(command)) {
                 // A bare "node" resolves in your shell and then fails inside Claude
@@ -303,7 +331,7 @@ export function diagnose(opts) {
                     name: "MCP server registered",
                     ok: false,
                     detail: `registered with a bare \`${command}\` command, which Claude Code may not find on its PATH`,
-                    fix: "npm run setup",
+                    fix: repair.setup,
                 });
             }
             else {

package/dist/mcp-server.js

@@ -25,8 +25,10 @@
  */
 import fs from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ErrorCode, GetPromptRequestSchema, ListPromptsRequestSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { BrowserEngine } from "./engine/browser.js";
 import { reapOrphanBrowsers } from "./engine/reaper.js";
@@ -34,6 +36,7 @@ import { MemoryStore, redactSecrets } from "./engine/memory.js";
 import { SessionQueue, withWatchdog } from "./engine/dispatch.js";
 import { FIXTURE_KINDS } from "./engine/fixtures.js";
 import { computeGaps, formatRouteCoverage, generateReport } from "./engine/report.js";
+import { EXPLORE_PROMPT_ARGUMENTS, explorePrompt, loadPlaybook, PLAYBOOK_PROMPT, PLAYBOOK_TOOL, SERVER_INSTRUCTIONS } from "./playbook.js";
 import { formatScan, scanProject } from "./scan.js";
 /** Live sessions: each name owns an independent BrowserEngine (browser + auth). */
 const engines = new Map();
@@ -71,7 +74,8 @@ const PKG_VERSION = (() => {
         return "0.0.0";
     }
 })();
-const server = new McpServer({ name: "scenescout", version: PKG_VERSION });
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const server = new McpServer({ name: "scenescout", version: PKG_VERSION }, { instructions: SERVER_INSTRUCTIONS });
 function text(t, session) {
     const eng = engines.get(session);
     const prefix = engines.size > 1 ? `[session ${session}${eng ? ` · ${eng.role}` : ""}]\n` : "";
@@ -167,6 +171,48 @@ const sessionParam = z
     .max(40)
     .optional()
     .describe("Target this session directly instead of the active one — pass it explicitly when dispatching to MULTIPLE sessions in one turn (e.g. two scout_click calls with different `session`), which then run CONCURRENTLY rather than queueing. Omit for single-session sequential use.");
+// The method, for every client that has no skill loader. It is read per call,
+// not cached: a source checkout's skill file can change under a running server.
+server.registerTool(PLAYBOOK_TOOL, {
+    description: "Return the SceneScout testing method: setup order, write modes, how to explore, what counts as done, how to report. " +
+        "Call this ONCE before the first scout_attach in a conversation, then follow it. " +
+        "If this client offers a SceneScout skill, load that instead — it is the same text, so never read both. Takes no input and touches no browser.",
+    // No inputSchema on purpose: with one, a call that carries no `arguments` field is rejected as invalid.
+}, async () => {
+    try {
+        return { content: [{ type: "text", text: loadPlaybook(PACKAGE_ROOT) }] };
+    }
+    catch (err) {
+        return errorText(err);
+    }
+});
+// The same method as a prompt, for clients that list server prompts as commands.
+// Registered on the protocol server directly: the SDK's prompt helper rejects a
+// request that carries no `arguments` object, which is exactly what a client
+// sends when the person typed none, and every argument here is optional.
+server.server.registerCapabilities({ prompts: {} });
+server.server.setRequestHandler(ListPromptsRequestSchema, () => ({
+    prompts: [
+        {
+            name: PLAYBOOK_PROMPT,
+            title: "Explore a web app with SceneScout",
+            description: "Start an exploratory test session: loads the SceneScout method and states the target.",
+            arguments: EXPLORE_PROMPT_ARGUMENTS,
+        },
+    ],
+}));
+server.server.setRequestHandler(GetPromptRequestSchema, (request) => {
+    if (request.params.name !== PLAYBOOK_PROMPT)
+        throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${request.params.name}`);
+    let message;
+    try {
+        message = explorePrompt(loadPlaybook(PACKAGE_ROOT), request.params.arguments);
+    }
+    catch (err) {
+        throw new McpError(ErrorCode.InvalidParams, err instanceof Error ? err.message : String(err));
+    }
+    return { messages: [{ role: "user", content: { type: "text", text: message } }] };
+});
 server.registerTool("scout_scan", {
     description: "Scan a project directory to discover the frontend workspace, framework, routes, dev command, Playwright auth storage states, and testid conventions. Run this first.",
     inputSchema: { projectPath: z.string().describe("Absolute path to the project root") },
@@ -179,16 +225,20 @@ server.registerTool("scout_scan", {
     }
 }));
 server.registerTool("scout_attach", {
-    description: "Launch a browser and attach to a running web app. Write policy is enforced at the NETWORK layer: mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
+    description: "Launch a browser and attach to a running web app. First attach in this conversation and you have read neither the SceneScout skill nor scout_playbook? Call scout_playbook before this. Write policy is enforced at the NETWORK layer: mode='observe' blocks EVERY request that is not a GET (login and token refresh excepted) — choose it for a target that holds real data, where even an ordinary form submission would create a record; mode='read-only' (default) blocks destructive-labeled elements AND all PUT/PATCH/DELETE + destructive POSTs, but lets ordinary form POSTs through; mode='safe-write' allows creating data and permits updates/deletes ONLY on resources this session created (use when the user wants create/edit flows tested); mode='destructive' allows everything — ONLY when the user explicitly confirmed a disposable/seeded environment. Pass a Playwright storage-state JSON to explore as an authenticated role. Pass `session` to keep MULTIPLE roles alive at once (one browser each, genuinely concurrent) for collaboration testing — target each directly with every tool's `session` param, or use scout_session to set which one is the default; coverage and findings merge into one project memory.",
     inputSchema: {
         url: z.string().describe("Base URL of the running app, e.g. http://localhost:3000"),
         projectPath: z.string().describe("Absolute path to the project (memory + report live in .scenescout/ here)"),
         storageStatePath: z.string().optional().describe("Optional Playwright storage-state JSON path for authenticated exploration"),
         mode: z
-            .enum(["read-only", "safe-write", "destructive"])
+            .enum(["observe", "read-only", "safe-write", "destructive"])
             .default("read-only")
             .describe("Write policy (see tool description). Never choose 'destructive' yourself — user opt-in only."),
         headed: z.boolean().default(false).describe("Show the browser window"),
+        browser: z
+            .enum(["chromium", "firefox", "webkit"])
+            .optional()
+            .describe("Browser to drive. Default: the SCENESCOUT_BROWSER environment variable, else chromium. firefox and webkit must be downloaded first (scenescout install --browser-only --browsers firefox). Use them for a cross-browser pass; stay on chromium otherwise."),
         viewportWidth: z.number().int().min(320).max(3840).optional().describe("Viewport width (default 1280); use e.g. 390 for a mobile pass"),
         viewportHeight: z.number().int().min(480).max(2400).optional().describe("Viewport height (default 900)"),
         session: z
@@ -197,7 +247,7 @@ server.registerTool("scout_attach", {
             .optional()
             .describe("Session name for multi-role runs (e.g. 'admin', 'qa'). Creates/replaces that session's browser and makes it the default. Default: 'default'."),
     },
-}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, viewportWidth, viewportHeight, session, }) => {
+}, serializedControl(async ({ url, projectPath, storageStatePath, mode, headed, browser, viewportWidth, viewportHeight, session, }) => {
     try {
         const target = session ?? activeName;
         if (session) {
@@ -258,7 +308,7 @@ server.registerTool("scout_attach", {
             /* conflict detection is best-effort */
         }
         const viewport = viewportWidth && viewportHeight ? { width: viewportWidth, height: viewportHeight } : undefined;
-        const out = await eng.attach({ url, projectDir: projectPath, storageStatePath, mode, headed, viewport, memoryStore: store });
+        const out = await eng.attach({ url, projectDir: projectPath, storageStatePath, mode, headed, browser, viewport, memoryStore: store });
         eng.role = storageStatePath ? path.basename(storageStatePath).replace(/\.json$/i, "") : "anonymous";
         return text(out + conflictNote + (engines.size > 1 ? `\n${sessionLines()}` : ""), target);
     }
@@ -563,7 +613,7 @@ server.registerTool("scout_note", {
     }
 }));
 server.registerTool("scout_screenshot", {
-    description: "Take a JPEG screenshot of the current viewport. LAST RESORT: geometry issues are in scout_snapshot and style/contrast/spacing issues are in scout_design_audit — use a screenshot only for pixel-native content (broken images, canvas, visual gestalt) that computed data cannot capture.",
+    description: "Take a JPEG screenshot of the current viewport. LAST RESORT: geometry issues are in scout_snapshot and style/contrast/spacing issues are in scout_design_audit — images that failed to load are listed in scout_snapshot under BROKEN IMAGES — use a screenshot only for pixel-native content (a canvas, visual gestalt) that computed data cannot capture.",
     inputSchema: { session: sessionParam },
 }, serializedPerSession("scout_screenshot", async (_args, session) => {
     try {
@@ -702,9 +752,13 @@ server.registerTool("scout_report", {
             routesTotal: all.length,
             designAudits: eng.designAuditCount,
             unvisitedRoutes: unvisited,
+            mode: eng.mode,
         });
         if (lvl === "extensive" && gapList.length > 0) {
             gates.push(`Level 'extensive' claims completeness, so it refuses while the GAP LEDGER is non-empty:\n` +
+                (eng.mode === "observe"
+                    ? `(observe mode blocks every form submission, so the unsubmitted-forms gap cannot be closed in this mode: report at level 'medium', which discloses it.)\n`
+                    : "") +
                 gapList.map((g) => `  ⚠ ${g}`).join("\n") +
                 `\nClose the gaps (or report at level 'medium', which discloses them instead).`);
         }
@@ -718,6 +772,7 @@ server.registerTool("scout_report", {
             designAudits: eng.designAuditCount,
             createdResources: eng.createdResources,
             unvisitedRoutes: unvisited,
+            mode: eng.mode,
             policyAttributed: eng.oracleLog.policyAttributed,
         });
         void p;

package/dist/playbook.js

@@ -0,0 +1,83 @@
+/**
+ * The testing method, served by the MCP server itself.
+ *
+ * The method lives in skills/scenescout/SKILL.md. Claude Code loads that file
+ * as a skill; no other client does, so an agent there gets the tools and none
+ * of the method: the setup order, the write modes, what counts as done. The
+ * server hands the same text to any client through a tool, a prompt and a short
+ * pointer in its instructions. One file, so the two can never disagree.
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const PLAYBOOK_TOOL = "scout_playbook";
+export const PLAYBOOK_PROMPT = "explore";
+/** Where the method is kept, relative to the package root. It is in the package's `files`. */
+export const PLAYBOOK_RELATIVE_PATH = path.join("skills", "scenescout", "SKILL.md");
+/**
+ * Sent to every client when it connects. Short on purpose: clients cut long
+ * instructions, and one that is cut in the middle is worse than a pointer.
+ */
+export const SERVER_INSTRUCTIONS = `SceneScout explores a running web app in a real browser and reports bugs, UX problems and coverage. ` +
+    `The scout_* tools are deterministic; the method for using them well is a separate text. ` +
+    `If this client offers a SceneScout skill, load that. Otherwise call ${PLAYBOOK_TOOL} once, before the first scout_attach in a conversation, and follow what it returns. ` +
+    `They are the same text, so never read both. ` +
+    `Never choose mode="destructive" yourself: that needs the user's explicit opt-in.`;
+export const LEVELS = ["minimal", "medium", "extensive"];
+/** What the `explore` prompt accepts, as MCP lists it. Every argument is optional. */
+export const EXPLORE_PROMPT_ARGUMENTS = [
+    { name: "url", description: "URL of the running app, e.g. http://localhost:3000", required: false },
+    { name: "level", description: `How far to go: ${LEVELS.join(", ")}`, required: false },
+    { name: "focus", description: "An area or flow to concentrate on", required: false },
+];
+/** The skill file without its YAML front matter, which only a skill loader reads. */
+export function stripFrontMatter(markdown) {
+    // An editor may save the file with a byte-order mark; it would hide the opening fence.
+    const text = markdown.replace(/^\uFEFF/, "");
+    // The fences may hold nothing between them, and the closing one may be the last line of the file.
+    const m = /^---[ \t]*\r?\n(?:[\s\S]*?\r?\n)?---[ \t]*(?:\r?\n|$)/.exec(text);
+    // Leading blank LINES go; indentation on the first line of the body stays.
+    return (m ? text.slice(m[0].length) : text).replace(/^(?:[ \t]*\r?\n)+/, "");
+}
+/**
+ * The method text. Throws when the file is not where the package puts it: an
+ * agent told "here is the method" and handed an empty string would proceed
+ * without one and never say so.
+ */
+export function loadPlaybook(packageRoot) {
+    const file = path.join(packageRoot, PLAYBOOK_RELATIVE_PATH);
+    let raw;
+    try {
+        raw = fs.readFileSync(file, "utf8");
+    }
+    catch (err) {
+        throw new Error(`The SceneScout playbook is missing from this install (${file}): ${err instanceof Error ? err.message : String(err)}. Reinstall the package.`);
+    }
+    const body = stripFrontMatter(raw);
+    if (body.trim().length === 0)
+        throw new Error(`The SceneScout playbook at ${file} is empty. Reinstall the package.`);
+    // Front matter that was not recognised would be served to the agent as if it were the method.
+    if (/^---[ \t]*(\r?\n|$)/.test(body))
+        throw new Error(`The SceneScout playbook at ${file} has front matter that could not be read. Reinstall the package.`);
+    return body;
+}
+/**
+ * The opening message of the `explore` prompt: the method, then what the person
+ * asked for. `args` is whatever the client sent, which may be nothing at all.
+ * A level the method does not know is refused, not passed on for the agent to guess at.
+ */
+export function explorePrompt(playbook, args) {
+    const given = (name) => {
+        const v = args?.[name];
+        return typeof v === "string" && v.trim() ? v.trim() : undefined;
+    };
+    const level = given("level");
+    if (level !== undefined && !LEVELS.includes(level)) {
+        throw new Error(`level "${level}" is not one the method knows. Use one of: ${LEVELS.join(", ")}.`);
+    }
+    const asks = [
+        given("url") ? `Target: ${given("url")}` : "Target: ask me for the URL of the running app, or find it from the project.",
+        level ? `Level: ${level}` : "",
+        given("focus") ? `Focus: ${given("focus")}` : "",
+    ].filter(Boolean);
+    return `${playbook}\n\n---\n\nRun an exploratory test session following the method above.\n${asks.join("\n")}`;
+}

package/dist/scan.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { codeRoutes } from "./code-routes.js";
 /**
  * What marks a package.json as a frontend workspace.
  *
@@ -10,6 +11,8 @@ import path from "node:path";
  * "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"];
+/** Frameworks whose routes live in code rather than in the filesystem. */
+const CODE_ROUTED = new Set(["vite+react", "react", "create-react-app", "vue", "vite", "angular"]);
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "coverage", "out", "docs", "examples", "e2e-tests"]);
 function readJson(file) {
     try {
@@ -272,13 +275,34 @@ export function scanProject(projectDir) {
             : framework === "nuxt"
                 ? fileRoutes(frontendDir, "nuxt")
                 : [];
+    // Routers configured in code (React Router, Vue Router, Angular): read the
+    // route records statically. Remix is file-routed in its own way and is not
+    // covered here.
+    let codeRouteFiles = [];
+    if (routes.length === 0 && framework !== null && CODE_ROUTED.has(framework)) {
+        const found = codeRoutes(frontendDir);
+        routes.push(...found.routes);
+        codeRouteFiles = found.files;
+        if (found.unresolved.length > 0) {
+            notes.push(`${found.unresolved.length} lazily loaded route branch(es) could not be followed (${found.unresolved.slice(0, 3).join(", ")}${found.unresolved.length > 3 ? ", …" : ""}): ` +
+                `the branch's own path is listed, the pages under it are not. Links found while exploring add them.`);
+        }
+        if (found.truncated) {
+            notes.push(`The source tree was too large or too deep to list completely, so a router file may have been missed; routes read from source may be incomplete.`);
+        }
+    }
     // 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 (codeRouteFiles.length > 0) {
+        notes.push(`${routes.length} route(s) read statically from the router configuration in ${codeRouteFiles.slice(0, 3).join(", ")}${codeRouteFiles.length > 3 ? ", …" : ""}. ` +
+            `Routes built at runtime (from data, a loop, or an identifier this reader could not follow) are not in this list; links found while exploring add to 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.`);
+        notes.push(`No routes could be read from source for "${framework}": it is not file-routed, and no router configuration this reader can follow was found ` +
+            `(routes built at runtime, or a router it does not know). The route contract will be built from links harvested during exploration, ` +
+            `so 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"));

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "1.2.0",
+  "description": "SceneScout — exploratory UI testing for AI coding agents. An MCP server that gives any agent (Claude Code, Cursor, VS Code Copilot, Codex, Gemini CLI and others) a structured view of a running web app, always-on oracles, a network-level write policy, memory across runs and a gap-checked report.",
   "license": "MIT",
   "author": "brunoboto96",
   "repository": {
@@ -14,13 +14,24 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "exploratory-testing",
     "ui-testing",
+    "e2e-testing",
+    "qa",
     "playwright",
+    "browser-automation",
+    "ai-agent",
+    "ai-testing",
+    "accessibility",
     "claude-code",
-    "qa",
-    "ai-agent"
+    "cursor",
+    "vscode",
+    "github-copilot",
+    "codex",
+    "gemini-cli",
+    "windsurf"
   ],
   "type": "module",
   "bin": {
@@ -47,7 +58,7 @@
     "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",
+    "version-packages": "changeset version && node scripts/sync-plugin-version.mjs && npm install --package-lock-only && prettier --write package.json .claude-plugin/plugin.json",
     "release": "npm run build && changeset publish",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
@@ -60,7 +71,7 @@
     "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",
+    "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 && npm run hygiene-test",
     "scan-test": "tsx scripts/scan-test.ts",
     "oracle-test": "tsx --test scripts/oracle-test.ts",
     "policy-test": "tsx --test scripts/policy-test.ts",
@@ -69,7 +80,8 @@
     "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"
+    "install-test": "tsx --test scripts/install-test.ts",
+    "hygiene-test": "tsx --test scripts/hygiene-test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",