@beryl-so/cli 0.8.0 → 0.11.1

package/README.md

@@ -37,9 +37,10 @@ beryl login                  # emailed one-time code; mints + stores a personal
 export BERYL_API_KEY=beryl_pat_…   # CI: use a token from Account → API tokens
 ```
 
-Defaults can be pinned per repo in a `.beryl.json` (`{"workspace": "…", "project": "…"}`)
-or globally via `beryl workspaces use` / `beryl projects use`.
-Precedence: flags > `BERYL_*` env > `.beryl.json` > `~/.config/beryl/config.json`.
+Config stores your token + API URL only — nothing else persists. Point a command at a
+workspace/project with the `--workspace` / `--project` flags or the `BERYL_WORKSPACE` /
+`BERYL_PROJECT` env vars; with exactly one, the CLI auto-picks it.
+Precedence: flags > `BERYL_*` env > auto-pick-if-one.
 
 ## CI in one line
 
@@ -56,18 +57,19 @@ claude mcp add beryl -- npx -y @beryl-so/cli mcp    # no install needed
 claude mcp add beryl -- beryl mcp                    # or, with the CLI installed
 ```
 
-Every non-interactive command below is exposed as an MCP tool with the same name
-(spaces and dashes become underscores).
+Most non-interactive commands below are exposed as an MCP tool with the same name
+(spaces and dashes become underscores) — see the MCP tool column. `—` marks commands
+kept CLI-only: account/billing/team admin, Slack alerts, feedback, and cloud exploration.
 
 ## Commands
 
 ### init
 
-Set up Beryl in this repo — sign in, pin a project, wire up your coding agent
+Set up Beryl in this repo — sign in and wire up your coding agent
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl init` | Set up Beryl in this repo — sign in, pin a project, wire up your coding agent | — |
+| `beryl init` | Set up Beryl in this repo — sign in and wire up your coding agent | — |
 
 ### login
 
@@ -95,11 +97,11 @@ Remove the stored token from the CLI config
 
 ### whoami
 
-Show the signed-in account and the CLI's resolved defaults
+Show the signed-in account
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl whoami` | Show the signed-in account and the CLI's resolved defaults | `whoami` |
+| `beryl whoami` | Show the signed-in account | `whoami` |
 
 ### tokens
 
@@ -122,7 +124,6 @@ Create and manage workspaces, and pick the one your commands act on by default.
 | `beryl workspaces create <name>` | Create a workspace | `workspaces_create` |
 | `beryl workspaces update` | Rename a workspace or change its visibility | `workspaces_update` |
 | `beryl workspaces delete` | Delete a workspace and everything in it | `workspaces_delete` |
-| `beryl workspaces use <workspace>` | Set the default workspace for future commands | `workspaces_use` |
 | `beryl workspaces history` | Show the workspace's action history (who did what, when) | `workspaces_history` |
 | `beryl workspaces leave` | Leave a workspace you are a member of | `workspaces_leave` |
 
