docs: clarify two install paths (plugin + npm-global) with Mermaid diagram across 11 READMEs

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<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>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

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<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>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)

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<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>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

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<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>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 プラグイン(ワンライナーインストール)

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<br/>(chat + agent)"]:::client
+      TERM["Terminal / other<br/>MCP clients<br/>(Cursor, Cline...)"]:::client
+    end
+
+    subgraph paths["Two install paths"]
+      direction LR
+      A["<b>Path A — /plugin install</b><br/>───────────────<br/>Lives in <code>~/.claude/plugins/</code><br/><br/>• MCP tools in chat<br/>• Auto-capture hooks<br/>• <code>/memesh</code> skill<br/>• Session-start banner"]:::pathA
+      B["<b>Path B — npm install -g</b><br/>───────────────<br/>Lives in <code>$(npm prefix -g)/bin/</code><br/><br/>• <code>memesh</code> shell command<br/>• <code>memesh-mcp</code>, <code>-http</code>, <code>-view</code> bins<br/>• For Cursor / Cline / other MCP"]:::pathB
+    end
+
+    DB[("Shared memory DB<br/><code>~/.memesh/knowledge-graph.db</code><br/>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 플러그인 (한 줄 설치)