explorbot 0.4.1 → 0.4.2

package/src/ai/tools.ts

@@ -15,7 +15,6 @@ import { pause } from '../utils/loop.js';
 import { WebElement } from '../utils/web-element.ts';
 import type { ToolDeps } from './agent.ts';
 import { Navigator } from './navigator.ts';
-import type { AIProvider } from './provider.ts';
 import { Researcher } from './researcher.ts';
 import { sectionContextRule } from './rules.ts';
 import { isInteractive } from './task-agent.ts';
@@ -31,7 +30,7 @@ interface AgentToolDeps extends ToolDeps {
 
 export const ASSERTION_TOOLS = ['verify'] as const;
 
-export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task) {
+export function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task) {
   return {
     click: tool({
       description: dedent`
@@ -44,6 +43,12 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           Container narrows search area. Use when page has multiple matching elements.
           Example: Page has 3 "Delete" buttons in different rows:
           I.click("Delete", ".row-1") - clicks Delete inside element with class row-1
+        I.click(locator, step.opts({ elementIndex: N })) - click the Nth element the locator matches
+          Use after a result reported several matches. N is the "Element N" number from that list.
+          step.opts() always goes LAST, after the container when there is one.
+          Example: the result listed 3 "Delete" buttons and you want the second:
+          I.click("Delete", step.opts({ elementIndex: 2 }))
+          I.click("Delete", ".table", step.opts({ elementIndex: 2 })) - same, narrowed to a container
 
         IMPORTANT: This tool ONLY accepts click commands. For typing text, use form() tool.
         CRITICAL: All commands MUST target the SAME element using different locators.
@@ -62,6 +67,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           3. I.click(CSS, container) - e.g. I.click("#btn", ".modal")
           4. I.click(CSS) or I.click(XPath) - when locator already includes context (ID, XPath)
           5. I.clickXY(x, y) - coordinates fallback
+          After a result reporting multiple matches, reuse that locator with step.opts({ elementIndex: N }) as the last argument.
         `),
         explanation: z.string().describe('Why you are clicking this element'),
       }),
@@ -91,6 +97,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
         const previousState = ActionResult.fromState(stateManager.getCurrentState()!);
         const action = explorer.action();
         const attempts: Array<{ command: string; success: boolean; error?: string }> = [];
+        let ambiguityError: Error | null = null;
 
         for (let i = 0; i < commands.length; i++) {
           const command = transformContainsCommand(commands[i]);
@@ -100,6 +107,8 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           if (action.lastError) attempt.error = errorText(action.lastError);
           attempts.push(attempt);
 
+          if (!ambiguityError && action.lastError?.name === 'MultipleElementsFound') ambiguityError = action.lastError;
+
           if (success) {
             const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, command);
             await commitNote(activeNote, TestResult.PASSED, toolResult, action);
@@ -107,31 +116,6 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
           }
         }
 
-        let disambiguated = null;
-        if (attempts.some((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
-          disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-        }
-
-        if (disambiguated) {
-          debugLog('Disambiguation picked element %d', disambiguated.position);
-          const failedCommand = attempts.find((a) => a.error?.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))?.command;
-          const retryCommands = [];
-          if (failedCommand) {
-            retryCommands.push(failedCommand.replace(/\)$/, `, step.opts({ elementIndex: ${disambiguated.position} }))`));
-          }
-          retryCommands.push(`I.click('${disambiguated.xpath.replace(/'/g, "\\'")}')`);
-
-          for (const retryCmd of retryCommands) {
-            if (!(await action.attempt(retryCmd, explanation))) {
-              attempts.push({ command: retryCmd, success: false, error: errorText(action.lastError) });
-              continue;
-            }
-            const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, retryCmd);
-            await commitNote(activeNote, TestResult.PASSED, toolResult, action);
-            return successToolResult('click', { ...toolResult, attempts, code: retryCmd, disambiguated: true }, action);
-          }
-        }
-
         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()!).toToolResult(previousState, commands[0]);
         await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
