@beryl-so/cli 0.7.1 → 0.9.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
 
@@ -162,10 +163,9 @@ Create and manage projects — a site Beryl explores, authors tests for, and run
 | `beryl projects create <url>` | Create a project — the agent starts exploring and authoring tests immediately | `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
 
@@ -324,9 +324,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 +334,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 +342,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

@@ -19,6 +19,26 @@ export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
         { action: "expect", expect_kind: "visible", selector: "text=Pro plan" },
     ],
 };
+// The OTP/signup example the skill shows verbatim (§5). Exported so the test suite lints
+// it with lintPlan, same as the minimal example — the documented await_email shape must
+// pass `beryl tests lint` on the first try.
+export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
+    steps: [
+        { action: "goto", url: "https://app.example.com/signup" },
+        { action: "fill", selector: "input[name=email]", value: "{{inbox_address}}" },
+        { action: "click", selector: "button[type=submit]" },
+        {
+            action: "await_email",
+            extract: "code",
+            subject_contains: "verification code",
+            capture_as: "otp",
+            wait_s: 45,
+        },
+        { action: "fill", selector: "input[name=code]", value: "{{otp}}" },
+        { action: "click", selector: "text=Verify" },
+        { action: "expect", expect_kind: "visible", selector: "text=Welcome" },
+    ],
+};
 export const BERYL_TEST_SKILL = `---
 name: beryl-test
 description: Author durable, healable end-to-end tests for a web app with Beryl. Use when writing, running, or fixing a Beryl test locally with your own coding agent — drafting the plan over the Playwright MCP, writing the natural-language intent, and running it with \`beryl runs local\`.
@@ -176,4 +196,52 @@ beryl runs local <test-id> --url-override http://localhost:3000 --dir ./beryl-lo
 
 Once the test passes locally against a real outcome, it's ready to bank and let Beryl run
 and heal it.
+
+## 5. Testing an OTP / signup flow (\`await_email\`)
+
+A flow that emails the user — a signup verification code, a magic sign-in link, a receipt
+— is testable with the \`await_email\` action. Beryl mints a **run-scoped inbox**
+automatically whenever a plan contains an \`await_email\` step (or cites
+\`{{inbox_address}}\`): no setup, no environment configuration, no flag to turn on. The
+minted address is in scope from step 1 as the reserved \`{{inbox_address}}\` handle.
+
+The wiring is a three-part chain:
+
+1. **Type the minted address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\`.
+   Every run gets a fresh address, so a signup flow is repeatable by construction (no
+   \`{{unique}}\` needed for the email itself; use \`{{unique}}\` for other must-not-collide
+   values like a username).
+2. **Await the mail and bank the extracted value** — an \`await_email\` step with:
+   - \`extract\` (required): \`code\` (an OTP), \`link\` (the sign-in/verify URL), or
+     \`pattern\` (your own regex in \`extract_pattern\`, exactly one capture group).
+   - \`capture_as\` (required): the handle name the extracted string is banked under.
+   - \`subject_contains\` / \`from_contains\` (optional): match the right mail when the app
+     sends more than one.
+   - \`wait_s\` (optional, 1–50, default 30): how many seconds the step blocks waiting
+     for the mail to land.
+3. **Use the banked value** — cite \`{{<capture_as>}}\` in a later step's \`value\` (fill the
+   code) or \`url\` (goto the magic link). A captured handle is legal **only** in
+   \`value\`/\`url\`; in a \`selector\`, \`option\`, or \`expect_text\` it would be used as
+   literal text, and the linter rejects it there.
+
+A fully valid signup-with-OTP plan:
+
+\`\`\`json
+${JSON.stringify(BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN, null, 2)}
+\`\`\`
+
+For a magic-link flow, replace the code steps with
+\`{ "action": "await_email", "extract": "link", "capture_as": "signin_link" }\` followed by
+\`{ "action": "goto", "url": "{{signin_link}}" }\`.
+
+Two caveats:
+
+- \`beryl tests create\` verifies an \`await_email\` plan like any other — the replay mints
+  its own inbox, so the app's mail really is received and extracted before the test is
+  accepted. (Note the replay signs up / sends mail for real; pass \`--no-verify\` only if
+  that side effect is unwanted.) \`runs local\` cannot serve \`await_email\` — the inbox
+  lives in Beryl's cloud — so iterate on these flows with
+  \`beryl runs trigger --test <id> --watch\`.
+- The outcome assertion discipline from §1 still applies: the green signal is the
+  post-verification state (the welcome screen, the dashboard), not "an email arrived".
 `;

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

