scenescout 1.1.0 → 1.2.0

package/dist/engine/launch.js

@@ -2,21 +2,28 @@
  * Turning a failed browser launch into something the person can act on.
  *
  * For anyone who installed from npm and never ran the setup step, the first
- * attach fails because Chromium was never downloaded — and Playwright reports
+ * attach fails because the browser was never downloaded — and Playwright reports
  * that as a multi-line box of text with a path in it. That is the single most
  * likely first-run failure, so it gets one plain instruction instead.
  */
+import { APPROX_DISK_MB, launchTarget } from "../browsers.js";
 /** Playwright's wording when the browser binary is not on disk. */
 const MISSING_BROWSER_RE = /Executable doesn't exist|playwright install|browserType\.launch:.*(not found|ENOENT)/i;
 export function isMissingBrowser(message) {
     return MISSING_BROWSER_RE.test(message);
 }
 /** The error text for a launch that failed. `reaped` is how many orphaned browsers were cleaned up between attempts. */
-export function explainLaunchFailure(message, reaped) {
+export function explainLaunchFailure(message, reaped, need = { engine: "chromium", headed: false }) {
     if (isMissingBrowser(message)) {
-        return (`Chromium has not been downloaded yet (one-time, ~150 MB). Run this once, then attach again:\n` +
-            `  npx -y scenescout install --browser-only\n` +
-            `(from a clone: npm run setup). On Linux, if system libraries are missing: npx playwright install --with-deps chromium`);
+        const target = launchTarget(need.engine, need.headed);
+        // Someone who installed only the headless shell did run install, so say what is different about a headed run.
+        const why = target === "chromium" && need.headed
+            ? "A headed run needs the full Chromium browser, which has not been downloaded (the headless shell alone cannot open a window)"
+            : `The ${target} build has not been downloaded yet`;
+        return (`${why} (one-time, about ${APPROX_DISK_MB[target]} MB on disk). Run this once, then attach again:\n` +
+            `  npx -y scenescout install --browser-only --browsers ${target}\n` +
+            `(from a clone: node dist/cli.js install --browser-only --browsers ${target}). ` +
+            `On Linux, if system libraries are missing: npx playwright install --with-deps ${target}`);
     }
     const firstLine = message.split("\n")[0];
     return (`browser launch failed twice (${firstLine})` +

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/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. */
@@ -250,9 +255,20 @@ export function parseRegistration(listing) {
  */
 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" }
-        : { setup: "npx -y scenescout install", build: "npx -y scenescout@latest install   (the installed package is incomplete; fetch it again)" };
+        ? {
+            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) {
@@ -262,12 +278,12 @@ export function diagnose(opts) {
     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: repair.build });
-    const chromiumOk = !!opts.chromiumPath && fs.existsSync(opts.chromiumPath);
+    const browser = opts.defaultBrowser;
     checks.push({
-        name: "chromium downloaded",
-        ok: chromiumOk,
-        detail: opts.chromiumPath ?? "playwright could not name a browser path",
-        fix: `${repair.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;

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,7 +225,7 @@ 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='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.",
+    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)"),
@@ -189,6 +235,10 @@ server.registerTool("scout_attach", {
             .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);
     }

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scenescout",
-  "version": "1.1.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": {

package/skills/scenescout/SKILL.md

@@ -5,16 +5,16 @@ description: AI exploratory UI testing — drive the SceneScout MCP browser tool
 
 # 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]`.
+You are the brain of an exploratory UI tester. The SceneScout MCP server gives you deterministic browser tools (the `scout_*` tools — some clients show them under a prefix: Claude Code lists `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:
+1. **Check the tools exist.** Reading this as the result of `scout_playbook` or of the `explore` prompt? Then they do: go to step 2. Otherwise 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 (these are Claude Code's commands; the README has the config for other clients):
    - 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.
+   If attach later reports that a browser build has not been downloaded, relay the one-time command it names. Attach drives Chromium unless you pass `browser: "firefox"` or `"webkit"`; do that only when the user asks for a cross-browser pass, and say in each finding which browser showed it.
 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, attach in `observe` mode unless the user says form submissions are acceptable on this target (then `read-only`), and never go past `read-only` unless they say the environment is disposable. In `observe` you may fill and submit forms freely: the engine blocks the request, so you still see client-side validation, and nothing is created. 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.