sp-rag 0.3.0 → 0.5.0

package/README.md

@@ -1,71 +1,129 @@
-# `sp-rag`
-
-CLI cho setup nhanh SP-RAG theo hướng dev-friendly:
-
-- lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias
-- kiểm tra nhanh health và observability của stack
-- gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
-- đọc docs đã render
-- cài MCP config cho client
-- cài skill để agent ưu tiên dùng RAG nội bộ
-- chạy evaluation/regression suite từ file JSON
-
-## Yêu cầu
-
-- Node.js `>= 20`
-
+# `sp-rag`
+
+CLI để setup nhanh SP-RAG theo hướng dev-friendly:
+
+- lưu cấu hình mặc định để dev không phải nhớ lại URL, client, alias
+- cài MCP config đúng format cho từng client
+- cài native skill / rule / custom agent cho từng IDE khi có convention ổn định
+- kiểm tra nhanh health và observability của stack
+- gọi sync codegraph/GitNexus theo branch hoặc `commit_sha`
+- đọc docs đã render
+- chạy evaluation/regression suite từ file JSON
+
+## Yêu cầu
+
+- Node.js `>= 20`
+
+## Trạng thái package
+
+- package npm public: `sp-rag`
+- version đang publish: `0.5.0`
+- binary public: `sp-rag`
+
 ## Cài từ source trong monorepo
 
 ```bash
 cd apps/sp-rag-cli
 npm install
+npm test -- --run
 npm run build
 node dist/index.js doctor
 ```
 
 ## Cài nhanh qua `npx`
 
-Nếu package đã được publish, luồng ngắn nhất là:
-
 ```bash
-npx sp-rag@latest install --client codex --mcp-token <token>
-npx sp-rag@latest token add --token <token> --client codex
+npx sp-rag@latest install --client codex --mcp-token <token truy cập MCP> --doctor
+npx sp-rag@latest install --client cursor --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+npx sp-rag@latest install --client vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+npx sp-rag@latest token add --token <token truy cập MCP> --client codex
+npx sp-rag@latest mcp add antigravity --mcp-token <token truy cập MCP>
+npx sp-rag@latest mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+npx sp-rag@latest skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+npx sp-rag@latest skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 ```
 
 Tương đương bằng `npm`:
 
 ```bash
-npm exec --yes sp-rag@latest install -- --client codex --mcp-token <token>
-npm exec --yes sp-rag@latest token add -- --token <token> --client codex
+npm exec --yes sp-rag@latest install -- --client codex --mcp-token <token truy cập MCP> --doctor
+npm exec --yes sp-rag@latest token add -- --token <token truy cập MCP> --client codex
 ```
 
+## MCP client được hỗ trợ
+
+- `codex`
+- `cursor`
+- `claude-code`
+- `antigravity`
+- `vscode`
+- `opencode`
+
+## Skill client được hỗ trợ
+
+- `codex` -> `SKILL.md`
+- `claude-code` -> `SKILL.md`
+- `antigravity` -> `SKILL.md`
+- `opencode` -> `SKILL.md`
+- `cursor` -> `.cursor/rules/sp-rag.mdc`
+- `vscode` -> `.github/agents/sp-rag.agent.md` hoặc `~/.copilot/agents/sp-rag.agent.md`
+
 Ghi chú:
 
-- `install` là lệnh onboarding một bước: lưu config, cài MCP config, cài skill, và có thể chạy `doctor`
-- `token add` dùng khi dev đã cài xong nhưng chưa gắn bearer token vào MCP client
+- generated skill luôn được render bằng tiếng Anh
+- `cursor` hiện nên dùng `scope project` cho rule `.mdc`
+- `vscode` hỗ trợ cả `scope project` lẫn `scope global`
 - nếu không muốn lưu token literal vào file config client, dùng `sp-rag mcp add --auth-env-var SP_RAG_MCP_TOKEN`
 
