hanzi-browse 2.3.1 → 2.3.2

package/README.md

@@ -1,45 +1,51 @@
-# Hanzi Browse — MCP Server
+# Hanzi Browse
 
-The MCP server exposes browser tools to MCP clients and forwards browser work to
-the Chrome extension over the local WebSocket relay.
+Give your AI agent a real browser — with your existing logins, cookies, and sessions.
 
-## Setup
+**Two ways to use it:**
+- **Use locally** — MCP server for Claude Code, Cursor, Codex, and other AI coding agents
+- **Build with it** — REST API + TypeScript SDK for embedding browser automation in your product
+
+## Quick Start (MCP)
 
 ```bash
-cd mcp-server
-npm install
-npm run build
+npx hanzi-browse setup
 ```
 
-Add to your MCP config (e.g., `~/.claude/claude_desktop_config.json`):
+This installs the Chrome extension and configures your AI agent. One command, done.
 
-```json
-{
-  "mcpServers": {
-    "browser": {
-      "command": "node",
-      "args": ["/path/to/hanzi-browse/mcp-server/dist/index.js"]
-    }
-  }
-}
+**Prerequisites:** Chrome must be open with the [Hanzi extension](https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd) installed.
+
+## Quick Start (API)
+
+```bash
+npm install @hanzi/browser-agent
 ```
 
-**Prerequisites:** The Chrome extension must be installed and running. See the [main README](../README.md) for full setup.
+```typescript
+import { HanziClient } from '@hanzi/browser-agent';
 
-## How It Works
+const client = new HanziClient({ apiKey: 'hic_live_...' });
 
-```text
-MCP client
-  -> mcp-server (stdio)
-  -> relay (WebSocket)
-  -> Chrome extension
-  -> browser agent
+// 1. Pair a browser — give the URL to your user
+const { pairingToken } = await client.createPairingToken();
+// User visits: https://api.hanzilla.co/pair/{pairingToken}
+
+// 2. Find their connected session
+const sessions = await client.listSessions();
+const browser = sessions.find(s => s.status === 'connected');
+
+// 3. Run a task (polls until complete)
+const result = await client.runTask({
+  browserSessionId: browser.id,
+  task: 'Go to example.com and read the page title',
+});
+console.log(result.answer);
 ```
 
