@optima-chat/dev-skills 0.7.31 → 0.7.32

package/.claude/skills/grant-balance/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: "grant-balance"
+description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod 两个环境。"
+allowed-tools: ["Bash"]
+---
+
+# 赠送 USD 余额（Grant Balance）
+
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+
+## 执行方式：使用 CLI 工具
+
+```bash
+optima-grant-balance <email> --amount <usd> [options]
+```
+
+**为什么使用 CLI 工具**：
+- 自动通过 email 查找 userId（跨 user-auth 数据库）
+- 自动处理 SSH 隧道和数据库连接
+- 不会影响现有订阅和已有余额（纯追加到 granted balance）
+- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+
+## 适用情况
+
+- 奖励额外余额（推广、活动）
+- 客户补偿（服务中断等）
+- 推荐奖励
+- 内部测试账户充值
+
+## 快速操作
+
+```bash
+# 赠送 $5（Stage 环境，默认）
+optima-grant-balance user@example.com --amount 5
+
+# 赠送 $10 到 Prod
+optima-grant-balance user@example.com --amount 10 --env prod
+
+# 带描述（Reason 仅在 console 输出，不存 DB）
+optima-grant-balance user@example.com --amount 20 --description "服务中断补偿" --env prod
+```
+
+> **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
+> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+
+### 参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `<email>` | 用户邮箱（必填） | - |
+| `--amount <usd>` | USD 金额（必填，> 0） | - |
+| `--description <text>` | 描述/原因（仅 console 输出） | - |
+| `--env <env>` | 环境：stage, prod | stage |
+
+## 与 grant-subscription 的区别
+
+| | grant-balance | grant-subscription |
+|---|---|---|
+| 作用 | 追加 USD granted balance | 开通/切换订阅计划 |
+| 现有余额 | 不影响（纯累加） | 重置 granted balance |
+| 现有订阅 | 不影响 | 取消旧的，创建新的 |
+| Token quota | 不影响 | 按计划更新 |
+| 适用场景 | 奖励、补偿、推广 | 开通会员、升级计划 |
+
+## 常见使用场景
+
+### 场景 1：客户补偿
+
+**用户请求**："服务出了问题，给 xxx@gmail.com 补偿 $5"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 5 --description "Service outage compensation" --env prod
+```
+
+### 场景 2：推荐奖励
+
+**用户请求**："xxx 推荐了新用户，奖励 $3"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 3 --description "Referral reward" --env prod
+```
+
+### 场景 3：运营发放
+
+**用户请求**："给 xxx@gmail.com 充 $20 测试余额"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 20 --env stage
+```
+
+## 安全提醒
+
+1. **Stage 优先**：默认操作 Stage 环境
+2. **Prod 谨慎**：操作 Prod 前确认邮箱和金额
+3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
+4. **Audit trail**：每次赠送会插入一条 `usd_wallet_topups` 记录（source=`admin_grant`）
+
+## 相关命令
+
+- `optima-grant-balance` - 赠送 USD 余额（主要方式）
+- `optima-grant-subscription` - 开通订阅计划
+- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）

package/.claude/skills/grant-subscription/SKILL.md

@@ -116,5 +116,5 @@ optima-grant-subscription user@example.com --plan starter --env prod
 ## 相关命令
 
 - `optima-grant-subscription` - 开通订阅（主要方式）
-- `optima-grant-credits` - 单独赠送 wallet 余额
+- `optima-grant-balance` - 单独赠送 wallet 余额
 - `optima-query-db` - 查询数据库验证结果

package/.codex/skills/grant-balance/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: "grant-balance"
+description: "Use when the user wants to grant USD wallet balance to an Optima user — for promotional grants, compensation, referral rewards, etc. Adds to granted_balance_micros without affecting subscriptions."
+---
+
+# 赠送 USD 余额（Grant Balance）
+
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+
+## 执行方式：使用 CLI 工具
+
+```bash
+optima-grant-balance <email> --amount <usd> [options]
+```
+
+**为什么使用 CLI 工具**：
+- 自动通过 email 查找 userId（跨 user-auth 数据库）
+- 自动处理 SSH 隧道和数据库连接
+- 不会影响现有订阅和已有余额（纯追加到 granted balance）
+- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+
+## 适用情况
+
+- 奖励额外余额（推广、活动）
+- 客户补偿（服务中断等）
+- 推荐奖励
+- 内部测试账户充值
+
+## 快速操作
+
+```bash
+# 赠送 $5（Stage 环境，默认）
+optima-grant-balance user@example.com --amount 5
+
+# 赠送 $10 到 Prod
+optima-grant-balance user@example.com --amount 10 --env prod
+
+# 带描述（Reason 仅在 console 输出，不存 DB）
+optima-grant-balance user@example.com --amount 20 --description "服务中断补偿" --env prod
+```
+
+> **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
+> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+
+### 参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `<email>` | 用户邮箱（必填） | - |
+| `--amount <usd>` | USD 金额（必填，> 0） | - |
+| `--description <text>` | 描述/原因（仅 console 输出） | - |
+| `--env <env>` | 环境：stage, prod | stage |
+
+## 与 grant-subscription 的区别
+
+| | grant-balance | grant-subscription |
+|---|---|---|
+| 作用 | 追加 USD granted balance | 开通/切换订阅计划 |
+| 现有余额 | 不影响（纯累加） | 重置 granted balance |
+| 现有订阅 | 不影响 | 取消旧的，创建新的 |
+| Token quota | 不影响 | 按计划更新 |
+| 适用场景 | 奖励、补偿、推广 | 开通会员、升级计划 |
+
+## 常见使用场景
+
+### 场景 1：客户补偿
+
+**用户请求**："服务出了问题，给 xxx@gmail.com 补偿 $5"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 5 --description "Service outage compensation" --env prod
+```
+
+### 场景 2：推荐奖励
+
+**用户请求**："xxx 推荐了新用户，奖励 $3"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 3 --description "Referral reward" --env prod
+```
+
+### 场景 3：运营发放
+
+**用户请求**："给 xxx@gmail.com 充 $20 测试余额"
+
+```bash
+optima-grant-balance xxx@gmail.com --amount 20 --env stage
+```
+
+## 安全提醒
+
+1. **Stage 优先**：默认操作 Stage 环境
+2. **Prod 谨慎**：操作 Prod 前确认邮箱和金额
+3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
+4. **Audit trail**：每次赠送会插入一条 `usd_wallet_topups` 记录（source=`admin_grant`）
+
+## 相关命令
+
+- `optima-grant-balance` - 赠送 USD 余额（主要方式）
+- `optima-grant-subscription` - 开通订阅计划
+- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）

package/AGENTS.md

@@ -10,7 +10,7 @@ Prefer the installed CLI tools over reimplementing long shell workflows:
 - `optima-show-env <service> <stage|prod> [options]`
 - `optima-generate-test-token [options]`
 - `optima-grant-subscription <email> [options]`
-- `optima-grant-credits <email> --amount <n> [options]`
+- `optima-grant-balance <email> --amount <usd> [options]`
 
 For code-reading tasks across Optima repositories, use `gh` commands against `Optima-Chat/<repo>`.
 
@@ -24,7 +24,7 @@ After `npm install -g @optima-chat/dev-skills`, this package installs skills und
 - `generate-test-token`
 - `read-code`
 - `grant-subscription`
-- `grant-credits`
+- `grant-balance`
 - `restart-ecs`
 - `use-commerce-cli`
 

package/bin/cli.js

@@ -33,7 +33,7 @@ switch (command) {
     log('  optima-query-db <service> "<sql>" [env]              Query database', 'cyan');
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
     log('  optima-generate-test-token [--env production]        Generate test token', 'cyan');
-    log('  optima-grant-credits <email> --amount <n> [--env]    Grant credits to user', 'cyan');
+    log('  optima-grant-balance <email> --amount <usd> [--env]  Grant USD wallet balance', 'cyan');
     log('  optima-grant-subscription <email> --plan <p> [--env] Grant subscription', 'cyan');
     log('  /logs <service> [lines] [env]                        View service logs (skill)', 'cyan');
     log('  /restart-ecs <service> [env]                         Restart ECS service (skill)', 'cyan');
@@ -48,7 +48,7 @@ switch (command) {
     log('\nExamples:', 'yellow');
     log('  /logs commerce-backend 100 prod', 'cyan');
     log('  optima-query-db user-auth "SELECT COUNT(*) FROM users" prod', 'cyan');
-    log('  optima-grant-credits user@example.com --amount 5000 --env prod', 'cyan');
+    log('  optima-grant-balance user@example.com --amount 5 --env prod', 'cyan');
 
     log('\nMore Info:', 'yellow');
     log('  optima-dev-skills --version              Show version', 'cyan');

package/bin/helpers/{grant-credits.ts → grant-balance.ts}

@@ -2,46 +2,57 @@
 
 import { getInfisicalConfig, getInfisicalToken, resolveUserId, connectBillingDB, escapeSQL } from './db-utils';
 
-function parseArgs(args: string[]): { email: string; amount: number; type: string; description: string | null; env: string } {
+function parseArgs(args: string[]): { email: string; amountUsd: number; description: string | null; env: string } {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-    console.log(`Usage: optima-grant-credits <email> --amount <n> [options]
+    console.log(`Usage: optima-grant-balance <email> --amount <usd> [options]
+
+Add USD balance to a user's wallet (granted_balance_micros).
+Used for promotional grants, compensation, referral rewards, etc.
 
 Options:
-  --amount <n>          Credits to grant (required)
-  --type <type>         Credit type: bonus, referral (default: bonus)
-  --description <text>  Description (optional)
+  --amount <usd>        USD amount to grant (required, e.g. 5 for $5.00)
+  --description <text>  Description for audit trail (optional)
   --env <env>           Environment: stage, prod (default: stage)
-  -h, --help            Show this help`);
+  -h, --help            Show this help
+
+Examples:
+  optima-grant-balance user@example.com --amount 5 --env prod
+  optima-grant-balance user@example.com --amount 10 --description "Service outage compensation"`);
     process.exit(0);
   }
 
   const email = args[0];
-  let amount = 0;
-  let type = 'bonus';
+  let amountUsd = 0;
   let description: string | null = null;
   let env = 'stage';
 
   for (let i = 1; i < args.length; i++) {
-    if (args[i] === '--amount' && args[i + 1]) { amount = parseInt(args[++i], 10); }
-    else if (args[i] === '--type' && args[i + 1]) { type = args[++i]; }
+    if (args[i] === '--amount' && args[i + 1]) { amountUsd = parseFloat(args[++i]); }
     else if (args[i] === '--description' && args[i + 1]) { description = args[++i]; }
     else if (args[i] === '--env' && args[i + 1]) { env = args[++i]; }
   }
 
-  if (amount < 1) { console.error('--amount is required and must be >= 1'); process.exit(1); }
-  if (!['bonus', 'referral'].includes(type)) { console.error(`Unknown type: ${type}. Available: bonus, referral`); process.exit(1); }
-  if (!['stage', 'prod'].includes(env)) { console.error('Env must be stage or prod (billing DB not available in CI)'); process.exit(1); }
+  if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
+    console.error('--amount is required and must be > 0 (USD)');
+    process.exit(1);
+  }
+  if (!['stage', 'prod'].includes(env)) {
+    console.error('Env must be stage or prod (billing DB not available in CI)');
+    process.exit(1);
+  }
 
-  return { email, amount, type, description, env };
+  return { email, amountUsd, description, env };
 }
 
 async function main() {
-  const { email, amount, type, description, env } = parseArgs(process.argv.slice(2));
+  const { email, amountUsd, description, env } = parseArgs(process.argv.slice(2));
   const infisicalConfig = getInfisicalConfig();
   const token = getInfisicalToken(infisicalConfig);
 
-  const amountMicros = amount * 10000; // 1 credit = $0.01 = 10,000 micros
-  console.log(`\n🎁 Granting $${(amountMicros / 1000000).toFixed(2)} (${amount} credits) as ${type} to ${email} [${env.toUpperCase()}]\n`);
+  // 1 USD = 1,000,000 micros. Round to integer micros.
+  const amountMicros = Math.round(amountUsd * 1_000_000);
+  console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} to ${email} [${env.toUpperCase()}]\n`);
+  if (description) console.log(`   Reason: ${description}`);
 
   const userId = await resolveUserId(email, env, infisicalConfig, token);
   const billing = await connectBillingDB(env, infisicalConfig, token);