+## Path mặc định quan trọng
+
+### MCP
+
+- `codex`: `~/.codex/config.toml`
+- `cursor` project: `.cursor/mcp.json`
+- `cursor` global: `~/.cursor/mcp.json`
+- `claude-code`: `.mcp.json`
+- `antigravity`: `~/.gemini/antigravity/mcp_config.json`
+- `vscode` project: `.vscode/mcp.json`
+- `vscode` global: file `mcp.json` trong user profile của VS Code
+- `opencode` project: `opencode.json`
+- `opencode` global: `~/.config/opencode/opencode.json`
+
+### Skill / rule / custom agent
+
+- `codex`: `~/.codex/skills/sp-rag/SKILL.md`
+- `claude-code`: `~/.claude/skills/sp-rag/SKILL.md`
+- `antigravity`: `~/.gemini/antigravity/skills/sp-rag/SKILL.md`
+- `opencode`: `~/.config/opencode/skills/sp-rag/SKILL.md`
+- `cursor` project: `.cursor/rules/sp-rag.mdc`
+- `vscode` project: `.github/agents/sp-rag.agent.md`
+- `vscode` global: `~/.copilot/agents/sp-rag.agent.md`
+
 ## Luồng khuyên dùng cho dev mới
 
 ```bash
-sp-rag install --client codex --mcp-token <token> --doctor
-sp-rag token add --token <token> --client codex
+sp-rag install --client codex --mcp-token <token truy cập MCP> --doctor
+sp-rag token add --token <token truy cập MCP> --client codex
 sp-rag config show
 sp-rag codegraph status
 sp-rag codegraph watch --interval-ms 2000
 sp-rag codegraph runs --limit 5
 sp-rag codegraph metrics
 sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-sp-rag mcp add codex --mcp-token <token>
+sp-rag mcp add antigravity --mcp-token <token truy cập MCP>
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag skill install
+sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
-```
-
-## Lệnh chính
-
+```
+
+## Lệnh chính
+
 ```bash
-sp-rag install --client codex --mcp-token <token> --doctor
-sp-rag token add --token <token> --client codex
+sp-rag install --client codex --mcp-token <token truy cập MCP> --doctor
+sp-rag token add --token <token truy cập MCP> --client codex
 sp-rag config show
 sp-rag doctor
 sp-rag codegraph status
@@ -73,16 +131,21 @@ sp-rag codegraph watch --interval-ms 2000
 sp-rag codegraph runs --limit 10
 sp-rag codegraph metrics
 sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token> --gitlab-job-token <ci-job-token>
+sp-rag codegraph sync --branch master --commit-sha <sha> --webhook-token <token webhook codegraph> --gitlab-job-token <ci-job-token>
 sp-rag docs get public --format md
-sp-rag mcp add codex --mcp-token <token>
+sp-rag mcp add codex --mcp-token <token truy cập MCP>
+sp-rag mcp add antigravity --mcp-token <token truy cập MCP>
+sp-rag mcp add vscode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
+sp-rag mcp add opencode --scope project --cwd D:/Webs/seo-booster --mcp-token <token truy cập MCP>
 sp-rag skill install
+sp-rag skill install --skill-client cursor --scope project --cwd D:/Webs/seo-booster
+sp-rag skill install --skill-client vscode --scope project --cwd D:/Webs/seo-booster
 sp-rag eval run --file ./examples/eval-suite.sample.json
-sp-rag update setup --client codex
-```
-
-## Cấu hình mặc định
-
+sp-rag update setup --client codex
+```
+
+## Cấu hình mặc định
+
 CLI lưu cấu hình tại:
 
 - `~/.sp-rag/config.json`
@@ -91,48 +154,22 @@ CLI lưu cấu hình tại:
 CLI có thể lưu thêm:
 
 - `mcpToken` cho flow cài nhanh
-- hoặc `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal
-
-Giá trị mặc định:
-
-- base URL: `https://sp-rag.secomapp.com`
-- MCP URL: `https://sp-rag.secomapp.com/mcp`
-- alias MCP: `sp-rag`
-
-Override nhanh bằng env:
-
-```bash
-SP_RAG_BASE_URL=https://sp-rag.secomapp.com
-SP_RAG_MCP_URL=https://sp-rag.secomapp.com/mcp
-SP_RAG_HOME_DIR=D:/Temp/sp-rag-home
-```
-
-## Evaluation mẫu
-
-- file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json)
-
-## Recovery khi sync bị treo
-
-Nếu worker crash giữa chừng, `codegraph-ts` sẽ tự đổi run `running` cũ sang `failed` ở lần truy cập đầu tiên sau khi service lên lại. Khi ops muốn dọn tay hoặc gắn lý do vận hành rõ ràng hơn, dùng:
+- `authEnvVar` nếu muốn client đọc token từ biến môi trường thay vì lưu literal
+- `defaultClient`, `defaultScope`, `skillClient`
 