@@ -145,7 +129,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             attempts,
             suggestion,
           },
-          action.lastError
+          ambiguityError || action.lastError
         );
       },
     }),
@@ -413,13 +397,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps,
             const message = errorText(action.lastError);
             await commitNote(activeNote, TestResult.FAILED, toolResult, action);
 
-            let formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
-            if (message.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN)) {
-              const disambiguated = await disambiguateElements(action.lastError, explanation, ai);
-              if (disambiguated) {
-                formSuggestion = `Multiple elements matched. Add step.opts({ elementIndex: ${disambiguated.position} }) to the failing command. Fallback locator: ${disambiguated.xpath}`;
-              }
-            }
+            const formSuggestion = 'Commands after the failing one never ran. Retry only those, using click() or form().';
 
             return failedToolResult(
               'form',
@@ -1284,13 +1262,11 @@ export async function failedToolResult(action: string, message: string, data?: R
 
 function getMultipleElementsSuggestion(): string {
   return dedent`
-    Multiple elements matched your locator. To fix this:
-    1. Use container context: I.click({ "role": "button", "text": "Submit" }, '.form-container')
-    2. Use more specific CSS: target the actual element (input, button, a) not wrapper divs
-    3. Add distinguishing attributes: input[type="submit"], button[type="submit"], [value="..."]
-    4. If buttons have similar text like "Create" and "Create Demo", use the FULL unique text
-    5. Use xpathCheck() to inspect matched elements and pick the correct one
-    6. Use visualClick() to click the right element by visual appearance
+    Multiple elements matched your locator, so that command did nothing — it selected no element and acted on none.
+    Read the numbered elements list and click the one you meant by its number:
+    reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    If none of them is the element you want, narrow the locator with a container or its full unique text.
+    If the list is missing, call xpathCheck() to see what the locator matches.
   `;
 }
 
@@ -1367,50 +1343,6 @@ export async function formatMatchedElements(error: Error | null | undefined): Pr
   return formatElementList(details);
 }
 
-async function disambiguateElements(error: Error | null | undefined, explanation: string, provider: AIProvider): Promise<{ position: number; xpath: string } | null> {
-  const elementDetails = await extractWebElements(error);
-  if (!elementDetails) return null;
-
-  const elementList = formatElementList(elementDetails);
-
-  const schema = z.object({
-    position: z.number().nullable().describe('1-based position of the correct element, or null if none match'),
-  });
-
-  try {
-    const result = await provider.generateObject(
-      [
-        {
-          role: 'user' as const,
-          content: dedent`
-            A click action failed because multiple elements matched the locator.
-            The intended action was: ${explanation}
-
-            Here are the matched elements:
-
-            ${elementList}
-
-            Which element (1-${elementDetails.length}) best matches the intended action?
-            Return the position number, or null if none of them match.
-          `,
-        },
-      ],
-      schema,
-      provider.getModelForAgent(),
-      { agentName: 'disambiguator', timeout: 15000 }
-    );
-
-    const position = result?.object?.position;
-    if (position && position >= 1 && position <= elementDetails.length) {
-      return { position, xpath: elementDetails[position - 1].xpath };
-    }
-    return null;
-  } catch (e) {
-    debugLog('Element disambiguation AI call failed: %s', e);
-    return null;
-  }
-}
-
 function getNotFoundSuggestion(errorMessage: string): string | null {
   if (!errorMessage.includes('not found')) {
     return null;

package/src/api/request-store.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { isDynamicSegment } from '../utils/url-matcher.ts';
+import { generalizeUrl, isDynamicSegment } from '../utils/url-matcher.ts';
 import { RequestResult } from './request-result.ts';
 
 const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
@@ -46,10 +46,6 @@ export class RequestStore {
     result.save(this.outputDir);
   }
 
-  addRequest(result: RequestResult): void {
-    this.addMadeRequest(result);
-  }
-
   getCapturedRequests(): RequestResult[] {
     return this.capturedRequests;
   }
@@ -58,27 +54,10 @@ export class RequestStore {
     return this.madeRequests;
   }
 
-  getRequests(): RequestResult[] {
-    return this.madeRequests;
-  }
-
   getLastRequest(): RequestResult | undefined {
     return this.madeRequests[this.madeRequests.length - 1];
   }
 
-  getRequestsByEndpoint(pathPrefix: string): RequestResult[] {
-    return this.madeRequests.filter((r) => r.path.startsWith(pathPrefix));
-  }
-
-  getRequestsByMethod(method: string): RequestResult[] {
-    const upper = method.toUpperCase();
-    return this.madeRequests.filter((r) => r.method === upper);
-  }
-
-  getRequestsByStatus(status: number): RequestResult[] {
-    return this.madeRequests.filter((r) => r.status === status);
-  }
-
   toEndpointList(scopePath?: string): string {
     let requests = this.capturedRequests;
     if (scopePath) requests = this.getWriteRequestsForScope(scopePath);
@@ -87,7 +66,7 @@ export class RequestStore {
     const lines: string[] = [];
 
     for (const req of requests) {
-      const key = `${req.method} ${normalizePathPattern(req.path)}`;
+      const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}`;
       if (seen.has(key)) continue;
       seen.add(key);
       lines.push(key);
@@ -113,14 +92,18 @@ export class RequestStore {
 
   findCapturedRequest(method: string, searchPath: string): RequestResult | undefined {
     const upper = method.toUpperCase();
-    const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+    const search = generalizeUrl(searchPath, () => '{id}')
+      .split('/')
+      .filter(Boolean);
 
     let best: RequestResult | undefined;
     let bestScore = -1;
 
     for (const req of this.capturedRequests) {
       if (req.method !== upper) continue;
-      const segments = normalizePathPattern(req.path).split('/').filter(Boolean);
+      const segments = generalizeUrl(req.path, () => '{id}')
+        .split('/')
+        .filter(Boolean);
       if (segments.length < search.length) continue;
       if (!search.every((segment, i) => segment === segments[i])) continue;
 
@@ -159,8 +142,7 @@ export class RequestStore {
   }
 
   getWriteRequestsForScope(scopePath: string): RequestResult[] {
-    const writeMethods = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
-    const writes = this.capturedRequests.filter((r) => writeMethods.has(r.method));
+    const writes = this.capturedRequests.filter((r) => r.isWrite);
     const scopeSegments = scopePath.split('/').filter(Boolean);
     if (scopeSegments.length === 0) return writes;
 
@@ -191,6 +173,10 @@ export class RequestStore {
   }
 }
 
+export function isFailedRequest(request: RequestResult): boolean {
+  return request.status >= 400 || Boolean(request.error);
+}
+
 function normalizePathPattern(urlPath: string): string {
   return urlPath
     .split('/')

package/src/commands/config-command.ts

@@ -5,6 +5,7 @@ import { type AIConfig, ConfigParser, EXPLORBOT_ENV_VARS, type ReporterConfig, c
 import { listSites } from '../global-config.js';
 import { Reporter } from '../reporter.js';
 import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
 import { tag } from '../utils/logger.js';
 import { BaseCommand } from './base-command.js';
 
@@ -75,13 +76,7 @@ export class ConfigCommand extends BaseCommand {
     if (options.json) return JSON.stringify(data, null, 2);
 
     const lines: string[] = [];
-    const section = (title: string, entries: [string, string][]) => {
-      if (!entries.length) return;
-      const width = Math.max(...entries.map(([label]) => label.length));
-      lines.push(chalk.bold(title));
-      for (const [label, value] of entries) lines.push(`  ${chalk.dim(label.padEnd(width))}  ${value}`);
-      lines.push('');
-    };
+    const section = (title: string, entries: [string, string][]) => lines.push(...renderSection(title, entries));
 
     const general: [string, string][] = [['config', data.config || 'EXPLORBOT_* environment variables']];
     if (data.url) general.push(['url', data.url]);

package/src/commands/index.ts

@@ -28,6 +28,7 @@ import { PlanLoadCommand } from './plan-load-command.js';
 import { PlanReloadCommand } from './plan-reload-command.js';
 import { PlanSaveCommand } from './plan-save-command.js';
 import { PlansCommand } from './plans-command.js';
+import { RecommendedModelsCommand } from './recommended-models-command.js';
 import { RerunCommand } from './rerun-command.js';
 import { ResearchCommand } from './research-command.js';
 import { RunsCommand } from './runs-command.js';
@@ -72,6 +73,7 @@ const commandClasses: CommandClass[] = [
   RerunCommand,
   StatusCommand,
   ConfigCommand,
+  RecommendedModelsCommand,
   DebugCommand,
   ExitCommand,
 ];

package/src/commands/init-command.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, extname, join, resolve } from 'node:path';
 import chalk from 'chalk';
-import { ConfigParser, PROVIDERS } from '../config.ts';
+import { ConfigParser, type ModelRole, PROVIDERS, missingModelRoles } from '../config.ts';
 import { findGlobalConfig, globalConfigPath, globalDir, globalEnvPath } from '../global-config.ts';
 import { getCliName } from '../utils/cli-name.ts';
 import { log, tag } from '../utils/logger.js';
@@ -91,7 +91,7 @@ export function writeGlobalConfig(provider: string, apiKey?: string): void {
   writeEnvKey(envKey, apiKey || '');
   log(`Stored ${envKey} in ${globalEnvPath()}`);
 
-  const missing = missingRoles(provider);
+  const missing = missingModelRoles(provider);
   if (missing.length) {
     tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${globalConfigPath()}`);
   }
@@ -156,7 +156,7 @@ export function runInitCommand(options: InitCommandOptions): void {
       log(`Env file already exists: ${relativeToCwd(envPath)}`);
     }
 
-    const missing = missingRoles(provider);
+    const missing = missingModelRoles(provider);
     if (missing.length) {
       tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${relativeToCwd(outPath)}`);
     }
@@ -255,7 +255,7 @@ async function renderLocalProviderWizard(): Promise<string | null> {
 
 function modelLines(provider: string): string {
   const recommended = ConfigParser.recommendedModels()[provider] || {};
-  const roles: Array<[ModelRoleName, string]> = [
+  const roles: Array<[ModelRole, string]> = [
     ['model', 'fast model with tool calling capabilities'],
     ['visionModel', 'vision model for screenshot analysis'],
     ['agenticModel', 'agentic model for decision making'],
@@ -308,11 +308,6 @@ function isModuleProject(configDir: string): boolean {
   }
 }
 
-function missingRoles(provider: string): string[] {
-  const recommended = ConfigParser.recommendedModels()[provider] || {};
-  return ['model', 'visionModel', 'agenticModel'].filter((role) => !recommended[role]);
-}
-
 function writeEnvKey(key: string, value: string): void {
   const envPath = globalEnvPath();
   let content = '# AI provider API keys';
@@ -327,8 +322,6 @@ function writeEnvKey(key: string, value: string): void {
   writeFileSync(envPath, `${lines.join('\n').trimEnd()}\n`, 'utf8');
 }
 
-type ModelRoleName = 'model' | 'visionModel' | 'agenticModel';
-
 type InitCommandOptions = {
   configPath?: string;
   force?: boolean;

package/src/commands/plans-command.ts

@@ -21,8 +21,7 @@ export class PlansCommand extends BaseCommand {
       return;
     }
 
-    const file = this.resolvePlanFile(target, files);
-    const plan = Plan.fromMarkdown(file.path);
+    const { plan, file } = this.resolvePlanFile(target, files);
     this.printPlanDetails(plan, file);
   }
 
@@ -71,12 +70,12 @@ export class PlansCommand extends BaseCommand {
     tag('info').log(`${getCliName()} test 1 --from-plan ${file.name}`);
   }
 
-  private resolvePlanFile(target: string, files: PlanFile[]): PlanFile {
+  private resolvePlanFile(target: string, files: PlanFile[]): { plan: Plan; file: PlanFile } {
     const index = Number.parseInt(target, 10);
     if (!Number.isNaN(index) && String(index) === target) {
       const file = files[index - 1];
       if (!file) throw new Error(`Plan #${target} not found. Available: 1-${files.length}`);
-      return file;
+      return { plan: Plan.fromMarkdown(file.path), file };
     }
 
     const plan = Plan.loadFromFile(target, this.explorBot.getPlansDir());
@@ -84,11 +83,12 @@ export class PlansCommand extends BaseCommand {
       throw new Error(`Plan file not found: ${target}`);
     }
 
-    return {
+    const file = {
       name: path.basename(plan.filePath),
       path: plan.filePath,
       modifiedAt: statSync(plan.filePath).mtimeMs,
     };
+    return { plan, file };
   }
 }
 

package/src/commands/recommended-models-command.ts

@@ -0,0 +1,92 @@
+import chalk from 'chalk';
+import type { Command } from 'commander';
+import { ConfigParser, EXPLORBOT_ENV_VARS, MODEL_ROLES, PROVIDERS } from '../config.js';
+import { getCliName } from '../utils/cli-name.js';
+import { renderSection } from '../utils/cli-section.js';
+import { tag } from '../utils/logger.js';
+import { BaseCommand } from './base-command.js';
+
+const DESCRIPTION = 'Show the models recommended for every AI provider';
+
+const ROLES: Record<string, { hint: string; env: string }> = {
+  model: { hint: 'fast', env: 'EXPLORBOT_AI_MODEL' },
+  visionModel: { hint: 'screenshots', env: 'EXPLORBOT_VISION_MODEL' },
+  agenticModel: { hint: 'smart', env: 'EXPLORBOT_AGENTIC_MODEL' },
+};
+
+const MODEL_ENV_VARS = MODEL_ROLES.map((role) => ROLES[role].env);
+
+export class RecommendedModelsCommand extends BaseCommand {
+  name = 'recommended-models';
+  description = DESCRIPTION;
+
+  async execute(): Promise<void> {
+    tag('info').log(RecommendedModelsCommand.render());
+  }
+
+  static register(program: Command): void {
+    program
+      .command('recommended-models')
+      .description(DESCRIPTION)
+      .option('--json', 'Print the recommendations as JSON')
+      .action((options) => console.log(RecommendedModelsCommand.render(options.json)));
+  }
+
+  static render(json = false): string {
+    const recommended = ConfigParser.recommendedModels();
+    if (json) return JSON.stringify(recommended, null, 2);
+
+    const lines = [
+      chalk.bold('Export the provider key, then pick one of two ways to select models:'),
+      `  ${chalk.bold('EXPLORBOT_AI_PROVIDER')} — every role takes that provider's recommendation below`,
+      `  ${chalk.bold(MODEL_ENV_VARS.join(' + '))} — no provider variable, pin every role yourself as ${chalk.dim('provider/model-id')}`,
+      '',
+    ];
+
+    for (const [provider, roles] of Object.entries(recommended)) {
+      lines.push(chalk.bold.yellow(`${provider}:`));
+
+      const models: [string, string][] = [];
+      for (const role of MODEL_ROLES) {
+        const label = `${role} (${ROLES[role].hint})`;
+        if (roles[role]) models.push([label, roles[role]]);
+        if (!roles[role]) models.push([label, chalk.dim('not served, pair with another provider')]);
+      }
+      lines.push(...renderSection('models', models, 2));
+
+      const envKey = PROVIDERS[provider]?.envKey;
+      if (!envKey) {
+        lines.push(`  ${chalk.dim('not bundled — import the provider in your config')}`, '');
+        continue;
+      }
+
+      const env: [string, string][] = [
+        ['key', envKey],
+        ['provider', `EXPLORBOT_AI_PROVIDER=${provider}`],
+      ];
+      let label = 'or models';
+      for (const role of MODEL_ROLES) {
+        if (!roles[role]) continue;
+        env.push([label, `${ROLES[role].env}=${provider}/${roles[role]}`]);
+        label = '';
+      }
+      lines.push(...renderSection('env variables', env, 2));
+    }
+
+    const modelVars = ['EXPLORBOT_AI_PROVIDER', ...MODEL_ENV_VARS];
+    const current: [string, string][] = [];
+    for (const variable of EXPLORBOT_ENV_VARS) {
+      if (!modelVars.includes(variable.name)) continue;
+      if (process.env[variable.name]) current.push([variable.name, process.env[variable.name]!]);
+    }
+    for (const [provider, { envKey }] of Object.entries(PROVIDERS)) {
+      if (process.env[envKey]) current.push([envKey, chalk.dim(`set, ${provider} usable`)]);
+    }
+
+    if (!current.length) lines.push(chalk.dim('Nothing set — export one of the variables above, or write models into your config'), '');
+    if (current.length) lines.push(...renderSection('Currently set', current));
+
+    lines.push(chalk.bold('Example using OpenRouter:'), `  OPENROUTER_API_KEY=sk-... EXPLORBOT_AI_PROVIDER=openrouter ${getCliName()} <command>`);
+    return lines.join('\n');
+  }
+}

package/src/config.ts

@@ -19,6 +19,8 @@ export const PROVIDERS: Record<string, ProviderInfo> = {
   sambanova: { envKey: 'SAMBANOVA_API_KEY', load: async () => (await import('sambanova-ai-provider')).createSambaNova() },
 };
 
+export const MODEL_ROLES: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
+
 let cachedOutputRoot: string | null = null;
 
 interface PlaywrightConfig {
@@ -765,6 +767,11 @@ export async function resolveModel(spec: string, role: ModelRole = 'model'): Pro
   return createModel(spec, modelId);
 }
 
+export function missingModelRoles(provider: string): ModelRole[] {
+  const recommended = ConfigParser.recommendedModels()[provider] || {};
+  return MODEL_ROLES.filter((role) => !recommended[role]);
+}
+
 export class ConfigMissingError extends Error {}
 
 export function envConfigRequested(): boolean {
@@ -786,6 +793,7 @@ export function missingConfigMessage(configFile = 'explorbot.config.js'): string
         EXPLORBOT_AI_PROVIDER=openrouter EXPLORBOT_URL=https://your-app.example.com ${cli} ...
 
     Providers: ${Object.keys(PROVIDERS).join(', ')}
+    See the models each one recommends: ${cli} recommended-models
   `;
 }
 
@@ -818,8 +826,7 @@ export function configuredModels(ai?: AIConfig): Record<string, ConfiguredModel>
 export async function resolveConfigModels(ai?: AIConfig): Promise<void> {
   if (!ai) return;
 
-  const roles: ModelRole[] = ['model', 'visionModel', 'agenticModel'];
-  for (const role of roles) {
+  for (const role of MODEL_ROLES) {
     if (typeof ai[role] === 'string') ai[role] = await resolveModel(ai[role], role);
   }
 

package/src/experience-tracker.ts

@@ -127,7 +127,7 @@ export class ExperienceTracker {
         url: state.url ? extractStatePath(state.url) : '',
         title: state.title,
       };
-      if (state.overlay.present && state.overlay.name) {
+      if (state.overlay.isOpen && state.overlay.name) {
         frontmatter.region = state.overlay.name;
         if (state.overlay.root) frontmatter.root = state.overlay.root;
       }

package/src/explorbot.ts

@@ -465,9 +465,9 @@ export class ExplorBot {
   }
 
   loadPlans(filename: string): Plan[] {
-    const plan = Plan.loadFromFile(filename, this.getPlansDir());
-    if (!plan?.filePath) throw new Error(`Plan file not found: ${filename}`);
-    return parsePlansFromMarkdown(plan.filePath);
+    const filePath = Plan.resolveFile(filename, this.getPlansDir());
+    if (!filePath) throw new Error(`Plan file not found: ${filename}`);
+    return parsePlansFromMarkdown(filePath);
   }
 
   setCurrentPlan(plan?: Plan): void {

package/src/global-config.ts

@@ -47,6 +47,14 @@ export function listSites(): SiteRecord[] {
     .sort((a, b) => b.lastRunAt.localeCompare(a.lastRunAt));
 }
 
+export function findSiteWith(subpath: string): SiteRecord | undefined {
+  return listSites().find((site) => existsSync(join(site.dir, subpath)));
+}
+
+export function listSitePlanDirs(): string[] {
+  return listSites().map((site) => join(site.dir, 'output', 'plans'));
+}
+
 export function registerSite(baseUrl: string): SiteRecord {
   const folder = siteFolderName(baseUrl);
   const dir = join(sitesDir(), folder);

package/src/state-manager.ts

@@ -3,6 +3,7 @@ import type { ExperienceTracker } from './experience-tracker.js';
 import type { Knowledge, KnowledgeTracker } from './knowledge-tracker.js';
 import { createDebug, tag } from './utils/logger.js';
 import { Overlay } from './utils/overlay.js';
+import type { Region } from './utils/region.js';
 import { slugify } from './utils/strings.js';
 import { extractStatePath } from './utils/url-matcher.js';
 
@@ -49,7 +50,7 @@ export interface WebPageState {
   focusedElement?: FocusedElement | null;
   links?: Link[];
   verifications?: Record<string, boolean>;
-  overlay?: Overlay;
+  overlay?: Region;
   /** Region name, the persisted scalar form of overlay.name used in experience frontmatter */
   region?: string;
   /** Region root selector, the persisted scalar form of overlay.root used in experience frontmatter */
@@ -124,7 +125,7 @@ export class StateManager {
   private emitStateChange(event: StateTransition): void {
     const state = event.toState;
     const payload: Record<string, unknown> = { url: state.fullUrl || state.url, path: state.url, title: state.title, h1: state.h1 };
-    if (state.overlay?.present) payload.region = state.overlay.name || state.overlay.type;
+    if (state.overlay?.isOpen) payload.region = state.overlay.name || state.overlay.type;
     tag('data').log('state', payload);
 
     this.stateChangeListeners.forEach((listener) => {
@@ -149,9 +150,9 @@ export class StateManager {
     if (newState.url) this.allVisitedUrls.add(normalizeUrl(newState.url));
 
     const hashChanged = actionResult.hash !== previousHash;
-    const regionAppeared = !hashChanged && this.hasRegionAppeared(previousState, newState);
+    const regionOpened = !hashChanged && this.regionOpened(previousState, newState);
 
-    if (hashChanged || regionAppeared) {
+    if (hashChanged || regionOpened) {
       const transition: StateTransition = {
         fromState: previousState,
         toState: newState,
@@ -162,7 +163,7 @@ export class StateManager {
       this.stateHistory.push(transition);
       this.emitStateChange(transition);
 
-      if (regionAppeared) {
+      if (regionOpened) {
         debugLog('State change detected: region of interest appeared');
       }
     }
@@ -212,10 +213,10 @@ export class StateManager {
     return newState;
   }
 
-  private hasRegionAppeared(previousState: WebPageState | null, newState: WebPageState): boolean {
-    const prevFocus = previousState?.overlay ?? Overlay.fromAria(previousState?.ariaSnapshot ?? null);
-    const newFocus = newState.overlay ?? Overlay.fromAria(newState.ariaSnapshot ?? null);
-    return !prevFocus.present && newFocus.present;
+  private regionOpened(previousState: WebPageState | null, newState: WebPageState): boolean {
+    const previous = Overlay.resolve(previousState ?? {});
+    const current = Overlay.resolve(newState);
+    return !previous.isOpen && current.isOpen;
   }
 
   /**