@@ -49,7 +60,6 @@ async function main() {
 
   const now = new Date().toISOString();
   const safeUserId = escapeSQL(userId);
-  const safeDesc = escapeSQL(description || `Admin ${type} grant`);
 
   console.log(`Granting to wallet...`);
   const txSQL = `
@@ -64,7 +74,7 @@ ON CONFLICT (user_id) DO NOTHING;
 UPDATE usd_wallets SET granted_balance_micros = granted_balance_micros + ${amountMicros}, updated_at = '${now}'
 WHERE user_id = '${safeUserId}';
 
--- Record topup for audit trail
+-- Record topup for audit trail (source='admin_grant' aligns with billing service convention)
 INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
 SELECT gen_random_uuid(), w.id, ${amountMicros}, 0, ${amountMicros}, 'completed', 'admin_grant', 'platform', '${now}', '${now}'
 FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
@@ -72,7 +82,7 @@ FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
 COMMIT;
   `.trim();
   bq(txSQL);
-  console.log(`✓ Wallet granted $${(amountMicros / 1000000).toFixed(2)}`);
+  console.log(`✓ Granted $${amountUsd.toFixed(2)} to wallet`);
 
   const balanceMicros = bq(`SELECT granted_balance_micros FROM usd_wallets WHERE user_id='${safeUserId}'`);
   const balanceUsd = (parseInt(balanceMicros, 10) / 1000000).toFixed(2);

package/dist/bin/helpers/{grant-credits.js → grant-balance.js}

@@ -4,27 +4,29 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const db_utils_1 = require("./db-utils");
 function parseArgs(args) {
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-        console.log(`Usage: optima-grant-credits <email> --amount <n> [options]
+        console.log(`Usage: optima-grant-balance <email> --amount <usd> [options]
+
+Add USD balance to a user's wallet (granted_balance_micros).
+Used for promotional grants, compensation, referral rewards, etc.
 
 Options:
-  --amount <n>          Credits to grant (required)
-  --type <type>         Credit type: bonus, referral (default: bonus)
-  --description <text>  Description (optional)
+  --amount <usd>        USD amount to grant (required, e.g. 5 for $5.00)
+  --description <text>  Description for audit trail (optional)
   --env <env>           Environment: stage, prod (default: stage)
-  -h, --help            Show this help`);
+  -h, --help            Show this help
+
+Examples:
+  optima-grant-balance user@example.com --amount 5 --env prod
+  optima-grant-balance user@example.com --amount 10 --description "Service outage compensation"`);
         process.exit(0);
     }
     const email = args[0];
-    let amount = 0;
-    let type = 'bonus';
+    let amountUsd = 0;
     let description = null;
     let env = 'stage';
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--amount' && args[i + 1]) {
-            amount = parseInt(args[++i], 10);
-        }
-        else if (args[i] === '--type' && args[i + 1]) {
-            type = args[++i];
+            amountUsd = parseFloat(args[++i]);
         }
         else if (args[i] === '--description' && args[i + 1]) {
             description = args[++i];
@@ -33,32 +35,30 @@ Options:
             env = args[++i];
         }
     }
