openmoneta-dev-kit 1.11.1 → 1.13.0

package/README.md

@@ -2,7 +2,7 @@
 
 > Biến **Cursor IDE / OpenCode** thành một **team developer hoàn chỉnh** với quy trình 6 bước (Lean Mode), adaptive planning, hooks enforcement, token-aware doc routing và sub-agents on-demand.
 
-[![version](https://img.shields.io/badge/version-1.9.0-blue.svg)](./VERSION)
+[![version](https://img.shields.io/badge/version-1.12.0-blue.svg)](./VERSION)
 [![docs](https://img.shields.io/badge/docs-Vietnamese-green.svg)](./docs/INDEX.md)
 [![platform](https://img.shields.io/badge/platform-macOS%20|%20Linux%20|%20Windows-lightgrey.svg)]()
 [![npm](https://img.shields.io/npm/v/openmoneta-dev-kit)](https://www.npmjs.com/package/openmoneta-dev-kit)
@@ -41,6 +41,7 @@ openmoneta init
 openmoneta update              # global + sync project hiện tại
 openmoneta update --yes        # auto-sync, skip nếu đã latest
 openmoneta check               # chỉ kiểm tra version mới
+openmoneta docs                # audit module README thiếu/lỗi thời + sync INDEX
 ```
 
 ## Cài đặt thủ công (git clone)
@@ -54,9 +55,10 @@ bash ~/OpenMoneta-Dev-Kit/install.sh
 
 ## Có gì trong này?
 
-- **10 skills** (4 core + 1 core conditional + 5 on-demand) — phân tích yêu cầu, thiết kế module, plan, systematic debugging, safe push, test, security
+- **11 skills** (4 core + 1 core conditional + 6 on-demand) — phân tích yêu cầu, thiết kế module, plan, systematic debugging, safe push, test, security, bảo trì docs
+- **`openmoneta docs`** — audit module README thiếu/lỗi thời (stale) + skill `docs-maintenance` backfill docs cho dự án cũ
 - **4 sub-agents** — 1 core + 3 on-demand (security-auditor, qa-autonomous, ui-tester)
-- **4 hooks + plugin** — enforce token-aware reading, adaptive plan scope
+- **4 hooks + plugin** — enforce token-aware reading, adaptive plan scope, và verify cuối phiên (module README + close plan); OpenCode đạt parity qua plugin guard `session.idle`
 - **Token Routing** — bảng map keyword → module giúp AI giảm 70-90% token đọc
 - **npm package** — `npm install -g openmoneta-dev-kit`, không cần git, không cần clone
 - **Auto-update check** — notify khi có version mới (cache 24h)

package/VERSION

@@ -1 +1 @@
-1.11.1
+1.13.0

package/hooks/inject-process-context.sh

@@ -10,12 +10,30 @@ set -euo pipefail
 
 INPUT_JSON=$(cat 2>/dev/null || echo '{}')
 
+# Auto-register project vào Cursor registry (seed cho `update --all-projects`).
+# Im lặng. Chỉ append khi: workspace có docs/INDEX.md, Cursor install home đã cài,
+# và path chưa có trong registry (dedup, chuẩn hoá pwd -P).
+register_project_cursor() {
+  local ws="$1"
+  [[ -n "$ws" && -f "$ws/docs/INDEX.md" ]] || return 0
+  [[ -f "$HOME/.cursor/.openmoneta-version" ]] || return 0
+  local reg="$HOME/.cursor/.openmoneta-projects"
+  local abs
+  abs="$(cd "$ws" 2>/dev/null && pwd -P)" || return 0
+  [[ -n "$abs" ]] || return 0
+  if [[ -f "$reg" ]] && grep -qFx "$abs" "$reg" 2>/dev/null; then
+    return 0
+  fi
+  echo "$abs" >> "$reg" 2>/dev/null || true
+}
+
 # Reset docs-index marker mỗi session (force re-read INDEX.md)
 if command -v jq >/dev/null 2>&1; then
   WORKSPACE_FROM_INPUT=$(echo "$INPUT_JSON" | jq -r '.workspace_roots[0] // ""' 2>/dev/null || echo "")
   if [[ -n "$WORKSPACE_FROM_INPUT" && -d "$WORKSPACE_FROM_INPUT/.cursor" ]]; then
     rm -f "$WORKSPACE_FROM_INPUT/.cursor/.docs-index-read" 2>/dev/null || true
   fi
+  register_project_cursor "$WORKSPACE_FROM_INPUT" 2>/dev/null || true
 fi
 
 # === Summary 6 bước (~45 dòng, ~650 tokens) ===
@@ -44,7 +62,7 @@ SUMMARY='# OpenMoneta Dev Kit v1.7.0 — Quy trình 6 bước (Adaptive Planning
 - `security-auditor`, `qa-autonomous`, `ui-tester` — **ON-DEMAND ONLY** (chỉ khi user yêu cầu explicit).
 
 ## Skills on-demand (KHÔNG tự trigger)
-`security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop` — chỉ kích hoạt khi user yêu cầu rõ ("audit security X", "viết test cho Y", "Playwright UI test Z").
+`security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop`, `docs-maintenance` — chỉ kích hoạt khi user yêu cầu rõ ("audit security X", "viết test cho Y", "Playwright UI test Z", "tạo/bảo trì docs dự án cũ").
 
 ## Skill core conditional
 `safe-push` — bắt buộc khi user yêu cầu push/đẩy code để tránh đè code người khác trong repo nhiều contributor.

package/opencode/AGENTS.md.tpl

@@ -29,6 +29,7 @@
 - OpenCode đọc global rules từ `~/.config/opencode/AGENTS.md`.
 - OpenCode đọc project rules từ `AGENTS.md` ở project root. Project rules là source of truth cho từng repo.
 - OpenMoneta skills được cài vào `~/.config/opencode/skills/*/SKILL.md` và agent nên load bằng skill tool khi cần.
+- **Bảo trì doc dự án cũ** (ON-DEMAND): khi user yêu cầu tạo/refresh docs còn thiếu hoặc lỗi thời, chạy `bash ~/.config/opencode/scripts/docs-audit.sh` để soi rồi load skill `docs-maintenance` (backfill MISSING + refresh STALE + sync `docs/INDEX.md`).
 - OpenMoneta subagents được cài vào `~/.config/opencode/agents/`.
 - OpenCode plugin guard trong `~/.config/opencode/plugins/openmoneta-guard.ts` enforce workflow tương đương Cursor hooks: `tool.execute.before` (docs-first + plan gate), `tool.execute.after` (track changes), và `event:session.idle` (verify B2/B5: module README + close plan, re-prompt nhắc hoàn tất với loop guard ≤4 lần).
 

package/opencode/plugins/openmoneta-guard.ts

@@ -400,6 +400,33 @@ function clearVerifyLoop(root: string) {
   fs.rmSync(path.join(root, ".cursor", ".openmoneta-verify-loop.json"), { force: true })
 }
 
+// Auto-register project vào OpenCode registry (seed cho `update --all-projects`).
+// Im lặng + try/catch — seed không được phép làm fail guard. Chỉ append khi:
+// project có docs/INDEX.md, OpenCode install home đã cài, path chưa có trong registry.
+function registerProjectOpenCode(root: string) {
+  try {
+    if (!fs.existsSync(path.join(root, "docs", "INDEX.md"))) return
+    const home = process.env.HOME || process.env.USERPROFILE || ""
+    const xdg = process.env.XDG_CONFIG_HOME || path.join(home, ".config")
+    const ocHome = path.join(xdg, "opencode")
+    if (!fs.existsSync(path.join(ocHome, ".openmoneta-version"))) return
+    const reg = path.join(ocHome, ".openmoneta-projects")
+    const abs = fs.realpathSync(root)
+    let lines: string[] = []
+    if (fs.existsSync(reg)) {
+      lines = fs
+        .readFileSync(reg, "utf8")
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean)
+    }
+    if (lines.includes(abs)) return
+    fs.appendFileSync(reg, `${abs}\n`)
+  } catch {
+    // im lặng
+  }
+}
+
 type SessionPromptClient = {
   session?: {
     prompt?: (input: {
@@ -434,7 +461,7 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
       {
         loaded_at: new Date().toISOString(),
         root,
-        version: "1.11.0",
+        version: "1.13.0",
         load_count: globalState[globalKey],
       },
       null,
@@ -442,6 +469,9 @@ export const OpenMonetaGuard = async (ctx: GuardContext) => {
     )}\n`,
   )
 
+  // Seed project vào OpenCode registry để `update --all-projects` thấy project này.
+  registerProjectOpenCode(root)
+
   // OpenCode does not have Cursor's sessionStart hook, so reset the docs-first
   // marker when the plugin is loaded for a new OpenCode process/session.
   if (fs.existsSync(marker)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openmoneta-dev-kit",
-  "version": "1.11.1",
+  "version": "1.13.0",
   "description": "OpenMoneta Dev Kit — Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh với quy trình 6 bước, adaptive planning, hooks enforcement, và token-aware doc routing",
   "keywords": [
     "cursor",

package/scripts/docs-audit.sh

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# docs-audit.sh — Quét module trong project hiện tại và đối chiếu với docs/modules/<slug>/README.md.
+#
+# Mục đích: phát hiện module thiếu doc (MISSING), doc lỗi thời so với code (STALE),
+# và doc/INDEX trỏ tới module không còn tồn tại (GHOST). Deterministic, không sửa file.
+#
+# Usage (chạy ở thư mục gốc project):
+#   bash docs-audit.sh                # report bảng (mặc định)
+#   bash docs-audit.sh --report       # như trên
+#   bash docs-audit.sh --worklist     # TSV: <slug>\t<docsPath>\t<sourcePath>\t<missing|stale|ok>
+#   bash docs-audit.sh --validate     # liệt kê GHOST (doc trỏ source/module không tồn tại)
+#
+# Stale detection: so commit mới nhất của source vs README (git); fallback mtime filesystem.
+
+set -uo pipefail
+
+MODE="report"
+case "${1:-}" in
+  --worklist) MODE="worklist" ;;
+  --validate) MODE="validate" ;;
+  --report|"") MODE="report" ;;
+  *) echo "[!] Mode không hợp lệ: $1 (dùng --report|--worklist|--validate)" >&2; exit 2 ;;
+esac
+
+GIT_OK=0
+if command -v git >/dev/null 2>&1 && git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  GIT_OK=1
+fi
+
+file_mtime() { stat -c %Y "$1" 2>/dev/null || stat -f %m "$1" 2>/dev/null || echo 0; }
+
+newest_mtime() {
+  local target="$1" newest=0 m
+  while IFS= read -r f; do
+    m=$(file_mtime "$f")
+    [[ "$m" -gt "$newest" ]] && newest=$m
+  done < <(find "$target" -type f 2>/dev/null)
+  echo "$newest"
+}
+
+git_last_commit() { git log -1 --format=%ct -- "$1" 2>/dev/null || echo ""; }
+
+# In status missing|stale|ok cho 1 module
+status_for() {
+  local readme="$1" src="$2" tr ts
+  if [[ ! -f "$readme" ]]; then echo "missing"; return; fi
+  if [[ "$GIT_OK" -eq 1 ]]; then
+    tr=$(git_last_commit "$readme")
+    ts=$(git_last_commit "$src")
+  fi
+  if [[ -z "${tr:-}" || -z "${ts:-}" ]]; then
+    tr=$(file_mtime "$readme")
+    ts=$(newest_mtime "$src")
+  fi
+  if [[ "${ts:-0}" -gt "${tr:-0}" ]]; then echo "stale"; else echo "ok"; fi
+}
+
+# Liệt kê module trong filesystem → "<slug>|<docsPath>|<sourcePath>"
+collect_modules() {
+  local d n e
+  if [[ -d apps ]]; then
+    for d in apps/*/; do
+      [[ -d "$d" ]] || continue; n=$(basename "$d"); [[ "$n" == .* ]] && continue
+      echo "apps-$n|docs/modules/apps-$n|apps/$n"
+    done
+  fi
+  if [[ -d packages ]]; then
+    for d in packages/*/; do
+      [[ -d "$d" ]] || continue; n=$(basename "$d"); [[ "$n" == .* ]] && continue
+      echo "packages-$n|docs/modules/packages-$n|packages/$n"
+    done
+  fi
+  if [[ -d src/modules ]]; then
+    for d in src/modules/*/; do
+      [[ -d "$d" ]] || continue; n=$(basename "$d"); [[ "$n" == .* ]] && continue
+      echo "$n|docs/modules/$n|src/modules/$n"
+    done
+  elif [[ -d src ]]; then
+    for e in src/*; do
+      [[ -e "$e" ]] || continue; n=$(basename "$e")
+      [[ "$n" == .* ]] && continue
+      [[ "$n" == "modules" ]] && continue
+      echo "$n|docs/modules/$n|$e"
+    done
+  fi
+}
+
+in_index() {
+  [[ -f docs/INDEX.md ]] || { echo "no"; return; }
+  if grep -q "modules/$1" docs/INDEX.md 2>/dev/null; then echo "yes"; else echo "no"; fi
+}
+
+# Map slug docs → candidate source path (cho validate/ghost)
+slug_to_source() {
+  local slug="$1"
+  if [[ "$slug" == apps-* ]]; then echo "apps/${slug#apps-}"
+  elif [[ "$slug" == packages-* ]]; then echo "packages/${slug#packages-}"
+  elif [[ -e "src/modules/$slug" ]]; then echo "src/modules/$slug"
+  else echo "src/$slug"
+  fi
+}
+
+MODULES=$(collect_modules | sort -u)
+
+# ---------- MODE: validate (ghost) ----------
+if [[ "$MODE" == "validate" ]]; then
+  ghosts=0
+  if [[ -d docs/modules ]]; then
+    for d in docs/modules/*/; do
+      [[ -d "$d" ]] || continue
+      slug=$(basename "$d")
+      src=$(slug_to_source "$slug")
+      if [[ ! -e "$src" ]]; then
+        echo "GHOST  docs/modules/$slug → source '$src' không tồn tại"
+        ghosts=$((ghosts+1))
+      fi
+    done
+  fi
+  # INDEX trỏ tới docs/modules/<x> không tồn tại
+  if [[ -f docs/INDEX.md ]]; then
+    while IFS= read -r ref; do
+      slug="${ref#modules/}"; slug="${slug%%/*}"
+      [[ -z "$slug" ]] && continue
+      if [[ ! -d "docs/modules/$slug" ]]; then
+        echo "GHOST  docs/INDEX.md → 'modules/$slug' nhưng thư mục docs/modules/$slug không tồn tại"
+        ghosts=$((ghosts+1))
+      fi
+    done < <(grep -oE 'modules/[A-Za-z0-9._-]+' docs/INDEX.md 2>/dev/null | sort -u)
+  fi
+  if [[ "$ghosts" -eq 0 ]]; then
+    echo "✓ Không phát hiện GHOST doc (mọi docs/modules + tham chiếu INDEX đều có source)."
+  else
+    echo ""
+    echo "Tổng: $ghosts cảnh báo GHOST."
+  fi
+  exit 0
+fi
+
+# ---------- MODE: worklist (TSV cho skill) ----------
+if [[ "$MODE" == "worklist" ]]; then
+  [[ -z "$MODULES" ]] && exit 0
+  while IFS='|' read -r slug docs src; do
+    [[ -z "$slug" ]] && continue
+    st=$(status_for "$docs/README.md" "$src")
+    printf '%s\t%s\t%s\t%s\n' "$slug" "$docs" "$src" "$st"
+  done <<< "$MODULES"
+  exit 0
+fi
+
+# ---------- MODE: report (mặc định) ----------
+echo ""
+echo "  Module doc audit — $(pwd)"
+echo "  ──────────────────────────────────────────────────────────────"
+if [[ -z "$MODULES" ]]; then
+  echo "  0 module (không thấy apps/ packages/ src/). Không có gì để audit."
+  echo ""
+  exit 0
+fi
+
+printf "  %-22s %-22s %-8s %-7s %-8s\n" "slug" "source" "README" "INDEX" "status"
+printf "  %-22s %-22s %-8s %-7s %-8s\n" "----" "------" "------" "-----" "------"
+
+n_missing=0; n_stale=0; n_ok=0; n_noindex=0
+while IFS='|' read -r slug docs src; do
+  [[ -z "$slug" ]] && continue
+  st=$(status_for "$docs/README.md" "$src")
+  idx=$(in_index "$slug")
+  rd="ok"; [[ "$st" == "missing" ]] && rd="MISSING"
+  printf "  %-22s %-22s %-8s %-7s %-8s\n" "$slug" "$src" "$rd" "$idx" "$st"
+  case "$st" in
+    missing) n_missing=$((n_missing+1)) ;;
+    stale)   n_stale=$((n_stale+1)) ;;
+    ok)      n_ok=$((n_ok+1)) ;;
+  esac
+  [[ "$idx" == "no" ]] && n_noindex=$((n_noindex+1))
+done <<< "$MODULES"
+
+echo "  ──────────────────────────────────────────────────────────────"
+echo "  Tổng: $((n_missing+n_stale+n_ok)) module · $n_missing thiếu README · $n_stale lỗi thời (stale) · $n_noindex chưa có trong INDEX"
+if [[ "$n_missing" -gt 0 || "$n_stale" -gt 0 ]]; then
+  echo ""
+  echo "  → Để SINH/CẬP NHẬT nội dung: mở Cursor/OpenCode và yêu cầu chạy skill 'docs-maintenance'."
+fi
+echo ""
+exit 0

package/scripts/init-project.sh

@@ -398,6 +398,25 @@ else
   fi
 fi
 
+# === Bước 4: Đăng ký project vào registry của mỗi install home đang tồn tại ===
+# Registry gắn với install home CỐ ĐỊNH (qua marker .openmoneta-version), KHÔNG dùng
+# $OPENMONETA_HOME (vì khi chạy từ repo kit, biến này trỏ về repo dir).
+register_in_home() {
+  local home="$1"
+  [[ -f "$home/.openmoneta-version" ]] || return 0
+  local reg="$home/.openmoneta-projects"
+  local abs
+  abs="$(cd "$PROJECT_DIR" && pwd -P)"
+  if [[ -f "$reg" ]] && grep -qFx "$abs" "$reg"; then
+    return 0
+  fi
+  echo "$abs" >> "$reg"
+  CREATED+=("registry: $reg ← $abs")
+}
+
+register_in_home "$HOME/.cursor"
+register_in_home "${XDG_CONFIG_HOME:-$HOME/.config}/opencode"
+
 # === Báo cáo ===
 echo ""
 echo "================================================"

package/skills/docs-maintenance/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: docs-maintenance
+description: "ON-DEMAND ONLY: dùng khi user yêu cầu tạo docs còn thiếu / backfill module README / refresh docs lỗi thời / audit docs / bảo trì docs dự án cũ. KHÔNG tự trigger trong quy trình bình thường."
+---
+
+# Docs Maintenance
+
+Quét cả repo một lượt để **backfill module README còn thiếu** và **refresh README đã lỗi thời** so với code, rồi **đồng bộ `docs/INDEX.md`** (Modules hiện có + Token Routing).
+
+Dùng khi onboard/bảo trì **dự án cũ** đã tích lũy nợ doc (code đụng nhiều nhưng README không được cập nhật), hoặc khi user yêu cầu rõ. Đây là phiên bản "chạy hàng loạt cho cả repo" của skill `module-architect` (vốn chạy từng module/session).
+
+## Iron Law
+
+```
+CHỈ VIẾT NHỮNG GÌ VERIFY ĐƯỢC TRONG CODE. KHÔNG BỊA API / PATH / DEPENDENCY.
+```
+
+Stale docs còn tệ hơn không có docs — session sau AI đọc sai, làm sai. Mỗi dòng trong README phải truy về một symbol/import có thật trong source. Không chắc → mô tả mức ý định cao, KHÔNG bịa signature.
+
+## Ranh giới (Lean — KHÔNG làm gì)
+
+- **KHÔNG** sinh bộ doc tổng quan kiểu khác (`system-architecture.md`, `project-roadmap.md`, `codebase-summary.md`...). Mô hình OM là **per-module README 3 sections + `docs/INDEX.md`**, đủ để navigate token-aware.
+- **KHÔNG** sửa code. Chỉ ghi file dưới `docs/`.
+- **KHÔNG** viết lại từ đầu README còn đúng — chỉ sửa phần lệch.
+- Cấu trúc README 3 sections theo skill [`module-architect`](../module-architect/SKILL.md) — KHÔNG lặp lại spec ở đây, đọc nó để biết format chuẩn.
+
+## 3 Modes
+
+| Mode | Xử lý | Ghi file? |
+|---|---|---|
+| `audit` | Report: liệt kê module MISSING / STALE / GHOST | Không |
+| `init` | **Tạo MISSING + refresh STALE** (full backfill) | Có |
+| `sync` | Chỉ refresh STALE | Có |
+
+> User nói "tạo docs thiếu" / "bảo trì docs cũ" → mặc định `init`. Nói "chỉ xem thiếu gì" → `audit`. Nói "cập nhật doc cho khớp code" → `sync`.
+
+## Phân loại trạng thái module
+
+- **MISSING**: module có source nhưng KHÔNG có `docs/modules/<slug>/README.md`.
+- **STALE**: README có rồi nhưng code module đổi SAU lần doc update cuối (so commit git source vs README; fallback mtime). Heuristic → phải đọc xác nhận trước khi sửa.
+- **GHOST**: `docs/modules/<slug>/` hoặc dòng INDEX trỏ tới source/module không còn tồn tại.
+
+## Workflow
+
+### 1. Lấy danh sách + soi ghost (deterministic)
+
+```bash
+bash ~/.cursor/scripts/docs-audit.sh --worklist    # MISSING/STALE/ok (TSV: slug\tdocs\tsource\tstatus)
+bash ~/.cursor/scripts/docs-audit.sh --validate     # liệt kê GHOST (doc/INDEX trỏ source/module đã mất)
+```
+
+(OpenCode: `~/.config/opencode/scripts/docs-audit.sh`.) **BẮT BUỘC chạy cả `--validate`** ở mọi mode để không bỏ sót ghost. Mode `audit` in cả 2 kết quả rồi dừng, không qua các bước tạo/sửa dưới.
+
+### 2. (Repo lớn) đọc song song
+
+Nếu nhiều module MISSING/STALE → delegate subagent `explore` đọc song song từng cụm module và trả summary (Public API thật + imports). Repo nhỏ → đọc trực tiếp.
+
+### 3. MISSING → tạo mới
+
+Cho mỗi module status `missing`:
+
+1. Đọc source thật (`sourcePath`) — entry point + các export.
+2. **Verify trước khi viết**: grep tên hàm/class/route trong source để chắc nó tồn tại + đúng signature.
+3. Viết `docs/modules/<slug>/README.md` 3 sections (Trách nhiệm + Public API + Dependencies) theo `module-architect`.
+
+### 4. STALE → refresh (không viết lại từ đầu)
+
+Cho mỗi module status `stale`:
+
+1. Đọc source + README cũ.
+2. Đối chiếu **Public API**: export mới chưa có trong README → thêm; symbol đã xóa/đổi signature → sửa/xóa.
+3. Đối chiếu **Dependencies**: import mới → thêm; import đã bỏ → xóa.
+4. Giữ nguyên phần còn đúng. Chỉ sửa phần lệch.
+
+### 5. Sync `docs/INDEX.md`
+
+- Module mới → thêm dòng vào bảng "Modules hiện có" + **3-5 keyword (VN+EN)** vào bảng "Token Routing" (bắt buộc, để hook docs-first + token-aware reading hoạt động).
+- **GHOST** (từ `--validate` ở Bước 1) → LIỆT KÊ rõ từng ghost cho user. **KHÔNG tự xóa** — map slug→source là heuristic, có thể là module vừa đổi tên/di chuyển. Hỏi user bằng `AskQuestion` (xóa doc/dòng INDEX, hay map lại sang source mới); chỉ thao tác sau khi user xác nhận từng cái.
+
+### 6. Report cuối
+
+In tóm tắt: `created / updated / skipped` + cảnh báo (module không verify được, ghost). Gợi ý chạy lại `openmoneta docs --validate` để xác nhận sạch.
+
+## Bảng Rationalization (cái cớ → sự thật)
+
+| Cái cớ | Sự thật |
+|---|---|
+| "README cũ chắc vẫn đúng, khỏi đọc source" | Stale là lý do bạn được gọi. Phải đọc source verify, không tin README cũ. |
+| "Đoán signature cho nhanh" | Bịa API = doc sai = tệ hơn không có. Grep verify hoặc bỏ. |
+| "Viết lại cả README cho gọn" | Phá nội dung đang đúng + tốn token. Chỉ sửa phần lệch. |
+| "Thêm doc tổng quan cho đầy đủ" | Trái Lean. OM chỉ module README + INDEX. |
+| "Module mới khỏi thêm Token Routing" | Không có keyword → AI không tìm thấy module → đọc loạn. Bắt buộc thêm. |
+
+## Red Flags — DỪNG
+
+- Đang định viết `funcName()` mà chưa thấy nó trong source.
+- Đang refresh STALE mà chưa mở source, chỉ sửa theo trí nhớ.
+- Đang định sinh `system-architecture.md` / `codebase-summary.md`.
+- Đang định xóa GHOST mà chưa hỏi user.
+- Tạo module mới trong INDEX nhưng quên Token Routing keyword.
+
+## Examples
+
+- User: "Dự án này nhiều module thiếu docs, tạo giúp" → `init`: chạy worklist → tạo mọi MISSING + refresh STALE → sync INDEX → report.
+- User: "Doc còn khớp code không?" → `audit`: chỉ report.
+- User: "Cập nhật doc 3 module vừa refactor" → `sync` (giới hạn các slug đó).

package/src/cli.js

@@ -19,6 +19,8 @@ async function cli(pkgRoot) {
     case "check":
     case "--check":
       return require("./commands/check").run(args)
+    case "docs":
+      return require("./commands/docs").run(args)
     case "--version":
     case "-v":
       console.log(`v${getLocalVersion() || "unknown"}`)
@@ -52,6 +54,9 @@ Biến Cursor IDE / OpenCode thành team developer hoàn chỉnh.
 
   openmoneta check                Kiểm tra version mới nhất từ npm
 
+  openmoneta docs                 Audit module README (thiếu/lỗi thời) + sync INDEX
+  openmoneta docs --validate      Phát hiện doc trỏ module/source không tồn tại (ghost)
+
   openmoneta uninstall            Gỡ cài đặt
 
 Trạng thái: Cursor: ${isInstalled("cursor") ? "đã cài" : "chưa cài"} | OpenCode: ${isInstalled("opencode") ? "đã cài" : "chưa cài"}

package/src/commands/docs.js

@@ -0,0 +1,37 @@
+const { execSync } = require("node:child_process")
+const path = require("node:path")
+const fs = require("node:fs")
+const { getPkgRoot, isWindows } = require("../lib/paths")
+
+async function run(args) {
+  const validate = args.includes("--validate")
+  const worklist = args.includes("--worklist")
+
+  const pkgRoot = getPkgRoot()
+  const script = path.join(pkgRoot, "scripts", "docs-audit.sh")
+  const cwd = process.cwd()
+
+  if (!fs.existsSync(script)) {
+    console.error(`\n  ❌ Không tìm thấy script: ${script}`)
+    process.exit(1)
+  }
+
+  let mode = "--report"
+  if (validate) mode = "--validate"
+  else if (worklist) mode = "--worklist"
+
+  try {
+    execSync(`bash "${script}" ${mode}`, {
+      stdio: "inherit",
+      cwd,
+      shell: isWindows() ? true : undefined,
+    })
+  } catch (err) {
+    if (isWindows()) {
+      console.log(`\n  ⚠ Cần Git Bash để chạy audit trên Windows: https://git-scm.com/download/win`)
+    }
+    process.exit(typeof err.status === "number" ? err.status : 1)
+  }
+}
+
+module.exports = { run }

package/src/commands/update.js

@@ -1,12 +1,180 @@
 const { execSync } = require("node:child_process")
 const path = require("node:path")
-const { getPkgRoot, isInstalled, isWindows, runScript } = require("../lib/paths")
+const fs = require("node:fs")
+const { getPkgRoot, isInstalled, isWindows, runScript, getProjectRegistry } = require("../lib/paths")
 const { getLocalVersion, getLatestVersion } = require("../lib/version")
 
+function isOpenmonetaProject(dir) {
+  try {
+    fs.accessSync(path.join(dir, "docs", "INDEX.md"))
+    return true
+  } catch {
+    return false
+  }
+}
+
+function readRegistry() {
+  const seen = new Set()
+  for (const target of ["cursor", "opencode"]) {
+    let content
+    try {
+      content = fs.readFileSync(getProjectRegistry(target), "utf8")
+    } catch {
+      continue
+    }
+    for (const line of content.split("\n")) {
+      const p = line.trim()
+      if (!p) continue
+      try {
+        seen.add(fs.realpathSync(p))
+      } catch {
+        // path không còn tồn tại → bỏ qua, prune sẽ dọn
+      }
+    }
+  }
+  return [...seen]
+}
+
+function pruneRegistry() {
+  let pruned = 0
+  for (const target of ["cursor", "opencode"]) {
+    const reg = getProjectRegistry(target)
+    let content
+    try {
+      content = fs.readFileSync(reg, "utf8")
+    } catch {
+      continue
+    }
+    const kept = []
+    for (const line of content.split("\n")) {
+      const p = line.trim()
+      if (!p) continue
+      if (isOpenmonetaProject(p)) kept.push(p)
+      else pruned++
+    }
+    fs.writeFileSync(reg, kept.length ? kept.join("\n") + "\n" : "")
+  }
+  return pruned
+}
+
+const SCAN_PRUNE_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "Library",
+  ".Trash",
+  ".cache",
+  ".npm",
+  ".cargo",
+  ".gradle",
+  ".venv",
+  "dist",
+  "build",
+])
+
+function findProjects(root, maxDepth) {
+  const out = []
+  function walk(dir, depth) {
+    if (depth > maxDepth) return
+    if (isOpenmonetaProject(dir)) {
+      try {
+        fs.accessSync(path.join(dir, "AGENTS.md"))
+        out.push(dir)
+      } catch {
+        // thiếu AGENTS.md → không tính là OM project khi scan
+      }
+    }
+    let entries
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue
+      if (SCAN_PRUNE_DIRS.has(e.name) || e.name.startsWith(".")) continue
+      walk(path.join(dir, e.name), depth + 1)
+    }
+  }
+  walk(root, 0)
+  return out
+}
+
+function scanSeed(root, pkgRoot) {
+  let absRoot
+  try {
+    absRoot = fs.realpathSync(root)
+  } catch {
+    console.log(`  [!] Scan root không tồn tại: ${root}`)
+    return
+  }
+  const targets = ["cursor", "opencode"].filter((t) => isInstalled(t))
+  if (targets.length === 0) {
+    console.log(`  [!] Chưa có install home nào để seed registry.`)
+    return
+  }
+  let kitRoot
+  try {
+    kitRoot = fs.realpathSync(pkgRoot)
+  } catch {
+    kitRoot = pkgRoot
+  }
+  const uniq = [
+    ...new Set(
+      findProjects(absRoot, 5)
+        .map((p) => {
+          try {
+            return fs.realpathSync(p)
+          } catch {
+            return p
+          }
+        })
+        .filter((p) => p !== kitRoot)
+    ),
+  ]
+  let seeded = 0
+  for (const t of targets) {
+    const reg = getProjectRegistry(t)
+    let existing = new Set()
+    try {
+      existing = new Set(
+        fs
+          .readFileSync(reg, "utf8")
+          .split("\n")
+          .map((l) => l.trim())
+          .filter(Boolean)
+      )
+    } catch {
+      // registry chưa tồn tại → tạo mới khi append
+    }
+    const toAdd = uniq.filter((p) => !existing.has(p))
+    if (toAdd.length) {
+      fs.appendFileSync(reg, toAdd.map((p) => `${p}\n`).join(""))
+      seeded += toAdd.length
+    }
+  }
+  console.log(`  Scan: thấy ${uniq.length} OM project, seed ${seeded} entry mới.`)
+}
+
+function syncProject(initScript, dir) {
+  if (isWindows()) {
+    execSync(`bash "${initScript}" "${dir}"`, { stdio: "inherit", shell: true })
+  } else {
+    execSync(`bash "${initScript}" "${dir}"`, { stdio: "inherit" })
+  }
+}
+
 async function run(args) {
   const checkOnly = args.includes("--check")
   const autoYes = args.includes("--yes") || args.includes("-y")
   const skipProjects = args.includes("--skip-projects")
+  const scanIdx = args.indexOf("--scan")
+  const scan = scanIdx !== -1
+  let scanRoot = process.env.HOME || process.env.USERPROFILE || "."
+  if (scan) {
+    const next = args[scanIdx + 1]
+    if (next && !next.startsWith("-")) scanRoot = next
+  }
+  const allProjects = args.includes("--all-projects") || scan
   const force = args.includes("--force")
 
   const local = getLocalVersion()
@@ -76,24 +244,61 @@ async function run(args) {
   if (!skipProjects) {
     const initScript = path.join(pkgRoot, "scripts", "init-project.sh")
     const cwd = process.cwd()
-    const docsIndex = path.join(cwd, "docs", "INDEX.md")
 
-    try {
-      require("node:fs").accessSync(docsIndex)
-      console.log(`\n  ▶ Syncing project: ${path.basename(cwd)}`)
-      if (isWindows()) {
-        execSync(`bash "${initScript}" "${cwd}"`, { stdio: "inherit", shell: true })
-      } else {
-        execSync(`bash "${initScript}" "${cwd}"`, { stdio: "inherit" })
+    if (scan) {
+      console.log(`\n  ▶ --scan: dò OM project để seed registry...`)
+      scanSeed(scanRoot, pkgRoot)
+    }
+
+    if (allProjects) {
+      const pruned = pruneRegistry()
+      if (pruned > 0) console.log(`\n  ℹ Registry: prune ${pruned} entry chết.`)
+
+      const projects = readRegistry()
+      if (isOpenmonetaProject(cwd) && !projects.includes(fs.realpathSync(cwd))) {
+        projects.push(fs.realpathSync(cwd))
       }
-      console.log(`\n  ✅ Project synced.`)
-    } catch (err) {
-      if (isWindows()) {
-        console.log(`\n  ⚠ Không thể sync project (cần Git Bash). Cài tại: https://git-scm.com/download/win`)
-        console.log(`     Sau đó chạy thủ công: bash "${initScript}" "${cwd}"`)
+
+      if (projects.length === 0) {
+        console.log(`\n  ℹ Registry trống. Init project trước: openmoneta init`)
       } else {
-        console.log(`\n  ℹ Không phát hiện project OpenMoneta ở thư mục hiện tại.`)
-        console.log(`     Sync thủ công: openmoneta init`)
+        console.log(`\n  ▶ Syncing ${projects.length} project (registry)...`)
+        let ok = 0
+        let fail = 0
+        for (const dir of projects) {
+          try {
+            console.log(`\n  ▶ ${path.basename(dir)}  (${dir})`)
+            syncProject(initScript, dir)
+            ok++
+          } catch {
+            console.error(`  ⚠ Sync fail: ${dir}`)
+            fail++
+          }
+        }
+        console.log(`\n  ✅ Projects synced: ${ok}${fail ? `, failed: ${fail}` : ""}`)
+      }
+    } else {
+      try {
+        fs.accessSync(path.join(cwd, "docs", "INDEX.md"))
+        console.log(`\n  ▶ Syncing project: ${path.basename(cwd)}`)
+        syncProject(initScript, cwd)
+        console.log(`\n  ✅ Project synced.`)
+      } catch (err) {
+        if (isWindows()) {
+          console.log(`\n  ⚠ Không thể sync project (cần Git Bash). Cài tại: https://git-scm.com/download/win`)
+          console.log(`     Sau đó chạy thủ công: bash "${initScript}" "${cwd}"`)
+        } else {
+          console.log(`\n  ℹ Không phát hiện project OpenMoneta ở thư mục hiện tại.`)
+          console.log(`     Sync thủ công: openmoneta init`)
+        }
+      }
+
+      const others = readRegistry().filter(
+        (p) => isOpenmonetaProject(p) && !(isOpenmonetaProject(cwd) && p === fs.realpathSync(cwd))
+      )
+      if (others.length > 0) {
+        console.log(`\n  ℹ Có ${others.length} project khác trong registry chưa sync. Sync tất cả:`)
+        console.log(`     openmoneta update --all-projects`)
       }
     }
   }
@@ -101,4 +306,7 @@ async function run(args) {
   console.log(`\n  🎉 Hoàn tất. Restart Cursor/OpenCode để áp dụng.`)
 }
 
-module.exports = { run }
+module.exports = {
+  run,
+  _internal: { isOpenmonetaProject, readRegistry, pruneRegistry, findProjects, scanSeed },
+}

package/src/lib/paths.js

@@ -19,6 +19,11 @@ function versionFilePath(target) {
   return path.join(CURSOR_DIR, ".openmoneta-version")
 }
 
+function getProjectRegistry(target) {
+  if (target === "opencode") return path.join(OPENCODE_DIR, ".openmoneta-projects")
+  return path.join(CURSOR_DIR, ".openmoneta-projects")
+}
+
 function installedVersion(target) {
   try {
     return fs.readFileSync(versionFilePath(target), "utf8").trim()
@@ -52,6 +57,7 @@ module.exports = {
   OPENCODE_DIR,
   REPO_DIR,
   versionFilePath,
+  getProjectRegistry,
   installedVersion,
   isInstalled,
   isWindows,

package/templates/AGENTS.md.tpl

@@ -87,7 +87,7 @@
 
 **Core conditional**: `safe-push` (Bước 6 — chỉ khi user yêu cầu push).
 
-**On-demand (chỉ trigger khi user yêu cầu rõ)**: `security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop`.
+**On-demand (chỉ trigger khi user yêu cầu rõ)**: `security-checklist`, `test-strategy`, `automated-testing`, `auth-bypass-testing`, `ui-test-loop`, `docs-maintenance`.
 
 ## Hooks enforce
 

package/update.ps1

@@ -6,6 +6,8 @@
 #   .\update.ps1 -Yes -Force            # global + auto-sync, luôn cài lại
 #   .\update.ps1 -Check                 # chỉ check, không cài
 #   .\update.ps1 -Project C:\path       # global + sync thêm project chỉ định
+#   .\update.ps1 -AllProjects           # global + sync MỌI project trong registry
+#   .\update.ps1 -Scan [-ScanRoot path] # dò OM project (mặc định $HOME) → seed registry → sync all
 #   .\update.ps1 -SkipProjects          # global only (old behavior)
 
 param(
@@ -13,6 +15,9 @@ param(
     [switch]$Force,
     [switch]$Check,
     [switch]$SkipProjects,
+    [switch]$AllProjects,
+    [switch]$Scan,
+    [string]$ScanRoot,
     [string[]]$Project
 )
 
@@ -83,6 +88,88 @@ function Sync-Project {
     return $true
 }
 
+# Helper: registry files (gắn với install home cố định, không dùng OPENMONETA_HOME)
+function Get-RegistryFiles {
+    $cursorReg = Join-Path $env:USERPROFILE ".cursor\.openmoneta-projects"
+    $openCodeBase = if ($env:XDG_CONFIG_HOME) { "$env:XDG_CONFIG_HOME\opencode" } else { "$env:USERPROFILE\.config\opencode" }
+    $openCodeReg = Join-Path $openCodeBase ".openmoneta-projects"
+    return @($cursorReg, $openCodeReg)
+}
+
+# Helper: đọc registry (merge 2 home, dedup)
+function Read-Registry {
+    $seen = [System.Collections.Generic.HashSet[string]]::new()
+    foreach ($f in Get-RegistryFiles) {
+        if (-not (Test-Path $f)) { continue }
+        foreach ($line in (Get-Content $f)) {
+            $p = $line.Trim()
+            if (-not $p) { continue }
+            $abs = (Resolve-Path $p -ErrorAction SilentlyContinue).Path
+            if ($abs) { [void]$seen.Add($abs) }
+        }
+    }
+    return @($seen)
+}
+
+# Helper: prune entry chết khỏi registry
+function Invoke-PruneRegistry {
+    $pruned = 0
+    foreach ($f in Get-RegistryFiles) {
+        if (-not (Test-Path $f)) { continue }
+        $kept = @()
+        foreach ($line in (Get-Content $f)) {
+            $p = $line.Trim()
+            if (-not $p) { continue }
+            if (Test-OpenMonetaProject $p) { $kept += $p } else { $pruned++ }
+        }
+        Set-Content -Path $f -Value $kept
+    }
+    return $pruned
+}
+
+# Helper: scan tìm OM project (docs\INDEX.md + AGENTS.md) → seed registry mỗi home tồn tại
+function Invoke-ScanSeed {
+    $root = if ($ScanRoot) { $ScanRoot } else { $env:USERPROFILE }
+    $absRoot = (Resolve-Path $root -ErrorAction SilentlyContinue).Path
+    if (-not $absRoot) { Write-Host "  [!] Scan root không tồn tại: $root"; return }
+
+    $homes = @()
+    if (Test-Path (Join-Path $env:USERPROFILE ".cursor\.openmoneta-version")) {
+        $homes += (Join-Path $env:USERPROFILE ".cursor\.openmoneta-projects")
+    }
+    $ocBase = if ($env:XDG_CONFIG_HOME) { "$env:XDG_CONFIG_HOME\opencode" } else { "$env:USERPROFILE\.config\opencode" }
+    if (Test-Path (Join-Path $ocBase ".openmoneta-version")) {
+        $homes += (Join-Path $ocBase ".openmoneta-projects")
+    }
+    if ($homes.Count -eq 0) { Write-Host "  [!] Chưa có install home nào để seed registry."; return }
+
+    $prune = @('node_modules', '.git', 'Library', '.Trash', '.cache', '.npm', '.cargo', '.gradle', '.venv', 'dist', 'build')
+    Write-Host "  Scanning '$absRoot' (depth ~6)..."
+    $indexes = Get-ChildItem -Path $absRoot -Recurse -Depth 6 -Filter "INDEX.md" -File -ErrorAction SilentlyContinue |
+        Where-Object { (Split-Path $_.DirectoryName -Leaf) -eq "docs" }
+
+    $found = 0; $seeded = 0
+    $absKit = (Resolve-Path $RepoDir -ErrorAction SilentlyContinue).Path
+    foreach ($idx in $indexes) {
+        $proj = Split-Path (Split-Path $idx.FullName -Parent) -Parent
+        $skip = $false
+        foreach ($d in $prune) { if ($proj -like "*\$d\*" -or $proj -like "*\$d") { $skip = $true; break } }
+        if ($skip) { continue }
+        if (-not (Test-Path (Join-Path $proj "AGENTS.md"))) { continue }
+        $abs = (Resolve-Path $proj -ErrorAction SilentlyContinue).Path
+        if (-not $abs -or $abs -eq $absKit) { continue }
+        $found++
+        foreach ($reg in $homes) {
+            $existing = @()
+            if (Test-Path $reg) { $existing = Get-Content $reg | ForEach-Object { $_.Trim() } | Where-Object { $_ } }
+            if ($existing -contains $abs) { continue }
+            Add-Content -Path $reg -Value $abs
+            $seeded++
+        }
+    }
+    Write-Host "  Scan: thấy $found OM project, seed $seeded entry mới vào registry."
+}
+
 # Helper: collect projects to sync
 function Get-OpenMonetaProjects {
     $found = @()
@@ -106,9 +193,34 @@ function Get-OpenMonetaProjects {
         }
     }
 
+    # Add registry projects khi -AllProjects
+    if ($AllProjects) {
+        foreach ($rp in (Read-Registry)) {
+            if (-not (Test-OpenMonetaProject $rp)) { continue }
+            if ($found -notcontains $rp) { $found += $rp }
+        }
+    }
+
     return $found
 }
 
+# Helper: nhắc user còn project trong registry chưa sync (chỉ khi không -AllProjects)
+function Write-RegistryHint {
+    param([string[]]$Synced)
+    if ($AllProjects) { return }
+    $count = 0
+    foreach ($rp in (Read-Registry)) {
+        if (-not (Test-OpenMonetaProject $rp)) { continue }
+        if ($Synced -contains $rp) { continue }
+        $count++
+    }
+    if ($count -gt 0) {
+        Write-Host ""
+        Write-Host "ℹ Có $count project khác trong registry chưa sync. Sync tất cả:"
+        Write-Host "  .\update.ps1 -AllProjects"
+    }
+}
+
 # === Step 1: Git pull ===
 $Status = git status --porcelain 2>$null
 if ($Status) {
@@ -196,6 +308,20 @@ if ($SkipProjects) {
     exit 0
 }
 
+if ($Scan) {
+    $AllProjects = $true
+    Write-Host ""
+    Write-Host "==> -Scan: dò OM project để seed registry..."
+    Invoke-ScanSeed
+}
+
+if ($AllProjects) {
+    Write-Host ""
+    Write-Host "==> -AllProjects: dọn registry + gom mọi project đã đăng ký..."
+    $pruned = Invoke-PruneRegistry
+    if ($pruned -gt 0) { Write-Host "  (registry: prune $pruned entry chết)" }
+}
+
 $Projects = Get-OpenMonetaProjects
 
 if ($Projects.Count -eq 0) {
@@ -209,6 +335,7 @@ if ($Projects.Count -eq 0) {
         Write-Host "Hoặc sync thủ công từng project:"
         Write-Host "  bash $RepoDir\scripts\init-project.sh <path>"
     }
+    Write-RegistryHint -Synced $Projects
     exit 0
 }
 
@@ -250,5 +377,6 @@ if ($SyncFail -gt 0) {
     Write-Host "   Failed: $SyncFail"
 }
 Write-Host "================================================"
+Write-RegistryHint -Synced $Projects
 Write-Host ""
 Write-Host "Restart Cursor để áp dụng changes."

package/update.sh

@@ -8,6 +8,8 @@
 #   bash update.sh --yes --force        # global + auto-sync, luôn cài lại
 #   bash update.sh --check              # chỉ check, không cài
 #   bash update.sh --project /path      # global + sync thêm project chỉ định
+#   bash update.sh --all-projects       # global + sync MỌI project trong registry
+#   bash update.sh --scan [root]        # dò OM project (mặc định $HOME) → seed registry → sync all
 #   bash update.sh --skip-projects      # global only (old behavior)
 
 set -euo pipefail
@@ -20,30 +22,43 @@ AUTO_YES=0
 SKIP_PROJECTS=0
 FORCE=0
 CHECK_ONLY=0
+ALL_PROJECTS=0
+SCAN=0
+SCAN_ROOT=""
 PROJECT_PATHS=()
 
-for arg in "$@"; do
-  case "$arg" in
+while [[ $# -gt 0 ]]; do
+  case "$1" in
     --yes|-y) AUTO_YES=1 ;;
     --force) FORCE=1 ;;
     --check) CHECK_ONLY=1 ;;
+    --all-projects) ALL_PROJECTS=1 ;;
     --skip-projects) SKIP_PROJECTS=1 ;;
+    --scan)
+      SCAN=1
+      ALL_PROJECTS=1
+      if [[ -n "${2:-}" && "${2:-}" != -* ]]; then
+        SCAN_ROOT="$2"
+        shift
+      fi
+      ;;
     --help|-h)
-      grep '^#' "$0" | sed 's/^# \?//' | head -17
+      grep '^#' "$0" | sed 's/^# \?//' | head -18
       exit 0
       ;;
     --project)
-      shift
-      if [[ -n "${1:-}" && "${1:-}" != -* ]]; then
-        PROJECT_PATHS+=("$1")
+      if [[ -n "${2:-}" && "${2:-}" != -* ]]; then
+        PROJECT_PATHS+=("$2")
+        shift
       fi
       ;;
     *)
-      if [[ "$arg" != -* ]]; then
-        PROJECT_PATHS+=("$arg")
+      if [[ "$1" != -* ]]; then
+        PROJECT_PATHS+=("$1")
       fi
       ;;
   esac
+  shift
 done
 
 cd "$REPO_DIR"
@@ -108,6 +123,80 @@ sync_project() {
   fi
 }
 
+# === Helper: registry files (gắn với install home cố định, không dùng OPENMONETA_HOME) ===
+registry_files() {
+  printf '%s\n' \
+    "$HOME/.cursor/.openmoneta-projects" \
+    "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/.openmoneta-projects"
+}
+
+# === Helper: đọc registry (merge 2 home, bỏ dòng trống, dedup) ===
+read_registry() {
+  local f
+  while IFS= read -r f; do
+    [[ -f "$f" ]] && cat "$f"
+  done < <(registry_files) | awk 'NF' | sort -u
+}
+
+# === Helper: prune entry chết khỏi registry (path mất / không còn OpenMoneta project) ===
+prune_registry() {
+  local f tmp pruned=0 line
+  while IFS= read -r f; do
+    [[ -f "$f" ]] || continue
+    tmp=$(mktemp)
+    while IFS= read -r line; do
+      [[ -z "$line" ]] && continue
+      if is_openmoneta_project "$line"; then
+        echo "$line" >> "$tmp"
+      else
+        pruned=$((pruned + 1))
+      fi
+    done < "$f"
+    mv "$tmp" "$f"
+  done < <(registry_files)
+  [[ $pruned -gt 0 ]] && echo "  (registry: prune $pruned entry chết)"
+  return 0
+}
+
+# === Helper: scan tìm OM project (docs/INDEX.md + AGENTS.md) → seed registry mỗi home tồn tại ===
+scan_seed() {
+  local root="${SCAN_ROOT:-$HOME}"
+  local abs_root
+  abs_root="$(cd "$root" 2>/dev/null && pwd -P)" || { echo "  [!] Scan root không tồn tại: $root"; return 0; }
+
+  local homes=()
+  [[ -f "$HOME/.cursor/.openmoneta-version" ]] && homes+=("$HOME/.cursor/.openmoneta-projects")
+  [[ -f "${XDG_CONFIG_HOME:-$HOME/.config}/opencode/.openmoneta-version" ]] && \
+    homes+=("${XDG_CONFIG_HOME:-$HOME/.config}/opencode/.openmoneta-projects")
+  if [[ ${#homes[@]} -eq 0 ]]; then
+    echo "  [!] Chưa có install home nào để seed registry."
+    return 0
+  fi
+
+  echo "  Scanning '$abs_root' (maxdepth project ~5)..."
+  local found=0 seeded=0 idx proj abs reg
+  while IFS= read -r idx; do
+    proj="$(dirname "$(dirname "$idx")")"
+    [[ -f "$proj/AGENTS.md" ]] || continue
+    abs="$(cd "$proj" 2>/dev/null && pwd -P)" || continue
+    [[ -z "$abs" || "$abs" == "$REPO_DIR" ]] && continue
+    found=$((found + 1))
+    for reg in "${homes[@]}"; do
+      if [[ -f "$reg" ]] && grep -qFx "$abs" "$reg" 2>/dev/null; then
+        continue
+      fi
+      echo "$abs" >> "$reg"
+      seeded=$((seeded + 1))
+    done
+  done < <(find "$abs_root" -maxdepth 7 \
+      \( -name node_modules -o -name .git -o -name Library -o -name .Trash \
+         -o -name .cache -o -name .npm -o -name .cargo -o -name .gradle \
+         -o -name .venv -o -name dist -o -name build \) -prune -o \
+      -type f -path '*/docs/INDEX.md' -print 2>/dev/null)
+
+  echo "  Scan: thấy $found OM project, seed $seeded entry mới vào registry."
+}
+
 # === Helper: collect projects to sync ===
 collect_projects() {
   local found=()
@@ -116,7 +205,7 @@ collect_projects() {
     local abs_kit
     abs_kit="$(cd "$REPO_DIR" && pwd -P)"
     if is_openmoneta_project "$ORIGINAL_PWD" && [[ "$(cd "$ORIGINAL_PWD" && pwd -P)" != "$abs_kit" ]]; then
-      found+=("$ORIGINAL_PWD")
+      found+=("$(cd "$ORIGINAL_PWD" && pwd -P)")
     fi
   fi
 
@@ -132,6 +221,20 @@ collect_projects() {
     fi
   done
 
+  if [[ $ALL_PROJECTS -eq 1 ]]; then
+    local rp abs_rp
+    while IFS= read -r rp; do
+      [[ -z "$rp" ]] && continue
+      is_openmoneta_project "$rp" || continue
+      abs_rp="$(cd "$rp" && pwd -P)"
+      local already=0
+      for f in "${found[@]}"; do
+        [[ "$f" == "$abs_rp" ]] && already=1 && break
+      done
+      [[ $already -eq 0 ]] && found+=("$abs_rp")
+    done < <(read_registry)
+  fi
+
   printf '%s\n' "${found[@]}"
 }
 
@@ -220,6 +323,39 @@ if [[ $SKIP_PROJECTS -eq 1 ]]; then
   exit 0
 fi
 
+# === Helper: nhắc user còn project trong registry chưa sync (chỉ khi không --all-projects) ===
+print_registry_hint() {
+  [[ $ALL_PROJECTS -eq 1 ]] && return 0
+  local count=0 rp abs_rp
+  while IFS= read -r rp; do
+    [[ -z "$rp" ]] && continue
+    is_openmoneta_project "$rp" || continue
+    abs_rp="$(cd "$rp" && pwd -P)"
+    if [[ -n "$PROJECTS" ]] && printf '%s\n' "$PROJECTS" | grep -qFx "$abs_rp"; then
+      continue
+    fi
+    count=$((count + 1))
+  done < <(read_registry)
+  if [[ $count -gt 0 ]]; then
+    echo ""
+    echo "ℹ Có $count project khác trong registry chưa sync. Sync tất cả:"
+    echo "  bash $REPO_DIR/update.sh --all-projects"
+  fi
+  return 0
+}
+
+if [[ $SCAN -eq 1 ]]; then
+  echo ""
+  echo "==> --scan: dò OM project để seed registry..."
+  scan_seed
+fi
+
+if [[ $ALL_PROJECTS -eq 1 ]]; then
+  echo ""
+  echo "==> --all-projects: dọn registry + gom mọi project đã đăng ký..."
+  prune_registry
+fi
+
 PROJECTS=$(collect_projects)
 
 if [[ -z "$PROJECTS" ]]; then
@@ -233,6 +369,7 @@ if [[ -z "$PROJECTS" ]]; then
     echo "Hoặc sync thủ công từng project:"
     echo "  bash $REPO_DIR/scripts/init-project.sh /path/to/project"
   fi
+  print_registry_hint
   exit 0
 fi
 
@@ -274,5 +411,6 @@ if [[ $SYNC_FAIL -gt 0 ]]; then
   echo "   Failed: $SYNC_FAIL"
 fi
 echo "================================================"
+print_registry_hint
 echo ""
 echo "Restart Cursor để áp dụng changes."