explorbot 0.2.5 → 0.3.1

package/dist/src/commands/init-command.js

@@ -7,15 +7,10 @@ import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from "..
 import { getCliName } from "../utils/cli-name.js";
 import { log, tag } from '../utils/logger.js';
 import { relativeToCwd } from "../utils/next-steps.js";
-const DEFAULT_CONFIG_TEMPLATE = `import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-// import { '<your provider here>' } from '<your provider package here>';
-
-// Vercel AI SDK is used to connect to AI providers.
-// Bring your own provider or use OpenRouter (one API key, many providers).
-// https://github.com/testomatio/explorbot/blob/main/docs/providers.md
-const openrouter = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
+function defaultConfigTemplate() {
+    return `// 'provider/model-id' uses a bundled provider.
+// It is also possible to import provider as a module from Vercel AI SDK.  
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 
 const config = {
   web: {
@@ -24,12 +19,7 @@ const config = {
   },
 
   ai: {
-    // fast model with tool calling capabilities
-    model: openrouter('openai/gpt-oss-20b:nitro'),
-    // vision model for screenshot analysis
-    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
-    // agentic model for decision making
-    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+${modelLines('openrouter')}
   },
 
   reporter: {
@@ -44,6 +34,7 @@ const config = {
 
 export default config;
 `;
+}
 const DEFAULT_ENV_TEMPLATE = dedent `
 # AI provider API keys
 OPENROUTER_API_KEY=
@@ -127,7 +118,7 @@ export function runInitCommand(options) {
             log('Use --force to overwrite existing file');
             process.exit(1);
         }
-        writeFileSync(outPath, DEFAULT_CONFIG_TEMPLATE, 'utf8');
+        writeFileSync(outPath, defaultConfigTemplate(), 'utf8');
         log(`Created config file: ${relativeToCwd(outPath)}`);
         const envPath = resolve(process.cwd(), '.env');
         if (!existsSync(envPath)) {
@@ -196,15 +187,17 @@ async function renderInitWizard(mode) {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-function globalConfigTemplate(provider) {
-    const { envKey } = PROVIDERS[provider];
+function modelLines(provider) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
         ['model', 'fast model with tool calling capabilities'],
         ['visionModel', 'vision model for screenshot analysis'],
         ['agenticModel', 'agentic model for decision making'],
     ];
-    const models = roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+}
+function globalConfigTemplate(provider) {
+    const { envKey } = PROVIDERS[provider];
     return `// Global Explorbot configuration — used by every directory without its own explorbot.config.js.
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
 // The key is read from ${envKey} in ~/.explorbot/.env
@@ -212,7 +205,7 @@ function globalConfigTemplate(provider) {
 // https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
 const config = {
   ai: {
-${models}
+${modelLines(provider)}
   },
 
   reporter: {

package/dist/src/config.d.ts

@@ -151,8 +151,9 @@ interface AIConfig {
     vision?: boolean;
     visionModel?: any;
     agenticModel?: any;
-    maxAttempts?: number;
+    retryAttempts?: number;
     retryDelay?: number;
+    maxParallelRequests?: number;
     agents?: AgentsConfig;
 }
 interface HtmlConfig {

package/dist/src/config.js

@@ -157,7 +157,7 @@ export class ConfigParser {
         const config = this.getConfig();
         if (!this.configPath)
             throw new Error('Config path not found');
-        return path.join(this.getProjectRoot(), config.dirs?.output || 'output');
+        return this.resolveProjectDir(config.dirs?.output || 'output');
     }
     getProjectRoot() {
         if (this.site)
@@ -168,6 +168,8 @@ export class ConfigParser {
         return process.cwd();
     }
     resolveProjectDir(relativeDir) {
+        if (path.isAbsolute(relativeDir))
+            return relativeDir;
         if (!this.configPath)
             return relativeDir;
         return path.join(this.getProjectRoot(), relativeDir);

package/dist/src/experience-tracker.d.ts

@@ -53,6 +53,7 @@ export declare class ExperienceTracker {
     getExperienceTableOfContents(state: ActionResult, options?: {
         includeDescendantExperience?: boolean;
     }): ExperienceTocEntry[];
+    renderExperienceFor(state: ActionResult): string;
     renderExperienceTocFor(state: ActionResult): string;
     getExperienceSection(fileTag: string, sectionIndex: number, state: ActionResult, options?: {
         includeDescendantExperience?: boolean;
@@ -77,6 +78,7 @@ export declare class ExperienceTracker {
         fileHash: string;
     } | null;
 }
+export declare function renderExperienceRecipes(recipes: string[]): string;
 export declare function renderExperienceToc(toc: ExperienceTocEntry[]): string;
 export interface ExperienceFile {
     filePath: string;

package/dist/src/experience-tracker.js

@@ -257,6 +257,13 @@ export class ExperienceTracker {
         });
         return this.buildToc(sorted);
     }
+    renderExperienceFor(state) {
+        const successful = this.getSuccessfulExperience(state);
+        if (!successful.length)
+            return '';
+        tag('operation').log(`Found ${successful.length} experience ${pluralize(successful.length, 'file')} for: ${state.url}`);
+        return renderExperienceRecipes(successful);
+    }
     renderExperienceTocFor(state) {
         const toc = this.getExperienceTableOfContents(state);
         if (toc.length === 0)
@@ -381,6 +388,11 @@ function indexToLetters(index) {
     }
     return result;
 }
+export function renderExperienceRecipes(recipes) {
+    if (recipes.length === 0)
+        return '';
+    return `<experience>\nPast successful recipes recorded from prior runs for this page. Prefer these solutions first if they match the goal.\n\n${recipes.join('\n\n')}\n</experience>`;
+}
 export function renderExperienceToc(toc) {
     if (toc.length === 0)
         return '';

package/dist/src/explorbot.js

@@ -199,7 +199,7 @@ export class ExplorBot {
             this.agents.tester = this.createAgent((deps) => {
                 const researcher = this.agentResearcher();
                 const navigator = this.agentNavigator();
-                const tools = createAgentTools({ ...deps, researcher, navigator });
+                const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
                 return new Tester(deps, researcher, navigator, tools);
             });
             const qm = this.agentQuartermaster();

package/dist/src/playwright-recorder.js

@@ -6,7 +6,7 @@ const RECORDABLE = {
     Frame: new Set(['click', 'dblclick', 'fill', 'selectOption', 'press', 'type', 'check', 'uncheck', 'hover', 'tap', 'focus', 'setInputFiles', 'scrollIntoViewIfNeeded', 'dragTo', 'goto', 'setContent']),
     Page: new Set(['goBack', 'goForward', 'reload', 'keyboardPress', 'keyboardType', 'keyboardDown', 'keyboardUp', 'keyboardInsertText', 'mouseClick', 'mouseDblclick', 'mouseMove', 'mouseDown', 'mouseUp', 'mouseWheel']),
 };
-const PLAYWRIGHT_INCOMPATIBLE = "Playwright output is not compatible with this Playwright version (playwright-core/lib/utils does not expose asLocator). Use output.framework: 'codeceptjs' instead, or pin Playwright to a version shipping lib/utils/isomorphic/locatorGenerators.js.";
+const PLAYWRIGHT_INCOMPATIBLE = "Playwright output requires playwright-core 1.62 or newer (lib/coreBundle does not expose iso.asLocator). Use output.framework: 'codeceptjs' instead.";
 let cachedAsLocator = null;
 let asLocatorLoadAttempted = false;
 const nodeRequire = typeof require === 'function' ? require : createRequire(import.meta.url);
@@ -16,17 +16,11 @@ function getAsLocator() {
     if (asLocatorLoadAttempted)
         throw new Error(PLAYWRIGHT_INCOMPATIBLE);
     asLocatorLoadAttempted = true;
-    try {
-        const mod = nodeRequire('playwright-core/lib/utils');
-        if (typeof mod?.asLocator === 'function') {
-            cachedAsLocator = mod.asLocator;
-            return cachedAsLocator;
-        }
-    }
-    catch {
-        // Module not exported or not found
-    }
-    throw new Error(PLAYWRIGHT_INCOMPATIBLE);
+    const asLocator = nodeRequire('playwright-core/lib/coreBundle')?.iso?.asLocator;
+    if (typeof asLocator !== 'function')
+        throw new Error(PLAYWRIGHT_INCOMPATIBLE);
+    cachedAsLocator = asLocator;
+    return cachedAsLocator;
 }
 export class PlaywrightRecorder {
     context = null;

package/dist/src/test-plan.d.ts

@@ -1,3 +1,4 @@
+import type { ActionResult } from './action-result.js';
 import { WebPageState } from './state-manager.js';
 export declare const TestResult: {
     readonly PASSED: "passed";
@@ -94,10 +95,13 @@ export declare class Test extends Task {
     startTime?: number;
     endTime?: number;
     resetCount: number;
+    appliedExperience: AppliedExperience[];
     constructor(scenario: string, priority: 'critical' | 'important' | 'high' | 'normal' | 'low', expectedOutcome: string | string[], startUrl: string, plannedSteps?: string[]);
     getVisitedUrls({ localOnly }?: {
         localOnly?: boolean;
     }): string[];
+    applyExperience(recipes: AppliedExperience[]): void;
+    getAppliedExperience(state: ActionResult): string[];
     addArtifact(artifact?: string): void;
     get hasFinished(): boolean;
     get isSuccessful(): boolean;
@@ -166,4 +170,8 @@ interface UrlNoteState {
     h2?: string;
     screenshotFile?: string;
 }
+interface AppliedExperience {
+    url: string;
+    content: string;
+}
 export {};

package/dist/src/test-plan.js

@@ -190,6 +190,7 @@ export class Test extends Task {
     startTime;
     endTime;
     resetCount = 0;
+    appliedExperience = [];
     constructor(scenario, priority, expectedOutcome, startUrl, plannedSteps = []) {
         super(scenario, startUrl);
         this.scenario = scenario;
@@ -208,6 +209,16 @@ export class Test extends Task {
         }
         return [...new Set([this.startUrl, ...this.states.map((s) => s.url)].filter((value) => Boolean(value) && value.trim() !== ''))];
     }
+    applyExperience(recipes) {
+        for (const recipe of recipes) {
+            if (this.appliedExperience.some((applied) => applied.content === recipe.content))
+                continue;
+            this.appliedExperience.push(recipe);
+        }
+    }
+    getAppliedExperience(state) {
+        return this.appliedExperience.filter((recipe) => state.isRelevantExperienceRecord({ url: recipe.url })).map((recipe) => recipe.content);
+    }
     addArtifact(artifact) {
         if (!artifact)
             return;

package/dist/src/utils/html-diff.d.ts

@@ -11,9 +11,14 @@ export interface HtmlDiffResult {
     removed: string[];
     similarity: number;
     summary: string;
+    messages: string[];
 }
 export declare function computeHtmlFingerprint(html: string): string[];
 /**
  * Compares two HTML documents and returns differences along with a diff subtree.
  */
 export declare function htmlDiff(originalHtml: string, modifiedHtml: string, htmlConfig?: HtmlConfig): Promise<HtmlDiffResult>;
+/**
+ * Text the app announced across a navigation. Only live regions: everything else on a new page is its content, not a message.
+ */
+export declare function liveRegionMessages(originalHtml: string, modifiedHtml: string): string[];

package/dist/src/utils/html-diff.js

@@ -2,6 +2,10 @@ import { parse, serialize } from 'parse5';
 import { TAILWIND_CLASS_PATTERNS, TRASH_HTML_CLASSES, minifyHtml } from "./html.js";
 import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const TEXT_LINE_PREFIX = 'TEXT:';
+const MESSAGE_MAX_LENGTH = 200;
+const MESSAGE_LIMIT = 8;
 /**
  * Get text content from an element node.
  */
@@ -141,7 +145,9 @@ export async function htmlDiff(originalHtml, modifiedHtml, htmlConfig) {
     const modifiedLines = flattenHtml(modifiedRoot);
     const similarity = calculateSimilarity(originalLines, modifiedLines);
     const { added, removed } = findDifferences(originalLines, modifiedLines);
-    const parts = await buildDiffParts(originalDocument, modifiedDocument);
+    const originalMap = collectElementMap(originalDocument);
+    const modifiedMap = collectElementMap(modifiedDocument);
+    const parts = await buildDiffParts(originalMap, modifiedMap);
     const structuralAdditions = parts.flatMap((p) => p.added.filter((a) => a.startsWith('ELEMENT:')));
     const allAdded = [...added, ...structuralAdditions];
     const totalChanges = allAdded.length + removed.length;
@@ -152,8 +158,63 @@ export async function htmlDiff(originalHtml, modifiedHtml, htmlConfig) {
         removed,
         similarity,
         summary,
+        messages: collectMessages(originalMap, modifiedMap, allAdded),
     };
 }
+/**
+ * Text the app announced while the page stayed the same: live region content first, then any other text that appeared.
+ */
+function collectMessages(originalMap, modifiedMap, added) {
+    const appearedText = added.filter((line) => line.startsWith(TEXT_LINE_PREFIX)).map((line) => line.slice(TEXT_LINE_PREFIX.length));
+    return limitMessages([...collectLiveRegionTexts(originalMap, modifiedMap), ...appearedText]);
+}
+/**
+ * Text the app announced across a navigation. Only live regions: everything else on a new page is its content, not a message.
+ */
+export function liveRegionMessages(originalHtml, modifiedHtml) {
+    const originalMap = collectElementMap(parseDocument(originalHtml));
+    const modifiedMap = collectElementMap(parseDocument(modifiedHtml));
+    return limitMessages(collectLiveRegionTexts(originalMap, modifiedMap));
+}
+function limitMessages(candidates) {
+    const messages = [];
+    for (const candidate of candidates) {
+        const text = candidate.replace(/\s+/g, ' ').trim().slice(0, MESSAGE_MAX_LENGTH);
+        if (!text)
+            continue;
+        if (messages.some((message) => message.includes(text)))
+            continue;
+        messages.push(text);
+        if (messages.length === MESSAGE_LIMIT)
+            break;
+    }
+    return messages;
+}
+function collectLiveRegionTexts(originalMap, modifiedMap) {
+    const texts = [];
+    for (const [path, element] of modifiedMap) {
+        if (!isLiveRegion(element))
+            continue;
+        const text = getTextContent(element).trim();
+        if (!text)
+            continue;
+        const previous = originalMap.get(path);
+        if (previous && getTextContent(previous).trim() === text)
+            continue;
+        texts.push(text);
+    }
+    return texts;
+}
+function isLiveRegion(element) {
+    if (element.tagName?.toLowerCase() === 'output')
+        return true;
+    const attrs = element.attrs ?? [];
+    const role = attrs.find((attr) => attr.name === 'role')?.value.toLowerCase();
+    if (role && LIVE_REGION_ROLES.has(role))
+        return true;
+    const live = attrs.find((attr) => attr.name === 'aria-live')?.value.toLowerCase();
+    return live === 'polite' || live === 'assertive';
+}
 /**
  * Parse HTML into a document, wrapping fragments with html/body for consistency.
  * Uses custom sanitization that removes iframes for diff purposes.
@@ -354,9 +415,7 @@ function findStableContainer(topLevelPath, originalMap, modifiedMap) {
     }
     return { path: 'html[1]/body[1]', selector: 'body' };
 }
-async function buildDiffParts(originalDocument, modifiedDocument) {
-    const originalMap = collectElementMap(originalDocument);
-    const modifiedMap = collectElementMap(modifiedDocument);
+async function buildDiffParts(originalMap, modifiedMap) {
     const addedPaths = [];
     const changedPaths = [];
     for (const [path, element] of modifiedMap.entries()) {
@@ -624,7 +683,7 @@ function flattenHtml(node) {
     function process(n) {
         if (n.type === 'text' && n.content) {
             if (n.content.length >= 5) {
-                lines.push(`TEXT:${n.content}`);
+                lines.push(`${TEXT_LINE_PREFIX}${n.content}`);
             }
             return;
         }
@@ -643,7 +702,7 @@ function flattenHtml(node) {
                 return;
             }
             if (n.content && n.content.length >= 5) {
-                lines.push(`TEXT:${n.content}`);
+                lines.push(`${TEXT_LINE_PREFIX}${n.content}`);
             }
             if (n.children) {
                 n.children.forEach((child) => process(child));

package/dist/src/utils/strings.d.ts

@@ -3,3 +3,5 @@ export declare function slugify(text: string): string;
 export declare function normalizeInlineText(text: string): string;
 export declare function sanitizeFilename(name: string): string;
 export declare function safeFilename(name: string, ext?: string, maxBytes?: number): string;
+export declare function truncate(text: string, max: number): string;
+export declare function compactErrorMessage(error: unknown): string;

package/dist/src/utils/strings.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import stripAnsi from 'strip-ansi';
 export function truncateJson(input) {
     if (!input)
         return '';
@@ -36,3 +37,34 @@ export function safeFilename(name, ext = '', maxBytes = 240) {
     }
     return truncated + suffix + ext;
 }
+export function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 3)}...`;
+}
+const MAX_COMPACT_ERROR = 400;
+export function compactErrorMessage(error) {
+    let text = stripAnsi(String(error));
+    for (const strip of STRIP_STRATEGIES) {
+        text = strip(text);
+    }
+    return truncate(text, MAX_COMPACT_ERROR);
+}
+function stripCallLog(text) {
+    const CALL_LOG = 'Call log:';
+    const NOISE = ['attempting', 'retrying', 'waiting'];
+    const [headline, ...log] = text.split(CALL_LOG);
+    if (!log.length)
+        return text;
+    const lines = new Set();
+    for (const line of log.join(CALL_LOG).split('\n')) {
+        const cleaned = normalizeInlineText(line);
+        if (!cleaned)
+            continue;
+        if (NOISE.some((noise) => cleaned.includes(noise)))
+            continue;
+        lines.add(cleaned);
+    }
+    return [headline.trim(), ...lines].join(' ');
+}
+const STRIP_STRATEGIES = [stripCallLog];

package/dist/src/utils/url-matcher.d.ts

@@ -1,5 +1,6 @@
 export declare function isDynamicSegment(segment: string): boolean;
 export declare function hasDynamicUrlSegment(url: string): boolean;
+export declare function isSamePageFamily(urlA: string, urlB: string): boolean;
 export declare function generalizeSegment(segment: string): string;
 export declare function generalizeUrl(url: string): string;
 export declare function matchesUrl(pattern: string, path: string): boolean;

package/dist/src/utils/url-matcher.js

@@ -32,6 +32,23 @@ export function isDynamicSegment(segment) {
 export function hasDynamicUrlSegment(url) {
     return url.split('/').some((seg) => seg.length > 0 && isDynamicSegment(seg));
 }
+export function isSamePageFamily(urlA, urlB) {
+    const partsA = new URL(urlA, 'http://localhost').pathname.toLowerCase().split('/').filter(Boolean);
+    const partsB = new URL(urlB, 'http://localhost').pathname.toLowerCase().split('/').filter(Boolean);
+    if (partsA.length !== partsB.length)
+        return false;
+    let diffCount = 0;
+    for (let i = 0; i < partsA.length; i++) {
+        if (partsA[i] === partsB[i])
+            continue;
+        diffCount++;
+        if (diffCount > 1)
+            return false;
+        if (!isDynamicSegment(partsA[i]) || !isDynamicSegment(partsB[i]))
+            return false;
+    }
+    return true;
+}
 export function generalizeSegment(segment) {
     if (/^\d+$/.test(segment))
         return '\\d+';
@@ -111,6 +128,18 @@ export function matchesNavigationUrl(expected, current) {
     if (!expectedPath.includes('?')) {
         currentPath = currentPath.split('?')[0];
     }
-    const normalize = (value) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
-    return normalize(expectedPath) === normalize(currentPath);
+    const normalize = (value) => value.replace(/^\/+|\/+$/g, '');
+    const expectedNormalized = normalize(expectedPath);
+    const currentNormalized = normalize(currentPath);
+    const expectedKey = expectedNormalized.toLowerCase();
+    const currentKey = currentNormalized.toLowerCase();
+    if (expectedKey === currentKey)
+        return true;
+    if (!currentKey.startsWith(`${expectedKey}/`))
+        return false;
+    const recordSegments = currentNormalized
+        .slice(expectedKey.length + 1)
+        .split('/')
+        .filter(Boolean);
+    return recordSegments.length > 0 && recordSegments.every(isDynamicSegment);
 }

package/docs/basics/getting-started.md

@@ -32,30 +32,53 @@ OPENROUTER_API_KEY=sk-...
 Then open `explorbot.config.js` and set your app's base URL — the host only, no path:
 
 ```javascript
-import { createOpenRouter } from '@openrouter/ai-sdk-provider';
-
-const openrouter = createOpenRouter({
-  apiKey: process.env.OPENROUTER_API_KEY,
-});
-
 export default {
   web: {
     url: 'http://localhost:3000',
   },
   ai: {
-    model: openrouter('openai/gpt-oss-20b:nitro'),
-    visionModel: openrouter('google/gemma-4-31b-it'),
-    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+    model: 'openrouter/openai/gpt-oss-20b:nitro',
+    visionModel: 'openrouter/openai/gpt-5.6-luna',
+    agenticModel: 'openrouter/openai/gpt-5.6-luna',
   },
 };
 ```
 
+That shorthand — `'provider/model-id'` — uses a provider package Explorbot ships, so nothing extra is installed. Bundled providers:
+
+- `openai`
+- `anthropic`
+- `google`
+- `groq`
+- `mistral`
+- `openrouter`
+- `sambanova`
+
+The other style is explicit: install a Vercel AI SDK package (`npm i @ai-sdk/openai`) and build the client yourself. It works for the providers above too, and it is the only way to reach one that isn't bundled, a custom `baseURL`, or extra client options:
+
+```javascript
+import { createOpenAI } from '@ai-sdk/openai';
+
+const poolside = createOpenAI({
+  apiKey: process.env.POOLSIDE_API_KEY,
+  baseURL: 'https://inference.poolside.ai/v1',
+});
+
+export default {
+  ai: {
+    model: poolside('poolside/laguna-xs-2.1'),
+  },
+};
+```
+
+Both styles mix freely across the three keys. See [Providers](./providers.md).
+
 Explorbot uses three models. Pick each one for speed and cost:
 
 | Model | Config key | Used by | Pick |
 |-------|-----------|---------|------|
 | `model` | `ai.model` | Tester, Navigator, Researcher — they read HTML and ARIA on every step | a fast, cheap model (e.g. `openai/gpt-oss-20b:nitro`) |
-| `visionModel` | `ai.visionModel` | screenshot analysis | a vision model (e.g. `google/gemma-4-31b-it`) |
+| `visionModel` | `ai.visionModel` | screenshot analysis | a vision model (e.g. `openai/gpt-5.6-luna`) |
 | `agenticModel` | `ai.agenticModel` | Captain and Pilot — they read short action logs and make the big decisions | a smarter model (e.g. MiniMax 2.5, Grok Fast) |
 
 Captain and Pilot barely use tokens, so a smarter `agenticModel` improves results for almost no extra cost. OpenRouter is the simplest start — one key, many models. To use OpenAI, Anthropic, Groq, or others, see [Providers](./providers.md). For every config option, see [Configuration](../reference/configuration.md).

package/docs/basics/providers.md

@@ -2,6 +2,8 @@
 
 Explorbot connects to AI providers through the [Vercel AI SDK](https://sdk.vercel.ai/). Use any supported provider, and mix providers across different models.
 
+Every provider below is set up the classical way: install its package, import it, build the client. Explorbot bundles some of these packages — for those you can skip the install and name the model as `'provider/model-id'` instead. See [Getting Started](./getting-started.md#2-configure) for that list and the two styles side by side.
+
 > The `export default` config block inside each `<!-- START/END provider -->` marker is generated from [`models.json`](../../models.json). After editing that file, run `bunosh docs:sync`. Everything else — including the import blocks — is hand-written.
 
 ## Requirements
@@ -51,8 +53,8 @@ Set the recommended models in the exported config:
 export default {
   ai: {
     model: openrouter('openai/gpt-oss-20b:nitro'),
-    visionModel: openrouter('google/gemma-4-31b-it:nitro'),
-    agenticModel: openrouter('google/gemma-4-31b-it:nitro'),
+    visionModel: openrouter('openai/gpt-5.6-luna'),
+    agenticModel: openrouter('openai/gpt-5.6-luna'),
   },
 };
 ```
@@ -118,8 +120,8 @@ Set the recommended models in the exported config:
 ```javascript
 export default {
   ai: {
-    model: openai('gpt-5.4-nano'),
-    visionModel: openai('gpt-5.4-nano'),
+    model: openai('gpt-5-nano'),
+    visionModel: openai('gpt-5.6-luna'),
     agenticModel: openai('gpt-5.6-luna'),
   },
 };