explorbot 0.4.2 → 0.4.4

package/bin/explorbot-cli.ts

@@ -8,6 +8,7 @@ import figureSet from 'figures';
 import { render } from 'ink';
 import React from 'react';
 import { flushTelemetry } from '../src/ai/provider.js';
+import { HelpJsonCommand } from '../src/commands/help-json-command.js';
 import { RecommendedModelsCommand } from '../src/commands/recommended-models-command.js';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
@@ -43,7 +44,9 @@ process.on('unhandledRejection', (reason) => {
   tag('error').log(`Unhandled rejection: ${reason instanceof Error ? `${reason.message}\n${reason.stack}` : String(reason)}`);
 });
 
-if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima')) {
+const printsJson = process.argv.includes('--json') || process.argv.includes('help-json');
+
+if (!process.env.EXPLORBOT_NO_BANNER && !process.argv.includes('prima') && !printsJson) {
   console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 
@@ -952,6 +955,8 @@ ${rows}
 `;
 };
 
+program.addHelpText('after', `\nFor agents and tools:\n  ${cli} help-json [command...]  the same definitions as JSON — commands, arguments, options, defaults\n`);
 program.addHelpText('after', envHelp);
+HelpJsonCommand.register(program);
 
 program.parse();

package/boat/api-tester/src/apibot.ts

@@ -10,7 +10,7 @@ import { setVerboseMode, tag } from '../../../src/utils/logger.ts';
 import { Chief } from './ai/chief.ts';
 import { Curler } from './ai/curler.ts';
 import { ApiClient } from './api-client.ts';
-import { type ApibotConfig, ApibotConfigParser } from './config.ts';
+import { type ApibotConfig, ApibotConfigParser, type ApibotRunOptions } from './config.ts';
 
 export class ApiBot {
   private configParser: ApibotConfigParser;
@@ -141,7 +141,7 @@ export class ApiBot {
     return this.currentPlan;
   }
 
-  savePlan(filename?: string): string | null {
+  savePlan(suffix?: string): string | null {
     if (!this.currentPlan) return null;
 
     const plansDir = this.configParser.getPlansDir();
@@ -149,8 +149,7 @@ export class ApiBot {
       mkdirSync(plansDir, { recursive: true });
     }
 
-    const planFilename = filename || this.generatePlanFilename();
-    const planPath = path.join(plansDir, planFilename);
+    const planPath = path.join(plansDir, this.generatePlanFilename(suffix));
     this.currentPlan.saveToMarkdown(planPath);
     return planPath;
   }
@@ -192,20 +191,16 @@ export class ApiBot {
     }
   }
 
-  private generatePlanFilename(): string {
+  private generatePlanFilename(suffix?: string): string {
     const endpoint = this.currentPlan?.url || '/';
-    const sanitized = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'root';
-    return `${sanitized.slice(0, 200)}.md`;
+    let name = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'root';
+    if (suffix) name = `${name}_${suffix}`;
+    return `${name.slice(0, 200)}.md`;
   }
 }
 
-interface ApibotOptions {
+interface ApibotOptions extends ApibotRunOptions {
   verbose?: boolean;
-  config?: string;
-  path?: string;
-  endpoint?: string;
-  baseEndpoint?: string;
-  spec?: string;
 }
 
 export type { ApibotOptions };

package/boat/api-tester/src/cli.ts

@@ -16,6 +16,7 @@ function buildOptions(options: any): ApibotOptions {
     path: options.path,
     baseEndpoint: options.endpoint,
     spec: options.spec,
+    header: options.header,
   };
 }
 
@@ -26,7 +27,8 @@ function addCommonOptions(cmd: Command): Command {
     .option('-c, --config <path>', 'Path to configuration file')
     .option('-p, --path <path>', 'Working directory path')
     .option('--endpoint <url>', 'Base API endpoint to test (env: EXPLORBOT_URL)')
-    .option('--spec <path>', 'OpenAPI spec file or URL (env: EXPLORBOT_API_SPEC)');
+    .option('--spec <path>', 'OpenAPI spec file or URL (env: EXPLORBOT_API_SPEC)')
+    .option('-H, --header <header>', 'Header sent with every request, as "Name: value". Repeatable (env: EXPLORBOT_API_HEADERS)', (value: string, previous: string[] = []) => [...previous, value]);
 }
 
 function selectTests(tests: any[], index?: string): any[] {
@@ -101,6 +103,7 @@ export function createApiCommands(name = 'api'): Command {
       const [site] = listSites();
       const runOptions = buildOptions(options);
       runOptions.endpoint = endpoint || site?.url;
+      if (runOptions.endpoint && URL.canParse(runOptions.endpoint)) runOptions.baseEndpoint ||= runOptions.endpoint;
       try {
         const config = await parser.loadConfig(runOptions);
         console.log(ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json }));
@@ -149,9 +152,10 @@ export function createApiCommands(name = 'api'): Command {
     }
   });
 
-  addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan')).action(async (endpoint, options) => {
+  addCommonOptions(cmd.command('explore <endpoint>').description('Full cycle: plan all styles, execute tests, re-plan. The endpoint may be the base endpoint itself')).action(async (endpoint, options) => {
     setPreserveConsoleLogs(true);
     try {
+      if (URL.canParse(endpoint)) options.endpoint ||= endpoint;
       const bot = new ApiBot({ ...buildOptions(options), endpoint });
       await bot.start();
 
@@ -182,7 +186,7 @@ export function createApiCommands(name = 'api'): Command {
           else totalFailed++;
         }
 
-        bot.savePlan(`${endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_')}_${style}.md`);
+        bot.savePlan(style);
       }
 
       console.log('\n=== Final Results ===');

package/boat/api-tester/src/config.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
-import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from '../../../src/config.ts';
+import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot, setOutputDir } from '../../../src/config.ts';
 import { type SiteRecord, findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from '../../../src/global-config.ts';
 
 export type { AIConfig };
@@ -24,6 +24,20 @@ interface ApibotConfig {
   };
 }
 
