@beryl-so/cli 0.17.0 → 0.22.0

package/dist/beryl-test-skill.js

@@ -11,7 +11,7 @@ export const BERYL_TEST_SKILL_DIR = "beryl-test";
 // lintPlan — the skill's documented shape must pass `beryl tests lint` on the first try.
 export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
     steps: [
-        { action: "goto", url: "https://app.example.com/pricing" },
+        { action: "goto", url: "/pricing" },
         {
             action: "expect",
             expect_kind: "have_text",
@@ -26,7 +26,7 @@ export const BERYL_TEST_SKILL_EXAMPLE_PLAN = {
 // pass `beryl tests lint` on the first try.
 export const BERYL_TEST_SKILL_OTP_EXAMPLE_PLAN = {
     steps: [
-        { action: "goto", url: "https://app.example.com/signup" },
+        { action: "goto", url: "/signup" },
         { action: "fill", selector: "input[name=email]", value: "{{inbox_address}}" },
         { action: "click", selector: "button[type=submit]" },
         {
@@ -57,7 +57,183 @@ 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 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)
+\`\`\`
+
+\`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.
+
+**Creates share the sign-in.** \`tests create\` replays a session-mode plan against the
+account's established session — reused from the last proven sign-in when it is still
+live — so a batch of creates costs at most one sign-in, same as a run. Still create one
+at a time: two racing creates would race the same mailbox for mail.
+
+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 — same shape as the cloud: one
+sign-in per invocation, shared by every session-mode test.
+
+### 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
@@ -67,6 +243,11 @@ assertion**, a strong **natural-language intent**, and the **local run-fix loop*
    \`{action, selector, url, value, ...}\`. Two structural rules the plan must satisfy:
    - the **first executed step is a \`goto\`** (the flow has to start by navigating somewhere), and
    - **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: the test keeps hitting whatever host you typed. 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/update/delete flow can clean up the record it made.
 
@@ -126,7 +307,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 +320,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 +376,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
 \`\`\`
@@ -197,23 +385,22 @@ beryl runs local              # the whole suite, results recorded in Beryl
 - **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.
+- \`--url-override\` swaps the root URL for THIS run — for a throwaway host (a dev server, a
+  per-PR preview). A standing environment is \`--env <id>\` instead, not an override.
 - \`--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.
-- \`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 +408,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 +458,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.
 `;