sp-rag 0.6.7 → 0.6.9

package/README.md

@@ -1,275 +1,301 @@
-# `sp-rag`
-
-CLI để setup nhanh SP-RAG theo hướng dev-friendly:
-
-- lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias
-- cài MCP config đúng format cho từng client
-- cài native skill / rule / custom agent cho từng IDE khi có convention ổn định
-- kiểm tra nhanh health và observability của stack
-- gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
-- đọc docs đã render
-- chạy evaluation/regression suite từ file JSON
-
-## Yêu cầu
-
-- Node.js `>= 20`
-
-## Trạng thái package
-
-- package npm public: `sp-rag`
-- version đang publish: `0.6.7`
-- binary public: `sp-rag`
-
-## Cài từ source trong monorepo
-
-```bash
-cd apps/sp-rag-cli
-npm install
-npm test -- --run
-npm run build
-node dist/index.js doctor
-```
-
-## Cài nhanh qua `npx`
-
-```bash
-npx sp-rag@latest install --client codex --mcp-token <grc_pat_...> --doctor
-npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-npx sp-rag@latest add --client claude-code --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest explain --client vscode --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest token add --token <grc_pat_...>
-npx sp-rag@latest token verify --token <grc_pat_...>
-npx sp-rag@latest mcp add antigravity
-npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest skill install --client cursor --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest skill install --client vscode --scope project --cwd D:/Webs/seo-booster
-```
-
-Tương đương bằng `npm`:
-
-```bash
-npm exec --yes sp-rag@latest install -- --client codex --mcp-token <grc_pat_...> --doctor
-npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd D:/Webs/seo-booster
-npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd D:/Webs/seo-booster
-npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
-npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
-```
-
-## Flow gọn cho dev
-
-Flow khuyên dùng sau khi đã có `grc_pat_*`:
-
-1. chạy `install` đúng một lần cho client đầu tiên, có kèm `--mcp-token`
-2. từ lần sau, dùng `add --client ...` để cài thêm MCP + skill cho client khác mà không phải nhập lại token
-3. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
-4. khi đổi token, chỉ cần `token add`
-5. khi muốn kiểm tra máy đang được cấu hình ra sao, dùng `explain`
-
-Ghi chú:
-
-- với `cursor` và `vscode` ở `scope project`, nếu Sếpp đang đứng sẵn trong repo thì có thể bỏ `--cwd`
-- CLI sẽ tự dùng thư mục hiện tại cho cả MCP lẫn skill
-- rule/agent mới đã được tăng độ ưu tiên MCP-first, giảm khả năng model nhảy thẳng sang grep/read file local
-- skill mới cũng dặn model tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`; không bê nguyên `answer_brief`
-
-Ví dụ:
-
-```bash
-sp-rag install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...> --doctor
-sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag mcp add antigravity
-sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag token add --token <grc_pat_moi>
-sp-rag explain --client vscode --scope project --cwd D:/Webs/seo-booster
-```
-
-## Lấy token ở đâu
-
-`sp-rag` public bây giờ dùng token gắn với tài khoản thật trên server.
-
-Luồng chuẩn:
-
-1. đăng nhập dashboard hoặc API account của GraphRAG
-2. tạo `personal access token` qua account hiện tại
-3. dùng chính token `grc_pat_*` đó cho MCP và CLI
-4. kiểm tra token bằng `sp-rag token verify`
-
-Điểm quan trọng:
-
-- token dev dùng cho MCP nên là `grc_pat_*` của account
-- quyền nhìn thấy tool/resource trên MCP bám theo role của account đó
-- `viewer`, `operator`, `approver`, `admin` sẽ thấy inventory khác nhau
-- `MCP_SERVER_ACCESS_TOKENS_JSON` chỉ còn là fallback legacy/break-glass, không còn là luồng chính cho dev
-- khi client đã có sẵn một alias trỏ cùng MCP endpoint, CLI sẽ ưu tiên cập nhật alias đó thay vì tạo alias mới song song
-
-Tự tạo PAT bằng API hiện có:
-
-1. lấy session token qua `POST /v1/account/login`
-2. gọi `POST /v1/account/personal-access-tokens`
-3. dùng trường `generated_token`
-
-Ví dụ đầy đủ:
-
-```bash
-curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
-  -H "Content-Type: application/json" \
-  -d '{"email":"dev@example.com","password":"<mật-khẩu>"}'
-```
-
-Lấy `session_token`, rồi gọi tiếp:
-
-```bash
-curl -X POST https://sp-rag.secomapp.com/api/v1/account/personal-access-tokens \
-  -H "Authorization: Bearer <grc_sess_...>" \
-  -H "Content-Type: application/json" \
-  -d '{"label":"SP-RAG CLI","expires_in_days":30}'
-```
-
-Response sẽ trả `generated_token`, chính là token `grc_pat_*` để đưa vào `sp-rag`.
-
-Ví dụ dev dùng token trực tiếp:
-
-```bash
-npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
-npx sp-rag@latest token verify --token <grc_pat_...>
-npx sp-rag@latest explain --client cursor --scope project --cwd D:/Webs/seo-booster
-```
-
-Hoặc dùng biến môi trường:
-
-```bash
-$env:GRAPHRAG_MCP_TOKEN="<grc_pat_...>"
-npx sp-rag@latest mcp add vscode --scope project --cwd D:/Webs/seo-booster --auth-env-var GRAPHRAG_MCP_TOKEN
-npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN
-```
-
-## MCP client được hỗ trợ
-
-- `codex`
-- `cursor`
-- `claude-code`
-- `antigravity`
-- `vscode`
-- `opencode`
-
-## Skill client được hỗ trợ
-
-- `codex` -> `SKILL.md`
-- `claude-code` -> `SKILL.md`
-- `antigravity` -> `SKILL.md`
-- `opencode` -> `SKILL.md`
-- `cursor` -> `.cursor/rules/sp-rag.mdc`
-- `vscode` -> `.github/agents/sp-rag.agent.md` + `.github/copilot-instructions.md` hoặc `~/.copilot/agents/sp-rag.agent.md` + `~/.copilot/instructions/sp-rag.instructions.md`
-
-Ghi chú:
-
-- generated skill luôn được render bằng tiếng Anh
-- `cursor` hiện nên dùng `scope project` cho rule `.mdc`
-- `vscode` hỗ trợ cả `scope project` lẫn `scope global`
-- nếu không muốn lưu token literal vào file config client, dùng `sp-rag mcp add --auth-env-var SP_RAG_MCP_TOKEN`
-
-## Path mặc định quan trọng
-
-### MCP
-
-- `codex`: `~/.codex/config.toml`
-- `cursor` project: `.cursor/mcp.json`
-- `cursor` global: `~/.cursor/mcp.json`
-- `claude-code`: `.mcp.json`
-- `antigravity`: `~/.gemini/antigravity/mcp_config.json`
-- `vscode` project: `.vscode/mcp.json`
-- `vscode` global: file `mcp.json` trong user profile của VS Code
-- `opencode` project: `opencode.json`
-- `opencode` global: `~/.config/opencode/opencode.json`
-
-### Skill / rule / custom agent
-
-- `codex`: `~/.codex/skills/sp-rag/SKILL.md`
-- `claude-code`: `~/.claude/skills/sp-rag/SKILL.md`
-- `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md`
-- `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md`
-- `cursor` project: `.cursor/rules/sp-rag.mdc`
-- `vscode` project: `.github/agents/sp-rag.agent.md` và `.github/copilot-instructions.md`
-- `vscode` global: `~/.copilot/agents/sp-rag.agent.md` và `~/.copilot/instructions/sp-rag.instructions.md`
-
-## Luồng khuyên dùng cho dev mới
-
-```bash
-sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
-sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag explain --client codex
-sp-rag token add --token <grc_pat_...>
-sp-rag token verify --token <grc_pat_...>
-sp-rag config show
-sp-rag codegraph status
-sp-rag codegraph watch --interval-ms 2000
-sp-rag codegraph runs --limit 5
-sp-rag codegraph metrics
-sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-sp-rag mcp add antigravity
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --client codex
-sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag eval run --file ./examples/eval-suite.sample.json
-```
-
-## Lệnh chính
-
-```bash
-sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
-sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag explain --client codex
-sp-rag token add --token <grc_pat_...>
-sp-rag token verify --token <grc_pat_...>
-sp-rag config show
-sp-rag doctor
-sp-rag codegraph status
-sp-rag codegraph watch --interval-ms 2000
-sp-rag codegraph runs --limit 10
-sp-rag codegraph metrics
-sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token webhook codegraph> --gitlab-job-token <ci-job-token>
-sp-rag docs get public --format md
-sp-rag mcp add codex
-sp-rag mcp add antigravity
-sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --client codex
-sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag eval run --file ./examples/eval-suite.sample.json
-sp-rag update setup --client codex
-```
-
-## Cấu hình mặc định
-
-CLI lưu cấu hình tại:
-
-- `~/.sp-rag/config.json`
-- có thể override home dir bằng `SP_RAG_HOME_DIR`
-
-CLI có thể lưu thêm:
-
-- `mcpToken` cho flow cài nhanh
-- `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal
-- `defaultClient`, `defaultScope`, `skillClient`
-
-Giá trị mặc định:
-
-- base URL: `https://sp-rag.secomapp.com`
-- MCP URL: `https://sp-rag.secomapp.com/mcp`
-- alias MCP: `sp-rag`
-
-## Evaluation mẫu
-
-- file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json)
-
-## Tài liệu thêm
-
-- [Hướng dẫn dev sử dụng SP-RAG](../../docs/runbooks/dev-usage-guide.md)
-- [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md)
-- [Runbook phát hành CLI `sp-rag`](../../docs/runbooks/sp-rag-cli-release.md)
-- [Runbook MCP Public](../../docs/runbooks/mcp-public-clients.md)
+# `sp-rag`
+
+CLI để setup nhanh SP-RAG theo hướng dev-friendly:
+
+- lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias
+- cài MCP config đúng format cho từng client
+- cài native skill / rule / custom agent cho từng IDE khi có convention ổn định
+- kiểm tra nhanh health và observability của stack
+- gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
+- đọc docs đã render
+- chạy evaluation/regression suite từ file JSON
+
+## Yêu cầu
+
+- Node.js `>= 20`
+
+## Trạng thái package
+
+- package npm public: `sp-rag`
+- version đang publish: `0.6.7`
+- binary public: `sp-rag`
+
+## Cài từ source trong monorepo
+
+```bash
+cd apps/sp-rag-cli
+npm install
+npm test -- --run
+npm run build
+node dist/index.js doctor
+```
+
+## Cài nhanh qua `npx`
+
+```bash
+npx sp-rag@latest install --client codex --mcp-token <grc_pat_...> --doctor
+npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
+npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
+npx sp-rag@latest add --client claude-code --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest explain --client vscode --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest token add --token <grc_pat_...>
+npx sp-rag@latest token verify --token <grc_pat_...>
+npx sp-rag@latest mcp add antigravity
+npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+```
+
+Tương đương bằng `npm`:
+
+```bash
+npm exec --yes sp-rag@latest install -- --client codex --mcp-token <grc_pat_...> --doctor
+npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd D:/Webs/seo-booster
+npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd D:/Webs/seo-booster
+npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
+npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
+```
+
+## Flow gọn cho dev
+
+Flow khuyên dùng sau khi đã có `grc_pat_*`:
+
+1. chạy `install` đúng một lần cho client đầu tiên, có kèm `--mcp-token`
+2. từ lần sau, dùng `add --client ...` để cài thêm MCP + skill cho client khác mà không phải nhập lại token
+3. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
+4. khi đổi token, chỉ cần `token add`
+5. khi muốn kiểm tra máy đang được cấu hình ra sao, dùng `explain`
+
+Ghi chú:
+
+- với `cursor` và `vscode` ở `scope project`, nếu Sếpp đang đứng sẵn trong repo thì có thể bỏ `--cwd`
+- CLI sẽ tự dùng thư mục hiện tại cho cả MCP lẫn skill
+- rule/agent mới đã được tăng độ ưu tiên MCP-first, giảm khả năng model nhảy thẳng sang grep/read file local
+- skill mới cũng dặn model tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`; không bê nguyên `answer_brief`
+
+Ví dụ:
+
+```bash
+sp-rag install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...> --doctor
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add antigravity
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag token add --token <grc_pat_moi>
+sp-rag explain --client vscode --scope project --cwd D:/Webs/seo-booster
+```
+
+## Lấy token ở đâu
+
+`sp-rag` public bây giờ dùng token gắn với tài khoản thật trên server.
+
+Luồng chuẩn:
+
+1. đăng nhập dashboard hoặc API account của GraphRAG
+2. tạo `personal access token` qua account hiện tại
+3. dùng chính token `grc_pat_*` đó cho MCP và CLI
+4. kiểm tra token bằng `sp-rag token verify`
+
+Điểm quan trọng:
+
+- token dev dùng cho MCP nên là `grc_pat_*` của account
+- quyền nhìn thấy tool/resource trên MCP bám theo role của account đó
+- `viewer`, `operator`, `approver`, `admin` sẽ thấy inventory khác nhau
+- `MCP_SERVER_ACCESS_TOKENS_JSON` chỉ còn là fallback legacy/break-glass, không còn là luồng chính cho dev
+- khi client đã có sẵn một alias trỏ cùng MCP endpoint, CLI sẽ ưu tiên cập nhật alias đó thay vì tạo alias mới song song
+
+Tự tạo PAT bằng API hiện có:
+
+1. lấy session token qua `POST /v1/account/login`
+2. gọi `POST /v1/account/personal-access-tokens`
+3. dùng trường `generated_token`
+
+Ví dụ đầy đủ:
+
+```bash
+curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"dev@example.com","password":"<mật-khẩu>"}'
+```
+
+Lấy `session_token`, rồi gọi tiếp:
+
+```bash
+curl -X POST https://sp-rag.secomapp.com/api/v1/account/personal-access-tokens \
+  -H "Authorization: Bearer <grc_sess_...>" \
+  -H "Content-Type: application/json" \
+  -d '{"label":"SP-RAG CLI","expires_in_days":30}'
+```
+
+Response sẽ trả `generated_token`, chính là token `grc_pat_*` để đưa vào `sp-rag`.
+
+Ví dụ dev dùng token trực tiếp:
+
+```bash
+npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <grc_pat_...>
+npx sp-rag@latest token verify --token <grc_pat_...>
+npx sp-rag@latest explain --client cursor --scope project --cwd D:/Webs/seo-booster
+```
+
+Hoặc dùng biến môi trường:
+
+```bash
+$env:GRAPHRAG_MCP_TOKEN="<grc_pat_...>"
+npx sp-rag@latest mcp add vscode --scope project --cwd D:/Webs/seo-booster --auth-env-var GRAPHRAG_MCP_TOKEN
+npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN
+```
+
+## MCP client được hỗ trợ
+
+- `codex`
+- `cursor`
+- `claude-code`
+- `antigravity`
+- `vscode`
+- `opencode`
+
+## Skill client được hỗ trợ
+
+- `codex` -> `SKILL.md`
+- `claude-code` -> `SKILL.md`
+- `antigravity` -> `SKILL.md`
+- `opencode` -> `SKILL.md`
+- `cursor` -> `.cursor/rules/sp-rag.mdc`
+- `vscode` -> `.github/agents/sp-rag.agent.md` + `.github/copilot-instructions.md` hoặc `~/.copilot/agents/sp-rag.agent.md` + `~/.copilot/instructions/sp-rag.instructions.md`
+
+Ghi chú:
+
+- generated skill luôn được render bằng tiếng Anh
+- `cursor` hiện nên dùng `scope project` cho rule `.mdc`
+- `vscode` hỗ trợ cả `scope project` lẫn `scope global`
+- nếu không muốn lưu token literal vào file config client, dùng `sp-rag mcp add --auth-env-var SP_RAG_MCP_TOKEN`
+
+## Path mặc định quan trọng
+
+### MCP
+
+- `codex`: `~/.codex/config.toml`
+- `cursor` project: `.cursor/mcp.json`
+- `cursor` global: `~/.cursor/mcp.json`
+- `claude-code`: `.mcp.json`
+- `antigravity`: `~/.gemini/antigravity/mcp_config.json`
+- `vscode` project: `.vscode/mcp.json`
+- `vscode` global: file `mcp.json` trong user profile của VS Code
+- `opencode` project: `opencode.json`
+- `opencode` global: `~/.config/opencode/opencode.json`
+
+### Skill / rule / custom agent
+
+- `codex`: `~/.codex/skills/sp-rag/SKILL.md`
+- `claude-code`: `~/.claude/skills/sp-rag/SKILL.md`
+- `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md`
+- `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md`
+- `cursor` project: `.cursor/rules/sp-rag.mdc`
+- `vscode` project: `.github/agents/sp-rag.agent.md` và `.github/copilot-instructions.md`
+- `vscode` global: `~/.copilot/agents/sp-rag.agent.md` và `~/.copilot/instructions/sp-rag.instructions.md`
+
+## Luồng khuyên dùng cho dev mới
+
+```bash
+sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag explain --client codex
+sp-rag token add --token <grc_pat_...>
+sp-rag token verify --token <grc_pat_...>
+sp-rag config show
+sp-rag codegraph status
+sp-rag codegraph watch --interval-ms 2000
+sp-rag codegraph runs --limit 5
+sp-rag codegraph metrics
+sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
+sp-rag mcp add antigravity
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client codex
+sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag eval run --file ./examples/eval-suite.sample.json
+```
+
+## Lệnh chính
+
+```bash
+sp-rag install --client codex --mcp-token <grc_pat_...> --doctor
+sp-rag add --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag explain --client codex
+sp-rag token add --token <grc_pat_...>
+sp-rag token verify --token <grc_pat_...>
+sp-rag config show
+sp-rag doctor
+sp-rag codegraph status
+sp-rag codegraph watch --interval-ms 2000
+sp-rag codegraph runs --limit 10
+sp-rag codegraph metrics
+sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
+sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token webhook codegraph> --gitlab-job-token <ci-job-token>
+sp-rag docs get public --format md
+sp-rag mcp add codex
+sp-rag mcp add antigravity
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client codex
+sp-rag skill install --client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag eval run --file ./examples/eval-suite.sample.json
+sp-rag update setup --client codex
+```
+
+## `doctor` kiểm gì
+
+`sp-rag doctor` giờ kiểm 2 lớp:
+
+- ping các endpoint `api`, `mcp`, `codegraph`
+- đọc đúng file MCP của client để kiểm:
+  - IDE đang nhìn vào file nào
+  - server entry nào được match theo alias hoặc theo endpoint
+  - `Authorization` đang là token literal, env var hợp lệ, hay đang thiếu
+  - khả năng IDE sẽ bật link đăng nhập OAuth
+
+Ví dụ:
+
+```bash
+sp-rag doctor --client vscode --scope project --cwd D:/Webs/seo-booster
+```
+
+Nếu output có dòng:
+
+```text
+- Authorization: thiếu hoàn toàn
+- Khả năng IDE bật link đăng nhập: cao
+```
+
+thì vấn đề thường không nằm ở skill, mà ở chỗ IDE chưa nạp được bearer header từ file MCP thực tế.
+
+## Cấu hình mặc định
+
+CLI lưu cấu hình tại:
+
+- `~/.sp-rag/config.json`
+- có thể override home dir bằng `SP_RAG_HOME_DIR`
+
+CLI có thể lưu thêm:
+
+- `mcpToken` cho flow cài nhanh
+- `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal
+- `defaultClient`, `defaultScope`, `skillClient`
+
+Giá trị mặc định:
+
+- base URL: `https://sp-rag.secomapp.com`
+- MCP URL: `https://sp-rag.secomapp.com/mcp`
+- alias MCP: `sp-rag`
+
+## Evaluation mẫu
+
+- file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json)
+
+## Tài liệu thêm
+
+- [Hướng dẫn dev sử dụng SP-RAG](../../docs/runbooks/dev-usage-guide.md)
+- [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md)
+- [Runbook phát hành CLI `sp-rag`](../../docs/runbooks/sp-rag-cli-release.md)
+- [Runbook MCP Public](../../docs/runbooks/mcp-public-clients.md)

