@beryl-so/cli 0.11.1 → 0.17.0

package/README.md

@@ -71,6 +71,14 @@ Set up Beryl in this repo — sign in and wire up your coding agent
 | --- | --- | --- |
 | `beryl init` | Set up Beryl in this repo — sign in and wire up your coding agent | — |
 
+### guide
+
+Print the Beryl test-authoring guide
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl guide` | Print the Beryl test-authoring guide | `guide` |
+
 ### login
 
 Authenticate the CLI with your Beryl account
@@ -214,7 +222,7 @@ Author, inspect, version, and heal a project's tests — the checks Beryl runs o
 | `beryl tests reset <test-id>` | Discard user edits and return the test to its latest system-authored version | `tests_reset` |
 | `beryl tests heal <test-id> <state>` | Turn self-healing on or off for a test | `tests_heal` |
 | `beryl tests history <test-id>` | Pass/fail history, streak, and stability for a test | `tests_history` |
-| `beryl tests script <test-id>` | Print the rendered Playwright spec for a test | `tests_script` |
+| `beryl tests script [test-id]` | Print the rendered Playwright spec for a test (or an unbanked plan file) | `tests_script` |
 | `beryl tests export <test-ids...>` | Export tests as Playwright .spec.ts files in a ZIP | `tests_export` |
 
 ### runs
@@ -226,7 +234,7 @@ Trigger a run of a project's tests (e.g. in CI), then watch, inspect, and downlo
 | Command | Summary | MCP tool |
 | --- | --- | --- |
 | `beryl runs trigger` | Trigger a test run (whole suite, a subset, or one environment) | `runs_trigger` |
-| `beryl runs local <test-id>` | Run a banked test locally with your own Playwright (public flows) | `runs_local` |
+| `beryl runs local [test-ids...]` | Run tests on your machine with your own Playwright; results sync to Beryl | `runs_local` |
 | `beryl runs list` | List recent runs | `runs_list` |
 | `beryl runs get <run-id>` | Show one run with its per-test results | `runs_get` |
 | `beryl runs watch <run-id>` | Attach to a run and stream progress until it finishes | `runs_watch` |
@@ -259,7 +267,7 @@ Manage the variables, secrets, and files the agent can use while exploring and r
 | `beryl config vars delete <key>` | Delete a config variable | `config_vars_delete` |
 | `beryl config secrets list` | List the project's secrets (values are never returned) | `config_secrets_list` |
 | `beryl config secrets set <key> <value>` | Create a secret (write-only; re-setting a key replaces it) | `config_secrets_set` |
-| `beryl config secrets get <key>` | Show one secret's metadata (the value is never returned) | `config_secrets_get` |
+| `beryl config secrets get <key>` | Show one secret's metadata, or reveal its value with --reveal | `config_secrets_get` |
 | `beryl config secrets delete <key>` | Delete a secret | `config_secrets_delete` |
 | `beryl config files list` | List files uploaded for the agent to use (e.g. CSVs, upload fixtures) | `config_files_list` |
 | `beryl config files get <file>` | Show one uploaded file's metadata | `config_files_get` |
@@ -280,33 +288,6 @@ Send run outcomes to a Slack channel via a per-project incoming webhook.
 | `beryl slack clear` | Remove the project's Slack webhook (stops all alerts) | — |
 | `beryl slack test` | Post a sample alert to the configured webhook | — |
 
-### credentials
-
-Manage saved logins Beryl reuses to test behind authentication, and attach them to projects.
-
-| Command | Summary | MCP tool |
-| --- | --- | --- |
-| `beryl credentials list` | List the workspace's saved logins | `credentials_list` |
-| `beryl credentials get <credential-id>` | Show one saved login (status and freshness — never the session itself) | `credentials_get` |
-| `beryl credentials projects <credential-id>` | List the projects using a saved login | `credentials_projects` |
-| `beryl credentials delete <credential-id>` | Delete a saved login | `credentials_delete` |
-| `beryl credentials attach <credential-id>` | Attach a saved login to a project | `credentials_attach` |
-| `beryl credentials detach` | Detach the project's saved login | `credentials_detach` |
-| `beryl credentials recapture <credential-id>` | Start a re-capture for an expiring saved login (returns a live browser URL) | `credentials_recapture` |
-| `beryl credentials capture` | Capture a login for the project interactively: log in once in a real browser | — |
-
-### auth-capture
-
-Drive a browser session that captures a target-site login for Beryl to reuse.
-
-| Command | Summary | MCP tool |
-| --- | --- | --- |
-| `beryl auth-capture start` | Start a login-capture browser session for the project (non-interactive) | `auth_capture_start` |
-| `beryl auth-capture login <session-id>` | Log into the target site headlessly with credentials (no human at the browser) | `auth_capture_login` |
-| `beryl auth-capture capture <session-id>` | Capture the session after the user has logged in via the live-view URL | `auth_capture_capture` |
-| `beryl auth-capture refresh <session-id>` | Capture a refreshed session for a project whose login is expiring | `auth_capture_refresh` |
-| `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing | `auth_capture_release` |
-
 ### inbox
 
 Email inboxes for testing flows that send mail — signups, OTPs, receipts.