@@ -1,13 +1,15 @@
+import { execFileSync } from "node:child_process";
 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 { 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,
@@ -16,38 +18,14 @@ const MCP_SERVER_ENTRY = {
     command: "npx",
     args: ["-y", "@beryl-so/cli@latest", "mcp"],
 };
+// Headless: the coding agent drives this browser to author tests — nobody watches the
+// window, and a headed default breaks on CI / headless boxes. Matches how most devs
+// already wire their own user-scoped playwright.
 const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
-    args: ["@playwright/mcp@latest"],
+    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)) {
@@ -76,6 +54,36 @@ function mergeMcpConfig(file, withPlaywright) {
     }
     return { beryl, playwright };
 }
+// A tool's config lives per-user (same as the PAT it needs, in ~/.config/beryl) — so wire the
+// MCP servers per-user too, not in a committed .mcp.json that 401s for every teammate until
+// they run `beryl login` anyway. We DON'T hand-edit ~/.claude.json (Claude Code owns it; a
+// corrupt write breaks the user's whole CLI) — we shell out to `claude mcp add` and let Claude
+// own the edit. Returns false when the `claude` binary isn't on PATH so the caller can fall
+// back to a copy-paste command.
+function claudeUserAdd(name, entry) {
+    try {
+        execFileSync("claude", ["mcp", "add", name, "-s", "user", "--", entry.command, ...entry.args], {
+            stdio: "ignore",
+        });
+        return true;
+    }
+    catch (err) {
+        // A non-zero exit ALSO covers "already exists" — but so does a missing binary. Distinguish:
+        // ENOENT means no `claude` on PATH (fall back), anything else means it ran and declined
+        // (already configured — treat as success, nothing to do).
+        if (err.code === "ENOENT")
+            return false;
+        return true;
+    }
+}
+function claudeAddHint(name, entry) {
+    return `claude mcp add ${name} -s user -- ${entry.command} ${entry.args.join(" ")}`;
+}
+// ~/.cursor/mcp.json is Cursor's user-scope config — small and ours to write safely, unlike
+// ~/.claude.json — so we merge it directly rather than shelling out.
+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")))
@@ -106,38 +114,31 @@ function writeSkill(cwd) {
 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 writes the " +
-            "MCP server config for your coding agent (.mcp.json for Claude Code, .cursor/mcp.json for " +
-            "Cursor). 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",
+                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",
+            },
             {
                 name: "local",
                 type: "boolean",
@@ -149,8 +150,8 @@ export const initCommands = [
         examples: [
             "npx @beryl-so/cli@latest init",
             "beryl init --editor-tools claude-code",
-            "beryl init --project https://app.example.com --authoring agent",
-            "beryl init --project https://app.example.com --authoring local --editor-tools none",
+            "beryl init --scope project",
+            "beryl init --editor-tools none",
         ],
         async run(ctx, input) {
             const cwd = process.cwd();
@@ -167,59 +168,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)
@@ -232,14 +180,35 @@ export const initCommands = [
             // 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 file = editor === "claude-code"
                     ? path.join(cwd, ".mcp.json")
-                    : path.join(cwd, ".cursor", "mcp.json");
+                    : scope === "user"
+                        ? cursorUserConfigPath()
+                        : path.join(cwd, ".cursor", "mcp.json");
                 const wrote = mergeMcpConfig(file, local);
-                ctx.err(`${green("✓")} ${editor} MCP ${wrote.beryl ? "configured" : "already configured"} ${dim(path.relative(cwd, 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(path.relative(cwd, file))}`);
+                    ctx.err(`${green("✓")} ${editor} Playwright MCP ${wrote.playwright ? "configured" : "already configured"} ${dim(where)}`);
             }
             if (choice === "auto" && editors.length === 0)
                 ctx.err(dim("No coding agent detected — pass --editor-tools claude-code|cursor to wire one."));
@@ -251,28 +220,18 @@ export const initCommands = [
                 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")}.`
-                        : "");
+            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";
@@ -198,22 +197,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/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/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.7.1",
+  "version": "0.9.1",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",