explorbot 0.5.7 → 0.5.9

package/bin/explorbot-cli.ts

@@ -13,7 +13,7 @@ import { RecommendedModelsCommand } from '../src/commands/recommended-models-com
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
 import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
-import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
+import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS, outputPath } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
@@ -123,6 +123,18 @@ async function startTUI(explorBot: ExplorBot): Promise<void> {
   });
 }
 
+function printPageContext(explorBot?: ExplorBot): void {
+  const state = explorBot?.stateManager().getCurrentState();
+  if (!state) return;
+  const lines = [`Last page: ${state.fullUrl || state.url}`];
+  if (state.title) lines.push(`Title: ${state.title}`);
+  if (state.screenshotFile) lines.push(`Screenshot: file://${outputPath('states', state.screenshotFile)}`);
+  if (state.htmlFile) lines.push(`HTML: file://${outputPath('states', state.htmlFile)}`);
+  if (state.ariaSnapshotFile) lines.push(`ARIA: file://${outputPath('states', state.ariaSnapshotFile)}`);
+  if (state.ariaSnapshot) lines.push('', state.ariaSnapshot);
+  console.error(lines.join('\n'));
+}
+
 async function showStatsAndExit(code: number): Promise<never> {
   if (remote.isAttached()) {
     await remote.close(code);
@@ -165,10 +177,11 @@ addCommonOptions(
     .option('--configure <spec>', 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"')
     .option('--dry-run', 'Mark picked tests as skipped without executing or generating new ones')
 ).action(async (explorePath, options) => {
+  let explorBot: ExplorBot | undefined;
   try {
     const urlFilter = new UrlFilter(options.urlFilter);
     const sitemapUrls = await readCliSitemap(explorePath, options.sitemap, urlFilter);
-    const explorBot = new ExplorBot(buildExplorBotOptions(explorePath || sitemapUrls?.[0], options));
+    explorBot = new ExplorBot(buildExplorBotOptions(explorePath || sitemapUrls?.[0], options));
     await explorBot.start();
     if (explorePath) await explorBot.visit(explorePath);
     const { ExploreCommand } = await import('../src/commands/explore-command.js');
@@ -188,6 +201,7 @@ addCommonOptions(
     await showStatsAndExit(0);
   } catch (error) {
     console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+    printPageContext(explorBot);
     await showStatsAndExit(1);
   }
 });
@@ -471,7 +485,13 @@ addCommonOptions(
     .join(' ');
   const { FreesailCommand } = await import('../src/commands/freesail-command.js');
   const cmd = new FreesailCommand(explorBot);
-  await cmd.execute(args);
+  try {
+    await cmd.execute(args);
+  } catch (error) {
+    console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+    printPageContext(explorBot);
+    await showStatsAndExit(1);
+  }
 });
 
 program
@@ -502,6 +522,7 @@ program
   .option('-g, --global', 'Configure explorbot in ~/.explorbot to run from anywhere')
   .option('--provider <name>', `AI provider for the global config: ${Object.keys(PROVIDERS).join(', ')}`)
   .option('--api-key <key>', 'API key stored in ~/.explorbot/.env')
+  .option('--url <url>', 'Web application URL written to web.url in the local config')
   .action(async (options) => {
     try {
       const { runInit } = await import('../src/commands/init-command.js');
@@ -512,6 +533,7 @@ program
         global: options.global,
         provider: options.provider,
         apiKey: options.apiKey,
+        url: options.url,
       });
     } catch (error) {
       console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');

package/boat/prima/README.md

@@ -41,6 +41,7 @@ playwright-cli close
 | `verify <assertion>` | Assert a statement about the current page |
 | `ask <question>` | Answer a question about the current page |
 | `research` | Map the current page and return verified locators |
+| `ux [focus]` | Review the area being worked on for UX issues at the current width, 768px and 375px |
 | `go <target>` | Navigate to a url, a path, or a page described in plain words |
 | `pw <fn>` | Run a Playwright function expression against the open page |
 | `status <hash>` | Show the artifacts and page detail recorded for an earlier command |
@@ -52,6 +53,8 @@ playwright-cli close
 
 `do` accounts for every instruction you gave: each is reported as ok, FAIL or ??. Nothing runs past the last instruction.
 
+`ux` reviews one area, not the whole page. A named focus is shown first with at most one click, which may open a dialog, tab or section or go to another page; nothing is submitted, and when no click leads to it the command fails without reviewing. The area reviewed is the dialog or region open on the page, else the focus you named, else the area your session's commands on this page acted in, else the main content. It measures target sizes, spacing, overflow, text size, zoom and motion at each width, runs axe on the area, and asks the model to judge copy, forms and navigation against the rules in `rules/quartermaster/ux/`. Findings are ranked Critical to Low. It reports problems only: no replacement wording and no colors or styles, since the project owns those. Override a rule by placing a file of the same name in `./rules/quartermaster/ux/`, or add your own with `ai.agents.quartermaster.rules`.
+
 ## AI model
 
 Prima needs a model, and takes it from the environment. There is no `init` to run and nothing is written for you.

package/boat/prima/src/cli.ts

@@ -4,7 +4,7 @@ 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 { askHelp, checkHelp, doHelp, helpContract, reportHelp, researchHelp, sessionHelp, statusHelp, uxHelp, verifyHelp } from './help.ts';
 import { Prima, type PrimaOptions } from './prima.ts';
 
 let rootOptions: () => any = () => ({});
@@ -129,6 +129,12 @@ export function createPrimaCommands(name = 'prima'): Command {
       await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
     });
 
+  addBrowserOptions(cmd.command('ux [focus]').description('Review the area being worked on for UX issues, across breakpoints'))
+    .addHelpText('after', `\n${uxHelp}`)
+    .action(async (focus, options) => {
+      await runPrima(options, ['ux', focus].filter(Boolean).join(' '), (prima) => prima.ux(focus));
+    });
+
   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));

package/boat/prima/src/envelope.ts

@@ -29,12 +29,14 @@ export interface EnvelopeData {
   used?: string[];
   page: { url: string; previousUrl?: string; redirectedFrom?: string; title: string; state: string; visits: number };
   changes?: string | null;
-  steps?: Array<{ label: string; ok: boolean; unconfirmed?: boolean; proof: string }>;
+  steps?: Array<{ label: string; ok: boolean; unconfirmed?: boolean; proof: string; state?: number }>;
+  states?: Array<{ url: string; aria: string }>;
   expectations?: SettledExpectation[];
   warning?: string;
   stepFiles?: string;
   value?: string;
   answer?: string;
+  pageIssues?: string[];
   research?: string;
   assertions?: Array<{ code: string; passed: boolean; proof: string[]; error?: string }>;
   failure?: { error: string; compactAria?: string };
@@ -44,7 +46,7 @@ export interface EnvelopeData {
 }
 
 export function renderEnvelope(data: EnvelopeData): string {
-  const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderExpectations(data), renderWarning(data), renderOutcome(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
+  const sections = [renderResult(data), renderPage(data), renderValue(data), renderChanges(data), renderSteps(data), renderStates(data), renderExpectations(data), renderWarning(data), renderOutcome(data), renderPageIssues(data), ...renderFailure(data), renderInstance(data), renderArtifacts(data)];
   return sections.filter((section) => section).join('\n\n');
 }
 
@@ -118,13 +120,20 @@ function renderSteps(data: EnvelopeData): string | null {
     let mark = 'FAIL';
     if (step.ok) mark = 'ok  ';
     if (step.unconfirmed) mark = '??  ';
-    lines.push(`${index + 1}. ${mark} ${step.label}`);
+    let label = step.label;
+    if (step.state) label += `  // state ${step.state}`;
+    lines.push(`${index + 1}. ${mark} ${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>.{${Object.values(STEP_FILES).join(',')}}`);
   return section('Steps', lines.join('\n'));
 }
 
+function renderStates(data: EnvelopeData): string | null {
+  if (!data.states?.length) return null;
+  return section('States', data.states.map((state, index) => `${index + 1}. ${state.url}\n   aria: ${state.aria}`).join('\n'));
+}
+
 function renderExpectations(data: EnvelopeData): string | null {
   if (!data.expectations?.length) return null;
 
@@ -132,7 +141,7 @@ function renderExpectations(data: EnvelopeData): string | null {
   data.expectations.forEach((expectation, index) => {
     lines.push(`${index + 1}. ${EXPECTATION_LABELS[expectation.status]} ${expectation.text}`);
     if (expectation.resolution) lines.push(`      resolved: ${expectation.resolution}`);
-    if (!expectation.contradicted && !expectation.failed && !expectation.resolution) return;
+    if (expectation.status === 'passed' && !expectation.resolution) return;
     for (const line of (expectation.evidence || '').split('\n').filter(Boolean)) lines.push(`      ${line}`);
   });
   return section('Expected outcomes', lines.join('\n'));
@@ -168,6 +177,11 @@ function renderOutcome(data: EnvelopeData): string | null {
   return section('Assertions', lines.join('\n'));
 }
 
+function renderPageIssues(data: EnvelopeData): string | null {
+  if (!data.pageIssues?.length) return null;
+  return section('Page issues', ['Noticed on the page while running, unrelated to the steps or the outcome:', ...data.pageIssues.map((issue) => `- ${issue}`)].join('\n'));
+}
+
 function renderFailure(data: EnvelopeData): Array<string | null> {
   if (!data.failure) return [];
   return [section('Failure', `error: ${data.failure.error}`), renderCompactAria(data.failure.compactAria)];

package/boat/prima/src/help.ts

@@ -25,15 +25,17 @@ export const checkHelp = dedent`
   --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.
+              "not verified" means never checked, not false; the line under it names
+              what kept the run from checking it.
   Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
   When screenshot and log disagree, the page structure breaks the tie: the outcome
   becomes PASSED or FAILED with a "resolved:" line naming the side that was wrong.
   CONTRADICTION remains when it cannot be broken, or when the page holds something
   it does not display; 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.
+  ok is false when any outcome FAILED or CONTRADICTED, when none was verified, or when
+  the run could not finish, reported as such rather than as an app failure.
+  ### Steps lists only the steps that failed.
+  Side issues found on the way go under ### Page issues, not as step failures.
 `;
 
 export const doHelp = dedent`
@@ -56,6 +58,15 @@ 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 uxHelp = dedent`
+  Reviews one area, not the page. A named focus is shown first with at most one click,
+  which may open a dialog, tab or section or go to another page; nothing is submitted. The area reviewed is the dialog or region open on the page,
+  else the named focus, else where the session's commands on this page acted, else main.
+  Measures it at the current width, 768px and 375px, then restores the viewport.
+  Findings come under ### Answer by priority; the review reports problems and never
+  proposes wording or visual style. ok stays true whatever it finds.
+`;
+
 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

package/boat/prima/src/prima.ts

@@ -20,7 +20,7 @@ import { findSiteWith, listSites } from '../../../src/global-config.ts';
 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 { Task, Test } from '../../../src/test-plan.ts';
 import { ariaRefSelector, ariaRefSnapshot, describeRef, parseAriaRefs, refIsGone } from '../../../src/utils/aria-ref.ts';
 import { compactAriaSnapshot } from '../../../src/utils/aria.ts';
 import { browserErrorMessage } from '../../../src/utils/browser-errors.ts';
@@ -37,6 +37,7 @@ const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
+const UX_SESSION_COMMANDS = 8;
 const AI_AGENT_NAME = 'prima';
 const CONNECT_TIMEOUT = 3000;
 const requireLib = createRequire(import.meta.url);
@@ -197,11 +198,13 @@ export class Prima {
         const unreported = this.openInstructions(ledger);
         if (!unreported || nudged) break;
         nudged = true;
+        let reminder = 'Do not act again on anything you have already carried out.';
+        if (!trace.length) reminder = 'Nothing has been carried out yet: text in a reply is never executed, only tool calls are. Act with tools.';
         conversation.addUserText(dedent`
           These instructions are still unreported:
           ${unreported}
 
-          Report each one with completed() or blocked(). Do not act again on anything you have already carried out.
+          Report each one with completed() or blocked(). ${reminder}
         `);
         continue;
       }
@@ -257,7 +260,8 @@ export class Prima {
     }
 
     if (!trace.length && unfinished.length === ledger.length) {
-      const reason = ['No action was performed for these instructions on the current page.', narration].filter(Boolean).join(' ');
+      let reason = 'No action was performed for these instructions on the current page.';
+      if (narration) reason += `\nThe model replied with text instead of calling a tool:\n${narration}`;
       return this.failureEnvelope(command, reason, previousState);
     }
 
@@ -382,22 +386,65 @@ export class Prima {
     const guard = await this.aiGuard(command);
     if (guard) return guard;
 
-    const previousState = await this.baselineState();
     const outcomes = expected.length ? expected : [scenario];
+    const preparation = await this.preparationSteps(scenario, outcomes);
+    let prepared: EnvelopeData | null = null;
+    if (preparation.length) {
+      prepared = await this.do(preparation, command);
+      if (!prepared.ok) {
+        prepared.failure = { error: `the check never ran, because preparing the page for it failed:\n${prepared.failure?.error || ''}` };
+        return prepared;
+      }
+    }
+
+    const previousState = await this.baselineState();
     const test = new Test(scenario, 'normal', outcomes, previousState?.url || this.options.url || '');
     const tester = this.bot.agentTester();
 
-    await tester.test(test, { startOnCurrentPage: true });
+    const states: Array<{ url: string; aria: string }> = [];
+    const visited = new Map<string, number>();
+    const timeline: Array<{ time: number; state: number }> = [];
+    const trackState = (state?: WebPageState | null) => {
+      if (!state?.hash) return;
+      let number = visited.get(state.hash);
+      if (!number) {
+        number = visited.size + 1;
+        visited.set(state.hash, number);
+        const aria = path.join(this.statusDir(), `state-${number}.aria.yml`);
+        mkdirSync(this.statusDir(), { recursive: true });
+        writeFileSync(aria, state.ariaSnapshot || '', 'utf-8');
+        states.push({ url: state.url, aria });
+      }
+      timeline.push({ time: performance.now(), state: number });
+    };
+    trackState(previousState);
+    const stopTracking = this.bot.stateManager().onStateChange((transition) => trackState(transition.toState));
+
+    await tester.test(test, { startOnCurrentPage: true }).finally(stopTracking);
 
     const notes = Object.values(test.notes || {}) as Array<{ message: string; status?: string; log?: string; observation?: boolean }>;
     const result = await this.capturedResult(this.bot.stateManager().getCurrentState(), { screenshot: this.visionEnabled() });
     const envelope = await this.reportEnvelope(command, result, previousState, {});
-    const recorded = notes.filter((note) => !note.observation && !outcomes.includes(note.message));
-    const failed = recorded.filter((note) => note.status === TestResult.FAILED);
-    envelope.steps = failed.map((note) => ({ label: note.message, ok: false, proof: note.log || '' }));
-
-    const routine = recorded.length - failed.length;
-    if (routine) envelope.steps.push({ label: `${routine} further ${pluralize(routine, 'step')} ran without failing — prima status ${envelope.status} for the full log`, ok: true, proof: '' });
+    const repeats = new Map<string, { message: string; ok: boolean; count: number; proof: string; state?: number }>();
+    for (const [startedAt, step] of Object.entries(test.steps || {})) {
+      const ok = step.status !== 'failed';
+      const state = timeline.findLast((entry) => entry.time <= Number.parseFloat(startedAt))?.state;
+      const key = `${ok} ${state} ${step.text}`;
+      let proof = '';
+      if (!ok) proof = step.error || '';
+      repeats.set(key, { message: step.text, ok, count: (repeats.get(key)?.count || 0) + 1, proof, state });
+    }
+    const preparedSteps = (prepared?.steps || []).map((step) => ({ ...step, label: `prepare: ${step.label}` }));
+    envelope.steps = [
+      ...preparedSteps,
+      ...[...repeats.values()].map(({ message, ok, count, proof, state }) => {
+        let label = message;
+        if (count > 1) label += ` (×${count})`;
+        return { label, ok, proof, state };
+      }),
+    ];
+    if (prepared?.stepFiles) envelope.stepFiles = prepared.stepFiles;
+    if (states.length) envelope.states = states;
 
     envelope.expectations = await this.bot.agentPilot().settleExpectations(test, result);
 
@@ -407,9 +454,12 @@ export class Prima {
 
     const unreached = envelope.expectations.filter((expectation) => expectation.failed);
     const contradicted = envelope.expectations.filter((expectation) => expectation.contradicted);
-    envelope.ok = !unreached.length && !contradicted.length;
+    const unverified = envelope.expectations.filter((expectation) => expectation.status === 'unverified');
+    const nothingVerified = unverified.length === envelope.expectations.length;
+    envelope.ok = !unreached.length && !contradicted.length && !nothingVerified;
 
     const problems = [...unreached.map((expectation) => `not reached: ${expectation.text}`), ...contradicted.map((expectation) => `the picture and the run disagree about: ${expectation.text}`)];
+    if (nothingVerified) problems.push(...unverified.map((expectation) => `not verified: ${expectation.text}`));
     if (problems.length) envelope.failure = { error: problems.join('\n') };
 
     if (!test.hasFinished || test.isSkipped) {
@@ -418,7 +468,7 @@ export class Prima {
     }
 
     const observations = notes.filter((note) => note.observation).map((note) => note.message);
-    if (observations.length) envelope.answer = ['Page problems noticed while running, not step failures:', ...observations.map((line) => `- ${line}`)].join('\n');
+    if (observations.length) envelope.pageIssues = observations;
     return envelope;
   }
 
@@ -466,6 +516,29 @@ export class Prima {
     return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
   }
 
+  async ux(focus?: string): Promise<EnvelopeData> {
+    const command = ['ux', focus].filter(Boolean).join(' ');
+    const guard = await this.aiGuard(command);
+    if (guard) return guard;
+
+    const previousState = await this.baselineState();
+    let clicked: string[] = [];
+    if (focus) {
+      const shown = await this.showFocus(focus, previousState);
+      if (!shown) return this.failureEnvelope(command, `Could not show "${focus}": it is not on this page and no single click from here leads to it, so no review was made.`, previousState);
+      clicked = shown;
+    }
+
+    const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
+    let auditFocus = focus;
+    if (result.overlay.isOpen && result.overlay.describe() !== previousState?.overlay?.describe()) auditFocus = undefined;
+    const answer = await this.bot.agentQuartermaster().auditUx(result, { focus: auditFocus, commands: this.sessionCommandsOn(result.url) });
+    const envelope = await this.reportEnvelope(command, result, previousState, { answer });
+    if (clicked.length) envelope.steps = clicked.map((code) => ({ label: code, ok: true, proof: '' }));
+    if (!this.visionEnabled()) envelope.warning = 'No screenshot backed this review, so visual checks were skipped. Set ai.visionModel to include them.';
+    return envelope;
+  }
+
   async go(target: string): Promise<EnvelopeData> {
     const command = `go ${target}`;
     const code = `I.amOnPage('${target}')`;
@@ -487,7 +560,7 @@ export class Prima {
     let arrived = true;
 
     try {
-      arrived = await this.bot.agentNavigator().visit(target, { recover: !isUrl });
+      arrived = await this.bot.agentNavigator().visit(target, { recover: !this.aiUnavailable() });
     } catch (error) {
       navigationError = error;
     }
@@ -498,7 +571,11 @@ export class Prima {
     if (isUrl) used.push(code);
     const result = await this.capturedResult(this.bot.stateManager().getCurrentState());
     const envelope = await this.successEnvelope(command, used, result, previousState);
-    if (!arrived) envelope.page.redirectedFrom = target;
+    if (arrived) return envelope;
+
+    envelope.page.redirectedFrom = target;
+    envelope.ok = false;
+    envelope.failure = { error: `${target} was not reached: the page redirected to ${result.url} and no AI model is available to recover (log in, follow knowledge)` };
     return envelope;
   }
 
@@ -516,7 +593,7 @@ export class Prima {
     const config = await this.loadConfig();
     const parser = ConfigParser.getInstance();
 
-    return ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json });
+    return ConfigCommand.render(config, { configPath: parser.getConfigPath(), siteConfigPath: parser.getSiteConfigPath(), root: parser.getProjectRoot(), json });
   }
 
   record(envelope: EnvelopeData, durationMs: number): void {
@@ -870,6 +947,42 @@ export class Prima {
     });
   }
 
+  private async preparationSteps(scenario: string, outcomes: string[]): Promise<string[]> {
+    const result = await this.capturedResult(await this.baselineState());
+    const page = compactAriaSnapshot(result.ariaSnapshot, true).slice(0, JUDGE_PAGE_CAP);
+
+    const judge = this.bot.judge?.();
+    if (judge) {
+      const question = 'Before this scenario can start, the current page needs actions the scenario does not perform itself: reaching the page where it starts, or setting up a precondition it relies on.';
+      const needed = await judge.decide(question, null, { scenario, outcomes, url: result.url, page });
+      if (needed.rejected) return [];
+    }
+
+    const prompt = dedent`
+      <scenario>
+      ${scenario}
+      </scenario>
+
+      <expected_outcomes>
+      ${outcomes.map((outcome) => `- ${outcome}`).join('\n')}
+      </expected_outcomes>
+
+      <page>
+      url: ${result.url}
+      ${page}
+      </page>
+
+      A check of this scenario runs next, starting from the current page. Decide whether the page must be prepared first.
+      Preparation is only what the scenario assumes but does not do: reaching the page where it starts when this is a different one,
+      or setting up a precondition it relies on. Never include the actions the scenario describes — the check performs and judges those.
+      List the preparation as short imperative instructions, in order. Return an empty list when the scenario can start here.
+    `;
+    const schema = z.object({ steps: z.array(z.string()).describe('preparation instructions, in order; empty when none are needed') });
+    const provider = this.bot.getProvider();
+    const response = await provider.generateObject([{ role: 'user', content: prompt }], schema, provider.getAgenticModel?.(AI_AGENT_NAME), { agentName: AI_AGENT_NAME }).catch(() => null);
+    return response?.object?.steps || [];
+  }
+
   private async pageContext(result: ActionResult): Promise<string> {
     const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
     const map = getPreviousResearch(result.baseHash);
@@ -922,13 +1035,8 @@ export class Prima {
     const pick = await judge.decide(`Which listed control leads to: ${target}`, [...labels, UNDECIDED], { target });
     if (!pick.value) return null;
 
-    const ref = refs[labels.indexOf(pick.value)].ref;
-    const explorer = this.bot.getExplorer();
-    if (await refIsGone(explorer, ref)) return null;
-
-    const named = await describeRef(explorer, ref);
-    const run = `I.usePlaywrightTo(${JSON.stringify(`go to ${target}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
-    if (!(await explorer.action().attempt(run, `go ${target}`))) return null;
+    const code = await this.clickRef(refs[labels.indexOf(pick.value)].ref, `go to ${target}`);
+    if (!code) return null;
 
     const newState = this.bot.stateManager().getCurrentState();
     if (!newState) return null;
@@ -938,11 +1046,59 @@ export class Prima {
     const arrived = await judge.decide(`The page now shows: ${target}`, null, { target, page });
     if (arrived.rejected) return null;
 
-    let code = run;
-    if (named) code = `I.click(${JSON.stringify(named)})`;
     return this.successEnvelope(`go ${target}`, [code], await this.capturedResult(newState), previousState);
   }
 
+  private async showFocus(focus: string, state: WebPageState | null): Promise<string[] | null> {
+    if (!state) return null;
+    const snapshot = (await this.refAriaSnapshot(ActionResult.fromState(state))) || '';
+    const refs = parseAriaRefs(snapshot).filter((entry) => entry.name);
+    const schema = z.object({
+      shown: z.boolean().describe('whether the page already shows the area'),
+      ref: z.enum(['none', ...refs.map((entry) => entry.ref)]).describe('when it is not shown, the one control whose click leads to it, or none'),
+    });
+    const prompt = dedent`
+      A UX review needs this area on screen: ${focus}
+      Say whether the page already shows it. If not, pick the one control whose single click opens, reveals or navigates to it.
+      Its label may differ from how the area was named: judge by what the control leads to.
+      Answer none when no control plausibly leads there.
+
+      <page_aria>
+      ${snapshot.slice(0, JUDGE_PAGE_CAP)}
+      </page_aria>
+    `;
+    const response = await this.bot
+      .getProvider()
+      .generateObject([{ role: 'user', content: prompt }], schema, undefined, { agentName: AI_AGENT_NAME })
+      .catch(() => null);
+    if (response?.object?.shown) return [];
+    const ref = response?.object?.ref;
+    if (!ref || ref === 'none') return null;
+    const code = await this.clickRef(ref, `show ${focus}`);
+    if (!code) return null;
+    return [code];
+  }
+
+  private async clickRef(ref: string, purpose: string): Promise<string | null> {
+    const explorer = this.bot.getExplorer();
+    if (await refIsGone(explorer, ref)) return null;
+
+    const named = await describeRef(explorer, ref);
+    const run = `I.usePlaywrightTo(${JSON.stringify(purpose)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
+    if (!(await explorer.action().attempt(run, purpose))) return null;
+    if (named) return `I.click(${JSON.stringify(named)})`;
+    return run;
+  }
+
+  private sessionCommandsOn(url: string): string[] {
+    if (!this.session) return [];
+    const { tests } = readSession(sessionFile(this.session.key));
+    return tests
+      .filter((test) => test.description?.split('\n')[0] === `page: ${url}` && !test.title.startsWith('ux'))
+      .map((test) => test.title)
+      .slice(-UX_SESSION_COMMANDS);
+  }
+
   private executedCodes(code: unknown): string[] {
     if (typeof code !== 'string') return [];
     return code

package/dist/bin/explorbot-cli.js

@@ -13,7 +13,7 @@ import { RecommendedModelsCommand } from '../src/commands/recommended-models-com
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
 import { decisionModelOption, knowledgeOption, wsOption } from '../src/commands/options/index.js';
-import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
+import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS, outputPath } from '../src/config.js';
 import { ExplorBot } from '../src/explorbot.js';
 import { remote } from '../src/remote.js';
 import { Stats } from '../src/stats.js';
@@ -94,6 +94,23 @@ async function startTUI(explorBot) {
         await cleanup();
     });
 }
+function printPageContext(explorBot) {
+    const state = explorBot?.stateManager().getCurrentState();
+    if (!state)
+        return;
+    const lines = [`Last page: ${state.fullUrl || state.url}`];
+    if (state.title)
+        lines.push(`Title: ${state.title}`);
+    if (state.screenshotFile)
+        lines.push(`Screenshot: file://${outputPath('states', state.screenshotFile)}`);
+    if (state.htmlFile)
+        lines.push(`HTML: file://${outputPath('states', state.htmlFile)}`);
+    if (state.ariaSnapshotFile)
+        lines.push(`ARIA: file://${outputPath('states', state.ariaSnapshotFile)}`);
+    if (state.ariaSnapshot)
+        lines.push('', state.ariaSnapshot);
+    console.error(lines.join('\n'));
+}
 async function showStatsAndExit(code) {
     if (remote.isAttached()) {
         await remote.close(code);
@@ -130,10 +147,11 @@ addCommonOptions(program
     .option('--focus <feature>', 'Focus area for exploration')
     .option('--configure <spec>', 'Reuse spec: keys new|from|style|subpages|pick_by|priority, e.g. "new:25%;pick_by=random;priority=critical,high"')
     .option('--dry-run', 'Mark picked tests as skipped without executing or generating new ones')).action(async (explorePath, options) => {
+    let explorBot;
     try {
         const urlFilter = new UrlFilter(options.urlFilter);
         const sitemapUrls = await readCliSitemap(explorePath, options.sitemap, urlFilter);
-        const explorBot = new ExplorBot(buildExplorBotOptions(explorePath || sitemapUrls?.[0], options));
+        explorBot = new ExplorBot(buildExplorBotOptions(explorePath || sitemapUrls?.[0], options));
         await explorBot.start();
         if (explorePath)
             await explorBot.visit(explorePath);
@@ -162,6 +180,7 @@ addCommonOptions(program
     }
     catch (error) {
         console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+        printPageContext(explorBot);
         await showStatsAndExit(1);
     }
 });
@@ -423,7 +442,14 @@ addCommonOptions(program
         .join(' ');
     const { FreesailCommand } = await import('../src/commands/freesail-command.js');
     const cmd = new FreesailCommand(explorBot);
-    await cmd.execute(args);
+    try {
+        await cmd.execute(args);
+    }
+    catch (error) {
+        console.error('Failed:', error instanceof Error ? error.message : 'Unknown error');
+        printPageContext(explorBot);
+        await showStatsAndExit(1);
+    }
 });
 program
     .command('config [url]')
@@ -452,6 +478,7 @@ program
     .option('-g, --global', 'Configure explorbot in ~/.explorbot to run from anywhere')
     .option('--provider <name>', `AI provider for the global config: ${Object.keys(PROVIDERS).join(', ')}`)
     .option('--api-key <key>', 'API key stored in ~/.explorbot/.env')
+    .option('--url <url>', 'Web application URL written to web.url in the local config')
     .action(async (options) => {
     try {
         const { runInit } = await import('../src/commands/init-command.js');
@@ -462,6 +489,7 @@ program
             global: options.global,
             provider: options.provider,
             apiKey: options.apiKey,
+            url: options.url,
         });
     }
     catch (error) {

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

@@ -4,7 +4,7 @@ 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 { askHelp, checkHelp, doHelp, helpContract, reportHelp, researchHelp, sessionHelp, statusHelp, uxHelp, verifyHelp } from "./help.js";
 import { Prima } from "./prima.js";
 let rootOptions = () => ({});
 function buildOptions(subcommand) {
@@ -120,6 +120,11 @@ export function createPrimaCommands(name = 'prima') {
         .action(async (options) => {
         await runPrima(options, 'research', (prima) => prima.research({ data: options.data, deep: options.deep, fresh: options.fresh }));
     });
+    addBrowserOptions(cmd.command('ux [focus]').description('Review the area being worked on for UX issues, across breakpoints'))
+        .addHelpText('after', `\n${uxHelp}`)
+        .action(async (focus, options) => {
+        await runPrima(options, ['ux', focus].filter(Boolean).join(' '), (prima) => prima.ux(focus));
+    });
     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;