-    if (amount < 1) {
-        console.error('--amount is required and must be >= 1');
-        process.exit(1);
-    }
-    if (!['bonus', 'referral'].includes(type)) {
-        console.error(`Unknown type: ${type}. Available: bonus, referral`);
+    if (!Number.isFinite(amountUsd) || amountUsd <= 0) {
+        console.error('--amount is required and must be > 0 (USD)');
         process.exit(1);
     }
     if (!['stage', 'prod'].includes(env)) {
         console.error('Env must be stage or prod (billing DB not available in CI)');
         process.exit(1);
     }
-    return { email, amount, type, description, env };
+    return { email, amountUsd, description, env };
 }
 async function main() {
-    const { email, amount, type, description, env } = parseArgs(process.argv.slice(2));
+    const { email, amountUsd, description, env } = parseArgs(process.argv.slice(2));
     const infisicalConfig = (0, db_utils_1.getInfisicalConfig)();
     const token = (0, db_utils_1.getInfisicalToken)(infisicalConfig);
-    const amountMicros = amount * 10000; // 1 credit = $0.01 = 10,000 micros
-    console.log(`\n🎁 Granting $${(amountMicros / 1000000).toFixed(2)} (${amount} credits) as ${type} to ${email} [${env.toUpperCase()}]\n`);
+    // 1 USD = 1,000,000 micros. Round to integer micros.
+    const amountMicros = Math.round(amountUsd * 1000000);
+    console.log(`\n🎁 Granting $${amountUsd.toFixed(2)} to ${email} [${env.toUpperCase()}]\n`);
+    if (description)
+        console.log(`   Reason: ${description}`);
     const userId = await (0, db_utils_1.resolveUserId)(email, env, infisicalConfig, token);
     const billing = await (0, db_utils_1.connectBillingDB)(env, infisicalConfig, token);
     const bq = billing.query;
     const now = new Date().toISOString();
     const safeUserId = (0, db_utils_1.escapeSQL)(userId);
-    const safeDesc = (0, db_utils_1.escapeSQL)(description || `Admin ${type} grant`);
     console.log(`Granting to wallet...`);
     const txSQL = `
 BEGIN;
@@ -72,7 +72,7 @@ ON CONFLICT (user_id) DO NOTHING;
 UPDATE usd_wallets SET granted_balance_micros = granted_balance_micros + ${amountMicros}, updated_at = '${now}'
 WHERE user_id = '${safeUserId}';
 
--- Record topup for audit trail
+-- Record topup for audit trail (source='admin_grant' aligns with billing service convention)
 INSERT INTO usd_wallet_topups (id, wallet_id, amount_micros, service_fee_micros, net_credit_micros, status, source, service_namespace, created_at, completed_at)
 SELECT gen_random_uuid(), w.id, ${amountMicros}, 0, ${amountMicros}, 'completed', 'admin_grant', 'platform', '${now}', '${now}'
 FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
@@ -80,7 +80,7 @@ FROM usd_wallets w WHERE w.user_id = '${safeUserId}';
 COMMIT;
   `.trim();
     bq(txSQL);
-    console.log(`✓ Wallet granted $${(amountMicros / 1000000).toFixed(2)}`);
+    console.log(`✓ Granted $${amountUsd.toFixed(2)} to wallet`);
     const balanceMicros = bq(`SELECT granted_balance_micros FROM usd_wallets WHERE user_id='${safeUserId}'`);
     const balanceUsd = (parseInt(balanceMicros, 10) / 1000000).toFixed(2);
     console.log(`\n✅ Done! ${email} now has $${balanceUsd} granted balance\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/dev-skills",
-  "version": "0.7.31",
+  "version": "0.7.32",
   "description": "Claude Code Skills for Optima development team - cross-environment collaboration tools",
   "main": "index.js",
   "bin": {
@@ -9,7 +9,7 @@
     "optima-generate-test-token": "dist/bin/helpers/generate-test-token.js",
     "optima-show-env": "dist/bin/helpers/show-env.js",
     "optima-grant-subscription": "dist/bin/helpers/grant-subscription.js",
-    "optima-grant-credits": "dist/bin/helpers/grant-credits.js"
+    "optima-grant-balance": "dist/bin/helpers/grant-balance.js"
   },
   "scripts": {
     "postinstall": "node scripts/install.js",

package/.claude/settings.local.json

@@ -1,51 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "WebSearch",
-      "WebFetch(domain:code.claude.com)",
-      "WebFetch(domain:platform.claude.com)",
-      "WebFetch(domain:github.com)",
-      "Bash(gh repo view:*)",
-      "Bash(gh repo clone:*)",
-      "Bash(gh repo list:*)",
-      "Read(//private/tmp/optima-docs/**)",
-      "Read(//tmp/optima-docs/**)",
-      "Bash(git init:*)",
-      "Bash(gh repo create:*)",
-      "Read(//private/tmp/optima-workspace/**)",
-      "Read(//tmp/optima-workspace/**)",
-      "Read(//tmp/optima-workspace/.claude/commands/**)",
-      "Bash(git add:*)",
-      "Bash(git push:*)",
-      "Bash(find:*)",
-      "Bash(git commit:*)",
-      "Bash(aws logs get-log-events:*)",
-      "Bash(npm install:*)",
-      "Bash(optima-dev-skills:*)",
-      "Bash(optima-generate-test-token:*)",
-      "Bash(optima-query-db:*)",
-      "Bash(gh variable set:*)",
-      "Bash(npm publish:*)",
-      "Bash(python3:*)",
-      "Bash(gh api:*)",
-      "Bash(curl -s http://auth.optima.chat/openapi.json)",
-      "Bash(curl -s https://auth.optima.chat/openapi.json)",
-      "Bash(cat:*)",
-      "Bash(node /Users/verypro/optima-dev-skills/scripts/install.js:*)",
-      "Bash(aws logs tail:*)",
-      "Bash(grep:*)",
-      "Bash(npm view:*)",
-      "Bash(npm version:*)",
-      "Bash(git checkout:*)",
-      "Bash(git pull:*)",
-      "Bash(node scripts/install.js:*)",
-      "Bash(gh issue:*)",
-      "Bash(npm run:*)",
-      "Bash(gh pr:*)",
-      "Bash(node:*)",
-      "Bash(echo \"exit: $?\")"
-    ],
-    "deny": [],
-    "ask": []
-  }
-}

package/.claude/skills/grant-credits/SKILL.md

@@ -1,107 +0,0 @@
----
-name: "grant-credits"
-description: "当用户请求赠送 credits、充值余额、grant credits、加余额、奖励积分、补偿、推荐奖励时，使用此技能。支持 Stage、Prod 两个环境。"
-allowed-tools: ["Bash"]
----
-
-# 赠送余额（Grant Credits）
-
-当你需要为用户赠送额外 wallet 余额时，使用这个场景。赠送的额度会加到 `usd_wallets.granted_balance_micros`。
-
-## 执行方式：使用 CLI 工具
-
-**重要**：使用 `optima-grant-credits` CLI 工具：
-
-```bash
-optima-grant-credits <email> --amount <n> [options]
-```
-
-**为什么使用 CLI 工具**：
-- 自动通过 email 查找 userId（跨 user-auth 数据库）
-- 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（纯追加到 granted balance）
-- 一条命令完成操作
-
-## 适用情况
-
-- 赠送额外余额（奖励、补偿、推广等）
-- 推荐奖励
-- 运营活动发放
-- 客户补偿
-
-## 快速操作
-
-```bash
-# 赠送 100 credits ($1.00)，Stage 环境（默认）
-optima-grant-credits user@example.com --amount 100
-
-# 赠送 500 credits ($5.00)，Prod 环境
-optima-grant-credits user@example.com --amount 500 --env prod
-
-# 推荐奖励
-optima-grant-credits user@example.com --amount 200 --type referral --env prod
-
-# 自定义描述
-optima-grant-credits user@example.com --amount 300 --description "客户补偿 - 服务中断" --env prod
-```
-
-> 1 credit = $0.01 = 10,000 micros。--amount 500 即赠送 $5.00 到 granted balance。
-
-### 参数说明
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `<email>` | 用户邮箱（必填） | - |
-| `--amount <n>` | Credits 数量（必填，>=1，1 credit = $0.01） | - |
-| `--type <type>` | 类型：bonus, referral | bonus |
-| `--description <text>` | 描述（可选） | Auto-generated |
-| `--env <env>` | 环境：stage, prod | stage |
-
-## 与 grant-subscription 的区别
-
-| | grant-credits | grant-subscription |
-|---|---|---|
-| 作用 | 追加 granted balance | 开通/切换订阅计划 |
-| 现有余额 | 不影响（纯累加） | 重置 granted balance |
-| 现有订阅 | 不影响 | 取消旧的，创建新的 |
-| Token quota | 不影响 | 按计划更新 |
-| 适用场景 | 奖励、补偿、推广 | 开通会员、升级计划 |
-
-## 常见使用场景
-
-### 场景 1：奖励余额
-
-**用户请求**："给 xxx@gmail.com 加 200 credits"
-
-```bash
-optima-grant-credits xxx@gmail.com --amount 200 --env prod
-```
-
-### 场景 2：推荐奖励
-
-**用户请求**："xxx 推荐了新用户，给他 referral 奖励 300"
-
-```bash
-optima-grant-credits xxx@gmail.com --amount 300 --type referral --env prod
-```
-
-### 场景 3：客户补偿
-
-**用户请求**："服务出了问题，补偿 xxx $5"
-
-```bash
-optima-grant-credits xxx@gmail.com --amount 500 --description "服务中断补偿" --env prod
-```
-
-## 安全提醒
-
-1. **Stage 优先**：默认操作 Stage 环境
-2. **Prod 谨慎**：操作 Prod 前确认邮箱和数量
-3. **纯追加**：不会影响现有余额和订阅（累加到 granted balance）
-4. **无过期**：granted balance 不会自动过期
-
-## 相关命令
-
-- `optima-grant-credits` - 赠送余额（主要方式）
-- `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果

package/.codex/skills/grant-credits/SKILL.md

@@ -1,28 +0,0 @@
----
-name: "grant-credits"
-description: "Use when the user wants to add bonus or referral balance to an Optima user's wallet without changing their subscription."
----
-
-# Grant Credits
-
-Use this skill when the user asks to add credits directly.
-
-## Preferred Command
-
-```bash
-optima-grant-credits <email> --amount <n> [options]
-```
-
-## Examples
-
-```bash
-optima-grant-credits user@example.com --amount 100
-optima-grant-credits user@example.com --amount 500 --env prod
-optima-grant-credits user@example.com --amount 300 --type referral --env prod
-```
-
-## Guidance
-
-- Default to `stage`.
-- Confirm the email and amount before using `prod`.
-- This operation appends to the user's wallet granted balance and does not replace their subscription. Amount is in credits (1 credit = $0.01).