explorbot 0.4.4 → 0.4.6

package/dist/boat/api-tester/src/commands/init-command.js

@@ -0,0 +1,88 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { envTemplate, modelLines } from "../../../../src/commands/init-command.js";
+import { missingModelRoles } from "../../../../src/config.js";
+import { log, tag } from "../../../../src/utils/logger.js";
+export async function runInit(options) {
+    const provider = options.provider || 'openrouter';
+    const originalCwd = process.cwd();
+    if (options.path) {
+        const dir = path.resolve(options.path);
+        mkdirSync(dir, { recursive: true });
+        process.chdir(dir);
+        log(`Working in directory: ${dir}`);
+    }
+    const configPath = path.resolve('apibot.config.js');
+    if (existsSync(configPath) && !options.force) {
+        log(`Config file already exists: ${configPath}`);
+        log('Use --force to overwrite existing file');
+        process.exit(1);
+    }
+    const answers = await ask(options);
+    if (!answers.baseEndpoint) {
+        tag('error').log('Base endpoint is required.');
+        process.exit(1);
+    }
+    if (!answers.spec) {
+        tag('error').log('OpenAPI spec is required. Chief plans from it and Curler looks up schemas in it.');
+        process.exit(1);
+    }
+    writeFileSync(configPath, configTemplate(provider, answers.baseEndpoint, answers.spec), 'utf8');
+    log(`Created config file: ${configPath}`);
+    const envPath = path.resolve('.env');
+    if (!existsSync(envPath)) {
+        writeFileSync(envPath, `${envTemplate(provider)}\n`, 'utf8');
+        log(`Created env file: ${envPath}`);
+    }
+    mkdirSync('output', { recursive: true });
+    mkdirSync('knowledge', { recursive: true });
+    if (answers.knowledge) {
+        const knowledgePath = path.resolve('knowledge', 'general.md');
+        writeFileSync(knowledgePath, `---\nendpoint: "*"\n---\n${answers.knowledge}\n`, 'utf8');
+        log(`Created knowledge file: ${knowledgePath}`);
+    }
+    const missing = missingModelRoles(provider);
+    if (missing.length) {
+        tag('warning').log(`No recommended ${missing.join(' and ')} for ${provider} — set the model ids in ${configPath}`);
+    }
+    log('');
+    log('Next steps:');
+    log('1. Add your provider API key to .env');
+    log('2. Describe the API so the plans match it');
+    tag('substep').log(chalk.yellow(`${options.prefix} know /users "CRUD endpoint for user management"`));
+    log('3. Plan and run tests for one endpoint');
+    tag('substep').log(chalk.yellow(`${options.prefix} explore /users`));
+    if (process.cwd() !== originalCwd)
+        process.chdir(originalCwd);
+}
+function configTemplate(provider, baseEndpoint, spec) {
+    return `// Models are written as 'provider/model-id' so they resolve without a local node_modules.
+// https://github.com/testomatio/explorbot/blob/main/docs/basics/providers.md
+
+export default {
+  ai: {
+${modelLines(provider, ['model', 'agenticModel'])}
+  },
+
+  api: {
+    baseEndpoint: '${baseEndpoint}',
+    spec: ['${spec}'],
+  },
+};
+`;
+}
+async function ask(options) {
+    if (options.baseEndpoint) {
+        return { baseEndpoint: options.baseEndpoint, spec: options.spec || '', knowledge: '' };
+    }
+    const rl = await import('node:readline');
+    const iface = rl.createInterface({ input: process.stdin, output: process.stdout });
+    const question = (text) => new Promise((resolve) => iface.question(text, (answer) => resolve(answer.trim())));
+    log('Apibot — API Testing Tool Setup\n');
+    const baseEndpoint = await question('Base API endpoint (e.g. https://api.example.com/v1): ');
+    const spec = await question('OpenAPI spec file or URL: ');
+    const knowledge = await question('Describe your API, its auth and its rules (Enter to skip): ');
+    iface.close();
+    return { baseEndpoint, spec, knowledge };
+}