package/dist/cli.js

@@ -2,9 +2,21 @@ import { readFile } from 'node:fs/promises';
 import { loadCliConfig, saveCliConfig, } from './lib/config-store.js';
 import { runEvaluationSuite } from './lib/eval.js';
 import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, resolveMcpConfigPath, } from './lib/mcp-config.js';
+import { diagnoseMcpConfig, formatMcpDoctorResult } from './lib/doctor.js';
 import { fetchJson, fetchText, runDoctor } from './lib/http.js';
 import { installSkill, resolveSkillInstallTarget, } from './lib/skill.js';
-const cliVersion = '0.6.7';
+let cliVersionPromise;
+async function resolveCliVersion() {
+    if (!cliVersionPromise) {
+        cliVersionPromise = readFile(new URL('../package.json', import.meta.url), 'utf8')
+            .then((raw) => {
+            const packageJson = JSON.parse(raw);
+            return packageJson.version?.trim() || '0.0.0';
+        })
+            .catch(() => '0.0.0');
+    }
+    return cliVersionPromise;
+}
 function parseArgv(argv) {
     const positionals = [];
     const options = {};
@@ -177,28 +189,28 @@ function resolveAuthForMcp(parsed, defaults) {
     };
 }
 function helpText() {
-    return `sp-rag - CLI cho setup, MCP, codegraph, eval và skill của SP-RAG
-
-Lệnh chính:
-  sp-rag install --client codex|cursor|claude-code|antigravity|vscode|opencode [--base-url URL] [--mcp-url URL] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH] [--doctor]
-  sp-rag add --client codex|cursor|claude-code|antigravity|vscode|opencode [--scope global|project] [--cwd PATH] [--target-dir PATH]
-  sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
-  sp-rag token add --token TOKEN
-  sp-rag token verify [--token TOKEN] [--base-url URL]
-  sp-rag config show
-  sp-rag explain [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
-  sp-rag doctor [--base-url URL]
-  sp-rag codegraph status [--base-url URL]
-  sp-rag codegraph watch [--base-url URL] [--interval-ms N] [--max-polls N]
-  sp-rag codegraph runs [--base-url URL] [--limit N]
-  sp-rag codegraph metrics [--base-url URL]
-  sp-rag codegraph recover [--base-url URL] [--reason TEXT]
-  sp-rag codegraph sync [--base-url URL] [--branch BRANCH] [--commit-sha SHA] [--force] [--webhook-token TOKEN] [--gitlab-job-token TOKEN]
-  sp-rag docs get <public|function|dev> [--base-url URL] [--format md|json|html]
-  sp-rag mcp add <codex|cursor|claude-code|antigravity|vscode|opencode> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
-  sp-rag skill install [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
-  sp-rag eval run --file eval-suite.json [--base-url URL]
-  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
+    return `sp-rag - CLI cho setup, MCP, codegraph, eval và skill của SP-RAG
+
+Lệnh chính:
+  sp-rag install --client codex|cursor|claude-code|antigravity|vscode|opencode [--base-url URL] [--mcp-url URL] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH] [--doctor]
+  sp-rag add --client codex|cursor|claude-code|antigravity|vscode|opencode [--scope global|project] [--cwd PATH] [--target-dir PATH]
+  sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag token add --token TOKEN
+  sp-rag token verify [--token TOKEN] [--base-url URL]
+  sp-rag config show
+  sp-rag explain [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
+  sp-rag doctor [--base-url URL] [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
+  sp-rag codegraph status [--base-url URL]
+  sp-rag codegraph watch [--base-url URL] [--interval-ms N] [--max-polls N]
+  sp-rag codegraph runs [--base-url URL] [--limit N]
+  sp-rag codegraph metrics [--base-url URL]
+  sp-rag codegraph recover [--base-url URL] [--reason TEXT]
+  sp-rag codegraph sync [--base-url URL] [--branch BRANCH] [--commit-sha SHA] [--force] [--webhook-token TOKEN] [--gitlab-job-token TOKEN]
+  sp-rag docs get <public|function|dev> [--base-url URL] [--format md|json|html]
+  sp-rag mcp add <codex|cursor|claude-code|antigravity|vscode|opencode> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
+  sp-rag skill install [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
+  sp-rag eval run --file eval-suite.json [--base-url URL]
+  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
 `;
 }
 function buildCliConfig(defaults) {
@@ -375,6 +387,28 @@ async function runSkillInstall(parsed, defaults, explicitClient) {
 async function saveResolvedConfig(defaults) {
     return saveCliConfig(buildCliConfig(defaults), defaults.homeDir);
 }
+async function emitDoctorReport(parsed, defaults, explicitClient, checks) {
+    const results = checks ?? (await runDoctor({ baseUrl: defaults.baseUrl }));
+    for (const result of results) {
+        process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
+    }
+    const client = resolveSelectedClient(parsed, defaults, explicitClient);
+    if (!client) {
+        process.stdout.write('INFO  doctor  bỏ qua chẩn đoán file MCP vì chưa xác định được client.\n');
+        return undefined;
+    }
+    const mcpDiagnostic = await diagnoseMcpConfig({
+        client,
+        url: defaults.mcpUrl,
+        serverAlias: defaults.serverAlias,
+        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
+        cwd: optionString(parsed, 'cwd'),
+    });
+    for (const line of formatMcpDoctorResult(mcpDiagnostic)) {
+        process.stdout.write(`${line}\n`);
+    }
+    return mcpDiagnostic;
+}
 async function runClientSetup(parsed, defaults, client) {
     const nextDefaults = deriveDefaultsForClient(parsed, defaults, client);
     const configPath = await saveResolvedConfig(nextDefaults);
@@ -386,10 +420,7 @@ async function runClientSetup(parsed, defaults, client) {
         await runSkillInstall(parsed, nextDefaults, client);
     }
     if (optionFlag(parsed, 'doctor')) {
-        const results = await runDoctor({ baseUrl: nextDefaults.baseUrl });
-        for (const result of results) {
-            process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
-        }
+        await emitDoctorReport(parsed, nextDefaults, client);
     }
 }
 async function runInit(parsed) {
@@ -405,10 +436,7 @@ async function runInit(parsed) {
         await runSkillInstall(parsed, nextDefaults, client);
     }
     if (optionFlag(parsed, 'doctor')) {
-        const results = await runDoctor({ baseUrl: nextDefaults.baseUrl });
-        for (const result of results) {
-            process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
-        }
+        await emitDoctorReport(parsed, nextDefaults, client);
     }
 }
 async function runInstall(parsed) {
@@ -560,7 +588,7 @@ export async function runCli(argv) {
     const [group, action] = parsed.positionals;
     try {
         if (optionFlag(parsed, 'version')) {
-            process.stdout.write(`sp-rag ${cliVersion}\n`);
+            process.stdout.write(`sp-rag ${await resolveCliVersion()}\n`);
             return 0;
         }
         if (!group || group === 'help' || group === '--help') {
@@ -597,13 +625,16 @@ export async function runCli(argv) {
         }
         if (group === 'doctor') {
             const defaults = await loadRuntimeDefaults(parsed);
-            const results = await runDoctor({
-                baseUrl: defaults.baseUrl,
-            });
-            for (const result of results) {
-                process.stdout.write(`${result.ok ? 'OK' : 'FAIL'}  ${result.name}  ${result.status}  ${result.url}\n`);
+            const results = await runDoctor({ baseUrl: defaults.baseUrl });
+            const mcpDiagnostic = await emitDoctorReport(parsed, defaults, undefined, results);
+            if (!mcpDiagnostic) {
+                return results.every((result) => result.ok) ? 0 : 1;
             }
-            return results.every((result) => result.ok) ? 0 : 1;
+            return results.every((result) => result.ok) &&
+                mcpDiagnostic.entryFound &&
+                !mcpDiagnostic.likelyOAuthLogin
+                ? 0
+                : 1;
         }
         if (group === 'codegraph' && action === 'status') {
             const defaults = await loadRuntimeDefaults(parsed);
@@ -655,7 +686,7 @@ export async function runCli(argv) {
             return 0;
         }
         if (group === 'version') {
-            process.stdout.write(`sp-rag ${cliVersion}\n`);
+            process.stdout.write(`sp-rag ${await resolveCliVersion()}\n`);
             return 0;
         }
         process.stdout.write(helpText());

package/dist/lib/doctor.js

@@ -0,0 +1,275 @@
+import { readFile } from 'node:fs/promises';
+import { resolveMcpConfigPath, } from './mcp-config.js';
+function normalizeEndpoint(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed ? trimmed.replace(/\/+$/, '') : undefined;
+}
+function parseJsonEntries(raw, client) {
+    const parsed = JSON.parse(raw);
+    let sectionKey = 'mcpServers';
+    let endpointKey = 'url';
+    if (client === 'vscode') {
+        sectionKey = 'servers';
+    }
+    else if (client === 'opencode') {
+        sectionKey = 'mcp';
+    }
+    else if (client === 'antigravity') {
+        endpointKey = 'serverUrl';
+    }
+    const section = parsed[sectionKey] && typeof parsed[sectionKey] === 'object'
+        ? parsed[sectionKey]
+        : {};
+    return Object.entries(section).flatMap(([alias, value]) => {
+        if (!value || typeof value !== 'object') {
+            return [];
+        }
+        const entry = value;
+        const headers = parseStringHeaders(entry.headers);
+        return [
+            {
+                alias,
+                endpoint: normalizeEndpoint(entry[endpointKey]),
+                headers,
+                oauth: entry.oauth,
+            },
+        ];
+    });
+}
+function parseStringHeaders(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const headers = {};
+    for (const [key, headerValue] of Object.entries(value)) {
+        if (typeof headerValue === 'string') {
+            headers[key] = headerValue;
+        }
+    }
+    return Object.keys(headers).length > 0 ? headers : undefined;
+}
+function parseTomlEntries(raw) {
+    const entries = new Map();
+    let currentAlias;
+    let currentSection;
+    for (const originalLine of raw.split(/\r?\n/)) {
+        const line = originalLine.trim();
+        if (!line || line.startsWith('#')) {
+            continue;
+        }
+        const headersMatch = line.match(/^\[mcp_servers\.(?:"([^"]+)"|([^\].]+))\.headers\]$/);
+        if (headersMatch) {
+            currentAlias = headersMatch[1] || headersMatch[2];
+            currentSection = 'headers';
+            if (!entries.has(currentAlias)) {
+                entries.set(currentAlias, { alias: currentAlias });
+            }
+            continue;
+        }
+        const serverMatch = line.match(/^\[mcp_servers\.(?:"([^"]+)"|([^\].]+))\]$/);
+        if (serverMatch) {
+            currentAlias = serverMatch[1] || serverMatch[2];
+            currentSection = 'server';
+            if (!entries.has(currentAlias)) {
+                entries.set(currentAlias, { alias: currentAlias });
+            }
+            continue;
+        }
+        if (!currentAlias || !currentSection) {
+            continue;
+        }
+        const keyValueMatch = line.match(/^([A-Za-z0-9_-]+)\s*=\s*"(.+)"$/);
+        if (!keyValueMatch) {
+            continue;
+        }
+        const [, key, value] = keyValueMatch;
+        const entry = entries.get(currentAlias) ?? { alias: currentAlias };
+        if (currentSection === 'server' && key === 'url') {
+            entry.endpoint = normalizeEndpoint(value);
+        }
+        if (currentSection === 'headers') {
+            entry.headers = {
+                ...(entry.headers ?? {}),
+                [key]: value,
+            };
+        }
+        entries.set(currentAlias, entry);
+    }
+    return [...entries.values()];
+}
+function findEntry(entries, serverAlias, targetUrl) {
+    const byAlias = entries.find((entry) => entry.alias === serverAlias);
+    if (byAlias) {
+        return {
+            entry: byAlias,
+            matchedBy: 'alias',
+        };
+    }
+    const normalizedTarget = normalizeEndpoint(targetUrl);
+    if (!normalizedTarget) {
+        return {};
+    }
+    const byEndpoint = entries.find((entry) => entry.endpoint === normalizedTarget);
+    if (byEndpoint) {
+        return {
+            entry: byEndpoint,
+            matchedBy: 'endpoint',
+        };
+    }
+    return {};
+}
+function analyzeAuthorization(headerValue) {
+    if (!headerValue?.trim()) {
+        return {
+            authorizationState: 'missing',
+            likelyOAuthLogin: true,
+        };
+    }
+    const trimmed = headerValue.trim();
+    const envStylePatterns = [
+        /\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/,
+        /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/,
+        /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/,
+    ];
+    for (const pattern of envStylePatterns) {
+        const match = trimmed.match(pattern);
+        if (!match) {
+            continue;
+        }
+        const envVar = match[1];
+        const envValue = process.env[envVar]?.trim();
+        return {
+            authorizationState: envValue ? 'env-present' : 'env-missing',
+            authorizationSource: 'env',
+            authorizationEnvVar: envVar,
+            likelyOAuthLogin: !envValue,
+        };
+    }
+    if (/^Bearer\s+\S+/i.test(trimmed)) {
+        return {
+            authorizationState: 'present',
+            authorizationSource: 'literal',
+            likelyOAuthLogin: false,
+        };
+    }
+    return {
+        authorizationState: 'invalid',
+        likelyOAuthLogin: true,
+    };
+}
+function entriesForClient(raw, client) {
+    if (client === 'codex') {
+        return parseTomlEntries(raw);
+    }
+    return parseJsonEntries(raw, client);
+}
+export async function diagnoseMcpConfig(options) {
+    const resolved = resolveMcpConfigPath({
+        client: options.client,
+        url: options.url,
+        serverAlias: options.serverAlias,
+        scope: options.scope,
+        cwd: options.cwd,
+    });
+    const baseResult = {
+        client: options.client,
+        path: resolved.path,
+        scope: resolved.scope,
+        exists: false,
+        entryFound: false,
+        authorizationState: 'missing',
+        likelyOAuthLogin: true,
+        issues: [],
+    };
+    let raw = '';
+    try {
+        raw = await readFile(resolved.path, 'utf8');
+    }
+    catch (error) {
+        return {
+            ...baseResult,
+            issues: [
+                `Không đọc được file MCP tại ${resolved.path}: ${error instanceof Error ? error.message : String(error)}`,
+            ],
+        };
+    }
+    const entries = entriesForClient(raw, options.client);
+    const { entry, matchedBy } = findEntry(entries, options.serverAlias, options.url);
+    if (!entry) {
+        return {
+            ...baseResult,
+            exists: true,
+            issues: [
+                `Không tìm thấy server MCP alias ${options.serverAlias} hoặc endpoint ${options.url} trong file config.`,
+            ],
+        };
+    }
+    const authorization = analyzeAuthorization(entry.headers?.Authorization ?? entry.headers?.authorization);
+    const issues = [...baseResult.issues];
+    if (authorization.authorizationState === 'missing') {
+        issues.push('Thiếu Authorization header. IDE rất dễ rơi sang luồng đăng nhập OAuth.');
+    }
+    else if (authorization.authorizationState === 'env-missing') {
+        issues.push(`Authorization đang dùng biến môi trường ${authorization.authorizationEnvVar} nhưng biến này chưa có giá trị trong phiên hiện tại.`);
+    }
+    else if (authorization.authorizationState === 'invalid') {
+        issues.push('Authorization header có định dạng lạ, IDE có thể bỏ qua và bật OAuth.');
+    }
+    const oauthDisabled = options.client === 'opencode' && typeof entry.oauth === 'boolean'
+        ? entry.oauth === false
+        : undefined;
+    if (options.client === 'opencode' && authorization.authorizationState !== 'missing' && oauthDisabled !== true) {
+        issues.push('OpenCode chưa có oauth=false dù đã cấu hình Authorization header.');
+    }
+    return {
+        ...baseResult,
+        exists: true,
+        entryFound: true,
+        matchedAlias: entry.alias,
+        matchedBy,
+        endpoint: entry.endpoint,
+        oauthDisabled,
+        issues,
+        ...authorization,
+    };
+}
+export function formatMcpDoctorResult(result) {
+    const lines = [
+        `MCP config cho ${result.client}: ${result.path} (${result.scope})`,
+    ];
+    if (!result.exists) {
+        lines.push(`- Trạng thái file: thiếu hoặc không đọc được`);
+        for (const issue of result.issues) {
+            lines.push(`- Cảnh báo: ${issue}`);
+        }
+        return lines;
+    }
+    lines.push(`- Trạng thái file: đã đọc được`);
+    lines.push(`- Server entry: ${result.entryFound
+        ? `${result.matchedAlias} (${result.matchedBy === 'endpoint' ? 'khớp theo endpoint' : 'khớp theo alias'})`
+        : 'không tìm thấy'}`);
+    if (result.endpoint) {
+        lines.push(`- Endpoint thực tế: ${result.endpoint}`);
+    }
+    const authText = result.authorizationState === 'present'
+        ? 'đã có bearer token literal'
+        : result.authorizationState === 'env-present'
+            ? `dùng biến môi trường ${result.authorizationEnvVar} và đang có giá trị`
+            : result.authorizationState === 'env-missing'
+                ? `dùng biến môi trường ${result.authorizationEnvVar} nhưng hiện chưa có giá trị`
+                : result.authorizationState === 'invalid'
+                    ? 'có header nhưng định dạng không hợp lệ'
+                    : 'thiếu hoàn toàn';
+    lines.push(`- Authorization: ${authText}`);
+    if (typeof result.oauthDisabled === 'boolean') {
+        lines.push(`- oauth=false: ${result.oauthDisabled ? 'có' : 'không'}`);
+    }
+    lines.push(`- Khả năng IDE bật link đăng nhập: ${result.likelyOAuthLogin ? 'cao' : 'thấp'}`);
+    for (const issue of result.issues) {
+        lines.push(`- Cảnh báo: ${issue}`);
+    }
+    return lines;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sp-rag",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "CLI cho setup MCP, codegraph GitNexus và skill của SP-RAG",
   "type": "module",
   "files": [