explorbot 0.2.3 → 0.2.5

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

package/docs/workflow/agentic-usage.md

@@ -0,0 +1,233 @@
+# Agentic Usage
+
+Explorbot is a terminal command, so a coding agent — Claude Code, Cursor, Codex, or your own script — can drive it the same way it drives `git` or `npm`. This page covers the two things an agent needs: getting Explorbot configured once, and handing it a test plan it wrote itself.
+
+The division of labour that works best: the agent decides *what* to test and writes it down as a plan; Explorbot figures out *how* to click through the app and reports what actually happened.
+
+## Start here: the global installation
+
+Configure models and keys once for the machine, and every later command works in any directory with no environment variables to remember:
+
+```bash
+npx explorbot init --global --provider openrouter --api-key sk-...
+npx explorbot explore https://app.example.com/login --max-tests 3
+```
+
+`init --global` writes `~/.explorbot/config.js` with the recommended model ids of this Explorbot version and stores the key in `~/.explorbot/.env`. It needs no terminal — with `--provider` there is no wizard, so an agent can run it unattended.
+
+The global config holds models and keys, never a site. Most commands carry the site themselves — `explore`, `plan`, `research`, `navigate`, `context`, `shell`, `freesail`, `docs collect`. The ones that take no URL argument — `test`, `learn`, `knows`, `experience`, `compact` — read it from `EXPLORBOT_URL`, and stop with `No site to explore` when it is unset:
+
+```bash
+EXPLORBOT_URL=https://app.example.com npx explorbot learn "/login" 'Sign in as ${env.APP_USER}'
+```
+
+This is the form to prefer. Each site explored gets its own folder under `~/.explorbot/sites/<host>/` holding `knowledge/`, `experience/`, and `output/`, so what Explorbot learns about an app is still there on the next run — the agent that explored `/checkout` yesterday does not start from zero today. Later runs can name the site by host instead of repeating the URL:
+
+```bash
+npx explorbot explore app.example.com/dashboard
+npx explorbot sites                                # what is registered, and when it last ran
+```
+
+The `EXPLORBOT_*` variables below still win over it: setting `EXPLORBOT_AI_PROVIDER` or `EXPLORBOT_AI_MODEL` builds the configuration from the environment and the global config is skipped. So an agent can install once and still override models or the URL per command.
+
+## One-liner API
+
+When nothing can be installed — a CI job, a container, someone else's machine — set `EXPLORBOT_AI_PROVIDER` and Explorbot builds a config from `EXPLORBOT_*` environment variables instead. Name a provider and you get its recommended models:
+
+```bash
+EXPLORBOT_URL=https://app.example.com \
+EXPLORBOT_AI_PROVIDER=openrouter \
+  npx explorbot explore /login --max-tests 3
+```
+
+No `init`, no config file, no project directory, no model IDs to look up. These variables win over the global installation, so a run can always be pinned to its own models. A project `explorbot.config.js` still wins over them, so adding these variables never changes the behavior of an existing project.
+
+### Variables
+
+<!-- START env -->
+| Variable | Required | Meaning |
+|---|---|---|
+| `EXPLORBOT_AI_PROVIDER` | yes | Provider name; fills every model role from its recommended models. Turns on config-free mode |
+| `EXPLORBOT_AI_MODEL` | no | Pins the main model — a model id for the provider, or a standalone provider/model-id |
+| `EXPLORBOT_URL` | yes | Base URL to test; the API boat reads it as the base endpoint |
+| `EXPLORBOT_VISION_MODEL` | no | Screenshot analysis; overrides the provider recommendation |
+| `EXPLORBOT_AGENTIC_MODEL` | no | Captain and Pilot decisions; overrides the provider recommendation |
+| `EXPLORBOT_OUTPUT` | no | Output root for states, plans, research, and reports. Defaults to the site dir under ~/.explorbot/sites |
+| `EXPLORBOT_EPHEMERAL` | no | Keep no state between runs — output goes to a fresh temp directory instead of the site dir |
+| `EXPLORBOT_KNOWLEDGE` | no | Inline knowledge text, applied to every page |
+| `EXPLORBOT_KNOWLEDGE_FILE` | no | Path to a knowledge markdown file |
+| `EXPLORBOT_API_SPEC` | no | OpenAPI spec path for the API boat |
+| `EXPLORBOT_NO_BANNER` | no | Suppress the startup banner, for machine-readable output |
+<!-- END env -->
+
+`EXPLORBOT_URL` is optional when the command itself carries an absolute URL, as `docs collect https://…` does. The [API boat](../api-testing/basics.md) reads it as the base endpoint.
+
+This table is generated from the registry in `src/config.ts`, which also feeds `explorbot --help` — so `npx explorbot --help` lists the same variables on any command, and an agent can discover them without reading these docs.
+
+### Naming models
+
+Set `EXPLORBOT_AI_PROVIDER` to a provider name and Explorbot uses that provider's recommended model for every role — the same IDs listed in [Providers](../basics/providers.md), maintained in [`models.json`](../../models.json):
+
+```bash
+EXPLORBOT_AI_PROVIDER=openrouter   # model, visionModel, and agenticModel all filled in
+```
+
+This is the form to reach for when you do not care which model runs, only that the run works. Recommendations change as models are released, so a provider name keeps up while a pinned ID does not.
+
+To pin the main model, add `EXPLORBOT_AI_MODEL`. With a provider set, it is the model id for that provider, used verbatim — slashes and all:
+
+```bash
+EXPLORBOT_AI_PROVIDER=openrouter \
+EXPLORBOT_AI_MODEL=openai/gpt-oss-120b:nitro \
+  npx explorbot explore /checkout
+```
+
+On its own, without a provider, `EXPLORBOT_AI_MODEL` must carry the provider as `provider/model-id`, and it sets only the main `model` — `visionModel` and `agenticModel` stay unset unless you add `EXPLORBOT_AI_PROVIDER` or set them explicitly. It splits on the **first** slash, so provider-qualified IDs survive intact:
+
+```
+openrouter/openai/gpt-oss-120b:nitro   → openrouter, model "openai/gpt-oss-120b:nitro"
+groq/openai/gpt-oss-20b                → groq, model "openai/gpt-oss-20b"
+anthropic/claude-haiku-4-5-20251001    → anthropic, model "claude-haiku-4-5-20251001"
+```
+
+`EXPLORBOT_VISION_MODEL` and `EXPLORBOT_AGENTIC_MODEL` override those roles the same way — a provider name for its recommendation, or `provider/model-id` to pin one. Mix the forms to take a provider's recommendations and override one role:
+
+```bash
+EXPLORBOT_AI_PROVIDER=groq \
+EXPLORBOT_AGENTIC_MODEL=anthropic \
+  npx explorbot explore /checkout
+```
+
+Supported providers: `openai`, `anthropic`, `google`, `groq`, `mistral`, `openrouter`, `sambanova`. Each is created with its conventional API-key variable — `OPENROUTER_API_KEY`, `GROQ_API_KEY`, `MISTRAL_API_KEY`, and so on.
+
+Not every provider has a recommendation for every role — Anthropic is recommended only for `agenticModel`, since Claude models are accurate but costly for token-heavy page reading. Naming a provider that has no recommendation for a role you asked for is an error that names the role, so combine providers as in the example above.
+
+A `.env` file in the working directory is loaded before the config lookup, so `EXPLORBOT_*` variables and API keys can live there instead of on the command line.
+
+### Knowledge without a project
+
+Both knowledge variables write into the run's knowledge directory, and both can be set at once.
+
+`EXPLORBOT_KNOWLEDGE` is the fast path for credentials — it applies to every page:
+
+```bash
+EXPLORBOT_KNOWLEDGE="Log in as admin@example.com / secret123. Dismiss the cookie banner first." \
+EXPLORBOT_URL=https://app.example.com \
+EXPLORBOT_AI_PROVIDER=openrouter \
+  npx explorbot explore /admin/users
+```
+
+`EXPLORBOT_KNOWLEDGE_FILE` points at a markdown file the agent wrote. Its frontmatter is preserved, so it can target specific URLs — see [Knowledge](./knowledge.md) for the format:
+
+```bash
+EXPLORBOT_KNOWLEDGE_FILE=./checkout-knowledge.md npx explorbot explore /checkout
+```
+
+### What this mode changes
+
+Config-free runs leave no trace in the working directory:
+
+- **Output goes to the site folder** — `~/.explorbot/sites/<host>/`, the same folder the global installation uses, so states, plans, research, and reports for one app collect in one place however the run was configured. `EXPLORBOT_OUTPUT` points them somewhere else. Read the path Explorbot resolved from the `Configuration built from EXPLORBOT_* environment variables. Output: …` line.
+- **`EXPLORBOT_EPHEMERAL=1` keeps nothing between runs** — output goes to a fresh temp directory instead, for throwaway CI jobs and demos. The [prima boat](../reference/commands.md#prima-boat) exposes the same switch as `--ephemeral`.
+- **Experience is written into the site folder.** What worked on a page is remembered and reused by later runs against the same host. `EXPLORBOT_EPHEMERAL=1` turns writing off, so an ephemeral run stays reproducible.
+- **The Historian is off.** No generated CodeceptJS or Playwright test files — that is the one thing the global installation gives that this mode does not. Plans and reports are still written.
+
+### Reading results
+
+Everything lands under the output root:
+
+| Path | Contents |
+|---|---|
+| `reports/<mode>-<session>.md` | Session report: coverage, defects, execution issues |
+| `plans/<page>.md` | The plan that was generated or executed |
+| `states/` | Per-state HTML, ARIA snapshots, and screenshots |
+| `research/` | UI maps produced by the Researcher |
+
+The report is the artifact to parse. It clusters findings by root cause and is written for a reader, not a machine.
+
+`explore` and `test` exit `0` whenever the session completes, and non-zero only when the run itself fails to start — a failing scenario is a result, not a crash. Do not read pass/fail from their exit code; read the report. `navigate` is the exception and exits `1` when a URL is unreachable, which makes it a useful pre-flight check.
+
+## Running agent-prepared plans
+
+A [test plan](./test-plans.md) is plain markdown. An agent that has read the codebase usually knows what a feature is supposed to do better than an agent looking at rendered HTML, so writing the plan and executing it are worth separating.
+
+Write the plan:
+
+```markdown
+<!-- suite -->
+# Checkout
+
+### Prerequisite
+
+* URL: /cart
+
+<!-- test
+priority: critical
+-->
+# Customer completes checkout with a saved card
+
+## Requirements
+/cart
+
+## Steps
+* Proceed to checkout from the cart
+* Pick the saved card as the payment method
+* Confirm the order
+
+## Expected
+* The order confirmation page shows an order number
+* The cart is empty afterwards
+```
+
+Then hand it to Explorbot:
+
+```bash
+EXPLORBOT_URL=https://app.example.com \
+EXPLORBOT_AI_PROVIDER=openrouter \
+  npx explorbot test checkout-plan.md '*'
+```
+
+The index argument selects tests: `1`, `1,3`, `1-5`, or `*` for all. The plan file is input only — Explorbot never rewrites it, so plans stay in version control next to the code they cover.
+
+Steps are guidance, not a script. The Tester adapts them to what the page actually shows, which is why steps should describe intent rather than selectors. Expected outcomes are the strict part: a test passes only when every one of them is verified. See the [Planner's outcome guidance](../web-testing/planner.md#built-in-styles) for what makes an outcome verifiable.
+
+To have Explorbot invent the scenarios instead, run `explorbot plan <path>` and read the generated file from `plans/`.
+
+## Inspecting a page without spending tokens
+
+Two commands help an agent orient itself before committing to a run:
+
+```bash
+npx explorbot context /login        # URL, headings, knowledge, interactive elements
+npx explorbot shell /login 'I.click("Sign in")'   # run one CodeceptJS command
+```
+
+`context` makes no AI calls. Use it to check that a page loads, that login knowledge applies, and that the elements a plan assumes are actually there.
+
+## The other boats
+
+The same variables drive API testing and doc collection.
+
+```bash
+EXPLORBOT_URL=https://api.example.com \
+EXPLORBOT_API_SPEC=./openapi.yaml \
+EXPLORBOT_AI_PROVIDER=openrouter \
+  npx explorbot api explore
+```
+
+```bash
+EXPLORBOT_AI_PROVIDER=openrouter \
+  npx explorbot docs collect https://app.example.com/dashboard --max-pages 20
+```
+
+`docs collect` takes its base URL from the absolute path argument, so `EXPLORBOT_URL` is optional there.
+
+Knowledge written by `EXPLORBOT_KNOWLEDGE` carries `endpoint: '*'` frontmatter alongside `url: '*'`, matching the convention `api init` and `api know` use. The API boat does not read knowledge at runtime yet; the frontmatter is there for when it does, and the web side ignores it.
+
+## See Also
+
+- [Test Plans](./test-plans.md) — the plan format in full
+- [Knowledge](./knowledge.md) — teaching Explorbot about your app
+- [Commands](../reference/commands.md) — every CLI command
+- [Continuous integration](./ci.md) — scheduled runs with cached experience
+- [Scripting](../reference/scripting.md) — the programmatic API when a CLI call is not enough

package/docs/workflow/application-spec.md

@@ -0,0 +1,73 @@
+# Application Specs
+
+An application spec is a versioned Markdown bundle that gives Explorbot previously collected information about an application. It can be produced by Docbot, another documentation tool, or by hand.
+
+Live HTML, ARIA, and screenshots remain the source of truth. Explorbot uses matching spec pages as supporting context and does not load the whole bundle into every prompt.
+
+## Configure
+
+Set the bundle directory in `explorbot.config.js`:
+
+```javascript
+export default {
+  dirs: {
+    spec: 'spec',
+  },
+};
+```
+
+Paths are resolved from the project directory. Use `--spec <path>` on a web command to override the configured bundle for one run. Both the bundle directory and its `index.md` path are accepted.
+
+## Bundle structure
+
+```text
+spec/
+|-- index.md
+`-- pages/
+    |-- home.md
+    `-- users.md
+```
+
+`index.md` is required and serves as a human-readable entry point. Its contents are not injected into agents. Page files may be nested anywhere below `pages/` and must use the contract below.
+
+## Page contract
+
+Every page is a Markdown file with YAML front matter:
+
+```markdown
+---
+format: explorbot-application-spec
+version: 1
+url: /users
+---
+
+# Users
+
+## Purpose
+
+Lists the application's users.
+
+## User Can
+
+- user can search users by name
+  Proof: A search field is visible above the user list.
+
+## User Might
+
+- user might export the user list
+  Signal: An unlabeled download control is present.
+```
+
+The front matter fields are mandatory:
+
+- `format` must be `explorbot-application-spec`.
+- `version` must be `1`.
+- `url` is the URL pattern used to select the page for the current browser state. It supports the same patterns as [knowledge files](./knowledge.md#url-patterns).
+
+The Markdown body is supplied to agents as written, so headings beyond those shown above are allowed. Use `User Can` only for observed capabilities and transitions. Put inferred or unverified capabilities under `User Might`; Explorbot will require confirmation from the live UI before relying on them.
+
+Screenshots and other relative links may be included for readers, but Explorbot currently consumes the Markdown text only.
+
+## 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.