explorbot 0.4.0 → 0.4.2

package/dist/src/ai/researcher/coordinates.js

@@ -62,6 +62,15 @@ export async function visuallyAnnotateContainers(page, containers) {
         return count;
     }, containers);
 }
+export async function removeVisualAnnotations(page) {
+    try {
+        await page.locator('[data-explorbot-annotation]').evaluateAll((elements) => {
+            for (const element of elements)
+                element.remove();
+        });
+    }
+    catch { }
+}
 export function WithCoordinates(Base) {
     return class extends Base {
         analyzeScreenshotForVisualProps() {
@@ -70,6 +79,9 @@ export function WithCoordinates(Base) {
         async visuallyAnnotateElements(opts) {
             return this.explorer.withPage((page) => visuallyAnnotateContainers(page, opts?.containers || []));
         }
+        async removeVisualAnnotations() {
+            await this.explorer.withPage((page) => removeVisualAnnotations(page));
+        }
         async _analyzeScreenshotForVisualProps() {
             const elements = new Map();
             const emptyResult = { elements, pagePurpose: null, primaryActions: null, focusedSection: null };
@@ -81,7 +93,7 @@ export function WithCoordinates(Base) {
             tag('step').log('Analyzing annotated screenshot for visual properties');
             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/dist/src/ai/researcher/deep-analysis.js

@@ -62,29 +62,29 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
-            const focusArea = current.overlay;
-            if (!focusArea.present || !focusArea.name)
+            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;
             }
             const alreadyExpanded = this._summarizeExpanded(parseResearchSections(cached)
                 .filter((s) => s.elements.length > 0)
                 .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;
             }
             const extQuery = mdq(cached).query('section1(~"Extended Research")');
@@ -97,7 +97,7 @@ export function WithDeepAnalysis(Base) {
                 updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
             }
             saveResearch({ hash: pageStateHash }, updated);
-            tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+            tag('substep').log(`Overlay research appended: ${region.name}`);
             return sectionMarkdown;
         }
         _loadPreviousExtendedSections(hash) {

package/dist/src/ai/researcher/fingerprint-worker.js

@@ -3,17 +3,7 @@ import { join } from 'node:path';
 import { parentPort } from 'node:worker_threads';
 import { computeHtmlFingerprint } from "../../utils/html-diff.js";
 import { isSamePageFamily } from "../../utils/url-matcher.js";
-function diceSimilarity(a, b) {
-    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.js";
 parentPort.on('message', (data) => {
     const { html, statesDir, maxAgeMs, threshold, url } = data;
     if (!existsSync(statesDir)) {

package/dist/src/ai/researcher.js

@@ -53,6 +53,8 @@ export class Researcher extends ResearcherBase {
         throw new Error('not implemented');
     }
     static getCachedResearch(state) {
+        if (state instanceof ActionResult)
+            return getCachedResearch(state.baseHash);
         return getCachedResearch(ActionResult.fromState(state).baseHash);
     }
     getSystemMessage() {
@@ -191,7 +193,7 @@ export class Researcher extends ResearcherBase {
                 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/dist/src/ai/rules.js

@@ -145,11 +145,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>
 `;
 export const dataProtectionRules = dedent `
@@ -164,7 +164,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>
@@ -318,6 +318,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/dist/src/ai/tester.js

@@ -486,14 +486,14 @@ export class Tester extends TaskAgent {
         const currentStateHash = currentState.hash;
         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) {
             const isTextInput = ['textbox', 'combobox', 'searchbox'].includes(focusedElement.role);
@@ -511,30 +511,30 @@ export class Tester extends TaskAgent {
         </no_focus>
       `;
         }
-        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>
       `;
         }
         if (currentState.isInsideIframe) {
@@ -594,7 +594,7 @@ export class Tester extends TaskAgent {
       `;
             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/dist/src/ai/tools.d.ts

@@ -12,7 +12,7 @@ interface AgentToolDeps extends ToolDeps {
     withExperience?: boolean;
 }
 export declare const ASSERTION_TOOLS: readonly ["verify"];
-export declare function createCodeceptJSTools({ explorer, stateManager, ai }: ToolDeps, task: Task): {
+export declare function createCodeceptJSTools({ explorer, stateManager }: ToolDeps, task: Task): {
     click: import("@ai-sdk/provider-utils").ExecutableTool<import("ai").Tool<{
         commands: any;
         explanation: any;

package/dist/src/ai/tools.js

@@ -16,7 +16,7 @@ import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
 const debugLog = createDebug('explorbot:tools');
 export const ASSERTION_TOOLS = ['verify'];
-export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
+export function createCodeceptJSTools({ explorer, stateManager }, task) {
     return {
         click: tool({
             description: dedent `
@@ -29,6 +29,12 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           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.
@@ -47,6 +53,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
           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'),
             }),
@@ -72,6 +79,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const attempts = [];
+                let ambiguityError = null;
                 for (let i = 0; i < commands.length; i++) {
                     const command = transformContainsCommand(commands[i]);
                     const success = await action.attempt(command, explanation);
@@ -79,34 +87,14 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     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);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
                 }
-                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);
                 const suggestion = clickFailureSuggestion(attempts);
@@ -114,7 +102,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     ...toolResult,
                     attempts,
                     suggestion,
-                }, action.lastError);
+                }, ambiguityError || action.lastError);
             },
         }),
         hover: tool({
@@ -344,13 +332,7 @@ export function createCodeceptJSTools({ explorer, stateManager, ai }, task) {
                     if (action.lastError) {
                         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', `Form execution FAILED! ${message}\n${formatExecutedSteps(action.executedSteps, codeLines.length)}`, {
                             ...toolResult,
                             code: codeBlock,
@@ -1123,13 +1105,11 @@ export async function failedToolResult(action, message, data, error) {
 }
 function getMultipleElementsSuggestion() {
     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.
   `;
 }
 export function withdrawVisionTools(tools) {
@@ -1194,42 +1174,6 @@ export async function formatMatchedElements(error) {
         return 'Could not fetch element details. Repeat the action to get better info.';
     return formatElementList(details);
 }
-async function disambiguateElements(error, explanation, provider) {
-    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',
-                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) {
     if (!errorMessage.includes('not found')) {
         return null;

package/dist/src/api/request-store.d.ts

@@ -12,14 +12,9 @@ export declare class RequestStore {
     getFailedRequests(): RequestResult[];
     onFailedRequest(cb: (r: RequestResult) => void): () => void;
     addMadeRequest(result: RequestResult): void;
-    addRequest(result: RequestResult): void;
     getCapturedRequests(): RequestResult[];
     getMadeRequests(): RequestResult[];
-    getRequests(): RequestResult[];
     getLastRequest(): RequestResult | undefined;
-    getRequestsByEndpoint(pathPrefix: string): RequestResult[];
-    getRequestsByMethod(method: string): RequestResult[];
-    getRequestsByStatus(status: number): RequestResult[];
     toEndpointList(scopePath?: string): string;
     extractAuthHeaders(): Record<string, string>;
     findCapturedRequest(method: string, searchPath: string): RequestResult | undefined;
@@ -28,3 +23,4 @@ export declare class RequestStore {
     getWriteRequestsForScope(scopePath: string): RequestResult[];
     clear(): void;
 }
+export declare function isFailedRequest(request: RequestResult): boolean;

package/dist/src/api/request-store.js

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import path from 'node:path';
-import { isDynamicSegment } from "../utils/url-matcher.js";
+import { generalizeUrl, isDynamicSegment } from "../utils/url-matcher.js";
 import { RequestResult } from "./request-result.js";
 const AUTH_HEADERS = ['authorization', 'x-api-key', 'x-csrf-token'];
 export class RequestStore {
@@ -38,31 +38,15 @@ export class RequestStore {
         this.madeRequests.push(result);
         result.save(this.outputDir);
     }
-    addRequest(result) {
-        this.addMadeRequest(result);
-    }
     getCapturedRequests() {
         return this.capturedRequests;
     }
     getMadeRequests() {
         return this.madeRequests;
     }
-    getRequests() {
-        return this.madeRequests;
-    }
     getLastRequest() {
         return this.madeRequests[this.madeRequests.length - 1];
     }
-    getRequestsByEndpoint(pathPrefix) {
-        return this.madeRequests.filter((r) => r.path.startsWith(pathPrefix));
-    }
-    getRequestsByMethod(method) {
-        const upper = method.toUpperCase();
-        return this.madeRequests.filter((r) => r.method === upper);
-    }
-    getRequestsByStatus(status) {
-        return this.madeRequests.filter((r) => r.status === status);
-    }
     toEndpointList(scopePath) {
         let requests = this.capturedRequests;
         if (scopePath)
@@ -70,7 +54,7 @@ export class RequestStore {
         const seen = new Set();
         const lines = [];
         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);
@@ -92,13 +76,17 @@ export class RequestStore {
     }
     findCapturedRequest(method, searchPath) {
         const upper = method.toUpperCase();
-        const search = normalizePathPattern(searchPath).split('/').filter(Boolean);
+        const search = generalizeUrl(searchPath, () => '{id}')
+            .split('/')
+            .filter(Boolean);
         let best;
         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]))
@@ -139,8 +127,7 @@ export class RequestStore {
         }
     }
     getWriteRequestsForScope(scopePath) {
-        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;
@@ -172,6 +159,9 @@ export class RequestStore {
         this.failedRequests = [];
     }
 }
+export function isFailedRequest(request) {
+    return request.status >= 400 || Boolean(request.error);
+}
 function normalizePathPattern(urlPath) {
     return urlPath
         .split('/')

package/dist/src/api/spec-reader.js

@@ -5,7 +5,7 @@ import { dereference } from '@scalar/openapi-parser';
 import { tag } from "../utils/logger.js";
 export function validateSpecs(specs) {
     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.');
     }
 }
 export async function loadSpec(specPaths, outputDir) {

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

@@ -5,6 +5,7 @@ import { ConfigParser, EXPLORBOT_ENV_VARS, configuredModels } from '../config.js
 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';
 export class ConfigCommand extends BaseCommand {
@@ -32,7 +33,7 @@ export class ConfigCommand extends BaseCommand {
         const dirs = {};
         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);
             }
         }
         const env = {};
@@ -68,15 +69,7 @@ export class ConfigCommand extends BaseCommand {
         if (options.json)
             return JSON.stringify(data, null, 2);
         const lines = [];
-        const section = (title, entries) => {
-            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, entries) => lines.push(...renderSection(title, entries));
         const general = [['config', data.config || 'EXPLORBOT_* environment variables']];
         if (data.url)
             general.push(['url', data.url]);

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

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

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

@@ -256,9 +256,15 @@ export class ExploreCommand extends BaseCommand {
             tag('info').log(`Exploring sub-page: ${pick.url} (${pick.reason})`);
             try {
                 await this.explorBot.visit(pick.url);
+                const errorPage = getStateErrorPageError(this.explorBot.stateManager().getCurrentState());
+                if (errorPage) {
+                    tag('warning').log(`Skipping sub-page: ${errorPage.message}`);
+                    this.failedSubPages.add(normalizeUrl(pick.url));
+                    continue;
+                }
                 await this.runAllStyles(pick.url, undefined, mainPlan, this.completedPlans, styles);
                 const subPlan = this.explorBot.getCurrentPlan();
-                if (subPlan && !this.completedPlans.includes(subPlan)) {
+                if (subPlan?.tests.length && !this.completedPlans.includes(subPlan)) {
                     this.completedPlans.push(subPlan);
                 }
                 knownUrls.add(normalizeUrl(pick.url));
@@ -297,6 +303,11 @@ export class ExploreCommand extends BaseCommand {
             if (this.dryRun)
                 opts.noSave = true;
             await this.planWithRetry(feature, opts, pageUrl);
+            const plan = this.explorBot.getCurrentPlan();
+            if (plan && plan.tests.length === 0) {
+                tag('warning').log('Nothing to test on this page, moving on');
+                return;
+            }
             await this.runPendingTests();
             this.rememberCurrentPlan();
             fresh = false;

package/dist/src/commands/index.js

@@ -26,6 +26,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';
@@ -66,6 +67,7 @@ const commandClasses = [
     RerunCommand,
     StatusCommand,
     ConfigCommand,
+    RecommendedModelsCommand,
     DebugCommand,
     ExitCommand,
 ];