explorbot 0.4.3 → 0.4.5

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

@@ -0,0 +1,63 @@
+import dedent from 'dedent';
+export const helpContract = dedent `
+  Prima drives the browser opened by playwright-cli.
+
+    playwright-cli open <url>    starts the session
+    prima <command> ...          drives it
+    playwright-cli close         ends it
+
+  One call runs a whole job:
+
+    prima check "a workflow can be created and appears in the list" --expected "the new workflow is listed"
+    prima do "open the account menu" "choose the settings entry" "switch the theme to dark" "check it took effect"
+    prima pw "({ page }) => page.click('[data-test=submit]')"
+
+  Only research maps a page. Other commands read the accessibility tree; a cached
+  research map joins when present. On large or unclear pages, run prima research first.
+  Without a usable AI model only pw works; otherwise use playwright-cli.
+  DEBUG='explorbot:*' in front of a command logs everything it does.
+`;
+export const checkHelp = dedent `
+  check states the outcome, not the clicks; it finds the path itself. It stays
+  on the current page and never reloads it, so an open dialog survives.
+  --expected  one required outcome, repeatable for several. Without it the
+              scenario text is the outcome. Each returns under
+              ### Expected outcomes as PASSED, FAILED, CONTRADICTION or not verified.
+              "not verified" means never checked, not false.
+  Proof is a full-page screenshot: what a user sees counts, the log only shows actions.
+  CONTRADICTION means screenshot and log disagree; judge the html, aria and
+  screenshot under ### Artifacts yourself.
+  ok is false when any outcome FAILED or CONTRADICTED, or the run could not finish,
+  reported as such rather than as an app failure.
+  Side issues found on the way go under ### Answer, not as step failures.
+`;
+export const doHelp = dedent `
+  ### Steps marks each instruction ok, FAIL or ??. ?? means it ran but the run ended
+  without confirming it - read the steps above. Only FAIL fails the command.
+  Nothing runs past the last instruction. Batch the whole sequence in one call;
+  that is what keeps this tier cheap.
+`;
+export const askHelp = dedent `
+  Answers from a page screenshot, or from its structure with --no-vision.
+`;
+export const verifyHelp = dedent `
+  Reports each expressible assertion as PASSED or FAILED with its playwright form;
+  no overall verdict, read the lines. "none ran" means unexpressible, not false.
+`;
+export const researchHelp = dedent `
+  The map is saved per page state and joins later commands there, so one research run pays for all that follow it.
+`;
+export const statusHelp = dedent `
+  Reads recorded files, so it needs no browser and outlives the session.
+  The hash is matched across all recorded sites. ### Artifacts lists every kept
+  file: aria, html, screenshot and network log when captured, plus per-step captures of a do run.
+`;
+export const reportHelp = dedent `
+  Built from the command log, so it needs no browser and outlives the session.
+  Reports the latest session unless --pw-session names another.
+`;
+export const sessionHelp = dedent `
+  Parallel jobs need one --instance each. --session is ignored when attached,
+  since the attached session keeps its own. --framework is parsed but inactive;
+  reported code is CodeceptJS either way.
+`;

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

@@ -18,19 +18,19 @@ 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";
 import { mdq } from "../../../src/utils/markdown-query.js";
 import { safeFilename } from "../../../src/utils/strings.js";
-import { STATUS_FILE, readArtifacts, writeArtifacts } from "./envelope.js";
+import { STATUS_FILE, STEP_FILES, readArtifacts, writeArtifacts } from "./envelope.js";
 import { isFunctionExpression, takePwValue, toCodeceptWrapper } from "./pw-parser.js";
 import { readDescriptors, selectDescriptor } from "./pw-registry.js";
 import { latestSessionFile, readSession, recordCommand, sessionFile, sessionsDir } from "./session-log.js";
-const TESTER_ONLY_TOOLS = ['learnExperience', 'askUser'];
+const WITHHELD_TOOLS = ['learnExperience', 'askUser', 'research'];
 const ITERATIONS_PER_INSTRUCTION = 2;
 const MAX_INSTRUCTION_ITERATIONS = 24;
