@alphafox/cli 0.3.11 → 0.3.12

package/README.md

@@ -86,10 +86,11 @@ skills then use public `operationId`s; an explicit local-execution skill may
 call its co-versioned built-in command.
 
 `alphafox install` (and the [Agent install guide](docs/alphafox-cli-installation-guide.md))
-verify the packaged Skills manifest and sync managed files into Agent skill
-directories (`.cursor/skills`, `.claude/skills`, `~/.agents/skills`, …).
-Use `alphafox skills status` to inspect missing, stale, or modified Skills and
-`alphafox skills sync` to repair safe drift.
+verify the packaged Skills manifest, copy it into `~/.agents/skills`, and link
+each Skill into `~/.claude/skills` (plus `~/.cursor/skills` / `~/.codex/skills`
+when those agents exist). Use `alphafox skills status` to inspect missing,
+stale, modified, or unlinked Skills and `alphafox skills sync` to repair safe
+drift — including Claude Code links when the canonical bundle is already current.
 
 ## Docs
 

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export { parseRequestBodyFlags, loadJsonArg } from "./commands/request-body";
 export { parseInstallArgs, runInstallWizard, semverLessThan, skillsListHasAlphafox, } from "./install/wizard";
 export { AGENT_INSTALL_GUIDE_BLOB_URL, AGENT_INSTALL_GUIDE_URL, SKILLS_GITHUB_SOURCE, } from "./install/types";
 export { buildSkillsManifest, inspectSkills, loadAndVerifySkillsManifest, loadSkillsState, syncSkills, writeSkillsManifest, } from "./skills/manager";
+export type { AgentSkillLinkStatus } from "./skills/manager";
 export { inspectCurrentSkills, installedSkillsRoot, skillsStatePath, syncCurrentSkills, } from "./skills/run-command";
 export { executeCliUpdate, parseUpdateArgs, } from "./update/run-command";
 export { formatUpdateNotice, maybeNotifyCliUpdate, shouldSkipUpdateCheck, } from "./update/notify";

package/dist/install/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSkillLinkStatus } from "../skills/manager";
 /** @deprecated AlphaFox Skills updates must use the verified npm package bundle. */
 export declare const SKILLS_GITHUB_SOURCE = "alphafoxai/alphafox-cli";
 export declare const SKILLS_NAME_PREFIX = "alphafox-";
