sp-rag 0.6.15 → 0.6.17

package/README.md

@@ -1,20 +1,20 @@
-# `sp-rag`
-
-## Context boundary
-
-`sp-rag` exists to connect IDEs/agents to SP-RAG evidence for the `seo-booster`
-application.
-
-- `graphrag-core` is the SP-RAG platform and knowledge runtime.
-- `seo-booster` is the target application and source workspace for app/business review.
-- `GitNexus`/codegraph references are platform internals or artifact sources, not
-  the project to review unless the task explicitly asks for codegraph debugging.
-- For project-scoped installs, use `--cwd <seo-booster-workspace>`.
-- Do not install project-scoped VS Code/Cursor/Claude config into `<graphrag-core-workspace>` when the goal is to review `seo-booster`.
-- Use `<graphrag-core-workspace>` as `--cwd` only when developing or debugging this SP-RAG platform itself.
-- `<seo-booster-workspace>` and `<graphrag-core-workspace>` are placeholders, not literal paths. Replace them with the local checkout path on each machine, or omit `--cwd` when already inside the target repo.
-
-Canonical boundary doc: [../../docs/runbooks/sp-rag-seo-booster-boundary.md](../../docs/runbooks/sp-rag-seo-booster-boundary.md)
+# `sp-rag`
+
+## Context boundary
+
+`sp-rag` exists to connect IDEs/agents to SP-RAG evidence for the `seo-booster`
+application.
+
+- `graphrag-core` is the SP-RAG platform and knowledge runtime.
+- `seo-booster` is the target application and source workspace for app/business review.
+- `GitNexus`/codegraph references are platform internals or artifact sources, not
+  the project to review unless the task explicitly asks for codegraph debugging.
+- For project-scoped installs, use `--cwd <seo-booster-workspace>`.
+- Do not install project-scoped VS Code/Cursor/Claude config into `<graphrag-core-workspace>` when the goal is to review `seo-booster`.
+- Use `<graphrag-core-workspace>` as `--cwd` only when developing or debugging this SP-RAG platform itself.
+- `<seo-booster-workspace>` and `<graphrag-core-workspace>` are placeholders, not literal paths. Replace them with the local checkout path on each machine, or omit `--cwd` when already inside the target repo.
+
+Canonical boundary doc: [../../docs/runbooks/sp-rag-seo-booster-boundary.md](../../docs/runbooks/sp-rag-seo-booster-boundary.md)
 
 CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 
@@ -33,7 +33,8 @@ CLI để setup nhanh SP-RAG theo hướng dev-friendly:
 ## Trạng thái package
 
 - package npm public: `sp-rag`
-- version đang publish: `0.6.15`
+- version trong repo: `0.6.17`
+- npm latest hiện tại: `0.6.17`
 - binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
@@ -48,15 +49,15 @@ node dist/index.js doctor
 
 ## Cài nhanh qua `npx`
 
-```bash
-npx sp-rag@latest token add --token <grc_pat_...>
-npx sp-rag@latest install --client codex --doctor
-npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
-npx sp-rag@latest install --client vscode --cwd <seo-booster-workspace>
-npx sp-rag@latest add --client claude-code --scope project --cwd <seo-booster-workspace>
-npx sp-rag@latest update --client claude-code --scope project --cwd <seo-booster-workspace>
-npx sp-rag@latest uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
-npx sp-rag@latest explain --client vscode --scope project --cwd <seo-booster-workspace>
+```bash
+npx sp-rag@latest token add --token <grc_pat_...>
+npx sp-rag@latest install --client codex --doctor
+npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
+npx sp-rag@latest install --client vscode --cwd <seo-booster-workspace>
+npx sp-rag@latest add --client claude-code --scope project --cwd <seo-booster-workspace>
+npx sp-rag@latest update --client claude-code --scope project --cwd <seo-booster-workspace>
+npx sp-rag@latest uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
+npx sp-rag@latest explain --client vscode --scope project --cwd <seo-booster-workspace>
 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
@@ -67,13 +68,13 @@ npx sp-rag@latest skill install --client vscode --scope project --cwd <seo-boost
 
 Tương đương bằng `npm`:
 
