explorbot 0.2.0 → 0.2.2

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`);
@@ -91,6 +94,9 @@ class Documentarian {
       if ((interaction.changes?.newElements || 0) > 0) {
         return true;
       }
+      if ((interaction.changes?.removedElements || 0) > 0) {
+        return true;
+      }
       return (interaction.discoveredUrls || []).length > 0;
     });
   }

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';
 
@@ -49,7 +49,10 @@ export interface InteractionScreenshot {
   relativePath: string;
 }
 
-export type CaptureInteractionState = (state: WebPageState, transition: DocStateTransition) => Promise<InteractionScreenshot | null>;
+export interface CaptureInteractionState {
+  before(): Promise<Buffer | null>;
+  after(beforeScreenshot: Buffer | null, state: WebPageState, transition: DocStateTransition): Promise<InteractionScreenshot | null>;
+}
 
 const DEFAULT_MAX_PRIMARY_CANDIDATES = 3;
 const DEFAULT_MAX_INTERACTIONS = 5;
@@ -58,14 +61,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 +76,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 +95,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 +105,7 @@ async function exploreTabGroup(explorer: Explorer, tabGroup: { elements: Researc
 
     const transition = await executeInteraction(
       explorer,
+      stateManager,
       {
         element,
         container: tabGroup.container,
@@ -123,12 +127,14 @@ 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;
   }
 
+  const beforeScreenshot = await captureState?.before();
+
   const executed = await attemptInteraction(explorer, candidate);
   if (!executed) {
     return null;
@@ -136,7 +142,7 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
 
   await wait(waitMs);
 
-  const afterState = explorer.getStateManager().getCurrentState();
+  const afterState = stateManager.getCurrentState();
   if (!afterState) {
     return null;
   }
@@ -150,13 +156,13 @@ async function executeInteraction(explorer: Explorer, candidate: InteractionCand
   });
 
   if (captureState && isMeaningfulStateTransition(transition)) {
-    const screenshot = await captureState(afterState, transition);
+    const screenshot = await captureState.after(beforeScreenshot ?? null, afterState, transition);
     if (screenshot) {
       transition.screenshot = screenshot;
     }
   }
 
-  if (urlChanged || ariaChanges.newCount > 0) {
+  if (urlChanged || ariaChanges.newCount > 0 || ariaChanges.removedCount > 0) {
     await restoreInteractionState(explorer, restoreUrl);
   }
 
@@ -164,7 +170,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 +184,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,16 +192,23 @@ 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}`);
 }
 
 function buildTransition(candidate: InteractionCandidate, beforeState: WebPageState, afterState: WebPageState, changes: InteractionChanges): DocStateTransition {
+  const existingUrls = new Set(collectLinks(beforeState).map((link) => link.url));
   const transition: DocStateTransition = {
     action: describeAction(candidate),
     before: summarizeInteractiveState(beforeState),
     after: summarizeInteractiveState(afterState),
-    discoveredUrls: collectLinks(afterState).map((link) => link.url),
+    discoveredUrls: [
+      ...new Set(
+        collectLinks(afterState)
+          .map((link) => link.url)
+          .filter((url) => !existingUrls.has(url))
+      ),
+    ],
     newCapabilities: collectDiscoveryNotes(afterState, changes),
     element: buildInteractionElement(candidate),
     changes,
@@ -238,7 +251,7 @@ function isMeaningfulStateTransition(transition: DocStateTransition): boolean {
   if (transition.targetUrl || transition.changes?.urlChanged) {
     return true;
   }
-  return (transition.changes?.newElements || 0) > 0;
+  return (transition.changes?.newElements || 0) > 0 || (transition.changes?.removedElements || 0) > 0;
 }
 
 function buildInteractionElement(candidate: InteractionCandidate): InteractionElement {

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,
   };
 }
@@ -96,6 +91,7 @@ export function createDocsCommands(name = 'docs'): Command {
             output: 'docs',
             screenshot: true,
             interactive: false,
+            ignoreErrors: true,
             collapseDynamicPages: true,
             scope: 'site',
             includePaths: [],

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

@@ -115,6 +115,7 @@ class DocbotConfigParser {
           output: 'docs',
           screenshot: true,
           interactive: false,
+          ignoreErrors: true,
           collapseDynamicPages: true,
           scope: 'site',
           includePaths: [],
@@ -151,6 +152,7 @@ interface DocbotConfig {
     maxPages?: number;
     output?: string;
     screenshot?: boolean;
+    ignoreErrors?: boolean | string[];
     prompt?: string;
     collapseDynamicPages?: boolean;
     scope?: 'site' | 'section' | 'subtree';

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

@@ -6,12 +6,13 @@ import { normalizeUrl } from '../../../src/state-manager.ts';
 import { tag } from '../../../src/utils/logger.ts';
 import { sanitizeFilename } from '../../../src/utils/strings.ts';
 import { Documentarian, type PageDocumentation } from './ai/documentarian.ts';
+import type { DocStateTransition } from './ai/tools.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 { type DocumentationScreenshot, captureBeforeInteraction, captureDocumentationScreenshots, captureInteractionScreenshot } from './screenshots.ts';
+import { renderMermaidBody } from './state-diagram.ts';
 
 class DocBot {
   private explorBot: ExplorBot;
@@ -43,7 +44,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 +77,7 @@ class DocBot {
         continue;
       }
 
-      const stateManager = this.explorBot.getExplorer().getStateManager();
+      const stateManager = this.explorBot.stateManager();
       if (stateManager.hasVisitedState(target)) {
         continue;
       }
@@ -113,16 +114,18 @@ class DocBot {
           force: true,
         });
         const pagePath = this.getPageFilePath(state.url);
-        const documentation = await this.documentarian.document(state, research, async (interactionState, transition) => {
-          if (!this.shouldUseScreenshots()) {
-            return null;
-          }
-          return captureInteractionScreenshot(this.explorBot.getExplorer(), interactionState, transition, {
-            pageFilePath: pagePath,
-            screenshotsDir: this.getScreenshotsDir(),
-            config: this.config,
-          });
-        });
+        const captureState = this.shouldUseScreenshots()
+          ? {
+              before: () => captureBeforeInteraction(this.explorBot.getExplorer()),
+              after: (beforeScreenshot: Buffer | null, interactionState: WebPageState, transition: DocStateTransition) =>
+                captureInteractionScreenshot(this.explorBot.getExplorer(), beforeScreenshot, interactionState, transition, {
+                  pageFilePath: pagePath,
+                  screenshotsDir: this.getScreenshotsDir(),
+                  config: this.config,
+                }),
+            }
+          : undefined;
+        const documentation = await this.documentarian.document(state, research, captureState);
         const lowSignalReason = this.getLowSignalReason(documentation, research);
         if (lowSignalReason) {
           skipped.push({
@@ -163,6 +166,9 @@ class DocBot {
         }
       } catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
+        if (!this.shouldIgnoreError(error)) {
+          throw error;
+        }
         tag('warning').log(`Skipping ${target}: ${reason}`);
         skipped.push({
           url: target,
@@ -410,6 +416,28 @@ class DocBot {
     return `low-signal page: only ${documentation.can.length} proven actions and ${interactiveCount} interactive elements`;
   }
 
+  private shouldIgnoreError(error: unknown): boolean {
+    const ignoreErrors = this.config.docs?.ignoreErrors;
+    if (ignoreErrors === undefined || ignoreErrors === true) return true;
+    if (ignoreErrors === false) return false;
+
+    const details = [error instanceof Error ? error.name : '', error instanceof Error ? error.message : String(error)];
+    if (typeof error === 'object' && error && 'code' in error) {
+      details.push(String(error.code));
+    }
+    const normalized = details
+      .join(' ')
+      .toLowerCase()
+      .replaceAll(/[\W_]+/g, ' ');
+    return ignoreErrors.some((pattern) => {
+      const normalizedPattern = pattern
+        .trim()
+        .toLowerCase()
+        .replaceAll(/[\W_]+/g, ' ');
+      return normalizedPattern.length > 0 && normalized.includes(normalizedPattern);
+    });
+  }
+
   private countInteractiveElements(research: string): number {
     const matches = [...research.matchAll(/\((\d+) elements?\)/g)];
     return matches.reduce((sum, match) => sum + Number.parseInt(match[1], 10), 0);