@@ -22,6 +23,7 @@ export interface InstallSkillsStep {
     readonly removed?: readonly string[];
     readonly blocked?: readonly string[];
     readonly backupDir?: string;
+    readonly agentLinks?: readonly AgentSkillLinkStatus[];
     readonly restartRequired?: boolean;
 }
 export interface InstallAuthStep {

package/dist/install/wizard.js

@@ -17,7 +17,6 @@ const exec_1 = require("./exec");
 const package_root_1 = require("./package-root");
 const types_1 = require("./types");
 const NPM_TIMEOUT_MS = 120_000;
-const SKILLS_TIMEOUT_MS = 120_000;
 function parseInstallArgs(args) {
     let noAuth = false;
     let help = false;
@@ -58,7 +57,7 @@ function nextSteps(input) {
     if (input.auth.action === "skipped" || input.auth.action === "planned") {
         steps.push("alphafox auth login --browser --format json --no-input", "alphafox auth login --no-wait --format json --no-input");
     }
-    steps.push("alphafox doctor --format json --no-input", `Agent 安装指南：${types_1.AGENT_INSTALL_GUIDE_BLOB_URL}`);
+    steps.push("alphafox doctor --format json --no-input", `Agent 安装指南：${types_1.AGENT_INSTALL_GUIDE_BLOB_URL}`, "登录并重启后，按 alphafox skill 的 After install 向用户展示新人引导。");
     if (input.dryRun) {
         steps.unshift("这是 --dry-run，去掉该参数再运行才会真正安装。");
     }
@@ -218,30 +217,7 @@ async function stepInstallSkills(flags, runner) {
         ? `将同步 Skills ${manifest.packageVersion}（${source}）`
         : `正在同步 AI Skills ${manifest.packageVersion}…`);
     try {
-        const result = await (0, manager_1.syncSkills)({
-            manifest,
-            packageRoot: source,
-            installedRoot: (0, run_command_1.installedSkillsRoot)(runner.env),
-            statePath: (0, run_command_1.skillsStatePath)(runner.env),
-            dryRun: flags.dryRun,
-            force: false,
-        }, {
-            install: async (names) => {
-                await runner.exec("npx", [
-                    "-y",
-                    "skills",
-                    "add",
-                    source,
-                    "-y",
-                    "-g",
-                    "--skill",
-                    ...names,
-                ], { timeoutMs: SKILLS_TIMEOUT_MS });
-            },
-            remove: async (names) => {
-                await runner.exec("npx", ["-y", "skills", "remove", ...names, "-y", "-g"], { timeoutMs: SKILLS_TIMEOUT_MS });
-            },
-        });
+        const result = await (0, run_command_1.syncCurrentSkills)({ force: false, dryRun: flags.dryRun }, runner.env, { runner, packageRoot: source });
         const action = result.blocked.length > 0
             ? "blocked"
             : result.action === "planned"
@@ -268,6 +244,7 @@ async function stepInstallSkills(flags, runner) {
             removed: result.removed,
             blocked: result.blocked,
             backupDir: result.backupDir,
+            agentLinks: result.status.agentLinks,
             restartRequired: result.restartRequired,
         };
     }

package/dist/skills/agent-links.d.ts

@@ -0,0 +1,29 @@
+import { type AgentSkillLinkStatus, type SkillsStatus, type SkillsSyncResult } from "./manager";
+export interface AgentSkillTarget {
+    readonly id: "claude-code" | "cursor" | "codex";
+    readonly required: boolean;
+    readonly home: string;
+    readonly skillsDir: string;
+}
+export interface AgentLinkChange {
+    readonly agent: AgentSkillTarget["id"];
+    readonly name: string;
+}
+export interface AgentLinkInput {
+    readonly canonicalRoot: string;
+    readonly skillNames: readonly string[];
+    readonly homeDir: string;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export declare function agentHomeDir(env?: NodeJS.ProcessEnv): string;
+export declare function resolveAgentSkillTargets(homeDir: string, env?: NodeJS.ProcessEnv): readonly AgentSkillTarget[];
+export declare function inspectAgentLinks(input: AgentLinkInput): readonly AgentSkillLinkStatus[];
+export declare function ensureAgentLinks(input: AgentLinkInput): readonly AgentLinkChange[];
+export declare function removeAgentLinks(input: AgentLinkInput): void;
+export declare function attachAgentLinks(status: SkillsStatus, env?: NodeJS.ProcessEnv): SkillsStatus;
+export declare function applyAgentLinkPass(result: SkillsSyncResult, input: {
+    readonly dryRun: boolean;
+    readonly env: NodeJS.ProcessEnv;
+    readonly canonicalRoot: string;
+}): SkillsSyncResult;
+export declare function agentLinksNeedWork(agentLinks: readonly AgentSkillLinkStatus[]): boolean;

package/dist/skills/agent-links.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentHomeDir = agentHomeDir;
+exports.resolveAgentSkillTargets = resolveAgentSkillTargets;
+exports.inspectAgentLinks = inspectAgentLinks;
+exports.ensureAgentLinks = ensureAgentLinks;
+exports.removeAgentLinks = removeAgentLinks;
+exports.attachAgentLinks = attachAgentLinks;
+exports.applyAgentLinkPass = applyAgentLinkPass;
+exports.agentLinksNeedWork = agentLinksNeedWork;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const manager_1 = require("./manager");
+function agentHomeDir(env = process.env) {
+    return env.ALPHAFOX_AGENT_HOME?.trim() || (0, node_os_1.homedir)();
+}
+function resolveAgentSkillTargets(homeDir, env = process.env) {
+    const claudeHome = env.CLAUDE_CONFIG_DIR?.trim() || (0, node_path_1.join)(homeDir, ".claude");
+    const cursorHome = (0, node_path_1.join)(homeDir, ".cursor");
+    const codexHome = env.CODEX_HOME?.trim() || (0, node_path_1.join)(homeDir, ".codex");
+    return [
+        {
+            id: "claude-code",
+            required: true,
+            home: claudeHome,
+            skillsDir: (0, node_path_1.join)(claudeHome, "skills"),
+        },
+        {
+            id: "cursor",
+            required: false,
+            home: cursorHome,
+            skillsDir: (0, node_path_1.join)(cursorHome, "skills"),
+        },
+        {
+            id: "codex",
+            required: false,
+            home: codexHome,
+            skillsDir: (0, node_path_1.join)(codexHome, "skills"),
+        },
+    ];
+}
+function inspectAgentLinks(input) {
+    return activeTargets(input).map((target) => classifyTarget(target, input));
+}
+function ensureAgentLinks(input) {
+    const created = [];
+    for (const status of inspectAgentLinks(input)) {
+        if (status.missing.length === 0)
+            continue;
+        (0, node_fs_1.mkdirSync)(status.skillsDir, { recursive: true });
+        for (const name of status.missing) {
+            linkSkillDir((0, node_path_1.join)(input.canonicalRoot, name), (0, node_path_1.join)(status.skillsDir, name));
+            created.push({ agent: status.id, name });
+        }
+    }
+    return created;
+}
+function removeAgentLinks(input) {
+    for (const target of activeTargets(input)) {
+        for (const name of input.skillNames) {
+            const dest = (0, node_path_1.join)(target.skillsDir, name);
+            if (!lexists(dest))
+                continue;
+            if (!isOurAgentLink(dest, (0, node_path_1.join)(input.canonicalRoot, name)))
+                continue;
+            (0, node_fs_1.unlinkSync)(dest);
+        }
+    }
+}
+function attachAgentLinks(status, env = process.env) {
+    const skillNames = status.skills
+        .filter((skill) => skill.status !== "missing")
+        .map((skill) => skill.name);
+    const agentLinks = inspectAgentLinks({
+        canonicalRoot: status.installedRoot,
+        skillNames,
+        homeDir: agentHomeDir(env),
+        env,
+    });
+    return {
+        ...status,
+        agentLinks,
+        restartRequired: status.restartRequired || agentLinksNeedWork(agentLinks),
+    };
+}
+function applyAgentLinkPass(result, input) {
+    const skillNames = result.status.skills
+        .filter((skill) => skill.status !== "missing")
+        .map((skill) => skill.name);
+    const linkInput = {
+        canonicalRoot: input.canonicalRoot,
+        skillNames,
+        homeDir: agentHomeDir(input.env),
+        env: input.env,
+    };
+    const created = input.dryRun ? [] : ensureAgentLinks(linkInput);
+    const status = attachAgentLinks(result.status, input.env);
+    if (!input.dryRun && agentLinksNeedWork(status.agentLinks)) {
+        throw Object.assign(new Error(`Failed to link Skills into Agent directories: ${missingAgentSummary(status.agentLinks)}`), {
+            type: "install",
+            subtype: "skills_agent_link_failed",
+            details: status.agentLinks.filter((item) => item.missing.length > 0),
+        });
+    }
+    const linked = created.length > 0 || agentLinksNeedWork(status.agentLinks);
+    return {
+        ...result,
+        status,
+        action: nextSyncAction(result.action, linked, input.dryRun),
+        restartRequired: result.restartRequired || linked,
+    };
+}
+function agentLinksNeedWork(agentLinks) {
+    return agentLinks.some((item) => item.missing.length > 0);
+}
+function activeTargets(input) {
+    return resolveAgentSkillTargets(input.homeDir, input.env ?? {}).filter((target) => target.required || (0, node_fs_1.existsSync)(target.home));
+}
+function classifyTarget(target, input) {
+    const linked = [];
+    const missing = [];
+    const blocked = [];
+    for (const name of input.skillNames) {
+        const state = classifyLink((0, node_path_1.join)(input.canonicalRoot, name), (0, node_path_1.join)(target.skillsDir, name));
+        if (state === "linked")
+            linked.push(name);
+        else if (state === "blocked")
+            blocked.push(name);
+        else
+            missing.push(name);
+    }
+    return {
+        id: target.id,
+        skillsDir: target.skillsDir,
+        linked,
+        missing,
+        blocked,
+    };
+}
+function classifyLink(canonical, dest) {
+    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(canonical, "SKILL.md")))
+        return "missing";
+    if ((0, node_path_1.resolve)(canonical) === (0, node_path_1.resolve)(dest))
+        return "linked";
+    if (!lexists(dest) || isBrokenSymlink(dest))
+        return "missing";
+    if (isOurAgentLink(dest, canonical))
+        return "linked";
+    return "blocked";
+}
+function isOurAgentLink(dest, canonical) {
+    if (pointsAtCanonical(dest, canonical))
+        return true;
+    try {
+        const stat = (0, node_fs_1.lstatSync)(dest);
+        if (stat.isSymbolicLink() || !stat.isDirectory())
+            return false;
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dest, "SKILL.md")))
+            return false;
+        return (0, manager_1.hashSkillDirectory)(dest) === (0, manager_1.hashSkillDirectory)(canonical);
+    }
+    catch {
+        return false;
+    }
+}
+function pointsAtCanonical(dest, canonical) {
+    try {
+        if ((0, node_fs_1.lstatSync)(dest).isSymbolicLink()) {
+            const resolved = (0, node_path_1.resolve)((0, node_path_1.dirname)(dest), (0, node_fs_1.readlinkSync)(dest));
+            if ((0, node_path_1.resolve)(resolved) === (0, node_path_1.resolve)(canonical))
+                return true;
+        }
+    }
+    catch {
+        // Compare real paths below when the symlink metadata is unreadable.
+    }
+    try {
+        return (0, node_fs_1.realpathSync)(dest) === (0, node_fs_1.realpathSync)(canonical);
+    }
+    catch {
+        return false;
+    }
+}
+function linkSkillDir(canonical, dest) {
+    if (isBrokenSymlink(dest))
+        (0, node_fs_1.unlinkSync)(dest);
+    (0, node_fs_1.symlinkSync)(canonical, dest, process.platform === "win32" ? "junction" : undefined);
+}
+function lexists(path) {
+    try {
+        (0, node_fs_1.lstatSync)(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isBrokenSymlink(path) {
+    try {
+        return (0, node_fs_1.lstatSync)(path).isSymbolicLink() && !(0, node_fs_1.existsSync)(path);
+    }
+    catch {
+        return false;
+    }
+}
+function nextSyncAction(action, linked, dryRun) {
+    if (!linked || action !== "skipped")
+        return action;
+    return dryRun ? "planned" : "synced";
+}
+function missingAgentSummary(agentLinks) {
+    return agentLinks
+        .filter((item) => item.missing.length > 0)
+        .map((item) => `${item.id} (${item.missing.join(", ")})`)
+        .join("; ");
+}

package/dist/skills/manager.d.ts

@@ -39,6 +39,13 @@ export interface InspectedSkill {
     readonly status: SkillStatus;
     readonly managed: boolean;
 }
+export interface AgentSkillLinkStatus {
+    readonly id: "claude-code" | "cursor" | "codex";
+    readonly skillsDir: string;
+    readonly linked: readonly string[];
+    readonly missing: readonly string[];
+    readonly blocked: readonly string[];
+}
 export interface SkillsStatus {
     readonly bundleVersion: string;
     readonly contractVersion: string;
@@ -52,6 +59,7 @@ export interface SkillsStatus {
         readonly modified: boolean;
     }[];
     readonly summary: Readonly<Record<SkillStatus, number>>;
+    readonly agentLinks: readonly AgentSkillLinkStatus[];
     readonly restartRequired: boolean;
 }
 export interface SkillsSyncResult {

package/dist/skills/manager.js

@@ -183,6 +183,7 @@ function inspectSkills(input) {
         skills,
         orphans,
         summary,
+        agentLinks: [],
         restartRequired: summary.missing + summary.stale + summary.modified + orphans.length > 0,
     };
 }

package/dist/skills/run-command.js

@@ -12,6 +12,7 @@ const profiles_1 = require("../config/profiles");
 const envelope_1 = require("../envelope");
 const exec_1 = require("../install/exec");
 const package_root_1 = require("../install/package-root");
+const agent_links_1 = require("./agent-links");
 const manager_1 = require("./manager");
 const SKILLS_TIMEOUT_MS = 120_000;
 function installedSkillsRoot(env = process.env) {
@@ -33,25 +34,34 @@ function resolveCurrentSkillsPackageRoot(searchDirs = [__dirname, process.cwd()]
 }
 function inspectCurrentSkills(env = process.env, packageRoot = resolveCurrentSkillsPackageRoot()) {
     const manifest = (0, manager_1.loadAndVerifySkillsManifest)(packageRoot);
-    return (0, manager_1.inspectSkills)({
+    return (0, agent_links_1.attachAgentLinks)((0, manager_1.inspectSkills)({
         manifest,
         installedRoot: installedSkillsRoot(env),
         state: (0, manager_1.loadSkillsState)(skillsStatePath(env)),
-    });
+    }), env);
 }
 async function syncCurrentSkills(input, env = process.env, deps = {}) {
     const packageRoot = deps.packageRoot ?? resolveCurrentSkillsPackageRoot();
     const runner = deps.runner ??
         (0, exec_1.createDefaultInstallRunner)(env, [__dirname, process.cwd()]);
+    const canonicalRoot = installedSkillsRoot(env);
     const manifest = (0, manager_1.loadAndVerifySkillsManifest)(packageRoot);
-    return await (0, manager_1.syncSkills)({
+    const result = await (0, manager_1.syncSkills)({
         manifest,
         packageRoot,
-        installedRoot: installedSkillsRoot(env),
+        installedRoot: canonicalRoot,
         statePath: skillsStatePath(env),
         dryRun: input.dryRun,
         force: input.force,
-    }, {
+    }, skillsBundleDeps(runner, packageRoot, canonicalRoot, env));
+    return (0, agent_links_1.applyAgentLinkPass)(result, {
+        dryRun: input.dryRun,
+        env,
+        canonicalRoot,
+    });
+}
+function skillsBundleDeps(runner, packageRoot, canonicalRoot, env) {
+    return {
         install: async (names) => {
             await runner.exec("npx", [
                 "-y",
@@ -66,8 +76,14 @@ async function syncCurrentSkills(input, env = process.env, deps = {}) {
         },
         remove: async (names) => {
             await runner.exec("npx", ["-y", "skills", "remove", ...names, "-y", "-g"], { timeoutMs: SKILLS_TIMEOUT_MS });
+            (0, agent_links_1.removeAgentLinks)({
+                canonicalRoot,
+                skillNames: names,
+                homeDir: (0, agent_links_1.agentHomeDir)(env),
+                env,
+            });
         },
-    });
+    };
 }
 async function cmdSkills(args, flags, env = process.env, deps = {}) {
     const parsed = parseSkillsArgs(args);
@@ -81,6 +97,7 @@ async function cmdSkills(args, flags, env = process.env, deps = {}) {
             ],
             notes: [
                 "Skills are synced only from the verified bundle inside the installed @alphafox/cli package",
+                "Sync also links Skills into ~/.claude/skills (and ~/.cursor/skills, ~/.codex/skills when those agents are present)",
                 "Modified Skills are preserved unless --force --yes is explicit",
                 "Restart the AI tool after a successful sync",
             ],

package/dist/skills-manifest.json

@@ -1,153 +1,153 @@
 {
   "schemaVersion": 1,
   "packageName": "@alphafox/cli",
-  "packageVersion": "0.3.11",
+  "packageVersion": "0.3.12",
   "contractVersion": "2026-08-13",
-  "bundleHash": "10abd3fc0d5bbd4a260f42a02bff35899e829543419cf0f678077546a7bebcc6",
+  "bundleHash": "5129a939b6c209ec5e5d1a08ee94fe3c4999c53bd251731314c27de29f8ff5f0",
   "skills": [
     {
       "name": "alphafox",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "ebc6138b666514ef543cf5b444d3ff293bd439eae5c39a231fada5b4dae27b11",
-          "size": 4408
+          "sha256": "37dc3b595471e1130662a54d8aed35e12a32222d2f95d3fadf3c9f5636a52ac9",
+          "size": 7415
         }
       ],
-      "hash": "c4c73d98a0ad828e66fccb406294ab3533530b1d003c71eebd9e569895cbf305"
+      "hash": "87347f1a8364fa982399b5641d6ff347c85376425e589ad6581001b1d1fefaac"
     },
     {
       "name": "alphafox-account",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "714b3f0094a67bc08764ae26f900e3f61463950b2a031f4b46a478a968deea74",
+          "sha256": "c4cdac0a980106ad110c306b5248b9b8f325d9de60e50f39d412b40854238a36",
           "size": 784
         }
       ],
-      "hash": "94085eb4ec63d15a217df97878282c7f0c1e59c93dfd34e26279113cdcc7b625"
+      "hash": "743b0f52a8f707f568c8ba9fba28d648d67d7ed524c6b41b550b9dd8d56434a0"
     },
     {
       "name": "alphafox-admin",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "dcdd0cdd11e6c4160e314766b7150b70fb0b0b6b52b4ad65723853c0ccefdd93",
+          "sha256": "6f06d16bd52b3d8651b91b0b6e4dc606d1d98de5827fc5c164f6d23705de3910",
           "size": 788
         }
       ],
-      "hash": "38f9a8eff99035a55e40e96bd156d407282aa09adcf0c08b7713b18508c112dc"
+      "hash": "ccbca03ae872a794eb950897b8cac4f398014a9c014ac956245c89ffb08bf4f0"
     },
     {
       "name": "alphafox-auth",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "1cc9b91b9f3994d3f0fde453fba4c08c0ff18849692518c1a73182cfc6267066",
+          "sha256": "5985bdd0663d806e8ae8ab08d2ef2e1c1aa99b541ff5a5e72b14337eff3f22e6",
           "size": 2371
         }
       ],
-      "hash": "f14d148e80c7c25b9306e57039e10b341b04c06fbe8c0602b60d49033436a149"
+      "hash": "a42814a37f6cddf2e21f6badd1f66254091d734d1210c87cff6e11ea17432241"
     },
     {
       "name": "alphafox-cache",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "292e0075bd55f5036a6bcb3afbc6184f5e010e4840b80c1940bbaa51bf8f2a9e",
+          "sha256": "9653fe4bc132b2f587a57cebf5c646527faf4f081d51f80645c3be34e952161e",
           "size": 1530
         }
       ],
-      "hash": "4baa604211122515fa189bb5830d4b4b0633a92b585fd91b918879828d221740"
+      "hash": "e3c8c25d221c5b0574f17d455b2c29d8a8c075c2a007cac4302c0fa47ea1e226"
     },
     {
       "name": "alphafox-engine-backtest",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "a0e00cdd48c4c4da1bbbe0d54f2b08dda273e6b6d7160e5a37485e7002218d05",
+          "sha256": "1bd19ba3222dd8ab90f69509c8c02db3e2b9ef460c0539816ad83fba396e8e64",
           "size": 8278
         }
       ],