@@ -132,9 +133,9 @@ Manage who belongs to a workspace and their roles.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl members list` | List workspace members | `members_list` |
-| `beryl members set-role <user-id> <role>` | Change a member's role | `members_set_role` |
-| `beryl members remove <user-id>` | Remove a member from the workspace | `members_remove` |
+| `beryl members list` | List workspace members | — |
+| `beryl members set-role <user-id> <role>` | Change a member's role | — |
+| `beryl members remove <user-id>` | Remove a member from the workspace | — |
 
 ### invites
 
@@ -142,12 +143,12 @@ Send, list, and revoke workspace invitations, and accept ones sent to you.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl invites send <email>` | Invite someone to the workspace by email | `invites_send` |
-| `beryl invites list` | List the workspace's outstanding invitations | `invites_list` |
-| `beryl invites revoke <invitation-id>` | Revoke a pending invitation | `invites_revoke` |
-| `beryl invites mine` | List invitations sent to you | `invites_mine` |
-| `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | `invites_accept` |
-| `beryl invites decline <invitation-id>` | Decline an invitation | `invites_decline` |
+| `beryl invites send <email>` | Invite someone to the workspace by email | — |
+| `beryl invites list` | List the workspace's outstanding invitations | — |
+| `beryl invites revoke <invitation-id>` | Revoke a pending invitation | — |
+| `beryl invites mine` | List invitations sent to you | — |
+| `beryl invites accept <invitation>` | Accept an invitation (by id, or by the token from the invite email) | — |
+| `beryl invites decline <invitation-id>` | Decline an invitation | — |
 
 ### projects
 
@@ -159,13 +160,12 @@ 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 | `projects_re_explore` |
+| `beryl projects re-explore` | Send the agent back in — run/heal existing tests and discover new flows | — |
 | `beryl projects report` | Aggregate quality report across recent runs (pass rates, flaky tests, trend) | `projects_report` |
 | `beryl projects reusable-auth <url>` | Check whether a saved login can be reused for a URL before creating a project | `projects_reusable_auth` |
-| `beryl projects use <project>` | Set the default project for future commands | `projects_use` |
 
 ### envs
 
@@ -241,11 +241,11 @@ Inspect the agent's exploration runs — how it crawled a site and authored its
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl explorations list` | List the agent's exploration passes for a project | `explorations_list` |
-| `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | `explorations_get` |
-| `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | `explorations_steps` |
-| `beryl explorations cancel <exploration-id>` | Cancel an in-flight exploration | `explorations_cancel` |
-| `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests | `explorations_watch` |
+| `beryl explorations list` | List the agent's exploration passes for a project | — |
+| `beryl explorations get <exploration-id>` | Show one exploration: authored tests, abandoned flows, coverage, frontier | — |
+| `beryl explorations steps <exploration-id>` | List every step the agent took in an exploration | — |
+| `beryl explorations cancel <exploration-id>` | Cancel an in-flight exploration | — |
+| `beryl explorations watch <exploration-id>` | Stream an exploration live — watch the agent explore and author tests | — |
 
 ### config
 
@@ -275,10 +275,10 @@ Send run outcomes to a Slack channel via a per-project incoming webhook.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl slack show` | Show the project's Slack alert config (webhook is masked) | `slack_show` |
-| `beryl slack set-webhook <url>` | Set the Slack incoming-webhook URL run alerts post to | `slack_set_webhook` |
-| `beryl slack clear` | Remove the project's Slack webhook (stops all alerts) | `slack_clear` |
-| `beryl slack test` | Post a sample alert to the configured webhook | `slack_test` |
+| `beryl slack show` | Show the project's Slack alert config (webhook is masked) | — |
+| `beryl slack set-webhook <url>` | Set the Slack incoming-webhook URL run alerts post to | — |
+| `beryl slack clear` | Remove the project's Slack webhook (stops all alerts) | — |
+| `beryl slack test` | Post a sample alert to the configured webhook | — |
 
 ### credentials
 
@@ -309,12 +309,13 @@ Drive a browser session that captures a target-site login for Beryl to reuse.
 
 ### 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` |
 
@@ -324,9 +325,9 @@ View and update your personal account profile.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl account get` | Show your account profile | `account_get` |
-| `beryl account update` | Update your profile | `account_update` |
-| `beryl account deletion-preview` | Preview what deleting your account would remove or leave | `account_deletion_preview` |
+| `beryl account get` | Show your account profile | — |
+| `beryl account update` | Update your profile | — |
+| `beryl account deletion-preview` | Preview what deleting your account would remove or leave | — |
 
 ### feedback
 
@@ -334,7 +335,7 @@ Send product feedback to the Beryl team.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl feedback send <message>` | Send product feedback to the Beryl team | `feedback_send` |
+| `beryl feedback send <message>` | Send product feedback to the Beryl team | — |
 
 ### billing
 
@@ -342,10 +343,10 @@ Review a workspace's plan usage, subscription, and invoices.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl billing usage` | Show plan usage: services and weekly AI units | `billing_usage` |
-| `beryl billing subscription` | Show the workspace's subscription | `billing_subscription` |
-| `beryl billing invoices` | List recent invoices | `billing_invoices` |
-| `beryl billing portal` | Get a Stripe billing-portal link for the workspace | `billing_portal` |
+| `beryl billing usage` | Show plan usage: services and weekly AI units | — |
+| `beryl billing subscription` | Show the workspace's subscription | — |
+| `beryl billing invoices` | List recent invoices | — |
+| `beryl billing portal` | Get a Stripe billing-portal link for the workspace | — |
 
 ### mcp
 

