@beryl-so/cli 0.14.1 → 0.21.4

package/README.md

@@ -222,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
@@ -234,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` |
@@ -267,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` |
@@ -288,42 +288,37 @@ 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
+### mailbox
 
-Manage saved logins Beryl reuses to test behind authentication, and attach them to projects.
+The project's standing email addresses — where its tests receive sign-in mail.
 
-| 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.
+`beryl mailbox` with no subcommand runs `mailbox get`.
 
 | 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 capture <session-id>` | Save the session after the user has logged in via the live-view URL (first login or re-login) | `auth_capture_capture` |
-| `beryl auth-capture release <session-id>` | Release a login-capture browser session without capturing | `auth_capture_release` |
+| `beryl mailbox get` | The project's mailbox address | `mailbox_get` |
+| `beryl mailbox list` | List the project's mailboxes | `mailbox_list` |
+| `beryl mailbox create` | Add a second mailbox to the project | `mailbox_create` |
+| `beryl mailbox delete <mailbox-id>` | Delete a mailbox and every email it has received | `mailbox_delete` |
+| `beryl mailbox read <mailbox-id>` | Read the latest email in a mailbox (waits for one to arrive) | `mailbox_read` |
+| `beryl mailbox emails <mailbox-id>` | List the emails a mailbox has received | `mailbox_emails` |
+
+### accounts
 
-### inbox
+Durable identities on the site under test — what an authenticated test signs in as.
 
-Email inboxes for testing flows that send mail — signups, OTPs, receipts.
+`beryl accounts` with no subcommand runs `accounts list`.
 
 | Command | Summary | MCP tool |
 | --- | --- | --- |
-| `beryl inbox create` | Mint an email inbox that Beryl receives mail for | `inbox_create` |
-| `beryl inbox list` | List the workspace's inboxes, newest first | `inbox_list` |
-| `beryl inbox delete <inbox-id>` | Delete an inbox and every email it has received | `inbox_delete` |
-| `beryl inbox read <inbox-id>` | Read the latest email from an inbox (waits for one to arrive) | `inbox_read` |
-| `beryl inbox emails <inbox-id>` | List the emails an inbox has received | `inbox_emails` |
+| `beryl accounts list` | List the test accounts an environment's tests sign in as | `accounts_list` |
+| `beryl accounts create` | Add a test account — the customer's own, or one Beryl signs up | `accounts_create` |
+| `beryl accounts provision <account-id>` | Prove a test account can get in, by replaying a plan that ends logged in | `accounts_provision` |
+| `beryl accounts set-login <account-id>` | Store the sign-in plan a run replays once, plus the probe that proves it | `accounts_set_login` |
+| `beryl accounts get-login <account-id>` | Read the stored sign-in plan, its probe, and the hash a safe write must cite | `accounts_get_login` |
+| `beryl accounts check <account-id>` | Sign in now and prove the session survives into a fresh browser | `accounts_check` |
+| `beryl accounts update <account-id>` | Change a test account's password, login method, or default flag | `accounts_update` |
+| `beryl accounts delete <account-id>` | Delete a test account | `accounts_delete` |
 
 ### account
 
@@ -354,6 +349,14 @@ Review a workspace's plan usage, subscription, and invoices.
 | `beryl billing invoices` | List recent invoices | — |
 | `beryl billing portal` | Get a Stripe billing-portal link for the workspace | — |
 
+### version
+
+Show the running CLI version, API URL, and Node version
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `beryl version` | Show the running CLI version, API URL, and Node version | `version` |
+
 ### mcp
 
 Run the Beryl MCP server (stdio) — every CLI command as an agent tool

package/dist/adapters/cli.js

@@ -230,6 +230,8 @@ export async function runCli(argv) {
     // flag we don't recognise as global — that one belongs to the command.
     const words = [];
     const wordIndices = [];
+    let sawGlobalFlag = false;
+    let sawVersionFlag = false;
     for (let i = 0; i < argv.length; i++) {
         const tok = argv[i];
         if (tok === "--")
@@ -238,6 +240,9 @@ export async function runCli(argv) {
             const span = globalFlagSpan(argv, i);
             if (span === 0)
                 break;
+            sawGlobalFlag = true;
+            if (tok === "--version" || tok === "-V")
+                sawVersionFlag = true;
             i += span - 1;
             continue;
         }
@@ -246,7 +251,16 @@ export async function runCli(argv) {
     }
     let rest = argv;
     let restWordIndices = wordIndices;
-    if (argv.includes("--version") || argv.includes("-V") || words[0] === "version") {
+    // `-V`, `--version`, and a plain `beryl version` keep printing just the number: that
+    // one-line output is a contract CI users parse, so it stays intercepted here rather than
+    // going through the registry (which would render the full key/value block instead).
+    // Any global flag alongside the `version` word (`--json`, `--api-url`, `--help`, …) means
+    // the caller wants more than the number, so it falls through to the `version` spec — the
+    // same build picture the `version` MCP tool returns (api_url, Node, staleness). Only flags
+    // the scanner above actually recognised count, so it honours `--` the same way (tokens
+    // after it are inert positionals, not a request for the spec).
+    const versionWord = words[0] === "version" && words.length === 1;
+    if (sawVersionFlag || (versionWord && !sawGlobalFlag)) {
         process.stdout.write(cliVersion() + "\n");
         return EXIT_OK;
     }

package/dist/adapters/mcp.js

@@ -1,8 +1,11 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import fs from "node:fs";
+import { loadConfig } from "../config.js";
 import { createContext } from "../context.js";
 import { CliError } from "../errors.js";
+import { ApiClient } from "../http.js";
 import { commands } from "../registry/index.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 export function toolName(spec) {
@@ -71,15 +74,50 @@ function toInput(spec, params) {
     }
     return { args, flags };
 }
+let authCache;
+/** The credentials as they are on disk RIGHT NOW, not as they were at spawn.
+ *
+ *  This server is long-lived and never re-execs, so reading the token once would leave a
+ *  `beryl login` performed afterwards invisible to it forever — and the 401 it then
+ *  returns tells you to run the login you just ran, which is unescapable without knowing
+ *  to reconnect. Keyed on mtime so the common path is a stat, not a rebuilt client. */
+export function currentAuth(fallback) {
+    let mtimeMs = 0;
+    try {
+        mtimeMs = fs.statSync(fallback.config.globalConfigPath).mtimeMs;
+    }
+    catch {
+        // No config file (env-var auth, or never logged in) — nothing to watch.
+    }
+    if (authCache?.mtimeMs === mtimeMs)
+        return authCache.auth;
+    const config = loadConfig();
+    const auth = {
+        client: new ApiClient(config.apiUrl, config.token),
+        config,
+    };
+    authCache = { mtimeMs, auth };
+    return auth;
+}
+export function __resetAuthCacheForTests() {
+    authCache = undefined;
+}
 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: {} },
-        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 " +
+        // The running version is stated up front because this server is long-lived and never
+        // hot-reloads: a session can sit on a days-old build while `@latest` has moved, and
+        // "that tool doesn't exist for me" is indistinguishable from a bug without it. Saying
+        // it here means the model knows without spending a `version` tool call.
+        instructions: `Beryl CLI v${cliVersion()} (call the \`version\` tool for the API URL, Node ` +
+            "version, and whether this build is behind npm's latest). " +
+            "Beryl authors, runs, and heals end-to-end tests for any web app: tests are JSON " +
+            "action plans replayed in real cloud browsers, signing in as a durable test " +
+            "account whose mail arrives at the project's own mailbox — so signup/OTP/" +
+            "magic-link flows are self-contained, with 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).",
     });
