explorbot 0.2.3 → 0.2.4

package/docs/web-testing/planner.md

@@ -0,0 +1,122 @@
+# Planner Agent
+
+The Planner agent turns Researcher findings into test scenarios. Each scenario has steps, expected outcomes, and a priority, ready for the Tester to run.
+
+## Overview
+
+When you run `/plan` or `/explore`, the Planner:
+
+1. Receives the Researcher's UI map of the current page.
+2. Applies a planning style.
+3. Generates 3 to 12 scenarios with steps and expected outcomes.
+4. Assigns priorities based on business importance.
+
+Run it again and the Planner adds new scenarios in a different style. It skips scenarios that already exist.
+
+## Write a useful focus
+
+Focus works best when it names one feature boundary, the user goal, and the behavior that matters. Treat it as a testing brief, not a keyword.
+
+```bash
+npx explorbot plan /checkout --focus "Guest checkout: complete an order with card payment; cover validation, declined payment, retry, and confirmation without testing account registration"
+```
+
+The same focus works in the TUI:
+
+```
+/plan --focus "Guest checkout: complete an order with card payment; cover validation, declined payment, retry, and confirmation without testing account registration"
+```
+
+`checkout` alone leaves the scope ambiguous. The fuller focus tells Planner where the flow starts and ends, which outcomes deserve scenarios, and what to leave out. Keep the focus observable from the current page; put durable product facts or credentials in [Knowledge](../workflow/knowledge.md), not in the focus.
+
+## Configuration
+
+```javascript
+ai: {
+  agents: {
+    planner: {
+      model: groq('gpt-oss-20b'),
+      styles: ['normal', 'curious', 'psycho'],
+      rules: [
+        { '/checkout/*': 'payment-focus' },
+      ],
+    },
+  },
+}
+```
+
+### Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `LanguageModel` | default model | Override model for Planner |
+| `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 |
+
+## Planning Styles
+
+A style is a testing approach that shapes which tests the Planner creates. Styles cycle on each planning iteration, so repeated runs produce different kinds of tests. See [Planning Styles](../workflow/planning-styles.md) for how cycling works, custom style files, and `extract-rules`.
+
+### 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 applied to real data, a mode or auth change the app remembers.
+3. **UI-only change** — something opens, closes, is cancelled, is hovered, or is toggled for display. The application registers nothing new.
+
+The Planner prefers scenarios that end in category 1 or 2. It proposes category 3 only when the UI-only behaviour has a verifiable side effect, such as a warning prompt, a persisted draft, or a badge appearing.
+
+| Style | Focus | What it generates |
+|-------|-------|-------------------|
+| **normal** | Complete user workflows | CRUD operations, full commit flows, filter+verify flows, distributed across feature areas. UI-only tests (tab switching, pagination, view toggles) come last. |
+| **curious** | Coverage gaps | Cross-references previous test results with page research to find untested controls. Variation scenarios and dismissal scenarios are kept separate — the planner will not merge them by appending a cancel at the end. |
+| **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. |
+
+### Style Cycling
+
+The default cycle is: normal, curious, psycho, then back to normal. The 1st `/plan` uses normal, the 2nd curious, the 3rd psycho. Each iteration proposes only scenarios that aren't already in the plan. When all feature areas are covered, the Planner returns an empty list.
+
+Force a specific style:
+
+```
+/plan --style psycho
+```
+
+Set `styles` in the config to control the rotation. To customize or add style files, see [Planning Styles](../workflow/planning-styles.md).
+
+## Page-Specific Rules
+
+Use [rules](../reference/configuration.md#rules) to give the Planner extra instructions for specific pages:
+
+```javascript
+planner: {
+  rules: [
+    'no-delete-tests',                    // rules/planner/no-delete-tests.md — all pages
+    { '/checkout/*': 'payment-rules' },   // rules/planner/payment-rules.md — checkout only
+    { '/admin/*': 'admin-scenarios' },    // rules/planner/admin-scenarios.md — admin pages
+  ],
+}
+```
+
+Rules are additive. The Planner concatenates all matching rules and appends them to its prompt alongside the active style.
+
+## Test Priorities
+
+The Planner assigns priorities by business importance:
+
+| Priority | Meaning | Examples |
+|----------|---------|---------|
+| **critical** | Core business functionality | Login, checkout, primary CRUD |
+| **important** | Key user flows | Profile edit, search, main filters |
+| **high** | Secondary features | Edge cases for critical flows |
+| **normal** | Supporting actions | Settings, configuration |
+| **low** | Minor interactions | Cosmetic checks, boundary tests |
+
+## See Also
+
+- [Planning Styles](../workflow/planning-styles.md) — cycling, custom styles, `extract-rules`
+- [Configuration: Rules](../reference/configuration.md#rules) — URL-aware rule files
+- [Agents](./agents.md) — all agent descriptions
+- [Commands](../reference/commands.md) — CLI and TUI commands

package/docs/web-testing/rerun.md

@@ -0,0 +1,164 @@
+# Rerunning Tests
+
+Explorbot generates CodeceptJS test files in `output/tests/` after an exploration session. Use the `runs` and `rerun` commands to list, inspect, and re-execute these tests with AI healing.
+
+## Workflow
+
+```
+npx explorbot explore /dashboard          # generates output/tests/dashboard.js
+npx explorbot runs                        # list all generated tests with indices
+npx explorbot runs output/tests/dashboard.js   # preview steps (dry-run)
+npx explorbot rerun output/tests/dashboard.js --session   # run with healing
+npx explorbot rerun output/tests/dashboard.js 3 --session # run test #3 only
+```
+
+## Listing tests
+
+```bash
+npx explorbot runs
+```
+
+Lists all generated test files with numbered scenarios:
+
+```
+Dashboard Testing
+output/tests/dashboard_testing.js
+  1. ❯ Create a new item
+  2. ─ Delete an item (skipped)
+  3. ❯ Edit item title
+```
+
+Active tests show `❯`, skipped tests show `─`.
+
+### Dry-run a file
+
+```bash
+npx explorbot runs output/tests/dashboard_testing.js
+```
+
+Prints the CodeceptJS steps each test runs, including `Before` hooks, without launching a browser. Use it to check what a test does before running it.
+
+## Re-running tests
+
+```bash
+npx explorbot rerun <file> [index] [--session]
+```
+
+Runs tests through CodeceptJS. The Rerunner agent heals steps that fail.
+
+### Index selection
+
+| Syntax | Meaning |
+|--------|---------|
+| _(no index)_ | Run all tests in the file |
+| `3` | Run test #3 only |
+| `1-5` | Run tests 1 through 5 |
+| `1,3,7` | Run specific tests |
+
+Indices match the numbers shown by `npx explorbot runs`.
+
+### What gets skipped
+
+- **Scenario.skip / Scenario.todo** — already marked as skipped in the test file.
+- **Tests without assertions** — tests with no `I.see`, `I.seeElement`, `I.dontSee`, or similar are skipped, because their results can't be verified.
+
+## AI healing
+
+When a step fails, the Rerunner agent diagnoses the problem and tries to fix it. It uses the same tools as the Tester agent: click, form, pressKey, xpathCheck, see, research, and bash.
+
+### How it works
+
+1. A step like `I.click("Save", ".modal")` fails.
+2. The healer receives the current page state (URL, ARIA tree) and trace data.
+3. It diagnoses the cause: wrong page, loading, broken locator, or missing data.
+4. It runs a replacement action, for example waiting for the page to load and then clicking with a corrected locator.
+5. On success, the test continues. On failure, it moves to the next test.
+
+### Healing boundaries
+
+AI healing repairs how an existing step reaches the same intended outcome. It is deliberately not a second exploratory test run.
+
+| Healing can | Healing does not |
+|-------------|------------------|
+| Replace a stale or ambiguous locator | Change the scenario's business intent |
+| Wait for loading or dismiss a blocking transient UI | Turn a failed assertion into a pass |
+| Restore expected navigation or repeat an equivalent interaction | Invent missing credentials, permissions, or test data |
+| Adapt to a small UI structure change | Work around a real product defect or unavailable service |
+
+The healer only has `healLimit` attempts per test and `healMaxIterations` AI iterations per failed step. It should stop when the expected element or state no longer exists, required data is missing, access is denied, or the application behavior contradicts the assertion. In those cases the test remains failed and the trace preserves the evidence for review.
+
+Successful healing updates the generated test file with the replacement step. Review that diff before committing it: healing shows that an equivalent interaction worked now, not that every UI change is safe or intentional.
+
+### Healing output
+
+During healing, the agent's actions show as substeps:
+
+```
+  ❯ Create a new test
+    I.amOnPage("/projects/testcaselabs/")
+    I.click("Test", ".sticky-header .first")
+    → Healing: I.click("Test", ".sticky-header .first")
+   > ✔ Detected loading spinner, waiting
+   > ✔ Click Test button in toolbar
+    ✔ Healed: I.click({"role":"button","text":"Test"})
+```
+
+### Healing configuration
+
+Configure the Rerunner agent in `explorbot.config.js`:
+
+```javascript
+export default {
+  ai: {
+    agents: {
+      rerunner: {
+        healLimit: 3,           // max heals per test (default: 3)
+        healMaxIterations: 3,   // max AI loop iterations per heal (default: 3)
+        recipes: {
+          // Custom healing recipes (CodeceptJS heal API)
+          waitForLoader: {
+            steps: ['amOnPage'],
+            fn: async () => {
+              return async ({ I }) => {
+                await I.waitForInvisible('.loader', 20);
+              };
+            },
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+### Custom rules
+
+Healing prompt rules live in `rules/rerunner/` as markdown files:
+
+| File | Purpose |
+|------|---------|
+| `healing-approach.md` | Step-by-step diagnosis strategy |
+
+To override a rule, place a file with the same name in your project's `rules/rerunner/` directory.
+
+## Trace output
+
+Each rerun creates a trace directory under `output/states/rerun_<timestamp>/` with per-test artifacts:
+
+- `trace.md` — execution timeline with links to all artifacts
+- `*_aria.txt` — ARIA snapshot per step
+- `*_page.html` — full HTML per step
+- `*_screenshot.png` — screenshot per step
+- `*_console.json` — browser console logs per step
+
+The healer reads these files to diagnose failures.
+
+## After exploration
+
+After `/explore` or `npx explorbot explore`, Explorbot shows the generated test files with rerun suggestions:
+
+```
+Generated: test_management.js
+List tests: npx explorbot runs
+Re-run with healing: npx explorbot rerun <filename> [index]
+```

package/docs/web-testing/researcher.md

@@ -0,0 +1,380 @@
+# Researcher Agent
+
+The Researcher analyzes web pages to understand their structure, identify UI elements, and build UI maps with locators.
+
+## Overview
+
+Research gives other agents the context they need:
+
+- **Planner** — calls the Researcher before generating test scenarios
+- **Tester** — uses research results to understand page context during execution
+
+You can also run research manually to inspect pages or debug locator issues.
+
+## Configuration
+
+> [!IMPORTANT]
+> The Researcher processes large amounts of HTML and ARIA tokens on every call. Use a **fast, cheap model** — it does not need deep thinking, just accurate element extraction. Models like `gpt-oss-20b` via Groq or Cerebras at 100+ TPS work well. On reasoning models the Researcher runs at low reasoning effort by default — see [Reasoning Effort](#reasoning-effort).
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      model: groq('openai/gpt-oss-20b'),
+      systemPrompt: 'Focus on form validation elements...',
+      sections: ['overlay', 'content', 'list'],
+      maxExpandableClicks: 10,
+      retries: 2,
+    },
+  },
+}
+```
+
+### Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `model` | `string` | - | Override the default model for the Researcher |
+| `systemPrompt` | `string` | - | Extra instructions appended to the research prompt |
+| `sections` | `string[]` | all sections | Page sections to identify (order = priority) |
+| `focusSections` | `string[]` | `[]` | CSS selectors used in the truncated-response fallback, when research is split into per-section requests (first match wins). The matching element becomes the container for the focused section — see [Handling Truncated Responses](#handling-truncated-responses). |
+| `maxExpandableClicks` | `number` | `10` | Max expandable elements clicked during deep research |
+| `errorPageTimeout` | `number` | `10` | Seconds to wait for the page to settle before research; error pages detected during this wait abort research. Set `0` to skip the wait |
+| `retries` | `number` | `2` | Retries when most locators are broken in Stage 2 |
+| `reasoning` | `string` | `'low'` | AI SDK v7 reasoning effort: `'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, `'xhigh'`, `'provider-default'` |
+| `providerOptions` | `object` | - | Provider-specific options. Reasoning keys here take precedence over `reasoning`. |
+
+See [Configuration Examples](#configuration-examples) at the end of this page for common setups.
+
+## Usage
+
+### CLI Mode
+
+```bash
+# Research a specific path (relative to url in config)
+npx explorbot research /login
+npx explorbot research /admin/users
+
+# Research with options
+npx explorbot research /dashboard --deep
+npx explorbot research /products --data
+```
+
+### TUI Mode (Interactive)
+
+```bash
+# Research current page
+/research
+
+# Research with deep expansion (clicks dropdowns, tabs, etc.)
+/research --deep
+
+# Research with data extraction
+/research --data
+
+# Research specific path
+/research /login
+/research /admin/pages
+
+# Skip locator validation and fixing
+/research --no-fix
+```
+
+Explicit research always runs fresh (bypassing the [cache](#caching)) and always captures a screenshot.
+
+### Automatic Research
+
+Research also runs as part of other commands:
+
+```bash
+# Planner researches the page before planning
+npx explorbot plan /dashboard
+
+# Explorer researches each new page it discovers
+npx explorbot explore /admin
+```
+
+## How It Works
+
+### Element Indexing (eidx)
+
+Before research begins, Explorbot injects a `data-explorbot-eidx` attribute into every interactive element on the page (buttons, links, inputs, tabs, and so on). Each element gets a unique numeric index — its **eidx**.
+
+The eidx is a stable bridge between three representations of the same element:
+
+| Representation | What it provides | Where eidx appears |
+|----------------|------------------|--------------------|
+| **HTML** | Structure, attributes, CSS selectors | `<button eidx="5">Save</button>` |
+| **ARIA tree** | Accessible roles, names | Mapped back via Playwright `getByRole` |
+| **Screenshot** | Visual position, color, icon | Colored label `5` drawn above the element |
+
+When the AI produces a research table with `eidx=5`, that index is used to:
+- Test the element's CSS locator against the live DOM
+- Look up its coordinates from the annotated screenshot
+- Generate a fallback XPath if CSS is broken
+
+Without eidx, there would be no reliable way to match "the third button in the HTML" with "the blue button at (400, 300) on the screenshot."
+
+### The 5-Stage Pipeline
+
+Research runs each page through five stages:
+
+| Stage | Name | What happens |
+|-------|------|--------------|
+| 1 | **Research** (AI) | AI analyzes HTML and ARIA, produces a UI map with sections, containers, ARIA locators, CSS locators, and eidx references |
+| 2 | **Test** | Test containers first, then element locators. Capture exact counts (`0 elements`, `3 elements`, `dynamic ID`). If all containers are broken or more than 80% of locators are broken, retry Stage 1 |
+| 3 | **Fix** (AI, same conversation) | Continue the Stage 1 conversation with Playwright test results. AI fixes broken locators with full page context |
+| 4 | **Visual** (optional) | Annotate the screenshot with eidx labels. AI extracts coordinates, colors, and icons. Merge into research by eidx |
+| 5 | **Backfill** | Re-test all locators. For still-broken elements, look up the eidx in the DOM and generate an XPath from attributes. Nullify containers that are still broken |
+
+Stage 3 reuses the Stage 1 conversation. The AI already has full context about the page HTML, so it fixes locators more accurately without extra token cost.
+
+### Research Modes
+
+#### Standard Research (HTML + ARIA)
+
+```bash
+/research
+```
+
+Analyzes the page using HTML and the ARIA tree. Fast, and works with any model.
+
+#### Deep Research
+
+```bash
+/research --deep
+```
+
+Expands hidden elements (dropdowns, accordions, tabs) to discover more UI. Clicks through interactive elements and documents what appears. Deep research also reuses what it found on previous runs — see [Reusing Previous Results](#reusing-previous-results).
+
+#### Research with Data Extraction
+
+```bash
+/research --data
+```
+
+Extracts domain-specific content (articles, products, users) as structured data.
+
+## Page Sections
+
+The Researcher breaks each page into sections by UI purpose. Sections are identified in priority order:
+
+| Section | Description |
+|---------|-------------|
+| `overlay` | Dialog, modal, drawer, popup, or active form overlay |
+| `list` | List area (items collection, table, cards, or list view) |
+| `detail` | Detail area (selected item preview or full details) |
+| `panes` | Screen is split into equal panes |
+| `content` | Main area of the page |
+| `menu` | Page menu (toolbar, context actions, filters, dropdowns) |
+| `navigation` | Main navigation (top bar, sidebar, breadcrumbs) |
+
+Each section includes:
+- A **container CSS selector** that scopes all elements within it
+- A **UI map table** listing interactive elements with ARIA and CSS locators
+
+Override the default section list via `ai.agents.researcher.sections` — see [Configuration](#configuration).
+
+## Vision Model Support
+
+### Without Vision
+
+The Researcher works with text-only models by analyzing HTML structure, the ARIA tree, and element roles and names. This is enough for most pages, and it is faster and cheaper.
+
+### With Vision
+
+With a vision model configured, the Researcher can analyze screenshots for visual elements, detect icons and visual indicators, and provide element coordinates for visual clicking.
+
+Enable vision by configuring a vision model instance:
+
+```javascript
+ai: {
+  visionModel: openai('gpt-4o'),
+}
+```
+
+Explicit research always captures a screenshot; when a vision model is configured, the screenshot is analyzed in Stage 4.
+
+Vision helps most on pages with icon-only buttons, canvas-based UIs, and when the HTML doesn't reflect the visual layout.
+
+## Deep Exploration
+
+Deep exploration (the `--deep` flag) discovers hidden UI by clicking through elements to find modals, dropdowns, tabs, and menus.
+
+For each element, the Researcher:
+1. Captures state before the click
+2. Clicks the element
+3. Detects what changed (navigation, modal, menu, UI change)
+4. Restores the original state (Escape key or navigate back)
+
+### Reusing Previous Results
+
+Hidden sections discovered by deep research are saved under an **Extended Research** block in the page's research file, together with the action that revealed each one. On the next deep run for the same page — even in a later session — the researcher builds on that instead of starting from scratch:
+
+1. **Replay** — it re-runs the saved action for every previously found section to check it still opens.
+2. **Reuse** — sections that still open are kept as-is and are not explored again, so the run spends its click budget on what is actually new.
+3. **Re-discover** — if a section's trigger no longer works (the button moved or was renamed), it is flagged to the AI as "this section existed before, find it again", so a relocated control is recovered rather than lost.
+4. **Skip** — when every known section still opens and the click budget is already covered, the slow click-through exploration is skipped because the page is effectively unchanged.
+
+This makes repeated deep runs faster and stops the researcher from silently losing hidden UI it had already mapped. The reuse reads the last saved research file directly, so it works across sessions and is not limited by the in-memory [cache window](#caching).
+
+### Selecting Elements
+
+Not every element should be explored. During deep analysis the AI itself discovers expandable candidates from the research results — and from the annotated screenshot when a vision model is configured — picking elements that hide content until clicked (menus, dropdowns, accordions, tabs) and skipping regular links and navigation. Repeated controls, like the same expand button on every list row, collapse to a single representative. When more candidates are found than the click budget allows, the AI selects the most promising ones. The budget is set by `maxExpandableClicks` (default 10).
+
+## Output Format
+
+Research results are saved to `output/research/{hash}.md`:
+
+```markdown
+## Summary
+
+Brief description of the page purpose.
+
+## Login Modal
+
+Modal dialog for user login...
+
+> Container: '[role="dialog"]'
+> **Focused**
+
+| Element | Type | ARIA | CSS |
+|---------|------|------|-----|
+| 'Email' | textbox | { role: 'textbox', text: 'Email' } | 'input#email' |
+| 'Password' | textbox | { role: 'textbox', text: 'Password' } | 'input[name="password"]' |
+| 'Sign In' | button | { role: 'button', text: 'Sign In' } | 'button[type="submit"]' |
+
+## Content Section
+
+Main content area...
+
+> Container: '.main-content'
+
+| Element | Type | ARIA | CSS | XPath | Coordinates |
+|---------|------|------|-----|-------|-------------|
+| 'Save' | button | { role: 'button', text: 'Save' } | 'button.save' | - | (400, 300) |
+| 'Delete' | button | { role: 'button', text: 'Delete' } | - | '//button[@class="del"]' | (500, 300) |
+```
+
+Notes:
+- Sections are named after their content (never "Focus"); a focused overlay is marked with a `> **Focused**` blockquote under its container line
+- The Type column is derived from the ARIA role during cleanup
+- The XPath column appears only when CSS is broken and XPath was backfilled from the DOM
+- Coordinates are backfilled from DOM positions for all indexed (eidx) elements; a vision model additionally contributes colors and icons
+- The container is shown as a blockquote `> Container: '...'` before the table
+
+## Caching
+
+Research results are cached for 6 hours:
+- In memory during the session
+- On disk in `output/research/`
+
+Separately, for up to 1 hour a page whose HTML fingerprint is at least 90% similar to an already-researched state reuses that state's research.
+
+The cache applies to research triggered automatically by other agents. Explicit `/research` always bypasses it and runs fresh.
+
+This cache controls when a fresh result is reused within a session. It is separate from how [deep research reuses previous results](#reusing-previous-results): a deep run always reloads the last saved research file from `output/research/` to replay and verify previously discovered hidden sections, regardless of the cache window or session.
+
+## Configuration Examples
+
+### Limit Sections
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      // Only research these sections, skip navigation and menu
+      sections: ['overlay', 'content', 'list', 'detail'],
+    },
+  },
+}
+```
+
+### Focus on a Single Element
+
+`focusSections` applies when a truncated response forces the Researcher into per-section research (see [Handling Truncated Responses](#handling-truncated-responses)). It is a list of CSS selectors — the first one that matches on the current page wins, and the split research treats that element as the focused container instead of the whole page. Useful for apps that open a modal, drawer, or detail panel on top of the main layout:
+
+```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, per-section research covers the whole page.
+
+### Handling Truncated Responses
+
+The Researcher produces a lot of output for busy pages. If the model's response is cut off at `maxOutputTokens`, Explorbot retries by splitting the work into one request per section (focus, main, sidebar, and so on) and merging the results. This usually happens transparently in the logs; no configuration is needed.
+
+If you see it often, consider:
+- lowering reasoning effort (see [Reasoning Effort](#reasoning-effort) below),
+- pinning the Researcher to a non-reasoning model with a larger output window,
+- or narrowing the scope with `focusSections`.
+
+### Custom Component Guidance
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      systemPrompt: `
+        This app uses custom components:
+        - <DataGrid> renders as div with role="grid"
+        - <Modal> uses [data-modal] attribute
+        - Dropdowns have [data-dropdown] attribute
+
+        Look for data-testid attributes for reliable selectors.
+      `,
+    },
+  },
+}
+```
+
+### Reasoning Effort
+
+The Researcher runs with `reasoning: 'low'` by default. On reasoning models this keeps the chain-of-thought short, so the output budget goes to the UI map instead of thinking tokens. `reasoning` is the provider-agnostic setting from AI SDK v7 — the SDK maps it to the active provider's effort control, so the same value works across OpenAI, Anthropic, Google, Groq, and others:
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      reasoning: 'none', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'provider-default'
+    },
+  },
+}
+```
+
+For provider-specific control (such as an exact thinking-token budget), set the provider's own keys in `providerOptions` — they take precedence over `reasoning`.
+
+If heavy pages still truncate the response (`AI response empty: output truncated at maxTokens`), lower `reasoning` to `'none'`, raise `maxOutputTokens`, or pin the Researcher to a non-reasoning model.
+
+### Vision-Heavy Research
+
+```javascript
+ai: {
+  agents: {
+    researcher: {
+      systemPrompt: `
+        Pay attention to:
+        - Icon buttons without text labels
+        - Color indicators (red = error, green = success)
+        - Visual hierarchy and spacing
+      `,
+    },
+  },
+}
+```
+
+## See Also
+
+- [Configuration](../reference/configuration.md) - general configuration options
+- [Agents](./agents.md) - all agent descriptions
+- [Knowledge Files](../workflow/knowledge.md) - domain-specific hints