@alphafox/cli 0.3.12 → 0.3.14

package/scripts/uninstall.cjs

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const readline = require("node:readline/promises");
+
+const CLI_PACKAGE = "@alphafox/cli";
+const PROFILES = Object.freeze(["production", "staging", "local"]);
+const NPM_TIMEOUT_MS = 120_000;
+const KEYCHAIN_TIMEOUT_MS = 10_000;
+const USAGE_EXIT = 64;
+const UNINSTALL_RAW_URL =
+  "https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/scripts/uninstall.cjs";
+const UNINSTALL_CURL = `curl -fsSL ${UNINSTALL_RAW_URL} | node -- --yes`;
+const UNINSTALL_DRY_RUN = `curl -fsSL ${UNINSTALL_RAW_URL} | node -- --dry-run`;
+
+function parseUninstallArgs(argv) {
+  let dryRun = false;
+  let yes = false;
+  let help = false;
+  const unknown = [];
+  for (const arg of argv.slice(1)) {
+    if (isLauncherArg(arg)) continue;
+    if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--help" || arg === "-h") help = true;
+    else unknown.push(arg);
+  }
+  return { dryRun, yes, help, unknown };
+}
+
+function isLauncherArg(arg) {
+  return (
+    arg === "-" ||
+    arg === "--" ||
+    arg.endsWith("uninstall.cjs") ||
+    arg.endsWith("uninstall.mjs")
+  );
+}
+
+function uninstallHelpText() {
+  return [
+    "卸载 AlphaFox CLI、Agent Skills、本机配置、登录凭据和回测缓存。",
+    "",
+    "用法：",
+    `  ${UNINSTALL_CURL}`,
+    `  ${UNINSTALL_DRY_RUN}`,
+    "  node scripts/uninstall.cjs [--dry-run|--yes]",
+    "",
+    "不会删除服务器上的策略实例或账户数据。完成后请重启 AI 工具。",
+  ].join("\n");
+}
+
+function homeDir(env) {
+  return env.ALPHAFOX_AGENT_HOME?.trim() || os.homedir();
+}
+
+function isAlphafoxSkillName(name) {
+  return name === "alphafox" || name.startsWith("alphafox-");
+}
+
+function readSkillName(skillMd) {
+  try {
+    const match = fs.readFileSync(skillMd, "utf8").match(
+      /^name:\s*["']?([^"'\s]+)["']?\s*$/m
+    );
+    return match?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function lexists(target) {
+  try {
+    fs.lstatSync(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isAlphafoxSkillDir(target) {
+  if (isAlphafoxSkillName(path.basename(target))) return true;
+  const name = readSkillName(path.join(target, "SKILL.md"));
+  return name != null && isAlphafoxSkillName(name);
+}
+
+function skillRoots(env) {
+  const home = homeDir(env);
+  const claudeHome = env.CLAUDE_CONFIG_DIR?.trim() || path.join(home, ".claude");
+  const codexHome = env.CODEX_HOME?.trim() || path.join(home, ".codex");
+  return [
+    env.ALPHAFOX_SKILLS_DIR?.trim() || path.join(home, ".agents", "skills"),
+    path.join(claudeHome, "skills"),
+    path.join(home, ".cursor", "skills"),
+    path.join(codexHome, "skills"),
+    path.join(home, ".grok", "skills"),
+  ];
+}
+
+function configDir(env) {
+  return env.ALPHAFOX_CONFIG_DIR?.trim() || path.join(homeDir(env), ".config", "alphafox");
+}
+
+function tapeCacheDir(env) {
+  return (
+    env.ALPHAFOX_TAPE_CACHE_DIR?.trim() ||
+    path.join(homeDir(env), ".alphafox", "cache", "engine-backtest")
+  );
+}
+
+function runtimeCacheDir(env) {
+  if (env.ALPHAFOX_BACKTEST_RUNTIME_CACHE_DIR?.trim()) {
+    return env.ALPHAFOX_BACKTEST_RUNTIME_CACHE_DIR.trim();
+  }
+  const xdg = env.XDG_CACHE_HOME?.trim();
+  return path.join(xdg || path.join(homeDir(env), ".cache"), "alphafox", "engine-backtest");
+}
+
+function managedPath(target, env) {
+  const resolved = path.resolve(target);
+  const home = path.resolve(homeDir(env));
+  const roots = [
+    home,
+    env.ALPHAFOX_SKILLS_DIR,
+    env.ALPHAFOX_CONFIG_DIR,
+    env.ALPHAFOX_TAPE_CACHE_DIR,
+    env.ALPHAFOX_BACKTEST_RUNTIME_CACHE_DIR,
+    env.XDG_CACHE_HOME,
+    env.CLAUDE_CONFIG_DIR,
+    env.CODEX_HOME,
+  ]
+    .filter(Boolean)
+    .map((root) => path.resolve(root));
+  if (resolved === home || resolved === path.parse(resolved).root) return false;
+  return roots.some(
+    (root) => resolved === root || resolved.startsWith(root + path.sep)
+  );
+}
+
+function assertRemovable(target, env) {
+  const resolved = path.resolve(target);
+  if (!managedPath(resolved, env)) {
+    throw Object.assign(new Error(`Refusing to remove unmanaged path ${resolved}`), {
+      type: "usage",
+      subtype: "uninstall_path_unsafe",
+    });
+  }
+  return resolved;
+}
+
+function collectSkillPaths(env) {
+  const found = [];
+  for (const root of skillRoots(env)) {
+    if (!lexists(root)) continue;
+    let entries;
+    try {
+      entries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      const target = path.join(root, entry.name);
+      if (isAlphafoxSkillDir(target)) found.push(target);
+    }
+  }
+  return found;
+}
+
+function collectDirPaths(env) {
+  const tape = path.resolve(tapeCacheDir(env));
+  const runtime = path.resolve(runtimeCacheDir(env));
+  const runtimeRoot =
+    path.basename(runtime) === "engine-backtest"
+      ? path.dirname(runtime)
+      : runtime;
+  return [configDir(env), tape, runtimeRoot];
+}
+
+function buildUninstallPlan(env = process.env) {
+  const paths = [...collectSkillPaths(env), ...collectDirPaths(env)]
+    .map((target) => path.resolve(target))
+    .filter((target, index, all) => all.indexOf(target) === index)
+    .filter((target) => lexists(target))
+    .map((target) => ({ kind: "path", path: assertRemovable(target, env) }));
+  return [
+    ...paths,
+    ...PROFILES.map((profile) => ({ kind: "keychain", profile })),
+    { kind: "npm", package: CLI_PACKAGE },
+  ];
+}
+
+function rmdirIfEmpty(dir) {
+  try {
+    fs.rmdirSync(dir);
+  } catch (err) {
+    if (err && (err.code === "ENOENT" || err.code === "ENOTEMPTY")) return;
+    throw err;
+  }
+}
+
+function pruneEmptyParents(target, env) {
+  const home = path.resolve(homeDir(env));
+  let current = path.dirname(path.resolve(target));
+  while (current !== home && current !== path.parse(current).root) {
+    const base = path.basename(current);
+    const parentName = path.basename(path.dirname(current));
+    const alphafoxCache = base === "cache" && parentName === ".alphafox";
+    if (base !== "alphafox" && base !== ".alphafox" && !alphafoxCache) break;
+    rmdirIfEmpty(current);
+    current = path.dirname(current);
+  }
+}
+
+function defaultRunCommand(command, args, options = {}) {
+  const timeout = options.timeoutMs ?? NPM_TIMEOUT_MS;
+  const env = options.env ?? process.env;
+  const platform = options.platform ?? process.platform;
+  const file = platform === "win32" ? "cmd.exe" : command;
+  const argv = platform === "win32" ? ["/c", command, ...args] : args;
+  const result = spawnSync(file, argv, {
+    encoding: "utf8",
+    env: { ...process.env, ...env },
+    timeout,
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+    error: result.error,
+  };
+}
+
+function keychainPlatform(env) {
+  const raw = env.ALPHAFOX_KEYCHAIN_PLATFORM?.trim();
+  if (raw === "darwin" || raw === "linux" || raw === "win32") return raw;
+  return process.platform;
+}
+
+function keychainDeleteArgs(profile, env) {
+  const platform = keychainPlatform(env);
+  const service = `alphafox-cli.${profile}`;
+  if (platform === "darwin") {
+    return {
+      command: "security",
+      args: ["delete-generic-password", "-s", service, "-a", "oauth-tokens"],
+    };
+  }
+  if (platform === "linux") {
+    return {
+      command: env.ALPHAFOX_SECRET_TOOL?.trim() || "secret-tool",
+      args: ["clear", "service", service, "account", "oauth-tokens"],
+    };
+  }
+  return {
+    command: "cmdkey",
+    args: [`/delete:alphafox-cli/${profile}/oauth-tokens`],
+  };
+}
+
+function isMissingSecret(result) {
+  if (result.status === 0) return false;
+  const text = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  return (
+    result.status === 44 ||
+    text.includes("could not be found") ||
+    text.includes("not found") ||
+    text.includes("no such") ||
+    text.includes("cannot find")
+  );
+}
+
+function applyPath(item, env) {
+  fs.rmSync(item.path, { recursive: true, force: true });
+  pruneEmptyParents(item.path, env);
+}
+
+function applyKeychain(item, env, runCommand) {
+  const spec = keychainDeleteArgs(item.profile, env);
+  const result = runCommand(spec.command, spec.args, {
+    env,
+    timeoutMs: KEYCHAIN_TIMEOUT_MS,
+  });
+  if (result.error && result.error.code === "ENOENT") return "skipped";
+  if (result.status === 0) return "removed";
+  if (isMissingSecret(result)) return "skipped";
+  throw new Error(
+    `删除 ${item.profile} 凭据失败：${result.stderr.trim() || result.error || result.status}`
+  );
+}
+
+function applyNpm(env, runCommand) {
+  const result = runCommand("npm", ["uninstall", "-g", CLI_PACKAGE], {
+    env,
+    timeoutMs: NPM_TIMEOUT_MS,
+  });
+  if (result.status === 0 && !result.error) return;
+  throw new Error(
+    `npm uninstall -g ${CLI_PACKAGE} 失败：${(result.stderr || result.stdout).trim() || result.error || result.status}`
+  );
+}
+
+async function confirmUninstall(confirm, isTty) {
+  if (typeof confirm === "function") return confirm();
+  if (!isTty()) return null;
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+  try {
+    const answer = await rl.question(
+      "将卸载全局 @alphafox/cli、本机 Agent Skills、配置、登录凭据和回测缓存。继续？ [Y/n] "
+    );
+    const token = answer.trim().toLowerCase();
+    return token === "" || token === "y" || token === "yes" || token === "是" || token === "好";
+  } finally {
+    rl.close();
+  }
+}
+
+function describeItem(item) {
+  if (item.kind === "path") return item.path;
+  if (item.kind === "keychain") return `keychain:${item.profile}`;
+  return `npm uninstall -g ${item.package}`;
+}
+
+function applyItem(item, env, runCommand, log) {
+  if (item.kind === "path") {
+    applyPath(item, env);
+    log(`已删除 ${item.path}`);
+    return describeItem(item);
+  }
+  if (item.kind === "keychain") {
+    if (applyKeychain(item, env, runCommand) !== "removed") return null;
+    log(`已删除 ${item.profile} 登录凭据`);
+    return describeItem(item);
+  }
+  applyNpm(env, runCommand);
+  log(`已卸载 ${CLI_PACKAGE}`);
+  return describeItem(item);
+}
+
+function usageError(error, hint) {
+  return { ok: false, exitCode: USAGE_EXIT, error, hint, plan: [], removed: [] };
+}
+
+async function approveUninstall(flags, input, isTty, log) {
+  if (flags.yes) return { ok: true };
+  const approved = await confirmUninstall(input.confirm, isTty);
+  if (approved === true) return { ok: true };
+  if (approved === false) {
+    log("已取消。");
+    return { ok: true, cancelled: true, plan: [], removed: [] };
+  }
+  return usageError("非交互卸载需要 --yes。", UNINSTALL_CURL);
+}
+
+async function runUninstall(input = {}) {
+  const env = input.env ?? process.env;
+  const flags = input.flags ?? parseUninstallArgs(process.argv);
+  const log = input.log ?? ((message) => process.stderr.write(`${message}\n`));
+  const runCommand = input.runCommand ?? defaultRunCommand;
+  const isTty =
+    input.isTty ?? (() => Boolean(process.stdin.isTTY && process.stderr.isTTY));
+
+  if (flags.unknown.length > 0) {
+    return usageError(
+      `未知的 uninstall 参数：${flags.unknown.join(" ")}`,
+      "用法：node scripts/uninstall.cjs [--dry-run|--yes]"
+    );
+  }
+  if (flags.help) {
+    log(uninstallHelpText());
+    return { ok: true, help: true, plan: [], removed: [] };
+  }
+
+  const plan = buildUninstallPlan(env);
+  if (flags.dryRun) {
+    log("这是 --dry-run，不会真正删除：");
+    for (const item of plan) log(`  ${describeItem(item)}`);
+    return { ok: true, dryRun: true, plan, removed: [] };
+  }
+
+  const approval = await approveUninstall(flags, input, isTty, log);
+  if (!approval.ok || approval.cancelled) return approval;
+
+  const removed = [];
+  const errors = [];
+  for (const item of plan) {
+    try {
+      const label = applyItem(item, env, runCommand, log);
+      if (label) removed.push(label);
+    } catch (err) {
+      errors.push(err instanceof Error ? err.message : String(err));
+    }
+  }
+  if (errors.length > 0) return { ok: false, exitCode: 1, plan, removed, errors };
+  log("卸载完成。请重启 AI 工具，以便卸载后的 Skills 生效。");
+  return { ok: true, plan, removed };
+}
+
+async function main() {
+  const result = await runUninstall();
+  if (result.error) process.stderr.write(`${result.error}\n`);
+  if (result.hint) process.stderr.write(`${result.hint}\n`);
+  if (result.errors) {
+    for (const line of result.errors) process.stderr.write(`${line}\n`);
+  }
+  process.exit(result.ok ? 0 : (result.exitCode ?? 1));
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  CLI_PACKAGE,
+  PROFILES,
+  UNINSTALL_CURL,
+  UNINSTALL_DRY_RUN,
+  UNINSTALL_RAW_URL,
+  USAGE_EXIT,
+  buildUninstallPlan,
+  isAlphafoxSkillDir,
+  isAlphafoxSkillName,
+  parseUninstallArgs,
+  runUninstall,
+  skillRoots,
+  uninstallHelpText,
+};

package/skills/account/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-account
 description: Account, wallet, and subscription read paths.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Account / wallet

package/skills/admin/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-admin
 description: Admin-only operations reusing Web role authorization.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Admin

package/skills/alphafox/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox
 description: AlphaFox CLI entry router. Use for any AlphaFox request — install, update, login, whoami, 回测, engine backtest, 清理回测缓存 / 历史数据, strategy definitions, create/list/start/stop a running strategy (trader), ticker/标的 resolve (美股 or crypto), market data, exchange connectors, wallet, subscriptions, notifications, or admin. After a successful install and login, present the 新人引导 in this file (Lite square 带单员 + classic strategies). If a CLI command prints `[alphafox] update available`, ask the user「检测到新的版本，是否需要我帮你升级？」and only then run `alphafox update --format json --no-input`. After a large backtest, if tape cache is large, ask「回测下载的历史数据比较大，要不要我帮你清理本地缓存？」then open `alphafox-cache`. Start here, then open the routed domain skill. Do not guess alphafox-engine-backtest vs alphafox-strategy vs alphafox-trading from memory.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # AlphaFox
@@ -18,7 +18,7 @@ A **trader** is a running strategy instance (paper or live), not a person. Creat
 
 | User intent | Skill |
 |---|---|
-| Install, update, Skills status/sync, doctor, version, catalog, how to call the CLI | `alphafox-shared` |
+| Install, update, uninstall, Skills status/sync, doctor, version, catalog, how to call the CLI | `alphafox-shared` |
 | 刚安装完 / 新人引导 / 热门带单员 / 经典策略介绍 | this file, **After install** |
 | Login, logout, whoami, profile, staging vs production | `alphafox-auth` |
 | Ticker / 标的 / 美股 / crypto / resolve a misspelled symbol | `alphafox-market` |
@@ -41,7 +41,7 @@ If several rows apply, load **all** of them (typical: `alphafox-shared` + `alpha
 The CLI may print this on **stderr** at most once every 24 hours:
 
 ```text
-[alphafox] update available: 0.3.11 -> 0.3.12. After the user confirms, run: alphafox update --format json --no-input,
+[alphafox] update available: 0.3.13 -> 0.3.14. After the user confirms, run: alphafox update --format json --no-input,
 ```
 
 If you see that notice (or `updateAvailable: true` from `alphafox update --check`):

package/skills/alphafox-shared/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-shared
 description: Shared AlphaFox CLI rules for Agents — auth, profiles, envelopes, risk gates, and public operationIds only.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # AlphaFox shared Agent contract
@@ -24,6 +24,13 @@ npx @alphafox/cli version --format json --no-input
 npx @alphafox/cli doctor --format json --no-input
 ```
 
+Uninstall is **not** `alphafox uninstall`. After an explicit user request:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/scripts/uninstall.cjs | node -- --dry-run
+curl -fsSL https://raw.githubusercontent.com/alphafoxai/alphafox-cli/main/scripts/uninstall.cjs | node -- --yes
+```
+
 After install, `auth status --verify` shows `session: active`, and the AI tool has restarted, follow skill `alphafox` **After install** (Lite square 带单员 + classic strategies). Do not skip that welcome.
 
 The CLI checks npm at most once every 24 hours and only prints a notice on

package/skills/auth/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-auth
 description: Login, status, logout, whoami, and environment isolation for AlphaFox CLI.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Auth Skill

package/skills/cache/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-cache
 description: Inspect and clean local Engine backtest caches (downloaded OHLCV tape and wasm runtime). Use when the user asks to 清理缓存, free disk, or after a large historical backtest.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Cache

package/skills/engine-backtest/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-engine-backtest
 description: Local Engine WASM backtest (alphafox engine-backtest run|sweep) vs catalog experiment CRUD.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Engine Backtest
@@ -52,6 +52,8 @@ alphafox engine-backtest run \
   --format jsonl --no-input
 ```
 
+`--config` is `{ common, strategy }` (the source file from skill `alphafox-strategy`). It is not the `validate_config` HTTP body `{ configSchemaVersion, config }`.
+
 Also valid: `--from` / `--to` instead of `--range`. `--create-experiment --name "..."` when there is no `--experiment` (needs `strategyDefinitionId` + `strategyDefinitionDisplay` `{zh,en}`; pass `--definition-label-zh` / `--definition-label-en` or the CLI falls back to the definition id). Persisted runs use the account tier from `subscriptions.me.get`; if `--tier` is supplied, it must match. With `--no-persist`, `runs.create` is skipped and `--tier` may simulate `free|pro|pro_max` (default `pro`). `--data-quality` defaults to `basic` (soft gaps finish the run and appear as `coverageNotice`; `prefix_gap` is less severe than `internal_gap`). `--data-quality strict` still fails on any gap. `--replay-timeframe` defaults to `1m` (allowed `1m|3m|5m|15m|30m|1h|4h`); this is the replay/download bar and is merged with plan indicator timeframes so a 4h RSI grid still replays on 1m. `runs.create` is `write`, not `high-risk-write` — do not add `--yes`. Do not update or delete experiments through this command.
 
 `--format jsonl` writes one JSON object per progress line (`{event:"progress",stage,fraction}`), then a final `{ok:true,data:{...}}` envelope.

package/skills/exchange/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-exchange
 description: Exchange connectors list and connection management via Public API.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Exchange connectors

package/skills/market/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-market
 description: Market data and ticker resolution for US equity perps, RWAs, and crypto on the same perp catalog. Use when the user names 美股, NVDA, AAPL, BTC, or any 标的. Keep the operator's asset class via symbolMetadata — do not rewrite NVDA into a crypto coin.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Market

package/skills/notification/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-notification
 description: Notification channels and subscriptions.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Notification

package/skills/strategy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-strategy
 description: Strategy definitions — list types, read a definition's contract, and validate config. Creating a running strategy is creating a trader; use alphafox-trading for that. Local Engine backtest is alphafox-engine-backtest.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Strategy definitions
@@ -42,28 +42,34 @@ The human answers knobs. You write JSON.
 
 1. Confirm the definition from `byId.get` in the operator's language (what it is, what drives it, how positions change).
 2. From `strategyConfigSchema` plus common required fields, ask **only** values the human must choose: symbols (resolve first), direction / mode, size, signal source, leverage. Do not walk every optional key.
-3. Write `strategy-config.json` as:
+3. Write `strategy-config.json` as the trader object:
 
 ```json
 {
-  "configSchemaVersion": 4,
-  "config": {
-    "common": {},
-    "strategy": {}
-  }
+  "common": {},
+  "strategy": {}
 }
 ```
 
-`configSchemaVersion` comes from the definition (`configSchemaVersion` on `byId.get` / list). Omit it only when the schema says it is optional; when present it must match the definition. `common` is shared risk / SLTP / execution / market. `strategy` is this type's parameters and decision logic. Do not use top-level `settings`, `policyId`, or `policyParams`.
+`common` is shared risk / SLTP / execution / market. `strategy` is this type's parameters and decision logic. Do not use top-level `settings`, `policyId`, or `policyParams`. `configSchemaVersion` comes from the definition (`byId.get` / list); keep it off this file.
 
-4. Keys and enums come from the definition schema, not from this skill. Do not ship a default `grid.json` / `dca.json`.
+4. Keys and enums come from the definition schema, not from this skill. Do not ship a default `grid.json` / `dca.json`. Reuse this source file for `engine-backtest --config` and as `trading.traders.create` `config`.
 
 ## Validate config
 
-Read `alphafox schema trading.strategy_definitions.byId.validate_config` first. Catalog `request.body` may look like a free `JsonObject`; still send the envelope above. The server checks the definition schema.
+Read `alphafox schema trading.strategy_definitions.byId.validate_config` first. Catalog `request.body` may look like a free `JsonObject`; still send the HTTP envelope, wrapping the source file — do not overwrite `strategy-config.json`:
+
+```json
+{
+  "configSchemaVersion": 4,
+  "config": { "common": {}, "strategy": {} }
+}
+```
+
+`config` is the contents of `strategy-config.json`. `configSchemaVersion` must match the definition.
 
 ```bash
-alphafox trading strategy_definitions byId validate_config --definitionId <id> --config @./strategy-config.json --format json --no-input
+alphafox trading strategy_definitions byId validate_config --definitionId <id> --config @./validate-config.json --format json --no-input
 ```
 
 `body_schema` / `body_schema_missing` (exit `64`): re-read the operation schema. Server field-path errors: fix that path. Do not retry with a different envelope.

package/skills/trading/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: alphafox-trading
 description: Running strategies (traders) — create, list, start, and stop. A trader is a live or paper strategy instance (grid, dca, copy, …), not a person.
-version: 0.3.12
+version: 0.3.14
 ---
 
 # Running strategies (traders)