@optima-chat/dev-skills 0.7.29 → 0.7.32

package/.claude/commands/trace-user.md

@@ -0,0 +1,293 @@
+# /trace-user - 用户链路追踪
+
+查看指定用户在 agentic-chat -> optima-gateway -> agent-runtime 全链路的日志，分析耗时、成功/失败、返回值等。
+
+**版本**: v0.1.0
+
+## 使用场景
+
+**前端开发者**: 用户反馈 "聊天没反应"，快速定位是前端、网关还是 Agent 的问题
+**后端开发者**: 追踪特定用户的请求链路，分析 LLM 调用耗时和工具执行
+**DevOps**: 排查线上用户问题，查看完整的跨服务日志关联
+
+## 用法
+
+```
+/trace-user <user-id-or-email> [environment] [time-range] [options]
+```
+
+## 参数
+
+- `user-id-or-email` (必需): 用户标识
+  - 包含 `@` → email（用 `userEmail` 字段过滤）
+  - UUID 格式 → userId（用 `userId` 字段过滤）
+- `environment` (可选): `stage` 或 `prod`，默认 `stage`
+- `time-range` (可选): 如 `10m`, `30m`, `1h`, `2h`, `1d`，默认 `30m`
+- 选项:
+  - `--errors` — 只看 error/warn 级别
+  - `--session SESSION_ID` — 限定某个 session
+  - `--trace TRACE_ID` — 限定某个 traceId
+  - `--raw` — 显示原始 JSON
+
+## 示例
+
+```bash
+/trace-user alice@example.com                    # Stage，最近 30 分钟
+/trace-user 37c03a9f-0b47-409c-81a3-5634eaab1a6c prod 2h  # Prod，最近 2 小时
+/trace-user alice@example.com --errors           # 只看错误
+/trace-user alice@example.com --session sess-xxx # 指定 session
+```
+
+如果用户输入 `/trace-user` 或 `/trace-user --help`，显示此帮助文档，不执行查询。
+
+ARGUMENTS: $ARGUMENTS
+
+## Claude Code 执行步骤
+
+### 1. 解析参数
+
+从 `$ARGUMENTS` 中解析用户标识、环境、时间范围和选项。
+
+**用户标识判断**:
+- 包含 `@` → email → 使用 `userEmail` 字段
+- UUID 格式（`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`）→ 使用 `userId` 字段
+- 其他 → 当作 userId 尝试
+
+### 2. 日志组映射
+
+三层服务对应的 CloudWatch Log Group：
+
+| 层 | 服务 | Stage 日志组 | Prod 日志组 |
+|----|------|-------------|------------|
+| L1 | agentic-chat | `/ecs/agentic-chat-stage` | `/ecs/agentic-chat-prod` |
+| L2 | gateway-core | `/ecs/gateway-core-stage` | `/ecs/gateway-core-prod` |
+| L3 | agent-runtime | `/ecs/gw-agent-runtime-stage` | `/ecs/gw-agent-runtime-prod` |
+
+**AWS 区域**: `ap-southeast-1`
+
+### 3. 搜索策略
+
+#### 第一步：在 gateway-core 找到用户的 session
+
+```bash
+# 按 email 搜索
+aws logs filter-log-events \
+  --log-group-name /ecs/gateway-core-{ENV} \
+  --filter-pattern '{ $.userEmail = "USER_EMAIL" }' \
+  --start-time $(date -d 'TIME_RANGE ago' +%s)000 \
+  --region ap-southeast-1 \
+  --output json | head -100
+
+# 按 userId 搜索
+aws logs filter-log-events \
+  --log-group-name /ecs/gateway-core-{ENV} \
+  --filter-pattern '{ $.userId = "USER_ID" }' \
+  --start-time $(date -d 'TIME_RANGE ago' +%s)000 \
+  --region ap-southeast-1 \
+  --output json | head -100
+```
+
+从结果中提取 `sessionId` 和 `traceId`。
+
+#### 第二步：跨服务关联查询（Logs Insights）
+
+优先使用 CloudWatch Logs Insights 跨多个 log group 查询：
+
+```bash
+# 按 userId/email 跨服务查询
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, @message
+    | filter userId = "USER_ID" or userEmail = "USER_EMAIL"
+    | sort @timestamp asc
+    | limit 500
+  ' \
+  --region ap-southeast-1
+
+# 等几秒后获取结果
+aws logs get-query-results --query-id QUERY_ID --region ap-southeast-1
+```
+
+如果已知 sessionId：
+
+```bash
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, level, message, sessionId, traceId, duration_ms
+    | filter sessionId = "SESSION_ID"
+    | sort @timestamp asc
+    | limit 500
+  ' \
+  --region ap-southeast-1
+```
+
+#### 第三步：agentic-chat 日志（补充）
+
+agentic-chat 前端日志可能不含 userId/sessionId 字段，用时间窗口 + 关键词辅助：
+
+```bash
+aws logs tail /ecs/agentic-chat-{ENV} --since {TIME_RANGE} \
+  --region ap-southeast-1 | grep -i "USER_EMAIL_OR_ID"
+```
+
+#### 第四步：只看错误（--errors）
+
+```bash
+aws logs start-query \
+  --log-group-names \
+    /ecs/gateway-core-{ENV} \
+    /ecs/gw-agent-runtime-{ENV} \
+  --start-time $(date -d 'TIME_RANGE ago' +%s) \
+  --end-time $(date +%s) \
+  --query-string '
+    fields @timestamp, @logStream, level, message, sessionId, error
+    | filter (userId = "USER_ID" or userEmail = "USER_EMAIL")
+      and (level = "error" or level = "warn")
+    | sort @timestamp asc
+    | limit 200
+  ' \
+  --region ap-southeast-1
+```
+
+### 4. 结构化日志字段参考
+
+optima-gateway 的日志通过 AsyncLocalStorage 自动注入：
+
+```json
+{
+  "timestamp": "2026-04-16T10:30:00.000Z",
+  "level": "info",
+  "service": "gateway-core",
+  "userId": "37c03a9f-...",
+  "userEmail": "alice@example.com",
+  "sessionId": "sess-xxx",
+  "traceId": "gw-abc123",
+  "message": "Session created",
+  "duration_ms": 123
+}
+```
+
+**关键字段**:
+- `userId` / `userEmail` — 用户标识
+- `sessionId` — 会话 ID
+- `traceId` — 跨服务链路 ID
+- `duration_ms` — 操作耗时
+- `level` — 日志级别（info/warn/error）
+
+### 5. 输出格式
+
+#### A. 概览信息
+
+```
+用户: alice@example.com (37c03a9f-...)
+环境: Stage
+时间范围: 最近 30 分钟
+找到 session 数: 3
+```
+
+#### B. Session 列表
+
+| Session ID | 创建时间 | 状态 | 持续时间 | 消息数 | 错误数 |
+|-----------|---------|------|---------|-------|-------|
+| sess-001 | 10:30:00 | running | 5m | 12 | 0 |
+| sess-002 | 10:20:00 | terminated | 8m | 24 | 1 |
+
+#### C. 请求链路时间线
+
+```
+Session: sess-001
+TraceId: gw-abc123
+
+时间线：
+┌──────────────────────────────────────────────────────────────────────┐
+│ 10:30:00.000 [gateway-core]   WS connected, authenticating...       │
+│ 10:30:00.150 [gateway-core]   OIDC verified, userId=37c03a9f       │ +150ms
+│ 10:30:00.200 [gateway-core]   Session creating                      │ +50ms
+│ 10:30:00.800 [gateway-core]   Agent task started (ECS RunTask)      │ +600ms
+│ 10:30:03.200 [agent-runtime]  Container ready, WS connected         │ +2400ms
+│ 10:30:03.250 [gateway-core]   Session running                       │ +50ms
+│ 10:30:05.000 [gateway-core]   Client message received               │
+│ 10:30:05.100 [agent-runtime]  LLM request started (openai)          │ +100ms
+│ 10:30:08.500 [agent-runtime]  LLM response complete                 │ +3400ms
+│ 10:30:08.600 [agent-runtime]  Tool call: read_file                  │
+│ 10:30:08.800 [agent-runtime]  Tool result returned                  │ +200ms
+│ 10:30:09.000 [gateway-core]   Message forwarded to client           │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+#### D. 耗时分析
+
+```
+关键耗时:
+  OIDC 认证:         150ms
+  Session 创建:       50ms
+  ECS 容器启动:     2400ms  (>2s 时标记 warning)
+  WS 回连:            50ms
+  首次 LLM 调用:    3400ms
+  工具执行:          200ms
+
+统计:
+  总消息数: 12 (user: 5, assistant: 7)
+  LLM 调用次数: 7
+  平均 LLM 延迟: 2800ms
+  工具调用次数: 3
+```
+
+#### E. 错误/告警
+
+```
+发现 1 个错误:
+  10:35:12 [agent-runtime] ERROR: LLM request failed
+    provider: openai
+    error: "rate_limit_exceeded"
+    sessionId: sess-002
+    → 已自动重试（CircuitBreaker half-open）
+```
+
+### 6. 常用诊断场景
+
+| 用户报告 | 推荐策略 |
+|---------|---------|
+| "连不上" / "打不开" | 查 gateway-core 连接日志 + OIDC 认证 |
+| "没反应" / "卡住了" | 查 agent-runtime 是否收到消息 + LLM 是否响应 |
+| "回复慢" | 查 duration_ms 字段，分析 ECS 启动 + LLM 延迟 |
+| "出错了" / "报错" | `--errors` 模式，重点看 error 级别 |
+| "用了一半断了" | 查 WS 断连事件 + session 状态变化 |
+| "总是失败" | 查 CircuitBreaker 状态 + provider 切换日志 |
+
+### 7. 快捷跟进命令
+
+```bash
+# 查看服务健康状态
+curl -s https://gw.stage.optima.onl/health | jq .
+curl -s https://ai.stage.optima.onl/api/health | jq .
+
+# 查看服务 debug 信息
+curl -s -H "X-Debug-Key: 7eede5747b6c50f1c8f2358b98462f74696cdef9bfeab85eaf7ea41166788b5c" \
+  https://gw.stage.optima.onl/debug/info | jq .
+
+# 查看 ECS 服务状态
+aws ecs describe-services --cluster optima-stage-cluster \
+  --services gateway-core-stage --region ap-southeast-1 \
+  --query 'services[0].{status:status,running:runningCount,desired:desiredCount}'
+```
+
+## 注意事项
+
+1. **CloudWatch 延迟**: 最新日志可能需要等 10-30 秒才出现
+2. **速率限制**: `filter-log-events` 有限流，大范围查询优先用 `start-query` (Logs Insights)
+3. **日志保留**: CloudWatch 保留 14 天
+4. **结构化日志**: JSON 日志输出到 stderr，在 CloudWatch 中显示为普通文本行
+5. **Insights 限制**: 最多返回 10000 条，一般够用
+6. **权限要求**: 需要 AWS CLI 配置了正确的凭证（`ap-southeast-1` 区域）
+7. 如果用户没有任何日志，可能是该用户在指定时间范围内没有活动、标识输入有误、或服务未部署

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

@@ -19,8 +19,8 @@ optima-grant-subscription <email> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 自动取消旧订阅、清零旧 credits
-- 自动按 plan 配置授予 credits 和 token quota
+- 自动取消旧订阅、重置 wallet granted balance
+- 自动按 plan 配置授予 USD wallet 余额和 token quota
 - 一条命令完成所有操作
 
 ## 适用情况
@@ -59,12 +59,14 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 
 ### 计划配置
 
-| Plan | Credits/月 | Session Token | Weekly Token |
-|------|-----------|---------------|--------------|
-| trial | 20 | 400K | 1M |
-| starter | 500 | 2M | 10M |
-| pro | 2,000 | 8M | 40M |
-| enterprise | 10,000 | 16M | 80M |
+| Plan | 月授予额 (USD) | Credits 等价 | Session Token | Weekly Token |
+|------|---------------|-------------|---------------|--------------|
+| trial | $0.20 | 20 | 400K | 1M |
+| starter | $5.00 | 500 | 2M | 10M |
+| pro | $20.00 | 2,000 | 8M | 40M |
+| enterprise | $100.00 | 10,000 | 16M | 80M |
+
+> 1 credit = $0.01 = 10,000 micros。授予额存入 `usd_wallets.granted_balance_micros`。
 
 ## 常见使用场景
 
@@ -97,22 +99,22 @@ optima-grant-subscription user@example.com --plan starter --env prod
 工具会自动完成以下步骤：
 
 1. 通过 email 在 user-auth 数据库查找 userId
-2. 加载对应 plan 的配置（credits、token 限额等）
+2. 加载对应 plan 的配置（月授予额、token 限额等）
 3. 取消该用户的所有活跃订阅
-4. 清零旧的 credits
-5. 创建新订阅（设置到期时间）
-6. 授予对应 credits
+4. 创建新订阅（设置到期时间）
+5. 重置 wallet granted balance 并授予新额度
+6. 记录 topup 审计记录（source: subscription_grant）
 7. 更新 token quota 限额
 
 ## 安全提醒
 
 1. **Stage 优先**：默认操作 Stage 环境
 2. **Prod 谨慎**：操作 Prod 前确认用户邮箱正确
-3. **不可逆**：旧订阅和 credits 会被清除
+3. **不可逆**：旧订阅会被取消，granted balance 会被重置
 4. **确认 email**：执行前务必确认邮箱地址无误
 
 ## 相关命令
 
 - `optima-grant-subscription` - 开通订阅（主要方式）
-- `optima-grant-credits` - 单独赠送 credits
+- `optima-grant-balance` - 单独赠送 wallet 余额
 - `optima-query-db` - 查询数据库验证结果

package/.claude/skills/query-db/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "query-db"
-description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
+description: "当用户请求查询数据库、执行SQL、查看数据、统计数据、检查数据库、查询表、数据库查询时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway、gateway-core、ads-backend、amazon-backend、shopify-backend、optima-sentinel 等服务的数据库查询。优先使用 optima-query-db CLI 工具。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -75,7 +75,8 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 - `user-auth` - 用户认证数据库
 - `agentic-chat` - AI 聊天数据库
 - `bi-backend` - BI 后端数据库
-- `session-gateway` - AI Shell 网关数据库
+- `session-gateway` - AI Shell 网关数据库（老）
+- `gateway-core` - Optima Gateway (`optima_gateway`) 数据库 — sessions / conversations / messages / transcripts / credits
 - `optima-logistics` - 物流服务数据库
 - `ads-backend` - Ads 数据库
 - `amazon-backend` - Amazon 数据库
@@ -212,6 +213,7 @@ optima-query-db commerce-backend "SELECT status, COUNT(*) FROM orders GROUP BY s
 | shopify-backend | `/services/shopify-backend` |
 | optima-generation | `/services/optima-generation` |
 | optima-sentinel | `/services/optima-sentinel` |
+| gateway-core | `/services/gateway-core` |
 
 ### RDS 连接
 

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/.codex/skills/grant-subscription/SKILL.md

@@ -25,5 +25,5 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 
 - Default to `stage`.
 - Confirm the user email before running on `prod`.
-- This operation replaces existing subscription state and resets credits according to the selected plan.
+- This operation replaces existing subscription state and resets the wallet granted balance according to the selected plan.
 - Use `optima-query-db` afterward if the user asks for verification.

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');