@beryl-so/cli 0.9.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
@@ -160,7 +168,7 @@ Create and manage projects — a site Beryl explores, authors tests for, and run
 | --- | --- | --- |
 | `beryl projects list` | List projects in the workspace | `projects_list` |
 | `beryl projects get` | Show one project, including its current exploration state | `projects_get` |
-| `beryl projects create <url>` | Create a project — the agent starts exploring and authoring tests immediately | `projects_create` |
+| `beryl projects create [url]` | Create a project — with a URL the agent starts exploring; with just --name an empty one | `projects_create` |
 | `beryl projects rename <name>` | Rename a project | `projects_rename` |
 | `beryl projects delete` | Delete a project and all its tests and runs | `projects_delete` |
 | `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows | — |
@@ -302,19 +310,18 @@ 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
 
-Disposable email inboxes for testing flows that send mail — signups, OTPs, receipts.
+Email inboxes for testing flows that send mail — signups, OTPs, receipts.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl inbox create` | Mint a disposable email inbox that Beryl receives mail for | `inbox_create` |
+| `beryl inbox create` | Mint an email inbox that Beryl receives mail for | `inbox_create` |
 | `beryl inbox list` | List the workspace's inboxes, newest first | `inbox_list` |
+| `beryl inbox delete <inbox-id>` | Delete an inbox and every email it has received | `inbox_delete` |
 | `beryl inbox read <inbox-id>` | Read the latest email from an inbox (waits for one to arrive) | `inbox_read` |
 | `beryl inbox emails <inbox-id>` | List the emails an inbox has received | `inbox_emails` |
 

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/beryl-test-skill.js

@@ -1,5 +1,7 @@
 // The `beryl-test` authoring skill, installed by `beryl init` into
-// `.agents/skills/beryl-test/SKILL.md` (vendor-neutral, editor-agnostic). Kept as an
+// `.agents/skills/beryl-test/SKILL.md` (vendor-neutral, editor-agnostic) — and, when
+// claude-code is a selected editor, ALSO into the `.claude/skills/beryl-test/SKILL.md`
+// that Claude Code actually indexes (see `writeSkills` in `commands/init.ts`). Kept as an
 // embedded string so it ships in the published package (`files: ["dist"]`) with no
 // build-time asset copy, and so there is ONE source for the guidance — not a copy in
 // the CLI and another in the docs. Edit here; `init` writes it verbatim.

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/inboxes.js

