explorbot 0.1.32-beta.1 → 0.2.1

package/README.md

@@ -14,7 +14,9 @@ npx explorbot start https://your-app.com
 
 It runs with no babysitting and reports back what it finds. This is vibe-testing.
 
-New here? Read the [Getting Started guide](docs/getting-started.md).
+Explorbot works with any AI provider through the [Vercel AI SDK](https://sdk.vercel.ai/providers). See [`models.json`](models.json) for the current recommended provider and model setup, and [Providers](docs/basics/providers.md) for how to configure each one.
+
+New here? Read the [Getting Started guide](docs/basics/getting-started.md).
 
 ## Use Cases
 
@@ -54,11 +56,11 @@ Cheap, fast workers do the clicking and reading; smart managers make the calls
 
 | | | |
 |---|---|---|
-| [Researcher](docs/reference/agents.md) | [Planner](docs/reference/agents.md) | [Tester](docs/reference/agents.md) |
-| [Pilot](docs/reference/agents.md) | [Captain](docs/reference/agents.md) | [Navigator](docs/reference/agents.md) |
-| [Analyst](docs/reference/agents.md) | [Historian](docs/reference/agents.md) | [Fisherman](docs/reference/agents.md) |
+| [Researcher](docs/web-testing/agents.md) | [Planner](docs/web-testing/agents.md) | [Tester](docs/web-testing/agents.md) |
+| [Pilot](docs/web-testing/agents.md) | [Captain](docs/web-testing/agents.md) | [Navigator](docs/web-testing/agents.md) |
+| [Analyst](docs/web-testing/agents.md) | [Historian](docs/web-testing/agents.md) | [Fisherman](docs/web-testing/agents.md) |
 
-See [Agents](docs/reference/agents.md) for what each one does.
+See [Agents](docs/web-testing/agents.md) for what each one does.
 
 ## Core Philosophy
 
@@ -74,7 +76,7 @@ See [Agents](docs/reference/agents.md) for what each one does.
 
 When tuned, Explorbot **runs autonomously for hours**, trying new scenarios on its own. The more it runs, the more it learns.
 
-## What you get
+## Tests, reports, videos
 
 Every run leaves behind:
 
@@ -83,7 +85,7 @@ Every run leaves behind:
 - **Videos** — step-by-step screencasts of every run.
 - **Experience** — what Explorbot learned, reused to test smarter next time.
 
-See [Automated Tests](docs/guides/automated-tests.md) for the test output and [Reporting](docs/guides/reporting.md) for reports.
+See [Automated Tests](docs/web-testing/automated-tests.md) for the test output and [Reporting](docs/workflow/reporting.md) for reports.
 
 ## It works with your suite
 
@@ -92,9 +94,9 @@ Explorbot won't replace your regression tests — it covers what they can't. You
 ## Requirements
 
 - Node.js 24+ or **Bun**
-- An **AI provider key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, and others via the [Vercel AI SDK](https://sdk.vercel.ai/providers)
+- An **AI provider key** — OpenRouter recommended; Groq, Cerebras, [OpenAI](docs/basics/providers.md#openai), Anthropic, and others via the [Vercel AI SDK](https://sdk.vercel.ai/providers)
 - A **modern terminal** — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL
-- A **compatible web app** — CRUD-heavy apps fit best. See [Prerequisites](docs/reference/prerequisites.md)
+- A **compatible web app** — CRUD-heavy apps fit best. See [Prerequisites](docs/basics/prerequisites.md)
 
 If your CI runs Playwright, it runs Explorbot. No GPUs, no special runners.
 
@@ -123,35 +125,49 @@ npx explorbot start /admin/users
 
 Type `/explore`, and Explorbot runs its loop on its own — research, plan, test, repeat — learning from every run.
 
-That's the gist. The [**Getting Started guide**](docs/getting-started.md) walks through the full setup — choosing models, teaching Explorbot to log in, and picking the right feature to start on.
+That's the gist. The [**Getting Started guide**](docs/basics/getting-started.md) walks through the full setup — choosing models, teaching Explorbot to log in, and picking the right feature to start on.
+
+### Or skip the config file
+
+For a CI job, a demo, or a coding agent, pass everything as environment variables. Name a provider and Explorbot picks its recommended models:
+
+```bash
+EXPLORBOT_URL=https://app.example.com \
+EXPLORBOT_AI_PROVIDER=openrouter \
+EXPLORBOT_KNOWLEDGE="Log in as admin@example.com / secret123" \
+  npx explorbot explore /admin/users --max-tests 3
+```
+
+Output lands in a temp directory and nothing is written to your project. See [Agentic Usage](docs/workflow/agentic-usage.md).
 
 ## Teaching Explorbot
 
 Explorbot gets better when you tell it about your app:
 
-- **Knowledge** — credentials, form rules, navigation quirks. See [Knowledge](docs/guides/knowledge.md).
+- **Knowledge** — credentials, form rules, navigation quirks. See [Knowledge](docs/workflow/knowledge.md).
 - **Rules** — per-agent, per-page instructions. See [Configuration](docs/reference/configuration.md#rules).
 - **Experience** — learned automatically from what works.
 
-Handling logins, cookie banners, modals, and test data takes a few lines — see [Customization](docs/guides/customization.md).
+Handling logins, cookie banners, modals, and test data takes a few lines — see [Customization](docs/web-testing/customization.md).
 
 ## It also tests REST APIs
 
-Point Explorbot at an OpenAPI spec and it plans and runs API tests too. See [API Testing](docs/guides/api-testing.md).
+Point Explorbot at an OpenAPI spec and it plans and runs API tests too. See [API Testing](docs/api-testing/basics.md).
 
 ## Keep going
 
-When you're ready to go deeper, the [full documentation](docs/README.md) covers everything, starting with the [Getting Started guide](docs/getting-started.md).
+When you're ready to go deeper, the [full documentation](docs/) covers everything, starting with the [Getting Started guide](docs/basics/getting-started.md).
 
 ## FAQ
 
 **Can I run it in Cursor or Claude Code?**
-No, Explorbot is a separate application designed for constant testing. Cursor, Codex, and Claude Code are coding agents — not relevant here.
-
-> However, Explorbot can be used as a subagent or terminal command controlled by a coding agent.
+Not as a replacement — Explorbot is a separate application designed for constant testing, while Cursor, Codex, and Claude Code are coding agents. But a coding agent can drive Explorbot as a terminal command or subagent: it writes the test plan, Explorbot executes it against the real app. See [Agentic Usage](docs/workflow/agentic-usage.md).
 
 **Can I bring a Cursor or OpenAI subscription?**
-No. Their models are too slow for the way Explorbot works. Use pay-per-token providers like Groq and OpenRouter.
+No. Explorbot needs an API key, not a chat subscription. Use pay-per-token access — Groq, OpenRouter, or OpenAI's own API.
+
+**Can I use OpenAI directly?**
+Yes. Add your `OPENAI_API_KEY` and point the models at OpenAI — a nano-class model for `model` and `visionModel`, a stronger one for `agenticModel`. Expect it to run a bit slower than hosted OSS models on Groq or Cerebras. See [Providers](docs/basics/providers.md#openai) for the config.
 
 **I want to use Opus!!!**
 Opus is great for coding. Testing needs a simpler model that can safely consume lots of HTML tokens, fast. Save the expensive models for sophisticated decision-making.
@@ -163,7 +179,7 @@ No. With fast open models (e.g. `openai/gpt-oss-20b` on OpenRouter or Groq), exp
 Not yet.
 
 **Can I build my own agents with it?**
-Yes, use the programmatic API. See [Scripting](docs/contributing/scripting.md).
+Yes, use the programmatic API. See [Scripting](docs/reference/scripting.md).
 
 **Can I do the same in Cursor with Playwright MCP?**
 Good luck running it on CI!

package/bin/explorbot-cli.ts

@@ -9,7 +9,7 @@ import { render } from 'ink';
 import React from 'react';
 import { App } from '../src/components/App.js';
 import { StatusPane } from '../src/components/StatusPane.js';
-import { ConfigParser } from '../src/config.js';
+import { ConfigParser, EXPLORBOT_ENV_VARS, PROVIDERS } from '../src/config.js';
 import { ExplorBot, type ExplorBotOptions } from '../src/explorbot.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
@@ -43,8 +43,6 @@ interface CLIOptions {
 }
 
 function buildExplorBotOptions(from: string | undefined, options: CLIOptions): ExplorBotOptions {
-  const sessionFile = options.session === true ? path.join(path.resolve(options.path || process.cwd()), 'output', 'session.json') : options.session;
-
   return {
     from,
     verbose: options.verbose || options.debug,
@@ -53,7 +51,7 @@ function buildExplorBotOptions(from: string | undefined, options: CLIOptions): E
     show: options.show,
     headless: options.headless,
     incognito: options.incognito,
-    session: sessionFile,
+    session: options.session,
   } as ExplorBotOptions;
 }
 
@@ -509,9 +507,10 @@ program
         path: options.path || process.cwd(),
       });
 
+      const { KnowledgeTracker } = await import('../src/knowledge-tracker.js');
+      const tracker = new KnowledgeTracker();
+
       if (url && description) {
-        const { KnowledgeTracker } = await import('../src/knowledge-tracker.js');
-        const tracker = new KnowledgeTracker();
         const result = tracker.addKnowledge(url, description);
         const action = result.isNewFile ? 'Created' : 'Updated';
         console.log(`Knowledge ${action} in: ${result.filename}`);
@@ -519,7 +518,7 @@ program
       }
 
       const AddKnowledge = (await import('../src/components/AddKnowledge.js')).default;
-      render(React.createElement(AddKnowledge, { initialUrl: url || '' }), {
+      render(React.createElement(AddKnowledge, { initialUrl: url || '', knowledgeTracker: tracker }), {
         exitOnCtrlC: false,
         patchConsole: false,
       });
@@ -689,7 +688,7 @@ program
         path: options.path,
         config: options.config,
         headless: true,
-        session: options.session === true ? 'output/session.json' : options.session,
+        session: options.session,
       };
 
       const explorBot = new ExplorBot(mainOptions);
@@ -719,11 +718,11 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
     await explorBot.start();
     await explorBot.agentNavigator().visit(url);
 
-    const action = explorBot.getExplorer().createAction();
+    const action = explorBot.getExplorer().action();
     await action.execute(command);
 
     log('Command executed successfully');
-    const state = explorBot.getExplorer().getStateManager().getCurrentState();
+    const state = explorBot.stateManager().getCurrentState();
     if (state) log(`URL: ${state.url}`);
 
     await explorBot.stop();
@@ -875,4 +874,28 @@ import { createDocsCommands } from '../boat/doc-collector/src/cli.ts';
 program.addCommand(createApiCommands('api'));
 program.addCommand(createDocsCommands('docs'));
 
+const envHelp = () => {
+  const width = Math.max(...EXPLORBOT_ENV_VARS.map((v) => v.name.length));
+  const rows = EXPLORBOT_ENV_VARS.map((v) => `  ${v.name.padEnd(width)}  ${v.description}`).join('\n');
+
+  return `
+Environment variables (config-free one-liner mode):
+  Set EXPLORBOT_AI_PROVIDER to run without an explorbot.config.js. A config file always wins.
+
+${rows}
+
+  Providers: ${Object.keys(PROVIDERS).join(', ')}
+  Example:
+    EXPLORBOT_URL=https://app.example.com EXPLORBOT_AI_PROVIDER=openrouter \\
+      ${cli} explore /login --max-tests 3
+`;
+};
+
+const addEnvHelp = (cmd: Command) => {
+  cmd.addHelpText('after', envHelp);
+  for (const sub of cmd.commands) addEnvHelp(sub);
+};
+
+addEnvHelp(program);
+
 program.parse();

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

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { parseEnv } from 'node:util';
-import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, EXPLORBOT_CONFIG_PATHS } from '../../../src/config.ts';
+import { type AIConfig, type ApiHookFn, type ApiConfig as BaseApiConfig, EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from '../../../src/config.ts';
 
 export type { AIConfig };
 
@@ -54,8 +54,11 @@ export class ApibotConfigParser {
 
     const resolvedPath = options?.config || this.findConfigFile();
     if (!resolvedPath) {
-      if (options?.path) process.chdir(originalCwd);
-      throw new Error('No configuration file found. Create apibot.config.js or apibot.config.ts');
+      try {
+        return await this.loadEnvConfig();
+      } finally {
+        if (options?.path && originalCwd !== process.cwd()) process.chdir(originalCwd);
+      }
     }
 
     try {
@@ -123,6 +126,45 @@ export class ApibotConfigParser {
     }
   }
 
+  private async loadEnvConfig(): Promise<ApibotConfig> {
+    const provider = process.env.EXPLORBOT_AI_PROVIDER;
+    const modelSpec = process.env.EXPLORBOT_AI_MODEL;
+    if (!provider && !modelSpec) {
+      throw new Error('No configuration file found. Create apibot.config.js or set EXPLORBOT_URL and EXPLORBOT_AI_PROVIDER environment variables');
+    }
+    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;
+    if (!baseEndpoint) {
+      throw new Error('No API endpoint to test. Set EXPLORBOT_URL to the API base endpoint');
+    }
+
+    const outputRoot = resolveOutputRoot();
+    materializeKnowledge(outputRoot);
+
+    const api: ApiConfig = { baseEndpoint };
+    if (process.env.EXPLORBOT_API_SPEC) {
+      api.spec = [process.env.EXPLORBOT_API_SPEC];
+    }
+
+    let model: any;
+    if (provider && modelSpec) model = await createModel(provider, modelSpec);
+    if (provider && !modelSpec) model = await resolveModel(provider, 'model');
+    if (!provider) model = await resolveModel(modelSpec!, 'model');
+
+    this.config = {
+      ai: { model },
+      api,
+      dirs: { output: '.', knowledge: 'knowledge' },
+    };
+    this.configPath = path.join(outputRoot, 'apibot.config.js');
+    this.validateConfig(this.config);
+
+    return this.config;
+  }
+
   private findConfigFile(): string | null {
     const apibotPaths = ['apibot.config.js', 'apibot.config.mjs', 'apibot.config.ts'];
     for (const p of apibotPaths) {

package/boat/doc-collector/src/ai/documentarian.ts

@@ -2,23 +2,26 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import type { AIProvider } from '../../../../src/ai/provider.ts';
 import type Explorer from '../../../../src/explorer.ts';
+import type { StateManager } from '../../../../src/state-manager.ts';
 import type { WebPageState } from '../../../../src/state-manager.ts';
 import { tag } from '../../../../src/utils/logger.ts';
 import type { DocbotConfig } from '../config.ts';
-import { collectDocInteractions } from './tools.ts';
+import { type CaptureInteractionState, type DocStateTransition, collectDocInteractions } from './tools.ts';
 
 class Documentarian {
   private provider: AIProvider;
   private config: DocbotConfig;
   private explorer?: Explorer;
+  private stateManager?: StateManager;
 
-  constructor(provider: AIProvider, config: DocbotConfig = {}, explorer?: Explorer) {
+  constructor(provider: AIProvider, config: DocbotConfig = {}, explorer?: Explorer, stateManager?: StateManager) {
     this.provider = provider;
     this.config = config;
     this.explorer = explorer;
+    this.stateManager = stateManager;
   }
 
-  async document(state: WebPageState, research: string): Promise<PageDocumentation> {
+  async document(state: WebPageState, research: string, captureState?: CaptureInteractionState): Promise<PageDocumentation> {
     const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
     if (!interactiveEnabled) {
       tag('info').log('Documentarian: Using static mode (interactive disabled or no explorer)');
@@ -26,7 +29,7 @@ class Documentarian {
     }
 
     tag('info').log('Documentarian: Using interactive mode with tools');
-    return this.documentWithInteraction(state, research);
+    return this.documentWithInteraction(state, research, captureState);
   }
 
   private async documentStatic(state: WebPageState, research: string): Promise<PageDocumentation> {
@@ -41,12 +44,13 @@ class Documentarian {
     }
   }
 
-  private async documentWithInteraction(state: WebPageState, research: string): Promise<PageDocumentation> {
+  private async documentWithInteraction(state: WebPageState, research: string, captureState?: CaptureInteractionState): Promise<PageDocumentation> {
+    let meaningfulInteractions: StateTransition[] = [];
     try {
       tag('info').log('Starting interactive exploration...');
 
-      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research, this.config);
-      const meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
+      const deterministicInteractions = await collectDocInteractions(this.explorer!, this.stateManager!, state, research, this.config, captureState);
+      meaningfulInteractions = this.getMeaningfulInteractions(deterministicInteractions);
       if (meaningfulInteractions.length > 0) {
         tag('success').log(`Collected ${meaningfulInteractions.length} deterministic interactions`);
         return await this.generateDocumentationWithInteractions(state, research, meaningfulInteractions);
@@ -61,7 +65,20 @@ class Documentarian {
       return this.documentStatic(state, research);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      tag('warning').log(`Interactive documentation failed: ${message}. Falling back to static.`);
+      tag('warning').log(`Interactive documentation failed: ${message}.`);
+      if (meaningfulInteractions.length > 0) {
+        tag('info').log(`Preserving ${meaningfulInteractions.length} observed interaction(s) without AI summary.`);
+        return this.normalizeDocumentation(
+          {
+            summary: `Observed ${meaningfulInteractions.length} interaction(s); AI-generated summary was unavailable.`,
+            can: [],
+            might: [],
+            interactions: meaningfulInteractions,
+          },
+          state,
+          research
+        );
+      }
       return this.documentStatic(state, research);
     }
   }
@@ -354,26 +371,7 @@ const pageDocumentationSchema = z.object({
   interactions: z.array(stateTransitionSchema).nullable(),
 });
 
-type StateTransition = {
-  action: string;
-  before: string;
-  after: string;
-  targetUrl?: string | null;
-  discoveredUrls?: string[] | null;
-  newCapabilities?: string[] | null;
-  element?: {
-    role: string;
-    name: string;
-    section: string;
-    container?: string | null;
-    locator?: string | null;
-  } | null;
-  changes?: {
-    urlChanged: boolean;
-    newElements: number;
-    removedElements: number;
-  } | null;
-};
+type StateTransition = DocStateTransition;
 type PageDocumentation = Omit<z.infer<typeof pageDocumentationSchema>, 'interactions'> & {
   interactions?: StateTransition[];
   qualityNotes?: string[];

package/boat/doc-collector/src/ai/tools.ts

@@ -1,6 +1,7 @@
 import { type ResearchElement, parseResearchSections } from '../../../../src/ai/researcher/parser.ts';
 import type Explorer from '../../../../src/explorer.ts';
-import type { WebPageState } from '../../../../src/state-manager.ts';
+import type { StateManager, WebPageState } from '../../../../src/state-manager.ts';
+import { detectFocusArea } from '../../../../src/utils/aria.ts';
 import type { DocbotConfig } from '../config.ts';
 
 export interface DocStateTransition {
@@ -12,6 +13,8 @@ export interface DocStateTransition {
   newCapabilities?: string[];
   element?: InteractionElement;
   changes?: InteractionChanges;
+  targetState?: InteractionState;
+  screenshot?: InteractionScreenshot;
 }
 
 interface InteractionCandidate {
@@ -35,6 +38,19 @@ interface InteractionChanges {
   removedElements: number;
 }
 
+export interface InteractionState {
+  kind: 'page' | 'dialog' | 'modal' | 'section';
+  label: string;
+  url: string;
+}
+
+export interface InteractionScreenshot {
+  title: string;
+  relativePath: string;
+}
+
+export type CaptureInteractionState = (state: WebPageState, transition: DocStateTransition) => Promise<InteractionScreenshot | null>;
+
 const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
 const DEFAULT_MAX_INTERACTIONS = 5;
 const MAX_LINKS = 15;
@@ -42,14 +58,14 @@ const DEFAULT_WAIT_MS = 700;
 const TAB_WAIT_MS = 500;
 const DEFAULT_DENIED_ACTION_LABELS = ['delete', 'remove', 'destroy', 'archive', 'discard', 'logout', 'sign out', 'signout', 'sign_out', 'erase', 'drop'];
 
-export async function collectDocInteractions(explorer: Explorer, state: WebPageState, research: string, config: DocbotConfig = {}): Promise<DocStateTransition[]> {
+export async function collectDocInteractions(explorer: Explorer, stateManager: StateManager, state: WebPageState, research: string, config: DocbotConfig = {}, captureState?: CaptureInteractionState): Promise<DocStateTransition[]> {
   const sections = parseResearchSections(research);
   const transitions: DocStateTransition[] = [];
   const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
   const tabGroup = findTabGroup(sections);
 
   if (tabGroup) {
-    transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions)));
+    transitions.push(...(await exploreTabGroup(explorer, stateManager, tabGroup, state.url, maxInteractions, captureState)));
   }
 
   for (const candidate of findActionCandidates(sections, config)) {
@@ -57,7 +73,7 @@ export async function collectDocInteractions(explorer: Explorer, state: WebPageS
       break;
     }
 
-    const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS);
+    const transition = await executeInteraction(explorer, stateManager, candidate, state.url, DEFAULT_WAIT_MS, captureState);
     if (!transition) {
       continue;
     }
@@ -76,7 +92,7 @@ export function pickDocActionCandidates(research: string, config: DocbotConfig =
   }));
 }
 
-async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string, maxInteractions: number): Promise<DocStateTransition[]> {
+async function exploreTabGroup(explorer: Explorer, stateManager: StateManager, tabGroup: { elements: ResearchElement[]; container?: string; sectionName: string }, restoreUrl: string, maxInteractions: number, captureState?: CaptureInteractionState): Promise<DocStateTransition[]> {
   const transitions: DocStateTransition[] = [];
 
   for (const element of tabGroup.elements) {
@@ -86,6 +102,7 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
 
     const transition = await executeInteraction(
       explorer,
+      stateManager,
       {
         element,
         container: tabGroup.container,
@@ -93,7 +110,8 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
         sectionName: tabGroup.sectionName,
       },
       restoreUrl,
-      TAB_WAIT_MS
+      TAB_WAIT_MS,
+      captureState
     );
     if (!transition) {
       continue;
@@ -106,8 +124,8 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
   return transitions;
 }
 
-async function executeInteraction(explorer: Explorer, candidate: InteractionCandidate, restoreUrl: string, waitMs: number): Promise<DocStateTransition | null> {
-  const beforeState = explorer.getStateManager().getCurrentState();
+async function executeInteraction(explorer: Explorer, stateManager: StateManager, candidate: InteractionCandidate, restoreUrl: string, waitMs: number, captureState?: CaptureInteractionState): Promise<DocStateTransition | null> {
+  const beforeState = stateManager.getCurrentState();
   if (!beforeState) {
     return null;
   }
@@ -119,7 +137,7 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
 
   await wait(waitMs);
 
-  const afterState = explorer.getStateManager().getCurrentState();
+  const afterState = stateManager.getCurrentState();
   if (!afterState) {
     return null;
   }
@@ -132,7 +150,14 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
     removedElements: ariaChanges.removedCount,
   });
 
-  if (urlChanged) {
+  if (captureState && isMeaningfulStateTransition(transition)) {
+    const screenshot = await captureState(afterState, transition);
+    if (screenshot) {
+      transition.screenshot = screenshot;
+    }
+  }
+
+  if (urlChanged || ariaChanges.newCount > 0) {
     await restoreInteractionState(explorer, restoreUrl);
   }
 
@@ -140,10 +165,10 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
 }
 
 async function attemptInteraction(explorer: Explorer, candidate: InteractionCandidate): Promise<boolean> {
-  const action = explorer.createAction();
+  const action = explorer.action();
 
   for (const command of buildClickCommands(candidate.element, candidate.container)) {
-    const success = await action.attempt(command, buildPurpose(candidate), false);
+    const success = await action.attempt(command, buildPurpose(candidate));
     if (success) {
       return true;
     }
@@ -154,16 +179,16 @@ async function attemptInteraction(explorer: Explorer, candidate: InteractionCand
 
 async function restoreInteractionState(explorer: Explorer, restoreUrl: string, primaryCommand?: string | null): Promise<void> {
   if (primaryCommand) {
-    const action = explorer.createAction();
-    const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`, false);
+    const action = explorer.action();
+    const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`);
     if (restored) {
       await wait(TAB_WAIT_MS);
       return;
     }
   }
 
-  const action = explorer.createAction();
-  await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`, false);
+  const action = explorer.action();
+  await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 
 function buildTransition(candidate: InteractionCandidate, beforeState: WebPageState, afterState: WebPageState, changes: InteractionChanges): DocStateTransition {
@@ -175,6 +200,7 @@ function buildTransition(candidate: InteractionCandidate, beforeState: WebPageSt
     newCapabilities: collectDiscoveryNotes(afterState, changes),
     element: buildInteractionElement(candidate),
     changes,
+    targetState: describeTargetState(beforeState, afterState, candidate),
   };
 
   if (changes.urlChanged) {
@@ -184,6 +210,38 @@ function buildTransition(candidate: InteractionCandidate, beforeState: WebPageSt
   return transition;
 }
 
+function describeTargetState(beforeState: WebPageState, afterState: WebPageState, candidate: InteractionCandidate): InteractionState {
+  const beforeFocus = detectFocusArea(beforeState.ariaSnapshot || null);
+  const afterFocus = detectFocusArea(afterState.ariaSnapshot || null);
+  if (afterFocus.detected && (!beforeFocus.detected || beforeFocus.name !== afterFocus.name)) {
+    return {
+      kind: afterFocus.type || 'dialog',
+      label: afterFocus.name || candidate.element.name.trim(),
+      url: afterState.url,
+    };
+  }
+
+  const beforePath = beforeState.url.split('?')[0].split('#')[0];
+  const afterPath = afterState.url.split('?')[0].split('#')[0];
+  const headings = collectHeadings(afterState);
+  let kind: InteractionState['kind'] = 'page';
+  if (beforePath === afterPath) {
+    kind = 'section';
+  }
+  return {
+    kind,
+    label: headings[0] || afterState.title || candidate.element.name.trim(),
+    url: afterState.url,
+  };
+}
+
+function isMeaningfulStateTransition(transition: DocStateTransition): boolean {
+  if (transition.targetUrl || transition.changes?.urlChanged) {
+    return true;
+  }
+  return (transition.changes?.newElements || 0) > 0;
+}
+
 function buildInteractionElement(candidate: InteractionCandidate): InteractionElement {
   const element: InteractionElement = {
     role: candidate.role,

package/boat/doc-collector/src/cli.ts

@@ -5,11 +5,6 @@ import { setPreserveConsoleLogs } from '../../../src/utils/logger.ts';
 import { DocBot, type DocbotOptions } from './docbot.ts';
 
 function buildOptions(options: any): DocbotOptions {
-  let session = options.session;
-  if (options.session === true) {
-    session = 'output/session.json';
-  }
-
   return {
     verbose: options.verbose || options.debug,
     config: options.config,
@@ -17,7 +12,7 @@ function buildOptions(options: any): DocbotOptions {
     show: options.show,
     headless: options.headless,
     incognito: options.incognito,
-    session,
+    session: options.session,
     docsConfig: options.docsConfig,
   };
 }