-```bash
-npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
-npm exec --yes sp-rag@latest install -- --client codex --doctor
-npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd <seo-booster-workspace>
-npm exec --yes sp-rag@latest update -- --client claude-code --scope project --cwd <seo-booster-workspace>
-npm exec --yes sp-rag@latest uninstall -- --client claude-code --scope project --cwd <seo-booster-workspace>
-npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd <seo-booster-workspace>
+```bash
+npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
+npm exec --yes sp-rag@latest install -- --client codex --doctor
+npm exec --yes sp-rag@latest add -- --client claude-code --scope project --cwd <seo-booster-workspace>
+npm exec --yes sp-rag@latest update -- --client claude-code --scope project --cwd <seo-booster-workspace>
+npm exec --yes sp-rag@latest uninstall -- --client claude-code --scope project --cwd <seo-booster-workspace>
+npm exec --yes sp-rag@latest explain -- --client vscode --scope project --cwd <seo-booster-workspace>
 npm exec --yes sp-rag@latest token add -- --token <grc_pat_...>
 npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
 ```
@@ -82,32 +83,32 @@ npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
 
 Flow khuyên dùng sau khi đã có `grc_pat_*`:
 
-1. chạy `sp-rag token add --token <grc_pat_...>` đúng một lần để lưu token
-2. chạy `install` cho client đầu tiên, không cần kèm `--mcp-token`
-3. 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
-4. khi muốn cập nhật lại MCP + skill mà giữ token cũ, dùng `update`
-5. khi muốn gỡ sạch MCP + skill + config CLI do `sp-rag` tạo, dùng `uninstall`
-6. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
-7. khi đổi token, chỉ cần `token add`
-8. khi muốn kiểm tra máy đang được cấu hình ra sao, dùng `explain`
+1. chạy `sp-rag token add --token <grc_pat_...>` đúng một lần để lưu token
+2. chạy `install` cho client đầu tiên, không cần kèm `--mcp-token`
+3. 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
+4. khi muốn cập nhật lại MCP + skill mà giữ token cũ, dùng `update`
+5. khi muốn gỡ sạch MCP + skill + config CLI do `sp-rag` tạo, dùng `uninstall`
+6. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
+7. khi đổi token, chỉ cần `token add`
+8. 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
-- `update` sẽ tự tính lại target project từ `--cwd` hoặc thư mục hiện tại, không dùng target cũ lệch project nếu user không truyền `--target-dir`
-- rule/agent mới route theo intent: feature/domain/docs thì MCP trước, còn edit/debug/current-code thì kiểm tra workspace trước
-- skill mới dùng hướng MCP-grounded + workspace-verified: tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`, không bê nguyên `answer_brief`, và đối chiếu lại `git status --short`/file hiện tại khi cần
+- 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
+- `update` sẽ tự tính lại target project từ `--cwd` hoặc thư mục hiện tại, không dùng target cũ lệch project nếu user không truyền `--target-dir`
+- rule/agent mới route theo intent: feature/domain/docs thì MCP trước, còn edit/debug/current-code thì kiểm tra workspace trước
+- skill mới dùng hướng MCP-grounded + workspace-verified: tổng hợp từ `matched_passages`, `top_entities`, `top_relations`, `citations`, không bê nguyên `answer_brief`, và đối chiếu lại `git status --short`/file hiện tại khi cần
 
 Ví dụ:
 
-```bash
-sp-rag token add --token <grc_pat_...>
-sp-rag install --client vscode --cwd <seo-booster-workspace> --doctor
-sp-rag add --client cursor --cwd <seo-booster-workspace>
-sp-rag update --client vscode --cwd <seo-booster-workspace>
-sp-rag uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
-sp-rag mcp add antigravity
+```bash
+sp-rag token add --token <grc_pat_...>
+sp-rag install --client vscode --cwd <seo-booster-workspace> --doctor
+sp-rag add --client cursor --cwd <seo-booster-workspace>
+sp-rag update --client vscode --cwd <seo-booster-workspace>
+sp-rag uninstall --client claude-code --scope project --cwd <seo-booster-workspace>
+sp-rag mcp add antigravity
 sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
 sp-rag token add --token <grc_pat_moi>
 sp-rag explain --client vscode --scope project --cwd <seo-booster-workspace>
@@ -141,7 +142,7 @@ Tự tạo PAT bằng API hiện có:
 Ví dụ đầy đủ:
 
 ```bash
-curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
+curl -X POST https://sb-rag.pielab.io/api/v1/account/login \
   -H "Content-Type: application/json" \
   -d '{"email":"dev@example.com","password":"<mật-khẩu>"}'
 ```
@@ -149,7 +150,7 @@ curl -X POST https://sp-rag.secomapp.com/api/v1/account/login \
 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 \
+curl -X POST https://sb-rag.pielab.io/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}'
@@ -157,14 +158,14 @@ curl -X POST https://sp-rag.secomapp.com/api/v1/account/personal-access-tokens \
 
 Response sẽ trả `generated_token`, chính là token `grc_pat_*` để đưa vào `sp-rag`.
 
-Ví dụ dev lưu token một lần rồi cài client:
-
-```bash
-npx sp-rag@latest token add --token <grc_pat_...>
-npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
-npx sp-rag@latest token verify --token <grc_pat_...>
-npx sp-rag@latest explain --client cursor --scope project --cwd <seo-booster-workspace>
-```
+Ví dụ dev lưu token một lần rồi cài client:
+
+```bash
+npx sp-rag@latest token add --token <grc_pat_...>
+npx sp-rag@latest install --client cursor --cwd <seo-booster-workspace>
+npx sp-rag@latest token verify --token <grc_pat_...>
+npx sp-rag@latest explain --client cursor --scope project --cwd <seo-booster-workspace>
+```
 
 Hoặc dùng biến môi trường:
 
@@ -216,8 +217,8 @@ Ghi chú:
 ### Skill / rule / custom agent
 
 - `codex`: `~/.codex/skills/sp-rag/SKILL.md`
-- `claude-code` project: `.claude/skills/sp-rag/SKILL.md`
-- `claude-code` global skill-only override: `~/.claude/skills/sp-rag/SKILL.md`
+- `claude-code` project: `.claude/skills/sp-rag/SKILL.md`
+- `claude-code` global skill-only override: `~/.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`
@@ -226,14 +227,14 @@ Ghi chú:
 
 ## Luồng khuyên dùng cho dev mới
 
-```bash
-sp-rag token add --token <grc_pat_...>
-sp-rag install --client codex --doctor
-sp-rag add --client cursor --cwd <seo-booster-workspace>
-sp-rag update --client cursor --cwd <seo-booster-workspace>
-sp-rag uninstall --client cursor --scope project --cwd <seo-booster-workspace>
-sp-rag explain --client codex
-sp-rag token verify --token <grc_pat_...>
+```bash
+sp-rag token add --token <grc_pat_...>
+sp-rag install --client codex --doctor
+sp-rag add --client cursor --cwd <seo-booster-workspace>
+sp-rag update --client cursor --cwd <seo-booster-workspace>
+sp-rag uninstall --client cursor --scope project --cwd <seo-booster-workspace>
+sp-rag explain --client codex
+sp-rag token verify --token <grc_pat_...>
 sp-rag config show
 sp-rag codegraph status
 sp-rag codegraph watch --interval-ms 2000
