explorbot 0.4.8 → 0.4.10

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/explorer.js

@@ -13,6 +13,7 @@ import { ConfigParser } from './config.js';
 import { BrowserRecoveryError, browserErrorMessage, isFatalBrowserError, isNavigationTransitionError } from "./utils/browser-errors.js";
 import { createDebug, log, tag } from './utils/logger.js';
 import { sleep, waitForPageReadiness } from "./utils/page-readiness.js";
+import { isInternalStep } from "./utils/step-analyzer.js";
 const debugLog = createDebug('explorbot:explorer');
 const RECOVERABLE_NAVIGATION_ERRORS = /net::ERR_ABORTED|page\.screenshot.*Timeout|waiting for fonts to load/i;
 const RECOVERY_NAVIGATION = { waitUntil: 'domcontentloaded', timeout: 10000 };
@@ -161,9 +162,7 @@ class Explorer {
         const stepHandler = (step, status, error, log) => {
             if (!step.toCode)
                 return;
-            if (step?.name?.startsWith('grab'))
-                return;
-            if (step?.name?.startsWith('save'))
+            if (isInternalStep(step))
                 return;
             test.addStep(step.toCode(), step.duration, status, error, log);
             if (!this.stateManager.getCurrentState())

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/reporter.js

@@ -111,6 +111,7 @@ export class Reporter {
     }
     combineStepsAndNotes(test, lastScreenshotFile) {
         const noteEntries = Object.entries(test.notes)
+            .filter(([, note]) => !note.observation)
             .map(([timestampKey, note]) => ({
             startTime: note.startTime,
             endTime: note.endTime,
@@ -233,9 +234,12 @@ export class Reporter {
                 description: test.description,
                 code: test.generatedCode || '',
                 steps,
-                logs: Object.values(test.steps)
-                    .map((stepData) => stepData.text)
-                    .join('\n'),
+                logs: [
+                    ...Object.values(test.steps).map((stepData) => stepData.text),
+                    ...Object.values(test.notes)
+                        .filter((note) => note.observation)
+                        .map((note) => note.message),
+                ].join('\n'),
                 files: Object.values(test.artifacts) || [],
                 message: test.summary || this.extractLastNoteMessage(test) || '',
                 meta,
@@ -300,7 +304,7 @@ export class Reporter {
         }
     }
     extractLastNoteMessage(test) {
-        const notes = Object.values(test.notes);
+        const notes = Object.values(test.notes).filter((note) => !note.observation);
         if (notes.length === 0)
             return '';
         return notes[notes.length - 1].message;

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/logger.js

@@ -189,7 +189,7 @@ class SpanDestination {
         if (!step?.toCode) {
             return;
         }
-        const stepName = step?.name ? `I.${step.name}` : 'I.step';
+        const stepName = step?.title ? `I.${step.title}` : 'I.step';
         const stepInput = typeof step?.toCode === 'function' ? step.toCode() : entry.content;
         const errorFromStep = step?.error;
         const errorMessage = stepError && typeof stepError === 'object' && 'message' in stepError && typeof stepError.message === 'string'

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/dist/src/utils/step-analyzer.d.ts

@@ -9,3 +9,6 @@ export declare function stripComments(code: string): string;
 export declare function isNonReusableCode(code: string): boolean;
 export declare function toReusableSessionStep(step: StepData): SessionStep | null;
 export declare function mergeUniqueStepsByCode(primary: SessionStep[], secondary: SessionStep[]): SessionStep[];
+export declare function isInternalStep(step: {
+    title?: string;
+}): boolean;

package/dist/src/utils/step-analyzer.js

@@ -1,5 +1,6 @@
 import { isDynamicId } from "./xpath.js";
 export const CODECEPT_TOOLS = ['click', 'hover', 'pressKey', 'form'];
+const INTERNAL_STEP_PREFIXES = ['grab', 'save'];
 const CODECEPT_FORM_COMMANDS = ['I.fillField', 'I.type', 'I.selectOption', 'I.attachFile', 'I.checkOption', 'I.uncheckOption'];
 export function isCodeceptToolName(toolName) {
     return CODECEPT_TOOLS.includes(toolName);
@@ -66,3 +67,9 @@ export function mergeUniqueStepsByCode(primary, secondary) {
     }
     return merged;
 }
+export function isInternalStep(step) {
+    const title = step?.title;
+    if (!title)
+        return false;
+    return INTERNAL_STEP_PREFIXES.some((prefix) => title.startsWith(prefix));
+}

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

@@ -6,3 +6,4 @@ export declare function generalizeUrl(url: string, replaceSegment?: (segment: st
 export declare function matchesUrl(pattern: string, path: string): boolean;
 export declare function extractStatePath(url: string): string;
 export declare function matchesNavigationUrl(expected: string, current: string): boolean;
+export declare function isSameHostFamily(urlA: string, urlB: string): boolean;

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

@@ -145,3 +145,10 @@ export function matchesNavigationUrl(expected, current) {
         .filter(Boolean);
     return recordSegments.length > 0 && recordSegments.every(isDynamicSegment);
 }
+export function isSameHostFamily(urlA, urlB) {
+    const hostA = URL.parse(urlA)?.host.toLowerCase();
+    const hostB = URL.parse(urlB)?.host.toLowerCase();
+    if (!hostA || !hostB)
+        return false;
+    return hostA === hostB || hostA.endsWith(`.${hostB}`) || hostB.endsWith(`.${hostA}`);
+}

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.