solution-erp/docs/guides/rag-onboarding-guide.md

# RAG Unified — Onboarding Guide cho dự án mới

> **Phiên bản:** 1.0 (2026-05-22) — chốt bởi em main SOLUTION_ERP S26+S27.
> **Pattern:** Approach B Distributed Bootstrap + Option 4a Manual PowerShell Scripts (per memory user-level `feedback_rag_distributed_ownership.md`).
> **Audience:** Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / dự án mới khác) khi anh pqhuy mở Claude Code session.
> **Cấu trúc nguồn:** SOLUTION_ERP em main đã pioneer setup `D:\.claude-rag\` infrastructure + 4 PS scripts + custom Dashboard. Project khác **TỰ BOOTSTRAP** theo guide này (~10 phút mỗi project), KHÔNG em main project khác làm hộ.

---

## §1 TL;DR (Quick start — 3 phút)

Anh pqhuy đã có RAG infrastructure global ở `D:\.claude-rag\` (Voyage AI + Qdrant Windows native + FastMCP). Em main project X mới chỉ cần 3 bước:

```powershell
# 1. Verify Qdrant + MCP server running (em pioneer đã setup)
rag-status

# 2. Tạo .claude/rag.json trong project root (template §4)
# 3. Bootstrap corpus
python D:\.claude-rag\bootstrap.py --project <project_id>
```

Restart Claude Code → 6 MCP tools `mcp__rag-unified__*` khả dụng trong session project mới.

**Em main project mới responsibility:**
- Tạo `.claude/rag.json` declare project_id + corpus_paths + sensitivity flag
- Run bootstrap.py ~5 phút embed
- Brief 4 sub-agent (nếu có setup multi-agent) qua MEMORY.md
- KHÔNG modify `D:\.claude-rag\server.py` (shared infrastructure)

---

## §2 Background — Tại sao Approach B Distributed?

### Bối cảnh

Anh pqhuy dev solo, có 5+ dự án cùng máy localhost (SOLUTION_ERP + NamGroup + DH Y Dược + Ashico + Vipix + tương lai). Mỗi project có 100-2000 file MD docs + agent memory.

### Quyết định chốt (per memory `feedback_rag_distributed_ownership.md`)

| Approach | Verdict |
|---|---|
| A. Em main SOLUTION_ERP làm hộ tất cả 4 project | ❌ Vi phạm Cognition "writes single-threaded" - em không có context project khác |
| **B. Distributed - 4 em main project khác tự bootstrap khi mở session** | ✅ **CHỌN** - đúng boundary, ownership rõ, sensitivity per project tự decide |
| C. Hybrid em làm 1 mẫu + 3 tự follow | 🤔 Vẫn còn cross-boundary 1 lần |

### Lý do CHỌN Approach B

1. **Cognition "writes single-threaded" principle** - mỗi em main own context flow project mình
2. **Em main project khác hiểu codebase sâu hơn** - SOLUTION_ERP em không có context active NamGroup
3. **Sensitivity per project** - vd DH Y Dược client confidential, em main DH biết set `share_to_global=false`. Em main SOLUTION_ERP KHÔNG biết → có thể set sai → leak risk
4. **Self-ownership re-bootstrap** - khi project Y thêm 50 file mới, em main Y biết để re-bootstrap. Em main X không monitor được Y
5. **Knowledge propagation natural** - em main Y bootstrap → `store_memory` pattern → `share_to_global=true` → các em main khác hưởng lợi qua RAG cross-share

---

## §3 Pre-check (Verify infrastructure global đã sẵn sàng)

Trước khi bootstrap, em main project mới CHECK:

```powershell
# 1. Aliases hoạt động (sẽ load $PROFILE auto)
rag-status
```

Output kỳ vọng:
- `[Qdrant Server] Status: Running PID xxx port 6333` (em pioneer đã start)
- `[MCP Server] Registration: rag-unified [OK] Connected (user-level)`
- `[Voyage AI] API key set: [OK]`

**Nếu Qdrant DOWN:**
```powershell
rag-start    # Em pioneer setup, just start
```

**Nếu MCP NOT REGISTERED:** Em main project mới KHÔNG self-register. Báo anh pqhuy để re-add user-level (1 lần duy nhất per Windows user):
```powershell
claude mcp add -s user -e "VOYAGE_API_KEY=$env:VOYAGE_API_KEY" -- rag-unified python "D:\.claude-rag\server.py"
```

**Nếu API key MISSING:**
```powershell
[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "pa-MiN...", "User")
# Restart Claude Code để pick up env var
```

---

## §4 Bootstrap 3 steps cho project mới

### Step 1: Tạo `.claude/rag.json` ở project root

Template generic:
```json
{
  "project_id": "<kebab-or-snake-case-id>",
  "display_name": "<Tên đầy đủ project>",
  "corpus_paths": [
    "docs/**/*.md",
    ".claude/agent-memory/**/MEMORY.md",
    ".claude/skills/**/SKILL.md"
  ],
  "exclude_paths": [
    "docs/_archive/**",
    "node_modules/**",
    "bin/**",
    "obj/**",
    ".git/**"
  ],
  "extra_corpus": [
    "C:\\Users\\pqhuy\\.claude\\projects\\<project-folder>\\memory\\*.md"
  ],
  "share_to_global": true,
  "search_scope_default": ["self", "shared_global"],
  "auto_reindex": true,
  "chunk_size": 1500,
  "chunk_overlap": 200,
  "contextual_retrieval": true
}
```

**Checklist customize:**

| Field | Hướng dẫn |
|---|---|
| `project_id` | Lowercase + underscore. Ví dụ: `namgroup_main`, `dh_y_duoc`, `ashico_erp`, `vipix_multisite`. Phải UNIQUE cross 5 project. |
| `display_name` | Tên đầy đủ cho dashboard hiển thị, vd `"NamGroup - HRM"` |
| `corpus_paths` | Glob patterns relative project root. Default 3 path cover docs + agent memory + skills. Tăng thêm nếu project có folder docs khác (vd `tests/specs/**/*.md`). |
| `exclude_paths` | KHÔNG embed file tạm/binary/archive |
| `extra_corpus` | Memory user-level Claude Code (path absolute). Folder: `C:\Users\pqhuy\.claude\projects\<your-project-folder-name>\memory\*.md` |
| `share_to_global` | **CRITICAL DECISION:** `true` = chunks promote-able to shared_global collection (cross-project search visible). `false` = client confidential, chỉ self-project access. **Em main project decide based on data sensitivity** (vd DH Y Dược client → `false`, NamGroup internal HRM → `true`). |
| `search_scope_default` | Default `["self", "shared_global"]` - cân bằng project-specific + cross-project pattern reuse |
| `chunk_size` / `chunk_overlap` | Default 1500/200 chars - đã tune cho MD docs Vietnamese. KHÔNG đổi unless project có docs structure khác hẳn. |
| `contextual_retrieval` | `true` - Anthropic Contextual Retrieval prepend "From <doc> > <heading>:" - +15% recall |

### Step 2: Run bootstrap

```powershell
python D:\.claude-rag\bootstrap.py --project <project_id>
```

Expected output:
```
[1/4] Scanning corpus... Found N files
[2/4] Chunking + contextual prepend... Total chunks: M
      Estimated tokens: ~XXX,XXX (Voyage free tier: 200M/month)
