explorbot 0.1.32-beta.1 → 0.2.1

package/src/ai/researcher/sections.ts

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import type { ActionResult } from '../../action-result.js';
+import type { ExplorbotConfig } from '../../config.ts';
 import { executionController } from '../../execution-controller.ts';
 import type Explorer from '../../explorer.ts';
 import type { StateManager } from '../../state-manager.js';
@@ -20,6 +21,7 @@ export function WithSections<T extends Constructor>(Base: T) {
     declare explorer: Explorer;
     declare provider: Provider;
     declare stateManager: StateManager;
+    declare config: ExplorbotConfig;
     declare actionResult: ActionResult | undefined;
 
     async researchBySections(): Promise<string> {
@@ -64,11 +66,11 @@ export function WithSections<T extends Constructor>(Base: T) {
     }
 
     private async _detectFocusCss(): Promise<string | null> {
-      const focusSections = (this.explorer.getConfig().ai?.agents?.researcher as any)?.focusSections as string[] | undefined;
+      const focusSections = (this.config.ai?.agents?.researcher as any)?.focusSections as string[] | undefined;
       if (!focusSections?.length) return null;
 
       for (const css of focusSections) {
-        const count = await this.explorer.playwrightLocatorCount((page: any) => page.locator(css)).catch(() => 0);
+        const count = await this.explorer.withPage((page) => page.locator(css).count()).catch(() => 0);
         if (count > 0) return css;
       }
       return null;
@@ -105,9 +107,13 @@ export function WithSections<T extends Constructor>(Base: T) {
         </section_format>
 
         <rules>
-        - Every element with eidx MUST appear in the table.
+        - List only elements physically inside this section's declared container.
+        - Do not copy global toolbar, navigation, list, or detail elements into this section unless they are descendants of this section container.
+        - Every element with eidx inside this section's container MUST appear in the table.
         - Every row needs CSS; ARIA may be "-" for icon-only buttons.
         - ARIA locator JSON uses keys "role" and "text" (NOT "name").
+        - Elements marked data-explorbot-hit="covered" or "offscreen" are not directly actionable; describe the covering or focused UI first.
+        - In split-pane pages, entity detail panels are active detail context; include close/back/pin controls in the detail panel section when present.
         </rules>
 
         ${generalLocatorRuleText}

package/src/ai/researcher.ts

@@ -1,24 +1,22 @@
-import { join } from 'node:path';
 import dedent from 'dedent';
 import { ActionResult } from '../action-result.js';
 import { setActivity } from '../activity.ts';
-import { ConfigParser, outputPath } from '../config.ts';
+import { ConfigParser, type ExplorbotConfig, outputPath } from '../config.ts';
 import { executionController } from '../execution-controller.ts';
 import type { ExperienceTracker } from '../experience-tracker.ts';
 import type Explorer from '../explorer.ts';
-import type { KnowledgeTracker } from '../knowledge-tracker.ts';
 import { Observability } from '../observability.ts';
 import type { StateManager } from '../state-manager.js';
 import { WebPageState } from '../state-manager.js';
 import { Stats } from '../stats.ts';
 import { diffAriaSnapshots } from '../utils/aria.ts';
 import { ErrorPageError, detectPageCondition } from '../utils/error-page.ts';
-import { HooksRunner } from '../utils/hooks-runner.ts';
 import { isBodyEmpty } from '../utils/html.ts';
-import { createDebug, pluralize, tag } from '../utils/logger.js';
+import { createDebug, tag } from '../utils/logger.js';
 import { mdq } from '../utils/markdown-query.ts';
 import { RulesLoader } from '../utils/rules-loader.ts';
-import type { Agent } from './agent.js';
+import { annotatePageElements } from '../utils/web-annotate.ts';
+import type { Agent, AgentDeps } from './agent.js';
 import type { Navigator } from './navigator.ts';
 import { ContextLengthError, type Provider } from './provider.js';
 import { findSimilarResearch, getCachedResearch, saveResearch } from './researcher/cache.ts';
@@ -56,20 +54,16 @@ export class Researcher extends ResearcherBase implements Agent {
   declare explorer: Explorer;
   declare provider: Provider;
   declare stateManager: StateManager;
+  declare config: ExplorbotConfig;
   private experienceTracker!: ExperienceTracker;
   private hasScreenshotToAnalyze = false;
   declare actionResult: ActionResult | undefined;
-  private hooksRunner!: HooksRunner;
 
-  constructor(explorer: Explorer, provider: Provider) {
-    super();
-    this.explorer = explorer;
-    this.provider = provider;
-    this.stateManager = explorer.getStateManager();
-    this.experienceTracker = this.stateManager.getExperienceTracker();
-    this.hooksRunner = new HooksRunner(explorer, explorer.getConfig());
+  constructor(deps: AgentDeps) {
+    super(deps);
+    this.experienceTracker = deps.stateManager.getExperienceTracker();
 
-    const ai = explorer.getConfig().ai;
+    const ai = deps.config.ai;
     if (ai) {
       ai.agents ??= {};
       ai.agents.researcher ??= {};
@@ -81,18 +75,6 @@ export class Researcher extends ResearcherBase implements Agent {
     throw new Error('not implemented');
   }
 
-  protected getExperienceTracker(): ExperienceTracker {
-    return this.experienceTracker;
-  }
-
-  protected getKnowledgeTracker(): KnowledgeTracker {
-    return this.explorer.getKnowledgeTracker();
-  }
-
-  protected getProvider(): Provider {
-    return this.provider;
-  }
-
   static getCachedResearch(state: WebPageState): string {
     return getCachedResearch(state.hash || '');
   }
@@ -111,7 +93,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
   async research(state: WebPageState, opts: { screenshot?: boolean; force?: boolean; deep?: boolean; data?: boolean; fix?: boolean; _retriesLeft?: number } = {}): Promise<string> {
     const { screenshot = false, force = false, deep = false, data = false, fix = true } = opts;
-    const maxRetries = (this.explorer.getConfig().ai?.agents?.researcher as any)?.retries ?? 2;
+    const maxRetries = (this.config.ai?.agents?.researcher as any)?.retries ?? 2;
     let retriesLeft = opts._retriesLeft ?? maxRetries;
     this.actionResult = ActionResult.fromState(state);
     const stateHash = state.hash || this.actionResult.getStateHash();
@@ -135,9 +117,9 @@ export class Researcher extends ResearcherBase implements Agent {
       await this.ensureNavigated(displayUrl, screenshot && this.provider.hasVision());
       await this.hooksRunner.runBeforeHook('researcher', state.url);
 
-      const annotatedElements = await this.explorer.annotateElements();
+      const { elements: annotatedElements } = await this.explorer.withPage(annotatePageElements);
       debugLog(`Annotated ${annotatedElements.length} interactive elements with eidx`);
-      this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot && this.provider.hasVision() });
+      this.actionResult = await this.explorer.capture({ screenshot: screenshot && this.provider.hasVision() });
 
       const condition = detectPageCondition(this.actionResult!);
       if (condition === 'error') {
@@ -209,11 +191,10 @@ export class Researcher extends ResearcherBase implements Agent {
       }
 
       if (!interrupted()) {
-        const containerLocs = result.containerLocators;
-        await this.testLocators(containerLocs);
-        const brokenContainers = containerLocs.filter((l) => l.valid === false);
-        if (containerLocs.length > 0 && brokenContainers.length === containerLocs.length && retriesLeft > 0) {
-          tag('warning').log(`All ${containerLocs.length} containers broken, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
+        const brokenContainers = await this.resolveContainers(result);
+        const containerCount = result.containers.length;
+        if (containerCount > 0 && brokenContainers.length === containerCount && retriesLeft > 0) {
+          tag('warning').log(`All ${containerCount} containers broken, retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
           await new Promise((r) => setTimeout(r, 2000));
           return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 } as any);
         }
@@ -227,14 +208,6 @@ export class Researcher extends ResearcherBase implements Agent {
 
         const toTest = result.locators.filter((l) => l.valid === null);
         await this.testLocators(toTest);
-
-        const brokenCount = result.locators.filter((l) => l.valid === false).length;
-        const brokenRatio = result.locators.length > 0 ? brokenCount / result.locators.length : 0;
-        if (brokenRatio > 0.8 && retriesLeft > 0) {
-          tag('warning').log(`${Math.round(brokenRatio * 100)}% locators broken, waiting 3s and retrying research (${maxRetries - retriesLeft + 1}/${maxRetries})...`);
-          await new Promise((r) => setTimeout(r, 3000));
-          return this.research(state, { ...opts, force: true, _retriesLeft: retriesLeft - 1 } as any);
-        }
       }
 
       // Stage 3: Fix broken sections via AI conversation continuation
@@ -246,7 +219,7 @@ export class Researcher extends ResearcherBase implements Agent {
       // Must run BEFORE visuallyAnnotateContainers — annotation overlays inject z-index 99998+ which would pollute the scoring.
       if (!interrupted() && this.hasScreenshotToAnalyze) {
         const sections = parseResearchSections(result.text);
-        const focused = await this.explorer.runWithBrowserRecovery('detectFocusedSection', () => detectFocusedSection(this.explorer.playwrightHelper.page, sections));
+        const focused = await this.explorer.withPage((page) => detectFocusedSection(page, sections));
         if (focused) markSectionAsFocused(result, focused);
       }
 
@@ -255,11 +228,11 @@ export class Researcher extends ResearcherBase implements Agent {
         const validContainers = extractValidContainers(result.text);
         result.parseLocators();
         const freshContainerLocs = result.containerLocators;
-        await this.testLocators(freshContainerLocs);
+        await this.testLocators(freshContainerLocs, { scope: true });
         const freshBroken = freshContainerLocs.filter((l) => l.valid === false).map((l) => l.locator);
         const containers = validContainers.filter((c) => !freshBroken.includes(c.css));
         await this.visuallyAnnotateElements({ containers });
-        this.actionResult = await this.explorer.capturePageWithScreenshot();
+        this.actionResult = await this.explorer.capture({ screenshot: true });
         const visualResult = await this.analyzeScreenshotForVisualProps();
         if (visualResult.elements.size > 0) {
           await this.mergeVisualData(result, visualResult.elements);
@@ -315,11 +288,9 @@ export class Researcher extends ResearcherBase implements Agent {
         researchFile = saveResearch(stateHash, result.text, combinedHtml);
       }
 
-      const summaryMatch = result.text.match(/## Summary\s*\n+([\s\S]*?)(?=\n##|$)/i);
-      if (summaryMatch) {
-        const summaryLine = summaryMatch[1].trim().split('\n')[0].trim().slice(0, 200);
-        if (summaryLine) this.experienceTracker.updateSummary(this.actionResult!, summaryLine);
-      }
+      const summaryText = mdq(result.text).query('section2(/^summary/)').query('paragraph[0]').text().trim();
+      const summaryLine = summaryText.split('\n')[0]?.trim().slice(0, 200);
+      if (summaryLine) this.experienceTracker.updateSummary(this.actionResult!, summaryLine);
 
       tag('multiline').log(formatResearchSummary(result.text, { visionUsed: this.hasScreenshotToAnalyze }));
       tag('success').log('Research complete');
@@ -337,8 +308,7 @@ export class Researcher extends ResearcherBase implements Agent {
   private async ensureNavigated(url: string, screenshot?: boolean): Promise<void> {
     if (!this.actionResult) {
       debugLog('No action result, navigating to URL');
-      await this.explorer.visit(url);
-      this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot });
+      this.actionResult = await this.explorer.visit(url, { screenshot });
       return;
     }
 
@@ -348,7 +318,7 @@ export class Researcher extends ResearcherBase implements Agent {
 
     if (!isEmpty && isOnCurrentState) {
       if ((!this.actionResult.screenshot && screenshot) || !this.actionResult.ariaSnapshot) {
-        this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot });
+        this.actionResult = await this.explorer.capture({ screenshot });
       }
       return;
     }
@@ -356,8 +326,7 @@ export class Researcher extends ResearcherBase implements Agent {
     if (isEmpty && isOnCurrentState) {
       debugLog('HTML body empty on current URL, waiting for content');
       tag('step').log('Page body is empty, waiting for content...');
-      await this.explorer.visit(url);
-      this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot ?? false });
+      this.actionResult = await this.explorer.visit(url, { screenshot: screenshot ?? false });
       await this.waitUntilSettled(screenshot ?? false);
       return;
     }
@@ -365,22 +334,21 @@ export class Researcher extends ResearcherBase implements Agent {
     debugLog('Not on current state, navigating to URL');
     tag('step').log('Navigating to URL...');
 
-    await this.explorer.visit(url);
-    this.actionResult = await this.explorer.capturePageState({ includeScreenshot: screenshot ?? false });
+    this.actionResult = await this.explorer.visit(url, { screenshot: screenshot ?? false });
   }
 
   private async waitUntilSettled(screenshot: boolean): Promise<boolean> {
-    const errorPageTimeout = (this.explorer.getConfig().ai?.agents?.researcher as any)?.errorPageTimeout ?? 10;
+    const errorPageTimeout = (this.config.ai?.agents?.researcher as any)?.errorPageTimeout ?? 10;
     if (errorPageTimeout <= 0) return false;
 
     const includeScreenshot = screenshot && this.provider.hasVision();
 
     try {
-      await this.explorer.runWithBrowserRecovery('waitUntilSettled', () => this.explorer.playwrightHelper.page?.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 }));
+      await this.explorer.withPage((page) => page.waitForLoadState('networkidle', { timeout: errorPageTimeout * 1000 }));
     } catch {}
 
-    await this.explorer.annotateElements();
-    this.actionResult = await this.explorer.capturePageState({ includeScreenshot });
+    await this.explorer.withPage(annotatePageElements);
+    this.actionResult = await this.explorer.capture({ screenshot: includeScreenshot });
 
     let condition = detectPageCondition(this.actionResult!);
     if (condition === 'error') {
@@ -390,8 +358,8 @@ export class Researcher extends ResearcherBase implements Agent {
 
     for (let i = 0; i < 3; i++) {
       await new Promise((r) => setTimeout(r, 1000));
-      await this.explorer.annotateElements();
-      this.actionResult = await this.explorer.capturePageState({ includeScreenshot });
+      await this.explorer.withPage(annotatePageElements);
+      this.actionResult = await this.explorer.capture({ screenshot: includeScreenshot });
       condition = detectPageCondition(this.actionResult!);
       if (condition === 'error') {
         throw new ErrorPageError(this.actionResult!.url, this.actionResult!.title, this.actionResult!.httpStatus);
@@ -403,7 +371,7 @@ export class Researcher extends ResearcherBase implements Agent {
   }
 
   private getConfiguredSections(): Record<string, string> {
-    const configSections = (this.explorer.getConfig().ai?.agents?.researcher as any)?.sections as string[] | undefined;
+    const configSections = (this.config.ai?.agents?.researcher as any)?.sections as string[] | undefined;
     if (!configSections?.length) return POSSIBLE_SECTIONS;
     const filtered: Record<string, string> = {};
     for (const key of configSections) {
@@ -428,7 +396,10 @@ export class Researcher extends ResearcherBase implements Agent {
       - Research all menus and navigational areas.
       - Ignore decorative sidebars, footer-only links, and external links.
       - Detect layout patterns: list/detail split, 2-pane, or 3-pane layouts.
-      - Every element with an eidx attribute MUST appear in the UI map — describe icon-only buttons by their visual role.
+      - In split-pane layouts, keep global toolbar, list pane, and detail pane as separate sections. Do not copy toolbar/list elements into the detail section unless they are physically inside that detail container.
+      - If the URL or page state opens an entity detail panel, describe that panel as the active detail context and include its close/back/pin controls when present.
+      - If an element has data-explorbot-hit="covered" or "offscreen", do not present it as directly actionable. Prefer the overlay, drawer, dialog, or focused section covering it, and mention what must be dismissed or revealed first.
+      - Every element with an eidx attribute MUST appear in exactly one matching UI map section — describe icon-only buttons by their visual role.
       - Every UI map row needs a CSS selector; ARIA may be "-" for icon-only buttons, CSS must never be "-".
       - ARIA locator JSON uses keys "role" and "text" (NOT "name").
       - Mark elements with likely hover interactions (title, aria-describedby, menu items with submenus) as "(hover)".
@@ -445,6 +416,7 @@ export class Researcher extends ResearcherBase implements Agent {
         .join('\n')}
 
       - Sections can overlap; prefer more detailed sections over broader ones.
+      - Section tables must list only elements physically inside the declared container. If a control belongs to a global toolbar, list it only in the toolbar section.
       - Never name a section "Focus" or "Focused" — use what it contains (Detail, Modal, Form, Content, List).
       - Omit sections that are not present or not relevant.
       - Each section needs a container CSS locator; UI map CSS locators are relative to it.
@@ -466,23 +438,7 @@ export class Researcher extends ResearcherBase implements Agent {
     if (!this.actionResult) throw new Error('actionResult is not set');
 
     const html = await this.actionResult.combinedHtml();
-    const knowledgeFiles = this.stateManager.getRelevantKnowledge();
-
-    let knowledge = '';
-    if (knowledgeFiles.length > 0) {
-      const knowledgeContent = knowledgeFiles
-        .map((k) => k.content)
-        .filter((k) => !!k)
-        .join('\n\n');
-
-      tag('operation').log(`Found ${knowledgeFiles.length} relevant knowledge ${pluralize(knowledgeFiles.length, 'file')} for: ${this.actionResult.url}`);
-      knowledge = `
-        <hint>
-        Here is relevant knowledge for this page:
-
-        ${knowledgeContent}
-        </hint>`;
-    }
+    const knowledge = this.knowledgeTracker.renderRelevantKnowledge(this.actionResult);
 
     const ariaSnapshot = this.actionResult.getCompactARIA();
 
@@ -540,39 +496,6 @@ export class Researcher extends ResearcherBase implements Agent {
     `;
   }
 
-  async textContent(state: WebPageState): Promise<string> {
-    const actionResult = ActionResult.fromState(state);
-    const html = await actionResult.combinedHtml();
-
-    const prompt = dedent`
-      Transform into markdown.
-      Identify headers, footers, asides, special application parts and main contant.
-      Content should be in markdown format. If it is content: tables must be tables, lists must be lists.
-      Navigation elements should be represented as standalone blocks after the content.
-      Do not summarize content, just transform it into markdown.
-      It is important to list all the content text
-      If it is link it must be linked
-      You can summarize footers/navigation/aside elements.
-      But main conteint should be kept as text and formatted as markdown based on its current markup.
-      Links to external web sites should be avoided in output.
-
-      Break down into sections:
-
-      ## Content Area
-
-      ## Navigation Area
-
-      <page_html>
-      ${html}
-      </page_html>
-    `;
-
-    const model = this.provider.getModelForAgent('researcher');
-    const r = await this.provider.chat([{ role: 'user', content: prompt }], model, { agentName: 'researcher', telemetryFunctionId: 'researcher.textContent' });
-
-    return r.text;
-  }
-
   private getScreenshotFromState(state: WebPageState): { actionResult: ActionResult; image: Buffer } | null {
     const actionResult = ActionResult.fromState(state);
     const image = actionResult.screenshot;
@@ -776,9 +699,9 @@ export class Researcher extends ResearcherBase implements Agent {
   async cancelInUi() {
     const beforeAria = this.stateManager.getCurrentState()?.ariaSnapshot || null;
 
-    await this.explorer.executeAction('I.clickXY(0, 0)');
-    if (diffAriaSnapshots(beforeAria, this.stateManager.getCurrentState()?.ariaSnapshot || null)) return;
+    await this.explorer.action().execute('I.clickXY(0, 0)');
+    if (diffAriaSnapshots(beforeAria, this.stateManager.getCurrentState()?.ariaSnapshot || null).text) return;
 
-    await this.explorer.executeAction(`I.pressKey('Escape')`);
+    await this.explorer.action().execute(`I.pressKey('Escape')`);
   }
 }

package/src/ai/rules.ts

@@ -2,7 +2,7 @@ import dedent from 'dedent';
 
 export const recommendedCodeceptCommands = ['I.click', 'I.type', 'I.fillField', 'I.see', 'I.seeElement'] as const;
 
-export const locatorRule = dedent`
+const locatorPriorityRule = dedent`
   <locator_priority>
   Use the following priority when selecting locators:
 
@@ -19,10 +19,12 @@ export const locatorRule = dedent`
      Example: '#login-btn', '[data-testid="submit"]', 'form#login input[name="email"]'
 
   4. XPath (last resort) - for complex hierarchy or when CSS can't express the path
-     Always start with //, never use positional indices like [1], [2]
+     Always start with //. Avoid positional indices like [1], [2] except as a last-resort disambiguator
      Example: '//form[@id="login"]//input[@name="email"]'
   </locator_priority>
+`;
 
+const contextSimplificationRule = dedent`
   <context_simplification>
   When container is available from UI map sections:
   - Text + container is simplest and PREFERRED: I.click('Save', '.modal')
@@ -30,7 +32,9 @@ export const locatorRule = dedent`
   - ALWAYS use context parameter unless locator is XPath or unique ID
   - No need for complex ARIA when container narrows scope sufficiently
   </context_simplification>
+`;
 
+const locatorStrategyRule = dedent`
   <disambiguation>
   When multiple elements could match the request, select based on intent:
   1. Match the context of recent actions - if filling a form, use elements in that same form
@@ -48,8 +52,9 @@ export const locatorRule = dedent`
   - Use aria-label value if present: { "role": "button", "text": "Close" } (from aria-label="Close")
   - Use title attribute if present: { "role": "button", "text": "Settings" } (from title="Settings")
   - If no accessible name exists, mark ARIA as "-" and use CSS/XPath:
-    * CSS: use partial href a[href*="settings"] or SVG icon class a:has(svg.md-icon-cog)
-    * XPath: use contains(@href,"settings") or SVG class //a[.//svg[contains(@class,"md-icon-cog")]]
+    * CSS: use partial href a[href*="settings"] or SVG icon class a:has(svg.icon-settings)
+    * XPath: use contains(@href,"settings") or SVG class //a[.//svg[contains(@class,"icon-settings")]]
+  - In inline create/edit rows, confirmation can be an icon-only control near the edited field instead of a text Save button. Anchor the locator to the same row/form as the field and target the adjacent confirm icon/control.
   - NEVER use empty text: { "role": "button", "text": "" } is INVALID and useless
 
   <good_aria_locator_example>
@@ -80,9 +85,9 @@ export const locatorRule = dedent`
   - Vue: data-v-* attributes
   Avoid locators that seem to have generated ids or class names (long random numbers, uuids, hashes, etc)
   Prefer text or ARIA locators over href-based ones. But for icon-only links with no accessible name, use:
-  - Partial href match: a[href*="settings"], a[href*="requirements"] (use path segments, not full URLs)
-  - SVG icon class: a:has(svg.md-icon-cog), button:has(svg.md-icon-plus) (target the SVG class inside the link/button)
-  Avoid full absolute href like a[href="/projects/imr_manual12/settings"] — use generic path segments instead
+  - Partial href match: a[href*="settings"], a[href*="reports"] (use path segments, not full URLs)
+  - SVG icon class: a:has(svg.icon-settings), button:has(svg.icon-add) (target the SVG class inside the link/button)
+  Avoid full absolute href like a[href="/items/12345/settings"] — use generic path segments instead
   Avoid CSS framework utility classes as containers (Tailwind: flex, grid, space-x-*, justify-*, items-*, w-*, h-*, p-*, m-*, etc; Bootstrap: col-*, row, d-flex, etc)
   Prefer semantic class names, roles, data attributes, or element hierarchy for containers
 
@@ -94,7 +99,7 @@ export const locatorRule = dedent`
 
   <xpath_rules>
   XPath locators must start with //.
-  XPath should use positional indices [1], [2], [3] and contains(., "text") for disambiguation.
+  XPath may use positional indices [1], [2] and contains(., "text") as a last-resort disambiguator when attribute/text strategies are exhausted.
   XPath should rely less on class names — prefer element hierarchy, position, and text content.
   XPath and CSS MUST provide different strategies for finding the same element.
   </xpath_rules>
@@ -106,22 +111,26 @@ export const locatorRule = dedent`
     '#content-top #user_name'
     '#content-top form input[name="name"]'
     'a.nav-item[href*="settings"]' // icon-only link matched by partial href
-    'a.nav-item:has(svg.md-icon-cog)' // icon-only link matched by SVG icon class
+    'a.nav-item:has(svg.icon-settings)' // icon-only link matched by SVG icon class
     '//nav//a[contains(@href,"settings")]' // XPath for icon-only nav link
   </good locator example>
 
   <bad locator example>
-    'a.filter-tab:nth-of-type(1)' // WRONG: positional in CSS, use :has-text("Manual") instead
-    '//a[contains(@class,"filter-tab") and contains(@class,"active")]' // WRONG: XPath repeats CSS approach, use positional //a[contains(@class,"filter-tab")][1]
+    'a.filter-tab:nth-of-type(1)' // WRONG: positional in CSS, use :has-text("Active") instead
+    '//a[contains(@class,"filter-tab") and contains(@class,"active")]' // WRONG: XPath repeats CSS approach, provide a different strategy e.g. //a[contains(@class,"filter-tab")][1]
     '//table//tbody/tr[1]//button[contains(@onclick,'fn()')]' // onclick is not semantic attribute
     '//html/body/vue-button-123' // vue-framework specific locator
-    'link "New Template"'  // WRONG: malformed string, use {"role":"link","text":"New Template"}
-    'a[href="/projects/imr_manual12/settings"]' // WRONG: full absolute href, use a[href*="settings"] instead
+    'link "New Item"'  // WRONG: malformed string, use {"role":"link","text":"New Item"}
+    'a[href="/items/12345/settings"]' // WRONG: full absolute href, use a[href*="settings"] instead
   </bad locator example>
 
   HTML locators must be valid JS strings
 `;
 
+export const locatorRule = [locatorPriorityRule, contextSimplificationRule, locatorStrategyRule].join('\n\n');
+
+export const drillLocatorRule = [locatorPriorityRule, locatorStrategyRule].join('\n\n');
+
 export const fileUploadRule = dedent`
   <file_upload>
   Explorbot CAN upload files using I.attachFile() via form() tool.
@@ -307,6 +316,7 @@ export const actionRule = dedent`
   Use context parameter (second argument) to narrow click area when:
   - The same text/button appears multiple times on page
   - You need to click inside a specific form, modal, or section
+  - You need an icon-only confirm/save control next to a field in an inline create/edit row
   Context should be a CSS selector pointing to a unique container.
 
   <example>
@@ -319,6 +329,7 @@ export const actionRule = dedent`
   </example>
 
   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.
 

package/src/ai/session-analyst.ts

@@ -49,6 +49,9 @@ export class SessionAnalyst implements Agent {
       ## Severity (defects only)
       [High] blocks a core flow · [Medium] degrades a flow but workaround exists · [Low] cosmetic / edge case
 
+      ## Naming tests
+      Reference every test by its full label wrapped in backticks: \`\`\`ET-<number> <test title>\`\`\` — the \`ref\` and \`scenario\` from its \`<test>\` block. Backticks only, never bold. Never write a bare \`#2\`.
+
       ## Format
 
       # Session Analysis
@@ -60,22 +63,22 @@ export class SessionAnalyst implements Agent {
       - Features: <capabilities>
 
       ## What works
-      - **<feature>** — #2, #7, #8
+      - **<feature>** — \`ET-2 <title>\`, \`ET-7 <title>\`
 
       ## Defects
 
       ### [Medium] <plain-English bug title>
-      Affects: #3, #5
+      Affects: \`ET-3 <title>\`, \`ET-5 <title>\`
       Reproduce:
         1. <concrete UI step>
         2. <next>
       Evidence: <one short observation>
 
       ## UX issues
-      - **<feature>** — <what's confusing> (#7)
+      - **<feature>** — <what's confusing> (\`ET-7 <title>\`)
 
       ## Execution Issues
-      - **#2 <scenario>** — <≤10 words, what was unreliable>
+      - \`ET-2 <title>\` — <≤10 words, what was unreliable>
 
       ## Brevity rules
 
@@ -143,7 +146,7 @@ export class SessionAnalyst implements Agent {
       : 'verification_status: none';
 
     return dedent`
-      <test ref="#${ref}">
+      <test ref="ET-${ref}">
       url: ${test.startUrl || '/'}
       scenario: ${test.scenario}
       result: ${test.result || 'unknown'}