package/dist/adapters/mcp.js

@@ -9,7 +9,7 @@ export function toolName(spec) {
     return spec.name.replace(/ /g, "_").replace(/-/g, "_");
 }
 export function mcpTools() {
-    return commands.filter((c) => !c.interactive && !c.hidden && c.name !== "mcp");
+    return commands.filter((c) => !c.interactive && !c.hidden && !c.mcpHidden && c.name !== "mcp");
 }
 const mcpToolNames = new Set(mcpTools().map(toolName));
 /** The tool name a command is exposed as under `beryl mcp`, or undefined if it isn't exposed. */

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

@@ -119,32 +119,16 @@ export const authCommands = [
             }
             const authed = new ApiClient(apiUrl, token);
             const me = (await authed.get("/account/"));
-            let sole;
-            let workspaceCount = 0;
-            try {
-                const workspaces = (await authed.get("/workspaces/"));
-                workspaceCount = workspaces.length;
-                if (workspaces.length === 1)
-                    sole = workspaces[0];
-            }
-            catch {
-                // pinning a default is a nicety — never fail the login over it
-            }
+            // Persist identity only — PAT + api_url. Workspace/project are never pinned;
+            // they resolve per-command from env/flags or auto-pick when there's exactly one.
             const saved = saveGlobalConfig({
                 token,
                 api_url: apiUrl === "https://api.beryl.so" ? undefined : apiUrl,
-                ...(sole && sole.id !== ctx.config.workspace
-                    ? { workspace: sole.id, project: undefined }
-                    : {}),
             });
-            let human = `${green("Logged in")} as ${me.name} <${me.email}>`;
-            if (sole)
-                human += `\n${dim(`Default workspace: ${sole.name} (${sole.id})`)}`;
-            else if (workspaceCount > 1 && !ctx.config.workspace)
-                human += `\n${dim("Pick a default workspace with `beryl workspaces use <id>`")}`;
-            human += `\n${dim(`Token saved to ${saved}`)}`;
+            const human = `${green("Logged in")} as ${me.name} <${me.email}>` +
+                `\n${dim(`Token saved to ${saved}`)}`;
             return {
-                data: { email: me.email, name: me.name, workspace: sole?.id ?? null, config: saved },
+                data: { email: me.email, name: me.name, config: saved },
                 human,
             };
         },