[3/4] Voyage-4-large embedding + Qdrant upsert + SQLite BM25... Upserted M chunks in T seconds
[4/4] Update registry...
[OK] Bootstrap complete: <project_id> ready (M chunks)
```

**Performance benchmark (SOLUTION_ERP 2026-05-22):**
- 126 files → 2,628 chunks → ~484K tokens → 60.9s embed + upsert
- 2nd bootstrap với cache hit: 6.5s (10× speedup)

### Step 3: Verify

```powershell
rag-status   # See new project in [Collections] section
rag-dashboard   # Visual verify via browser
```

Test query in Claude Code session (project mới):
```
search_memory("pattern X tôi đã làm chưa")
```

Should return chunks từ project mới + shared_global (nếu có).

---

## §5 6 MCP Tools matrix

| Tool | Scope | Use case |
|---|---|---|
| `search_memory(query, scope, top_k, use_rerank)` | `self` / `shared_global` / `all_projects` / `default` | Tìm pattern, gotcha, narrative trong project hiện tại + shared |
| `cross_project_search(query, top_k)` | All projects | "Pattern X tao đã làm ở dự án nào trước chưa?" - explore cross-project knowledge |
| `search_code(query, file_pattern, top_k)` | Self only (BM25-heavy) | Tìm exact symbol/function name trong source code |
| `store_memory(content, source_path, tags)` | Self | Save pattern on-the-fly cuối session, không cần re-bootstrap |
| `promote_to_shared(chunk_id)` | Self → shared_global | Pattern proven cross-project ≥2x use → visible to all projects (v0 stub, defer v1) |
| `list_projects()` | All registry | Overview projects + collection chunk counts |

**Em main project mới brief 4 sub-agent (nếu có setup):**

| Agent | Skills preload + RAG access |
|---|---|
| 🟦 Investigator | Auto-detect cwd → project_id → `mcp__rag-unified__search_memory(scope="self")` cho research patterns |
| 🟨 Implementer | Same auto-detect + `search_code` cho symbol lookup khi cookie-cutter mirror |
| 🟥 Reviewer | Same auto-detect + `cross_project_search` để verify pattern proven elsewhere trước commit |
| 🟩 CICD Monitor | Same + `list_projects` cho infra state checks |

---

## §6 4 Sub-agent setup brief (optional - cho project ≥10K LOC, ≥3 month)

Per memory `feedback_multi_agent_setup.md` - setup multi-agent CHỈ khi pass 6/6 decision gate. SOLUTION_ERP S20 turn 12 đã match (59 tables + 142 endpoints + 6 skills + 44 gotchas).

**Pattern reusable cho project mới:**

1. Tạo `.claude/agents/` folder + 4 `.md` files (Investigator + Implementer + Reviewer + CICD Monitor)
2. Tạo `.claude/agent-memory/<name>/MEMORY.md` seed per agent
3. Copy template từ SOLUTION_ERP `.claude/agents/README.md` (master coordination guide)
4. Customize project-specific:
   - Skills preload (tùy stack: .NET / React / Python / Go)
   - Domain entities + workflow patterns
   - Live prod URLs + bearer tokens
   - Gotcha catalog reference
5. End-of-session: 4 agent flush MEMORY.md updates → em main synthesize cross-agent learnings → integrate vào memory + session log

**Reference SOLUTION_ERP files (paste-friendly templates):**
- `.claude/agents/README.md` - master coordination guide với 6-criteria decision gate
- `.claude/agents/investigator.md` - frontmatter + system prompt template
- `.claude/agents/implementer.md` - REFUSE strict 6-criteria
- `.claude/agents/reviewer.md` - 5-category checklist + Smart Friend guard
- `.claude/agents/cicd-monitor.md` - 5-stage post-deploy verify

---

## §7 Permission + Security

### MCP user-level scope (1 lần setup per Windows user)

`claude mcp add -s user` registers `rag-unified` ở `%USERPROFILE%\.claude.json` - persist across ALL Claude Code sessions cho user pqhuy. Bất kỳ project nào pqhuy mở đều có access 6 tools (KHÔNG cần re-register).

### VOYAGE_API_KEY scope

`[Environment]::SetEnvironmentVariable("VOYAGE_API_KEY", "...", "User")` - Windows User registry, persist boot-to-boot. KHÔNG commit vào git. KHÔNG share cross-machine.

### `share_to_global` flag (per-project)

- `true` → chunks có thể promote vào `shared_global` collection → cross-project search visible (em main khác có thể thấy)
- `false` → strict isolated cho project (client confidential, NDA, regulated data)

**KIẾN NGHỊ:** Em main project mới BẮT BUỘC review sensitivity TRƯỚC khi bootstrap. Vd:
- DH Y Dược (client confidential): `share_to_global=false` + exclude paths chứa client name
- NamGroup (internal HRM): `share_to_global=true` ok
- Vipix multisite (public docs): `share_to_global=true`

---

## §8 Workflow daily — Em main project mới

```powershell
# Morning - mở session Claude Code project mới
rag-status         # Check infra OK
rag-dashboard      # Visual sanity check

