explorbot 0.0.1

package/LICENSE

@@ -0,0 +1,94 @@
+Elastic License 2.0 (ELv2)
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is Testomat.io (JESUSMARIA.DESIGN sp. z o.o.), the entity
+offering these terms, and the **software** is the software the licensor makes
+available under these terms, including any portion of it.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. **Control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your
+licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,267 @@
+# Explorbot
+
+**The vibe-testing agent for web applications.**
+
+![Explorbot Terminal UI](assets/screenshot.png)
+
+Explorbot explores your web app like a curious human would — clicking around, filling forms, finding bugs, and learning as it goes. No test scripts required. Just point it at your app and let it work.
+
+```bash
+explorbot start https://your-app.com
+```
+
+Explorbot is your first assitant in testing.
+It will do its best to use your application with no babysitting. It will use application and provide you valuable feedback.
+
+## Use Cases
+
+* Autonomously test web application or its parts
+* Discover test scenarios and get automated tests for them
+* Write manual test cases from exploring website
+* 24h/7d of monkey-testing for web application that can reveal hidden errors
+* Quick-test for MVPs and prototypes
+
+Explorbot can start testing features which were not covered by unit tests or browser tests.
+
+## Demo
+
+![Explorbot in action](assets/demo.gif)
+
+## Requirements
+
+- **Bun** (not Node.js)
+- **AI provider API key** — OpenRouter recommended; Groq, Cerebras, OpenAI, Anthropic, or others via [Vercel AI SDK](https://sdk.vercel.ai/providers)
+- **Modern terminal** — iTerm2, WARP, Kitty, Ghostty. WSL if running on Windows
+- **Compatible web app** — Check [docs/prerequisites.md](docs/prerequisites.md) to verify your app works with Explorbot
+
+## Quick Start
+
+**1. Install dependencies**
+
+```bash
+bun install
+bunx playwright install
+```
+
+**2. Initialize config**
+
+```bash
+explorbot init
+```
+
+**3. Edit `explorbot.config.js`** — set your app URL and AI provider:
+
+> [!IMPORTANT]
+> **Explorbot uses three types of models:**
+>
+> | Type | Config key | Purpose | Recommendation |
+> |------|-----------|---------|----------------|
+> | **model** | `ai.model` | Standard model for HTML/ARIA processing. Used by Tester, Navigator, Researcher. Should be fast and cheap — these agents are token-hungry. | e.g. `openai/gpt-oss-20b` |
+> | **visionModel** | `ai.visionModel` | Screenshot analysis. Used when agents need to visually inspect the page. | e.g. `meta-llama/llama-4-scout-17b-16e-instruct` |
+> | **agenticModel** | `ai.agenticModel` | Exceptional decision making. Used by Captain and Pilot — agents that read compact action logs and make high-level decisions. Benefits from a smarter model. | Strong agentic models but fast (MiniMax 2.5, Grok Fast, Qwen, …) |
+>
+> See [OpenRouter](https://openrouter.ai/rankings#performance) for latency-focused model picks.
+
+This example uses **OpenRouter** (one API key, many providers). Any Vercel AI SDK provider works; see [docs/providers.md](docs/providers.md).
+
+```javascript
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+
+const openrouter = createOpenRouter({
+  apiKey: process.env.OPENROUTER_API_KEY,
+});
+
+export default {
+  playwright: {
+    browser: 'chromium',
+    url: 'https://your-app.com',
+  },
+  ai: {
+    model: openrouter('openai/gpt-oss-20b'),
+    visionModel: openrouter('meta-llama/llama-4-scout-17b-16e-instruct'),
+    agenticModel: openrouter('minimax/minimax-m2.5:nitro'),
+  },
+};
+```
+
+> [!TIP]
+> Captain and Pilot barely use tokens (just action summaries), so a smarter `agenticModel` costs very little while significantly improving test quality. You can also override any agent's model individually via `ai.agents.<name>.model`.
+
+**4. Add knowledge** (optional but recommended)
+
+If your app requires authentication, tell Explorbot how to log in:
+
+```bash
+# Interactive mode
+explorbot learn
+
+# Or via CLI
+explorbot learn "/login" "Use credentials: admin@example.com / secret123"
+```
+
+> [!TIP]
+> Use `--session` to persist browser cookies and localStorage between runs. Log in once, and Explorbot will restore the session on next start:
+> ```bash
+> explorbot start /login --session          # saves to output/session.json
+> explorbot start /dashboard --session      # restores session, skips login
+> explorbot start /app --session auth.json  # custom session file
+> ```
+
+> [!NOTE]
+> Use `*` as URL pattern to add general knowledge that applies to all pages. See [docs/knowledge.md](docs/knowledge.md) for more.
+
+**5. Run**
+
+```bash
+explorbot start /admin/users
+```
+
+Start from a small functional area of your app (admin panel, settings, any CRUD section) so Explorbot can quickly understand its business purpose and context.
+
+Browser runs headless by default — use `--show` to see it:
+
+```bash
+explorbot start /settings --show
+```
+
+Requires a modern terminal (iTerm2, WARP, Kitty, Ghostty, Windows Terminal). On Windows, use WSL.
+
+## How It Works
+
+Explorbot explores websites, analyzes their UI, and proposes tests — which it can then execute. It controls its own browser through CodeceptJS → Playwright (no MCP involved).
+
+![Explorbot Architecture](assets/architecture.png)
+
+Run `/explore` in TUI or use `explorbot explore` from CLI to watch the cycle: research → plan → test → repeat.
+
+**Supporting components:**
+
+* **Pilot** — supervises Tester from a separate conversation: reviews action logs, detects stuck patterns, makes final pass/fail decisions. Uses `agenticModel` since it only processes compact summaries, not raw HTML
+* **Historian** — saves sessions as CodeceptJS code, learns from experience
+* **Quartermaster** — analyzes pages for A11y issues (axe-core + semantic)
+* **Reporter** — sends test results to Testomat.io
+
+## Basic Usage
+
+Once in the terminal UI:
+
+```
+/explore              # Full cycle: research → plan → test
+/research             # Analyze current page
+/plan                 # Generate test scenarios
+/test                 # Run next test
+/navigate /settings   # Go to a page
+```
+
+You can also run CodeceptJS commands directly:
+
+```
+I.click('Login')
+I.fillField('email', 'test@example.com')
+I.see('Welcome')
+```
+
+See [docs/commands.md](docs/commands.md) for all commands.
+
+> [!NOTE]
+> Most TUI commands also have CLI equivalents that run headless and exit. For example, `explorbot research <url>` and `explorbot plan <path>` work without launching TUI. See [docs/commands.md](docs/commands.md) for the full mapping.
+
+## What You Get
+
+| Output | Location | Description |
+|--------|----------|-------------|
+| Test files | `output/tests/*.js` | CodeceptJS tests you can run independently |
+| Test plans | `output/plans/*.md` | Markdown documentation of scenarios |
+| Experience | `./experience/` | What Explorbot learned about your app |
+
+## Two Ways to Run
+
+**Interactive mode** — Launch TUI, guide exploration, get real-time feedback:
+
+```bash
+explorbot start https://your-app.com
+```
+
+**Autonomous mode** — Non-interactive testing and planning:
+
+```bash
+explorbot explore /admin/users
+```
+
+**Freesail mode** — Fully autonomous, continuous exploration across multiple pages:
+
+```bash
+explorbot freesail /admin              # explore and test pages indefinitely
+explorbot freesail /app --deep         # depth-first: explore nearby pages first
+explorbot freesail /app --shallow      # breadth-first: spread across many pages
+explorbot freesail /app --scope /admin # restrict to URLs under /admin
+```
+
+Freesail navigates to a page, researches it, runs tests, then moves on to the next least-visited page — repeating until stopped. Also available as `/freesail` in TUI.
+
+## Core Philosophy
+
+**Strategic decisions are deterministic** — The workflow (research → plan → test) is predictable and consistent.
+
+**Tactical decisions are AI-driven** — How to click that button, what to do when a modal appears, how to recover from errors.
+
+**Cheap workers, smart managers** — Tester, Navigator, and Researcher are token-hungry agents that chew through HTML and ARIA on every step. They run on the fast, cheap `model`. Captain and Pilot are the decision-makers — they read only compact action logs and make high-level choices. Set `agenticModel` to a smarter model for better results at negligible extra cost.
+
+**Explorbot learns from its failures** — It uses previous experience interacting with a web page for faster and better decisions on next runs.
+
+**Explorbot needs your knowledge** — You adjust Explorbot prompts by passing suggestions, UI explanations, and domain knowledge as text files, which are loaded when the corresponding page is opened.
+
+When tuned, Explorbot **can run autonomously for hours** navigating a web application and trying different scenarios. You don't need to watch it. The more Explorbot runs, the more it learns and the more complex scenarios it can test.
+
+
+## Teaching Explorbot
+
+* **Knowledge** (`./knowledge/`) — Tell Explorbot about your app: credentials, form rules, navigation quirks. See [docs/knowledge.md](docs/knowledge.md).
+* **Rules** (`./rules/`) — Customize agent behavior with markdown files. Add page-specific instructions, override planning styles, or tune how agents work on different parts of your app. See [docs/configuration.md](docs/configuration.md#rules).
+* **Experience** (`./experience/`) — Explorbot learns automatically from successful interactions and saves what works.
+
+## Further Reading
+
+- [docs/prerequisites.md](docs/prerequisites.md) — Application compatibility checklist
+- [docs/commands.md](docs/commands.md) — Terminal command reference
+- [docs/knowledge.md](docs/knowledge.md) — Knowledge system and URL patterns
+- [docs/providers.md](docs/providers.md) — AI provider configuration
+- [docs/agents.md](docs/agents.md) — Agent descriptions and capabilities
+- [docs/planner.md](docs/planner.md) — Planner agent: planning styles and customization
+- [docs/scripting.md](docs/scripting.md) — Building custom autonomous scripts
+- [docs/observability.md](docs/observability.md) — Langfuse tracing and debugging
+- [docs/page-interaction.md](docs/page-interaction.md) — How agents interact with pages
+
+## FAQ
+
+**Can I run it in Cursor? or Claude Code?**
+No, Explorbot is a separate application designed for constant testing. Cursor, Codex, or Claude Code are coding agents — not relevant here.
+
+**Why do you hate Opus?**
+Opus is great for coding. Here we need a simple model that can consume lots of HTML tokens to find the relevant ones. Leave more interesting tasks to Opus.
+
+**Is that expensive?**
+No. With fast open models (e.g. `openai/gpt-oss-20b` on OpenRouter or Groq), expect roughly ~$1/hour of continuous run, depending on provider and traffic.
+
+**Does Explorbot have MCP?**
+Not yet.
+
+**Can I build my own agents with it?**
+Yes, use the programmatic API. See [docs/scripting.md](docs/scripting.md).
+
+**Ok, but I can do the same in Cursor with Playwright MCP!**
+Good luck running it on CI! Also, you'll need to check on it every 10 seconds to see how it's running the browser.
+
+## License
+
+Explorbot is licensed under the [Elastic License 2.0 (ELv2)](LICENSE).
+
+**Free for commercial use** — you can use Explorbot to test any application, including commercial products, without paying a license fee. You can modify it, self-host it, and integrate it into your workflow.
+
+The only restriction: you may not offer Explorbot itself as a hosted/managed service (i.e., resell it as a product). This license is used by Elastic, Grafana, and other open-source companies.
+
+Explorbot is built by [Testomat.io](https://testomat.io).
+
+---
+
+Explorbot learns as it explores. The more it tests your app, the better it gets at testing your app. That's vibe-testing.

package/assets/sample-files/sample.pdf

@@ -0,0 +1,21 @@
+%PDF-1.0
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>
+endobj
+xref
+0 4
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+trailer
+<< /Size 4 /Root 1 0 R >>
+startxref
+190
+%%EOF

package/dist/assets/sample-files/sample.pdf

@@ -0,0 +1,21 @@
+%PDF-1.0
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] >>
+endobj
+xref
+0 4
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+trailer
+<< /Size 4 /Root 1 0 R >>
+startxref
+190
+%%EOF