@pcamarajr/scout 0.5.0 → 0.7.0

package/dist/runner/engines/claude-agent-sdk.js

@@ -0,0 +1,117 @@
+import { createSdkMcpServer, query, tool } from "@anthropic-ai/claude-agent-sdk";
+/**
+ * The original, trusted engine: runs the verification through the
+ * `@anthropic-ai/claude-agent-sdk` subprocess. Behavior here is intentionally
+ * IDENTICAL to the pre-refactor ai-runner: bypassPermissions, empty
+ * settingSources, allowedTools scoped to the in-process MCP browser server, the
+ * query()+drain() loop, and an abort-in-finally so no subprocess outlives a run.
+ */
+export class ClaudeAgentSdkEngine {
+    async run(spec) {
+        const browserServer = createSdkMcpServer({
+            name: "browser",
+            version: "1.0.0",
+            tools: spec.tools.map(toAgentSdkTool),
+        });
+        const baseOptions = {
+            model: spec.model,
+            systemPrompt: spec.systemPrompt,
+            mcpServers: { browser: browserServer },
+            allowedTools: ["mcp__browser__*"],
+            tools: [],
+            settingSources: [],
+            permissionMode: "bypassPermissions",
+        };
+        const transcript = [];
+        let sessionId;
+        let endInfo;
+        // Drains a query, collecting transcript/session/end info. Always aborts at
+        // the end so no claude-agent-sdk subprocess outlives the run.
+        const drain = async (q, controller) => {
+            try {
+                for await (const message of q) {
+                    if ("session_id" in message && message.session_id)
+                        sessionId = message.session_id;
+                    if (message.type === "assistant") {
+                        for (const block of message.message.content) {
+                            if (block.type === "text" && block.text.trim())
+                                transcript.push(block.text.trim());
+                        }
+                    }
+                    if (message.type === "result") {
+                        endInfo = {
+                            subtype: message.subtype,
+                            numTurns: message.num_turns,
+                            errors: "errors" in message ? message.errors : undefined,
+                        };
+                        break;
+                    }
+                }
+            }
+            finally {
+                controller.abort();
+            }
+        };
+        const mainController = new AbortController();
+        try {
+            await drain(query({
+                prompt: spec.userPrompt,
+                options: { ...baseOptions, maxTurns: spec.maxTurns, abortController: mainController },
+            }), mainController);
+        }
+        catch (error) {
+            endInfo = {
+                subtype: "sdk_error",
+                errors: [error instanceof Error ? error.message : String(error)],
+            };
+        }
+        const resume = async (prompt, maxTurns) => {
+            const resumeTranscript = [];
+            let resumeEnd;
+            if (!sessionId) {
+                return { end: { subtype: "no_session" }, transcript: resumeTranscript };
+            }
+            const rescueController = new AbortController();
+            // Reuse drain() so transcript/session/end semantics stay identical, then
+            // split off only what the rescue produced for the resume result.
+            const beforeLen = transcript.length;
+            try {
+                await drain(query({
+                    prompt,
+                    options: { ...baseOptions, maxTurns, resume: sessionId, abortController: rescueController },
+                }), rescueController);
+                resumeEnd = endInfo;
+            }
+            catch (error) {
+                resumeEnd = {
+                    subtype: "sdk_error",
+                    errors: [error instanceof Error ? error.message : String(error)],
+                };
+            }
+            resumeTranscript.push(...transcript.slice(beforeLen));
+            return { end: resumeEnd ?? { subtype: "no_session" }, transcript: resumeTranscript };
+        };
+        return {
+            get end() {
+                return endInfo ?? { subtype: "sdk_error" };
+            },
+            transcript,
+            resume,
+        };
+    }
+}
+/**
+ * Adapts an engine-neutral ScoutTool into the Agent SDK `tool()` shape. The
+ * Agent SDK's tool() wants a raw Zod shape, so we hand it `schema.shape`, and we
+ * map our normalized {text, isError} result back into a CallToolResult.
+ */
+function toAgentSdkTool(scoutTool) {
+    return tool(scoutTool.name, scoutTool.description, scoutTool.schema.shape, async (args) => {
+        const result = await scoutTool.handler(args);
+        return {
+            content: [{ type: "text", text: result.text }],
+            ...(result.isError ? { isError: true } : {}),
+        };
+    });
+}
+//# sourceMappingURL=claude-agent-sdk.js.map

