explorbot 0.2.3 → 0.2.4

package/docs/superpowers/specs/2026-08-07-prima-fixes-design.md

@@ -0,0 +1,394 @@
+# Prima Fixes — Perception Ladder, No Heal, Proof-Carrying Envelopes
+
+**Date:** 2026-08-07
+**Status:** Draft for review
+**Supersedes parts of:** `2026-08-01-prima-boat-design.md`
+**Evidence:** `docs/superpowers/reviews/2026-08-06-prima-vs-playwright-cli.md`
+
+## Problem
+
+A field run of prima against a live app (Testeiya, `localhost:3050`) found the boat working but
+not trustworthy as an executor. Four defects matter:
+
+- A `pw` call on a selector that does not exist returned `ok: true`, `healed: true`, having
+  clicked an unrelated control ("New agent"). Heal substituted the target and reported success.
+- `### Changes` never appeared in any successful envelope, so a successful action proved
+  nothing and every step had to be confirmed with a playwright-cli snapshot.
+- `do` given two instructions performed four, typing into a live chat box actions nobody asked
+  for.
+- Auto-discovery of a playwright-cli session never matched, while the failure message advised
+  opening the session the user already had open.
+
+Underneath the third defect is a perception problem. `action.ts:139` captures
+`page.locator('body').ariaSnapshot()` **without** `mode: 'ai'`, so `do` sees roles and text but
+no element handles and must invent locators. That is why the `click` tool's schema demands
+"multiple commands targeting the SAME element" and why one click produced five ladder attempts,
+one of them invalid JavaScript.
+
+## Goals
+
+- Prima is the executor for an expensive orchestrator: page data never enters that context on
+  the happy path, intent is never guessed, and every action carries proof of what changed.
+- `do` acts on element handles it was given, not on locators it invented.
+- Failures are failures. No code path may reach a different element than the one asked for.
+- Attachment to an existing playwright-cli session works without hand-editing files.
+
+## Non-Goals
+
+- Replacing playwright-cli. It remains the fallback for direct driving and the tool prima
+  points back to when it cannot help.
+- Reducing per-command latency, and improving `research` locator quality. Separate concerns.
+- Changing Tester, Navigator, or Researcher behaviour outside the shared pieces named below.
+
+---
+
+## 1. Perception ladder for `do`
+
+Four tiers, tried in order. Each tier answers "what can I act on here?" at a different cost.
+
+| Tier | Source | When |
+|---|---|---|
+| 1 | Research UI map | a stored map exists for this state hash and the state is well-visited |
+| 2 | **ARIA snapshot with refs** | default |
+| 3 | Compact HTML tree | a ref action failed, or the control is absent from the ARIA tree |
+| 4 | Vision (`visualClick`) | click only, when the target is identifiable solely by appearance |
+
+### Tier 1 — research map
+
+Read through `getPreviousResearch(hash)` — a TTL-free disk read. Not `getCachedResearch`, whose
+six-hour TTL carries session-scoped semantics that must not be stretched for cross-invocation
+reuse. The trigger is the StateManager visit count for the current state hash, the same number
+the envelope already prints as `visit #N`: use the map from the **third visit onward**, so a
+state has to prove it is worth the map before prima prefers one. Below that, skip to tier 2.
+The threshold is a single config field under `ai.agents.prima`, per the one-knob convention.
+
+Research cost is real — 41s on the vision model in the field run — so tier 1 only pays off
+amortized across repeat visits to one state. Prima does not run research on the caller's behalf
+inside `do`; it consumes a map that already exists.
+
+### Tier 2 — ARIA snapshot with refs (the default)
+
+`page.locator('body').ariaSnapshot({ mode: 'ai' })` emits `[ref=eN]` handles. Playwright resolves
+them natively through the `aria-ref=` selector engine, verified live against the running app:
+
+```
+aria-ref=e1 → 1 match
+```
+
+No DOM mutation, no attribute stamping. The model is given the ref-bearing tree and names a ref;
+resolution to a CodeceptJS command is §1.1. One ref becomes one command and the
+multiple-locator fallback ladder collapses.
+
+**Ref lifetime is one context injection.** Refs are snapshot-scoped and shift between calls —
+in the field run the same sidebar button was `ref=e13` in one snapshot and `ref=e284` in a later
+one on the same page. Prima re-snapshots whenever the `do` loop re-injects context on state-hash
+change (the hook exists at `prima.ts:104`), and the prompt states that refs from an earlier
+injection are dead.
+
+**Ref shape.** Refs are frame-qualified: every ref this app emits is `f1e13`-shaped, not `e13`.
+A validator that accepts only `e\d+` rejects every real ref and silently disables the whole tier,
+so the accepted shape is `(f\d+)?e\d+`. Refs are never adapted or invented — a ref that does not
+parse, or that resolves to nothing, is a failure with its own message.
+
+### Tier 3 — compact HTML tree
+
+The current `simplifiedHtml` path. Entered when a ref action fails or the target is not
+represented in the accessibility tree.
+
+### Descending the ladder — `context()`
+
+The tiers above are only reachable if something can move between them mid-run. The `do` loop
+re-injects context between iterations when the state hash changes, which leaves no way to
+recover from a ref that died *within* an iteration — the model's only remaining moves would be
+to guess a locator, which the prompt forbids, or to stop.
+
+`do` therefore carries a `context` tool. First call returns the page as it is now with fresh
+refs, which replace every ref the model was holding; a later call on the same page drops to
+capped markup for elements the accessibility tree does not describe. It is the tier descent, not
+a page dump.
+
+This is deliberately **not** the `context` tool from `createAgentTools`. That one returns
+`getInteractiveARIA()` — `compactAriaSnapshot` over `ActionResult.ariaSnapshot`, captured without
+`mode: 'ai'`, so it carries **no refs** — plus a 6k-char HTML dump beside it. Offering it here
+would hand the model a ref-less tree and push it straight back to guessed locators, undoing
+tier 2.
+
+### Tier 4 — vision
+
+`visualClick` (`src/ai/tools.ts:791`), already implemented. Click only — a coordinate is not a
+handle, so it cannot serve fills, selects, or assertions.
+
+### 1.1 Acting on a ref — `clickRef` / `hoverRef` in `boat/prima/src/tools.ts`
+
+CodeceptJS has no `aria-ref` locator, so a ref cannot be handed to `I.click()` directly. It is
+resolved to a locator CodeceptJS does understand, using machinery that already exists:
+
+```
+page.locator(`aria-ref=${ref}`)
+  → WebElement.fromPlaywrightLocator(...)     (web-element.ts:112)
+  → I.click(<xpath>)
+```
+
+**Which XPath, and the one that is not available.** `WebElement` declares two — `clickXPath`,
+built attribute-first by `buildClickableXPath` (`utils/xpath.ts`), and `xpath`, the absolute
+positional path. On this path only `clickXPath` exists: `fromPlaywrightLocator` builds through
+`fromRawData`, which hardcodes `xpath: ''` (`web-element.ts:89`). Only `fromXPathMatch`, the
+static-HTML path, populates the absolute form. So there is no positional fallback to reach for,
+and that is the right outcome anyway — an absolute path is deduplication machinery, fragile the
+moment the DOM shifts, and the ref resolution and the click happen on separate round-trips.
+
+Verified live, ref → `clickXPath` → match count:
+
+```
+e15  link "Checking the proxy…"  //*[self::a and contains(.,"Checking the proxy and the firewall")]  → 1
+e19  button "Reload"             //*[@id="reload-button"]                                            → 1
+e20  button "Details"            //*[@id="details-button"]                                           → 1
+```
+
+**Require a unique match.** Because there is no fallback, the resolved `clickXPath` is checked
+to match exactly one element before it is used. Zero or many is a failure, reported as such —
+never a click on an ambiguous match and never a retreat to guessed locators.
+
+Ref acting lives in **separate tools in the boat** — `clickRef` and `hoverRef`, from a
+`createRefTools` factory in `boat/prima/src/tools.ts`. `click` and `hover` in `src/ai/tools.ts`
+are left byte-identical. A prima-only tool belongs to prima; core keeps only what every caller
+uses, and lends the boat its result-shaping helpers (`successToolResult`, `failedToolResult`,
+`commitNote`) rather than having them copied.
+
+Adding an optional `ref` to the existing tools looks cheaper and is wrong. A tool's schema and
+description are shared with every caller, and Tester never receives ref-bearing snapshots, so it
+would be shown a parameter it can only fill by inventing one. Making `commands` optional to
+accommodate the new field weakens the contract for Tester too. "Prima enables ref mode, Tester is
+untouched" is not achievable through one definition: there is one definition, and Tester sees it.
+
+Each ref tool takes a ref and nothing else, resolves it, executes one command, and reports that
+command as `used:` — real CodeceptJS a generated test can keep. A ref that does not resolve is a
+failure, not a cue to fall back to a guessed locator: it means the context is stale.
+
+`hoverRef` exists for the same reason as `hover` — revealing hover-only controls is a
+prerequisite for clicking them.
+
+Prima keeps the locator tools alongside the ref tools: tier 3 works from markup that carries no
+refs, and needs them. Tier 4 keeps the coordinate input.
+
+---
+
+## 2. Heal is deleted
+
+`heal()` (`prima.ts:428-460`) is removed, along with `--no-heal`, `PrimaOptions.heal`, the
+`healed:` / `healNote` envelope fields, the `HealAttempt` type, and the
+`### Healing attempts` section. The three call sites — `pw` (`:79`), `do` (`:135`), `go` (`:211`)
+— go straight to `failureEnvelope`.
+
+The failure envelope already does the right thing and becomes the only failure path: `ok: false`,
+the exact error with its call log, and compact ARIA inline. Measured at 8.6s in the field run
+against 34.8s for the heal path that got the answer wrong.
+
+This removes the substitution defect at the root. No remaining code path can select an element
+other than the one asked for, so no envelope can report success for an action the caller did not
+request. Routine obstructions — an overlay covering a button, an element not yet visible — now
+return the failure envelope, and the orchestrating model decides. That is the accepted cost: the
+compact ARIA block is the one place page data deliberately enters the expensive context.
+
+---
+
+## 3. Proof-carrying envelopes
+
+Two defects with one cause. `renderOutcome` (`envelope.ts:76`) returns the **first** of
+changes / answer / research / verdict, so `### Changes` is structurally impossible alongside
+`### Verdict`, `### Answer`, or `### Research`. And `pageChanges` returns `ariaChanges ?? null`,
+which renders nothing when the diff is empty or `previousState` is null.
+
+- `### Changes` renders on every action envelope, showing `no change` explicitly when the tree is
+  identical. A caller can then tell "nothing happened" from "prima did not say".
+- `renderOutcome` stops being mutually exclusive: `### Changes` renders alongside the command's
+  own outcome section.
+- Prima captures an explicit before-snapshot rather than relying on whatever `stateManager`
+  holds at process start.
+- New `### Steps` block for `do`: one line per instruction, each naming the ariaDiff entry that
+  proves it, or marked `unproven`.
+
+### Refs must never reach the diff or hash pipeline
+
+The ref-bearing snapshot is a **context artifact only**. Refs are stripped before hashing and
+diffing. Storing the `mode: 'ai'` output in `ActionResult.ariaSnapshot` would poison every
+`### Changes` block, because Playwright renumbers refs on each call. Measured on an identical
+page whose refs merely shifted:
+
+```
+ref churn only, page identical → diff count = 6
+  added:   button "Cancel" [ref=e21], button "Save" [ref=e20], textbox "Name" [ref=e22]
+  removed: button "Cancel" [ref=e11], button "Save" [ref=e10], textbox "Name" [ref=e12]
+```
+
+Six phantom entries for a page that did not change. Capture ref-bearing and ref-free variants,
+and feed only the ref-free one to `diffAriaSnapshots` and `getStateHash`.
+
+---
+
+## 4. Executor prompt
+
+`instructionSystemPrompt` (`prima.ts:493`) already says to stop when every instruction is done,
+but nothing tracks per-instruction completion, so the loop runs until the model stops calling
+tools. Two rules are added, stated as general principles rather than as counter-examples from
+any debugging session:
+
+- Act only on the listed instructions. An adjacent action that appears helpful is out of scope;
+  report it as an observation instead of performing it.
+- For each instruction, cite the observed page change that proves it. An instruction that cannot
+  be tied to an observed change is reported unproven rather than claimed as done.
+
+The prompt also states the ref contract: act on refs from the current context injection; refs
+from an earlier injection are dead.
+
+---
+
+## 5. Attachment and discovery
+
+Three separate faults, all confirmed empirically.
+
+**Connect with the daemon's own build when attached.** `connectDescriptor` (`prima.ts:374`)
+tries prima's own playwright first and only falls back to `descriptor.playwrightLib` if connect
+fails. Connect *succeeds* across builds, so the fallback is never reached — and then the tier-2
+snapshot breaks:
+
+| client lib | `connect()` | `ariaSnapshot({mode:'ai'})` |
+|---|---|---|
+| own playwright 1.62.1 | ok | `locator.ariaSnapshot: timeout: expected float, got undefined` |
+| daemon playwright-core 1.62.0-alpha | ok | ok, 3376 bytes, `aria-ref=e1` → 1 match |
+
+In attached mode, prefer `descriptor.playwrightLib` when present and fall back to our own. Carry
+`playwrightLib` through the `--endpoint` path too, which currently hardcodes `''`.
+
+**Stop keying discovery on `workspaceDir`.** No `@playwright/cli` release writes that field —
+verified on 0.1.13 and 0.1.17. `parseDescriptor` (`pw-registry.ts:56`) requires it and
+`selectDescriptor` filters on it, so every descriptor is dropped and discovery finds nothing no
+matter what is installed. Resolution becomes: `--endpoint` → `--pw-session <title>` →
+`PLAYWRIGHT_CLI_SESSION` → live descriptor titled `default` → the single live descriptor →
+tool error listing candidate titles. Liveness-probe before selecting.
+
+**Bump the playwright pin to `^1.62`.** `playwright@^1.60` could not `connect()` to a 1.61/1.62
+browser server at all; 1.62.1 connects. The pin is the reason the original review concluded
+attach was broken outright.
+
+Consequences: `browser list` shows attachable sessions rather than reporting none while one is
+live, and the no-browser error stops advising `playwright-cli open <url>` to someone who already
+ran it.
+
+---
+
+## 6. `verify` honesty
+
+`rules/navigator/verification-actions.md` offers nine assertions — `see`, `seeElement`,
+`seeInField`, `seeInTitle`, `seeInSource` and their `dontSee*` counterparts — none of which
+express enabled, disabled, checked, selected, or expanded. A claim about interactive state is
+therefore unprovable by construction, and the field run reported a working feature as failing:
+
+```
+verify "the Save button in the skill editor is now enabled ..."
+→ passed: false, code: (empty), evidence: no assertion held on the current page
+```
+
+The app was correct — `● unsaved` was displayed and the button was enabled.
+
+- Add state assertions to the rule.
+- `verify` distinguishes **assertion failed** from **could not express this assertion**. The
+  second is not a test failure and must not be reported as one.
+- With §7's compaction fix, `verify` reads state from the same ref-bearing snapshot the tier-2
+  ladder produces.
+
+---
+
+## 7. Prerequisite fix — ARIA compaction drops refs and state
+
+`compactAriaSnapshot` keeps only the first bracket group on a line. Playwright emits state
+attributes before `[ref=]`, so every stateful control loses its handle. Measured:
+
+```
+button "Plain"    [ref=e10]              → ref KEPT
+button "Active"   [active]   [ref=e13]   → ref LOST
+button "Disabled" [disabled] [ref=e14]   → ref LOST
+button "Pressed"  [pressed]  [ref=e15]   → ref LOST
+button "Expanded" [expanded] [ref=e16]   → ref LOST
+checkbox "Checked" [checked] [ref=e17]   → ref LOST
+button "Cursor"   [ref=e18] [cursor=pointer] → ref KEPT
+```
+
+The controls most worth acting on and asserting about are exactly the ones stripped of their
+handle. **Keep every bracket group on a line.** No allow-list, no drop-list — parsing one group
+and discarding the rest is the whole bug, and any rule about which groups survive re-creates it
+the next time Playwright adds an attribute. This fix is a prerequisite for §1 tier 2 and enables
+§6.
+
+---
+
+## 8. Envelope hygiene
+
+- `used:` carries the winning line only — no concatenated ladder attempts, no comment lines. The
+  field run produced `I.click(".sidebar button:has-text("Workflows")")`, which is not valid
+  JavaScript, and a `// 1. Open dialog...` comment inside the code block.
+- `click` and `fill` stop labelling themselves `do` in `command:`.
+- `network.jsonl` is written and advertised only when requests were actually captured. It was
+  0 bytes across all 18 runs while being advertised in every envelope; an artifact line that
+  points at an empty file is worse than no line.
+- Research annotation overlays are removed from the DOM after use. The browser is shared with
+  playwright-cli, and leftover `Legend` / `e8` / `e10` nodes appeared in its next snapshot.
+- Commands stop requiring a URL when attached to a browser already on a page.
+- A redirect that preserves origin and path counts as navigation success. The app's
+  `/` → `/?session=<uuid>&ws=1` redirect cost 3m00s and eight attempts under the old heal path,
+  and a hard tool failure against a prima-owned browser — in an envelope whose own inlined ARIA
+  proved the page had loaded.
+
+---
+
+## Testing
+
+- **Unit** — envelope rendering with `### Changes` always present, including the `no change`
+  form and the combination with `### Verdict` / `### Answer` / `### Research`; compaction
+  preserving every bracket group across the §7 combinations and any order of them; ref-free
+  diffing (the six-phantom case must yield zero); descriptor selection without `workspaceDir`,
+  including the ambiguous multi-session error.
+- **Ref resolution** — a ref resolves to an attribute-based `clickXPath` matching exactly one
+  element, and still matching after unrelated siblings are added or removed; a ref that resolves
+  to zero or many fails rather than falling back to a guessed locator.
+- **Integration** — `do` prompt behaviour through the existing `@copilotkit/aimock` harness per
+  `docs/contributing/ai-integration-tests.md`: instructions performed and nothing beyond them,
+  per-instruction proof citation, unproven reporting. Fictional fixture data only.
+- **End-to-end** — against a local fixture: a ref named from the snapshot clicks the element it
+  names and no other; a failing `pw` returns `ok: false` with compact ARIA and never a
+  substituted action; attach to a live playwright-cli session with no descriptor editing; a
+  session-param redirect resolves as success.
+
+---
+
+## Decisions Log
+
+- Heal is deleted outright rather than constrained to same-target recovery. No flag, no opt-in.
+- `do` perception is a four-tier ladder: research map, ARIA with refs, compact HTML, vision for
+  click.
+- Refs come from Playwright's native `aria-ref=` engine. No eidx attribute stamping, so the
+  shared browser's DOM is not mutated.
+- Ref acting lives in `boat/prima/src/tools.ts`, not in core; `click` and `hover` are untouched.
+  Extending a shared tool would show Tester a `ref` parameter it can only fill by inventing one,
+  and would weaken `commands` for every caller.
+- A ref resolves through `WebElement` to an attribute-based `clickXPath`. The absolute positional
+  `xpath` is not a fallback — `fromRawData` never populates it on the live-locator path, and it
+  would be the fragile choice regardless.
+- A resolved `clickXPath` must match exactly one element. A dead or ambiguous ref is a failure,
+  never a fallback to guessed locators.
+- ARIA compaction keeps every bracket group. No allow-list of attributes to preserve.
+- Refs are a context artifact only, stripped before hashing and diffing.
+- Ref lifetime is one context injection; the loop re-snapshots on state-hash change.
+- Tier 1 reads maps via `getPreviousResearch`; the trigger is StateManager visit count.
+- Discovery matches on title plus liveness; `workspaceDir` is abandoned as a key.
+- Attached mode connects with `descriptor.playwrightLib` first, because connect succeeds across
+  builds but `ariaSnapshot` does not.
+- The playwright pin moves to `^1.62`.
+- `verify` reports inexpressible assertions as inexpressible, never as failures, and does not
+  record them as verifications — a claim that could not be checked must not be remembered as
+  one that failed.
+- `do` carries a prima-shaped `context` tool that descends the ladder — fresh refs first, capped
+  markup on a repeat call. The shared `context` from `createAgentTools` is not reused: it returns
+  a ref-less tree and an HTML dump.
+- The baseline snapshot is captured lazily when a command needs a diff, not in `start()`, which
+  runs before a page is loaded.