-      "hash": "49f17cdd45fef3c600ee954bb089b239609228dd205f12edad8973c6e2a13fba"
+      "hash": "ff899b9199e5ac28ef77f6fc8bf582d341483d0617933f669ca4f9a40e8d5bef"
     },
     {
       "name": "alphafox-exchange",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "e883d53ce237ecec682555c9171519bf16139fee0db968825a47d8cfc4ccb25b",
+          "sha256": "0dd186a4f7c34b01ad19028da5ecdfe2f15a15e2dc00997e048a7caa54e9d5b2",
           "size": 744
         }
       ],
-      "hash": "087f26e565876d66709fb303cc6e379648a1b7de6f9f54c4015e973b8398fcb8"
+      "hash": "b2a0a6d2ad588da804bbadfd505b395ecace330732b3be5dcc3110f3c4d0a2eb"
     },
     {
       "name": "alphafox-market",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "d37df5d1498d201abd9206f5536ffbbf35fa20ec7f47aa20da40f07abcd3f847",
+          "sha256": "fba7e2e1a8a474234d984ab9bb99a91d003e8e365c10796687d6f7d8b20319ab",
           "size": 3079
         }
       ],
-      "hash": "dc57e16172f577410f80922436593ab5ac5d1d2ab62402fb2c8ee7d8bac84cbd"
+      "hash": "9e804c4418f4745b18915a4c0b8f7b7ef1a2eb4e5263d43cb5f665523b547425"
     },
     {
       "name": "alphafox-notification",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "0fdcc37a21deaee5195c2576ce563b895dc7aac2af2e269a38b2506860fbb5fc",
+          "sha256": "02fc964294afa9630f220ff9bdaed283df15ddd92d52a9d9e48432072dfe87ed",
           "size": 699
         }
       ],