package/dist/runner/engines/claude-agent-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-agent-sdk.js","sourceRoot":"","sources":["../../../src/runner/engines/claude-agent-sdk.ts"],"names":[],"mappings":"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"}

package/dist/runner/engines/index.d.ts

@@ -0,0 +1,20 @@
+import type { AiProvider } from "../../credentials.js";
+import { AiSdkEngine } from "./ai-sdk.js";
+import { ClaudeAgentSdkEngine } from "./claude-agent-sdk.js";
+import type { AgentEngine } from "./types.js";
+/** The two engines Scout can run an AI verification through. */
+export type EngineKind = "agent-sdk" | "ai-sdk";
+/**
+ * Resolves which engine to use. Explicit preference (SCOUT_ENGINE / config
+ * `engine`) wins. Otherwise the default is forward-looking: the trusted Agent
+ * SDK for Anthropic, the AI SDK for non-Anthropic providers (which is the only
+ * engine that can reach them — still gated by credential detection until those
+ * providers are wired up).
+ */
+export declare function resolveEngineKind(provider: AiProvider, enginePref: EngineKind | undefined): EngineKind;
+/** Instantiates the engine for a provider + explicit preference. */
+export declare function selectEngine(provider: AiProvider, enginePref: EngineKind | undefined): AgentEngine;
+/** Parses a raw SCOUT_ENGINE / config value, ignoring unknown strings. */
+export declare function parseEngineKind(value: string | undefined): EngineKind | undefined;
+export { AiSdkEngine, ClaudeAgentSdkEngine };
+export type { AgentEngine };

package/dist/runner/engines/index.js

@@ -0,0 +1,28 @@
+import { AiSdkEngine } from "./ai-sdk.js";
+import { ClaudeAgentSdkEngine } from "./claude-agent-sdk.js";
+/**
+ * Resolves which engine to use. Explicit preference (SCOUT_ENGINE / config
+ * `engine`) wins. Otherwise the default is forward-looking: the trusted Agent
+ * SDK for Anthropic, the AI SDK for non-Anthropic providers (which is the only
+ * engine that can reach them — still gated by credential detection until those
+ * providers are wired up).
+ */
+export function resolveEngineKind(provider, enginePref) {
+    if (enginePref)
+        return enginePref;
+    return provider === "anthropic" ? "agent-sdk" : "ai-sdk";
+}
+/** Instantiates the engine for a provider + explicit preference. */
+export function selectEngine(provider, enginePref) {
+    return resolveEngineKind(provider, enginePref) === "ai-sdk"
+        ? new AiSdkEngine()
+        : new ClaudeAgentSdkEngine();
+}
+/** Parses a raw SCOUT_ENGINE / config value, ignoring unknown strings. */
+export function parseEngineKind(value) {
+    if (value === "agent-sdk" || value === "ai-sdk")
+        return value;
+    return undefined;
+}
+export { AiSdkEngine, ClaudeAgentSdkEngine };
+//# sourceMappingURL=index.js.map

package/dist/runner/engines/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/runner/engines/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAM7D;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAC/B,QAAoB,EACpB,UAAkC;IAElC,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC3D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAC1B,QAAoB,EACpB,UAAkC;IAElC,OAAO,iBAAiB,CAAC,QAAQ,EAAE,UAAU,CAAC,KAAK,QAAQ;QACzD,CAAC,CAAC,IAAI,WAAW,EAAE;QACnB,CAAC,CAAC,IAAI,oBAAoB,EAAE,CAAC;AACjC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,eAAe,CAAC,KAAyB;IACvD,IAAI,KAAK,KAAK,WAAW,IAAI,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC9D,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/runner/engines/types.d.ts

