chore: add Why Aluvia and CDP Connection sections and update installation instruction

aluvia-cursor/SKILL.md

@@ -15,6 +15,16 @@ Aluvia routes traffic through **real US mobile carrier IPs** — the same IPs us
 
 The CLI manages headless Chromium sessions with automatic block detection and bypass. Every command returns structured JSON to stdout.
 
+## Why Aluvia
+
+Aluvia provides browser session infrastructure for AI agents.
+
+Some tools such as Browserbase, Steel, Hyperbrowser, and Browserless provide hosted cloud browsers. Aluvia instead runs locally and exposes a direct Chrome DevTools Protocol (CDP) endpoint for the active session.
+
+Some platforms such as Apify or fully managed browser agents abstract the browser behind higher-level APIs. Aluvia does not abstract browser control. The agent connects directly to the CDP endpoint and retains full control using any compatible client such as Playwright, Puppeteer, OpenClaw, agent-browser, or other CDP tools.
+
+Aluvia focuses on network-layer block mitigation using US mobile carrier IP routing, automatic block detection, IP rotation, and dynamic proxy rules, while keeping the existing browser automation stack unchanged.
+
 ## Prerequisites Check
 
 Before using any command, verify the environment:
@@ -30,7 +40,7 @@ aluvia help --json
 node -e "require('playwright')"
 ```
 
-If the API key is missing, tell the user to set `ALUVIA_API_KEY` from the [Aluvia dashboard](https://dashboard.aluvia.io). If `aluvia` is not found, run `npm install @aluvia/sdk`. If Playwright is missing, run `npm install playwright`.
+If the API key is missing, tell the user to set `ALUVIA_API_KEY` from the [Aluvia dashboard](https://dashboard.aluvia.io). If `aluvia` is not found, run `npm install @aluvia/mcp`. If Playwright is missing, run `npm install playwright`.
 
 ## Core Commands Quick Reference
 
@@ -57,9 +67,44 @@ Always use `--browser-session` to name your session. Always use `--auto-unblock`
 aluvia session start https://example.com --auto-unblock --browser-session my-task
 ```
 
-The start command returns JSON with `browserSession`, `pid`, `cdpUrl`, `connectionId`, `blockDetection`, and `autoUnblock` fields. Save `browserSession` for subsequent commands.
+The start command returns:
 
-### 2. Monitor for blocks
+```json
+{
+  "browserSession": "my-task",
+  "pid": 12345,
+  "startUrl": "https://example.com",
+  "cdpUrl": "http://127.0.0.1:38209",
+  "connectionId": 3449,
+  "blockDetection": true,
+  "autoUnblock": true
+}
+```
+
+Save `browserSession` — you need it for every subsequent command.
+
+### 2. CDP Connection
+
+`aluvia session start` returns JSON containing a `cdpUrl`.
+This is the Chrome DevTools Protocol (CDP) endpoint for the active browser session.
+
+`cdpUrl` is **NOT a website URL**.
+Do not navigate to it.
+
+- Check available tools for a CDP-compatible client (a Playwright or Puppeteer client that supports attaching to an existing CDP endpoint).
+- If available, attach the tool to the browser using `cdpUrl`. Only use tools that support CDP attach; skip tools that launch a new browser.
+- Reuse the existing browser context and page.
+- If no CDP-compatible tool is available, connect programmatically using Playwright:
+
+```ts
+import { chromium } from "playwright";
+
+const browser = await chromium.connectOverCDP(cdpUrl);
+const context = browser.contexts()[0];
+const page = context.pages()[0];
+```
+
+### 3. Monitor for blocks
 
 ```bash
 aluvia session get --browser-session my-task
@@ -67,7 +112,7 @@ aluvia session get --browser-session my-task
 
 Check the `lastDetection` object. Block scores: `blocked` >= 0.7, `suspected` >= 0.4, `clear` < 0.4. With `--auto-unblock`, blocks are remediated automatically.
 
-### 3. Rotate IP if blocked
+### 4. Rotate IP if blocked
 
 ```bash
 aluvia session rotate-ip --browser-session my-task
@@ -75,13 +120,13 @@ aluvia session rotate-ip --browser-session my-task
 
 Returns a new `sessionId` (UUID). The next request uses a fresh IP.
 
-### 4. Set geo-targeting if needed
+### 5. Set geo-targeting if needed
 
 ```bash
 aluvia session set-geo us_ca --browser-session my-task
 ```
 
-### 5. Expand routing rules
+### 6. Expand routing rules
 
 If navigating to new domains that need proxying:
 
@@ -91,7 +136,7 @@ aluvia session set-rules "newsite.com,api.newsite.com" --browser-session my-task
 
 Rules are appended to existing rules (not replaced).
 
-### 6. Close the session when done
+### 7. Close the session when done
 
 **Always close your session.** Sessions consume resources until explicitly closed.