@optima-chat/dev-skills 0.7.37 → 0.7.40

package/.claude/commands/logs.md

@@ -50,6 +50,7 @@
   - `ci` - CI 持续集成环境（开发环境，默认）
   - `stage` - Stage 预发布环境（ECS Fargate）
   - `prod` - 生产环境（ECS Fargate）
+  - `cn-prod`（别名 `cn`）- 阿里云 cn-prod 环境（SAE，cn-beijing，经 buildbox 取日志）
 
 ## 示例
 
@@ -71,6 +72,7 @@
 - `ci` 或未指定 → 使用 SSH + Docker Compose（第 0 节，默认）
 - `stage` → 使用 AWS CloudWatch Logs - ECS（第 1 节）
 - `prod` → 使用 AWS CloudWatch Logs - ECS（第 2 节）
+- `cn-prod` / `cn` → 阿里云 SAE，经 buildbox 调 `DescribeInstanceLog`（第 3 节）
 
 ### 0. CI 环境（environment = "ci" 或默认）
 
@@ -209,6 +211,59 @@ aws logs get-log-events --log-group-name /ecs/commerce-backend-prod --log-stream
 
 **注意**: `optima-store` 仅在 Stage 环境部署
 
+### 3. cn-prod 环境（environment = "cn-prod" 或 "cn"）
+
+**部署方式**: 阿里云 **SAE**（Serverless App Engine，cn-beijing），不是 ECS/CloudWatch。
+**访问方式**: 经 buildbox（`root@47.94.105.163`，唯一装了 `aliyun-optima` profile + VPC 可达的机器）调 SAE OpenAPI。
+
+> ⚠️ SAE **未配 SLS**，stdout 日志只能用 `DescribeInstanceLog` 取实例**当前缓冲**（非历史检索；重启/滚动后旧日志丢）。要历史检索需给 SAE 配 SLS。
+
+**日志链**: service → AppId → GroupId → InstanceId → `DescribeInstanceLog`
+
+**关键坑**（实测）:
+- API 是 RPC-style `aliyun sae DescribeInstanceLog`，ROA 路径是 `/pop/v1/sam/**instance**/describeInstanceLog`（不是 `/sam/app/...`，写错报 "can not find api by path"）。
+- buildbox 密码在 1P `op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password`（标题带括号必须用 item ID）。
+
+**service → AppId 映射**（cn-prod，2026-06-01；新增/变动用 `aliyun sae ListApplications` 重查）:
+
+| service | AppId |
+|---|---|
+| `gateway-core` | `a08ce23f-3d3e-4d89-a2cf-53c8adba614e` |
+| `agentic-chat` | `6e290c73-a646-43ef-9da5-ad0b2e7eff73` |
+| `gw-admin` | `c6bc5a78-b27f-46e2-825a-eaa338c23645` |
+| `user-auth` | `d6fbf9de-fed6-4165-978f-7b3a0a456acc` |
+| `user-auth-admin` | `54093f99-37bf-4354-abd7-f6e76abdbcb6` |
+| `optima-scout` | `f5bb7e82-e57c-4bd4-83ae-2c25f8d38647` |
+| `optima-skills` | `55a63ee7-fb75-46e4-99f3-20854a699237` |
+| `infisical` | `52b33fc6-b26d-495a-8885-225d38b3d42f` |
+
+**完整脚本**（本地跑、经 buildbox 中转；改 `SERVICE`/`LINES`）:
+```bash
+SERVICE=gateway-core; LINES=80
+BBPW=$(op-win read "op://Optima/gdmixcizjci5bvuu3nuvgg4ooe/password")
+declare -A APPID=(
+  [gateway-core]=a08ce23f-3d3e-4d89-a2cf-53c8adba614e
+  [agentic-chat]=6e290c73-a646-43ef-9da5-ad0b2e7eff73
+  [gw-admin]=c6bc5a78-b27f-46e2-825a-eaa338c23645
+  [user-auth]=d6fbf9de-fed6-4165-978f-7b3a0a456acc
+  [user-auth-admin]=54093f99-37bf-4354-abd7-f6e76abdbcb6
+  [optima-scout]=f5bb7e82-e57c-4bd4-83ae-2c25f8d38647
+  [optima-skills]=55a63ee7-fb75-46e4-99f3-20854a699237
+  [infisical]=52b33fc6-b26d-495a-8885-225d38b3d42f )
+AID=${APPID[$SERVICE]}
+sshpass -p "$BBPW" ssh -o StrictHostKeyChecking=no root@47.94.105.163 "bash -s" <<REMOTE | tail -n $LINES
+P="--region cn-beijing --profile aliyun-optima"
+GID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationGroups --AppId $AID \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin)['Data'][0]['GroupId'])")
+IID=\$(aliyun sae GET /pop/v1/sam/app/describeApplicationInstances --AppId $AID --GroupId \$GID \$P 2>/dev/null | python3 -c "import sys,json;d=json.load(sys.stdin)['Data'];print((d if isinstance(d,list) else d['Instances'])[0]['InstanceId'])")
+aliyun sae DescribeInstanceLog --InstanceId "\$IID" \$P 2>/dev/null | python3 -c "import sys,json;print(json.load(sys.stdin).get('Data',''))"
+REMOTE
+```
+
+**局限 / 提示**:
+- 只取第 1 个 InstanceId；多副本要遍历 `Data` 里全部 instance。
+- `agent-runtime` 不在 SAE（是 ECI 动态容器）——它的日志看 `gateway-core` 里 `eci-bridge` 的转发/错误行，或单独查对应 ECI。
+- 过滤：把上面输出 `| grep -iE 'error|eci|fail'` 即可（例：排 agentic-chat 链路 ECI 失败就 grep `gateway-core` 日志的 `eci-bridge`）。
+
 ## 完整示例脚本
 
 ### Stage 环境

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

