explorbot 0.4.4 → 0.4.6

package/docs/superpowers/specs/2026-09-09-pagination-rule-design.md

@@ -0,0 +1,317 @@
+# Pagination rule: page numbers and infinite scroll
+
+## Problem
+
+Explorbot cannot reach list content that is not already loaded. A list shows a window onto
+a larger collection, and when the item under test is outside that window the tester concludes
+it is absent.
+
+Nothing in the repo scrolls anything. `<actions>` (`src/ai/rules.ts:307`) documents no scroll
+command, so the model has no way to know scrolling is available. Where scrolling is mentioned
+at all it is as a passing hint inside an unrelated suggestion string
+(`src/ai/tools.ts:875`, `:989`, `:1297`).
+
+Two strategies cover practically every paginated list on the web:
+
+- **Controls that replace the window** — next, previous, page numbers, load more.
+- **Appending on scroll** — new items are fetched and appended as the list is scrolled.
+
+The second is the hard one, because the scroller is often a container with its own scrollbar
+rather than the page. `I.scrollPageToBottom()` moves the window and leaves such a container
+untouched.
+
+## Approach
+
+Detection finds out which strategy a list uses; a rule tells the tester what to do about it,
+and is injected only when there is something to say. No new tool: the gesture already exists in
+CodeceptJS and is reachable through `form`.
+
+Splitting it that way is what keeps the rule short. The tester never has to discover anything
+at run time, and never carries guidance for a strategy this page does not use.
+
+### Why `I.scrollTo` is sufficient
+
+`Playwright.scrollTo(locator)` calls `el.scrollIntoViewIfNeeded()`
+(`node_modules/codeceptjs/lib/helper/Playwright.js:1679`), which scrolls **every scrollable
+ancestor** of the target. Pointing it at the last item currently in a list therefore scrolls
+that list's own scroller.
+
+Verified against Chromium on a page with both a scrollable `div` and a scrollable window:
+
+```
+before          {"box":0,    "win":0}
+scrollIntoView  {"box":2200, "win":1821}
+after cjs tail  {"box":2200, "win":1821}
+```
+
+Both scrollers moved. The `window.scrollBy` call CodeceptJS runs afterwards is a no-op: it
+passes one object to a two-positional-parameter function, so both deltas coerce to `NaN` and
+normalize to zero. Nothing needs to be worked around.
+
+The gesture is a single line beginning with `I.`, so it passes the `form` tool's line check
+(`src/ai/tools.ts:384`) and needs no new tool.
+
+### Signals already on the wire
+
+- **`pageDiff.ariaChanges` / `ariaChangeCount`** — `diffAriaSnapshots` (`src/utils/aria.ts:503`)
+  counts node summaries, so appended rows surface as counted additions.
+- **`pageDiff.requests`** — `Action.recordNetworkCall` (`src/action.ts:314`) captures same-origin
+  xhr/fetch as `{method, path, status}`, deduped. It stores `url.pathname` only, so the query
+  string is dropped: presence of a call, never a page number.
+
+## Design
+
+### A. Researcher determines each list's pagination strategy
+
+Four steps, cheapest first, stopping as soon as one answers. This is the escalation ladder from
+CLAUDE.md end to end: a table lookup, then AI judgment, then a probe whose result converts
+judgment back into a recorded fact.
+
+**0. Do the ARIA/HTML conventions name it? (deterministic, no research, no AI)**
+
+Some markup states the answer outright. These are spec-defined attributes and values, so this
+tier is a lookup, not a guess — and it is the only step that works when research has not run.
+
+| Marker | Means | Available in |
+|---|---|---|
+| `[aria-current="page"]` | current page of a pagination set | HTML only |
+| `a[rel="next"]`, `a[rel="prev"]` | sequential document relations | HTML only |
+| `[role="feed"]` | scrollable list that grows as it is scrolled | HTML and ARIA snapshot |
+| `[aria-setsize="-1"]` | total count unknown, so the set loads lazily | HTML only |
+
+The first two mean `controls`, the last two mean `infinite`.
+
+Verified against Chromium: `ariaSnapshot()` does **not** emit `aria-current`, so a link marked
+as the current page is indistinguishable from its neighbours in the ARIA path. Explorbot also
+dissolves `navigation` wrappers (`src/utils/aria.ts:46`, `:147`) and treats the role as
+template chrome (`src/utils/aria.ts:543`), so a `nav` labelled "Pagination" never reaches the
+model either. **These markers must be read from HTML.** `role="feed"` is the one exception —
+it survives as `- feed "…"` in the snapshot.
+
+Two constraints that keep this a lookup rather than a heuristic:
+
+- The value must be `aria-current="page"` exactly. `aria-current="true"` is what tabs and
+  breadcrumbs use and would over-match — confirmed in the same probe.
+- A `nav` whose `aria-label` reads "Pagination" is author prose, not closed grammar. It is not
+  part of this tier.
+
+**Absence proves nothing.** A pager built from plain buttons, and an infinite feed built from
+plain divs, carry none of these. That is what steps 1–3 are for.
+
+**1. Are there pagination controls? (AI, free)**
+
+Only asked when step 0 found nothing. Controls are named in open-ended ways — words, arrows,
+bare numbers — so this is AI judgment, not a pattern match. Researcher is already describing
+the section, so it costs nothing extra:
+a new `rules/researcher/pagination.md`, loaded alongside the existing three at
+`src/ai/researcher/sections.ts:81`, asks it to note when a section contains controls that move
+between pages of the same collection.
+
+If found, the section records `> Pagination: controls` and the remaining steps are skipped.
+
+**2. Can the section scroll at all? (deterministic gate)**
+
+Only asked when no controls were found. One `page.evaluate` per container:
+
+- `el.scrollHeight > el.clientHeight` → the container has its own scroller.
+- `el.getBoundingClientRect().bottom > innerHeight` → the list continues below the fold.
+- Neither → nothing more to do; no line recorded.
+
+This gate exists to keep step 3 from running on every short list.
+
+**3. Probe: does scrolling load more? (deterministic measurement)**
+
+Scroll the container to its end, wait for readiness (`waitForPageReadiness`,
+`src/utils/page-readiness.ts`), and compare. More descendant rows than before, or a same-origin
+xhr/fetch fired during the scroll, means the list appends. Record `> Pagination: infinite`.
+
+Then restore `scrollTop` to what it was, so screenshots, coordinates and later research see the
+page as they found it. Scroll position is not app state, so this needs none of the modal
+cleanup `_restorePageState` does in `deep-analysis.ts:453` — there is nothing to reuse there.
+
+**Recorded vocabulary:** `controls` or `infinite`, as a line in the section's container
+blockquote. Nothing is written when a list neither paginates nor grows, which is the common
+case and should stay silent.
+
+```
+> Container: '.semantic-container'
+> Pagination: infinite
+```
+
+**This line has a reader**, because section B injects the rule only when pagination was
+detected, and that decision is code. `extractPaginationFromBlockquote` joins
+`extractContainerFromBlockquote` (`src/ai/researcher/parser.ts:86`) and returns the recorded
+value or null.
+
+That makes `Pagination:` a closed vocabulary read deterministically by code, so the envelope
+checklist from CLAUDE.md applies and holds: read by code, scoped to a section of a state,
+optional with "absent" as the default, and written by one module.
+
+### A2. Where the code goes
+
+New `src/ai/researcher/pagination.ts` mixin, composed into `ResearcherBase`
+(`src/ai/researcher.ts:47`), owning steps 2 and 3. Step 1 is prompt text in
+`rules/researcher/pagination.md` and needs no code.
+
+It runs after `validateContainers` (`src/ai/researcher/locators.ts:268`), on containers that
+survived validation, so a probe never targets a selector already known to be broken.
+
+Not `deep-analysis.ts`: that mixin owns the same interact-measure-restore shape, but it is
+gated behind `deep` (`src/ai/researcher.ts:287`), and infinite scroll has to be detected on
+ordinary research runs too. It is also already 26k.
+
+Not `locators.ts`: that mixin owns locator validity, not list behaviour.
+
+**One writer for the blockquote.** `updateSectionContainer`
+(`src/ai/researcher/locators.ts:300`) currently owns that `blockquote[0]` replace. The
+pagination mixin must not write it independently. Extract the blockquote composition into one
+helper both call, so `Container:` and `Pagination:` are always emitted by the same code.
+
+A new `src/utils/pagination.ts` owns the two deterministic halves — the step 0 marker scan over
+HTML, and the in-page evaluate functions for steps 2 and 3, self-contained with no outer-scope
+references. One concern: how a list continues. `measureLayout` in `overlay.ts` is not reused:
+it is xpath-based and returns a modal-scoring `RegionLayout`, while sections carry CSS
+selectors and need neither.
+
+### B. The pagination rule, injected only when pagination was detected
+
+Not part of the static system message. A page with no list should not carry list guidance, and
+a page with page numbers should not be told how to scroll.
+
+**Seam:** `reinjectContextIfNeeded` (`src/ai/tester.ts:554`), which already injects per-state
+blocks conditionally — `focusedElementRule` when something is focused, an `<overlay>` block
+when a region is open. A `<pagination>` block joins them. Navigator gets the same block where
+it builds its own per-state context (`src/ai/navigator.ts:414`).
+
+**Condition:** the state shows pagination if step 0's markers are present in the current HTML,
+or `extractPaginationFromBlockquote` finds a recorded value for a section. Markers win when
+both are available, since they describe the page as it is now rather than as research left it.
+
+**Which text:** the strategy selects the fragment, so the model is never shown the other one.
+
+`paginationControlsRule`:
+
+```
+<pagination>
+This list pages through a larger collection. If what you need is not on screen,
+click next or the page number you need before concluding it is absent.
+</pagination>
+```
+
+`infiniteScrollRule`:
+
+```
+<pagination>
+This list grows as it is scrolled. If what you need is not on screen, scroll to
+the last item in the list — every scrollable ancestor of that item scrolls, so
+this reaches a list with its own scrollbar.
+
+New rows in the aria changes mean more arrived; a request with none means nothing
+was left. Stop on the first attempt that adds no rows: the end of a collection is
+an answer, not a failure.
+</pagination>
+```
+
+Both live in `src/ai/rules.ts` as exports. Not `rules/*.md`: those load per agent, and these
+have two consumers.
+
+**Reach narrows from the earlier draft.** Composing into `actionRule` would have reached
+Rerunner (`src/ai/rerunner.ts:450`) and Captain web-mode (`src/ai/captain/web-mode.ts:148`) too;
+conditional injection reaches only agents that build per-state context, which is Tester and
+Navigator. That is the cost of making it conditional, and it is the right trade: Rerunner heals
+known steps rather than traversing lists.
+
+Constraints both fragments keep: general phrasing, no selectors, no site names, no example
+taken from a debug session, one to three lines per bullet.
+
+### C. `actionRule` documents the gesture
+
+`<actions>` (`src/ai/rules.ts:307`) gains a scroll entry covering `I.scrollTo(<locator>)` —
+stating that it scrolls every scrollable ancestor of the target — and
+`I.scrollPageToBottom()` for the window. The `form` tool description
+(`src/ai/tools.ts:354`) gains "reach items further down a list" as a use case, since it
+currently reads as a typing tool.
+
+### D. Tool output that contradicts the rule
+
+Both are wrong reporting on existing tools, not new behaviour.
+
+**`src/ai/tools.ts:415`** — `hasObservablePageChange` (`src/ai/tools.ts:1236`) ignores
+`pageDiff.requests`. A scroll that fires a fetch which has not yet rendered rows, and a scroll
+at the true end of a list, both return `failedToolResult` carrying the suggestion "Treat the
+field/form action as not completed. Re-locate the editable control…" and commit
+`TestResult.FAILED` into the note. That note is read by final review and by Historian, so a
+correct end-of-list check is recorded as a failed test step.
+
+Fix: one line in `hasObservablePageChange` — `if (data.pageDiff.requests?.length) return true;`
+— and a no-change message that states what was observed rather than prescribing a
+form-specific recovery.
+
+**`src/ai/tools.ts:1208`** — `isMajorPageChange` (`src/ai/tools.ts:1220`) fires at
+`ariaChangeCount >= 50` with no URL change (`LARGE_ARIA_CHANGE_THRESHOLD`,
+`src/utils/aria.ts:581`), producing "MAJOR PAGE CHANGE. Page entered a different mode."
+`diffByCount` (`src/utils/aria.ts:309`) pushes one entry per surplus occurrence, so a batch of
+appended rows clears 50 easily. The rule says growth is the same state; the tool says the mode
+changed.
+
+Fix: a diff consisting of additions with no corresponding removals is growth, not a mode
+change. Mode changes churn — they remove as well as add.
+
+The added/removed split exists inside `diffAriaSnapshots` but is flattened into a single
+`count` before it reaches the check, so it has to be threaded through:
+
+1. `AriaDiff` (`src/utils/aria.ts:587`) gains `added: number; removed: number` — both arrays
+   are already computed at `src/utils/aria.ts:522`.
+2. `Diff` (`src/action-result.ts:650`) stores them alongside `_ariaChangeCount`, set where
+   `diffAriaSnapshots` is called (`src/action-result.ts:740`), and exposes them.
+3. `PageDiff` (`src/action-result.ts:46`) gains `ariaAdded` / `ariaRemoved`, populated next to
+   `ariaChanges` / `ariaChangeCount` (`src/action-result.ts:552`).
+4. `isMajorPageChange` then reads the split instead of the total.
+
+## Risks
+
+- **The probe costs a scroll per candidate section.** Steps 1 and 2 narrow it to sections that
+  have no pagination controls and can actually scroll, which on most pages is zero or one. If
+  it still proves too slow, the gate to tighten is step 2, not the probe itself.
+- **Region misclassification.** `OverlayPage.detectRegion` (`src/utils/overlay.ts:41`) accepts
+  in-flow added content that is `sizable` (≥5,000 chars, `src/utils/region.ts:99`), dominant
+  (≥70% of added raw size) and carries a name or root. A large appended batch in one list
+  container fits all three, which would fork the state hash with `region_<name>` and record a
+  transition. The probe can trigger this during research as well as the tester during a run.
+  Watch for it on the first real run; not changed here.
+- **Virtualized lists.** Recycled nodes keep counts flat, so the probe sees no growth and the
+  aria diff shows renames (`src/utils/aria.ts:325`) rather than additions. Such a list records
+  nothing and the rule will not know to scroll it. Out of scope.
+- **The stop condition lives only in the prompt.** No tool enforces it, so a model that keeps
+  scrolling past an attempt which added no rows will keep scrolling. Accepted: the tester's own
+  iteration cap is the only backstop.
+- **A REST call alone no longer stops the loop, by design.** After the D fix an empty-payload
+  200 counts as an observable change, so the tool reports success. The rule makes rows, not
+  calls, the evidence that more arrived — otherwise a list that answers every scroll with an
+  empty page would loop.
+
+## Testing
+
+- Unit coverage for step 0's marker scan: `aria-current="page"` and `rel=next/prev` yield
+  `controls`; `role="feed"` and `aria-setsize="-1"` yield `infinite`; `aria-current="true"` on a
+  tab list yields nothing.
+- `tests/integration/researcher-sections.test.ts` — `> Pagination: controls` appears for a
+  section whose UI map holds next/prev controls, and step 1 is not asked when step 0 already
+  answered.
+- A browser test for steps 2 and 3, following `tests/integration/overlay-modal-browser.test.ts`:
+  a container with its own scroller that appends on scroll (`infinite`), one that does not
+  (silent), a list with pagination controls (`controls`, no probe runs), and confirmation that
+  `scrollTop` is restored afterwards.
+- An aimock prompt-inspection test that the matching fragment reaches the tester on a paginated
+  state, the other fragment does not, and neither appears on a state with no list, per
+  `docs/contributing/ai-integration-tests.md`.
+- Unit coverage for the two `tools.ts` corrections: requests-only diff counts as observable;
+  an additions-only diff over the threshold is not a major page change.
+
+## Out of scope
+
+- Any new tool. The gesture is reachable through `form` today.
+- Persisting the strategy across runs. Research recomputes it, and the research cache is
+  session-scoped.
+- Virtualized list support.
+- Changing `detectRegion` thresholds.