# Trong session - search context
search_memory("workflow X")           # MCP tool call trong session
cross_project_search("pattern Y")     # Find proven pattern elsewhere

# End of session - save new pattern
store_memory("Pattern Z chốt 2026-XX-XX...", tags=["pattern", "<topic>"])

# Periodic - re-bootstrap khi docs thay đổi nhiều
python D:\.claude-rag\bootstrap.py --project <project_id> --re-embed
```

### Khi nào re-bootstrap?

- Sau session lớn thêm > 20 file MD docs mới
- Sau drastic refactor MD structure (rename folders, restructure)
- Monthly cadence per `feedback_md_compact_narrative.md` audit + curate cycle

### Khi nào KHÔNG re-bootstrap (cache hit)?

- File MD chỉ patched < 30% content - bootstrap re-embed sẽ skip chunks unchanged (SHA256 cache hit)
- Session khác không touch corpus paths

---

## §9 Troubleshooting

### Q: `rag-status` báo Qdrant DOWN nhưng anh đã `rag-start`?

A: Check 30s timeout - Qdrant cần ~10s warmup. Retry sau:
```powershell
Start-Sleep -Seconds 10
Invoke-RestMethod -Uri "http://localhost:6333/healthz" -TimeoutSec 10
```

Nếu vẫn DOWN, check logs:
```powershell
Get-Content "D:\.claude-rag\logs\qdrant-$(Get-Date -Format 'yyyyMMdd').log" -Tail 30
```

### Q: MCP server `rag-unified` NOT CONNECTED?

A: 3 nguyên nhân thường gặp:

1. **VOYAGE_API_KEY chưa load vào Claude Code env** → Restart Claude Code completely (close all windows)
2. **Python deps thiếu** → `pip install fastmcp voyageai qdrant-client watchdog python-dotenv`
3. **MCP đăng ký sai path** → Check `claude mcp list` - phải có dòng `rag-unified: python D:\.claude-rag\server.py - [OK] Connected`

### Q: `bootstrap.py` báo Voyage rate limit hoặc 429?

A: Free tier 200M tokens/month chia equally across requests. Nếu hit limit:
- Wait 1 phút retry (Voyage rate limit window ~60s)
- Batch nhỏ hơn: `--batch-size 32` thay vì default 128
- Check Voyage dashboard: https://dash.voyageai.com/

### Q: SQLite FTS5 query error `no such column: in`?

A: Gotcha #48 cousin - reserved keyword. `_sanitize_fts5_query()` strip non-alphanumeric. Nếu vẫn fail, simplify query (remove `-`, `:`, `()`)

### Q: Qdrant batch upsert WinError 10053 "connection aborted"?

A: Batch quá lớn. `lib/retrieval.py:UPSERT_BATCH = 64` đã limit. Nếu vẫn fail, giảm xuống 32.

### Q: HuggingFace symlinks warning Windows?

A: Non-critical (cache works degraded efficiency). Suppress: `$env:HF_HUB_DISABLE_SYMLINKS_WARNING=1`

---

## §10 Tunings (advanced)

### Tăng recall (sacrifice cost)

```json
{
  "chunk_size": 1000,        // smaller chunks = more granular match
  "chunk_overlap": 300,      // higher overlap = catch boundary patterns
  "use_rerank_default": true // rerank-2.5 = +20-30% recall vs vector-only
}
```

Cost trade-off: smaller chunks = N% more tokens to embed + rerank.

### Giảm cost (sacrifice recall)

```json
{
  "chunk_size": 2500,
  "chunk_overlap": 100,
  "use_rerank_default": false  // rely on vector + BM25 only
}
```

Saving: ~30% Voyage tokens. Recall drop ~10-15%.

### BM25 weight tuning

Default RRF k=60 (Reciprocal Rank Fusion). Tăng `k` = giảm BM25 dominance, tăng vector. Em main project mới KHÔNG tune trừ khi có golden benchmark dataset.

---

## §11 Best practices cross-project

1. **`store_memory` defensive** - cuối session save new pattern proven, không đợi monthly bootstrap
2. **Cross-project search BEFORE design** - `cross_project_search("pattern X")` check trước khi implement mới
3. **Sensitivity audit per session** - khi push file mới có client info → confirm `share_to_global` flag đúng
4. **Dashboard daily** - mở `rag-dashboard` mỗi sáng để verify infra healthy + collection counts không drop bất thường
5. **Document `.claude/rag.json` decisions** - comment trong file lý do chốt sensitivity flag, exclude paths
6. **Cron monthly audit cadence** - per rule §6.4 SOLUTION_ERP, project mới adopt monthly cron skill+doc audit. Drift trigger sớm nếu +5 gotcha mới

---

## §12 Status Monitoring + Manual Control (Option 4b NSSM Windows Service ⭐ UPGRADED S27)

### Upgrade S27: Qdrant chạy as Windows Service (NSSM)

Phiên bản S26 dùng Option 4a (manual PS scripts only). **S27 upgrade lên Option 4b** với NSSM Windows Service:

| | Option 4a (S26) | **Option 4b NSSM (S27 RECOMMEND)** |
|---|---|---|
| Auto-start timing | Sau anh login Windows (Startup folder) | ✅ Boot-time (trước login) |
| Auto-restart on crash | ❌ Stay crashed | ✅ Auto-respawn 3s delay |
| Survive logout/login | ❌ Stop khi logout | ✅ Service runs background |
| Control | `rag-start/stop/status/dashboard` | Same + `Get-Service Qdrant` native |
| Setup once | ~30 phút | ~35 phút (+ install NSSM elevated) |
| OOM recovery (vd 8.4MB OOM em pioneer S27) | Manual rag-restart | ✅ Auto-respawn |

**Setup elevated PowerShell (1 lần duy nhất):**
```powershell
# 1. Download NSSM 2.24 (~3 MB, may retry nssm.cc 503 transient)
$nssmDir = "D:\.claude-rag\nssm"
Invoke-WebRequest -Uri "https://nssm.cc/release/nssm-2.24.zip" -OutFile "$nssmDir\nssm-2.24.zip"
Expand-Archive "$nssmDir\nssm-2.24.zip" $nssmDir -Force
Copy-Item "$nssmDir\nssm-2.24\win64\nssm.exe" "$nssmDir\nssm.exe"