@@ -245,25 +246,25 @@ sp-rag mcp add vscode --scope project --cwd <seo-booster-workspace>
 sp-rag mcp add opencode --scope project --cwd <seo-booster-workspace>
 sp-rag skill install --client codex
 sp-rag skill install --client cursor --scope project --cwd <seo-booster-workspace>
-sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
-sp-rag eval run --file ./examples/eval-suite.sample.json
-sp-rag update --client vscode --scope project --cwd <seo-booster-workspace>
-sp-rag uninstall --client vscode --scope project --cwd <seo-booster-workspace>
+sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
+sp-rag eval run --file ./examples/eval-suite.sample.json
+sp-rag update --client vscode --scope project --cwd <seo-booster-workspace>
+sp-rag uninstall --client vscode --scope project --cwd <seo-booster-workspace>
 ```
 
 ## Lệnh chính
 
-```bash
-sp-rag token add --token <grc_pat_...>
-sp-rag install --client codex --doctor
-sp-rag add --client cursor --cwd <seo-booster-workspace>
-sp-rag explain --client codex
-sp-rag token verify --token <grc_pat_...>
-sp-rag config show
-sp-rag doctor
-sp-rag audit install --client codex
-sp-rag audit signal --file ./sp-audit-signal.json
-sp-rag codegraph status
+```bash
+sp-rag token add --token <grc_pat_...>
+sp-rag install --client codex --doctor
+sp-rag add --client cursor --cwd <seo-booster-workspace>
+sp-rag explain --client codex
+sp-rag token verify --token <grc_pat_...>
+sp-rag config show
+sp-rag doctor
+sp-rag audit install --client codex
+sp-rag audit signal --file ./sp-audit-signal.json
+sp-rag codegraph status
 sp-rag codegraph watch --interval-ms 2000
 sp-rag codegraph runs --limit 10
 sp-rag codegraph metrics
@@ -277,10 +278,10 @@ sp-rag mcp add opencode --scope project --cwd <seo-booster-workspace>
 sp-rag skill install --client codex
 sp-rag skill install --client cursor --scope project --cwd <seo-booster-workspace>
 sp-rag skill install --client vscode --scope project --cwd <seo-booster-workspace>
-sp-rag eval run --file ./examples/eval-suite.sample.json
-sp-rag update --client codex
-sp-rag update setup --client codex
-sp-rag uninstall --client codex
+sp-rag eval run --file ./examples/eval-suite.sample.json
+sp-rag update --client codex
+sp-rag update setup --client codex
+sp-rag uninstall --client codex
 ```
 
 ## `doctor` kiểm gì
@@ -292,6 +293,7 @@ sp-rag uninstall --client codex
   - 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
+  - riêng Codex, xác nhận `bearer_token_env_var`/`http_headers` thay vì legacy `[mcp_servers.<alias>.headers]`
   - khả năng IDE sẽ bật link đăng nhập OAuth
 
 Ví dụ:
@@ -324,53 +326,57 @@ CLI có thể lưu thêm:
 
 Giá trị mặc định:
 
