@beryl-so/cli 0.11.1 → 0.14.1

package/README.md

@@ -71,6 +71,14 @@ Set up Beryl in this repo — sign in and wire up your coding agent
 | --- | --- | --- |
 | `beryl init` | Set up Beryl in this repo — sign in and wire up your coding agent | — |
 
+### guide
+
+Print the Beryl test-authoring guide
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl guide` | Print the Beryl test-authoring guide | `guide` |
+
 ### login
 
 Authenticate the CLI with your Beryl account
@@ -302,9 +310,7 @@ Drive a browser session that captures a target-site login for Beryl to reuse.
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) | `auth_capture_start` |
-| `beryl auth-capture login <session-id>` | Log into the target site headlessly with credentials (no human at the browser) | `auth_capture_login` |
-| `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL | `auth_capture_capture` |
-| `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring | `auth_capture_refresh` |
+| `beryl auth-capture capture <session-id>` | Save the session after the user has logged in via the live-view URL (first login or re-login) | `auth_capture_capture` |
 | `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing | `auth_capture_release` |
 
 ### inbox

package/dist/adapters/mcp.js

@@ -75,7 +75,14 @@ export async function serveMcp(baseCtx) {
     // Fire-and-forget staleness warning: a stale MCP server silently exposes fewer
     // tools, and stderr is the one channel a stdio MCP server can safely log to.
     void warnIfStale(cliVersion(), (msg) => console.error(msg));
-    const server = new Server({ name: "beryl", version: cliVersion() }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "beryl", version: cliVersion() }, {
+        capabilities: { tools: {} },
+        instructions: "Beryl authors, runs, and heals end-to-end tests for any web app: tests are JSON " +
+            "action plans replayed in real cloud browsers, with per-run email inboxes that make " +
+            "signup/OTP/magic-link flows fully self-contained (no human login needed). Before " +
+            "authoring your first test plan, call the `guide` tool — it returns the full " +
+            "authoring guide (plan shape, outcome assertions, email/OTP wiring, run-fix loop).",
+    });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: mcpTools().map((spec) => ({
             name: toolName(spec),

package/dist/commands/credentials.js

@@ -1,6 +1,5 @@
-import { UsageError } from "../errors.js";
 import { dim, green, yellow } from "../output.js";
-import { arg, flagBool, flagStr } from "./util.js";
+import { arg, flagBool } from "./util.js";
 const capturePath = (ws, p) => `/auth-capture/workspaces/${ws}/projects/${p}/sessions`;
 export const credentialCommands = [
     {
@@ -98,7 +97,7 @@ export const credentialCommands = [
                     .del(`${capturePath(workspaceId, projectId)}/${session.session_id}`)
                     .catch(() => { });
             }
-            return { human: `${green("Login captured.")} ${dim("The agent can now test the gated app.")}` };
+            return { human: `${green("Login captured.")} ${dim("The agent can test the gated app with it.")}` };
         },
     },
     {
@@ -111,40 +110,9 @@ export const credentialCommands = [
             return { data: await ctx.client.post(capturePath(workspaceId, projectId)) };
         },
     },
-    {
-        name: "auth-capture login",
-        summary: "Log into the target site headlessly with credentials (no human at the browser)",
-        description: "Drives the login inside the capture session started by `auth-capture start`, so " +
-            "an agent can complete start → login → capture with zero human intervention. The " +
-            "credentials are sent to the server, typed into the target site over the wire, and " +
-            "never stored, logged, or returned — the captured session stays encrypted " +
-            "server-side. Follow with `auth-capture capture` to snapshot the authenticated session.",
-        scope: "project",
-        args: [
-            { name: "session-id", description: "Session id from auth-capture start", required: true },
-        ],
-        flags: [
-            { name: "username", type: "string", description: "Login username / email", required: true },
-            { name: "password", type: "string", description: "Login password", required: true },
-            {
-                name: "login-url",
-                type: "string",
-                description: "Explicit login page URL (defaults to the session's current page)",
-            },
-        ],
-        async run(ctx, input) {
-            const { workspaceId, projectId } = await ctx.requireProject(input);
-            const username = flagStr(input, "username");
-            const password = flagStr(input, "password");
-            if (!username || !password)
-                throw new UsageError("--username and --password are required");
-            await ctx.client.post(`${capturePath(workspaceId, projectId)}/${arg(input, "session-id")}/login`, { username, password, login_url: flagStr(input, "login-url") ?? null });
-            return { human: "Logged in." };
-        },
-    },
     {
         name: "auth-capture capture",
-        summary: "Capture the session after the user has logged in via the live-view URL",
+        summary: "Save the session after the user has logged in via the live-view URL (first login or re-login)",
         scope: "project",
         args: [{ name: "session-id", description: "Session id from auth-capture start", required: true }],
         async run(ctx, input) {
@@ -153,17 +121,6 @@ export const credentialCommands = [
             return { human: "Captured." };
         },
     },
-    {
-        name: "auth-capture refresh",
-        summary: "Capture a refreshed session for a project whose login is expiring",
-        scope: "project",
-        args: [{ name: "session-id", description: "Session id from auth-capture start", required: true }],
-        async run(ctx, input) {
-            const { workspaceId, projectId } = await ctx.requireProject(input);
-            await ctx.client.post(`${capturePath(workspaceId, projectId)}/${arg(input, "session-id")}/capture-refresh`);
-            return { human: "Captured." };
-        },
-    },
     {
         name: "auth-capture release",
         summary: "Release a login-capture browser session without capturing",

package/dist/commands/init.js

@@ -7,7 +7,7 @@ import { loadConfig } from "../config.js";
 import { CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
 import { bold, cyan, dim, green, red, yellow } from "../output.js";
-import { confirmInstall, hasPlaywrightTest, installPlaywright, PLAYWRIGHT_INSTALL_COMMANDS, } from "../playwright-install.js";
+import { hasPlaywrightTest, installPlaywright, PLAYWRIGHT_INSTALL_COMMANDS, } from "../playwright-install.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
 import { flagStr } from "./util.js";
@@ -27,7 +27,7 @@ const PLAYWRIGHT_SERVER_ENTRY = {
     args: ["@playwright/mcp@latest", "--headless"],
 };
 const ACTION_PLAN_SCHEMA_URL = "https://api.beryl.so/api/v1/schemas/action-plan.schema.json";
-function mergeMcpConfig(file, withPlaywright) {
+function mergeMcpConfig(file) {
     let existing = {};
     if (fs.existsSync(file)) {
         try {
@@ -41,13 +41,10 @@ function mergeMcpConfig(file, withPlaywright) {
     const beryl = JSON.stringify(servers.beryl) !== JSON.stringify(MCP_SERVER_ENTRY);
     if (beryl)
         servers.beryl = MCP_SERVER_ENTRY;
-    let playwright;
-    if (withPlaywright) {
-        // Never clobber a playwright server the user already wired up.
-        playwright = servers.playwright === undefined;
-        if (playwright)
-            servers.playwright = PLAYWRIGHT_SERVER_ENTRY;
-    }
+    // Never clobber a playwright server the user already wired up.
+    const playwright = servers.playwright === undefined;
+    if (playwright)
+        servers.playwright = PLAYWRIGHT_SERVER_ENTRY;
     if (beryl || playwright) {
         existing.mcpServers = servers;
         fs.mkdirSync(path.dirname(file), { recursive: true });
@@ -85,14 +82,6 @@ function claudeAddHint(name, entry) {
 function cursorUserConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
-function detectEditors(cwd) {
-    const editors = [];
-    if (fs.existsSync(path.join(cwd, ".claude")) || fs.existsSync(path.join(cwd, "CLAUDE.md")))
-        editors.push("claude-code");
-    if (fs.existsSync(path.join(cwd, ".cursor")))
-        editors.push("cursor");
-    return editors;
-}
 // Write the skill to one `.../beryl-test/SKILL.md` file. Idempotent: an identical copy is
 // left alone; a customer-EDITED copy is never clobbered — we notice and skip so their
 // changes survive a re-run.
@@ -111,89 +100,78 @@ function writeSkillFile(file) {
     return { outcome: "wrote", file };
 }
 const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
-// The authoring skill always lands in the vendor-neutral `.agents/skills/` dir (mirroring
-// Momentic) — any coding agent that reads `.agents/skills/` picks it up. Claude Code does
-// NOT index `.agents/skills/`; it auto-discovers skills from `~/.claude/skills/` (user
-// scope) and the repo's `.claude/skills/` (project scope). So when `claude-code` is a
-// selected editor we ALSO write the same skill string to the `.claude/skills/` location
-// that matches the MCP `--scope`, or the user never sees it. Each destination is written
-// with the same idempotent / never-clobber-a-customer-edit behavior.
-function writeSkills(cwd, editors, scope) {
-    const results = [writeSkillFile(skillLeaf(path.join(cwd, ".agents", "skills")))];
-    if (editors.includes("claude-code")) {
-        const claudeRoot = scope === "user"
-            ? path.join(os.homedir(), ".claude", "skills")
-            : path.join(cwd, ".claude", "skills");
-        results.push(writeSkillFile(skillLeaf(claudeRoot)));
-    }
-    return results;
+// The authoring skill follows the `--scope` flag, same as the MCP servers: under `user`
+// (the default) it lands in the HOME `.agents/skills/` + `.claude/skills/` dirs, so the
+// knowledge travels with the user into every session the user-scoped MCP tools do —
+// otherwise an agent outside this repo has all the tools and none of the guide. Under
+// `project` both copies stay repo-local (committed, so teammates get them with the repo).
+// `.agents/skills/` is the vendor-neutral location; Claude Code does NOT index it, so the
+// same string also goes to `.claude/skills/`, which Claude Code auto-discovers. Both are
+// written with the same idempotent / never-clobber-a-customer-edit behavior. Existing
+// repo-local copies from earlier inits are left untouched.
+function writeSkills(cwd, scope) {
+    const root = scope === "user" ? os.homedir() : cwd;
+    return [
+        writeSkillFile(skillLeaf(path.join(root, ".agents", "skills"))),
+        writeSkillFile(skillLeaf(path.join(root, ".claude", "skills"))),
+    ];
 }
-// Local authoring drives a real browser via `@playwright/test` + chromium. init wires the
-// Playwright MCP but historically installed neither, so the first `beryl runs local` hit a wall.
-// On a TTY we offer to install now; non-interactively we print the exact commands rather than
-// running installs unprompted (which would be a surprise in CI). Never throws — a declined or
-// failed install must not fail `init`, which has already done its wiring.
+// Local authoring drives a real browser via `@playwright/test` + chromium, and the whole
+// authoring workflow (walk the flow first, then bank the plan) depends on it — so the
+// install is mandatory, not offered: missing means install now, no prompt, no opt-out.
+// Never throws — a failed install must not fail `init`, which has already done its wiring;
+// it prints the exact commands to finish by hand instead.
 async function ensureLocalPlaywright(ctx, cwd) {
     if (hasPlaywrightTest(cwd)) {
         ctx.err(`${green("✓")} @playwright/test already installed ${dim("(local runs ready)")}`);
         return;
     }
-    const hint = () => ctx.err(`${dim("•")} To run tests locally, install Playwright in this project:\n` +
-        `    ${cyan(PLAYWRIGHT_INSTALL_COMMANDS)}`);
-    if (!ctx.interactive || !(await confirmInstall(ctx.prompt))) {
-        hint();
-        return;
-    }
     try {
         await installPlaywright(cwd, (line) => ctx.err(dim(line)));
         ctx.err(`${green("✓")} Local Playwright installed ${dim("(local runs ready)")}`);
     }
     catch (err) {
         ctx.err(`${red("✗")} Playwright install failed: ${err.message}`);
-        hint();
+        ctx.err(`${dim("•")} Finish the install by hand — local runs and browser authoring need it:\n` +
+            `    ${cyan(PLAYWRIGHT_INSTALL_COMMANDS)}`);
     }
 }
 export const initCommands = [
     {
         name: "init",
         summary: "Set up Beryl in this repo — sign in and wire up your coding agent",
-        description: "One-command onboarding: signs you in (emailed one-time code) and wires the MCP servers " +
-            "for your coding agent, then hands off to Claude. By default they're wired per-user " +
-            "(matching where your login token lives) — via `claude mcp add -s user` for Claude Code, " +
-            "~/.cursor/mcp.json for Cursor; pass --scope project to write a committed .mcp.json for a " +
-            "shared repo instead. No workspace/project pin and no URL prompt — open your editor and ask " +
-            "Claude to write tests for your site; it resolves the workspace/project and sets the URL for " +
-            "you. Safe to re-run; every step skips what is already set up.",
+        description: "One-command onboarding: signs you in (emailed one-time code) and wires up your coding " +
+            "agent. Nothing is detected and nothing is conditional — every run wires the beryl AND " +
+            "playwright MCP servers, installs the authoring skill (user scope: your home " +
+            ".agents/skills/ + .claude/skills/, so it follows you into every session; --scope " +
+            "project: the repo's own dirs, committed for teammates), and installs @playwright/test " +
+            "+ chromium if missing — browser authoring and local runs depend on it. By default the " +
+            "servers are wired per-user (matching where your login token lives) via `claude mcp add " +
+            "-s user`; pass --scope project to write a committed .mcp.json for a shared repo " +
+            "instead. No workspace/project pin and no URL prompt — ask Claude to write tests for " +
+            "your site and it resolves the workspace, project, and URL. Safe to re-run; every step " +
+            "is idempotent and skips what is already set up.",
         interactive: true,
         flags: [
-            {
-                name: "editor-tools",
-                type: "string",
-                enum: ["claude-code", "cursor", "both", "none"],
-                description: "Which coding agent to write MCP config for (default: auto-detect)",
-            },
             {
                 name: "scope",
                 type: "string",
                 enum: ["user", "project"],
                 description: "Where to wire the MCP servers. `user` (default) configures them per-user (matching " +
-                    "where your Beryl login token lives) via `claude mcp add -s user` / ~/.cursor/mcp.json. " +
-                    "`project` writes a committed .mcp.json for a shared repo — every teammate still runs " +
-                    "`beryl login` to authenticate",
+                    "where your Beryl login token lives) via `claude mcp add -s user`. `project` writes a " +
+                    "committed .mcp.json for a shared repo — every teammate still runs `beryl login` to " +
+                    "authenticate",
             },
             {
-                name: "local",
+                name: "cursor",
                 type: "boolean",
-                description: "Also wire the Playwright MCP so your coding agent can drive a local browser, and " +
-                    "offer to install @playwright/test + chromium so local runs work (for authoring tests " +
-                    "yourself). Default: on whenever a coding agent is wired; pass --no-local to skip it",
+                description: "Also write the same two MCP servers to Cursor's config",
             },
         ],
         examples: [
             "npx @beryl-so/cli@latest init",
-            "beryl init --editor-tools claude-code",
             "beryl init --scope project",
-            "beryl init --editor-tools none",
+            "beryl init --cursor",
         ],
         async run(ctx, input) {
             const cwd = process.cwd();
@@ -210,57 +188,37 @@ export const initCommands = [
                     throw new CliError("Login did not persist a token");
                 client = new ApiClient(config.apiUrl, config.token);
             }
-            const choice = flagStr(input, "editor-tools") ?? "auto";
-            const editors = choice === "auto"
-                ? detectEditors(cwd)
-                : choice === "both"
-                    ? ["claude-code", "cursor"]
-                    : choice === "none"
-                        ? []
-                        : [choice];
-            // Wiring an editor's MCP config at all implies the user wants to author tests there,
-            // and local authoring needs the Playwright MCP — so default it on. `--no-local` (parsed
-            // as an explicit false) opts out.
-            const local = input.flags.local ?? editors.length > 0;
             const scope = (flagStr(input, "scope") ?? "user");
-            for (const editor of editors) {
-                if (scope === "user" && editor === "claude-code") {
-                    // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
-                    const berylOk = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
-                    const playwrightOk = local ? claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY) : undefined;
-                    if (berylOk) {
-                        ctx.err(`${green("✓")} claude-code MCP configured ${dim("(user scope)")}`);
-                        if (playwrightOk)
-                            ctx.err(`${green("✓")} claude-code Playwright MCP configured ${dim("(user scope)")}`);
-                    }
-                    else {
-                        ctx.err(yellow("• `claude` not on PATH — run these to wire user-scope MCP servers:"));
-                        ctx.err(`    ${cyan(claudeAddHint("beryl", MCP_SERVER_ENTRY))}`);
-                        if (local)
-                            ctx.err(`    ${cyan(claudeAddHint("playwright", PLAYWRIGHT_SERVER_ENTRY))}`);
-                    }
-                    continue;
+            const report = (label, fresh, where) => ctx.err(`${green("✓")} ${label} ${fresh ? "configured" : "already configured"} ${dim(where)}`);
+            if (scope === "user") {
+                // Claude Code owns ~/.claude.json — shell out to `claude mcp add` rather than write it.
+                const berylOk = claudeUserAdd("beryl", MCP_SERVER_ENTRY);
+                const playwrightOk = claudeUserAdd("playwright", PLAYWRIGHT_SERVER_ENTRY);
+                if (berylOk && playwrightOk) {
+                    ctx.err(`${green("✓")} beryl + playwright MCP configured ${dim("(user scope)")}`);
                 }
-                const file = editor === "claude-code"
-                    ? path.join(cwd, ".mcp.json")
-                    : scope === "user"
-                        ? cursorUserConfigPath()
-                        : path.join(cwd, ".cursor", "mcp.json");
-                const wrote = mergeMcpConfig(file, local);
+                else {
+                    ctx.err(yellow("• `claude` not on PATH — run these to wire user-scope MCP servers:"));
+                    ctx.err(`    ${cyan(claudeAddHint("beryl", MCP_SERVER_ENTRY))}`);
+                    ctx.err(`    ${cyan(claudeAddHint("playwright", PLAYWRIGHT_SERVER_ENTRY))}`);
+                }
+            }
+            else {
+                const file = path.join(cwd, ".mcp.json");
+                const wrote = mergeMcpConfig(file);
+                const where = path.relative(cwd, file);
+                report("beryl MCP", wrote.beryl, where);
+                report("playwright MCP", wrote.playwright, where);
+            }
+            if (input.flags.cursor) {
+                const file = scope === "user" ? cursorUserConfigPath() : path.join(cwd, ".cursor", "mcp.json");
+                const wrote = mergeMcpConfig(file);
                 const where = scope === "user" ? file : path.relative(cwd, file);
-                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(where)}`);
-                if (wrote.playwright !== undefined)
-                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(where)}`);
+                report("cursor beryl MCP", wrote.beryl, where);
+                report("cursor playwright MCP", wrote.playwright, where);
             }
-            if (choice === "auto" && editors.length === 0)
-                ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));
-            // The authoring skill always goes to `.agents/skills/` (any `.agents/skills/`-aware
-            // harness gets it); when claude-code is selected it ALSO goes to the `.claude/skills/`
-            // location Claude Code actually indexes (per --scope), or the user never sees it.
-            const skills = writeSkills(cwd, editors, scope);
+            const skills = writeSkills(cwd, scope);
             for (const skill of skills) {
-                // Repo-relative for paths under cwd (`.agents/…`, project-scope `.claude/…`);
-                // absolute for a user-scope `~/.claude/…` path that lives outside the repo.
                 const rel = path.relative(cwd, skill.file);
                 const skillWhere = rel.startsWith("..") ? skill.file : rel;
                 if (skill.outcome === "customized")
@@ -268,25 +226,38 @@ export const initCommands = [
                 else
                     ctx.err(`${green("✓")} Beryl authoring skill ${skill.outcome === "wrote" ? "installed" : "already installed"} ${dim(skillWhere)}`);
             }
-            // Local authoring needs @playwright/test + chromium on the customer's machine; wiring the
-            // Playwright MCP alone isn't enough. Offer/print the install so the first `beryl runs local`
-            // just works instead of hitting a "Local Playwright not found" wall.
-            if (local)
-                await ensureLocalPlaywright(ctx, cwd);
+            await ensureLocalPlaywright(ctx, cwd);
             const nextSteps = `\n${bold("Beryl is set up — now open your editor and ask Claude to write tests.")}\n` +
                 `  ${dim('• Say: "write tests for https://your-app.com" — Claude picks your workspace/project')}\n` +
                 `  ${dim("  and sets the URL for you (no pin, no prompt).")}\n` +
-                (local
-                    ? `  ${dim("• Playwright MCP is wired — Claude can drive a real browser to author from your plan.")}\n`
-                    : `  ${dim("• Re-run with --editor-tools to wire the Playwright MCP for local authoring.")}\n`) +
+                `  ${dim("• Playwright MCP is wired — Claude can drive a real browser to author from your plan.")}\n` +
                 `\nAuthor against the ActionPlan JSON Schema: ${cyan(ACTION_PLAN_SCHEMA_URL)}`;
             // The .mcp.json entry is pinned to @latest, but a global install / old npx cache
             // still wins resolution — so tell the user when the CLI they just ran is stale.
             await warnIfStale(cliVersion(), (msg) => ctx.err(yellow(msg)));
             return {
-                data: { editors },
+                data: {
+                    scope,
+                    skills: skills.map((s) => {
+                        const rel = path.relative(cwd, s.file);
+                        return rel.startsWith("..") ? s.file : rel;
+                    }),
+                },
                 human: nextSteps,
             };
         },
     },
+    {
+        name: "guide",
+        summary: "Print the Beryl test-authoring guide",
+        description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
+            "assertions, natural-language intent, per-run email inboxes for OTP/signup flows " +
+            "({{inbox_address}} + await_email), and the local run-fix loop. The same content " +
+            "`beryl init` installs as the beryl-test skill — call this before authoring your " +
+            "first plan when no skill is installed (works without logging in).",
+        examples: ["beryl guide"],
+        async run() {
+            return { human: BERYL_TEST_SKILL };
+        },
+    },
 ];

package/dist/commands/tests.js

@@ -1,10 +1,44 @@
 import fs from "node:fs";
 import { UsageError } from "../errors.js";
+import { ApiError } from "../http.js";
 import { lintPlan } from "../lint.js";
 import { table } from "../output.js";
 import { ACTION_PLAN_SCHEMA } from "../schema.generated.js";
 import { arg, argList, flagBool, flagNum, flagStr, projectPath, readJsonFlag } from "./util.js";
 const testPath = (ws, p, id) => `${projectPath(ws, p)}/tests/${id}`;
+// The server transcodes a failure screenshot to WebP to fit it under the payload cap,
+// so the format is not knowable up front — sniff it off the decoded magic bytes rather
+// than asserting PNG.
+export function sniffImageMime(b64) {
+    const head = Buffer.from(b64.slice(0, 24), "base64");
+    if (head.subarray(0, 4).toString("latin1") === "RIFF" && head.subarray(8, 12).toString("latin1") === "WEBP") {
+        return "image/webp";
+    }
+    if (head.subarray(0, 3).toString("hex") === "ffd8ff")
+        return "image/jpeg";
+    return "image/png";
+}
+// A verify-failure 422 carries evidence (a11y page state + failure screenshot).
+// Returned as a CommandResult rather than thrown: a thrown error is text-only in
+// the MCP adapter, and the screenshot only reaches the agent as image content.
+function verifyFailureResult(err) {
+    if (!(err instanceof ApiError) || err.status !== 422)
+        return undefined;
+    const detail = err.detail;
+    if (typeof detail !== "object" || detail === null || !detail.message)
+        return undefined;
+    const parts = [detail.message];
+    if (detail.error_context) {
+        parts.push("", "----- Page state at failure (accessibility snapshot) -----", detail.error_context);
+    }
+    return {
+        human: parts.join("\n"),
+        images: detail.screenshot_b64
+            ? [{ data: detail.screenshot_b64, mimeType: sniffImageMime(detail.screenshot_b64) }]
+            : undefined,
+        exitCode: 1,
+    };
+}
 // The concise human table for `tests list` — the full TestResponse is a 24-column
 // firehose of internal ids that wraps unreadably in a normal terminal. `--wide`
 // (and `--json`) still expose every field.
@@ -124,14 +158,22 @@ export const testCommands = [
             if (!title)
                 throw new UsageError("--title is required");
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            return {
-                data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
-                    title,
-                    plan: readJsonFlag(input, "file"),
-                    verify: !flagBool(input, "no-verify"),
-                    description: flagStr(input, "description"),
-                }),
-            };
+            try {
+                return {
+                    data: await ctx.client.post(`${projectPath(workspaceId, projectId)}/tests`, {
+                        title,
+                        plan: readJsonFlag(input, "file"),
+                        verify: !flagBool(input, "no-verify"),
+                        description: flagStr(input, "description"),
+                    }),
+                };
+            }
+            catch (err) {
+                const failure = verifyFailureResult(err);
+                if (failure)
+                    return failure;
+                throw err;
+            }
         },
     },
     {
@@ -227,8 +269,14 @@ export const testCommands = [
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
+            const res = (await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: readJsonFlag(input, "file") }));
+            // Base64 in the JSON output would flood the caller's context — hand the
+            // failure screenshot over as image content instead.
+            const shot = typeof res.screenshot_b64 === "string" ? res.screenshot_b64 : undefined;
+            delete res.screenshot_b64;
             return {
-                data: await ctx.client.post(`${testPath(workspaceId, projectId, arg(input, "test-id"))}/plan/recompile`, { json_plan: readJsonFlag(input, "file") }),
+                data: res,
+                images: shot ? [{ data: shot, mimeType: sniffImageMime(shot) }] : undefined,
             };
         },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.11.1",
+  "version": "0.14.1",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
@@ -34,6 +34,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",