explorbot 0.4.3 → 0.4.5

package/boat/prima/src/prima.ts

@@ -20,20 +20,20 @@ import { Reporter } from '../../../src/reporter.ts';
 import type { WebPageState } from '../../../src/state-manager.ts';
 import { Stats } from '../../../src/stats.ts';
 import { Task, Test, TestResult } from '../../../src/test-plan.ts';
+import { ariaRefSnapshot } from '../../../src/utils/aria-ref.ts';
 import { compactAriaSnapshot } from '../../../src/utils/aria.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
 import { pluralize } from '../../../src/utils/logger.ts';
 import { mdq } from '../../../src/utils/markdown-query.ts';
 import { safeFilename } from '../../../src/utils/strings.ts';
-import { type EnvelopeData, type InstanceInfo, STATUS_FILE, readArtifacts, writeArtifacts } from './envelope.ts';
+import { type ArtifactPaths, type EnvelopeData, type InstanceInfo, STATUS_FILE, STEP_FILES, readArtifacts, writeArtifacts } from './envelope.ts';
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from './pw-parser.ts';
 import { type PwServerDescriptor, readDescriptors, selectDescriptor } from './pw-registry.ts';
 import { type SessionRun, latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from './session-log.ts';
 
-const TESTER_ONLY_TOOLS = ['learnExperience', 'askUser'];
+const WITHHELD_TOOLS = ['learnExperience', 'askUser', 'research'];
 const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
-const DEFAULT_RESEARCH_AFTER_VISITS = 3;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
 const AI_AGENT_NAME = 'prima';
@@ -74,7 +74,6 @@ export class Prima {
   private server: { close: () => Promise<void> } | null = null;
   private attached: string | null = null;
   private session: SessionRun | null = null;
-  private artifacts?: EnvelopeData['artifacts'];
 
   constructor(options: PrimaOptions = {}) {
     this.options = options;
@@ -108,6 +107,7 @@ export class Prima {
     const config = await this.loadConfig();
     await this.resolveBrowser(config, discovery);
     await this.bot.start();
+    this.bot.agentResearcher().disable();
 
     if (!this.options.url) return;
     if (this.bot.getCurrentState()) return;
@@ -325,11 +325,15 @@ export class Prima {
       return null;
     });
 
-    if (settleError) trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: browserErrorMessage(settleError) });
-
+    const stillOpen = ledger.filter((entry) => entry.status === 'open').length;
     for (const execution of invoked?.toolExecutions || []) {
       this.applyLedgerReport(execution, ledger, trace);
     }
+
+    let unsettled = '';
+    if (settleError) unsettled = browserErrorMessage(settleError);
+    if (invoked && ledger.filter((entry) => entry.status === 'open').length === stillOpen) unsettled = 'the model was asked to report every remaining instruction and reported none';
+    if (unsettled) trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: unsettled });
   }
 
   private ledgerProgress(ledger: LedgerEntry[]): string {
@@ -422,9 +426,12 @@ export class Prima {
     const guard = await this.aiGuard(command);
     if (guard) return guard;
 
+    const researcher = this.bot.agentResearcher();
+    researcher.enable();
+
     const previousState = this.bot.stateManager().getCurrentState();
     const result = await this.capturedResult(previousState);
-    const uiMap = await this.bot.agentResearcher().research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
+    const uiMap = await researcher.research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
     return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
   }
 
@@ -820,7 +827,7 @@ export class Prima {
     if (!researcher || !navigator) return {};
 
     const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
-    for (const name of TESTER_ONLY_TOOLS) delete tools[name];
+    for (const name of WITHHELD_TOOLS) delete tools[name];
     return tools;
   }
 
@@ -878,14 +885,15 @@ export class Prima {
 
   private async pageContext(result: ActionResult): Promise<string> {
     const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
-    const map = this.researchMap(result);
+    const map = getPreviousResearch(result.baseHash);
+    let uiMap = '';
     if (map) {
-      return dedent`
-        <page_ui_map url="${result.url}" title="${result.title}">
+      uiMap = dedent`
+        <page_ui_map>
+        A map of this page recorded by an earlier research run. It names parts the accessibility
+        tree does not, and can be out of date — the tree is what the page holds now.
         ${map}
         </page_ui_map>
-
-        ${experience}
       `;
     }
 
@@ -894,21 +902,12 @@ export class Prima {
       ${compactAriaSnapshot(await this.refAriaSnapshot(result), true, (value) => this.offloadValue(value))}
       </page>
 
+      ${uiMap}
+
       ${experience}
     `;
   }
 
-  private researchMap(result: ActionResult): string {
-    if (this.bot.stateManager().getVisitCount(result.url) < this.researchAfterVisits()) return '';
-    return getPreviousResearch(result.getStateHash());
-  }
-
-  private researchAfterVisits(): number {
-    const configured = this.bot.getConfig?.()?.ai?.agents?.prima?.researchAfterVisits;
-    if (typeof configured === 'number') return configured;
-    return DEFAULT_RESEARCH_AFTER_VISITS;
-  }
-
   private offloadValue(value: string): string | undefined {
     const dir = this.statusDir();
     const name = `value-${createHash('sha1').update(value).digest('hex').slice(0, 8)}.txt`;
@@ -922,7 +921,7 @@ export class Prima {
   }
 
   private async refAriaSnapshot(result: ActionResult): Promise<string | null> {
-    const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.((page: any) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+    const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.(ariaRefSnapshot)).catch(() => null);
     return snapshot || result.ariaSnapshot;
   }
 
@@ -982,16 +981,13 @@ export class Prima {
 
   private async successEnvelope(command: string, used: string[], result: ActionResult, previousState: WebPageState | null): Promise<EnvelopeData> {
     const changes = await this.pageChanges(result, previousState, used[0]);
-    const status = await this.saveStatus(result);
     return {
       ok: true,
       command,
       used,
       page: this.pageBlock(result, previousState),
       changes,
-      instance: await this.instanceInfo(),
-      status,
-      artifacts: this.artifacts,
+      ...(await this.envelopeTail(result)),
     };
   }
 
@@ -1000,31 +996,30 @@ export class Prima {
     const failure: EnvelopeData['failure'] = { error: browserErrorMessage(error) };
     if (result.ariaSnapshot) failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
 
-    const status = await this.saveStatus(result);
     return {
       ok: false,
       command,
       page: this.pageBlock(result, previousState),
       failure,
-      instance: await this.instanceInfo(),
-      status,
-      artifacts: this.artifacts,
+      ...(await this.envelopeTail(result)),
     };
   }
 
   private async reportEnvelope(command: string, result: ActionResult, previousState: WebPageState | null, outcome: Partial<EnvelopeData>): Promise<EnvelopeData> {
-    const status = await this.saveStatus(result);
     return {
       ok: true,
       command,
       page: this.pageBlock(result, previousState),
       ...outcome,
-      instance: await this.instanceInfo(),
-      status,
-      artifacts: this.artifacts,
+      ...(await this.envelopeTail(result)),
     };
   }
 
+  private async envelopeTail(result: ActionResult): Promise<Pick<EnvelopeData, 'instance' | 'status' | 'artifacts'>> {
+    const { hash, artifacts } = await this.saveStatus(result);
+    return { instance: await this.instanceInfo(), status: hash, artifacts };
+  }
+
   private async capturedResult(previousState: WebPageState | null, opts: { screenshot?: boolean } = {}): Promise<ActionResult> {
     const captured = await this.bot
       .getExplorer()
@@ -1086,11 +1081,11 @@ export class Prima {
     };
   }
 
-  private async saveStatus(result: ActionResult): Promise<string> {
+  private async saveStatus(result: ActionResult): Promise<{ hash: string; artifacts: ArtifactPaths }> {
     const hash = this.statusHash();
-    await this.writeSnapshot(result);
+    const artifacts = await this.writeSnapshot(result);
     writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
-    return hash;
+    return { hash, artifacts };
   }
 
   private async writeStepFiles(index: number, label: string, diff: string): Promise<void> {
@@ -1102,17 +1097,17 @@ export class Prima {
     const stem = path.join(dir, `${index}-${safeFilename(label.slice(0, 60))}`);
     const result = ActionResult.fromState(state);
 
-    writeFileSync(`${stem}.aria.yaml`, result.ariaSnapshot ?? '', 'utf-8');
-    writeFileSync(`${stem}.html`, await result.combinedHtml(), 'utf-8');
-    if (diff) writeFileSync(`${stem}.diff.yaml`, diff, 'utf-8');
+    writeFileSync(`${stem}.${STEP_FILES.aria}`, result.ariaSnapshot ?? '', 'utf-8');
+    writeFileSync(`${stem}.${STEP_FILES.html}`, await result.combinedHtml(), 'utf-8');
+    if (diff) writeFileSync(`${stem}.${STEP_FILES.diff}`, diff, 'utf-8');
   }
 
-  private async writeSnapshot(result: ActionResult): Promise<void> {
-    this.artifacts = writeArtifacts(this.statusDir(), {
+  private async writeSnapshot(result: ActionResult): Promise<ArtifactPaths> {
+    return writeArtifacts(this.statusDir(), {
       aria: result.ariaSnapshot,
       html: await result.combinedHtml(),
       screenshot: result.screenshot,
-      requests: this.bot.requestStore().getMadeRequests(),
+      requests: this.bot.requestStore().getCapturedRequests(),
     });
   }
 

package/dist/boat/api-tester/src/apibot.js

@@ -120,15 +120,14 @@ export class ApiBot {
         this.currentPlan = Plan.fromMarkdown(planPath);
         return this.currentPlan;
     }
-    savePlan(filename) {
+    savePlan(suffix) {
         if (!this.currentPlan)
             return null;
         const plansDir = this.configParser.getPlansDir();
         if (!existsSync(plansDir)) {
             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;
     }
@@ -162,9 +161,11 @@ export class ApiBot {
             return undefined;
         }
     }
-    generatePlanFilename() {
+    generatePlanFilename(suffix) {
         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`;
     }
 }

package/dist/boat/api-tester/src/cli.js

@@ -15,6 +15,7 @@ function buildOptions(options) {
         path: options.path,
         baseEndpoint: options.endpoint,
         spec: options.spec,
+        header: options.header,
     };
 }
 function addCommonOptions(cmd) {
@@ -24,7 +25,8 @@ function addCommonOptions(cmd) {
         .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, previous = []) => [...previous, value]);
 }
 function selectTests(tests, index) {
     if (!index || index === '*' || index === 'all') {
@@ -87,6 +89,8 @@ export function createApiCommands(name = 'api') {
         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 }));
@@ -130,9 +134,11 @@ export function createApiCommands(name = 'api') {
             process.exit(1);
         }
     });
-    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();
             const styles = Object.keys(getStyles());
@@ -160,7 +166,7 @@ export function createApiCommands(name = 'api') {
                     else
                         totalFailed++;
                 }
-                bot.savePlan(`${endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_')}_${style}.md`);
+                bot.savePlan(style);
             }
             console.log('\n=== Final Results ===');
             console.log(`Total: ${totalTests} tests, ${totalPassed} passed, ${totalFailed} failed`);

package/dist/boat/api-tester/src/config.js

@@ -10,8 +10,21 @@ import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
-import { ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot } from "../../../src/config.js";
+import { ConfigMissingError, EXPLORBOT_CONFIG_PATHS, createModel, envConfigRequested, materializeKnowledge, missingConfigMessage, resolveConfigModels, resolveModel, resolveOutputRoot, setOutputDir } from "../../../src/config.js";
 import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from "../../../src/global-config.js";
+function isAbsoluteEndpoint(value) {
+    return !!value && (value.startsWith('http://') || value.startsWith('https://'));
+}
+function parseHeaders(raw) {
+    const headers = {};
+    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 {
     static instance;
     config = null;
@@ -65,6 +78,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);
@@ -74,6 +88,7 @@ export class ApibotConfigParser {
                 this.enterGlobalMode(this.config, options?.endpoint);
             }
             this.validateConfig(this.config);
+            setOutputDir(this.getOutputDir());
             return this.config;
         }
         finally {
@@ -103,12 +118,14 @@ export class ApibotConfigParser {
         return path.dirname(configPath);
     }
     resolveEndpointPath(endpoint) {
-        if (!this.site)
+        if (!this.site && !isAbsoluteEndpoint(endpoint))
             return endpoint;
-        const resolved = resolveSiteTarget(endpoint, this.site.url);
-        if (resolved.baseUrl !== this.site.url)
+        const base = new URL(this.getConfig().api.baseEndpoint);
+        const origin = this.site?.url || base.origin;
+        const resolved = resolveSiteTarget(endpoint, origin);
+        if (resolved.baseUrl !== origin)
             return endpoint;
-        const basePath = new URL(this.getConfig().api.baseEndpoint).pathname.replace(/\/$/, '');
+        const basePath = base.pathname.replace(/\/$/, '');
         if (!basePath)
             return resolved.path;
         if (resolved.path === basePath)
@@ -137,12 +154,19 @@ export class ApibotConfigParser {
             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');
     }
     applyEnvSpec(api) {
         if (!process.env.EXPLORBOT_API_SPEC)
             return;
         api.spec = [process.env.EXPLORBOT_API_SPEC];
     }
+    applyEnvHeaders(api) {
+        if (!process.env.EXPLORBOT_API_HEADERS)
+            return;
+        api.headers = { ...api.headers, ...parseHeaders(process.env.EXPLORBOT_API_HEADERS) };
+    }
     enterGlobalMode(config, endpoint) {
         const site = resolveSiteTarget(endpoint);
         this.site = registerSite(site.baseUrl);
@@ -163,7 +187,7 @@ export class ApibotConfigParser {
         if (modelSpec && !provider && !modelSpec.includes('/')) {
             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');
         }
@@ -171,6 +195,7 @@ export class ApibotConfigParser {
         materializeKnowledge(outputRoot);
         const api = { baseEndpoint };
         this.applyEnvSpec(api);
+        this.applyEnvHeaders(api);
         let model;
         if (provider && modelSpec)
             model = await createModel(provider, modelSpec);
@@ -185,6 +210,7 @@ export class ApibotConfigParser {
         };
         this.configPath = path.join(outputRoot, 'apibot.config.js');
         this.validateConfig(this.config);
+        setOutputDir(this.getOutputDir());
         return this.config;
     }
     findConfigFile() {

package/dist/boat/prima/src/cli.js

@@ -1,73 +1,12 @@
 import { Command } from 'commander';
-import dedent from 'dedent';
 import { keepServerRunning } from "../../../src/browser-server.js";
 import { RecommendedModelsCommand } from "../../../src/commands/recommended-models-command.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { isVerboseMode, setQuietMode } from "../../../src/utils/logger.js";
 import { clearActivityLine, trackActivityLine } from "./activity-line.js";
 import { renderEnvelope } from "./envelope.js";
+import { askHelp, checkHelp, doHelp, helpContract, reportHelp, researchHelp, sessionHelp, statusHelp, verifyHelp } from "./help.js";
 import { Prima } from "./prima.js";
-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 = () => ({});
 function buildOptions(subcommand) {
     const options = { ...rootOptions(), ...stripEmpty(subcommand) };
@@ -104,13 +43,15 @@ function addCommonOptions(cmd) {
         .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) {
+    return addCommonOptions(cmd).addHelpText('after', `\n${sessionHelp}`);
 }
 function primaFor(options) {
     Prima.applyEnv();
@@ -124,20 +65,23 @@ function primaFor(options) {
         process.env.EXPLORBOT_SPEC = options.spec;
     return new Prima(buildOptions(options));
 }
-async function runPrima(options, command, run) {
+async function runPrima(options, command, run, opts = {}) {
+    const { browser = true, record = true } = opts;
     setQuietMode(!isVerboseMode());
     trackActivityLine();
     const prima = primaFor(options);
     const startedAt = Date.now();
     let envelope;
     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(() => { });
@@ -156,37 +100,41 @@ async function runBrowser(options, run) {
 }
 export function createPrimaCommands(name = 'prima') {
     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, all) => [...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) => {
+    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) => {
+    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));
@@ -204,11 +152,7 @@ export function createPrimaCommands(name = 'prima') {
     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) => 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'))
         .addHelpText('after', `\n${reportHelp}`)
@@ -220,7 +164,7 @@ export function createPrimaCommands(name = 'prima') {
         process.exit(0);
     });
     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) => {
@@ -230,7 +174,7 @@ export function createPrimaCommands(name = 'prima') {
             return keepServerRunning(() => prima.browserStop());
         });
     });
-    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) => {
@@ -239,13 +183,13 @@ export function createPrimaCommands(name = 'prima') {
             return stopped;
         });
     });
-    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/dist/boat/prima/src/envelope.js

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 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       ',
@@ -86,7 +87,7 @@ function renderSteps(data) {
             lines.push(`      ${line}`);
     });
     if (data.stepFiles)
-        lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{aria.yaml,html,diff.yaml}`);
+        lines.push('', `page after each step: ${data.stepFiles}/<n>-<step>.{${Object.values(STEP_FILES).join(',')}}`);
     return section('Steps', lines.join('\n'));
 }
 function renderExpectations(data) {