@m8i-51/shoal 0.1.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m8i-51
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,13 +2,16 @@
 
 # shoal
 
+[![npm](https://img.shields.io/npm/v/@m8i-51/shoal?color=red)](https://www.npmjs.com/package/@m8i-51/shoal)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Playwright](https://img.shields.io/badge/Playwright-browser-45ba4b?logo=playwright&logoColor=white)](https://playwright.dev/)
 [![Anthropic](https://img.shields.io/badge/Anthropic-Claude-blueviolet?logo=anthropic&logoColor=white)](https://www.anthropic.com/)
 
 Point it at any web app. Agents explore it and file GitHub Issues.
 
-shoal drops a swarm of agents onto a web app. Each agent has a distinct persona and evaluation lens — accessibility, security, business logic, data integrity, new user experience. They explore independently via API and real browser, then a triage agent deduplicates findings and files GitHub Issues.
+shoal drops a swarm of agents onto a web app. Each agent has a distinct persona and evaluation lens — accessibility, security, business logic, data integrity, new user experience, and goal alignment. They explore independently via API and real browser, then a triage agent deduplicates findings and files GitHub Issues.
+
+A **web dashboard** lets you start runs, monitor live progress, review findings by category, and track estimated LLM cost per run.
 
 No test scripts. No test data. No prior knowledge of the app required.
 
@@ -19,7 +22,7 @@ No test scripts. No test data. No prior knowledge of the app required.
 ```
 Target App (any URL)
         │
-        ▼  autonomously learns what the app does
+        ▼  autonomously learns what the app does + its goals
   Product Discovery
         │
         ▼  generates a user persona team for that app
@@ -42,6 +45,31 @@ Target App (any URL)
 
 ## Quick Start
 
+**Install globally:**
+
+```bash
+npm install -g @m8i-51/shoal
+npx playwright install chromium
+```
+
+Create a `.env` in your working directory:
+
+```env
+ANTHROPIC_API_KEY=sk-ant-...
+BASE_URL=http://localhost:3000
+# GITHUB_TOKEN=...   # optional: enables Issue creation
+# GITHUB_REPO=owner/repo
+```
+
+Then run:
+
+```bash
+shoal          # run agents against BASE_URL
+shoal serve    # open web dashboard at http://localhost:4000
+```
+
+**Or clone and develop locally:**
+
 ```bash
 git clone https://github.com/m8i-51/shoal
 cd shoal
@@ -52,6 +80,23 @@ npm start
 
 ---
 
+## Web dashboard
+
+```bash
+shoal serve        # global install
+# or
+npm run serve      # from cloned repo
+```
+
+Opens at `http://localhost:4000`. From there you can:
+
+- **Start a run** — configure agent count, target URL, and custom instructions
+- **Monitor live progress** — watch agents explore and file findings in real time
+- **Review past runs** — findings by category, agent count, duration, and estimated cost
+- **Edit app goals** — guide the goal-gap detector by defining what the app should achieve
+
+---
+
 ## Configuration
 
 | Variable | Default | Description |
@@ -70,20 +115,22 @@ npm start
 
 shoal loads `shoal.config.ts` from the **current working directory** at startup. Two common setups:
 
-**Option A — config inside the shoal repo** (simplest)
+**Option A — config in your project directory** (recommended)
 
 ```bash
-cp shoal.config.example.ts shoal.config.ts
-# edit shoal.config.ts, then:
-npm start
+# Copy the example from the repo (or create from scratch)
+curl -O https://raw.githubusercontent.com/m8i-51/shoal/main/shoal.config.example.ts
+mv shoal.config.example.ts shoal.config.ts
+# Edit shoal.config.ts, then:
+shoal
 ```
 
-**Option B — config in your project directory** (keeps shoal untouched)
+**Option B — config inside the cloned repo** (simplest for development)
 
 ```bash
-cp /path/to/shoal/shoal.config.example.ts ./shoal.config.ts
-# edit shoal.config.ts, then run shoal from your project root:
-BASE_URL=http://localhost:3000 npm start --prefix /path/to/shoal
+cp shoal.config.example.ts shoal.config.ts
+# edit shoal.config.ts, then:
+npm start
 ```
 
 `shoal.config.ts` must export a `target` object with two fields:
@@ -106,6 +153,21 @@ Alternatively, copy `targets/example.ts`, register it in `targets/index.ts`, and
 
 ---
 
+## Account Manager
+
+For apps that require login, shoal includes an Account Manager agent that autonomously discovers and tests authentication. It finds login pages, tests credentials from `test-accounts/` (gitignored), and injects session state into explorer agents so they can reach authenticated routes.
+
+Create `test-accounts/accounts.json` with your test credentials:
+
+```json
+[
+  { "email": "test@example.com", "password": "testpassword", "role": "user" },
+  { "email": "admin@example.com", "password": "adminpassword", "role": "admin" }
+]
+```
+
+---
+
 ## LLM providers
 
 shoal defaults to Anthropic Claude. To use a different provider, set these variables in `.env`:
@@ -114,8 +176,15 @@ shoal defaults to Anthropic Claude. To use a different provider, set these varia
 |---|---|
 | Anthropic (default) | `ANTHROPIC_API_KEY` |
 | OpenAI | `LLM_PROVIDER=openai`, `LLM_API_KEY`, `LLM_MODEL` |
+| OpenRouter | `LLM_PROVIDER=openrouter`, `LLM_API_KEY`, `LLM_MODEL` |
 | Codex (ChatGPT subscription) | run `npm run auth:codex` once, then `LLM_PROVIDER=codex` |
 | Ollama | `LLM_BASE_URL=http://localhost:11434/v1`, `LLM_MODEL` |
 | LM Studio | `LLM_BASE_URL=http://localhost:1234/v1`, `LLM_MODEL` |
 
 See `.env.example` for full examples.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m8i-51/shoal",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Multi-agent web exploration framework — finds bugs, UX issues, and missing features by running AI agents against your app",
   "bin": {