Merge branch 'fix/more-tests-res-improv'

# Conflicts:
#	src/ai/researcher.ts

Author: DavertMik

CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 2026-04-17
+
+### Configuration
+- **`ai.agents.researcher.focusSections`** — List of CSS selectors that narrow research to a specific element when present on the page. If any selector matches, the researcher maps only that element instead of the whole page — useful for apps that open a focused panel (modal, drawer, detail view) on top of the main layout.
+  ```javascript
+  ai: {
+    agents: {
+      researcher: {
+        focusSections: ['[role="dialog"]', '.drawer-open', '#focused-panel'],
+      },
+    },
+  }
+  ```
+
+### Changes
+- [Tester] Detects modals and dialogs that appear mid-test and extends the page UI map with their controls — including overlays that don't expose `role="dialog"` (a "Close X" button is enough to recognize them), so the next tool call has selectors for the overlay.
+- [Researcher] New overlay analysis appends a section for each newly opened dialog/modal under the page's "Extended Research" heading and caches the result, so revisiting the same page skips the work.
+- ExploreCommand: The "Generated:" hints printed at the end of an explore session now list only the test files written during this run, not every file already sitting in `output/tests/`.
+- [Researcher] When the model's response gets truncated by context limits, the researcher now retries by splitting research into one request per section (focus, main, sidebar, etc.) and merging the results, instead of a single focused-retry prompt.
+- [Researcher] Honors the new `focusSections` config — if any configured CSS selector is present on the page, the researcher limits its UI map to that element rather than the full page.
+- [Tester] Past experience is no longer inlined into every tester turn. Instead, a compact table of contents (file tags plus section headings) is injected, and the agent fetches specific sections on demand via the new `learn_experience` tool. Cuts tester token usage on pages with accumulated experience.
+- [Pilot] Receives the same experience table of contents when tools are enabled and can pull full sections via `learn_experience`.
+- [Captain] The interactive web mode now exposes the `learn_experience` tool alongside `see`, `context`, and `visualClick`, so TUI-driven sessions can read past experience on demand.
+- [Planner] Rewrote the `normal`, `curious`, and `psycho` planning styles to rank scenarios by outcome strength: **data change > state change > UI-only**. Normal style now asks for complete commit flows over "form appears" checks, curious style treats an untested control as covered only when the scenario built around it reaches a data or state change (and refuses to merge a variation with a dismissal ending), and psycho style now attacks every reachable control in the same scenario with a different strange value instead of isolating one control per scenario.
+- Experience Tracker: New `getExperienceTableOfContents` / `getExperienceSection` API backs the TOC-based experience flow; sections are addressed by a short file tag (A, B, ...) and a 1-based section index.
+
 ## 2026-04-15
 
 ### CLI Changes

docs/agents.md

@@ -169,7 +169,7 @@ Agents share context through:
 
 1. **State Manager** — Tracks current page, URL, navigation history
 2. **Research Results** — Structured page analysis available to Planner and Tester
-3. **Experience Files** — Learned patterns shared across sessions
+3. **Experience Files** — Learned patterns shared across sessions. Injected as a compact table of contents (file tags + section headings) rather than full bodies; agents pull individual sections on demand via the `learn_experience` tool.
 4. **Knowledge Files** — Domain knowledge you provide
 
 Each agent maintains minimal context to keep costs down. They request specific information when needed rather than carrying full conversation history.

docs/configuration.md

@@ -211,6 +211,7 @@ The researcher agent supports all standard agent options plus additional options
 |--------|------|-------------|
 | `excludeSelectors` | `string[]` | CSS selectors for containers to exclude |
 | `includeSelectors` | `string[]` | CSS selectors for containers to always explore |
+| `focusSections` | `string[]` | CSS selectors that narrow research to a matching element when present (e.g. an open modal or drawer). First match wins. |
 | `stopWords` | `string[]` | Words to filter out (replaces defaults if provided) |
 | `maxElementsToExplore` | `number` | Maximum elements to explore per page (default: 10) |
 

docs/planner.md

@@ -45,11 +45,19 @@ Each time the Planner generates scenarios, it applies a **style** — a testing
 
 ### Built-in Styles
 
+All three built-in styles rank scenarios by **outcome strength**, from strongest to weakest:
+
+1. **Data change** — a record is created, edited, deleted; a setting is persisted; a message is sent; a job is triggered.
+2. **State change** — a route change, a filter or sort actually applied to real data, a mode or auth change the app remembers.
+3. **UI-only change** — something opens, closes, is cancelled, is hovered, is toggled for display. The application never registers anything new.
+
+Scenarios ending in category 1 or 2 are preferred. Category 3 is only proposed when the UI-only behaviour itself has a verifiable side effect (a warning prompt, a persisted draft, a badge appearing).
+
 | Style | Focus | What it generates |
 |-------|-------|-------------------|
-| **normal** | Complete user workflows | CRUD operations, form submissions, filter+verify flows. Each test changes application state. Distributes tests across all feature areas. |
-| **psycho** | Invalid and extreme inputs | Empty submissions, 10000-character strings, special characters, SQL injection, wrong formats, boundary values, incompatible combinations. Finds what breaks. |
-| **curious** | Coverage gaps | Cross-references previous test results with page research to find untested controls. Exercises every select option, checkbox state, and skipped form field. Fills gaps, not repeats. |
+| **normal** | Complete user workflows | CRUD operations, full commit flows, filter+verify flows — each test ends in a data change or state change. UI-only tests (tab switching, pagination, view toggles) come last and only when data- and state-changing coverage is done. Distributes tests across feature areas. |
+| **psycho** | Invalid and extreme inputs | Attacks **every reachable control in the same scenario** with a different strange value — empty, 10000 chars, unicode, SQL, script tags, invalid formats, conflicting toggles, out-of-range dates — then commits. Scenarios that enter bad data and cancel are rejected: the application never received the payload. |
+| **curious** | Coverage gaps | Cross-references previous test results with page research to find untested controls. An untested control is only considered covered when the scenario built around it reaches a data or state change. Variation scenarios and dismissal/UI-only scenarios are kept separate — the planner will not merge them by appending a cancel at the end. |
 
 ### How Cycling Works
 

