@alphafox/cli 0.3.11 → 0.3.13

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 export declare const CLI_NAME = "alphafox";
 export declare const CLI_PACKAGE = "@alphafox/cli";
-export declare const CLI_VERSION = "0.3.11";
+export declare const CLI_VERSION = "0.3.13";
 export { CATALOG_VERSION as CLI_CONTRACT_VERSION } from "./catalog/operations";

package/dist/version.js

@@ -3,6 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_CONTRACT_VERSION = exports.CLI_VERSION = exports.CLI_PACKAGE = exports.CLI_NAME = void 0;
 exports.CLI_NAME = "alphafox";
 exports.CLI_PACKAGE = "@alphafox/cli";
-exports.CLI_VERSION = "0.3.11";
+exports.CLI_VERSION = "0.3.13";
 var operations_1 = require("./catalog/operations");
 Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });

package/docs/alphafox-cli-installation-guide.md

@@ -24,6 +24,11 @@ npm install -g @alphafox/cli
 alphafox skills sync --format json --no-input
 ```
 
+`alphafox skills sync` writes the verified bundle to `~/.agents/skills` and
+then links each Skill into `~/.claude/skills` so Claude Code can discover it.
+Cursor (`~/.cursor/skills`) and Codex (`~/.codex/skills`) are linked when those
+tools are already present. `alphafox skills status` reports `agentLinks`.
+
 Do not install Skills from GitHub `main` as a fallback. The CLI verifies the
 manifest and hashes inside the npm package before syncing. If sync fails, stop
 and report the error rather than downloading a different Skills version.
@@ -87,8 +92,14 @@ Parse the JSON envelope: `ok === true` means success. Errors land on
 ## Step 4: Tell the user to restart
 
 Ask the user to **restart the AI tool** so the new Skills are loaded.
-Then they can ask the Agent to use AlphaFox. The entry skill `alphafox` routes
-to auth, market, engine-backtest, strategy, trading, and the rest.
+
+## Step 5: New-user welcome
+
+After restart and `alphafox auth status --verify` shows `session: active`,
+follow skill `alphafox` **After install**: fetch the Lite square catalog
+(`lite.catalog_config.get`, `lite.signal_sources.list`) and introduce the
+classic strategy definitions from `trading.strategy_definitions.list`. Do not
+invent 带单员 names. Do not create a trader until the user asks.
 
 ## Human wizard (do not run this from an Agent)
 
@@ -102,3 +113,19 @@ npx @alphafox/cli@latest install
 That wizard installs the CLI globally, verifies and syncs the packaged Skills,
 and may prompt for `alphafox auth login --browser`. It is TTY-oriented.
 Agents must follow Steps 1–4 in this document rather than the wizard.
+
+## Uninstall
+
+Uninstall is a standalone script, not `alphafox uninstall`. After the user
+explicitly asks to uninstall:
+
+```shell
+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
+```
+
+That removes the global `@alphafox/cli` package, Agent Skills under
+`~/.agents/skills` (and Claude / Cursor / Codex / Grok links),
+`~/.config/alphafox`, login tokens, and local Engine backtest caches.
+It does not delete running traders or other server-side data. Ask the user
+to restart the AI tool afterwards. Do not invent a CLI subcommand.

package/docs/release-supply-chain.md

@@ -19,7 +19,7 @@ named `@alphafoxai/cli` (that name was never published; npmjs returns 404).
 | License | MIT |
 | Node | LTS **≥ 20** (`engines.node`) |
 | OS | macOS, Linux, Windows (npm install; no standalone native binary in v1) |
-| Package contents | `bin/`, `dist/`, `skills/`, `README.md`, `docs/`, `LICENSE` |
+| Package contents | `bin/`, `dist/`, `skills/`, `README.md`, `docs/`, `scripts/uninstall.cjs`, `LICENSE` |
 
 v1 does **not** ship independent GitHub Release binaries, so there is no extra
 binary signing/checksum channel. Integrity is npm pack integrity plus
@@ -92,9 +92,9 @@ OIDC-provenance release.
 
 | Platform | Install | Update | Uninstall | Secrets |
 |----------|---------|--------|-----------|---------|
-| macOS | `npm install -g @alphafox/cli` or `npx @alphafox/cli` | `npm update -g @alphafox/cli` or pin `@<version>` | `npm uninstall -g @alphafox/cli` | Keychain Access |
-| Linux | same | same | same | Secret Service, or file fallback mode `0600` |
-| Windows | same | same | same | Credential Manager (`CredWrite`/`CredRead`); file fallback mode `0600` if unavailable |
+| macOS | `npm install -g @alphafox/cli` or `npx @alphafox/cli` | `npm update -g @alphafox/cli` or pin `@<version>` | `scripts/uninstall.cjs` (or `npm uninstall -g @alphafox/cli` plus local Skills/config/cache) | Keychain Access |
+| Linux | same | same | same (`scripts/uninstall.cjs`) | Secret Service, or file fallback mode `0600` |
+| Windows | same | same | same (`scripts/uninstall.cjs`) | Credential Manager (`CredWrite`/`CredRead`); file fallback mode `0600` if unavailable |
 
 Fresh-machine acceptance (release checklist, not optional):
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphafox/cli",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "description": "AlphaFox CLI — Agent/Human entry for the public Application API.",
   "type": "commonjs",
   "bin": {
@@ -15,6 +15,7 @@
     "vendor",
     "README.md",
     "docs",
+    "scripts/uninstall.cjs",
     "LICENSE"
   ],
   "scripts": {

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.11
+version: 0.3.13
 ---
 
 # 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.11
+version: 0.3.13
 ---
 
 # 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. 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.11
+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.13
 ---
 
 # AlphaFox
@@ -18,7 +18,8 @@ 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` |
 | Engine WASM backtest, experiment, `engine-backtest run`, persist a local run | `alphafox-engine-backtest` |