-- base URL: `https://sp-rag.secomapp.com`
-- MCP URL: `https://sp-rag.secomapp.com/mcp`
-- alias MCP: `sp-rag`
-
-## Audit workflow `sp-rag audit`
-
-`sp-audit` khong phai la CLI moi. No la skill/agent workflow duoc cai bang
-CLI hien tai `sp-rag`.
-
-Lenh chuan de cai audit workflow:
-
-```bash
-sp-rag audit install --client codex
-```
-
-Lenh nay:
-
-- cai MCP config cho client da chon
-- cai native skill/rule/custom agent `sp-audit`
-- tai su dung config/token cua `sp-rag`
-- van la cung binary `sp-rag`, tuong tu `sp-rag add` hay `sp-rag doctor`
-- neu token chua duoc luu, chay `sp-rag token add --token <grc_pat_...>` mot lan truoc do
-- scope mac dinh suy theo client: `codex` la global, `cursor`/`vscode` la project
-
-Neu chi muon cai lai skill audit ma khong cham vao MCP config, co the dung
-low-level command:
-
-```bash
-sp-rag skill install --client codex --name sp-audit
-```
-
-Day JSON signal do `sp-audit` tao ra vao server memory import path:
-
-```bash
-sp-rag audit signal --file ./sp-audit-signal.json
-```
-
-Native paths cua audit workflow:
-
-- Codex: `~/.codex/skills/sp-audit/SKILL.md`
-- Claude Code: `.claude/skills/sp-audit/SKILL.md` hoac `~/.claude/skills/sp-audit/SKILL.md`
-- Antigravity: `~/.gemini/antigravity/skills/sp-audit/SKILL.md`
-- OpenCode: `~/.config/opencode/skills/sp-audit/SKILL.md`
-- Cursor: `.cursor/rules/sp-audit.mdc`
-- VS Code: `.github/agents/sp-audit.agent.md` hoac `~/.copilot/agents/sp-audit.agent.md`
-
-Chi tiet: [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.md).
+- base URL: `https://sb-rag.pielab.io`
+- MCP URL: `https://sb-rag.pielab.io/mcp`
+- alias MCP: `sp-rag`
+
+## Audit workflow `sp-rag audit`
+
+`sp-audit` khong phai la CLI moi. No la skill/agent workflow duoc cai bang
+CLI hien tai `sp-rag`.
+
+Lenh chuan de cai audit workflow:
+
+```bash
+sp-rag audit install --client codex
+```
+
+Lenh nay:
+
+- cai MCP config cho client da chon
+- cai native skill/rule/custom agent `sp-audit`
+- tai su dung config/token cua `sp-rag`
+- van la cung binary `sp-rag`, tuong tu `sp-rag add` hay `sp-rag doctor`
+- neu token chua duoc luu, chay `sp-rag token add --token <grc_pat_...>` mot lan truoc do
+- scope mac dinh suy theo client: `codex` la global, `cursor`/`vscode` la project
+
+Neu chi muon cai lai skill audit ma khong cham vao MCP config, co the dung
+low-level command:
+
+```bash
+sp-rag skill install --client codex --name sp-audit
+```
+
+Day JSON signal do `sp-audit` tao ra vao server memory import path:
+
+```bash
+sp-rag audit signal --file ./sp-audit-signal.json
+```
+
+`audit signal` posts through the existing knowledge-source import API with
+`normalizer_provider=heuristic` and `warm_cache=false`, so small audit feedback
+records do not block on AI normalization or semantic-cache materialization.
+
+Native paths cua audit workflow:
+
+- Codex: `~/.codex/skills/sp-audit/SKILL.md`
+- Claude Code: `.claude/skills/sp-audit/SKILL.md` hoac `~/.claude/skills/sp-audit/SKILL.md`
+- Antigravity: `~/.gemini/antigravity/skills/sp-audit/SKILL.md`
+- OpenCode: `~/.config/opencode/skills/sp-audit/SKILL.md`
+- Cursor: `.cursor/rules/sp-audit.mdc`
+- VS Code: `.github/agents/sp-audit.agent.md` hoac `~/.copilot/agents/sp-audit.agent.md`
+
+Chi tiet: [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.md).
 
 ## Evaluation mẫu
 
@@ -379,7 +385,7 @@ Chi tiet: [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.md).
 ## 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 `sp-rag audit`](../../docs/runbooks/sp-audit.md)