@@ -207,15 +191,13 @@ export const authCommands = [
     },
     {
         name: "whoami",
-        summary: "Show the signed-in account and the CLI's resolved defaults",
+        summary: "Show the signed-in account",
         async run(ctx) {
             const me = (await ctx.client.get("/account/"));
             return {
                 data: {
                     ...me,
                     api_url: ctx.client.baseUrl,
-                    default_workspace: ctx.config.workspace ?? null,
-                    default_project: ctx.config.project ?? null,
                 },
             };
         },

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

@@ -3,13 +3,14 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { BERYL_TEST_SKILL, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME, } from "../beryl-test-skill.js";
-import { LOCAL_CONFIG_FILENAME, loadConfig } from "../config.js";
-import { CliError, UsageError } from "../errors.js";
+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 { confirmInstall, hasPlaywrightTest, installPlaywright, PLAYWRIGHT_INSTALL_COMMANDS, } from "../playwright-install.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 import { authCommands } from "./auth.js";
-import { flagBool, flagStr } from "./util.js";
+import { flagStr } from "./util.js";
 // Pinned to @latest (like the Playwright entry below) — an unpinned spec lets npx
 // serve whatever stale global/cache install already resolves, so the agent's MCP
 // server would silently miss newer tools. mergeMcpConfig compares entries verbatim,
@@ -26,33 +27,6 @@ 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";
-// The authoring fork only appears when we create a fresh project with no tests yet; an
-// explicit flag wins, otherwise a TTY prompt defaults to local on enter, and a
-// non-interactive run defaults to local so CI never burns server exploration on a project
-// the user means to hand-author.
-async function resolveAuthoring(ctx, flag) {
-    if (flag === "local" || flag === "agent")
-        return flag;
-    if (!ctx.interactive)
-        return "local";
-    ctx.err(`\n${bold("How do you want to author tests for this project?")}`);
-    ctx.err(`  ${green("1")}. Local / manual — with your own coding agent (Playwright MCP) or by hand ${dim("(default)")}`);
-    ctx.err(`  2. Beryl agent explores the site and authors tests for you`);
-    const answer = await ctx.prompt("Authoring [1-2]: ");
-    return answer.trim() === "2" ? "agent" : "local";
-}
-async function pick(ctx, kind, items) {
-    if (items.length === 1)
-        return items[0];
-    ctx.err(`\n${bold(`Which ${kind}?`)}`);
-    items.forEach((item, i) => ctx.err(`  ${i + 1}. ${item.name ?? item.root_url ?? item.id} ${dim(item.id)}`));
-    const answer = await ctx.prompt(`${kind} [1-${items.length}]: `);
-    const index = Number(answer) - 1;
-    const chosen = items[index];
-    if (!chosen)
-        throw new UsageError(`"${answer}" is not between 1 and ${items.length}`);
-    return chosen;
-}
 function mergeMcpConfig(file, withPlaywright) {
     let existing = {};
     if (fs.existsSync(file)) {
@@ -119,12 +93,10 @@ function detectEditors(cwd) {
         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.
@@ -138,43 +110,68 @@ 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 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;
+}
+// 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.
+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();
+    }
+}
 export const initCommands = [
     {
         name: "init",
-        summary: "Set up Beryl in this repo — sign in, pin a project, wire up your coding agent",
-        description: "One-command onboarding: signs you in (emailed one-time code), pins this repo to a " +
-            "workspace and project via .beryl.json (offering to create the project), and wires the " +
-            "MCP servers for your coding agent. 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. " +
-            "When creating a fresh project it asks how you want to author tests — locally with " +
-            "your own coding agent or by hand (the default), or by letting Beryl's agent explore and " +
-            "author them for you. Safe to re-run; every step skips what is already set up.",
+        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.",
         interactive: true,
         flags: [
-            { name: "workspace", type: "string", description: "Workspace id or name to pin" },
-            {
-                name: "project",
-                type: "string",
-                description: "Project id, name, or URL to pin. With no projects yet, a URL here is the root URL of " +
-                    "the project to create — supply it (plus --authoring) to run init non-interactively in CI",
-            },
-            {
-                name: "authoring",
-                type: "string",
-                enum: ["local", "agent"],
-                description: "How to author tests for a newly created project: `local` (author yourself with your " +
-                    "coding agent or by hand — the project is created without server exploration) or " +
-                    "`agent` (Beryl's agent explores the site and authors tests). Default: local. " +
-                    "Pass this to skip the interactive prompt in CI",
-            },
             {
                 name: "editor-tools",
                 type: "string",
                 enum: ["claude-code", "cursor", "both", "none"],
                 description: "Which coding agent to write MCP config for (default: auto-detect)",
             },
-            { name: "no-pin", type: "boolean", description: "Skip writing .beryl.json" },
             {
                 name: "scope",
                 type: "string",
@@ -187,17 +184,16 @@ export const initCommands = [
             {
                 name: "local",
                 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 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",
             },
         ],
         examples: [
             "npx @beryl-so/cli@latest init",
             "beryl init --editor-tools claude-code",
             "beryl init --scope project",
-            "beryl init --project https://app.example.com --authoring agent",
-            "beryl init --project https://app.example.com --authoring local --editor-tools none",
+            "beryl init --editor-tools none",
         ],
         async run(ctx, input) {
             const cwd = process.cwd();
@@ -214,59 +210,6 @@ export const initCommands = [
                     throw new CliError("Login did not persist a token");
                 client = new ApiClient(config.apiUrl, config.token);
             }
-            let workspaceId;
-            let projectId;
-            let authoredLocally = false;
-            if (!flagBool(input, "no-pin")) {
-                const workspaces = (await client.get("/workspaces/"));
-                if (workspaces.length === 0)
-                    throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
-                const wanted = flagStr(input, "workspace");
-                const workspace = wanted
-                    ? workspaces.find((w) => w.id === wanted || w.name?.toLowerCase() === wanted.toLowerCase())
-                    : await pick(ctx, "workspace", workspaces);
-                if (!workspace)
-                    throw new CliError(`No workspace named "${wanted}" found`);
-                workspaceId = workspace.id;
-                const projects = (await client.get(`/workspaces/${workspaceId}/projects`));
-                const wantedProject = flagStr(input, "project");
-                // With projects already present, --project pins an existing one; with none, it's the
-                // root URL of the project to create — which is what makes a fresh init CI-drivable.
-                if (wantedProject && projects.length > 0) {
-                    projectId = (await ctx.requireProject({
-                        args: {},
-                        flags: { workspace: workspaceId, project: wantedProject },
-                    })).projectId;
-                }
-                else if (projects.length > 0) {
-                    projectId = (await pick(ctx, "project", projects)).id;
-                }
-                else {
-                    const url = wantedProject ?? (await ctx.prompt("No projects yet. Root URL of the site to test: "));
-                    const authoring = await resolveAuthoring(ctx, flagStr(input, "authoring"));
-                    authoredLocally = authoring === "local";
-                    const created = (await client.post(`/workspaces/${workspaceId}/projects`, {
-                        root_url: url,
-                        skip_exploration: authoredLocally,
-                    }));
-                    projectId = created.project_id;
-                    if (authoredLocally)
-                        ctx.err(`${green("✓")} Project created for ${url} ${dim("(no server exploration — you'll author the tests)")}`);
-                    else
-                        ctx.err(`${green("✓")} Project created — the agent is exploring ${url} and authoring tests ` +
-                            `(watch with \`beryl explorations watch\`)`);
-                }
-                const localFile = path.join(cwd, LOCAL_CONFIG_FILENAME);
-                let local = {};
-                try {
-                    local = JSON.parse(fs.readFileSync(localFile, "utf8"));
-                }
-                catch {
-                    // no local config yet
-                }
-                fs.writeFileSync(localFile, JSON.stringify({ ...local, workspace: workspaceId, project: projectId }, null, 2) + "\n");
-                ctx.err(`${green("✓")} Pinned to ${LOCAL_CONFIG_FILENAME} ${dim(`(${projectId})`)}`);
-            }
             const choice = flagStr(input, "editor-tools") ?? "auto";
             const editors = choice === "auto"
                 ? detectEditors(cwd)
@@ -311,36 +254,37 @@ export const initCommands = [
             }
             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)}`);
-            const nextSteps = authoredLocally
-                ? `\n${bold("Beryl is set up — author your tests locally.")} Next steps:\n` +
-                    (local
-                        ? `  ${dim("• Playwright MCP is wired — point your coding agent at it to drive a real browser and draft a plan.")}\n`
-                        : `  ${dim("• Re-run with --editor-tools to wire the Playwright MCP for your coding agent, or author a plan by hand.")}\n`) +
-                    `  ${cyan("beryl tests lint --file plan.json")}     validate a plan offline against the schema\n` +
-                    `  ${cyan("beryl tests create --file plan.json")}   push a test from your plan\n` +
-                    `  ${cyan("beryl runs trigger --watch")}            run the suite\n\n` +
-                    `Author against the ActionPlan JSON Schema: ${cyan(ACTION_PLAN_SCHEMA_URL)}`
-                : `\n${bold("Beryl is set up.")} Try:\n` +
-                    `  ${cyan("beryl runs trigger --watch")}     run the suite\n` +
-                    `  ${cyan("beryl explorations watch")}       watch the agent work\n` +
-                    `  ${cyan("beryl tests list")}               see authored tests` +
-                    (local
-                        ? `\n\nPlaywright MCP is wired — your coding agent can explore the site locally ` +
-                            `and push tests with ${cyan("beryl tests create")}.`
-                        : "");
+            // 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);
+            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")
+                    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)}`);
+            }
+            // 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);
+            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`) +
+                `\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: { workspace: workspaceId ?? null, project: projectId ?? null, editors },
+                data: { editors },
                 human: nextSteps,
             };
         },