-```bash
-sp-rag codegraph recover --reason "Ops dọn stale run sau crash"
-```
+Giá trị mặc định:
 
-CLI này gọi `POST /codegraph/sync-recover-stale` và trả lại danh sách run vừa được chuyển sang `failed`.
+- base URL: `https://sp-rag.secomapp.com`
+- MCP URL: `https://sp-rag.secomapp.com/mcp`
+- alias MCP: `sp-rag`
 
-## Theo dõi active
-
-Khi một sync đang chạy và ops muốn biết phase hiện tại theo thời gian thực, dùng:
+## Evaluation mẫu
 
-```bash
-sp-rag codegraph watch --interval-ms 2000
-```
+- file mẫu: [`examples/eval-suite.sample.json`](./examples/eval-suite.sample.json)
 
-CLI sẽ in liên tục `lastStatus`, `activity.currentPhase`, `progressPercentHint`, `elapsed` và `message`.
-
 ## Tài liệu thêm
 
 - [Hướng dẫn dev sử dụng SP-RAG](../../docs/runbooks/dev-usage-guide.md)
 - [Runbook CLI `sp-rag`](../../docs/runbooks/sp-rag-cli.md)
+- [Runbook phát hành CLI `sp-rag`](../../docs/runbooks/sp-rag-cli-release.md)
 - [Runbook MCP Public](../../docs/runbooks/mcp-public-clients.md)

package/dist/cli.js

@@ -3,7 +3,7 @@ import { loadCliConfig, saveCliConfig, } from './lib/config-store.js';
 import { runEvaluationSuite } from './lib/eval.js';
 import { defaultBaseUrl, defaultMcpServerAlias, defaultMcpUrl, installMcpConfig, } from './lib/mcp-config.js';
 import { fetchJson, fetchText, runDoctor } from './lib/http.js';
