@youtyan/browser-pilot 0.7.1

package/skills/bp-generate-manual/SKILL.md

@@ -0,0 +1,367 @@
+---
+name: bp-generate-manual
+description: Use when creating site operation manuals with screenshots and videos using browser-pilot MCP tools. Triggers on "マニュアル作成", "操作マニュアル", "手順書", "使い方ガイド", "site manual", "how-to guide".
+---
+
+# Site Manual Generator — ブラウザ操作マニュアル自動生成
+
+2つのワークフローがある。手動で設計してから撮影する **Design-First** と、操作を記録して自動生成する **Record-First**。
+
+## Workflow Selection
+
+```dot
+digraph {
+  rankdir=TB;
+  "目的は?" [shape=diamond];
+  "Design-First (手動設計)" [shape=box];
+  "Record-First (自動生成)" [shape=box];
+
+  "目的は?" -> "Design-First (手動設計)" [label="丁寧なマニュアルが必要\nレイアウト・文言を制御したい"];
+  "目的は?" -> "Record-First (自動生成)" [label="操作手順をすばやく記録したい\nテストスクリプトも欲しい"];
+}
+```
+
+---
+
+# Workflow A: Design-First（手動設計 → 撮影）
+
+サイトを回遊して構造を把握し、撮影仕様を詰めてから操作を録画・撮影し、Markdownマニュアルを生成する。「先に設計、後で撮影」で録画中の無駄な尺を排除する。
+
+## Decision Tree
+
+```dot
+digraph {
+  rankdir=TB;
+  "Phase 1: ヒアリング" [shape=box];
+  "Phase 2: 回遊・調査" [shape=box];
+  "Phase 3: spec.md 作成" [shape=box];
+  "ユーザー承認?" [shape=diamond];
+  "Phase 4: 撮影実行" [shape=box];
+  "最初3ステップで失敗?" [shape=diamond];
+  "Phase 5: manual.md 生成" [shape=box];
+
+  "Phase 1: ヒアリング" -> "Phase 2: 回遊・調査";
+  "Phase 2: 回遊・調査" -> "Phase 3: spec.md 作成";
+  "Phase 3: spec.md 作成" -> "ユーザー承認?";
+  "ユーザー承認?" -> "Phase 3: spec.md 作成" [label="修正"];
+  "ユーザー承認?" -> "Phase 4: 撮影実行" [label="OK"];
+  "Phase 4: 撮影実行" -> "最初3ステップで失敗?";
+  "最初3ステップで失敗?" -> "Phase 3: spec.md 作成" [label="yes: spec見直し"];
+  "最初3ステップで失敗?" -> "Phase 5: manual.md 生成" [label="no: 続行"];
+}
+```
+
+## Phase 1: ヒアリング
+
+ユーザーに以下を確認する。未指定のものはデフォルト値を使う。
+
+| 項目 | 選択肢 | デフォルト |
+|------|--------|-----------|
+| 対象サイトURL | 自由入力 or 既に開いてるタブ | — |
+| マニュアルの目的 | 自由入力（例: 経費申請の手順） | — |
+| 読者レベル | A: 社内メンバー（簡潔） / B: エンドユーザー（丁寧） | B |
+| 出力形式 | A: Markdownのみ / B: 動画のみ / C: 両方 | C |
+
+ヒアリング後、出力ディレクトリを決定:
+
+```
+docs/YYYY-MM-DD-{site}-{topic}/
+  spec.md        撮影仕様（Phase 3）
+  manual.md      最終成果物（Phase 5）
+  images/        stepNN-{name}.png
+  videos/        stepNN-{name}.webm
+```
+
+## Phase 2: 回遊・調査
+
+対象サイトをブラウザツールで実際に操作し、構造を把握する。
+
+```
+browser_tab(action: "list")  or  browser_tab(action: "create", url: "...")
+browser_tab(action: "connect", tabId: ...)
+browser_get_page(mode: "markdown")
+browser_screenshot()
+browser_find_elements(tag: "button", limit: 50)
+```
+
+**目的:**
+- 各画面のDOM構造を把握する
+- 操作対象のセレクタ（CSS selector / text / role）を特定する
+- 画面遷移のフローを確認する
+- 動的要素（ローディング、モーダル等）の有無を把握する
+
+**セレクタ選定の優先順位:**
+1. `data-testid` / `data-*` 属性（最も安定）
+2. `id` 属性
+3. `role` + `name`（アクセシビリティ属性）
+4. CSS セレクタ（クラス名）
+5. テキストマッチ（最終手段、ロケール依存リスク）
+
+## Phase 3: spec.md 作成
+
+回遊結果を元に撮影仕様を作成する。
+
+**確認タイミングの判断:**
+- ステップ数 8以下: spec.md を一括でユーザー確認
+- ステップ数 9以上: セクション単位で段階的に確認
+
+### spec.md フォーマット
+
+```markdown
+# {トピック} — 撮影仕様
+
+## メタ情報
+- サイト: {URL}
+- 読者: {レベル}
+- 出力: {形式}
+- 作成日: {YYYY-MM-DD}
+
+## ステップ一覧
+
+### Step 1: {画面名}
+- 撮影: screenshot -> images/step01-{name}.png
+- 操作: なし（画面説明用）
+- 説明: {このステップでマニュアルに書く内容の概要}
+
+### Step 2: {操作名}
+- 撮影: record start
+- 操作:
+  - browser_set_values(fields: [{selector: "#email", value: "demo@example.com"}])
+  - browser_click(selector: "button[type=submit]")
+  - browser_wait_for(selector: ".dashboard", condition: "appear")
+- 撮影: record stop -> videos/step02-{name}.webm
+- 撮影: screenshot -> images/step02-{name}.png
+- 説明: {このステップでマニュアルに書く内容の概要}
+```
+
+**spec.md の各ステップに必須の項目:**
+- 撮影指示（screenshot / record start / record stop + ファイルパス）
+- 操作内容（使うツールとパラメータ。セレクタは具体値）
+- wait_for 条件（操作後に何を待つか）
+- 説明（manual.md に書く内容の概要）
+
+## Phase 4: 撮影実行
+
+spec.md に従い、順番に操作と撮影を実行する。
+
+**撮影手順:**
+1. screenshot の場合: `browser_screenshot()` → 画像を確認 → `images/` に保存指示
+2. record の場合: `browser_record(action: "start", savePath: "/path/to/videos/stepNN-name.webm")` → 操作実行 → `browser_record(action: "stop")`
+3. 各操作後に `browser_wait_for` で画面遷移を確認してから次へ
+
+**browser_record パラメータ:**
+
+| パラメータ | 型 | デフォルト | 説明 |
+|-----------|-----|-----------|------|
+| action | "start" / "stop" / "status" / "abort" | — | 必須。start で録画開始、stop で保存、abort で破棄 |
+| savePath | string | — | 出力ファイルのフルパス（例: ~/docs/videos/login.webm）。filename と排他 |
+| filename | string | recording-{timestamp}.webm | ファイル名のみ（パス区切り不可）。savePath と排他。一時ディレクトリに保存 |
+| fps | number (1-30) | 15 | フレームレート |
+| quality | number (1-100) | 80 | JPEG品質（フレームキャプチャ用） |
+| includeAudio | boolean | false | タブ音声を含める（CDP screencast では無視） |
+
+**エラーハンドリング:**
+- 最初の3ステップ以内で失敗: spec.md の見直しが必要。Phase 3 に戻りセレクタ・手順を修正
+- 途中の1ステップが失敗: スキップして続行。失敗ステップを記録
+- 最後にまとめて失敗一覧を報告
+
+**撮影中の注意:**
+- `browser_record` の前にタブがアクティブであることを確認（CDP screencast はコンポジタ活動が必要）
+- 動画録画中は操作を淀みなく実行する（spec で事前に詰めた通りに）
+- 静的ページではフレームが生成されないため、スクショのみにする
+- `savePath` を使えば直接出力ディレクトリに保存できる。`filename` はテンポラリ保存用
+
+## Phase 5: manual.md 生成
+
+spec.md と撮影済み素材から最終マニュアルを組み立てる。
+
+### manual.md フォーマット
+
+```markdown
+# {トピック} マニュアル
+
+## Step 1: ログイン画面
+
+ブラウザで {URL} にアクセスすると、ログイン画面が表示されます。
+
+![ログイン画面](./images/step01-login.png)
+
+## Step 2: ログイン
+
+メールアドレスとパスワードを入力し、「ログイン」ボタンをクリックします。
+
+操作動画: [ログイン操作](./videos/step02-login.webm)
+
+![ログイン後のダッシュボード](./images/step02-dashboard.png)
+
+ログインに成功するとダッシュボード画面が表示されます。
+```
+
+**読者レベルによる文体:**
+- 社内メンバー: 「○○画面で△△を入力して送信」程度の簡潔な記述
+- エンドユーザー: スクショの吹き出し的な説明。「画面左上の青い『申請』ボタンをクリックしてください」レベルの丁寧さ
+
+**失敗ステップの扱い:**
+撮影に失敗したステップは manual.md に「※ このステップは手動で操作してください」と注記する。
+
+---
+
+# Workflow B: Record-First（操作記録 → 自動生成）
+
+操作をそのまま実行し、アクションログから自動でマニュアルとテストスクリプトを生成する。Work IR（中間表現）を経由してマルチ出力を得る。
+
+## パイプライン概要
+
+```
+操作実行（browser_click, browser_set_values, ...）
+  ↓ 自動でアクションログに記録
+  ↓ begin_step / end_step でステップをグルーピング
+  ↓
+browser_tab(action: "generate_manual")  → Markdown マニュアル
+browser_tab(action: "generate_test")    → bun:test E2E テストスクリプト
+browser_tab(action: "export_bundle")    → JSON バンドル（IR + manual + test + source map）
+browser_tab(action: "save_bundle", savePath: "...")  → バンドルをファイルに保存
+```
+
+## Step 1: アクションログの管理
+
+全ての `browser_*` ツール呼び出しは自動的にアクションログに記録される。明示的な設定は不要。
+
+**ログの確認と管理:**
+
+```
+browser_tab(action: "log")                  → テキスト形式でログ表示
+browser_tab(action: "log", format: "json")  → JSON形式でログ取得（machine-readable）
+browser_tab(action: "clear_log")            → ログをリセット（新しいマニュアル生成の前に）
+```
+
+ログエントリの各項目: timestamp, tool, tabId, ok (成否), target (パラメータ), summary, artifacts (スクショ・動画パス)。
+
+## Step 2: ステップのグルーピング
+
+`begin_step` / `end_step` で操作を意味のあるステップにグルーピングする。グルーピングすると、generate_manual の出力で複数の操作が1つの番号付きステップにまとまる。
+
+```
+browser_tab(action: "begin_step", label: "ログイン")
+  browser_set_values(fields: [{selector: "#email", value: "user@example.com"}])
+  browser_click(selector: "button[type=submit]")
+  browser_screenshot()
+browser_tab(action: "end_step")
+
+browser_tab(action: "begin_step", label: "ダッシュボード確認")
+  browser_get_page(mode: "markdown")
+  browser_screenshot()
+browser_tab(action: "end_step")
+```
+
+**ルール:**
+- `begin_step` は `label` 必須。ステップ名になる
+- ネスト不可。`begin_step` → `end_step` を閉じてから次の `begin_step`
+- `end_step` せずに `begin_step` するとエラー
+- グルーピングなしでも generate_manual は動く（各ツール呼び出しが個別ステップになる）
+
+## Step 3: マニュアル自動生成
+
+**generate_manual** — アクションログを番号付きMarkdownマニュアルに変換:
+
+```
+browser_tab(action: "generate_manual")
+```
+
+- 成功した操作のみ出力（失敗はスキップ）
+- `begin_step` / `end_step` で囲んだ操作は1つのステップにマージ
+- スクリーンショットは `![Step N](path)` として埋め込み
+- 動画は `[Video](path)` としてリンク
+- アーティファクトが見つからない場合は `<!-- WARNING: file not found -->` コメント付き
+- コンパイル診断（warnings/errors数）が末尾に付与
+
+## Step 4: テストスクリプト自動生成
+
+**generate_test** — アクションログを bun:test E2E テストスクリプトに変換:
+
+```
+browser_tab(action: "generate_test")
+```
+
+- Browser Pilot HTTP API (`/api/tool`) を叩く `callTool` ヘルパーを自動生成
+- `browser_set_values` の値は機密としてリダクト（TODO プレースホルダー + fieldHints からの環境変数名）
+- `browser_batch` は TODO コメントとして展開（サブアクション個別に）
+- 失敗した操作はコメントアウト
+- 安定ロケーターがないステップ（ephemeral ref/backendNodeId のみ）は TODO として出力
+- 末尾に replayability サマリー: runnable / needs_todo / needs_manual_fix
+
+## Step 5: バンドルのエクスポート
+
+**export_bundle** — Work IR 全体を JSON で取得:
+
+```
+browser_tab(action: "export_bundle")
+```
+
+バンドル内容:
+- `version`: "1.0"
+- `compiledAt`: ISO timestamp
+- `steps`: WorkStep[] — コンパイル済みステップ（intent, locator, assertions, artifacts 等）
+- `diagnostics`: CompileDiagnostic[] — エラー/警告/info
+- `summary`: { total, runnable, needsTodo, needsManualFix, warnings, errors }
+- `manual`: 生成されたMarkdown（または null）
+- `test`: 生成されたテストスクリプト（または null）
+- `sourceMap`: SourceMapEntry[] — ステップとmanual/testの行番号のマッピング
+
+**save_bundle** — バンドルをファイルに保存:
+
+```
+browser_tab(action: "save_bundle", savePath: "/path/to/bundle.json")
+```
+
+## Record-First の典型的なフロー
+
+```
+# 1. ログをクリア（前回の記録が残っている場合）
+browser_tab(action: "clear_log")
+
+# 2. 対象ページに接続
+browser_tab(action: "connect", tabId: ...)
+
+# 3. ステップを記録しながら操作
+browser_tab(action: "begin_step", label: "ログインページを開く")
+browser_navigation(url: "https://example.com/login")
+browser_screenshot()
+browser_tab(action: "end_step")
+
+browser_tab(action: "begin_step", label: "認証情報を入力してログイン")
+browser_set_values(fields: [{selector: "#email", value: "..."}])
+browser_click(selector: "button[type=submit]")
+browser_wait_for(selector: ".dashboard", condition: "appear")
+browser_screenshot()
+browser_tab(action: "end_step")
+
+# 4. ログを確認
+browser_tab(action: "log")
+
+# 5. マニュアルを生成
+browser_tab(action: "generate_manual")
+
+# 6. テストスクリプトを生成（オプション）
+browser_tab(action: "generate_test")
+
+# 7. バンドルを保存（オプション）
+browser_tab(action: "save_bundle", savePath: "/path/to/output/bundle.json")
+```
+
+---
+
+# Common Mistakes
+
+| 間違い | 正しい対応 |
+|--------|-----------|
+| 回遊せずにいきなり撮影（Design-First） | Phase 2 で必ずセレクタを特定してから spec を書く |
+| spec.md にセレクタを書かない | 具体的な CSS selector / text / role を必ず記載 |
+| 録画中に要素を探し始める | spec で詰めた通りに淀みなく操作する |
+| wait_for を省略 | SPA は画面遷移に時間がかかる。必ず待機条件を入れる |
+| 静的ページを動画で撮る | 動きがないページは screenshot のみにする |
+| 全ステップを動画にする | 動きのある操作だけ動画。画面説明はスクショで十分 |
+| begin_step を閉じずに次の begin_step | 必ず end_step してからネストなしで次の begin_step |
+| clear_log せずに新しいマニュアルを生成 | 前回の操作が混入する。clear_log でリセットしてから記録開始 |
+| generate_manual の出力をそのまま最終成果物にする | 自動生成は骨格。文言・レイアウトはユーザーが調整する |
+| savePath と filename を同時指定 | 排他パラメータ。どちらか一方のみ |

