diff --git a/CHANGELOG.md b/CHANGELOG.md
index b06bda15..521b1a23 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,17 @@
 
 All notable changes to MeMesh are documented here.
 
+## [Unreleased]
+
+### Docs
+- **All 11 README locales now have an `## Upgrading` section** (`README.md`, `README.zh-TW.md`, `README.zh-CN.md`, `README.ja.md`, `README.ko.md`, `README.de.md`, `README.fr.md`, `README.es.md`, `README.pt.md`, `README.vi.md`, `README.th.md`) — v4.2.5–v4.2.7 release notes added the upgrade flow + pre-v4.2.5 fallback to English + Thai only, so 9 locales were missing the section entirely. Now every locale has the three upgrade paths and the npm-global fallback note.
+- **"Actively developed" callout at the top of every README** — adds a `> [!IMPORTANT]` block immediately after the hero divider linking to the GitHub Issues tracker. Sets expectations that features evolve between releases and routes bug reports / feature requests to the correct channel from the first glance.
+
+### Fixed
+- **Test flake: `tests/transports/http.test.ts > returns array (possibly empty) for no-match query`** — assertion was `toHaveLength(0)`, but `recallEnhanced` may supplement FTS5 results with sqlite-vec near-neighbours when ONNX embeddings are loaded, so a query that misses FTS5 can still legitimately return a small set. The API contract is "always return a valid JSON array of entities, never a 500"; assertion now mirrors that contract (length bounded, all rows shaped like entities).
+- **Test flake: `tests/tools.test.ts > auto-archives entity when superseded by new remember`** — same root cause; the `recall('JWT')` after archiving `auth-v2` asserted exactly `[]`, but vector supplement could surface the related `auth-v3`. The behavioural guarantee is "archived rows stay hidden from default recall", so the assertion now checks `not.toContain('auth-v2')` instead of empty-array.
+- **Test isolation: `tests/hooks/pre-bash-orchestration-nudge.test.ts` no longer reads the developer's real `~/.memesh/config.json`** — `isAgenticOrchestrationEnabled()` falls back to `readHookConfig()` when the env var is unset, and `readHookConfig()` reads `<memeshDir>/config.json`. The "default off" test deleted the env var but didn't pin `MEMESH_DIR`, so a developer with `enableAgenticOrchestration: true` in their personal config saw the test fail even though hook code was correct. Both the test helper and the gate-off case now point `MEMESH_DIR` at the per-test tmpdir.
+
 ## [4.2.7] — 2026-05-13
 
 ### Added