package/dist/commands/projects.js

@@ -1,4 +1,3 @@
-import { saveGlobalConfig } from "../config.js";
 import { detectAuthGating } from "../detect.js";
 import { UsageError } from "../errors.js";
 import { dim, green } from "../output.js";
@@ -55,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",
@@ -85,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,
@@ -198,22 +227,4 @@ export const projectCommands = [
             };
         },
     },
-    {
-        name: "projects use",
-        summary: "Set the default project for future commands",
-        scope: "workspace",
-        args: [{ name: "project", description: "Project id, name, or URL", required: true }],
-        async run(ctx, input) {
-            const value = arg(input, "project");
-            const { workspaceId, projectId } = await ctx.requireProject({
-                args: {},
-                flags: { ...input.flags, project: value },
-            });
-            saveGlobalConfig({ workspace: workspaceId, project: projectId });
-            return {
-                data: { workspace: workspaceId, project: projectId },
-                human: `${green("Default project set")}: ${projectId} ${dim(`(workspace ${workspaceId})`)}`,
-            };
-        },
-    },
 ];

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

@@ -1,5 +1,3 @@
-import { saveGlobalConfig } from "../config.js";
-import { green } from "../output.js";
 import { arg, flagBool, flagStr } from "./util.js";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 export const workspaceCommands = [
@@ -75,23 +73,6 @@ export const workspaceCommands = [
             return { human: "Deleted." };
         },
     },