@@ -1,12 +1,12 @@
 ---
 name: "grant-balance"
-description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod 两个环境。"
+description: "当用户请求赠送余额、充值 USD 余额、grant balance、加余额、奖励、补偿、推荐奖励、运营发放时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
 allowed-tools: ["Bash"]
 ---
 
 # 赠送 USD 余额（Grant Balance）
 
-当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额按 $1=700 积分换算，经 billing API 入 **bonus 积分桶（30 天有效期）**（P15 钱包退役后语义），billing 服务在扣费时会优先消费 granted balance。
 
 ## 执行方式：使用 CLI 工具
 
@@ -17,8 +17,8 @@ optima-grant-balance <email> --amount <usd> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（纯追加到 granted balance）
-- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+- 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
+- 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
 
 ## 适用情况
 
@@ -41,7 +41,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 ```
 
 > **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
-> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+> 数据库底层用 micro-USD 精度（1 USD = 700 积分（P15 统一账本口径）
 
 ### 参数说明
 
@@ -50,7 +50,9 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod（国内环境）**：全程 HTTPS（auth-cn/billing-cn.optima.chat），email 查找走 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分，与 CN ¥1 = 100 积分同一账本单位）。例：`optima-grant-balance user@example.com --amount 1 --env cn-prod`
 
 ## 与 grant-subscription 的区别
 
@@ -93,10 +95,10 @@ 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`）
+4. **Audit trail**：每次赠送对应一个 credit_lot（幂等键前缀 `dev-skills-grant:`，type=bonus）
 
 ## 相关命令
 
 - `optima-grant-balance` - 赠送 USD 余额（主要方式）
 - `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）
+- `optima-query-db` - 查询数据库验证结果（`GET /api/billing/balance（credits.byType.bonus）或 query-db credit_lot

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

@@ -1,6 +1,6 @@
 ---
 name: "grant-subscription"
-description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod 两个环境。"
+description: "当用户请求开通会员、赠送订阅、grant subscription、开通 Pro/Starter/Enterprise、升级计划、给用户开会员时，使用此技能。支持 Stage、Prod、cn-prod 三个环境。"
 allowed-tools: ["Bash"]
 ---
 