+- [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md)
+- [Runbook `sp-rag audit`](../../docs/runbooks/sp-audit.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

@@ -227,11 +227,11 @@ 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 update [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--doctor]
-  sp-rag uninstall [--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 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 update [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH] [--target-dir PATH] [--doctor]
+  sp-rag uninstall [--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
@@ -244,12 +244,12 @@ Lệnh chính:
   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 audit install --client codex|cursor|claude-code|antigravity|vscode|opencode [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH] [--doctor]
-  sp-rag audit signal --file signal.json [--mcp-token TOKEN] [--external-ref REF] [--title TEXT] [--provider builtin]
-  sp-rag eval run --file eval-suite.json [--base-url URL]
-  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--name sp-rag|sp-audit] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  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 audit install --client codex|cursor|claude-code|antigravity|vscode|opencode [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH] [--doctor]
+  sp-rag audit signal --file signal.json [--mcp-token TOKEN] [--external-ref REF] [--title TEXT] [--provider builtin]
+  sp-rag eval run --file eval-suite.json [--base-url URL]
+  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--name sp-rag|sp-audit] [--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) {
@@ -655,6 +655,8 @@ async function runAuditSignal(parsed) {
         content_type: 'application/json',
         title_hint: titleHint,
         provider: optionString(parsed, 'provider') ?? 'builtin',
+        normalizer_provider: 'heuristic',
+        warm_cache: 'false',
     });
     const result = await fetchJson(`${defaults.baseUrl.replace(/\/+$/, '')}/api/v1/import/knowledge-source/file?${params.toString()}`, {
         method: 'POST',

package/dist/lib/doctor.js

@@ -62,7 +62,16 @@ function parseTomlEntries(raw) {
         const headersMatch = line.match(/^\[mcp_servers\.(?:"([^"]+)"|([^\].]+))\.headers\]$/);
         if (headersMatch) {
             currentAlias = headersMatch[1] || headersMatch[2];
-            currentSection = 'headers';
+            currentSection = 'legacy_headers';
+            if (!entries.has(currentAlias)) {
+                entries.set(currentAlias, { alias: currentAlias });
+            }
+            continue;
+        }
+        const httpHeadersMatch = line.match(/^\[mcp_servers\.(?:"([^"]+)"|([^\].]+))\.http_headers\]$/);
+        if (httpHeadersMatch) {
+            currentAlias = httpHeadersMatch[1] || httpHeadersMatch[2];
+            currentSection = 'http_headers';
             if (!entries.has(currentAlias)) {
                 entries.set(currentAlias, { alias: currentAlias });
             }
@@ -89,12 +98,21 @@ function parseTomlEntries(raw) {
         if (currentSection === 'server' && key === 'url') {
             entry.endpoint = normalizeEndpoint(value);
         }
-        if (currentSection === 'headers') {
+        if (currentSection === 'server' && key === 'bearer_token_env_var') {
+            entry.bearerTokenEnvVar = value;
+        }
+        if (currentSection === 'http_headers') {
             entry.headers = {
                 ...(entry.headers ?? {}),
                 [key]: value,
             };
         }
+        if (currentSection === 'legacy_headers') {
+            entry.legacyHeaders = {
+                ...(entry.legacyHeaders ?? {}),
+                [key]: value,
+            };
+        }
         entries.set(currentAlias, entry);
     }
     return [...entries.values()];
@@ -186,6 +204,12 @@ function analyzeAuthorization(headerValue) {
         likelyOAuthLogin: true,
     };
 }
+function analyzeEntryAuthorization(entry) {
+    if (entry.bearerTokenEnvVar?.trim()) {
+        return analyzeAuthorization(`Bearer \${${entry.bearerTokenEnvVar.trim()}}`);
+    }
+    return analyzeAuthorization(entry.headers?.Authorization ?? entry.headers?.authorization);
+}
 function entriesForClient(raw, client) {
     if (client === 'codex') {
         return parseTomlEntries(raw);
@@ -233,8 +257,11 @@ export async function diagnoseMcpConfig(options) {
             ],
         };
     }
-    const authorization = analyzeAuthorization(entry.headers?.Authorization ?? entry.headers?.authorization);
+    const authorization = analyzeEntryAuthorization(entry);
     const issues = [...baseResult.issues];
+    if (options.client === 'codex' && entry.legacyHeaders) {
+        issues.push('Codex config đang dùng legacy [mcp_servers.<alias>.headers]. Streamable HTTP MCP cần http_headers, env_http_headers hoặc bearer_token_env_var; legacy headers có thể không expose tools.');
+    }
     if (authorization.authorizationState === 'missing') {
         issues.push('Thiếu Authorization header. IDE rất dễ rơi sang luồng đăng nhập OAuth.');
     }

package/dist/lib/mcp-config.js

@@ -124,38 +124,48 @@ export function defaultMcpServerAlias() {
     return 'sp-rag';
 }
 export function defaultMcpUrl() {
-    return process.env['SP_RAG_MCP_URL']?.trim() || 'https://sp-rag.secomapp.com/mcp';
+    return process.env['SP_RAG_MCP_URL']?.trim() || 'https://sb-rag.pielab.io/mcp';
 }
 export function defaultBaseUrl() {
-    return process.env['SP_RAG_BASE_URL']?.trim() || 'https://sp-rag.secomapp.com';
+    return process.env['SP_RAG_BASE_URL']?.trim() || 'https://sb-rag.pielab.io';
 }
 export function upsertCodexConfig(existing, options) {
     const alias = options.serverAlias.trim();
     const aliasPattern = escapeRegex(alias);
     const cleaned = existing
         .replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\.headers\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), '')
+        .replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\.http_headers\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), '')
         .replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), '')
         .trimEnd();
     const lines = [
         `[mcp_servers.${quotedTomlKey(alias)}]`,
         `url = "${options.url}"`,
     ];
-    const headers = bearerHeader(options.authToken, options.authEnvVar, 'shell');
-    if (headers?.Authorization) {
-        lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.headers]`);
-        lines.push(`Authorization = "${headers.Authorization.replace(/"/g, '\\"')}"`);
+    const literalHeaders = bearerHeader(options.authToken, undefined, 'shell');
+    if (literalHeaders?.Authorization) {
+        lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.http_headers]`);
+        lines.push(`Authorization = "${literalHeaders.Authorization.replace(/"/g, '\\"')}"`);
+    }
+    else if (options.authEnvVar?.trim()) {
+        lines.push(`bearer_token_env_var = "${options.authEnvVar.trim().replace(/"/g, '\\"')}"`);
     }
     return `${cleaned ? `${cleaned}\n\n` : ''}${lines.join('\n')}\n`;
 }
-export function removeCodexConfigContent(existing, serverAlias) {
-    const alias = serverAlias.trim();
-    const aliasPattern = escapeRegex(alias);
+function removeCodexSubtable(existing, aliasPattern, subtable) {
     let removed = false;
-    const withoutHeaders = existing.replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\.headers\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), () => {
+    const content = existing.replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\.${subtable}\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), () => {
         removed = true;
         return '';
     });