# 2. Run install script (em pioneer write D:\.claude-rag\scripts\install-service.ps1)
& "D:\.claude-rag\scripts\install-service.ps1"
```

Script tự động: stop manual qdrant + register service + AppDirectory + log paths + Start SERVICE_AUTO_START + AppExit Default Restart 3s delay + DisplayName "Qdrant Vector DB (RAG Unified)" + Description + start service + health verify.

**Verify post-install:**
```powershell
Get-Service Qdrant   # Should show Status: Running, StartType: Automatic
```

**Troubleshooting nếu start fail (WAL lock conflict):**
```powershell
# Pre-existing qdrant.exe manual holding WAL → kill + retry
& "D:\.claude-rag\scripts\fix-service-start.ps1"  # elevated
```

### Aliases trong $PROFILE (~30 phút first-time setup)

```powershell
function rag-start     { & "D:\.claude-rag\scripts\start.ps1" }     # Start Qdrant background
function rag-stop      { & "D:\.claude-rag\scripts\stop.ps1" }      # Graceful stop
function rag-status    { & "D:\.claude-rag\scripts\status.ps1" }    # Full status report 6 section
function rag-dashboard { & "D:\.claude-rag\scripts\dashboard.ps1" } # Custom HTML dashboard + open browser
function rag-restart   { & "D:\.claude-rag\scripts\stop.ps1"; Start-Sleep 2; & "D:\.claude-rag\scripts\start.ps1" }
function rag-boot      { & "D:\.claude-rag\scripts\boot.ps1" }      # Manual trigger boot sequence
```

### 6 PS scripts khả dụng (em pioneer SOLUTION_ERP đã build — Service mode S27)

| Script | Mục đích | Output |
|---|---|---|
| `start.ps1` | `Start-Service Qdrant` (needs Admin if stopped) | Service status + PID + RAM |
| `stop.ps1` | `Stop-Service Qdrant -Force` (needs Admin) | Status verification |
| `status.ps1` | Full status: Service + Process + MCP + Voyage + Collections + Disk + Agent MEMORY | Terminal 6 section colored (no Admin) |
| `dashboard.ps1` | Generate custom HTML dashboard (STATIC snapshot) + open browser | `D:\.claude-rag\dashboard.html` |
| `boot.ps1` | Post-login: verify service Running + regen Dashboard + open browser | Used by Startup folder shortcut |
| `install-service.ps1` | NSSM register Qdrant as Windows Service (1 lần) | Service Running + Auto-start verified |
| `fix-service-start.ps1` | Recover service after WAL lock conflict (rare) | Service Running verified |

### Custom MCP Dashboard

**URL:** `file:///D:/.claude-rag/dashboard.html` (auto-generated, auto-open by `rag-dashboard` command)

⚠️ **IMPORTANT (S27 fix):** Dashboard HTML là **STATIC SNAPSHOT** tại thời điểm anh chạy `rag-dashboard`. **KHÔNG auto-poll Qdrant API live** — browser meta refresh chỉ reload HTML cached, KHÔNG re-run PS script. Muốn data live → mở **Qdrant Native Dashboard** (`http://localhost:6333/dashboard`) fetch API real-time. Custom Dashboard chỉ dùng cho ecosystem overview (Service+MCP+Voyage+Agent MEMORY combined panel mà Qdrant native không có).

**Panels:**
1. **Qdrant Vector DB** - PID/version/uptime/RAM/storage + link Qdrant native dashboard
2. **MCP Server (FastMCP)** - Registration status + 6 tools matrix
3. **Collections** - List all `proj_*` + `shared_global` chunk counts
4. **Voyage AI** - API key + scope + embedding/rerank model + free tier
5. **System** - Disk usage + Python version + paths
6. **Agent MEMORY** - 4 agent MEMORY.md sizes (SOLUTION_ERP) with curate threshold warnings
7. **Recent Qdrant Logs** - last 10 lines

**Auto-refresh:** 60s via `<meta http-equiv="refresh" content="60">`. Manual refresh via "Refresh Now" button.

**Customization cho project mới (optional):**
- Edit `dashboard.ps1` Section 6 `$memDir` path → point to project mới `.claude/agent-memory/`
- Add custom panels (vd Section "Recent commits" via `git log --oneline -10`)
- Color palette: change `#f59e0b` (orange) → project brand color

### Auto-start on Windows boot (S27 — 2-layer)

**Layer 1 — NSSM Windows Service (auto-start Qdrant):**
- Service `Qdrant` StartType=Automatic → boot-time auto-start (trước login)
- Auto-restart on crash (AppExit Default Restart 3s delay)
- Survive logout/login

**Layer 2 — Startup folder shortcut (auto-open Dashboard sau anh login):**
- Path: `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\rag-boot.lnk`
- Target: `powershell.exe -NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File "D:\.claude-rag\scripts\boot.ps1"`
- `boot.ps1` S27 updated: verify service Running (KHÔNG start lại) + regen Dashboard + open browser
- Disable: Delete `.lnk` file (Qdrant vẫn auto-start by service)

### Qdrant Native Dashboard (built-in FREE — Web UI v0.2.12)

URL: **`http://localhost:6333/dashboard`** (browse Qdrant collections, query playground, metrics)

⚠️ **Yêu cầu trước:** Em pioneer SOLUTION_ERP đã download Web UI static files vào `D:\.claude-rag\qdrant-bin\static\` (S27 hotfix - Qdrant Windows binary zip không bundle Web UI). Nếu native dashboard 404, xem Gotcha #4 §A2 để re-download.

**Khác biệt Native Qdrant vs Custom MCP Dashboard:**

| | Qdrant Native | Custom MCP (em pioneer build) |
|---|---|---|
| URL | `http://localhost:6333/dashboard` | `file:///D:/.claude-rag/dashboard.html` |
| Mục đích | Browse collections + query playground + metrics | Status overview RAG ecosystem |
| Panels | Collections, Console, Cluster, Snapshots | Qdrant+MCP+Voyage+Agent MEMORY+Logs |
| Auto-refresh | Yes (Qdrant native polling) | 60s meta refresh |
| Khi dùng | Khi cần inspect collection data, run test query | Khi cần check overall health + 4 agent MEMORY sizes + Voyage token usage |

