explorbot 0.4.0 → 0.4.2

package/src/ai/provider.ts

@@ -11,6 +11,7 @@ import { type AIConfig, configuredModels, modelName as getModelName } from '../c
 import { executionController } from '../execution-controller.ts';
 import { Observability } from '../observability.ts';
 import { Stats } from '../stats.ts';
+import { getCliName } from '../utils/cli-name.js';
 import { createDebug, tag } from '../utils/logger.js';
 import { type RetryOptions, withRetry } from '../utils/retry.js';
 import { RulesLoader } from '../utils/rules-loader.ts';
@@ -51,12 +52,7 @@ export async function flushTelemetry(): Promise<void> {
 const CONTEXT_LENGTH_PATTERNS = ['reduce the length', 'context length', 'maximum context', 'token limit', 'too many tokens', 'max_tokens', 'context_length_exceeded', 'output truncated at maxtokens'];
 
 function extractCachedTokens(usage: any): number {
-  if (!usage) return 0;
-  const direct = usage.inputTokenDetails?.cacheReadTokens ?? usage.cachedInputTokens;
-  if (typeof direct === 'number') return direct;
-  const raw = usage.raw;
-  const fromRaw = raw?.prompt_tokens_details?.cached_tokens ?? raw?.promptTokensDetails?.cachedTokens;
-  return typeof fromRaw === 'number' ? fromRaw : 0;
+  return usage?.inputTokenDetails?.cacheReadTokens ?? 0;
 }
 
 function abortAfterIdle(ms: number, cancel: { cancelled: boolean }, controller: AbortController): Promise<never> {
@@ -110,7 +106,7 @@ export class Provider {
 
   constructor(config: AIConfig) {
     if (!config?.model) {
-      throw new AiError('AI model is not configured. Set ai.model in your config file.');
+      throw new AiError(`AI model is not configured. Set ai.model in your config file, or pick one with ${getCliName()} recommended-models`);
     }
     this.config = config;
     this.initLangfuse();
@@ -243,8 +239,8 @@ export class Provider {
   private recordUsage(agentName: string, modelName: string, usage: any): void {
     if (!usage) return;
     Stats.recordTokens(agentName, modelName, {
-      input: usage.inputTokens ?? usage.promptTokens ?? 0,
-      output: usage.outputTokens ?? usage.completionTokens ?? 0,
+      input: usage.inputTokens ?? 0,
+      output: usage.outputTokens ?? 0,
       total: usage.totalTokens ?? 0,
       cached: extractCachedTokens(usage),
     });
@@ -428,7 +424,7 @@ export class Provider {
     let invalidRequestFeedbackAdded = false;
     const executedStepMessages: ModelMessage[] = [];
     try {
-      const response = await this.withModelRequestSlot(() =>
+      let response = await this.withModelRequestSlot(() =>
         withRetry(async () => {
           const stepMessages: ModelMessage[] = [];
           const onStepEnd = (step: any) => {
@@ -458,7 +454,7 @@ export class Provider {
 
       clearActivity();
 
-      withExecutedSteps(response, executedStepMessages);
+      response = withExecutedSteps(response, executedStepMessages);
 
       // Log tool usage summary
       if (response.toolCalls && response.toolCalls.length > 0) {
@@ -651,7 +647,7 @@ export class Provider {
 
   async processImage(prompt: string, image: string): Promise<any> {
     if (!this.config.visionModel) {
-      throw new Error('Vision model not configured. Please set ai.visionModel in your config.');
+      throw new Error(`Vision model not configured. Set ai.visionModel in your config; ${getCliName()} recommended-models lists the providers that serve one`);
     }
 
     setActivity(`🤖 Processing image with ${this.config.visionModel}`, 'ai');

package/src/ai/researcher/coordinates.ts

@@ -71,6 +71,14 @@ export async function visuallyAnnotateContainers(page: Page, containers: Array<{
   }, containers);
 }
 
+export async function removeVisualAnnotations(page: Page): Promise<void> {
+  try {
+    await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+      for (const element of elements) element.remove();
+    });
+  } catch {}
+}
+
 export function WithCoordinates<T extends Constructor>(Base: T) {
   return class extends Base {
     declare explorer: Explorer;
@@ -85,6 +93,10 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
       return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
     }
 
+    async removeVisualAnnotations(): Promise<void> {
+      await this.explorer.withPage((page) => removeVisualAnnotations(page));
+    }
+
     private async _analyzeScreenshotForVisualProps(): Promise<VisualAnalysisResult> {
       const elements = new Map<string, { coordinates: string | null; color: string | null; icon: string | null }>();
       const emptyResult: VisualAnalysisResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
@@ -96,7 +108,7 @@ export function WithCoordinates<T extends Constructor>(Base: T) {
 
       const prompt = dedent`
         This screenshot has two types of annotations:
-        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-left maps dashed line colors to section names. Ignore containers for this task.
+        - **Section containers**: dashed bordered boxes (no labels on them). A legend at the bottom-right maps dashed line colors to section names. Ignore containers for this task.
         - **Interactive elements**: solid bordered boxes with eidx numbers in the top-right corner above the box. Adjacent elements use different colors.
 
         For each interactive element (solid border, eidx number), report:

package/src/ai/researcher/deep-analysis.ts

@@ -88,22 +88,22 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     }
 
     async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
-      const focusArea = current.overlay;
-      if (!focusArea.present || !focusArea.name) return null;
+      const region = current.overlay;
+      if (!region.isOpen || !region.name) return null;
 
       const cached = getCachedResearch(pageStateHash);
       if (!cached) return null;
 
-      const escaped = focusArea.name.replace(/"/g, '\\"');
+      const escaped = region.name.replace(/"/g, '\\"');
       if (mdq(cached).query(`section3(~"${escaped}")`).count() > 0) {
-        debugLog(`Overlay "${focusArea.name}" already in cached research, skipping`);
+        debugLog(`Overlay "${region.name}" already in cached research, skipping`);
         return null;
       }
 
       const diff = await current.diff(previous);
 
       if (!diff.ariaChanged && diff.htmlParts.length === 0) {
-        debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
+        debugLog(`No diff between current and previous state for overlay "${region.name}"`);
         return null;
       }
 
@@ -113,10 +113,10 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
           .map((s) => s.rawMarkdown)
       );
 
-      tag('substep').log(`Researching overlay: ${focusArea.name}`);
-      const sectionMarkdown = await this._analyzeExpandedAction('', focusArea.name, diff, alreadyExpanded);
+      tag('substep').log(`Researching overlay: ${region.name}`);
+      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
       if (!sectionMarkdown) {
-        debugLog(`Overlay "${focusArea.name}" produced no meaningful expansion`);
+        debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
         return null;
       }
 
@@ -130,7 +130,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
 
       saveResearch({ hash: pageStateHash }, updated);
-      tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+      tag('substep').log(`Overlay research appended: ${region.name}`);
       return sectionMarkdown;
     }
 

package/src/ai/researcher/fingerprint-worker.ts

@@ -3,16 +3,7 @@ import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from '../../utils/html-diff.ts';
 import { isSamePageFamily } from '../../utils/url-matcher.ts';
-
-function diceSimilarity(a: Set<string>, b: Set<string>): number {
-  let intersection = 0;
-  for (const item of a) {
-    if (b.has(item)) intersection++;
-  }
-  const total = a.size + b.size;
-  if (total === 0) return 100;
-  return Math.round(((2 * intersection) / total) * 100);
-}
+import { diceSimilarity } from '../../utils/similarity.ts';
 
 parentPort!.on('message', (data: FingerprintRequest) => {
   const { html, statesDir, maxAgeMs, threshold, url } = data;

package/src/ai/researcher.ts

@@ -76,6 +76,7 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   static getCachedResearch(state: WebPageState): string {
+    if (state instanceof ActionResult) return getCachedResearch(state.baseHash);
     return getCachedResearch(ActionResult.fromState(state).baseHash);
   }
 
@@ -235,7 +236,7 @@ export class Researcher extends ResearcherBase implements Agent {
         const containers = validContainers.filter((c) => !freshBroken.includes(c.css));
         await this.visuallyAnnotateElements({ containers });
         this.actionResult = await this.explorer.capture({ screenshot: true });
-        const visualResult = await this.analyzeScreenshotForVisualProps();
+        const visualResult = await this.analyzeScreenshotForVisualProps().finally(() => this.removeVisualAnnotations());
         if (visualResult.elements.size > 0) {
           await this.mergeVisualData(result, visualResult.elements);
           result.parseLocators();

package/src/ai/rules.ts

@@ -154,11 +154,11 @@ export const protectionRule = dedent`
 
   Pre-existing data on the page belongs to the application, not the test.
   Items that were not created inside the current test scenario must not be deleted, removed, emptied, reset, archived, or otherwise destroyed.
-  If a scenario needs to verify destructive behaviour, the same scenario must first create a disposable target and then destroy that specific target — never operate on data that was already there when the test started.
+  If a scenario needs to verify destructive behaviour, the same scenario must first create its own target and then destroy that specific target — never operate on data that was already there when the test started.
 
   The resource that the current page URL represents is "under test".
   The test must not destroy the resource it is running against — doing so invalidates every subsequent scenario that starts on the same URL.
-  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on disposable children created within the scenario itself.
+  Do not propose or perform delete/remove/archive actions on the entity that owns the current URL; propose such actions only on children created within the scenario itself.
   </important>
 `;
 
@@ -174,7 +174,7 @@ export const dataProtectionRules = dedent`
   filter, tab, or list-inspection constraint. Use visible existing data when it is available.
   If no suitable data exists, report the missing precondition instead of creating data.
 
-  Destructive actions are allowed only against disposable data created by the current scenario
+  Destructive actions are allowed only against data created by the current scenario
   or prepared for that scenario by Fisherman/API preconditions. Existing application data must
   remain unchanged.
   </data_protection_rules>
@@ -335,6 +335,14 @@ export const actionRule = dedent`
   If locator doesn't work, try CSS or XPath locators.
   If nothing works, use I.clickXY(x, y) as last resort.
 
+  When a click result reports several matches, pick one from its numbered list by position rather than guessing a new locator.
+  Reuse the same locator with step.opts({ elementIndex: N }) as the LAST argument. N is the "Element N" number.
+
+  <example>
+    I.click('Remove', step.opts({ elementIndex: 2 }));
+    I.click({ role: 'link', text: 'Details' }, '.panel', step.opts({ elementIndex: 1 }));
+  </example>
+
   For checkboxes, prefer I.checkOption/I.uncheckOption over I.click.
 
 

package/src/ai/tester.ts

@@ -548,17 +548,17 @@ export class Tester extends TaskAgent implements Agent {
     const isNewUrl = this.previousUrl !== currentUrl;
     const isNewState = !isNewUrl && this.previousStateHash !== null && this.previousStateHash !== currentStateHash;
 
-    if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.present) {
+    if (this.previousRegionPresent !== null && this.previousRegionPresent !== currentState.overlay.isOpen) {
       this.regionTransitioned = true;
     }
-    this.previousRegionPresent = currentState.overlay.present;
+    this.previousRegionPresent = currentState.overlay.isOpen;
 
     this.previousUrl = currentUrl;
     this.previousStateHash = currentStateHash;
 
     let context = '';
 
-    const focusArea = currentState.overlay;
+    const region = currentState.overlay;
 
     const focusedElement = currentState.focusedElement;
     if (focusedElement) {
@@ -577,29 +577,29 @@ export class Tester extends TaskAgent implements Agent {
       `;
     }
 
-    if (focusArea.detected) {
-      const areaName = focusArea.name ? ` "${focusArea.name}"` : '';
+    if (region.isModal) {
+      const areaName = region.name ? ` "${region.name}"` : '';
       let rootHint = '';
-      if (focusArea.root) rootHint = `\nIts content lives inside \`${focusArea.root}\` — scope locators to it.`;
+      if (region.root) rootHint = `\nIts content lives inside \`${region.root}\` — scope locators to it.`;
       context += dedent`
-        <focus_scope>
-        A ${focusArea.type}${areaName} is currently open above the page.${rootHint}
-        Scope all interactions to elements inside this ${focusArea.type}.
-        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the ${focusArea.type}.
-        Use <page_aria> to confirm the element you target is actually inside the ${focusArea.type}.
-        </focus_scope>
+        <overlay>
+        An overlay${areaName} is currently open above the page.${rootHint}
+        Scope all interactions to elements inside this overlay.
+        Page navigation, filters, and tabs that exist outside it are not actionable while it is open and may share names or roles with elements inside it — prefer the locator inside the overlay.
+        Use <page_aria> to confirm the element you target is actually inside the overlay.
+        </overlay>
       `;
     }
 
-    if (!focusArea.detected && focusArea.present && isNewState) {
+    if (!region.isModal && region.isOpen && isNewState) {
       let rootHint = '';
-      if (focusArea.root) rootHint = `\nIt lives inside \`${focusArea.root}\`.`;
+      if (region.root) rootHint = `\nIt lives inside \`${region.root}\`.`;
       context += dedent`
-        <area_of_interest>
-        A large new area "${focusArea.name || 'unnamed area'}" appeared on this page without navigation.${rootHint}
+        <region>
+        A large new region "${region.name || 'unnamed region'}" appeared on this page without navigation.${rootHint}
         The scenario most likely continues inside this area — prefer its elements for your next actions.
         The rest of the page (navigation, menus, filters) is still interactive and remains available.
-        </area_of_interest>
+        </region>
       `;
     }
 
@@ -663,7 +663,7 @@ export class Tester extends TaskAgent implements Agent {
       return context;
     }
 
-    if (focusArea.present && focusArea.name && this.pageStateHash && this.pageActionResult) {
+    if (region.isOpen && region.name && this.pageStateHash && this.pageActionResult) {
       const overlaySection = await this.researcher.researchOverlay(currentState, this.pageActionResult, this.pageStateHash).catch(this.skipResearch);
       if (overlaySection) {
         context += dedent`

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/api/spec-reader.ts

@@ -6,7 +6,7 @@ import { tag } from '../utils/logger.ts';
 
 export function validateSpecs(specs?: string[]): void {
   if (!specs?.length) {
-    throw new Error('API spec is required. Set api.spec in your config file.');
+    throw new Error('API spec is required. Pass --spec, set EXPLORBOT_API_SPEC, or set api.spec in your config file.');
   }
 }
 

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';
 
@@ -37,7 +38,7 @@ export class ConfigCommand extends BaseCommand {
     const dirs: Record<string, string> = {};
     if (options.root) {
       for (const [name, dir] of Object.entries({ output: 'output', ...config.dirs })) {
-        dirs[name] = path.join(options.root, dir);
+        dirs[name] = path.resolve(options.root, dir);
       }
     }
 
@@ -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/drill-command.ts

@@ -26,7 +26,7 @@ export class DrillCommand extends BaseCommand {
   }
 
   private parseKnowledgeArg(args: string): string | undefined {
-    const match = args.match(/--knowledge\s+(\S+)/);
+    const match = args.match(/--save-knowledge\s+(\S+)/);
     return match ? match[1] : undefined;
   }