sp-rag 0.6.14 → 0.6.16

package/README.md

@@ -1,4 +1,20 @@
-# `sp-rag`
+# `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:
 
@@ -16,9 +32,10 @@ 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.14`
-- binary public: `sp-rag`
+- package npm public: `sp-rag`
+- version trong repo: `0.6.16`
+- npm latest hiện tại: `0.6.15`
+- binary public: `sp-rag`
 
 ## Cài từ source trong monorepo
 
@@ -32,30 +49,32 @@ 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 update --client claude-code --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest uninstall --client claude-code --scope project --cwd D:/Webs/seo-booster
-npx sp-rag@latest explain --client vscode --scope project --cwd D:/Webs/seo-booster
+```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
-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
+npx sp-rag@latest mcp add opencode --scope project --cwd <seo-booster-workspace>
+npx sp-rag@latest skill install --client cursor --scope project --cwd <seo-booster-workspace>
+npx sp-rag@latest skill install --client vscode --scope project --cwd <seo-booster-workspace>
 ```
 
 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 update -- --client claude-code --scope project --cwd D:/Webs/seo-booster
-npm exec --yes sp-rag@latest uninstall -- --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
+```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_...>
 ```
@@ -64,13 +83,14 @@ npm exec --yes sp-rag@latest token verify -- --token <grc_pat_...>
 
 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 muốn cập nhật lại MCP + skill mà giữ token cũ, dùng `update`
-4. khi muốn gỡ sạch MCP + skill + config CLI do `sp-rag` tạo, dùng `uninstall`
-5. khi chỉ muốn làm một nửa, dùng `mcp add` hoặc `skill install`
-6. khi đổi token, chỉ cần `token add`
-7. 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ú:
 
@@ -82,15 +102,16 @@ Ghi chú:
 
 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 update --client vscode --scope project --cwd D:/Webs/seo-booster
-sp-rag uninstall --client claude-code --scope project --cwd D:/Webs/seo-booster
+```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 D:/Webs/seo-booster
+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 D:/Webs/seo-booster
+sp-rag explain --client vscode --scope project --cwd <seo-booster-workspace>
 ```
 
 ## Lấy token ở đâu
@@ -137,19 +158,20 @@ 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 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
-```
+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:
 
 ```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 mcp add vscode --scope project --cwd <seo-booster-workspace> --auth-env-var GRAPHRAG_MCP_TOKEN
 npx sp-rag@latest token verify --token $env:GRAPHRAG_MCP_TOKEN
 ```
 
@@ -205,14 +227,14 @@ Ghi chú:
 
 ## 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 update --client cursor --scope project --cwd D:/Webs/seo-booster
-sp-rag uninstall --client cursor --scope project --cwd D:/Webs/seo-booster
+```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 add --token <grc_pat_...>
-sp-rag token verify --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
@@ -220,27 +242,29 @@ 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 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 D:/Webs/seo-booster
-sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+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 D:/Webs/seo-booster
-sp-rag uninstall --client vscode --scope project --cwd D:/Webs/seo-booster
+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 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
+```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
@@ -249,11 +273,11 @@ sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <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 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 D:/Webs/seo-booster
-sp-rag skill install --client vscode --scope project --cwd D:/Webs/seo-booster
+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
@@ -266,15 +290,16 @@ sp-rag uninstall --client codex
 
 - 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
+  - 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ụ:
 
 ```bash
-sp-rag doctor --client vscode --scope project --cwd D:/Webs/seo-booster
+sp-rag doctor --client vscode --scope project --cwd <seo-booster-workspace>
 ```
 
 Nếu output có dòng:
@@ -303,7 +328,55 @@ Giá trị mặc định:
 
 - base URL: `https://sp-rag.secomapp.com`
 - MCP URL: `https://sp-rag.secomapp.com/mcp`
-- alias MCP: `sp-rag`
+- 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
 
@@ -312,6 +385,7 @@ Giá trị mặc định:
 ## 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 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