@@ -19,8 +19,8 @@ optima-grant-subscription <email> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 自动取消旧订阅、重置 wallet granted balance
-- 自动按 plan 配置授予 USD wallet 余额和 token quota
+- 自动取消旧订阅、经 billing API supersede 旧授予（void 旧 subscription lot + 发新）
+- 自动按 plan 配置发放 subscription 积分（期末过期）和 token quota
 - 一条命令完成所有操作
 
 ## 适用情况
@@ -46,6 +46,10 @@ optima-grant-subscription user@example.com --plan starter --months 3
 
 # 开通 Enterprise，Prod 环境
 optima-grant-subscription user@example.com --plan enterprise --env prod
+
+# cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
+optima-grant-subscription user@example.com --env cn-prod
+optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
 ```
 
 ### 参数说明
@@ -55,7 +59,9 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 | `<email>` | 用户邮箱（必填） | - |
 | `--plan <id>` | 计划：trial, starter, pro, enterprise | pro |
 | `--months <n>` | 时长（月） | 1 |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod（国内环境）**：plan 用 CNY 定价的 `-cn` 档（trial / starter-cn / pro-cn / enterprise-cn，默认 pro-cn）；裸 USD 档 id 会被客户端拒绝（防止给 CN 用户误赠 USD 档积分量）。email 查找走 user-auth internal lookup API（无 SSH 隧道）。
 
 ### 计划配置
 
@@ -66,7 +72,7 @@ optima-grant-subscription user@example.com --plan enterprise --env prod
 | 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`。
+> 积分经 billing API 发放（subscription 桶，期末过期；P15 后无 wallet）
 
 ## 常见使用场景
 
@@ -102,7 +108,7 @@ optima-grant-subscription user@example.com --plan starter --env prod
 2. 加载对应 plan 的配置（月授予额、token 限额等）
 3. 取消该用户的所有活跃订阅
 4. 创建新订阅（设置到期时间）
-5. 重置 wallet granted balance 并授予新额度
+5. 经 billing API supersede 旧授予（void 旧 subscription lot + 发新） 并授予新额度
 6. 记录 topup 审计记录（source: subscription_grant）
 7. 更新 token quota 限额
 

package/.claude/skills/logs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "logs"
-description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志时，使用此技能。支持 CI、Stage、Prod 三个环境的 commerce-backend、user-auth、agentic-chat、bi-backend、session-gateway 等服务。"
+description: "当用户请求查看日志、查看服务日志、排查问题、看看日志、检查日志、商品服务日志、后端日志、API日志、正式环境日志、生产环境日志、CI环境日志、开发环境日志、阿里云日志、cn-prod 日志、SAE 日志时，使用此技能。支持 CI、Stage、Prod（AWS ECS/CloudWatch）以及 cn-prod（阿里云 SAE，经 buildbox）四个环境的 commerce-backend、user-auth、agentic-chat、gateway-core、optima-scout、optima-skills 等服务。"
 allowed-tools: ["Bash", "SlashCommand"]
 ---
 
@@ -175,6 +175,19 @@ INFO - Database query took 3200ms: SELECT * FROM products WHERE...
 - 通过 CloudWatch Logs 查看
 - 日志保留 7 天
 
+### cn-prod 环境（阿里云）
+
+```
+/logs gateway-core 100 cn-prod
+/logs agentic-chat 80 cn
+```
+
+**特点**：
+- 阿里云 **SAE**（cn-beijing），不是 AWS
+- 经 buildbox（`root@47.94.105.163`）调 SAE `DescribeInstanceLog`
+- SAE 未配 SLS → 只取实例**当前 stdout 缓冲**（非历史检索）
+- 技术细节 + service→AppId 映射见 `/logs --help`（第 3 节）
+
 ## 支持的服务列表
 
 | 服务 | 说明 | CI | Stage | Prod |

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

@@ -1,11 +1,11 @@
 ---
 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."
+description: "Use when the user wants to grant credits (bonus, 30-day expiry) to an Optima user — for promotional grants, compensation, referral rewards, etc. $1 = 700 credits via billing API; does not affect subscriptions."
 ---
 
 # 赠送 USD 余额（Grant Balance）
 