package/dist/boat/api-tester/src/commands/know-command.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { tag } from "../../../../src/utils/logger.js";
+import { ApiCommand } from "./api-command.js";
+export class KnowCommand extends ApiCommand {
+    name = 'know';
+    aliases = ['add-knowledge'];
+    description = 'Add API knowledge for an endpoint';
+    knowledge = '';
+    async execute(endpoint) {
+        if (!this.knowledge) {
+            throw new Error('Description is required.');
+        }
+        const knowledgeDir = await this.resolveKnowledgeDir();
+        fs.mkdirSync(knowledgeDir, { recursive: true });
+        const filename = endpoint.replace(/^\//, '').replace(/[^a-zA-Z0-9]/g, '_') || 'general';
+        const filePath = path.join(knowledgeDir, `${filename}.md`);
+        if (fs.existsSync(filePath)) {
+            fs.appendFileSync(filePath, `\n---\n${this.knowledge}\n`, 'utf8');
+            tag('success').log(`Updated: ${filePath}`);
+            return;
+        }
+        fs.writeFileSync(filePath, `---\nendpoint: "${endpoint}"\n---\n${this.knowledge}\n`, 'utf8');
+        tag('success').log(`Created: ${filePath}`);
+    }
+    async resolveKnowledgeDir() {
+        const parser = this.bot.getConfigParser();
+        const options = this.bot.getOptions();
+        try {
+            await parser.loadConfig(options);
+            return parser.getKnowledgeDir();
+        }
+        catch {
+            if (options.path)
+                return path.join(path.resolve(options.path), 'knowledge');
+            return 'knowledge';
+        }
+    }
+}

package/dist/boat/api-tester/src/commands/plan-command.js

@@ -0,0 +1,37 @@
+import { tag } from "../../../../src/utils/logger.js";
+import { printNextSteps, relativeToCwd } from "../../../../src/utils/next-steps.js";
+import { ApiCommand } from "./api-command.js";
+export class PlanCommand extends ApiCommand {
+    name = 'plan';
+    description = 'Generate a test plan for an API endpoint';
+    style;
+    fresh = false;
+    async execute(endpoint) {
+        await this.bot.plan(endpoint, { style: this.style, fresh: this.fresh });
+        const plan = this.bot.getCurrentPlan();
+        if (!plan?.tests.length) {
+            throw new Error('No test scenarios generated.');
+        }
+        const lines = [`Plan: ${plan.title} (${plan.tests.length} tests)`];
+        for (const [i, test] of plan.tests.entries()) {
+            lines.push(`  ${String(i + 1).padStart(2)}. [${test.priority}] ${test.scenario}`);
+        }
+        tag('multiline').log(lines.join('\n'), { maxLines: 24 });
+        const savedPath = this.bot.savePlan();
+        if (!savedPath)
+            return;
+        const relative = relativeToCwd(savedPath);
+        const sections = [
+            {
+                label: 'Plan',
+                path: savedPath,
+                commands: [
+                    { label: 'Run first', command: `${this.prefix} test ${relative} 1` },
+                    { label: 'Run all', command: `${this.prefix} test ${relative} *` },
+                    { label: 'Run range', command: `${this.prefix} test ${relative} 1-3` },
+                ],
+            },
+        ];
+        printNextSteps(sections);
+    }
+}

package/dist/boat/api-tester/src/commands/test-command.js

@@ -0,0 +1,45 @@
+import figureSet from 'figures';
+import { tag } from "../../../../src/utils/logger.js";
+import { ApiCommand } from "./api-command.js";
+export class TestCommand extends ApiCommand {
+    name = 'test';
+    description = 'Execute tests from a plan file. Index: 1, 1-3, *';
+    index;
+    failed = 0;
+    async execute(planfile) {
+        const plan = this.bot.loadPlan(planfile);
+        tag('info').log(`Plan loaded: "${plan.title}" (${plan.tests.length} tests)`);
+        const tests = selectTests(plan.tests, this.index);
+        tag('info').log(`Running ${tests.length} test(s)`);
+        let passed = 0;
+        for (const test of tests) {
+            const result = await this.bot.runTest(test);
+            if (result.success)
+                passed++;
+            else
+                this.failed++;
+        }
+        this.bot.savePlan();
+        tag('info').log(`${figureSet.tick} ${tests.length} tests completed: ${passed} passed, ${this.failed} failed`);
+    }
+}
+export function selectTests(tests, index) {
+    if (!index || index === '*' || index === 'all') {
+        return tests.filter((t) => t.status === 'pending');
+    }
+    const rangeMatch = index.match(/^(\d+)-(\d+)$/);
+    if (rangeMatch) {
+        const start = Number.parseInt(rangeMatch[1]) - 1;
+        const end = Number.parseInt(rangeMatch[2]);
+        return tests.slice(start, end);
+    }
+    if (index.includes(',')) {
+        const indices = index.split(',').map((i) => Number.parseInt(i.trim()) - 1);
+        return indices.map((i) => tests[i]).filter(Boolean);
+    }
+    const num = Number.parseInt(index);
+    if (!Number.isNaN(num) && tests[num - 1]) {
+        return [tests[num - 1]];
+    }
+    return tests.filter((t) => t.status === 'pending');
+}

package/dist/boat/prima/src/prima.js

@@ -18,6 +18,7 @@ import { findSiteWith, listSites } from "../../../src/global-config.js";
 import { Reporter } from "../../../src/reporter.js";
 import { Stats } from "../../../src/stats.js";
 import { Task, Test, TestResult } from "../../../src/test-plan.js";
+import { ariaRefSnapshot } from "../../../src/utils/aria-ref.js";
 import { compactAriaSnapshot } from "../../../src/utils/aria.js";
 import { browserErrorMessage } from "../../../src/utils/browser-errors.js";
 import { pluralize } from "../../../src/utils/logger.js";
@@ -295,11 +296,17 @@ export class Prima {
             settleError = error;
             return null;
         });