**Bookmark cả 2** — complementary, không thay thế nhau.

---

## §13 Approach B Distributed Workflow (Em main pioneer KHÔNG làm hộ)

### Responsibility split

**Em main pioneer (SOLUTION_ERP):**
- ✅ Build infrastructure `D:\.claude-rag\` (Qdrant binary + FastMCP server + lib + scripts)
- ✅ Build 4 PS scripts (start/stop/status/dashboard) + boot.ps1
- ✅ Custom MCP Dashboard HTML generator
- ✅ $PROFILE aliases setup
- ✅ Startup folder shortcut auto-boot
- ✅ Bootstrap SOLUTION_ERP corpus (proj_solution_erp)
- ✅ Xuất guide này (file `rag-onboarding-guide.md`)
- ❌ **KHÔNG bootstrap data cho project Y/Z khác** - đó là việc của em main project đó

**Em main project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác — khi anh pqhuy mở Claude Code project đó):**

1. **Đọc guide này** (5 phút) - paste vào `docs/guides/rag-onboarding-guide.md` của project nếu chưa có
2. **Tự tạo `.claude/rag.json`** - em main project hiểu CONTEXT cụ thể (project_id, corpus paths, sensitivity flag)
3. **Tự run bootstrap.py** ~5 phút embed
4. **Test query verify** hoạt động
5. **Brief 4 sub-agent của project đó** qua MEMORY.md (nếu có setup multi-agent)

### Pattern reusable cross-project

**Setup-once, scale-distributed pattern** cho bất kỳ multi-project shared infrastructure (RAG + MCP + future tools):

```
1. Em main project pioneer (P1 = SOLUTION_ERP) build infra + xuất onboarding MD
2. P1 KHÔNG executable cho P2/P3/.../Pn
3. Em main P2/P3/.../Pn tự đọc MD + apply khi anh pqhuy mở session project đó
4. Cumulative knowledge graph natural - mỗi em main own context, share qua shared_global collection
```

### Anti-patterns avoided

- ❌ Em main project X bootstrap data cho project Y/Z - vi phạm Cognition boundary
- ❌ Hardcode `.claude/rag.json` cho project khác trong em main X - em không biết sensitivity
- ❌ Task Scheduler auto-start dù không cần (RAM cost + lose control - anh chọn manual scripts thay)
- ❌ Embed config decisions qua chat conversation - KHÔNG vào RAG, mất khi session crash

---

## §A3 Context loading Hybrid pattern — em main workflow optimization ⭐ S27 NEW

> **Audience:** Em main Opus project Y/Z (NamGroup / DH Y Dược / Ashico / Vipix / khác). Áp dụng cho mỗi session daily ops.
> **Origin:** Memory user-level `feedback_rag_hybrid_pattern.md` (Cách A defensive). Bài học S27 SOLUTION_ERP em pioneer.

### §A3.1 — Why Hybrid (Cách A defensive vs Cách B aggressive)

Em main Opus 4.7 có **1M token context window** (qua `model: inherit` từ parent). KHÔNG load hết tất cả MD vào blanket — wasteful + context rot.

| Cách | Blanket size | RAG usage | Decision quality | UX latency | Khi dùng |
|---|---|---|---|---|---|
| **Cách A defensive (CHỌN)** | ~120K | Supplement retrieve on-demand | 90% (control flow strong) | Smooth | **Project MD > 1M tokens cumulative** |
| Cách B aggressive | Cắt 60-70% | Cascade retrieve mỗi task | 75-80% (fragmented) | +1-2s mỗi state question | KHÔNG khuyến nghị |
| Skip RAG | Blanket all | Zero | Best decision quality | Best UX | Project MD < 200K tokens |

**Decision gate cho project mới:**
- MD < 200K tokens → Skip RAG entirely
- MD 200K-1M → Lazy blanket sufficient, RAG nice-to-have
- **MD > 1M → RAG MANDATORY** (vượt context window blanket)

### §A3.2 — Layer 1: Blanket auto-load (mỗi session start)

Auto-injected vào em main session khi anh mở Claude Code project:

| Component | Estimate KB | Always loaded? |
|---|---|---|
| System prompt + tool definitions | 15-20 | ✅ Always |
| `CLAUDE.md` (project root pointer) | 1-3 | ✅ Always |
| `docs/CLAUDE.md` (full project context) | 8-15 | ✅ Always |
| `docs/STATUS.md` Recently Done snapshot | 30-60 (oversize warn) | ✅ Always (per CLAUDE.md priority) |
| `docs/HANDOFF.md` brief 5 phút | 80-90 (oversize warn) | ✅ Always |
| User memory `MEMORY.md` index | 3-5 | ✅ Always |
| 6 skill descriptions | 3 | ✅ Always |
| 4 sub-agent definitions + first 200 lines MEMORY each | 50-80 | ✅ Always (post CLI restart pickup model:inherit) |
| **Tổng blanket estimate** | **~200-280 KB ≈ 50-70K tokens** | |

**KHÔNG auto-load (cần RAG retrieve hoặc Read direct):**
- Session logs cũ `docs/changelog/sessions/*.md` (~30+ files cumulative)
- Skill SKILL.md full content (chỉ description in blanket)
- Memory user-level full content (chỉ index)
- Source code BE/FE
- Archive folders `.claude/agent-memory/*/archive/*`
- Migration scripts old + DbInitializer

### §A3.3 — Layer 2: RAG retrieve decision tree

```
Em main cần thông tin → CHỌN tool:

├── Cần PATTERN proven từ session cũ / cross-project?
│     → mcp__rag-unified__search_memory("pattern X", scope="default")
│     Vd: "per-NV admin opt-in flag pattern", "FE merge synthetic audit"
│
├── Đang implement feature mới — kiểm tra đã làm ở project nào trước chưa?
│     → mcp__rag-unified__cross_project_search("feature Y")
│     Vd: "audit recovery pattern", "Workflow N-stage state machine"
│
├── Cần lookup EXACT function/class/method trong source code?
│     → mcp__rag-unified__search_code("ApproveV2Async signature")
│     BM25-heavy, exact symbol match. NOT cho semantic question.
│
├── Cần GOTCHA cụ thể đã gặp?
│     → search_memory("gotcha #48 SQLite tie-break") OR Read docs/gotchas.md direct
│     Decision: < 5 gotcha lookup/session → Read direct. > 5 → search_memory.
│
├── Cần SESSION LOG cụ thể S22-S26 history?
│     → search_memory("S23 Plan K F2 refactor") thay vì Read full session log 15-25KB
│     Saves 80-90% tokens per lookup
│
├── End-of-session phát hiện NEW pattern reusable?
│     → mcp__rag-unified__store_memory(content, tags=["pattern", "<topic>"])
│     KHÔNG đợi monthly bootstrap — instant index
│
├── Pattern proven cross-project ≥ 2× use, muốn share?
│     → mcp__rag-unified__promote_to_shared(chunk_id)
│     (v0 stub, defer v1)
│
└── Daily ops, không cần cụ thể?
      → Skip RAG, dùng blanket auto-load + Read on-demand specific files
```

### §A3.4 — Token budget guidance per session

**Target utilization Opus 4.7 1M context:**

| % Used | State | Action |
|---|---|---|
| 0-30% (~0-300K) | 🟢 Healthy | Continue normal work |
| 30-50% (~300-500K) | 🟢 Heavy session | OK, monitor sub-agent spawn cost |
| 50-70% (~500-700K) | 🟡 Warning | Consider end-of-session soon, save patterns via `store_memory` |
| 70-85% (~700-850K) | 🟠 Approach limit | End session ASAP, finalize HANDOFF, S+1 fresh |
| > 85% (~850K+) | 🔴 Critical | Response lag + repetition. End immediately. |

**Em main session activity sample S27 (~5h heavy):**
- Read full 4 MEMORY (180KB) + STATUS (60KB) + HANDOFF (90KB) + multiple skill files + session logs S25-S26
- Write 7 PS scripts + dashboard HTML + onboarding guide (440 lines) + 4 archive files + memory NEW
- Estimate context used: ~400-560K (40-55% utilization) — Warning state
- Pattern: Heavy session ~5-6h → end session, S+1 fresh start

**Anti-pattern wasteful:**
- ❌ Read entire `STATUS.md` (60KB) cho 1 question — use search_memory instead
- ❌ Read tất cả session log S20-S26 (~30 files ~300KB) — use search_memory specific term
- ❌ Read entire 4 sub-agent MEMORY (180KB) mỗi session — auto-injected first 200 lines, đủ; full Read only when explicit reference
- ❌ Search RAG với empty/vague query ("test", "data") — return noise
- ❌ Read full source code BE (3K LOC) cho 1 line lookup — use search_code BM25

### §A3.5 — 6 MCP tools examples concrete (em main daily)

**1. `search_memory(query, scope, top_k, use_rerank)`** — Most common

```python
# Vietnamese OK
search_memory("workflow approve V2 actor scope check")

# English OK
search_memory("multi-agent setup pitfall model inherit")

# Specific gotcha lookup (skip Read gotchas.md full)
search_memory("gotcha 48 SQLite tie-break multi Changelog")

# Cross-project default (self + shared_global)
search_memory("Per-NV admin opt-in flag pattern", scope="default")

# Self-only (project-specific narrow)
search_memory("Plan AG tree view UI", scope="self")
```

**2. `cross_project_search(query, top_k)`** — Khi explore broader

```python
# "Pattern X tao đã làm ở dự án nào trước chưa?"
cross_project_search("audit recovery synthetic rows FE merge")
cross_project_search("EF migration BACKFILL reorder discipline")
cross_project_search("Custom Dashboard PowerShell HTML generator")
```

**3. `search_code(query, file_pattern, top_k)`** — BM25 exact match

```python
# Exact function name
search_code("ApproveV2Async EnsureCanRejectV2Async")

# Specific TS prop
search_code("AllowApproverEditBudget per-Level slot", file_pattern="**/*.cs")

