explorbot 0.4.1 → 0.4.3

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'];
@@ -12,6 +12,7 @@ export class RequestStore {
   private onFailedListeners: Array<(r: RequestResult) => void> = [];
   private outputDir: string;
   private sessionStartedAt = new Date();
+  private readEndpointKeys = new Set<string>();
 
   constructor(outputDir: string) {
     this.outputDir = outputDir;
@@ -22,6 +23,14 @@ export class RequestStore {
     result.save(this.outputDir);
   }
 
+  addReadRequest(result: RequestResult): void {
+    const key = readEndpointKey(result);
+    if (this.readEndpointKeys.has(key)) return;
+    this.readEndpointKeys.add(key);
+    this.capturedRequests.push(result);
+    result.save(this.outputDir);
+  }
+
   addFailedRequest(result: RequestResult): void {
     this.failedRequests.push(result);
     for (const cb of this.onFailedListeners) {
@@ -46,10 +55,6 @@ export class RequestStore {
     result.save(this.outputDir);
   }
 
-  addRequest(result: RequestResult): void {
-    this.addMadeRequest(result);
-  }
-
   getCapturedRequests(): RequestResult[] {
     return this.capturedRequests;
   }
@@ -58,36 +63,19 @@ 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);
+  toEndpointList(scopePath?: string, methods: EndpointFamily = 'write'): string {
+    let requests = this.capturedRequests.filter((r) => matchesFamily(r, methods));
+    if (scopePath) requests = this.getRequestsForScope(scopePath, methods);
 
     const seen = new Set<string>();
     const lines: string[] = [];
 
     for (const req of requests) {
-      const key = `${req.method} ${normalizePathPattern(req.path)}`;
+      const key = `${req.method} ${generalizeUrl(req.path, () => '{id}')}${queryParamHint(req)}`;
       if (seen.has(key)) continue;
       seen.add(key);
       lines.push(key);
@@ -113,14 +101,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;
 
@@ -151,6 +143,11 @@ export class RequestStore {
       try {
         const result = RequestResult.load(path.join(requestsDir, file));
         if (existingIds.has(result.id)) continue;
+        if (!result.isWrite) {
+          const key = readEndpointKey(result);
+          if (this.readEndpointKeys.has(key)) continue;
+          this.readEndpointKeys.add(key);
+        }
         this.capturedRequests.push(result);
       } catch {
         // skip invalid files
@@ -159,17 +156,31 @@ 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));
+    return this.getRequestsForScope(scopePath, 'write');
+  }
+
+  getReadRequestsForScope(scopePath: string): RequestResult[] {
+    return this.getRequestsForScope(scopePath, 'read');
+  }
+
+  clear(): void {
+    this.capturedRequests = [];
+    this.madeRequests = [];
+    this.failedRequests = [];
+    this.readEndpointKeys.clear();
+  }
+
+  private getRequestsForScope(scopePath: string, methods: EndpointFamily): RequestResult[] {
+    const candidates = this.capturedRequests.filter((r) => matchesFamily(r, methods));
     const scopeSegments = scopePath.split('/').filter(Boolean);
-    if (scopeSegments.length === 0) return writes;
+    if (scopeSegments.length === 0) return candidates;
 
     let scoped: RequestResult[] = [];
     let fewest = Number.POSITIVE_INFINITY;
     let ambiguous = false;
     for (const segment of scopeSegments) {
       if (isDynamicSegment(segment)) continue;
-      const matches = writes.filter((r) => r.path.split('/').includes(segment));
+      const matches = candidates.filter((r) => r.path.split('/').includes(segment));
       if (matches.length === 0 || matches.length > fewest) continue;
       if (matches.length === fewest) {
         if (!scoped.every((r, i) => r.id === matches[i].id)) ambiguous = true;
@@ -183,17 +194,32 @@ export class RequestStore {
 
     return scoped;
   }
+}
 
-  clear(): void {
-    this.capturedRequests = [];
-    this.madeRequests = [];
-    this.failedRequests = [];
-  }
+export function isFailedRequest(request: RequestResult): boolean {
+  return request.status >= 400 || Boolean(request.error);
+}
+
+function readEndpointKey(result: RequestResult): string {
+  return `${result.method} ${generalizeUrl(result.path, () => '{id}')}?${queryParamNames(result).join(',')}`;
 }
 
-function normalizePathPattern(urlPath: string): string {
-  return urlPath
-    .split('/')
-    .map((segment) => (segment && isDynamicSegment(segment) ? '{id}' : segment))
-    .join('/');
+function matchesFamily(result: RequestResult, methods: EndpointFamily): boolean {
+  if (methods === 'write') return result.isWrite;
+  return result.method === 'GET';
 }
+
+function queryParamHint(result: RequestResult): string {
+  if (result.isWrite) return '';
+  const names = queryParamNames(result);
+  if (names.length === 0) return '';
+  return ` ?${names.join(',')}`;
+}
+
+function queryParamNames(result: RequestResult): string[] {
+  const query = result.fullUrl.split('?')[1];
+  if (!query) return [];
+  return [...new Set(new URLSearchParams(query).keys())].sort();
+}
+
+export type EndpointFamily = 'read' | 'write';

package/src/api/xhr-capture.ts

@@ -60,26 +60,25 @@ export class XhrCapture {
       this.store.addFailedRequest(failure);
     }
 
-    if (!WRITE_METHODS.has(method)) return;
-
     const contentType = response.headers()['content-type'] || '';
     if (!JSON_CONTENT_TYPES.test(contentType)) return;
 
+    if (method === 'GET') {
+      if (status !== 200) return;
+      this.captureReadEndpoint(request, response);
+      return;
+    }
+
+    if (!WRITE_METHODS.has(method)) return;
+
     if (status === 304) return;
 
     const parsedUrl = new URL(url);
     const origin = parsedUrl.pathname + parsedUrl.search;
     const id = generateRequestId(method, parsedUrl.pathname, 'xhr_');
 
-    const requestHeaders: Record<string, string> = {};
-    for (const [k, v] of Object.entries(request.headers())) {
-      requestHeaders[k] = String(v);
-    }
-
-    const responseHeaders: Record<string, string> = {};
-    for (const [k, v] of Object.entries(response.headers())) {
-      responseHeaders[k] = String(v);
-    }
+    const requestHeaders = this.toHeaderMap(request.headers());
+    const responseHeaders = this.toHeaderMap(response.headers());
 
     let rawBody = '';
     try {
@@ -115,4 +114,33 @@ export class XhrCapture {
 
     this.store.addCapturedRequest(result);
   }
+
+  private captureReadEndpoint(request: any, response: any): void {
+    const parsedUrl = new URL(request.url());
+    const requestHeaders = this.toHeaderMap(request.headers());
+
+    const result = new RequestResult({
+      id: generateRequestId('GET', parsedUrl.pathname, 'xhr_'),
+      method: 'GET',
+      path: parsedUrl.pathname,
+      fullUrl: parsedUrl.pathname + parsedUrl.search,
+      requestHeaders,
+      status: response.status(),
+      statusText: response.statusText(),
+      responseHeaders: {},
+      timing: 0,
+      timestamp: new Date(),
+    });
+    result.rawResponseBodyValue = '';
+
+    this.store.addReadRequest(result);
+  }
+
+  private toHeaderMap(headers: Record<string, unknown>): Record<string, string> {
+    const map: Record<string, string> = {};
+    for (const [k, v] of Object.entries(headers)) {
+      map[k] = String(v);
+    }
+    return map;
+  }
 }

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/help-json-command.ts

@@ -0,0 +1,74 @@
+import type { Command } from 'commander';
+import { EXPLORBOT_ENV_VARS } from '../config.js';
+
+const DESCRIPTION = 'Print command definitions as JSON for agents and tools';
+
+export class HelpJsonCommand {
+  static register(program: Command): void {
+    program
+      .command('help-json [command...]')
+      .description(DESCRIPTION)
+      .action(async (names: string[]) => {
+        const target = HelpJsonCommand.find(program, names);
+        if (!target) {
+          console.error(`Unknown command: ${names.join(' ')}`);
+          process.exit(1);
+        }
+        const json = JSON.stringify(HelpJsonCommand.data(target, target === program), null, 2);
+        await new Promise<void>((resolve) => process.stdout.write(`${json}\n`, () => resolve()));
+      });
+  }
+
+  static data(cmd: Command, root = false): CommandDefinition {
+    const helper = cmd.createHelp();
+    const definition: CommandDefinition = {
+      name: cmd.name(),
+      description: cmd.description(),
+      aliases: cmd.aliases(),
+      arguments: cmd.registeredArguments.map((argument) => ({
+        name: argument.name(),
+        description: argument.description,
+        required: argument.required,
+        variadic: argument.variadic,
+      })),
+      options: helper.visibleOptions(cmd).map((option) => ({
+        flags: option.flags,
+        description: option.description,
+        default: option.defaultValue,
+        choices: option.argChoices,
+      })),
+      commands: helper.visibleCommands(cmd).map((sub) => HelpJsonCommand.data(sub)),
+    };
+
+    if (!root) return definition;
+
+    definition.version = cmd.version();
+    definition.env = EXPLORBOT_ENV_VARS.map((variable) => ({
+      name: variable.name,
+      description: variable.description,
+      required: !!variable.required,
+    }));
+    return definition;
+  }
+
+  private static find(cmd: Command, names: string[]): Command | undefined {
+    let target = cmd;
+    for (const name of names) {
+      const sub = target.commands.find((candidate) => candidate.name() === name || candidate.aliases().includes(name));
+      if (!sub) return undefined;
+      target = sub;
+    }
+    return target;
+  }
+}
+
+interface CommandDefinition {
+  name: string;
+  description: string;
+  aliases: string[];
+  version?: string;
+  arguments: { name: string; description: string; required: boolean; variadic: boolean }[];
+  options: { flags: string; description: string; default?: unknown; choices?: string[] }[];
+  commands: CommandDefinition[];
+  env?: { name: string; description: string; required: boolean }[];
+}

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);