explorbot 0.4.4 → 0.4.6

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/commands/base-command.d.ts

@@ -7,15 +7,15 @@ export interface Suggestion {
     command?: string;
     hint: string;
 }
-export declare abstract class BaseCommand {
+export declare abstract class BaseCommand<T = ExplorBot> {
     abstract name: string;
     abstract description: string;
     aliases: string[];
     options: CommandOption[];
     tuiEnabled: boolean;
     suggestions: Suggestion[];
-    explorBot: ExplorBot;
-    constructor(explorBot: ExplorBot);
+    explorBot: T;
+    constructor(explorBot: T);
     abstract execute(args: string): Promise<void>;
     matches(commandName: string): boolean;
     printSuggestions(): void;

package/dist/src/commands/init-command.d.ts

@@ -1,6 +1,9 @@
+import { type ModelRole } from '../config.js';
+export declare function envTemplate(provider: string): string;
 export declare function runInit(options: InitCommandOptions): Promise<void>;
 export declare function writeGlobalConfig(provider: string, apiKey?: string): void;
 export declare function runInitCommand(options: InitCommandOptions): void;
+export declare function modelLines(provider: string, only?: ModelRole[]): string;
 type InitCommandOptions = {
     configPath?: string;
     force?: boolean;

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

@@ -37,7 +37,7 @@ ${modelLines(provider)}
 ${moduleExport}
 `;
 }
-function envTemplate(provider) {
+export function envTemplate(provider) {
     const keyLines = Object.entries(PROVIDERS).map(([name, { envKey }]) => {
         if (name === provider)
             return `${envKey}=`;
@@ -219,14 +219,17 @@ async function renderLocalProviderWizard() {
         }), { exitOnCtrlC: false, patchConsole: false });
     });
 }
-function modelLines(provider) {
+export function modelLines(provider, only) {
     const recommended = ConfigParser.recommendedModels()[provider] || {};
     const roles = [
         ['model', 'fast model with tool calling capabilities'],
         ['visionModel', 'vision model for screenshot analysis'],
         ['agenticModel', 'agentic model for decision making'],
     ];
-    return roles.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
+    let selected = roles;
+    if (only)
+        selected = roles.filter(([role]) => only.includes(role));
+    return selected.map(([role, comment]) => `    // ${comment}\n    ${role}: '${provider}/${recommended[role] || '<model-id>'}',`).join('\n');
 }
 function globalConfigTemplate(provider) {
     const { envKey } = PROVIDERS[provider];

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/explorer.d.ts

@@ -39,7 +39,7 @@ declare class Explorer {
     testPageErrorHandler: ((error: Error) => void) | null;
     testConsoleHandler: ((message: any) => void) | null;
     testDialogHandler: ((dialog: any) => void) | null;
-    eventDispatcher: any;
+    eventDispatcher: NodeJS.EventEmitter<[never]>;
     constructor(config: ExplorbotConfig, options: ExplorerOptions | undefined, deps: ExplorerDeps);
     get actor(): CodeceptJS.I;
     get page(): Page | null;

package/dist/src/explorer.js

@@ -208,7 +208,7 @@ class Explorer {
         codeceptjs.container.create(this.convertToCodeceptConfig(this.config), {});
     }
     convertToCodeceptConfig(config) {
-        const playwrightConfig = { ...config.playwright };
+        const playwrightConfig = { visibleLocator: true, ...config.playwright };
         if (this.options?.show !== undefined) {
             playwrightConfig.show = this.options.show;
         }

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/html-diff.js

@@ -4,7 +4,7 @@ import { isDynamicId, isGenericClass } from "./xpath.js";
 const IGNORED_PATHS = new Set(['html[1]', 'html[1]/head[1]', 'html[1]/body[1]']);
 const SHELL_RATIO = 0.8;
 const ROOT_CONTENT_RATIO = 0.8;
-const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log']);
+const LIVE_REGION_ROLES = new Set(['alert', 'alertdialog', 'status', 'log', 'tooltip']);
 const TEXT_LINE_PREFIX = 'TEXT:';
 const MESSAGE_MAX_LENGTH = 200;
 const MESSAGE_LIMIT = 8;
@@ -447,6 +447,9 @@ function semanticSelectorFor(element, allElements) {
         const selector = buildContainerSelector(current, allElements);
         if (selector)
             return selector;
+        const classAttr = (current.attrs ?? []).find((a) => a.name === 'class')?.value;
+        if (classAttr && filterContainerClasses(classAttr.split(/\s+/).filter(Boolean)).length > 0)
+            return undefined;
         current = dominantChild(current);
     }
     return undefined;

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/api-testing/basics.md

@@ -66,7 +66,7 @@ npx explorbot api explore https://api.example.com/v1 \
   -H "Authorization: Bearer $TOKEN"
 ```
 
-`api explore` takes the base endpoint as its argument, so one line covers the whole run: it plans in every style, executes each plan, and reports the totals. The other commands take a path within the API and read the base from `--endpoint`:
+`api explore` takes an endpoint or a pattern as its argument, so one line covers the whole run: it plans, executes each plan, and reports the totals. Passing the base endpoint covers every collection the spec describes. The other commands take a path within the API and read the base from `--endpoint`:
 
 ```bash
 npx explorbot api plan /users \
@@ -81,7 +81,7 @@ The base endpoint keeps its path prefix: given `https://api.example.com/v1`, ste
 
 ### A dedicated API project
 
-If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.ts` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
+If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.js` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
 
 ## Your first run
 
@@ -99,6 +99,30 @@ npx explorbot api test output/plans/users.md
 
 Curler runs the scenarios and prints how many passed and failed.
 
+### Covering many endpoints
+
+`api explore` runs the whole loop for you: plan, test, re-plan. Given one endpoint it plans in every style.
+
+```bash
+npx explorbot api explore /users
+```
+
+The endpoint may be a pattern. `*` stands for one path segment, and a pattern also covers the paths below it, so `/users` and `/users/*` both cover `/users/{id}`. Quote it, or your shell will try to expand it first.
+
+```bash
+npx explorbot api explore '/projects/acme/*'
+```
+
+Explorbot explores collections, not raw paths: `/users/{id}` and `/users/{id}/posts` fold into `/users`, whose spec lookup brings them along anyway. When a pattern matches several collections the planning styles spread across them, one style per collection, so covering a whole API stays one plan per collection rather than one per style.
+
+Pass `/` to take every collection in the spec. The path parameters have to come from somewhere, so put them in the base endpoint.
+
+```bash
+npx explorbot api explore / --endpoint https://api.example.com/v2/acme
+```
+
+If a parameter is left with no value the run stops and names it, rather than sending requests to a literal `{project_id}`. Collections whose own parameters no pattern can fill, like `/analytics/stats/{kind}`, are listed and skipped.
+
 ## Output files
 
 | Output | Location | What it is |

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: { /* ... */ },
     },