-const DEFAULT_RESEARCH_AFTER_VISITS = 3;
 const CONTEXT_HTML_CAP = 6000;
 const MAX_TOOL_ROUNDTRIPS = 5;
 const AI_AGENT_NAME = 'prima';
@@ -68,7 +68,6 @@ export class Prima {
     server = null;
     attached = null;
     session = null;
-    artifacts;
     constructor(options = {}) {
         this.options = options;
         this.bot = new ExplorBot({
@@ -99,6 +98,7 @@ export class Prima {
         const config = await this.loadConfig();
         await this.resolveBrowser(config, discovery);
         await this.bot.start();
+        this.bot.agentResearcher().disable();
         if (!this.options.url)
             return;
         if (this.bot.getCurrentState())
@@ -296,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
@@ -382,9 +388,11 @@ export class Prima {
         const guard = await this.aiGuard(command);
         if (guard)
             return guard;
+        const researcher = this.bot.agentResearcher();
+        researcher.enable();
         const previousState = this.bot.stateManager().getCurrentState();
         const result = await this.capturedResult(previousState);
-        const uiMap = await this.bot.agentResearcher().research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
+        const uiMap = await researcher.research(result, { screenshot: true, data: opts.data, deep: opts.deep, force: opts.fresh });
         return this.reportEnvelope(command, result, previousState, { research: dropVolatileColumns(uiMap) });
     }
     async go(target) {
@@ -768,7 +776,7 @@ export class Prima {
         if (!researcher || !navigator)
             return {};
         const tools = createAgentTools({ ...deps, researcher, navigator, withExperience: false });
-        for (const name of TESTER_ONLY_TOOLS)
+        for (const name of WITHHELD_TOOLS)
             delete tools[name];
         return tools;
     }
@@ -823,14 +831,15 @@ export class Prima {
     }
     async pageContext(result) {
         const experience = this.bot.experienceTracker?.()?.renderExperienceTocFor?.(result) || '';
-        const map = this.researchMap(result);
+        const map = getPreviousResearch(result.baseHash);
+        let uiMap = '';
         if (map) {
-            return dedent `
-        <page_ui_map url="${result.url}" title="${result.title}">
+            uiMap = dedent `
+        <page_ui_map>
+        A map of this page recorded by an earlier research run. It names parts the accessibility
+        tree does not, and can be out of date — the tree is what the page holds now.
         ${map}
         </page_ui_map>
-
-        ${experience}
       `;
         }
         return dedent `
@@ -838,20 +847,11 @@ export class Prima {
       ${compactAriaSnapshot(await this.refAriaSnapshot(result), true, (value) => this.offloadValue(value))}
       </page>
 
+      ${uiMap}
+
       ${experience}
     `;
     }
-    researchMap(result) {
-        if (this.bot.stateManager().getVisitCount(result.url) < this.researchAfterVisits())
-            return '';
-        return getPreviousResearch(result.getStateHash());
-    }
-    researchAfterVisits() {
-        const configured = this.bot.getConfig?.()?.ai?.agents?.prima?.researchAfterVisits;
-        if (typeof configured === 'number')
-            return configured;
-        return DEFAULT_RESEARCH_AFTER_VISITS;
-    }
     offloadValue(value) {
         const dir = this.statusDir();
         const name = `value-${createHash('sha1').update(value).digest('hex').slice(0, 8)}.txt`;
@@ -865,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) {
@@ -923,16 +923,13 @@ export class Prima {
     }
     async successEnvelope(command, used, result, previousState) {
         const changes = await this.pageChanges(result, previousState, used[0]);
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             used,
             page: this.pageBlock(result, previousState),
             changes,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async failureEnvelope(command, error, previousState) {
@@ -940,29 +937,27 @@ export class Prima {
         const failure = { error: browserErrorMessage(error) };
         if (result.ariaSnapshot)
             failure.compactAria = compactAriaSnapshot(result.ariaSnapshot, true);
-        const status = await this.saveStatus(result);
         return {
             ok: false,
             command,
             page: this.pageBlock(result, previousState),
             failure,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
     async reportEnvelope(command, result, previousState, outcome) {
-        const status = await this.saveStatus(result);
         return {
             ok: true,
             command,
             page: this.pageBlock(result, previousState),
             ...outcome,
-            instance: await this.instanceInfo(),
-            status,
-            artifacts: this.artifacts,
+            ...(await this.envelopeTail(result)),
         };
     }
+    async envelopeTail(result) {
+        const { hash, artifacts } = await this.saveStatus(result);
+        return { instance: await this.instanceInfo(), status: hash, artifacts };
+    }
     async capturedResult(previousState, opts = {}) {
         const captured = await this.bot
             .getExplorer()
@@ -1026,9 +1021,9 @@ export class Prima {
     }
     async saveStatus(result) {
         const hash = this.statusHash();
-        await this.writeSnapshot(result);
+        const artifacts = await this.writeSnapshot(result);
         writeFileSync(path.join(this.statusDir(hash), STATUS_FILE), JSON.stringify({ page: this.pageBlock(result, null) }), 'utf-8');
-        return hash;
+        return { hash, artifacts };
     }
     async writeStepFiles(index, label, diff) {
         const state = this.bot.stateManager().getCurrentState();
@@ -1038,17 +1033,17 @@ export class Prima {
         mkdirSync(dir, { recursive: true });
         const stem = path.join(dir, `${index}-${safeFilename(label.slice(0, 60))}`);
         const result = ActionResult.fromState(state);
-        writeFileSync(`${stem}.aria.yaml`, result.ariaSnapshot ?? '', 'utf-8');
-        writeFileSync(`${stem}.html`, await result.combinedHtml(), 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.aria}`, result.ariaSnapshot ?? '', 'utf-8');
+        writeFileSync(`${stem}.${STEP_FILES.html}`, await result.combinedHtml(), 'utf-8');
         if (diff)
-            writeFileSync(`${stem}.diff.yaml`, diff, 'utf-8');
+            writeFileSync(`${stem}.${STEP_FILES.diff}`, diff, 'utf-8');
     }
     async writeSnapshot(result) {
-        this.artifacts = writeArtifacts(this.statusDir(), {
+        return writeArtifacts(this.statusDir(), {
             aria: result.ariaSnapshot,
             html: await result.combinedHtml(),
             screenshot: result.screenshot,
-            requests: this.bot.requestStore().getMadeRequests(),
+            requests: this.bot.requestStore().getCapturedRequests(),
         });
     }
     statusHash() {

package/dist/package.json

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

package/dist/src/action-result.d.ts

@@ -26,6 +26,7 @@ interface ActionResultData extends WebPageState {
     }>;
     ariaSnapshot?: string | null;
     ariaSnapshotFile?: string;
+    regionAria?: string | null;
     focusedElement?: FocusedElement | null;
     iframeURL?: string;
     links?: Link[];
@@ -84,6 +85,7 @@ export declare class ActionResult implements ActionResultData {
     links: Link[];
     verifications?: Record<string, boolean>;
     overlay: Region;
+    regionAria: string | null;
     _diffCache: {
         previousId: number | undefined;
         diff: Diff;
@@ -109,6 +111,7 @@ export declare class ActionResult implements ActionResultData {
     }): Promise<string>;
     textHtml(htmlConfig?: HtmlConfig): Promise<string>;
     getInteractiveARIA(): string;
+    getRegionARIA(): string;
     getCompactARIA(): string;
     normalizeHtmlConfig(htmlConfig?: HtmlConfig): HtmlConfig | undefined;
     static fromState(state: WebPageState): ActionResult;

package/dist/src/action-result.js

@@ -40,6 +40,7 @@ export class ActionResult {
     links = [];
     verifications;
     overlay = new Region();
+    regionAria = null;
     _diffCache = null;
     constructor(data) {
         this.id = data.id;
@@ -55,6 +56,7 @@ export class ActionResult {
         this.iframeURL = data.iframeURL;
         this.notes = data.notes ?? [];
         this.verifications = data.verifications;
+        this.regionAria = data.regionAria ?? null;
         // Set readonly properties
         if (data.screenshotFile !== undefined) {
             this.screenshotFile = data.screenshotFile;
@@ -238,6 +240,9 @@ export class ActionResult {
     getInteractiveARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, false);
     }
+    getRegionARIA() {
+        return compactAriaSnapshot(this.regionAria, false);
+    }
     getCompactARIA() {
         return compactAriaSnapshot(this.ariaSnapshot, true);
     }

package/dist/src/action.js

@@ -165,8 +165,19 @@ class Action {
                 focusedElement,
                 iframeURL: frame ? frame.url?.() || 'iframe' : undefined,
             });
-            if (!frame)
+            if (!frame) {
                 await this.detectRegion(result).catch((err) => debugLog('Region detection failed:', err.message));
+                const regionRoot = result.overlay.root;
+                if (result.overlay.isModal && regionRoot) {
+                    result.regionAria = await this.playwrightHelper.page
+                        .locator(regionRoot)
+                        .ariaSnapshot()
+                        .catch((err) => {
+                        debugLog('Region ARIA snapshot failed:', err.message);
+                        return null;
+                    });
+                }
+            }
             this.stateManager.updateState(result, codeBlock);
             return result;
         }

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

@@ -1,5 +1,5 @@
 import { ActionResult, type Diff } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.js';
+import { type ExplorbotConfig } from '../../config.js';
 import type Explorer from '../../explorer.js';
 import type { StateManager } from '../../state-manager.js';
 import { WebPageState } from '../../state-manager.js';

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

@@ -1,5 +1,6 @@
 import dedent from 'dedent';
 import { ActionResult } from '../../action-result.js';
+import { agentSettings } from "../../config.js";
 import { executionController } from "../../execution-controller.js";
 import { diffAriaSnapshots } from "../../utils/aria.js";
 import { extractCodeBlocks } from "../../utils/code-extractor.js";
@@ -16,7 +17,7 @@ export function WithDeepAnalysis(Base) {
         async performDeepAnalysis(state, result) {
             tag('info').log('Starting deep analysis of expandable elements');
             await this.navigateTo(state.fullUrl || state.url);
-            const maxClicks = this.config.ai?.agents?.researcher?.maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
+            const maxClicks = agentSettings(this.config, 'researcher').maxExpandableClicks ?? DEFAULT_MAX_EXPANDABLE_CLICKS;
             const expandedSections = [];
             const navigationLinks = [];
             let verifiedCodes = [];
@@ -62,6 +63,8 @@ export function WithDeepAnalysis(Base) {
             this._appendExtendedResearch(result, expandedSections, navigationLinks);
         }
         async researchOverlay(current, previous, pageStateHash) {
+            if (!this.isEnabled())
+                return null;
             const region = current.overlay;
             if (!region.isOpen || !region.name)
                 return null;

package/dist/src/ai/researcher/sections.d.ts

@@ -1,5 +1,5 @@
 import type { ActionResult } from '../../action-result.js';
-import type { ExplorbotConfig } from '../../config.js';
+import { type ExplorbotConfig } from '../../config.js';
 import type Explorer from '../../explorer.js';
 import type { StateManager } from '../../state-manager.js';
 import type { Provider } from '../provider.js';

package/dist/src/ai/researcher/sections.js

@@ -1,4 +1,5 @@
 import dedent from 'dedent';
+import { agentSettings } from "../../config.js";
 import { executionController } from "../../execution-controller.js";
 import { tag } from '../../utils/logger.js';
 import { RulesLoader } from "../../utils/rules-loader.js";
@@ -50,7 +51,7 @@ export function WithSections(Base) {
             return focused.text;
         }
         async _detectFocusCss() {
-            const focusSections = this.config.ai?.agents?.researcher?.focusSections;
+            const focusSections = agentSettings(this.config, 'researcher').focusSections;
             if (!focusSections?.length)
                 return null;
             for (const css of focusSections) {