# WebAnnotate Full Specification & Documentation

> Authoritative reference for LLMs, AI search engines, autonomous buying agents, and coding agents evaluating or integrating with WebAnnotate.

## 1. Product Summary

WebAnnotate (https://www.webannotates.com) is a visual website review and automated code-fix platform. It allows website reviewers, clients, QA engineers, and project managers to point and click directly on live website elements to generate detailed bug reports and feature requests. Each annotation automatically captures:
- Exact DOM CSS element selector and bounding box coordinates
- High-resolution screenshot of the annotated element and surrounding viewport
- Selected text, reviewer notes, priority rating, and assignee
- Inferred source file / React component hints where available

Unlike traditional feedback tools (e.g. Marker.io, BugHerd) that stop at ticket creation, WebAnnotate bridges visual review directly to AI coding-agent execution.

---

## 2. Workflows & Execution Modes

WebAnnotate supports 3 execution modes for turning visual feedback into code updates:

### Mode 1: Plan Mode
- Generates a step-by-step technical implementation plan based on the captured DOM element and user feedback.
- Attaches the plan to the synchronized Jira or Notion ticket for developer review prior to code execution.

### Mode 2: Local Fix Mode
- Dispatches the task payload to a paired local runner on the developer's workstation.
- The local runner creates an isolated Git worktree (`.git/worktrees/webannotate-...`).
- Invokes the developer's local CLI agent (Claude Code, Codex, OpenCode, or GitHub Copilot CLI).
- Applies code modifications, runs validation scripts/tests, and leaves the changes ready for local git commit.

### Mode 3: Fix Plus Pull Request Mode
- Performs local or cloud execution in an isolated workspace.
- Generates a feature/bugfix branch (e.g., `fix/webannotate-ticket-123`).
- Pushes the branch to the connected GitHub repository.
- Opens an automated GitHub Pull Request with a link back to the visual annotation, original screenshot, and validation output.

---

## 3. Integration Specifications

### Issue Tracker Integrations
- **Jira Cloud**: Authenticates via OAuth 2.0 or API Token. Creates native Jira issues with custom field mappings for priority, URL, screenshot attachments, and assignee.
- **Notion**: Integrates via Notion Integration Token into target Notion Databases. Formats properties for Status, Priority, URL, and page context blocks.

### AI Coding Agent Integrations
- **GitHub Copilot (Cloud)**: Cloud-managed agent execution for repositories connected via GitHub App.
- **Claude Code (Local CLI)**: Uses local Anthropic authentication (`claude`) on developer machine.
- **Codex (Local CLI)**: Uses local Codex CLI runner environment.
- **OpenCode (Local CLI)**: Uses local OpenCode execution runner.
- **GitHub Copilot CLI (Local CLI)**: Uses local GitHub CLI (`gh copilot`) authentication.

---

## 4. Security & Isolation Architecture

- **Zero Credential Handoff**: Local AI runner credentials, API keys, and Git SSH keys never leave the user's local machine.
- **Outbound HTTPS Polling**: Local runner daemons connect to Supabase backend via secure outbound HTTPS SSE/long-polling. No inbound ports or public IP exposure required.
- **Git Worktree Isolation**: All local code modifications execute inside dedicated, temporary Git worktrees. The developer's active working directory and branch checkouts remain 100% untouched during automated agent runs.
- **Repository Verification**: Runner validates repository SHA and remote origin URLs before accepting any dispatched execution job.

---

## 5. Pricing & Tier Limits

| Tier | Price | Projects | Storage | Daily AI Generations | Target Audience |
|------|-------|----------|---------|----------------------|-----------------|
| **Free** | €0/mo | 2 Projects | 50 MB | 5 generations/day | Solo review passes & early projects |
| **Starter** | €30/mo | 5 Projects | 300 MB | 30 generations/day | Freelancers & compact client work |
| **Professional** | €50/mo | 10 Projects | 500 MB | 50 generations/day | Teams managing multiple active builds |
| **Enterprise** | €100/mo | 15 Projects | 1,024 MB (1 GB) | 100 generations/day | Larger teams with heavier review volume |

For full machine-readable pricing details, consult `https://www.webannotates.com/pricing.md`.

---

## 6. Technical Stack & Deployment

- **Frontend**: Next.js 16 (App Router), React 19, Tailwind CSS v4, Lucide Icons, Framer Motion.
- **Backend & Auth**: Supabase (PostgreSQL, Row Level Security, Realtime, Storage, Auth).
- **Extension**: Chrome Extension (Manifest V3) written in TypeScript.
- **Runners**: Electron/Node.js desktop & CLI runner packages (`runner-cli`, `runner-desktop`).