@beryl-so/cli 0.24.0 → 0.24.1

package/dist/adapters/mcp.js

@@ -6,6 +6,7 @@ import { loadConfig } from "../config.js";
 import { createContext } from "../context.js";
 import { CliError } from "../errors.js";
 import { ApiClient } from "../http.js";
+import { parseArgv } from "./cli.js";
 import { commands } from "../registry/index.js";
 import { cliVersion, warnIfStale } from "../version-check.js";
 export function toolName(spec) {
@@ -31,15 +32,103 @@ export function toolInputSchema(spec) {
             required.push(a.name);
     }
     for (const f of spec.flags ?? []) {
+        const withDefault = f.default !== undefined ? { default: f.default } : {};
         properties[f.name] =
             f.type === "strings"
-                ? { type: "array", items: { type: "string" }, description: f.description }
-                : { type: f.type, description: f.description, ...(f.enum ? { enum: f.enum } : {}) };
+                ? { type: "array", items: { type: "string" }, description: f.description, ...withDefault }
+                : {
+                    type: f.type,
+                    description: f.description,
+                    ...(f.enum ? { enum: f.enum } : {}),
+                    ...withDefault,
+                };
         if (f.required)
             required.push(f.name);
     }
     return { type: "object", properties, ...(required.length ? { required } : {}) };
 }
