explorbot 0.2.0 → 0.2.1

package/README.md

@@ -14,6 +14,8 @@ npx explorbot start https://your-app.com
 
 It runs with no babysitting and reports back what it finds. This is vibe-testing.
 
+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
@@ -92,7 +94,7 @@ 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/basics/prerequisites.md)
 
@@ -125,6 +127,19 @@ Type `/explore`, and Explorbot runs its loop on its own — research, plan, test
 
 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:
@@ -146,12 +161,13 @@ When you're ready to go deeper, the [full documentation](docs/) covers everythin
 ## 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.

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;
 }
 
@@ -690,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);
@@ -720,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();
@@ -876,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,6 +2,7 @@ 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';
@@ -11,11 +12,13 @@ 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, captureState?: CaptureInteractionState): Promise<PageDocumentation> {
@@ -46,7 +49,7 @@ class Documentarian {
     try {
       tag('info').log('Starting interactive exploration...');
 
-      const deterministicInteractions = await collectDocInteractions(this.explorer!, state, research, this.config, captureState);
+      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`);

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

@@ -1,6 +1,6 @@
 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';
 
@@ -58,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 = {}, captureState?: CaptureInteractionState): 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, captureState)));
+    transitions.push(...(await exploreTabGroup(explorer, stateManager, tabGroup, state.url, maxInteractions, captureState)));
   }
 
   for (const candidate of findActionCandidates(sections, config)) {
@@ -73,7 +73,7 @@ export async function collectDocInteractions(explorer: Explorer, state: WebPageS
       break;
     }
 
-    const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS, captureState);
+    const transition = await executeInteraction(explorer, stateManager, candidate, state.url, DEFAULT_WAIT_MS, captureState);
     if (!transition) {
       continue;
     }
@@ -92,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, captureState?: CaptureInteractionState): 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) {
@@ -102,6 +102,7 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
 
     const transition = await executeInteraction(
       explorer,
+      stateManager,
       {
         element,
         container: tabGroup.container,
@@ -123,8 +124,8 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
   return transitions;
 }
 
-async function executeInteraction(explorer: Explorer, candidate: InteractionCandidate, restoreUrl: string, waitMs: number, captureState?: CaptureInteractionState): 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;
   }
@@ -136,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;
   }
@@ -164,7 +165,7 @@ 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));
@@ -178,7 +179,7 @@ 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 action = explorer.action();
     const restored = await action.attempt(primaryCommand, `Restore initial state on ${restoreUrl}`);
     if (restored) {
       await wait(TAB_WAIT_MS);
@@ -186,7 +187,7 @@ async function restoreInteractionState(explorer: Explorer, restoreUrl: string, p
     }
   }
 
-  const action = explorer.createAction();
+  const action = explorer.action();
   await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 

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,
   };
 }

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

@@ -8,10 +8,10 @@ import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { Documentarian, type PageDocumentation } from './ai/documentarian.ts';
 import { type DocbotConfig, DocbotConfigParser } from './config.ts';
 import { type DocumentedPage, type SkippedPage, renderPageDocumentation, renderSpecIndex } from './docs-renderer.ts';
-import { renderMermaidBody } from './state-diagram.ts';
 import { getDocPageKey, shouldCrawlDocPath } from './path-filter.ts';
 import { extractResearchNavigationTargets } from './research-navigation.ts';
 import { type DocumentationScreenshot, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
+import { renderMermaidBody } from './state-diagram.ts';
 
 class DocBot {
   private explorBot: ExplorBot;
@@ -43,7 +43,7 @@ class DocBot {
       config: this.options.docsConfig,
       path: this.options.path,
     });
-    this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer());
+    this.documentarian = new Documentarian(this.explorBot.getProvider(), this.config, this.explorBot.getExplorer(), this.explorBot.stateManager());
     this.ensureDirectory(this.configParser.getOutputDir());
     this.ensureDirectory(this.getPagesDir());
   }
@@ -76,7 +76,7 @@ class DocBot {
         continue;
       }
 
-      const stateManager = this.explorBot.getExplorer().getStateManager();
+      const stateManager = this.explorBot.stateManager();
       if (stateManager.hasVisitedState(target)) {
         continue;
       }

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

@@ -11,7 +11,7 @@ import type { DocbotConfig } from './config.ts';
 const DEFAULT_MAX_SECTION_SCREENSHOTS = 8;
 
 export async function captureDocumentationScreenshots(explorer: Explorer, state: WebPageState, research: string, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot[]> {
-  const page = explorer.playwrightHelper?.page;
+  const page = explorer.page;
   if (!page) {
     return [];
   }
@@ -62,7 +62,7 @@ export function getScreenshotSections(research: string): ScreenshotSection[] {
 }
 
 export async function captureInteractionScreenshot(explorer: Explorer, state: WebPageState, transition: DocStateTransition, options: DocumentationScreenshotOptions): Promise<DocumentationScreenshot | null> {
-  const page = explorer.playwrightHelper?.page;
+  const page = explorer.page;
   if (!page) {
     return null;
   }

package/dist/bin/explorbot-cli.js

@@ -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 } from '../src/explorbot.js';
 import { Stats } from '../src/stats.js';
 import { Plan } from '../src/test-plan.js';
@@ -27,7 +27,6 @@ if (!process.env.EXPLORBOT_NO_BANNER) {
     console.log(`⛵ ${chalk.yellow.bold(`Explorbot v${pkgVersion}`)} ${chalk.dim('Autonomous Testing Agent')}`);
 }
 function buildExplorBotOptions(from, options) {
-    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,
@@ -36,7 +35,7 @@ function buildExplorBotOptions(from, options) {
         show: options.show,
         headless: options.headless,
         incognito: options.incognito,
-        session: sessionFile,
+        session: options.session,
     };
 }
 function addCommonOptions(cmd) {
@@ -623,7 +622,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);
         await explorBot.start();
@@ -652,10 +651,10 @@ addCommonOptions(program.command('shell <url> <command>').description('Execute a
         const explorBot = new ExplorBot(buildExplorBotOptions(url, options));
         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();
@@ -793,4 +792,25 @@ import { createApiCommands } from "../boat/api-tester/src/cli.js";
 import { createDocsCommands } from "../boat/doc-collector/src/cli.js";
 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) => {
+    cmd.addHelpText('after', envHelp);
+    for (const sub of cmd.commands)
+        addEnvHelp(sub);
+};
+addEnvHelp(program);
 program.parse();

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

@@ -9,7 +9,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path, { resolve } from 'node:path';
 import { parseEnv } from 'node:util';
-import { EXPLORBOT_CONFIG_PATHS } from "../../../src/config.js";
+import { EXPLORBOT_CONFIG_PATHS, createModel, materializeKnowledge, resolveModel, resolveOutputRoot } from "../../../src/config.js";
 export class ApibotConfigParser {
     static instance;
     config = null;
@@ -37,9 +37,13 @@ export class ApibotConfigParser {
         ApibotConfigParser.loadEnv('.env');
         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 {
             const configModule = await this.loadConfigModule(resolvedPath);
@@ -98,6 +102,41 @@ export class ApibotConfigParser {
             mkdirSync(dirPath, { recursive: true });
         }
     }
+    async loadEnvConfig() {
+        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 = { baseEndpoint };
+        if (process.env.EXPLORBOT_API_SPEC) {
+            api.spec = [process.env.EXPLORBOT_API_SPEC];
+        }
+        let model;
+        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;
+    }
     findConfigFile() {
         const apibotPaths = ['apibot.config.js', 'apibot.config.mjs', 'apibot.config.ts'];
         for (const p of apibotPaths) {

package/dist/boat/doc-collector/src/ai/documentarian.js

@@ -6,10 +6,12 @@ class Documentarian {
     provider;
     config;
     explorer;
-    constructor(provider, config = {}, explorer) {
+    stateManager;
+    constructor(provider, config = {}, explorer, stateManager) {
         this.provider = provider;
         this.config = config;
         this.explorer = explorer;
+        this.stateManager = stateManager;
     }
     async document(state, research, captureState) {
         const interactiveEnabled = this.config.docs?.interactive === true && this.explorer;
@@ -35,7 +37,7 @@ class Documentarian {
         let meaningfulInteractions = [];
         try {
             tag('info').log('Starting interactive exploration...');
-            const deterministicInteractions = await collectDocInteractions(this.explorer, state, research, this.config, captureState);
+            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`);

package/dist/boat/doc-collector/src/ai/tools.js

@@ -6,19 +6,19 @@ const MAX_LINKS = 15;
 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, state, research, config = {}, captureState) {
+export async function collectDocInteractions(explorer, stateManager, state, research, config = {}, captureState) {
     const sections = parseResearchSections(research);
     const transitions = [];
     const maxInteractions = getPositiveConfigNumber(config.docs?.maxInteractions, DEFAULT_MAX_INTERACTIONS);
     const tabGroup = findTabGroup(sections);
     if (tabGroup) {
-        transitions.push(...(await exploreTabGroup(explorer, tabGroup, state.url, maxInteractions, captureState)));
+        transitions.push(...(await exploreTabGroup(explorer, stateManager, tabGroup, state.url, maxInteractions, captureState)));
     }
     for (const candidate of findActionCandidates(sections, config)) {
         if (transitions.length >= maxInteractions) {
             break;
         }
-        const transition = await executeInteraction(explorer, candidate, state.url, DEFAULT_WAIT_MS, captureState);
+        const transition = await executeInteraction(explorer, stateManager, candidate, state.url, DEFAULT_WAIT_MS, captureState);
         if (!transition) {
             continue;
         }
@@ -33,13 +33,13 @@ export function pickDocActionCandidates(research, config = {}) {
         section: candidate.sectionName,
     }));
 }
-async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions, captureState) {
+async function exploreTabGroup(explorer, stateManager, tabGroup, restoreUrl, maxInteractions, captureState) {
     const transitions = [];
     for (const element of tabGroup.elements) {
         if (transitions.length >= maxInteractions) {
             break;
         }
-        const transition = await executeInteraction(explorer, {
+        const transition = await executeInteraction(explorer, stateManager, {
             element,
             container: tabGroup.container,
             role: 'tab',
@@ -53,8 +53,8 @@ async function exploreTabGroup(explorer, tabGroup, restoreUrl, maxInteractions,
     await restoreInteractionState(explorer, restoreUrl, buildPrimaryCommand(tabGroup.elements[0], tabGroup.container));
     return transitions;
 }
-async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captureState) {
-    const beforeState = explorer.getStateManager().getCurrentState();
+async function executeInteraction(explorer, stateManager, candidate, restoreUrl, waitMs, captureState) {
+    const beforeState = stateManager.getCurrentState();
     if (!beforeState) {
         return null;
     }
@@ -63,7 +63,7 @@ async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captu
         return null;
     }
     await wait(waitMs);
-    const afterState = explorer.getStateManager().getCurrentState();
+    const afterState = stateManager.getCurrentState();
     if (!afterState) {
         return null;
     }
@@ -86,7 +86,7 @@ async function executeInteraction(explorer, candidate, restoreUrl, waitMs, captu
     return transition;
 }
 async function attemptInteraction(explorer, candidate) {
-    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));
         if (success) {
@@ -97,14 +97,14 @@ async function attemptInteraction(explorer, candidate) {
 }
 async function restoreInteractionState(explorer, restoreUrl, primaryCommand) {
     if (primaryCommand) {
-        const action = explorer.createAction();
+        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();
+    const action = explorer.action();
     await action.attempt(`I.amOnPage(${JSON.stringify(restoreUrl)})`, `Restore page ${restoreUrl}`);
 }
 function buildTransition(candidate, beforeState, afterState, changes) {