@@ -0,0 +1,68 @@
+import type { AiProvider } from "../../credentials.js";
+import type { Step, Verdict } from "../../types.js";
+import type { ScoutTool } from "../agent-tools.js";
+export interface AiRunOutcome {
+    verdict: Verdict;
+    reason: string;
+    steps: Step[];
+    transcript: string[];
+    /**
+     * Set when the runner itself failed to produce a verdict (agent never called
+     * scout_verdict) — NOT a UI judgment. Callers may retry and must report it
+     * as an infrastructure failure, never as "the scenario is blocked by the UI".
+     */
+    runnerFailure?: string;
+}
+/**
+ * How an engine run ended, for no-verdict diagnostics. The Agent SDK fills this
+ * from the SDK `result` message; the AI SDK engine maps its `finishReason` into
+ * the same `subtype` vocabulary so {@link describeNoVerdict} works unchanged.
+ */
+export interface QueryEndInfo {
+    subtype: string;
+    numTurns?: number;
+    errors?: string[];
+}
+/**
+ * Human-readable cause for a run that ended without scout_verdict.
+ * Distinguishes runner-infrastructure causes (turn budget, SDK errors) from
+ * an agent that simply stopped talking.
+ */
+export declare function describeNoVerdict(end: QueryEndInfo | undefined, maxTurns: number): string;
+/**
+ * Records navigation relative to the configured baseUrl so cached scripts
+ * survive --base-url / SCOUT_BASE_URL pointing at another server. URLs that
+ * merely share the prefix (http://localhost:3000x) or live on other hosts
+ * stay absolute.
+ */
+export declare function relativizeUrl(url: string, baseUrl: string): string;
+/** Everything an engine needs to drive one agent run. */
+export interface EngineRunSpec {
+    /** Inferred from the model id; selects the AI SDK provider in the AI SDK engine. */
+    provider: AiProvider;
+    model: string;
+    systemPrompt: string;
+    userPrompt: string;
+    tools: ScoutTool[];
+    maxTurns: number;
+}
+/** The result of resuming a session (the forced-verdict rescue). */
+export interface EngineResumeResult {
+    end: QueryEndInfo;
+    transcript: string[];
+}
+/**
+ * A live (or just-finished) engine session. The shared orchestrator reads
+ * `end`/`transcript`, and — if no verdict was captured — calls `resume()` to
+ * run the forced-verdict rescue with a small turn budget.
+ */
+export interface EngineSession {
+    end: QueryEndInfo;
+    /** Assistant text collected during the run, in order. */
+    transcript: string[];
+    resume(prompt: string, maxTurns: number): Promise<EngineResumeResult>;
+}
+/** A pluggable agent engine. `run` performs the initial verification pass. */
+export interface AgentEngine {
+    run(spec: EngineRunSpec): Promise<EngineSession>;
+}

package/dist/runner/engines/types.js

@@ -0,0 +1,37 @@
+/**
+ * Human-readable cause for a run that ended without scout_verdict.
+ * Distinguishes runner-infrastructure causes (turn budget, SDK errors) from
+ * an agent that simply stopped talking.
+ */
+export function describeNoVerdict(end, maxTurns) {
+    if (!end)
+        return "a sessão do agente terminou sem emitir resultado (subprocesso morreu?)";
+    switch (end.subtype) {
+        case "error_max_turns":
+            return `o agente estourou o limite de ${maxTurns} turns sem chamar scout_verdict`;
+        case "error_during_execution":
+            return `erro durante a execução do agente${end.errors?.length ? `: ${end.errors.join("; ")}` : ""}`;
+        case "success":
+            return "o agente encerrou normalmente sem chamar scout_verdict";
+        default:
+            return `a sessão do agente terminou com "${end.subtype}"${end.errors?.length ? `: ${end.errors.join("; ")}` : ""}`;
+    }
+}
+/**
+ * Records navigation relative to the configured baseUrl so cached scripts
+ * survive --base-url / SCOUT_BASE_URL pointing at another server. URLs that
+ * merely share the prefix (http://localhost:3000x) or live on other hosts
+ * stay absolute.
+ */
+export function relativizeUrl(url, baseUrl) {
+    const base = baseUrl.replace(/\/+$/, "");
+    if (url === base || url === `${base}/`)
+        return "/";
+    if (url.startsWith(base)) {
+        const rest = url.slice(base.length);
+        if (rest.startsWith("/") || rest.startsWith("?") || rest.startsWith("#"))
+            return rest;
+    }
+    return url;
+}
+//# sourceMappingURL=types.js.map

