explorbot 0.1.5 → 0.1.6

package/dist/src/ai/tools.js

@@ -389,9 +389,9 @@ export function createSpecialContextTools(explorer, context) {
         }),
     };
 }
-export function createAgentTools({ explorer, researcher, navigator, }) {
+export function createAgentTools({ explorer, researcher, navigator, experienceTracker, getState, }) {
     let visionDisabled = false;
-    return {
+    const tools = {
         see: tool({
             description: dedent `
         Check the page contents based on current page state and screenshot.
@@ -830,6 +830,31 @@ export function createAgentTools({ explorer, researcher, navigator, }) {
             },
         }),
     };
+    if (experienceTracker && getState) {
+        tools.learn_experience = tool({
+            description: dedent `
+        Read the full body of a specific experience section listed in <experience>.
+        The TOC shows entries like "A.1 ## Successful Flow: ...". Pass the fileTag and sectionIndex.
+        Only call when a TOC entry looks directly relevant to the current step.
+      `,
+            inputSchema: z.object({
+                fileTag: z.string().describe('File tag from the TOC, e.g. "A", "B", "AA"'),
+                sectionIndex: z.number().int().positive().describe('1-based section index within that file'),
+            }),
+            execute: async ({ fileTag, sectionIndex }) => {
+                const state = getState();
+                if (!state) {
+                    return { error: 'No current page state available.' };
+                }
+                const section = experienceTracker.getExperienceSection(fileTag, sectionIndex, state);
+                if (!section) {
+                    return { error: 'Section not found. Experience may have been updated; re-read the latest TOC.' };
+                }
+                return section;
+            },
+        });
+    }
+    return tools;
 }
 const PAGE_DIFF_SUGGESTION = 'Analyze page diff. htmlParts shows what changed and WHERE — each part has a container selector. Use the container as context when clicking elements from the diff.';
 function transformContainsCommand(command) {

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

@@ -1,8 +1,6 @@
-import { existsSync, readdirSync } from 'node:fs';
 import figureSet from 'figures';
 import path from 'node:path';
 import { getStyles } from '../ai/planner/styles.js';
-import { ConfigParser } from "../config.js";
 import { getCliName } from "../utils/cli-name.js";
 import { jsonToTable } from '../utils/markdown-parser.js';
 import { tag } from '../utils/logger.js';
@@ -110,14 +108,11 @@ export class ExploreCommand extends BaseCommand {
         }
     }
     printRerunSuggestions() {
-        const testsDir = ConfigParser.getInstance().getTestsDir();
-        if (!existsSync(testsDir))
+        const savedFiles = this.explorBot.agentHistorian().getSavedFiles();
+        if (savedFiles.length === 0)
             return;
-        const testFiles = readdirSync(testsDir).filter((f) => f.endsWith('.js'));
-        if (testFiles.length === 0)
-            return;
-        for (const file of testFiles) {
-            tag('info').log(`Generated: ${file}`);
+        for (const filePath of savedFiles) {
+            tag('info').log(`Generated: ${path.basename(filePath)}`);
         }
         tag('info').log(`List tests: ${getCliName()} runs`);
         tag('info').log(`Re-run with healing: ${getCliName()} rerun <filename> [index]`);

package/dist/src/experience-tracker.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import matter from 'gray-matter';
+import { marked } from 'marked';
 import { ConfigParser } from './config.js';
 import { KnowledgeTracker } from './knowledge-tracker.js';
 import { createDebug, tag } from './utils/logger.js';
@@ -290,4 +291,128 @@ ${filteredCode}
         }
         return results;
     }
+    getExperienceTableOfContents(state, options) {
+        const records = this.getRelevantExperience(state, options);
+        if (records.length === 0)
+            return [];
+        const sorted = [...records].sort((a, b) => {
+            const aHash = basename(a.filePath, '.md');
+            const bHash = basename(b.filePath, '.md');
+            return aHash.localeCompare(bHash);
+        });
+        const toc = [];
+        for (let i = 0; i < sorted.length; i++) {
+            const record = sorted[i];
+            const fileHash = basename(record.filePath, '.md');
+            const url = record.data?.url || '';
+            const sections = listTocHeadings(record.content);
+            if (sections.length === 0)
+                continue;
+            toc.push({
+                fileTag: indexToLetters(i),
+                fileHash,
+                url,
+                sections,
+            });
+        }
+        return toc;
+    }
+    getExperienceSection(fileTag, sectionIndex, state, options) {
+        const toc = this.getExperienceTableOfContents(state, options);
+        const entry = toc.find((e) => e.fileTag === fileTag);
+        if (!entry)
+            return null;
+        const filePath = this.findExperienceFileByHash(entry.fileHash);
+        if (!filePath)
+            return null;
+        const { content } = this.readExperienceFile(entry.fileHash);
+        const extracted = extractHeadingSection(content, sectionIndex);
+        if (!extracted)
+            return null;
+        return { title: extracted.title, url: entry.url, content: extracted.body };
+    }
+    findExperienceFileByHash(fileHash) {
+        for (const dir of this.getExperienceDirectories()) {
+            const candidate = join(dir, `${fileHash}.md`);
+            if (existsSync(candidate))
+                return candidate;
+        }
+        return null;
+    }
+}
+function listTocHeadings(content) {
+    const tokens = marked.lexer(content);
+    const result = [];
+    let index = 0;
+    for (const token of tokens) {
+        if (token.type !== 'heading')
+            continue;
+        const heading = token;
+        if (heading.depth !== 2 && heading.depth !== 3)
+            continue;
+        index++;
+        result.push({ index, level: heading.depth, title: heading.text });
+    }
+    return result;
+}
+function extractHeadingSection(content, sectionIndex) {
+    const tokens = marked.lexer(content);
+    const matching = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token.type !== 'heading')
+            continue;
+        const heading = token;
+        if (heading.depth !== 2 && heading.depth !== 3)
+            continue;
+        matching.push({ tokenIdx: i, depth: heading.depth, text: heading.text });
+    }
+    if (sectionIndex < 1 || sectionIndex > matching.length)
+        return null;
+    const target = matching[sectionIndex - 1];
+    let endTokenIdx = tokens.length;
+    for (let j = target.tokenIdx + 1; j < tokens.length; j++) {
+        const token = tokens[j];
+        if (token.type !== 'heading')
+            continue;
+        if (token.depth <= target.depth) {
+            endTokenIdx = j;
+            break;
+        }
+    }
+    const body = tokens
+        .slice(target.tokenIdx, endTokenIdx)
+        .map((t) => t.raw || '')
+        .join('');
+    return { title: target.text, body };
+}
+function indexToLetters(index) {
+    let n = index;
+    let result = '';
+    while (true) {
+        result = String.fromCharCode(65 + (n % 26)) + result;
+        n = Math.floor(n / 26);
+        if (n === 0)
+            break;
+        n -= 1;
+    }
+    return result;
+}
+export function renderExperienceToc(toc) {
+    if (toc.length === 0)
+        return '';
+    const lines = [];
+    lines.push('<experience>');
+    lines.push('Past experience for this page. Call learn_experience({ fileTag, sectionIndex }) to read a section.');
+    lines.push('');
+    for (const entry of toc) {
+        lines.push(`File ${entry.fileTag} ${entry.url}:`);
+        for (const section of entry.sections) {
+            const prefix = '#'.repeat(section.level);
+            lines.push(`  ${entry.fileTag}.${section.index} ${prefix} ${section.title}`);
+        }
+        lines.push('');
+    }
+    lines.push('</experience>');
+    return lines.join('\n');
 }

package/dist/src/explorbot.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
+import { ActionResult } from "./action-result.js";
 import { ApiClient } from "./api/api-client.js";
 import { RequestStore } from "./api/request-store.js";
 import { loadSpec } from "./api/spec-reader.js";
@@ -144,8 +145,14 @@ export class ExplorBot {
         return (this.agents.pilot ||= this.createAgent(({ ai, explorer }) => {
             const researcher = this.agentResearcher();
             const navigator = this.agentNavigator();
-            const tools = createAgentTools({ explorer, researcher, navigator });
-            return new Pilot(ai, tools, researcher, explorer);
+            const stateManager = explorer.getStateManager();
+            const experienceTracker = stateManager.getExperienceTracker();
+            const getState = () => {
+                const state = stateManager.getCurrentState();
+                return state ? ActionResult.fromState(state) : null;
+            };
+            const tools = createAgentTools({ explorer, researcher, navigator, experienceTracker, getState });
+            return new Pilot(ai, tools, researcher, explorer, experienceTracker);
         }));
     }
     agentTester() {

package/dist/src/utils/aria.js

@@ -333,8 +333,40 @@ const parseAriaSnapshot = (snapshot, keepNamed = false) => {
     }
     return pruneNodes(roots, keepNamed);
 };
+const CLOSE_OVERLAY_BUTTON_RE = /^close\s+(modal|dialog|popup|drawer|panel|sheet)\b/i;
+const findOverlayByCloseButton = (nodeList) => {
+    const closeIdx = nodeList.findIndex((n) => n.role === 'button' && CLOSE_OVERLAY_BUTTON_RE.test(n.name || ''));
+    if (closeIdx !== -1) {
+        let heading;
+        for (let i = closeIdx - 1; i >= 0; i--) {
+            if (nodeList[i].role === 'heading' && nodeList[i].name) {
+                heading = nodeList[i];
+                break;
+            }
+        }
+        if (!heading) {
+            for (let i = closeIdx + 1; i < nodeList.length; i++) {
+                if (nodeList[i].role === 'heading' && nodeList[i].name) {
+                    heading = nodeList[i];
+                    break;
+                }
+            }
+        }
+        return {
+            detected: true,
+            type: 'dialog',
+            name: heading?.name || null,
+        };
+    }
+    for (const node of nodeList) {
+        const inner = findOverlayByCloseButton(node.children);
+        if (inner)
+            return inner;
+    }
+    return null;
+};
 export const detectFocusArea = (snapshot) => {
-    const nodes = parseAriaSnapshot(snapshot);
+    const nodes = parseAriaSnapshot(snapshot, true);
     const findFocusArea = (nodeList) => {
         for (const node of nodeList) {
             if (node.role === 'dialog' || node.role === 'alertdialog') {
@@ -359,7 +391,12 @@ export const detectFocusArea = (snapshot) => {
         return null;
     };
     const result = findFocusArea(nodes);
-    return result || { detected: false, type: null, name: null };
+    if (result)
+        return result;
+    const fallback = findOverlayByCloseButton(nodes);
+    if (fallback && fallback.name)
+        return fallback;
+    return { detected: false, type: null, name: null };
 };
 export const collectInteractiveNodes = (snapshot) => {
     const nodes = parseAriaSnapshot(snapshot);

package/package.json

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

package/rules/planner/styles/curious.md

@@ -1,5 +1,12 @@
 Detect new valid paths that previous tests missed. Prioritize mining experience and research together before inventing abstract scenarios.
 
+Rank every scenario you build by the **strength of its outcome**, from strongest to weakest:
+1. **Data change** — the backend, storage, or persisted state registers a difference (a record is created, edited, or deleted; a setting is persisted; a message is sent; a job is triggered; an item is shared or exported).
+2. **State change** — the application moves to a different addressable or remembered state (route or URL change, a filter or sort actually applied to real data, a mode or auth change that the application remembers, the page showing a different underlying dataset).
+3. **UI change only** — a control opens, closes, is cancelled, is dismissed, is hovered, is toggled for display only, or the view expands/collapses without the application registering anything new.
+
+Prefer scenarios whose ending falls into category 1. Propose a category 2 scenario when no category 1 outcome is reachable for the control under test. Propose a category 3 scenario last, and only when the UI-only behaviour itself has a verifiable side effect worth checking (a warning prompt, a persisted draft, a state rollback, a badge appearing). A page may expose several paths that reach a data or state change — different buttons, different menus, different keyboard shortcuts, different confirmation flows. Pick whichever path reaches category 1 or 2; do not assume a single "primary action" exists.
+
 When <previously_tested_flows> is present, treat it as the ground truth for what already worked:
 - List items under Successful Flow describe the path that was executed
 - Lines in blockquotes (lines starting with >) are discoveries: extra fields, side panels, conditional UI, inputs called out during that run
@@ -11,7 +18,7 @@ When <previously_tested_flows> is NOT present, use <tested_scenarios> as the gro
 Read the step lines for each test to understand which controls were actually interacted with.
 Identify elements from <page_research> that appear in NO test steps — these are coverage gaps.
 
-Cross-read with <page_research>: for each form and Extended Research subsection, compare against those flows. Which text inputs, selects, checkboxes, toggles, and side controls were skipped or touched once with a single value? Prefer filling those gaps over repeating the same path.
+Cross-read with <page_research>: for each section and Extended Research subsection, compare against those flows. Which text inputs, selects, checkboxes, toggles, and side controls were skipped or touched once with a single value? Prefer filling those gaps over repeating the same path.
 
 The Type column in <page_research> tables shows the ARIA role of each element.
 Cross-reference these types with the steps listed in <tested_scenarios> or <previously_tested_flows>:
@@ -24,16 +31,22 @@ Coverage gaps to look for:
 - Action buttons that were never clicked as part of a complete workflow
 - Dependent UI: controls that appear or change based on another control's value
 
-When proposing tests for forms, prefer filling ALL visible fields — not just required ones.
+A coverage gap for an untested control is only **closed** when the scenario built around it reaches a data change or state change. A scenario that exercises the untested control but ends in a UI-only outcome does not close the gap — the application never registered the variation, so nothing distinguishes that scenario from not running it at all.
+
+Exercising an untested control and testing a UI-only dismissal (cancel, close, navigate away, discard) are **two different categories of scenario**. Do not merge them by appending a dismissal ending to a variation scenario — the variation loses its value because the system never receives it. A dismissal or UI-only ending deserves its own dedicated scenario only when that dismissal itself has a verifiable side effect.
+
+When multiple inputs or configurable controls contribute to the same outcome, prefer scenarios that configure **several of them together** before triggering the data or state change, rather than touching one control in isolation and ending there.
 Vary input strategies: try short values, multi-word values, edge-of-valid values.
-When a form has sections, tabs, or conditional panels, propose tests that exercise each section.
-If a control has downstream effects (e.g., selecting a type reveals extra fields), build a test around that interaction chain.
+When sections, tabs, or conditional panels exist, exercise each section.
+When a control has downstream effects (selecting one option reveals extra fields, toggling one setting enables another), build the scenario around that interaction chain — and still end it in a data or state change.
 
 Combinatorial coverage (valid data only):
 - For each select or equivalent, ensure each option is exercised in at least one scenario, or one scenario whose steps walk through distinct options in sequence if that fits the task constraints better
 - Exercise each checkbox or binary control in both states when behavior can differ
 - Combine checkboxes and related toggles in small sets (pairs or triples) when they plausibly change validation, visible sections, or outcomes — avoid exploding into huge Cartesian products
 
-When heavy forms are not the focus, still pursue: unvisited state transitions, follow-ups after creates (share, export, duplicate), alternative routes to the same goal, preconditions that unlock UI, and visible controls never clicked.
+Each proposed combination must be exercised in a scenario that reaches a data change or state change. Combinations that only change the UI and never reach a registerable outcome do not count as coverage — the system never distinguishes them from each other.
+
+When the page is not heavy on inputs, still pursue: unvisited state transitions, follow-ups after data-changing operations (share, export, duplicate, re-open), alternative paths to the same data change, preconditions that unlock new data-changing actions, and visible controls never clicked. Again, prioritise scenarios whose ending falls into category 1 or 2.
 
 Skip the Menu/Navigation section — we are testing THIS page.

package/rules/planner/styles/normal.md

@@ -2,18 +2,18 @@ Study the page and figure out its business purpose. What is this page FOR? What
 
 Based on the page type, propose tests for COMPLETE user workflows:
 - If this is a data page (lists, tables): test CRUD operations end-to-end (create item → verify in list, edit item → verify changes saved, delete item → verify removed)
-- If this is a form page: test full submission flow, not just "form appears"
+- If the page has inputs to fill in: test the full commit flow, not just that the controls render
 - If this has filters and search: test filtering AND verify results change, not just "filter tab clicked"
 - If this has modals/dropdowns: test the ACTION inside them, not just opening/closing them
 
-Each test should end with the application in a different state than it started.
+Each test should end in a **data change** (record created/edited/deleted, setting persisted, message sent) or a **state change** (route change, filter applied to real data, mode change the app remembers). Tests ending in UI-only outcomes (open, close, hover, expand) are the weakest and should be rare.
 
 IMPORTANT: Distribute tests across DIFFERENT feature areas from the research.
 Do not propose more than 2 tests for the same feature area.
 Every Extended Research section (modal, dropdown, panel) with actionable features deserves at least one test.
-Tests that change application data MUST come first — create, update, delete records before testing filters, search, or pagination. You are aiming to change application state.
+Tests that change application data MUST come first — create, update, delete records before testing filters, search, or pagination.
 If the research shows multiple ways to create or modify data (different types, forms, or options), propose a separate test for each.
-View only tests (tab switching, pagination, view toggles) should be proposed only after  data-changing interactions are covered.
+UI-only tests (tab switching, pagination, view toggles) should be proposed only after data-changing and state-changing interactions are covered.
 
 Skip the Menu/Navigation section — we are testing THIS page.
 

package/rules/planner/styles/psycho.md

@@ -1,14 +1,17 @@
-Stress-test the page by filling invalid, empty, and extreme values into every input.
+Stress-test the page by feeding invalid, empty, or extreme values to its controls and committing.
 
-Focus on:
-- Empty states: submit forms with no data, clear required fields, remove default values
-- Long values: paste 10000 characters into inputs, use extremely long names and descriptions
-- Boundary values: zero, negative numbers, special characters, unicode, HTML tags in text fields
-- Invalid formats: wrong email formats, letters in number fields, SQL injection strings, script tags
-- Invalid combinations: select incompatible options, mix conflicting settings
-- Combining states: apply multiple filters at once, use conflicting form values together
-- Out-of-range values: dates in the past/future, quantities beyond limits, prices with too many decimals
+**Match attack breadth to controls reachable.** If only ONE control is reachable, attack it alone. If several are reachable, attack **all of them in the same scenario** — each with a different strange value. Never stress one while leaving the rest untouched: attacking one-at-a-time hides interaction bugs and wastes plan budget.
 
-Push every input to its limits. Find what breaks when the form receives unexpected data.
+Do not produce multiple scenarios that each isolate one control of the same section. Fold those attacks into fewer scenarios that push every reachable control strangely at once. Vary the **mix** between scenarios — which control receives SQL, which receives 10000 chars, which receives unicode, which receives a conflicting combination — not the single control under attack.
 
-Skip the Menu/Navigation section — we are testing THIS page.
+**Attack categories** (combine across controls, not one-per-scenario):
+empty • very long (10000+ chars) • boundary (zero, negative, unicode, HTML, special chars) • invalid formats (malformed email/url/number, SQL, script tags) • invalid combinations (mutually exclusive toggles together, conflicting modes) • out-of-range (far dates, quantities beyond limits, excess decimals) • dependent-UI stress (flip a control that reveals more, attack those too).
+
+**Prefer scenarios that:**
+- Push every reachable control to a different bad-data category, then commit
+- Trigger a conditional section, attack revealed and base controls together, then commit
+- Combine mutually exclusive control states with invalid values, then commit
+
+End each scenario with the state **committed** (saved, applied, sent, triggered). A scenario that enters bad data then cancels or navigates away reveals nothing — the application never received the payload.
+
+Skip the Menu/Navigation section — we are testing THIS page.

package/src/ai/captain/web-mode.ts

@@ -1,6 +1,7 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
+import { ActionResult } from '../../action-result.ts';
 import { actionRule, locatorRule, sectionContextRule } from '../rules.ts';
 import { createAgentTools, createCodeceptJSTools } from '../tools.ts';
 import { type Constructor, type ModeContext, debugLog } from './mixin.ts';
@@ -9,13 +10,19 @@ export function WithWebMode<T extends Constructor>(Base: T) {
   return class extends Base {
     webModeTools(ctx: ModeContext): Record<string, any> {
       const explorer = ctx.explorBot.getExplorer();
+      const stateManager = explorer.getStateManager();
       const codeceptTools = createCodeceptJSTools(explorer, ctx.task);
       const agentTools = createAgentTools({
         explorer,
         researcher: ctx.explorBot.agentResearcher(),
         navigator: ctx.explorBot.agentNavigator(),
+        experienceTracker: stateManager.getExperienceTracker(),
+        getState: () => {
+          const state = stateManager.getCurrentState();
+          return state ? ActionResult.fromState(state) : null;
+        },
       });
-      const { see, context, visualClick } = agentTools;
+      const { see, context, visualClick, learn_experience } = agentTools;
 
       return {
         navigate: tool({
@@ -96,6 +103,7 @@ export function WithWebMode<T extends Constructor>(Base: T) {
         see,
         context,
         visualClick,
+        learn_experience,
       };
     }
 

package/src/ai/historian.ts

@@ -22,6 +22,7 @@ export class Historian {
   private experienceTracker: ExperienceTracker;
   private reporter?: Reporter;
   private stateManager?: StateManager;
+  private savedFiles = new Set<string>();
 
   constructor(provider: Provider, experienceTracker?: ExperienceTracker, reporter?: Reporter, stateManager?: StateManager) {
     this.provider = provider;
@@ -30,6 +31,10 @@ export class Historian {
     this.stateManager = stateManager;
   }
 
+  getSavedFiles(): string[] {
+    return [...this.savedFiles];
+  }
+
   async saveSession(task: Task, initialState: ActionResult, conversation: Conversation): Promise<void> {
     debugLog('Saving session experience');
 
@@ -433,6 +438,7 @@ export class Historian {
     const filename = plan.title.replace(/[^a-zA-Z0-9]/g, '_').toLowerCase();
     const filePath = join(testsDir, `${filename}.js`);
     writeFileSync(filePath, lines.join('\n'));
+    this.savedFiles.add(filePath);
 
     tag('substep').log(`Saved plan tests to: ${filePath}`);
     return filePath;
@@ -447,6 +453,7 @@ export class Historian {
     }
 
     writeFileSync(filePath, content);
+    this.savedFiles.add(filePath);
     tag('substep').log(`Updated test file with healed steps: ${filePath}`);
   }
 

package/src/ai/pilot.ts

@@ -1,8 +1,9 @@
 import { tool } from 'ai';
 import dedent from 'dedent';
 import { z } from 'zod';
-import type { ActionResult } from '../action-result.ts';
+import { ActionResult } from '../action-result.ts';
 import { ConfigParser } from '../config.ts';
+import { type ExperienceTracker, renderExperienceToc } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
 import { type Test, TestResult } from '../test-plan.ts';
 import { collectInteractiveNodes, detectFocusArea, extractFocusedElement } from '../utils/aria.ts';
@@ -28,12 +29,14 @@ export class Pilot implements Agent {
   private researcher: Researcher;
   private explorer: Explorer;
   private fisherman: Fisherman | null = null;
+  private experienceTracker: ExperienceTracker | null;
 
-  constructor(provider: Provider, agentTools: any, researcher: Researcher, explorer: Explorer) {
+  constructor(provider: Provider, agentTools: any, researcher: Researcher, explorer: Explorer, experienceTracker?: ExperienceTracker) {
     this.provider = provider;
     this.agentTools = agentTools;
     this.researcher = researcher;
     this.explorer = explorer;
+    this.experienceTracker = experienceTracker || null;
   }
 
   setFisherman(fisherman: Fisherman): void {
@@ -376,7 +379,15 @@ export class Pilot implements Agent {
 
   private async sendToPilot(userText: string, functionId: string, opts: { tools?: boolean; maxToolRoundtrips?: number; task?: Test } = {}): Promise<string> {
     debugLog(`sendToPilot: ${functionId}, tools: ${!!opts.tools}, roundtrips: ${opts.maxToolRoundtrips ?? 0}`);
-    this.conversation!.addUserText(userText);
+
+    let finalUserText = userText;
+    if (opts.tools) {
+      const tocBlock = this.getExperienceToc();
+      if (tocBlock) {
+        finalUserText = `${tocBlock}\n\n${userText}`;
+      }
+    }
+    this.conversation!.addUserText(finalUserText);
     let tools = opts.tools ? this.agentTools : undefined;
 
     if (opts.tools && opts.task) {
@@ -391,6 +402,15 @@ export class Pilot implements Agent {
     return result?.response?.text || '';
   }
 
+  private getExperienceToc(): string {
+    if (!this.experienceTracker) return '';
+    const state = this.explorer.getStateManager().getCurrentState();
+    if (!state) return '';
+    const actionResult = ActionResult.fromState(state);
+    const toc = this.experienceTracker.getExperienceTableOfContents(actionResult);
+    return renderExperienceToc(toc);
+  }
+
   private buildPreconditionTool(task: Test) {
     return {
       precondition: tool({

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

@@ -3,10 +3,12 @@ import { ActionResult, type Diff } from '../../action-result.js';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';
-import { diffAriaSnapshots } from '../../utils/aria.ts';
+import { detectFocusArea, diffAriaSnapshots } from '../../utils/aria.ts';
 import { executionController } from '../../execution-controller.ts';
 import { tag } from '../../utils/logger.js';
+import { mdq } from '../../utils/markdown-query.ts';
 import type { Provider } from '../provider.js';
+import { getCachedResearch, saveResearch } from './cache.ts';
 import { type Constructor, debugLog } from './mixin.ts';
 import { type ResearchElement, parseResearchSections } from './parser.ts';
 import type { ResearchResult } from './research-result.ts';
@@ -76,6 +78,55 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
     }
 
+    async researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null> {
+      const focusArea = detectFocusArea(current.ariaSnapshot);
+      if (!focusArea.detected || !focusArea.name) return null;
+      if (focusArea.type !== 'dialog' && focusArea.type !== 'modal') return null;
+
+      const cached = getCachedResearch(pageStateHash);
+      if (!cached) return null;
+
+      const escaped = focusArea.name.replace(/"/g, '\\"');
+      if (mdq(cached).query(`section3(~"${escaped}")`).count() > 0) {
+        debugLog(`Overlay "${focusArea.name}" already in cached research, skipping`);
+        return null;
+      }
+
+      const diff = await current.diff(previous);
+      await diff.calculate();
+
+      if (!diff.ariaChanged && diff.htmlParts.length === 0) {
+        debugLog(`No diff between current and previous state for overlay "${focusArea.name}"`);
+        return null;
+      }
+
+      const alreadyExpanded = this._summarizeExpanded(
+        parseResearchSections(cached)
+          .filter((s) => s.elements.length > 0)
+          .map((s) => s.rawMarkdown)
+      );
+
+      tag('substep').log(`Researching overlay: ${focusArea.name}`);
+      const sectionMarkdown = await this._analyzeExpandedAction('', focusArea.name, diff, alreadyExpanded);
+      if (!sectionMarkdown) {
+        debugLog(`Overlay "${focusArea.name}" produced no meaningful expansion`);
+        return null;
+      }
+
+      const extQuery = mdq(cached).query('section1(~"Extended Research")');
+      let updated: string;
+      if (extQuery.count() > 0) {
+        const existing = extQuery.text().trimEnd();
+        updated = extQuery.replace(`${existing}\n\n${sectionMarkdown}\n`);
+      } else {
+        updated = `${cached.trimEnd()}\n\n# Extended Research\n\n${sectionMarkdown}\n`;
+      }
+
+      saveResearch(pageStateHash, updated);
+      tag('substep').log(`Overlay research appended: ${focusArea.name}`);
+      return sectionMarkdown;
+    }
+
     private async _discoverExpandables(researchText: string): Promise<ExpandableElement[]> {
       const allElements = new Map<string, ExpandableElement>();
       for (const section of parseResearchSections(researchText)) {
@@ -314,8 +365,27 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
     private async _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null> {
       const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
 
+      let intro: string;
+      if (code) {
+        intro = `An action on "${description}" (\`${code}\`) revealed new UI content.`;
+      } else {
+        intro = `An overlay "${description}" appeared on the page.`;
+      }
+
+      let actionBlock = '';
+      if (code) {
+        actionBlock = dedent`
+          Action:
+
+          \`\`\`js
+          ${code}
+          \`\`\`
+
+        `;
+      }
+
       const prompt = dedent`
-        An action on "${description}" (\`${code}\`) revealed new UI content.
+        ${intro}
         Analyze the changes and produce a UI map section.
 
         ARIA changes:
@@ -329,13 +399,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
 
         ### <Short descriptive name>
 
-        Action:
-
-        \`\`\`js
-        ${code}
-        \`\`\`
-
-        <One sentence: what appeared — dropdown menu, modal, tab content, expanded panel, etc.>
+        ${actionBlock}<One sentence: what appeared — dropdown menu, modal, tab content, expanded panel, etc.>
 
         | Element | ARIA | CSS |
         |---------|------|-----|
@@ -409,4 +473,5 @@ interface ExpandableElement extends ResearchElement {
 
 export interface DeepAnalysisMethods {
   performDeepAnalysis(state: WebPageState, result: ResearchResult): Promise<void>;
+  researchOverlay(current: ActionResult, previous: ActionResult, pageStateHash: string): Promise<string | null>;
 }