package/docs/web-testing/agents.md

@@ -0,0 +1,158 @@
+# AI Agents
+
+Explorbot splits the testing workflow across specialized AI agents. Each agent handles one part of the work, which keeps it focused and keeps token costs down.
+
+## Agent Overview
+
+```mermaid
+flowchart LR
+    A[Navigator] --> B[Researcher] --> C[Planner] --> D[Tester]
+    A -- "goes to page" --> B
+    B -- "analyzes UI" --> C
+    C -- "suggests tests" --> D
+    D -- "runs tests" --> A
+    E[Pilot] -.->|supervises| D
+```
+
+## Navigator Agent
+
+Handles browser interactions: clicks, form fills, and navigation.
+
+The Navigator runs CodeceptJS commands in the browser. When a selector fails, it tries other locator strategies and resolves the interaction without stopping the run. It remembers what worked and what didn't, so failed selectors don't keep killing your runs and tests survive UI changes.
+
+Commands that use Navigator:
+- `/navigate <target>`
+- `I.click()`, `I.fillField()`, `I.amOnPage()`, etc.
+
+## Researcher Agent
+
+Analyzes pages to find what's actually on them.
+
+The Researcher discovers every interactive element, including content hidden in accordions, dropdowns, and modals. It maps navigation paths and form structures, extracts data from tables and lists, and filters out noise like cookie banners and ads. The result is a complete map of what you can test, with form validation rules documented.
+
+Commands that use Researcher:
+- `npx explorbot research /path` (CLI)
+- `/research [path]` (TUI)
+- `/research --deep` — expand hidden elements
+- `/research --data` — extract page data
+
+Explicit research always captures a screenshot; a configured vision model analyzes it.
+
+See [Researcher Agent](./researcher.md) for configuration and usage.
+
+## Planner Agent
+
+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.
+
+Commands that use Planner:
+- `/plan [--focus <feature>]`
+- `/explore`
+
+See [Planner Agent](./planner.md) for planning styles, customization, and configuration.
+
+## Tester Agent
+
+Runs the planned scenarios.
+
+The Tester executes scenarios step by step and adapts when something goes wrong. It tracks state changes during execution, records actual results against expected ones, and uses research context to make decisions. It handles unexpected modals and popups, recovers from minor failures on its own, and produces detailed execution logs.
+
+Commands that use Tester:
+- `/test [scenario]`
+- `/explore`
+
+## Pilot Agent
+
+Supervises the Tester and steps in when a test gets stuck.
+
+The Pilot keeps a separate conversation to track progress over time. It detects stuck patterns — loops, repeated failures, no page changes — and decides what context the Tester needs next (HTML, ARIA, UI map). When automated recovery fails, it asks the user for help instead of giving up.
+
+Because the Pilot sees only tool summaries rather than raw HTML, you can run it on a smarter model without a token cost explosion.
+
+The Pilot intervenes when:
+- Actions succeed but the page doesn't change (wrong element)
+- The same action repeats several times (loop)
+- The same locator keeps failing (need a different approach)
+- Only research or context calls run, with no action tools (no progress)
+
+## Analyst Agent
+
+Produces a human-readable session report after `/explore` and `/freesail` runs.
+
+The Analyst reads every test in the session — scenario, expected outcome, final result, notes, and step log. It clusters findings by root cause: three tests that fail on the same control become one defect with three test references, not three rows. It separates product defects from automation problems, so an element the test could not click is not reported as a bug.
+
+The report is plain markdown: a one-to-two sentence headline about the feature state (no test counts), then `## Coverage`, `## What works`, `## Defects` (each with a `[High]`/`[Medium]`/`[Low]` severity tag, reproduce steps, and one-line evidence), `## UX issues`, and `## Execution Issues`. Empty sections are omitted.
+
+It runs automatically at the end of `/explore` (per-run) and on app exit (session-wide, across multiple `/explore` or `/freesail` runs). The same markdown goes to the console, to `output/reports/<mode>-<sessionName>.md`, and — when the reporter is enabled — to the Testomat.io run description.
+
+Configuration:
+
+```javascript
+export default {
+  ai: {
+    agents: {
+      analyst: {
+        // model: openai('gpt-4o'),       // override the model
+        // systemPrompt: 'Focus on...',   // append guidance to the prompt
+        // enabled: false,                // disable the analyst entirely
+      },
+    },
+  },
+};
+```
+
+The Analyst resolves its model like other agentic tasks: the agent-specific `model`, then `ai.agenticModel`, then `ai.model`.
+
+## Captain Agent
+
+Handles your direct requests in the TUI and recovers the session when something breaks.
+
+The Captain steps in when a slash command isn't enough — answering questions about your setup, inspecting tests and page states, and reading recent output before it replies. It works in four modes:
+
+- **idle** — plan management, project inspection, knowledge and experience files; available before any page loads
+- **web** — page interaction, navigation, and browser diagnostics
+- **test** — test timeline, state inspection, generated code and logs
+- **heal** — browser and test recovery when an active test loses its page or browser
+
+When a test hits a fatal browser error, the Captain tries to recover — reload, restart the browser, open a fresh tab, or close extra tabs — before the test is stopped, then tells the Tester how to continue. It runs on explicit TUI requests and on test interrupts (stop, pass, skip, or redirect a running test).
+
+## Per-Agent Model Configuration
+
+Use different models for different agents to control cost:
+
+```javascript
+export default {
+  ai: {
+    model: groq('openai/gpt-oss-20b'),
+    visionModel: groq('meta-llama/llama-4-scout-17b-16e-instruct'),
+    agents: {
+      navigator: { model: groq('openai/gpt-oss-20b') },
+      researcher: { model: groq('openai/gpt-oss-20b') },
+      planner: { model: groq('openai/gpt-oss-20b') },
+      tester: { model: groq('openai/gpt-oss-20b'), progressCheckInterval: 5 },
+      pilot: { stepsToReview: 5 },
+    },
+  },
+};
+```
+
+Typical choices:
+- Navigator needs fast responses for real-time interaction
+- Researcher benefits from vision
+- Planner can use a larger model for better test design
+- Tester needs tool use for execution
+- Pilot can use a smarter model — it only processes tool summaries, not HTML or ARIA
+
+## How Agents Communicate
+
+Agents share context through four channels:
+
+1. **State Manager** — tracks the current page, URL, and navigation history
+2. **Research Results** — structured page analysis available to Planner and Tester
+3. **Experience Files** — patterns learned across sessions. Injected as a compact table of contents (file tags plus section headings) rather than full bodies; agents pull individual sections on demand via the `learnExperience` tool
+4. **Knowledge Files** — domain knowledge you provide
+
+Each agent keeps its context minimal to hold costs down. Agents request specific information when they need it instead of carrying full conversation history.
+
+The Pilot keeps a separate conversation from the Tester. The Tester's conversation carries heavy HTML and ARIA context; the Pilot sees only tool execution summaries (what succeeded, what failed, what changed). That lets the Pilot run on expensive models without a token cost explosion.