-      "hash": "c4acd5b245e6c1f21f1d35d96a33ffe8c1a4754c8405c92c54180765f14072ea"
+      "hash": "acc77bfbd3f74625e80b4aeabcf2e29ff55eadb9a20a1a421f8be95ab6f2d84b"
     },
     {
       "name": "alphafox-shared",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "cfd0716870fb6bcadbb20c7cad1999f32f8f237cfebb1fa143f6a49687256568",
-          "size": 5386
+          "sha256": "3d9d42c3e63c1f3c524923c9b2c544fe948464e3bf9ea1a7ec898023f68efe7c",
+          "size": 5643
         }
       ],
-      "hash": "939e048cd4243a13a341d0405a13f40d82dd6553a2db5e42765d90dae909331d"
+      "hash": "68affee820b6b6d41d01c0b83cebcd9431fa70eafe975d98736e983d47059d89"
     },
     {
       "name": "alphafox-strategy",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "be35901e6d5c3766f73274552e5403e172a9c3ce9d560fbfd78cb68fd1c894c1",
-          "size": 1827
+          "sha256": "956198df91f79ae2976d5aed8a5842a9e22c907ecafb28378e89fe5b942ee5c2",
+          "size": 4398
         }
       ],
-      "hash": "e031e199ee2c1013e2bc39d2fc2a72b9f734ede86b3ca93d2a3ca53ace1c65cf"
+      "hash": "58e72dbd185c1fa033aa52c63a79478701e3a75c14583fca13459ad55d9b3622"
     },
     {
       "name": "alphafox-trading",
-      "version": "0.3.11",
+      "version": "0.3.12",
       "files": [
         {
           "path": "SKILL.md",
-          "sha256": "2bac318aae54820edf6454c98e8ce4a16b350fce8e0e29c936ea434a72a0857d",
+          "sha256": "09da55fd6ff864c6fdac0b79e106e62d7c3f083610ae71b4fad38439b529dd91",
           "size": 3123
         }
       ],
-      "hash": "2da4c6f7a381472f1d82118d5e44e3c52a1a6e7185b2f9e5a16181aa5f1c89bd"
+      "hash": "5ae19801df517c9c7f73c7d1b64fe0feeb0790ea660905f0971eea5ae9f209f9"
     }
   ]
 }

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.12";
 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.12";
 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)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphafox/cli",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "AlphaFox CLI — Agent/Human entry for the public Application API.",
   "type": "commonjs",
   "bin": {

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.12
 ---
 
 # 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.12
 ---
 
 # 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.12
 ---
 
 # AlphaFox
@@ -19,6 +19,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` |
+| 刚安装完 / 新人引导 / 热门带单员 / 经典策略介绍 | 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.11 -> 0.3.12. 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).

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.11
+version: 0.3.12
 ---
 
 # AlphaFox shared Agent contract
@@ -14,7 +14,7 @@ Co-versioned with `@alphafox/cli`. Query compatibility with `alphafox version --
 
 Prefer the wizard (CLI + Agent Skills) or the Agent install guide. Do not treat
 `npm install -g @alphafox/cli` as enough for Agents — Skills must be registered
-with `alphafox skills sync`.
+with `alphafox skills sync` (canonical store plus `~/.claude/skills` links).
 
 ```bash
 npx @alphafox/cli@latest install
@@ -24,6 +24,8 @@ npx @alphafox/cli version --format json --no-input
 npx @alphafox/cli doctor --format json --no-input
 ```
 
+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
 **stderr**. It never auto-upgrades. If you see
 `[alphafox] update available` (or `updateAvailable: true`), ask the user:

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.11
+version: 0.3.12
 ---
 
 # 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.11
+version: 0.3.12
 ---
 
 # 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.11
+version: 0.3.12
 ---
 
 # Engine Backtest

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.11
+version: 0.3.12
 ---
 
 # 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.11
+version: 0.3.12
 ---
 
 # Market

package/skills/notification/SKILL.md

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

package/skills/strategy/SKILL.md

@@ -1,18 +1,22 @@
 ---
 name: alphafox-strategy
-description: Strategy definitions — list types (grid, dca, copy, …) and validate config. Creating a running strategy is creating a trader; use alphafox-trading for that.
-version: 0.3.11
+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
 ---
 
 # Strategy definitions
 
 Always `--format json --no-input`. Read scopes `trading:read`; validate is `trading:write`.
 
-A **definition** is a strategy type (grid, dca, copy, …). A **trader** is one running instance of a definition. Instantiating a definition is `alphafox-trading`, not this skill.
+A **definition** is a strategy type. A **trader** is one running instance. Instantiating is `alphafox-trading`. Local wasm backtest is `alphafox-engine-backtest`. This skill only discovers types and checks config.
 
-Whenever the human names a ticker (US stock, coin, or contract), resolve it with `alphafox resolve-symbols` (`skills/market`) before writing symbols into a config you later validate or hand to create. 美股 are equity perps in `binance_perp_usdt` (`NVDA/USDT:USDT`, `assetClass=equity_perp`) — do not swap them for a crypto coin.
+Human-named tickers go through `alphafox resolve-symbols` (`skills/market`) before they enter a config you later validate or hand to create. 美股 are equity perps in `binance_perp_usdt` (`NVDA/USDT:USDT`, `assetClass=equity_perp`).
 
-## Read
+Do not enumerate engine strategy IDs in this file. Pick the definition from `list` / `byId.get`. Do not add a wizard command. Do not invent a second catalog.
+
+## Discover
+
+`trading.strategy_definitions.list` returns **active** rows only. Hidden types (including Hyperliquid / rebate copy) are absent from list; `byId.get` and `validate_config` still work when the operator named that id. Creation of those copy variants is `alphafox-trading` (`trading.hl_copy_traders.create` / `trading.rebate_copy_traders.create`).
 
 ```bash
 alphafox schema trading.strategy_definitions.list --format json --no-input
@@ -20,18 +24,51 @@ alphafox api GET /api/v1/trading/strategy-definitions --format json --no-input
 alphafox trading strategy_definitions byId get --definitionId <id> --format json --no-input
 ```
 
-Use the list to pick the definition the operator named. Copy / rebate-copy / DCA / grid are rows in this catalog, not a separate product.
+Match the name the operator used against list `id` / `name` / `display`. If they already gave an id that list omitted, `byId.get` that id. Copy / DCA / grid are catalog rows, not separate products.
+
+`byId.get` is the operator model. Read, in order:
+
+1. `id`, `category` (`COPY` / `DCA` / `GRID` / `TREND` / `OTHERS`), `status`
+2. English `description` (mechanism). Prefer it over marketing `display.description`
+3. `capabilities` and `commonModules` (event-driven vs polling, signal sources, manual sync)
+4. `strategyConfigSchema` required fields and each field's `display` — including decision-logic enums inside this definition
+5. `capabilities.actionDefinitions` (what a manual action changes)
+
+Explain the type from those fields. Missing a layer → say unknown; do not fill from memory. Decision logic (`simple-long`, grid `mode` `neutral`/`long`/`short`) is an internal parameter, not a new definition id.
+
+## Configure with the human
+
+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:
+
+```json
+{
+  "configSchemaVersion": 4,
+  "config": {
+    "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`.
+
+4. Keys and enums come from the definition schema, not from this skill. Do not ship a default `grid.json` / `dca.json`.
 
 ## Validate config
 
-Read `request.body` first. Do not invent definition or config fields.
+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.
 
 ```bash
-alphafox schema trading.strategy_definitions.byId.validate_config --format json --no-input
 alphafox trading strategy_definitions byId validate_config --definitionId <id> --config @./strategy-config.json --format json --no-input
 ```
 
-After the config validates, create the running instance with `alphafox-trading`.
+`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.
+
+After it validates: create with `alphafox-trading`, or backtest with `alphafox-engine-backtest`. Do not create or backtest from this skill.
 
 ## operationIds
 

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.11
+version: 0.3.12
 ---
 
 # Running strategies (traders)