@@ -30,14 +31,17 @@ A **trader** is a running strategy instance (paper or live), not a person. Creat
 | Notification channels | `alphafox-notification` |
 | Admin-only operations | `alphafox-admin` |
 
-If several rows apply, load **all** of them (typical: `alphafox-shared` + `alphafox-market` + one domain skill). “帮我建一个网格/DCA/跟单策略” → `alphafox-strategy` (pick the definition) **and** `alphafox-trading` (create the trader).
+If several rows apply, load **all** of them (typical: `alphafox-shared` + `alphafox-market` + one domain skill).
+
+- “帮我配/建一个网格/DCA/跟单策略” → `alphafox-strategy` (pick definition, ask knobs, validate `{common, strategy}`) **and** `alphafox-market` (resolve tickers) **and** `alphafox-trading` (create the trader). Hidden copy variants still create through `alphafox-trading`.
+- “帮我回测这个配置” → `alphafox-strategy` (definition + config) **and** `alphafox-engine-backtest`.
 
 ## Upgrade reminder
 
 The CLI may print this on **stderr** at most once every 24 hours:
 
 ```text
-[alphafox] update available: 0.3.10 -> 0.3.11. After the user confirms, run: alphafox update --format json --no-input,
+[alphafox] update available: 0.3.12 -> 0.3.13. After the user confirms, run: alphafox update --format json --no-input,
 ```
 
 If you see that notice (or `updateAvailable: true` from `alphafox update --check`):
@@ -54,6 +58,56 @@ alphafox update --format json --no-input
 
 Do not install Skills from GitHub. Details and dry-run / check commands live in `alphafox-shared`.
 
+## After install
+
+After CLI + Skills are installed, login is `session: active`, and the AI tool has restarted, present this welcome **once**. Fetch live data first. Do not invent 带单员 names, ROI, or strategy scenarios.
+
+Classic product names to introduce (match `trading.strategy_definitions.list` `display.label` zh-CN / `name`; then `byId.get` that row — do not hardcode definition ids):
+
+1. 组合跟单策略
+2. 轮动马丁策略
+3. 网格策略
+4. 拼盘策略
+5. 滚仓宝策略
+
+```bash
+alphafox lite catalog_config get --format json --no-input
+alphafox lite signal_sources list --format json --no-input
+alphafox trading strategy_definitions list --format json --no-input
+```
+
+Keep Lite catalog order from `featuredSourceIds`. Resolve `id` → `name` from `lite.signal_sources` `sources[]`. Take the first **3** named rows. Optional ROI:
+
+```bash
+alphafox lite signal_source_metrics list --sourceIds <id,id,id> --window all --mode scalars --format json --no-input
+```
+
+Print `roi` as returned. If the catalog or metrics call fails, skip that part and say the square catalog could not be loaded — do not substitute other signal sources.
+
+For each classic name that matched a definition, `byId.get` and use Chinese `display.description` (fallback English `description`) as the scenario. Then one live leaderboard example:
+
+```bash
+alphafox trader_leaderboard list --strategyDefinitionId <id> --sort roi --order desc --positiveRoi true --window 30d --limit 1 --includePaper false --format json --no-input
+```
+
+Use `items[0].traderName` + `roiPercent` when present. Omit the leaderboard clause when the list is empty.
+
+Present in the operator's language, this shape:
+
+```text
+安装完成！
+以下是最近热门的一些带单员：{name}{、name}{、name}。
+您可以直接通过组合跟单策略来跟随这些带单员，做实时自动化交易。
+
+如果您想配置自己的交易策略，推荐先了解这些内置的经典策略。
+{策略名}：{display.description}。排行榜上 {traderName} 近 30 日收益 {roiPercent}%。
+…
+
+想跟单或者运行策略，告诉我即可。或者您想先看看排行榜，也可以直接告诉我。
+```
+
+Do not create a trader from this welcome. When they pick 跟单 / a classic strategy, read `alphafox-strategy` + `alphafox-trading` (+ `alphafox-market` if they name a ticker). When they ask for 排行榜, list `trader_leaderboard` (same flags, no `strategyDefinitionId` unless they named a type) and summarize — do not dump the envelope.
+
 ## Do not mix these backtest paths
 
 - Local Engine tape + wasm + optional persist → `alphafox-engine-backtest` (`alphafox engine-backtest run`, hyphen).