@beryl-so/cli 0.24.0 → 0.25.0

package/dist/beryl-test-skill.js

@@ -5,6 +5,12 @@
 // embedded string so it ships in the published package (`files: ["dist"]`) with no
 // build-time asset copy, and so there is ONE source for the guidance — not a copy in
 // the CLI and another in the docs. Edit here; `init` writes it verbatim.
+import { actionTable, expectTable, extractLine } from "./skill-tables.js";
+import { cliVersion } from "./version-check.js";
+const indent = (text) => text
+    .split("\n")
+    .map((line) => `   ${line}`)
+    .join("\n");
 export const BERYL_TEST_SKILL_FILENAME = "SKILL.md";
 export const BERYL_TEST_SKILL_DIR = "beryl-test";
 // The example plan the skill shows verbatim. Exported so the test suite lints it with
@@ -48,23 +54,21 @@ description: Author durable, healable end-to-end tests for a web app with Beryl.
 
 # Authoring Beryl tests
 
-Beryl is automated web-app testing: a test drives a real browser through a flow and
-asserts the flow reached its meaningful outcome. \`beryl init\` has already wired two MCP
-servers for you — **beryl** (create/list/run tests) and **playwright** (drive a real
-browser). Your job is to author tests that keep passing as the app's markup drifts,
-because Beryl can **heal** them — but only when you give it what it needs to.
+beryl-test v${cliVersion()} — installed by \`beryl init\`; the \`guide\` tool always returns the current version of this guide.
 
-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**.
+A Beryl test drives a real browser through a flow and asserts the flow reached its
+meaningful outcome. \`beryl init\` wired two MCP servers: **beryl** (create/list/run
+tests) and **playwright** (drive a real browser). Beryl **heals** tests as the app's
+markup drifts — but only when you supply the three things that make a test durable: a
+real **outcome assertion**, a strong **natural-language intent**, and the **local
+run-fix loop**.
 
 ## 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.
+**Everything happens on your machine first** — you drive the flow here, and
+\`tests create\` proves the plan here too, so a working local browser IS the loop.
+Avoid \`--no-verify\` (banks unproven); replay mechanics and the cloud-session
+exception are in \`tests create\`'s own description.
 
 Before the first plan:
 
@@ -78,10 +82,9 @@ beryl accounts check <id>                             # does that stored sign-in
 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.
+\`accounts list\` comes FIRST: standing account vs new identity changes the plan you
+write (discovering it afterwards means rewriting), and an authenticated test cannot be
+created until its account's login plan is stored.
 
 Then, per test:
 
@@ -89,9 +92,9 @@ Then, per test:
    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).
+4. \`beryl tests create --title … --file … --description "<the intent>"\` — replays the
+   plan locally, banks it only on green; a red replay hands back the failure — fix 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.
 
@@ -107,40 +110,41 @@ 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.
+\`{{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 create rejects a \`requires_auth\` plan without it. \`"inline"\` = the plan
+signs itself in like this; \`"session"\` = no sign-in steps, rides the account's
+once-per-run session (§ Session mode). \`auth_label\` picks a non-default identity
+(the \`*\` row is the default). Handles resolve at run time to the named account, 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
+A run replays that plan to produce the session its tests ride, and replays it again
 when the session expires — so \`tests create\` rejects a \`requires_auth\` plan whose
-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.
+account has none, naming the fix. Store it once per account with
+\`beryl accounts set-login\` (§ Session mode).
 
-**NEVER paste a real email or password into a plan.** The handles resolve at run time —
+**NEVER paste a real email or password into a plan.** Handles resolve at run time —
 the password never lands in the rendered spec and is scrubbed from artifacts. A pasted
-value is baked into the test forever and rots on the next rotation.
+value is baked in 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 account persists between runs and accumulates real data — that is the point. It
+reaches what a fresh signup never could: a populated list, filters with something to
+filter, run history, a dashboard with numbers. **A flow that needs pre-existing data is
+the signal to use the test account**, not to build 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\`.
+  (\`expect.persisted\` on a \`{{unique}}\`-named row), not "there are 3 rows" — a count
+  assertion goes stale by itself.
+- **Own the resource lifecycle, both directions.** Creating? Delete it in \`after\`
+  (runs on pass AND fail, unlike a trailing step inside \`steps\`). Deleting? Create
+  your own victim first — in \`before\` or the opening steps, \`{{unique}}\`-named —
+  then delete it and assert \`gone\`. Never aim a delete at standing data: run 2 would
+  have nothing to delete, and it eats the account's accumulated coverage.
 
 ### If there is no account yet
 
@@ -153,32 +157,26 @@ An empty \`accounts list\` means nothing is set up. In order of preference:
    \`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.
+   for a new account, or a **sign-in** for one that already exists (hand-made, or the
+   record was lost); both prove the same thing. No password sign-in? Pass
+   \`--login-method otp\` (or \`magic_link\`) and let the plan \`await_email\` through —
+   later sign-ins read the same mailbox.
 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
+A project with no accounts falls back to the \`LOGIN_EMAIL\` variable +
+\`LOGIN_PASSWORD\` secret with the same handle resolution, 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.
+\`"inline"\` re-types the plan's own sign-in steps every run; always available.
+
+\`"session"\` moves the sign-in out of the test: the account signs in ONCE at the start
+of the run, the session is proved live, and every \`requires_auth\` test rides it
+(inline ones just start already signed in). No login preamble in the plan, the replay,
+or the failure evidence; nothing to turn on. A session-mode test has no sign-in steps
+to fall back to, so an account with no stored login plan fails at setup with
+\`SESSION_NO_LOGIN_PLAN\`.
 
 Set it up once per account:
 
@@ -187,82 +185,89 @@ 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.
+What \`--file\` and \`--probe\` must contain, and the \`--base-hash\` read-before-write
+rule for later edits, are in \`accounts set-login\` / \`accounts get-login\`'s own
+descriptions.
 
-Then write the tests with \`requires_auth: true\` and \`auth_mode: "session"\`, and NO
+Then write the tests with \`requires_auth: true\`, \`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.
+**Creates share the sign-in.** \`tests create\` replays session-mode plans against the
+account's established session (reused while it stays live), so a batch of creates costs
+at most one sign-in — but still create one at a time: racing creates race the same
+mailbox for mail.
 
-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: every run proves the stored session and, on a
+miss, signs in again from the login plan. A "reconnect" message only appears when there
+is no stored login plan to refresh from.
 
-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.
+When \`accounts check\` fails, its description explains which half broke and each
+\`SESSION_*\` reason. The one that changes your authoring: an account marked
+unsupported (its session cannot survive a fresh browser) is not your bug, but it IS
+your move — re-author its session-mode tests with \`auth_mode: "inline"\` and their own
+sign-in steps.
 
 ### 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\`).
+Invite-a-teammate-and-accept-as-them needs two identities mid-flow — not bankable as
+one test. Bank the half the app shows to account A ("the invitation is listed as
+pending", "the share link is issued") — a real, strong outcome. While AUTHORING you can
+drive the full handshake live: a second account (\`accounts create --label member\`), or
+a second mailbox (\`mailbox create --label invitee\`, read with \`mailbox read\`).
+
+SSO-only sites (no email+password form at all) ride a captured session instead: a human
+signs in once through a live browser view in the Beryl webapp, Beryl stores the session
+encrypted server-side and injects it into cloud runs — \`tests create\` verifies such
+plans server-side, \`runs trigger\` runs them, \`runs local\` skips them (the session
+never leaves Beryl's cloud).
 
-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
-   elements by their accessibility ref from the latest page snapshot, not a guessed
-   selector. Watch what actually happens; don't author from imagination.
+1. **Drive the flow in a real browser first.** Walk it by hand over the Playwright MCP
+   — log in, fill, submit — acting on elements by their accessibility ref from the
+   latest page snapshot, never a guessed selector. Watch what actually happens.
 2. **Write it as an ActionPlan** — a JSON object whose \`steps\` are
-   \`{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
+   \`{action, selector, url, value, ...}\`. Two structural rules:
+   - the **first executed step is a \`goto\`**, 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.
+   \`https://app.example.com/pricing\`. The origin comes from the environment's root
+   URL, so one plan runs against prod, staging and a preview; bake the origin in and
+   \`--env\` is silently ignored. Absolute URLs stay legal for OTHER origins (an OAuth
+   handoff, a magic link on another domain).
+   Optional \`before\` / \`after\` arrays hold setup and teardown; \`after\` runs even
+   when a main step fails, so a create flow can clean up its record — and a deletion
+   flow creates its own record in \`before\` first.
+
+   The full action vocabulary:
+
+${indent(actionTable())}
+
+   The routinely mis-written ones — exact semantics:
+   - \`upload\`'s \`value\` names a file in the project's CONFIG-FILE store
+     (\`config files upload\`), never a filesystem path.
+   - \`dialog\` arms a one-shot accept/dismiss handler for the dialog the NEXT step
+     triggers (armed before the click, or Playwright auto-dismisses it). No selector;
+     optional \`dialog_expect_text\` asserts the dialog's message.
+   - \`switch_tab\` / \`close_tab\`: \`value\` is a 0-based tab index OR a URL substring.
+   - \`scroll\` with no selector scrolls the PAGE — \`value\` is \`bottom\`, \`top\`,
+     \`up\`, \`down\`, or a signed pixel count; default one viewport down. With a
+     selector it scrolls that element into view.
+
+   Any element action can reach inside an iframe (Stripe/Adyen card fields) via the
+   \`iframe\` field — a URL-substring match on the frame's \`src\`; ignored by
+   page-level verbs.
 
    An \`expect\` step's shape is \`{action: "expect", expect_kind, selector, expect_text}\`:
-   - \`expect_kind\` (required) is one of \`visible\`, \`attached\`, \`hidden\`, \`checked\`,
-     \`enabled\`, \`disabled\`, \`have_text\`, \`have_value\`, \`have_url\`, \`have_title\`,
-     \`have_count\`, \`persisted\`, \`gone\`, \`count_delta\`.
-   - \`selector\` is required for every kind except the page-level \`have_url\` /
-     \`have_title\` (those assert on the page, not an element).
-   - \`expect_text\` carries the expected string for \`have_text\` / \`have_value\` (exact
-     match on the element) and \`have_url\` / \`have_title\` (substring match on the page).
-     There is no \`value\` field on an expect and no bare \`text\` / \`url\` kind.
-   - Two kinds take other fields instead: \`have_count\` needs \`expect_count\`, and
-     \`count_delta\` needs \`capture_ref\` + \`expect_delta\` (vs a baseline banked by an
-     earlier \`capture_count\` step).
+
+${indent(expectTable())}
+
+   - \`expect_text\` is an exact match on the element for \`have_text\` / \`have_value\`,
+     a substring match on the page for \`have_url\` / \`have_title\` (page-level kinds
+     take no selector). There is no \`value\` field on an expect and no bare \`text\` /
+     \`url\` kind.
+   - \`have_count\` needs \`expect_count\`; \`count_delta\` needs \`capture_ref\` +
+     \`expect_delta\` (vs a baseline banked by an earlier \`capture_count\` step).
 
    A fully valid minimal plan ("the pricing page renders"):
 
@@ -278,89 +283,79 @@ ${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\` 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
+   \`create\` banks the plan only on a green local replay; a red one hands back the
+   failure — fix and re-run. Replay mechanics (where it runs over MCP, \`--no-sync\`,
+   \`--no-verify\`, the cloud-session exception) are in \`tests create\`'s own
+   description. Inspect the exact spec with \`beryl tests script --file plan.json\`.
+   Full ActionPlan JSON Schema:
    https://api.beryl.so/api/v1/schemas/action-plan.schema.json.
 
 ### The outcome assertion is the whole game
 
 A flow is only worth banking if you can point at the **success signal** — the one
-observable proof the flow worked. Get this right and everything else follows.
-
-- The signal must be **true only if the flow succeeded**. A confirmation message that
-  appeared, an element that showed up or disappeared, content unique to where the flow
-  landed.
-- **Never assert global chrome** — the nav bar, logo, footer, or cookie banner is on every
-  page, so asserting it tests nothing. "Was there anyway" means site-wide chrome, NOT the
-  destination's own distinctive content.
+observable proof the flow worked.
+
+- The signal must be **true only if the flow succeeded**: a confirmation that appeared,
+  an element that showed up or disappeared, content unique to where the flow landed.
+- **Never assert global chrome** — nav bar, logo, footer, cookie banner are on every
+  page, so asserting them tests nothing. "Was there anyway" means site-wide chrome, NOT
+  the destination's own distinctive content.
 - For a **navigation** flow, the strongest signal is that the destination actually
-  **rendered**: assert its unique heading or a piece of content specific to that page (for
-  \`/pricing\`, the "Pricing" H1 or a plan name). Prefer that over the URL alone — a bare
-  "the URL is /pricing" passes even on a blank or broken page that never rendered.
-  Reserve a URL-only assertion for when the URL *is* the outcome (a form that lands on
-  \`/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). §2 has the full
-  \`expect_kind\` list and the step shape.
+  **rendered**: its unique heading or page-specific content (for \`/pricing\`, the
+  "Pricing" H1 or a plan name). A bare "the URL is /pricing" passes even on a blank,
+  broken page — reserve URL-only assertions for when the URL *is* the outcome (a form
+  landing on \`/thank-you\`) and no distinctive content exists.
+- 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 — a spinner, the item you just deleted).
 - **\`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
-  nav chrome. Target the specific element that carries the text (the \`h1\`, the toast),
-  or assert the page instead (\`have_title\`, which is a substring match). To check "this
-  string is visible somewhere", use \`expect_kind: "visible"\` with a \`text=…\` selector.
-- **If you can't name a success signal, the flow is not test-worthy.** Don't bank a test
-  that verifies nothing. Explore a different flow instead.
-- **Don't work around a real app failure to make a test go green.** If the flow is
-  genuinely broken in the app, that's a finding to report — not something to paper over
-  with a weaker assertion.
+  \`have_text: "Documentation"\` on \`body\` fails because \`body\` includes all the nav
+  chrome. Target the element that carries the text (the \`h1\`, the toast), assert the
+  page with \`have_title\` (substring), or check "this string is visible somewhere"
+  with \`expect_kind: "visible"\` + a \`text=…\` selector.
+- **If you can't name a success signal, the flow is not test-worthy.** Don't bank a
+  test that verifies nothing; explore a different flow.
+- **Don't work around a real app failure to make a test go green.** A genuinely broken
+  flow is a finding to report, not something to paper over with a weaker assertion.
 
 ### 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.
+   profile. Author while signed in and you never see the gate — you will mark gated
+   pages as public. **Log out first**, then confirm the gated page really redirects 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 a returning address skips. A stored login plan must
+   be the **returning** path — drive it twice: once to create, once to sign 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.
+   buttons can share a label ("Continue" / "Continue with Google"), and Beryl relaxes
+   \`text=X\` to a case-insensitive SUBSTRING — \`text=Continue\` is ambiguous. Use
+   something unique (\`button[type=submit]\`, \`input[name=email]\`,
+   \`input[autocomplete=one-time-code]\`).
+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 is discarded on re-render. 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']\`) — the plan is about the app, not 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 — a section heading, a
+   permanent explainer, an always-present control.
 
 ## 3. Writing the natural-language intent
 
-Pass the intent as \`--description\` on \`beryl tests create\` (or \`tests set-plan\` when you
-re-author). 1–3 sentences. This is the immutable anchor from §6 — write it well.
+Pass the intent as \`--description\` on \`beryl tests create\` (or \`tests set-plan\`
+when you re-author). 1–3 sentences. This is the immutable anchor from §6.
 
 - **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 §2, in words.
-- **Never describe global chrome.** The intent is about the flow's destination and
-  outcome, not "the header is present".
+  clicks submit" — the trajectory 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 — §2's
+  success signal, in words.
+- **Never describe global chrome.**
 
 Good:
 > "Proves a returning user can sign in: after submitting valid credentials, the
@@ -371,79 +366,63 @@ Weak (describes steps + asserts nothing meaningful):
 
 ## 4. The local run-fix loop
 
-Iterate on your machine before you rely on the cloud. \`beryl runs local\` fetches the
-test's rendered spec and runs it with your local \`@playwright/test\` — no cloud, no waiting
-for a scheduled run.
+Iterate on your machine before you rely on the cloud. \`beryl runs local\` runs banked
+tests with your local \`@playwright/test\` — no cloud, no waiting for a scheduled run.
 
 \`\`\`
-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\` 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 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.
+The loop: draft → \`tests lint\` → \`tests create\` → \`runs local --no-sync\` while
+iterating (a synced run lands in the project's run history) → read \`--dir\`'s
+\`report.json\` to see which step or assertion failed and why → fix the plan →
+\`tests set-plan\` → run again. Flag semantics, session-mode behavior, \`await_email\`
+and authenticated-test handling, and exit codes are in \`runs local\`'s own description.
+
+Once the test passes locally against a real outcome, it's ready to bank and let Beryl
+run 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. No setup, no environment configuration, no
+A flow that emails the user — a signup verification code, a magic sign-in link, a
+receipt — is testable with the \`await_email\` action. No setup, no 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:
+**The project has one permanent mailbox and all of its mail arrives there.** Two
+handles put an address on the page; 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.
+An alias is a real address the site has never issued, so a signup is repeatable run
+after run; the mail lands in the same mailbox and Beryl reads only the alias's own
+mail. Nothing expires; 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, an invite accepted as a second person.
 
 The wiring is a three-part chain:
 
-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).
+1. **Type the address into the app** — a \`fill\` with \`value: "{{inbox_address}}"\`
+   (or \`{{mailbox_address}}\`). The alias is fresh every run, so a signup is
+   repeatable by construction — no \`{{unique}}\` needed for the email itself; use it
+   for other must-not-collide values like a username. The generator handles
+   \`{{unique}}\`, \`{{uuid}}\`, \`{{timestamp}}\` are each minted once per execution;
+   \`{{timestamp}}\` is second-resolution (a time, NOT a uniqueness guarantee —
+   \`{{unique}}\` is).
 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).
+   - \`extract\` (required): ${extractLine()}.
    - \`capture_as\` (required): the handle name the extracted string is banked under.
-   - \`subject_contains\` / \`from_contains\` (optional): match the right mail when the app
-     sends more than one.
-   - \`wait_s\` (optional, 1–50, default 30): how many seconds the step blocks waiting
-     for the mail to land.
-3. **Use the banked value** — cite \`{{<capture_as>}}\` in a later step's \`value\` (fill the
-   code) or \`url\` (goto the magic link). A captured handle is legal **only** in
-   \`value\`/\`url\`; in a \`selector\`, \`option\`, or \`expect_text\` it would be used as
-   literal text, and the linter rejects it there.
+   - \`subject_contains\` / \`from_contains\` (optional): match the right mail when the
+     app sends more than one.
+   - \`wait_s\` (optional, 1–50, default 30): seconds to block waiting for the mail.
+3. **Use the banked value** — cite \`{{<capture_as>}}\` in a later step's \`value\`
+   (fill the code) or \`url\` (goto the magic link). A captured handle is legal
+   **only** in \`value\`/\`url\`; in a \`selector\`, \`option\`, or \`expect_text\` it
+   would be literal text, and the linter rejects it there.
 
 A fully valid signup-with-OTP plan:
 
@@ -457,34 +436,32 @@ 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 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".
+- \`beryl tests create\` verifies an \`await_email\` plan like any other: the local
+  replay receives at the project mailbox and answers each step over the API, so the
+  app's mail really is received and extracted before the test is accepted. The replay
+  signs up / sends mail FOR REAL — pass \`--no-verify\` only if that side effect is
+  unwanted. \`beryl runs local\` serves \`await_email\` the same way, so the local loop
+  covers OTP/signup flows end to end.
+- §2's outcome discipline still applies: the green signal is the post-verification
+  state (the welcome screen, the dashboard), not "an email arrived".
 
 ## 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.
+Beryl's cloud runs your test on a schedule. When markup drifts and a selector stops
+matching, a heal-vs-fail agent decides whether to **heal** (silently re-derive the
+selector/trajectory, stay green) or **fail** (surface a real regression) — judged
+against your test's **intent**:
+
+- **The intent is the immutable anchor; Beryl never rewrites it.** It states what the
+  test proves — what every future run is judged against.
+- **Selectors and the trajectory are the healable "how"** — a moved button, a renamed
+  class, an extra click. Beryl re-derives those because your intent says what the flow
+  is *for*.
+- **A failed outcome assertion is a real regression Beryl will NOT heal green.** If the
+  success signal stops holding, the app broke, and the test fails loudly. That is the
+  point.
+
+So a test is *healable* exactly when it has **a strong intent + a real outcome
+assertion**. With a vague intent and a chrome-only assertion Beryl can't tell
+regression from cosmetic drift — it either heals over real breakage or fails on noise.
 `;