-        if (settleError)
-            trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: browserErrorMessage(settleError) });
+        const stillOpen = ledger.filter((entry) => entry.status === 'open').length;
         for (const execution of invoked?.toolExecutions || []) {
             this.applyLedgerReport(execution, ledger, trace);
         }
+        let unsettled = '';
+        if (settleError)
+            unsettled = browserErrorMessage(settleError);
+        if (invoked && ledger.filter((entry) => entry.status === 'open').length === stillOpen)
+            unsettled = 'the model was asked to report every remaining instruction and reported none';
+        if (unsettled)
+            trace.push({ label: 'settling which instructions were satisfied', ok: false, proof: unsettled });
     }
     ledgerProgress(ledger) {
         return ledger
@@ -858,7 +865,7 @@ export class Prima {
         return path.join(path.basename(dir), name);
     }
     async refAriaSnapshot(result) {
-        const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.((page) => page.locator('body').ariaSnapshot({ mode: 'ai' }))).catch(() => null);
+        const snapshot = await Promise.resolve(this.bot.getExplorer()?.withPage?.(ariaRefSnapshot)).catch(() => null);
         return snapshot || result.ariaSnapshot;
     }
     executedCodes(code) {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explorbot",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "CLI app built with React Ink, CodeceptJS, and Playwright",
   "license": "Elastic-2.0",
   "type": "module",
@@ -101,7 +101,7 @@
     "bash-tool": "^1.3.15",
     "chalk": "^5.6.2",
     "cli-highlight": "^2.1.11",
-    "codeceptjs": "4.0.0-rc.16",
+    "codeceptjs": "4.2.0-beta.2",
     "commander": "^14.0.1",
     "debug": "^4.4.3",
     "dedent": "^1.6.0",
@@ -123,8 +123,8 @@
     "ora-classic": "^5.4.2",
     "parse5": "^8.0.0",
     "pixelmatch": "^7.2.0",
-    "playwright": "^1.62",
-    "playwright-core": "^1.62",
+    "playwright": "^1.63",
+    "playwright-core": "^1.63",
     "pngjs": "^7.0.0",
     "react": "^19.1.1",
     "sambanova-ai-provider": "^1.2.2",

package/dist/src/ai/fisherman/tools.js

@@ -3,8 +3,10 @@ import dedent from 'dedent';
 import { z } from 'zod';
 import { extractEndpointDefinition } from "../../api/spec-reader.js";
 import { tag } from "../../utils/logger.js";
+import { truncate } from "../../utils/strings.js";
 import { isDynamicSegment } from "../../utils/url-matcher.js";
 const BODY_PREVIEW_LIMIT = 2000;
+const READS_IN_ANSWER = 3;
 export function createFishermanTools(apiClient, requestStore, haul, opts) {
     const readOnly = opts.readOnly === true;
     let finished = false;
@@ -213,7 +215,7 @@ export function createAskApiTool(fisherman, task) {
                     return { answered: false, reason: result.summary || 'The API could not answer this question' };
                 }
                 task.addNote(`Asked API: ${question} — ${result.summary}`);
-                tag('success').log(`Ask API: ${result.summary}`);
+                tag('success').log(`Ask API: ${truncate(result.summary, 200)}`);
                 return { answered: true, answer: result.summary };
             },
         }),