package/dist/adapters/mcp.js

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

package/dist/beryl-test-skill.js

@@ -97,8 +97,14 @@ ${JSON.stringify(BERYL_TEST_SKILL_EXAMPLE_PLAN, null, 2)
    beryl tests create --title "Log in" --file plan.json \\
      --description "<the intent — see §3>"
    \`\`\`
-   By default \`create\` verifies the plan in a real browser before accepting it. The full
-   ActionPlan JSON Schema is at
+   By default \`create\` proves the plan by replaying it in a browser ON YOUR MACHINE
+   (your local \`@playwright/test\` — §4's prerequisites apply) before anything is banked.
+   The same is true over the MCP: the replay runs wherever the MCP server runs — your
+   computer, never Beryl's — so the §4 install must exist there too.
+   A red replay banks nothing: fix the plan file and re-run \`create\`. The green proving
+   replay is imported as the test's first run (\`--no-sync\` to skip); \`--no-verify\` banks
+   unproven. Inspect the exact spec that would run with \`beryl tests script --file
+   plan.json\`. The full ActionPlan JSON Schema is at
    https://api.beryl.so/api/v1/schemas/action-plan.schema.json.
 
 ### The outcome assertion is the whole game
@@ -183,18 +189,31 @@ for a scheduled run.
 
 \`\`\`
 npm i -D @playwright/test && npx playwright install   # once
-beryl runs local <test-id> --url-override http://localhost:3000 --dir ./beryl-local
+beryl runs local <test-id> --no-sync --url-override http://localhost:3000 --dir ./beryl-local
+beryl runs local              # the whole suite, results recorded in Beryl
 \`\`\`
 
+- Takes one or more test ids; with none it runs every active test in the project.
+- **Results sync to Beryl by default** — the finished run is imported as a first-class
+  run (history, replay, report; trigger source \`local\`). While ITERATING on a draft,
+  pass \`--no-sync\` so every fix-loop attempt doesn't land in the project's run history.
 - \`--url-override\` points the run at a local dev server or a preview deploy.
 - \`--dir\` keeps the **spec, artifacts, and a JSON \`report.json\`** on disk so you (or your
   coding agent) can read exactly what happened and iterate: read the report, see which step
   or assertion failed and why, fix the plan, \`beryl tests set-plan\`, run again.
 - It exits **0** if every test passed, **1** on a failure — so it drops straight into a
   run-fix-run loop.
-- **v1 is public / unauthenticated flows only.** A test that signs in first runs only in
-  Beryl's cloud (which holds the encrypted session — it's never handed to your disk);
-  \`runs local\` refuses it. Run those with \`beryl runs trigger\`.
+- \`await_email\` steps work locally: the CLI mints the run inbox and answers them over
+  the API, exactly as the cloud runner would.
+- **Saved-login tests work locally.** A plan that fills \`{{login_email}}\` /
+  \`{{login_password}}\` runs fine: the email is baked into the fetched spec and the
+  password is revealed once over the logged secret-reveal route, then scrubbed from
+  any uploaded error text or DOM snapshot. If the LOGIN_EMAIL variable or
+  LOGIN_PASSWORD secret isn't set, the test is skipped with the exact fix-it command.
+- **Captured-session tests stay cloud-only.** A test that signs in with a captured
+  browser session runs only in Beryl's cloud (which holds the encrypted session — it's
+  never handed to your disk); \`runs local\` skips it with a note. Run those with
+  \`beryl runs trigger\`.
 
 Once the test passes locally against a real outcome, it's ready to bank and let Beryl run
 and heal it.
@@ -238,12 +257,49 @@ For a magic-link flow, replace the code steps with
 
 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\`.
+- \`beryl tests create\` verifies an \`await_email\` plan like any other — its local
+  replay mints a fresh run inbox and answers each step over the API, 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.)
+  \`beryl runs local\` serves \`await_email\` the same way, so the whole local loop covers
+  OTP/signup flows end to end.
 - 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".
+
+## 6. Accounts: minted or saved-login — never captured
+
+How a test gets an account is a fixed decision, made at the start of every authoring
+session from \`projects get\`, which reports \`login_email_set\` / \`login_password_set\`.
+Both paths are plain steps in the plan — no captured sessions, no saved browser
+state, no human-in-the-loop login.
+
+- **Saved login present (both flags true) → use it.** The project's dedicated test
+  account lives in config: the \`LOGIN_EMAIL\` variable + the \`LOGIN_PASSWORD\`
+  secret. Author the login as ordinary opening steps citing the reserved handles —
+  fill \`{{login_email}}\`, fill \`{{login_password}}\`, submit, assert the logged-in
+  shell. NEVER paste the real values into a plan: the handles resolve at run time
+  (the password never lands in the rendered spec and is scrubbed from artifacts).
+  To drive the real login live while authoring, read the values with
+  \`config vars get LOGIN_EMAIL\` and \`config secrets get LOGIN_PASSWORD --reveal\`.
+  \`tests create\` still replays the whole flow (locally, on your machine) before
+  banking, so a login that doesn't work is rejected with evidence — nothing is
+  banked on faith.
+- **Not set → mint.** \`{{inbox_address}}\` is a fresh real mailbox, minted per test,
+  per run. Type it into the site's own signup form, \`await_email\` the code or link
+  (§5). Fresh every run means nothing expires, nothing rots, no state leaks between
+  tests. Do not ask the user for credentials — mint is the default path.
+- **Handed credentials in chat? Bank them first** (\`config vars set LOGIN_EMAIL\`,
+  \`config secrets set LOGIN_PASSWORD\`), then author with the handles as above.
+  A DEDICATED test account only — never a real user's.
+- **Never hard-code an email address or password in a plan.** Minted inboxes expire
+  and pasted values rot on rotation — the handles are the only durable references.
+- **One identity per banked test.** A flow involving a second account — invite a
+  teammate and accept as them, share and open as the viewer — is not bankable as one
+  test yet: a run has one inbox, and \`await_email\` reads only that inbox. Bank the
+  half the app shows to account A ("the invitation is listed as pending", "the share
+  link is issued") — a real, strong outcome. While AUTHORING you can still verify the
+  full handshake live: mint a second inbox (\`inbox create\`), read its mail
+  (\`inbox read\`), drive both sides in the browser — then bank the single-identity
+  halves.
+- SSO-only sites (no email+password form at all) remain webapp territory.
 `;

package/dist/commands/config-vars.js

@@ -112,12 +112,33 @@ export const configCommands = [
     },
     {
         name: "config secrets get",
-        summary: "Show one secret's metadata (the value is never returned)",
+        summary: "Show one secret's metadata, or reveal its value with --reveal",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
+        flags: [
+            {
+                name: "reveal",
+                type: "boolean",
+                description: "Return the decrypted value — the explicit read that lets the agent drive a " +
+                    "real login while authoring. Member-gated; every reveal is logged",
+            },
+            {
+                name: "env",
+                type: "string",
+                description: "With --reveal: prefer the row scoped to this environment id when the key " +
+                    "exists at both scopes (matches what a run against that environment resolves)",
+            },
+        ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
-            const rows = (await ctx.client.get(`${configPath(workspaceId, projectId)}/secrets`));
+            const base = `${configPath(workspaceId, projectId)}/secrets`;
+            if (flagBool(input, "reveal")) {
+                const env = flagStr(input, "env");
+                return {
+                    data: await ctx.client.get(`${base}/${encodeURIComponent(arg(input, "key"))}/value`, env ? { environment_id: env } : undefined),
+                };
+            }
+            const rows = (await ctx.client.get(base));
             return { data: findByKey(rows, arg(input, "key"), "secret") };
         },
     },

package/dist/commands/inboxes.js

@@ -1,27 +1,6 @@
+import { extractCode } from "../email-extract.js";
 import { dim, green } from "../output.js";
 import { arg, flagBool, flagNum, flagStr } from "./util.js";
-// Mirrors the API's own extractor (email_inbox/step_resolver.py): a labelled digit run
-// ("your code is 654321") beats the bare fenced pattern, because a real sign-in mail is
-// full of innocent 4-8 digit runs — "© 2026", a support number — and the bare fence
-// would happily return the first of them.
-const CODE_PATTERN = /(?<!\d)(\d{4,8})(?!\d)/;
-const LABELLED_CODE_PATTERN = /(?:verification|security|one[\s-]?time|login|sign[\s-]?in|access|confirmation)?\s*(?:code|otp|passcode|pin)\b[^0-9]{0,20}(?<!\d)(\d{4,8})(?!\d)/i;
-function visibleText(html) {
-    return html
-        .replace(/<(style|script|head)\b[\s\S]*?<\/\1>/gi, " ")
-        .replace(/<[^>]+>/g, " ");
-}
-function extractCode(email) {
-    const body = email.body_text || (email.body_html ? visibleText(email.body_html) : "");
-    for (const pattern of [LABELLED_CODE_PATTERN, CODE_PATTERN]) {
-        for (const text of [body, email.subject ?? ""]) {
-            const match = text.match(pattern);
-            if (match)
-                return match[1];
-        }
-    }
-    return null;
-}
 export const inboxCommands = [
     {
         name: "inbox create",

package/dist/commands/init.js

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