-当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额会加到 `usd_wallets.granted_balance_micros`，billing 服务在扣费时会优先消费 granted balance。
+当你需要为用户赠送 wallet USD 余额时，使用这个场景。金额按 $1=700 积分换算，经 billing API 入 **bonus 积分桶（30 天有效期）**（P15 钱包退役后语义），billing 服务在扣费时会优先消费 granted balance。
 
 ## 执行方式：使用 CLI 工具
 
@@ -16,8 +16,8 @@ optima-grant-balance <email> --amount <usd> [options]
 **为什么使用 CLI 工具**：
 - 自动通过 email 查找 userId（跨 user-auth 数据库）
 - 自动处理 SSH 隧道和数据库连接
-- 不会影响现有订阅和已有余额（纯追加到 granted balance）
-- 自动写入 audit trail（`usd_wallet_topups` source=admin_grant）
+- 不会影响现有订阅和已有余额（发放 bonus 积分（30 天有效期，重复执行会叠加发放））
+- 自动留审计痕迹（credit_lot 行，幂等键前缀 `dev-skills-grant:`）
 
 ## 适用情况
 
@@ -40,7 +40,7 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 ```
 
 > **单位是美元（USD）**。`--amount 5` 即赠送 $5.00 到 granted balance。
-> 数据库底层用 micro-USD 精度（1 USD = 1,000,000 micros），CLI 自动换算。
+> 数据库底层用 micro-USD 精度（1 USD = 700 积分（P15 统一账本口径）
 
 ### 参数说明
 
@@ -49,7 +49,9 @@ optima-grant-balance user@example.com --amount 20 --description "服务中断补
 | `<email>` | 用户邮箱（必填） | - |
 | `--amount <usd>` | USD 金额（必填，> 0） | - |
 | `--description <text>` | 描述/原因（仅 console 输出） | - |
-| `--env <env>` | 环境：stage, prod | stage |
+| `--env <env>` | 环境：stage, prod, cn-prod | stage |
+
+> **cn-prod**：走 HTTPS（auth-cn/billing-cn.optima.chat），email 查找经 user-auth internal lookup API（无 SSH 隧道）。金额输入仍是 USD（$1 = 700 积分 = ¥7 档积分口径一致）。
 
 ## 与 grant-subscription 的区别
 
@@ -92,10 +94,10 @@ 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`）
+4. **Audit trail**：每次赠送对应一个 credit_lot（幂等键前缀 `dev-skills-grant:`，type=bonus）
 
 ## 相关命令
 
 - `optima-grant-balance` - 赠送 USD 余额（主要方式）
 - `optima-grant-subscription` - 开通订阅计划
-- `optima-query-db` - 查询数据库验证结果（`SELECT granted_balance_micros FROM usd_wallets WHERE user_id=...`）
+- `optima-query-db` - 查询数据库验证结果（`GET /api/billing/balance（credits.byType.bonus）或 query-db credit_lot

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

@@ -21,9 +21,16 @@ optima-grant-subscription user@example.com --plan starter --months 3
 optima-grant-subscription user@example.com --plan enterprise --env prod
 ```
 
+```bash
+# cn-prod（国内环境）：plan 用 -cn 档，默认 pro-cn
+optima-grant-subscription user@example.com --env cn-prod
+optima-grant-subscription user@example.com --plan starter-cn --env cn-prod
+```
+
 ## Guidance
 
 - Default to `stage`.
-- Confirm the user email before running on `prod`.
+- Confirm the user email before running on `prod` / `cn-prod`.
+- `cn-prod` plans are the CNY-priced `-cn` ids (`starter-cn`, `pro-cn`, `enterprise-cn`, plus `trial`); bare USD ids are rejected client-side to avoid granting a USD-priced plan to a CN user.
 - 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/bin/cli.js

