explorbot 0.2.3 → 0.2.4

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.

package/docs/basics/providers.md

@@ -0,0 +1,362 @@
+# AI Provider Configuration
+
+Explorbot connects to AI providers through the [Vercel AI SDK](https://sdk.vercel.ai/). Use any supported provider, and mix providers across different models.
+
+> The `export default` config block inside each `<!-- START/END provider -->` marker is generated from [`models.json`](../../models.json). After editing that file, run `bunosh docs:sync`. Everything else — including the import blocks — is hand-written.
+
+## Requirements
+
+Your model must support:
+- Structured output (JSON mode)
+- Tool use (function calling)
+
+To analyze screenshots, you also need a vision-capable model.
+
+Explorbot uses three roles: 
+
+- `model` for token-heavy page reading of ARIA & HTMLs (cheap & fast).
+- `visionModel` for screenshot analysis
+- `agenticModel` as advisor and planner. 
+
+Pick a fast, cheap model for the first two and a stronger one for the third. When a provider has no recommended model for one of these roles, combine it with another provider for that role.
+
+### OpenRouter
+
+Start with OpenRouter. One key reaches [many providers and models](https://openrouter.ai/models).
+Openrouter is an optimal solution as you can balance the models and provider for best price and speed.
+So if your goal is to optimize costs, choose Openrouter.
+
+> Openrouter is recommended to start as it serves best models 
+
+Install the provider package:
+
+```bash
+npm i @openrouter/ai-sdk-provider
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:openrouter -->
+```javascript
+export default {
+  ai: {
+    model: openrouter('openai/gpt-oss-20b:nitro'),
+    visionModel: openrouter('google/gemma-4-31b-it:nitro'),
+    agenticModel: openrouter('google/gemma-4-31b-it:nitro'),
+  },
+};
+```
+<!-- END provider:openrouter -->
+
+Pick model IDs from [OpenRouter](https://openrouter.ai/) that support structured output and tools. The `:nitro` variants route to the fastest available host.
+
+### Groq
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/groq
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createGroq } from '@ai-sdk/groq';
+
+const groq = createGroq({
+  apiKey: process.env.GROQ_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:groq -->
+```javascript
+export default {
+  ai: {
+    model: groq('openai/gpt-oss-20b'),
+    visionModel: groq('qwen/qwen3.6-27b'),
+    agenticModel: groq('qwen/qwen3.6-27b'),
+  },
+};
+```
+<!-- END provider:groq -->
+
+The gpt-oss models are fast and cheap; the larger 120B handles the agenticModel role.
+
+### OpenAI
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/openai
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createOpenAI } from '@ai-sdk/openai';
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:openai -->
+```javascript
+export default {
+  ai: {
+    model: openai('gpt-5.4-nano'),
+    visionModel: openai('gpt-5.4-nano'),
+    agenticModel: openai('gpt-5.6-luna'),
+  },
+};
+```
+<!-- END provider:openai -->
+
+### Anthropic
+
+Claude Haiku is the only Anthropic model suited to Explorbot, and even it is too costly per token for the token-heavy roles, so we recommend it only for the low-volume agenticModel. Use a cheaper provider for `model` and `visionModel` (see [Multi-Provider Configuration](#multi-provider-configuration)).
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/anthropic
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createAnthropic } from '@ai-sdk/anthropic';
+
+const anthropic = createAnthropic({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+```
+
+Set the recommended model in the exported config:
+
+<!-- START provider:anthropic -->
+```javascript
+export default {
+  ai: {
+    agenticModel: anthropic('claude-haiku-4-5-20251001'),
+  },
+};
+```
+
+> [!NOTE]
+> This provider currently doesn't serve `model` and `visionModel`, which is required for Explorbot to run at optimal cost and speed.
+> It is recommended to pair it with another AI provider.
+<!-- END provider:anthropic -->
+
+### Azure OpenAI
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/azure
+```
+
+Import it inside `explorbot.config.ts` and create the client from your resource name and API key:
+
+```javascript
+import { createAzure } from '@ai-sdk/azure';
+
+const azure = createAzure({
+  resourceName: process.env.AZURE_RESOURCE_NAME,
+  apiKey: process.env.AZURE_API_KEY,
+});
+```
+
+Set the models in the exported config, using the deployment names you created in your resource:
+
+```javascript
+export default {
+  ai: {
+    model: azure('your-deployment-name'),
+    visionModel: azure('your-deployment-name'),
+    agenticModel: azure('your-deployment-name'),
+  },
+};
+```
+
+Azure addresses models by the deployment names you create in your resource, not by public model IDs. Use separate deployments if chat and vision run on different endpoints.
+
+### Google (Gemini)
+
+An API key from [Google AI Studio](https://aistudio.google.com/apikey) already has the Gemini API enabled. A key from the Google Cloud console may need the API enabled first, and service-account (Vertex Express) keys use a different API surface than the one this provider targets.
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/google
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+
+const google = createGoogleGenerativeAI({
+  apiKey: process.env.GOOGLE_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:google -->
+```javascript
+export default {
+  ai: {
+    model: google('gemini-3.1-flash-lite'),
+    visionModel: google('gemini-3.1-flash-lite'),
+    agenticModel: google('gemini-3.5-flash'),
+  },
+};
+```
+<!-- END provider:google -->
+
+The flash-lite tier is the cheapest current option for the token-heavy `model` and `visionModel` roles; the full flash is stronger for the low-volume `agenticModel`.
+
+On a free (no-billing) key the `agenticModel` is heavily rate-limited and will fail with quota errors mid-session — keep every role on the flash-lite model or enable billing. Google also retires older models for new accounts: `gemini-2.5-flash` and `gemini-2.5-flash-lite` return a 404 for keys created after their cutoff, and enabling billing does not bring them back.
+
+Note: Gemini models are slower than hosted OSS models on Groq or Cerebras. Everything works, sessions just take more wall-clock time.
+
+### Mistral
+
+Install the provider package:
+
+```bash
+npm i @ai-sdk/mistral
+```
+
+Import it inside `explorbot.config.ts` and create the client from your API key:
+
+```javascript
+import { createMistral } from '@ai-sdk/mistral';
+
+const mistral = createMistral({
+  apiKey: process.env.MISTRAL_API_KEY,
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:mistral -->
+```javascript
+export default {
+  ai: {
+    model: mistral('mistral-small-latest'),
+    visionModel: mistral('mistral-small-latest'),
+    agenticModel: mistral('mistral-large-latest'),
+  },
+};
+```
+<!-- END provider:mistral -->
+
+Mistral Small covers the token-heavy `model` and `visionModel` roles — it accepts image input, so it can read screenshots. Mistral Large, the larger multimodal flagship, handles the low-volume `agenticModel`. The `-latest` aliases track Mistral's newest release of each, so recommendations keep up as models ship.
+
+### Poolside
+
+Poolside serves an OpenAI-compatible endpoint, so it uses the OpenAI provider package with a custom `baseURL`:
+
+```bash
+npm i @ai-sdk/openai
+```
+
+Import it inside `explorbot.config.ts` and point the client at the poolside endpoint:
+
+```javascript
+import { createOpenAI } from '@ai-sdk/openai';
+
+const poolside = createOpenAI({
+  apiKey: process.env.POOLSIDE_API_KEY,
+  baseURL: 'https://inference.poolside.ai/v1',
+});
+```
+
+Set the recommended models in the exported config:
+
+<!-- START provider:poolside -->
+```javascript
+export default {
+  ai: {
+    model: poolside('poolside/laguna-xs-2.1'),
+  },
+};
+```
+
+> [!NOTE]
+> This provider currently doesn't serve `visionModel` and `agenticModel`, which is required for Explorbot to run at optimal cost and speed.
+> It is recommended to pair it with another AI provider.
+<!-- END provider:poolside -->
+
+Laguna XS is an agentic coding model — fast, cheap, and reliable at tool calling, which makes it a good fit for the token-heavy `model` role that reads page HTML and drives the browser.
+
+Keep `agenticModel` on another provider. Poolside's endpoint accepts `response_format: json_schema` but does not enforce it, so structured-output calls depend on the model volunteering valid JSON. Laguna XS usually does; Laguna S answers in prose instead, which makes it unusable for the Planner, Pilot, and Captain. Laguna S is also slow enough under page-sized prompts to hit Explorbot's request timeouts, so it is not a substitute for Laguna XS in the `model` role either.
+
+## Multi-Provider Configuration
+
+Mix clients the same way you assign `model`, `visionModel`, and `agenticModel`. Each field can use a different provider instance — a fast provider does the token-heavy reading while a stronger one makes the decisions:
+
+```javascript
+import { createGroq } from '@ai-sdk/groq';
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const groq = createGroq({ apiKey: process.env.GROQ_API_KEY });
+const openrouter = createOpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
+
+export default {
+  ai: {
+    model: groq('openai/gpt-oss-20b'),
+    visionModel: groq('meta-llama/llama-4-scout-17b-16e-instruct'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+};
+```
+
+## Per-Agent Model Configuration
+
+Any agent can override the defaults. Add an `agents` block and set per-agent options — a different `model` (using any client shown above) or a `reasoning` level:
+
+```javascript
+export default {
+  ai: {
+    // ...your model, visionModel, agenticModel...
+    agents: {
+      researcher: { reasoning: 'low' },
+      planner: { reasoning: 'none' },
+      tester: { reasoning: 'none' },
+    },
+  },
+};
+```
+
+See [Configuration](../reference/configuration.md) for every per-agent option.
+
+## Environment Variables
+
+Set your API key as an environment variable, or use a `.env` file in your project root:
+
+```bash
+export OPENROUTER_API_KEY=your-key-here
+export GROQ_API_KEY=your-key-here
+export CEREBRAS_API_KEY=your-key-here
+export OPENAI_API_KEY=your-key-here
+export ANTHROPIC_API_KEY=your-key-here
+export GOOGLE_API_KEY=your-key-here
+export MISTRAL_API_KEY=your-key-here
+```

package/docs/basics/running.md

@@ -0,0 +1,78 @@
+# Running Explorbot: TUI and CLI
+
+There are two ways to run Explorbot: an interactive terminal UI where you watch and steer, and plain CLI commands that do one job and exit. Same engine, same config, same artifacts — the difference is whether you are in the loop.
+
+| Use | Choose it when | Start with |
+|-----|----------------|------------|
+| **TUI** | You are learning, steering, or debugging interactively | `npx explorbot start /path` |
+| **CLI** | You want one repeatable task that prints a result and exits | `npx explorbot explore /path` |
+| **Persistent browser** | You run several local commands and want to avoid starting a new browser process each time | `npx explorbot browser start --show` |
+| **CI** | You need unattended, scheduled, or pipeline runs with saved reports | `npx explorbot explore /path --max-tests 10` |
+
+Persistent browser is an optimization for local TUI or CLI work, while CI uses CLI commands. Each command still creates a fresh browser context; use `--session` when cookies and login state must carry over. See [Persistent Browser](../reference/commands.md#persistent-browser) and [Continuous Integration](../workflow/ci.md) for setup details.
+
+## TUI mode
+
+`npx explorbot start` opens the interactive terminal UI. Pass a path to start on a specific page:
+
+```bash
+npx explorbot start /admin/projects
+```
+
+The screen splits into a log pane, where everything Explorbot does is printed as it happens, and an input line at the bottom. Type slash-commands to drive it:
+
+```
+/explore     # full loop: research, plan, test, repeat
+/research    # analyze the current page
+/plan        # propose test scenarios
+/test        # run the next test
+```
+
+You can also type raw CodeceptJS commands — `I.click('Save')`, `I.amOnPage('/login')` — and they execute in the browser immediately. In interactive mode the bot asks you for help when it gets stuck, instead of giving up.
+
+Use the TUI for:
+
+- **First runs.** You see every step and every mistake as it happens.
+- **Teaching Explorbot your app.** Watch it fail, add a knowledge file, retry — the tight loop is what the TUI is for.
+- **Debugging a failing scenario.** Replay it step by step with slash-commands and raw `I.*` commands.
+
+The TUI needs a modern terminal — iTerm2, WARP, Kitty, Ghostty, or Windows Terminal with WSL; see [Prerequisites](./prerequisites.md) for the compatibility notes.
+
+## CLI mode
+
+Every other command runs without the TUI: it launches a browser (headless by default), does its job, prints the result, and exits.
+
+| Command | What it does | Docs |
+|---------|--------------|------|
+| `explore <path>` | Research a page, plan tests, run them, move to sub-pages | [Web Testing Basics](../web-testing/basics.md) |
+| `plan <path>` | Generate a test plan as markdown and exit | [Test Plans](../workflow/test-plans.md) |
+| `test <planfile> [index]` | Run tests from a saved plan | [Test Plans](../workflow/test-plans.md) |
+| `rerun <file>` | Re-run generated tests with AI healing | [Rerun](../web-testing/rerun.md) |
+| `docs collect <url>` | Crawl pages and generate documentation | [Doc Collection](../doc-collection/basics.md) |
+| `api plan` / `api test` / `api explore` | Plan and run API tests | [API Testing](../api-testing/basics.md) |
+
+The full list, with every option, is in the [Commands reference](../reference/commands.md).
+
+### Exit codes
+
+CLI commands follow one rule: exit `0` when the run completed, `1` when the run itself failed — a config error, an unreachable start page, a provider that won't respond. Before exiting, the CLI shows a short session summary if anything happened during the run.
+
+For `explore` and `test`, a failing test does **not** change the exit code. The run completed; the failure is a result, printed in the console summary and recorded in the reports. So `npx explorbot explore / || echo broken` catches crashes, not bugs. To gate a pipeline on test results, read the reports — see [Continuous Integration](../workflow/ci.md).
+
+A few commands have sharper semantics you can script against:
+
+- `plan` exits `1` when no test scenarios could be generated.
+- `navigate <url>` exits `0` when the page was reached, `1` when not — a cheap "is the app up and can we log in" probe.
+- `api test` and `api explore` exit `1` when any test failed.
+
+## Flags that matter in both modes
+
+The browser runs headless by default; `--show` opens a visible window and `--headless` forces it hidden. `--session [file]` saves and restores the browser session (cookies, localStorage) — the default file is `output/session.json` — so login happens once and later runs skip it. `--incognito` runs without recording experience, useful for throwaway runs. `--verbose` prints debug logs. See the [Commands reference](../reference/commands.md) for the rest.
+
+## Driving Explorbot from other tools
+
+CLI mode makes Explorbot scriptable by anything that can run a shell command — including coding agents like Claude Code. Every input and output is plain markdown: plans land in `output/plans/`, reports in `output/reports/`, and hints live in `knowledge/`. An agent can run `explorbot plan /checkout`, read the generated plan, edit or extend it, run `explorbot test` on it, read the report, then write a knowledge file to fix what confused the bot — and iterate. No API or SDK needed; the files are the interface.
+
+## Running in CI
+
+Because CLI commands exit cleanly and keep their learning in cacheable directories, Explorbot fits scheduled pipelines: run `explore` nightly with a test budget, cache `experience/` and `output/` between runs, and upload the reports. See [Continuous Integration](../workflow/ci.md) for worked examples.