@@ -25,25 +25,35 @@ function extractCode(email) {
 export const inboxCommands = [
     {
         name: "inbox create",
-        summary: "Mint a disposable email inbox that Beryl receives mail for",
-        groupSummary: "Disposable email inboxes for testing flows that send mail — signups, OTPs, receipts.",
+        summary: "Mint an email inbox that Beryl receives mail for",
+        groupSummary: "Email inboxes for testing flows that send mail — signups, OTPs, receipts.",
         description: "Creates a receiving address under Beryl's inbound email domain and returns it. " +
             "Use it wherever a test needs a real, readable mailbox — e.g. as the --email for " +
-            "`beryl signup`, then read the code back with `beryl inbox read --extract-code`.",
+            "`beryl signup`, then read the code back with `beryl inbox read --extract-code`. " +
+            "Pass --permanent to mint the workspace's single permanent mailbox (no TTL).",
         scope: "workspace",
         flags: [
+            {
+                name: "permanent",
+                type: "boolean",
+                description: "Mint the workspace's permanent mailbox (no TTL); one per workspace",
+            },
             {
                 name: "ttl-hours",
                 type: "number",
-                description: "Hours before the inbox expires and stops receiving (1-168, default 24)",
+                description: "Hours before the inbox expires and stops receiving (1-168, default 24; ignored with --permanent)",
             },
             { name: "project", type: "string", description: "Attach the inbox to a project id" },
         ],
-        examples: ["beryl inbox create --json", "beryl inbox create --ttl-hours 2"],
+        examples: [
+            "beryl inbox create --json",
+            "beryl inbox create --ttl-hours 2",
+            "beryl inbox create --permanent",
+        ],
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
             const inbox = (await ctx.client.post(`/workspaces/${ws}/inboxes`, {
-                ttl_hours: flagNum(input, "ttl-hours") ?? 24,
+                ttl_hours: flagBool(input, "permanent") ? null : (flagNum(input, "ttl-hours") ?? 24),
                 project_id: flagStr(input, "project") ?? null,
             }));
             return {
@@ -58,11 +68,33 @@ export const inboxCommands = [
         summary: "List the workspace's inboxes, newest first",
         description: "Every inbox the workspace has minted with `beryl inbox create`. Expired inboxes " +
             "stop receiving and are hard-deleted by a background sweep, so they drop off " +
-            "this list shortly after their TTL.",
+            "this list shortly after their TTL. Pass --permanent for just the permanent mailbox.",
+        scope: "workspace",
+        flags: [
+            {
+                name: "permanent",
+                type: "boolean",
+                description: "Only the workspace's permanent mailbox (no TTL, not run/project scoped)",
+            },
+        ],
+        async run(ctx, input) {
+            const ws = await ctx.requireWorkspace(input);
+            const query = flagBool(input, "permanent") ? { permanent: true } : undefined;
+            return { data: await ctx.client.get(`/workspaces/${ws}/inboxes`, query) };
+        },
+    },
+    {
+        name: "inbox delete",
+        summary: "Delete an inbox and every email it has received",
         scope: "workspace",
+        args: [{ name: "inbox-id", description: "Inbox id from `beryl inbox create`", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
-            return { data: await ctx.client.get(`/workspaces/${ws}/inboxes`) };
+            const id = arg(input, "inbox-id");
+            await ctx.confirm(`Delete inbox ${id} and its emails?`, flagBool(input, "force"));
+            await ctx.client.del(`/workspaces/${ws}/inboxes/${id}`);
+            return { human: "Deleted." };
         },
     },
     {
@@ -118,11 +150,16 @@ export const inboxCommands = [
         args: [{ name: "inbox-id", description: "Inbox id from `beryl inbox create`", required: true }],
         flags: [
             { name: "since", type: "string", description: "Only emails received after this ISO timestamp" },
+            {
+                name: "limit",
+                type: "number",
+                description: "Return only the most recent N emails (newest first)",
+            },
         ],
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
             return {
-                data: await ctx.client.get(`/workspaces/${ws}/inboxes/${arg(input, "inbox-id")}/emails`, { since: flagStr(input, "since") }),
+                data: await ctx.client.get(`/workspaces/${ws}/inboxes/${arg(input, "inbox-id")}/emails`, { since: flagStr(input, "since"), limit: flagNum(input, "limit") }),
             };
         },
     },

package/dist/commands/init.js

@@ -6,7 +6,8 @@ import { BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } fr
 import { loadConfig } from "../config.js";
 import { CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
-import { bold, cyan, dim, green, yellow } from "../output.js";
+import { bold, cyan, dim, green, red, yellow } from "../output.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";
@@ -26,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 {
@@ -40,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 });
@@ -84,20 +82,10 @@ 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;
-}
-// The authoring skill lives in the vendor-neutral `.agents/skills/` dir (mirroring
-// Momentic), NOT `.claude/` — any coding agent that reads `.agents/skills/` picks it up.
-// 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.
-function writeSkill(cwd) {
-    const file = path.join(cwd, ".agents", "skills", BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
+// 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.
+function writeSkillFile(file) {
     if (fs.existsSync(file)) {
         // Compare with line endings normalized so a CRLF checkout of our own content still
         // reads as unchanged (not falsely "customized") — we always write LF.
@@ -111,47 +99,79 @@ function writeSkill(cwd) {
     fs.writeFileSync(file, BERYL_TEST_SKILL);
     return { outcome: "wrote", file };
 }
+const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
+// 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, 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;
+    }
+    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}`);
+        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 " +
-                    "(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();
@@ -168,72 +188,76 @@ 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)")}`);
+                }
+                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))}`);
                 }
-                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 {
+                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);
+            }
+            const skills = writeSkills(cwd, scope);
+            for (const skill of skills) {
+                const rel = path.relative(cwd, skill.file);
+                const skillWhere = rel.startsWith("..") ? skill.file : rel;
+                if (skill.outcome === "customized")
+                    ctx.err(`${dim("•")} Beryl authoring skill left as-is ${dim(`(${skillWhere} — you edited it; delete it to reinstall)`)}`);
+                else
+                    ctx.err(`${green("✓")} Beryl authoring skill ${skill.outcome === "wrote" ? "installed" : "already installed"} ${dim(skillWhere)}`);
             }
-            if (choice === "auto" && editors.length === 0)
-                ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));
-            // Editor-agnostic: the authoring skill goes to `.agents/skills/` regardless of which
-            // (if any) editor MCP config we wrote, so any `.agents/skills/`-aware harness gets it.
-            const skill = writeSkill(cwd);
-            const skillRel = path.relative(cwd, skill.file);
-            if (skill.outcome === "customized")
-                ctx.err(`${dim("•")} Beryl authoring skill left as-is ${dim(`(${skillRel} — you edited it; delete it to reinstall)`)}`);
-            else
-                ctx.err(`${green("✓")} Beryl authoring skill ${skill.outcome === "wrote" ? "installed" : "already installed"} ${dim(skillRel)}`);
+            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/projects.js

@@ -54,10 +54,22 @@ export const projectCommands = [
     },
     {
         name: "projects create",
-        summary: "Create a project — the agent starts exploring and authoring tests immediately",
+        summary: "Create a project — with a URL the agent starts exploring; with just --name an empty one",
         scope: "workspace",
-        args: [{ name: "url", description: "Root URL of the site to test", required: true }],
+        args: [
+            {
+                name: "url",
+                description: "Root URL of the site to test. Omit to create an empty project (see --name)",
+                required: false,
+            },
+        ],
         flags: [
+            {
+                name: "name",
+                type: "string",
+                description: "Name for an empty project when no URL is given. Add a URL later with " +
+                    "`beryl envs update <env-id>`, or author tests over the CLI/MCP",
+            },
             {
                 name: "auth",
                 type: "string",
@@ -84,13 +96,31 @@ export const projectCommands = [
             "beryl projects create https://app.example.com --watch",
             "beryl projects create https://app.example.com --auth gated",
             "beryl projects create https://app.example.com --auth public --no-explore",
+            'beryl projects create --name "Acme production"',
         ],
         async run(ctx, input) {
             const noExplore = flagBool(input, "no-explore");
             if (noExplore && flagBool(input, "watch"))
                 throw new UsageError("--no-explore cannot be combined with --watch");
             const ws = await ctx.requireWorkspace(input);
-            const url = arg(input, "url");
+            const rawUrl = input.args.url;
+            const url = typeof rawUrl === "string" ? rawUrl : "";
+            const name = flagStr(input, "name");
+            // Name-only: create a real empty project (no URL, no exploration). Set a URL
+            // later with `beryl envs update <env-id>` or author over the CLI/MCP.
+            if (!url) {
+                if (!name)
+                    throw new UsageError("Provide a URL to explore, or --name to create an empty project");
+                const created = (await ctx.client.post(`/workspaces/${ws}/projects`, {
+                    name,
+                }));
+                return {
+                    data: created,
+                    human: `${green("Project created")}: ${created.project_id} ${dim("(empty)")}\n` +
+                        `Add a site with \`beryl envs update <env-id>\`, or author tests with ` +
+                        `\`beryl tests create\`.`,
+                };
+            }
             const auth = flagStr(input, "auth") ?? (await resolveAuthChoice(ctx, ws, url));
             const created = (await ctx.client.post(`/workspaces/${ws}/projects`, {
                 root_url: url,

package/dist/commands/runs.js

@@ -1,8 +1,9 @@
 import fs from "node:fs";
 import { downloadRunArtifacts, failureImages, isFailing, resultsOf, } from "../artifacts.js";
 import { CliError, UsageError } from "../errors.js";
-import { runSpecLocally } from "../local-run.js";
+import { PlaywrightMissingError, runSpecLocally } from "../local-run.js";
 import { dim, green, red, yellow } from "../output.js";
+import { confirmInstall, installPlaywright } from "../playwright-install.js";
 import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 import { watchRun } from "./watch.js";
 const MAX_FAILURE_SCREENSHOTS = 5;
@@ -71,8 +72,9 @@ export const runCommands = [
         name: "runs local",
         summary: "Run a banked test locally with your own Playwright (public flows)",
         description: "Unlike `runs trigger`, this runs on YOUR machine, not Beryl's cloud — fetches the test's " +
-            "rendered spec, then runs it with your local @playwright/test (install it once with " +
-            "`npm i -D @playwright/test && npx playwright install`). Point --url-override at a local " +
+            "rendered spec, then runs it with your local @playwright/test. On a terminal it offers to " +
+            "install @playwright/test + chromium for you the first time they're missing (over MCP it " +
+            "prints the install commands instead). Point --url-override at a local " +
             "dev server or preview, and --dir to keep the spec, artifacts, and JSON report on disk so " +
             "an agent can run-fix-run. v1 targets public/unauthenticated flows: an authenticated test " +
             "refuses to run locally (those run in Beryl's cloud, which holds the session) — no session " +
@@ -107,14 +109,34 @@ export const runCommands = [
                     "session) — local runs are for public/unauthenticated flows. Run it with " +
                     "`beryl runs trigger`.");
             }
+            const runOnce = () => runSpecLocally({
+                spec: script.content,
+                testName: testId,
+                dir: flagStr(input, "dir"),
+                onProgress: (line) => ctx.err(dim(line)),
+            });
             let outcome;
             try {
-                outcome = await runSpecLocally({
-                    spec: script.content,
-                    testName: testId,
-                    dir: flagStr(input, "dir"),
-                    onProgress: (line) => ctx.err(dim(line)),
-                });
+                try {
+                    outcome = await runOnce();
+                }
+                catch (err) {
+                    // Local Playwright missing: on a TTY offer to install it and retry, instead of only
+                    // printing a hint the user then has to act on by hand. Non-interactively we can't
+                    // prompt, so we re-throw and the hint surfaces as before (no unprompted install).
+                    if (err instanceof PlaywrightMissingError && ctx.interactive) {
+                        // confirmInstall swallows a prompt failure into `false`, so a broken prompt falls
+                        // back to re-throwing the actionable missing-Playwright hint, not the prompt's error.
+                        if (!(await confirmInstall(ctx.prompt)))
+                            throw err;
+                        await installPlaywright(process.cwd(), (line) => ctx.err(dim(line)));
+                        ctx.err(green("✓ Local Playwright installed — running the test…"));
+                        outcome = await runOnce();
+                    }
+                    else {
+                        throw err;
+                    }
+                }
             }
             catch (err) {
                 // Every failure to run the spec (missing Playwright, a compile error, a customer

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/dist/local-run.js

@@ -1,12 +1,13 @@
 import { spawn } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-// The customer already has @playwright/test (the MCP `init` wires it), so we invoke it
-// as an external rather than bundling it — the CLI's zero-runtime-dep rule. In a node_modules
-// install `playwright` is on PATH; otherwise fall back to `npx playwright`, exactly as the
-// cloud runner does.
+import { PLAYWRIGHT_INSTALL_COMMANDS } from "./playwright-install.js";
+// We invoke @playwright/test as an external rather than bundling it — the CLI's zero-runtime-dep
+// rule. In a node_modules install `playwright` is on PATH; otherwise fall back to `npx playwright`,
+// exactly as the cloud runner does. The install commands come from playwright-install.ts so the
+// hint text and the actual installer never drift apart.
 export const PLAYWRIGHT_INSTALL_HINT = "Local Playwright not found. Install it in this project, then re-run:\n" +
-    "  npm i -D @playwright/test && npx playwright install chromium";
+    `  ${PLAYWRIGHT_INSTALL_COMMANDS}`;
 // Isolate the run from any playwright.config.ts in the customer's repo: a stray `testMatch`
 // would exclude our spec (a zero-test run that reads as a false pass), and a `use.baseURL` /
 // `use.storageState` / `globalSetup` there would silently retarget or reauth the run we mean

package/dist/playwright-install.js

@@ -0,0 +1,58 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import path from "node:path";
+// The two commands that turn "nothing Playwright-related installed" into "local runs work":
+// the test runner as a dev dep, then its browser binary. Kept as data so the CLI can both
+// run them and print them verbatim for the non-interactive / copy-paste path.
+export const INSTALL_TEST_RUNNER = ["npm", "i", "-D", "@playwright/test"];
+export const INSTALL_CHROMIUM = ["npx", "playwright", "install", "chromium"];
+export const PLAYWRIGHT_INSTALL_COMMANDS = `${INSTALL_TEST_RUNNER.join(" ")} && ${INSTALL_CHROMIUM.join(" ")}`;
+// Resolve `@playwright/test` the way Playwright itself will at run time — from the project
+// tree, not from wherever the globally-installed CLI happens to live. `createRequire` rooted
+// at cwd walks up the same node_modules chain, so this is true iff a local run would find it.
+export function hasPlaywrightTest(cwd) {
+    try {
+        createRequire(path.join(cwd, "package.json")).resolve("@playwright/test");
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export const INSTALL_PROMPT = `Install local Playwright now (${PLAYWRIGHT_INSTALL_COMMANDS})? [Y/n] `;
+// Ask (default-yes) whether to install. Returns false — not throwing — when there is no answer
+// or the prompt fails, so callers uniformly fall back to printing the install hint.
+export async function confirmInstall(prompt) {
+    try {
+        return !/^n(o)?$/i.test(await prompt(INSTALL_PROMPT));
+    }
+    catch {
+        return false;
+    }
+}
+const withCmdExt = (cmd) => process.platform === "win32" && (cmd === "npm" || cmd === "npx") ? `${cmd}.cmd` : cmd;
+function runInherit(command, args, cwd) {
+    return new Promise((resolve, reject) => {
+        // stdio inherited: an install is slow and the user wants to watch npm/browser-download
+        // progress live, exactly as if they'd typed it themselves.
+        const child = spawn(withCmdExt(command), [...args], { cwd, stdio: "inherit" });
+        child.on("error", reject);
+        child.on("close", (code) => code === 0
+            ? resolve()
+            : reject(new Error(`\`${command} ${args.join(" ")}\` exited with code ${code}`)));
+    });
+}
+/**
+ * Install the local Playwright test runner + chromium into `cwd`, streaming each step's output.
+ * Throws if either step exits non-zero (so the caller surfaces the failure, not a silent partial
+ * install). Skips the `@playwright/test` step when it is already resolvable, but always ensures
+ * the browser binary — an installed runner with no browser still fails a real run.
+ */
+export async function installPlaywright(cwd, onStep) {
+    if (!hasPlaywrightTest(cwd)) {
+        onStep?.(`Installing @playwright/test — ${INSTALL_TEST_RUNNER.join(" ")}`);
+        await runInherit(INSTALL_TEST_RUNNER[0], INSTALL_TEST_RUNNER.slice(1), cwd);
+    }
+    onStep?.(`Installing the Chromium browser — ${INSTALL_CHROMIUM.join(" ")}`);
+    await runInherit(INSTALL_CHROMIUM[0], INSTALL_CHROMIUM.slice(1), cwd);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.9.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,9 +34,13 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@types/node": "^26.1.1",
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "@hono/node-server": "2.0.11"
   }
 }