-import { installCodexSkill } from './lib/skill.js';
+import { installSkill, } from './lib/skill.js';
 function parseArgv(argv) {
     const positionals = [];
     const options = {};
@@ -42,10 +42,47 @@ function supportedClient(value) {
     if (!value) {
         return undefined;
     }
-    if (value === 'codex' || value === 'cursor' || value === 'claude-code') {
+    if (value === 'codex' ||
+        value === 'cursor' ||
+        value === 'claude-code' ||
+        value === 'antigravity' ||
+        value === 'vscode' ||
+        value === 'opencode') {
         return value;
     }
-    throw new Error('Client phải là codex, cursor hoặc claude-code.');
+    throw new Error('Client phải là codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
+}
+function supportedSkillClient(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (value === 'codex' ||
+        value === 'cursor' ||
+        value === 'claude-code' ||
+        value === 'antigravity' ||
+        value === 'vscode' ||
+        value === 'opencode') {
+        return value;
+    }
+    throw new Error('Skill client phải là codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
+}
+function defaultSkillClientForMcpClient(client) {
+    switch (client) {
+        case 'codex':
+            return 'codex';
+        case 'cursor':
+            return 'cursor';
+        case 'claude-code':
+            return 'claude-code';
+        case 'antigravity':
+            return 'antigravity';
+        case 'vscode':
+            return 'vscode';
+        case 'opencode':
+            return 'opencode';
+        default:
+            return undefined;
+    }
 }
 function supportedScope(value) {
     if (!value) {
@@ -90,6 +127,9 @@ async function loadRuntimeDefaults(parsed) {
             optionString(parsed, 'token') ??
             process.env['SP_RAG_MCP_TOKEN']?.trim() ??
             config?.mcpToken,
+        skillClient: supportedSkillClient(optionString(parsed, 'skill-client')) ??
+            config?.skillClient ??
+            defaultSkillClientForMcpClient(defaultClient),
         skillTargetDir: optionString(parsed, 'target-dir') ?? config?.skillTargetDir,
     };
 }
@@ -97,9 +137,9 @@ function helpText() {
     return `sp-rag - CLI cho setup, MCP, codegraph, eval và skill của SP-RAG
 
 Lệnh chính:
-  sp-rag install [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code] [--scope global|project] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--target-dir PATH]
-  sp-rag init [--base-url URL] [--mcp-url URL] [--client codex|cursor|claude-code] [--scope global|project] [--auth-env-var ENV_VAR] [--target-dir PATH]
-  sp-rag token add --token TOKEN [--client codex|cursor|claude-code] [--scope global|project] [--cwd PATH]
+  sp-rag install [--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] [--mcp-token TOKEN] [--auth-env-var ENV_VAR] [--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 [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--cwd PATH]
   sp-rag config show
   sp-rag doctor [--base-url URL]
   sp-rag codegraph status [--base-url URL]
@@ -109,10 +149,10 @@ 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> [--url URL] [--scope global|project] [--auth-env-var ENV_VAR] [--mcp-token TOKEN]
-  sp-rag skill install [--target-dir PATH] [--mcp-url URL] [--docs-url URL]
+  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 [--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] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
+  sp-rag update setup [--client codex|cursor|claude-code|antigravity|vscode|opencode] [--skill-client codex|cursor|claude-code|antigravity|vscode|opencode] [--scope global|project] [--url URL] [--auth-env-var ENV_VAR] [--target-dir PATH]
 `;
 }
 function buildCliConfig(defaults) {
@@ -124,6 +164,7 @@ function buildCliConfig(defaults) {
         defaultScope: defaults.defaultScope,
         authEnvVar: defaults.authEnvVar,
         mcpToken: defaults.mcpToken,
+        skillClient: defaults.skillClient,
         skillTargetDir: defaults.skillTargetDir,
         docsUrl: defaults.docsUrl,
     };
@@ -256,7 +297,7 @@ async function runDocsGet(parsed) {
 async function runMcpAdd(parsed, defaults, explicitClient) {
     const client = supportedClient(explicitClient ?? parsed.positionals[2] ?? defaults.defaultClient);
     if (!client) {
-        throw new Error('Thiếu client. Dùng codex, cursor hoặc claude-code.');
+        throw new Error('Thiếu client. Dùng codex, cursor, claude-code, antigravity, vscode hoặc opencode.');
     }
     const result = await installMcpConfig({
         client,
@@ -270,13 +311,19 @@ async function runMcpAdd(parsed, defaults, explicitClient) {
     process.stdout.write(`Đã cập nhật cấu hình MCP cho ${result.client} tại ${result.path} (${result.scope}).\n`);
 }
 async function runSkillInstall(parsed, defaults) {
-    const result = await installCodexSkill({
+    const client = supportedSkillClient(optionString(parsed, 'skill-client')) ??
+        defaults.skillClient ??
+        'codex';
+    const result = await installSkill({
+        client,
+        cwd: optionString(parsed, 'cwd'),
+        scope: supportedScope(optionString(parsed, 'scope')) ?? defaults.defaultScope,
         targetDir: optionString(parsed, 'target-dir') ?? defaults.skillTargetDir,
         serverAlias: optionString(parsed, 'server-alias') ?? defaults.serverAlias,
         mcpUrl: optionString(parsed, 'mcp-url') ?? defaults.mcpUrl,
         docsUrl: optionString(parsed, 'docs-url') ?? defaults.docsUrl,
     });
-    process.stdout.write(`Đã cài Codex skill tại ${result.path}\n`);
+    process.stdout.write(`Đã cài skill cho ${result.client} tại ${result.path}\n`);
 }
 async function runInit(parsed) {
     const defaults = await loadRuntimeDefaults(parsed);
@@ -286,7 +333,7 @@ async function runInit(parsed) {
     if (!optionFlag(parsed, 'skip-mcp') && defaults.defaultClient) {
         await runMcpAdd(parsed, defaults, defaults.defaultClient);
     }
-    if (!optionFlag(parsed, 'skip-skill')) {
+    if (!optionFlag(parsed, 'skip-skill') && defaults.skillClient) {
         await runSkillInstall(parsed, defaults);
     }
     if (optionFlag(parsed, 'doctor')) {
@@ -356,7 +403,7 @@ async function runUpdateSetup(parsed) {
             positionals: ['mcp', 'add', client],
         }, defaults, client);
     }
-    if (!optionFlag(parsed, 'skip-skill')) {
+    if (!optionFlag(parsed, 'skip-skill') && defaults.skillClient) {
         await runSkillInstall(parsed, defaults);
     }
 }
@@ -444,7 +491,7 @@ export async function runCli(argv) {
             return 0;
         }
         if (group === 'version') {
-            process.stdout.write('sp-rag 0.3.0\n');
+            process.stdout.write('sp-rag 0.5.0\n');
             return 0;
         }
         process.stdout.write(helpText());

package/dist/lib/mcp-config.js

@@ -7,6 +7,64 @@ function escapeRegex(value) {
 function quotedTomlKey(value) {
     return `"${value.replace(/"/g, '\\"')}"`;
 }
+function parseJsonObject(existing) {
+    return existing?.trim() ? JSON.parse(existing) : {};
+}
+function withHeaders(target, headers) {
+    if (!headers) {
+        return target;
+    }
+    return {
+        ...target,
+        headers,
+    };
+}
+function bearerHeader(authToken, authEnvVar, envStyle = 'shell') {
+    const trimmedToken = authToken?.trim();
+    if (trimmedToken) {
+        return {
+            Authorization: `Bearer ${trimmedToken}`,
+        };
+    }
+    const trimmedEnvVar = authEnvVar?.trim();
+    if (!trimmedEnvVar) {
+        return undefined;
+    }
+    switch (envStyle) {
+        case 'vscode':
+            return {
+                Authorization: `Bearer \${env:${trimmedEnvVar}}`,
+            };
+        case 'opencode':
+            return {
+                Authorization: `Bearer {env:${trimmedEnvVar}}`,
+            };
+        default:
+            return {
+                Authorization: `Bearer \${${trimmedEnvVar}}`,
+            };
+    }
+}
+function upsertObjectEntry(base, sectionKey, entryKey, entryValue) {
+    const section = base[sectionKey] && typeof base[sectionKey] === 'object'
+        ? { ...base[sectionKey] }
+        : {};
+    section[entryKey] = entryValue;
+    return {
+        ...base,
+        [sectionKey]: section,
+    };
+}
+function vscodeGlobalConfigPath(home) {
+    if (process.platform === 'win32') {
+        const appData = process.env['APPDATA']?.trim() || path.join(home, 'AppData', 'Roaming');
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(home, 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    return path.join(home, '.config', 'Code', 'User', 'mcp.json');
+}
 export function defaultMcpServerAlias() {
     return 'sp-rag';
 }
@@ -27,54 +85,60 @@ export function upsertCodexConfig(existing, options) {
         `[mcp_servers.${quotedTomlKey(alias)}]`,
         `url = "${options.url}"`,
     ];
-    const authToken = options.authToken?.trim();
-    const authEnvVar = options.authEnvVar?.trim();
-    if (authToken) {
-        lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.headers]`);
-        lines.push(`Authorization = "Bearer ${authToken.replace(/"/g, '\\"')}"`);
-    }
-    else if (authEnvVar) {
+    const headers = bearerHeader(options.authToken, options.authEnvVar, 'shell');
+    if (headers?.Authorization) {
         lines.push('', `[mcp_servers.${quotedTomlKey(alias)}.headers]`);
-        lines.push(`Authorization = "Bearer \${${authEnvVar}}"`);
+        lines.push(`Authorization = "${headers.Authorization.replace(/"/g, '\\"')}"`);
     }
     return `${cleaned ? `${cleaned}\n\n` : ''}${lines.join('\n')}\n`;
 }
 export function upsertJsonMcpConfig(existing, options) {
-    const base = existing?.trim()
-        ? JSON.parse(existing)
-        : {};
-    const mcpServers = base['mcpServers'] && typeof base['mcpServers'] === 'object'
-        ? { ...base['mcpServers'] }
-        : {};
-    const serverConfig = {
+    const base = parseJsonObject(existing);
+    const serverConfig = withHeaders({
+        ...(options.includeTypeHttp ? { type: 'http' } : {}),
         url: options.url,
-    };
-    if (options.includeTypeHttp) {
-        serverConfig['type'] = 'http';
-    }
-    const authToken = options.authToken?.trim();
-    const authEnvVar = options.authEnvVar?.trim();
-    if (authToken) {
-        serverConfig['headers'] = {
-            Authorization: `Bearer ${authToken}`,
-        };
-    }
-    else if (authEnvVar) {
-        serverConfig['headers'] = {
-            Authorization: `Bearer \${${authEnvVar}}`,
+    }, bearerHeader(options.authToken, options.authEnvVar, 'shell'));
+    return `${JSON.stringify(upsertObjectEntry(base, 'mcpServers', options.serverAlias, serverConfig), null, 2)}\n`;
+}
+export function upsertAntigravityConfig(existing, options) {
+    const base = parseJsonObject(existing);
+    const serverConfig = withHeaders({
+        serverUrl: options.url,
+    }, bearerHeader(options.authToken, options.authEnvVar, 'shell'));
+    return `${JSON.stringify(upsertObjectEntry(base, 'mcpServers', options.serverAlias, serverConfig), null, 2)}\n`;
+}
+export function upsertVsCodeConfig(existing, options) {
+    const base = parseJsonObject(existing);
+    const serverConfig = withHeaders({
+        type: 'http',
+        url: options.url,
+    }, bearerHeader(options.authToken, options.authEnvVar, 'vscode'));
+    return `${JSON.stringify(upsertObjectEntry(base, 'servers', options.serverAlias, serverConfig), null, 2)}\n`;
+}
+export function upsertOpenCodeConfig(existing, options) {
+    const base = parseJsonObject(existing);
+    const headers = bearerHeader(options.authToken, options.authEnvVar, 'opencode');
+    const nextBase = typeof base['$schema'] === 'string'
+        ? base
+        : {
+            ...base,
+            $schema: 'https://opencode.ai/config.json',
         };
-    }
-    mcpServers[options.serverAlias] = serverConfig;
-    return `${JSON.stringify({
-        ...base,
-        mcpServers,
-    }, null, 2)}\n`;
+    const serverConfig = withHeaders({
+        type: 'remote',
+        url: options.url,
+        enabled: true,
+        ...(headers ? { oauth: false } : {}),
+    }, headers);
+    return `${JSON.stringify(upsertObjectEntry(nextBase, 'mcp', options.serverAlias, serverConfig), null, 2)}\n`;
 }
 export function resolveMcpConfigPath(options) {
-    const scope = options.scope ??
-        (options.client === 'codex' ? 'global' : 'project');
-    if (options.client === 'codex' && scope !== 'global') {
-        throw new Error('Codex hiện chỉ hỗ trợ scope global trong CLI này.');
+    const inferredScope = options.client === 'codex' || options.client === 'antigravity'
+        ? 'global'
+        : 'project';
+    const scope = options.scope ?? inferredScope;
+    if ((options.client === 'codex' || options.client === 'antigravity') && scope !== 'global') {
+        throw new Error(`${options.client} hiện chỉ hỗ trợ scope global trong CLI này.`);
     }
     if (options.client === 'claude-code' && scope !== 'project') {
         throw new Error('Claude Code hiện chỉ hỗ trợ scope project trong CLI này.');
@@ -102,6 +166,26 @@ export function resolveMcpConfigPath(options) {
                 scope,
                 path: path.join(cwd, '.mcp.json'),
             };
+        case 'antigravity':
+            return {
+                client: options.client,
+                scope,
+                path: path.join(home, '.gemini', 'antigravity', 'mcp_config.json'),
+            };
+        case 'vscode':
+            return {
+                client: options.client,
+                scope,
+                path: scope === 'global' ? vscodeGlobalConfigPath(home) : path.join(cwd, '.vscode', 'mcp.json'),
+            };
+        case 'opencode':
+            return {
+                client: options.client,
+                scope,
+                path: scope === 'global'
+                    ? path.join(home, '.config', 'opencode', 'opencode.json')
+                    : path.join(cwd, 'opencode.json'),
+            };
     }
 }
 export async function installMcpConfig(options) {
@@ -109,20 +193,58 @@ export async function installMcpConfig(options) {
     const existing = await readFile(resolved.path, 'utf8').catch(() => '');
     const alias = options.serverAlias?.trim() || defaultMcpServerAlias();
     const url = options.url.trim();
-    const content = resolved.client === 'codex'
-        ? upsertCodexConfig(existing, {
-            serverAlias: alias,
-            url,
-            authEnvVar: options.authEnvVar,
-            authToken: options.authToken,
-        })
-        : upsertJsonMcpConfig(existing, {
-            serverAlias: alias,
-            url,
-            authEnvVar: options.authEnvVar,
-            authToken: options.authToken,
-            includeTypeHttp: resolved.client === 'claude-code',
-        });
+    let content;
+    switch (resolved.client) {
+        case 'codex':
+            content = upsertCodexConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+            });
+            break;
+        case 'cursor':
+            content = upsertJsonMcpConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+            });
+            break;
+        case 'claude-code':
+            content = upsertJsonMcpConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+                includeTypeHttp: true,
+            });
+            break;
+        case 'antigravity':
+            content = upsertAntigravityConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+            });
+            break;
+        case 'vscode':
+            content = upsertVsCodeConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+            });
+            break;
+        case 'opencode':
+            content = upsertOpenCodeConfig(existing, {
+                serverAlias: alias,
+                url,
+                authEnvVar: options.authEnvVar,
+                authToken: options.authToken,
+            });
+            break;
+    }
     await mkdir(path.dirname(resolved.path), { recursive: true });
     await writeFile(resolved.path, content, 'utf8');
     return resolved;

package/dist/lib/skill.js

@@ -1,51 +1,191 @@
 import os from 'node:os';
 import path from 'node:path';
 import { mkdir, writeFile } from 'node:fs/promises';
-export function defaultSkillDir() {
-    return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
+function clientLabel(client) {
+    switch (client) {
+        case 'codex':
+            return 'Codex';
+        case 'claude-code':
+            return 'Claude Code';
+        case 'antigravity':
+            return 'Antigravity';
+        case 'opencode':
+            return 'OpenCode';
+        case 'cursor':
+            return 'Cursor';
+        case 'vscode':
+            return 'VS Code';
+    }
 }
-export function renderCodexSkill(options) {
-    return `---
-name: sp-rag
-description: Dùng RAG nội bộ qua MCP để trả lời câu hỏi về codebase, domain, docs và vận hành trước khi dựa vào trí nhớ.
----
-
-# SP-RAG
-
-MCP server alias mặc định: \`${options.serverAlias}\`
-MCP URL: \`${options.mcpUrl}\`
-Docs URL: \`${options.docsUrl}\`
-
-## Khi nào dùng
-
-- Khi câu hỏi liên quan đến codebase nội bộ, domain nghiệp vụ, docs đã render, trạng thái sync hoặc inventory import.
-- Khi cần câu trả lời có evidence thay vì suy đoán theo trí nhớ.
-
-## Luồng dùng khuyến nghị
-
-1. Gọi \`healthz\` nếu nghi server đang lỗi hoặc vừa kết nối lần đầu.
-2. Dùng \`query_context\` cho câu hỏi về kiến trúc, domain, flow nghiệp vụ, entities, relations.
-3. Dùng \`get_rendered_docs\` cho public docs, function docs hoặc dev docs đã render sẵn.
-4. Dùng \`get_sync_status\`, \`get_sync_runs\` hoặc \`get_sync_metrics\` khi cần kiểm tra code graph đang ở commit nào, sync có lỗi không, hay muốn đọc lịch sử và metrics vận hành.
-5. Chỉ dùng \`trigger_code_graph_sync\` khi user yêu cầu làm mới index hoặc code graph.
-
-## Nguyên tắc trả lời
-
-- Ưu tiên câu trả lời grounded từ MCP/RAG trước.
-- Nếu evidence có dấu hiệu stale, nói rõ dữ liệu có thể chưa được sync mới nhất.
-- Không tự kích hoạt sync/index nếu user chưa yêu cầu hoặc chưa thật sự cần.
-- Khi docs đã đủ, ưu tiên trích từ docs đã render thay vì tự diễn giải dài dòng.
+function normalizeScope(client, scope) {
+    if (scope) {
+        return scope;
+    }
+    switch (client) {
+        case 'cursor':
+            return 'project';
+        case 'vscode':
+            return 'project';
+        default:
+            return 'global';
+    }
+}
+function requireProjectCwd(client, cwd) {
+    if (!cwd?.trim()) {
+        throw new Error(`${client} cần --cwd hoặc --target-dir để cài skill theo project.`);
+    }
+    return path.resolve(cwd);
+}
+export function defaultSkillDir(client = 'codex', cwd, scope) {
+    const normalizedScope = normalizeScope(client, scope);
+    switch (client) {
+        case 'codex':
+            return path.join(os.homedir(), '.codex', 'skills', 'sp-rag');
+        case 'claude-code':
+            return path.join(os.homedir(), '.claude', 'skills', 'sp-rag');
+        case 'antigravity':
+            return path.join(os.homedir(), '.gemini', 'antigravity', 'skills', 'sp-rag');
+        case 'opencode':
+            return path.join(os.homedir(), '.config', 'opencode', 'skills', 'sp-rag');
+        case 'cursor':
+            if (normalizedScope !== 'project') {
+                throw new Error('Cursor rule hiện chỉ nên cài ở scope project qua .cursor/rules.');
+            }
+            return path.join(requireProjectCwd(client, cwd), '.cursor', 'rules');
+        case 'vscode':
+            return normalizedScope === 'project'
+                ? path.join(requireProjectCwd(client, cwd), '.github', 'agents')
+                : path.join(os.homedir(), '.copilot', 'agents');
+    }
+}
+function renderSkillMarkdown(context) {
+    return `---
+name: sp-rag
+description: Use SP-RAG whenever the user asks about this codebase, internal business domain, rendered docs, import inventory, or codegraph sync status. Prefer MCP-backed evidence before answering from memory.
+---
+
+# 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 this skill whenever the request is about the internal codebase, business workflows, rendered docs, import inventory, or sync state.
+- Use this skill when grounded evidence matters more than memory or intuition.
+- Use this skill when the answer should come from MCP tools or rendered docs before freeform reasoning.
+
+## Recommended Workflow
+
+1. Call \`healthz\` if the MCP server might be unavailable or the connection is brand new.
+2. Use \`query_context\` for architecture, domain, entities, relations, and business flow questions.
+3. Use \`get_rendered_docs\` for public, function, or dev docs that were already rendered from the latest graph.
+4. Use \`get_sync_status\`, \`get_sync_runs\`, or \`get_sync_metrics\` when you need to verify commit freshness, investigate failures, or inspect operational history.
+5. Only call \`trigger_code_graph_sync\` when the user explicitly asks to refresh the graph or when a stale graph is the confirmed blocker.
+
+## Guardrails
+
+- Prefer MCP-grounded answers before relying on memory.
+- If the 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 instead of rewriting everything from scratch.
 `;
 }
-export async function installCodexSkill(options = {}) {
-    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir());
-    const filePath = path.join(targetDir, 'SKILL.md');
-    const content = renderCodexSkill({
+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: false
+---
+
+# SP-RAG
+
+- Prefer the \`${context.serverAlias}\` MCP server at \`${context.mcpUrl}\` before answering from memory.
+- Use rendered docs from \`${context.docsUrl}\` when documentation already answers the question.
+- For architecture, domain, entities, relations, and business workflow questions, query MCP first and only then synthesize the answer.
+- 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 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.
+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.
+
+## Recommended Workflow
+
+1. Start with \`healthz\` if connectivity or freshness is uncertain.
+2. Use \`query_context\` for architecture, domain, entities, relations, and workflow questions.
+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. Trigger codegraph sync only when the user explicitly requests a refresh or stale evidence is the confirmed blocker.
+
+## Guardrails
+
+- Prefer MCP-grounded evidence before answering from memory.
+- 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.
+`;
+}
+function renderSkillArtifact(context) {
+    switch (context.client) {
+        case 'cursor':
+            return {
+                fileName: 'sp-rag.mdc',
+                content: renderCursorRule(context),
+            };
+        case 'vscode':
+            return {
+                fileName: 'sp-rag.agent.md',
+                content: renderVsCodeAgent(context),
+            };
+        default:
+            return {
+                fileName: 'SKILL.md',
+                content: renderSkillMarkdown(context),
+            };
+    }
+}
+export function renderSkill(options) {
+    return renderSkillArtifact(options).content;
+}
+export function renderCodexSkill(options) {
+    return renderSkill({
+        client: 'codex',
+        ...options,
+    });
+}
+export async function installSkill(options = {}) {
+    const client = options.client ?? 'codex';
+    const scope = normalizeScope(client, options.scope);
+    const targetDir = path.resolve(options.targetDir ?? defaultSkillDir(client, options.cwd, scope));
+    const artifact = renderSkillArtifact({
+        client,
         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',
     });
+    const filePath = path.join(targetDir, artifact.fileName);
     await mkdir(targetDir, { recursive: true });
-    await writeFile(filePath, content, 'utf8');
-    return { path: filePath };
+    await writeFile(filePath, artifact.content, 'utf8');
+    return {
+        client,
+        path: filePath,
+    };
+}
+export async function installCodexSkill(options = {}) {
+    return installSkill({
+        ...options,
+        client: 'codex',
+    });
 }

package/package.json

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