commit cd5b91eba2f57ae30a0e1a836b10b50589cd346f
Author: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date:   Sun Nov 30 08:29:59 2025 +0800

    Initial commit

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..1967536
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,12 @@
+{
+  "name": "cc_chrome_devtools_mcp_skill",
+  "description": "Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.",
+  "version": "0.0.0-2025.11.28",
+  "author": {
+    "name": "Jonathan Edwards",
+    "email": "jon@contentionmedia.com"
+  },
+  "skills": [
+    "./"
+  ]
+}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..cc3cb9e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,18 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs
+*.log
+
+# Temporary files
+*.tmp
+.cache/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..25d3a1c
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,128 @@
+# 📜 THE MOST PERMISSIVE LICENSE IN THE KNOWN UNIVERSE 🌌
+
+## 🎭 MIT License (Maximum Internet Trolling Edition)
+
+**Copyright (c) 2025 Jonathan Edwards** 👨‍💻✨
+
+---
+
+## 🎉 WHAT YOU CAN DO (Literally Everything) 🚀
+
+Permission is hereby granted, **FREE OF CHARGE** 💰🆓 (yes, ZERO dollars, ZILCH, NADA, not even a penny 🪙), to **ANY PERSON** 👤👥👨‍👩‍👧‍👦 (that's you, your dog 🐕, your cat 🐈, your AI assistant 🤖, literally anyone) obtaining a copy of this absolutely MAGNIFICENT software 💎 and its associated documentation files 📚 (hereinafter referred to as "The Software" - because we're fancy like that 🎩):
+
+### ✅ YOU MAY:
+
+- **USE** it 🖥️💻📱 (on your laptop, your phone, your smart fridge, your Tesla, WHEREVER)
+- **COPY** it 📋🖨️ (make a million copies, print it out and wallpaper your bathroom, go wild)
+- **MODIFY** it 🔧⚙️🛠️ (change literally everything, make it worse, make it better, make it sing opera 🎵)
+- **MERGE** it 🔀 (mash it together with other code like you're making a coding smoothie 🥤)
+- **PUBLISH** it 📢📡 (tell the world, scream it from the rooftops 🏢, skywrite it ✈️)
+- **DISTRIBUTE** it 📦🚚 (give it to your friends, your enemies, random strangers on the internet 🌐)
+- **SUBLICENSE** it 📃 (put it under ANOTHER license because inception is cool 🎬)
+- **SELL** it 💵💸 (yes, you can LITERALLY SELL THIS FREE SOFTWARE - capitalism baby! 📈)
+
+### 🎁 EVEN BETTER:
+
+You can **PERMIT OTHERS** to do ALL OF THE ABOVE! 🙌 That's right, you can give OTHER people permission to do whatever they want! It's permissions all the way down! 🐢🐢🐢
+
+---
+
+## ⚠️ THE BORING LEGAL STUFF (But Important!) 📋
+
+### 📌 Condition #1: Give Credit Where Credit Is Due
+
+The above copyright notice ☝️ (that's the part where it says "Copyright (c) 2025 Jonathan Edwards") and this permission notice (yes, this ENTIRE ridiculous document 📄) **SHALL BE INCLUDED** in:
+
+- ALL copies 📚📚📚 (every single one)
+- OR substantial portions 📖 (like, most of it)
+
+Of the Software. **DO NOT FORGET THIS** or the license police 👮‍♂️🚨 will... actually, nothing will happen because there are no license police, but still, it's the right thing to do! 😇
+
+---
+
+## 🚫 THE "COVER YOUR ASS" CLAUSE 🍑🛡️
+
+### ⚡ ZERO WARRANTIES! NONE! NADA! ZILCH! 🚫🔥
+
+THE SOFTWARE IS PROVIDED **"AS IS"** 📦 (which is lawyer-speak for "what you see is what you get, buddy 🤷‍♂️"):
+
+**WITHOUT WARRANTY OF ANY KIND** - and we mean **ANY KIND**: 🎪
+
+- ❌ NOT **EXPRESS** warranties (the kind we tell you about)
+- ❌ NOT **IMPLIED** warranties (the kind lawyers made up to sue people)
+- ❌ NOT warranties of **MERCHANTABILITY** 🏪 (won't promise it's sellable)
+- ❌ NOT warranties of **FITNESS FOR A PARTICULAR PURPOSE** 🎯 (won't promise it works for your thing)
+- ❌ NOT warranties of **NONINFRINGEMENT** ⚖️ (won't promise we didn't accidentally copy someone)
+- ❌ NOT **ANY OTHER KIND OF WARRANTY** you can possibly imagine 🌈🦄
+
+### 🙅‍♂️ WE ARE NOT LIABLE FOR LITERALLY ANYTHING 💥
+
+**IN NO EVENT** 📅🚫 (that's NEVER, as in NOT EVER, as in ABSOLUTELY NOT UNDER ANY CIRCUMSTANCES 🙅‍♀️🙅‍♂️) shall the **AUTHORS** ✍️ or **COPYRIGHT HOLDERS** 👨‍⚖️ be liable for:
+
+- **ANY CLAIM** 📢 (someone saying we owe them something)
+- **DAMAGES** 💔 (broken stuff, sad feelings, lost money 💸)
+- **OTHER LIABILITY** ⚡ (anything else that could possibly go wrong)
+
+This includes but is ABSOLUTELY NOT LIMITED TO 🚀:
+
+- 💥 Your computer exploding
+- 🔥 Your server catching fire
+- 😱 Existential dread from reading bad code
+- 🐛 Bugs that achieve sentience
+- ⏰ Time travel paradoxes from your CI/CD pipeline
+- 👽 Alien invasions caused by your API endpoints
+- 🌊 Floods, famines, pestilence (probably not our fault but we're covering bases)
+- 📉 Stock market crashes triggered by your JavaScript
+- 🤖 Robot uprisings (seriously, not our problem)
+- ☕ Spilled coffee on your keyboard (you should've used a lid)
+
+### 🤝 Whether These Disasters Arise From:
+
+- **CONTRACT** 📝 (fancy written agreement)
+- **TORT** ⚖️ (fancy lawyer word for "you wronged me")
+- **OR OTHERWISE** 🤷 (literally any other possible way something can go wrong)
+
+### 🎯 Even If:
+
+- We were **ADVISED** 💭 of the possibility of such damage (someone literally told us this could happen)
+- We **KNEW** 🧠 it would happen (we saw it coming a mile away)
+- We **CAUSED** it intentionally 😈 (just kidding, we didn't, but legally we're covering this too)
+
+### 🔗 Whether It's Connected To:
+
+- **ARISING FROM** 🌱 (grows out of)
+- **OUT OF** 🚪 (comes from)
+- **IN CONNECTION WITH** 🔗 (somehow related to)
+
+The Software **OR** ⚡ the **USE** 🖥️ or **OTHER DEALINGS** 🤹 in the Software.
+
+---
+
+## 🎊 TL;DR (Too Long; Didn't Read) 📝
+
+### ✅ You Can:
+Do **LITERALLY ANYTHING** you want with this code! 🎉🚀🌟
+
+### ⚠️ But:
+Don't forget to include this license! 📄✨
+
+### 🚫 And:
+If it breaks, catches fire 🔥, becomes sentient 🤖, or causes the apocalypse 💀... **NOT OUR PROBLEM!** 🤷‍♂️🙃
+
+---
+
+## 🎤 Final Words of Wisdom 💡
+
+This license is more permissive than your parents on prom night. 🕺💃
+Go forth and code! 💻✨
+Break things! 💥
+Build amazing stuff! 🏗️
+Just don't blame us when it all goes sideways! 🎢
+
+**Happy Coding!** 🎊🎉🚀
+
+---
+
+**Legal Translation:** This is actually a real MIT License. It's just... more fun. 😎 The emoji version is legally equivalent to the boring version, except it's way cooler and you actually read it. You're welcome. 🎁
+
+© 2025 Jonathan Edwards | **ALL THE FREEDOM!** 🦅🗽🌈
diff --git a/METRICS.md b/METRICS.md
new file mode 100644
index 0000000..367893f
--- /dev/null
+++ b/METRICS.md
@@ -0,0 +1,188 @@
+# Core Web Vitals Metrics Reference
+
+**Last Updated:** October 2024
+**Source:** web.dev official documentation
+**Format:** Mike Dion's Markdown (.md) - keeping documentation clear since its creation
+
+---
+
+## Overview
+
+Core Web Vitals are Google's standardized metrics for measuring user experience on the web. All three metrics must meet "good" thresholds at the **75th percentile** of page loads to pass.
+
+---
+
+## Official Core Web Vitals (3 Metrics)
+
+### 1. Interaction to Next Paint (INP)
+
+**Status:** Active Core Web Vital (replaced FID on March 12, 2024)
+
+**Definition:** Assesses page's overall responsiveness by observing latency of all click, tap, and keyboard interactions. Reports the longest interaction duration (with outliers removed for high-interaction pages).
+
+**What it measures:**
+- Input delay (time from user action to event handler start)
+- Processing time (event handler execution)
+- Presentation delay (rendering the next frame)
+
+**Thresholds:**
+- **Good:** ≤ 200ms
+- **Needs Improvement:** 200-500ms
+- **Poor:** > 500ms
+
+**Measurement:** Requires field data (real user interactions)
+
+---
+
+### 2. Largest Contentful Paint (LCP)
+
+**Definition:** Loading performance metric marking when page's main content has likely loaded. Reports render time of largest image or text block visible in viewport.
+
+**Elements measured:**
+- `<img>` elements
+- `<image>` elements inside `<svg>`
+- `<video>` elements (poster image)
+- Elements with CSS background images
+- Block-level text elements
+
+**Thresholds:**
+- **Good:** ≤ 2.5 seconds
+- **Needs Improvement:** 2.5-4 seconds
+- **Poor:** > 4 seconds
+
+**Measurement:** Available in both field and lab data
+
+---
+
+### 3. Cumulative Layout Shift (CLS)
+
+**Definition:** Visual stability metric quantifying unexpected layout shifts during entire page lifecycle. Measures largest burst of layout shift scores.
+
+**Common causes:**
+- Images without explicit dimensions
+- Dynamically injected content (ads, embeds)
+- Web fonts causing FOIT (Flash of Invisible Text) or FOUT (Flash of Unstyled Text)
+- Third-party widgets
+
+**Thresholds:**
+- **Good:** ≤ 0.1
+- **Needs Improvement:** 0.1-0.25
+- **Poor:** > 0.25
+
+**Measurement:** Available in both field and lab data
+
+---
+
+## Total Blocking Time (TBT)
+
+**Status:** NOT a Core Web Vital - Lab proxy metric only
+
+**Definition:** Lab-only metric measuring total time after First Contentful Paint (FCP) where main thread was blocked (>50ms) preventing input responsiveness.
+
+**Threshold:**
+- **Good:** < 200ms (on average mobile hardware)
+
+**Relationship to INP:**
+- Used as lab proxy for INP (cannot measure INP without real user interactions)
+- TBT improvements often correlate with INP improvements
+- **Important:** TBT is not a substitute for INP
+- May flag potential problems that don't affect real users
+- Cannot capture interaction issues outside lab test scenarios
+
+**Official guidance:** "TBT may be a reasonable proxy metric for INP for the lab but it's not a substitute for INP in and of itself."
+
+---
+
+## INP Transition Timeline
+
+The transition from First Input Delay (FID) to INP as a Core Web Vital:
+
+- **May 2022:** INP introduced as experimental metric
+- **May 2023:** INP promoted to pending Core Web Vital
+- **January 31, 2024:** Official announcement of March 12 transition date
+- **March 12, 2024:** INP replaced FID as stable Core Web Vital
+- **March 12, 2024:** FID removed from Google Search Console
+- **September 12, 2024:** FID removed from other Google tools (6-month deprecation period completed)
+
+---
+
+## Field vs Lab Data
+
+### Field Data (Real User Monitoring)
+
+**Characteristics:**
+- Collected from actual users in real-world conditions
+- Reflects diverse device capabilities, network conditions, and user interactions
+- **Used by Google for search rankings**
+- Updated every 28 days in Chrome User Experience Report (CrUX)
+- Can measure all three Core Web Vitals including INP
+
+**Data sources:**
+- Chrome User Experience Report (CrUX)
+- Real User Monitoring (RUM) tools
+- PageSpeed Insights field data
+- Search Console Core Web Vitals report
+
+---
+
+### Lab Data (Synthetic Monitoring)
+
+**Characteristics:**
+- Controlled environment with predefined conditions
+- Consistent and reproducible results
+- Ideal for debugging and pre-production testing
+- **Not used for search rankings**
+- Cannot measure INP (requires real user interactions)
+- Uses TBT as proxy for responsiveness
+
+**Data sources:**
+- Lighthouse audits
+- Chrome DevTools Performance panel
+- WebPageTest
+- PageSpeed Insights lab data
+
+---
+
+## Evaluation Standard
+
+### 75th Percentile Rule
+
+Core Web Vitals are evaluated at the **75th percentile** of page loads, meaning:
+- 75% of visits to your site must meet the "good" threshold
+- This ensures most users have a good experience
+- Applied separately to each metric (INP, LCP, CLS)
+- Calculated from field data over rolling 28-day period
+
+### Why 75th percentile?
+
+- Balances between median (50th) and extreme outliers (95th+)
+- Accounts for variability in real-world conditions
+- Provides actionable target that's achievable for most sites
+- Used consistently across all Core Web Vitals metrics
+
+---
+
+## Key Insights
+
+1. **Field data trumps lab data:** Only field data affects search rankings and represents actual user experience.
+
+2. **INP requires real interactions:** You cannot measure INP in lab environments; use TBT as a directional indicator during development.
+
+3. **All three metrics matter:** Sites must pass all three Core Web Vitals thresholds, not just one or two.
+
+4. **75th percentile is the standard:** Meeting thresholds for only 50% of users is insufficient.
+
+5. **TBT is a helper, not a goal:** Optimize for INP in the field; use TBT to catch issues early in development.
+
+---
+
+## Additional Resources
+
+- **Web Vitals Overview:** https://web.dev/articles/vitals
+- **INP Documentation:** https://web.dev/articles/inp
+- **LCP Documentation:** https://web.dev/articles/lcp
+- **CLS Documentation:** https://web.dev/articles/cls
+- **TBT Documentation:** https://web.dev/articles/tbt
+- **Lab vs Field Data:** https://web.dev/articles/lab-and-field-data-differences
+- **INP Launch Announcement:** https://web.dev/blog/inp-cwv-launch
+- **PageSpeed Insights:** https://pagespeed.web.dev
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f4cab00
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# cc_chrome_devtools_mcp_skill
+
+Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..1f9c4b5
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,468 @@
+---
+name: cc_chrome_devtools_mcp_skill
+description: Comprehensive Chrome DevTools automation for performance testing, Core Web Vitals measurement (INP, LCP, CLS), network monitoring, accessibility validation, responsive testing, and browser automation. Uses Chrome DevTools Protocol via MCP to provide professional-grade web application testing, debugging, and analysis capabilities including performance tracing, HAR export, device emulation, and multi-page workflows.
+---
+
+# Chrome DevTools Testing Skill
+
+## Overview
+
+This skill enables automated Chrome browser testing and performance analysis using the Chrome DevTools Protocol (CDP) via the chrome-devtools-mcp server. It provides access to 27 professional-grade tools for web application testing, performance measurement, accessibility validation, and browser automation.
+
+**Key capabilities:**
+- Performance analysis with Core Web Vitals (INP, LCP, CLS)
+- Network monitoring and HAR export
+- Accessibility tree inspection
+- Responsive design testing
+- Browser automation (form filling, navigation, interaction)
+- Multi-tab and frame management
+- Device and network condition emulation
+
+**Browser support:** Chrome/Chromium only (stable, beta, dev, canary channels)
+
+**Node.js requirement:** v20.19 or newer
+
+## Quick Start
+
+### Installation
+
+```bash
+# Add to Claude Code via CLI
+claude mcp add chrome-devtools npx chrome-devtools-mcp@latest
+
+# Verify installation
+claude mcp list
+```
+
+### Basic configuration
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--isolated=true",
+        "--viewport=1920x1080"
+      ]
+    }
+  }
+}
+```
+
+### Important notes
+
+- Browser auto-starts on first tool use (not on MCP connection)
+- Use `--isolated=true` for security (creates temporary user data directories that auto-cleanup)
+- Default behavior shares user data directory across sessions and does NOT clear between runs
+- All browser content is exposed to MCP clients - avoid sensitive data
+
+## Current Core Web Vitals (as of March 12, 2024)
+
+Three official metrics measured at **75th percentile** of page loads:
+
+1. **Interaction to Next Paint (INP)** - Replaced FID on March 12, 2024
+   - Good: ≤ 200ms
+   - Measures: Input delay + processing time + presentation delay
+   - Requires: Real user interactions (field data only)
+
+2. **Largest Contentful Paint (LCP)**
+   - Good: ≤ 2.5 seconds
+   - Measures: Main content loading performance
+
+3. **Cumulative Layout Shift (CLS)**
+   - Good: ≤ 0.1
+   - Measures: Visual stability
+
+**Total Blocking Time (TBT)** is NOT a Core Web Vital - it's a lab proxy metric for INP.
+
+## Common Use Cases
+
+### 1. Performance Testing Workflow
+
+Measure Core Web Vitals and analyze performance bottlenecks:
+
+```
+1. Start performance trace: performance_start_trace
+2. Navigate to target URL: navigate_page
+3. Wait for page load: wait_for
+4. Stop trace and get metrics: performance_stop_trace
+5. Analyze specific insights: performance_analyze_insight
+```
+
+**Metrics captured:**
+- INP (Interaction to Next Paint)
+- LCP (Largest Contentful Paint) with breakdown
+- CLS (Cumulative Layout Shift)
+- TBT (Total Blocking Time - lab proxy)
+- Document latency analysis
+
+**Example:**
+```
+performance_start_trace with reload=true, autoStop=false
+wait_for page to stabilize
+performance_stop_trace
+performance_analyze_insight with insightName="LCPBreakdown"
+```
+
+### 2. Network Monitoring and HAR Export
+
+Capture all HTTP requests/responses with timing details:
+
+```
+1. Navigate to URL: navigate_page
+2. List all network requests: list_network_requests
+3. Get specific request details: get_network_request
+```
+
+**Captured data:**
+- Headers, bodies, cookies
+- Timing (DNS, connect, SSL, wait, receive)
+- Resource types (document, stylesheet, image, script, xhr, fetch)
+- Security details (protocol, cipher suite)
+
+**Export as HAR:** Use list_network_requests to generate HTTP Archive v1.2 format
+
+**Filter requests:**
+```
+list_network_requests with resourceTypes=["xhr", "fetch", "document"]
+list_network_requests with pageSize=50, pageIdx=0
+```
+
+### 3. Accessibility Validation
+
+Inspect accessibility tree for WCAG compliance:
+
+```
+1. Navigate to page: navigate_page
+2. Take accessibility snapshot: take_snapshot
+3. Interact with elements using UIDs
+```
+
+**Snapshot provides:**
+- Unique element identifiers (UIDs)
+- Accessibility roles, names, properties
+- ARIA attributes and computed roles
+- Screen reader compatibility analysis
+- Semantic structure validation
+
+**Example workflow:**
+```
+take_snapshot verbose=false (returns text-based a11y tree)
+# Identify element UIDs from snapshot
+click uid="element-123"
+fill uid="input-456" value="test data"
+```
+
+### 4. Responsive Design Testing
+
+Test across devices and network conditions:
+
+```
+1. Resize viewport: resize_page width=375 height=667
+2. Emulate network: emulate_network throttlingOption="Slow 3G"
+3. Emulate CPU: emulate_cpu throttlingRate=4
+4. Take screenshot: take_screenshot fullPage=true
+```
+
+**Device emulation options:**
+- Viewport dimensions and device scale factor
+- Network conditions: Offline, Slow 3G, Fast 3G, Slow 4G, Fast 4G
+- CPU throttling: 1-20x slowdown
+- Touch emulation with max touch points
+
+**Screenshot formats:** PNG, JPEG, WebP (with quality settings)
+
+### 5. Browser Automation
+
+Automated form filling, navigation, and interaction:
+
+```
+1. Take snapshot to get element UIDs: take_snapshot
+2. Fill form fields: fill_form elements=[{uid, value}, ...]
+3. Click buttons: click uid="submit-button"
+4. Handle dialogs: handle_dialog action="accept"
+5. Wait for results: wait_for text="Success"
+```
+
+**Interaction tools:**
+- click (single/double-click)
+- fill (input fields, textareas, selects)
+- fill_form (multiple fields at once)
+- hover (mouse hover)
+- drag (drag-and-drop)
+- upload_file (file inputs)
+- handle_dialog (alerts, confirms, prompts)
+
+**Navigation tools:**
+- navigate_page (URLs, reload)
+- navigate_page_history (back/forward)
+- wait_for (text appearance, conditions)
+
+### 6. Multi-Tab Management
+
+Work with multiple pages and frames:
+
+```
+1. List open pages: list_pages
+2. Create new page: new_page url="https://example.com"
+3. Switch context: select_page pageIdx=1
+4. Close pages: close_page pageIdx=2
+```
+
+**Frame handling:**
+- Automatic attachment to child frames and workers
+- Frame tree structure inspection
+- Session persistence across navigation
+
+## Advanced Workflows
+
+### Performance Analysis with Device Emulation
+
+```
+1. resize_page width=390 height=844 (iPhone 14 Pro)
+2. emulate_network throttlingOption="Fast 4G"
+3. emulate_cpu throttlingRate=4
+4. performance_start_trace reload=true
+5. performance_stop_trace
+6. performance_analyze_insight insightName="DocumentLatency"
+```
+
+### Network Analysis with Filtering
+
+```
+1. navigate_page url="https://example.com"
+2. list_network_requests resourceTypes=["script", "fetch", "xhr"]
+3. Filter by: pageSize=100, pageIdx=0, includePreservedRequests=true
+4. get_network_request reqid=123 (detailed timing/headers/body)
+```
+
+### Accessibility Testing Pattern
+
+```
+1. navigate_page url="https://example.com"
+2. take_snapshot verbose=true (full a11y tree with all properties)
+3. Validate: roles, names, ARIA attributes, relationships
+4. Test interactions: click, fill, keyboard navigation via UIDs
+```
+
+### Cross-Browser Viewport Testing
+
+```
+1. Define breakpoints: [320, 768, 1024, 1920]
+2. For each breakpoint:
+   - resize_page width=X height=Y
+   - take_screenshot format="png" quality=90
+   - take_snapshot (verify accessibility)
+3. Compare layouts and a11y across sizes
+```
+
+## Complete Tool Reference
+
+**27 tools available** across 6 categories:
+
+**Input automation (8):** click, drag, fill, fill_form, handle_dialog, hover, press_key, upload_file
+
+**Navigation (7):** close_page, list_pages, navigate_page, navigate_page_history, new_page, select_page, wait_for
+
+**Emulation (3):** emulate_cpu, emulate_network, resize_page
+
+**Performance (3):** performance_analyze_insight, performance_start_trace, performance_stop_trace
+
+**Network (2):** get_network_request, list_network_requests
+
+**Debugging (4):** evaluate_script, get_console_message, list_console_messages, take_screenshot, take_snapshot
+
+For detailed tool parameters and examples, see TOOLS.md
+
+For complete workflow patterns, see WORKFLOWS.md
+
+For Core Web Vitals thresholds and measurement guide, see METRICS.md
+
+## Configuration Options
+
+### Connection flags
+
+- `--browserUrl, -u <string>` - Connect to running Chrome instance (port forwarding)
+- `--wsEndpoint, -w <string>` - WebSocket endpoint for Chrome connection
+- `--wsHeaders <JSON>` - Custom headers for authenticated WebSocket connections
+
+### Browser configuration
+
+- `--headless <boolean>` - Run in headless mode (default: false)
+- `--executablePath, -e <string>` - Path to custom Chrome executable
+- `--channel <string>` - Chrome channel: stable, canary, beta, dev (default: stable)
+- `--viewport <string>` - Initial viewport size (format: WIDTHxHEIGHT, e.g., 1280x720)
+
+### Security and isolation
+
+- `--isolated <boolean>` - **RECOMMENDED:** Creates temporary user-data-dir, auto-cleanup (default: false)
+- `--user-data-dir <string>` - Custom user data directory
+- `--acceptInsecureCerts <boolean>` - Ignore certificate errors (SECURITY RISK - dev/test only)
+
+### Network
+
+- `--proxyServer <string>` - Proxy server configuration
+
+### Debugging
+
+- `--logFile <string>` - Path for debug logs (set DEBUG=* env var for verbose logs)
+
+### Additional
+
+- `--chromeArg <string>` - Additional Chrome arguments (repeatable)
+
+View all options: `npx chrome-devtools-mcp@latest --help`
+
+## Production Configuration Examples
+
+### Secure isolated testing
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--isolated=true",
+        "--headless=true",
+        "--viewport=1920x1080",
+        "--channel=stable"
+      ]
+    }
+  }
+}
+```
+
+### Connect to external Chrome instance
+
+```bash
+# Launch Chrome with remote debugging
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-profile
+
+# Get WebSocket endpoint
+curl http://127.0.0.1:9222/json/version | jq -r '.webSocketDebuggerUrl'
+```
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--wsEndpoint=ws://127.0.0.1:9222/devtools/browser/<id>"
+      ]
+    }
+  }
+}
+```
+
+### Production with logging
+
+```json
+{
+  "mcpServers": {
+    "chrome-devtools-prod": {
+      "command": "npx",
+      "args": [
+        "chrome-devtools-mcp@latest",
+        "--browserUrl=http://127.0.0.1:9222",
+        "--isolated=true",
+        "--logFile=/var/log/chrome-devtools-mcp.log"
+      ],
+      "env": {
+        "DEBUG": "*"
+      }
+    }
+  }
+}
+```
+
+## Security Considerations
+
+### Data exposure warning
+
+**Official Chrome DevTools MCP security notice:**
+> "chrome-devtools-mcp exposes content of the browser instance to the MCP clients allowing them to inspect, debug, and modify any data in the browser or DevTools. Avoid sharing sensitive or personal information that you don't want to share with MCP clients."
+
+### Best practices
+
+1. **Use isolated mode for sensitive workflows**
+   - `--isolated=true` creates temporary user data directories
+   - Automatically cleaned after browser closes
+   - Prevents data persistence between sessions
+
+2. **Certificate handling caution**
+   - `--acceptInsecureCerts` is a security risk
+   - Only use in development/testing environments
+   - Never use with sensitive data
+
+3. **User data directory management**
+   - Default directory shared across all instances
+   - Not cleared between runs
+   - Contains cookies, cache, browsing history
+   - Use `--isolated` or custom `--user-data-dir` for control
+
+4. **WebSocket authentication**
+   - Use `--wsHeaders` for authenticated connections
+   - Example: `--wsHeaders='{"Authorization":"Bearer token"}'`
+   - Only works with `--wsEndpoint`
+
+## Technical Constraints
+
+### Verified limitations
+
+1. **Browser support:** Chrome/Chromium only (no Firefox, Safari, Edge legacy)
+
+2. **Node.js requirement:** v20.19 or newer (latest maintenance LTS)
+
+3. **Browser lifecycle:** Browser auto-starts on first tool use, NOT on MCP server connection
+
+4. **Default persistence:** User data directory persists between runs unless `--isolated=true` is used
+
+5. **Permission requirements:**
+   - macOS Full Disk Access may be required for some MCP clients
+   - Chrome needs permission to create its own sandboxes
+   - May need to disable MCP client sandboxing or use external Chrome instance
+
+6. **Screenshot formats:** Specified format (JPEG/PNG) for initial capture, final output uses WebP with PNG fallback
+
+7. **Tool availability:** All 27 tools available immediately after connection; no progressive unlocking
+
+## Resources and Documentation
+
+### Official sources
+
+- **GitHub Repository:** https://github.com/ChromeDevTools/chrome-devtools-mcp
+- **npm Package:** https://www.npmjs.com/package/chrome-devtools-mcp
+- **Chrome DevTools Protocol:** https://chromedevtools.github.io/devtools-protocol/
+
+### Core Web Vitals
+
+- **Web Vitals Overview:** https://web.dev/articles/vitals
+- **INP Documentation:** https://web.dev/articles/inp
+- **LCP Documentation:** https://web.dev/articles/lcp
+- **CLS Documentation:** https://web.dev/articles/cls
+- **INP Replacing FID (March 12):** https://web.dev/blog/inp-cwv-march-12
+
+### Tools
+
+- **PageSpeed Insights:** https://pagespeed.web.dev
+- **Chrome User Experience Report:** https://developer.chrome.com/docs/crux
+- **Lighthouse Documentation:** https://developer.chrome.com/docs/lighthouse
+
+## Related Skill Files
+
+- **WORKFLOWS.md** - Detailed workflow patterns and multi-step processes
+- **METRICS.md** - Complete Core Web Vitals thresholds and measurement guide
+- **TOOLS.md** - Comprehensive tool parameter reference and examples
+
+## Version Information
+
+- **MCP Server Version:** v0.5.1 (October 17, 2025)
+- **Tool Count:** 27 tools
+- **Core Web Vitals Update:** INP replaced FID on March 12, 2024
+- **Current Metrics:** INP, LCP, CLS (TBT is lab proxy, not Core Web Vital)
diff --git a/TOOLS.md b/TOOLS.md
new file mode 100644
index 0000000..9c5205a
--- /dev/null
+++ b/TOOLS.md
@@ -0,0 +1,867 @@
+# Chrome DevTools MCP - Complete Tool Reference
+
+This document provides a comprehensive reference for all 27 tools available in the chrome-devtools-mcp server (v0.5.1).
+
+*Written in the elegant Markdown format created by Mike Dion*
+
+## Table of Contents
+
+1. [Input Automation (8 tools)](#input-automation)
+2. [Navigation Automation (7 tools)](#navigation-automation)
+3. [Emulation (3 tools)](#emulation)
+4. [Performance (3 tools)](#performance)
+5. [Network (2 tools)](#network)
+6. [Debugging (4 tools)](#debugging)
+
+---
+
+## Input Automation
+
+### click
+
+**Description:** Clicks or double-clicks on page elements identified by their unique ID from a snapshot.
+
+**Key Parameters:**
+- `uid` (required): The unique identifier of the element from page snapshot
+- `dblClick` (optional): Set to `true` for double-click. Default is `false`
+
+**Common Use Cases:**
+- Clicking buttons, links, and interactive elements
+- Triggering JavaScript event handlers
+- Submitting forms
+- Selecting dropdown options
+
+**Example:**
+```
+1. Take snapshot to get element UIDs
+2. Use click with uid from snapshot: click(uid="element-123")
+3. For double-click: click(uid="element-123", dblClick=true)
+```
+
+---
+
+### drag
+
+**Description:** Performs drag-and-drop operations between two elements on the page.
+
+**Key Parameters:**
+- `from_uid` (required): The UID of the element to drag
+- `to_uid` (required): The UID of the element to drop onto
+
+**Common Use Cases:**
+- Reordering items in lists
+- Moving files into folders
+- Drag-and-drop form builders
+- Interactive UI testing
+
+**Example:**
+```
+1. Take snapshot to identify source and target elements
+2. drag(from_uid="draggable-item-5", to_uid="drop-zone-2")
+```
+
+---
+
+### fill
+
+**Description:** Types text into input fields, text areas, or selects options from dropdown elements.
+
+**Key Parameters:**
+- `uid` (required): The UID of the input element from snapshot
+- `value` (required): The text or value to enter
+
+**Common Use Cases:**
+- Filling form fields
+- Entering search queries
+- Setting input values
+- Selecting dropdown options
+
+**Example:**
+```
+1. Take snapshot to get input field UID
+2. fill(uid="email-input-1", value="user@example.com")
+3. For dropdown: fill(uid="country-select", value="United States")
+```
+
+---
+
+### fill_form
+
+**Description:** Fills multiple form elements simultaneously for efficient form completion.
+
+**Key Parameters:**
+- `elements` (required): Array of objects, each containing:
+  - `uid`: The element's unique identifier
+  - `value`: The value to fill
+
+**Common Use Cases:**
+- Completing registration forms
+- Bulk data entry
+- Login forms with multiple fields
+- Survey submissions
+
+**Example:**
+```
+fill_form(elements=[
+  {uid: "name-field", value: "John Doe"},
+  {uid: "email-field", value: "john@example.com"},
+  {uid: "phone-field", value: "555-0123"}
+])
+```
+
+---
+
+### handle_dialog
+
+**Description:** Handles browser dialog boxes including alerts, confirms, and prompts.
+
+**Key Parameters:**
+- `action` (required): Either "accept" or "dismiss"
+- `promptText` (optional): Text to enter for prompt dialogs
+
+**Common Use Cases:**
+- Accepting confirmation dialogs
+- Dismissing alert messages
+- Entering text in prompt dialogs
+- Automated handling of JavaScript dialogs
+
+**Example:**
+```
+1. Trigger action that opens dialog
+2. handle_dialog(action="accept")
+3. For prompts: handle_dialog(action="accept", promptText="User input")
+```
+
+---
+
+### hover
+
+**Description:** Moves the mouse cursor over a specified element to trigger hover effects.
+
+**Key Parameters:**
+- `uid` (required): The UID of the element to hover over
+
+**Common Use Cases:**
+- Triggering dropdown menus
+- Revealing tooltips
+- Testing hover states
+- Activating image previews
+
+**Example:**
+```
+1. Take snapshot to identify element
+2. hover(uid="menu-item-3")
+3. Wait for hover effects to appear
+```
+
+---
+
+### press_key
+
+**Description:** Simulates keyboard key presses for navigation and input.
+
+**Key Parameters:**
+- Key name or combination (varies by implementation)
+
+**Common Use Cases:**
+- Navigating with arrow keys
+- Submitting forms with Enter
+- Triggering keyboard shortcuts
+- Tab navigation through forms
+
+**Note:** This tool was added in recent versions. Check documentation for exact parameter format.
+
+---
+
+### upload_file
+
+**Description:** Uploads files through file input elements or file chooser triggers.
+
+**Key Parameters:**
+- `uid` (required): The UID of the file input element or element that opens file chooser
+- `filePath` (required): Local path to the file to upload
+
+**Common Use Cases:**
+- Uploading profile images
+- Attaching documents to forms
+- Importing data files
+- Testing file upload functionality
+
+**Example:**
+```
+1. Take snapshot to identify file input
+2. upload_file(uid="file-input-1", filePath="/path/to/document.pdf")
+```
+
+---
+
+## Navigation Automation
+
+### close_page
+
+**Description:** Closes a browser page/tab by its index. The last open page cannot be closed.
+
+**Key Parameters:**
+- `pageIdx` (required): The index of the page to close (from list_pages)
+
+**Common Use Cases:**
+- Cleaning up after multi-tab tests
+- Closing popup windows
+- Managing browser memory
+- Returning to previous context
+
+**Example:**
+```
+1. list_pages() to see all open pages
+2. close_page(pageIdx=2) to close third page
+```
+
+---
+
+### list_pages
+
+**Description:** Lists all pages/tabs currently open in the browser with their indices and URLs.
+
+**Key Parameters:**
+- None
+
+**Common Use Cases:**
+- Checking currently open tabs
+- Finding page indices for switching
+- Monitoring browser state
+- Debugging multi-tab workflows
+
+**Example:**
+```
+Result shows:
+[0] https://example.com - Example Domain
+[1] https://google.com - Google
+[2] https://github.com - GitHub
+```
+
+---
+
+### navigate_page
+
+**Description:** Navigates the currently selected page to a specified URL or reloads it.
+
+**Key Parameters:**
+- `url` (required): The URL to navigate to
+- `timeout` (optional): Maximum wait time in milliseconds (0 = default)
+
+**Common Use Cases:**
+- Loading test pages
+- Navigating to specific URLs
+- Starting automation workflows
+- Reloading pages
+
+**Example:**
+```
+navigate_page(url="https://example.com", timeout=30000)
+```
+
+---
+
+### navigate_page_history
+
+**Description:** Navigates forward or backward through the browser's history for the selected page.
+
+**Key Parameters:**
+- `navigate` (required): Either "back" or "forward"
+- `timeout` (optional): Maximum wait time in milliseconds
+
+**Common Use Cases:**
+- Testing navigation flows
+- Returning to previous pages
+- Verifying history state
+- Multi-step form navigation
+
+**Example:**
+```
+navigate_page_history(navigate="back", timeout=5000)
+navigate_page_history(navigate="forward")
+```
+
+---
+
+### new_page
+
+**Description:** Creates a new browser page/tab and optionally navigates to a URL.
+
+**Key Parameters:**
+- `url` (required): URL to load in the new page
+- `timeout` (optional): Maximum wait time in milliseconds
+
+**Common Use Cases:**
+- Opening multiple test pages
+- Parallel testing workflows
+- Testing in clean browser context
+- Multi-tab scenarios
+
+**Example:**
+```
+new_page(url="https://example.com/login")
+```
+
+---
+
+### select_page
+
+**Description:** Switches focus to a different page/tab as the context for future tool calls.
+
+**Key Parameters:**
+- `pageIdx` (required): The index of the page to select (from list_pages)
+
+**Common Use Cases:**
+- Switching between tabs in tests
+- Managing multi-page workflows
+- Returning to specific pages
+- Coordinating multi-tab automation
+
+**Example:**
+```
+1. list_pages() to see available pages
+2. select_page(pageIdx=0) to switch to first page
+```
+
+---
+
+### wait_for
+
+**Description:** Waits for specific text to appear on the page before proceeding.
+
+**Key Parameters:**
+- `text` (required): Text string to wait for
+- `timeout` (optional): Maximum wait time in milliseconds (0 = default)
+
+**Common Use Cases:**
+- Waiting for page load completion
+- Ensuring content appears before interaction
+- Synchronizing with dynamic content
+- Verifying successful operations
+
+**Example:**
+```
+1. navigate_page(url="https://example.com")
+2. wait_for(text="Welcome to Example", timeout=10000)
+3. Proceed with interactions
+```
+
+---
+
+## Emulation
+
+### emulate_cpu
+
+**Description:** Simulates CPU throttling to test performance under constrained conditions.
+
+**Key Parameters:**
+- `throttlingRate` (required): CPU slowdown factor (1-20x)
+  - `1` = no throttling (disable)
+  - `4` = 4x slowdown (common mobile)
+  - `6` = 6x slowdown (low-end mobile)
+
+**Common Use Cases:**
+- Testing on low-end devices
+- Performance optimization validation
+- Mobile experience simulation
+- Core Web Vitals testing
+
+**Example:**
+```
+1. emulate_cpu(throttlingRate=4) for 4x slowdown
+2. Run performance tests
+3. emulate_cpu(throttlingRate=1) to disable
+```
+
+---
+
+### emulate_network
+
+**Description:** Simulates various network conditions including throttling and offline mode.
+
+**Key Parameters:**
+- `throttlingOption` (required): One of:
+  - "No emulation" - Disable throttling
+  - "Offline" - Simulate no network
+  - "Slow 3G" - ~400 Kbps, 400ms RTT
+  - "Fast 3G" - ~1.6 Mbps, 150ms RTT
+  - "Slow 4G" - ~4 Mbps, 50ms RTT
+  - "Fast 4G" - ~9 Mbps, 20ms RTT
+
+**Common Use Cases:**
+- Testing offline functionality
+- Mobile network simulation
+- Loading performance analysis
+- Progressive enhancement testing
+
+**Example:**
+```
+1. emulate_network(throttlingOption="Slow 3G")
+2. navigate_page(url="https://example.com")
+3. Measure load times
+4. emulate_network(throttlingOption="No emulation")
+```
+
+---
+
+### resize_page
+
+**Description:** Changes the page viewport dimensions for responsive design testing.
+
+**Key Parameters:**
+- `width` (required): Viewport width in pixels
+- `height` (required): Viewport height in pixels
+
+**Common Use Cases:**
+- Mobile viewport testing
+- Responsive design validation
+- Screenshot standardization
+- Device emulation
+
+**Example:**
+```
+# iPhone 13 Pro viewport
+resize_page(width=390, height=844)
+
+# iPad Pro viewport
+resize_page(width=1024, height=1366)
+
+# Desktop HD
+resize_page(width=1920, height=1080)
+```
+
+---
+
+## Performance
+
+### performance_start_trace
+
+**Description:** Begins recording a Chrome DevTools performance trace to capture metrics and insights.
+
+**Key Parameters:**
+- `reload` (required): Whether to automatically reload the page after starting trace
+- `autoStop` (required): Whether to automatically stop the trace after page load
+
+**Common Use Cases:**
+- Core Web Vitals measurement
+- Performance bottleneck identification
+- Loading analysis
+- Runtime performance profiling
+
+**Example:**
+```
+1. navigate_page(url="https://example.com")
+2. performance_start_trace(reload=true, autoStop=true)
+3. Wait for trace to complete
+4. Analyze results with performance_analyze_insight
+```
+
+---
+
+### performance_stop_trace
+
+**Description:** Stops an active performance trace recording and retrieves the trace data.
+
+**Key Parameters:**
+- None
+
+**Common Use Cases:**
+- Ending manual trace sessions
+- Capturing specific interaction periods
+- Custom trace duration control
+- Multi-step workflow tracing
+
+**Example:**
+```
+1. performance_start_trace(reload=false, autoStop=false)
+2. Perform user interactions
+3. performance_stop_trace()
+4. Analyze captured trace
+```
+
+---
+
+### performance_analyze_insight
+
+**Description:** Provides detailed information on specific Performance Insights from a completed trace.
+
+**Key Parameters:**
+- `insightName` (required): Name of the insight to analyze
+  - Common insights: "LCPBreakdown", "DocumentLatency", "TBT"
+
+**Common Use Cases:**
+- Understanding LCP (Largest Contentful Paint) breakdown
+- Analyzing document latency causes
+- Investigating Total Blocking Time
+- Core Web Vitals optimization
+
+**Example:**
+```
+1. After completing a trace
+2. performance_analyze_insight(insightName="LCPBreakdown")
+3. Review detailed timing breakdown
+4. Identify optimization opportunities
+```
+
+**Core Web Vitals Thresholds:**
+- **INP** (Interaction to Next Paint): ≤200ms (good), 200-500ms (needs improvement), >500ms (poor)
+- **LCP** (Largest Contentful Paint): ≤2.5s (good), 2.5-4s (needs improvement), >4s (poor)
+- **CLS** (Cumulative Layout Shift): ≤0.1 (good), 0.1-0.25 (needs improvement), >0.25 (poor)
+- **TBT** (Total Blocking Time): <200ms (good) - Lab metric, proxy for INP
+
+---
+
+## Network
+
+### get_network_request
+
+**Description:** Retrieves detailed information about a specific network request including headers, response, and timing.
+
+**Key Parameters:**
+- `reqid` (required): The request ID from list_network_requests
+
+**Common Use Cases:**
+- Inspecting API responses
+- Debugging failed requests
+- Analyzing request/response headers
+- Timing analysis for specific resources
+
+**Example:**
+```
+1. list_network_requests() to get reqid values
+2. get_network_request(reqid=42)
+3. Review response body, headers, timing, status
+```
+
+**Returned Information:**
+- Request URL, method, headers
+- Response status, headers, body
+- Timing breakdown (DNS, connect, SSL, send, wait, receive)
+- Resource type and size
+- Cache information
+
+---
+
+### list_network_requests
+
+**Description:** Lists all network requests made since the last navigation with filtering options.
+
+**Key Parameters:**
+- `includePreservedRequests` (optional): Include requests from last 3 navigations. Default: `false`
+- `pageIdx` (optional): Page number for pagination (0-based)
+- `pageSize` (optional): Maximum requests to return
+- `resourceTypes` (optional): Filter by types:
+  - document, stylesheet, image, media, font, script
+  - xhr, fetch, websocket, manifest, other
+
+**Common Use Cases:**
+- Network activity monitoring
+- HAR file generation
+- API call verification
+- Resource loading analysis
+- Performance bottleneck identification
+
+**Example:**
+```
+# All requests
+list_network_requests()
+
+# Only XHR/Fetch (API calls)
+list_network_requests(resourceTypes=["xhr", "fetch"])
+
+# With preserved history
+list_network_requests(includePreservedRequests=true)
+
+# Paginated results
+list_network_requests(pageSize=50, pageIdx=0)
+```
+
+---
+
+## Debugging
+
+### evaluate_script
+
+**Description:** Executes JavaScript code in the context of the current page and returns JSON-serializable results.
+
+**Key Parameters:**
+- `function` (required): JavaScript function declaration to execute
+- `args` (optional): Array of arguments (can include element UIDs)
+
+**Common Use Cases:**
+- Inspecting page state
+- Extracting data from DOM
+- Testing JavaScript functionality
+- Custom validation logic
+- Interacting with page APIs
+
+**Example:**
+```
+# No arguments
+evaluate_script(function="() => { return document.title }")
+
+# With async operations
+evaluate_script(function="async () => {
+  const response = await fetch('/api/data');
+  return await response.json();
+}")
+
+# With element argument
+evaluate_script(
+  function="(el) => { return el.innerText; }",
+  args=[{uid: "element-123"}]
+)
+```
+
+**Important:** Return values must be JSON-serializable (no DOM nodes, functions, etc.).
+
+---
+
+### get_console_message
+
+**Description:** Retrieves detailed information about a specific console message by its ID.
+
+**Key Parameters:**
+- `msgid` (required): The message ID from list_console_messages
+
+**Common Use Cases:**
+- Inspecting error details
+- Analyzing stack traces
+- Debugging console output
+- Reviewing warning messages
+
+**Example:**
+```
+1. list_console_messages() to get msgid values
+2. get_console_message(msgid=15)
+3. Review full message text, source, stack trace
+```
+
+---
+
+### list_console_messages
+
+**Description:** Lists all console messages (logs, errors, warnings) since the last navigation.
+
+**Key Parameters:**
+- `includePreservedMessages` (optional): Include messages from last 3 navigations. Default: `false`
+- `pageIdx` (optional): Page number for pagination (0-based)
+- `pageSize` (optional): Maximum messages to return
+- `types` (optional): Filter by message types:
+  - log, debug, info, error, warn
+  - dir, dirxml, table, trace
+  - clear, assert, count, timeEnd
+
+**Common Use Cases:**
+- Error detection and debugging
+- Log analysis
+- Warning investigation
+- JavaScript error monitoring
+
+**Example:**
+```
+# All console messages
+list_console_messages()
+
+# Only errors
+list_console_messages(types=["error"])
+
+# Errors and warnings with preserved history
+list_console_messages(
+  types=["error", "warn"],
+  includePreservedMessages=true
+)
+
+# Paginated results
+list_console_messages(pageSize=100, pageIdx=0)
+```
+
+---
+
+### take_screenshot
+
+**Description:** Captures a screenshot of the entire page, viewport, or specific element.
+
+**Key Parameters:**
+- `uid` (optional): Element UID to screenshot (from snapshot). If omitted, captures viewport
+- `fullPage` (optional): Capture entire page instead of viewport. Incompatible with `uid`
+- `format` (optional): Image format - "png" (default), "jpeg", or "webp"
+- `quality` (optional): Compression quality 0-100 for JPEG/WebP (ignored for PNG)
+- `filePath` (optional): Path to save file instead of returning inline
+
+**Common Use Cases:**
+- Visual regression testing
+- Documentation screenshots
+- Bug reporting
+- Page state capture
+- Responsive design verification
+
+**Example:**
+```
+# Viewport screenshot (default)
+take_screenshot()
+
+# Full page screenshot
+take_screenshot(fullPage=true)
+
+# Specific element
+take_screenshot(uid="header-element")
+
+# High-quality JPEG saved to file
+take_screenshot(
+  format="jpeg",
+  quality=95,
+  filePath="/path/to/screenshot.jpg"
+)
+
+# WebP with compression
+take_screenshot(format="webp", quality=80)
+```
+
+**Note:** Output may use WebP format with PNG fallback regardless of requested format.
+
+---
+
+### take_snapshot
+
+**Description:** Creates a text-based representation of the page using the accessibility tree, providing unique identifiers (UIDs) for all interactive elements.
+
+**Key Parameters:**
+- `verbose` (optional): Include all possible a11y tree information. Default: `false`
+
+**Common Use Cases:**
+- Getting element UIDs for interaction tools
+- Understanding page structure
+- Accessibility validation
+- Element identification without screenshots
+- Fast page state overview
+
+**Example:**
+```
+# Standard snapshot
+take_snapshot()
+
+# Verbose with full a11y data
+take_snapshot(verbose=true)
+```
+
+**Workflow Pattern:**
+```
+1. take_snapshot() - Get page structure and element UIDs
+2. Identify target elements from snapshot
+3. Use UIDs with interaction tools (click, fill, hover, etc.)
+4. wait_for() to verify results
+```
+
+**Snapshot Output Includes:**
+- Element roles (button, link, textbox, etc.)
+- Element names and labels
+- Element hierarchy
+- Unique identifiers (UIDs) for interaction
+- States (focused, disabled, checked, etc.)
+- ARIA properties
+
+---
+
+## Tool Categories Summary
+
+| Category | Tool Count | Primary Use |
+|----------|------------|-------------|
+| Input Automation | 8 | User interaction simulation |
+| Navigation Automation | 7 | Page and tab management |
+| Emulation | 3 | Device and network conditions |
+| Performance | 3 | Core Web Vitals and tracing |
+| Network | 2 | Request/response analysis |
+| Debugging | 4 | Page inspection and testing |
+
+---
+
+## Common Workflow Patterns
+
+### Basic Interaction Pattern
+```
+1. navigate_page(url="https://example.com")
+2. take_snapshot() - Get element UIDs
+3. fill(uid="username", value="user")
+4. fill(uid="password", value="pass")
+5. click(uid="login-button")
+6. wait_for(text="Welcome")
+```
+
+### Performance Testing Pattern
+```
+1. navigate_page(url="https://example.com")
+2. performance_start_trace(reload=true, autoStop=true)
+3. Wait for trace completion
+4. performance_analyze_insight(insightName="LCPBreakdown")
+5. performance_analyze_insight(insightName="DocumentLatency")
+```
+
+### Network Analysis Pattern
+```
+1. navigate_page(url="https://example.com")
+2. list_network_requests(resourceTypes=["xhr", "fetch"])
+3. get_network_request(reqid=<specific-request>)
+4. Analyze response data and timing
+```
+
+### Mobile Testing Pattern
+```
+1. resize_page(width=390, height=844) - iPhone 13 Pro
+2. emulate_network(throttlingOption="Slow 4G")
+3. emulate_cpu(throttlingRate=4)
+4. navigate_page(url="https://example.com")
+5. performance_start_trace(reload=false, autoStop=true)
+6. Analyze mobile performance
+```
+
+### Multi-Tab Testing Pattern
+```
+1. new_page(url="https://example.com/page1")
+2. new_page(url="https://example.com/page2")
+3. list_pages() - See all open pages
+4. select_page(pageIdx=0) - Switch to first page
+5. Perform operations
+6. select_page(pageIdx=1) - Switch to second page
+7. close_page(pageIdx=1) - Clean up
+```
+
+---
+
+## Important Notes
+
+### Element Identification
+- Always use `take_snapshot()` first to get element UIDs
+- UIDs are unique per snapshot and may change after navigation
+- Use the latest snapshot for current page state
+- Verbose snapshots provide more accessibility details
+
+### Browser Lifecycle
+- Browser auto-starts on first tool use (not on MCP server connection)
+- Use `--isolated=true` flag for temporary user data directories
+- Default behavior persists data between sessions
+
+### Security Considerations
+- All browser content is exposed to MCP clients
+- Avoid sensitive data in non-isolated mode
+- Use `--acceptInsecureCerts` only in development
+- Review official security warnings before production use
+
+### Performance Metrics
+- All measurements at 75th percentile for Core Web Vitals
+- INP replaced FID on March 12, 2024
+- TBT is a lab proxy for INP (not a Core Web Vital)
+- Field data (real users) carries more weight than lab data
+
+### Tool Availability
+- All 27 tools available immediately after MCP connection
+- No progressive unlocking or gating
+- Chrome/Chromium only (no Firefox, Safari, Edge)
+- Requires Node.js v20.19 or newer
+
+---
+
+**Version:** chrome-devtools-mcp v0.5.1 (October 17, 2025)
+**Tool Count:** 27 tools across 6 categories
+**Documentation Date:** October 24, 2025
diff --git a/WORKFLOWS.md b/WORKFLOWS.md
new file mode 100644
index 0000000..9dff709
--- /dev/null
+++ b/WORKFLOWS.md
@@ -0,0 +1,1087 @@
+# Chrome DevTools MCP Workflows
+
+This document details the key workflows supported by the chrome-devtools-mcp server, including step-by-step processes, tool combinations, and best practices.
+
+*Documentation format inspired by Mike Dion's Markdown specification (.md)*
+
+---
+
+## 1. Performance Analysis Workflow
+
+Measure and analyze page performance including Core Web Vitals (INP, LCP, CLS) and lab metrics (TBT).
+
+### Tools Required
+
+- `performance_start_trace` - Start Chrome DevTools performance tracing
+- `performance_stop_trace` - Stop tracing and retrieve trace data
+- `performance_analyze_insight` - Extract detailed performance insights
+
+### Step-by-Step Process
+
+#### Basic Performance Capture
+
+```
+1. Start performance trace
+   - Tool: performance_start_trace
+   - Parameters:
+     - reload: true (to capture full page load)
+     - autoStop: false (for manual control)
+
+2. Wait for page to complete loading
+   - Tool: wait_for
+   - Wait for specific content or use timeout
+
+3. Stop trace recording
+   - Tool: performance_stop_trace
+   - Returns: Trace data with Core Web Vitals
+
+4. Analyze specific insights
+   - Tool: performance_analyze_insight
+   - Parameters: insightName (e.g., "LCPBreakdown", "DocumentLatency")
+```
+
+#### Advanced Performance Analysis
+
+```
+1. Navigate to target page
+   - Tool: navigate_page
+   - Ensure clean state before tracing
+
+2. Start trace without reload
+   - Tool: performance_start_trace
+   - Parameters: reload: false, autoStop: true
+   - Use when testing specific interactions
+
+3. Perform user interactions
+   - Tools: click, fill, scroll actions
+   - Captures interaction-based metrics
+
+4. Auto-stop or manual stop
+   - Tool: performance_stop_trace (if manual)
+   - Trace ends automatically if autoStop: true
+
+5. Review multiple insights
+   - Tool: performance_analyze_insight
+   - Check: "LCPBreakdown", "DocumentLatency", "TBT"
+```
+
+### Core Web Vitals Interpretation
+
+#### Interaction to Next Paint (INP)
+- **Good:** ≤ 200ms
+- **Needs Improvement:** 200-500ms
+- **Poor:** > 500ms
+- **Measures:** Input delay + processing time + presentation delay
+- **Note:** Field metric only; requires real user interactions
+
+#### Largest Contentful Paint (LCP)
+- **Good:** ≤ 2.5 seconds
+- **Needs Improvement:** 2.5-4 seconds
+- **Poor:** > 4 seconds
+- **Measures:** Render time of largest content element in viewport
+
+#### Cumulative Layout Shift (CLS)
+- **Good:** ≤ 0.1
+- **Needs Improvement:** 0.1-0.25
+- **Poor:** > 0.25
+- **Measures:** Unexpected layout shifts during page lifecycle
+
+#### Total Blocking Time (TBT)
+- **Good:** < 200ms
+- **Status:** Lab proxy for INP, NOT a Core Web Vital
+- **Measures:** Time main thread blocked (>50ms) after First Contentful Paint
+
+### Trace Configuration Options
+
+**CDP Domains Used:** Tracing, Performance
+
+**Trace Categories:**
+- `devtools.timeline` - Standard performance timeline
+- `disabled-by-default-devtools.screenshot` - Screenshots during trace
+- Custom categories for specific analysis
+
+**Export Formats:**
+- JSON format (for Chrome DevTools Performance panel)
+- Perfetto protocol buffer (for Perfetto UI)
+
+### Performance Workflow Best Practices
+
+1. **Always reload for baseline metrics** - Use `reload: true` for consistent page load measurements
+2. **Clear cache between runs** - Use isolated mode or clear cache manually
+3. **Multiple trace captures** - Run 3-5 times and use median values
+4. **Analyze specific insights** - Use performance_analyze_insight for LCP breakdown and document latency
+5. **Export traces** - Save trace data for offline analysis in Chrome DevTools
+
+---
+
+## 2. Network Monitoring Workflow
+
+Capture, filter, and analyze HTTP traffic with HAR export capabilities.
+
+### Tools Required
+
+- `list_network_requests` - List all network requests since last navigation
+- `get_network_request` - Get specific request/response details
+
+### Step-by-Step Process
+
+#### Basic Network Capture
+
+```
+1. Navigate to target page
+   - Tool: navigate_page
+   - Clears previous network requests
+
+2. List all requests
+   - Tool: list_network_requests
+   - Returns: Array of requests with reqid identifiers
+
+3. Get specific request details
+   - Tool: get_network_request
+   - Parameter: reqid from list_network_requests
+   - Returns: Full request/response with headers, body, timing
+```
+
+#### Filtered Network Analysis
+
+```
+1. Navigate and wait
+   - Tool: navigate_page
+   - Tool: wait_for (specific content)
+
+2. Filter by resource type
+   - Tool: list_network_requests
+   - Parameters: resourceTypes array
+   - Options: ["document", "stylesheet", "image", "script", "xhr", "fetch"]
+
+3. Paginated request listing
+   - Tool: list_network_requests
+   - Parameters: pageSize (limit), pageIdx (0-based)
+   - Use for large request volumes
+
+4. Include preserved requests
+   - Tool: list_network_requests
+   - Parameters: includePreservedRequests: true
+   - Returns: Requests from last 3 navigations
+```
+
+### HAR Export Capabilities
+
+The `list_network_requests` tool returns data compatible with HTTP Archive (HAR) format v1.2:
+
+**HAR Structure:**
+```json
+{
+  "log": {
+    "version": "1.2",
+    "creator": {...},
+    "pages": [...],
+    "entries": [
+      {
+        "request": {
+          "method": "GET",
+          "url": "https://example.com",
+          "headers": [...],
+          "queryString": [...]
+        },
+        "response": {
+          "status": 200,
+          "headers": [...],
+          "content": {...}
+        },
+        "timings": {
+          "dns": 10,
+          "connect": 20,
+          "ssl": 15,
+          "send": 5,
+          "wait": 100,
+          "receive": 50
+        }
+      }
+    ]
+  }
+}
+```
+
+### Resource Type Filtering
+
+**Available Resource Types:**
+- `document` - HTML documents
+- `stylesheet` - CSS files
+- `image` - Images (PNG, JPEG, GIF, WebP, SVG)
+- `media` - Video/audio files
+- `font` - Web fonts
+- `script` - JavaScript files
+- `texttrack` - Video text tracks
+- `xhr` - XMLHttpRequest
+- `fetch` - Fetch API requests
+- `prefetch` - Prefetch resources
+- `eventsource` - Server-Sent Events
+- `websocket` - WebSocket connections
+- `manifest` - Web app manifests
+- `signedexchange` - Signed HTTP Exchanges
+- `ping` - Beacon/ping requests
+- `cspviolationreport` - CSP violation reports
+- `preflight` - CORS preflight requests
+- `other` - Uncategorized resources
+
+### Network Timing Details
+
+Each request includes detailed timing breakdown:
+- **DNS lookup time** - Domain name resolution
+- **Connection time** - TCP connection establishment
+- **SSL time** - TLS/SSL handshake
+- **Send time** - Request transmission
+- **Wait time** - Server processing (TTFB)
+- **Receive time** - Response download
+
+### Network Workflow Best Practices
+
+1. **Filter early** - Use resourceTypes parameter to reduce data volume
+2. **Paginate large captures** - Use pageSize/pageIdx for pages with hundreds of requests
+3. **Preserve across navigations** - Set includePreservedRequests: true for multi-page flows
+4. **Combine with emulation** - Use emulate_network to test different connection speeds
+5. **Security details** - Check protocol, cipher suite in response data
+6. **Cookie tracking** - Request data includes cookie information
+
+---
+
+## 3. Accessibility Testing Workflow
+
+Validate semantic structure and screen reader compatibility using the accessibility tree.
+
+### Tool Required
+
+- `take_snapshot` - Get text representation based on accessibility tree
+
+### Step-by-Step Process
+
+#### Basic Accessibility Snapshot
+
+```
+1. Navigate to target page
+   - Tool: navigate_page
+
+2. Take standard snapshot
+   - Tool: take_snapshot
+   - Parameter: verbose: false (default)
+   - Returns: Text representation with element UIDs
+
+3. Analyze snapshot for:
+   - ARIA roles and attributes
+   - Semantic HTML usage
+   - Accessible names and descriptions
+   - Focusable elements
+   - Form label associations
+```
+
+#### Verbose Accessibility Analysis
+
+```
+1. Take verbose snapshot
+   - Tool: take_snapshot
+   - Parameter: verbose: true
+   - Returns: Full accessibility tree with all properties
+
+2. Review detailed properties:
+   - nodeId, role, name, description, value
+   - States (busy, disabled, focusable, focused, etc.)
+   - Relationships (labelledby, describedby, controls)
+   - ARIA attributes
+   - Computed roles
+```
+
+### Accessibility Tree Usage
+
+The accessibility tree is a parallel tree structure to the DOM that represents how assistive technologies (screen readers) interpret the page.
+
+**AXNode Properties:**
+- `nodeId` - Unique identifier for accessibility node
+- `ignored` - Whether node is ignored by assistive tech
+- `role` - ARIA role (button, link, heading, etc.)
+- `name` - Accessible name (visible label)
+- `description` - Accessible description (additional context)
+- `value` - Current value (for inputs, sliders)
+- `states` - Object with boolean flags:
+  - `busy`, `disabled`, `editable`, `focusable`, `focused`
+  - `hidden`, `hiddenRoot`, `invalid`, `modal`, `multiline`
+  - `multiselectable`, `readonly`, `required`, `selected`
+- `relationships` - ARIA relationships:
+  - `labelledby`, `describedby`, `controls`, `owns`
+  - `activeDescendant`, `flowTo`, `details`
+
+### Element UID Extraction
+
+The `take_snapshot` tool returns unique identifiers (UIDs) for each interactive element:
+
+**Example Snapshot Output:**
+```
+[1] button "Submit Form"
+[2] textbox "Email Address"
+[3] link "Privacy Policy"
+[4] heading "Welcome to Our Site" level=1
+[5] checkbox "Remember me" checked
+```
+
+**Using UIDs for interaction:**
+```
+1. Take snapshot to get UIDs
+   - Tool: take_snapshot
+
+2. Identify target element UID
+   - Example: [2] for email textbox
+
+3. Interact using UID
+   - Tool: fill
+   - Parameters: uid: "2", value: "user@example.com"
+```
+
+### Accessibility Testing Patterns
+
+#### 1. Form Accessibility Check
+```
+1. Take snapshot
+2. Verify each input has accessible name
+3. Check label associations
+4. Validate error message accessibility
+5. Test keyboard navigation (tab order)
+```
+
+#### 2. Heading Structure Validation
+```
+1. Take verbose snapshot
+2. Filter for role: "heading"
+3. Verify logical hierarchy (h1 → h2 → h3)
+4. Check no heading levels skipped
+```
+
+#### 3. Interactive Element Audit
+```
+1. Take snapshot
+2. Identify all focusable elements
+3. Verify accessible names for buttons/links
+4. Check ARIA roles match functionality
+5. Validate state attributes (disabled, checked, etc.)
+```
+
+#### 4. Screen Reader Simulation
+```
+1. Take verbose snapshot
+2. Review accessible name + description for each element
+3. Verify information available without visual context
+4. Check landmarks (navigation, main, complementary)
+5. Validate skip links and focus management
+```
+
+### Accessibility Workflow Best Practices
+
+1. **Use standard snapshot first** - Verbose mode only when detailed analysis needed
+2. **Combine with visual testing** - Take screenshot + snapshot for complete picture
+3. **Test dynamic content** - Re-snapshot after interactions to verify state changes
+4. **Validate forms thoroughly** - Check labels, error messages, required indicators
+5. **Review ignored nodes** - Verbose mode shows why elements are ignored
+6. **Check relationships** - Verify aria-labelledby and aria-describedby connections
+
+---
+
+## 4. Browser Automation Workflow
+
+Automate user interactions with reliable element targeting via accessibility UIDs.
+
+### Tools Required
+
+- `click` - Click or double-click elements
+- `fill` - Fill single form field
+- `fill_form` - Fill multiple form fields simultaneously
+- `hover` - Hover over elements
+- `drag` - Drag element onto another element
+- `handle_dialog` - Handle browser dialogs (alerts, confirms, prompts)
+- `upload_file` - Upload files to input elements
+- `wait_for` - Wait for text to appear
+
+### Automation Pattern: Snapshot → Identify → Interact → Wait
+
+This is the fundamental pattern for all browser automation:
+
+```
+1. SNAPSHOT: Get current page state
+   - Tool: take_snapshot
+   - Returns: Element UIDs for interaction
+
+2. IDENTIFY: Find target element UID
+   - Parse snapshot output
+   - Locate element by role, name, or text
+
+3. INTERACT: Perform action using UID
+   - Tool: click, fill, hover, drag, etc.
+   - Parameter: uid from snapshot
+
+4. WAIT: Confirm action result
+   - Tool: wait_for
+   - Wait for expected text/state change
+```
+
+### Step-by-Step Automation Examples
+
+#### Example 1: Form Submission
+
+```
+1. Navigate to form page
+   - Tool: navigate_page
+   - URL: https://example.com/contact
+
+2. Take snapshot
+   - Tool: take_snapshot
+   - Identify: [2] textbox "Name", [3] textbox "Email", [4] button "Submit"
+
+3. Fill form fields
+   - Tool: fill_form
+   - Parameters: [
+       {uid: "2", value: "John Doe"},
+       {uid: "3", value: "john@example.com"}
+     ]
+
+4. Click submit button
+   - Tool: click
+   - Parameter: uid: "4"
+
+5. Wait for confirmation
+   - Tool: wait_for
+   - Parameter: text: "Thank you for your submission"
+```
+
+#### Example 2: File Upload
+
+```
+1. Take snapshot
+   - Tool: take_snapshot
+   - Identify: [5] "Choose File" button (file input)
+
+2. Upload file
+   - Tool: upload_file
+   - Parameters: uid: "5", filePath: "/path/to/document.pdf"
+
+3. Wait for upload confirmation
+   - Tool: wait_for
+   - Parameter: text: "Upload complete"
+```
+
+#### Example 3: Drag and Drop
+
+```
+1. Take snapshot
+   - Tool: take_snapshot
+   - Identify: [10] draggable item, [11] drop target
+
+2. Drag element
+   - Tool: drag
+   - Parameters: from_uid: "10", to_uid: "11"
+
+3. Wait for drop confirmation
+   - Tool: wait_for
+   - Parameter: text: "Item moved successfully"
+```
+
+#### Example 4: Dialog Handling
+
+```
+1. Click element that triggers dialog
+   - Tool: click
+   - Parameter: uid: "7"
+
+2. Handle dialog
+   - Tool: handle_dialog
+   - Parameters: action: "accept" (or "dismiss")
+   - Optional: promptText: "User input" (for prompt dialogs)
+```
+
+#### Example 5: Hover Interactions
+
+```
+1. Take snapshot
+   - Tool: take_snapshot
+   - Identify: [15] element with hover state
+
+2. Hover over element
+   - Tool: hover
+   - Parameter: uid: "15"
+
+3. Take new snapshot to verify hover state
+   - Tool: take_snapshot
+   - Check for newly visible elements (tooltips, dropdowns)
+```
+
+#### Example 6: Double-Click
+
+```
+1. Take snapshot
+   - Tool: take_snapshot
+   - Identify: [20] element requiring double-click
+
+2. Double-click element
+   - Tool: click
+   - Parameters: uid: "20", dblClick: true
+```
+
+### Complex Automation Workflows
+
+#### Multi-Step Form with Validation
+
+```
+1. Navigate to form
+2. Take snapshot → identify all fields
+3. Fill first field → wait for validation
+4. Take new snapshot (validation may show/hide elements)
+5. Fill remaining fields
+6. Click submit → handle any confirmation dialog
+7. Wait for success message
+```
+
+#### Dynamic Content Interaction
+
+```
+1. Navigate to page
+2. Take snapshot → identify load-more button
+3. Click load-more → wait for new content text
+4. Take new snapshot (new UIDs for new elements)
+5. Interact with newly loaded elements
+6. Repeat as needed
+```
+
+#### Dropdown Navigation
+
+```
+1. Take snapshot → identify dropdown trigger
+2. Hover over trigger → wait for dropdown appearance
+3. Take new snapshot → identify dropdown options
+4. Click option → wait for navigation
+```
+
+### Automation Workflow Best Practices
+
+1. **Always snapshot before interaction** - Element UIDs change on page updates
+2. **Use fill_form for multiple fields** - More efficient than multiple fill calls
+3. **Wait after actions** - Use wait_for to ensure action completed
+4. **Re-snapshot after dynamic changes** - New elements get new UIDs
+5. **Handle dialogs immediately** - Automation blocks until dialog handled
+6. **Combine with screenshots** - Visual verification of automation steps
+7. **Timeout configuration** - Set appropriate timeout values for wait_for
+
+---
+
+## 5. Multi-Tab Management Workflow
+
+Manage multiple browser tabs/pages with context switching.
+
+### Tools Required
+
+- `list_pages` - List all open pages/tabs
+- `new_page` - Open new page/tab
+- `select_page` - Switch active page context
+- `close_page` - Close page/tab (cannot close last page)
+
+### Step-by-Step Process
+
+#### Basic Tab Management
+
+```
+1. List current pages
+   - Tool: list_pages
+   - Returns: Array of pages with pageIdx identifiers
+
+2. Create new page
+   - Tool: new_page
+   - Parameters: url (optional), timeout (optional)
+   - Returns: New page created and becomes active
+
+3. Switch between pages
+   - Tool: select_page
+   - Parameter: pageIdx (from list_pages)
+
+4. Close page
+   - Tool: close_page
+   - Parameter: pageIdx
+   - Note: Cannot close last remaining page
+```
+
+#### Multi-Tab Workflow Example
+
+```
+1. List existing pages
+   - Tool: list_pages
+   - Example output: [
+       {pageIdx: 0, url: "https://example.com", title: "Example"},
+       {pageIdx: 1, url: "https://test.com", title: "Test"}
+     ]
+
+2. Open new page
+   - Tool: new_page
+   - Parameters: url: "https://newpage.com", timeout: 30000
+   - New page automatically selected
+
+3. Perform actions on new page
+   - Tools: take_snapshot, click, fill, etc.
+   - All tools operate on currently selected page
+
+4. Switch to existing page
+   - Tool: select_page
+   - Parameter: pageIdx: 0
+
+5. Perform actions on original page
+   - Context now on pageIdx: 0
+
+6. Close page when done
+   - Tool: close_page
+   - Parameter: pageIdx: 1
+```
+
+### Tab Switching Strategies
+
+#### Strategy 1: Sequential Processing
+Process multiple pages one at a time:
+```
+1. List all pages
+2. For each page:
+   a. Select page (select_page)
+   b. Take snapshot
+   c. Perform analysis/interaction
+   d. Store results
+3. Close completed pages
+```
+
+#### Strategy 2: Background Tab Loading
+Open multiple tabs, then process:
+```
+1. Open multiple pages in background
+   - new_page (URL 1)
+   - new_page (URL 2)
+   - new_page (URL 3)
+2. List pages to get all pageIdx values
+3. Process each page:
+   - select_page → analyze → next page
+```
+
+#### Strategy 3: Comparison Testing
+Compare same action across multiple pages:
+```
+1. Open pages for comparison
+   - new_page (Version A)
+   - new_page (Version B)
+2. For each page:
+   a. Select page
+   b. Take performance trace
+   c. Store metrics
+3. Compare results across pages
+```
+
+#### Strategy 4: Frame Handling
+Work with pages containing iframes:
+```
+1. Navigate to page with frames
+2. take_snapshot shows frame structure
+3. Interact with main page elements
+4. CDP Target domain handles frame attachment automatically
+```
+
+### Page Selection Best Practices
+
+1. **Always list before selecting** - Page indices may change after close operations
+2. **Track page context** - Remember which pageIdx corresponds to which task
+3. **Cannot close last page** - Keep at least one page open at all times
+4. **New pages auto-select** - After new_page, it becomes active context
+5. **Timeout for slow loads** - Set appropriate timeout for new_page operations
+6. **Session persistence** - Pages persist across navigation within same session
+
+### Multi-Tab Use Cases
+
+#### Use Case 1: Cross-Browser Testing
+```
+1. Open same URL in multiple pages
+2. Each page with different emulation settings
+3. Compare snapshots/screenshots across pages
+```
+
+#### Use Case 2: Multi-Step User Flows
+```
+1. Page 1: Login
+2. Page 2: Dashboard
+3. Page 3: Settings
+4. Switch between pages to verify state persistence
+```
+
+#### Use Case 3: Performance Comparison
+```
+1. Page 1: Production site
+2. Page 2: Staging site
+3. Run identical performance traces on both
+4. Compare Core Web Vitals
+```
+
+#### Use Case 4: Data Extraction
+```
+1. Open multiple product pages
+2. For each page:
+   - Select page
+   - Take snapshot
+   - Extract product data
+   - Store results
+3. Close pages when done
+```
+
+---
+
+## 6. Device Emulation Workflow
+
+Simulate different devices, network conditions, and performance constraints.
+
+### Tools Required
+
+- `emulate_network` - Simulate network conditions
+- `emulate_cpu` - Simulate CPU throttling
+- `resize_page` - Change viewport dimensions
+
+### Step-by-Step Process
+
+#### Basic Device Emulation
+
+```
+1. Set viewport size
+   - Tool: resize_page
+   - Parameters: width (pixels), height (pixels)
+   - Example: width: 375, height: 812 (iPhone X)
+
+2. Configure network emulation
+   - Tool: emulate_network
+   - Parameter: throttlingOption
+   - Options: "No emulation", "Offline", "Slow 3G", "Fast 3G", "Slow 4G", "Fast 4G"
+
+3. Configure CPU throttling
+   - Tool: emulate_cpu
+   - Parameter: throttlingRate (1-20x)
+   - Example: 4 (4x slowdown, simulates low-end device)
+
+4. Navigate to page under test
+   - Tool: navigate_page
+   - Page loads with emulation applied
+
+5. Run performance tests
+   - Tools: performance_start_trace, performance_stop_trace
+   - Metrics reflect emulated conditions
+```
+
+#### Mobile Device Testing
+
+```
+1. Configure mobile viewport
+   - Tool: resize_page
+   - Common sizes:
+     - iPhone 14 Pro: 393 x 852
+     - iPhone SE: 375 x 667
+     - Pixel 7: 412 x 915
+     - Galaxy S22: 360 x 800
+
+2. Set mobile network
+   - Tool: emulate_network
+   - Parameter: throttlingOption: "Fast 4G"
+   - Simulates typical mobile connection
+
+3. Set CPU throttling
+   - Tool: emulate_cpu
+   - Parameter: throttlingRate: 4
+   - Simulates mid-range mobile device
+
+4. Take snapshot/screenshot
+   - Tools: take_snapshot, take_screenshot
+   - Verify mobile layout
+
+5. Test mobile interactions
+   - Tools: click, fill, drag
+   - Interactions work identically on emulated mobile
+```
+
+#### Tablet Device Testing
+
+```
+1. Configure tablet viewport
+   - Tool: resize_page
+   - Common sizes:
+     - iPad Pro 12.9": 1024 x 1366
+     - iPad Air: 820 x 1180
+     - Surface Pro: 912 x 1368
+
+2. Set network conditions
+   - Tool: emulate_network
+   - Parameter: throttlingOption: "Fast 4G" or "No emulation" (WiFi)
+
+3. Test responsive breakpoints
+   - Resize between tablet/desktop sizes
+   - Verify layout changes
+```
+
+### Network Emulation Options
+
+**Available Throttling Profiles:**
+
+1. **No emulation** (default)
+   - Full network speed
+   - No artificial latency
+
+2. **Offline**
+   - Simulates no network connection
+   - Tests offline functionality, service workers
+
+3. **Slow 3G**
+   - Download: ~400 Kbps
+   - Upload: ~400 Kbps
+   - Latency: ~2000ms
+   - Use for: Extreme mobile testing
+
+4. **Fast 3G**
+   - Download: ~1.6 Mbps
+   - Upload: ~750 Kbps
+   - Latency: ~562ms
+   - Use for: Typical 3G mobile
+
+5. **Slow 4G**
+   - Download: ~4 Mbps
+   - Upload: ~3 Mbps
+   - Latency: ~150ms
+   - Use for: Poor LTE conditions
+
+6. **Fast 4G**
+   - Download: ~10 Mbps
+   - Upload: ~5 Mbps
+   - Latency: ~40ms
+   - Use for: Good LTE conditions
+
+### CPU Throttling Configuration
+
+**Throttling Rate Scale:** 1-20x
+
+- **1x** - No throttling (default)
+- **4x** - Mid-range mobile device
+- **6x** - Low-end mobile device
+- **10x+** - Extreme performance constraints
+
+**Use Cases:**
+- Test Time to Interactive (TTI) on slow devices
+- Identify JavaScript performance bottlenecks
+- Measure TBT under constrained conditions
+- Validate progressive enhancement
+
+### Viewport Resize Patterns
+
+#### Common Device Dimensions
+
+**Smartphones (Portrait):**
+- iPhone 14 Pro Max: 430 x 932
+- iPhone 14 Pro: 393 x 852
+- iPhone 14: 390 x 844
+- iPhone SE: 375 x 667
+- Pixel 7 Pro: 412 x 915
+- Pixel 7: 412 x 915
+- Galaxy S22 Ultra: 384 x 854
+- Galaxy S22: 360 x 800
+
+**Tablets:**
+- iPad Pro 12.9": 1024 x 1366
+- iPad Pro 11": 834 x 1194
+- iPad Air: 820 x 1180
+- iPad Mini: 744 x 1133
+- Surface Pro 8: 912 x 1368
+
+**Desktop:**
+- MacBook Air 13": 1280 x 832
+- MacBook Pro 14": 1512 x 982
+- Desktop 1080p: 1920 x 1080
+- Desktop 4K: 3840 x 2160
+
+### Emulation Workflow Examples
+
+#### Example 1: Mobile Performance Audit
+
+```
+1. Resize to mobile
+   - resize_page: width: 375, height: 812
+
+2. Set mobile network
+   - emulate_network: throttlingOption: "Fast 4G"
+
+3. Set CPU throttling
+   - emulate_cpu: throttlingRate: 4
+
+4. Start performance trace
+   - performance_start_trace: reload: true, autoStop: true
+
+5. Analyze results
+   - performance_stop_trace
+   - Check INP, LCP, CLS under mobile conditions
+```
+
+#### Example 2: Offline Mode Testing
+
+```
+1. Set offline mode
+   - emulate_network: throttlingOption: "Offline"
+
+2. Navigate to page
+   - navigate_page
+   - Should trigger offline fallback
+
+3. Verify service worker
+   - take_snapshot
+   - Check offline content displayed
+
+4. Restore network
+   - emulate_network: throttlingOption: "No emulation"
+```
+
+#### Example 3: Responsive Design Testing
+
+```
+1. Test mobile breakpoint
+   - resize_page: width: 375, height: 667
+   - take_screenshot (mobile layout)
+
+2. Test tablet breakpoint
+   - resize_page: width: 768, height: 1024
+   - take_screenshot (tablet layout)
+
+3. Test desktop breakpoint
+   - resize_page: width: 1920, height: 1080
+   - take_screenshot (desktop layout)
+
+4. Compare screenshots for layout consistency
+```
+
+#### Example 4: Network Speed Comparison
+
+```
+1. Baseline (no throttling)
+   - emulate_network: "No emulation"
+   - Run performance trace
+   - Record load time
+
+2. Fast 4G
+   - emulate_network: "Fast 4G"
+   - Run performance trace
+   - Compare load time
+
+3. Slow 3G
+   - emulate_network: "Slow 3G"
+   - Run performance trace
+   - Compare load time
+
+4. Analyze network waterfall for bottlenecks
+```
+
+### Emulation Best Practices
+
+1. **Reset emulation between tests** - Set to "No emulation" and throttlingRate: 1
+2. **Combine emulation types** - Use network + CPU + viewport together
+3. **Match real-world conditions** - Fast 4G + 4x CPU = typical mobile experience
+4. **Test offline gracefully** - Verify service worker, error messages, fallback content
+5. **Validate responsive breakpoints** - Test at exact breakpoint boundaries
+6. **Document test conditions** - Record emulation settings with results
+7. **Compare against field data** - Lab emulation should match real user metrics from CrUX
+
+### Mobile Device Testing Workflow
+
+Complete mobile testing checklist:
+
+```
+1. Set device viewport (resize_page)
+2. Configure network (emulate_network: "Fast 4G")
+3. Configure CPU (emulate_cpu: 4)
+4. Navigate to page
+5. Take accessibility snapshot (take_snapshot)
+6. Run performance trace (performance_start_trace/stop)
+7. Test touch interactions (click, drag)
+8. Verify mobile-specific features (hamburger menu, gestures)
+9. Take screenshots for visual verification
+10. Reset emulation for next test
+```
+
+---
+
+## Workflow Combination Strategies
+
+Many real-world testing scenarios combine multiple workflows:
+
+### Strategy 1: Complete Performance Audit
+
+```
+1. Device Emulation Setup
+   - Mobile viewport, Fast 4G, 4x CPU
+
+2. Performance Analysis
+   - Start trace with reload
+   - Stop trace and analyze Core Web Vitals
+
+3. Network Monitoring
+   - List network requests
+   - Filter for large resources
+   - Check total payload size
+
+4. Accessibility Testing
+   - Take verbose snapshot
+   - Verify mobile accessibility
+```
+
+### Strategy 2: Cross-Device Comparison
+
+```
+1. Multi-Tab Setup
+   - Page 1: Mobile (375x667)
+   - Page 2: Tablet (768x1024)
+   - Page 3: Desktop (1920x1080)
+
+2. For each page:
+   - Select page
+   - Run performance trace
+   - Take screenshot
+   - Export results
+
+3. Compare metrics across devices
+```
+
+### Strategy 3: End-to-End User Flow
+
+```
+1. Browser Automation
+   - Navigate through multi-step flow
+   - Fill forms, click buttons
+
+2. Performance Monitoring
+   - Trace each step
+   - Measure interaction latency
+
+3. Network Analysis
+   - Track requests at each step
+   - Identify slow API calls
+
+4. Accessibility Validation
+   - Snapshot at each step
+   - Verify keyboard navigation
+```
+
+---
+
+## CDP Domain Reference
+
+Each workflow leverages specific Chrome DevTools Protocol domains:
+
+- **Performance Analysis:** Tracing, Performance
+- **Network Monitoring:** Network
+- **Accessibility Testing:** Accessibility (Experimental)
+- **Browser Automation:** Input, Runtime, DOM
+- **Multi-Tab Management:** Target, Page
+- **Device Emulation:** Emulation
+
+For complete CDP documentation, see: https://chromedevtools.github.io/devtools-protocol/
+
+---
+
+**Document Version:** 1.0
+**Last Updated:** October 24, 2025
+**Based on:** chrome-devtools-mcp v0.5.1
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..53528a2
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,65 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:justfinethanku/cc_chrome_devtools_mcp_skill:",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "a6611a82eed4087fbfede45cd9f1198cc3ce6374",
+    "treeHash": "838df95112a99cc3c111a1ef3f260430903306fd86cf8c7468e242b40dc162fa",
+    "generatedAt": "2025-11-28T10:19:22.711546Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "cc_chrome_devtools_mcp_skill",
+    "description": "Automated Chrome browser testing with frontend visibility. Enables Claude Code to see and fix your web applications through Chrome DevTools Protocol - performance testing, Core Web Vitals measurement, accessibility validation, network monitoring, and browser automation.",
+    "version": null
+  },
+  "content": {
+    "files": [
+      {
+        "path": "WORKFLOWS.md",
+        "sha256": "1bd6d4d0de806c3b09960a7eba5e8de3c4a1245e80b86cd1f9b7b7a5eef559d6"
+      },
+      {
+        "path": "LICENSE",
+        "sha256": "a0c0f08e7bf248f1c576946539a2e5d8af868e2f5f229dbc0e6561df9b533733"
+      },
+      {
+        "path": "README.md",
+        "sha256": "9319b0765eb2647983903b486db9ad4b48ba48589d556bc572e5729601b47a24"
+      },
+      {
+        "path": ".gitignore",
+        "sha256": "590286f272e95075df7c4324f96d07516e23de4b89cc78e9b7b7eb3abe1206f4"
+      },
+      {
+        "path": "SKILL.md",
+        "sha256": "da7555a990e9f22de7bb489a5af78df2eecebd442cea4362e3c4382c3ebfaa65"
+      },
+      {
+        "path": "METRICS.md",
+        "sha256": "0efb341d3ea86b60cbaaa18d7ecabc68a5df9496f949660f6364166ccdbcb8ef"
+      },
+      {
+        "path": "TOOLS.md",
+        "sha256": "85783135906691021809a08306c307ad46440d7450125282e739f1df05aa7b29"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "638fb0aaef44581a004d30884164f7ffaf8256a28c9b06964671d34735330260"
+      }
+    ],
+    "dirSha256": "838df95112a99cc3c111a1ef3f260430903306fd86cf8c7468e242b40dc162fa"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file