diff --git a/.claude/skills/canicode/SKILL.md b/.claude/skills/canicode/SKILL.md
index 4c833734..9f9b5482 100644
--- a/.claude/skills/canicode/SKILL.md
+++ b/.claude/skills/canicode/SKILL.md
@@ -30,6 +30,22 @@ Note: The first time you connect, Figma OAuth will prompt you to authorize in th
 
 Do NOT proceed with analysis if Figma MCP is not available. Do NOT fall back to CLI `--mcp` mode.
 
+## CLI vs this skill (Figma MCP)
+
+This skill is the **MCP path** only. For some goals, `canicode analyze` with **FIGMA_TOKEN** (CLI) is a better fit:
+
+| Feature | CLI (REST API) | This skill (Figma MCP) |
+|---------|:-:|:-:|
+| Node structure | ✅ Full tree | ✅ XML metadata |
+| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind from design context |
+| Component metadata (name, desc) | ✅ | ❌ |
+| Component master trees | ✅ `componentDefinitions` | ❌ |
+| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` in code |
+| Screenshots | ✅ via API | ✅ `get_screenshot` |
+| FIGMA_TOKEN | Required for live API | Not required when Figma MCP is connected |
+
+Use **CLI + token** when the user needs accurate component analysis. Use **this skill** for fast checks and workflows that rely on dev annotations.
+
 ## How to Analyze a Figma URL
 
 When the user provides a Figma URL, follow these steps:
diff --git a/CLAUDE.md b/CLAUDE.md
index 95c17d8b..89d10d2b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,6 +52,8 @@ app/                          # Browser runtime
 - Output: HTML report (opens in browser)
 - Options: `--preset`, `--token`, `--output`, `--custom-rules`, `--config`
 - Also: `canicode save-fixture` to save Figma data as JSON for offline analysis
+- Component master resolution: fetches `componentDefinitions` for accurate component analysis
+- Annotations: NOT available (REST API annotations field is private beta)
 
 **2. MCP Server (`canicode-mcp`)**
 - Install: `claude mcp add canicode -- npx -y -p canicode canicode-mcp`
@@ -62,6 +64,23 @@ app/                          # Browser runtime
   - No FIGMA_TOKEN needed when using Figma MCP
 - Also works standalone with FIGMA_TOKEN (REST API fallback via `input` param)
 
+**CLI vs MCP Feature Comparison**
+
+| Feature | CLI (REST API) | MCP (Figma MCP) |
+|---------|:-:|:-:|
+| Node structure | ✅ Full tree | ✅ XML metadata |
+| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind code |
+| Component metadata (name, desc) | ✅ | ❌ |
+| Component master trees | ✅ `componentDefinitions` | ❌ |
+| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` |
+| Screenshots | ✅ via API | ✅ `get_screenshot` |
+| FIGMA_TOKEN required | ✅ | ❌ |
+
+**When to use which:**
+- Accurate component analysis (style overrides, missing-component) → **CLI with FIGMA_TOKEN**
+- Quick structure/style check, annotation-aware workflows → **MCP**
+- Offline/CI analysis → **CLI with saved fixtures**
+
 **3. Claude Code Skill (`/canicode`)**
 - Location: `.claude/skills/canicode/SKILL.md` (copy to any project)
 - Requires: Official Figma MCP (`https://mcp.figma.com/mcp`) at project level
diff --git a/README.md b/README.md
index 5dc314b0..1659c7b6 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,28 @@ The rules themselves run deterministically on every analysis — no tokens consu
 | Add to CI/CD | **[GitHub Action](https://github.com/marketplace/actions/canicode-action)** |
 | Full control | **CLI** |
 
+<details>
+<summary><strong>CLI vs MCP</strong> (feature comparison)</summary>
+
+Same detail as in [`CLAUDE.md`](CLAUDE.md); summarized here for quick reference.
+
+| Feature | CLI (REST API) | MCP (Figma MCP) |
+|---------|:-:|:-:|
+| Node structure | ✅ Full tree | ✅ XML metadata |
+| Style values | ✅ Raw Figma JSON | ✅ React+Tailwind code |
+| Component metadata (name, desc) | ✅ | ❌ |
+| Component master trees | ✅ `componentDefinitions` | ❌ |
+| Annotations (dev mode) | ❌ private beta | ✅ `data-annotations` |
+| Screenshots | ✅ via API | ✅ `get_screenshot` |
+| FIGMA_TOKEN required | ✅ | ❌ |
+
+**When to use which:**
+- Accurate component analysis (style overrides, missing-component rules) → **CLI with FIGMA_TOKEN**
+- Quick structure/style checks or annotation-aware flows → **MCP**
+- Offline/CI → **CLI with saved fixtures** (`save-fixture`)
+
+</details>
+
 <details>
 <summary><strong>CLI</strong></summary>
 
diff --git a/src/mcp/server.ts b/src/mcp/server.ts
index 5e2f103f..e3e48168 100644
--- a/src/mcp/server.ts
+++ b/src/mcp/server.ts
@@ -281,7 +281,18 @@ claude mcp add -s project -t http figma https://mcp.figma.com/mcp
 With Figma API token (no Figma MCP needed):
 \`\`\`bash
 claude mcp add canicode -e FIGMA_TOKEN=figd_xxxxxxxxxxxxx -- npx -y -p canicode canicode-mcp
-\`\`\``,
+\`\`\`
+
+## CLI vs MCP
+
+| Feature | CLI (FIGMA_TOKEN) | MCP (Figma MCP) |
+|---------|:-:|:-:|
+| Component master trees | ✅ | ❌ |
+| Component metadata | ✅ | ❌ |
+| Annotations (dev mode) | ❌ private beta | ✅ data-annotations |
+| FIGMA_TOKEN required | ✅ | ❌ |
+
+Use CLI for accurate component analysis. Use MCP for quick checks and annotation-aware workflows.`,
 
       "visual-compare": `# Visual Compare