package/docs/web-testing/agents.md

@@ -44,7 +44,7 @@ See [Researcher Agent](./researcher.md) for configuration and usage.
 
 Generates test scenarios from research findings.
 
-The Planner writes business-focused scenarios with priority levels (critical/important/high/normal/low) and expected outcomes for verification. It balances positive and negative cases, skips scenarios you already have, and cycles through planning styles (normal, psycho, curious) to broaden coverage across iterations. You can add your own styles and page-specific rules.
+The Planner writes business-focused scenarios with priority levels (critical/important/high/normal/low) and expected outcomes for verification. It balances positive and negative cases, skips scenarios you already have, and cycles through planning styles (normal, psycho, curious) to broaden coverage across iterations. You can add your own styles and page-specific rules. With the Scout agent enabled, it also plans from collected documentation, weighted by `docsWeight`.
 
 Commands that use Planner:
 - `/plan [--focus <feature>]`
@@ -52,6 +52,14 @@ Commands that use Planner:
 
 See [Planner Agent](./planner.md) for planning styles, customization, and configuration.
 
+## Scout Agent
+
+Retrieves documentation relevant to the page being planned.
+
+Scout searches the collected documentation corpus — the [application spec](../workflow/application-spec.md) from `explorbot docs collect` plus any extra markdown directories you configure — and reports the documented capabilities, states and transitions that matter for the current page and focus. The Planner receives them as a `<docs_context>` block and grounds part of its scenarios in them. Pages already injected as `<application_spec>` for the current URL are not repeated. Scout is opt-in (`ai.agents.scout.enabled`) and searches with ripgrep or grep, falling back to an in-process scan when neither is installed.
+
+See [Configuration: Scout agent](../reference/configuration.md#scout-agent).
+
 ## Tester Agent
 
 Runs the planned scenarios.

package/docs/web-testing/planner.md

@@ -53,6 +53,11 @@ ai: {
 | `styles` | `string[]` | `['normal', 'curious', 'psycho']` | Style names and cycling order |
 | `rules` | `RuleEntry[]` | `[]` | URL-aware rule files from `rules/planner/` |
 | `systemPrompt` | `string` | - | Inline instructions appended to the prompt |
+| `docsWeight` | `number` | `70` | With Scout enabled, the rough share of scenarios exercising documented behavior; the rest explore beyond the documentation |
+
+## Planning from documentation
+
+With the [Scout agent](../reference/configuration.md#scout-agent) enabled, the Planner also receives a `<docs_context>` block — capabilities, states and transitions retrieved from collected documentation that are relevant to the current page and focus. `docsWeight` steers the mix: at `70` roughly seven of ten scenarios exercise documented behavior and three explore what the documentation does not cover. Set it to `100` for documentation-only planning, or lower it to lean on the Planner's own reading of the page. Pages whose documentation is already injected as `<application_spec>` are not repeated in `<docs_context>`.
 
 ## Planning Styles
 

package/docs/workflow/application-spec.md

@@ -75,3 +75,7 @@ Screenshots and other relative links may be included for readers, but Explorbot
 ## Validation
 
 Explorbot rejects a bundle when `index.md` or `pages/` is missing, when it contains no page files, or when a page has an unsupported format, version, or missing URL.
+
+## Scout
+
+Beyond the per-URL injection, the same bundle feeds the [Scout agent](../reference/configuration.md#scout-agent): when Scout is enabled, it searches `pages/` (and any extra `ai.agents.scout.dirs`) for documentation relevant to the page being planned and reports it to the Planner. Pages already injected for the current URL are excluded from scouting, so the two channels never duplicate each other.

package/package.json

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

package/src/ai/fisherman/tools.ts

@@ -7,11 +7,13 @@ import type { RequestStore } from '../../api/request-store.ts';
 import { extractEndpointDefinition } from '../../api/spec-reader.ts';
 import type { Test } from '../../test-plan.ts';
 import { tag } from '../../utils/logger.ts';
+import { truncate } from '../../utils/strings.ts';
 import { isDynamicSegment } from '../../utils/url-matcher.ts';
 import type { Fisherman } from '../fisherman.ts';
 import type { RequestHaul } from './request-haul.ts';
 
 const BODY_PREVIEW_LIMIT = 2000;
+const READS_IN_ANSWER = 3;
 
 export function createFishermanTools(apiClient: ApiClient, requestStore: RequestStore, haul: RequestHaul, opts: { spec?: any; baseEndpoint?: string; readOnly?: boolean }) {
   const readOnly = opts.readOnly === true;
@@ -242,7 +244,7 @@ export function createAskApiTool(fisherman: Fisherman | null, task: Test) {
         }
 
         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 };
       },
     }),
@@ -285,6 +287,11 @@ function synthesizeResult(haul: RequestHaul, declaredDone: boolean, readOnly: bo
     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) summary += `; last failure: ${lastFailure.toSummary()}`;

package/src/ai/fisherman.ts

@@ -3,6 +3,7 @@ import type { ApiClient } from '../api/api-client.ts';
 import { type EndpointFamily, type RequestStore, isFailedRequest } from '../api/request-store.ts';
 import { listAllEndpoints } from '../api/spec-reader.ts';
 import { createDebug, tag } from '../utils/logger.ts';
+import { truncate } from '../utils/strings.ts';
 
 const debugLog = createDebug('explorbot:fisherman');
 import { loop } from '../utils/loop.ts';
@@ -137,7 +138,7 @@ export class Fisherman implements Agent {
     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;
   }
 

package/src/ai/pilot.ts

@@ -363,8 +363,6 @@ export class Pilot implements Agent {
     return dedent`
       SCENARIO: ${task.scenario}
 
-      ${this.buildDeletionScope(task)}
-
       EXPECTED RESULTS (milestones):
       ${task.expected.map((e) => `- ${e}`).join('\n')}
     `;
@@ -372,20 +370,22 @@ export class Pilot implements Agent {
 
   private buildResetSystemPrompt(task: Test): string {
     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.
 
@@ -1102,23 +1102,6 @@ export class Pilot implements Agent {
       .join('\n\n');
   }
 
-  private buildDeletionScope(task: Test): string {
-    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 '';
-  }
-
   private getSystemPrompt(task: Test, initialState: ActionResult): string {
     const interactive = isInteractive();
     const stepsText = task.plannedSteps.length > 0 ? task.plannedSteps.map((s, i) => `${i + 1}. ${s}`).join('\n') : 'No planned steps';

package/src/ai/planner.ts

@@ -25,6 +25,7 @@ import { POSSIBLE_SECTIONS, type Researcher } from './researcher.ts';
 import { findSimilarStateHash } from './researcher/cache.ts';
 import { hasFocusedSection } from './researcher/focus.ts';
 import { capabilityGroundingRule, dataProtectionRules, fileUploadRule } from './rules.ts';
+import type { Scout } from './scout.ts';
 
 const debugLog = createDebug('explorbot:planner');
 
@@ -63,6 +64,7 @@ export class Planner extends PlannerBase implements Agent {
   private lastSuite: Suite | null = null;
   researcher: Researcher;
   private fisherman: Fisherman | null = null;
+  private scout: Scout | null = null;
 
   constructor(deps: AgentDeps, researcher: Researcher) {
     super();
@@ -78,10 +80,19 @@ export class Planner extends PlannerBase implements Agent {
     this.fisherman = fisherman;
   }
 
+  setScout(scout: Scout): void {
+    this.scout = scout;
+  }
+
   private get sectionOrder(): string[] {
     return ConfigParser.getInstance().getConfig().ai?.agents?.researcher?.sections || Object.keys(POSSIBLE_SECTIONS);
   }
 
+  private get docsWeight(): number {
+    const value = ConfigParser.getInstance().getConfig().ai?.agents?.planner?.docsWeight ?? 70;
+    return Math.max(0, Math.min(100, value));
+  }
+
   private getDefaultStartUrl(state: { url: string; fullUrl?: string }): string {
     return state.fullUrl || state.url;
   }
@@ -328,6 +339,7 @@ export class Planner extends PlannerBase implements Agent {
     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));
 
@@ -385,6 +397,11 @@ export class Planner extends PlannerBase implements Agent {
     const research = await this.researcher.research(currentState || state, {
       deep: true,
     });
+
+    let docsPromise: Promise<string> | null = 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')
@@ -419,6 +436,22 @@ export class Planner extends PlannerBase implements Agent {
       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/src/ai/provider.ts

@@ -409,7 +409,8 @@ export class Provider {
     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/src/ai/researcher/deep-analysis.ts

@@ -116,7 +116,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       );
 
       tag('substep').log(`Researching overlay: ${region.name}`);
-      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded);
+      const sectionMarkdown = await this._analyzeExpandedAction('', region.name, diff, alreadyExpanded, region.root);
       if (!sectionMarkdown) {
         debugLog(`Overlay "${region.name}" produced no meaningful expansion`);
         return null;
@@ -421,9 +421,9 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       await new Promise((r) => setTimeout(r, 500));
 
       let diff: Diff;
+      let currAR: ActionResult;
       try {
-        await this.explorer.capture();
-        const currAR = ActionResult.fromState(this.stateManager.getCurrentState()!);
+        currAR = await this.explorer.capture();
         diff = await currAR.diff(previousState);
       } catch (err) {
         tag('warning').log(`State capture failed after click: ${err instanceof Error ? err.message : err}`);
@@ -444,7 +444,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
         return { status: 'none', code: clickCode };
       }
 
-      const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded);
+      const sectionMarkdown = await this._analyzeExpandedAction(clickCode, description, diff, alreadyExpanded, currAR.overlay.root);
       await this._restorePageState(state.url, originalAria);
       if (!sectionMarkdown) return { status: 'none', code: clickCode };
       return { status: 'revealed', code: clickCode, sectionMarkdown };
@@ -467,7 +467,7 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       }
     }
 
-    private async _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[]): Promise<string | null> {
+    private async _analyzeExpandedAction(code: string, description: string, diff: Diff, alreadyExpanded: string[], containerCss: string | null = null): Promise<string | null> {
       const alreadyHint = alreadyExpanded.length > 0 ? `\nAlready expanded sections:\n${alreadyExpanded.join('\n')}` : '';
 
       let intro: string;
@@ -532,7 +532,14 @@ export function WithDeepAnalysis<T extends Constructor>(Base: T) {
       const sections = parseResearchSections(text);
       if (sections.length === 0) return null;
 
-      return sections[0].rawMarkdown;
+      const sectionMarkdown = sections[0].rawMarkdown;
+      if (!containerCss) return sectionMarkdown;
+
+      let heading = mdq(sectionMarkdown).query('h3[0]');
+      if (heading.count() === 0) heading = mdq(sectionMarkdown).query('h2[0]');
+      if (heading.count() === 0) return sectionMarkdown;
+
+      return heading.replace(`${heading.text().trimEnd()}\n\n> Container: '${containerCss}'\n\n`);
     }
 
     private _deduplicateExpandedSections(sections: string[]): string[] {