site-agent-pro 1.0.0

package/README.md

@@ -0,0 +1,689 @@
+# Site Agent Pro
+
+> AI-powered browser agent that executes real user tasks on any website, captures step-by-step evidence, and produces scored, actionable reports.
+
+**Playwright** · **OpenAI / Ollama** · **axe-core** · **TypeScript** · **Zod**
+
+---
+
+## How It Works
+
+```
+User submits URL + tasks
+        │
+        ▼
+┌─────────────────────────────┐
+│  Chromium launches           │
+│  (desktop 1440×900           │
+│   or mobile 390×844)         │
+└──────────┬──────────────────┘
+           ▼
+┌─────────────────────────────┐
+│  For each task:              │
+│   1. Capture page state      │
+│   2. LLM plans next action   │
+│   3. Playwright executes it  │
+│   4. Repeat until done       │
+└──────────┬──────────────────┘
+           ▼
+┌─────────────────────────────┐
+│  Site checks:                │
+│  SEO · Performance ·         │
+│  Security · Accessibility ·  │
+│  Mobile · Content · CRO      │
+└──────────┬──────────────────┘
+           ▼
+┌─────────────────────────────┐
+│  LLM evaluates the run       │
+│  → Scored report (1-10)      │
+│  → HTML / Markdown / JSON    │
+│  → Activity replay animation │
+└─────────────────────────────┘
+```
+
+---
+
+## Features
+
+- **Task-driven execution** — the agent follows only the tasks you provide, nothing more
+- **Step-by-step evidence** — every interaction, page state, relevant console signal, and network failure is logged
+- **Ordered instruction parsing** — pasted instructions, bullet lists, JSON tasks, and uploaded text files are normalized into accepted task lanes
+- **Independent evaluation** — the LLM scores from captured evidence, not from the agent's own impressions
+- **Multi-agent perspectives** — run 1–5 agents with different personas on the same site, merged into one report
+- **Auth-aware** — detects login walls mid-run, fills signup forms, polls IMAP for OTP/verification emails
+- **Supplemental audits** — SEO crawl, security headers, performance timings, accessibility (axe-core), CRO signals, content readability, mobile layout
+- **Activity replay** — compact animated WebP that overlays all recorded agent actions onto the captured click frames
+- **Exchange-flow QA** — safely tests Naira/crypto buy and sell flows with harmless values and stops before real transfers
+- **Paystack Integration** — provision dedicated virtual Naira accounts for agents and execute **autonomous bank transfers** during tasks
+- **Dual LLM support** — OpenAI (GPT-5) for production, Ollama for local/private development
+- **Two deployment modes** — CLI or web dashboard, including Render web service deployment
+
+---
+
+## Quick Start
+
+> **Using site-agent-pro in your own project?** Install it as a devDependency instead of cloning:
+> ```bash
+> npm install --save-dev site-agent-pro
+> 
+> # Run a quick audit
+> site-agent-pro --url http://localhost:3000 --task "Check the homepage"
+> 
+> # OR launch the web UI to enter tasks visually
+> site-agent-pro ui
+> ```
+> See [Programmatic API](#programmatic-api) for scripted and CI usage.
+
+### 1. Install (self-hosted / contributor setup)
+
+```bash
+npm install
+npm run browser:install
+```
+
+### 2. Configure
+
+```bash
+cp .env.example .env
+```
+
+Set your LLM provider in `.env`:
+
+```bash
+# Option A: OpenAI (recommended for production)
+LLM_PROVIDER=openai
+OPENAI_API_KEY=your_key_here
+
+LLM_PROVIDER=ollama
+OLLAMA_MODEL=llama3.1:8b
+```
+
+#### Sensitive Data & CLI Overrides
+If you prefer not to save sensitive credentials in your `.env` file, you can pass them directly via the CLI:
+
+```bash
+npx site-agent-pro --url https://example.com \
+  --openai-api-key "sk-..." \
+  --imap-password "your-app-password" \
+  --auth-password "test-user-password" \
+  --private-key "0x..."
+```
+CLI flags always take precedence over values in `.env`.
+
+### 3. Run
+
+```bash
+# Run the agent against a site
+npm run dev -- --url https://example.com \
+  --task "Open pricing and compare the visible plans before signup"
+
+# Start the web dashboard
+npm run dashboard
+# → http://localhost:4173
+```
+
+### 4. View Results
+
+Artifacts are saved to `runs/<run-id>/`:
+
+| File | Contents |
+|---|---|
+| `report.html` | Standalone shareable report |
+| `report.json` | Machine-readable scored report |
+| `report.md` | Markdown report |
+| `task-results.json` | Per-task step history and outcomes |
+| `raw-events.json` | Every browser event, console log, and network request |
+| `accessibility.json` | axe-core violation list |
+| `site-checks.json` | SEO, performance, security, CRO, content, mobile checks |
+| `click-replay.webp` | Compact animated activity replay with click screenshots and overlays for all recorded actions |
+| `*.webm` | Full browser session video recording (enabled via `RECORD_VIDEO=true`) |
+| `inputs.json` | Run configuration and timing metadata |
+| `trade-executions.json` | Optional deterministic trade validation/execution records when trade mode is enabled |
+| `trade-instruction.json` | Optional standalone trade CLI input copy when `npm run trade:run` is used |
+
+---
+
+## CLI Reference
+
+```bash
+# Basic single-task run
+npm run dev -- --url https://example.com --task "Click the pricing tab"
+
+# Multiple tasks
+npm run dev -- --url https://example.com \
+  --task "Read the visible how-to-play section" \
+  --task "Play the game five times and record each win or loss"
+
+# Mobile viewport (iPhone 13, 390×844)
+npm run dev -- --url https://example.com --task "Check the mobile nav" --mobile
+
+# Headed mode (visible browser)
+npm run dev -- --url https://example.com --task "Open pricing" --headed
+
+# Ollama for local sites
+npm run dev -- --url http://127.0.0.1:3000 --task "Check the homepage CTA" \
+  --llm-provider ollama --model llama3.1:8b
+
+# Allow self-signed HTTPS certificates
+npm run dev -- --url https://localhost:3000 --task "Check the homepage" --ignore-https-errors
+
+# Exchange-flow QA without real transfers
+npm run dev -- --url https://example.com \
+  --task "Click Buy; enter 50000 NGN; confirm the crypto preview updates; copy the account number if available; stop before making any real payment" \
+  --task "Click Sell; enter 0.01 USDT; confirm the Naira payout preview updates; stop before sending any real crypto"
+
+# Deterministic onchain validation in dry-run mode
+npm run dev -- --url https://example-dapp.test \
+  --task "Sell 0.01 USDC using the visible deposit address" \
+  --trade-dry-run --trade-strategy deposit_only
+
+# Autonomous Paystack transfer during a task
+npm run dev -- --url https://example-shop.com \
+  --task "Pay 100 Naira to the bank account shown on the checkout page" \
+  --trade-enabled
+```
+
+> **Note:** Every CLI run requires at least one `--task` flag. Runs with no tasks are rejected.
+
+### All CLI Options
+
+| Flag | Description |
+|---|---|
+| `--url <url>` | **(Required)** Website URL to test |
+| `--task <task>` | **(Required)** Task for the agent. Repeat for multiple tasks |
+| `--headed` | Run browser in headed (visible) mode |
+| `--mobile` | Use iPhone 13 mobile viewport |
+| `--ignore-https-errors` | Allow invalid or self-signed HTTPS certificates |
+| `--llm-provider <name>` | LLM provider: `openai` or `ollama` |
+| `--model <name>` | Override the model name |
+| `--ollama-base-url <url>` | Override the Ollama endpoint |
+| `--storage-state <path>` | Load Playwright storage state JSON before the run |
+| `--save-storage-state <path>` | Save Playwright storage state JSON after the run |
+| `--auth-flow` | Bootstrap a test account (signup/login/OTP), then run tasks |
+| `--auth-only` | Bootstrap a test account and save session — skip task run |
+| `--signup-url <url>` | Signup page URL (absolute or relative) |
+| `--login-url <url>` | Login page URL (absolute or relative) |
+| `--access-url <url>` | Protected page URL to verify after login |
+| `--trade-enabled` | Allow deterministic onchain trade execution for this run |
+| `--trade-dry-run` | Validate extracted trade details without broadcasting a transaction |
+| `--trade-strategy <strategy>` | Trade strategy: `auto`, `dapp_only`, or `deposit_only` |
+| `--trade-confirmations <count>` | Confirmations to wait for before marking a trade confirmed, 0–12 |
+
+---
+
+## Programmatic API
+
+Install site-agent-pro as a devDependency in your own project — no cloning required:
+
+```bash
+npm install --save-dev site-agent-pro
+```
+
+Then run audits from any script, test file, or CI pipeline:
+
+```ts
+import { runAudit } from "site-agent-pro";
+
+const result = await runAudit({
+  url: "http://localhost:3000",   // works with localhost dev servers
+  tasks: [
+    "Open the pricing page and note the visible plans",
+    "Click the sign-up button and check the form fields",
+  ],
+});
+
+console.log(`Score: ${result.report.overall_score}/10`);
+console.log(`Summary: ${result.report.summary}`);
+console.log(`Artifacts saved to: ${result.runDir}`);
+
+// Gate your CI pipeline on a minimum quality score
+if (result.report.overall_score < 7) {
+  process.exit(1);
+}
+```
+
+Or add site-agent-pro to your `package.json` scripts and run it from the CLI:
+
+```json
+"scripts": {
+  "audit": "site-agent-pro --url http://localhost:3000 --task 'Check the homepage CTA'",
+  "audit:ui": "site-agent-pro ui",
+  "audit:mobile": "site-agent-pro --url http://localhost:3000 --task 'Check mobile nav' --mobile",
+  "audit:auth": "site-agent-pro --url http://localhost:3000 --task 'Reach the dashboard' --auth-flow"
+}
+```
+
+```bash
+npm run dev &    # your app
+npm run audit    # site-agent-pro hits it live
+```
+
+For full control, import the lower-level API directly:
+
+```ts
+import { runAuditJob, buildCustomTaskSuite, normalizeCustomTasks } from "site-agent-pro";
+```
+
+> **Note:** site-agent-pro requires Playwright's Chromium browser. Run `npx playwright install chromium` once after installing the package.
+
+---
+
+## Web Dashboard
+
+```bash
+npm run dashboard
+```
+
+| URL | Purpose |
+|---|---|
+| `http://localhost:4173/` | Public submission form — enter URL, paste instructions, or upload text/JSON tasks |
+| `http://localhost:4173/dashboard` | Internal run dashboard — inspect all results |
+| `/submissions/<id>` | Submission progress tracking |
+| `/r/<token>` | Public shareable report link (valid 30 days) |
+| `/outputs/<run-id>` | Standalone HTML report for any run |
+| `/api/runs` | REST API — list all runs |
+| `/api/runs/<id>` | REST API — run detail |
+
+The dashboard supports:
+- Instruction paste box plus optional `.txt`, `.md`, `.json`, or `.csv` upload
+- Public-hosted or localhost/private target mode for local development
+- 1–5 concurrent agent perspectives per submission
+- Per-submission trade controls for enablement, dry-run, strategy, and confirmation count
+- Aggregate and per-agent report inspection
+- Artifact downloads (JSON, Markdown, HTML, WebP activity replay)
+- Strengths, weaknesses, and top fix recommendations
+
+---
+
+## Authentication
+
+The agent can bootstrap authenticated sessions for sites that require signup/login.
+
+### Quick Example
+
+```bash
+npm run dev -- --url https://example.com \
+  --task "Reach the account dashboard and confirm billing is visible" \
+  --auth-flow --signup-url /register --login-url /login --access-url /app
+```
+
+### What Auth Bootstrap Does
+
+1. Fills visible signup fields with your configured test identity
+2. Polls your IMAP inbox for OTP or verification emails
+3. Submits the OTP code or opens the verification link
+4. Logs in with the same credentials
+5. Verifies a protected page (if `--access-url` is provided)
+6. Saves the authenticated session to `.auth/session.json`
+
+Successful auth also caches the working identity in `.auth/credentials.json`, keyed by target origin, so later runs against the same site can reuse the saved username or email plus password.
+
+Auth walls detected mid-task are handled automatically when auth credentials are configured or a working identity has already been cached for that target origin.
+
+### Auth-Only Mode
+
+Save an authenticated session without running tasks:
+
+```bash
+npm run dev -- --url https://example.com --auth-only \
+  --signup-url /register --login-url /login --access-url /dashboard
+```
+
+### Session Reuse
+
+For sites behind verified sessions, load a saved Playwright storage state:
+
+```bash
+# Via CLI flag
+npm run dev -- --url https://example.com --task "Reach the dashboard" \
+  --storage-state .auth/session.json
+
+# Via .env (auto-loaded on every run)
+PLAYWRIGHT_STORAGE_STATE_PATH=.auth/session.json
+```
+
+> **Important:** This does not bypass CAPTCHA, MFA, or anti-bot controls. It reuses legitimate sessions you've established.
+
+### Auth Environment Variables
+
+**Required for a fresh auth bootstrap** (not needed when the target origin already has cached credentials):
+
+| Variable | Description |
+|---|---|
+| `AUTH_TEST_EMAIL` | Email address for signup/login |
+| `AUTH_TEST_PASSWORD` | Password for signup/login |
+
+**Optional login field:**
+
+`AUTH_TEST_USERNAME`
+
+**IMAP inbox** (for OTP/verification email polling):
+
+| Variable | Default | Description |
+|---|---|---|
+| `AUTH_IMAP_HOST` | — | IMAP server hostname |
+| `AUTH_IMAP_PORT` | `993` | IMAP port |
+| `AUTH_IMAP_SECURE` | `true` | Use TLS |
+| `AUTH_IMAP_USER` | — | IMAP username |
+| `AUTH_IMAP_PASSWORD` | — | IMAP password |
+| `AUTH_IMAP_MAILBOX` | `INBOX` | Mailbox to poll |
+
+**Optional identity fields:**
+
+`AUTH_TEST_FIRST_NAME` · `AUTH_TEST_LAST_NAME` · `AUTH_TEST_PHONE` · `AUTH_TEST_ADDRESS_LINE1` · `AUTH_TEST_ADDRESS_LINE2` · `AUTH_TEST_CITY` · `AUTH_TEST_STATE` · `AUTH_TEST_POSTAL_CODE` · `AUTH_TEST_COUNTRY` · `AUTH_TEST_COMPANY`
+
+**Optional tuning:**
+
+| Variable | Default | Description |
+|---|---|---|
+| `AUTH_EMAIL_POLL_TIMEOUT_MS` | `180000` | Max wait time for verification email |
+| `AUTH_EMAIL_POLL_INTERVAL_MS` | `5000` | Poll frequency |
+| `AUTH_OTP_LENGTH` | `6` | Expected OTP digit count |
+| `AUTH_EMAIL_FROM_FILTER` | — | Filter emails by sender |
+| `AUTH_EMAIL_SUBJECT_FILTER` | — | Filter emails by subject |
+| `AUTH_GENERATED_IDENTITY_MAX_ATTEMPTS` | `5` | Signup retry count when a generated identity is rejected |
+| `AUTH_EMAIL_DOMAIN` | — | Override the generated plus-address domain |
+| `AUTH_SIGNUP_URL` | — | Default signup URL (instead of CLI flag) |
+| `AUTH_LOGIN_URL` | — | Default login URL |
+| `AUTH_ACCESS_URL` | — | Default protected page URL |
+| `AUTH_SESSION_STATE_PATH` | `.auth/session.json` | Where to save the session |
+
+---
+
+## Web3 Wallet Integration
+
+The agent has built-in support for interacting with Web3 dApps. It uses a dual-mode architecture:
+
+1. **Programmatic Provider (Default):** Injects a secure, headless-compatible `window.ethereum` provider. Transaction signing requests are intercepted and sent to a local HTTP relay running securely inside the Node.js process. The private key never enters the browser.
+2. **MetaMask Extension Mode (Optional):** Runs a full headed browser with the MetaMask extension loaded, and automatically clicks "Connect", "Confirm", or "Sign" in MetaMask popups.
+
+### Quick Setup
+
+Configure your wallet in `.env`:
+
+```bash
+# Required
+WALLET_PRIVATE_KEY=your_private_key_here
+WALLET_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/...
+WALLET_CHAIN_ID=11155111
+
+# Optional: Mnemonic instead of private key
+# WALLET_MNEMONIC="word1 word2 ..."
+```
+
+Once configured, the agent will automatically inject the wallet into every page it visits. The LLM planner is also aware of its wallet address and can interact with "Connect Wallet" flows.
+
+### Deterministic Trade Execution
+
+Trade execution is off by default unless `TRADE_ENABLED=true` or a run explicitly passes `--trade-enabled` or `--trade-dry-run`. When enabled, the agent only attempts a deterministic EVM sell/deposit handoff when the visible page and task provide enough evidence for recipient address, token, chain, and amount. Dry-run mode validates the extracted instruction and writes `trade-executions.json` without broadcasting.
+
+Useful controls:
+
+```bash
+# Validate only; do not broadcast
+--trade-dry-run
+
+# Broadcast only if validation passes
+--trade-enabled
+
+# Choose how to handle the visible trade path
+--trade-strategy auto|dapp_only|deposit_only
+```
+
+For a standalone trade instruction JSON file, use:
+
+```bash
+npm run trade:run -- --instruction ./sell-instruction.json --strategy deposit_only
+
+# Add --broadcast only when you are ready to send the transaction
+npm run trade:run -- --instruction ./sell-instruction.json --broadcast
+```
+
+### Using MetaMask Extension Mode
+
+If you specifically need to test how a dApp interacts with the MetaMask UI, you can run the agent with the extension loaded. This requires extracting the MetaMask extension folder (not a `.crx` file).
+
+**How to get the Extension Path (Mac):**
+1. Ensure MetaMask is installed in your normal Google Chrome browser.
+2. The extracted path is typically located at:
+   `/Users/<YourUsername>/Library/Application Support/Google/Chrome/Default/Extensions/nkbihfbeogaeaoehlefnkodbefgpgknn/<version_number>`
+3. Set the environment variable in `.env`:
+   ```bash
+   WALLET_METAMASK_EXTENSION_PATH=/Users/YourUsername/Library/.../11.14.2_0
+   WALLET_METAMASK_USER_DATA_DIR=/Users/YourUsername/.site-agent-metamask-profile
+   ```
+*Note: Using this mode forces the agent to run in headed (visible) mode. For real MetaMask signing/confirm popups, point `WALLET_METAMASK_USER_DATA_DIR` at a persistent Chromium profile where MetaMask is already set up and unlocked.*
+
+---
+
+## Paystack Integration
+
+The agent has built-in support for the Paystack API (Nigeria) to handle Naira payments and payouts. This enables "Agent-as-a-Service" monetization flows.
+
+### Features
+- **Dedicated Virtual Accounts (DVA):** Automatically provisions a unique bank account number (Wema/GTB) for each agent persona.
+- **Naira Transfers:** Initiates outbound transfers to any Nigerian bank account via the Transfers API.
+- **Webhook Processing:** Securely handles `charge.success` and `transfer.success` events with HMAC-SHA512 verification.
+- **Zero-Dependency Client:** Uses Node 20+ native `fetch` (no `axios` required).
+
+### Quick Setup
+Configure Paystack in `.env`:
+```bash
+PAYSTACK_SECRET_KEY=sk_test_...
+PAYSTACK_PUBLIC_KEY=pk_test_...
+PAYSTACK_DVA_PROVIDER=wema-bank
+PAYSTACK_AGENT_PHONE=+234...  # Required for Live DVAs
+```
+
+### Autonomous Transfers & Verification
+The agent can autonomously fulfill payment requests and **verify incoming funds or tokens** using its direct API/on-chain access:
+- **Sending Naira**: When it encounters a task like "Pay the vendor ₦500," it extracts the bank details from the page and initiates a transfer using the `pay` action.
+- **Verifying Naira**: If tasked to "wait for payment before releasing tokens," the agent monitors its own Paystack transaction history. It will only proceed to click "Release" or "Confirm" once it sees the matching successful transaction in its account.
+- **Verifying Tokens**: If tasked to "confirm tokens have arrived before paying Naira," the agent monitors its actual on-chain wallet balance via its RPC connection. It ignores potentially fake website UIs and only pays once the blockchain confirms the receipt of funds.
+
+**Safety:** Transfers are only broadcast if `PAYSTACK_TRANSFER_ENABLED=true`. Otherwise, it performs a dry-run validation.
+
+### Testing the Integration
+Run the standalone smoke test to verify your API keys and DVA provisioning:
+```bash
+npm run paystack:test
+```
+
+---
+
+
+## Configuration
+
+All settings are read from environment variables (`.env` file).
+
+### Core Settings
+
+| Variable | Default | Description |
+|---|---|---|
+| `LLM_PROVIDER` | `openai` | LLM backend: `openai` or `ollama` |
+| `OPENAI_API_KEY` | — | **(Required for OpenAI)** API key |
+| `OPENAI_MODEL` | `gpt-5` | Model for planning and evaluation |
+| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama server URL |
+| `OLLAMA_MODEL` | `llama3.1:8b` | Ollama model name |
+
+### Execution Limits
+
+| Variable | Default | Description |
+|---|---|---|
+| `MAX_SESSION_DURATION_MS` | `600000` | Total run time cap (clamped 60s–600s) |
+| `MAX_STEPS_PER_TASK` | `32` | Max actions per task |
+| `ACTION_DELAY_MS` | `600` | Delay between actions (human-like pacing) |
+| `NAVIGATION_TIMEOUT_MS` | `25000` | Page load timeout |
+| `RECORD_VIDEO` | `false` | Record Playwright video into the run directory |
+
+### Browser
+
+| Variable | Default | Description |
+|---|---|---|
+| `HEADLESS` | `true` | Set `false` for headed mode |
+| `PLAYWRIGHT_STORAGE_STATE_PATH` | — | Auto-load session state JSON |
+| `PLAYWRIGHT_EXECUTABLE_PATH` | — | Custom Chromium binary path |
+| `USE_SERVERLESS_CHROMIUM` | — | Force `@sparticuz/chromium` |
+| `SPARTICUZ_CHROMIUM_LOCATION` | — | Chromium binary location hint |
+
+### Trade Policy
+
+| Variable | Default | Description |
+|---|---|---|
+| `TRADE_ENABLED` | `false` | Enable deterministic trade execution by default |
+| `TRADE_ALLOWLISTED_CHAIN_IDS` | — | Comma-separated chain IDs allowed for trade execution |
+| `TRADE_TOKEN_REGISTRY` | `[]` | JSON array of `{ chainId, symbol, assetKind, contract?, decimals }` entries |
+| `TRADE_MAX_TOKEN_AMOUNT` | — | Maximum token amount allowed by policy |
+| `TRADE_REQUIRE_EXACT_TOKEN_CONTRACT` | `true` | Require ERC-20 contract matches when validating trades |
+| `TRADE_CONFIRMATIONS_REQUIRED` | `1` | Default confirmations to wait for, 0–12 |
+| `TRADE_RECEIPT_TIMEOUT_MS` | `120000` | Max wait time for transaction receipt/confirmation |
+
+### Dashboard & Deployment
+
+| Variable | Default | Description |
+|---|---|---|
+| `APP_BASE_URL` | — | Production URL for public report links. On Render, `RENDER_EXTERNAL_URL` is used automatically when this is unset. |
+| `SITE_AGENT_DATA_DIR` | — | Root directory for persisted runs and submissions. Set this to your Render disk mount path for durable storage. |
+| `PORT` | `10000` on Render | Public HTTP port for Render web services |
+| `DASHBOARD_PORT` | `4173` | Dashboard server port |
+| `DASHBOARD_HOST` | `127.0.0.1` locally, `0.0.0.0` on Render | Dashboard server host |
+| `REPORT_TTL_DAYS` | `30` | Public report link expiry |
+| `INTERNAL_JOB_SECRET` | — | Restrict background job invocation |
+
+---
+
+## Writing Effective Tasks
+
+Since the agent follows only your tasks, structure them as focused coverage lanes:
+
+```bash
+# Map the main journey
+--task "Navigate to pricing and compare the monthly vs yearly plans"
+
+# Inspect discovery paths
+--task "Use the site search to find 'refund policy' and read the visible result"
+
+# Follow the conversion path
+--task "Click the Sign Up Free tab, fill every visible detail, and submit"
+
+# Probe edge cases
+--task "Enter an invalid email in the signup form and check the error message"
+
+# Safely test an exchange flow
+--task "Click Buy; enter 50000 NGN; confirm the crypto preview updates; provide a harmless test wallet address; verify the payment account card appears; stop before making any real payment"
+
+# Ask for monitoring evidence
+--task "Check exchange-flow monitoring evidence for amount entry, wallet submission, bank submission, displayed account details, copy actions, and transfer attempts"
+
+# Autonomous fulfillment
+--task "Buy the token; pay ₦500 to the Zenith Bank account shown on the confirmation screen"
+```
+
+**Tips for better results:**
+- Write **specific, concrete actions** — not "explore the site"
+- Use ordered verbs like **click**, **enter**, **copy**, **scroll**, **wait**, **go back**, and **stop** when the sequence matters
+- Include literal values when needed, for example `enter 50000 NGN` or `type "test@example.com" into email`
+- Split large journeys into **separate tasks** so early clicks don't consume the entire budget
+- Paste multi-line instructions or upload text/JSON files in the dashboard when tasks come from a spec
+- A combined Naira/crypto exchange spec that mentions Buy flow, Sell flow, Naira, crypto, and logging/monitoring/events is expanded into separate Buy, Sell, and monitoring tasks
+- For slow sites, increase `NAVIGATION_TIMEOUT_MS` before increasing step counts
+- Use `--storage-state` for pages behind authentication
+- Run **multiple agent perspectives** (2-5) when you want broader coverage
+- For game sites, be explicit: "Play 5 rounds and record each win or loss"
+- For exchange/payment QA, use harmless test values and explicitly tell the agent to stop before any real payment, crypto transfer, purchase, or payout
+
+---
+
+## Render Deployment
+
+This repo now targets a standard Render web service deployment:
+
+- **Dashboard server** (`src/dashboard/server.ts`) — handles the app, submission routes, public reports, and dashboard APIs
+- **Local filesystem persistence** — submissions and run artifacts are stored under `SITE_AGENT_DATA_DIR`
+- **Render Blueprint** (`render.yaml`) — defines the Render web service, health check, and persistent disk mount
+- **Full Playwright runtime** — the build installs Chromium for the dashboard worker process
+
+### Included `render.yaml`
+
+The repo root includes a Render Blueprint with:
+
+- `runtime: node`
+- `buildCommand: npm ci && npm run build && npm run browser:install`
+- `startCommand: npm run render:start`
+- `healthCheckPath: /health`
+- a persistent disk mounted at `/opt/render/project/src/data`
+
+### Required Environment Variables
+
+| Variable | Description |
+|---|---|
+| `OPENAI_API_KEY` | OpenAI API key when `LLM_PROVIDER=openai` |
+
+### Recommended Environment Variables
+
+| Variable | Description |
+|---|---|
+| `LLM_PROVIDER` | Use `openai` for a single-service Render deployment unless you are also hosting Ollama separately |
+| `APP_BASE_URL` | Optional. If unset on Render, the app falls back to `RENDER_EXTERNAL_URL` |
+| `SITE_AGENT_DATA_DIR` | Override only if you change the disk mount path from the default in `render.yaml` |
+| `INTERNAL_JOB_SECRET` | Optional hardening for internal job-style routes |
+
+> **Note:** Render web services must bind to `0.0.0.0:$PORT`, and persistent filesystem data survives deploys only when it is written under the attached disk mount path. See the official Render docs for [web services](https://render.com/docs/web-services), [persistent disks](https://render.com/docs/disks), and the [Blueprint spec](https://render.com/docs/blueprint-spec).
+
+---
+
+## Architecture
+
+For a detailed technical breakdown of every module, see [**ARCHITECTURE.md**](ARCHITECTURE.md).
+
+High-level summary:
+
+| Layer | Key Files | Purpose |
+|---|---|---|
+| **Entry points** | `cli/run.ts`, `dashboard/server.ts` | CLI and web UI |
+| **Orchestration** | `runAuditJob.ts`, `processSubmissionBatch.ts` | Single-run and multi-agent execution |
+| **Agent loop** | `runner.ts` → `planner.ts` → `executor.ts` | Capture state → LLM plans → Playwright acts |
+| **Page understanding** | `pageState.ts`, `siteBrief.ts`, `taskDirectives.ts`, `submissions/customTasks.ts` | DOM snapshots, site comprehension, ordered instruction and upload parsing |
+| **Authentication** | `auth/profile.ts`, `auth/inbox.ts`, `auth/runner.ts` | Identity management, IMAP OTP polling, login flows |
+| **Evaluation** | `evaluator.ts`, `aggregateReport.ts` | LLM scoring, multi-agent result merging |
+| **Site checks** | `siteChecks.ts`, `audit.ts` | SEO, performance, security, accessibility |
+| **Paystack** | `paystack/*` | Dedicated virtual accounts, Naira transfers, webhooks |
+| **Reporting** | `reporting/html.ts`, `reporting/markdown.ts`, `clickReplay.ts` | HTML/MD/JSON reports, activity replay animation |
+| **Trade safety** | `trade/*`, `wallet/*` | Wallet injection, deterministic trade extraction, policy validation, dry-run/broadcast records |
+| **LLM** | `llm/client.ts`, `prompts/browserAgent.ts`, `prompts/reviewer.ts` | OpenAI + Ollama client, system prompts |
+
+---
+
+## Important Constraints
+
+- **No CAPTCHA/MFA bypass** — the agent does not solve CAPTCHAs, MFA challenges, or anti-bot controls
+- **No hidden DOM access** — the agent interacts only with visible elements, like a real user
+- **No unsupported claims** — the evaluator scores from evidence only, not from the agent's impressions
+- **Task-required** — every run must have at least one explicit task
+- **Legitimate sessions only** — storage state reuse is for approved, pre-established sessions
+- **Trade-safe by default** — onchain execution is disabled unless explicitly enabled, and exchange-flow QA should stop before real-world transfers
+
+---
+
+## Step-by-Step Guides
+
+| Guide | Topic |
+|---|---|
+| `docs/01-installation.md` | Installation and setup |
+| `docs/02-running-your-first-audit.md` | Your first run |
+| `docs/03-configuration.md` | Configuration deep-dive |
+| `docs/04-how-the-agent-thinks.md` | Agent planning internals |
+| `docs/05-extending-personas-and-tasks.md` | Custom personas and tasks |
+| `docs/06-hardening-for-production.md` | Production deployment |
+
+---
+
+## Recommended Rollout
+
+1. **Start local** — run manually on desktop, inspect logs and reports
+2. **Tune tasks** — write focused coverage lanes for your product
+3. **Add mobile** — include `--mobile` runs
+4. **Multi-agent** — use 2-5 perspectives for broader coverage
+5. **CI integration** — only after you've validated the scores match your expectations
+
+> Treat the scores as **signals, not ground truth** until you've calibrated them against your own quality bar.