package/dist/runner/engines/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/runner/engines/types.ts"],"names":[],"mappings":"AA4BA;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAA6B,EAAE,QAAgB;IAC/E,IAAI,CAAC,GAAG;QAAE,OAAO,wEAAwE,CAAC;IAC1F,QAAQ,GAAG,CAAC,OAAO,EAAE,CAAC;QACpB,KAAK,iBAAiB;YACpB,OAAO,iCAAiC,QAAQ,iCAAiC,CAAC;QACpF,KAAK,wBAAwB;YAC3B,OAAO,oCAAoC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACtG,KAAK,SAAS;YACZ,OAAO,wDAAwD,CAAC;QAClE;YACE,OAAO,oCAAoC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IACvH,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,GAAW,EAAE,OAAe;IACxD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACzC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACnD,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACpC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;IACxF,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/scaffold.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Onboarding artifacts written by `scout init` so any AI agent in the consuming
+ * repo can help a QA team configure Scout and author `.scout.md` scenarios.
+ *
+ * Three files, two ownership models:
+ *   - AGENTS.md (repo root) — SHARED with the user and other tools. Scout owns
+ *     only a managed block delimited by the markers below; everything outside
+ *     it is left untouched.
+ *   - .claude/skills/scout/SKILL.md and .cursor/rules/scout.mdc — Scout-OWNED,
+ *     overwritten on every init (init is the upgrade path).
+ *
+ * Re-running init refreshes all three. `scout.config.json` is never touched here.
+ */
+export declare const SCOUT_BLOCK_START = "<!-- scout:start -->";
+export declare const SCOUT_BLOCK_END = "<!-- scout:end -->";
+/** Resolve the bundled `templates/` dir, whether running from `src/` or `dist/`. */
+export declare function templatesDir(): string;
+/**
+ * Embed `body` inside the scout managed block in `existing` content.
+ *
+ *  - no existing content        → just the block.
+ *  - existing WITH a block       → replace ONLY the block's contents.
+ *  - existing WITHOUT a block    → append the block, preserving everything else.
+ */
+export declare function applyManagedBlock(existing: string | undefined, body: string): string;
+export interface ScaffoldDeps {
+    cwd?: string;
+    log?: (message: string) => void;
+}
+/** Write/refresh AGENTS.md (managed block), the Claude skill, and the Cursor rule. */
+export declare function scaffoldAgentOnboarding(deps?: ScaffoldDeps): void;

