@beryl-so/cli 0.64.0 → 0.73.2

package/dist/commands/accounts.js

@@ -26,7 +26,7 @@ function accountTable(rows) {
     return table(rows.map((a) => ({
         label: a.identity_label + (a.is_default ? " *" : ""),
         email: a.email,
-        type: a.type,
+        type: a.type + (a.lifetime ? ` (${a.lifetime})` : ""),
         login: a.login_method,
         status: a.status,
         id: a.id,
@@ -51,21 +51,40 @@ export const testAccountCommands = [
             if (rows.length === 0)
                 return {
                     data: rows,
-                    human: dim("No test accounts. Authenticated tests fall back to the LOGIN_EMAIL variable " +
-                        "and LOGIN_PASSWORD secret. A flow that must sign up fresh cites " +
-                        "{{inbox_address}} and deletes the account in `after`."),
+                    human: dim("No test accounts, so {{login_email}} and {{login_password}} have nothing to " +
+                        "resolve to. Add one with `beryl accounts create`. A flow that must sign up " +
+                        "fresh cites {{inbox_address}} and deletes the account in `after`."),
                 };
             return { data: rows, human: accountTable(rows) };
         },
     },
+    {
+        name: "accounts get",
+        summary: "Show one test account: origin, lifetime, sign-in state",
+        description: "One test account by id. `type` is its origin: captured (a session from the Chrome " +
+            "plugin), provisioned (Beryl signed it up; `lifetime` permanent or throwaway), or " +
+            "provided (your own account).",
+        scope: "project",
+        args: [{ name: "account-id", description: "Account id from `beryl accounts list`", required: true }],
+        examples: ["beryl accounts get acc_123"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const account = (await ctx.client.get(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}`));
+            return { data: account, human: accountTable([account]) };
+        },
+    },
     {
         name: "accounts create",
         summary: "Add a test account: the customer's own, or one Beryl signs up",
-        description: "Two kinds. `--type user_provided` records a dedicated account you already have on " +
-            "the site: pass --email and --password, and it is usable immediately. `--type beryl` " +
-            "reserves one Beryl will sign up itself, addressed at the project mailbox. It starts " +
-            "`pending` and becomes usable after `beryl accounts signup`. " +
-            "Works for Google-only apps too: bank a dedicated Google test account as user_provided " +
+        description: "Two kinds. `--type provided` records a dedicated account you already have on " +
+            "the site: pass --email and --password, and it is usable immediately. " +
+            "`--type provisioned` reserves one Beryl will sign up itself, addressed at the project " +
+            "mailbox; `--lifetime` says whether it is kept (permanent, the default) or a " +
+            "throwaway. It starts `pending` and becomes usable after `beryl accounts signup`. " +
+            "A captured account (a signed-in session from the Beryl Chrome extension) is not " +
+            "created here: capture it with the extension, then give it a probe with " +
+            "`beryl accounts set-login --probe`. " +
+            "Works for Google-only apps too: bank a dedicated Google test account as provided " +
             "and author its sign-in plan through Google's form. " +
             "The first account an environment gets is its default whatever you pass.",
         scope: "project",
@@ -73,19 +92,25 @@ export const testAccountCommands = [
             {
                 name: "type",
                 type: "string",
-                enum: ["user_provided", "beryl"],
-                description: "Whose account this is (default: user_provided when --password is given)",
+                enum: ["provided", "provisioned"],
+                description: "Whose account this is (default: provided when --password is given)",
+            },
+            {
+                name: "lifetime",
+                type: "string",
+                enum: ["permanent", "throwaway"],
+                description: "provisioned only: keep it, or a throwaway (default permanent)",
             },
             {
                 name: "label",
                 type: "string",
                 description: "Identity label a plan's auth_label names (default 'default')",
             },
-            { name: "email", type: "string", description: "user_provided only: the account's email" },
+            { name: "email", type: "string", description: "provided only: the account's email" },
             {
                 name: "password",
                 type: "string",
-                description: "user_provided only: stored encrypted as a project secret, never returned",
+                description: "provided only: stored encrypted as a project secret, never returned",
             },
             {
                 name: "login-method",
@@ -98,7 +123,7 @@ export const testAccountCommands = [
         ],
         examples: [
             "beryl accounts create --email qa@acme.test --password 'hunter2'",
-            "beryl accounts create --type beryl --login-method otp",
+            "beryl accounts create --type provisioned --login-method otp",
             "beryl accounts create --email admin@acme.test --password 'hunter2' --label admin",
             "beryl accounts create --email qa@gmail.com --password 'hunter2'  # Google-only app",
         ],
@@ -106,7 +131,8 @@ export const testAccountCommands = [
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const password = flagStr(input, "password");
             const account = (await ctx.client.post(accountsPath(workspaceId, projectId), {
-                type: flagStr(input, "type") ?? (password ? "user_provided" : "beryl"),
+                type: flagStr(input, "type") ?? (password ? "provided" : "provisioned"),
+                lifetime: flagStr(input, "lifetime") ?? null,
                 identity_label: flagStr(input, "label") ?? "default",
                 email: flagStr(input, "email") ?? null,
                 password: password ?? null,
@@ -124,6 +150,54 @@ export const testAccountCommands = [
             };
         },
     },
+    {
+        name: "accounts capture",
+        summary: "Store a signed-in session as a captured test account",
+        description: "Usually done by the Beryl Chrome extension from a signed-in tab; this takes the " +
+            "same session JSON from a file: {schema_version: 2, final_url, cookies (CDP " +
+            "shape), local_storage, session_storage, indexed_db}. Upserts by --label on the " +
+            "environment, so capturing an existing label replaces its session. Cookies for " +
+            "other domains are dropped and listed. A captured account cannot sign itself in: " +
+            "give it a probe with `beryl accounts set-login --probe`, then prove it with " +
+            "`beryl accounts check`. Its session is never served back to a client.",
+        scope: "project",
+        flags: [
+            {
+                name: "file",
+                type: "string",
+                required: true,
+                description: "The captured session, as JSON (path, or - for stdin)",
+            },
+            {
+                name: "label",
+                type: "string",
+                description: "Identity label a plan's auth_label names (default 'default')",
+            },
+            { name: "email", type: "string", description: "The signed-in user's email" },
+            { name: "env", type: "string", description: "Environment id (default: the project's)" },
+            { name: "default", type: "boolean", description: "Make this the environment's default" },
+        ],
+        examples: ["beryl accounts capture --file session.json --label admin"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const account = (await ctx.client.put(`${accountsPath(workspaceId, projectId)}/captured`, {
+                session: readJsonFlag(input, "file"),
+                identity_label: flagStr(input, "label") ?? "default",
+                email: flagStr(input, "email") ?? null,
+                environment_id: flagStr(input, "env") ?? null,
+                is_default: flagBool(input, "default"),
+            }));
+            const ignored = account.ignored_cookie_domains.length
+                ? yellow(`\nDropped cookies for other domains: ${account.ignored_cookie_domains.join(", ")}`)
+                : "";
+            return {
+                data: account,
+                human: `${green("Captured")} ${account.identity_label} (${account.id})${ignored}\n` +
+                    dim(`Next: beryl accounts set-login ${account.id} --probe probe.json, then ` +
+                        `beryl accounts check ${account.id}`),
+            };
+        },
+    },
     {
         name: "accounts signup",
         summary: "Store a test account's signup plan and sign it up on its environment",
@@ -177,6 +251,8 @@ export const testAccountCommands = [
             "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" +
+            "A captured account (from the Beryl Chrome extension) takes --probe alone: it rides " +
+            "the captured session and cannot sign itself in, so there is no --file.\n\n" +
             "Storing only stores. Run `beryl accounts check` to prove it against the live app.",
         scope: "project",
         args: [
@@ -186,8 +262,8 @@ export const testAccountCommands = [
             {
                 name: "file",
                 type: "string",
-                required: true,
-                description: "The sign-in ActionPlan, as JSON (path, or - for stdin)",
+                description: "The sign-in ActionPlan, as JSON (path, or - for stdin). Required except for a " +
+                    "captured account",
             },
             {
                 name: "probe",
@@ -206,12 +282,13 @@ export const testAccountCommands = [
         examples: [
             "beryl accounts set-login acc_123 --file signin.json --probe probe.json",
             "beryl accounts set-login acc_123 --file signin.json --probe probe.json --base-hash 9f2c…",
+            "beryl accounts set-login acc_456 --probe probe.json  # captured account",
         ],
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             try {
                 const account = (await ctx.client.put(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`, {
-                    plan: readJsonFlag(input, "file"),
+                    plan: flagStr(input, "file") ? readJsonFlag(input, "file") : null,
                     probe: readJsonFlag(input, "probe"),
                     base_hash: flagStr(input, "base-hash") ?? null,
                 }));
@@ -240,7 +317,7 @@ export const testAccountCommands = [
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);
             const login = (await ctx.client.get(`${accountsPath(workspaceId, projectId)}/${arg(input, "account-id")}/login`));
-            if (!login.plan)
+            if (!login.plan && !login.probe)
                 return {
                     data: login,
                     human: dim("No login plan stored. Author one by driving the sign-in in a browser, then " +

package/dist/commands/config-vars.js

@@ -86,7 +86,7 @@ export const configCommands = [
     },
     {
         name: "config secrets list",
-        summary: "List the project's secrets (values are never returned)",
+        summary: "List the project's secrets (values are never returned); a test account's password is managed on the account, not here",
         scope: "project",
         async run(ctx, input) {
             const { workspaceId, projectId } = await ctx.requireProject(input);

package/dist/commands/environments.js

@@ -29,6 +29,11 @@ export const environmentCommands = [
     {
         name: "envs get",
         summary: "Show one environment",
+        description: "`site_health_runs_reset_fields` and `site_health_tracker_reset_fields` name stored Site " +
+            "Health settings that were invalid and fell back to defaults (`*` = all of them). " +
+            "Scheduled and CI runs, or ticket filing, auto-close and the digest, stop until they are " +
+            "saved again: `envs update` with any `--health-*` flag rewrites the run settings, any " +
+            "`--tracker-*` flag the tracker settings.",
         scope: "project",
         args: [{ name: "env-id", description: "Environment id", required: true }],
         async run(ctx, input) {

package/dist/commands/health.js

@@ -277,7 +277,9 @@ export const healthCommands = [
             "and on desktop separately (`speeds`, each with its own Core Web Vitals) and takes " +
             "the worse of the two; one that couldn't be measured is left out. A category's `unchecked` lists checks this run " +
             "couldn't determine (e.g. robots.txt timed out): they neither pass nor fail. Pass --report for a single-page check started with " +
-            "`health run --path`.",
+            "`health run --path`. `site_health_runs_reset_fields` and `site_health_tracker_reset_fields` " +
+            "name stored settings that were invalid and fell back to defaults (`*` = all of them): " +
+            "scheduled and CI runs, or ticket filing, stop until they are saved again with `envs update`.",
         scope: "project",
         flags: [
             ENV_FLAG,

package/dist/commands/init.js

@@ -20,8 +20,8 @@ const MCP_SERVER_ENTRY = {
     command: "npx",
     args: ["-y", "@beryl-so/cli@latest", "mcp"],
 };
-// Headless: the coding agent drives this browser to author tests — nobody watches the
-// window, and a headed default breaks on CI / headless boxes. Matches how most devs
+// Headless: the coding agent drives this browser to set up sign-ins and repair plans; nobody
+// watches the window, and a headed default breaks on CI / headless boxes. Matches how most devs
 // already wire their own user-scoped playwright.
 const PLAYWRIGHT_SERVER_ENTRY = {
     command: "npx",
@@ -194,7 +194,7 @@ const outcomeLabel = (o) => o === "installed"
         ? "updated (refreshed to this CLI's version)"
         : "already current";
 const skillLeaf = (root) => path.join(root, BERYL_TEST_SKILL_DIR, BERYL_TEST_SKILL_FILENAME);
-// The authoring skill follows the `--scope` flag, same as the MCP servers: under `user`
+// The beryl-test skill follows the `--scope` flag, same as the MCP servers: under `user`
 // (the default) it lands in the HOME `.agents/skills/` + `.claude/skills/` dirs, so the
 // knowledge travels with the user into every session the user-scoped MCP tools do —
 // otherwise an agent outside this repo has all the tools and none of the guide. Under
@@ -230,8 +230,7 @@ export function refreshInstalledSkills(cwd) {
     }
     return refreshed;
 }
-// Local authoring drives a real browser, and the whole authoring workflow (walk the flow
-// first, then bank the plan) depends on it — so the install is mandatory, not offered:
+// Local runs drive a real browser, so the install is mandatory, not offered:
 // missing means install now, no prompt, no opt-out. The runner ships with the CLI; the
 // browser is the per-machine half, fetched for the runner's own revision. Never throws — a
 // failed install must not fail `init`, which has already done its wiring; it prints the
@@ -253,7 +252,7 @@ async function ensureLocalPlaywright(ctx, cwd) {
     }
     catch (err) {
         ctx.err(`${red("✗")} Playwright install failed: ${err.message}`);
-        ctx.err(`${dim("•")} Finish the install by hand — local runs and browser authoring need it:\n` +
+        ctx.err(`${dim("•")} Finish the install by hand; local runs need it:\n` +
             `    ${cyan(installCommandsFor(gaps, cwd))}`);
     }
 }
@@ -292,7 +291,7 @@ export const initCommands = [
         name: "init",
         summary: "Set up Beryl in this repo: sign in and wire up your coding agent",
         description: "Signs you in, wires the beryl and playwright MCP servers into the coding agent you " +
-            "pick, writes the beryl-test authoring skill, and installs Chromium if it is missing. " +
+            "pick, writes the beryl-test skill, and installs Chromium if it is missing. " +
             "Pick an agent with --claude, --cursor, --vscode and/or --opencode. With no flag it " +
             "prompts (Enter picks Claude); with no flag and no TTY it wires nothing and prints the " +
             "flags. --claude also wires the Claude DESKTOP app when installed, which needs a quit " +
@@ -507,7 +506,7 @@ export const initCommands = [
                 const where = skill.outcome === "updated"
                     ? `${skillWhere} (refreshed to this CLI's version)`
                     : skillWhere;
-                ctx.err(`${green("✓")} Beryl authoring skill ${what} ${dim(where)}`);
+                ctx.err(`${green("✓")} beryl-test skill ${what} ${dim(where)}`);
             }
             await ensureLocalPlaywright(ctx, cwd);
             // Name the agent actually wired, not the raw flag: the picker sets `clients` too.
@@ -519,7 +518,7 @@ export const initCommands = [
                         ? { open: "open VS Code", agent: "Copilot" }
                         : { open: "open opencode", agent: "opencode" };
             const nextSteps = clients.size === 0
-                ? `\n${bold("Beryl is signed in and the authoring skill is installed.")}\n` +
+                ? `\n${bold("Beryl is signed in and the beryl-test skill is installed.")}\n` +
                     `  ${dim("• No MCP server is wired yet, so no agent can reach Beryl.")}\n` +
                     `  ${dim(`• Using ${CLIENT_LABEL_LIST}? Re-run and pick it:`)}\n` +
                     `    ${cyan("npx @beryl-so/cli@latest init")}\n` +
@@ -527,10 +526,10 @@ export const initCommands = [
                     `${cyan(MANUAL_CONFIG_SNIPPET)}\n` +
                     `    ${dim("Some clients name that key `servers` or `mcp`.")}\n` +
                     `    ${yellow(`Details: ${MANUAL_SETUP_DOCS}`)}\n`
-                : `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to write tests.`)}\n` +
-                    `  ${dim(`• Say: "write tests for https://example.com" and ${ed.agent} picks your workspace/project`)}\n` +
-                    `  ${dim("  and sets the URL for you (no pin, no prompt).")}\n` +
-                    `  ${dim(`• Playwright MCP is wired, so ${ed.agent} can drive a real browser to author from your plan.`)}\n`;
+                : `\n${bold(`Beryl is set up. Now ${ed.open} and ask ${ed.agent} to create tests.`)}\n` +
+                    `  ${dim(`• Say: "create tests for https://example.com from docs/checkout.md" and ${ed.agent} starts`)}\n` +
+                    `  ${dim("  a cloud test-creation job that authors them from that document.")}\n` +
+                    `  ${dim(`• Then ask ${ed.agent} to run them on this machine (local runs) or in the cloud.`)}\n`;
             // The .mcp.json entry is pinned to @latest, but a global install / old npx cache
             // still wins resolution — so tell the user when the CLI they just ran is stale.
             await warnIfStale(cliVersion(), (msg) => ctx.err(yellow(msg)));
@@ -549,11 +548,12 @@ export const initCommands = [
     },
     {
         name: "guide",
-        summary: "Print the Beryl test-authoring guide",
-        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. Same content as the beryl-test skill `beryl init` installs. " +
+        summary: "Print the Beryl test guide",
+        description: "The guide to durable, healable tests: where new tests come from (`jobs create`), 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. 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"],

package/dist/commands/jobs.js

@@ -0,0 +1,125 @@
+import fs from "node:fs";
+import path from "node:path";
+import { UsageError } from "../errors.js";
+import { arg, flagBool, flagStr, projectPath } from "./util.js";
+const jobsPath = (ws, p) => `${projectPath(ws, p)}/test-creation-jobs`;
+const LLM_NOTICE = "The document is sent to the LLM that drives the agent, so leave out anything you " +
+    "would not share with it.";
+function readDocument(file) {
+    try {
+        return new Uint8Array(fs.readFileSync(file));
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            throw new UsageError(`file not found: ${file}`);
+        throw new UsageError(`cannot read ${file} (${code ?? err.message})`);
+    }
+}
+export function jobHuman(job) {
+    const lines = [`Job ${job.id}: ${job.status}`];
+    if (job.error)
+        lines.push(`Error: ${job.error}`);
+    for (const t of job.tests)
+        lines.push(`  ${t.title ?? t.id} [${t.surface}] ${t.id}`);
+    if (!job.tests.length)
+        lines.push("  No tests yet.");
+    const skipped = job.skipped_flows ?? [];
+    if (skipped.length)
+        lines.push("Skipped scenarios:");
+    for (const s of skipped)
+        lines.push(`  ${s.handle}: ${s.reason}`);
+    return lines.join("\n");
+}
+export const jobCommands = [
+    {
+        name: "jobs create",
+        groupSummary: "Test-creation jobs: the cloud agent reads a document and authors tests from it.",
+        summary: "Create tests from a document (PRD, release notes) on Beryl's cloud",
+        description: "Uploads a document (Markdown, plain text, PDF or DOCX, or --text) and queues a " +
+            "job: the agent explores the environment, drafts one flow per scenario the document " +
+            "describes, and authors one test per enabled surface of the project. New tests get " +
+            "no groups. A job runs once; to run it again, use `jobs clone`. " +
+            LLM_NOTICE,
+        scope: "project",
+        args: [{ name: "file", description: "Path to the document" }],
+        flags: [
+            { name: "text", type: "string", description: "The document as text, instead of a file" },
+            {
+                name: "env",
+                type: "string",
+                description: "Environment id to explore (defaults to the project's default)",
+            },
+        ],
+        examples: ["beryl jobs create ./release-notes.md --env <env-id>"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const file = input.args.file;
+            const text = flagStr(input, "text");
+            if (Boolean(file) === Boolean(text)) {
+                throw new UsageError("pass a document file or --text, not both");
+            }
+            const form = new FormData();
+            if (file)
+                form.set("file", new Blob([readDocument(file)]), path.basename(file));
+            else
+                form.set("text", text);
+            const envId = flagStr(input, "env");
+            if (envId)
+                form.set("environment_id", envId);
+            const job = (await ctx.client.request("POST", jobsPath(workspaceId, projectId), {
+                form,
+            }));
+            return {
+                data: job,
+                human: `Job ${job.id} queued. Check it with \`beryl jobs get ${job.id}\`.`,
+            };
+        },
+    },
+    {
+        name: "jobs list",
+        summary: "List the project's test-creation jobs",
+        scope: "project",
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            return { data: await ctx.client.get(jobsPath(workspaceId, projectId)) };
+        },
+    },
+    {
+        name: "jobs get",
+        summary: "Show a job's status and the tests it created",
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const job = (await ctx.client.get(`${jobsPath(workspaceId, projectId)}/${arg(input, "job-id")}`));
+            return { data: job, human: jobHuman(job) };
+        },
+    },
+    {
+        name: "jobs clone",
+        summary: "Run a job again: queue a new job with the same document and environment",
+        description: LLM_NOTICE,
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id to clone", required: true }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const job = (await ctx.client.post(`${jobsPath(workspaceId, projectId)}/${arg(input, "job-id")}/clone`));
+            return { data: job, human: `Job ${job.id} queued.` };
+        },
+    },
+    {
+        name: "jobs delete",
+        summary: "Delete a job; the flows and tests it created stay",
+        scope: "project",
+        args: [{ name: "job-id", description: "Job id", required: true }],
+        flags: [{ name: "force", type: "boolean", description: "Skip the confirmation prompt" }],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const jobId = arg(input, "job-id");
+            await ctx.confirm(`Delete job ${jobId}? Its tests stay.`, flagBool(input, "force"));
+            await ctx.client.del(`${jobsPath(workspaceId, projectId)}/${jobId}`);
+            return { human: "Deleted." };
+        },
+    },
+];

package/dist/commands/projects.js

@@ -1,7 +1,7 @@
 import { detectAuthGating } from "../detect.js";
 import { UsageError } from "../errors.js";
 import { dim, green, table, timeAgo } from "../output.js";
-import { arg, flagBool, flagNum, flagStr, projectPath } from "./util.js";
+import { arg, argList, flagBool, flagNum, flagStr, projectPath } from "./util.js";
 import { pollCurrentExploration, watchExploration } from "./watch.js";
 // The API treats the auth choice as the visitor's answer and never infers it — a null
 // choice leaves the project waiting on a login capture that never comes — so resolve it
@@ -37,7 +37,7 @@ export const projectCommands = [
         summary: "List projects in the workspace",
         scope: "workspace",
         groupDefault: true,
-        groupSummary: "Create and manage projects: a site Beryl explores, authors tests for, and runs.",
+        groupSummary: "Create and manage projects: a site you author tests for and run.",
         async run(ctx, input) {
             const ws = await ctx.requireWorkspace(input);
             const rows = (await ctx.client.get(`/workspaces/${ws}/projects`));
@@ -70,7 +70,7 @@ export const projectCommands = [
     },
     {
         name: "projects create",
-        summary: "Create a project. With a URL the agent starts exploring; with just --name an empty one",
+        summary: "Create a project for a URL, or an empty one with just --name",
         scope: "workspace",
         args: [
             {
@@ -84,7 +84,7 @@ export const projectCommands = [
                 name: "name",
                 type: "string",
                 description: "Name for an empty project when no URL is given. Add a URL later with " +
-                    "`beryl envs update <env-id>`, or author tests over the CLI/MCP",
+                    "`beryl envs update <env-id>`",
             },
             {
                 name: "auth",
@@ -95,41 +95,45 @@ export const projectCommands = [
             },
             { name: "force-new-login", type: "boolean", description: "Ignore any reusable saved login" },
             {
-                name: "no-explore",
+                name: "explore",
                 type: "boolean",
-                description: "Create the project without starting the cloud exploration. Author tests yourself " +
-                    "via `beryl tests create` or your coding agent over MCP",
+                description: "Also start a cloud exploration that authors tests for you. Off by default: create " +
+                    "tests from a document with `beryl jobs create`",
+                mcpDescription: "Leave unset: create tests from a document with `jobs create`. Set only when the " +
+                    "user explicitly asks for a cloud exploration",
             },
-            { name: "watch", type: "boolean", description: "Stream the agent's exploration live" },
+            { name: "watch", type: "boolean", description: "Start the exploration (implies --explore) and stream it live" },
             { name: "timeout", type: "number", description: "With --watch: max minutes to wait" },
         ],
         examples: [
-            "beryl projects create https://app.example.com --watch",
+            "beryl projects create https://app.example.com",
             "beryl projects create https://app.example.com --auth gated",
-            "beryl projects create https://app.example.com --auth public --no-explore",
             'beryl projects create --name "Acme production"',
         ],
         async run(ctx, input) {
-            const noExplore = flagBool(input, "no-explore");
-            if (noExplore && flagBool(input, "watch"))
+            const watch = flagBool(input, "watch");
+            if (input.flags.explore === false && watch)
                 throw new UsageError("--no-explore cannot be combined with --watch");
+            const explore = flagBool(input, "explore") || watch;
             const ws = await ctx.requireWorkspace(input);
             const rawUrl = input.args.url;
             const url = typeof rawUrl === "string" ? rawUrl : "";
             const name = flagStr(input, "name");
             // Name-only: create a real empty project (no URL, no exploration). Set a URL
-            // later with `beryl envs update <env-id>` or author over the CLI/MCP.
+            // later with `beryl envs update <env-id>`.
             if (!url) {
                 if (!name)
-                    throw new UsageError("Provide a URL to explore, or --name to create an empty project");
+                    throw new UsageError("Provide a URL, or --name to create an empty project");
+                if (explore)
+                    throw new UsageError("--explore and --watch need a URL to explore");
                 const created = (await ctx.client.post(`/workspaces/${ws}/projects`, {
                     name,
                 }));
                 return {
                     data: created,
                     human: `${green("Project created")}: ${created.project_id} ${dim("(empty)")}\n` +
-                        `Add a site with \`beryl envs update <env-id>\`, or author tests with ` +
-                        `\`beryl tests create\`.`,
+                        `Add a site with \`beryl envs update <env-id>\`, then create tests with ` +
+                        `\`beryl jobs create <document>\`.`,
                 };
             }
             const auth = flagStr(input, "auth") ?? (await resolveAuthChoice(ctx, ws, url));
@@ -137,13 +141,13 @@ export const projectCommands = [
                 root_url: url,
                 requires_auth_choice: auth,
                 force_new_login: flagBool(input, "force-new-login"),
-                skip_exploration: noExplore,
+                skip_exploration: !explore,
             }));
-            if (noExplore)
+            if (!explore)
                 return {
                     data: created,
-                    human: `${green("Project created")}: ${created.project_id} ${dim("(no exploration started)")}\n` +
-                        `Ready for your own tests — author a plan and push it with \`beryl tests create\`.`,
+                    human: `${green("Project created")}: ${created.project_id}\n` +
+                        `Create tests from a document describing the flows: \`beryl jobs create <file>\`.`,
                 };
             // The agent cannot start until a login is captured, so there is nothing to watch.
             if (created.auth_status === "needs_capture")
@@ -223,6 +227,55 @@ export const projectCommands = [
             return { data: await ctx.client.patch(projectPath(workspaceId, projectId), body) };
         },
     },
+    {
+        name: "projects surfaces",
+        summary: "Set which surfaces are enabled for this project",
+        description: "Replaces the project's enabled surfaces with the ones listed: web-desktop, " +
+            "web-tablet, web-mobile. A new project has web-desktop only. At least one is " +
+            "required; `projects get` shows the current set. Turning a surface off removes " +
+            "no tests: delete a surface's tests to stop running them.",
+        scope: "project",
+        args: [
+            {
+                name: "surfaces",
+                description: "web-desktop | web-tablet | web-mobile, one or more",
+                required: true,
+                variadic: true,
+            },
+        ],
+        examples: ["beryl projects surfaces web-desktop web-mobile", "beryl projects surfaces web-desktop"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), {
+                enabled_surfaces: argList(input, "surfaces"),
+            }));
+            return { data, human: `Enabled surfaces: ${data.enabled_surfaces.join(", ")}` };
+        },
+    },
+    {
+        name: "projects findings-gate",
+        summary: "Turn the findings gate on each run on or off",
+        description: "With the gate on (new-since-green), every run also reports a findings gate: failed " +
+            "when the environment's Site Health has a finding first seen after the last green run " +
+            "or came back after it (every current finding if there is no green run yet), unknown " +
+            "when Site Health has not run there or is not recording findings (its issue tracker " +
+            "must be connected). The gate sits next to the test verdicts and never changes one, nor the " +
+            "exit code of `runs watch`; read it from `findings_gate` on `runs get`. Off by default.",
+        scope: "project",
+        args: [{ name: "mode", description: "off | new-since-green", required: true }],
+        examples: ["beryl projects findings-gate new-since-green", "beryl projects findings-gate off"],
+        async run(ctx, input) {
+            const { workspaceId, projectId } = await ctx.requireProject(input);
+            const mode = arg(input, "mode").toLowerCase().replace(/-/g, "_");
+            if (mode !== "off" && mode !== "new_since_green") {
+                throw new UsageError(`Expected "off" or "new-since-green", got "${arg(input, "mode")}"`);
+            }
+            const data = (await ctx.client.patch(projectPath(workspaceId, projectId), {
+                findings_gate: mode,
+            }));
+            return { data, human: `Findings gate: ${data.findings_gate.replace(/_/g, "-")}` };
+        },
+    },
     {
         name: "projects delete",
         summary: "Delete a project and all its tests and runs",
@@ -254,7 +307,7 @@ export const projectCommands = [
     },
     {
         name: "projects report",
-        summary: "Aggregate quality report across recent runs (pass rates, flaky tests, trend)",
+        summary: "Aggregate quality report across recent runs (pass rates, per-test history, trend)",
         scope: "project",
         flags: [
             { name: "runs", type: "number", description: "How many recent runs to aggregate" },