# Migration name lookup
search_code("Mig 29 RefactorAdvancedOptionsToPerLevelAndDrafterUser")
```

**4. `store_memory(content, source_path, tags)`** — End-of-session NEW pattern

```python
store_memory(
    content="""
    Pattern S27 NEW: NSSM Windows Service for Qdrant auto-start.
    - 7 PS scripts (install/fix/start/stop/status/dashboard/boot)
    - Service mode auto-restart on crash + survive logout
    - Gotcha: WAL lock conflict if manual qdrant.exe running → kill first
    Reusable cross-project bất kỳ multi-project shared infrastructure.
    """,
    source_path="manual/S27-nssm-pattern",
    tags=["nssm", "windows-service", "qdrant", "pattern"]
)
```

**5. `promote_to_shared(chunk_id)`** — Cross-project pattern proven

```python
# v0 stub - defer v1. For now manually duplicate-index to shared via store_memory
# (Pattern proven ≥ 2× use → manual cross-share)
```

**6. `list_projects()`** — Registry overview (rare daily, common monthly audit)

```python
# Check infra health
list_projects()
# Returns: [{project_id, collection, chunk_count, last_indexed_at}, ...]
```

### §A3.6 — Best practices em main daily workflow

**Morning session start (5 phút):**
```powershell
rag-status                    # Check Qdrant Service + collection counts
rag-dashboard                 # Visual sanity (snapshot - mỗi sáng OK fresh)
```
+ Spawn test sub-agent IMMEDIATELY:
```
Agent(subagent_type="investigator", prompt="Test reply 1 sentence")
```
→ Verify registry load. Nếu fail → check `feedback_subagent_setup_pitfalls.md` §4 diagnose.

**Trong session daily ops:**
- **Default tool: `search_memory`** thay vì Read MD direct (saves 80-90% tokens per lookup)
- Read direct CHỈ KHI cần edit file đó hoặc cần see full file structure
- `cross_project_search` khi design feature mới — check proven elsewhere
- `search_code` khi need exact symbol/function lookup

**End of session save NEW patterns:**
```python
# 1. store_memory cho mỗi pattern proven phát hiện trong session
store_memory(content="Pattern Z chốt YYYY-MM-DD: ...", tags=[...])