@@ -252,6 +254,10 @@ function synthesizeResult(haul, declaredDone, readOnly) {
         succeeded = haul.successfulReads();
         successLabel = 'successful reads';
     }
+    if (readOnly && succeeded.length > 0) {
+        const bodies = succeeded.slice(-READS_IN_ANSWER).map((read) => `${read.toEndpoint()} → ${read.rawResponseBody.substring(0, BODY_PREVIEW_LIMIT)}`);
+        return { success: true, summary: bodies.join('\n\n'), created: [], failed: [] };
+    }
     let summary = `Stopped before finishing: ${made.length} requests, ${succeeded.length} ${successLabel}, ${failures.length} failed`;
     const lastFailure = failures[failures.length - 1];
     if (lastFailure)

package/dist/src/ai/fisherman.js

@@ -2,6 +2,7 @@ import dedent from 'dedent';
 import { isFailedRequest } from "../api/request-store.js";
 import { listAllEndpoints } from "../api/spec-reader.js";
 import { createDebug, tag } from "../utils/logger.js";
+import { truncate } from "../utils/strings.js";
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from "../utils/loop.js";
 import { RequestHaul } from "./fisherman/request-haul.js";
@@ -106,7 +107,7 @@ export class Fisherman {
     `);
         await this.runSession(conversation, tools, { haul, isFinished, finishFromText, label: `fisherman lookup: ${question.slice(0, 50)}` });
         const result = getResult();
-        tag('info').log(`Fisherman answer: ${result.summary}`);
+        tag('info').log(`Fisherman answer: ${truncate(result.summary, 200)}`);
         return result;
     }
     async runSession(conversation, tools, opts) {

package/dist/src/ai/pilot.d.ts

@@ -97,7 +97,6 @@ export declare class Pilot implements Agent {
     hasSuccessfulCheckEvidence(currentState: ActionResult, testerConversation: Conversation): boolean;
     formatSuccessfulAssertions(currentState: ActionResult, testerConversation: Conversation): string;
     formatActions(toolCalls: any[]): string;
-    buildDeletionScope(task: Test): string;
     getSystemPrompt(task: Test, initialState: ActionResult): string;
 }
 export type SettledStatus = 'passed' | 'failed' | 'unverified' | 'contradiction';

package/dist/src/ai/pilot.js

@@ -316,28 +316,28 @@ export class Pilot {
         return dedent `
       SCENARIO: ${task.scenario}
 
-      ${this.buildDeletionScope(task)}
-
       EXPECTED RESULTS (milestones):
       ${task.expected.map((e) => `- ${e}`).join('\n')}
     `;
     }
     buildResetSystemPrompt(task) {
         return dedent `
-      You are Pilot — decide whether a reset is legitimate. Reset is DESTRUCTIVE: it abandons this
-      iteration's work, but server-side side effects (records created, forms submitted) persist.
-      Unnecessary resets create duplicate data and infinite loops.
+      You are Pilot — decide whether a reset is legitimate. Reset only re-navigates to the start URL:
+      it writes nothing, though it abandons this iteration's work and server-side side effects persist.
+      The hazard is the tester REDOING a completed flow afterwards — duplicate data and infinite loops.
 
       ${this.buildSharedEvidenceRules()}
 
       DECISION:
-      - "allow": current page cannot host the scenario, irrecoverable error, or no path back.
-      - "continue": prior action already succeeded (URL changed, record visible, confirmation shown) — verify/finish instead. Or scenario goal may already be met; instruct tester to verify the actual outcome rather than redo. Provide guidance.
+      - "allow": current page cannot host the scenario, irrecoverable error, no path back, or an
+        expectation requires the outcome to survive a reload or a return to the start page and no
+        reset has been taken yet this run — there the reset IS the check, not a redo.
+      - "continue": the outcome the scenario needs is already observable on the CURRENT page — verify/finish instead. Provide guidance.
       - "fail": resetCount >= 2 and underlying situation hasn't changed; same flow tried twice with same failure mode.
       - "skipped": feature doesn't exist on this app or prerequisites can't be met.
 
       PRIORITY:
-      1) Successful side effects in session_log → almost never allow reset.
+      1) Successful side effects in session_log → allow reset only to re-observe them, never to repeat them.
       2) resetCount — each prior reset raises the bar.
       3) Tester's stated reason — weigh against evidence, don't trust blindly.
 
