explorbot 0.4.7 → 0.4.9

package/dist/src/ai/tester.js

@@ -29,7 +29,7 @@ const SAMPLE_FILES = {
 };
 export class Tester extends TaskAgent {
     ACTION_TOOLS = ['click', 'hover', 'pressKey', 'form'];
-    DELEGATED_ACTION_TOOLS = ['interact'];
+    DELEGATED_ACTION_TOOLS = ['interact', 'visualClick'];
     SPECIAL_CONTEXT_ACTION_TOOLS = ['exitIframe'];
     emoji = '🧪';
     requestStore;

package/dist/src/ai/tools.js

@@ -312,6 +312,7 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
         - Performing multiple form actions in a single batch
         - Complex interactions requiring sequential commands
         - Reaching items further down a list (I.scrollTo)
+        - Reloading the page to prove a change outlived it (I.reloadPage)
 
         Example - filling a form with context (PREFERRED):
         I.fillField('Username', 'John', '.login-form')
@@ -324,7 +325,7 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
         I.selectOption({"role":"combobox","text":"Category"}, 'Technology')
 
         Do not submit form - use verify() first to check fields were filled correctly, then click() to submit.
-        Do not use: wait functions, amOnPage, reloadPage, saveScreenshot        
+        Do not use: wait functions, amOnPage, saveScreenshot        
       `,
             inputSchema: z.object({
                 codeBlock: z.string().describe('Valid CodeceptJS code starting with I. Can contain multiple commands separated by newlines.'),
@@ -1201,7 +1202,8 @@ async function extractWebElements(error) {
 function formatElementList(matched) {
     if (!matched)
         return 'Could not fetch element details. Repeat the action to get better info.';
-    return matched
+    const keys = matched.map((el) => `${el.text}::${el.visible}::${el.html}`);
+    const list = matched
         .map((el, i) => {
         const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
         if (el.visible !== undefined)
@@ -1209,10 +1211,16 @@ function formatElementList(matched) {
         const wrapped = matched.map((_, j) => j).filter((j) => j !== i && matched[j].xpath.startsWith(`${el.xpath}/`));
         if (wrapped.length)
             lines.push(`Wraps: element ${wrapped.map((j) => j + 1).join(', ')}`);
+        const same = keys.map((_, j) => j).filter((j) => j !== i && keys[j] === keys[i]);
+        if (same.length)
+            lines.push(`Identical to element ${same.map((j) => j + 1).join(', ')}`);
         lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
         return lines.join('\n');
     })
         .join('\n\n');
+    if (new Set(keys).size === matched.length)
+        return list;
+    return `${list}\n\nIdentical matches are not told apart by their number — picking one is a guess. Click the one you mean by appearance with visualClick().`;
 }
 export async function formatMatchedElements(error) {
     return formatElementList(await extractWebElements(error));

package/dist/src/commands/config-command.d.ts

@@ -15,11 +15,13 @@ export declare class ConfigCommand extends BaseCommand {
 }
 interface ConfigSummaryOptions {
     configPath?: string | null;
+    siteConfigPath?: string | null;
     root?: string;
     json?: boolean;
 }
 export interface ConfigData {
     config: string;
+    siteConfig: string;
     url: string;
     browser: string;
     headless: boolean;

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

@@ -13,7 +13,7 @@ export class ConfigCommand extends BaseCommand {
     description = 'Show models, config file and paths used by this run';
     async execute() {
         const parser = ConfigParser.getInstance();
-        tag('info').log(ConfigCommand.render(this.explorBot.getConfig(), { configPath: parser.getConfigPath(), root: parser.getProjectRoot() }));
+        tag('info').log(ConfigCommand.render(this.explorBot.getConfig(), { configPath: parser.getConfigPath(), siteConfigPath: parser.getSiteConfigPath(), root: parser.getProjectRoot() }));
     }
     static async summary(options = {}) {
         const parser = ConfigParser.getInstance();
@@ -24,12 +24,15 @@ export class ConfigCommand extends BaseCommand {
                 throw error;
             return load(site.url);
         });
-        return ConfigCommand.render(config, { configPath: parser.getConfigPath(), root: parser.getProjectRoot(), json: options.json });
+        return ConfigCommand.render(config, { configPath: parser.getConfigPath(), siteConfigPath: parser.getSiteConfigPath(), root: parser.getProjectRoot(), json: options.json });
     }
     static data(config, options = {}) {
         let configPath = '';
         if (options.configPath && existsSync(options.configPath))
             configPath = options.configPath;
+        let siteConfigPath = '';
+        if (options.siteConfigPath && existsSync(options.siteConfigPath))
+            siteConfigPath = options.siteConfigPath;
         const dirs = {};
         if (options.root) {
             for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
@@ -55,6 +58,7 @@ export class ConfigCommand extends BaseCommand {
         }
         return {
             config: configPath,
+            siteConfig: siteConfigPath,
             url: config.playwright?.url || config.web?.url || config.api?.baseEndpoint || '',
             browser: config.playwright?.browser || '',
             headless: !config.playwright?.show,
@@ -75,6 +79,8 @@ export class ConfigCommand extends BaseCommand {
         const lines = [];
         const section = (title, entries) => lines.push(...renderSection(title, entries));
         const general = [['config', data.config || 'EXPLORBOT_* environment variables']];
+        if (data.siteConfig)
+            general.push(['site config', data.siteConfig]);
         if (data.url)
             general.push(['url', data.url]);
         if (data.browser) {

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

@@ -6,10 +6,7 @@ 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";
-function defaultConfigTemplate(provider, esm) {
-    let moduleExport = 'module.exports = config;';
-    if (esm)
-        moduleExport = 'export default config;';
+function defaultConfigTemplate(provider) {
     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
@@ -34,7 +31,7 @@ ${modelLines(provider)}
   },
 };
 
-${moduleExport}
+export default config;
 `;
 }
 export function envTemplate(provider) {
@@ -128,8 +125,7 @@ export function runInitCommand(options) {
             log('Use --force to overwrite existing file');
             process.exit(1);
         }
-        const esm = extname(outPath) !== '.js' || isModuleProject(dirname(outPath));
-        writeFileSync(outPath, defaultConfigTemplate(provider, esm), 'utf8');
+        writeFileSync(outPath, defaultConfigTemplate(provider), 'utf8');
         log(`Created config file: ${relativeToCwd(outPath)}`);
         const envPath = resolve(process.cwd(), '.env');
         if (!existsSync(envPath)) {
@@ -234,6 +230,8 @@ export function modelLines(provider, only) {
 function globalConfigTemplate(provider) {
     const { envKey } = PROVIDERS[provider];
     return `// Global Explorbot configuration — used by every directory without its own explorbot.config.js.
+// Settings shared by every site. Each site extends them in
+// ~/.explorbot/sites/<host>/explorbot.config.js, written on its first run.
 // Models are written as 'provider/model-id' so they resolve without a local node_modules.
 // The key is read from ${envKey} in ~/.explorbot/.env
 // Model ids are snapshotted from the recommendations of this Explorbot version.
@@ -251,27 +249,9 @@ ${modelLines(provider)}
   },
 };
 
-module.exports = config;
+export default config;
 `;
 }
-function isModuleProject(configDir) {
-    let currentDir = resolve(configDir);
-    while (true) {
-        const packagePath = join(currentDir, 'package.json');
-        if (existsSync(packagePath)) {
-            try {
-                return JSON.parse(readFileSync(packagePath, 'utf8')).type === 'module';
-            }
-            catch {
-                return false;
-            }
-        }
-        const parentDir = dirname(currentDir);
-        if (parentDir === currentDir)
-            return false;
-        currentDir = parentDir;
-    }
-}
 function writeEnvKey(key, value) {
     const envPath = globalEnvPath();
     let content = '# AI provider API keys';

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

@@ -1,4 +1,4 @@
-import { listSites, sitesDir } from '../global-config.js';
+import { findSiteConfig, listSites, sitesDir } from '../global-config.js';
 import { getCliName } from '../utils/cli-name.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
@@ -16,6 +16,11 @@ export class SitesCommand extends BaseCommand {
         tag('info').log(`Registered sites (${sites.length}):`);
         for (const site of sites) {
             tag('info').log(`  ${site.folder.padEnd(width)}  ${site.url}  last run ${site.lastRunAt.slice(0, 16).replace('T', ' ')}`);
+            let config = 'inherits global config';
+            const sitePath = findSiteConfig(site.dir);
+            if (sitePath)
+                config = sitePath;
+            tag('info').log(`  ${' '.repeat(width)}  ${config}`);
         }
         tag('info').log('');
         tag('info').log(`Stored in ${sitesDir()}`);

package/dist/src/config.d.ts

@@ -1,4 +1,4 @@
-import { type SiteRecord } from './global-config.js';
+import { EXPLORBOT_CONFIG_PATHS, type SiteRecord } from './global-config.js';
 export declare const PROVIDERS: Record<string, ProviderInfo>;
 export declare const MODEL_ROLES: ModelRole[];
 interface PlaywrightConfig {
@@ -224,7 +224,7 @@ interface ExplorbotConfig {
     dynamicPageRegex?: string;
 }
 type RuleEntry = string | Record<string, string>;
-export declare const EXPLORBOT_CONFIG_PATHS: string[];
+export { EXPLORBOT_CONFIG_PATHS };
 export declare const EXPLORBOT_ENV_VARS: EnvVar[];
 export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, ScoutAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
 export declare class ConfigParser {
@@ -235,6 +235,7 @@ export declare class ConfigParser {
     runtimeTarget: string | null;
     site: SiteRecord | null;
     siteStartPath: string;
+    siteConfigPath: string | null;
     constructor();
     static loadEnv(filePath: string, keepExisting?: boolean): void;
     static recommendedModels(): Record<string, Record<string, string>>;
@@ -252,6 +253,7 @@ export declare class ConfigParser {
     resolveProjectDir(relativeDir: string): string;
     isGlobalMode(): boolean;
     getSite(): SiteRecord | null;
+    getSiteConfigPath(): string | null;
     resolveTargetPath(target?: string): string;
     getStatesDir(): string;
     getPlansDir(): string;
@@ -260,7 +262,7 @@ export declare class ConfigParser {
     static setupTestConfig(): void;
     static getTestDirectories(): string[];
     static cleanupAllTestDirectories(): void;
-    enterGlobalMode(config: ExplorbotConfig, target: string | null): void;
+    enterGlobalMode(config: ExplorbotConfig, target: string | null): Promise<ExplorbotConfig>;
     applyEnvSpec(config: ExplorbotConfig): void;
     buildEnvConfig(baseUrl: string | undefined, outputRoot: string): Promise<ExplorbotConfig>;
     findConfigFile(): string | null;
@@ -271,7 +273,6 @@ export declare class ConfigParser {
     validateConfig(config: ExplorbotConfig): void;
     getNestedValue(obj: any, path: string): any;
     mergeWithDefaults(config: Partial<ExplorbotConfig>): ExplorbotConfig;
-    deepMerge(target: any, source: any): any;
     ensureDirectory(path: string): void;
 }
 export declare function setOutputDir(dir: string): void;

package/dist/src/config.js

@@ -13,8 +13,9 @@ import { pathToFileURL } from 'node:url';
 import { parseEnv } from 'node:util';
 import dedent from 'dedent';
 import matter from 'gray-matter';
-import { findGlobalConfig, globalEnvPath, isGlobalConfigPath, registerSite, resolveSiteTarget } from './global-config.js';
+import { EXPLORBOT_CONFIG_PATHS, findGlobalConfig, globalEnvPath, isGlobalConfigPath, loadSiteConfig, registerSite, resolveSiteTarget } from './global-config.js';
 import { getCliName } from './utils/cli-name.js';
+import { deepMerge } from './utils/merge.js';
 import { log, tag } from './utils/logger.js';
 export const PROVIDERS = {
     openai: { envKey: 'OPENAI_API_KEY', load: async () => (await import('@ai-sdk/openai')).createOpenAI() },
@@ -37,7 +38,7 @@ const config = {
         model: null,
     },
 };
-export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
+export { EXPLORBOT_CONFIG_PATHS };
 export const EXPLORBOT_ENV_VARS = [
     { name: 'EXPLORBOT_AI_PROVIDER', required: true, description: 'Provider name; fills every model role from its recommended models. Turns on config-free mode' },
     { name: 'EXPLORBOT_AI_MODEL', description: 'Pins the main model — a model id for the provider, or a standalone provider/model-id' },
@@ -62,6 +63,7 @@ export class ConfigParser {
     runtimeTarget = null;
     site = null;
     siteStartPath = '/';
+    siteConfigPath = null;
     constructor() { }
     static loadEnv(filePath, keepExisting = false) {
         const resolved = resolve(filePath);
@@ -125,14 +127,16 @@ export class ConfigParser {
                 sourcePath = join(outputRoot, 'explorbot.config.js');
                 log(`Configuration built from EXPLORBOT_* environment variables. Output: ${outputRoot}`);
             }
-            this.config = this.resolveConfig(loadedConfig, options);
-            await resolveConfigModels(this.config.ai);
-            this.runtimeTarget = target;
-            this.configPath = sourcePath;
+            let config = this.resolveConfig(loadedConfig, options);
+            await resolveConfigModels(config.ai);
             this.site = null;
+            this.siteConfigPath = null;
             if (resolvedPath && isGlobalConfigPath(resolvedPath)) {
-                this.enterGlobalMode(this.config, target);
+                config = await this.enterGlobalMode(config, target);
             }
+            this.config = config;
+            this.runtimeTarget = target;
+            this.configPath = sourcePath;
             this.applyEnvSpec(this.config);
             // Restore original directory after successful config load
             if (options?.path && originalCwd !== process.cwd()) {
@@ -186,6 +190,9 @@ export class ConfigParser {
     getSite() {
         return this.site;
     }
+    getSiteConfigPath() {
+        return this.siteConfigPath;
+    }
     resolveTargetPath(target) {
         if (!this.site) {
             const configured = this.config?.playwright?.url || this.config?.web?.url;
@@ -222,6 +229,7 @@ export class ConfigParser {
             ConfigParser.instance.runtimeTarget = null;
             ConfigParser.instance.site = null;
             ConfigParser.instance.siteStartPath = '/';
+            ConfigParser.instance.siteConfigPath = null;
         }
     }
     // For testing purposes only - sets up minimal default config
@@ -269,14 +277,20 @@ export class ConfigParser {
             // Ignore cleanup errors
         }
     }
-    enterGlobalMode(config, target) {
+    async enterGlobalMode(config, target) {
         const site = resolveSiteTarget(target || undefined, config.web?.url || config.playwright?.url);
         this.site = registerSite(site.baseUrl);
         this.siteStartPath = site.path;
-        config.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
-        config.playwright = { ...config.playwright, browser: config.playwright?.browser || 'chromium', url: site.baseUrl };
+        const { path: sitePath, config: siteConfig } = await loadSiteConfig(this.site.dir, site.baseUrl);
+        this.siteConfigPath = sitePath;
+        const merged = deepMerge(config, siteConfig);
+        await resolveConfigModels(merged.ai);
+        resolveLangfuse(merged.ai);
+        merged.dirs = { knowledge: 'knowledge', experience: 'experience', output: 'output' };
+        merged.playwright = { ...merged.playwright, browser: merged.playwright?.browser || 'chromium', url: site.baseUrl };
         materializeKnowledge(this.site.dir);
         log(`Global mode: ${site.baseUrl} stored in ${this.site.dir}`);
+        return merged;
     }
     applyEnvSpec(config) {
         const spec = process.env.EXPLORBOT_SPEC;
@@ -414,19 +428,7 @@ export class ConfigParser {
                 output: 'output',
             },
         };
-        return this.deepMerge(defaults, config);
-    }
-    deepMerge(target, source) {
-        const result = { ...target };
-        for (const key in source) {
-            if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) && source[key].constructor === Object) {
-                result[key] = this.deepMerge(result[key] || {}, source[key]);
-            }
-            else {
-                result[key] = source[key];
-            }
-        }
-        return result;
+        return deepMerge(defaults, config);
     }
     ensureDirectory(path) {
         if (!existsSync(path)) {

package/dist/src/global-config.d.ts

@@ -1,3 +1,4 @@
+export declare const EXPLORBOT_CONFIG_PATHS: string[];
 export declare function globalDir(): string;
 export declare function globalEnvPath(): string;
 export declare function globalConfigPath(): string;
@@ -6,6 +7,11 @@ export declare function isGlobalConfigPath(configPath: string): boolean;
 export declare function sitesDir(): string;
 export declare function siteFolderName(url: string): string;
 export declare function listSites(): SiteRecord[];
+export declare function findSiteConfig(dir: string): string | null;
+export declare function loadSiteConfig(dir: string, baseUrl: string): Promise<{
+    path: string;
+    config: any;
+}>;
 export declare function findSiteWith(subpath: string): SiteRecord | undefined;
 export declare function listSitePlanDirs(): string[];
 export declare function registerSite(baseUrl: string): SiteRecord;

package/dist/src/global-config.js

@@ -1,8 +1,19 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import os from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import dedent from 'dedent';
 const GLOBAL_CONFIG_NAMES = ['config.js', 'config.mjs', 'config.ts'];
 const SITE_DIRS = ['knowledge', 'experience', 'output'];
+export const EXPLORBOT_CONFIG_PATHS = ['explorbot.config.js', 'explorbot.config.mjs', 'explorbot.config.ts'];
 export function globalDir() {
     return join(os.homedir(), '.explorbot');
 }
@@ -13,12 +24,7 @@ export function globalConfigPath() {
     return join(globalDir(), 'config.js');
 }
 export function findGlobalConfig() {
-    for (const name of GLOBAL_CONFIG_NAMES) {
-        const fullPath = join(globalDir(), name);
-        if (existsSync(fullPath))
-            return fullPath;
-    }
-    return null;
+    return firstExisting(globalDir(), GLOBAL_CONFIG_NAMES);
 }
 export function isGlobalConfigPath(configPath) {
     return GLOBAL_CONFIG_NAMES.some((name) => join(globalDir(), name) === configPath);
@@ -38,6 +44,47 @@ export function listSites() {
         .filter((site) => !!site)
         .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
+export function findSiteConfig(dir) {
+    return firstExisting(dir, EXPLORBOT_CONFIG_PATHS);
+}
+function ensureSiteConfig(dir, baseUrl) {
+    const existing = findSiteConfig(dir);
+    if (existing)
+        return existing;
+    const path = join(dir, EXPLORBOT_CONFIG_PATHS[0]);
+    writeFileSync(path, siteConfigTemplate(baseUrl), 'utf8');
+    return path;
+}
+export async function loadSiteConfig(dir, baseUrl) {
+    const path = ensureSiteConfig(dir, baseUrl);
+    const module = await import(__rewriteRelativeImportExtension(pathToFileURL(resolve(path)).href));
+    const config = module.default || module;
+    validateSiteConfig(config, path, baseUrl);
+    return { path, config };
+}
+function validateSiteConfig(config, configPath, baseUrl) {
+    const url = config?.web?.url;
+    if (!url) {
+        throw new Error(dedent `
+      Site config is missing web.url.
+        ${configPath}
+
+      Add it so the config states which site it configures:
+        web: { url: '${baseUrl}' },
+    `);
+    }
+    const declared = URL.parse(url)?.origin;
+    if (declared === baseUrl)
+        return;
+    throw new Error(dedent `
+    Site config declares a different site.
+      ${configPath}
+      web.url:  ${url}
+      site:     ${baseUrl}
+
+    Fix web.url, or explore ${url} to register it as its own site.
+  `);
+}
 export function findSiteWith(subpath) {
     return listSites().find((site) => existsSync(join(site.dir, subpath)));
 }
@@ -88,6 +135,34 @@ export function resolveSiteTarget(target, defaultBaseUrl) {
     }
     return { baseUrl: site.url, path };
 }
+function firstExisting(dir, names) {
+    for (const name of names) {
+        const fullPath = join(dir, name);
+        if (existsSync(fullPath))
+            return fullPath;
+    }
+    return null;
+}
+function siteConfigTemplate(baseUrl) {
+    return `// Config for ${baseUrl}
+// Extends ~/.explorbot/config.js — set only what differs.
+const config = {
+  web: {
+    url: '${baseUrl}',
+  },
+
+  // ai: {
+  //   model: 'openrouter/openai/gpt-oss-120b',
+  // },
+
+  // playwright: {
+  //   show: true,
+  // },
+};
+
+export default config;
+`;
+}
 function readSite(folder) {
     const dir = join(sitesDir(), folder);
     const metaPath = join(dir, 'site.json');

package/dist/src/utils/code-extractor.js

@@ -1,11 +1,15 @@
 import { createDebug } from './logger.js';
 const debugLog = createDebug('explorbot:code-extractor');
+const JS_LANGUAGES = new Set(['', 'js', 'javascript']);
 export function extractCodeBlocks(aiResponse) {
-    const codeBlockRegex = /```(?:js|javascript)?\s*\n([\s\S]*?)\n```/g;
+    const codeBlockRegex = /```([^\n`]*)\n([\s\S]*?)\n```/g;
     const codeBlocks = [];
     let match = null;
     while ((match = codeBlockRegex.exec(aiResponse))) {
-        const code = match[1].trim();
+        const language = match[1].trim().toLowerCase();
+        if (!JS_LANGUAGES.has(language))
+            continue;
+        const code = match[2].trim();
         if (!code)
             continue;
         try {

package/dist/src/utils/html.js

@@ -1283,6 +1283,12 @@ function cleanElement(element) {
         'aria-labelledby',
         'aria-describedby',
         'aria-owns',
+        'aria-checked',
+        'aria-expanded',
+        'aria-selected',
+        'aria-pressed',
+        'aria-current',
+        'aria-disabled',
         'role',
         'title',
         'href',

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

@@ -0,0 +1 @@
+export declare function deepMerge(target: any, source: any): any;

package/dist/src/utils/merge.js

@@ -0,0 +1,11 @@
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) && source[key].constructor === Object) {
+            result[key] = deepMerge(result[key] || {}, source[key]);
+            continue;
+        }
+        result[key] = source[key];
+    }
+    return result;
+}

package/docs/reference/commands.md

@@ -127,7 +127,7 @@ EXPLORBOT_AI_PROVIDER=openrouter \
 
 `npx explorbot recommended-models` prints, per provider, the model this version recommends for each role, and the two ways to select it. Both need the provider's API key exported. Set `EXPLORBOT_AI_PROVIDER=<name>` and every role takes that provider's recommendation; leave it out and pin the roles yourself with `EXPLORBOT_AI_MODEL`, `EXPLORBOT_VISION_MODEL` and `EXPLORBOT_AGENTIC_MODEL`, each written as `provider/model-id` — the command prints those three lines filled in, ready to paste. A role a provider does not serve is named as such, so you know to pair it with another. It closes with the model variables and provider keys currently exported, and a ready-to-run OpenRouter one-liner. It reads nothing but the bundled recommendations, so it answers before any configuration exists and every CLI carries it: `npx explorbot api recommended-models`, `npx explorbot docs recommended-models`, `npx prima recommended-models`. `--json` prints the bundled recommendations as an object.
 
-Explorbot resolves its configuration in this order: the path given to `--config`, then `explorbot.config.*` in the working directory, then the `EXPLORBOT_*` variables, and finally `~/.explorbot/config.*` from the global installation. A bare provider name fills every model role from the recommendations in [Providers](../basics/providers.md); a `provider/model-id` spec pins one model and splits on the first slash, so `openrouter/openai/gpt-oss-120b:nitro` selects OpenRouter with model `openai/gpt-oss-120b:nitro`. Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`.
+Explorbot resolves its configuration in this order: the path given to `--config`, then `explorbot.config.*` in the working directory, then the `EXPLORBOT_*` variables, and finally `~/.explorbot/config.*` from the global installation, which each site then extends with its own [per-site config](configuration.md#per-site-configuration). A bare provider name fills every model role from the recommendations in [Providers](../basics/providers.md); a `provider/model-id` spec pins one model and splits on the first slash, so `openrouter/openai/gpt-oss-120b:nitro` selects OpenRouter with model `openai/gpt-oss-120b:nitro`. Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`.
 
 In this mode output goes to `~/.explorbot/sites/<host>/output/` (or `EXPLORBOT_OUTPUT`, or a temp directory with `EXPLORBOT_EPHEMERAL=1`), experience is kept beside it unless the run is ephemeral, and the Historian is off, so no generated test files appear. See [Agentic Usage](../workflow/agentic-usage.md) for the full picture.
 
@@ -934,12 +934,20 @@ See [Configuration](configuration.md#running-from-anywhere-the-global-installati
 
 ### `npx explorbot sites`
 
-List the sites registered in the global installation — folder name, base URL, and last run. Sites register themselves the first time you explore them by URL.
+List the sites registered in the global installation — folder name, base URL, last run, and the [per-site config](configuration.md#per-site-configuration) each one uses. Sites register themselves the first time you explore them by URL.
 
 ```bash
 npx explorbot sites
 ```
 
+```
+Registered sites (2):
+  app.example.com    https://app.example.com    last run 2026-09-16 09:57
+                     /home/you/.explorbot/sites/app.example.com/explorbot.config.js
+  other.example.com  https://other.example.com  last run 2026-09-01 10:00
+                     inherits global config
+```
+
 ### `npx explorbot clean [target]`
 
 Clean generated files. Targets: `states`, `research`, `plans`, `tests`, `experiences`, `output`.

package/docs/reference/configuration.md

@@ -413,7 +413,7 @@ Explorbot looks for a config file in this order:
 7. `src/config/explorbot.config.js`
 8. `src/config/explorbot.config.mjs`
 9. `src/config/explorbot.config.ts`
-10. `~/.explorbot/config.js` (or `.mjs`, `.ts`) — the global installation
+10. `~/.explorbot/config.js` (or `.mjs`, `.ts`) — the global installation, extended per site by `~/.explorbot/sites/<host>/explorbot.config.js`
 
 Or pass a custom path:
 
@@ -431,14 +431,15 @@ Env files fill in rather than override: the `.env` of the working directory is r
 
 ```
 ~/.explorbot/
-├── config.js            # AI models and keys, no URL
+├── config.js                    # AI models and keys, shared by every site
 ├── .env
 └── sites/
     ├── app.example.com/
-    │   ├── site.json    # base URL, first and last run
+    │   ├── explorbot.config.js  # this site's settings, extends config.js
+    │   ├── site.json            # base URL, first and last run
     │   ├── knowledge/
     │   ├── experience/
-    │   └── output/      # states, plans, reports, tests
+    │   └── output/              # states, plans, reports, tests
     └── localhost_3000/
 ```
 
@@ -456,6 +457,38 @@ npx explorbot sites                                   # list registered sites
 
 A `dirs` section in the global config is ignored in favor of the layout above. A `web.url` is allowed and acts as the default site for commands that pass no URL of their own.
 
+#### Per-site configuration
+
+`~/.explorbot/config.js` holds what every site shares — models, keys, reporter settings. Anything one site needs differently goes in its own `explorbot.config.js`, written into the site folder the first time that site is explored:
+
+```javascript
+// Config for https://app.example.com
+// Extends ~/.explorbot/config.js — set only what differs.
+const config = {
+  web: {
+    url: 'https://app.example.com',
+  },
+
+  ai: {
+    model: 'openrouter/anthropic/claude-sonnet-5',
+  },
+
+  playwright: {
+    show: true,
+  },
+};
+
+export default config;
+```
+
+The two are merged section by section, and the site wins. A site that overrides `ai.model` keeps the global `ai.visionModel`. Use it to give a slow or unusual app a stronger model, a visible browser, or its own reporter settings, without changing how every other site runs.
+
+`web.url` is required, and must be the site the folder belongs to — it is what makes the file readable on its own rather than meaningful only by where it sits. Explorbot refuses to run when it is missing or names a different site, instead of quietly ignoring the mismatch. To configure a different site, explore it and edit the config in its own folder.
+
+`dirs` and the base URL stay owned by the layout above and cannot be overridden. The file is never rewritten once created, and a site without one simply uses the global config.
+
+Per-site configs apply to the global installation only. A directory with its own `explorbot.config.js` and the `EXPLORBOT_*` environment mode below both resolve to a single config with nothing to extend.
+
 ### Running without a config file
 
 When the working directory has no config file and `EXPLORBOT_AI_PROVIDER` (or `EXPLORBOT_AI_MODEL`) is set, Explorbot synthesizes a configuration from `EXPLORBOT_*` environment variables, in preference to a global installation. Output goes to the site folder `~/.explorbot/sites/<host>/` (`EXPLORBOT_OUTPUT` overrides it, `EXPLORBOT_EPHEMERAL=1` sends it to a temp directory instead), experience is written there and reused by later runs against the same host unless the run is ephemeral, and the Historian is off. This is meant for one-liner CI jobs, demos, and coding agents — see [Agentic Usage](../workflow/agentic-usage.md) for the variable list and the trade-offs.