diff --git a/README.de.md b/README.de.md
index 8352055f..bafd0467 100644
--- a/README.de.md
+++ b/README.de.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Aktiv entwickeltes Projekt** — Funktionen entwickeln sich kontinuierlich weiter und können sich zwischen Releases ändern. Bei Bugs oder Feature-Wünschen bitte [ein Issue eröffnen](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Das Problem
 
 Ihr Coding-Agent vergisst, was zwischen Sessions passiert ist. Jede Architekturentscheidung, jede Bugfix, jeder fehlgeschlagene Test und jede hart erarbeitete Erkenntnis muss erneut erklärt werden. Claude Code startet von vorne, entdeckt alte Constraints neu und verschwendet Context auf Dinge, die es längst wissen sollte.
@@ -376,6 +379,35 @@ Der Kern ist Framework-agnostisch. Dieselbe Logik läuft vom Terminal, HTTP oder
 
 ---
 
+## Aktualisieren
+
+Der Plugin-Marketplace von Claude Code fixiert Versionen zum Installationszeitpunkt und aktualisiert **nicht** automatisch. So holst du dir ein neues Release:
+
+**Option A — `/plugin` UI**: `memesh@pcircle-memesh` deinstallieren, dann neu installieren. Claude Code holt die neueste Marketplace-Version.
+
+**Option B — Einzeiler-Skript** (kein UI-Klicken, idempotent):
+
+```bash
+# Wenn deine Plugin-Installation v4.2.5 oder neuer ist, ist das Skript enthalten:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Bei Installationen vor v4.2.5 (also v4.2.4 oder v4.2.3)
+# ist das Skript noch nicht im Plugin. Nutze stattdessen die npm-global-Kopie:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Das setzt voraus, dass du auch `npm install -g @pcircle/memesh` ausgeführt hast.
+# Falls nicht, ist jetzt ein guter Moment dafür — siehe oben „Installationspfade auf
+# einen Blick" für die Gründe, warum die meisten Nutzer beide Pfade wollen.)
+```
+
+Das Skript fast-forwarded den Marketplace-Cache, legt die neue Version unter `~/.claude/plugins/cache/` ab, installiert Runtime-Dependencies und zeigt `installed_plugins.json` neu. Starte danach Claude Code neu, damit der MCP-Server sich neu verbindet.
+
+**npm-global-Installationen** (`npm install -g @pcircle/memesh`) können sich via `memesh update` selbst aktualisieren. Source-Checkouts: `git pull && npm install && npm run build`.
+
+Beim Session-Start erscheint ein einzeiliges Banner (pro Version alle 24h gedrosselt), wenn ein neueres Release verfügbar ist, und `memesh doctor` meldet das Upgrade-Ziel mit kanalspezifischem Befehl.
+
+---
+
 ## Beitragen
 
 ```bash
diff --git a/README.es.md b/README.es.md
index c02e27aa..69ae5c97 100644
--- a/README.es.md
+++ b/README.es.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Proyecto en desarrollo activo** — las funcionalidades evolucionan continuamente y pueden cambiar entre versiones. Si encuentras un bug o tienes una solicitud de funcionalidad, por favor [abre un issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## El Problema
 
 Tu agente de codificación olvida lo que sucedió en sesiones anteriores. Cada decisión arquitectónica, corrección de bugs, prueba fallida y lección aprendida con esfuerzo debe explicarse de nuevo. Claude Code comienza desde cero, redescubre restricciones antiguas y gasta contexto en cosas que ya debería saber.
@@ -404,6 +407,35 @@ El core es agnóstico de framework. La misma lógica se ejecuta desde terminal,
 
 ---
 
+## Actualizar
+
+El plugin marketplace de Claude Code fija las versiones en el momento de la instalación y **no** se actualiza automáticamente. Para obtener una nueva versión:
+
+**Opción A — Interfaz `/plugin`**: desinstala `memesh@pcircle-memesh`, luego reinstala. Claude Code obtiene la versión más reciente del marketplace.
+
+**Opción B — Script en una línea** (sin hacer clic en la UI, idempotente):
+
+```bash
+# Si tu plugin instalado es v4.2.5 o posterior, el script viene incluido:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si instalaste antes de v4.2.5 (es decir, v4.2.4 o v4.2.3),
+# el script aún no está en tu plugin. Usa la copia npm-global en su lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Esto asume que también ejecutaste `npm install -g @pcircle/memesh`. Si no lo has hecho,
+# este es un buen momento para hacerlo — consulta la sección "Vista rápida de las rutas
+# de instalación" arriba para entender por qué la mayoría de los usuarios quieren ambas.)
+```
+
+El script fast-forwarded el caché del marketplace, prepara la nueva versión en `~/.claude/plugins/cache/`, instala las runtime deps y repunta `installed_plugins.json`. Reinicia Claude Code después para que el MCP server se reconecte.
+
+**Las instalaciones npm-global** (`npm install -g @pcircle/memesh`) pueden auto-actualizarse mediante `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+Al inicio de sesión aparece un banner de una línea (limitado a una vez cada 24h por versión) cuando hay una nueva versión disponible, y `memesh doctor` reporta el objetivo de actualización con el comando específico del canal.
+
+---
+
 ## Contribuir
 
 ```bash
diff --git a/README.fr.md b/README.fr.md
index 5a0a9fbe..85d2e76e 100644
--- a/README.fr.md
+++ b/README.fr.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projet en développement actif** — les fonctionnalités évoluent continuellement et peuvent changer entre les versions. En cas de bug ou de demande de fonctionnalité, merci d'[ouvrir une issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Le Problème
 
 Votre agent de codage oublie ce qui s'est passé d'une session à l'autre. Chaque décision architecturale, correction de bug, test échoué et leçon apprise difficilement doit être réexpliquée. Claude Code redémarre à zéro, redécouvre les anciennes contraintes et gaspille du contexte sur des éléments qu'il devrait déjà connaître.
@@ -377,6 +380,35 @@ Le cœur est agnostique du framework. La même logique s'exécute depuis le term
 
 ---
 
+## Mise à Jour
+
+Le plugin marketplace de Claude Code fige les versions à l'installation et **ne** se met **pas** à jour automatiquement. Pour récupérer une nouvelle version :
+
+**Option A — Interface `/plugin`** : désinstaller `memesh@pcircle-memesh`, puis réinstaller. Claude Code récupère la dernière version du marketplace.
+
+**Option B — Script en une ligne** (sans cliquer dans l'UI, idempotent) :
+
+```bash
+# Si votre plugin est en v4.2.5 ou plus récent, le script est embarqué :
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Si vous avez installé avant v4.2.5 (c.-à-d. v4.2.4 ou v4.2.3),
+# le script n'est pas encore dans votre plugin. Utilisez la copie npm-global :
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Cela suppose que vous avez aussi exécuté `npm install -g @pcircle/memesh`. Sinon,
+# c'est le bon moment — voir la section « Aperçu des chemins d'installation »
+# ci-dessus pour comprendre pourquoi la plupart des utilisateurs veulent les deux.)
+```
+
+Le script fast-forward le cache marketplace, place la nouvelle version dans `~/.claude/plugins/cache/`, installe les runtime deps, et repointe `installed_plugins.json`. Redémarrez Claude Code ensuite pour que le serveur MCP se reconnecte.
+
+**Les installations npm-global** (`npm install -g @pcircle/memesh`) peuvent s'auto-mettre à jour via `memesh update`. Source checkouts : `git pull && npm install && npm run build`.
+
+Au démarrage de session, une bannière sur une ligne s'affiche (limitée à une fois par 24h par version) quand une nouvelle version est disponible, et `memesh doctor` indique la cible de mise à jour avec la commande adaptée au canal.
+
+---
+
 ## Contribuer
 
 ```bash
diff --git a/README.ja.md b/README.ja.md
index c85ac08e..c8d78df8 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **活発に開発中のプロジェクト** — 機能は継続的に更新され、リリース間で変更される可能性があります。バグや機能要望がある場合は[issue を開いてください](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 課題
 
 コーディングエージェントはセッション間で記憶を失います。アーキテクチャの決定、バグ修正、テスト失敗、苦労して得た教訓 — すべてを毎回説明し直さなければなりません。Claude Code はいつも初期状態から始まり、既に知っているはずの制約を再発見し、貴重なコンテキストを無駄にします。
@@ -404,6 +407,35 @@ memesh  # ダッシュボード → Settings タブを開く
 
 ---
 
+## アップグレード
+
+Claude Code の plugin marketplace はインストール時にバージョンを固定し、**自動更新しません**。新しいリリースを取得するには：
+
+**オプション A — `/plugin` UI**：`memesh@pcircle-memesh` をアンインストールして再インストール。Claude Code が marketplace の最新バージョンを取得します。
+
+**オプション B — ワンラインスクリプト**（UI クリック不要、冪等）：
+
+```bash
+# plugin が v4.2.5 以降なら、スクリプトは同梱済み：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# v4.2.5 より前（つまり v4.2.4 または v4.2.3）のインストールの場合、
+# スクリプトはまだ plugin に入っていません。npm-global の副本を使用：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （`npm install -g @pcircle/memesh` も実行済みであることを前提とします。
+# まだなら、ちょうど良い機会です — 上の「インストールパス早見表」セクションで、
+# 多くのユーザーが両方のパスを必要とする理由を確認してください。）
+```
+
+スクリプトは marketplace cache を fast-forward し、新バージョンを `~/.claude/plugins/cache/` に展開し、runtime deps をインストールし、`installed_plugins.json` を新バージョンに向け直します。完了後、MCP server が再接続するように Claude Code を再起動してください。
+
+**npm-global インストール**（`npm install -g @pcircle/memesh`）は `memesh update` で自動更新できます。Source checkouts：`git pull && npm install && npm run build`。
+
+セッション開始時、新しいリリースがあると 1 行のバナーが表示されます（バージョンごとに 24 時間スロットル）。`memesh doctor` はアップグレードターゲットとチャンネル固有のコマンドを報告します。
+
+---
+
 ## コントリビュート
 
 ```bash
diff --git a/README.ko.md b/README.ko.md
index 90fdc095..02e80e97 100644
--- a/README.ko.md
+++ b/README.ko.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **활발히 개발 중인 프로젝트** — 기능이 지속적으로 업데이트되며 릴리스 간에 변경될 수 있습니다. 버그나 기능 요청이 있으면 [issue를 열어주세요](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## 문제점
 
 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버립니다. 아키텍처 결정, 버그 수정, 실패한 테스트, 힘들게 얻은 교훈 — 매번 다시 설명해야 합니다. Claude Code는 매번 새로 시작하고, 이미 알아야 할 제약 조건을 다시 발견하며, 불필요하게 컨텍스트를 소비합니다.
@@ -404,6 +407,35 @@ memesh  # 대시보드 열기 → Settings 탭
 
 ---
 
+## 업그레이드
+
+Claude Code의 plugin marketplace는 설치 시 버전을 고정하며 **자동으로 업데이트되지 않습니다**. 새 릴리스를 가져오려면:
+
+**옵션 A — `/plugin` UI**: `memesh@pcircle-memesh`를 제거한 후 다시 설치합니다. Claude Code가 marketplace의 최신 버전을 가져옵니다.
+
+**옵션 B — 한 줄 스크립트** (UI 클릭 불필요, 멱등):
+
+```bash
+# plugin이 v4.2.5 이상이면 스크립트가 함께 제공됩니다:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# v4.2.5 이전 버전(즉 v4.2.4 또는 v4.2.3)을 설치한 경우,
+# 스크립트가 plugin에 아직 없습니다. npm-global 사본을 사용하세요:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (이는 `npm install -g @pcircle/memesh`도 실행했다고 가정합니다. 아직 안 했다면
+# 지금이 적기입니다 — 위의 "설치 경로 한눈에 보기" 섹션에서 대부분의 사용자가
+# 두 경로를 모두 원하는 이유를 확인하세요.)
+```
+
+스크립트는 marketplace cache를 fast-forward하고, 새 버전을 `~/.claude/plugins/cache/`에 스테이징하고, runtime deps를 설치하고, `installed_plugins.json`을 새 버전으로 다시 가리킵니다. 완료 후 MCP server가 다시 연결되도록 Claude Code를 재시작하세요.
+
+**npm-global 설치**(`npm install -g @pcircle/memesh`)는 `memesh update`로 자체 업데이트할 수 있습니다. Source checkouts: `git pull && npm install && npm run build`.
+
+세션 시작 시 새 릴리스가 있으면 한 줄 배너가 표시됩니다(버전당 24시간 스로틀). `memesh doctor`는 업그레이드 대상과 채널별 명령을 보고합니다.
+
+---
+
 ## 기여하기
 
 ```bash
diff --git a/README.md b/README.md
index 6ad0e85d..46d8f4c8 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Actively developed project** — features evolve and may change between releases. If you hit a bug or have a feature request, please [open an issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## The Problem
 
 Your coding agent forgets what happened between sessions. Every architecture decision, bug fix, failed test, and hard-won lesson has to be re-explained. Claude Code starts fresh, re-discovers old constraints, and burns context on things it should already know.
diff --git a/README.pt.md b/README.pt.md
index 7f9c0ebb..eeb7f3e5 100644
--- a/README.pt.md
+++ b/README.pt.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Projeto em desenvolvimento ativo** — funcionalidades evoluem continuamente e podem mudar entre releases. Em caso de bug ou pedido de funcionalidade, por favor [abra uma issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## O Problema
 
 Seu agente de código esquece tudo entre sessões. Toda decisão arquitetônica, correção de bug, teste que falhou e lição conquistada na marra precisa ser re-explicada. Claude Code sempre começa do zero, redescobre restrições antigas e queima contexto em coisas que já deveria saber.
@@ -377,6 +380,35 @@ Core é agnóstico a framework. A mesma lógica roda de terminal, HTTP ou MCP.
 
 ---
 
+## Atualizando
+
+O plugin marketplace do Claude Code fixa versões no momento da instalação e **não** atualiza automaticamente. Para obter uma nova versão:
+
+**Opção A — UI `/plugin`**: desinstale `memesh@pcircle-memesh`, depois reinstale. O Claude Code busca a versão mais recente do marketplace.
+
+**Opção B — Script de uma linha** (sem cliques na UI, idempotente):
+
+```bash
+# Se o seu plugin instalado for v4.2.5 ou mais recente, o script já está incluído:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Se você instalou antes de v4.2.5 (ou seja, v4.2.4 ou v4.2.3),
+# o script ainda não está no seu plugin. Use a cópia npm-global no lugar:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Isso assume que você também executou `npm install -g @pcircle/memesh`. Se não,
+# este é um bom momento para fazê-lo — veja a seção "Caminhos de instalação resumidos"
+# acima para entender por que a maioria dos usuários quer ambos os caminhos.)
+```
+
+O script fast-forwarded o cache do marketplace, prepara a nova versão em `~/.claude/plugins/cache/`, instala runtime deps e repõe o ponteiro de `installed_plugins.json`. Reinicie o Claude Code depois para o MCP server reconectar.
+
+**Instalações npm-global** (`npm install -g @pcircle/memesh`) podem se auto-atualizar via `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+No início da sessão aparece um banner de uma linha (limitado a uma vez por 24h por versão) quando há uma nova versão disponível, e `memesh doctor` reporta o alvo de upgrade com o comando específico do canal.
+
+---
+
 ## Contribuindo
 
 ```bash
diff --git a/README.th.md b/README.th.md
index 08d03cb5..4e0001a7 100644
--- a/README.th.md
+++ b/README.th.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **โปรเจกต์อยู่ระหว่างพัฒนาอย่างต่อเนื่อง** — ฟีเจอร์มีการอัปเดตอย่างต่อเนื่องและอาจเปลี่ยนแปลงระหว่างเวอร์ชัน หากพบบักหรือมีคำขอฟีเจอร์ กรุณา[เปิด issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)
+
 ## ปัญหา
 
 เอเจนต์คิดโค้ดลืมสิ่งที่เกิดขึ้นระหว่างเซสชัน ทุกการตัดสินใจด้านสถาปัตยกรรม การแก้บั๊ก การทดสอบที่ล้มเหลว และบทเรียนที่ยากที่สุดต้องอธิบายซ้ำ Claude Code เริ่มต้นใหม่ ค้นพบข้อจำกัดเดิม และใช้ context ไปกับสิ่งที่น่าจะรู้อยู่แล้ว
diff --git a/README.vi.md b/README.vi.md
index 3f24bf71..d5fb645a 100644
--- a/README.vi.md
+++ b/README.vi.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **Dự án đang phát triển tích cực** — tính năng cập nhật liên tục và có thể thay đổi giữa các bản phát hành. Nếu gặp lỗi hoặc có yêu cầu tính năng, vui lòng [mở issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues).
+
 ## Vấn đề
 
 Agent coding của bạn quên mất những gì đã xảy ra giữa các phiên làm việc. Mỗi quyết định kiến trúc, bug fix, test thất bại và bài học từng trải phải được giải thích lại từ đầu. Claude Code luôn bắt đầu từ trang trắng, phát hiện lại những ràng buộc cũ, và lãng phí context cho những thứ nó đã nên biết.
@@ -377,6 +380,35 @@ Core là framework-agnostic. Logic tương tự chạy từ terminal, HTTP, ho
 
 ---
 
+## Nâng cấp
+
+Plugin marketplace của Claude Code ghim phiên bản lúc cài đặt và **không** tự động cập nhật. Để lấy bản phát hành mới:
+
+**Tùy chọn A — Giao diện `/plugin`**: gỡ cài `memesh@pcircle-memesh`, rồi cài lại. Claude Code sẽ kéo phiên bản mới nhất từ marketplace.
+
+**Tùy chọn B — Script một dòng** (không cần click UI, idempotent):
+
+```bash
+# Nếu bản plugin đã cài là v4.2.5 trở lên, script đã có sẵn:
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# Nếu bạn cài trước v4.2.5 (tức là v4.2.4 hoặc v4.2.3),
+# script chưa nằm trong plugin của bạn. Dùng bản sao npm-global thay thế:
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# (Giả định bạn cũng đã chạy `npm install -g @pcircle/memesh`. Nếu chưa, đây là
+# thời điểm tốt để cài — xem phần "Tổng quan các đường cài đặt" ở trên để hiểu
+# vì sao đa số người dùng muốn có cả hai đường.)
+```
+
+Script sẽ fast-forward marketplace cache, đặt phiên bản mới vào `~/.claude/plugins/cache/`, cài runtime deps, rồi trỏ lại `installed_plugins.json`. Khởi động lại Claude Code sau đó để MCP server kết nối lại.
+
+**Bản cài npm-global** (`npm install -g @pcircle/memesh`) có thể tự cập nhật qua `memesh update`. Source checkouts: `git pull && npm install && npm run build`.
+
+Khi bắt đầu session, banner một dòng (throttle mỗi 24h mỗi version) hiện ra khi có bản phát hành mới, và `memesh doctor` báo cáo phiên bản nâng cấp với lệnh tương ứng kênh cài đặt.
+
+---
+
 ## Đóng góp
 
 ```bash
diff --git a/README.zh-CN.md b/README.zh-CN.md
index e4c9400a..bd43d410 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **持续开发中的项目** — 功能会持续更新，版本之间可能会有变动。遇到问题或想要新功能，请[开 issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 问题
 
 编码代理在会话间会遗忘。每个架构决策、每次 bug 修复、失败的测试用例、每一次来之不易的经验教训都需要重新解释一遍。Claude Code 每次都从零开始，重新发现老约束，浪费上下文在早该掌握的东西上。
@@ -404,6 +407,34 @@ memesh  # 打开仪表板 → 设置标签页
 
 ---
 
+## 升级
+
+Claude Code 的 plugin marketplace 在安装时把版本钉住，**不会**自动更新。要拿到新版本：
+
+**方法 A — `/plugin` 界面**：先卸载 `memesh@pcircle-memesh`，再重新安装。Claude Code 会抓取 marketplace 最新版。
+
+**方法 B — 一行命令**（无需点击 UI、幂等）：
+
+```bash
+# 如果 plugin 已经是 v4.2.5 或更新，脚本已内置：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# 如果是 v4.2.5 之前的版本（即 v4.2.4 或 v4.2.3），
+# 脚本还没在你的 plugin 里，改用 npm-global 的副本：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （这假设你也运行过 `npm install -g @pcircle/memesh`。如果还没，
+# 现在正好可以一起装 — 参考上面「安装路径一览」了解为什么大多数人两条路径都装。）
+```
+
+脚本会 fast-forward marketplace cache、把新版本放入 `~/.claude/plugins/cache/`、安装 runtime deps，然后把 `installed_plugins.json` 重指向新版本。完成后请重启 Claude Code 让 MCP server 重连。
+
+**npm-global 安装**（`npm install -g @pcircle/memesh`）可以直接通过 `memesh update` 自动更新。Source checkouts：`git pull && npm install && npm run build`。
+
+Session 开始时，若有新版本可下载，会显示一行 banner（每版本每 24 小时节流一次），`memesh doctor` 会报告升级目标版本与对应命令。
+
+---
+
 ## 贡献
 
 ```bash
diff --git a/README.zh-TW.md b/README.zh-TW.md
index 0924ef0d..6a5b4da3 100644
--- a/README.zh-TW.md
+++ b/README.zh-TW.md
@@ -16,6 +16,9 @@
 
 ---
 
+> [!IMPORTANT]
+> **持續開發中的專案** — 功能會持續更新，版本之間可能會有變動。遇到問題或想要新功能，請[開 issue](https://github.com/PCIRCLE-AI/memesh-llm-memory/issues)。
+
 ## 問題所在
 
 你的程式開發代理在每次對話之間就會忘記一切。每個架構決策、每個修復的臭蟲、每個失敗的測試、每個代價不菲的教訓，都得重新跟它解釋一遍。Claude Code 每次都從零開始，重新發現舊的限制條件，浪費寶貴的上下文在它本應已知的事情上。
@@ -404,6 +407,34 @@ memesh  # 開啟儀表板 → Settings 分頁
 
 ---
 
+## 升級
+
+Claude Code 的 plugin marketplace 在安裝時把版本釘住，**不會**自動更新。要拿到新版本：
+
+**方法 A — `/plugin` 介面**：先 uninstall `memesh@pcircle-memesh`，再重新安裝。Claude Code 會抓 marketplace 最新版。
+
+**方法 B — 一行指令**（不用點 UI、可重複執行）：
+
+```bash
+# 如果 plugin 已經是 v4.2.5 或更新，腳本已經內建：
+bash ~/.claude/plugins/cache/pcircle-memesh/memesh/<current-version>/scripts/upgrade-plugin.sh
+
+# 如果是 v4.2.5 之前的版本（也就是 v4.2.4 或 v4.2.3），
+# 腳本還沒在你的 plugin 裡，改用 npm-global 的副本：
+bash "$(npm prefix -g)/lib/node_modules/@pcircle/memesh/scripts/upgrade-plugin.sh"
+
+# （這假設你也跑過 `npm install -g @pcircle/memesh`。如果還沒，
+# 現在正好可以一起裝 — 參考上面「安裝路徑一覽」說明為什麼大部分人兩條路徑都裝。）
+```
+
+腳本會 fast-forward marketplace cache、把新版本放進 `~/.claude/plugins/cache/`、安裝 runtime deps，然後把 `installed_plugins.json` 重指向新版本。執行完請重啟 Claude Code 讓 MCP server 重連。
+
+**npm-global 安裝**（`npm install -g @pcircle/memesh`）可以直接 `memesh update` 自動更新。Source checkouts：`git pull && npm install && npm run build`。
+
+Session 開始時，有新版本可下載時會跳一行 banner（每版本每 24 小時節流一次），`memesh doctor` 會回報升級目標版本與對應指令。
+
+---
+
 ## 貢獻
 
 ```bash
diff --git a/tests/hooks/pre-bash-orchestration-nudge.test.ts b/tests/hooks/pre-bash-orchestration-nudge.test.ts
index 74a915a0..81ff3f02 100644
--- a/tests/hooks/pre-bash-orchestration-nudge.test.ts
+++ b/tests/hooks/pre-bash-orchestration-nudge.test.ts
@@ -40,6 +40,10 @@ describe('Feature: Pre-Bash Orchestration Nudge Hook', () => {
       input: jsonInput,
       env: {
         ...process.env,
+        // Point MEMESH_DIR at the isolated testDir so readHookConfig() in
+        // _shared.js doesn't pick up the developer's real
+        // ~/.memesh/config.json (which may have enableAgenticOrchestration: true).
+        MEMESH_DIR: testDir,
         MEMESH_DB_PATH: dbPath,
         MEMESH_ENABLE_AGENTIC_ORCHESTRATION: '1',
         ...extraEnv,
@@ -56,7 +60,14 @@ describe('Feature: Pre-Bash Orchestration Nudge Hook', () => {
     const dbPath = path.join(testDir, 'knowledge-graph.db');
     const jsonInput = JSON.stringify({ tool_input: { command: 'npm test' } });
     // Build a clean env that explicitly does NOT carry the opt-in flag.
-    const cleanEnv: Record<string, string> = { ...process.env, MEMESH_DB_PATH: dbPath };
+    // MEMESH_DIR pins config lookup to testDir so a developer's real
+    // ~/.memesh/config.json with enableAgenticOrchestration:true can't
+    // smuggle the gate open via readHookConfig().
+    const cleanEnv: Record<string, string> = {
+      ...process.env,
+      MEMESH_DIR: testDir,
+      MEMESH_DB_PATH: dbPath,
+    };
     delete cleanEnv.MEMESH_ENABLE_AGENTIC_ORCHESTRATION;
     let out = '';
     try {
diff --git a/tests/tools.test.ts b/tests/tools.test.ts
index 2726170b..4d3856ad 100644
--- a/tests/tools.test.ts
+++ b/tests/tools.test.ts
@@ -86,15 +86,21 @@ describe('remember', () => {
       relations: [{ to: 'auth-v2', type: 'supersedes' }],
     });
 
-    // auth-v2 should be auto-archived
+    // auth-v2 should be auto-archived — must NOT appear in default recall.
+    // (We don't assert []: if ONNX embeddings are loaded, recallEnhanced
+    // can supplement with vector hits, e.g. surfacing the related auth-v3.
+    // The behavioural guarantee here is "archived rows stay hidden", not
+    // "no results at all".)
     const recallOld = await handleTool('recall', { query: 'JWT' });
-    expect(JSON.parse(recallOld.content[0].text)).toEqual([]);
+    const oldNames = JSON.parse(recallOld.content[0].text).map((e: any) => e.name);
+    expect(oldNames).not.toContain('auth-v2');
 
-    // auth-v3 should be active
+    // auth-v3 should be active and surfaced by an OAuth query.
     const recallNew = await handleTool('recall', { query: 'OAuth' });
     const data = JSON.parse(recallNew.content[0].text);
-    expect(data).toHaveLength(1);
-    expect(data[0].name).toBe('auth-v3');
+    expect(data.length).toBeGreaterThanOrEqual(1);
+    expect(data.map((e: any) => e.name)).toContain('auth-v3');
+    expect(data.map((e: any) => e.name)).not.toContain('auth-v2');
 
     // Both visible with include_archived
     const recallAll = await handleTool('recall', { include_archived: true });
diff --git a/tests/transports/http.test.ts b/tests/transports/http.test.ts
index cdc35865..9e223e09 100644
--- a/tests/transports/http.test.ts
+++ b/tests/transports/http.test.ts
@@ -118,10 +118,19 @@ describe('HTTP Transport: POST /v1/recall', () => {
   });
 
   it('returns array (possibly empty) for no-match query', async () => {
+    // Recall supplements FTS5 with sqlite-vec when ONNX embeddings are
+    // available, so a query that misses FTS5 can still surface near-neighbour
+    // entities under the MAX_VECTOR_DISTANCE threshold. Asserting toHaveLength(0)
+    // is brittle in that path — the API contract here is "always return a
+    // valid JSON array, never a 500" and a generous upper bound on count.
     const res = await req('POST', '/v1/recall', { query: 'no-match-xyz-999' });
     expect(res.status).toBe(200);
     expect(Array.isArray(res.body.data)).toBe(true);
-    expect(res.body.data).toHaveLength(0);
+    expect(res.body.data.length).toBeLessThanOrEqual(20);
+    for (const e of res.body.data) {
+      expect(typeof e.name).toBe('string');
+      expect(typeof e.type).toBe('string');
+    }
   });
 
   it('lists entities when no query provided', async () => {