package/skills/bp-test-scripts/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: bp-test-scripts
+description: Use when writing executable test scripts that control a real Chrome browser via browser-pilot HTTP API. Triggers on "テストスクリプト", "E2Eスクリプト", "自動テスト", "test script", "automated test", "browser test code", "コード駆動テスト".
+---
+
+# Browser Testing Scripts — コード駆動ブラウザテスト
+
+browser-pilot MCP ServerのHTTP APIを使い、Bun/TypeScriptでテストスクリプトを書く。
+リアルChromeが目の前で動く。MCP Server（Claude Code接続）と同時利用可能。
+
+## Two API Layers
+
+| エンドポイント | 用途 | レスポンス |
+|---------------|------|-----------|
+| `POST /api/tool` | **推奨。** MCP toolと同じ処理を経由 | markdown変換済み、fuzzy検索済み |
+| `POST /api/request` | Extension直通（raw） | 生HTML、生DOM情報 |
+
+### `/api/tool` (推奨)
+
+MCP toolハンドラを直接呼ぶ。`browser_get_page` のmarkdown変換、`browser_find_elements` のfuzzy検索等、全ての内部処理が適用される。
+
+```
+テストスクリプト (Bun)
+    ↓ HTTP POST /api/tool
+MCP Tool Handler (markdown変換, fuzzy検索, etc.)
+    ↓ bridge.request()
+Chrome Extension (WebSocket client)
+    ↓
+Real Chrome Browser (visible)
+```
+
+### `/api/request` (raw)
+
+Extension直通。MCP toolの変換処理をスキップ。生HTMLが必要な場合に使う。
+
+## Authentication
+
+全 `/api/*` エンドポイントは Bearer トークン認証が必須。トークンは `~/.browser-pilot-token` に保存されている。
+
+```typescript
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const API_TOKEN = (await readFile(join(homedir(), ".browser-pilot-token"), "utf-8")).trim();
+```
+
+全リクエストに `Authorization: Bearer ${API_TOKEN}` ヘッダーを付与すること。
+
+## Quick Start (推奨: /api/tool)
+
+```typescript
+const TOOL_API = "http://127.0.0.1:18888/api/tool";
+
+async function tool(name: string, args: Record<string, unknown> = {}) {
+  const res = await fetch(TOOL_API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_TOKEN}`,
+    },
+    body: JSON.stringify({ tool: name, args }),
+  });
+  const body = await res.json();
+  if (body.isError) throw new Error(body.content?.[0]?.text ?? "Unknown error");
+  return body;
+}
+
+// タブ一覧取得
+const tabs = await tool("browser_tab", { action: "list" });
+console.log(tabs.content[0].text);
+
+// タブ作成（自動connect）
+await tool("browser_tab", { action: "create", url: "https://example.com" });
+
+// ページ取得 → markdownで返る（htmlToText不要）
+const page = await tool("browser_get_page", { mode: "markdown" });
+console.log(page.content[0].text);
+
+// 要素検索 → fuzzy検索対応
+const els = await tool("browser_find_elements", { text: "送信", tag: "button" });
+console.log(els.content[0].text);
+```
+
+## Quick Start (Raw: /api/request)
+
+```typescript
+const RAW_API = "http://127.0.0.1:18888/api/request";
+
+async function bp(action: string, params: Record<string, unknown> = {}) {
+  const res = await fetch(RAW_API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_TOKEN}`,
+    },
+    body: JSON.stringify({ action, params }),
+  });
+  const body = await res.json();
+  if (body.status === "error") throw new Error(body.error ?? body.message);
+  return body;
+}
+
+// get_page は生HTMLを返す → テキスト抽出ヘルパーが必要
+function htmlToText(html: string): string {
+  return html
+    .replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+const tabs = await bp("list_tabs");
+const tab = tabs.data[0];
+const page = await bp("get_page", { tabId: tab.id });
+console.log(htmlToText(page.data.html));
+```
+
+## Response Format Comparison
+
+| 操作 | `/api/tool` response | `/api/request` response |
+|------|---------------------|------------------------|
+| get_page | `{ content: [{ type: "text", text: "# markdown..." }] }` | `{ data: { html: "<div>..." } }` |
+| find_elements | `{ content: [{ type: "text", text: "Found 3..." }] }` | `{ data: { count: 3, elements: [...] } }` |
+| click | `{ content: [{ type: "text", text: "Clicked..." }] }` | `{ data: { clicked: true } }` |
+| screenshot | `{ content: [{ type: "image", data: "base64...", mimeType: "image/webp" }] }` | `{ screenshot: "base64..." }` |
+
+## Test Pattern with bun:test (推奨: /api/tool)
+
+```typescript
+import { describe, it, expect, beforeAll } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const API = "http://127.0.0.1:18888/api/tool";
+const API_TOKEN = (await readFile(join(homedir(), ".browser-pilot-token"), "utf-8")).trim();
+
+async function tool(name: string, args: Record<string, unknown> = {}) {
+  const res = await fetch(API, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_TOKEN}`,
+    },
+    body: JSON.stringify({ tool: name, args }),
+  });
+  const body = await res.json();
+  if (body.isError) throw new Error(body.content?.[0]?.text ?? "Unknown error");
+  return body;
+}
+
+function getText(result: { content: Array<{ type: string; text?: string }> }): string {
+  return result.content
+    .filter((c) => c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+}
+
+describe("My App", () => {
+  beforeAll(async () => {
+    await tool("browser_tab", { action: "create", url: "http://localhost:3000" });
+    await tool("browser_wait_for", { selector: "main", condition: "appear", timeout: 10000 });
+  });
+
+  it("shows page title", async () => {
+    const page = await tool("browser_get_page", { mode: "markdown" });
+    expect(getText(page)).toContain("My App");
+  });
+
+  it("has submit button", async () => {
+    const els = await tool("browser_find_elements", { tag: "button", text: "Submit" });
+    expect(getText(els)).not.toContain("No elements found");
+  });
+
+  it("click navigates", async () => {
+    await tool("browser_click", { text: "Next" });
+    await tool("browser_wait_for", { selector: ".step-2", condition: "appear" });
+    const page = await tool("browser_get_page", { mode: "markdown" });
+    expect(getText(page)).toContain("Step 2");
+  });
+});
+```
+
+Run: `mise x -- bun test tests/e2e/my-test.test.ts`
+
+## Tool Name Mapping (/api/tool vs /api/request)
+
+### Tab Management (unified `browser_tab` tool)
+
+`browser_tab` は action パラメータで操作を切り替える統合ツール。`/api/request` では個別アクション名を使う。
+
+| `/api/tool` の呼び方 | `/api/request` の action名 |
+|---------------------|---------------------------|
+| `browser_tab` (action: "list") | `list_tabs` |
+| `browser_tab` (action: "connect", tabId) | N/A (MCP tool専用) |
+| `browser_tab` (action: "create", url) | `create_tab` |
+| `browser_tab` (action: "close", tabId) | `close_tab` |
+| `browser_tab` (action: "lock") | N/A (MCP tool専用) |
+| `browser_tab` (action: "unlock") | N/A (MCP tool専用) |
+| `browser_tab` (action: "log") | N/A (MCP tool専用) |
+| `browser_tab` (action: "clear_log") | N/A (MCP tool専用) |
+| `browser_tab` (action: "begin_step", label) | N/A (MCP tool専用) |
+| `browser_tab` (action: "end_step") | N/A (MCP tool専用) |
+| `browser_tab` (action: "generate_manual") | N/A (MCP tool専用) |
+| `browser_tab` (action: "generate_test") | N/A (MCP tool専用) |
+| `browser_tab` (action: "export_bundle") | N/A (MCP tool専用) |
+| `browser_tab` (action: "save_bundle", savePath) | N/A (MCP tool専用) |
+
+### Page & Navigation
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_get_page` | `get_page` |
+| `browser_navigation` (action: "goto", url) | `get_page` (with url param) |
+| `browser_navigation` (action: "back") | `go_back` |
+| `browser_navigation` (action: "forward") | `go_forward` |
+| `browser_navigation` (action: "reload") | `reload` |
+| `browser_scroll` | `scroll` |
+| `browser_wait_for` | `wait_for` |
+
+### Element Interaction
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_click` | `click_element` |
+| `browser_set_values` | `set_value` |
+| `browser_select_option` | `click_element` (sequence) |
+| `browser_action` | `action_element` |
+| `browser_keyboard` | `press_key` |
+| `browser_find_elements` | `find_elements` |
+| `browser_get_attributes` | `get_attributes` |
+| `browser_get_bounds` | `get_bounds` |
+| `browser_diagnose_interaction` | `diagnose_interaction` |
+| `browser_paste_file` | `paste_file` |
+| `browser_upload_file` | `upload_file` |
+| `browser_handle_dialog` | N/A (background直通) |
+
+### Data Extraction & Inspection
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_extract` | `extract_data` |
+| `browser_css_inspect` | `css_inspect` |
+| `browser_execute_javascript` | `evaluate` |
+| `browser_assert` | N/A (MCP tool専用) |
+
+### Capture & Media
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_screenshot` | `screenshot` |
+| `browser_pdf` | `print_to_pdf` |
+| `browser_annotate` | `annotate` / `clear_annotations` |
+| `browser_record` | `start_recording` / `stop_recording` / `recording_status` |
+
+### Diagnostics & DevTools
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_console` | `get_console_messages` |
+| `browser_network` | `get_network_requests` |
+| `browser_performance` | `get_performance_metrics` |
+| `browser_storage` | `get_storage` |
+| `browser_cookie` | `set_cookie` / `delete_cookie` / (get via `get_storage` type:cookies) |
+| `browser_health` | N/A (MCP tool専用) |
+
+### Batch Execution
+
+| `/api/tool` の tool名 | `/api/request` の action名 |
+|----------------------|---------------------------|
+| `browser_batch` | N/A (MCP tool専用 — 複数ツール呼び出しを1リクエストで実行) |
+
+## Prerequisites
+
+- MCP Server が起動中（Claude Code接続 or `mise x -- bun run apps/mcp/src/index.ts`）
+- Chrome Extension がインストール済み & 接続済み
+- テスト対象のWebアプリが起動済み
+
+## Common Mistakes
+
+| 間違い | 正しい対応 |
+|--------|-----------|
+| `browser_create_tab` を使う | `browser_tab` (action: "create", url: "...") を使う |
+| `browser_list_tabs` を使う | `browser_tab` (action: "list") を使う |
+| `browser_connect_tab` を使う | `browser_tab` (action: "connect", tabId: N) を使う |
+| `browser_set_value` (単数形) を使う | `browser_set_values` (複数形) を使う |
+| `/api/tool` で action名を使う | MCP tool名を使う（`browser_get_page` 等） |
+| `/api/request` でtool名を使う | content.tsのメソッド名を使う（`get_page` 等） |
+| `/api/request` の `page.data` を文字列扱い | `page.data.html` が生HTML。`/api/tool` なら変換済み |
+| `/api/request` で tabId を渡さない | `create_tab` の戻り値から取得して毎回渡す |
+| `/api/tool` で tabId を渡す | 不要。TabSessionが自動注入（`browser_tab` action:"connect" で設定済みなら） |
+| MCP Server 未起動で実行 | Claude Code接続中 or 手動起動が必要 |
+| wait なしで次の操作 | `browser_wait_for` で遷移完了を待つ |
+| `Authorization` ヘッダー未付与で `401 Unauthorized` | `~/.browser-pilot-token` を読んで `Bearer` トークンを全リクエストに付与 |