package/dist/scaffold.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Onboarding artifacts written by `scout init` so any AI agent in the consuming
+ * repo can help a QA team configure Scout and author `.scout.md` scenarios.
+ *
+ * Three files, two ownership models:
+ *   - AGENTS.md (repo root) — SHARED with the user and other tools. Scout owns
+ *     only a managed block delimited by the markers below; everything outside
+ *     it is left untouched.
+ *   - .claude/skills/scout/SKILL.md and .cursor/rules/scout.mdc — Scout-OWNED,
+ *     overwritten on every init (init is the upgrade path).
+ *
+ * Re-running init refreshes all three. `scout.config.json` is never touched here.
+ */
+export const SCOUT_BLOCK_START = "<!-- scout:start -->";
+export const SCOUT_BLOCK_END = "<!-- scout:end -->";
+const AGENTS_FILE = "AGENTS.md";
+const SKILL_FILE = path.join(".claude", "skills", "scout", "SKILL.md");
+const CURSOR_RULE_FILE = path.join(".cursor", "rules", "scout.mdc");
+/** Resolve the bundled `templates/` dir, whether running from `src/` or `dist/`. */
+export function templatesDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    // here is <pkg>/src or <pkg>/dist → templates sits at <pkg>/templates
+    return path.join(here, "..", "templates");
+}
+function readTemplate(name) {
+    return fs.readFileSync(path.join(templatesDir(), name), "utf8");
+}
+/**
+ * Embed `body` inside the scout managed block in `existing` content.
+ *
+ *  - no existing content        → just the block.
+ *  - existing WITH a block       → replace ONLY the block's contents.
+ *  - existing WITHOUT a block    → append the block, preserving everything else.
+ */
+export function applyManagedBlock(existing, body) {
+    const block = `${SCOUT_BLOCK_START}\n${body.trim()}\n${SCOUT_BLOCK_END}\n`;
+    if (existing === undefined || existing.trim() === "") {
+        return block;
+    }
+    const startIdx = existing.indexOf(SCOUT_BLOCK_START);
+    const endIdx = existing.indexOf(SCOUT_BLOCK_END);
+    if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+        const before = existing.slice(0, startIdx);
+        const after = existing.slice(endIdx + SCOUT_BLOCK_END.length);
+        // Trim a leading newline off `after` so we don't accumulate blank lines.
+        return `${before}${block}${after.replace(/^\n/, "")}`;
+    }
+    // No block yet — append, keeping the user's content and a clean separator.
+    const sep = existing.endsWith("\n") ? "\n" : "\n\n";
+    return `${existing}${sep}${block}`;
+}
+/** Write/refresh AGENTS.md (managed block), the Claude skill, and the Cursor rule. */
+export function scaffoldAgentOnboarding(deps = {}) {
+    const cwd = deps.cwd ?? process.cwd();
+    const log = deps.log ?? ((m) => console.log(m));
+    // 1. AGENTS.md — managed block, never clobbers surrounding content.
+    const agentsPath = path.join(cwd, AGENTS_FILE);
+    const body = readTemplate("AGENTS.md");
+    const existing = fs.existsSync(agentsPath) ? fs.readFileSync(agentsPath, "utf8") : undefined;
+    const had = existing !== undefined;
+    const hadBlock = had && existing.includes(SCOUT_BLOCK_START);
+    fs.writeFileSync(agentsPath, applyManagedBlock(existing, body));
+    log(hadBlock
+        ? `✓ ${AGENTS_FILE} — refreshed the Scout block.`
+        : had
+            ? `✓ ${AGENTS_FILE} — appended the Scout block (your content kept).`
+            : `✓ ${AGENTS_FILE} created.`);
+    // 2. Claude Code skill — Scout-owned, overwrite.
+    const skillPath = path.join(cwd, SKILL_FILE);
+    fs.mkdirSync(path.dirname(skillPath), { recursive: true });
+    fs.writeFileSync(skillPath, readTemplate("SKILL.md"));
+    log(`✓ ${SKILL_FILE}`);
+    // 3. Cursor rule — Scout-owned, overwrite.
+    const cursorPath = path.join(cwd, CURSOR_RULE_FILE);
+    fs.mkdirSync(path.dirname(cursorPath), { recursive: true });
+    fs.writeFileSync(cursorPath, readTemplate("scout.mdc"));
+    log(`✓ ${CURSOR_RULE_FILE}`);
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/scaffold.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.js","sourceRoot":"","sources":["../src/scaffold.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pcamarajr/scout",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Self-healing browser QA: natural-language scenarios verified by an AI agent, replayed deterministically in CI",
   "type": "module",
   "license": "MIT",
@@ -35,19 +35,26 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit",
     "test": "node --import tsx --test tests/*.test.ts",
+    "smoke": "node scripts/smoke.mjs",
     "prepublishOnly": "npm run build",
     "prepare": "husky"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
+    "@ai-sdk/google": "^3.0.83",
+    "@ai-sdk/google-vertex": "^4.0.147",
+    "@ai-sdk/openai": "^3.0.73",
     "@anthropic-ai/claude-agent-sdk": "^0.3.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
+    "ai": "^6.0.208",
     "commander": "^13.1.0",
     "gray-matter": "^4.0.3",
     "playwright": "^1.52.0",

package/templates/AGENTS.md

@@ -0,0 +1,100 @@
+# Scout — browser QA for AI agents
+
+Scout turns **natural-language scenarios** into **AI-verified, deterministically-replayed** browser tests. A scenario is written in plain English in a `.scout.md` file; on its first `scout go` an AI agent drives a real browser (Playwright), judges the outcome, and records a deterministic script. Every later run replays that script with **no LLM** — fast and free — and only falls back to AI when the script breaks (self-heal).
+
+This file is the **single source of truth** for how an AI agent should help a QA team work with Scout in this repo. The Claude Code skill and the Cursor rule both point here.
+
+## Your primary job: co-author scenarios with QA
+
+When a QA person describes a flow they want covered, **you write the `.scout.md` directly** — do not make them hand-write it. You have full repo context (routes, components, copy, auth), so you can author a richer, more accurate spec than the CLI scaffold (`scout create`) ever could. Then you verify it and iterate with the human until it is green.
+
+The loop:
+
+1. **Author** — translate the QA person's intent into one or more scenarios in a `.scout.md` file (format below). Capture the flow *and* the expected behavior, in plain language. No selectors, no code.
+2. **Verify** — run `scout go` (optionally `-s <slug>` to target one scenario). The first run is AI-driven, in a real browser.
+3. **Interpret** — read the verdict Scout reports and relay it to the human verbatim (see *Verdicts* below).
+4. **Iterate** — refine the scenario text with QA until the verdict is `verified`, then commit the `.scout.md` and the recorded script.
+
+> `scout create <name> -f <feature> -c <text>` exists as a convenience for **humans without an agent**. As the agent, prefer authoring the `.scout.md` directly — you can write a fuller spec from repo context.
+
+## ⛔ Verification-integrity rule (non-negotiable)
+
+**Never declare a scenario working, passing, or done without actually running `scout go` and reporting the real verdict.**
+
+- Do **not** fabricate, assume, or predict success. Run it.
+- Report the verdict Scout produced **verbatim** — including the `reason` line.
+- If the result is `failed`, `partial`, or `blocked`, say so honestly. If a replay **healed**, surface that and show the script diff so a human can review what changed.
+
+This rule protects Scout's entire value proposition: a verdict is trustworthy only because it came from a real run. Inventing one poisons the suite.
+
+## The `.scout.md` authoring guide
+
+Scenarios live as markdown under `.scout/specs/**/*.scout.md` — **one file per feature/component**, versioned and reviewed like any other test. The markdown is a **pure input**: a run never writes back to it (status lives in `.scout/runs/`), so the spec diff only ever reflects an intent change.
+
+Format:
+
+```markdown
+---
+feature: Paywall          # optional; defaults to the filename
+profile: anon             # optional; default auth profile for scenarios below
+tags: [monetization]      # optional
+---
+
+## Free user hits paywall on ep 3
+Open ep 3 of series X without login; the paywall appears with a signup CTA.
+
+## Subscriber bypasses paywall
+profile: qa               # per-scenario override (also: notes, tags)
+
+Logged-in subscriber opens ep 3; the episode plays with no paywall.
+```
+
+Rules that matter when you author:
+
+- **Frontmatter** (YAML, optional): `feature` (defaults to the filename), `profile` (default auth profile), `tags`.
+- **Each `## heading` is one scenario.** Its logical slug is `<file-slug>/<scenario-slug>` (e.g. `paywall/free-user-hits-paywall-on-ep-3`) and must be unique across the suite. Duplicate headings in a file, or a scenario with no body text, are hard errors.
+- **Per-scenario overrides:** immediately under a heading you may place `profile:`, `notes:`, and `tags:` lines (before the prose) to override the file-level defaults.
+- **Body = flow + expected behavior, in plain language.** Describe what the user does and what must (or must not) be true. No CSS selectors, no Playwright code — the agent discovers the real elements at run time and records them.
+- A `.scout.md` whose every `##` lives inside a fenced ```` ``` ```` block parses as **zero scenarios** (that is how `example.scout.md` documents the format without polluting the suite).
+
+## Base URL and secrets
+
+There is a **default base URL** set at `scout init` (in `scout.config.json`). It can be **overridden per run** without editing the file:
+
+- `scout go --base-url https://staging.example.com`
+- `SCOUT_BASE_URL=https://staging.example.com scout go`
+- Precedence: `--base-url` flag > `SCOUT_BASE_URL` env > `baseUrl` in `scout.config.json`.
+
+Recorded scripts store navigation **relative to the base URL in effect at record time**, so a script recorded against `:3000` replays unchanged against staging.
+
+For credentials and tokens, never put a literal secret in a scenario. Use a **`$ENV:VAR` placeholder** — Scout resolves it from the environment at run time, in both **form fills** and **`browser_navigate` URLs** (e.g. `/renew?token=$ENV:RENEW_TOKEN`). The real value never enters the committed script and never passes through the LLM. Declare the allowed env vars per auth profile in `scout.config.json` (`profiles.<name>.env`).
+
+## Verdicts (what `scout go` reports)
+
+| Verdict | Meaning |
+|---|---|
+| `verified` ✅ | All expected behavior confirmed by assertions. |
+| `failed` ❌ | Broken behavior — the `reason` says exactly what. |
+| `partial` ⚠️ | Only part of the expected behavior was confirmed. |
+| `blocked` 🚫 | Couldn't reach the flow at all (app down, login broken). |
+
+**Healed:** when a cached script breaks but the AI re-verifies and re-records it, the run is flagged `healed`. The recorded-script diff is the heal diff — review it; a legitimate UI change is fine to commit, an unexpected one is a real regression.
+
+**Runner failure ≠ UI verdict:** an AI run can die without producing a verdict (turn budget exhausted, SDK error). Scout flags that as `runnerFailure` / 💥 — it is an infrastructure failure, **not** a judgment about the app. Rerun it; don't debug the app over it.
+
+## Secondary: helping triage a failed replay
+
+When a replay comes back `failed`/`partial`/`blocked` or `healed`, you can help — but the **human stays in the loop on intent**. Triage flow:
+
+1. Read the `reason` and open the run artifacts under `.scout/runs/<timestamp>-<slug>/` — `report.md` (verdict + recorded script), `trace.zip` (`npx playwright show-trace`), screenshots, and `transcript.md` for AI runs.
+2. Decide *with the human* whether this is a **real regression** (the app broke → fix the app) or a **legitimate UI change** (the spec/script is stale → re-verify with `scout go --ai -s <slug>` to re-record, then review the diff).
+3. Never silently re-record to make a red suite green. A green verdict must reflect reality.
+
+## Defer to the live CLI for commands and flags
+
+Commands and flags evolve — read them live instead of trusting a copy:
+
+- `scout --help` — all commands.
+- `scout <command> --help` — flags for one command (e.g. `scout go --help`).
+
+The core commands you will use: `scout go` (verify/replay), `scout list` (scenarios + status), `scout report` (suite summary, `--check` for a CI gate). `scout init` is the setup/upgrade entry point and also refreshes these onboarding files.

package/templates/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: scout
+description: >
+  Help a QA team use Scout — browser QA where natural-language scenarios are
+  AI-verified once and then replayed deterministically. TRIGGER when the user
+  mentions Scout, a `.scout.md` scenario, `scout.config.json`, `scout go` /
+  `scout init` / `scout report`, browser/E2E/QA testing of a user flow, or asks
+  to author, verify, replay, or triage a browser test scenario. Do NOT trigger
+  for unrelated unit tests or non-browser work.
+---
+
+# Scout
+
+Scout is self-healing browser QA: QA describes a flow in plain English, an AI
+agent verifies it once in a real browser and records a deterministic script,
+and every later run replays that script with no LLM.
+
+Your job is to **co-author `.scout.md` scenarios** with QA, **verify** them with
+`scout go`, and **report the real verdict** — never claim a scenario passes
+without running it.
+
+**Read `AGENTS.md` at the repo root — it is the canonical, always-current guide**
+to the authoring loop, the `.scout.md` format, base-URL/secret handling,
+verdicts, and failure triage. Follow it. For commands and flags, run
+`scout --help` / `scout <command> --help`.

package/templates/scout.mdc

@@ -0,0 +1,21 @@
+---
+description: Scout browser QA — authoring and verifying .scout.md scenarios.
+globs:
+  - "**/*.scout.md"
+  - "scout.config.json"
+alwaysApply: false
+---
+
+# Scout
+
+When working with Scout files (`*.scout.md`, `scout.config.json`), you are
+helping a QA team with **browser QA**: natural-language scenarios that are
+AI-verified once and then replayed deterministically.
+
+Co-author `.scout.md` scenarios with QA, verify them with `scout go`, and report
+the **real** verdict — never claim a scenario passes without running it.
+
+**Read `AGENTS.md` at the repo root** — it is the canonical, always-current
+guide to the authoring loop, the `.scout.md` format, base-URL/secret handling,
+verdicts, and failure triage. For commands and flags, run `scout --help` /
+`scout <command> --help`.