@@ -32,6 +32,7 @@ switch (command) {
     log('Available Commands:', 'yellow');
     log('  optima-query-db <service> "<sql>" [env]              Query database', 'cyan');
     log('  optima-show-env <service> [env]                      Show service env vars', 'cyan');
+    log('  optima-verify-health <service> [--env cn|prod|all]   Probe L1-L5 上线健康', 'cyan');
     log('  optima-generate-test-token [--env production]        Generate test token', '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');

package/bin/helpers/billing-http.ts

@@ -5,8 +5,14 @@ import { getInfisicalConfig, getInfisicalToken } from './db-utils';
 const USER_AUTH_URLS: Record<string, string> = {
   stage: 'https://auth.stage.optima.onl',
   prod: 'https://auth.optima.onl',
+  'cn-prod': 'https://auth-cn.optima.chat',
 };
 
+// cn-prod URLs are hardcoded: cn Infisical (secrets-cn.optima.chat) is a
+// separate instance dev-skills has no machine identity for, and these domains
+// are stable. AWS envs keep reading /shared-secrets/domain-urls.
+const CN_PROD_BILLING_URL = 'https://billing-cn.optima.chat';
+
 /**
  * Validate the --env flag value at command entry, before any I/O.
  *
@@ -24,6 +30,20 @@ export function validateEnv(env: string): 'stage' | 'prod' {
   return env;
 }
 
+/**
+ * Variant for commands that also support cn-prod — currently grant-balance /
+ * grant-subscription, which reach billing + user-auth over HTTPS only.
+ * Other commands resolve users via the AWS RDS SSH tunnel, which does not
+ * exist for cn-prod (Aliyun VPC-internal RDS) — keep them on validateEnv so a
+ * cn-prod typo fails fast instead of dying inside the tunnel setup.
+ */
+export function validateEnvCnProd(env: string): 'stage' | 'prod' | 'cn-prod' {
+  if (env !== 'stage' && env !== 'prod' && env !== 'cn-prod') {
+    throw new Error(`--env must be "stage", "prod" or "cn-prod" (got: ${env})`);
+  }
+  return env;
+}
+
 // T1 discovered: client_id differs per env (stage=dev-skills-ubd3qz6n,
 // prod=dev-skills-hinxa0rs). Both stored in Infisical alongside the
 // secret at /shared-secrets/oauth-clients/.
@@ -31,6 +51,21 @@ const DEV_SKILLS_OAUTH_PATH = '/shared-secrets/oauth-clients';
 const DEV_SKILLS_CLIENT_ID_KEY = 'DEV_SKILLS_OAUTH_CLIENT_ID';
 const DEV_SKILLS_CLIENT_SECRET_KEY = 'DEV_SKILLS_OAUTH_CLIENT_SECRET';
 
+// cn-prod: the client (dev-skills-ecee51qo) lives in cn user-auth, but its
+// credentials are mirrored into AWS Infisical (prod environment, same path)
+// under CN_PROD-prefixed keys so we reuse the existing Infisical access —
+// zero new credential chain. Canonical copy lives in cn Infisical
+// /shared-secrets/oauth-clients (DEV_SKILLS_OAUTH_CLIENT_ID/SECRET).
+const DEV_SKILLS_CN_CLIENT_ID_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_ID';
+const DEV_SKILLS_CN_CLIENT_SECRET_KEY = 'DEV_SKILLS_CN_PROD_OAUTH_CLIENT_SECRET';
+
+// cn-prod tokens must carry this scope: resolveUserIdByEmail calls cn
+// user-auth POST /api/v1/internal/users/lookup, whose guard
+// (verify_internal_service_token) requires it. user-auth issues
+// request∩allowed_scopes and an unscoped request yields scope="" (verified
+// against cn-prod 2026-06-12), so the request must name it explicitly.
+const CN_PROD_TOKEN_SCOPE = 'internal:users:write';
+
 // ───── Cache (process-lifetime) ─────────────────────────────────────────────
 // One CLI invocation does at most a handful of HTTP calls. We mint the M2M
 // token once and reuse it. Cross-invocation re-mint is fine — JWT TTL is
@@ -46,6 +81,7 @@ const billingUrlCache: Record<string, string> = {};
 const skillsUrlCache: Record<string, string> = {};
 
 function getBillingUrl(env: string): string {
+  if (env === 'cn-prod') return CN_PROD_BILLING_URL;
   if (billingUrlCache[env]) return billingUrlCache[env];
   const url = fetchInfisicalSecret(env, '/shared-secrets/domain-urls', 'BILLING_URL');
   billingUrlCache[env] = url;
@@ -65,13 +101,20 @@ export function getServiceToken(env: string): string {
   const cfg = getInfisicalConfig();
   const tok = getInfisicalToken(cfg);
   // Fetch BOTH client_id and client_secret from Infisical — they differ per env.
-  const clientId = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_ID_KEY, cfg, tok);
-  const clientSecret = fetchInfisicalSecret(env, DEV_SKILLS_OAUTH_PATH, DEV_SKILLS_CLIENT_SECRET_KEY, cfg, tok);
+  // cn-prod credentials are mirrored in the AWS Infisical *prod* environment
+  // (fetchInfisicalSecret has no cn-prod env slug), under CN-specific keys.
+  const isCn = env === 'cn-prod';
+  const infisicalEnv = isCn ? 'prod' : env;
+  const idKey = isCn ? DEV_SKILLS_CN_CLIENT_ID_KEY : DEV_SKILLS_CLIENT_ID_KEY;
+  const secretKey = isCn ? DEV_SKILLS_CN_CLIENT_SECRET_KEY : DEV_SKILLS_CLIENT_SECRET_KEY;
+  const clientId = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, idKey, cfg, tok);
+  const clientSecret = fetchInfisicalSecret(infisicalEnv, DEV_SKILLS_OAUTH_PATH, secretKey, cfg, tok);
 
   const authUrl = USER_AUTH_URLS[env];
   if (!authUrl) throw new Error(`Unknown env: ${env}`);
 
-  const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}`;
+  const scopeParam = isCn ? `&scope=${encodeURIComponent(CN_PROD_TOKEN_SCOPE)}` : '';
+  const body = `grant_type=client_credentials&client_id=${encodeURIComponent(clientId)}&client_secret=${encodeURIComponent(clientSecret)}${scopeParam}`;
   const response = execSync(
     `curl -s -X POST '${authUrl}/api/v1/oauth/token' -H 'Content-Type: application/x-www-form-urlencoded' -d '${body}'`,
     { encoding: 'utf-8' },
@@ -189,3 +232,40 @@ export async function callSkills<T = unknown>(
 ): Promise<ServiceResponse<T>> {
   return callService<T>(getSkillsUrl(env), env, method, path, body);
 }
+
+/**
+ * Resolve a user's id by email via user-auth's internal lookup endpoint
+ * (POST /api/v1/internal/users/lookup). cn-prod only: AWS envs resolve via
+ * the RDS SSH tunnel (db-utils resolveUserId) and their dev-skills clients
+ * don't carry the internal:users:write scope this endpoint requires.
+ */
+export async function resolveUserIdByEmail(env: string, email: string): Promise<string> {
+  console.log(`Looking up user by email: ${email}`);
+  const token = getServiceToken(env);
+  const authUrl = USER_AUTH_URLS[env];
+  if (!authUrl) throw new Error(`Unknown env: ${env}`);
+
+  const res = await fetch(`${authUrl}/api/v1/internal/users/lookup`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ email }),
+  });
+  const text = await res.text();
+  if (res.status === 404) {
+    throw new Error(`User not found (${env}): ${email}`);
+  }
+  if (!res.ok) {
+    throw new Error(formatServiceError(res.status, res.statusText, text));
+  }
+  let parsed: { user_id?: string };
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new Error(`user-auth lookup returned non-JSON 2xx body: ${text.slice(0, 200)}`);
+  }
+  if (!parsed.user_id) {
+    throw new Error(`user-auth lookup response missing user_id: ${text.slice(0, 200)}`);
+  }
+  console.log(`✓ Found user: ${parsed.user_id}`);
+  return parsed.user_id;
+}