-    const cleaned = withoutHeaders.replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), () => {
+    return { content, removed };
+}
+export function removeCodexConfigContent(existing, serverAlias) {
+    const alias = serverAlias.trim();
+    const aliasPattern = escapeRegex(alias);
+    const withoutLegacyHeaders = removeCodexSubtable(existing, aliasPattern, 'headers');
+    const withoutHttpHeaders = removeCodexSubtable(withoutLegacyHeaders.content, aliasPattern, 'http_headers');
+    let removed = withoutLegacyHeaders.removed || withoutHttpHeaders.removed;
+    const cleaned = withoutHttpHeaders.content.replace(new RegExp(`(?:^|\\n)\\[mcp_servers\\.(?:"${aliasPattern}"|${aliasPattern})\\][\\s\\S]*?(?=(?:\\n\\[[^\\n]+\\])|$)`, 'g'), () => {
         removed = true;
         return '';
     });

package/dist/lib/skill.js

@@ -93,8 +93,8 @@ export function defaultSkillDir(client = 'codex', cwd, scope, skillName = 'sp-ra
     }
 }
 function renderSkillMarkdown(context) {
-    return `---
-name: sp-rag
+    return `---
+name: sp-rag
 description: Use SP-RAG for seo-booster codebase, feature, domain, rendered-docs, import-inventory, or codegraph freshness work that needs grounded evidence.
 ---
 
@@ -135,138 +135,139 @@ Docs URL: \`${context.docsUrl}\`
 - Expand through related symbols, callers, services, controllers, jobs, routes, models, components, and tests using workspace search when needed.
 - Prefer rendered docs when they answer business behavior, but verify current code before making implementation claims.
 
-## Guardrails
-
-${seoBoosterProjectGuard}
-${seoBoosterReportGuard}
-- Find root cause before fixing bugs.
-- Use evidence before conclusions; do not claim completion without verification.
-- For behavior changes, write or update tests before implementation when feasible.
+## Guardrails
+
+${seoBoosterProjectGuard}
+${seoBoosterReportGuard}
+- Codex streamable HTTP MCP config must use \`http_headers\`, \`env_http_headers\`, or \`bearer_token_env_var\`; \`[mcp_servers.<alias>.headers]\` is legacy-invalid and will not expose tools.
+- Find root cause before fixing bugs.
+- Use evidence before conclusions; do not claim completion without verification.
+- For behavior changes, write or update tests before implementation when feasible.
 - If evidence may be stale, say so clearly and mention that the graph or docs may need a refresh.
 - Do not trigger sync or import actions unless the user asked for it or the workflow truly requires it.
 - When rendered docs already answer the question, cite or summarize those docs, then check current code if the answer depends on implementation details.
 `;
 }
 function renderSpAuditMarkdown(context) {
-    return `---
-name: sp-audit
-description: Use when reviewing seo-booster or SP-RAG audit reports, scoring report quality, extracting optimization signals, or preparing admin-agent feedback loops.
----
-
-# SP-AUDIT
-
-Target client: ${clientLabel(context.client)}
-Default MCP server alias: \`${context.serverAlias}\`
-MCP URL: \`${context.mcpUrl}\`
-Docs URL: \`${context.docsUrl}\`
-
-## When To Use This Skill
-
-- Use this after an AI agent returns an audit or review report for seo-booster.
-- Use it to score the report quality, identify missing verification, and extract optimization signals.
-- Use it when the user asks to audit MCP/RAG-assisted answers, improve prompts, or make the system learn from weak reports.
-- Do not use it as a replacement for the original source audit. This skill audits the audit result.
-
-## Hard Boundaries
-
-${seoBoosterProjectGuard}
-- Do not grade SP-RAG, MCP, GitNexus, or codegraph quality unless the report explicitly evaluates platform quality.
-- If the report is supposed to audit seo-booster, the final score must judge report quality for seo-booster, not MCP quality.
-- Report file paths must be repo-relative. Do not include machine-specific absolute workspace paths in the final answer.
-- Tra loi bang tieng Viet. Keep code symbols, file paths, route names, and JSON keys unchanged.
-
-## Required Input
-
-Before scoring, identify:
-
-1. Target workflow or feature under review.
-2. Claims made by the audit report.
-3. MCP evidence the report used, if any.
-4. Workspace source evidence the report verified.
-5. Bugs, risks, tests, or gaps the report found.
-
-If the report lacks enough evidence, score it down and say exactly what evidence is missing.
-
-## Scoring Rubric
-
-Start from 100 and subtract only for concrete gaps:
-
-- Target and repo boundary: 10 points.
-- MCP usage and provenance: 10 points.
-- Source coverage across routes, controllers, services, jobs, models, database, frontend, and tests: 25 points.
-- Evidence quality with repo-relative paths, symbols, line ranges when available, and confidence: 20 points.
-- Risk quality with severity, what can go wrong, why current source suggests it, and verification limits: 15 points.
-- No overclaiming, no local absolute paths, and no accidental MCP/platform grading: 10 points.
-- Optimization signal clarity: 10 points.
-
-Verdict bands:
-
-- 90-100: pass.
-- 70-89: needs optimization.
-- 0-69: fail.
-
-## Required Output
-
-Use this exact structure:
-
-## 1. Audit score
-- Score: X/100
-- Verdict: pass | needs optimization | fail
-
-## 2. What the report did well
-
-## 3. Issues in the report
-
-## 4. Required improvements
-
-Separate improvements into:
-- Prompt or skill guardrails.
-- MCP retrieval or indexing.
-- Source-inspection checklist.
-- Tests or evaluation cases.
-
-## 5. Optimization signals for server memory
-
-Return one compact JSON object:
-
-~~~json
-{
-  "target_app": "seo-booster",
-  "flow": "short workflow name",
-  "score": 0,
-  "verdict": "pass | needs_optimization | fail",
-  "missing_checks": [],
-  "prompt_guardrail_gaps": [],
-  "mcp_retrieval_gaps": [],
-  "source_index_gaps": [],
-  "recommended_actions": [],
-  "requires_admin_agent": false
-}
-~~~
-
-## 6. Admin-agent fallback command
-
-If a dedicated server-side audit-signal ingestion endpoint is available, send the JSON signal there and mention the trace/id returned.
-
-If server-side self-evolution is not available, do not claim it happened. If token is already saved in \`sp-rag\`, tell the admin to run:
-
-\`sp-rag audit install --client <codex|cursor|claude-code|antigravity|vscode|opencode>\`
-
-If this is the first setup on the machine, save the token once with:
-
-\`sp-rag token add --token <token>\`
-
-Then run the audit install command above. The admin AI agent should use the installed \`sp-audit\` skill to review new audit outputs. To persist the JSON signal through the existing server memory import path, save the JSON object and run:
-
-\`sp-rag audit signal --file <signal.json>\`
-
-Feed the same JSON signal into the next prompt, eval suite, retrieval tuning task, or reviewed server-side memory import.
-
-## Evolution Policy
-
-- Self-evolution must be review-gated. Do not let the server silently rewrite prompts, skills, indexes, or production settings from one weak report.
-- If the same optimization signal repeats across reports, propose a durable change: prompt guardrail, skill update, eval case, retrieval query rewrite, docs import, or index refresh.
-- Prefer measurable changes: a failing eval case before prompt/retrieval changes, then a passing eval after the fix.
+    return `---
+name: sp-audit
+description: Use when reviewing seo-booster or SP-RAG audit reports, scoring report quality, extracting optimization signals, or preparing admin-agent feedback loops.
+---
+
+# SP-AUDIT
+
+Target client: ${clientLabel(context.client)}
+Default MCP server alias: \`${context.serverAlias}\`
+MCP URL: \`${context.mcpUrl}\`
+Docs URL: \`${context.docsUrl}\`
+
+## When To Use This Skill
+
+- Use this after an AI agent returns an audit or review report for seo-booster.
+- Use it to score the report quality, identify missing verification, and extract optimization signals.
+- Use it when the user asks to audit MCP/RAG-assisted answers, improve prompts, or make the system learn from weak reports.
+- Do not use it as a replacement for the original source audit. This skill audits the audit result.
+
+## Hard Boundaries
+
+${seoBoosterProjectGuard}
+- Do not grade SP-RAG, MCP, GitNexus, or codegraph quality unless the report explicitly evaluates platform quality.
+- If the report is supposed to audit seo-booster, the final score must judge report quality for seo-booster, not MCP quality.
+- Report file paths must be repo-relative. Do not include machine-specific absolute workspace paths in the final answer.
+- Tra loi bang tieng Viet. Keep code symbols, file paths, route names, and JSON keys unchanged.
+
+## Required Input
+
+Before scoring, identify:
+
+1. Target workflow or feature under review.
+2. Claims made by the audit report.
+3. MCP evidence the report used, if any.
+4. Workspace source evidence the report verified.
+5. Bugs, risks, tests, or gaps the report found.
+
+If the report lacks enough evidence, score it down and say exactly what evidence is missing.
+
+## Scoring Rubric
+
+Start from 100 and subtract only for concrete gaps:
+
+- Target and repo boundary: 10 points.
+- MCP usage and provenance: 10 points.
+- Source coverage across routes, controllers, services, jobs, models, database, frontend, and tests: 25 points.
+- Evidence quality with repo-relative paths, symbols, line ranges when available, and confidence: 20 points.
+- Risk quality with severity, what can go wrong, why current source suggests it, and verification limits: 15 points.
+- No overclaiming, no local absolute paths, and no accidental MCP/platform grading: 10 points.
+- Optimization signal clarity: 10 points.
+
+Verdict bands:
+
+- 90-100: pass.
+- 70-89: needs optimization.
+- 0-69: fail.
+
+## Required Output
+
+Use this exact structure:
+
+## 1. Audit score
+- Score: X/100
+- Verdict: pass | needs optimization | fail
+
+## 2. What the report did well
+
+## 3. Issues in the report
+
+## 4. Required improvements
+
+Separate improvements into:
+- Prompt or skill guardrails.
+- MCP retrieval or indexing.
+- Source-inspection checklist.
+- Tests or evaluation cases.
+
+## 5. Optimization signals for server memory
+
+Return one compact JSON object:
+
+~~~json
+{
+  "target_app": "seo-booster",
+  "flow": "short workflow name",
+  "score": 0,
+  "verdict": "pass | needs_optimization | fail",
+  "missing_checks": [],
+  "prompt_guardrail_gaps": [],
+  "mcp_retrieval_gaps": [],
+  "source_index_gaps": [],
+  "recommended_actions": [],
+  "requires_admin_agent": false
+}
+~~~
+
+## 6. Admin-agent fallback command
+
+If a dedicated server-side audit-signal ingestion endpoint is available, send the JSON signal there and mention the trace/id returned.
+
+If server-side self-evolution is not available, do not claim it happened. If token is already saved in \`sp-rag\`, tell the admin to run:
+
+\`sp-rag audit install --client <codex|cursor|claude-code|antigravity|vscode|opencode>\`
+
+If this is the first setup on the machine, save the token once with:
+
+\`sp-rag token add --token <token>\`
+
+Then run the audit install command above. The admin AI agent should use the installed \`sp-audit\` skill to review new audit outputs. To persist the JSON signal through the existing server memory import path, save the JSON object and run:
+
+\`sp-rag audit signal --file <signal.json>\`
+
+Feed the same JSON signal into the next prompt, eval suite, retrieval tuning task, or reviewed server-side memory import.
+
+## Evolution Policy
+
+- Self-evolution must be review-gated. Do not let the server silently rewrite prompts, skills, indexes, or production settings from one weak report.
+- If the same optimization signal repeats across reports, propose a durable change: prompt guardrail, skill update, eval case, retrieval query rewrite, docs import, or index refresh.
+- Prefer measurable changes: a failing eval case before prompt/retrieval changes, then a passing eval after the fix.
 `;
 }
 function withoutYamlFrontmatter(markdown) {
@@ -280,19 +281,19 @@ function withoutYamlFrontmatter(markdown) {
     return markdown.slice(endIndex + '\n---\n'.length);
 }
 function renderCursorRule(context) {
-    return `---
-description: Use SP-RAG when the request is about this codebase, internal business workflows, rendered docs, import inventory, or codegraph sync status.
+    return `---
+description: Use SP-RAG when the request is about this codebase, internal business workflows, rendered docs, import inventory, or codegraph sync status.
 globs:
 alwaysApply: true
 ---
 
 # SP-RAG
 
-${seoBoosterProjectGuard}
-${seoBoosterReportGuard}
-- Route by intent before choosing tools.
-- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
-- Use workspace search first for current-code, edit, bug, and test-failure work.
+${seoBoosterProjectGuard}
+${seoBoosterReportGuard}
+- Route by intent before choosing tools.
+- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
+- Use workspace search first for current-code, edit, bug, and test-failure work.
 - Verify MCP evidence against \`git status --short\` and current workspace files before making implementation claims.
 - Use rendered docs from \`${context.docsUrl}\` when documentation already answers the question.
 - Treat \`answer_brief\` only as a hint. Build the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
@@ -303,18 +304,18 @@ ${seoBoosterReportGuard}
 `;
 }
 function renderSpAuditCursorRule(context) {
-    return `---
-description: Use SP-AUDIT when reviewing seo-booster audit reports, scoring report quality, or extracting optimization signals.
-globs:
-alwaysApply: false
----
-
-${withoutYamlFrontmatter(renderSpAuditMarkdown(context))}
+    return `---
+description: Use SP-AUDIT when reviewing seo-booster audit reports, scoring report quality, or extracting optimization signals.
+globs:
+alwaysApply: false
+---
+
+${withoutYamlFrontmatter(renderSpAuditMarkdown(context))}
 `;
 }
 function renderVsCodeAgent(context) {
-    return `---
-name: SP-RAG
+    return `---
+name: SP-RAG
 description: Use this custom agent whenever the request is about this codebase, internal business workflows, rendered docs, import inventory, or codegraph sync status.
 tools: ['${context.serverAlias}/*']
 ---
@@ -337,38 +338,38 @@ Route by intent before choosing tools. MCP gives the semantic map; the current w
 
 ## Guardrails
 
-${seoBoosterProjectGuard}
-${seoBoosterReportGuard}
-- Prefer MCP-grounded evidence before answering from memory, but current workspace files override MCP evidence when they differ.
-- Treat \`answer_brief\` as a hint. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
-- When evidence may be stale, say so clearly and mention that a refresh might be needed.
+${seoBoosterProjectGuard}
+${seoBoosterReportGuard}
+- Prefer MCP-grounded evidence before answering from memory, but current workspace files override MCP evidence when they differ.
+- Treat \`answer_brief\` as a hint. Prefer the richer evidence in \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\` when writing the final answer.
+- When evidence may be stale, say so clearly and mention that a refresh might be needed.
 - Do not trigger sync or import actions unless the workflow truly requires it.
 - When rendered docs already answer the question, summarize those docs instead of rewriting everything from scratch.
 - Find root cause before fixes, write or update tests for behavior changes when feasible, and verify before claiming completion.
 `;
 }
 function renderSpAuditVsCodeAgent(context) {
-    return `---
-name: SP-AUDIT
-description: Use this custom agent to score seo-booster audit reports and extract optimization signals.
-tools: ['${context.serverAlias}/*']
----
-
-You are the SP-AUDIT custom agent for this workspace.
-
-Use the \`${context.serverAlias}\` MCP server only when you need to verify freshness, citations, rendered docs, or retrieval gaps. Your primary job is to audit the audit result.
-
-${withoutYamlFrontmatter(renderSpAuditMarkdown(context))}
+    return `---
+name: SP-AUDIT
+description: Use this custom agent to score seo-booster audit reports and extract optimization signals.
+tools: ['${context.serverAlias}/*']
+---
+
+You are the SP-AUDIT custom agent for this workspace.
+
+Use the \`${context.serverAlias}\` MCP server only when you need to verify freshness, citations, rendered docs, or retrieval gaps. Your primary job is to audit the audit result.
+
+${withoutYamlFrontmatter(renderSpAuditMarkdown(context))}
 `;
 }
 function renderVsCodeAlwaysOnInstructions(context) {
-    return `# SP-RAG workspace instructions
+    return `# SP-RAG workspace instructions
 
-${seoBoosterProjectGuard}
-${seoBoosterReportGuard}
-- Route by intent before choosing tools.
-- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
-- Use workspace inspection first for current-code, edit, debug, failing-test, and local-error work.
+${seoBoosterProjectGuard}
+${seoBoosterReportGuard}
+- Route by intent before choosing tools.
+- Use the \`${context.serverAlias}\` MCP server first for feature, domain, architecture, workflow, docs, and "what does this do" questions.
+- Use workspace inspection first for current-code, edit, debug, failing-test, and local-error work.
 - Verify MCP evidence against current workspace state, including \`git status --short\` and current file contents when implementation details matter.
 - Start with \`healthz\` only when connectivity is uncertain or the session is new.
 - When \`query_context\` returns, synthesize the final answer from \`matched_passages\`, \`top_entities\`, \`top_relations\`, and \`citations\`.
@@ -422,8 +423,8 @@ function createSkillContext(options = {}, client) {
         client: client ?? options.client ?? 'codex',
         skillName: options.skillName ?? 'sp-rag',
         serverAlias: options.serverAlias?.trim() || 'sp-rag',
-        mcpUrl: options.mcpUrl?.trim() || 'https://sp-rag.secomapp.com/mcp',
-        docsUrl: options.docsUrl?.trim() || 'https://sp-rag.secomapp.com/codegraph/docs/public?format=md',
+        mcpUrl: options.mcpUrl?.trim() || 'https://sb-rag.pielab.io/mcp',
+        docsUrl: options.docsUrl?.trim() || 'https://sb-rag.pielab.io/codegraph/docs/public?format=md',
     };
 }
 function resolveAdditionalSkillArtifacts(options, resolved, context) {

package/package.json

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