# 2. Update HANDOFF.md với S+1 priority HIGH
# 3. Commit + push (nếu có code changes)
```

**Monthly audit cadence (re-bootstrap if drift):**
```powershell
python D:\.claude-rag\bootstrap.py --project <project_id>          # incremental cache hit
python D:\.claude-rag\bootstrap.py --project <project_id> --force-reindex   # clean slate
```

Trigger re-bootstrap khi:
- +20 file MD docs mới sau session lớn
- Drastic refactor MD structure (rename folders)
- Monthly audit per rule §6.4 cadence
- Sau khi clean curate 4 sub-agent MEMORY

### §A3.7 — Anti-patterns cross-project (đừng làm)

1. ❌ **Solo cả session vì assume agents chưa load** — VIPIX + SOLUTION_ERP S27 lesson. ALWAYS spawn test agent first.
2. ❌ **Read full session log cũ (15-25KB each)** — use `search_memory("S## Plan X")` instead, saves 80-90% tokens
3. ❌ **Read full 4 MEMORY.md mỗi session** — auto-injected first 200 lines blanket đủ; full Read only when explicit pattern reference
4. ❌ **search_memory với query vague** ("test", "data", "fix") — return noise. Specific terms: "gotcha #48 SQLite tie-break", "Plan AG tree view".
5. ❌ **Skip `store_memory` end-of-session** — pattern mất khi session crash. Save instant, không đợi monthly bootstrap.
6. ❌ **Em main solo task qualify Implementer Case 1/2** — vi phạm directive S22 chốt BẮT BUỘC delegate. Spawn Implementer cho cookie-cutter mechanical (≥5 file independent + deterministic spec).
7. ❌ **Heavy session > 6h không end** — context rot risk. End session + S+1 fresh.

### §A3.8 — Context monitoring + when to end session

**Em main không có exact token counter built-in** (Anthropic Claude Code CLI có thể có `/context` hoặc status bar — em check tùy version).

**Estimate heuristics:**
- Số lượng files Read full: > 10 large files (>30KB each) → likely > 40% context
- Session duration: > 5h heavy work → likely > 50% context
- Sub-agent spawn count: 4 agents × 100K each = ~400K used by sub-agent overhead alone
- Tool calls cumulative: > 100 tool calls likely > 50% context

**Signs of context full (end session ASAP):**
- 🚨 Response lag noticeable (longer wait)
- 🚨 Em main lặp lại logic đã reasoning
- 🚨 Em main miss reference to earlier session context
- 🚨 Sub-agent spawn returns wrong/incomplete results

**End session protocol:**
1. `store_memory` mọi NEW pattern phát hiện trong session
2. Update `STATUS.md` Recently Done
3. Update `HANDOFF.md` với S+1 priority HIGH list
4. Write `docs/changelog/sessions/YYYY-MM-DD-S##-<topic>.md`
5. Commit + push (per project workflow)
6. Anh restart Claude Code CLI cho S+1 fresh

---

## §A2 Cấu trúc chuẩn em main pioneer (SOLUTION_ERP) đã setup

> **Notes integrated từ Plan A.2 (skip bootstrap hộ, but provide structure documentation for 4 em main khác self-setup).**

### File tree `D:\.claude-rag\` (em pioneer SOLUTION_ERP build)

```
D:\.claude-rag\
├── bootstrap.py              (150 LOC - CLI bootstrap project corpus)
├── server.py                 (210 LOC - FastMCP entry, 6 tool handlers)
├── README.md                 (project README)
├── dashboard.html            (generated by dashboard.ps1 - DO NOT edit manually)
├── lib/
│   ├── __init__.py
│   ├── projects.py           (140 LOC - auto-detect cwd, registry tracking)
│   ├── chunking.py           (120 LOC - Markdown chunking + Anthropic Contextual Retrieval prepend)
│   ├── embed.py              (140 LOC - Voyage AI wrapper, retry exponential backoff, SHA256 cache)
│   ├── retrieval.py          (230 LOC - 3-layer pipeline: Vector + BM25 + RRF + Voyage rerank-2.5)
│   └── watcher.py            (100 LOC - Watchdog file watcher, debounce 2s — defer v1 wire)
├── scripts/
│   ├── start.ps1             (Qdrant background hidden + health check, ASCII-only)
│   ├── stop.ps1              (Graceful stop + verify, ASCII-only)
│   ├── status.ps1            (6-section full report, ASCII-only)
│   ├── dashboard.ps1         (Generate custom HTML + open browser, ASCII-only)
│   └── boot.ps1              (Auto-boot sequence: start + dashboard, used by Startup shortcut)
├── qdrant-bin/
│   ├── qdrant.exe            (88 MB v1.18.0 Windows native binary)
│   ├── qdrant-v1.18.0.zip    (download archive 28.3 MB)
│   ├── .qdrant-initialized   (marker file)
│   └── config/               (Qdrant config folder, currently empty - uses defaults)
├── data/
│   └── qdrant-storage/       (Qdrant data dir, ~85+ MB per project bootstrap)
├── logs/
│   └── qdrant-YYYYMMDD.log   (rotated daily)
└── __pycache__/              (Python bytecode cache)
```

### 8-step Bootstrap checklist cho em main project mới

```
[ ] 1. Verify infra global ready: rag-status → 3 OK (Qdrant + MCP + Voyage)
[ ] 2. Decide project_id (lowercase + underscore, UNIQUE cross 5 project)
[ ] 3. Decide sensitivity: share_to_global=true/false (client confidential check)
[ ] 4. Identify corpus_paths (default 3 + extra docs folders project-specific)
[ ] 5. Identify exclude_paths (binary, node_modules, archive, secrets)
[ ] 6. Identify extra_corpus (memory user-level path cho project Claude Code folder)
[ ] 7. Write .claude/rag.json from template §4
[ ] 8. Run: python D:\.claude-rag\bootstrap.py --project <project_id>
[ ] 9. Verify: rag-status (see new project in [Collections] section)
[ ] 10. Test query in Claude Code session: search_memory("test")
```