+function isAbsoluteEndpoint(value?: string): boolean {
+  return !!value && (value.startsWith('http://') || value.startsWith('https://'));
+}
+
+function parseHeaders(raw: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  for (const line of raw.split('\n')) {
+    const separator = line.indexOf(':');
+    if (separator < 1) continue;
+    headers[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+  }
+  return headers;
+}
+
 export class ApibotConfigParser {
   private static instance: ApibotConfigParser;
   private config: ApibotConfig | null = null;
@@ -45,7 +59,7 @@ export class ApibotConfigParser {
     Object.assign(process.env, parseEnv(readFileSync(resolved, 'utf8')));
   }
 
-  async loadConfig(options?: { config?: string; path?: string; endpoint?: string; baseEndpoint?: string; spec?: string }): Promise<ApibotConfig> {
+  async loadConfig(options?: ApibotRunOptions): Promise<ApibotConfig> {
     if (this.config && !options?.config && !options?.path) return this.config;
 
     const originalCwd = process.cwd();
@@ -84,6 +98,7 @@ export class ApibotConfigParser {
 
       this.config = this.mergeWithDefaults(loadedConfig);
       this.applyEnvSpec(this.config.api);
+      this.applyEnvHeaders(this.config.api);
       if (options?.baseEndpoint) this.config.api.baseEndpoint = options.baseEndpoint.replace(/\/$/, '');
       await resolveConfigModels(this.config.ai);
       this.configPath = resolvedPath;
@@ -94,6 +109,7 @@ export class ApibotConfigParser {
       }
 
       this.validateConfig(this.config);
+      setOutputDir(this.getOutputDir());
 
       return this.config;
     } finally {
@@ -125,12 +141,15 @@ export class ApibotConfigParser {
   }
 
   resolveEndpointPath(endpoint: string): string {
-    if (!this.site) return endpoint;
+    if (!this.site && !isAbsoluteEndpoint(endpoint)) return endpoint;
 
-    const resolved = resolveSiteTarget(endpoint, this.site.url);
-    if (resolved.baseUrl !== this.site.url) return endpoint;
+    const base = new URL(this.getConfig().api.baseEndpoint);
+    const origin = this.site?.url || base.origin;
 
-    const basePath = new URL(this.getConfig().api.baseEndpoint).pathname.replace(/\/$/, '');
+    const resolved = resolveSiteTarget(endpoint, origin);
+    if (resolved.baseUrl !== origin) return endpoint;
+
+    const basePath = base.pathname.replace(/\/$/, '');
     if (!basePath) return resolved.path;
     if (resolved.path === basePath) return '/';
     if (resolved.path.startsWith(`${basePath}/`)) return resolved.path.slice(basePath.length);
@@ -156,9 +175,10 @@ export class ApibotConfigParser {
     }
   }
 
-  private applyRunOptions(options?: { baseEndpoint?: string; spec?: string }): void {
+  private applyRunOptions(options?: ApibotRunOptions): void {
     if (options?.baseEndpoint) process.env.EXPLORBOT_URL = options.baseEndpoint;
     if (options?.spec) process.env.EXPLORBOT_API_SPEC = options.spec;
+    if (options?.header?.length) process.env.EXPLORBOT_API_HEADERS = options.header.join('\n');
   }
 
   private applyEnvSpec(api: ApiConfig): void {
@@ -166,6 +186,11 @@ export class ApibotConfigParser {
     api.spec = [process.env.EXPLORBOT_API_SPEC];
   }
 
+  private applyEnvHeaders(api: ApiConfig): void {
+    if (!process.env.EXPLORBOT_API_HEADERS) return;
+    api.headers = { ...api.headers, ...parseHeaders(process.env.EXPLORBOT_API_HEADERS) };
+  }
+
   private enterGlobalMode(config: ApibotConfig, endpoint?: string): void {
     const site = resolveSiteTarget(endpoint);
     this.site = registerSite(site.baseUrl);
@@ -189,7 +214,7 @@ export class ApibotConfigParser {
       throw new Error('EXPLORBOT_AI_MODEL needs a provider — set EXPLORBOT_AI_PROVIDER, or write it as "provider/model-id"');
     }
 
-    const baseEndpoint = process.env.EXPLORBOT_URL;
+    const baseEndpoint = process.env.EXPLORBOT_URL?.replace(/\/$/, '');
     if (!baseEndpoint) {
       throw new Error('No API endpoint to test. Pass --endpoint or set EXPLORBOT_URL to the API base endpoint');
     }
@@ -199,6 +224,7 @@ export class ApibotConfigParser {
 
     const api: ApiConfig = { baseEndpoint };
     this.applyEnvSpec(api);
+    this.applyEnvHeaders(api);
 
     let model: any;
     if (provider && modelSpec) model = await createModel(provider, modelSpec);
@@ -212,6 +238,7 @@ export class ApibotConfigParser {
     };
     this.configPath = path.join(outputRoot, 'apibot.config.js');
     this.validateConfig(this.config);
+    setOutputDir(this.getOutputDir());
 
     return this.config;
   }
@@ -282,4 +309,13 @@ export class ApibotConfigParser {
   }
 }
 
-export type { ApibotConfig, ApiConfig, HookFn };
+interface ApibotRunOptions {
+  config?: string;
+  path?: string;
+  endpoint?: string;
+  baseEndpoint?: string;
+  spec?: string;
+  header?: string[];
+}
+
+export type { ApibotConfig, ApiConfig, HookFn, ApibotRunOptions };

package/boat/prima/src/cli.ts

@@ -1,81 +1,13 @@
 import { Command } from 'commander';
-import dedent from 'dedent';
 import { keepServerRunning } from '../../../src/browser-server.ts';
 import { RecommendedModelsCommand } from '../../../src/commands/recommended-models-command.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { isVerboseMode, setQuietMode } from '../../../src/utils/logger.ts';
 import { clearActivityLine, trackActivityLine } from './activity-line.ts';
 import { type EnvelopeData, renderEnvelope } from './envelope.ts';
+import { askHelp, checkHelp, doHelp, helpContract, reportHelp, researchHelp, sessionHelp, statusHelp, verifyHelp } from './help.ts';
 import { Prima, type PrimaOptions } from './prima.ts';
 
-const helpContract = dedent`
-  Prima is a high-level AI extension to playwright-cli, driving the browser it has open.
-
-    playwright-cli open <url>    starts the session
-    prima <command> ...          drives it
-    playwright-cli close         ends it
-
-  One call takes a whole job:
-
-    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
-    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
-    prima pw "({ page }) => page.click('[data-test=submit]')"
-`;
-
-const checkHelp = dedent`
-  check takes an outcome rather than a click path, and works out how to reach it. It runs
-  on the page you are already on and never reloads it, so an open dialog survives the check.
-  --expected  one outcome the run must reach, repeatable for several. Without it the
-              scenario text is the single expected outcome. Each comes back under
-              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
-              "not verified" means the run never checked it, which is not the same
-              as false.
-  Outcomes are settled against a screenshot of the whole page: what a user can see is
-  the proof, and the run log only says what was done. CONTRADICTION means the two
-  disagree - reported with both sides rather than settled one way, so read the html,
-  aria and screenshot named under ### Artifacts and judge it yourself. Not finding
-  something in the picture is not enough on its own; that is "not verified".
-  ok: follows those outcomes - false when one FAILED or CONTRADICTED, or when the run
-  could not complete, which is reported as such rather than as an app failure.
-  Page problems seen on the way appear under ### Answer, not as step failures.
-`;
-
-const doHelp = dedent`
-  Each instruction is numbered and accounted for: ### Steps reports each as ok, FAIL or ??.
-  ?? means the action ran but the run ended without confirming that instruction - read the
-  steps above it. Only FAIL and an instruction the page could not carry out fail the command.
-  Nothing runs past the last instruction given. A whole remaining sequence in one call is
-  what makes this tier cheap.
-`;
-
-const verifyHelp = dedent`
-  Reports each assertion it could express as PASSED or FAILED with its playwright form,
-  and gives no overall verdict - read the lines and decide. "none ran" means the claim
-  could not be expressed, which is not the same as false.
-`;
-
-const statusHelp = dedent`
-  Reads the files a command recorded, so it needs no browser and outlives the session.
-  The hash is looked up across every recorded site. ### Artifacts names every file kept
-  under it: the aria tree, the html, the screenshot and network log when they were
-  captured, and the per-step captures of a do run.
-`;
-
-const reportHelp = dedent`
-  Commands are logged as they run, so the report needs no browser and outlives the session.
-  The most recent session is reported unless --pw-session names another.
-`;
-
-const sessionHelp = dedent`
-  --endpoint <ep>    attach to a browser server endpoint directly, skipping discovery
-  --instance <name>  which prima-owned browser you talk to; parallel work needs one each
-  --session [file]   cookies and storage persisted across processes; ignored while
-                     attached, since the attached session keeps its own
-  --framework        parsed but not active yet; reported code is CodeceptJS either way
-  DEBUG='explorbot:*' in front of a command prints the log of everything it does.
-  When no AI model is usable pw still works; for everything else drive playwright-cli.
-`;
-
 let rootOptions: () => any = () => ({});
 
 function buildOptions(subcommand: any): PrimaOptions {
@@ -114,13 +46,16 @@ function addCommonOptions(cmd: Command): Command {
     .option('--session [file]', 'Persist cookies and storage to a session file')
     .option('--model <model>', 'Main model, as provider/model-id')
     .option('--vision-model <model>', 'Model for screenshot analysis, as provider/model-id')
-    .option('--ephemeral', 'Keep no state between runs; applies to config-free runs, where output goes to a temp directory')
-    .option('--framework <name>', 'Not active yet: framework the reported code targets, codeceptjs or playwright')
+    .option('--ephemeral', 'Keep no state; config-free runs use a temp directory')
+    .option('--framework <name>', 'Inactive: reported code targets codeceptjs or playwright')
     .option('--url <url>', 'Page to open when the session has no page yet')
     .option('--spec <path>', 'Docbot application spec directory or index.md to read as page knowledge')
     .option('--endpoint <ep>', 'Websocket endpoint of a browser server to attach to, skipping discovery')
-    .option('--pw-session <title>', 'Title of the playwright-cli session to attach to')
-    .addHelpText('after', `\n${sessionHelp}`);
+    .option('--pw-session <title>', 'Title of the playwright-cli session to attach to');
+}
+
+function addBrowserOptions(cmd: Command): Command {
+  return addCommonOptions(cmd).addHelpText('after', `\n${sessionHelp}`);
 }
 
 function primaFor(options: any): Prima {
@@ -132,7 +67,8 @@ function primaFor(options: any): Prima {
   return new Prima(buildOptions(options));
 }
 
-async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>): Promise<void> {
+async function runPrima(options: any, command: string, run: (prima: Prima) => Promise<EnvelopeData>, opts: { browser?: boolean; record?: boolean } = {}): Promise<void> {
+  const { browser = true, record = true } = opts;
   setQuietMode(!isVerboseMode());
   trackActivityLine();
   const prima = primaFor(options);
@@ -140,13 +76,13 @@ async function runPrima(options: any, command: string, run: (prima: Prima) => Pr
 
   let envelope: EnvelopeData;
   try {
-    await prima.start();
+    if (browser) await prima.start();
     envelope = await run(prima);
   } catch (error) {
     envelope = await prima.toolFailureEnvelope(command, error);
   }
 
-  prima.record(envelope, Date.now() - startedAt);
+  if (record) prima.record(envelope, Date.now() - startedAt);
   clearActivityLine();
   console.log(renderEnvelope(envelope));
   await prima.stop().catch(() => {});
@@ -167,46 +103,48 @@ async function runBrowser(options: any, run: (prima: Prima) => Promise<boolean>)
 
 export function createPrimaCommands(name = 'prima'): Command {
   const cmd = new Command(name);
-  cmd.description('Tests and drives a web app through described behaviour instead of locators: one command carries a whole scenario, verifies it, and reports the proof');
+  cmd.description('Drives a web app through described behaviour, not locators');
   cmd.option('--pw-session <title>', 'Title of the playwright-cli session to attach to');
   cmd.option('--url <url>', 'Page to open when the session has no page yet');
   cmd.addHelpText('after', `\n${helpContract}`);
   rootOptions = () => cmd.opts();
 
-  addCommonOptions(cmd.command('pw <fn>').description('Run a Playwright function expression against the open page')).action(async (fn, options) => {
+  addBrowserOptions(cmd.command('pw <fn>').description('Run a Playwright function expression against the open page')).action(async (fn, options) => {
     await runPrima(options, `pw ${fn}`, (prima) => prima.pw(fn));
   });
 
-  addCommonOptions(cmd.command('do <instructions...>').description('Run high-level instructions tester-style, one argument per instruction'))
+  addBrowserOptions(cmd.command('do <instructions...>').description('Run instructions, one argument each'))
     .addHelpText('after', `\n${doHelp}`)
     .action(async (instructions, options) => {
       await runPrima(options, `do ${instructions.join(' ')}`, (prima) => prima.do(instructions));
     });
 
-  addCommonOptions(cmd.command('check <scenario>').description('Run a scenario end to end as a test, with its own verification, and report the steps it took'))
+  addBrowserOptions(cmd.command('check <scenario>').description('Run a scenario as a test, with verification'))
     .option('--expected <outcome>', 'An outcome the run must reach; repeat the flag for several', (value: string, all: string[]) => [...all, value], [])
     .addHelpText('after', `\n${checkHelp}`)
     .action(async (scenario, options) => {
       await runPrima(options, `check ${scenario}`, (prima) => prima.check(scenario, options.expected));
     });
 
-  addCommonOptions(cmd.command('ask <question>').description('Answer a question about the current page').option('--no-vision', 'Answer from page structure only, without a screenshot')).action(async (question, options) => {
-    await runPrima(options, `ask ${question}`, (prima) => prima.ask(question));
-  });
+  addBrowserOptions(cmd.command('ask <question>').description('Answer a question about the current page').option('--no-vision', 'Answer from page structure only, without a screenshot'))
+    .addHelpText('after', `\n${askHelp}`)
+    .action(async (question, options) => {
+      await runPrima(options, `ask ${question}`, (prima) => prima.ask(question));
+    });
 
-  addCommonOptions(cmd.command('verify <assertion>').alias('assert').description('Assert a statement about the current page'))
+  addBrowserOptions(cmd.command('verify <assertion>').alias('assert').description('Assert a statement about the current page'))
     .addHelpText('after', `\n${verifyHelp}`)
     .action(async (assertion, options) => {
       await runPrima(options, `verify ${assertion}`, (prima) => prima.verify(assertion));
     });
 
-  addCommonOptions(
-    cmd.command('research').description('Map the current page and return verified locators').option('--data', 'Include data extraction in the map').option('--deep', 'Expand hidden elements for a deeper map').option('--fresh', 'Ignore the cached map and research the page again')
-  ).action(async (options) => {
-    await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
-  });
+  addBrowserOptions(cmd.command('research').description('Map the current page and return verified locators').option('--data', 'Include data extraction in the map').option('--deep', 'Expand hidden elements for a deeper map').option('--fresh', 'Ignore the cached map and research the page again'))
+    .addHelpText('after', `\n${researchHelp}`)
+    .action(async (options) => {
+      await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
+    });
 
-  addCommonOptions(cmd.command('go <target>').description('Navigate to a url, a path, or a page described in plain words')).action(async (target, options) => {
+  addBrowserOptions(cmd.command('go <target>').description('Navigate to a url, a path, or a page described in plain words')).action(async (target, options) => {
     if (URL.canParse(target)) options.baseUrl = target;
     await runPrima(options, `go ${target}`, (prima) => prima.go(target));
   });
@@ -226,11 +164,7 @@ export function createPrimaCommands(name = 'prima'): Command {
   addCommonOptions(cmd.command('status <hash>').description('Show the artifacts and page detail recorded for an earlier command'))
     .addHelpText('after', `\n${statusHelp}`)
     .action(async (hash, options) => {
-      setQuietMode(!isVerboseMode());
-      const prima = primaFor(options);
-      const envelope = await prima.status(hash).catch((error: unknown) => prima.toolFailureEnvelope(`status ${hash}`, error));
-      console.log(renderEnvelope(envelope));
-      process.exit(envelope.ok ? 0 : 1);
+      await runPrima(options, `status ${hash}`, (prima) => prima.status(hash), { browser: false, record: false });
     });
 
   addCommonOptions(cmd.command('report').description('Turn every command of a session into one html and markdown report'))
@@ -247,7 +181,7 @@ export function createPrimaCommands(name = 'prima'): Command {
 
   const browser = cmd.command('browser').description('Manage the browsers prima drives');
 
-  addCommonOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
+  addBrowserOptions(browser.command('start').description('Start a prima-owned browser and hold it open until Ctrl+C'))
     .option('-s, --show', 'Launch the browser in a visible window')
     .option('--headless', 'Launch the browser without a window')
     .action(async (options) => {
@@ -258,7 +192,7 @@ export function createPrimaCommands(name = 'prima'): Command {
       });
     });
 
-  addCommonOptions(browser.command('stop').description('Stop the browser of this instance'))
+  addBrowserOptions(browser.command('stop').description('Stop the browser of this instance'))
     .option('--all', 'Stop every running instance')
     .action(async (options) => {
       await runBrowser(options, async (prima) => {
@@ -268,14 +202,14 @@ export function createPrimaCommands(name = 'prima'): Command {
       });
     });
 
-  addCommonOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
+  addBrowserOptions(browser.command('status').description('Report the browser of this instance')).action(async (options) => {
     await runBrowser(options, async (prima) => {
       console.log(await prima.browserStatus());
       return true;
     });
   });
 
-  addCommonOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
+  addBrowserOptions(browser.command('list').description('List every browser instance that is running')).action(async (options) => {
     await runBrowser(options, async (prima) => {
       console.log(await prima.browserList());
       return true;

package/boat/prima/src/envelope.ts

@@ -5,6 +5,8 @@ export const STATUS_FILE = 'status.json';
 
 const ARTIFACT_FILES = { aria: 'aria.yml', html: 'page.html', screenshot: 'page.png', network: 'network.jsonl' };
 
+export const STEP_FILES = { aria: 'aria.yaml', html: 'html', diff: 'diff.yaml' };
+
 const EXPECTATION_LABELS = {
   passed: 'PASSED       ',
   failed: 'FAILED       ',
@@ -117,7 +119,7 @@ function renderSteps(data: EnvelopeData): string | null {
     lines.push(`${index + 1}. ${mark} ${step.label}`);
     for (const line of (step.proof || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
-  if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{aria.yaml,html,diff.yaml}`);
+  if (data.stepFiles) lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{${Object.values(STEP_FILES).join(',')}}`);
   return section('Steps', lines.join('\n'));
 }
 

package/boat/prima/src/help.ts

@@ -0,0 +1,72 @@
+import dedent from 'dedent';
+
+export const helpContract = dedent`
+  Prima drives the browser opened by playwright-cli.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call runs a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+
+  Only research maps a page. Other commands read the accessibility tree; a cached
+  research map joins when present. On large or unclear pages, run prima research first.
+  Without a usable AI model only pw works; otherwise use playwright-cli.
+  DEBUG='explorbot:*' in front of a command logs everything it does.
+`;
+
+export const checkHelp = dedent`
+  check states the outcome, not the clicks; it finds the path itself. It stays
+  on the current page and never reloads it, so an open dialog survives.
+  --expected  one required outcome, repeatable for several. Without it the
+              scenario text is the outcome. Each returns under
+              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
+              "not verified" means never checked, not false.
+  Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
+  CONTRADICTION means screenshot and log disagree; judge the html, aria and
+  screenshot under ### Artifacts yourself.
+  ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
+  reported as such rather than as an app failure.
+  Side issues found on the way go under ### Answer, not as step failures.
+`;
+
+export const doHelp = dedent`
+  ### Steps marks each instruction ok, FAIL or ??. ?? means it ran but the run ended
+  without confirming it - read the steps above. Only FAIL fails the command.
+  Nothing runs past the last instruction. Batch the whole sequence in one call;
+  that is what keeps this tier cheap.
+`;
+
+export const askHelp = dedent`
+  Answers from a page screenshot, or from its structure with --no-vision.
+`;
+
+export const verifyHelp = dedent`
+  Reports each expressible assertion as PASSED or FAILED with its playwright form;
+  no overall verdict, read the lines. "none ran" means unexpressible, not false.
+`;
+
+export const researchHelp = dedent`
+  The map is saved per page state and joins later commands there, so one research run pays for all that follow it.
+`;
+
+export const statusHelp = dedent`
+  Reads recorded files, so it needs no browser and outlives the session.
+  The hash is matched across all recorded sites. ### Artifacts lists every kept
+  file: aria, html, screenshot and network log when captured, plus per-step captures of a do run.
+`;
+
+export const reportHelp = dedent`
+  Built from the command log, so it needs no browser and outlives the session.
+  Reports the latest session unless --pw-session names another.
+`;
+
+export const sessionHelp = dedent`
+  Parallel jobs need one --instance each. --session is ignored when attached,
+  since the attached session keeps its own. --framework is parsed but inactive;
+  reported code is CodeceptJS either way.
+`;