@@ -1,10 +1,11 @@
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { clearCliConfig, loadCliConfig, saveCliConfig, } from './lib/config-store.js';
 import { runEvaluationSuite } from './lib/eval.js';
 import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, removeMcpConfig, resolveMcpConfigPath, } from './lib/mcp-config.js';
 import { diagnoseMcpConfig, formatMcpDoctorResult } from './lib/doctor.js';
 import { fetchJson, fetchText, runDoctor } from './lib/http.js';
-import { installSkill, removeSkill, resolveSkillInstallTarget, } from './lib/skill.js';
+import { installSkill, removeSkill, resolveSkillInstallTarget, supportedSkillName, } from './lib/skill.js';
 let cliVersionPromise;
 async function resolveCliVersion() {
     if (!cliVersionPromise) {
@@ -83,6 +84,20 @@ function supportedSkillClient(value) {
     }
     throw new Error('Skill client phải là codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
 }
+function resolveSelectedSkillName(parsed) {
+    return supportedSkillName(optionString(parsed, 'name') ??
+        optionString(parsed, 'skill-name') ??
+        optionString(parsed, 'skill'));
+}
+function withSelectedSkillName(parsed, skillName) {
+    return {
+        ...parsed,
+        options: {
+            ...parsed.options,
+            name: skillName,
+        },
+    };
+}
 function defaultSkillClientForMcpClient(client) {
     switch (client) {
         case 'codex':
@@ -110,6 +125,13 @@ function supportedScope(value) {
     }
     throw new Error('Scope phải là global hoặc project.');
 }
+function hasExplicitClientSelection(parsed, explicitClient) {
+    return Boolean(explicitClient ?? optionString(parsed, 'client') ?? parsed.positionals[2]);
+}
+function resolveScopeForSelectedClient(parsed, defaults, explicitClient) {
+    return (supportedScope(optionString(parsed, 'scope')) ??
+        (hasExplicitClientSelection(parsed, explicitClient) ? undefined : defaults.defaultScope));
+}
 async function loadRuntimeDefaults(parsed) {
     const homeDir = optionString(parsed, 'home-dir');
     const config = await loadCliConfig(homeDir);
@@ -168,7 +190,7 @@ function resolveSelectedSkillClient(parsed, defaults, client) {
 }
 function deriveDefaultsForClient(parsed, defaults, client) {
     const nextClient = client ?? defaults.defaultClient;
-    const nextScope = supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope;
+    const nextScope = resolveScopeForSelectedClient(parsed, defaults);
     const nextSkillClient = resolveSelectedSkillClient(parsed, defaults, nextClient);
     return {
         ...defaults,
@@ -194,7 +216,7 @@ function resolveAuthForMcp(parsed, defaults) {
     const authToken = validateMcpToken(optionString(parsed, 'mcp-token') ?? defaults.mcpToken);
     const authEnvVar = optionString(parsed, 'auth-env-var') ?? defaults.authEnvVar;
     if (!authToken?.trim() && !authEnvVar?.trim()) {
-        throw new Error('Chưa có token MCP trong config. Hãy chạy sp-rag install --client <client> --mcp-token <token> hoặc sp-rag token add --token <token>.');
+        throw new Error('Chưa có token MCP trong config. Hãy chạy sp-rag token add --token <token> một lần, hoặc truyền --mcp-token cho lần cài đặt này.');
     }
     return {
         authToken: authToken?.trim(),
@@ -222,10 +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 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]
+  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) {
@@ -374,7 +398,7 @@ async function runMcpAdd(parsed, defaults, explicitClient) {
     const result = await installMcpConfig({
         client,
         url: optionString(parsed, 'url') ?? defaults.mcpUrl,
-        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
+        scope: resolveScopeForSelectedClient(parsed, defaults, explicitClient),
         authEnvVar: resolveAuthForMcp(parsed, defaults).authEnvVar,
         authToken: resolveAuthForMcp(parsed, defaults).authToken,
         cwd: optionString(parsed, 'cwd'),
@@ -386,6 +410,7 @@ async function runSkillInstall(parsed, defaults, explicitClient) {
     const client = resolveSelectedSkillClient(parsed, defaults, explicitClient) ?? 'codex';
     const result = await installSkill({
         client,
+        skillName: resolveSelectedSkillName(parsed),
         cwd: optionString(parsed, 'cwd'),
         scope: supportedScope(optionString(parsed, 'scope')),
         targetDir: optionString(parsed, 'target-dir'),
@@ -415,7 +440,7 @@ async function emitDoctorReport(parsed, defaults, explicitClient, checks) {
         client,
         url: defaults.mcpUrl,
         serverAlias: defaults.serverAlias,
-        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
+        scope: resolveScopeForSelectedClient(parsed, defaults, explicitClient),
         cwd: optionString(parsed, 'cwd'),
     });
     for (const line of formatMcpDoctorResult(mcpDiagnostic)) {
@@ -462,7 +487,7 @@ async function runInstall(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
     const client = resolveSelectedClient(parsed, defaults);
     if (!client) {
-        throw new Error('Thiếu client. Dùng sp-rag install --client <client> --mcp-token <token>.');
+        throw new Error('Thiếu client. Dùng sp-rag install --client <client>.');
     }
     await runClientSetup(parsed, defaults, client);
 }
@@ -474,6 +499,15 @@ async function runAdd(parsed) {
     }
     await runClientSetup(parsed, defaults, client);
 }
+async function runAuditInstall(parsed) {
+    const auditParsed = withSelectedSkillName(parsed, 'sp-audit');
+    const defaults = await loadRuntimeDefaults(auditParsed);
+    const client = resolveSelectedClient(auditParsed, defaults);
+    if (!client) {
+        throw new Error('Thieu client. Dung sp-rag audit install --client <client>.');
+    }
+    await runClientSetup(auditParsed, defaults, client);
+}
 async function runTokenAdd(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
     const token = validateMcpToken(optionString(parsed, 'token') ?? optionString(parsed, 'mcp-token') ?? defaults.mcpToken);
@@ -510,7 +544,7 @@ async function runConfigShow(parsed) {
 async function runExplain(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
     const client = resolveSelectedClient(parsed, defaults);
-    const scope = supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope;
+    const scope = resolveScopeForSelectedClient(parsed, defaults);
     const tokenStatus = defaults.mcpToken?.trim()
         ? 'đã lưu'
         : defaults.authEnvVar?.trim()
@@ -542,6 +576,7 @@ async function runExplain(parsed) {
             if (skillClient) {
                 const skillTarget = resolveSkillInstallTarget({
                     client: skillClient,
+                    skillName: resolveSelectedSkillName(parsed),
                     scope: supportedScope(optionString(parsed, 'scope')),
                     cwd: optionString(parsed, 'cwd'),
                     targetDir: optionString(parsed, 'target-dir'),
@@ -560,7 +595,8 @@ async function runExplain(parsed) {
     lines.push('## Cách dùng chuẩn');
     if (!defaults.mcpToken?.trim() && !defaults.authEnvVar?.trim()) {
         lines.push('- Máy này chưa có token MCP. Hãy chạy:');
-        lines.push(`  sp-rag install --client ${client ?? 'vscode'} --mcp-token <token>`);
+        lines.push('  sp-rag token add --token <token>');
+        lines.push(`  sp-rag install --client ${client ?? 'vscode'}`);
     }
     else {
         const chosenClient = client ?? defaults.defaultClient ?? 'vscode';
@@ -589,6 +625,52 @@ async function runEval(parsed) {
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     return result.failed === 0 ? 0 : 1;
 }
+async function runAuditSignal(parsed) {
+    const filePath = optionString(parsed, 'file');
+    if (!filePath) {
+        throw new Error('Thieu --file tro toi JSON signal cua sp-audit.');
+    }
+    const defaults = await loadRuntimeDefaults(parsed);
+    const token = validateMcpToken(optionString(parsed, 'mcp-token') ?? defaults.mcpToken);
+    if (!token?.trim()) {
+        throw new Error('Thieu token. Dung --mcp-token <grc_pat_...> hoac sp-rag token add --token <grc_pat_...>.');
+    }
+    const raw = await readFile(filePath, 'utf8');
+    let parsedSignal;
+    try {
+        parsedSignal = JSON.parse(raw);
+    }
+    catch {
+        parsedSignal = undefined;
+    }
+    const fileName = optionString(parsed, 'file-name') ?? path.basename(filePath);
+    const externalRef = optionString(parsed, 'external-ref') ?? `sp-audit:${fileName}`;
+    const titleHint = optionString(parsed, 'title') ??
+        (typeof parsedSignal?.['flow'] === 'string'
+            ? `SP-AUDIT signal: ${parsedSignal['flow']}`
+            : 'SP-AUDIT optimization signal');
+    const params = new URLSearchParams({
+        external_ref: externalRef,
+        file_name: fileName,
+        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',
+        headers: {
+            authorization: `Bearer ${token.trim()}`,
+            'content-type': 'application/json',
+        },
+        body: raw,
+    });
+    process.stdout.write(`${JSON.stringify({
+        ok: true,
+        imported: result,
+    }, null, 2)}\n`);
+}
 async function runUpdateSetup(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
     const client = resolveSelectedClient(parsed, defaults);
@@ -616,7 +698,7 @@ async function runUninstall(parsed) {
     if (!client) {
         throw new Error('Thiếu client. Dùng sp-rag uninstall --client <client>.');
     }
-    const scope = supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope;
+    const scope = resolveScopeForSelectedClient(parsed, defaults);
     const mcpResult = await removeMcpConfig({
         client,
         url: optionString(parsed, 'url') ?? defaults.mcpUrl,
@@ -741,6 +823,14 @@ export async function runCli(argv) {
             await runSkillInstall(parsed, defaults);
             return 0;
         }
+        if (group === 'audit' && action === 'install') {
+            await runAuditInstall(parsed);
+            return 0;
+        }
+        if (group === 'audit' && action === 'signal') {
+            await runAuditSignal(parsed);
+            return 0;
+        }
         if (group === 'eval' && action === 'run') {
             return runEval(parsed);
         }

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

@@ -134,28 +134,38 @@ export function upsertCodexConfig(existing, options) {
     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

@@ -8,6 +8,20 @@ const seoBoosterProjectGuard = [
     `- Nếu basename không phải \`seo-booster\` hoặc \`sb\`, hãy kiểm tra \`git remote get-url origin\` và chỉ gọi SP-RAG khi remote hiện tại là \`${seoBoosterRemoteUrl}\`.`,
     '- Nếu project hiện tại không khớp hai điều kiện trên, không được gọi SP-RAG và phải nói rõ MCP này chỉ dành cho seo-booster.',
 ].join('\n');
+const seoBoosterReportGuard = [
+    '- Report file paths repo-relative; do not include machine-specific absolute workspace paths in answers.',
+    '- Confirm the workspace by repo basename and remote identity, not by printing a local absolute path.',
+    '- Do not grade SP-RAG, MCP, GitNexus, or codegraph quality unless the user explicitly asks for platform evaluation.',
+    '- Use MCP as supporting evidence for seo-booster; do not make MCP quality the main subject of an app review.',
+    '- Final verdict must judge the target seo-booster workflow or implementation.',
+    '- If serious bugs, missing retries, weak constraints, or missing tests are found, do not call the app flow reliable just because MCP citations matched source files.',
+    '- For user-facing flows, verify frontend entry points by searching route names, controller actions, or request payload keys.',
+    '- If the flow reads or writes database tables, open the actual model and migration or schema files.',
+    '- Only call MCP evidence stale when it cites a concrete file, symbol, or behavior that conflicts with current source.',
+    '- Treat semantic-only MCP entities as context-only evidence, not stale source evidence.',
+    '- Every high or medium risk should include repo-relative path, symbol, line range when available, and confidence.',
+    '- If external runtime behavior is not directly verified, mark that specific behavior as not verified instead of using it as strong evidence.',
+].join('\n');
 function clientLabel(client) {
     switch (client) {
         case 'codex':
@@ -38,6 +52,15 @@ function normalizeScope(client, scope) {
             return 'global';
     }
 }
+export function supportedSkillName(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === 'sp-rag' || value === 'sp-audit') {
+        return value;
+    }
+    throw new Error('Skill name phải là sp-rag hoặc sp-audit.');
+}
 function requireProjectCwd(client, cwd) {
     const resolvedCwd = cwd?.trim() ? cwd : process.cwd();
     if (!resolvedCwd.trim()) {
@@ -45,19 +68,19 @@ function requireProjectCwd(client, cwd) {
     }
     return path.resolve(resolvedCwd);
 }
-export function defaultSkillDir(client = 'codex', cwd, scope) {
+export function defaultSkillDir(client = 'codex', cwd, scope, skillName = 'sp-rag') {
     const normalizedScope = normalizeScope(client, scope);
     switch (client) {
         case 'codex':
-            return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
+            return path.join(os.homedir(), '.codex', 'skills', skillName);
         case 'claude-code':
             return normalizedScope === 'project'
-                ? path.join(requireProjectCwd(client, cwd), '.claude', 'skills', 'sp-rag')
-                : path.join(os.homedir(), '.claude', 'skills', 'sp-rag');
+                ? path.join(requireProjectCwd(client, cwd), '.claude', 'skills', skillName)
+                : path.join(os.homedir(), '.claude', 'skills', skillName);
         case 'antigravity':
-            return path.join(os.homedir(), '.gemini', 'antigravity', 'skills', 'sp-rag');
+            return path.join(os.homedir(), '.gemini', 'antigravity', 'skills', skillName);
         case 'opencode':
-            return path.join(os.homedir(), '.config', 'opencode', 'skills', 'sp-rag');
+            return path.join(os.homedir(), '.config', 'opencode', 'skills', skillName);
         case 'cursor':
             if (normalizedScope !== 'project') {
                 throw new Error('Cursor rule hiện chỉ nên cài ở scope project qua .cursor/rules.');
@@ -72,10 +95,66 @@ export function defaultSkillDir(client = 'codex', cwd, scope) {
 function renderSkillMarkdown(context) {
     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.
+description: Use SP-RAG for seo-booster codebase, feature, domain, rendered-docs, import-inventory, or codegraph freshness work that needs grounded evidence.
+---
+
+# SP-RAG
+
+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 SP-RAG whenever the request is about seo-booster codebase, features, business workflows, rendered docs, import inventory, or sync state.
+- Use this skill for seo-booster codebase, feature, business workflow, rendered docs, import inventory, and sync-state questions.
+- The operating model is MCP-grounded, workspace-verified.
+- Do not treat MCP as the only source. MCP gives context; current workspace files and git state verify the final answer.
+
+## Intent Routing
+
+- For feature, domain, architecture, workflow, docs, or "what does this do" questions: call \`${context.serverAlias}\` MCP first, usually \`query_context\`, then verify with workspace files when implementation details matter.
+- For current-code, edit, bug, failing-test, local-error, or "why is this broken right now" work: inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads, then use MCP to widen context if needed.
+- For mixed questions: get MCP context, inspect current files, compare both, then answer.
+- For docs questions, use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
+- For sync freshness and operations, use \`get_sync_status\`, \`get_sync_runs\`, and \`get_sync_metrics\`. Only use \`trigger_code_graph_sync\` when the user explicitly asks or stale evidence is the confirmed blocker.
+
+## Workspace Verification
+
+1. Run or mentally account for \`git status --short\` before relying on MCP for current behavior.
+2. If MCP cites files, inspect the current workspace version of those files when the answer depends on exact code.
+3. If changed files are related to the question, current workspace files override MCP evidence.
+4. If MCP and workspace disagree, say the graph may be stale and explain which source you are trusting.
+
+## Expand Evidence
+
+- After \`query_context\`, synthesize from \`matched_passages\`, \`top_entities\`, \`top_relations\`, \`citations\`, and \`feature_memory\` diagnostics when present.
+- Treat \`answer_brief\` as a hint only.
+- Do not stop at the first one or two MCP citations for broad feature questions.
+- 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}
+- 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-RAG
+# SP-AUDIT
 
 Target client: ${clientLabel(context.client)}
 Default MCP server alias: \`${context.serverAlias}\`
@@ -84,119 +163,243 @@ Docs URL: \`${context.docsUrl}\`
 
 ## When To Use This Skill
 
-- Use SP-RAG whenever the request is about seo-booster codebase, features, business workflows, rendered docs, import inventory, or sync state.
-- Use this skill for seo-booster codebase, feature, business workflow, rendered docs, import inventory, and sync-state questions.
-- The operating model is MCP-grounded, workspace-verified.
-- Do not treat MCP as the only source. MCP gives context; current workspace files and git state verify the final answer.
+- 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.
 
-## Intent Routing
+## Hard Boundaries
 
-- For feature, domain, architecture, workflow, docs, or "what does this do" questions: call \`${context.serverAlias}\` MCP first, usually \`query_context\`, then verify with workspace files when implementation details matter.
-- For current-code, edit, bug, failing-test, local-error, or "why is this broken right now" work: inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads, then use MCP to widen context if needed.
-- For mixed questions: get MCP context, inspect current files, compare both, then answer.
-- For docs questions, use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
-- For sync freshness and operations, use \`get_sync_status\`, \`get_sync_runs\`, and \`get_sync_metrics\`. Only use \`trigger_code_graph_sync\` when the user explicitly asks or stale evidence is the confirmed blocker.
+${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.
 
-## Workspace Verification
+## Required Input
 
-1. Run or mentally account for \`git status --short\` before relying on MCP for current behavior.
-2. If MCP cites files, inspect the current workspace version of those files when the answer depends on exact code.
-3. If changed files are related to the question, current workspace files override MCP evidence.
-4. If MCP and workspace disagree, say the graph may be stale and explain which source you are trusting.
+Before scoring, identify:
 
-## Expand Evidence
+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.
 
-- After \`query_context\`, synthesize from \`matched_passages\`, \`top_entities\`, \`top_relations\`, \`citations\`, and \`feature_memory\` diagnostics when present.
-- Treat \`answer_brief\` as a hint only.
-- Do not stop at the first one or two MCP citations for broad feature questions.
-- 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.
+If the report lacks enough evidence, score it down and say exactly what evidence is missing.
 
-## Guardrails
+## Scoring Rubric
 
-${seoBoosterProjectGuard}
-- 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.
+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) {
+    if (!markdown.startsWith('---\n')) {
+        return markdown;
+    }
+    const endIndex = markdown.indexOf('\n---\n', 4);
+    if (endIndex < 0) {
+        return 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.
-globs:
-alwaysApply: true
----
-
-# SP-RAG
-
+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.
-- 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\`.
-- Do not stop at the first one or two MCP citations for broad feature questions. Expand through related files, symbols, services, controllers, jobs, components, and tests.
-- For freshness or operational questions, check sync status, recent runs, and metrics before assuming the graph is current.
-- Only trigger codegraph sync when the user explicitly asks for it or stale evidence is the confirmed blocker.
-- If the evidence may be stale, say so clearly.
+- 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\`.
+- Do not stop at the first one or two MCP citations for broad feature questions. Expand through related files, symbols, services, controllers, jobs, components, and tests.
+- For freshness or operational questions, check sync status, recent runs, and metrics before assuming the graph is current.
+- Only trigger codegraph sync when the user explicitly asks for it or stale evidence is the confirmed blocker.
+- If the evidence may be stale, say so clearly.
+`;
+}
+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))}
 `;
 }
 function renderVsCodeAgent(context) {
     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.
+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}/*']
+---
+
+You are the SP-RAG custom agent for this workspace.
+
+Use the \`${context.serverAlias}\` MCP server at \`${context.mcpUrl}\` and the rendered docs URL \`${context.docsUrl}\` as your grounded source of truth.
+
+Route by intent before choosing tools. MCP gives the semantic map; the current workspace verifies exact code.
+
+## Recommended Workflow
+
+1. For feature, domain, architecture, workflow, docs, and "what does this do" questions, use \`query_context\` first.
+2. For current-code, edit, debug, failing-test, and local-error work, inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads.
+3. Use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
+4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` for freshness, incident review, or operational debugging.
+5. After MCP returns, verify important citations against current workspace files if the answer depends on exact implementation.
+6. Expand beyond the first one or two MCP citations for broad feature questions. Search related symbols, callers, services, controllers, jobs, routes, models, components, and tests.
+7. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
+
+## 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.
+- 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-RAG custom agent for this workspace.
+You are the SP-AUDIT custom agent for this workspace.
 
-Use the \`${context.serverAlias}\` MCP server at \`${context.mcpUrl}\` and the rendered docs URL \`${context.docsUrl}\` as your grounded source of truth.
-
-Route by intent before choosing tools. MCP gives the semantic map; the current workspace verifies exact code.
-
-## Recommended Workflow
-
-1. For feature, domain, architecture, workflow, docs, and "what does this do" questions, use \`query_context\` first.
-2. For current-code, edit, debug, failing-test, and local-error work, inspect the workspace first with \`git status --short\`, \`rg\`, and direct file reads.
-3. Use \`get_rendered_docs\` when public, function, or dev docs may already answer the question.
-4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` for freshness, incident review, or operational debugging.
-5. After MCP returns, verify important citations against current workspace files if the answer depends on exact implementation.
-6. Expand beyond the first one or two MCP citations for broad feature questions. Search related symbols, callers, services, controllers, jobs, routes, models, components, and tests.
-7. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
-
-## Guardrails
+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.
 
-${seoBoosterProjectGuard}
-- 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.
+${withoutYamlFrontmatter(renderSpAuditMarkdown(context))}
 `;
 }
 function renderVsCodeAlwaysOnInstructions(context) {
     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.
-- 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\`.
-- Treat \`answer_brief\` as a hint only, not the final answer.
-- Expand beyond the first one or two MCP citations for broad feature questions.
-- Use \`get_rendered_docs\` when rendered docs can answer the question faster than raw code inspection.
-- Only trigger codegraph sync when the user explicitly asks for it or stale graph evidence is the confirmed blocker.
-- If MCP and current workspace files disagree, say MCP may be stale and trust the current workspace for implementation details.
+- 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\`.
+- Treat \`answer_brief\` as a hint only, not the final answer.
+- Expand beyond the first one or two MCP citations for broad feature questions.
+- Use \`get_rendered_docs\` when rendered docs can answer the question faster than raw code inspection.
+- Only trigger codegraph sync when the user explicitly asks for it or stale graph evidence is the confirmed blocker.
+- If MCP and current workspace files disagree, say MCP may be stale and trust the current workspace for implementation details.
 `;
 }
 function renderSkillArtifact(context) {
+    if (context.skillName === 'sp-audit') {
+        switch (context.client) {
+            case 'cursor':
+                return {
+                    fileName: 'sp-audit.mdc',
+                    content: renderSpAuditCursorRule(context),
+                };
+            case 'vscode':
+                return {
+                    fileName: 'sp-audit.agent.md',
+                    content: renderSpAuditVsCodeAgent(context),
+                };
+            default:
+                return {
+                    fileName: 'SKILL.md',
+                    content: renderSpAuditMarkdown(context),
+                };
+        }
+    }
     switch (context.client) {
         case 'cursor':
             return {
@@ -218,6 +421,7 @@ function renderSkillArtifact(context) {
 function createSkillContext(options = {}, client) {
     return {
         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',
@@ -227,6 +431,9 @@ function resolveAdditionalSkillArtifacts(options, resolved, context) {
     if (resolved.client !== 'vscode') {
         return [];
     }
+    if (context.skillName !== 'sp-rag') {
+        return [];
+    }
     const workspaceRoot = resolved.scope === 'project'
         ? requireProjectCwd('vscode', options.cwd)
         : undefined;
@@ -243,7 +450,8 @@ function resolveAdditionalSkillArtifacts(options, resolved, context) {
 export function resolveSkillInstallTarget(options = {}) {
     const client = options.client ?? 'codex';
     const scope = normalizeScope(client, options.scope);
-    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
+    const skillName = options.skillName ?? 'sp-rag';
+    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope, skillName));
     const artifact = renderSkillArtifact(createSkillContext(options, client));
     return {
         client,
@@ -289,7 +497,10 @@ async function removeIfSpRagArtifact(filePath) {
     if (content === null) {
         return false;
     }
-    if (!content.includes('SP-RAG') && !content.includes('sp-rag')) {
+    if (!content.includes('SP-RAG') &&
+        !content.includes('sp-rag') &&
+        !content.includes('SP-AUDIT') &&
+        !content.includes('sp-audit')) {
         return false;
     }
     await rm(filePath, { force: true });

package/package.json

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