docs/researcher.md

@@ -43,6 +43,7 @@ ai: {
 | `model` | `string` | - | Override default model for Researcher |
 | `systemPrompt` | `string` | - | Additional instructions appended to the research prompt |
 | `sections` | `string[]` | all sections | Page sections to identify (order = priority) |
+| `focusSections` | `string[]` | `[]` | CSS selectors that narrow research to a matching element when present (first match wins). Useful for apps that open a modal, drawer, or detail panel on top of the main layout — the researcher will map only that element instead of the whole page. |
 | `excludeSelectors` | `string[]` | `[]` | CSS selectors to exclude from deep exploration |
 | `includeSelectors` | `string[]` | `[]` | CSS selectors to always explore (second pass) |
 | `stopWords` | `string[]` | defaults | Words to filter during deep exploration (replaces defaults) |
@@ -366,6 +367,35 @@ ai: {
 }
 ```
 
+### Focus on a Single Element
+
+When your app opens a modal, drawer, or detail panel on top of the main layout, you usually want the researcher to map only that overlay, not the page behind it. `focusSections` is a list of CSS selectors — the first one that matches on the current page wins, and the researcher limits its UI map to that element:
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      focusSections: [
+        '[role="dialog"]',   // open modal
+        '.drawer-open',      // expanded side drawer
+        '#focused-panel',    // your app's detail panel
+      ],
+    },
+  },
+}
+```
+
+When none of the selectors match, the researcher falls back to mapping the whole page as usual.
+
+### Handling Truncated Responses
+
+The researcher produces a lot of output for busy pages. If the model's response gets cut off at `maxTokens`, Explorbot automatically retries by splitting the work into one request per section (focus, main, sidebar, etc.) and merging the results. You will usually see this transparently in the logs; no configuration needed.
+
+If you see this happening often, consider:
+- lowering reasoning effort (see [Low Reasoning Effort](#low-reasoning-effort) below),
+- pinning the researcher to a non-reasoning model with a larger output window,
+- or narrowing the scope with `focusSections`.
+
 ### Custom Stop Words
 
 ```javascript

docs/test-plans.md

@@ -0,0 +1,77 @@
+# Test Plans
+
+A test plan is a markdown file containing a suite of scenarios for the Tester to execute. Explorbot generates plans via the [Planner](./planner.md), but the format is plain markdown — you can hand-write plans, edit generated ones, or check them into version control.
+
+Plans are saved to `output/plans/` by default and loaded by the same parser whether they were generated or authored manually.
+
+The format is a dialect of the [Testomat.io classical markdown format](https://docs.testomat.io/project/import-export/export-tests/classical-tests-markdown-format/), extended with a `### Prerequisite` block so Explorbot knows which page to open before executing each test.
+
+## Format
+
+```markdown
+<!-- suite -->
+# Plan Title
+
+### Prerequisite
+
+* URL: /relative-path
+
+<!-- test
+priority: critical
+-->
+# Scenario written as a user-facing sentence
+
+## Steps
+* First step in plain language
+* Second step
+
+## Expected
+* First expected outcome
+* Second expected outcome
+```
+
+A single file may contain multiple suites — each begins with its own `<!-- suite -->` marker and parses as an independent plan.
+
+## Elements
+
+### `<!-- suite -->`
+
+Marks the start of a plan. The `#` heading on the following line becomes the plan's title. Follows the Testomat.io convention of HTML-comment metadata blocks.
+
+### `### Prerequisite`
+
+Holds the suite-level URL as a single bullet:
+
+```
+* URL: /relative-path
+```
+
+**The URL is required — without it, tests in the suite will not be executed.** It must be **relative** to the configured base URL (start with `/`), so the same plan runs against staging, production, or a local dev server without edits.
+
+Every test in the suite inherits this URL as its start page. Explorbot navigates to it before running each scenario.
+
+### `<!-- test priority: … -->`
+
+Opens a test block. Valid priorities: `critical`, `important`, `high`, `normal`, `low`. Defaults to `normal` if omitted. See [Test Priorities](./planner.md#test-priorities) for what each level means.
+
+### `#` Scenario heading
+
+A single `#` heading inside a test block is the scenario description. Write it as a business outcome, not a click path.
+
+### `## Steps`
+
+Bulleted list (`* `) of planned actions in plain language. The Tester reads these as guidance, not a strict script — it may adapt them to what it actually sees on the page. A step may span multiple lines by indenting continuation lines with 2 spaces.
+
+Unlike the Testomat.io classical format — which inlines `*Expected*:` inside each step — Explorbot separates actions and outcomes into distinct `## Steps` and `## Expected` sections.
+
+### `## Expected`
+
+Bulleted list (`* `) of expected outcomes. Each outcome should describe a **verifiable change** — a data change, state change, or a UI change with a side effect. See the Planner's [outcome-strength guidance](./planner.md#built-in-styles) for what counts.
+
+The Tester marks a test as passing only when every expected outcome has been verified.
+
+## See Also
+
+- [Planner](./planner.md) — how plans are generated
+- [Commands](./commands.md) — `/plan`, `/explore`, `explorbot plan`
+- [Rerun](./rerun.md) — re-executing generated tests

rules/planner/styles/curious.md

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