explorbot 0.4.4 → 0.4.5

package/dist/src/ai/tools.js

@@ -11,6 +11,7 @@ import { cleanHtmlSnippet } from "../utils/html.js";
 import { createDebug, tag } from '../utils/logger.js';
 import { compactErrorMessage, normalizeInlineText, truncate } from "../utils/strings.js";
 import { pause } from '../utils/loop.js';
+import { ariaRefSelector, describeRef, refIsGone } from "../utils/aria-ref.js";
 import { WebElement } from "../utils/web-element.js";
 import { sectionContextRule } from "./rules.js";
 import { isInteractive } from "./task-agent.js";
@@ -52,7 +53,6 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
           2. I.click(ARIA, container) - e.g. I.click({"role":"button","text":"Save"}, ".modal")
           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'),
@@ -63,10 +63,18 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('click', 'No commands provided');
                 }
-                const invalidCommands = rawCommands.map((cmd) => cmd.trim()).filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
+                const trimmedCommands = rawCommands.map((cmd) => cmd.trim());
+                const coordinateCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.clickXY'));
+                if (coordinateCommands.length > 0) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('click', `Coordinate commands are not locators: ${coordinateCommands.join(', ')}. A coordinate click always runs, so it cannot tell you whether the element was there.`, {
+                        suggestion: 'Name the element instead. Use visualClick() when you can see the target but cannot address it, or form() for a deliberate coordinate click such as dismissing a layer.',
+                    });
+                }
+                const invalidCommands = trimmedCommands.filter((cmd) => cmd.startsWith('I.') && !cmd.startsWith('I.click'));
                 if (invalidCommands.length > 0) {
                     activeNote.commit(TestResult.FAILED);
-                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() or I.clickXY() commands.`, {
+                    return failedToolResult('click', `Invalid commands: ${invalidCommands.join(', ')}. Click tool only accepts I.click() commands.`, {
                         suggestion: 'Use form() tool for typing text or multiple actions, or exitIframe() to leave iframe context.',
                     });
                 }
@@ -91,6 +99,15 @@ export function createCodeceptJSTools({ explorer, stateManager }, task) {
                         ambiguityError = action.lastError;
                     if (success) {
                         const toolResult = await ActionResult.fromState(stateManager.getCurrentState()).toToolResult(previousState, command);
+                        if (!hasObservablePageChange(toolResult)) {
+                            activeNote.commit(TestResult.FAILED);
+                            return failedToolResult('click', 'Click executed, but no observable page change was captured.', {
+                                ...toolResult,
+                                attempts,
+                                code: command,
+                                suggestion: 'Treat the element as not clicked. It may be covered by another layer, disabled, or the locator may have matched a non-interactive ancestor. Re-locate via xpathCheck(), which reports whether the element is covered or offscreen, before retrying.',
+                            });
+                        }
                         await commitNote(activeNote, TestResult.PASSED, toolResult, action);
                         return successToolResult('click', { ...toolResult, attempts, code: command }, action);
                     }
@@ -385,10 +402,16 @@ export function createRefTools({ explorer, stateManager }, task) {
             }),
             execute: async ({ ref, element }) => {
                 const activeNote = task.startNote(`Click ${element}`);
+                if (await refIsGone(explorer, ref)) {
+                    activeNote.commit(TestResult.FAILED);
+                    return failedToolResult('clickRef', `Ref ${ref} names no element on the page any more.`, {
+                        suggestion: 'The page has been rebuilt since you were given that ref. Call context() and use the ref it gives, or fall back to click() with a locator.',
+                    });
+                }
                 const previousState = ActionResult.fromState(stateManager.getCurrentState());
                 const action = explorer.action();
                 const named = await describeRef(explorer, ref);
-                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(`aria-ref=${ref}`)}).click())`;
+                const run = `I.usePlaywrightTo(${JSON.stringify(`click ${element}`)}, async ({ page }) => page.locator(${JSON.stringify(ariaRefSelector(ref))}).click())`;
                 if (!(await action.attempt(run, `Click ${element}`))) {
                     activeNote.commit(TestResult.FAILED);
                     return failedToolResult('clickRef', `Ref ${ref} could not be clicked: ${errorText(action.lastError)}`, {
@@ -1015,17 +1038,6 @@ export async function commitNote(activeNote, result, toolResult, action) {
     }
     activeNote.commit(result);
 }
-async function describeRef(explorer, ref) {
-    return Promise.resolve(explorer?.withPage?.((page) => page.locator(`aria-ref=${ref}`).evaluate((el) => {
-        const tag = el.tagName.toLowerCase();
-        const roles = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
-        const role = el.getAttribute('role') || roles[tag] || tag;
-        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
-        if (!text)
-            return null;
-        return { role, text };
-    }))).catch(() => null);
-}
 async function hasFocusedElement(explorer) {
     return explorer.withPage((page) => page.evaluate(() => !!document.activeElement && document.activeElement !== document.body)).catch(() => true);
 }
@@ -1085,6 +1097,8 @@ function hasObservablePageChange(data) {
         return true;
     if (data.pageDiff.messages?.length)
         return true;
+    if (data.pageDiff.requests?.length)
+        return true;
     return Array.isArray(data.pageDiff.htmlParts) && data.pageDiff.htmlParts.length > 0;
 }
 export async function failedToolResult(action, message, data, error) {
@@ -1093,12 +1107,11 @@ export async function failedToolResult(action, message, data, error) {
         result.suggestion = data.suggestion ? `${data.suggestion} ${PAGE_DIFF_SUGGESTION}` : PAGE_DIFF_SUGGESTION;
     }
     const errorTexts = [message, ...(data?.attempts?.map((a) => a.error || '') || [])];
-    const hasMultipleElements = errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN));
-    const multipleElementsSuggestion = hasMultipleElements ? getMultipleElementsSuggestion() : null;
-    if (multipleElementsSuggestion) {
-        result.suggestion = multipleElementsSuggestion;
+    if (errorTexts.some((t) => t.toLowerCase().includes(MULTIPLE_ELEMENTS_PATTERN))) {
+        const matched = await extractWebElements(error);
+        result.suggestion = getMultipleElementsSuggestion(matched);
         result.multipleElementsDetected = true;
-        result.elements = await formatMatchedElements(error);
+        result.elements = formatElementList(matched);
         return result;
     }
     const notFoundSuggestion = getNotFoundSuggestion(message);
@@ -1108,11 +1121,16 @@ export async function failedToolResult(action, message, data, error) {
     }
     return result;
 }
-function getMultipleElementsSuggestion() {
+function getMultipleElementsSuggestion(matched) {
+    const visible = (matched || []).filter((element) => element.visible !== false);
+    let onlyVisible = '';
+    if (matched && visible.length === 1)
+        onlyVisible = `\nOnly element ${matched.indexOf(visible[0]) + 1} is on screen, so that is the one to act on.`;
     return dedent `
     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:
+    Read the numbered elements list and act on the one you meant by its number:
     reuse the same locator with step.opts({ elementIndex: N }) as the last argument.
+    A match reported as not visible can never be acted on — pick one that is.${onlyVisible}
     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.
   `;
@@ -1132,7 +1150,7 @@ export function clickFailureSuggestion(attempts) {
         return 'Element exists but another element covers it. Close the overlapping panel or dialog, then retry.';
     }
     if (errors.some((e) => e.includes('is not visible'))) {
-        return 'Element is in the DOM but not visible. Reveal it first — scroll to it, expand its section, or open the panel holding it.';
+        return 'Element is in the DOM but not visible. Reveal it — scroll to it, expand its section, open the panel holding it — or, when the page carries several copies of the same control, target the one that is on screen.';
     }
     if (errors.some((e) => e.includes('SyntaxError'))) {
         return 'The command string never parsed as JavaScript — quotes or brackets do not match. No element was looked up, so this tells you nothing about the page. Re-emit the same intent as valid CodeceptJS.';
@@ -1162,7 +1180,8 @@ async function extractWebElements(error) {
             const xpath = await elements[i].toAbsoluteXPath();
             const html = truncate(cleanHtmlSnippet(await elements[i].toOuterHTML()), MAX_DISAMBIGUATE_HTML);
             const text = truncate(normalizeInlineText((await elements[i].getText()) || ''), MAX_DISAMBIGUATE_TEXT);
-            result.push({ xpath, html, text });
+            const visible = await Promise.resolve(elements[i].isVisible?.()).catch(() => undefined);
+            result.push({ xpath, html, text, visible });
         }
         catch (e) {
             debugLog('Failed to get details for element %d: %s', i, e);
@@ -1170,14 +1189,21 @@ async function extractWebElements(error) {
     }
     return result.length > 0 ? result : null;
 }
-function formatElementList(details) {
-    return details.map((el, i) => `Element ${i + 1}:\nText: "${el.text}"\nXPath: ${el.xpath}\nHTML: ${el.html}`).join('\n\n');
+function formatElementList(matched) {
+    if (!matched)
+        return 'Could not fetch element details. Repeat the action to get better info.';
+    return matched
+        .map((el, i) => {
+        const lines = [`Element ${i + 1}:`, `Text: "${el.text}"`];
+        if (el.visible !== undefined)
+            lines.push(`Visible: ${el.visible}`);
+        lines.push(`XPath: ${el.xpath}`, `HTML: ${el.html}`);
+        return lines.join('\n');
+    })
+        .join('\n\n');
 }
 export async function formatMatchedElements(error) {
-    const details = await extractWebElements(error);
-    if (!details)
-        return 'Could not fetch element details. Repeat the action to get better info.';
-    return formatElementList(details);
+    return formatElementList(await extractWebElements(error));
 }
 function getNotFoundSuggestion(errorMessage) {
     if (!errorMessage.includes('not found')) {

package/dist/src/application-spec.d.ts

@@ -4,10 +4,13 @@ export declare class ApplicationSpec {
     readonly sourcePath: string;
     constructor(sourcePath: string);
     renderFor(state: ActionResult): string;
+    matchedUrls(state: ActionResult): string[];
     get pageCount(): number;
     load(): void;
     resolveSourcePath(sourcePath: string): string;
+    relevantPages(state: ActionResult): ApplicationSpecPage[];
 }
+export declare function resolveSpecBundlePath(sourcePath: string): string | null;
 interface ApplicationSpecPage {
     url: string;
     content: string;

package/dist/src/application-spec.js

@@ -13,7 +13,7 @@ export class ApplicationSpec {
         this.load();
     }
     renderFor(state) {
-        const relevant = this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
+        const relevant = this.relevantPages(state);
         if (relevant.length === 0)
             return '';
         tag('operation').log(`Found application specification for ${state.url}`);
@@ -25,6 +25,9 @@ export class ApplicationSpec {
       </application_spec>
     `;
     }
+    matchedUrls(state) {
+        return this.relevantPages(state).map((page) => page.url);
+    }
     get pageCount() {
         return this.pages.length;
     }
@@ -63,9 +66,22 @@ export class ApplicationSpec {
         }
     }
     resolveSourcePath(sourcePath) {
-        if (path.isAbsolute(sourcePath))
-            return path.resolve(sourcePath);
-        const configParser = ConfigParser.getInstance();
-        return path.resolve(configParser.resolveProjectDir(sourcePath));
+        return resolveSpecSource(sourcePath);
+    }
+    relevantPages(state) {
+        return this.pages.filter((page) => state.isMatchedBy({ url: page.url }));
     }
 }
+export function resolveSpecBundlePath(sourcePath) {
+    const resolved = resolveSpecSource(sourcePath);
+    if (!existsSync(resolved))
+        return null;
+    if (statSync(resolved).isDirectory())
+        return resolved;
+    return path.dirname(resolved);
+}
+function resolveSpecSource(sourcePath) {
+    if (path.isAbsolute(sourcePath))
+        return path.resolve(sourcePath);
+    return path.resolve(ConfigParser.getInstance().resolveProjectDir(sourcePath));
+}

package/dist/src/config.d.ts

@@ -105,6 +105,10 @@ interface RerunnerAgentConfig extends AgentConfig {
 interface PlannerAgentConfig extends AgentConfig {
     styles?: string[];
     stylesDir?: string;
+    docsWeight?: number;
+}
+interface ScoutAgentConfig extends AgentConfig {
+    dirs?: string[];
 }
 interface ScreencastConfig {
     size?: {
@@ -129,6 +133,7 @@ interface AgentsConfig {
     quartermaster?: AgentConfig;
     historian?: HistorianAgentConfig;
     fisherman?: AgentConfig;
+    scout?: ScoutAgentConfig;
     chief?: AgentConfig;
     curler?: AgentConfig;
     rerunner?: RerunnerAgentConfig;
@@ -221,7 +226,7 @@ interface ExplorbotConfig {
 type RuleEntry = string | Record<string, string>;
 export declare const EXPLORBOT_CONFIG_PATHS: string[];
 export declare const EXPLORBOT_ENV_VARS: EnvVar[];
-export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
+export type { ExplorbotConfig, PlaywrightConfig, AIConfig, HtmlConfig, ActionConfig, AgentConfig, AgentsConfig, HistorianAgentConfig, ResearcherAgentConfig, NavigatorAgentConfig, PlannerAgentConfig, ScoutAgentConfig, RerunnerAgentConfig, HealRecipe, Hook, HookConfig, HooksConfig, PlaywrightHook, CodeceptJSHook, HookPatternMap, RuleEntry, ReporterConfig, ApiConfig, WebConfig, ApiHookFn, };
 export declare class ConfigParser {
     static instance: ConfigParser;
     static recommended: Record<string, Record<string, string>> | null;

package/dist/src/explorbot.d.ts

@@ -12,6 +12,7 @@ import { AIProvider } from './ai/provider.js';
 import { Quartermaster } from './ai/quartermaster.js';
 import { Rerunner } from './ai/rerunner.js';
 import { Researcher } from './ai/researcher.js';
+import { Scout } from './ai/scout.js';
 import { SessionAnalyst } from './ai/session-analyst.js';
 import { Tester } from './ai/tester.js';
 import { RequestStore } from './api/request-store.js';
@@ -99,6 +100,8 @@ export declare class ExplorBot {
     agentDriller(): Driller;
     agentSessionAnalyst(): SessionAnalyst;
     agentFisherman(): Fisherman | null;
+    agentScout(): Scout | null;
+    scoutCorpusDirs(): string[];
     getCurrentPlan(): Plan | undefined;
     getSuite(): Suite | null;
     getPlanFeature(): string | undefined;

package/dist/src/explorbot.js

@@ -12,12 +12,15 @@ import { AIProvider } from "./ai/provider.js";
 import { Quartermaster } from "./ai/quartermaster.js";
 import { Rerunner } from "./ai/rerunner.js";
 import { Researcher } from "./ai/researcher.js";
+import { Scout } from "./ai/scout.js";
+import { loadScoutCorpus } from "./ai/scout/tools.js";
 import { SessionAnalyst } from "./ai/session-analyst.js";
 import { Tester } from "./ai/tester.js";
 import { createAgentTools } from "./ai/tools.js";
 import { ApiClient } from "./api/api-client.js";
 import { RequestStore } from "./api/request-store.js";
 import { loadSpec } from "./api/spec-reader.js";
+import { resolveSpecBundlePath } from "./application-spec.js";
 import { ConfigParser } from "./config.js";
 import { ExperienceTracker } from "./experience-tracker.js";
 import Explorer from "./explorer.js";
@@ -184,6 +187,9 @@ export class ExplorBot {
             const fisherman = this.agentFisherman();
             if (fisherman)
                 this.agents.planner.setFisherman(fisherman);
+            const scout = this.agentScout();
+            if (scout)
+                this.agents.planner.setScout(scout);
         }
         return this.agents.planner;
     }
@@ -310,6 +316,33 @@ export class ExplorBot {
         }
         return this.agents.fisherman;
     }
+    agentScout() {
+        const scoutConfig = this.config.ai?.agents?.scout;
+        if (scoutConfig?.enabled !== true)
+            return null;
+        const dirs = this.scoutCorpusDirs();
+        if (dirs.length === 0) {
+            tag('warning').log('Scout enabled but no documentation found — set --spec or ai.agents.scout.dirs');
+            return null;
+        }
+        return (this.agents.scout ||= this.createAgent(({ ai }) => new Scout(ai, loadScoutCorpus(dirs))));
+    }
+    scoutCorpusDirs() {
+        const dirs = [];
+        const specPath = this.options.applicationSpec || this.config.dirs?.spec;
+        if (specPath) {
+            const bundle = resolveSpecBundlePath(specPath);
+            const pagesDir = bundle && path.join(bundle, 'pages');
+            if (pagesDir && existsSync(pagesDir))
+                dirs.push(pagesDir);
+        }
+        for (const dir of this.config.ai?.agents?.scout?.dirs || []) {
+            const resolved = this.configParser.resolveProjectDir(dir);
+            if (existsSync(resolved))
+                dirs.push(resolved);
+        }
+        return [...new Set(dirs)];
+    }
     getCurrentPlan() {
         return this.currentPlan;
     }

package/dist/src/knowledge-tracker.d.ts

@@ -16,6 +16,7 @@ export declare class KnowledgeTracker {
     renderEndpointKnowledge(endpoint: string): string;
     renderRelevantContext(state: ActionResult): string;
     renderApplicationSpec(state: ActionResult): string;
+    applicationSpecUrls(state: ActionResult): string[];
     addKnowledge(urlPattern: string, description: string, opts?: {
         replace?: boolean;
     }): {

package/dist/src/knowledge-tracker.js

@@ -79,6 +79,9 @@ export class KnowledgeTracker {
     renderApplicationSpec(state) {
         return this.applicationSpec?.renderFor(state) || '';
     }
+    applicationSpecUrls(state) {
+        return this.applicationSpec?.matchedUrls(state) || [];
+    }
     addKnowledge(urlPattern, description, opts) {
         const configParser = ConfigParser.getInstance();
         const configPath = configParser.getConfigPath();

package/dist/src/utils/aria-ref.d.ts

@@ -0,0 +1,16 @@
+import { WebElement } from './web-element.js';
+export declare function ariaRefSelector(ref: string): string;
+export declare function isAriaRef(ref: string): boolean;
+export declare function ariaRefSnapshot(page: any): Promise<string>;
+export declare function parseAriaRefs(ariaSnapshot: string): AriaRefEntry[];
+export declare function elementFromAriaRef(page: any, ref: string): Promise<WebElement | null>;
+export declare function refIsGone(explorer: any, ref: string): Promise<boolean>;
+export declare function describeRef(explorer: any, ref: string): Promise<{
+    role: string;
+    text: string;
+} | null>;
+export interface AriaRefEntry {
+    role: string;
+    name: string;
+    ref: string;
+}

package/dist/src/utils/aria-ref.js

@@ -0,0 +1,47 @@
+import { WebElement } from "./web-element.js";
+const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
+const ARIA_REF_PATTERN = /^(f\d+)?e\d+$/i;
+const REF_ROLES = { a: 'link', button: 'button', select: 'combobox', textarea: 'textbox' };
+export function ariaRefSelector(ref) {
+    return `aria-ref=${ref}`;
+}
+export function isAriaRef(ref) {
+    return ARIA_REF_PATTERN.test(ref);
+}
+export function ariaRefSnapshot(page) {
+    return page.locator('body').ariaSnapshot({ mode: 'ai' });
+}
+export function parseAriaRefs(ariaSnapshot) {
+    const entries = [];
+    for (const line of ariaSnapshot.split('\n')) {
+        const match = line.match(REF_LINE_PATTERN);
+        if (!match)
+            continue;
+        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
+    }
+    return entries;
+}
+export async function elementFromAriaRef(page, ref) {
+    if (!isAriaRef(ref))
+        return null;
+    return WebElement.fromPlaywrightLocator(page.locator(ariaRefSelector(ref)));
+}
+export async function refIsGone(explorer, ref) {
+    const count = () => Promise.resolve(explorer?.withPage?.((page) => page.locator(ariaRefSelector(ref)).count())).catch(() => undefined);
+    if ((await count()) !== 0)
+        return false;
+    await Promise.resolve(explorer?.withPage?.(ariaRefSnapshot)).catch(() => null);
+    return (await count()) === 0;
+}
+export async function describeRef(explorer, ref) {
+    return Promise.resolve(explorer?.withPage?.((page) => page.locator(ariaRefSelector(ref)).evaluate((el, roles) => {
+        const tag = el.tagName.toLowerCase();
+        const role = el.getAttribute('role') || roles[tag];
+        if (!role)
+            return null;
+        const text = (el.getAttribute('aria-label') || el.innerText || el.value || '').trim().split('\n')[0];
+        if (!text)
+            return null;
+        return { role, text };
+    }, REF_ROLES))).catch(() => null);
+}

package/dist/src/utils/aria.js

@@ -434,9 +434,9 @@ const formatDiffSection = (label, items) => {
     const summary = countBy(items);
     if (summary.size === 0)
         return [`  ${label}: []`];
-    const sorted = Array.from(summary.entries()).sort(([aItem, aCount], [bItem, bCount]) => bCount - aCount || aItem.localeCompare(bItem));
-    const top = sorted.slice(0, TOP_DIFF_ITEMS);
-    const rest = sorted.slice(TOP_DIFF_ITEMS);
+    const ordered = Array.from(summary.entries());
+    const top = ordered.slice(0, TOP_DIFF_ITEMS);
+    const rest = ordered.slice(TOP_DIFF_ITEMS);
     const lines = [`  ${label}:`];
     for (const [item, count] of top) {
         let suffix = '';

package/dist/src/utils/web-annotate.js

@@ -1,24 +1,12 @@
+import { ariaRefSnapshot, parseAriaRefs } from "./aria-ref.js";
 import { ELEMENT_EXTRACTION_CONFIG, getElementDataExtractorSource } from "./html.js";
 import { createDebug } from './logger.js';
 import { WebElement } from "./web-element.js";
 const debugLog = createDebug('explorbot:web-annotate');
-const REF_LINE_PATTERN = /^(\s*)-\s+(\w+)\s*(?:"([^"]*)")?.*?\[ref=(e\d+)\]/;
 const ANNOTATABLE_ROLES = new Set(['button', 'link', 'textbox', 'searchbox', 'checkbox', 'radio', 'switch', 'combobox', 'tab', 'menuitem', 'menuitemcheckbox', 'menuitemradio', 'option', 'slider', 'spinbutton', 'treeitem']);
-function parseAriaRefs(ariaSnapshot) {
-    const entries = [];
-    for (const line of ariaSnapshot.split('\n')) {
-        const match = line.match(REF_LINE_PATTERN);
-        if (!match)
-            continue;
-        if (!ANNOTATABLE_ROLES.has(match[2]))
-            continue;
-        entries.push({ role: match[2], name: match[3] || '', ref: match[4] });
-    }
-    return entries;
-}
 export async function annotatePageElements(page) {
-    const ariaSnapshot = await page.locator('body').ariaSnapshot({ mode: 'ai' });
-    const refEntries = parseAriaRefs(ariaSnapshot);
+    const ariaSnapshot = await ariaRefSnapshot(page);
+    const refEntries = parseAriaRefs(ariaSnapshot).filter((entry) => ANNOTATABLE_ROLES.has(entry.role));
     const byRole = new Map();
     for (const { role, name, ref } of refEntries) {
         let list = byRole.get(role);

package/dist/src/utils/web-element.d.ts

@@ -36,8 +36,6 @@ export declare class WebElement {
     static fromXPathMatch(m: XPathMatch): WebElement;
     static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
     static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
-    static isAriaRef(ref: string): boolean;
-    static fromAriaRef(page: any, ref: string): Promise<WebElement | null>;
     static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
     static commonAncestor(page: any, eidxList: string[]): Promise<WebElement | null>;
     static findByXPath(html: string, xpath: string): Promise<{

package/dist/src/utils/web-element.js

@@ -111,14 +111,6 @@ export class WebElement {
     static async fromEidx(page, eidx) {
         return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
     }
-    static isAriaRef(ref) {
-        return /^(f\d+)?e\d+$/i.test(ref);
-    }
-    static async fromAriaRef(page, ref) {
-        if (!WebElement.isAriaRef(ref))
-            return null;
-        return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
-    }
     static async fromEidxList(page, eidxList) {
         const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
         if (validEidxList.length === 0)

package/docs/reference/configuration.md

@@ -179,6 +179,7 @@ Each agent takes its own model and system prompt.
 | `rerunner` | Heals failing steps when re-running generated tests |
 | `analyst` | Writes the end-of-session markdown report |
 | `fisherman` | Prepares test data through API requests |
+| `scout` | Retrieves relevant documentation for the Planner |
 | `chief` | API test planning |
 | `curler` | API test execution |
 
@@ -206,7 +207,7 @@ agents: {
 | `beforeHook` | `Hook \| HookPatternMap` | Code to run before agent execution |
 | `afterHook` | `Hook \| HookPatternMap` | Code to run after agent execution |
 
-Some agents take extra options: `pilot` accepts `stepsToReview` (recent steps reviewed per check, default 5); `planner` accepts `styles` (see [Planning styles](#planning-styles)); `rerunner` accepts `healLimit` (max heal attempts, default 3) and `recipes` (custom heal recipes, see [Rerunning Tests](../web-testing/rerun.md)). Researcher and Historian options are documented below.
+Some agents take extra options: `pilot` accepts `stepsToReview` (recent steps reviewed per check, default 5); `planner` accepts `styles` (see [Planning styles](#planning-styles)) and `docsWeight` (share of scenarios grounded in documentation when Scout is enabled, default 70); `scout` accepts `dirs` (see [Scout agent](#scout-agent)); `rerunner` accepts `healLimit` (max heal attempts, default 3) and `recipes` (custom heal recipes, see [Rerunning Tests](../web-testing/rerun.md)). Researcher and Historian options are documented below.
 
 See [Agent hooks](../web-testing/hooks.md) for hook configuration.
 
@@ -257,6 +258,31 @@ See [AI providers](../basics/providers.md) for recommended models and provider s
 
 Fisherman prepares test data over the API before a scenario runs, and can also answer questions about data that already exists without creating or changing anything. Pilot reaches this read-only capability through its `askApi(question)` tool, calling it to check whether suitable data is already there — or to get the exact name or id of an existing record — before deciding whether to create anything through `precondition()`. In replicate mode, where Fisherman learns the API by watching browser traffic instead of reading a spec, the read endpoints it can query come from successful GET requests observed in the browser, alongside the write endpoints already captured from XHR traffic. The endpoint list shown to the model names only the path and its query-parameter names, never their values; the underlying capture on disk holds the full request URL and headers — what write captures already hold — but no response body.
 
+### Scout agent
+
+Scout retrieves documentation relevant to the page being planned and hands it to the Planner as a `<docs_context>` block, so scenarios can be grounded in what the application documents say. It is opt-in and needs documentation collected beforehand:
+
+```javascript
+ai: {
+  agents: {
+    scout: {
+      enabled: true,          // Opt in — Scout never runs without this
+      dirs: ['docs'],         // Extra markdown directories to search, beyond the spec bundle
+    },
+    planner: {
+      docsWeight: 70,         // Roughly 70% of scenarios exercise documented behavior, the rest explore beyond it
+    },
+  },
+},
+```
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `enabled` | `boolean` | Turn Scout on. Default: off. |
+| `dirs` | `string[]` | Markdown directories added to the corpus, resolved relative to the project |
+
+The corpus combines the [application spec](../workflow/application-spec.md) bundle (`--spec` / `EXPLORBOT_SPEC` / `dirs.spec`, set by `explorbot docs collect`) with the `dirs` above. Scout scans it with the same `bash` + `readFile` tools Captain uses: the corpus is loaded into an in-memory sandbox and the model itself runs `rg` (or `grep` — whichever is installed) to explore it. One of the two must be on PATH — Scout fails loudly when neither is found. Pages already injected for the current URL as `<application_spec>` are excluded from the Scout corpus, so the two blocks never duplicate each other. Files under `dirs` that carry no page URL are listed as hand-written notes for Scout to inspect when they are relevant.
+
 ## Playwright settings
 
 ### Browser selection
@@ -512,6 +538,7 @@ export default {
       quartermaster: { /* ... */ },
       historian: { /* ... */ },
       fisherman: { /* ... */ },
+      scout: { enabled: true, dirs: ['docs'] }, // Documentation retrieval for the Planner
       rerunner: { /* ... */ },
       analyst: { /* ... */ },
     },

package/docs/web-testing/agents.md

@@ -44,7 +44,7 @@ See [Researcher Agent](./researcher.md) for configuration and usage.
 
 Generates test scenarios from research findings.
 
-The Planner writes business-focused scenarios with priority levels (critical/important/high/normal/low) and expected outcomes for verification. It balances positive and negative cases, skips scenarios you already have, and cycles through planning styles (normal, psycho, curious) to broaden coverage across iterations. You can add your own styles and page-specific rules.
+The Planner writes business-focused scenarios with priority levels (critical/important/high/normal/low) and expected outcomes for verification. It balances positive and negative cases, skips scenarios you already have, and cycles through planning styles (normal, psycho, curious) to broaden coverage across iterations. You can add your own styles and page-specific rules. With the Scout agent enabled, it also plans from collected documentation, weighted by `docsWeight`.
 
 Commands that use Planner:
 - `/plan [--focus <feature>]`
@@ -52,6 +52,14 @@ Commands that use Planner:
 
 See [Planner Agent](./planner.md) for planning styles, customization, and configuration.
 
+## Scout Agent
+
+Retrieves documentation relevant to the page being planned.
+
+Scout searches the collected documentation corpus — the [application spec](../workflow/application-spec.md) from `explorbot docs collect` plus any extra markdown directories you configure — and reports the documented capabilities, states and transitions that matter for the current page and focus. The Planner receives them as a `<docs_context>` block and grounds part of its scenarios in them. Pages already injected as `<application_spec>` for the current URL are not repeated. Scout is opt-in (`ai.agents.scout.enabled`) and searches with ripgrep or grep, falling back to an in-process scan when neither is installed.
+
+See [Configuration: Scout agent](../reference/configuration.md#scout-agent).
+
 ## Tester Agent
 
 Runs the planned scenarios.

package/docs/web-testing/planner.md

@@ -53,6 +53,11 @@ ai: {
 | `styles` | `string[]` | `['normal', 'curious', 'psycho']` | Style names and cycling order |
 | `rules` | `RuleEntry[]` | `[]` | URL-aware rule files from `rules/planner/` |
 | `systemPrompt` | `string` | - | Inline instructions appended to the prompt |
+| `docsWeight` | `number` | `70` | With Scout enabled, the rough share of scenarios exercising documented behavior; the rest explore beyond the documentation |
+
+## Planning from documentation
+
+With the [Scout agent](../reference/configuration.md#scout-agent) enabled, the Planner also receives a `<docs_context>` block — capabilities, states and transitions retrieved from collected documentation that are relevant to the current page and focus. `docsWeight` steers the mix: at `70` roughly seven of ten scenarios exercise documented behavior and three explore what the documentation does not cover. Set it to `100` for documentation-only planning, or lower it to lean on the Planner's own reading of the page. Pages whose documentation is already injected as `<application_spec>` are not repeated in `<docs_context>`.
 
 ## Planning Styles
 

package/docs/workflow/application-spec.md

@@ -75,3 +75,7 @@ Screenshots and other relative links may be included for readers, but Explorbot
 ## Validation
 
 Explorbot rejects a bundle when `index.md` or `pages/` is missing, when it contains no page files, or when a page has an unsupported format, version, or missing URL.
+
+## Scout
+
+Beyond the per-URL injection, the same bundle feeds the [Scout agent](../reference/configuration.md#scout-agent): when Scout is enabled, it searches `pages/` (and any extra `ai.agents.scout.dirs`) for documentation relevant to the page being planned and reports it to the Planner. Pages already injected for the current URL are excluded from scouting, so the two channels never duplicate each other.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",