@@ -105,9 +143,10 @@ export async function serveMcp(baseCtx) {
             if (lines.length > 400)
                 lines.splice(0, lines.length - 400);
         };
+        const auth = currentAuth(baseCtx);
         const ctx = createContext({
-            client: baseCtx.client,
-            config: baseCtx.config,
+            client: auth.client,
+            config: auth.config,
             json: true,
             interactive: false,
             mcp: true,

package/dist/beryl-test-skill.js

@@ -57,7 +57,182 @@ because Beryl can **heal** them — but only when you give it what it needs to.
 Read this before authoring. The three ideas that make a test durable: a real **outcome
 assertion**, a strong **natural-language intent**, and the **local run-fix loop**.
 
-## 1. Author locally over the Playwright MCP
+## 0. Start here
+
+**Everything happens on your machine first.** You drive the flow in a real browser here,
+and \`tests create\` replays the plan here — over MCP that means the machine running the
+MCP server, never Beryl's. A red replay banks nothing. Two exceptions to "proven
+locally": a plan that depends on a session only Beryl's cloud holds is verified
+server-side instead (create tells you when), and \`--no-verify\` banks unproven — avoid
+it. So a broken local browser is not a detail you can skip past; it is the whole loop.
+
+Before the first plan:
+
+\`\`\`
+npm i -D @playwright/test && npx playwright install chromium   # once, per project
+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)
+\`\`\`
+
+\`accounts list\` comes FIRST, before you author anything. It decides whether a flow signs
+in as a standing account or acquires a new identity, and that choice changes the plan you
+write — discovering it afterwards means rewriting. If a flow needs signing in, the
+account's login plan has to be stored before you can create the test at all.
+
+Then, per test:
+
+1. **Drive the flow** in a real browser over the Playwright MCP — never author from
+   imagination (§2).
+2. **Write the ActionPlan**, with one real outcome assertion (§2).
+3. \`beryl tests lint --file plan.json\` — schema check, offline, no network.
+4. \`beryl tests create --title … --file … --description "<the intent>"\` — replays the plan
+   locally and banks it only if it goes green. A red replay banks nothing and hands back
+   the failure; fix the file and re-run (§3 for the intent, §4 for the loop).
+5. \`beryl runs local\` — re-run banked tests on your machine while iterating.
+6. \`beryl runs trigger\` — hand it to Beryl's cloud, on demand or on a schedule.
+
+## 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\`:
+
+\`\`\`
+label      email                          type           login     status
+default *  qa@acme.test                   user_provided  password  ready
+admin      qa+admin@x7k2p9.email.beryl.so beryl          otp       ready
+\`\`\`
+
+Author the sign-in as ordinary opening steps citing the reserved handles — fill
+\`{{login_email}}\`, fill \`{{login_password}}\`, submit, assert the logged-in shell. Set
+\`requires_auth: true\` AND \`auth_mode\` — both, always. \`auth_mode\` has NO default and
+a \`requires_auth\` plan without it is rejected at create: \`"inline"\` when the plan
+signs itself in like this, \`"session"\` when it carries no sign-in steps and rides its
+account's once-per-run session (§ Session mode). Add \`auth_label\` only to pick a
+non-default identity (the row marked \`*\` is what a plan gets otherwise). The handles
+resolve at run time to whichever account the plan named, so one plan stays correct
+across environments.
+
+**The account needs a stored login plan before any authenticated test can be created.**
+That plan is what a run replays to produce the session its tests ride, and replays again
+when the session expires — so \`tests create\` rejects a \`requires_auth\` plan whose
+account has none, and names the command. Store it once per account with
+\`beryl accounts set-login\` (§ Session mode); everything after that is just authoring.
+
+**NEVER paste a real email or password into a plan.** The handles resolve at run time —
+the password never lands in the rendered spec and is scrubbed from artifacts. A pasted
+value is baked into the test forever and rots on the next rotation.
+
+### Why this matters for coverage
+
+The account persists between runs, so it accumulates real data — and that is the point. A
+standing account reaches what a fresh signup never could: a populated list, filters with
+something to filter, run history, a dashboard with numbers in it. **When a flow needs
+pre-existing data, that is the signal to use the test account** rather than building the
+data inside the test.
+
+The trade is drift — run 200 has 200 of everything run 1 created. So:
+
+- **Assert relatively, never absolutely.** "The row I just created is present"
+  (\`expect.persisted\` on a \`{{unique}}\`-named row), not "there are 3 rows". A count
+  assertion is true in week one and false in week four with nobody having touched it.
+- **Clean up what you create** — put the delete in the plan's \`after\` section, which runs
+  on pass AND on fail, unlike a trailing step inside \`steps\`.
+
+### If there is no account yet
+
+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.
+2. **No credentials, but the app has a signup form** → let Beryl make one.
+   \`beryl accounts create --type beryl\`, then prove it with
+   \`beryl accounts provision <id> --file <plan.json>\`. The plan is any ActionPlan that
+   ends LOGGED IN — a signup filling \`{{mailbox_address}}\` and \`{{login_password}}\`
+   when the account is new, or a **sign-in** when it already exists (you made it by hand,
+   or a previous provision succeeded and the record was lost). Both prove the same thing.
+   If the app has no password sign-in, pass \`--login-method otp\` (or \`magic_link\`)
+   and let the plan \`await_email\` its way through — later sign-ins read the same mailbox.
+3. **Neither** → the flow is not testable authenticated. Say so rather than guessing.
+
+A project with no accounts still falls back to the \`LOGIN_EMAIL\` variable +
+\`LOGIN_PASSWORD\` secret and the handles resolve the same way, so existing tests are
+unaffected — but new work should create an account.
+
+### Session mode: sign in once per run, not once per test
+
+Every \`requires_auth\` plan declares its \`auth_mode\` — there is no default. With
+\`"inline"\` the test carries its own sign-in steps and re-types them on every run; that
+is fine and always available.
+
+\`auth_mode: "session"\` moves the sign-in out of the test. The account signs in ONCE at
+the start of the run, the resulting browser session is proved live, and every
+\`requires_auth\` test in that run rides it — session-mode tests carry no sign-in steps
+at all, and inline ones simply start already signed in. The test then starts where the
+flow it actually tests begins — no login preamble in the plan, in the replay, or in the
+failure evidence. Nothing has to be turned on for it: every run signs in its accounts and
+hands out the sessions. What a session-mode test DOES need is a stored login plan on its
+account — with none, there is nothing to sign in with, and the test fails at setup with
+\`SESSION_NO_LOGIN_PLAN\` rather than falling back, because it has no sign-in steps of its
+own to fall back to.
+
+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
+\`\`\`
+
+- **\`--file\`** is the SIGN-IN plan (not the signup): opens the login page, fills
+  \`{{login_email}}\` / \`{{login_password}}\`, \`await_email\`s a code if the account
+  needs one, and asserts the logged-in shell.
+- **\`--probe\`** is two steps: goto a gated page, then a **positive** assertion that only
+  holds when signed in — \`expect.visible\` on the account menu or a "Sign out" control.
+  It is required. \`hidden\`, \`count 0\` and a URL match on a redirect ALL pass against a
+  logged-out page, so without a positive signal a dead session runs every test logged-out
+  and the run still reports green.
+
+Then write the tests with \`requires_auth: true\` and \`auth_mode: "session"\`, and NO
+sign-in steps.
+
+**Create them one at a time.** Locally there is no run to share a session across, so
+\`tests create\` renders each session-mode test with the account's sign-in in front of it —
+every create performs a real sign-in. Two at once would both trigger a code and race for
+the newest mail in the same mailbox. In the cloud that cost disappears: the whole run
+shares one sign-in.
+
+Reading before writing matters here: the login plan self-heals, so
+\`beryl accounts get-login <id>\` first and pass its \`login_plan_hash\` back as
+\`--base-hash\` — a blind overwrite would clobber a repair you never saw.
+
+An expired session is never your problem to notice. Beryl proves the stored session at
+the start of every run and, if it no longer works, treats that as a cache miss and signs
+in again from the login plan. Nothing asks a human to reconnect — that message only
+appears for a project with no stored login plan to refresh from.
+
+What to expect when it does not work: \`accounts check\` returning
+\`SESSION_LOGIN_FAILED\` means the sign-in plan itself is wrong — fix it.
+\`SESSION_PROOF_FAILED\` means signing in worked but the session could not be carried into
+a fresh browser, because this app keeps its credential somewhere unextractable. That is not
+your bug, but it IS your move: the account is marked unsupported, and its session-mode
+tests fail at setup with \`SESSION_UNSUPPORTED\` on every run until you re-author them
+with \`auth_mode: "inline"\` and their own sign-in steps. Inline tests are unaffected.
+
+\`beryl runs local\` works on session-mode tests too — locally the server renders the
+account's sign-in steps in front of the test, so it proves the same thing on your machine.
+
+### Two identities in one test
+
+Still not bankable as one test: invite-a-teammate-and-accept-as-them needs two identities
+mid-flow. 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: create a second account (\`accounts create --label member\`), or add a
+second mailbox (\`mailbox create --label invitee\`) and read it (\`mailbox read\`).
+
+SSO-only sites (no email+password form at all) remain webapp territory.
+## 2. Author locally over the Playwright MCP
 
 1. **Drive the flow in a real browser first.** Use the Playwright MCP to open the app and
    walk the flow by hand — log in, fill the form, submit, whatever the flow is. You act on
@@ -97,8 +272,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
@@ -120,7 +301,7 @@ observable proof the flow worked. Get this right and everything else follows.
   \`/thank-you\`) and no distinctive destination content is available.
 - The usual outcome kinds: \`visible\` (the success element showed up), \`have_text\` (an
   element's text matches), \`have_url\` (the URL contains a value), \`gone\` (an element
-  disappeared — e.g. a spinner, or the item you just deleted). §1 has the full
+  disappeared — e.g. a spinner, or the item you just deleted). §2 has the full
   \`expect_kind\` list and the step shape.
 - **\`have_text\` is an EXACT full-text match on the selector's element** — asserting
   \`have_text: "Documentation"\` on \`body\` fails, because \`body\`'s text includes all the
@@ -133,38 +314,45 @@ observable proof the flow worked. Get this right and everything else follows.
   genuinely broken in the app, that's a finding to report — not something to paper over
   with a weaker assertion.
 
-## 2. What "durable" and "healable" mean here
-
-Beryl's cloud runs your test on a schedule. When the app's markup drifts and a selector
-stops matching, a heal-vs-fail agent decides whether to **heal** the test (silently
-re-derive the selector/trajectory and keep it green) or **fail** it (surface a real
-regression). It decides that against your test's **intent**:
-
-- **The natural-language intent is the immutable anchor. Beryl never rewrites it.** It's
-  the description of what the test proves — the load-bearing statement the heal agent
-  judges every future run against.
-- **Selectors and the trajectory are the healable "how".** A button moved, a class name
-  changed, a step needs an extra click — those are mechanics Beryl can re-derive on its
-  own, because your intent tells it what the flow was *for*.
-- **A failed outcome assertion is a real regression Beryl will NOT silently heal green.**
-  If the success signal from §1 stops holding — the confirmation never appears, the page
-  never renders — that's the app breaking, and the test fails loudly. That is the point.
-
-So a test is *healable* exactly when you gave it **a strong intent + a real outcome
-assertion**. A test with a vague intent and a chrome-only assertion is brittle: Beryl
-can't tell a real regression from cosmetic drift, so it either heals over real breakage or
-fails on noise.
+### Traps when authoring against a real app
+
+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, so a session can survive from earlier work. Author while signed in and you
+   never see the gate — you will mark gated pages as public. **Log out first**, then
+   confirm the page you think is gated really does redirect to the login.
+2. **The sign-UP flow is not the sign-IN flow.** A brand-new address often gets an extra
+   "create your account" step that a returning address skips entirely. An account's stored
+   login plan must be the **returning** path — that is what runs on every future run. Drive
+   it twice: once to create the account, once to see signing in again.
+3. **Read the DOM, not just the accessibility tree, before picking a selector.** Two
+   buttons can share a visible label ("Continue" and "Continue with Google"), and Beryl
+   relaxes \`text=X\` to a case-insensitive SUBSTRING — so \`text=Continue\` is ambiguous.
+   Find something unique (\`button[type=submit]\`, \`input[name=email]\`,
+   \`input[autocomplete=one-time-code]\`) and use that.
+4. **A single-page app can redirect after the first \`goto\`.** If \`/dashboard\` client-side
+   redirects to \`/dashboard/<id>\`, a click fired straight after the goto lands on the
+   pre-redirect render and its effect is discarded when the app re-renders — a dialog that
+   opens and instantly vanishes, for instance. Put a \`wait_for\` on something that exists
+   only AFTER the redirect, then act.
+5. **Never bake an id into a URL.** \`goto /projects/8ab46d63-.../settings\` breaks for any
+   other account. Navigate to the stable entry point and click through
+   (\`a[href$='/settings']\`), so the plan is about the app, not about your row.
+6. **Assert durable content, not the empty state.** "No tests yet" is true today and false
+   the moment anything exists. Prefer what is structural to the page — a section heading, a
+   permanent explainer, a control that is always there.
 
 ## 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 §2 — write it well.
+re-author). 1–3 sentences. This is the immutable anchor from §6 — write it well.
 
 - **State the purpose, not the steps.** Not "clicks Sign in, types email and password,
   clicks submit" — that's the trajectory, which Beryl already has and which will change.
   Instead: *what does a green run prove is true about the app?*
 - **Name the one observable outcome** that is true only if the flow worked — the same
-  success signal you asserted in §1, in words.
+  success signal you asserted in §2, in words.
 - **Never describe global chrome.** The intent is about the flow's destination and
   outcome, not "the header is present".
 
@@ -182,19 +370,30 @@ test's rendered spec and runs it with your local \`@playwright/test\` — no clo
 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
+npm i -D @playwright/test && npx playwright install chromium   # once
+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 answers them over the API against the same
+  mailbox the cloud runner would use, exactly as it would.
+- **Authenticated tests work locally.** A plan that signs itself in by filling
+  \`{{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 test account it names has
+  no password stored, the test is skipped with the exact fix-it command.
+- A test that depends on a session Beryl holds server-side, rather than signing itself in,
+  is skipped locally 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.
@@ -202,17 +401,30 @@ 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.
+— is testable with the \`await_email\` action. No setup, no environment configuration, no
+flag to turn on.
+
+**The project has one permanent mailbox and all of its mail arrives there.** Two handles
+put an address on the page, and the one you cite decides which *identity* the test acts as:
+
+| Handle | Renders as | Use it for |
+|---|---|---|
+| \`{{mailbox_address}}\` | the mailbox's own address, the same every run | signing in as the project's standing test account (§1) |
+| \`{{inbox_address}}\` | a \`+tag\` alias of it, fresh every run | tests whose subject IS getting a NEW identity — a signup, an invited teammate |
+
+An alias is a real address the site has never issued, so a signup is repeatable run after
+run; the mail still lands in the same mailbox, and Beryl reads only the alias's own mail.
+Nothing expires and there is no second inbox to manage.
+
+Default to \`{{mailbox_address}}\`. Reach for \`{{inbox_address}}\` only when an existing
+account would be rejected — a signup form, or an invite you must accept as a second person.
 
 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).
+1. **Type the address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\` (or
+   \`{{mailbox_address}}\`). An alias is fresh every run, 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).
@@ -238,12 +450,34 @@ 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\`.
-- The outcome assertion discipline from §1 still applies: the green signal is the
+- \`beryl tests create\` verifies an \`await_email\` plan like any other — its 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. (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 §2 still applies: the green signal is the
   post-verification state (the welcome screen, the dashboard), not "an email arrived".
+
+## 6. Why this shape: durable and healable
+
+Beryl's cloud runs your test on a schedule. When the app's markup drifts and a selector
+stops matching, a heal-vs-fail agent decides whether to **heal** the test (silently
+re-derive the selector/trajectory and keep it green) or **fail** it (surface a real
+regression). It decides that against your test's **intent**:
+
+- **The natural-language intent is the immutable anchor. Beryl never rewrites it.** It's
+  the description of what the test proves — the load-bearing statement the heal agent
+  judges every future run against.
+- **Selectors and the trajectory are the healable "how".** A button moved, a class name
+  changed, a step needs an extra click — those are mechanics Beryl can re-derive on its
+  own, because your intent tells it what the flow was *for*.
+- **A failed outcome assertion is a real regression Beryl will NOT silently heal green.**
+  If the success signal from §2 stops holding — the confirmation never appears, the page
+  never renders — that's the app breaking, and the test fails loudly. That is the point.
+
+So a test is *healable* exactly when you gave it **a strong intent + a real outcome
+assertion**. A test with a vague intent and a chrome-only assertion is brittle: Beryl
+can't tell a real regression from cosmetic drift, so it either heals over real breakage or
+fails on noise.
 `;