-    {
-        name: "workspaces use",
-        summary: "Set the default workspace for future commands",
-        args: [{ name: "workspace", description: "Workspace id or name", required: true }],
-        async run(ctx, input) {
-            const value = arg(input, "workspace");
-            const id = UUID_RE.test(value)
-                ? value
-                : await ctx.requireWorkspace({ args: {}, flags: { workspace: value } });
-            const detail = (await ctx.client.get(`/workspaces/${id}`));
-            saveGlobalConfig({ workspace: id, project: undefined });
-            return {
-                data: { workspace: id },
-                human: `${green("Default workspace set")}: ${detail.name} (${id})`,
-            };
-        },
-    },
     {
         name: "workspaces history",
         summary: "Show the workspace's action history (who did what, when)",

package/dist/config.js

@@ -2,7 +2,6 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 export const DEFAULT_API_URL = "https://api.beryl.so";
-export const LOCAL_CONFIG_FILENAME = ".beryl.json";
 export function globalConfigPath(env = process.env) {
     const base = env.BERYL_CONFIG_DIR ??
         (env.XDG_CONFIG_HOME ? path.join(env.XDG_CONFIG_HOME, "beryl") : undefined) ??
@@ -17,30 +16,15 @@ function readJson(file) {
         return undefined;
     }
 }
-export function findLocalConfig(cwd) {
-    let dir = path.resolve(cwd);
-    for (;;) {
-        const candidate = path.join(dir, LOCAL_CONFIG_FILENAME);
-        if (fs.existsSync(candidate))
-            return candidate;
-        const parent = path.dirname(dir);
-        if (parent === dir)
-            return undefined;
-        dir = parent;
-    }
-}
-export function loadConfig(env = process.env, cwd = process.cwd()) {
+export function loadConfig(env = process.env) {
     const globalPath = globalConfigPath(env);
     const global = readJson(globalPath) ?? {};
-    const localPath = findLocalConfig(cwd);
-    const local = localPath ? (readJson(localPath) ?? {}) : {};
     return {
-        apiUrl: env.BERYL_API_URL ?? local.api_url ?? global.api_url ?? DEFAULT_API_URL,
-        token: env.BERYL_API_KEY ?? env.BERYL_TOKEN ?? local.token ?? global.token,
-        workspace: env.BERYL_WORKSPACE ?? local.workspace ?? global.workspace,
-        project: env.BERYL_PROJECT ?? local.project ?? global.project,
+        apiUrl: env.BERYL_API_URL ?? global.api_url ?? DEFAULT_API_URL,
+        token: env.BERYL_API_KEY ?? env.BERYL_TOKEN ?? global.token,
+        workspace: env.BERYL_WORKSPACE,
+        project: env.BERYL_PROJECT,
         globalConfigPath: globalPath,
-        localConfigPath: localPath,
     };
 }
 export function saveGlobalConfig(patch, env = process.env) {

package/dist/context.js

@@ -65,8 +65,7 @@ export function createContext(options) {
                 throw new CliError("You have no workspaces yet — create one with `beryl workspaces create`");
             }
             else {
-                throw new UsageError("Multiple workspaces — pass --workspace <id|name>, set BERYL_WORKSPACE, " +
-                    "or run `beryl workspaces use <id|name>`:\n" +
+                throw new UsageError("Multiple workspaces — pass --workspace <id|name> or set BERYL_WORKSPACE:\n" +
                     workspaces.map((w) => `  ${w.id}  ${w.name ?? ""}`).join("\n"));
             }
             return workspaceCache;
@@ -87,11 +86,11 @@ export function createContext(options) {
                 projectId = projects[0].id;
             }
             else if (projects.length === 0) {
-                throw new CliError("No projects in this workspace — create one with `beryl projects create`");
+                throw new CliError("This workspace has no project yet — create one with " +
+                    "`beryl projects create <url>` (add --no-explore to author tests yourself).");
             }
             else {
-                throw new UsageError("Multiple projects — pass --project <id|name|url>, set BERYL_PROJECT, " +
-                    "or run `beryl projects use <id|name>`:\n" +
+                throw new UsageError("Multiple projects — pass --project <id|name|url> or set BERYL_PROJECT:\n" +
                     projects.map((p) => `  ${p.id}  ${p.name ?? p.root_url ?? ""}`).join("\n"));
             }
             projectCache = { workspaceId, projectId };

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/dist/registry/index.js

@@ -15,14 +15,12 @@ import { workspaceCommands } from "../commands/workspaces.js";
 export const WORKSPACE_FLAG = {
     name: "workspace",
     type: "string",
-    description: "Workspace id or name (defaults to BERYL_WORKSPACE, .beryl.json, `beryl workspaces use`, " +
-        "or your only workspace)",
+    description: "Workspace id or name (defaults to BERYL_WORKSPACE, or your only workspace)",
 };
 export const PROJECT_FLAG = {
     name: "project",
     type: "string",
-    description: "Project id, name, or URL (defaults to BERYL_PROJECT, .beryl.json, `beryl projects use`, " +
-        "or the workspace's only project)",
+    description: "Project id, name, or URL (defaults to BERYL_PROJECT, or the workspace's only project)",
 };
 function withScopeFlags(spec) {
     if (!spec.scope || spec.scope === "none")
@@ -35,6 +33,24 @@ function withScopeFlags(spec) {
         extra.push(PROJECT_FLAG);
     return { ...spec, flags: [...(spec.flags ?? []), ...extra] };
 }
+// Command groups kept OUT of the `beryl mcp` tool surface while staying full CLI commands:
+// account/billing/team admin, Slack alerts, feedback, and the cloud-exploration mode
+// (incl. `projects re-explore`) — none of it is part of authoring/editing/running tests,
+// which is all an agent drives over MCP.
+const MCP_HIDDEN_PREFIXES = [
+    "slack",
+    "account",
+    "billing",
+    "feedback",
+    "explorations",
+    "members",
+    "invites",
+    "projects re-explore",
+];
+function hideFromMcp(spec) {
+    const hidden = MCP_HIDDEN_PREFIXES.some((p) => spec.name === p || spec.name.startsWith(`${p} `));
+    return hidden ? { ...spec, mcpHidden: true } : spec;
+}
 export const commands = [
     ...initCommands,
     ...authCommands,
@@ -50,7 +66,7 @@ export const commands = [
     ...inboxCommands,
     ...accountCommands,
     ...mcpCommands,
-].map(withScopeFlags);
+].map(withScopeFlags).map(hideFromMcp);
 export function findCommand(words) {
     let best;
     for (const spec of commands) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.8.0",
+  "version": "0.11.1",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",
@@ -38,5 +38,8 @@
     "tsx": "^4.23.1",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
+  },
+  "overrides": {
+    "@hono/node-server": "2.0.11"
   }
 }