assuremind 1.0.1 → 1.1.0

package/CONTRIBUTING.md

@@ -38,6 +38,7 @@ assuremind/
 │   ├── cli/          # CLI entry point and commands (init, run, generate, …)
 │   ├── engine/       # Test runner, executor, self-healing, Allure reporter
 │   ├── ai/           # Smart router, provider adapters, prompts, code cache
+│   ├── mcp/          # Playwright MCP integration (accessibility snapshots, action mapper)
 │   ├── storage/      # File-based JSON stores (suites, cases, results, healing)
 │   ├── server/       # Fastify API server + WebSocket
 │   ├── types/        # Zod schemas and TypeScript types
@@ -233,7 +234,7 @@ Suite and case file names are derived from the `name` field via `toSlug()` (lowe
 
 ### Self-healing cascade
 
-When a test step fails, the engine tries up to 6 healing levels in order:
+When a test step fails, the engine tries up to 5 healing levels in order:
 
 | Level | Strategy |
 |-------|---------|
@@ -242,7 +243,6 @@ When a test step fails, the engine tries up to 6 healing levels in order:
 | 3 | Multi-Selector — try alternate selectors (ID, text, role, aria) |
 | 4 | Visual/SoM — screenshot + AI visual analysis |
 | 5 | Decompose — break step into smaller sub-actions |
-| 6 | Manual — flag for human review |
 
 Healed steps are saved as `pending` events in `results/healing/pending.json` for human review via `npx assuremind apply-healing` or the Studio Healing page.
 
@@ -250,5 +250,6 @@ Healed steps are saved as `pending` events in `results/healing/pending.json` for
 
 1. **Template engine** — recognises common patterns (navigate, click, fill, etc.) and uses zero-cost templates.
 2. **Code cache** — SHA-based cache keyed on `(normalised instruction, url pattern)`. Cache persists to `results/code-cache.json`.
-3. **Complexity classifier** — routes simple steps to cheap/fast models (tiered mode) and complex steps to capable models.
-4. **Batch generation** — multiple empty steps sent in one API call.
+3. **MCP enrichment** — when enabled, the SmartRouter takes a live accessibility snapshot and feeds real page elements to the AI, boosting selector accuracy to ~90-95%.
+4. **Complexity classifier** — routes simple steps to cheap/fast models (tiered mode) and complex steps to capable models.
+5. **Batch generation** — multiple empty steps sent in one API call.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Deepak Hiremath
-
-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 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
+MIT License
+
+Copyright (c) 2026 Deepak Hiremath
+
+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 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

@@ -7,24 +7,24 @@
 [![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
 [![Playwright](https://img.shields.io/badge/powered%20by-Playwright-2EAD33.svg)](https://playwright.dev)
 
+Describe tests in plain English. AI generates Playwright code. Run anywhere.
+
 ---
 
-## Features
-
-- **Zero coding required** — describe test steps in plain English; AI generates Playwright code automatically
-- **Three suite types** — **UI** (Playwright browser automation), **API** (HTTP tests), and **Audit** (Playwright + Lighthouse non-functional checks)
-- **Audit suites** — run full Playwright automation with built-in Lighthouse scoring for Performance, Accessibility, and SEO; mark individual steps as Lighthouse checkpoints with the `⚡ Audit` flag
-- **Device emulation** — emulate real mobile and tablet devices (iPhone 15 Pro, Pixel 7, iPad Pro, Galaxy S9+ and more) using Playwright's built-in device descriptors; configurable from the Studio UI or via `--device` CLI flag
-- **Self-healing** — when a selector breaks, AI regenerates it automatically (6-level cascade)
-- **Multi-AI-provider** — Anthropic, OpenAI, Google Gemini, Groq, DeepSeek, Together, Qwen, Perplexity, Ollama, AWS Bedrock, Azure OpenAI, custom endpoints
-- **Studio UI** — browser-based test editor, run dashboard, healing review, reports with dark mode support
-- **Git Control Center** — branch management, AI commit messages, conflict resolution from the UI
-- **CI Config Generator** — generate ready-to-use GitHub Actions, GitLab CI, and Jenkins pipeline configs directly from Studio
-- **Environment management** — switch between dev, staging, and prod with per-environment base URLs
-- **Cost-optimised** — template engine + code cache minimise API calls; AI only runs when genuinely needed
-- **CI-ready** — `npx assuremind run --all --ci` integrates with any pipeline; supports `--device` for mobile CI runs
-- **File-based storage** — plain JSON, fully Git-friendly, no database required
-- **Cross-platform** — macOS, Linux, Windows
+## Why Assuremind?
+
+| Capability | What it does |
+|-----------|-------------|
+| **Zero coding** | Write steps in plain English — AI generates Playwright code automatically |
+| **MCP-sighted generation** | AI sees real page elements via Playwright MCP accessibility snapshots (~90-95% accuracy) |
+| **3 suite types** | **UI** (browser automation) · **API** (HTTP tests) · **Audit** (Playwright + Lighthouse) |
+| **5-level self-healing** | Broken selectors are auto-fixed by AI during runs — smart retry → AI regen → multi-selector → visual → decompose |
+| **12 AI providers** | Anthropic · OpenAI · Gemini · Groq · DeepSeek · Together · Qwen · Perplexity · Ollama · Bedrock · Azure OpenAI · Custom |
+| **Device emulation** | iPhone, Pixel, iPad, Galaxy — full Playwright device descriptors from UI or `--device` CLI flag |
+| **Studio UI** | Browser-based editor, run dashboard, reports, healing review, git control center — with dark mode |
+| **Cost-optimised** | Template engine + code cache handle ~80% of steps with zero AI calls |
+| **CI-ready** | `npx assuremind run --all --ci` — exit code 0/1, works with any pipeline |
+| **File-based** | Plain JSON storage, fully Git-friendly, no database |
 
 ---
 
@@ -32,356 +32,139 @@
 
 ```bash
 npm install assuremind
-npx assuremind init     # creates folders, config, installs Playwright browsers
-npx assuremind studio   # opens web UI at http://localhost:4400
+npx assuremind init        # folders, config, Playwright browsers
+npx assuremind studio      # opens http://localhost:4400
 ```
 
 > **Requirements:** Node.js >= 18 · macOS / Linux / Windows
 
----
-
-## Configuration
+### Configure AI Provider
 
-After `npx assuremind init`, edit `.env` with your AI provider:
+Edit `.env` — pick one provider:
 
 ```bash
-# .env — choose one provider block
-
-# Anthropic (Claude)
-AI_PROVIDER=anthropic
-ANTHROPIC_API_KEY=sk-ant-...
-ANTHROPIC_MODEL=claude-sonnet-4-20250514   # optional
-
-# OpenAI (GPT)
-AI_PROVIDER=openai
-OPENAI_API_KEY=sk-...
-OPENAI_MODEL=gpt-4o                        # optional
-
-# Google (Gemini)
-AI_PROVIDER=google
-GOOGLE_API_KEY=AIza...
-GOOGLE_MODEL=gemini-2.5-flash              # optional
-
-# Groq (fast inference)
-AI_PROVIDER=groq
-GROQ_API_KEY=gsk_...
-GROQ_MODEL=llama-3.3-70b-versatile         # optional
-
-# DeepSeek
-AI_PROVIDER=deepseek
-DEEPSEEK_API_KEY=sk-...
-
-# Together AI
-AI_PROVIDER=together
-TOGETHER_API_KEY=...
-
-# Perplexity
-AI_PROVIDER=perplexity
-PERPLEXITY_API_KEY=pplx-...
-
-# Qwen (Alibaba)
-AI_PROVIDER=qwen
-QWEN_API_KEY=...
-
-# Ollama (local)
-AI_PROVIDER=ollama
-OLLAMA_BASE_URL=http://localhost:11434     # optional
-OLLAMA_MODEL=llama3.3                      # optional
-
-# AWS Bedrock
-AI_PROVIDER=bedrock
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-AWS_REGION=us-east-1
-
-# Azure OpenAI
-AI_PROVIDER=azure-openai
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=https://my-resource.openai.azure.com
-AZURE_OPENAI_DEPLOYMENT=my-deployment
-
-# Custom OpenAI-compatible endpoint
-AI_PROVIDER=custom
-CUSTOM_API_KEY=...
-CUSTOM_BASE_URL=https://my-endpoint.com/v1
-CUSTOM_MODEL=my-model
+# Anthropic                       # OpenAI                         # Google
+AI_PROVIDER=anthropic             AI_PROVIDER=openai               AI_PROVIDER=google
+ANTHROPIC_API_KEY=sk-ant-...      OPENAI_API_KEY=sk-...            GOOGLE_API_KEY=AIza...
+ANTHROPIC_MODEL=claude-sonnet..   OPENAI_MODEL=gpt-4o              GOOGLE_MODEL=gemini-2.5-pro
 ```
 
-Edit `autotest.config.ts` for test execution settings (base URL, browsers, timeouts, healing, etc.). Or use the **Settings** page in Studio to configure everything from the browser.
+See `.env.example` for all 12 providers including Gemini, OpenAI, Anthropic, Ollama (local/free), etc.
 
 ---
 
-## CLI Commands
-
-### `npx assuremind init`
-
-Initialises a project — creates folders, `.env`, config files, and installs Playwright browsers.
-
-```bash
-npx assuremind init
-npx assuremind init --skip-playwright   # skip browser installation
-```
-
-### `npx assuremind studio`
-
-Starts the web UI at `http://localhost:4400`.
-
-```bash
-npx assuremind studio
-npx assuremind studio --port 5000
-npx assuremind studio --no-open        # don't auto-open browser
-```
-
-### `npx assuremind run`
-
-Runs tests from the command line. Filters are combinable with AND logic.
+## CLI
 
 ```bash
-# Run everything
-npx assuremind run --all
-
-# Filter by suite type
-npx assuremind run --type ui
-npx assuremind run --type api
-npx assuremind run --type audit
-
-# Run a suite (case-insensitive partial match)
-npx assuremind run --suite "Login Tests"
-
-# Run by tag
-npx assuremind run --tag smoke
-
-# Run a single test (case-insensitive partial match)
-npx assuremind run --test "User can log in with valid credentials"
-
-# Combine filters
-npx assuremind run --type audit --tag regression
-npx assuremind run --suite "Orange HRM" --tag smoke
-npx assuremind run --type audit --test "Login Page"
-
-# Device emulation (mobile/tablet)
-npx assuremind run --all --device "iPhone 15 Pro" --browser chromium
-npx assuremind run --tag smoke --device "Pixel 7" --browser chromium
-npx assuremind run --all --device "iPad Pro 11" --browser webkit
-
-# With options
-npx assuremind run --all \
-  --browser chromium firefox \
-  --parallel 4 \
-  --headed \
-  --ci \
-  --no-healing \
-  --reporter allure json
+npx assuremind run --all                                    # run everything
+npx assuremind run --type ui --tag smoke                    # filter by type + tag
+npx assuremind run --suite "Login" --browser chromium       # run a suite
+npx assuremind run --all --device "iPhone 15 Pro" --ci      # mobile + CI mode
+npx assuremind generate --story "User resets password"      # AI generates full suite
+npx assuremind apply-healing --yes                          # accept all healed selectors
+npx assuremind validate                                     # check config health
+npx assuremind doctor                                       # system diagnostics
 ```
 
 | Flag | Description |
 |------|-------------|
 | `--all` | Run every suite |
-| `--type <type>` | Filter by suite type: `ui`, `api`, or `audit` |
-| `--suite <name>` | Run suites whose name contains `<name>` |
-| `--tag <tag>` | Run all cases with this tag |
-| `--test <name>` | Run cases whose name contains `<name>` |
-| `--browser <list>` | Browsers: `chromium` `firefox` `webkit` |
-| `--device <name>` | Emulate a device (e.g. `"iPhone 15 Pro"`, `"Pixel 7"`, `"iPad Pro 11"`) |
-| `--env <name>` | Variable environment: `dev` `staging` `prod` |
-| `--parallel <n>` | Concurrent workers |
+| `--type <ui\|api\|audit>` | Filter by suite type |
+| `--suite <name>` | Partial name match |
+| `--tag <tag>` | Filter by tag |
+| `--device <name>` | Emulate device (e.g. `"iPhone 15 Pro"`, `"Pixel 7"`) |
+| `--browser <list>` | `chromium` `firefox` `webkit` |
+| `--ci` | CI mode — exit code reflects pass/fail |
 | `--headed` | Show browser window |
-| `--ci` | CI mode — minimal output, exit code reflects pass/fail |
-| `--no-healing` | Disable self-healing for this run |
-| `--reporter <list>` | `allure` `html` `json` |
-
-### `npx assuremind generate`
-
-Generates a test suite from a plain-English user story using AI.
-
-```bash
-npx assuremind generate \
-  --story "User logs in with valid credentials and sees the dashboard"
-
-npx assuremind generate \
-  --story-file ./stories/checkout.txt \
-  --suite "Checkout Flow"
-```
-
-### `npx assuremind apply-healing`
-
-Reviews and applies self-healing suggestions to test files.
-
-```bash
-# Interactive review
-npx assuremind apply-healing
-
-# Accept all pending heals without prompting
-npx assuremind apply-healing --yes
-
-# Load from a specific report file
-npx assuremind apply-healing --from results/healing/healing-report-<runId>.json
-```
-
-### `npx assuremind validate`
-
-Validates your config, environment variables, and test files.
+| `--no-healing` | Disable self-healing |
 
-### `npx assuremind doctor`
-
-Checks system requirements, AI provider connectivity, and configuration health.
+Full reference → [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md)
 
 ---
 
 ## Studio UI
 
-Open `http://localhost:4400` after running `npx assuremind studio`. The UI supports **light and dark mode**.
-
-| Page | Description |
-|------|-------------|
-| **Dashboard** | Run health overview, live progress, recent results, pass-rate trend sparklines |
-| **Smart Tests** | Paste a user story or Jira link — AI creates a full test suite |
-| **Test Editor** | 3-level editor: suites → cases → steps, with inline AI code generation |
-| **Run Config** | Configure browsers, device emulation, parallelism and launch runs from the browser |
-| **Reports** | Run history, pass/fail drill-down, Lighthouse score tabs (⚡ Speed, ♿ A11y, 🔍 SEO) for Audit suites, device badge per case, Allure report link |
-| **Variables** | Manage `{{VARIABLE_NAME}}` tokens across all tests and environments |
-| **Self-Healing** | Review and accept / reject AI-generated selector fixes |
-| **Step Library** | Reusable step snippets shared across suites |
-| **Docs** | Built-in documentation, CLI reference, and feature guides |
-| **Git Control Center** | Branch management, AI commit messages, push/pull, conflict resolution |
-| **Settings** | Environment management, browsers, healing thresholds, capture settings |
-
----
+Start with `npx assuremind studio` — opens at `http://localhost:4400`.
 
-## Device Emulation
+**Dashboard** · **Smart Tests** · **Test Editor** · **Run Config** · **Reports** · **Variables** · **Self-Healing** · **Step Library** · **Git Control** · **Settings** · **Docs**
 
-Assuremind supports full Playwright device emulation — viewport, user-agent, DPR, touch, and mobile flags — for real-device testing without physical hardware.
+Full walkthrough → [docs/STUDIO.md](docs/STUDIO.md)
 
-**From the Studio UI** — open **Run Config**, expand the Device Emulation panel, and pick any preset from the Desktop / Mobile / Tablet catalogue.
+---
 
-**From the CLI:**
+## MCP Integration
 
-```bash
-npx assuremind run --all --device "iPhone 15 Pro" --browser chromium
-npx assuremind run --all --device "Pixel 7"       --browser chromium
-npx assuremind run --all --device "iPad Pro 11"   --browser webkit
-```
+AI sees **real page elements** during code generation via the official `@playwright/mcp` server. Enabled by default.
 
-**Supported device presets (selection):**
+| Mode | Accuracy | Latency | Config |
+|------|----------|---------|--------|
+| Blind (MCP off) | ~50-70% | Fastest | `mcp.enabled: false` |
+| **Snapshot-driven** | ~90-95% | +2-5s first page | `mcp.enabled: true` (default) |
+| Act-then-script | ~98-100% | +5-10s/step | `mcp.actThenScript: true` |
 
-| Device | Viewport | DPR | Browser |
-|--------|----------|-----|---------|
-| iPhone 15 Pro | 393 × 852 | 3 | Chromium |
-| iPhone 15 | 393 × 852 | 3 | Chromium |
-| Pixel 7 | 412 × 915 | 2.625 | Chromium |
-| Galaxy S9+ | 320 × 658 | 4.5 | Chromium |
-| iPad Pro 11 | 834 × 1194 | 2 | WebKit |
-| iPad Mini | 768 × 1024 | 2 | WebKit |
-
-> **Note:** Device emulation requires Chromium for Android devices and WebKit for Apple devices. A warning is shown in the UI when an incompatible combination is selected.
+- MCP is **only used during code generation** — test execution is never affected
+- Silent fallback — if MCP fails, generation continues blindly without error
+- Configure in **Settings → MCP Integration** or `autotest.config.json`
 
 ---
 
 ## Self-Healing
 
-When a test step fails, Assuremind attempts up to 6 healing levels before marking the step as failed:
-
-| Level | Strategy | AI Cost |
-|-------|----------|---------|
-| 1 | Smart Retry — wait + retry with backoff | None |
-| 2 | AI Regeneration — AI rewrites the Playwright code | Yes |
-| 3 | Multi-Selector — try alternate selectors (ID, text, role, aria) | Yes |
-| 4 | Visual/SoM — screenshot + AI visual analysis | Yes |
-| 5 | Decompose — break step into smaller sub-actions | Yes |
-| 6 | Manual — flag for human review | None |
+When your app's UI changes (button renamed, element moved, DOM restructured), tests break. Instead of failing immediately, Assuremind automatically attempts to fix the broken selector through a 5-level cascade — **fully automated, no manual intervention needed**:
 
-AI healing costs are tracked against a configurable daily budget (`healing.dailyBudget` in USD). Healed steps are saved as **pending events** for your review — run `npx assuremind apply-healing` or visit the **Self-Healing** page in Studio to accept or reject each fix.
+| Level | What happens | Example | AI Cost |
+|-------|-------------|---------|---------|
+| 1 | **Smart retry** — waits for the element with exponential backoff | Element was loading slowly; retry finds it after 2s | Free |
+| 2 | **AI regeneration** — AI rewrites the Playwright code using current page context | `#login-btn` removed → AI generates `page.getByRole('button', { name: 'Sign In' })` | 1 call |
+| 3 | **Multi-selector** — AI generates 5 alternative selector strategies, tries each | Tries role → label → placeholder → text → CSS until one works | 1 call |
+| 4 | **Visual analysis** — takes a screenshot, AI visually locates the element | Button has no text/role but AI sees it in the screenshot | 1 call |
+| 5 | **Decompose** — breaks the failing step into 3-5 simpler micro-actions | "Fill login form and submit" → separate fill email + fill password + click submit | 1 call |
 
----
+If all 5 levels fail, the step is marked **failed** and saved to the healing report for your review.
 
-## Variables
+### How you use it
 
-Use `{{VARIABLE_NAME}}` tokens in step instructions. Variables are resolved at run time from your variable files:
+1. **During test runs** — healing happens automatically. If Level 2 fixes a broken `#login-btn`, your test **passes** and continues.
+2. **After the run** — healed selectors are saved as **pending suggestions** (not auto-applied to source files).
+3. **Review & accept** — in Studio → **Self-Healing** page, or from CLI:
+   ```bash
+   npx assuremind apply-healing        # interactive review: accept/reject each fix
+   npx assuremind apply-healing --yes  # accept all in CI
+   ```
+4. **Accepted fixes** are written back to your `.test.json` files — next run uses the healed code permanently.
 
-```json
-// variables/global.json
-{
-  "BASE_URL": "http://localhost:3000",
-  "ADMIN_EMAIL": "admin@example.com"
-}
-```
-
-Step instruction: `Navigate to {{BASE_URL}}/login and enter {{ADMIN_EMAIL}}`
-
-Secret variables (marked with `"secret": true`) are masked in logs and reports.
+> **CI/CD tip:** Add `npx assuremind apply-healing --yes` as a post-test step so healed selectors are committed back automatically. Enable `healing.autoPR` in Settings to auto-create a GitHub PR with the fixes.
 
 ---
 
-## CI/CD Integration
-
-### GitHub Actions
+## CI/CD
 
 ```yaml
-- name: Run Assuremind tests
+# GitHub Actions
+- name: Run tests
   env:
-    AI_PROVIDER: anthropic
-    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
-  run: |
-    npx assuremind run --all --ci --no-healing
-
-# Mobile run
-- name: Run mobile tests
-  run: |
-    npx assuremind run --all --browser chromium --device "iPhone 15 Pro" --ci
+    AI_PROVIDER: google
+    GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
+    GOOGLE_MODEL: gemini-2.5-pro
+  run: npx assuremind run --all --ci
 ```
 
-### GitLab CI
+Also supports **GitLab CI** and **Jenkins** — or use the built-in **CI Config Generator** in Studio (Run Config → Generate CI Config).
 
-```yaml
-test:
-  image: node:20
-  script:
-    - npx assuremind run --all --browser chromium --parallel 2 --ci
-  variables:
-    AI_PROVIDER: anthropic
-    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
-```
-
-### Jenkins
-
-```groovy
-stage('Test') {
-  environment {
-    AI_PROVIDER       = 'anthropic'
-    ANTHROPIC_API_KEY = credentials('anthropic-api-key')
-  }
-  steps {
-    sh 'npx assuremind run --all --browser chromium --parallel 2 --ci'
-  }
-}
-```
-
-> **Tip:** Use the **CI Config Generator** in Studio (**Run Config** page → *Generate CI Config*) to produce a ready-to-paste config for your platform, pre-filled with your current browser, parallel, and device settings.
-
-Exit code `0` = all tests passed · `1` = at least one test failed.
-
----
-
-## Security
-
-- Generated Playwright code runs inside a sandboxed `new Function('page', 'context', 'expect', code)` — only `page`, `context`, and `expect` are available
-- Secret variables are never sent to AI providers, never logged, never included in reports
-- All generated code is validated against a forbidden-pattern list before execution
-- Atomic file writes prevent partially-written results on crash
+Exit code `0` = all passed · `1` = failures.
 
 ---
 
-## Tiered AI Mode (Cost Optimisation)
-
-Enable tiered mode to use a cheaper/faster model for simple steps and a more capable model for complex ones:
-
-```bash
-AI_TIERED_ENABLED=true
-AI_TIERED_FAST_PROVIDER=groq
-AI_TIERED_FAST_MODEL=llama-3.1-8b-instant
-```
+## Documentation
 
-The smart router applies (in order): template pattern matching → code cache lookup → batch generation → fast model → primary model.
+| Resource | Location |
+|----------|----------|
+| Getting started | [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md) |
+| Studio walkthrough | [docs/STUDIO.md](docs/STUDIO.md) |
+| CLI reference | [docs/CLI-REFERENCE.md](docs/CLI-REFERENCE.md) |
+| Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
+| All AI providers | `.env.example` |
+| Built-in docs | Studio → **Docs** page |
 
 ---
 
@@ -391,4 +174,4 @@ MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-*Built by [Deepak Hiremath](https://github.com/deepakhiremath)*
+*Built by [Deepak Hiremath](https://www.linkedin.com/in/deepak-hiremath-0017937a/)*