@@ -999,22 +999,6 @@ export class Pilot {
         })
             .join('\n\n');
     }
-    buildDeletionScope(task) {
-        const deletableItems = task.plan
-            ? task.plan
-                .listTests()
-                .filter((t) => t.isSuccessful && t.sessionName)
-                .map((t) => t.sessionName)
-            : [];
-        const scenarioLower = task.scenario.toLowerCase();
-        if (deletableItems.length > 0) {
-            return `For deletion scenarios, items can only be deleted if their title contains: ${deletableItems.join(', ')}`;
-        }
-        if (scenarioLower.includes('delete') || scenarioLower.includes('remove')) {
-            return 'No items available for deletion — test should create an item first';
-        }
-        return '';
-    }
     getSystemPrompt(task, initialState) {
         const interactive = isInteractive();
         const stepsText = task.plannedSteps.length > 0 ? task.plannedSteps.map((s, i) => `${i + 1}. ${s}`).join('\n') : 'No planned steps';

package/dist/src/ai/planner.d.ts

@@ -9,6 +9,7 @@ import { Conversation } from './conversation.js';
 import type { Fisherman } from './fisherman.js';
 import type { Provider } from './provider.js';
 import { type Researcher } from './researcher.js';
+import type { Scout } from './scout.js';
 declare const PlannerBase: {
     new (...args: any[]): {
         currentPlan: Plan | null;
@@ -59,9 +60,12 @@ export declare class Planner extends PlannerBase implements Agent {
     lastSuite: Suite | null;
     researcher: Researcher;
     fisherman: Fisherman | null;
+    scout: Scout | null;
     constructor(deps: AgentDeps, researcher: Researcher);
     setFisherman(fisherman: Fisherman): void;
+    setScout(scout: Scout): void;
     get sectionOrder(): string[];
+    get docsWeight(): number;
     getDefaultStartUrl(state: {
         url: string;
         fullUrl?: string;

package/dist/src/ai/planner.js

@@ -50,6 +50,7 @@ export class Planner extends PlannerBase {
     lastSuite = null;
     researcher;
     fisherman = null;
+    scout = null;
     constructor(deps, researcher) {
         super();
         this.explorer = deps.explorer;
@@ -62,9 +63,16 @@ export class Planner extends PlannerBase {
     setFisherman(fisherman) {
         this.fisherman = fisherman;
     }
+    setScout(scout) {
+        this.scout = scout;
+    }
     get sectionOrder() {
         return ConfigParser.getInstance().getConfig().ai?.agents?.researcher?.sections || Object.keys(POSSIBLE_SECTIONS);
     }
+    get docsWeight() {
+        const value = ConfigParser.getInstance().getConfig().ai?.agents?.planner?.docsWeight ?? 70;
+        return Math.max(0, Math.min(100, value));
+    }
     getDefaultStartUrl(state) {
         return state.fullUrl || state.url;
     }
@@ -291,6 +299,7 @@ export class Planner extends PlannerBase {
         const conversation = new Conversation([], model);
         conversation.autoTrimTag('page_research', 20000);
         conversation.autoTrimTag('tested_scenarios', 10000);
+        conversation.autoTrimTag('docs_context', 8000);
         conversation.addUserText(this.getSystemMessage(feature));
         const planningPrompt = dedent `
       <task>
@@ -345,6 +354,10 @@ export class Planner extends PlannerBase {
         const research = await this.researcher.research(currentState || state, {
             deep: true,
         });
+        let docsPromise = null;
+        if (this.scout && this.docsWeight > 0) {
+            docsPromise = this.scout.collectDocs({ url: state.url, title: state.title, feature, excludeUrls: this.knowledgeTracker.applicationSpecUrls(state) });
+        }
         let plannerResearch = mdq(research).query('code').replace('');
         plannerResearch = mdq(plannerResearch)
             .query('table')
@@ -376,6 +389,21 @@ export class Planner extends PlannerBase {
         if (applicationContext) {
             conversation.addUserText(applicationContext);
         }
+        if (docsPromise) {
+            const docs = await docsPromise;
+            if (docs) {
+                conversation.addUserText(dedent `
+          <docs_context>
+          Documentation retrieved from the collected corpus by the Scout agent.
+          Ground scenarios in these documented capabilities where they apply; treat them as supporting context, not a script.
+
+          Aim for roughly ${this.docsWeight}% of the scenarios to exercise behavior documented above; the remainder may explore beyond the documentation.
+
+          ${docs}
+          </docs_context>
+        `);
+            }
+        }
         conversation.addUserText(dedent `
       ${this.buildApproach(style)}
 

package/dist/src/ai/provider.js

@@ -366,7 +366,9 @@ export class Provider {
         const modelName = getModelName(model);
         setActivity(`🤖 Asking ${modelName} with dynamic tools`, 'ai');
         promptLog(`Using model: ${modelName}`);
-        const toolsWithCommentary = tools?.commentary ? tools : { ...tools, commentary: createHarmonyChannelFallbackTool() };
+        let toolsWithCommentary = tools;
+        if (!tools?.commentary && options.toolChoice !== 'required')
+            toolsWithCommentary = { ...tools, commentary: createHarmonyChannelFallbackTool() };
         const toolNames = Object.keys(toolsWithCommentary || {});
         tag('debug').log(`Tools enabled: [${toolNames.join(', ')}]`);
         promptLog('Available tools:', toolNames);

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

@@ -38,7 +38,7 @@ export declare function WithDeepAnalysis<T extends Constructor>(Base: T): {
         }>): Promise<void>;
         _executeAndAnalyze(commands: string[], description: string, state: WebPageState, originalAria: string, alreadyExpanded: string[]): Promise<ExpansionOutcome>;
         _restorePageState(url: string, originalAria: string): Promise<void>;
-        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null>;
+        _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[], containerCss?: string | null): Promise<string | null>;
         _deduplicateExpandedSections(sections: string[]): string[];
         _summarizeExpanded(expandedSections: string[]): string[];
         _sectionFingerprint(sectionMarkdown: string): string | null;

package/dist/src/ai/researcher/deep-analysis.js

@@ -85,7 +85,7 @@ export function WithDeepAnalysis(Base) {
                 .filter((s) => s.elements.length > 0)
                 .map((s) => s.rawMarkdown));
             tag('substep').log(`Researching overlay: ${region.name}`);
-            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded, region.root);
             if (!sectionMarkdown) {
                 debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
                 return null;
@@ -367,9 +367,9 @@ export function WithDeepAnalysis(Base) {
             }
             await new Promise((r) => setTimeout(r, 500));
             let diff;
+            let currAR;
             try {
-                await this.explorer.capture();
-                const currAR = ActionResult.fromState(this.stateManager.getCurrentState());
+                currAR = await this.explorer.capture();
                 diff = await currAR.diff(previousState);
             }
             catch (err) {
@@ -388,7 +388,7 @@ export function WithDeepAnalysis(Base) {
                 debugLog(`No changes from: ${description.slice(0, 80)}`);
                 return { status: 'none', code: clickCode };
             }
-            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded);
+            const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded, currAR.overlay.root);
             await this._restorePageState(state.url, originalAria);
             if (!sectionMarkdown)
                 return { status: 'none', code: clickCode };
@@ -413,7 +413,7 @@ export function WithDeepAnalysis(Base) {
                 tag('warning').log(`navigateTo failed during restore: ${err instanceof Error ? err.message : err}`);
             }
         }
-        async _analyzeExpandedAction(code, description, diff, alreadyExpanded) {
+        async _analyzeExpandedAction(code, description, diff, alreadyExpanded, containerCss = null) {
             const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
             let intro;
             if (code) {
@@ -473,7 +473,15 @@ export function WithDeepAnalysis(Base) {
             const sections = parseResearchSections(text);
             if (sections.length === 0)
                 return null;
-            return sections[0].rawMarkdown;
+            const sectionMarkdown = sections[0].rawMarkdown;
+            if (!containerCss)
+                return sectionMarkdown;
+            let heading = mdq(sectionMarkdown).query('h3[0]');
+            if (heading.count() === 0)
+                heading = mdq(sectionMarkdown).query('h2[0]');
+            if (heading.count() === 0)
+                return sectionMarkdown;
+            return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
         }
         _deduplicateExpandedSections(sections) {
             const seen = new Set();

package/dist/src/ai/rules.js

@@ -6,8 +6,9 @@ const locatorPriorityRule = dedent `
 
   1. ARIA locators (first choice) - target browser's accessibility tree, most reliable
      Use JSON format: { "role": "button", "text": "Login" }
-     Copy role and text VERBATIM from the ARIA snapshot or UI map — never guess the pair.
-     If the element is absent from the snapshot, do not invent one; use text or CSS instead.
+     Copy role and text VERBATIM from the ARIA snapshot, UI map, or the page diff that
+     reported the element — never guess the pair; a guessed role can silently match a
+     different element with the same text. If named nowhere, use text or CSS instead.
 
   2. Text locators (second choice) - exact visible text, use only when unique on the page
      Example: 'Login', 'Submit', 'Username'
@@ -225,10 +226,10 @@ export const unexpectedPopupRule = dedent `
   If buttons are disabled unexpectedly, check if a popup is blocking interaction or if required form fields are empty.
 
   Dismiss strategy (try in order):
-  1. I.clickXY(0, 0) — click outside the popup to close it
-  2. I.pressKey('Escape') — press Escape to dismiss
-  3. I.click('Cancel') — click Cancel button if present
-  4. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  1. I.pressKey('Escape') — press Escape to dismiss
+  2. I.click('Cancel') — click Cancel button if present
+  3. I.click({ role: 'button', text: 'Close' }) — click X/close button if present
+  4. I.clickXY(0, 0) via form() tool and check if page diff changed
   </unexpected_popup_rule>
 `;
 export const sectionContextRule = dedent `
@@ -318,7 +319,7 @@ export const actionRule = dedent `
   Prefer text/ARIA locators with context over complex CSS/XPath selectors.
   For inline create/edit flows, after filling a field verify it contains the value, then confirm using the nearest explicit button/link, an adjacent icon-only confirm control in the same row/form, or Enter if the field remains focused.
   If locator doesn't work, try CSS or XPath locators.
-  If nothing works, use I.clickXY(x, y) as last resort.
+  If nothing works, use visualClick() — it locates the target in a screenshot before clicking it.
 
   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.

package/dist/src/ai/scout/tools.d.ts

@@ -0,0 +1,17 @@
+export declare function loadScoutCorpus(dirs: string[]): ScoutCorpus;
+export declare function excludeCorpusUrls(corpus: ScoutCorpus, urls: string[]): ScoutCorpus;
+export declare function createScoutTools(corpus: ScoutCorpus): Promise<{
+    tools: Record<string, any>;
+    scanner: "rg" | "grep";
+    getResult: () => string;
+    finishFromText: (text?: string) => void;
+}>;
+export interface ScoutCorpus {
+    dirs: string[];
+    files: ScoutCorpusFile[];
+    excludedPaths: string[];
+}
+export interface ScoutCorpusFile {
+    path: string;
+    url?: string;
+}