explorbot 0.2.3 → 0.2.5

package/dist/src/utils/logger.js

@@ -52,13 +52,19 @@ const debugFilter = new DebugFilter();
 class ConsoleDestination {
     verboseMode = false;
     forceEnabled = false;
+    quiet = false;
     recentSteps = new RecentStepFilter();
     isEnabled() {
+        if (this.quiet)
+            return false;
         return this.forceEnabled || !process.env.INK_RUNNING;
     }
     forceEnable(enabled) {
         this.forceEnabled = enabled;
     }
+    setQuiet(enabled) {
+        this.quiet = enabled;
+    }
     setVerboseMode(enabled) {
         this.verboseMode = enabled;
     }
@@ -113,6 +119,9 @@ class DebugDestination {
     }
     setVerboseMode(enabled) {
         this.verboseMode = enabled;
+        // the debug package reads DEBUG when it loads, so a namespace turned on later needs enabling by hand
+        if (enabled)
+            debug.enable(process.env.DEBUG || 'explorbot:*');
     }
     write(namespace, ...args) {
         if (!this.isNamespaceEnabled(namespace))
@@ -296,6 +305,7 @@ class Logger {
     span = new SpanDestination();
     react = new ReactDestination();
     captain = new CaptainDestination();
+    extra = [];
     truncateTags = ['page_html'];
     constructor() { }
     static getInstance() {
@@ -317,9 +327,17 @@ class Logger {
     setPreserveConsoleLogs(enabled) {
         this.console.forceEnable(enabled);
     }
+    setQuietMode(enabled) {
+        this.console.setQuiet(enabled);
+    }
     isVerboseMode() {
         return this.debugDestination.isEnabled();
     }
+    addDestination(destination) {
+        if (this.extra.includes(destination))
+            return;
+        this.extra.push(destination);
+    }
     registerLogPane(addLog) {
         this.react.registerLogPane(addLog);
     }
@@ -388,6 +406,14 @@ class Logger {
             }
             return;
         }
+        if (type === 'data') {
+            const entry = { type, content: String(args[0]), timestamp: new Date(), originalArgs: args };
+            for (const destination of this.extra) {
+                if (destination.isEnabled())
+                    destination.write(entry);
+            }
+            return;
+        }
         const options = this.extractLogOptions(type, args);
         let content = this.processArgs(args);
         if (type === 'step' && args[0]?.toCode) {
@@ -406,6 +432,10 @@ class Logger {
             this.span.write(entry);
         if (this.captain.isEnabled())
             this.captain.write(entry);
+        for (const destination of this.extra) {
+            if (destination.isEnabled())
+                destination.write(entry);
+        }
         if (process.env.INK_RUNNING) {
             this.react.write(entry);
         }
@@ -475,9 +505,11 @@ export const startLogCapture = () => logger.captain.startCapture();
 export const stopLogCapture = () => logger.captain.stopCapture();
 export const setVerboseMode = (enabled) => logger.setVerboseMode(enabled);
 export const setPreserveConsoleLogs = (enabled) => logger.setPreserveConsoleLogs(enabled);
+export const setQuietMode = (enabled) => logger.setQuietMode(enabled);
 export const isVerboseMode = () => logger.isVerboseMode();
 export const setDebugMode = (enabled) => logger.setDebugMode(enabled);
 export const isDebugMode = () => logger.isDebugMode();
+export const addDestination = (destination) => logger.addDestination(destination);
 export const registerLogPane = (addLog) => logger.registerLogPane(addLog);
 export const unregisterLogPane = (addLog) => logger.unregisterLogPane(addLog);
 export const addTruncateTag = (tagName) => logger.addTruncateTag(tagName);

package/dist/src/utils/page-readiness.js

@@ -3,9 +3,26 @@ export async function waitForPageReadiness(page, options = {}) {
         return;
     const timeout = options.timeout ?? 6000;
     await page.waitForLoadState?.('domcontentloaded', { timeout })?.catch(() => { });
-    await Promise.race([waitForNetworkIdle(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => { });
+    await Promise.race([waitForNetworkIdle(page, timeout), waitForDomQuiet(page, timeout), waitForVisibleSpinnersHidden(page, options.spinnerSelectors || [], timeout), sleep(timeout)]).catch(() => { });
     await waitForPageBodyContent(page, timeout);
 }
+const DOM_QUIET_MS = 350;
+function waitForDomQuiet(page, timeout) {
+    if (!page?.waitForFunction)
+        return new Promise(() => { });
+    return page
+        .waitForFunction((quiet) => {
+        const store = window;
+        if (!store.__explorbotDomQuiet) {
+            store.__explorbotDomQuiet = { last: Date.now() };
+            new MutationObserver(() => {
+                store.__explorbotDomQuiet.last = Date.now();
+            }).observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+        }
+        return Date.now() - store.__explorbotDomQuiet.last >= quiet;
+    }, DOM_QUIET_MS, { timeout, polling: 100 })
+        .catch(() => { });
+}
 function waitForNetworkIdle(page, timeout) {
     if (!page?.waitForLoadState)
         return Promise.resolve();

package/dist/src/utils/url-matcher.js

@@ -108,6 +108,9 @@ export function matchesNavigationUrl(expected, current) {
     if (!expectedPath.includes('#')) {
         currentPath = currentPath.split('#')[0];
     }
+    if (!expectedPath.includes('?')) {
+        currentPath = currentPath.split('?')[0];
+    }
     const normalize = (value) => value.replace(/^\/+|\/+$/g, '').toLowerCase();
     return normalize(expectedPath) === normalize(currentPath);
 }

package/dist/src/utils/web-element.d.ts

@@ -36,6 +36,8 @@ export declare class WebElement {
     static fromXPathMatch(m: XPathMatch): WebElement;
     static fromPlaywrightLocator(locator: any): Promise<WebElement | null>;
     static fromEidx(page: any, eidx: string): Promise<WebElement | null>;
+    static isAriaRef(ref: string): boolean;
+    static fromAriaRef(page: any, ref: string): Promise<WebElement | null>;
     static fromEidxList(page: any, eidxList: string[]): Promise<WebElement[]>;
     static commonAncestor(page: any, eidxList: string[]): Promise<WebElement | null>;
     static findByXPath(html: string, xpath: string): Promise<{

package/dist/src/utils/web-element.js

@@ -111,6 +111,14 @@ export class WebElement {
     static async fromEidx(page, eidx) {
         return WebElement.fromPlaywrightLocator(page.locator(`[${EXPLORBOT_ATTRS.eidx}="${eidx}"]`));
     }
+    static isAriaRef(ref) {
+        return /^(f\d+)?e\d+$/i.test(ref);
+    }
+    static async fromAriaRef(page, ref) {
+        if (!WebElement.isAriaRef(ref))
+            return null;
+        return WebElement.fromPlaywrightLocator(page.locator(`aria-ref=${ref}`));
+    }
     static async fromEidxList(page, eidxList) {
         const validEidxList = eidxList.filter((eidx) => /^e\d+$/i.test(eidx));
         if (validEidxList.length === 0)

package/dist/src/utils/web-sandbox.d.ts

@@ -1,4 +1,4 @@
 export declare function sanitizeCodeBlock(code: string): string;
 export declare function hasPlaywrightCommands(code: string): boolean;
 export declare function playwrightSandbox(page: any, code: string): Promise<any>;
-export declare function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): void;
+export declare function codeceptJSSandbox(actor: any, codeOrFn: string | ((...args: any[]) => void)): any;

package/dist/src/utils/web-sandbox.js

@@ -25,11 +25,10 @@ export function playwrightSandbox(page, code) {
 }
 export function codeceptJSSandbox(actor, codeOrFn) {
     if (typeof codeOrFn === 'function') {
-        codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
-        return;
+        return codeOrFn(actor, tryTo, retryTo, within, hopeThat, step, faker);
     }
     const run = createSandbox(CODECEPT_ARG_NAMES, codeOrFn);
-    run(actor, tryTo, retryTo, within, hopeThat, step, faker);
+    return run(actor, tryTo, retryTo, within, hopeThat, step, faker);
 }
 function createSandbox(argNames, body) {
     const fn = new Function(...argNames, ...SHADOWED_GLOBALS, `'use strict';\n${body}`);

package/docs/api-testing/basics.md

@@ -0,0 +1,90 @@
+# API Testing Basics
+
+Explorbot tests REST APIs the same way it tests web apps: it plans scenarios, runs them, and reports results — no test scripts. Two AI agents do the work.
+
+**Chief** reads your endpoint, its OpenAPI spec, and any [knowledge](../workflow/knowledge.md) you've written, then plans test scenarios: what to send, and what a correct response looks like.
+
+**Curler** takes each scenario and executes it as real HTTP requests, checking the responses with assertions.
+
+The plans Chief writes are ordinary Explorbot [test plans](../workflow/test-plans.md) — plain markdown you can read, edit, and commit. The web and API sides share the same plan format and the same [reporting](../workflow/reporting.md).
+
+## Configure
+
+Point Explorbot at your API by adding an `api` key to your `explorbot.config.js`:
+
+```javascript
+export default {
+  ai: {
+    model: openrouter('openai/gpt-oss-20b:nitro'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+  api: {
+    baseEndpoint: 'http://localhost:3000/api/v1',
+    spec: ['http://localhost:3000/api/openapi.json'],
+    headers: {
+      Authorization: 'Bearer <token>',
+    },
+  },
+};
+```
+
+- **`baseEndpoint`** (required) — the base URL prepended to every request. Test steps use relative paths like `/users`; Curler adds the base for you.
+- **`spec`** (required) — one or more OpenAPI specs, given as HTTP(S) URLs or local file paths, in YAML or JSON. Chief uses the spec to plan; Curler uses it to look up schemas. Both agents refuse to run without one.
+- **`headers`** — sent with every request. This is where API keys and auth tokens go.
+
+See the [full configuration reference](../reference/configuration.md) for every option and [providers](../basics/providers.md) for choosing an AI model.
+
+### Authenticating
+
+If a static token in `headers` is enough, you're done. If you need to log in and fetch a token first, use the `bootstrap` hook — it runs once before any tests, and whatever headers it returns merge into every later request:
+
+```javascript
+api: {
+  baseEndpoint: 'http://localhost:3000/api/v1',
+  spec: ['http://localhost:3000/api/openapi.json'],
+  bootstrap: async ({ baseEndpoint }) => {
+    const res = await fetch(`${baseEndpoint}/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email: 'admin@test.com', password: 'secret' }),
+    });
+    const { token } = await res.json();
+    return { Authorization: `Bearer ${token}` };
+  },
+},
+```
+
+A matching `teardown` hook runs after all tests finish — use it to clean up data.
+
+### A dedicated API project
+
+If you don't have a web `explorbot.config.js`, run `npx explorbot api init`. It asks for your base endpoint, spec, and a one-line description of the API, then writes a standalone `apibot.config.ts` (with an `ai` and `api` section) plus `output/` and `knowledge/` directories. When both files exist, `apibot.config.*` takes precedence over `explorbot.config.*`.
+
+## Your first run
+
+The minimal loop is plan, then test. Point Chief at an endpoint:
+
+```bash
+npx explorbot api plan /users
+```
+
+On startup Explorbot does a health check — a `GET /` against your base endpoint — so a bad URL or token fails immediately. Then Chief fetches sample data, reads the spec, and writes scenarios to `output/plans/users.md`. Hand that file to Curler:
+
+```bash
+npx explorbot api test output/plans/users.md
+```
+
+Curler runs the scenarios and prints how many passed and failed.
+
+## Output files
+
+| Output | Location | What it is |
+|--------|----------|------------|
+| Test plans | `output/plans/*.md` | Chief's scenarios — priorities, steps, expected outcomes |
+| Request logs | `output/requests/*.request.yaml` | Every HTTP request and response, for debugging |
+| Reports | via the shared [reporter](../workflow/reporting.md) | Pass/fail results, optionally sent to Testomat.io |
+
+## Next steps
+
+- [Planning API tests](./planning.md) — give Chief context and steer what it tests.
+- [Running API tests](./running-tests.md) — execute plans, read request logs, and run the full autonomous cycle.

package/docs/api-testing/planning.md

@@ -0,0 +1,57 @@
+# Planning API Tests
+
+Chief plans the scenarios; how good they are depends on the context you give it. Start by feeding it what it needs, then choose how aggressively it should probe.
+
+## Give Chief context
+
+**The API spec.** Chief reads the OpenAPI spec from your `spec` config to learn paths, methods, and request/response schemas. It also fetches live sample data from the endpoint — real IDs, enum values, field names — so the scenarios it writes reference data that actually exists instead of guessing. A good spec is the single biggest lever on plan quality.
+
+**Endpoint knowledge.** The spec says what an endpoint accepts, not how your business rules work. Add that with `know`:
+
+```bash
+npx explorbot api know /users "CRUD for users. Admin role required for writes. IDs are UUIDs."
+```
+
+This writes a markdown file under `knowledge/` with `endpoint:` frontmatter:
+
+```markdown
+---
+endpoint: "/users"
+---
+CRUD for users. Admin role required for writes. IDs are UUIDs.
+```
+
+Chief loads knowledge matching the endpoint it's planning. Running `know` again on the same endpoint appends to the file. See [knowledge](../workflow/knowledge.md) for how matching and files work.
+
+## Choose a planning style
+
+A style tells Chief what kind of tests to prioritize. Four ship by default:
+
+| Style | Focus |
+|-------|-------|
+| `normal` | Standard CRUD and happy paths — create, read, update, delete, verify status codes and schemas |
+| `curious` | Maximum coverage — every field, every enum value, arrays, defaults |
+| `psycho` | Malformed and extreme input — missing fields, injection payloads, wrong content types, boundary values |
+| `hacker` | Security probing — infers hidden endpoints and undocumented fields from responses, then tries privilege escalation, IDOR, and auth-bypass against them |
+
+Pick one with `--style`:
+
+```bash
+npx explorbot api plan /users --style hacker
+```
+
+Without `--style`, Chief uses `normal`. Styles are markdown files in `rules/chief/styles/`, so you can edit them or drop in your own. The cycling and customization mechanism is shared with web planning — see [planning styles](../workflow/planning-styles.md).
+
+## Replan from scratch or add to a plan
+
+By default a `plan` run generates a fresh set of scenarios. When a plan already exists in the same run, Chief compares against it and adds only new, non-duplicate scenarios — it won't re-propose behavior it already covered, even under a different style. Pass `--fresh` to discard the in-progress plan and start clean:
+
+```bash
+npx explorbot api plan /users --fresh
+```
+
+This is what [`explore`](./running-tests.md) uses to give each style its own clean plan.
+
+## Where plans land
+
+Chief saves each plan to `output/plans/`, named after the endpoint (for example `output/plans/users.md`). The file is a standard Explorbot [test plan](../workflow/test-plans.md): a suite of scenarios, each with steps, expected outcomes, and a priority. Read it, edit it, or commit it — then run it as described in [Running API tests](./running-tests.md).

package/docs/api-testing/running-tests.md

@@ -0,0 +1,55 @@
+# Running API Tests
+
+Once Chief has written a plan, Curler runs it. Curler reads each scenario and drives it to a pass or fail by making real HTTP requests and asserting on the responses.
+
+## Run a plan
+
+Point Curler at a plan file:
+
+```bash
+npx explorbot api test output/plans/users.md
+```
+
+With no index, Curler runs every pending test. Add an index to run a subset:
+
+```bash
+npx explorbot api test output/plans/users.md 1      # the first test
+npx explorbot api test output/plans/users.md 1-3    # tests 1 through 3
+npx explorbot api test output/plans/users.md 1,3,5  # specific tests
+npx explorbot api test output/plans/users.md *      # all pending tests
+```
+
+Curler prints a running log of requests and, at the end, how many tests passed and failed.
+
+## What Curler can do
+
+Curler works through AI tool calls. Its toolset:
+
+- **`request`** — make an HTTP request (any method: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS) with a body, headers, or query params. Returns status, timing, and a preview of the response; the full body is saved to disk. This is how Curler chains requests — it reads an ID from one response and feeds it into the next.
+- **`verifyStructure`** — check the response shape against a Zod schema. On success it reports the actual structure, which Curler uses to write correct value assertions.
+- **`verifyData`** — assert specific values with `expect()` (`toBe`, `toHaveProperty`, `toHaveLength`, and so on).
+- **`schemaFor`** — search the OpenAPI spec for related endpoints when a test needs to set up prerequisite data or discover a dependency.
+- **`record`** — note a finding or observation as the test runs.
+- **`finish`** / **`stop`** — mark the test complete, or abandon it when the scenario is impossible.
+
+Curler favors verification over trust: for writes, it follows up with a `GET` to confirm the data actually persisted rather than believing the write response alone.
+
+## Debugging with request logs
+
+Every request Curler makes is saved to `output/requests/` as a `.request.yaml` file — full URL, headers, body, status, and response. When a test fails and the log isn't enough, open these to see exactly what went over the wire, including a reproducible curl command.
+
+## Explore an endpoint end to end
+
+`explore` runs the whole cycle autonomously across every planning style:
+
+```bash
+npx explorbot api explore /users
+```
+
+For each style — `normal`, `curious`, `psycho`, `hacker` — it plans a fresh set of scenarios, runs them with Curler, and saves one plan file per style (`users_normal.md`, `users_hacker.md`, and so on). Scenarios are de-duplicated across styles, so the same test won't run twice. When every style is done, it prints the combined totals.
+
+Use `explore` to hammer an endpoint from every angle in one command; use `plan` plus `test` when you want to review or edit scenarios before running them.
+
+## Results and reporting
+
+Pass/fail results flow through Explorbot's shared reporter — the same one the web side uses. See [reporting](../workflow/reporting.md) for local reports and sending runs to Testomat.io.

package/docs/basics/getting-started.md

@@ -0,0 +1,140 @@
+# Getting Started
+
+Explorbot explores your web app, plans tests, and runs them — no test scripts. This guide gets you from zero to your first test in about ten minutes.
+
+The path is short: install, configure, tell it how to log in, then point it at one feature and let it work.
+
+## 1. Install
+
+```bash
+npm i explorbot --save
+npx playwright install
+```
+
+You need Node.js 24+ (or Bun), an AI provider key, and a modern terminal — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL. For the full compatibility checklist, see [Prerequisites](./prerequisites.md).
+
+## 2. Configure
+
+Create the config files:
+
+```bash
+npx explorbot init
+```
+
+This writes `explorbot.config.js`, an `.env` file for your keys, and an `output/` folder.
+
+Open `.env` and add your provider key:
+
+```bash
+OPENROUTER_API_KEY=sk-...
+```
+
+Then open `explorbot.config.js` and set your app's base URL — the host only, no path:
+
+```javascript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export default {
+  web: {
+    url: 'http://localhost:3000',
+  },
+  ai: {
+    model: openrouter('openai/gpt-oss-20b:nitro'),
+    visionModel: openrouter('google/gemma-4-31b-it'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+};
+```
+
+Explorbot uses three models. Pick each one for speed and cost:
+
+| Model | Config key | Used by | Pick |
+|-------|-----------|---------|------|
+| `model` | `ai.model` | Tester, Navigator, Researcher — they read HTML and ARIA on every step | a fast, cheap model (e.g. `openai/gpt-oss-20b:nitro`) |
+| `visionModel` | `ai.visionModel` | screenshot analysis | a vision model (e.g. `google/gemma-4-31b-it`) |
+| `agenticModel` | `ai.agenticModel` | Captain and Pilot — they read short action logs and make the big decisions | a smarter model (e.g. MiniMax 2.5, Grok Fast) |
+
+Captain and Pilot barely use tokens, so a smarter `agenticModel` improves results for almost no extra cost. OpenRouter is the simplest start — one key, many models. To use OpenAI, Anthropic, Groq, or others, see [Providers](./providers.md). For every config option, see [Configuration](../reference/configuration.md).
+
+## 3. Tell Explorbot how to log in
+
+Most apps need a login. Give Explorbot the credentials once, and it signs in on its own:
+
+```bash
+npx explorbot learn "/login" "Use credentials: admin@example.com / secret123"
+```
+
+This saves a knowledge file under `knowledge/`. Explorbot reads it whenever it opens the login page. Use `*` as the URL pattern for knowledge that applies to every page.
+
+To skip the login on later runs, add `--session`. Explorbot logs in once and restores the saved cookies next time:
+
+```bash
+npx explorbot start /login --session        # logs in, saves the session
+npx explorbot start /dashboard --session    # restores it, skips login
+```
+
+Keep real secrets in environment variables, and handle cookie banners, modals, and test data the same way — see [Customization](../web-testing/customization.md).
+
+## 4. Pick one feature to test
+
+Don't point Explorbot at your homepage. Start it on a single focused feature — a page with a clear, visible CRUD interface it can work with. Good first targets:
+
+- `/admin/projects`
+- `/posts`
+- `/admin/users`
+- any list-and-edit or settings page
+
+A page where you can create, edit, and delete items gives Explorbot an obvious job and a clear way to tell whether it worked.
+
+## 5. Run
+
+```bash
+npx explorbot start /admin/projects
+```
+
+The browser runs hidden by default. Add `--show` to watch it:
+
+```bash
+npx explorbot start /admin/projects --show
+```
+
+When the terminal UI opens, type `/explore`. Explorbot researches the page, plans tests, runs them, and repeats. To go one step at a time:
+
+> [!WARNING]
+> Run your first `/explore` against staging, a disposable workspace, or another isolated environment with non-production data. Explorbot can create, edit, and delete records while testing. Make sure the data is safe to change and easy to restore.
+
+```
+/research    # analyze the current page
+/plan        # propose test scenarios
+/test        # run the next test
+```
+
+### What a successful run looks like
+
+A completed exploration shows the test totals, a session analysis, the covered features, and any execution issues that need review:
+
+![Successful Explorbot run with two completed tests](../assets/successful-explore-run.png)
+
+## The concepts
+
+You have now touched everything Explorbot is built on. Here is the whole vocabulary, once:
+
+- **State** — where the bot is: the page URL plus its main headings (`h1`, `h2`). States anchor navigation, learning, and loop detection.
+- **Research** — reading a page. The Researcher agent maps forms, buttons, tables, and navigation into a UI map the other agents work from. Saved under `output/research/`. See [Researcher](../web-testing/researcher.md).
+- **Plan** — test scenarios invented from research, with priorities and expected outcomes. Markdown you can read and edit, in `output/plans/`. See [Test plans](../workflow/test-plans.md).
+- **Test** — one scenario executed step by step in the real browser. Passing tests are saved as runnable Playwright or CodeceptJS code in `output/tests/`. See [Automated tests](../web-testing/automated-tests.md).
+- **Knowledge** — facts you teach Explorbot: credentials, quirks, hints. Markdown files in `knowledge/`, matched to pages by URL — you wrote your first one in step 3. See [Knowledge](../workflow/knowledge.md).
+- **Experience** — what Explorbot learns by doing: failed attempts and the fixes that worked, saved in `experience/` and reused on every later run. Knowledge you write; experience it earns. See [Learning](../web-testing/basics.md#learning).
+- **Agents** — the AI workers behind each step: Researcher, Planner, Tester, Pilot, and more, each with its own job and model. See [Agents](../web-testing/agents.md).
+- **Report** — the end-of-session summary of defects, UX findings, and coverage in `output/reports/`. See [Reporting](../workflow/reporting.md).
+
+## Next steps
+
+- [Running Explorbot](./running.md) — the TUI you just used, the headless CLI, and when to use each.
+- [Customization](../web-testing/customization.md) — login, cookie bars, modals, and test data.
+- [Commands](../reference/commands.md) — every command, in the terminal and on the CLI.
+- [Knowledge](../workflow/knowledge.md) — teach Explorbot more about your app.

package/docs/basics/prerequisites.md

@@ -0,0 +1,63 @@
+# Application prerequisites
+
+## Security
+
+Give Explorbot an isolated environment that can never touch production data. This is your responsibility.
+
+Explorbot logs in with a user session and predefined credentials. Give that user limited permissions so it cannot harm the environment.
+
+Do not put real sensitive data in that environment. Explorbot has no secret redaction: anything the browser sees can end up in logs, AI prompts, and saved artifacts. Use disposable test data.
+
+Explorbot runs with few privileges. Explorbot cannot:
+
+- read or write local files (except the Captain agent, and only in the `knowledge/`, `experience/`, and `output/` folders)
+- fetch content from external websites (it stays on the configured site)
+- run Bash or CLI tools like `git` or `rm -rf` (except the Captain agent, for a limited set of actions)
+
+Explorbot follows a predefined script and a plan. It does not act on its own. Its main actions are web and API requests, which you should restrict.
+
+Run Explorbot on local, dev, or staging environments. You can still run it on production for regression testing, as long as its user has narrow access and works in a single project or workspace.
+
+## Data management
+
+Run Explorbot against an isolated workspace: a separate project inside your app, a staging environment, or similar. Pre-populate it with data. Explorbot reads that data to learn what the application does and proposes more meaningful tests.
+
+Explorbot can change or delete data through the web interface. Make sure you can reload that data if something breaks.
+
+To prepare:
+
+- Add a dataset to the pages Explorbot will visit, so it learns the app faster.
+- Keep that data non-critical and easy to restore.
+
+Explorbot works best on CRUD-heavy web applications:
+
+- SaaS platforms
+- ecommerce
+- ERP
+- admin panels
+- internal tools
+
+It is not a good fit for landing pages, blogs, CMS, or static sites.
+
+## Page management
+
+Explorbot uses URLs as anchor points when it navigates. Each change in the URL or the `h1`/`h2` headings creates a new state. This is how Explorbot tracks where it is and analyzes each transition. The `title` and `h3`/`h4` headings are captured too, but they do not define state identity.
+
+If your app does not change the URL on navigation, or skips `h1`/`h2` headings, navigation gets harder. Use URLs to identify your application states.
+
+Set edge cases and domain rules in [Knowledge files](../workflow/knowledge.md). These attach to page URLs.
+
+## Web elements
+
+Explorbot identifies elements through HTML, ARIA, and the screenshot. When one strategy fails, another usually works.
+
+Avoid long scrolling pages. They make visual identification harder.
+
+Explorbot reads ARIA attributes first, then falls back to HTML when ARIA elements are empty. An ARIA tree like this still works:
+
+```
+- role: button
+  text:
+```
+
+Following A11y standards across your site improves results. Explorbot makes fewer failed attempts on common elements.