+function shellTokens(text) {
+    const tokens = [];
+    let current = "";
+    let quote = null;
+    let pending = false;
+    for (const ch of text) {
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            else
+                current += ch;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            pending = true;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (pending || current)
+                tokens.push(current);
+            current = "";
+            pending = false;
+            continue;
+        }
+        if (">|;#&".includes(ch))
+            return null;
+        current += ch;
+        pending = true;
+    }
+    if (quote)
+        return null;
+    if (pending || current)
+        tokens.push(current);
+    return tokens;
+}
+/** A CLI example translated to the JSON args the MCP tool takes, or null when it doesn't
+ *  translate cleanly (shell syntax, another command's example, nothing beyond defaults) —
+ *  agents must see tool args as JSON, never `--flag` syntax. */
+export function exampleArgs(spec, example) {
+    const prefix = `beryl ${spec.name}`;
+    if (example !== prefix && !example.startsWith(`${prefix} `))
+        return null;
+    const tokens = shellTokens(example.slice(prefix.length));
+    if (!tokens)
+        return null;
+    let parsed;
+    try {
+        parsed = parseArgv(spec, tokens);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.help)
+        return null;
+    const byName = new Map((spec.flags ?? []).map((f) => [f.name, f]));
+    const out = {};
+    for (const [name, value] of Object.entries(parsed.input.args)) {
+        if (value === undefined || (Array.isArray(value) && value.length === 0))
+            continue;
+        out[name] = value;
+    }
+    for (const [name, value] of Object.entries(parsed.input.flags)) {
+        const f = byName.get(name);
+        // parseArgv fills declared defaults in; only what the example explicitly set teaches.
+        if (value === undefined || value === f?.default)
+            continue;
+        out[name] =
+            f?.type === "number" && typeof value === "string" && Number.isFinite(Number(value))
+                ? Number(value)
+                : value;
+    }
+    return Object.keys(out).length ? out : null;
+}
+export function toolDescription(spec) {
+    const base = spec.description ? `${spec.summary}. ${spec.description}` : spec.summary;
+    const lines = (spec.examples ?? [])
+        .map((e) => exampleArgs(spec, e))
+        .filter((a) => a !== null)
+        .map((a) => `Example: ${JSON.stringify(a)}`);
+    return lines.length ? `${base}\n${lines.join("\n")}` : base;
+}
 export function toolResult(result, lines) {
     const parts = [...lines];
     if (result.data !== undefined)
@@ -102,29 +191,36 @@ export function currentAuth(fallback) {
 export function __resetAuthCacheForTests() {
     authCache = undefined;
 }
+// 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.
+export function mcpInstructions() {
+    const version = cliVersion();
+    return (`Beryl CLI v${version} (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. " +
+        "The full authoring guide (plan shape, outcome assertions, email/OTP wiring, " +
+        "run-fix loop) ships as both the beryl-test skill and the `guide` tool — same " +
+        `content. If a beryl-test skill stating v${version} is already loaded, do not ` +
+        "call `guide`; if no beryl-test skill is available or it states another version, " +
+        "call `guide` before authoring your first test plan.");
+}
 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: {} },
-        // 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).",
+        instructions: mcpInstructions(),
     });
     server.setRequestHandler(ListToolsRequestSchema, () => ({
         tools: mcpTools().map((spec) => ({
             name: toolName(spec),
-            description: spec.description ? `${spec.summary}. ${spec.description}` : spec.summary,
+            description: toolDescription(spec),
             inputSchema: toolInputSchema(spec),
         })),
     }));

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.
 `;

package/dist/commands/accounts.js

@@ -172,9 +172,10 @@ export const testAccountCommands = [
             "--probe is the liveness check: a two-step plan (goto a gated page, then a POSITIVE " +
             "assertion that only holds when signed in — the account menu, a 'Sign out' control). " +
             "It is replayed in a fresh browser carrying only the captured session. It is " +
-            "REQUIRED, and not a formality: assertions like `hidden` and `count 0` all pass " +
-            "against a logged-out page, so without a positive signal a dead session would run " +
-            "every test logged-out and still report the run green.\n\n" +
+            "REQUIRED, and not a formality: assertions like `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 would run every test logged-out and still report the run " +
+            "green.\n\n" +
             "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
         scope: "project",
         args: [
@@ -264,8 +265,10 @@ export const testAccountCommands = [
             "itself did not complete (fix the plan); SESSION_PROOF_FAILED means the sign-in " +
             "worked but the session did not survive the move to a fresh browser, so this app " +
             "keeps its credential somewhere that cannot be carried (a service worker, a " +
-            "WebAuthn binding). In that case the account is marked unsupported and its tests " +
-            "keep signing in inline — degraded, not broken.\n\n" +
+            "WebAuthn binding). In that case the account is marked unsupported: its " +
+            "session-mode tests fail at setup with SESSION_UNSUPPORTED on every run until " +
+            "re-authored with auth_mode \"inline\" and their own sign-in steps; inline tests " +
+            "are unaffected.\n\n" +
             "Blocks for two browser replays.",
         scope: "project",
         args: [{ name: "account-id", description: "Account id", required: true }],

package/dist/commands/config-vars.js

@@ -57,6 +57,9 @@ export const configCommands = [
     {
         name: "config vars get",
         summary: "Show one config variable",
+        description: "Returns the variable row with its value in plaintext (variables are not secret) — " +
+            "a sensitive value lives in `config secrets`, readable only via `config secrets " +
+            "get --reveal`.",
         scope: "project",
         args: [{ name: "key", description: "Variable key or id", required: true }],
         async run(ctx, input) {
@@ -113,6 +116,8 @@ export const configCommands = [
     {
         name: "config secrets get",
         summary: "Show one secret's metadata, or reveal its value with --reveal",
+        description: "Returns metadata only by default; --reveal is a logged, member-gated decrypt — " +
+            "unlike `config vars get`, which returns its value in plaintext.",
         scope: "project",
         args: [{ name: "key", description: "Secret key or id", required: true }],
         flags: [

package/dist/commands/init.js

@@ -285,8 +285,8 @@ export const initCommands = [
         description: "The full guide to authoring durable, healable tests: the ActionPlan shape, outcome " +
             "assertions, natural-language intent, test accounts and the project mailbox " +
             "({{login_email}}, {{mailbox_address}}, {{inbox_address}} + await_email), and the " +
-            "local run-fix loop. The same content `beryl init` installs as the beryl-test " +
-            "skill — call this before authoring your first plan when no skill is installed " +
+            "local run-fix loop. Same content as the beryl-test skill `beryl init` installs — " +
+            `skip if a loaded beryl-test skill states v${cliVersion()}; else call this first ` +
             "(works without logging in).",
         examples: ["beryl guide"],
         async run() {

package/dist/commands/mailboxes.js

@@ -91,7 +91,9 @@ export const mailboxCommands = [
             "the server caps the wait at 50s — re-run to keep waiting). With --extract-code, " +
             "also pulls the one-time code (4-8 digits) out of the body/subject. Use " +
             "--recipient-contains to read only one `+tag` alias's mail when several identities " +
-            "share the mailbox. Exits non-zero if nothing arrives before the timeout.",
+            "share the mailbox. Exits non-zero if nothing arrives before the timeout. Waits for " +
+            "and returns ONE latest matching email — `mailbox emails` lists what has already " +
+            "arrived, without waiting.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [
@@ -139,6 +141,8 @@ export const mailboxCommands = [
     {
         name: "mailbox emails",
         summary: "List the emails a mailbox has received",
+        description: "Returns the already-received emails without waiting — `mailbox read` blocks for " +
+            "a matching one and returns just it.",
         scope: "project",
         args: [{ name: "mailbox-id", description: "Mailbox id from `beryl mailbox list`", required: true }],
         flags: [

package/dist/commands/runs.js

@@ -102,17 +102,19 @@ export const runCommands = [
             "says so once instead of failing every test (on a terminal the CLI offers to install " +
             "whichever half is missing; over MCP it prints the exact install commands). " +
             "Signup/OTP flows work: the CLI answers the spec's await_email steps over the API " +
-            "against the same mailbox the cloud runner uses. Authenticated tests work too: a plan " +
-            "that signs itself in with {{login_email}}/{{login_password}} has its password fetched " +
+            "against the same mailbox the cloud runner uses. Authenticated tests work too: for a plan " +
+            "that signs itself in with {{login_email}}/{{login_password}}, the email is baked into " +
+            "the fetched spec and the password is fetched " +
             "once over the logged secret-reveal route, handed to the spec the way the cloud runner " +
-            "does, and scrubbed from any error text or DOM snapshot before results upload. When the " +
+            "does, and scrubbed from any error text or DOM snapshot before results upload; a test " +
+            "whose account has no stored password is skipped with the exact fix-it command. When the " +
             "run finishes, the results and replay artifacts are imported into Beryl as a normal run " +
             "(trigger source `local`) — history, replay, and reports all work; pass --no-sync to " +
             "keep a run entirely off the record while iterating. Session-mode tests behave as " +
             "in the cloud: their account signs in once per invocation and every session-mode " +
             "test rides that session; a failed sign-in fails those tests with the same " +
             "SESSION_* reason a cloud run reports. Only a test that depends on a session Beryl " +
-            "captured server-side is skipped, with a note. Point " +
+            "captured server-side is skipped, with a note — run those with `runs trigger`. Point " +
             "--url-override at a local dev server or preview, and --dir to keep specs, artifacts, " +
             "and reports on disk. Exits 0 only if every executed test passed.",
         scope: "project",
@@ -134,7 +136,12 @@ export const runCommands = [
                 type: "string",
                 description: "Run against this base URL instead of the environment's (e.g. http://localhost:3000)",
             },
-            { name: "env", type: "string", description: "Environment id to attach the imported run to" },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to run against and attach the imported run to — use for a " +
+                    "standing environment; --url-override is for a throwaway host",
+            },
             {
                 name: "sync",
                 type: "boolean",
@@ -464,7 +471,9 @@ export const runCommands = [
         summary: "Show one run with its per-test results",
         description: "Over MCP the failure screenshots come back as viewable image content, so an agent can " +
             "look at the page that broke instead of guessing from the error string. Set screenshots " +
-            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image.",
+            "to false to skip fetching them. Ignored outside MCP — the terminal cannot show an image. " +
+            "Returns the run row with its per-test results — `runs report` returns the generated " +
+            "report document, `runs explain` an AI explanation of one failed result.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         flags: [
@@ -516,6 +525,8 @@ export const runCommands = [
     {
         name: "runs report",
         summary: "Show the generated report for a run",
+        description: "Returns the run's stored generated report (404 until it has been generated) — " +
+            "`runs get` returns the raw run row with per-test results.",
         scope: "project",
         args: [{ name: "run-id", description: "Run id", required: true }],
         async run(ctx, input) {
@@ -595,6 +606,8 @@ export const runCommands = [
     {
         name: "runs explain",
         summary: "Explain, with AI, why a test result failed",
+        description: "Takes a single test-RESULT id (not a run id) and returns an AI failure " +
+            "explanation for that result — `runs get` lists a run's results and their ids.",
         scope: "project",
         args: [{ name: "result-id", description: "Test result id (from `beryl runs get`)", required: true }],
         async run(ctx, input) {

package/dist/commands/tests.js

@@ -128,6 +128,9 @@ export const testCommands = [
     {
         name: "tests get",
         summary: "Show one test",
+        description: "Returns the test's metadata row (status, flags, per-environment last result), not " +
+            "the plan — `tests plan` prints the stored JSON plan, `tests script` the rendered " +
+            "Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -138,6 +141,8 @@ export const testCommands = [
     {
         name: "tests plan",
         summary: "Print a test's current step plan (JSON)",
+        description: "Returns the stored json_plan of the test's current version — `tests get` returns " +
+            "the metadata row, `tests script` the rendered Playwright spec.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -164,11 +169,16 @@ export const testCommands = [
             "image content), you fix the plan file and re-run. The proving run is imported as the " +
             "test's first run (--no-sync to skip). A plan that signs in with a session Beryl captured " +
             "server-side cannot replay locally (that session never leaves Beryl's cloud) — it falls " +
-            "back to server-side verification automatically. A session-mode plan replays locally " +
+            "back to server-side verification automatically, and says so. A session-mode plan replays locally " +
             "fine: the server renders it with its account's stored sign-in steps in front, so " +
             "the same identity is exercised on your machine. Optional `before` and `after` arrays hold setup and teardown " +
             "steps: `after` runs even when a main step fails, which is how a create/update/delete test " +
-            "cleans up the record it made on the runs that go red.",
+            "cleans up the record it made on the runs that go red. " +
+            "Recovery: a 409 `duplicate_title` carries existing_test_id + existing_plan_hash — " +
+            "reconcile with that test (`tests get` / `tests set-plan`), don't rename-and-retry; a " +
+            "409 `plan_hash_mismatch` means the submitted plan is not the bytes that were replayed " +
+            "— re-run `tests create`; a 429 with Retry-After 30 means the verify slots are " +
+            "saturated — wait and retry.",
         scope: "project",
         flags: [
             { name: "title", type: "string", required: true, description: "Title for the new test" },
@@ -421,7 +431,9 @@ export const testCommands = [
         description: "Accepts the same plan shape as `tests create`, including the optional `before` and " +
             "`after` sections — `after` runs on pass and on fail, so cleanup happens even when the " +
             "test goes red. Pass `--description` when the re-authored plan changes what the test " +
-            "proves; omit it to keep the test's existing intent.",
+            "proves; omit it to keep the test's existing intent. Saves the edit with NO replay — " +
+            "it rides into the next run unproven; `tests recompile` is the verify-first " +
+            "alternative.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -464,9 +476,12 @@ export const testCommands = [
         name: "tests quarantine",
         summary: "Mute a flaky test: it keeps running, but its failures stop failing the run",
         description: "A quarantined test still executes and its result is still recorded and visible — its " +
-            "red just doesn't count towards the run's verdict, so it can't red-light a deploy. Use " +
+            "red lands in the run's quarantined_count and gates neither the run's verdict nor exit " +
+            "codes, so it can't red-light a deploy. Use " +
             "it on a persistently flaky test instead of deleting it (which destroys the history) or " +
-            "asking support to deactivate it (which stops it running at all). `off` un-quarantines.",
+            "asking support to deactivate it (which stops it running at all). After 5 consecutive " +
+            "clean passes the test reports rehab_ready — advisory only, nothing un-quarantines " +
+            "itself. `off` un-quarantines.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -501,6 +516,13 @@ export const testCommands = [
     {
         name: "tests recompile",
         summary: "Validate + verify an edited plan against the live site before persisting",
+        description: "Unlike `tests set-plan` (which saves the edit and lets it ride into the next run), " +
+            "this replays the edited plan against the live site before anything persists. A " +
+            "deterministic replay failure (verdict `drop`) REJECTS the edit — persisted:false, " +
+            "the prior plan stays live — and returns the failure evidence (over MCP the " +
+            "screenshot is image content). Verdict `flag` (the runner errored, no verdict on " +
+            "the flow) persists the plan but reports it unverified. Returns 429 with " +
+            "Retry-After 30 when the 2 inline-verify slots are saturated — wait and retry.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         flags: [
@@ -569,6 +591,9 @@ export const testCommands = [
     {
         name: "tests restore",
         summary: "Restore a test to an earlier version",
+        description: "Copies the named older version's plan forward as a NEW head version — unlike " +
+            "`tests reset`, which flips authored_by back to `system` and leaves the plan " +
+            "untouched.",
         scope: "project",
         args: [
             { name: "test-id", description: "Test id", required: true },
@@ -584,6 +609,9 @@ export const testCommands = [
     {
         name: "tests reset",
         summary: "Discard user edits and return the test to its latest system-authored version",
+        description: "Flips authored_by back to `system` WITHOUT changing the plan (the next " +
+            "regeneration overwrites it) — unlike `tests restore`, which copies an older " +
+            "version's plan forward as a new version.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id", required: true }],
         async run(ctx, input) {
@@ -632,7 +660,9 @@ export const testCommands = [
         summary: "Print the rendered Playwright spec for a test (or an unbanked plan file)",
         description: "With a test id, fetches the banked test's rendered .spec.ts. With --file, compiles a " +
             "plan JSON that has NOT been banked yet — the same render `tests create` proves locally — " +
-            "so you can inspect exactly what would run before creating anything.",
+            "so you can inspect exactly what would run before creating anything. This returns the " +
+            "executable spec — `tests plan` returns the stored JSON plan it is rendered from, " +
+            "`tests get` the metadata row.",
         scope: "project",
         args: [{ name: "test-id", description: "Test id (omit when passing --file)" }],
         flags: [

package/dist/skill-tables.js

@@ -0,0 +1,74 @@
+// Table rows derive from the schema snapshot at module load, so the skill can never
+// drift from the plan language; only the one-liners are hand-written, and parity
+// tests fail when a schema enum gains or loses a member the docs don't cover.
+import { ACTION_PLAN_SCHEMA } from "./schema.generated.js";
+const defs = ACTION_PLAN_SCHEMA.$defs;
+export const ACTION_TYPES = defs.ActionType.enum;
+export const EXPECT_KINDS = defs.ExpectKind.enum;
+export const EMAIL_EXTRACTS = defs.EmailExtract.enum;
+function actionRequires(action) {
+    const rule = defs.PlanStep.allOf.find((r) => r.if.properties.action?.const === action && !r.if.properties.extract);
+    return rule?.then.required ?? [];
+}
+function expectRequires(kind) {
+    const rule = defs.PlanStep.allOf.find((r) => r.if.properties.expect_kind?.const === kind);
+    return rule?.then.required ?? [];
+}
+export const ACTION_DOCS = {
+    goto: "Navigate to `url` — a path on your app, absolute only for another origin",
+    fill: "Type `value` into the `selector` element",
+    click: "Click the `selector` element",
+    press: "Press keyboard `key` (e.g. `Enter`) on the `selector` element",
+    check: "Check the `selector` checkbox",
+    uncheck: "Uncheck the `selector` checkbox",
+    select: "Choose `option` in the `selector` dropdown",
+    hover: "Hover the `selector` element",
+    scroll: "Scroll the page (no selector) or bring `selector` into view — see below",
+    wait_for: "Wait for the `selector` element to appear",
+    expect: "Assert — kinds in the expect table below",
+    capture_count: "Bank the live count of `selector` matches under `capture_as` for a later `count_delta`",
+    await_email: "Await mail in the run inbox, bank the extracted value under `capture_as` (§5)",
+    upload: "Set a file input: `value` names a project config file — see below",
+    dialog: "Arm a one-shot accept/dismiss handler for the NEXT step's dialog — see below",
+    switch_tab: "Make another open tab the active page; `value` picks it — see below",
+    close_tab: "Close the active tab (optional `value` picks one) and fall back to the previous",
+    drag: "Drag the `selector` element onto the `value` TARGET selector",
+};
+export const EXPECT_DOCS = {
+    visible: "The element is visible",
+    attached: "In the DOM, maybe not shown — for carousel/slider content where `visible` is timing-flaky",
+    hidden: "The element is not visible",
+    checked: "The checkbox/radio is checked",
+    enabled: "The element is enabled",
+    disabled: "The element is disabled",
+    have_text: "The element's text EXACTLY equals `expect_text`",
+    have_value: "The input's value equals `expect_text`",
+    have_url: "The page URL contains `expect_text` (page-level, no selector)",
+    have_title: "The page title contains `expect_text` (page-level, no selector)",
+    have_count: "Exactly `expect_count` elements match `selector`",
+    persisted: "The record just created is present — a visible match for the `{{unique}}`-named row",
+    gone: "Zero matches — absent from the DOM, stronger than `hidden`",
+    count_delta: "The match count moved by signed `expect_delta` vs the `capture_ref` baseline",
+};
+export const EXTRACT_DOCS = {
+    code: "the one-time code",
+    link: "the sign-in/verify URL",
+    pattern: "your own regex in `extract_pattern`, exactly one capture group",
+};
+function table(header, rows) {
+    return [
+        `| ${header} | required fields | meaning |`,
+        "|---|---|---|",
+        ...rows.map(([name, req, doc]) => `| \`${name}\` | ${req} | ${doc} |`),
+    ].join("\n");
+}
+const fields = (names) => names.map((f) => `\`${f}\``).join(", ") || "—";
+export function actionTable() {
+    return table("action", ACTION_TYPES.map((a) => [a, fields(actionRequires(a)), ACTION_DOCS[a] ?? ""]));
+}
+export function expectTable() {
+    return table("expect_kind", EXPECT_KINDS.map((k) => [k, fields(expectRequires(k)), EXPECT_DOCS[k] ?? ""]));
+}
+export function extractLine() {
+    return EMAIL_EXTRACTS.map((e) => `\`${e}\` (${EXTRACT_DOCS[e] ?? ""})`).join(", ");
+}

package/package.json

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