-The extension is the browser executor. The MCP server should only manage MCP
-tool calls, local session bookkeeping, and blocking waits for completion.
+Full API docs: [browse.hanzilla.co/docs.html](https://browse.hanzilla.co/docs.html)
 
-## Tools
+## MCP Tools
 
 ### `browser_start`
 
@@ -55,7 +61,6 @@ browser_start(
 → {
   "session_id": "abc123",
   "status": "complete",
-  "task": "Search for flights to Tokyo...",
   "answer": "Found 3 flights: JAL $850, ANA $920, United $780",
   "total_steps": 8,
   "recent_steps": ["Opened Google Flights", "Set destination to Tokyo", ...]
@@ -64,7 +69,7 @@ browser_start(
 
 ### `browser_message`
 
-Send follow-up instructions to an existing session. Also blocks until the agent finishes.
+Send follow-up instructions to an existing session.
 
 ```
 browser_message(session_id: "abc123", message: "Book the cheapest one")
@@ -75,7 +80,7 @@ browser_message(session_id: "abc123", message: "Book the cheapest one")
 Check known sessions and their latest status.
 
 ```
-browser_status()                    // all active sessions
+browser_status()                     // all active sessions
 browser_status(session_id: "abc123") // specific session
 ```
 
@@ -85,7 +90,7 @@ Stop a task.
 
 ```
 browser_stop(session_id: "abc123")
-browser_stop(session_id: "abc123", remove: true)  // also delete session
+browser_stop(session_id: "abc123", remove: true)  // also close window
 ```
 
 ### `browser_screenshot`
@@ -98,84 +103,63 @@ browser_screenshot(session_id: "abc123")
 
 ## Examples
 
-**Research:**
-```
-browser_start("Find the top 3 competitors for Acme Corp and summarize their pricing")
-```
-
 **Logged-in workflows:**
 ```
-browser_start("Go to Jira, find my open tickets, and summarize what needs attention this week")
+browser_start("Go to Jira, find my open tickets, and summarize what needs attention")
 ```
 
 **Multi-turn:**
 ```
 s = browser_start("Go to LinkedIn and find AI Engineer jobs in Montreal")
-→ { session_id: "x1", answer: "Found: Applied AI Engineer at Cohere" }
-
-browser_message("x1", "Click into that job and tell me the requirements")
-→ { answer: "Requirements: 3+ years Python, ML experience..." }
-
-browser_message("x1", "Apply to this job using my profile")
-→ { answer: "Application submitted successfully" }
+browser_message(s.session_id, "Click into the Cohere job and tell me the requirements")
+browser_message(s.session_id, "Apply to this job using my profile")
 ```
 
 **Parallel execution:**
 ```
 browser_start("Check flight prices to Tokyo")
 browser_start("Check hotel prices in Shibuya")
-browser_start("Look up train pass costs")
-// All three run simultaneously
+// Both run simultaneously in separate windows
 ```
 
 ## Configuration
 
 | Environment Variable | Default | Description |
 |---|---|---|
-| `HANZI_IN_CHROME_MAX_SESSIONS` | `5` | Max concurrent browser tasks |
+| `HANZI_BROWSE_MAX_SESSIONS` | `5` | Max concurrent browser tasks |
+| `HANZI_BROWSE_TIMEOUT_MS` | `300000` | Task timeout (ms) |
 | `WS_RELAY_PORT` | `7862` | WebSocket relay port |
 
-## Architecture
+## Skills
 
-```
-AI Tool (Claude Code, Cursor, etc.)
-    ↓ MCP Protocol (stdio)
-MCP Server
-    ↓ WebSocket
-Relay Server
-    ↓ WebSocket
-Chrome Extension
-    ↓ Extension agent loop
-Target Website
-```
-
-The relay server starts automatically when the MCP server connects. It routes
-messages between the MCP server and the Chrome extension and briefly queues
-messages while the extension service worker is asleep.
-
-> **Principle**: Hanzi is for real browser work in your signed-in Chrome.
-> Agents should prefer code, logs, APIs, and existing tools first. Use Hanzi when the job needs a real browser session.
-
-## Prompts
-
-The server exposes MCP prompts that clients auto-discover as slash commands:
+The server exposes MCP prompts that clients auto-discover:
 
 | Prompt | Description |
 |--------|-------------|
-| `linkedin-prospector` | Goal-driven LinkedIn outreach — networking, sales, partnerships, or hiring |
-| `e2e-tester` | Test your app in a real browser — reports bugs with screenshots and code references |
-| `social-poster` | Post across LinkedIn, Twitter, Reddit, HN — drafts per-platform, posts from your browser |
-
-In Claude Code, use the built-in `linkedin-prospector` prompt from the MCP prompt list.
-
-## Skills CLI
+| `linkedin-prospector` | Goal-driven LinkedIn outreach |
+| `e2e-tester` | Test your app in a real browser with screenshots |
+| `social-poster` | Post across LinkedIn, Twitter, Reddit from your browser |
+| `x-marketer` | Find X/Twitter conversations and draft voice-matched replies |
 
 ```bash
 hanzi-browser skills                              # list available skills
 hanzi-browser skills install linkedin-prospector   # install SKILL.md to your project
 ```
 
-Skills are portable SKILL.md files for agents that don't support MCP prompts (Cline, Codex). Each skill follows the same principle: use existing tools first, Hanzi only for real browser steps.
+## Architecture
+
+```
+AI Agent (Claude Code, Cursor, etc.)
+    ↓ MCP Protocol (stdio)
+MCP Server (this package)
+    ↓ WebSocket
+Chrome Extension
+    ↓ Chrome DevTools Protocol
+User's Real Browser
+```
+
+> **Principle**: Hanzi is for real browser work in your signed-in Chrome.
+> Agents should prefer code, logs, APIs, and existing tools first. Use Hanzi when the job needs a real browser session.
 
 ## License
 

package/dist/agent/domain-knowledge.d.ts

@@ -1,10 +1,11 @@
 /**
- * Domain-specific knowledge for the server-side agent loop.
- * Matches the extension's domain-skills.js but only includes domains
- * relevant to managed/API tasks.
+ * Domain-specific knowledge for the agent loop.
+ * Single source of truth — shared between server (managed API, MCP)
+ * and extension (via import at build time).
  */
 interface DomainEntry {
     domain: string;
+    antiBot?: boolean;
     skill: string;
 }
 /**
@@ -12,4 +13,8 @@ interface DomainEntry {
  * Returns the first matching entry, or null.
  */
 export declare function getDomainSkill(url: string): DomainEntry | null;
+/**
+ * Get all domain skills. Used by extension to import the full list.
+ */
+export declare function getAllDomainSkills(): DomainEntry[];
 export {};

package/dist/agent/domain-knowledge.js

@@ -1,51 +1,15 @@
 /**
- * Domain-specific knowledge for the server-side agent loop.
- * Matches the extension's domain-skills.js but only includes domains
- * relevant to managed/API tasks.
+ * Domain-specific knowledge for the agent loop.
+ * Single source of truth — shared between server (managed API, MCP)
+ * and extension (via import at build time).
  */
-const DOMAIN_KNOWLEDGE = [
-    {
-        domain: "x.com",
-        skill: `X/Twitter — verified patterns (updated 2026-03-30)
-
-## Reading pages (CRITICAL)
-- X loads content asynchronously — page looks empty for 3-5 seconds after navigation.
-- read_page often returns ONLY "To view keyboard shortcuts" — tweets haven't loaded yet.
-- DO NOT re-navigate to the same URL. That resets loading and makes it worse.
-- Instead: wait 5 seconds, then use get_page_text — it reads visible text and is more reliable.
-- If get_page_text returns nothing, scroll down once and try again.
-
-## Search
-- URL: x.com/search?q={encoded_query}&src=typed_query&f=live
-- After navigating, wait 5 seconds, then get_page_text (NOT read_page).
-- Scroll down once to load more tweets, then get_page_text again.
-- Tweet URLs in page text follow pattern: /status/{id}
-
-## Text input (CRITICAL — Draft.js)
-- form_input DOES NOT WORK — Draft.js ignores programmatic input.
-- computer type action GARBLES TEXT.
-- ONLY RELIABLE METHOD — use javascript_tool:
-  document.querySelector('[data-testid="tweetTextarea_0"]').focus();
-  document.execCommand('insertText', false, 'your reply text here');
-- Always verify text appeared by reading after insertion.
-
-## Replying to a tweet
-1. Navigate to tweet URL (x.com/{handle}/status/{id})
-2. Wait 3 seconds, read the page
-3. Click the reply/comment icon (speech bubble) in the action bar
-4. Use javascript_tool to insert text (see above)
-5. Verify text appeared, then click blue "Reply" button
-6. Wait 2 seconds to confirm reply posted
-
-## Known traps
-- DO NOT scroll looking for "Post your reply" — reply box appears after clicking comment icon
-- x.com/compose/post may open — that's fine, type and click Reply there
-- "Leave site?" dialog — ALWAYS click Cancel, finish posting first
-- Reply button is disabled until text is entered — verify first
-- Space replies 15+ seconds apart (rate limiting)
-- NEVER navigate to the same URL you're already on`,
-    },
-];
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+// Load from shared JSON file
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const DOMAIN_SKILLS = JSON.parse(readFileSync(join(__dirname, "domain-skills.json"), "utf-8"));
 /**
  * Look up domain knowledge for a URL.
  * Returns the first matching entry, or null.
@@ -53,11 +17,17 @@ const DOMAIN_KNOWLEDGE = [
 export function getDomainSkill(url) {
     try {
         const hostname = new URL(url).hostname.toLowerCase();
-        return DOMAIN_KNOWLEDGE.find((d) => hostname === d.domain || hostname.endsWith("." + d.domain)) || null;
+        return DOMAIN_SKILLS.find((d) => hostname === d.domain || hostname.endsWith("." + d.domain)) || null;
     }
     catch {
         // URL might not be a full URL — try matching as a bare domain
         const lower = url.toLowerCase();
-        return DOMAIN_KNOWLEDGE.find((d) => lower.includes(d.domain)) || null;
+        return DOMAIN_SKILLS.find((d) => lower.includes(d.domain)) || null;
     }
 }
+/**
+ * Get all domain skills. Used by extension to import the full list.
+ */
+export function getAllDomainSkills() {
+    return DOMAIN_SKILLS;
+}

package/dist/agent/domain-skills.json

@@ -0,0 +1,66 @@
+[
+  {
+    "domain": "mail.google.com",
+    "skill": "Gmail best practices:\n- To open an email, click directly on the email subject/preview text, NOT the checkbox or star\n- Use keyboard shortcuts: 'c' to compose, 'r' to reply, 'a' to reply all, 'f' to forward, 'e' to archive\n- To search, use the search bar at the top with operators like 'from:', 'to:', 'subject:', 'is:unread'\n- Reading pane may be on the right or below depending on user settings - check which layout is active\n- Verification codes are often in emails from 'noreply@' addresses with subjects containing 'verification', 'code', or 'confirm'"
+  },
+  {
+    "domain": "docs.google.com",
+    "skill": "Google Docs best practices:\n- This is a canvas-based application - use screenshots to see content, read_page may not capture all text\n- Use keyboard shortcuts: Cmd/Ctrl+B for bold, Cmd/Ctrl+I for italic, Cmd/Ctrl+K for links\n- To navigate, use Cmd/Ctrl+F to find text, then click on the result\n- For editing, click to place cursor then type - triple-click to select a paragraph\n- Access menus via the menu bar at the top (File, Edit, View, Insert, Format, etc.)"
+  },
+  {
+    "domain": "sheets.google.com",
+    "skill": "Google Sheets best practices:\n- Click on cells to select them, double-click to edit cell content\n- Use Tab to move right, Enter to move down, arrow keys to navigate\n- Formulas start with '=' - e.g., =SUM(A1:A10), =VLOOKUP(), =IF()\n- Use Cmd/Ctrl+C and Cmd/Ctrl+V for copy/paste\n- Select ranges by clicking and dragging, or Shift+click for range selection"
+  },
+  {
+    "domain": "github.com",
+    "skill": "GitHub best practices:\n- Repository navigation: Code tab for files, Issues for bug tracking, Pull requests for code review\n- To view a file, click on the filename in the file tree\n- Use 't' to open file finder, 'l' to jump to a line\n- In PRs: 'Files changed' tab shows diffs, 'Conversation' tab shows comments\n- Use the search bar with qualifiers: 'is:open is:pr', 'is:issue label:bug'"
+  },
+  {
+    "domain": "reddit.com",
+    "antiBot": true,
+    "skill": "Reddit UI patterns:\n- Posts are listed in a feed - click on post title to view full post and comments\n- Comments are nested/threaded - each comment has its own reply button underneath\n- Upvote (up arrow) and downvote (down arrow) buttons are to the left of each post/comment\n- To comment, scroll to comment box at top of comments section, or click reply under a specific comment\n- Use the search bar at top to find subreddits or posts\n- r/subredditname format for community names"
+  },
+  {
+    "domain": "linkedin.com",
+    "antiBot": true,
+    "skill": "LinkedIn UI patterns:\n\n## Messaging & Connections\n- To message someone: first check if you're connected (1st degree) - if not, send a connection request first\n- Connection request: go to their profile, click 'Connect' button, optionally add a note\n- Once connected, use the 'Message' button on their profile or go to Messaging tab\n- InMail (messaging non-connections) requires Premium subscription\n\n## Easy Apply Forms\n- Contact Info page is pre-filled from LinkedIn profile - don't try to modify, just click Next\n- Modal forms may need scrolling to see all content and buttons\n- Use screenshots over read_page for modals - accessibility tree often misses modal content\n\n## Navigation\n- Main tabs: Home (feed), My Network, Jobs, Messaging, Notifications\n- Job search: Jobs tab → filter by location, experience level, date posted\n- 'Easy Apply' = apply within LinkedIn; 'Apply' = external site\n- Profile sections are collapsible - click 'Show all' to expand"
+  },
+  {
+    "domain": "indeed.com",
+    "skill": "Indeed best practices:\n- Search for jobs using the 'What' and 'Where' fields at the top\n- Filter results by date posted, salary, job type, experience level\n- Click job title to view full description\n- 'Apply now' or 'Apply on company site' buttons are typically on the right panel\n- Sign in to save jobs and track applications"
+  },
+  {
+    "domain": "calendar.google.com",
+    "skill": "Google Calendar best practices:\n- Click on a time slot to create a new event\n- Drag events to reschedule them\n- Click on an event to view details, edit, or delete\n- Use the mini calendar on the left to navigate to different dates\n- Keyboard: 'c' to create event, 't' to go to today, arrow keys to navigate"
+  },
+  {
+    "domain": "drive.google.com",
+    "skill": "Google Drive best practices:\n- Double-click files to open them, single-click to select\n- Right-click for context menu (download, share, rename, etc.)\n- Use the search bar to find files by name or content\n- Create new items with the '+ New' button on the left\n- Drag and drop to move files between folders"
+  },
+  {
+    "domain": "notion.so",
+    "skill": "Notion best practices:\n- Click to place cursor, type '/' to open command menu\n- Drag blocks using the ⋮⋮ handle on the left\n- Use sidebar for navigation between pages\n- Toggle blocks expand/collapse on click\n- Databases can be viewed as table, board, calendar, etc."
+  },
+  {
+    "domain": "figma.com",
+    "skill": "Figma best practices:\n- This is a canvas-based design tool - always use screenshots to see content\n- Use 'V' for select tool, 'R' for rectangle, 'T' for text\n- Zoom with Cmd/Ctrl+scroll or Cmd/Ctrl++ and Cmd/Ctrl+-\n- Navigate frames in the left sidebar\n- Right-click for context menus and additional options"
+  },
+  {
+    "domain": "slack.com",
+    "skill": "Slack best practices:\n- Channels listed in left sidebar - click to switch\n- Cmd/Ctrl+K to quickly switch channels/DMs\n- @ mentions notify users, # references channels\n- Thread replies keep conversations organized\n- Use the search bar to find messages, files, and people"
+  },
+  {
+    "domain": "twitter.com",
+    "antiBot": true,
+    "skill": "See x.com — twitter.com redirects to x.com."
+  },
+  {
+    "domain": "x.com",
+    "antiBot": true,
+    "skill": "X/Twitter — verified patterns (updated 2026-03-30)\n\n## Reading pages (CRITICAL)\n- X loads content asynchronously — page looks empty for 3-5 seconds after navigation.\n- read_page often returns ONLY \"To view keyboard shortcuts\" — tweets haven't loaded yet.\n- DO NOT re-navigate to the same URL. That resets loading and makes it worse.\n- Instead: wait 5 seconds, then use get_page_text — it reads visible text and is more reliable.\n- If get_page_text returns nothing, scroll down once and try again.\n\n## Search\n- URL: x.com/search?q={encoded_query}&src=typed_query&f=live\n- After navigating, wait 5 seconds, then get_page_text (NOT read_page).\n- Scroll down once to load more tweets, then get_page_text again.\n- Tweet URLs in page text follow pattern: /status/{id}\n\n## Text input (CRITICAL — Draft.js)\n- form_input DOES NOT WORK — Draft.js ignores programmatic input.\n- computer type action GARBLES TEXT.\n- ONLY RELIABLE METHOD — use javascript_tool:\n  document.querySelector('[data-testid=\"tweetTextarea_0\"]').focus();\n  document.execCommand('insertText', false, 'your reply text here');\n- Always verify text appeared by reading after insertion.\n\n## Replying to a tweet\n1. Navigate to tweet URL (x.com/{handle}/status/{id})\n2. Wait 3 seconds, read the page\n3. Click the reply/comment icon (speech bubble) in the action bar\n4. Use javascript_tool to insert text (see above)\n5. Verify text appeared, then click blue \"Reply\" button\n6. Wait 2 seconds to confirm reply posted\n\n## Known traps\n- DO NOT scroll looking for \"Post your reply\" — reply box appears after clicking comment icon\n- x.com/compose/post may open — that's fine, type and click Reply there\n- \"Leave site?\" dialog — ALWAYS click Cancel, finish posting first\n- Reply button is disabled until text is entered — verify first\n- Space replies 15+ seconds apart (rate limiting)\n- NEVER navigate to the same URL you're already on"
+  },
+  {
+    "domain": "amazon.com",
+    "skill": "Amazon best practices:\n- Use the search bar at the top for product search\n- Filter results using the left sidebar (price, ratings, Prime, etc.)\n- Click 'Add to Cart' or 'Buy Now' to purchase\n- Product details and reviews are on the product page\n- Check seller information and shipping times before purchasing"
+  }
+]

package/dist/managed/api.js

@@ -955,6 +955,7 @@ function parseBody(req) {
 const ALLOWED_ORIGINS = [
     "https://browse.hanzilla.co",
     "https://api.hanzilla.co",
+    "https://tools.hanzilla.co",
     ...(process.env.NODE_ENV === "production" ? [] : [
         "http://localhost:3000",
         "http://localhost:5173", // Vite dev server
@@ -1096,11 +1097,7 @@ async function handleRequest(req, res) {
         if (method === "GET" && url === "/v1/me") {
             let profile = await resolveSessionProfile(req);
             if (!profile) {
-                // Debug: try reading session directly from cookie + DB
-                const cookieHeader = req.headers.cookie || '';
-                const tokenMatch = cookieHeader.match(/better-auth[.\-]session_token=([^;.\s]+)/);
-                const rawToken = tokenMatch ? decodeURIComponent(tokenMatch[1]) : null;
-                sendJson(req, res, 401, { error: "Not signed in", debug: { rawToken: rawToken?.substring(0, 10), cookieHeader: cookieHeader.substring(0, 100) } });
+                sendJson(req, res, 401, { error: "Not signed in" });
                 return;
             }
             sendJson(req, res, 200, {
@@ -1363,8 +1360,8 @@ async function handleRequest(req, res) {
         sendJson(req, res, 404, { error: "Not found" });
     }
     catch (err) {
-        log.error("Request error", { requestId }, { method, url, error: err.message });
-        sendJson(req, res, 500, { error: err.message, request_id: requestId });
+        log.error("Request error", { requestId }, { method, url, error: err.message, stack: err.stack });
+        sendJson(req, res, 500, { error: "Internal server error", request_id: requestId });
     }
 }
 /**

package/dist/managed/auth.js

@@ -146,13 +146,11 @@ export async function resolveSessionProfile(req) {
         // Extract session token from cookie (handles both __Secure- and plain prefix)
         const cookieHeader = req.headers.cookie || '';
         const tokenMatch = cookieHeader.match(/better-auth[.\-]session_token=([^;]+)/);
-        console.error(`[AUTH] step1: match=${!!tokenMatch} cookieLen=${cookieHeader.length}`);
         if (!tokenMatch)
             return null;
         // Token format: "rawToken.signature" — we only need the raw token for DB lookup
         const rawValue = decodeURIComponent(tokenMatch[1]);
         const token = rawValue.split('.')[0];
-        console.error(`[AUTH] step2: token=${token.substring(0, 10)}... rawLen=${rawValue.length}`);
         if (!token)
             return null;
         const db = getProvisionPool();
@@ -160,12 +158,10 @@ export async function resolveSessionProfile(req) {
        FROM session s
        JOIN "user" u ON u.id = s."userId"
        WHERE s.token = $1 LIMIT 1`, [token]);
-        console.error(`[AUTH] step3: rows=${sessionRes.rows.length}`);
         if (sessionRes.rows.length === 0)
             return null;
         const row = sessionRes.rows[0];
         // Check expiry
-        console.error(`[AUTH] step4: userId=${row.userId} expires=${row.expiresAt} expired=${new Date(row.expiresAt) < new Date()}`);
         if (new Date(row.expiresAt) < new Date())
             return null;
         const wsRes = await db.query(`SELECT wm.workspace_id, w.name as workspace_name
@@ -173,7 +169,6 @@ export async function resolveSessionProfile(req) {
        JOIN workspaces w ON w.id = wm.workspace_id
        WHERE wm.user_id = $1
        ORDER BY wm.created_at ASC LIMIT 1`, [row.userId]);
-        console.error(`[AUTH] step5: wsRows=${wsRes.rows.length}`);
         if (wsRes.rows.length === 0)
             return null;
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hanzi-browse",
-  "version": "2.3.1",
+  "version": "2.3.2",
   "description": "Give your AI agent a real browser — click, type, fill forms, test workflows, post content, and read authenticated pages",
   "license": "PolyForm-Noncommercial-1.0.0",
   "author": "hanzili",
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc && rm -rf dist/managed/templates && cp -r src/managed/templates dist/managed/templates && cd dashboard && npm run build",
+    "build": "tsc && rm -rf dist/managed/templates && cp -r src/managed/templates dist/managed/templates && cp src/agent/domain-skills.json dist/agent/domain-skills.json && cd dashboard && npm run build",
     "build:server": "tsc",
     "build:dashboard": "cd dashboard && npm run build",
     "dev": "tsc --watch",

package/skills/competitor-monitor/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: competitor-monitor
+description: Monitor competitor websites for changes. Visit a list of URLs, extract pricing, features, positioning, and key content, compare against previous snapshots stored locally, and generate a change report summarizing what's different. Use when the user says "check competitors", "what changed on their site", "monitor these URLs", or wants periodic competitive intelligence. Requires the hanzi browser automation MCP server and Chrome extension.
+---
+
+# Competitor Monitor
+
+You monitor competitor websites and report what changed. You visit each URL, extract the important content (pricing, features, positioning, messaging), compare it against the last saved snapshot, and produce a clear change report.
+
+## Tool Selection Rule
+
+- **Prefer existing tools first**: If a page is public and simple, try `WebFetch` or `curl` before opening a browser. Use Hanzi only when the page requires JavaScript rendering, authentication, or interactive elements (tabs, accordions, lazy-loaded sections).
+- **Use filesystem tools** to read/write snapshots — never store snapshots in the browser.
+- **If a site blocks or shows a CAPTCHA**, stop that URL and move to the next. Report the failure.
+
+## Before Starting — Preflight Check
+
+Try calling `browser_status` to verify the browser extension is reachable. If the tool doesn't exist or returns an error:
+
+> **Hanzi isn't set up yet.** This skill needs the hanzi browser extension running in Chrome.
+>
+> 1. Install from the Chrome Web Store: https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd
+> 2. The extension will walk you through setup (~1 minute)
+> 3. Then come back and run this again
+
+---
+
+## What You Need From the User
+
+1. **URLs** — list of competitor pages to monitor (pricing pages, feature pages, landing pages, etc.)
+2. **Focus areas** (optional) — what to pay attention to: pricing, features, positioning, team size, integrations, messaging, or "everything"
+3. **Label** (optional) — a name for this monitoring set (e.g., "competitor-pricing", "market-landscape"). Defaults to "default".
+
+Optional:
+- Specific sections or elements to watch (e.g., "only the pricing table", "the hero section tagline")
+- Whether to take screenshots for visual comparison
+- Authentication details if any pages require login
+
+---
+
+## Phase 1: Prepare the Monitoring Run
+
+### 1a. Load Previous Snapshots
+
+Snapshots are stored in `~/.hanzi-browse/competitor-monitor/{label}/`. Each URL gets a file named by its sanitized hostname + path.
+
+```bash
+mkdir -p ~/.hanzi-browse/competitor-monitor/{label}
+ls ~/.hanzi-browse/competitor-monitor/{label}/ 2>/dev/null || echo "NO_PREVIOUS_SNAPSHOTS"
+```
+
+For each URL, check if a previous snapshot exists:
+```bash
+cat ~/.hanzi-browse/competitor-monitor/{label}/{sanitized_filename}.json 2>/dev/null || echo "NO_SNAPSHOT"
+```
+
+If no previous snapshots exist, this is a **baseline run** — you'll capture the initial state without generating a diff.
+
+### 1b. Plan the Extraction
+
+For each URL, determine what to extract based on the page type and user's focus areas:
+
+| Page Type | What to Extract |
+|-----------|----------------|
+| **Pricing page** | Plan names, prices, billing periods, feature lists per tier, CTAs, free tier details, enterprise contact options |
+| **Features page** | Feature names, descriptions, categories, "new" or "coming soon" badges, comparison tables |
+| **Landing/home page** | Hero headline, subheadline, value propositions, social proof (logos, testimonials, stats), CTAs |
+| **About/team page** | Team size, key hires, office locations, funding mentions |
+| **Blog/changelog** | Latest 3-5 post titles, dates, and summaries |
+| **Integrations page** | List of integrations, categories, "new" badges |
+| **Docs/API page** | Navigation structure, new sections, deprecation notices |
+
+Present the plan: "I'll visit these N URLs and extract [focus areas]. Previous snapshots: [found/not found]. Ready to proceed?"
+
+**Wait for user confirmation before visiting any URLs.**
+
+---
+
+## Phase 2: Visit and Extract (browser via Hanzi)
+
+Visit each URL using `browser_start`. Run up to 3 URLs **in parallel** — each gets its own browser window.
+
+For each URL:
+
+```
+browser_start({
+  task: "Visit this page and extract all [focus areas]. Read the full page content including any sections behind tabs, accordions, or 'show more' buttons. Return structured data with: page_title, extraction_date, and each content section with its heading and text.",
+  url: "{competitor_url}",
+  context: "Focus areas: {focus_areas}. Extract exact text — do not paraphrase. Include prices with currency symbols. Expand any collapsed sections."
+})
+```
+
+After `browser_start` returns:
+1. Parse the result to extract structured content
+2. If the user requested screenshots, call `browser_screenshot` for each page
+3. Call `browser_stop` with `remove: true` to clean up
+
+### Extraction Format
+
+Structure the extracted data consistently:
+
+```json
+{
+  "url": "https://competitor.com/pricing",
+  "extracted_at": "2026-04-02T10:30:00Z",
+  "page_title": "Pricing - Competitor",
+  "sections": [
+    {
+      "name": "Plans",
+      "content": [
+        {
+          "plan": "Starter",
+          "price": "$9/mo",
+          "billing": "billed annually",
+          "features": ["Feature A", "Feature B", "5 users"]
+        }
+      ]
+    },
+    {
+      "name": "Hero",
+      "headline": "The fastest way to do X",
+      "subheadline": "Used by 10,000+ teams"
+    }
+  ]
+}
+```
+
+### Error Handling
+
+- **Page blocked / CAPTCHA**: Skip, note in report, move to next URL
+- **Page not found (404)**: Record as "page removed" — this itself is a significant change
+- **Timeout**: Call `browser_screenshot` to capture current state, then `browser_stop`. Retry once. If it fails again, skip.
+- **Login required**: Stop and ask the user for credentials. Pass via `context` field, never in `task`.
+
+---
+
+## Phase 3: Compare Against Previous Snapshots (no browser)
+
+For each URL, compare the new extraction against the stored snapshot.
+
+### Diff Categories
+
+Classify every change into one of these categories:
+
+| Category | What it means | Priority |
+|----------|--------------|----------|
+| **Pricing change** | Price increase/decrease, new tier, removed tier, changed billing | HIGH |
+| **Feature change** | New feature added, feature removed, feature renamed or moved between tiers | HIGH |
+| **Positioning change** | Headline, tagline, or value prop rewritten | MEDIUM |
+| **Social proof change** | New logos, updated stats, new testimonials | LOW |
+| **Structural change** | New page sections, reorganized layout, new navigation items | LOW |
+| **Content update** | Minor text edits, typo fixes, updated dates | LOW |
+| **Page removed** | URL now returns 404 or redirects | HIGH |
+| **New page** | First time monitoring this URL (baseline) | INFO |
+
+### Comparison Rules
+
+- Compare section by section, not character by character
+- For pricing: flag exact dollar amounts, percentage changes, and tier restructuring
+- For features: track additions, removals, and tier movements separately
+- For text: ignore minor formatting changes (whitespace, punctuation). Flag substantive rewording.
+- If a section existed before but is now missing, flag as removed
+- If a new section appears, flag as added
+
+---
+
+## Phase 4: Save Updated Snapshots
+
+After comparison, save the new extraction as the current snapshot:
+
+```bash
+mkdir -p ~/.hanzi-browse/competitor-monitor/{label}
+```
+
+Write the JSON snapshot file for each URL:
+```bash
+cat > ~/.hanzi-browse/competitor-monitor/{label}/{sanitized_filename}.json << 'SNAPSHOT_EOF'
+{extracted_json_here}
+SNAPSHOT_EOF
+```
+
+Also append to the monitoring log:
+```bash
+echo '{"url":"{url}","checked_at":"{timestamp}","changes_found":{count},"categories":["{cat1}","{cat2}"]}' >> ~/.hanzi-browse/competitor-monitor/{label}/monitor-log.jsonl
+```
+
+---
+
+## Phase 5: Generate Change Report
+
+### Baseline Run (no previous snapshots)
+
+If this is the first run, present the captured state:
+
+```
+Competitor Monitor — Baseline Captured
+
+Label: {label}
+Date: {date}
+URLs monitored: {N}
+
+Competitor: {name or domain}
+  URL: {url}
+  Pricing: {summary of tiers and prices}
+  Key features: {top features}
+  Positioning: "{headline}" — {subheadline}
+
+Competitor: {name or domain}
+  ...
+
+Snapshots saved to ~/.hanzi-browse/competitor-monitor/{label}/
+Next run will compare against this baseline.
+```
+
+### Change Report (subsequent runs)
+
+```
+Competitor Monitor — Change Report
+
+Label: {label}
+Date: {date}
+URLs monitored: {N}
+URLs with changes: {N}
+URLs unchanged: {N}
+URLs failed: {N}
+
+--- HIGH PRIORITY CHANGES ---
+
+[Competitor Name] — {url}
+  PRICING: Starter plan increased from $9/mo to $12/mo (+33%)
+  PRICING: New "Enterprise" tier added at custom pricing
+  FEATURE: "AI Assistant" added to Pro tier (was not listed before)
+
+--- MEDIUM PRIORITY CHANGES ---
+
+[Competitor Name] — {url}
+  POSITIONING: Hero headline changed
+    Was: "The simple way to manage projects"
+    Now: "The AI-powered way to manage projects"
+
+--- LOW PRIORITY CHANGES ---
+
+[Competitor Name] — {url}
+  SOCIAL PROOF: Customer count updated from "5,000+" to "10,000+"
+  CONTENT: Footer copyright year updated to 2026
+
+--- NO CHANGES ---
+
+[Competitor Name] — {url}: No changes detected
+
+--- FAILED ---
+
+[Competitor Name] — {url}: Blocked by CAPTCHA
+```
+
+### Strategic Insights
+
+After the change report, provide analysis:
+
+1. **Pricing trends** — Are competitors raising or lowering prices? Adding tiers? Moving to usage-based?
+2. **Feature signals** — What are they building? What features are moving down-market (from enterprise to lower tiers)?
+3. **Positioning shifts** — How is their messaging evolving? Are they targeting a new audience?
+4. **Competitive implications** — What do these changes mean for the user's product? Any threats or opportunities?
+5. **Recommended actions** — Specific suggestions: "Consider matching their free tier offering", "Their new AI feature overlaps with your roadmap item X"
+
+---
+
+## Snapshot File Naming
+
+Sanitize URLs to create filenames:
+- Replace `https://` and `http://` with nothing
+- Replace `/`, `?`, `&`, `=` with `_`
+- Replace `.` with `_` (except file extensions)
+- Truncate to 100 characters
+- Example: `https://competitor.com/pricing?plan=all` becomes `competitor_com_pricing_plan_all`
+
+---
+
+## Rules
+
+- Always confirm the URL list and focus areas with the user before visiting any pages
+- Never modify competitor websites — read only
+- Save snapshots after every run so the next run has a baseline
+- Classify all changes by priority — don't bury pricing changes in a wall of minor edits
+- If a URL requires authentication, ask the user — never guess credentials
+- Max 20 URLs per session to avoid rate limiting and long execution times
+- Run up to 3 browser visits in parallel for speed, but not more (avoids overwhelming the browser)
+- If a competitor site blocks automated access, note it and suggest the user visit manually
+- Keep snapshots as structured JSON, not raw HTML — this makes comparison reliable across minor layout changes
+- Log every monitoring run to `monitor-log.jsonl` for trend tracking across sessions

package/skills/job-applier/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: job-applier
+description: Apply to jobs from your real browser. Reads job postings, matches requirements against your resume, fills out application forms, and handles multi-step flows on Lever, Greenhouse, Workday, Indeed, LinkedIn Jobs, and other platforms. Reviews everything before submitting. Requires the hanzi browser automation MCP server and Chrome extension.
+---
+
+# Job Application Helper
+
+You help users apply to jobs by reading postings, matching qualifications, and filling out application forms in a real browser with their signed-in sessions.
+
+## Tool Selection Rule
+
+- **Prefer existing tools first**: code search, file reads, APIs, and other MCP integrations.
+- **Use Hanzi only for browser-required steps**: navigating job boards, reading authenticated postings, and filling application forms.
+- **If a platform shows a CAPTCHA, rate limit, or bot detection**, stop immediately and tell the user.
+
+## Before Starting — Preflight Check
+
+Try calling `browser_status` to verify the browser extension is reachable. If the tool doesn't exist or returns an error:
+
+> **Hanzi isn't set up yet.** This skill needs the hanzi browser extension running in Chrome.
+>
+> 1. Install from the Chrome Web Store: https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd
+> 2. The extension will walk you through setup (~1 minute)
+> 3. Then come back and run this again
+
+---
+
+## What You Need From the User
+
+1. **Job URL** — link to the job posting
+2. **Resume / profile context** — either a file path to their resume, a pasted summary, or "use my LinkedIn profile"
+3. **Additional context** — cover letter tone, salary expectations, visa status, availability, or any field-specific answers
+
+Optional:
+- Preferred name or contact info overrides
+- Answers to common screening questions (years of experience, willing to relocate, etc.)
+- Whether to actually submit or just fill and pause for review
+
+---
+
+## Phase 1: Gather Context BEFORE Opening the Browser
+
+### Read the user's resume
+
+If the user provided a file path, read it. If they pasted text, use that. Extract:
+- Name, email, phone, location
+- Current title and company
+- Skills and technologies
+- Years of experience
+- Education
+- Notable achievements
+
+Store these as structured data — you'll need them for every form field.
+
+### Read the job posting
+
+If the job URL is publicly accessible, try fetching it with `WebFetch` or `curl` first — no browser needed for public postings.
+
+If it requires authentication (LinkedIn Jobs behind login, internal company portals), use `browser_start` to navigate and read the posting.
+
+Extract from the posting:
+- Job title, company, location, remote/hybrid/onsite
+- Required qualifications
+- Preferred qualifications
+- Responsibilities
+- Application deadline (if listed)
+
+### Match qualifications
+
+Compare the user's profile against the job requirements. Present a brief match summary:
+
+```
+Match summary for [Job Title] at [Company]:
+
+Strong matches:
+- [Requirement] — [How the user matches]
+- [Requirement] — [How the user matches]
+
+Gaps:
+- [Requirement] — [What's missing or weak]
+
+Overall fit: [Strong / Moderate / Weak]
+```
+
+If the fit is weak, tell the user honestly. Ask if they want to proceed anyway.
+
+---
+
+## Phase 2: Prepare Application Answers
+
+Before touching the browser, prepare answers for common application fields:
+
+**Standard fields** (auto-fill from resume):
+- Full name, email, phone, location
+- Current company, current title
+- LinkedIn URL, portfolio/website
+- Resume upload (file path)
+
+**Screening questions** (need user input if not provided):
+- Are you authorized to work in [country]?
+- Do you require visa sponsorship?
+- Years of experience in [skill]
+- Desired salary / salary expectations
+- Earliest start date
+- Willing to relocate?
+- How did you hear about this role?
+
+**Cover letter** (generate if needed):
+- Tailor to the specific role and company
+- Reference 2-3 specific requirements from the posting that match the user's experience
+- Keep it under 300 words
+- Match the tone the user requested (professional, conversational, etc.)
+
+Present all prepared answers to the user. Ask them to confirm or adjust before proceeding.
+
+---
+
+## Phase 3: Fill the Application Form
+
+Navigate to the application page using `browser_start`. Apply **one job at a time, sequentially**.
+
+### Platform-specific patterns
+
+**Lever** (jobs.lever.co):
+- Single-page form with resume upload, standard fields, and custom questions
+- Upload resume first — Lever sometimes auto-fills fields from it
+- Custom questions appear below the standard fields
+
+**Greenhouse** (boards.greenhouse.io):
+- Multi-step form: personal info, resume, custom questions, voluntary self-identification
+- Each step has a "Next" or "Continue" button
+- EEOC/voluntary fields are optional — skip unless the user wants to fill them
+
+**Workday** (*.myworkdayjobs.com):
+- Requires account creation — warn the user before proceeding
+- Multi-page flow with "Save and Continue" between sections
+- Often requires re-entering information already on the resume
+- May have autofill from LinkedIn — use it if the user is signed in
+
+**LinkedIn Jobs** (linkedin.com/jobs):
+- "Easy Apply" is a modal overlay, not a new page
+- May have 1-3 steps within the modal
+- Can upload resume or use LinkedIn profile
+- Some postings redirect to the company's external ATS
+
+**Indeed** (indeed.com):
+- May require an Indeed account
+- "Apply Now" sometimes redirects to external site
+- Indeed's own application flow has screening questions upfront
+
+**Generic ATS / company career pages**:
+- Look for the application form — usually behind "Apply" or "Apply Now"
+- Fill fields based on label matching (name, email, phone, etc.)
+- For file uploads, use the resume file path from the user
+- For dropdowns, select the closest matching option
+
+### Filling strategy
+
+1. Navigate to the application URL
+2. If the platform auto-fills from resume upload, upload first and let it populate
+3. Fill remaining empty fields using prepared answers
+4. For multi-step forms, complete each step before moving to the next
+5. On the final step, **STOP before clicking Submit**
+
+Pass all form data via the `context` field in `browser_start`:
+
+```
+browser_start({
+  task: "Fill out the job application form. Upload the resume, fill all fields, answer screening questions. DO NOT click Submit — stop on the final review page.",
+  url: "https://jobs.lever.co/company/position-id/apply",
+  context: "Resume file: /path/to/resume.pdf\nName: Jane Smith\nEmail: jane@example.com\nPhone: 555-0123\nLinkedIn: linkedin.com/in/janesmith\nCover letter: [prepared text]\nYears of Python experience: 6\nVisa sponsorship needed: No\nDesired salary: $150,000"
+})
+```
+
+If `browser_start` times out mid-form, call `browser_screenshot` to see progress, then `browser_message` to continue from where it left off.
+
+---
+
+## Phase 4: Review Before Submitting
+
+This is the most important phase. **Never submit without explicit user approval.**
+
+After the form is filled, call `browser_screenshot` to capture the final state. Present to the user:
+
+```
+Application ready for [Job Title] at [Company]:
+
+Filled fields:
+- Name: Jane Smith
+- Email: jane@example.com
+- Phone: 555-0123
+- Resume: uploaded
+- Cover letter: [first 2 lines]...
+- [Screening question]: [answer]
+- [Screening question]: [answer]
+
+Screenshot attached showing the completed form.
+
+Ready to submit? (yes / no / edit [field])
+```
+
+If the user says yes:
+```
+browser_message({
+  session_id: "abc123",
+  message: "Click the Submit / Apply button to submit the application."
+})
+```
+
+If the user wants edits, use `browser_message` to make the changes, take a new screenshot, and confirm again.
+
+After successful submission, take a final screenshot as confirmation. Log the application:
+```bash
+mkdir -p ~/.hanzi-browse && echo "[date] | [company] | [job title] | [url] | submitted" >> ~/.hanzi-browse/applications.txt
+```
+
+---
+
+## Batch Applications
+
+If the user provides multiple job URLs:
+
+1. Analyze all postings first (Phase 1 for each)
+2. Present a summary table:
+
+| # | Company | Role | Fit | Platform | Status |
+|---|---------|------|-----|----------|--------|
+| 1 | Acme Corp | Senior Engineer | Strong | Lever | Ready |
+| 2 | Beta Inc | Staff Engineer | Moderate | Greenhouse | Ready |
+| 3 | Gamma Co | Principal Engineer | Weak | Workday | Needs discussion |
+
+3. Ask which ones to proceed with
+4. Apply one at a time, reviewing each before submission
+5. Report progress: "Applied 2/5 — continuing with #3..."
+
+---
+
+## Safety Rules
+
+- **Never submit without explicit user approval** — always pause on the final step
+- **Never create accounts** on job platforms without asking the user first
+- **Never provide false information** — if a field asks something you don't have an answer for, ask the user
+- **One application at a time** — don't run parallel browser sessions for applications
+- If the form requires payment or credit card information, stop and warn the user
+- If the application asks for SSN, government ID, or similarly sensitive data, stop and tell the user to fill those fields manually
+- If a CAPTCHA appears, pause and ask the user to solve it, then continue
+- Max 10 applications per session to avoid triggering platform rate limits
+
+---
+
+## When Done
+
+Summarize:
+- Total applications: filled / submitted / skipped
+- Per-application status with confirmation screenshots
+- Any issues encountered (CAPTCHAs, missing fields, platform errors)
+- Running total from the applications log:
+  ```bash
+  wc -l ~/.hanzi-browse/applications.txt 2>/dev/null || echo "0 applications logged"
+  ```

package/skills/seo-checker/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: seo-checker
+description: Audit web pages for SEO issues in a real browser. Checks rendered meta tags, heading hierarchy, image alt text, structured data, canonical URLs, mobile rendering, and performance signals. Produces a scored report with specific findings and fixes. Read-only — inspects, doesn't modify. Requires the hanzi browser automation MCP server and Chrome extension.
+---
+
+# SEO Checker
+
+You audit web pages for SEO issues using a real browser — rendered meta tags, actual heading structure, real schema markup, mobile viewport behavior. This skill is read-only: observe and report, don't modify.
+
+## Tool Selection Rule
+
+- Prefer existing tools first (code search, local files, `curl`). Review HTML source, meta tags, and sitemap before opening the browser.
+- Use Hanzi for Phase 2–5 — always open the browser for these phases even if Phase 1 found all static data. Do not substitute curl or WebFetch for browser phases.
+
+## Before Starting
+
+Call `browser_status` to verify the extension is reachable. If unavailable, tell the user to install from: https://chromewebstore.google.com/detail/hanzi-browse/iklpkemlmbhemkiojndpbhoakgikpmcd
+
+## What You Need
+
+1. **URL** — page or site to audit
+2. **Scope** — single page, specific section, or full site (default: single page)
+3. **Focus** — any specific SEO concerns (e.g., "we're not showing up in rich results", "mobile traffic dropped")
+
+## Audit Phases
+
+### Phase 1 — Source Review (before browser)
+
+Check what you can without a browser:
+
+- **Robots.txt**: Fetch `<domain>/robots.txt` — check for accidental `Disallow: /` or blocked important paths
+- **Sitemap**: Fetch `<domain>/sitemap.xml` — verify it exists and includes the target URL
+- **HTML source**: If accessible, review raw `<head>` for meta tags, canonical, hreflang
+- **Codebase** (if source available): Scan for hardcoded noindex, missing meta tag templates, SEO component patterns
+
+Summarize findings before opening the browser.
+
+### Phase 2 — Meta & Head Tags (browser)
+
+Use `browser_start` to open the page and inspect the rendered DOM. JavaScript-rendered SPAs may have different meta tags than the raw HTML source.
+
+- **Title tag**: Exists, 50-60 characters, unique, descriptive (not "Home" or "Untitled")
+- **Meta description**: Exists, 150-160 characters, includes target keywords, compelling for CTR
+- **Canonical URL**: Present, points to the correct URL (not a duplicate or wrong domain)
+- **Robots meta**: Check for unintentional `noindex`, `nofollow`, or `none` directives
+- **Open Graph tags**: `og:title`, `og:description`, `og:image`, `og:url` — all present and correct
+- **Twitter Card tags**: `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image`
+- **Viewport meta**: `<meta name="viewport" content="width=device-width, initial-scale=1">` present
+- **Charset & lang**: `<meta charset="utf-8">` and `<html lang="...">` set correctly
+
+Screenshot the page after loading.
+
+### Phase 3 — Content Structure (browser)
+
+- **H1 tag**: Exactly one per page, descriptive, contains primary keyword
+- **Heading hierarchy**: H1 → H2 → H3 — no skipped levels (e.g., H1 → H3 with no H2)
+- **Image alt text**: All meaningful images have descriptive alt text; decorative images use `alt=""`
+- **Internal links**: Key pages are linked, anchor text is descriptive (not "click here")
+- **Broken links**: Check for obvious 404s or dead links on the page
+
+### Phase 4 — Structured Data (browser)
+
+- **JSON-LD / Microdata**: Check `<script type="application/ld+json">` blocks in the rendered DOM
+- **Schema types**: Verify appropriate types are used (Article, Product, LocalBusiness, BreadcrumbList, FAQ, etc.)
+- **Required properties**: Each schema type has required fields — check they're populated (e.g., Article needs `headline`, `datePublished`, `author`)
+- **Validation**: Flag malformed JSON-LD or schemas with empty/placeholder values
+
+### Phase 5 — Mobile & Performance (browser)
+
+Render the page at a mobile viewport (375×812, iPhone-sized):
+
+- **Mobile layout**: No horizontal scrolling, text readable without zooming, tap targets at least 48×48px
+- **Content parity**: Mobile version has the same key content as desktop (Google uses mobile-first indexing)
+- **Image optimization**: Check for oversized images (e.g., 2000px wide image in a 375px container), missing `loading="lazy"` on below-fold images
+- **CLS indicators**: Elements that visibly shift during load (ads, images without dimensions, dynamically injected content)
+
+Screenshot at mobile viewport.
+
+## Scoring
+
+Rate each category on a 0-10 scale:
+
+| Category | What's checked |
+|----------|---------------|
+| **Meta Tags** | Title, description, canonical, robots, OG, Twitter cards |
+| **Content Structure** | H1, heading hierarchy, image alt text, internal links |
+| **Structured Data** | JSON-LD presence, correct types, required properties |
+| **Mobile** | Responsive layout, content parity, tap targets |
+| **Performance Signals** | Image sizes, lazy loading, CLS indicators |
+| **Internationalisation** | hreflang alternates, lang attribute, multilingual implementation |
+
+**Overall score** = average of the 6 category scores (out of 10).
+
+- **9-10**: Excellent — production-ready SEO
+- **7-8**: Good — minor improvements needed
+- **5-6**: Needs work — several issues affecting visibility
+- **3-4**: Poor — significant SEO problems
+- **0-2**: Critical — major issues blocking indexing or ranking
+
+## Report Format
+
+```
+# SEO Audit: [URL]
+Overall Score: [X]/10
+
+## Meta Tags — [X]/10
+✓ [What passed — one line each]
+✗ [What failed — element, issue, specific fix]
+  📸 Screenshot: [evidence]
+
+## Content Structure — [X]/10
+✓ / ✗ [same format]
+
+## Structured Data — [X]/10
+✓ / ✗ [same format]
+
+## Mobile — [X]/10
+✓ / ✗ [same format]
+
+## Performance Signals — [X]/10
+✓ / ✗ [same format]
+
+## Internationalisation — [X]/10
+✓ / ✗ [same format]
+
+## Top 3 Priorities
+1. [Most impactful fix — what to do and why]
+2. [Second priority]
+3. [Third priority]
+```
+
+For each failing item, include:
+- **What's wrong**: specific element and current value
+- **Why it matters**: impact on search visibility or user experience
+- **How to fix**: concrete action (e.g., "Add `<meta name="description" content="...">` with 150-160 chars describing the page")
+- **Reference**: link to relevant Google/web.dev guideline where helpful
+
+## Rules
+
+- One page at a time — screenshot at each phase
+- Be specific: "the hero image (1920×1080, 2.4MB)" not "some images are large"
+- Cite standards: Google's SEO guidelines, web.dev, Schema.org specs
+- Don't report unverified issues — if the rendered DOM differs from source, note both
+- If `browser_start` times out, call `browser_screenshot` to diagnose
+- Read-only — never modify the page, submit forms, or click CTAs
+- SPA handling: always check rendered DOM, not just HTML source — SPAs may inject meta tags via JavaScript