diff --git a/README.de.md b/README.de.md
index 5849f526..8352055f 100644
--- a/README.de.md
+++ b/README.de.md
@@ -42,6 +42,67 @@ Reproduktionsbefehle, Datensatz-SHA256, rohe Ergebnisse pro Frage und Analyse be
---
+## Installationspfade auf einen Blick
+
+MeMesh hat **zwei Installationspfade, die nebeneinander existieren**. Die meisten Nutzer brauchen beide. Beide schreiben in die **selbe Speicher-Datenbank** (`~/.memesh/knowledge-graph.db`), so dass im Claude-Code-Chat erfasste Memories auch in deiner Shell erscheinen und umgekehrt.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**Welchen brauchst du?**
+
+| Was du willst | Installationspfad |
+|---|---|
+| `/memesh` skill im Claude-Code-Chat verwenden | Path A (Plugin) |
+| Auto-Capture in Claude Code (Session → Lessons → nächste Recall) | Path A (Plugin) |
+| `memesh remember` / `memesh recall` / `memesh doctor` im Terminal | Path B (npm-global) |
+| `memesh` direkt zum Öffnen des Dashboards (ohne `npx`-Startverzögerung) | Path B (npm-global) |
+| `memesh-mcp` an Cursor, Cline oder andere MCP-Clients anbinden | Path B (npm-global) |
+| Alles oben | **Beide installieren** — kein Konflikt |
+
+> **Häufiges Missverständnis**: Das Claude-Code-Plugin legt `memesh` **nicht** auf deinen Shell-`PATH`. Wenn du nur `/plugin install` läufst und dann im Terminal `memesh reindex` tippst, siehst du `command not found`. Das ist normal — für den Shell-Befehl brauchst du zusätzlich `npm install -g @pcircle/memesh`.
+
+### ⚠️ Das Plugin installiert NICHT das CLI
+
+Das ist die häufigste Verwechslung. Einmal lesen, spart dir später Zeit:
+
+- `/plugin install memesh@pcircle-memesh` aus Claude Code → installiert **nur Path A**. Du erhältst MCP-Tools, Hooks, das `/memesh` skill. `memesh` landet **nicht** auf deinem Shell-`PATH`.
+- `memesh reindex` / `memesh update` / `memesh doctor` im Terminal → braucht **Path B** (npm-global). Sonst: `zsh: command not found: memesh`.
+- **Empfohlenes Setup für Claude-Code-Nutzer**: **beide installieren**. Koexistieren, teilen sich dieselbe DB, kein Konflikt.
+
+```bash
+# Nach /plugin install ..., auch das ausführen:
+npm install -g @pcircle/memesh
+```
+
+Wenn du memesh nur im Claude-Code-Chat verwendest (nie `memesh` im Terminal tippst), reicht Path A. Alle anderen: beide installieren.
+
+---
+
## In 60 Sekunden starten
### Schritt 1: Installation
diff --git a/README.es.md b/README.es.md
index a15f2f61..c02e27aa 100644
--- a/README.es.md
+++ b/README.es.md
@@ -42,6 +42,67 @@ Los comandos de reproducción, SHA256 del dataset, resultados crudos por pregunt
---
+## Vista rápida de las rutas de instalación
+
+MeMesh tiene **dos rutas de instalación que coexisten**. La mayoría de usuarios quiere ambas. Escriben en la **misma base de datos de memoria** (`~/.memesh/knowledge-graph.db`), por lo que los recuerdos capturados en el chat de Claude Code aparecen en tu shell, y viceversa.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**¿Cuál necesitas?**
+
+| Lo que quieres hacer | Ruta de instalación |
+|---|---|
+| Usar el skill `/memesh` dentro de una conversación de Claude Code | Path A (plugin) |
+| Auto-captura en Claude Code (sesión → lecciones → recall siguiente) | Path A (plugin) |
+| Ejecutar `memesh remember` / `memesh recall` / `memesh doctor` en cualquier terminal | Path B (npm-global) |
+| Abrir el dashboard con `memesh` (sin retraso de arranque de `npx`) | Path B (npm-global) |
+| Conectar `memesh-mcp` a Cursor, Cline u otro cliente MCP | Path B (npm-global) |
+| Todo lo anterior | **Instala ambos** — no entran en conflicto |
+
+> **Confusión común**: el plugin de Claude Code **no** pone `memesh` en tu `PATH` del shell. Si solo ejecutas `/plugin install` y luego escribes `memesh reindex` en una terminal, verás `command not found`. Es normal — añade `npm install -g @pcircle/memesh` también para acceso desde el shell.
+
+### ⚠️ Instalar el plugin NO instala el CLI
+
+Es la confusión más común. Léelo una vez y te ahorrarás un bucle futuro:
+
+- `/plugin install memesh@pcircle-memesh` desde Claude Code → instala **solo Path A**. Te da herramientas MCP, hooks, el skill `/memesh`. **NO** pone `memesh` en tu `PATH` del shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` en una terminal → necesita **Path B** (npm-global). Sin él: `zsh: command not found: memesh`.
+- **Configuración recomendada para usuarios de Claude Code**: **instala ambos**. Coexisten, comparten la misma base de datos, no conflictúan.
+
+```bash
+# Después de /plugin install ..., ejecuta también esto:
+npm install -g @pcircle/memesh
+```
+
+Si solo usas memesh a través del chat de Claude Code (nunca tecleas `memesh` en una terminal), Path A solo es suficiente. Para todos los demás: instala ambos.
+
+---
+
## Primeros Pasos en 60 Segundos
### Opción A — Plugin de Claude Code (instalación de una línea)
diff --git a/README.fr.md b/README.fr.md
index 0be7bd3b..5a0a9fbe 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -42,6 +42,67 @@ Les commandes de reproduction, le SHA256 du jeu de données, les résultats brut
---
+## Aperçu des chemins d'installation
+
+MeMesh a **deux chemins d'installation coexistants**. La plupart des utilisateurs veulent les deux. Ils écrivent dans la **même base de données mémoire** (`~/.memesh/knowledge-graph.db`), donc les mémoires capturées dans Claude Code apparaissent dans votre shell, et vice versa.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**Lequel vous faut-il ?**
+
+| Ce que vous voulez faire | Chemin d'installation |
+|---|---|
+| Utiliser le skill `/memesh` dans une conversation Claude Code | Path A (plugin) |
+| Auto-capture dans Claude Code (session → leçons → recall suivant) | Path A (plugin) |
+| Exécuter `memesh remember` / `memesh recall` / `memesh doctor` dans n'importe quel terminal | Path B (npm-global) |
+| Ouvrir le dashboard via `memesh` (sans délai de démarrage `npx`) | Path B (npm-global) |
+| Brancher `memesh-mcp` à Cursor, Cline ou un autre client MCP | Path B (npm-global) |
+| Tout ce qui précède | **Installez les deux** — ils ne sont pas en conflit |
+
+> **Confusion courante** : le plugin Claude Code **ne** met **pas** `memesh` sur votre `PATH` shell. Si vous lancez seulement `/plugin install` puis tapez `memesh reindex` dans un terminal, vous verrez `command not found`. C'est normal — il faut aussi `npm install -g @pcircle/memesh` pour l'accès shell.
+
+### ⚠️ Installer le plugin n'installe PAS le CLI
+
+C'est la confusion la plus fréquente. Lisez ceci une fois et vous gagnerez du temps plus tard :
+
+- `/plugin install memesh@pcircle-memesh` depuis Claude Code → installe **uniquement Path A**. Vous obtenez les outils MCP, les hooks, le skill `/memesh`. `memesh` n'est **PAS** ajouté à votre `PATH` shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` dans un terminal → nécessite **Path B** (npm-global). Sans : `zsh: command not found: memesh`.
+- **Configuration recommandée pour les utilisateurs Claude Code** : **installez les deux**. Coexistent, partagent la même base de données, aucun conflit.
+
+```bash
+# Après /plugin install ..., exécutez aussi ceci :
+npm install -g @pcircle/memesh
+```
+
+Si vous utilisez memesh uniquement via le chat Claude Code (jamais `memesh` dans un terminal), Path A suffit. Tous les autres : installez les deux.
+
+---
+
## Démarrer en 60 Secondes
### Étape 1 : Installer
diff --git a/README.ja.md b/README.ja.md
index 1121ec17..c85ac08e 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -42,6 +42,67 @@ MeMesh の検索エンジンは **FTS5 のみ**(LLM もホットパスのエン
---
+## インストールパス早見表
+
+MeMesh には**共存する 2 つのインストールパス**があります。ほとんどのユーザーは両方が必要です。両者は**同じメモリデータベース**（`~/.memesh/knowledge-graph.db`）に書き込むため、Claude Code チャットで捕捉した記憶がシェルにも反映され、逆も同様です。
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**どちらが必要？**
+
+| やりたいこと | インストールパス |
+|---|---|
+| Claude Code の会話で `/memesh` skill を使う | Path A（プラグイン）|
+| Claude Code で自動キャプチャ（session → 学習 → 次回リコール） | Path A（プラグイン）|
+| ターミナルで `memesh remember` / `memesh recall` / `memesh doctor` を実行 | Path B（npm-global）|
+| `memesh` でダッシュボードを直接起動（`npx` 起動遅延なし） | Path B（npm-global）|
+| `memesh-mcp` を Cursor、Cline、その他の MCP クライアントに接続 | Path B（npm-global）|
+| すべて | **両方インストール** — 競合しません |
+
+> **よくある誤解**：Claude Code のプラグインは **`memesh` をシェルの `PATH` には追加しません**。`/plugin install` だけを実行して、ターミナルで `memesh reindex` と打つと `command not found` が出ます。これは仕様です — シェルコマンドを使うには `npm install -g @pcircle/memesh` も必要です。
+
+### ⚠️ プラグインのインストールでは CLI は入りません
+
+最もよくある混乱です。一度読んでおけば、後で時間を節約できます：
+
+- Claude Code 内で `/plugin install memesh@pcircle-memesh` → **Path A のみ**インストール。MCP ツール、hooks、`/memesh` skill が手に入ります。`memesh` はシェルの `PATH` には**入りません**。
+- ターミナルで `memesh reindex` / `memesh update` / `memesh doctor` → **Path B**（npm-global）が必要。なければ `zsh: command not found: memesh`。
+- **Claude Code ユーザーへの推奨セットアップ**：**両方インストール**。共存し、同じデータベースを共有し、競合しません。
+
+```bash
+# /plugin install ... の後、これも実行：
+npm install -g @pcircle/memesh
+```
+
+Claude Code の会話だけで memesh を使う場合（ターミナルで `memesh` を打たない場合）、Path A だけで十分です。それ以外の方は両方インストールしてください。
+
+---
+
## 60 秒で始める
### オプション A — Claude Code プラグイン(ワンライナーインストール)
diff --git a/README.ko.md b/README.ko.md
index 1d90df85..90fdc095 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -42,6 +42,67 @@ MeMesh의 검색 엔진은 **FTS5 단독**(핫 패스에 LLM 없음, 임베딩
---
+## 설치 경로 한눈에 보기
+
+MeMesh에는 **공존하는 두 가지 설치 경로**가 있습니다. 대부분의 사용자는 둘 다 필요합니다. 동일한 **메모리 데이터베이스**(`~/.memesh/knowledge-graph.db`)에 기록되므로 Claude Code 채팅에서 저장한 기억이 셸에서도 보이고 그 반대도 마찬가지입니다.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**어느 쪽이 필요한가요?**
+
+| 하고 싶은 일 | 설치 경로 |
+|---|---|
+| Claude Code 대화에서 `/memesh` skill 사용 | Path A(플러그인) |
+| Claude Code에서 자동 캡처(session → 교훈 → 다음 recall) | Path A(플러그인) |
+| 터미널에서 `memesh remember` / `memesh recall` / `memesh doctor` 실행 | Path B(npm-global) |
+| `memesh`로 대시보드 바로 열기(`npx` 시작 지연 없음) | Path B(npm-global) |
+| `memesh-mcp`를 Cursor, Cline 또는 기타 MCP 클라이언트에 연결 | Path B(npm-global) |
+| 위 전부 | **둘 다 설치** — 충돌 없음 |
+
+> **흔한 오해**: Claude Code 플러그인은 `memesh`를 셸 `PATH`에 **추가하지 않습니다**. `/plugin install`만 실행하고 터미널에 `memesh reindex`를 입력하면 `command not found`가 나옵니다. 정상입니다 — 셸 명령을 쓰려면 `npm install -g @pcircle/memesh`도 실행해야 합니다.
+
+### ⚠️ 플러그인 설치만으로는 CLI가 설치되지 않습니다
+
+가장 흔한 혼란입니다. 한 번만 읽어두면 됩니다:
+
+- Claude Code에서 `/plugin install memesh@pcircle-memesh` → **Path A만** 설치. MCP 도구, hooks, `/memesh` skill을 제공. `memesh`를 셸 `PATH`에 **추가하지 않음**.
+- 터미널에서 `memesh reindex` / `memesh update` / `memesh doctor` 입력 → **Path B**(npm-global)가 필요. 없으면 `zsh: command not found: memesh`.
+- **Claude Code 사용자 권장 설정**: **둘 다 설치**. 공존하며 동일한 데이터베이스를 공유하고 충돌하지 않습니다.
+
+```bash
+# /plugin install ... 후에 이것도 실행:
+npm install -g @pcircle/memesh
+```
+
+Claude Code 대화에서만 memesh를 사용한다면(터미널에서 `memesh`를 입력하지 않는다면) Path A만으로 충분합니다. 나머지는 둘 다 설치하세요.
+
+---
+
## 60초 안에 시작하기
### 옵션 A — Claude Code 플러그인 (한 줄 설치)
diff --git a/README.md b/README.md
index 5ef935b7..0958eff4 100644
--- a/README.md
+++ b/README.md
@@ -42,6 +42,65 @@ Reproduction commands, dataset SHA256, raw per-question results, and known-failu
---
+## Install paths at a glance
+
+MeMesh has **two install paths that coexist**. Most users want both. They write to the **same memory database** (`~/.memesh/knowledge-graph.db`), so memories captured in Claude Code chat appear in your shell, and vice versa.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**Which one do you need?**
+
+| What you want to do | Install path |
+|---|---|
+| Use the `/memesh` skill inside a Claude Code conversation | Path A (plugin) |
+| Get auto-capture (sessions → lessons → recall) in Claude Code | Path A (plugin) |
+| Run `memesh remember` / `memesh recall` / `memesh doctor` in any terminal | Path B (npm-global) |
+| Open the local dashboard via `memesh` (no `npx` lookup delay) | Path B (npm-global) |
+| Plug `memesh-mcp` into Cursor, Cline, or another MCP client | Path B (npm-global) |
+| All of the above | **Install both** — they don't conflict |
+
+### ⚠️ Installing the plugin does NOT install the CLI
+
+This is the most common confusion. Read this once and you'll save yourself the loop:
+
+- `/plugin install memesh@pcircle-memesh` from inside Claude Code → installs **Path A only**. Gives you MCP tools, hooks, the `/memesh` skill. Does **NOT** put `memesh` on your shell `PATH`.
+- `memesh reindex` / `memesh update` / `memesh doctor` typed in a normal terminal → needs **Path B** (npm-global). Without it: `zsh: command not found: memesh`.
+- **Recommended setup for Claude Code users**: install **both**. They coexist, share the same database, never conflict.
+
+```bash
+# After /plugin install ..., also run this:
+npm install -g @pcircle/memesh
+```
+
+If you only use memesh through Claude Code chat (never type `memesh` in a terminal), Path A alone is enough. Everyone else: install both.
+
+---
+
## Get Started in 60 Seconds
### Option A — Claude Code plugin (one-line install)
@@ -53,7 +112,11 @@ If you use Claude Code, install MeMesh as a plugin from inside the CLI:
/plugin install memesh@pcircle-memesh
```
-Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent. The CLI and the local dashboard are also fully accessible without any extra global install — `npx @pcircle/memesh ` runs every CLI command, and `npx @pcircle/memesh` launches the dashboard at `localhost:3737`. The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no `npm install -g`, no build step needed. If the native `better-sqlite3` binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process before continuing.
+Claude Code wires hooks, skills, and the MCP server automatically. You get in-session auto-capture, proactive recall, the `/memesh` skill (remember / recall / learn / forget) inside the Claude Code conversation, and `remember` / `recall` / `forget` / `learn` available as MCP tools to the agent.
+
+The MCP server runs directly from the plugin's bundled compiled output — no `npx` lookup, no build step needed. If the native `better-sqlite3` binding is missing on first start (e.g. after a Node major upgrade), the launcher self-heals by rebuilding it in-process.
+
+> **This installs the plugin only.** You can run CLI commands via `npx @pcircle/memesh ` if you absolutely don't want a global install, but typing plain `memesh` in a terminal will report `command not found`. To get a real shell `memesh` command, also run **Option B** below — both paths coexist and share the same memory database. The "Install paths at a glance" diagram above covers this.
### Option B — npm global (optional optimisation)
diff --git a/README.pt.md b/README.pt.md
index b10abf39..7f9c0ebb 100644
--- a/README.pt.md
+++ b/README.pt.md
@@ -42,6 +42,67 @@ Comandos de reprodução, SHA256 do dataset, resultados brutos por pergunta e an
---
+## Caminhos de instalação resumidos
+
+MeMesh tem **dois caminhos de instalação que coexistem**. A maioria dos usuários quer ambos. Ambos escrevem no **mesmo banco de dados de memória** (`~/.memesh/knowledge-graph.db`), então memórias capturadas no chat do Claude Code aparecem no seu shell, e vice-versa.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**Qual você precisa?**
+
+| O que você quer fazer | Caminho de instalação |
+|---|---|
+| Usar o skill `/memesh` numa conversa do Claude Code | Path A (plugin) |
+| Auto-captura no Claude Code (sessão → lições → recall seguinte) | Path A (plugin) |
+| Rodar `memesh remember` / `memesh recall` / `memesh doctor` em qualquer terminal | Path B (npm-global) |
+| Abrir o dashboard via `memesh` (sem atraso de inicialização do `npx`) | Path B (npm-global) |
+| Conectar `memesh-mcp` ao Cursor, Cline ou outro cliente MCP | Path B (npm-global) |
+| Tudo acima | **Instale ambos** — não conflitam |
+
+> **Confusão comum**: o plugin do Claude Code **não** coloca `memesh` no `PATH` do seu shell. Se você só rodar `/plugin install` e depois digitar `memesh reindex` num terminal, vai ver `command not found`. É normal — adicione `npm install -g @pcircle/memesh` também para acesso pelo shell.
+
+### ⚠️ Instalar o plugin NÃO instala o CLI
+
+É a confusão mais comum. Leia uma vez e economize tempo no futuro:
+
+- `/plugin install memesh@pcircle-memesh` no Claude Code → instala **apenas Path A**. Te dá ferramentas MCP, hooks, o skill `/memesh`. **NÃO** coloca `memesh` no `PATH` do seu shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` num terminal → precisa do **Path B** (npm-global). Sem ele: `zsh: command not found: memesh`.
+- **Configuração recomendada para usuários do Claude Code**: **instale ambos**. Coexistem, compartilham o mesmo banco, sem conflito.
+
+```bash
+# Depois de /plugin install ..., rode também isto:
+npm install -g @pcircle/memesh
+```
+
+Se você só usa memesh pelo chat do Claude Code (nunca digita `memesh` num terminal), Path A sozinho basta. Os demais: instale ambos.
+
+---
+
## Comece em 60 Segundos
### Passo 1: Instale
diff --git a/README.th.md b/README.th.md
index 3a483f02..fbab0421 100644
--- a/README.th.md
+++ b/README.th.md
@@ -42,6 +42,67 @@
---
+## ภาพรวมเส้นทางการติดตั้ง
+
+MeMesh มี **เส้นทางการติดตั้งสองเส้นที่อยู่ร่วมกันได้** ผู้ใช้ส่วนใหญ่ต้องการทั้งคู่ ทั้งสองเขียนลงใน **ฐานข้อมูลความจำเดียวกัน** (`~/.memesh/knowledge-graph.db`) ดังนั้นความจำที่บันทึกในแชท Claude Code จะปรากฏใน shell และในทางกลับกัน
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**คุณต้องการเส้นทางไหน?**
+
+| สิ่งที่คุณต้องการทำ | เส้นทางการติดตั้ง |
+|---|---|
+| ใช้ skill `/memesh` ในการสนทนา Claude Code | Path A (plugin) |
+| Auto-capture ใน Claude Code (session → บทเรียน → recall ครั้งถัดไป) | Path A (plugin) |
+| รัน `memesh remember` / `memesh recall` / `memesh doctor` ใน terminal | Path B (npm-global) |
+| เปิด dashboard ผ่าน `memesh` (ไม่มีดีเลย์ของ `npx`) | Path B (npm-global) |
+| เสียบ `memesh-mcp` เข้ากับ Cursor, Cline หรือ MCP client อื่น | Path B (npm-global) |
+| ทั้งหมดข้างต้น | **ติดตั้งทั้งสอง** — ไม่ขัดแย้งกัน |
+
+> **ความเข้าใจผิดที่พบบ่อย**: plugin ของ Claude Code **ไม่** ใส่ `memesh` ลงใน `PATH` ของ shell ถ้าคุณรันแค่ `/plugin install` แล้วพิมพ์ `memesh reindex` ใน terminal คุณจะเห็น `command not found` — เป็นเรื่องปกติ ต้องเพิ่ม `npm install -g @pcircle/memesh` ด้วย เพื่อใช้คำสั่งใน shell
+
+### ⚠️ การติดตั้ง plugin ไม่ได้ติดตั้ง CLI
+
+นี่คือความสับสนที่พบบ่อยที่สุด อ่านครั้งเดียวจะประหยัดเวลาในอนาคต:
+
+- `/plugin install memesh@pcircle-memesh` จากภายใน Claude Code → ติดตั้ง **เฉพาะ Path A**ให้ MCP tools, hooks, skill `/memesh`**ไม่ได้** ใส่ `memesh` ลงใน `PATH` ของ shell
+- `memesh reindex` / `memesh update` / `memesh doctor` ใน terminal → ต้องใช้ **Path B** (npm-global) ถ้าไม่มี: `zsh: command not found: memesh`
+- **การติดตั้งที่แนะนำสำหรับผู้ใช้ Claude Code**: **ติดตั้งทั้งสอง** อยู่ร่วมกัน ใช้ DB เดียวกัน ไม่ขัดแย้งกัน
+
+```bash
+# หลังจาก /plugin install ... ให้รันคำสั่งนี้ด้วย:
+npm install -g @pcircle/memesh
+```
+
+ถ้าคุณใช้ memesh ผ่านแชท Claude Code เท่านั้น (ไม่เคยพิมพ์ `memesh` ใน terminal), Path A อย่างเดียวก็พอ คนอื่นๆ ให้ติดตั้งทั้งสอง
+
+---
+
## เริ่มต้นใน 60 วินาที
### ตัวเลือก A — Claude Code plugin (ติดตั้งด้วยบรรทัดเดียว)
diff --git a/README.vi.md b/README.vi.md
index 03f3dccd..3f24bf71 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -42,6 +42,67 @@ Lệnh tái hiện, SHA256 của dataset, kết quả thô theo từng câu hỏ
---
+## Tổng quan các đường cài đặt
+
+MeMesh có **hai đường cài đặt cùng tồn tại**. Hầu hết người dùng muốn cả hai. Chúng ghi vào **cùng một cơ sở dữ liệu bộ nhớ** (`~/.memesh/knowledge-graph.db`), nên ký ức ghi trong chat Claude Code sẽ xuất hiện ở shell, và ngược lại.
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**Bạn cần đường nào?**
+
+| Bạn muốn làm gì | Đường cài đặt |
+|---|---|
+| Dùng skill `/memesh` trong cuộc trò chuyện Claude Code | Path A (plugin) |
+| Tự động capture trong Claude Code (session → bài học → recall lần sau) | Path A (plugin) |
+| Chạy `memesh remember` / `memesh recall` / `memesh doctor` ở bất kỳ terminal nào | Path B (npm-global) |
+| Mở dashboard qua `memesh` (không bị trễ khởi động `npx`) | Path B (npm-global) |
+| Cắm `memesh-mcp` vào Cursor, Cline hoặc client MCP khác | Path B (npm-global) |
+| Tất cả các mục trên | **Cài cả hai** — không xung đột |
+
+> **Nhầm lẫn phổ biến**: plugin Claude Code **không** đặt `memesh` lên `PATH` của shell. Nếu bạn chỉ chạy `/plugin install` rồi gõ `memesh reindex` trong terminal, bạn sẽ thấy `command not found`. Đó là điều bình thường — thêm `npm install -g @pcircle/memesh` để có lệnh shell.
+
+### ⚠️ Cài plugin KHÔNG cài CLI
+
+Đây là nhầm lẫn phổ biến nhất. Đọc một lần để tiết kiệm thời gian sau này:
+
+- `/plugin install memesh@pcircle-memesh` từ Claude Code → chỉ cài **Path A**. Bạn có công cụ MCP, hooks, skill `/memesh`. **KHÔNG** đặt `memesh` lên `PATH` shell.
+- `memesh reindex` / `memesh update` / `memesh doctor` gõ trong terminal → cần **Path B** (npm-global). Không có nó: `zsh: command not found: memesh`.
+- **Thiết lập khuyến nghị cho người dùng Claude Code**: **cài cả hai**. Cùng tồn tại, chia sẻ cùng DB, không xung đột.
+
+```bash
+# Sau khi /plugin install ..., chạy luôn dòng này:
+npm install -g @pcircle/memesh
+```
+
+Nếu bạn chỉ dùng memesh qua chat Claude Code (không bao giờ gõ `memesh` trong terminal), Path A đủ rồi. Còn lại: cài cả hai.
+
+---
+
## Bắt đầu trong 60 giây
### Bước 1: Cài đặt
diff --git a/README.zh-CN.md b/README.zh-CN.md
index d3a017d5..e4c9400a 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -42,6 +42,67 @@ MeMesh 的检索引擎**只用 FTS5**（热路径上没有 LLM、也没有 embed
---
+## 安装路径一览
+
+MeMesh 有**两条共存的安装路径**。多数用户两条都需要。它们写入**同一份记忆数据库**（`~/.memesh/knowledge-graph.db`），所以 Claude Code 对话里记下的东西在 terminal 也看得到，反之亦然。
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**你需要哪条？**
+
+| 你想做什么 | 安装路径 |
+|---|---|
+| 在 Claude Code 对话里用 `/memesh` skill | Path A（plugin）|
+| 在 Claude Code 启用自动 capture（session → 教训 → 下次 recall） | Path A（plugin）|
+| 在任何 terminal 跑 `memesh remember` / `memesh recall` / `memesh doctor` | Path B（npm-global）|
+| 用 `memesh` 直接开 dashboard（没有 `npx` 启动延迟） | Path B（npm-global）|
+| 把 `memesh-mcp` 接到 Cursor、Cline 或其他 MCP client | Path B（npm-global）|
+| 以上全要 | **两条都装** — 不会冲突 |
+
+> **常见误会**：Claude Code 的 plugin **不会** 把 `memesh` 放到你的 shell `PATH` 上。如果你只跑 `/plugin install`，然后在 terminal 打 `memesh reindex`，你会看到 `command not found`。这是正常的 — 还要加 `npm install -g @pcircle/memesh` 才有 shell 命令。
+
+### ⚠️ 装 plugin 不会装 CLI
+
+这是最常见的踩坑点，读一次省下未来的循环：
+
+- 从 Claude Code 跑 `/plugin install memesh@pcircle-memesh` → 只装 **Path A**。给你 MCP 工具、hooks、`/memesh` skill。**不会**把 `memesh` 放到你的 shell `PATH`。
+- 在 terminal 打 `memesh reindex` / `memesh update` / `memesh doctor` → 需要 **Path B**（npm-global）。没装就会 `zsh: command not found: memesh`。
+- **Claude Code 使用者建议的安装方式**：**两条都装**。共存、共用同一份数据库、不冲突。
+
+```bash
+# 跑完 /plugin install ... 之后，再跑这个：
+npm install -g @pcircle/memesh
+```
+
+如果你只透过 Claude Code 对话用 memesh（从不在 terminal 打 `memesh`），Path A 自己就够了。其他人请两条都装。
+
+---
+
## 60 秒快速开始
### 选项 A — Claude Code 插件（一行安装）
diff --git a/README.zh-TW.md b/README.zh-TW.md
index de9e7bbd..0924ef0d 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -42,6 +42,67 @@ MeMesh 的檢索引擎**只用 FTS5**（熱路徑上不使用 LLM、不使用嵌
---
+## 安裝路徑一覽
+
+MeMesh 有**兩條會共存的安裝路徑**。多數使用者兩條都需要。它們寫入**同一份記憶資料庫**（`~/.memesh/knowledge-graph.db`），所以 Claude Code 對話裡記下的東西在 terminal 也看得到，反之亦然。
+
+```mermaid
+flowchart TB
+ classDef client fill:#1f2937,stroke:#4b5563,color:#f9fafb,stroke-width:1px
+ classDef pathA fill:#1e3a8a,stroke:#3b82f6,color:#eff6ff,stroke-width:2px
+ classDef pathB fill:#14532d,stroke:#22c55e,color:#f0fdf4,stroke-width:2px
+ classDef db fill:#7c2d12,stroke:#f97316,color:#fff7ed,stroke-width:2px
+
+ subgraph clients["Where you use memesh from"]
+ direction LR
+ CC["Claude Code
(chat + agent)"]:::client
+ TERM["Terminal / other
MCP clients
(Cursor, Cline...)"]:::client
+ end
+
+ subgraph paths["Two install paths"]
+ direction LR
+ A["Path A — /plugin install
───────────────
Lives in ~/.claude/plugins/
• MCP tools in chat
• Auto-capture hooks
• /memesh skill
• Session-start banner"]:::pathA
+ B["Path B — npm install -g
───────────────
Lives in $(npm prefix -g)/bin/
• memesh shell command
• memesh-mcp, -http, -view bins
• For Cursor / Cline / other MCP"]:::pathB
+ end
+
+ DB[("Shared memory DB
~/.memesh/knowledge-graph.db
Same data, both paths see it")]:::db
+
+ CC -->|uses| A
+ TERM -->|uses| B
+ A --> DB
+ B --> DB
+```
+
+**你需要哪一條？**
+
+| 你想做什麼 | 安裝路徑 |
+|---|---|
+| 在 Claude Code 對話裡用 `/memesh` skill | Path A（plugin）|
+| 在 Claude Code 自動 capture（session → 教訓 → 下次 recall）| Path A（plugin）|
+| 在任何 terminal 跑 `memesh remember` / `memesh recall` / `memesh doctor` | Path B（npm-global）|
+| 用 `memesh` 直接開 dashboard（沒有 `npx` 啟動延遲）| Path B（npm-global）|
+| 把 `memesh-mcp` 接到 Cursor、Cline 或其他 MCP client | Path B（npm-global）|
+| 以上都要 | **兩條都裝** — 不會衝突 |
+
+> **常見誤會（小心踩雷）**：Claude Code 的 plugin **不會** 把 `memesh` 放到你的 shell `PATH` 上。如果你只跑 `/plugin install`，然後在 terminal 打 `memesh reindex`，你會看到 `command not found`。這是正常的 — 還要加 `npm install -g @pcircle/memesh` 才有 shell 指令。
+
+### ⚠️ 裝 plugin 不會裝 CLI
+
+這個是最常見的踩坑點，讀一次省下未來的循環：
+
+- 從 Claude Code 跑 `/plugin install memesh@pcircle-memesh` → 只裝 **Path A**。給你 MCP 工具、hooks、`/memesh` skill。**不會**把 `memesh` 放到你的 shell `PATH`。
+- 在 terminal 打 `memesh reindex` / `memesh update` / `memesh doctor` → 需要 **Path B**（npm-global）。沒裝就會 `zsh: command not found: memesh`。
+- **Claude Code 使用者建議的安裝方式**：**兩條都裝**。共存、共用同一份資料庫、不衝突。
+
+```bash
+# 跑完 /plugin install ... 之後，再跑這個：
+npm install -g @pcircle/memesh
+```
+
+如果你只透過 Claude Code 對話用 memesh（從不在 terminal 打 `memesh`），Path A 自己就夠了。其他人請兩條都裝。
+
+---
+
## 60 秒快速開始
### 選項 A — Claude Code 外掛（一行安裝）
diff --git a/dist/skills-manifest.json b/dist/skills-manifest.json
index 27d39738..27586bdc 100644
--- a/dist/skills-manifest.json
+++ b/dist/skills-manifest.json
@@ -1,6 +1,6 @@
{
"schema": "memesh.skills-manifest/v1",
- "generated_at": "2026-05-13T05:46:34.185Z",
+ "generated_at": "2026-05-13T08:03:27.372Z",
"entries": [
{
"path": ".claude-plugin/plugin.json",