@beryl-so/cli 0.50.0 → 0.52.0

package/dist/beryl-test-skill.js

@@ -48,7 +48,7 @@ export const BERYL_COPILOT_SECTION = `${BERYL_COPILOT_MARK_BEGIN}
 ${BERYL_GUIDE_POINTER}
 ${BERYL_COPILOT_MARK_END}`;
 // The example plan the skill shows verbatim. Exported so the test suite lints it with
-// lintPlan — the skill's documented shape must pass `beryl tests lint` on the first try.
+// lintPlan; the skill's documented shape must pass `tests_lint` on the first try.
 export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
     steps: [
         { action: "goto", url: "/pricing" },
@@ -63,7 +63,7 @@ export const BERYL_TEST_SKILL_EXAMPLE_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.
+// pass `tests_lint` on the first try.
 export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
     steps: [
         { action: "goto", url: "/signup" },
@@ -89,7 +89,7 @@ export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
 };
 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\`.
+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 \`runs_local\`.
 ---
 
 # Authoring Beryl tests
@@ -97,52 +97,50 @@ description: Author durable, healable end-to-end tests for a web app with Beryl.
 beryl-test v${cliVersion()} — installed by \`beryl init\`; the \`guide\` tool always returns the current version of this guide.
 
 A Beryl test drives a real browser through a flow and asserts the flow reached its
-meaningful outcome. \`beryl init\` wired two MCP servers: **beryl** (create/list/run
-tests) and **playwright** (drive a real browser). Beryl **heals** tests as the app's
-markup drifts — but only when you supply the three things that make a test durable: a
-real **outcome assertion**, a strong **natural-language intent**, and the **local
-run-fix loop**.
+meaningful outcome. \`beryl init\` wired two MCP servers: **beryl** (the tools you author
+with: \`accounts_list\`, \`tests_create\`, \`runs_local\`, and the rest) and **playwright**
+(drive a real browser). You do everything below by calling those tools. Beryl **heals**
+tests as the app's markup drifts, but only when you supply the three things that make a
+test durable: a real **outcome assertion**, a strong **natural-language intent**, and the
+**local run-fix loop**.
 
 ## 0. Start here
 
-**Everything happens on your machine first** — you drive the flow here, and
-\`tests create\` proves the plan here too, so a working local browser IS the loop.
-Avoid \`--no-verify\` (banks unproven); replay mechanics and the cloud-session
-exception are in \`tests create\`'s own description.
+**Everything happens on your machine first**: you drive the flow here, and
+\`tests_create\` proves the plan here too, so a working local browser IS the loop.
+Keep \`tests_create\`'s verify on (banking unproven is a trap); replay mechanics and the
+cloud-session exception are in the \`tests_create\` tool's own description.
 
-Before the first plan:
+Set up (once): if you cannot call the Beryl tools yet, run \`beryl init\` in a terminal to
+install the browser and wire the tools. Then, before the first plan:
 
-\`\`\`
-npx @beryl-so/cli@latest init                         # once per machine: installs the Chromium browser (the runner ships with the CLI)
-beryl envs list                                       # the root URL gotos resolve against (§2)
-beryl envs update <id> --url https://app.example.com  # set it if root_url is empty — required
-beryl accounts list                                   # who do authenticated tests sign in as? (§1)
-beryl accounts set-login <id> --file … --probe …      # store its sign-in — required (§1)
-beryl accounts check <id>                             # does that stored sign-in still work? (§1)
-beryl mailbox get                                     # the address they receive mail at (§5)
-\`\`\`
+- \`envs_list\`: the root URL gotos resolve against (§2). If it is empty, set it with
+  \`envs_update\`.
+- \`accounts_list\`: who do authenticated tests sign in as (§1)? Store its sign-in with
+  \`accounts_set_login\`, prove it with \`accounts_check\`.
+- \`mailbox_get\`: the address the account receives mail at (§5).
 
-\`accounts list\` comes FIRST: standing account vs new identity changes the plan you
+\`accounts_list\` comes FIRST: standing account vs new identity changes the plan you
 write (discovering it afterwards means rewriting), and an authenticated test cannot be
 created until its account's login plan is stored.
 
 Then, per test:
 
-1. **Drive the flow** in a real browser over the Playwright MCP — never author from
-   imagination (§2).
+1. **Drive the flow** in a real browser over the Playwright MCP, never from imagination (§2).
 2. **Write the ActionPlan**, with one real outcome assertion (§2).
-3. \`beryl tests lint --file plan.json --access read|write\` — schema and access check,
-   offline, no network.
-4. \`beryl tests create --title … --file … --access read|write --description "<the
-   intent>"\` — replays the plan locally, banks it only on green, records no run; a red
-   replay hands back the failure — fix and re-run (§3 for the intent, §4 for the loop).
-5. When the batch is banked, run the new ids together ONCE (\`beryl runs local <id…>\`,
-   or \`beryl runs trigger\` for the cloud) so they land as one run with real first results.
+3. **Lint it** with \`tests_lint\` (the plan plus its \`read\`/\`write\` access): schema and
+   access check, offline.
+4. **Bank it** with \`tests_create\` (the title, the plan, its \`access\`, and the
+   \`description\` intent): it replays the plan locally, banks only on green, records no
+   run; a red replay hands back the failure to fix and re-run (§3 for the intent, §4 for
+   the loop).
+5. When the batch is banked, run the new ids together ONCE with \`runs_local\` (or
+   \`runs_trigger\` for the cloud) so they land as one run with real first results.
 
 ## 1. First: who do your tests sign in as?
 
 An authenticated test **signs in as an account that already exists** — it does not sign
-one up. Start every authoring session with \`beryl accounts list\`:
+one up. Start every authoring session with \`accounts_list\`:
 
 \`\`\`
 label      email                          type           login     status
@@ -161,9 +159,9 @@ one plan stays correct across environments.
 
 **The account needs a stored login plan before any authenticated test can be created.**
 A run replays that plan to produce the session its tests ride, and replays it again
-when the session expires — so \`tests create\` rejects a \`requires_auth\` plan whose
+when the session expires, so \`tests_create\` rejects a \`requires_auth\` plan whose
 account has none, naming the fix. Store it once per account with
-\`beryl accounts set-login\` (§ Session mode).
+\`accounts_set_login\` (§ Session mode).
 
 **NEVER paste a real email or password into a plan.** Handles resolve at run time —
 the password never lands in the rendered spec and is scrubbed from artifacts. A pasted
@@ -193,8 +191,8 @@ The trade is drift — run 200 has 200 of everything run 1 created. So:
     was. Capture the original BEFORE you change it with \`capture_text\` (or \`capture_value\`
     for a form input), banking it under \`capture_as\`, then \`fill {{handle}}\` in \`after\`
     to put it back.
-- **You label each test \`read\` or \`write\`; Beryl takes your word for it.** Set it with
-  \`--access\` (default \`read\`). Beryl does NOT infer it from your selectors, so YOU
+- **You label each test \`read\` or \`write\`; Beryl takes your word for it.** Set its
+  \`access\` (default \`read\`). Beryl does NOT infer it from your selectors, so YOU
   decide, by one test: **would the app be different after this test runs?**
   - **\`write\`** = it leaves a change behind: it creates, edits, deletes, renames, moves,
     uploads or toggles a record or setting that is still different once the test ends. A
@@ -208,35 +206,33 @@ The trade is drift — run 200 has 200 of everything run 1 created. So:
   A flow that both changes and reads is a \`write\`. Only the \`write\` label is checked
   (its closing teardown proof, and a \`write\` whose teardown removes nothing fails the
   run); \`read\` is taken at your word, so a real write you mislabel \`read\` silently
-  drifts the account. Label deliberately, and flip a banked test with
-  \`beryl tests set-access <id> read|write\`.
+  drifts the account. Label deliberately, and flip a banked test with \`tests_set_access\`.
 
 ### If there is no account yet
 
-An empty \`accounts list\` means nothing is set up. In order of preference:
+An empty \`accounts_list\` means nothing is set up. In order of preference:
 
-1. **The user has a dedicated test account** → bank it:
-   \`beryl accounts create --email <email> --password <password>\`. A DEDICATED test
-   account only — never a real user's.
+1. **The user has a dedicated test account** → bank it with \`accounts_create\` (email +
+   password). A DEDICATED test account only, never a real user's.
 2. **Only Google (or another SSO) sign-in, no email+password form** → the same path:
-   ask for a DEDICATED Google test account and bank it with \`accounts create --email
-   --password\`. Its sign-in plan runs through Google's own pages — click the app's
+   ask for a DEDICATED Google test account and bank it with \`accounts_create\`. Its
+   sign-in plan runs through Google's own pages: click the app's
    Google button, fill \`#identifierId\` with \`{{login_email}}\`, click
    \`#identifierNext\`, fill \`input[name=Passwd]\` with \`{{login_password}}\`, click
-   \`#passwordNext\`, then assert the app's signed-in shell. Store it with \`accounts
-   set-login\`, prove it with \`accounts check\`. Author its tests with \`auth_mode:
+   \`#passwordNext\`, then assert the app's signed-in shell. Store it with
+   \`accounts_set_login\`, prove it with \`accounts_check\`. Author its tests with \`auth_mode:
    "session"\` only, so Google is signed in once per run, never per test. Google may
    still challenge a scripted sign-in now and then ("Verify it's you"); the captured
    session (end of §1) is the fallback for that, not the default.
 3. **No credentials, but the app has a signup form** → let Beryl make one.
-   \`beryl accounts create --type beryl\`, then sign it up with
-   \`beryl accounts signup <id> --file <signup-plan.json>\`. The plan is the app's own
+   \`accounts_create\` (type \`beryl\`), then sign it up with \`accounts_signup\` (its
+   signup plan). The plan is the app's own
    signup form as an ActionPlan, ending LOGGED IN, filling \`{{mailbox_address}}\` and
    \`{{login_password}}\`. It stays on the account, so a new environment signs the same
    identity up again by itself. An account that already exists on the site (hand-made,
-   or the record was lost) skips signup: store its sign-in with \`accounts set-login\`.
-   No password sign-in? Pass \`--login-method otp\` (or \`magic_link\`) and let the plan
-   \`await_email\` through; later sign-ins read the same mailbox.
+   or the record was lost) skips signup: store its sign-in with \`accounts_set_login\`.
+   No password sign-in? Set the account's login method to \`otp\` (or \`magic_link\`) and
+   let the plan \`await_email\` through; later sign-ins read the same mailbox.
 4. **Neither** → the flow is not testable authenticated. Say so rather than guessing.
 
 A project with no accounts falls back to the \`LOGIN_EMAIL\` variable +
@@ -254,21 +250,17 @@ or the failure evidence; nothing to turn on. A session-mode test has no sign-in
 to fall back to, so an account with no stored login plan fails at setup with
 \`SESSION_NO_LOGIN_PLAN\`.
 
-Set it up once per account:
-
-\`\`\`
-beryl accounts set-login <id> --file signin.json --probe probe.json
-beryl accounts check <id>          # signs in NOW and proves it — do not skip this
-\`\`\`
+Set it up once per account: \`accounts_set_login\` (the sign-in plan and a probe), then
+\`accounts_check\` (signs in NOW and proves it; do not skip this).
 
-What \`--file\` and \`--probe\` must contain, and the \`--base-hash\` read-before-write
-rule for later edits, are in \`accounts set-login\` / \`accounts get-login\`'s own
+What the sign-in plan and the probe must contain, and the read-before-write rule for
+later edits, are in the \`accounts_set_login\` / \`accounts_get_login\` tools' own
 descriptions.
 
 Then write the tests with \`requires_auth: true\`, \`auth_mode: "session"\`, and NO
 sign-in steps.
 
-**Creates share the sign-in.** \`tests create\` replays session-mode plans against the
+**Creates share the sign-in.** \`tests_create\` replays session-mode plans against the
 account's established session (reused while it stays live), so a batch of creates costs
 at most one sign-in — but still create one at a time: racing creates race the same
 mailbox for mail.
@@ -277,7 +269,7 @@ An expired session is never your problem: every run proves the stored session an
 miss, signs in again from the login plan. A "reconnect" message only appears when there
 is no stored login plan to refresh from.
 
-When \`accounts check\` fails, its description explains which half broke and each
+When \`accounts_check\` fails, its description explains which half broke and each
 \`SESSION_*\` reason. The one that changes your authoring: an account marked
 unsupported (its session cannot survive a fresh browser) is not your bug, but it IS
 your move — re-author its session-mode tests with \`auth_mode: "inline"\` and their own
@@ -288,15 +280,15 @@ sign-in steps.
 Invite-a-teammate-and-accept-as-them needs two identities mid-flow — not bankable as
 one test. 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
-drive the full handshake live: a second account (\`accounts create --label member\`), or
-a second mailbox (\`mailbox create --label invitee\`, read with \`mailbox read\`).
+drive the full handshake live: a second account (\`accounts_create\`, labelled), or a
+second mailbox (\`mailbox_create\`, read with \`mailbox_read\`).
 
 SSO-only sites are not a dead end: with a dedicated Google test account they follow §1
 item 2 like any password account. The captured session is the FALLBACK — no test account
 can be provided, or Google challenges the scripted sign-in: a human signs in once
 through a live browser view in the Beryl webapp, Beryl stores the session encrypted
-server-side and injects it into cloud runs — \`tests create\` verifies such plans
-server-side, \`runs trigger\` runs them, \`runs local\` skips them (the session never
+server-side and injects it into cloud runs, and \`tests_create\` verifies such plans
+server-side, \`runs_trigger\` runs them, \`runs_local\` skips them (the session never
 leaves Beryl's cloud).
 
 ## 2. Author locally over the Playwright MCP
@@ -310,9 +302,9 @@ leaves Beryl's cloud).
    - **at least one step is an \`expect\`** (a test that asserts nothing is not a test).
    **A \`goto\` at your own app is a PATH, never a full URL** — \`/pricing\`, not
    \`https://app.example.com/pricing\`. The origin comes from the environment's root
-   URL, so one plan runs against prod, staging and a preview; bake the origin in and
-   \`--env\` is silently ignored. Absolute URLs stay legal for OTHER origins (an OAuth
-   handoff, a magic link on another domain).
+   URL, so one plan runs against prod, staging and a preview; bake the origin in and the
+   run's environment is silently ignored. Absolute URLs stay legal for OTHER origins (an
+   OAuth handoff, a magic link on another domain).
    Optional \`before\` / \`after\` arrays hold setup and teardown; \`after\` runs even
    when a main step fails, so a create flow can clean up its record — and a deletion
    flow creates its own record in \`before\` first. A step in \`after\` may carry
@@ -361,21 +353,28 @@ ${JSON.stringify(BERYL_TEST_SKILL_EXAMPLE_PLAN, null, 2)
     .map((line) => `   ${line}`)
     .join("\n")}
    \`\`\`
-3. **Validate offline, then create:**
-   \`\`\`
-   beryl tests lint --file plan.json        # check the plan against the schema, no network
-   beryl tests create --title "Log in" --file plan.json \\
-     --description "<the intent — see §3>"
-   \`\`\`
-   \`create\` banks the plan only on a green local replay; a red one hands back the
-   failure — fix and re-run. It records no run. Replay mechanics (where it runs over
-   MCP, \`--no-verify\`, the cloud-session exception) are in \`tests create\`'s own
-   description. Inspect the exact spec with \`beryl tests script --file plan.json\`.
+3. **Validate offline, then create.** Lint with \`tests_lint\` (schema check, no network),
+   then bank with \`tests_create\` (the title, the plan, and the \`description\` intent, see
+   §3). \`tests_create\` banks the plan only on a green local replay; a red one hands back
+   the failure to fix and re-run. It records no run. Replay mechanics (where it runs over
+   MCP, its verify option, the cloud-session exception) are in the \`tests_create\` tool's
+   own description. Inspect the exact spec with \`tests_script\`.
    Full ActionPlan JSON Schema:
    https://api.beryl.so/api/v1/schemas/action-plan.schema.json.
-   Groups are optional and never block: after the test is banked, if \`beryl groups list\`
-   shows any, offer them once (\`tests set-groups <id> --group <name>\`); no answer = leave
-   it ungrouped and move on. Never create a group yourself — that's the user's call.
+   Groups are optional and never block: after the test is banked, if \`groups_list\`
+   shows any, offer them once (\`tests_set_groups\`); no answer = leave it ungrouped and
+   move on. Never create a group yourself, that is the user's call.
+
+### Testing a mobile or tablet viewport
+A test runs at a desktop viewport unless you say otherwise. To cover a responsive layout,
+set \`device\` on the plan: \`"mobile"\` or \`"tablet"\` (default \`"desktop"\`). This is
+full Chromium device emulation, not a resize: the viewport, a mobile Chrome user-agent,
+touch and the device pixel ratio all change together, so a hamburger or a nav that only
+exists on small screens actually renders and is testable. \`mobile\` emulates a Pixel-class
+phone, \`tablet\` a Galaxy-class tablet; both keep a Chrome user-agent so the emulated UA
+matches the engine. Author the flow at that size over the Playwright MCP (resize the MCP
+browser to match) so the refs you act on are the ones the small-screen layout renders. The
+account, session and teardown rules are unchanged; \`device\` only sets the frame it runs in.
 
 ### The outcome assertion is the whole game
 
@@ -407,7 +406,7 @@ observable proof the flow worked.
 
 ### Traps when authoring against a real app
 
-Every one of these has produced a wrong plan or a red \`tests create\`. Check them.
+Every one of these has produced a wrong plan or a red \`tests_create\`. Check them.
 
 1. **Your browser may already be signed in.** The Playwright MCP keeps a persistent
    profile. Author while signed in and you never see the gate — you will mark gated
@@ -439,8 +438,8 @@ Every one of these has produced a wrong plan or a red \`tests create\`. Check th
 
 ## 3. Writing the natural-language intent
 
-Pass the intent as \`--description\` on \`beryl tests create\` (or \`tests set-plan\`
-when you re-author). 1–3 sentences. This is the immutable anchor from §6.
+Give the intent as the \`description\` of \`tests_create\` (or \`tests_set_plan\`
+when you re-author). 1-3 sentences. This is the immutable anchor from §6.
 
 - **State the purpose, not the steps.** Not "clicks Sign in, types email and password,
   clicks submit" — the trajectory will change. Instead: *what does a green run prove is
@@ -458,20 +457,17 @@ Weak (describes steps + asserts nothing meaningful):
 
 ## 4. The local run-fix loop
 
-Iterate on your machine before you rely on the cloud. \`beryl runs local\` runs banked
-tests with the Playwright runner bundled in the CLI — no cloud, no waiting for a scheduled run.
-
-\`\`\`
-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
-\`\`\`
+Iterate on your machine before you rely on the cloud. \`runs_local\` runs banked tests
+with the Playwright runner bundled in the CLI: no cloud, no waiting for a scheduled run.
+Run it un-synced with a report directory against one test id while you iterate, or with
+no id to run the whole suite and record the results in Beryl.
 
-The loop: draft → \`tests lint\` → \`tests create\` (proves, records nothing) →
-\`runs local --no-sync\` while iterating → read \`--dir\`'s \`report.json\` to see which
-step or assertion failed and why → fix the plan → \`tests set-plan\` → run again. When
-the batch is done, one synced \`runs local <id…>\` (or \`runs trigger\`) records it as a
-single run. Flag semantics, session-mode behavior, \`await_email\` and
-authenticated-test handling, and exit codes are in \`runs local\`'s own description.
+The loop: draft → \`tests_lint\` → \`tests_create\` (proves, records nothing) → \`runs_local\`
+un-synced while iterating → read the run's \`report.json\` to see which step or assertion
+failed and why → fix the plan → \`tests_set_plan\` → run again. When the batch is done, one
+synced \`runs_local\` (or \`runs_trigger\`) records it as a single run. Its options,
+session-mode behavior, and \`await_email\` / authenticated-test handling are in the
+\`runs_local\` tool's own description.
 
 ## 5. Testing an OTP / signup flow (\`await_email\`)
 
@@ -482,7 +478,7 @@ flag to turn on.
 **The project has one permanent mailbox and all of its mail arrives there.** The
 standing account is used one way only, \`requires_auth: true\` (its session is injected
 before the first step); a test never types its address (the save refuses it), only the
-account's own \`signup\` / \`set-login\` plans fill \`{{mailbox_address}}\`. Every flow that
+account's own signup and sign-in plans fill \`{{mailbox_address}}\`. Every flow that
 sends mail (a signup, a sign-in code, a wrong code, a lockout, a resend timer, an
 invitation) cites \`{{inbox_address}}\`, a \`+tag\` alias minted per execution and read by
 this test alone.
@@ -492,7 +488,7 @@ this test alone.
 | creates an account, or signs in as one it created (a returning-user test: \`before\` signs up the alias and logs out, the steps sign in as it) | an \`after\` section that deletes it through the app, its steps marked \`optional\`; a plan that reads its signup mail is refused at save time without one |
 | only makes mail arrive, read or not, no account created | nothing to clean up; mail is kept for 48 hours |
 
-Every alias minted is listed by \`beryl mailbox identities\` with how its teardown
+Every alias minted is listed by \`mailbox_identities\` with how its teardown
 ended; the run detail shows the same outcome on each result.
 
 The wiring is a three-part chain:
@@ -527,11 +523,11 @@ For a magic-link flow, replace the code steps with
 
 Two caveats:
 
-- \`beryl tests create\` verifies an \`await_email\` plan like any other: the local
+- \`tests_create\` verifies an \`await_email\` plan like any other: the local
   replay receives at the project mailbox and answers each step over the API, so the
   app's mail really is received and extracted before the test is accepted. 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 local loop
+  signs up / sends mail FOR REAL, so turn \`tests_create\`'s verify off only if that side
+  effect is unwanted. \`runs_local\` serves \`await_email\` the same way, so the local loop
   covers OTP/signup flows end to end.
 - §2's outcome discipline still applies: the green signal is the post-verification
   state (the welcome screen, the dashboard), not "an email arrived".

package/dist/commands/init.js

@@ -89,6 +89,22 @@ function claudeAddHint(name, entry) {
 function cursorUserConfigPath() {
     return path.join(os.homedir(), ".cursor", "mcp.json");
 }
+// VS Code's user-scope MCP config lives in the profile dir, NOT ~/.vscode (which VS Code
+// ignores): macOS ~/Library/Application Support/Code/User, Linux ~/.config/Code/User,
+// Windows %APPDATA%/Code/User. Pure resolver so all three platforms are testable.
+export function vscodeUserConfigDirFor(platform, home, env) {
+    return platform === "darwin"
+        ? path.join(home, "Library", "Application Support", "Code", "User")
+        : platform === "win32"
+            ? path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Code", "User")
+            : path.join(env.XDG_CONFIG_HOME ?? path.join(home, ".config"), "Code", "User");
+}
+// Returns null when that dir is absent (VS Code not installed there, Insiders / VSCodium,
+// portable mode) so the caller falls back to a repo-local file.
+function vscodeUserConfigDir() {
+    const dir = vscodeUserConfigDirFor(process.platform, os.homedir(), process.env);
+    return fs.existsSync(dir) ? dir : null;
+}
 // Write generated content that ships with the CLI and changes every release, so anything
 // that differs is overwritten: a stale copy silently feeds agents months-old guidance,
 // which is worse than losing a local edit the user can redo (and `beryl guide` still prints
@@ -218,7 +234,8 @@ export const initCommands = [
             "instead. With --cursor the same two servers are also wired into Cursor and a repo-local " +
             ".cursor/rules/beryl.mdc authoring rule is written (Cursor's equivalent of the skill, " +
             "since it reads neither skills dir); --vscode does the same for VS Code / GitHub Copilot " +
-            "(.vscode/mcp.json plus a marked section in .github/copilot-instructions.md). No " +
+            "(VS Code's user mcp.json, or .vscode/mcp.json with --scope project, plus a marked " +
+            "section in .github/copilot-instructions.md). 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 run " +
             "refreshes the authoring skill to this CLI's version (overwriting an older or edited " +
@@ -244,8 +261,8 @@ export const initCommands = [
             {
                 name: "vscode",
                 type: "boolean",
-                description: "Also wire the two MCP servers into .vscode/mcp.json and add a Beryl section to " +
-                    ".github/copilot-instructions.md for GitHub Copilot (both repo-local)",
+                description: "Also wire the two MCP servers into VS Code's user config (or .vscode/mcp.json with " +
+                    "--scope project) and add a Beryl section to .github/copilot-instructions.md for Copilot",
             },
         ],
         examples: [
@@ -341,16 +358,30 @@ export const initCommands = [
             // marked section in `.github/copilot-instructions.md` for the guide pointer. VS Code's
             // per-user MCP config is managed through its UI, not a portable file, so scope is moot.
             if (input.flags.vscode) {
-                const file = path.join(cwd, ".vscode", "mcp.json");
+                // User scope (default) targets VS Code's real profile mcp.json, so it works in
+                // every project. Project scope, or a missing profile dir, falls back to the repo.
+                const userDir = scope === "user" ? vscodeUserConfigDir() : null;
+                const file = userDir
+                    ? path.join(userDir, "mcp.json")
+                    : path.join(cwd, ".vscode", "mcp.json");
                 const wrote = mergeMcpConfig(file, "servers", {
                     beryl: VSCODE_MCP_SERVER_ENTRY,
                     playwright: VSCODE_PLAYWRIGHT_SERVER_ENTRY,
                 });
-                const where = path.relative(cwd, file);
+                const where = userDir ? file : path.relative(cwd, file);
                 report("vscode beryl MCP", wrote.beryl, where);
                 report("vscode playwright MCP", wrote.playwright, where);
+                if (scope === "user" && !userDir) {
+                    ctx.err(dim("  • VS Code's user config dir was not found, so this went to a repo-local " +
+                        ".vscode/mcp.json. Run --vscode from your project, or add the server via " +
+                        'VS Code\'s "MCP: Add Server".'));
+                }
                 const inst = writeCopilotInstructions(cwd);
                 ctx.err(`${green("✓")} copilot instructions ${outcomeLabel(inst.outcome)} ${dim(path.relative(cwd, inst.file))}`);
+                if (!fs.existsSync(path.join(cwd, ".git"))) {
+                    ctx.err(dim("  • copilot-instructions is repo-local; this dir is not a git repo, so " +
+                        "Copilot may not read it. Run --vscode from your project root."));
+                }
             }
             const skills = writeSkills(cwd, scope);
             for (const skill of skills) {
@@ -367,10 +398,16 @@ export const initCommands = [
                 ctx.err(`${green("✓")} Beryl authoring skill ${what} ${dim(where)}`);
             }
             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` +
+            // Name the editor's own agent, so the message speaks to what the user just set up.
+            const ed = input.flags.vscode
+                ? { open: "open VS Code", agent: "Copilot" }
+                : input.flags.cursor
+                    ? { open: "open Cursor", agent: "Cursor" }
+                    : { open: "open your editor", agent: "Claude" };
+            const nextSteps = `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to write tests.`)}\n` +
+                `  ${dim(`• Say: "write tests for https://your-app.com" and ${ed.agent} picks your workspace/project`)}\n` +
                 `  ${dim("  and sets the URL for you (no pin, no prompt).")}\n` +
-                `  ${dim("• Playwright MCP is wired — Claude can drive a real browser to author from your plan.")}\n` +
+                `  ${dim(`• Playwright MCP is wired, so ${ed.agent} 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.

package/dist/schema.generated.js

@@ -36,6 +36,16 @@ export const ACTION_PLAN_SCHEMA = {
             "title": "AuthMode",
             "type": "string"
         },
+        "DeviceClass": {
+            "description": "The viewport and device a test runs at. The AUTHOR sets it when a flow is specific\nto a form factor (a mobile-only nav, a hamburger, a stacked layout); omit it and the\ntest runs at the default desktop viewport.\n\n``mobile`` / ``tablet`` are full Chromium device emulation, not a bare resize: the\nviewport, a mobile Chrome user-agent, touch, and the device pixel ratio all change\ntogether, so a control gated behind a touch or mobile-UA media query actually appears.",
+            "enum": [
+                "desktop",
+                "tablet",
+                "mobile"
+            ],
+            "title": "DeviceClass",
+            "type": "string"
+        },
         "DialogChoice": {
             "enum": [
                 "accept",
@@ -1344,6 +1354,11 @@ export const ACTION_PLAN_SCHEMA = {
             "title": "Before",
             "type": "array"
         },
+        "device": {
+            "$ref": "#/$defs/DeviceClass",
+            "default": "desktop",
+            "description": "Viewport and device to run at. 'mobile' and 'tablet' apply full Chromium device emulation (viewport, mobile user-agent, touch, pixel ratio); 'desktop' (default) runs at the standard desktop viewport."
+        },
         "requires_auth": {
             "default": false,
             "title": "Requires Auth",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beryl-so/cli",
-  "version": "0.50.0",
+  "version": "0.52.0",
   "description": "Beryl on the command line — projects, runs, the exploring agent, and an MCP server over the same commands.",
   "license": "MIT",
   "type": "module",