### Files em pioneer ĐÃ build (KHÔNG edit cross-project)

| File | Content | Owner |
|---|---|---|
| `D:\.claude-rag\server.py` | FastMCP entry + 6 tool handlers | **Em pioneer SOLUTION_ERP** (do NOT modify per-project) |
| `D:\.claude-rag\lib\*.py` | Shared library | **Em pioneer** (modify only via PR to em pioneer project) |
| `D:\.claude-rag\bootstrap.py` | CLI bootstrap script | **Em pioneer** |
| `D:\.claude-rag\scripts\*.ps1` | 5 PowerShell scripts | **Em pioneer** (em main project mới có thể customize project-specific aliases per §12) |
| `D:\.claude-rag\qdrant-bin\` | Qdrant binary | **Shared** (Windows native v1.18.0, no Docker) |
| `D:\.claude-rag\data\` | Qdrant storage | **Shared** (all collections live here) |
| `<project>\.claude\rag.json` | Per-project config | **Em main project đó** (own this file fully) |
| `dashboard.html` | Auto-generated | **dashboard.ps1 generates, DO NOT edit manually** |

### Cấu trúc stack chốt

| Component | Tool/Version | Note |
|---|---|---|
| Embedding | Voyage-4-large (1024-dim) | 200M tokens/month free tier |
| Reranker | Voyage rerank-2.5 | $0.05/1K query, 20× cheaper than Cohere |
| Vector DB | Qdrant v1.18.0 Windows native binary | No Docker, 28.3 MB binary |
| BM25 | SQLite FTS5 (unicode61 + remove_diacritics 2) | Built-in to SQLite, no Postgres |
| Fusion | RRF k=60 (Reciprocal Rank Fusion) | Industry standard |
| MCP framework | FastMCP 3.3.1 stdio | Anthropic official SDK |
| Contextual Retrieval | "From <doc_title> > <heading_path>:" prepend | Anthropic blog Sept 2024 pattern |
| Distribution | User-level Global MCP (Approach A — 1 dev N project localhost) | NO team VPS pattern |

### 4 Gotcha discoveries S26-S27 (cho project khác tránh)

1. **Qdrant Windows binary chính thức tồn tại** - GitHub release `qdrant-x86_64-pc-windows-msvc.zip` 28.3 MB. No Docker overhead.
2. **`claude mcp add` cần `--` separator** terminate variadic `-e` flag: `claude mcp add -s user -e "VOYAGE_API_KEY=$VK" -- rag-unified python "D:\.claude-rag\server.py"`. Em pioneer trial 5 lần fail trước khi tìm ra fix.
3. **Qdrant batch upsert WinError 10053** với batch > 64 chunks → fix bằng `UPSERT_BATCH = 64` trong `lib/retrieval.py`.
4. **Qdrant Windows binary KHÔNG bundled Web UI static files** (S27 discovery 2026-05-22) — `qdrant.exe` log warn `Static content folder for Web UI './static' does not exist` + `http://localhost:6333/dashboard` returns 404. **Fix:** Download separate `dist-qdrant.zip` từ https://github.com/qdrant/qdrant-web-ui/releases/latest (6.59 MB v0.2.12) + extract vào `D:\.claude-rag\qdrant-bin\static\` (flatten `dist/` subfolder up to `static/` root level so `index.html` ở `static\index.html`). Restart Qdrant → native dashboard work HTTP 200 "UI | Qdrant".
   ```powershell
   $url = "https://github.com/qdrant/qdrant-web-ui/releases/download/v0.2.12/dist-qdrant.zip"
   Invoke-WebRequest -Uri $url -OutFile "D:\.claude-rag\qdrant-bin\dist-qdrant.zip"
   Expand-Archive -Path "D:\.claude-rag\qdrant-bin\dist-qdrant.zip" -DestinationPath "D:\.claude-rag\qdrant-bin\static" -Force
   # Flatten dist/ up to static/ root:
   Get-ChildItem "D:\.claude-rag\qdrant-bin\static\dist" | Move-Item -Destination "D:\.claude-rag\qdrant-bin\static" -Force
   Remove-Item "D:\.claude-rag\qdrant-bin\static\dist" -Force
   rag-restart
   ```

### PowerShell gotcha (per memory `feedback_node_cicd.md` cousin)

- **ASCII-only trong .ps1 source** - PowerShell 5.1 fragile với UTF-8 BOM. Em pioneer trial fail 2x với `✓ → âœ"` mangling. Replace ALL unicode trong code source bằng ASCII (`[OK]`, `[FAIL]`, `->`, `*`, `!`). HTML output unicode OK (file save UTF-8 + browser charset declare).
- **Bash shell KHÔNG inherit User-scope env var từ PowerShell parent** - workaround: `VK=$(powershell -NoProfile -Command "...")` mỗi Bash command + `export VOYAGE_API_KEY="$VK"`

---

## Cross-ref

- `feedback_rag_distributed_ownership.md` (memory user-level) - Decision Approach B + Option 4a rationale full
- `feedback_rag_hybrid_pattern.md` (memory user-level) - Stack architecture chốt S26 + 7 gotcha discoveries
- `feedback_multi_agent_setup.md` (memory user-level) - 4 sub-agent decision gate
- `feedback_md_compact_narrative.md` (memory user-level) - §6.5 KEEP narrative rule cho bootstrap chunking strategy
- `.claude/agents/README.md` (SOLUTION_ERP) - master coordination guide template cho project mới adopt
- Anthropic Contextual Retrieval - https://www.anthropic.com/news/contextual-retrieval
- FastMCP docs - https://fastmcp.com
- Qdrant Windows release - https://github.com/qdrant/qdrant/releases

---

## Changelog

- **2026-05-22** v1.0 chốt S27 em main SOLUTION_ERP + bro pqhuy. Initial release. 13 sections + §A2 cấu trúc chuẩn em pioneer (replace Plan A.2 skip bootstrap hộ).
- Future versions update khi 4 em main project khác feedback usage real.