@beryl-so/cli 0.17.0 → 0.21.4

package/README.md

@@ -288,17 +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 | — |
 
-### inbox
+### mailbox
 
-Email inboxes for testing flows that send mail — signups, OTPs, receipts.
+The project's standing email addresses — where its tests receive sign-in mail.
+
+`beryl mailbox` with no subcommand runs `mailbox get`.
+
+| Command | Summary | MCP tool |
+| --- | --- | --- |
+| `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
+
+Durable identities on the site under test — what an authenticated test signs in as.
+
+`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
 
@@ -329,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
@@ -126,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
@@ -139,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".
 
@@ -188,7 +370,7 @@ 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
+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
 \`\`\`
@@ -203,17 +385,15 @@ beryl runs local              # the whole suite, results recorded in Beryl
   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.
-- \`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\`.
+- \`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.
@@ -221,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).
@@ -258,48 +451,33 @@ For a magic-link flow, replace the code steps with
 Two caveats:
 
 - \`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
+  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. 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.
+## 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.
 `;