@alphafox/cli 0.3.4 → 0.3.6

package/dist/skills-manifest.json

@@ -0,0 +1,141 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@alphafox/cli",
+  "packageVersion": "0.3.6",
+  "contractVersion": "2026-08-13",
+  "bundleHash": "1eb4c16a941eee4c125efc6bb64ed7bb0db1d12b71f71cae66e55e64f600cf9a",
+  "skills": [
+    {
+      "name": "alphafox",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "a60f579e6321533d4f965c607f1158ddb50d1a89905d8793eca0b401b3f67fd2",
+          "size": 3055
+        }
+      ],
+      "hash": "c47e6e2d6154e831a681b731e123053c2d20c6c77654191f0a78ae2137ce5304"
+    },
+    {
+      "name": "alphafox-account",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "c60baab539cca008ccc48d53f0262d7a019db82b3945402d16b5ac84624b475f",
+          "size": 783
+        }
+      ],
+      "hash": "e828192ec19a24bc18ce64d07a583eaba498e6a0c356214dbe18ccae6e9f6a6d"
+    },
+    {
+      "name": "alphafox-admin",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "87bbc12b803be021d94ad8161293263ce69e1d6c50f887a245ebe5c0a285e4f6",
+          "size": 787
+        }
+      ],
+      "hash": "2881be10858efaad4543ffbe94f3bf87a91d4b0a4f3d905c3e0a5b8463e8756b"
+    },
+    {
+      "name": "alphafox-auth",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "99e954df23206b0deb32761ce39396897d5af2ee8852e3a8340ed1b9c2e88a46",
+          "size": 1919
+        }
+      ],
+      "hash": "659ca92bdfa0b31bcd1d39d7af151c308f1f9e7cd541bd38cf89326a825a38b8"
+    },
+    {
+      "name": "alphafox-engine-backtest",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "176c329a665709461403671d34e73dd5b58bf389a328010c8a32cec5b949a9c5",
+          "size": 7346
+        }
+      ],
+      "hash": "23db5ab285f8600a43561ce3d4b7641ea45cd55c7c3b16d9f6fb7ff0c862b379"
+    },
+    {
+      "name": "alphafox-exchange",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "089db4794cd55ba04278d4616cd6d5e92bc4c1d4c7c183001ea363bc4eeba578",
+          "size": 743
+        }
+      ],
+      "hash": "d4b0fe876ced82185eb477a23420cb24a8990f3dcbb6d4d5e9412dfd4cd2c279"
+    },
+    {
+      "name": "alphafox-market",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "79fd7431c119b9d9318566c0419e2820ad9b06f0fda2882fdf9d1d7f4c1b9566",
+          "size": 1801
+        }
+      ],
+      "hash": "8814883b9b5bfb7eab4406fe1236091410dcb1130d4904dae8756e1302a02687"
+    },
+    {
+      "name": "alphafox-notification",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "9a90360b83b72bb252349612cb052ffded40d00e07ca8568b76a6b13479252ac",
+          "size": 698
+        }
+      ],
+      "hash": "99f8309b235b2b89734ed49d0a9e0e8981b5216025815fbe69f9101cf4f412cc"
+    },
+    {
+      "name": "alphafox-shared",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "60051a6c9b789e306ec968d3c8762a75039c34a0db2470dfddd1063bf2a3553f",
+          "size": 5071
+        }
+      ],
+      "hash": "20832738f9f15063291309871197b6274fd24f2630bd2525092ac017f7491b68"
+    },
+    {
+      "name": "alphafox-strategy",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "e4188e115eca6610c482bbcdf11ab1eb455cb5b6f242af96d1d8090e6ce9ce9d",
+          "size": 1450
+        }
+      ],
+      "hash": "878fd5c365eb33a431e91f6922a8cf45bcf94a7136b0105d50f3b487112c3573"
+    },
+    {
+      "name": "alphafox-trading",
+      "version": "0.3.6",
+      "files": [
+        {
+          "path": "SKILL.md",
+          "sha256": "098e0f975ae9f0169b0da696b76e74ffd3c6748e898e7c4f8c8f8a33aec47dc8",
+          "size": 1435
+        }
+      ],
+      "hash": "99b72870808f871ddeffd69ee89872e8532f2847494a0e5ad83de48ad58c675a"
+    }
+  ]
+}

package/dist/update/notify.d.ts

@@ -0,0 +1,24 @@
+export declare const UPDATE_CHECK_INTERVAL_MS: number;
+export interface UpdateCheckState {
+    readonly schemaVersion: 1;
+    readonly checkedAt: string;
+    readonly currentVersion: string;
+    readonly latestVersion: string | null;
+    readonly updateAvailable: boolean;
+}
+export interface UpdateNoticeResult {
+    readonly checked: boolean;
+    readonly notified: boolean;
+    readonly latestVersion: string | null;
+}
+export interface UpdateNoticeDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly currentVersion?: string;
+    readonly now?: Date;
+    readonly fetchLatest?: () => Promise<string>;
+    readonly writeNotice?: (line: string) => void;
+}
+export declare function updateCheckStatePath(env?: NodeJS.ProcessEnv): string;
+export declare function formatUpdateNotice(currentVersion: string, latestVersion: string): string;
+export declare function shouldSkipUpdateCheck(command: string | undefined, env?: NodeJS.ProcessEnv): boolean;
+export declare function maybeNotifyCliUpdate(deps?: UpdateNoticeDeps): Promise<UpdateNoticeResult>;

package/dist/update/notify.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPDATE_CHECK_INTERVAL_MS = void 0;
+exports.updateCheckStatePath = updateCheckStatePath;
+exports.formatUpdateNotice = formatUpdateNotice;
+exports.shouldSkipUpdateCheck = shouldSkipUpdateCheck;
+exports.maybeNotifyCliUpdate = maybeNotifyCliUpdate;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const profiles_1 = require("../config/profiles");
+const exec_1 = require("../install/exec");
+const wizard_1 = require("../install/wizard");
+const version_1 = require("../version");
+exports.UPDATE_CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+const NPM_VIEW_TIMEOUT_MS = 4_000;
+function updateCheckStatePath(env = process.env) {
+    return (0, node_path_1.join)((0, profiles_1.defaultConfigDir)(env), "update-check.json");
+}
+function formatUpdateNotice(currentVersion, latestVersion) {
+    return `[alphafox] update available: ${currentVersion} -> ${latestVersion}. After the user confirms, run: alphafox update --format json --no-input`;
+}
+function shouldSkipUpdateCheck(command, env = process.env) {
+    if (env.ALPHAFOX_SKIP_UPDATE_CHECK === "1")
+        return true;
+    return command === "update" || command === "install";
+}
+async function maybeNotifyCliUpdate(deps = {}) {
+    const env = deps.env ?? process.env;
+    const currentVersion = deps.currentVersion ?? version_1.CLI_VERSION;
+    const now = deps.now ?? new Date();
+    const writeNotice = deps.writeNotice ??
+        ((line) => {
+            process.stderr.write(`${line}\n`);
+        });
+    const previous = loadUpdateCheckState(updateCheckStatePath(env));
+    if (previous &&
+        now.getTime() - Date.parse(previous.checkedAt) < exports.UPDATE_CHECK_INTERVAL_MS) {
+        return {
+            checked: false,
+            notified: false,
+            latestVersion: previous.latestVersion,
+        };
+    }
+    let latestVersion = null;
+    try {
+        latestVersion = await (deps.fetchLatest ?? defaultFetchLatest)(env);
+    }
+    catch {
+        saveUpdateCheckState(updateCheckStatePath(env), {
+            schemaVersion: 1,
+            checkedAt: now.toISOString(),
+            currentVersion,
+            latestVersion: previous?.latestVersion ?? null,
+            updateAvailable: false,
+        });
+        return {
+            checked: true,
+            notified: false,
+            latestVersion: previous?.latestVersion ?? null,
+        };
+    }
+    const updateAvailable = (0, wizard_1.semverLessThan)(currentVersion, latestVersion);
+    saveUpdateCheckState(updateCheckStatePath(env), {
+        schemaVersion: 1,
+        checkedAt: now.toISOString(),
+        currentVersion,
+        latestVersion,
+        updateAvailable,
+    });
+    if (updateAvailable) {
+        writeNotice(formatUpdateNotice(currentVersion, latestVersion));
+    }
+    return {
+        checked: true,
+        notified: updateAvailable,
+        latestVersion,
+    };
+}
+function loadUpdateCheckState(path) {
+    if (!(0, node_fs_1.existsSync)(path))
+        return null;
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, "utf8"));
+        if (parsed.schemaVersion !== 1 ||
+            typeof parsed.checkedAt !== "string" ||
+            Number.isNaN(Date.parse(parsed.checkedAt))) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function saveUpdateCheckState(path, state) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.join)(path, ".."), { recursive: true });
+    (0, node_fs_1.writeFileSync)(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+async function defaultFetchLatest(env) {
+    const runner = (0, exec_1.createDefaultInstallRunner)(env, []);
+    const { stdout } = await runner.exec("npm", ["view", version_1.CLI_PACKAGE, "version"], {
+        timeoutMs: NPM_VIEW_TIMEOUT_MS,
+    });
+    const version = stdout.trim();
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new Error(`invalid npm version: ${version}`);
+    }
+    return version;
+}

package/dist/update/run-command.d.ts

@@ -0,0 +1,41 @@
+import type { InstallRunner } from "../install/types";
+import type { SkillsSyncResult } from "../skills/manager";
+export interface UpdateArgs {
+    readonly check: boolean;
+    readonly help: boolean;
+    readonly version?: string;
+}
+export interface UpdateExecutionFlags {
+    readonly yes: boolean;
+    readonly dryRun: boolean;
+}
+export interface UpdateCliFlags extends UpdateExecutionFlags {
+    readonly format: "json" | "jsonl" | "text";
+    readonly noInput: boolean;
+    readonly jq?: string;
+}
+export interface UpdateDeps {
+    readonly runner?: InstallRunner;
+    readonly packageHasSkills?: (packageRoot: string) => boolean;
+    readonly sync?: (packageRoot: string, runner: InstallRunner) => Promise<SkillsSyncResult>;
+}
+export interface CliUpdateResult {
+    readonly currentVersion: string | null;
+    readonly targetVersion: string;
+    readonly updateAvailable: boolean;
+    readonly checkOnly: boolean;
+    readonly dryRun: boolean;
+    readonly cli: {
+        readonly action: "available" | "planned" | "updated" | "current";
+        readonly previousVersion: string | null;
+        readonly version: string;
+    };
+    readonly skills: SkillsSyncResult | {
+        readonly action: "not-run";
+        readonly reason: "check-only" | "dry-run";
+    };
+    readonly restartRequired: boolean;
+}
+export declare function parseUpdateArgs(args: readonly string[]): UpdateArgs;
+export declare function executeCliUpdate(args: UpdateArgs, flags: UpdateExecutionFlags, env?: NodeJS.ProcessEnv, deps?: UpdateDeps): Promise<CliUpdateResult>;
+export declare function cmdUpdate(args: string[], flags: UpdateCliFlags, env?: NodeJS.ProcessEnv, deps?: UpdateDeps): Promise<number>;

package/dist/update/run-command.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseUpdateArgs = parseUpdateArgs;
+exports.executeCliUpdate = executeCliUpdate;
+exports.cmdUpdate = cmdUpdate;
+const envelope_1 = require("../envelope");
+const exec_1 = require("../install/exec");
+const package_root_1 = require("../install/package-root");
+const wizard_1 = require("../install/wizard");
+const run_command_1 = require("../skills/run-command");
+const version_1 = require("../version");
+const NPM_TIMEOUT_MS = 120_000;
+function parseUpdateArgs(args) {
+    let check = false;
+    let help = false;
+    let version;
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === "--check") {
+            check = true;
+        }
+        else if (arg === "--version") {
+            version = args[++i];
+            if (!version)
+                throw updateUsage("--version requires a value");
+        }
+        else if (arg.startsWith("--version=")) {
+            version = arg.slice("--version=".length);
+        }
+        else if (arg === "--help" || arg === "-h" || arg === "help") {
+            help = true;
+        }
+        else {
+            throw updateUsage(`Unknown update argument: ${arg}`);
+        }
+    }
+    if (version && !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw updateUsage(`Invalid version: ${version}`);
+    }
+    return { check, help, ...(version ? { version } : {}) };
+}
+async function executeCliUpdate(args, flags, env = process.env, deps = {}) {
+    const runner = deps.runner ??
+        (0, exec_1.createDefaultInstallRunner)(env, [__dirname, process.cwd()]);
+    const currentVersion = await readGlobalVersion(runner);
+    const targetVersion = await readTargetVersion(runner, args.version);
+    const updateAvailable = args.version
+        ? currentVersion !== targetVersion
+        : currentVersion == null || (0, wizard_1.semverLessThan)(currentVersion, targetVersion);
+    const effectiveVersion = updateAvailable ? targetVersion : (currentVersion ?? targetVersion);
+    if (args.check) {
+        return {
+            currentVersion,
+            targetVersion,
+            updateAvailable,
+            checkOnly: true,
+            dryRun: false,
+            cli: {
+                action: updateAvailable ? "available" : "current",
+                previousVersion: currentVersion,
+                version: effectiveVersion,
+            },
+            skills: { action: "not-run", reason: "check-only" },
+            restartRequired: false,
+        };
+    }
+    if (updateAvailable &&
+        args.version &&
+        currentVersion &&
+        (0, wizard_1.semverLessThan)(targetVersion, currentVersion) &&
+        !flags.yes) {
+        throw Object.assign(new Error(`Downgrading ${version_1.CLI_PACKAGE} from ${currentVersion} to ${targetVersion} requires --yes`), {
+            type: "confirmation",
+            subtype: "cli_downgrade_confirmation_required",
+        });
+    }
+    if (flags.dryRun) {
+        return {
+            currentVersion,
+            targetVersion,
+            updateAvailable,
+            checkOnly: false,
+            dryRun: true,
+            cli: {
+                action: updateAvailable ? "planned" : "current",
+                previousVersion: currentVersion,
+                version: effectiveVersion,
+            },
+            skills: { action: "not-run", reason: "dry-run" },
+            restartRequired: updateAvailable,
+        };
+    }
+    if (updateAvailable) {
+        await runner.exec("npm", ["install", "-g", `${version_1.CLI_PACKAGE}@${targetVersion}`], { timeoutMs: NPM_TIMEOUT_MS });
+        const installedVersion = await readGlobalVersion(runner);
+        if (installedVersion !== targetVersion) {
+            throw Object.assign(new Error(`npm reported ${installedVersion ?? "no global install"} after updating to ${targetVersion}`), {
+                type: "install",
+                subtype: "cli_update_verify_failed",
+            });
+        }
+    }
+    const packageRoot = await resolveUpdatedPackageRoot(runner, deps.packageHasSkills ?? package_root_1.packageHasSkills, !updateAvailable);
+    const sync = deps.sync ??
+        (async (root, activeRunner) => await (0, run_command_1.syncCurrentSkills)({ force: false, dryRun: false }, env, { runner: activeRunner, packageRoot: root }));
+    const skills = await sync(packageRoot, runner);
+    return {
+        currentVersion,
+        targetVersion,
+        updateAvailable,
+        checkOnly: false,
+        dryRun: false,
+        cli: {
+            action: updateAvailable ? "updated" : "current",
+            previousVersion: currentVersion,
+            version: effectiveVersion,
+        },
+        skills,
+        restartRequired: updateAvailable || skills.restartRequired,
+    };
+}
+async function cmdUpdate(args, flags, env = process.env, deps = {}) {
+    const parsed = parseUpdateArgs(args);
+    if (parsed.help) {
+        (0, envelope_1.writeSuccess)({
+            name: "update",
+            usage: [
+                "alphafox update --check",
+                "alphafox update [--dry-run]",
+                "alphafox update --version <version> [--yes]",
+            ],
+            notes: [
+                "Updates @alphafox/cli through npm, then syncs the verified co-versioned Skills bundle",
+                "A downgrade requires --yes",
+                "No Skills are downloaded independently from GitHub",
+            ],
+        }, { format: flags.format, jq: flags.jq });
+        return 0;
+    }
+    const result = await executeCliUpdate(parsed, flags, env, deps);
+    (0, envelope_1.writeSuccess)(result, { format: flags.format, jq: flags.jq });
+    return result.skills.action !== "not-run" &&
+        result.skills.blocked.length > 0
+        ? 1
+        : 0;
+}
+async function readGlobalVersion(runner) {
+    try {
+        const { stdout, stderr } = await runner.exec("npm", ["list", "-g", version_1.CLI_PACKAGE, "--depth=0"], { timeoutMs: 15_000 });
+        return (0, wizard_1.parseNpmListVersion)(`${stdout}\n${stderr}`);
+    }
+    catch {
+        return null;
+    }
+}
+async function readTargetVersion(runner, requested) {
+    const spec = requested ? `${version_1.CLI_PACKAGE}@${requested}` : version_1.CLI_PACKAGE;
+    const { stdout } = await runner.exec("npm", ["view", spec, "version"], {
+        timeoutMs: 15_000,
+    });
+    const version = stdout.trim();
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw Object.assign(new Error(`npm returned an invalid version for ${spec}`), {
+            type: "install",
+            subtype: "npm_version_invalid",
+        });
+    }
+    return version;
+}
+async function resolveUpdatedPackageRoot(runner, packageHasSkills, allowCurrentFallback) {
+    try {
+        const { stdout } = await runner.exec("npm", ["root", "-g"], {
+            timeoutMs: 15_000,
+        });
+        const root = (0, package_root_1.globalPackageRoot)(stdout.trim());
+        if (packageHasSkills(root))
+            return root;
+    }
+    catch {
+        // Fall back to the currently executing package for repair-only updates.
+    }
+    if (!allowCurrentFallback) {
+        throw Object.assign(new Error("Updated @alphafox/cli package does not contain Skills"), {
+            type: "install",
+            subtype: "updated_skills_missing",
+        });
+    }
+    const current = (0, run_command_1.resolveCurrentSkillsPackageRoot)(runner.packageSearchDirs().length > 0
+        ? runner.packageSearchDirs()
+        : [__dirname, process.cwd()]);
+    if (packageHasSkills(current))
+        return current;
+    throw Object.assign(new Error("Updated @alphafox/cli package does not contain Skills"), {
+        type: "install",
+        subtype: "updated_skills_missing",
+    });
+}
+function updateUsage(message) {
+    return Object.assign(new Error(message), {
+        type: "usage",
+        subtype: "invalid_update_args",
+        status: 64,
+    });
+}

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.4";
+export declare const CLI_VERSION = "0.3.6";
 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.4";
+exports.CLI_VERSION = "0.3.6";
 var operations_1 = require("./catalog/operations");
 Object.defineProperty(exports, "CLI_CONTRACT_VERSION", { enumerable: true, get: function () { return operations_1.CATALOG_VERSION; } });

package/docs/agents/issue-tracker.md

@@ -1,6 +1,6 @@
 # Issue tracker: Feishu Tasks
 
-Issues and specs for this repo live as tasks in the **Alphafox-Issues** Feishu (Lark) tasklist. Use the `lark-cli` CLI ([`@larksuite/cli`](https://github.com/larksuite/cli)) for all operations, always with `--as user` — a task created by the bot identity is invisible in the human's task centre.
+Issues and specs for this repo live as tasks in the **AlphaFox-Issues** Feishu (Lark) tasklist. Use the `lark-cli` CLI ([`@larksuite/cli`](https://github.com/larksuite/cli)) for all operations, always with `--as user` — a task created by the bot identity is invisible in the human's task centre.
 
 List: <https://applink.feishu.cn/client/todo/task_list?guid=6d628d79-cdfe-47cc-98f7-35561944494b>
 
@@ -46,7 +46,7 @@ Every other label is an option on the single-select `Type` field. Address an opt
 ## Conventions
 
 - **Shared-list title** — prefix every issue/task title with `[alphafox-cli]` so the repository remains identifiable on the shared board.
-- **Tracker boundary** — Matt Skills issues, specs, tickets, triage items, and wayfinder maps belong in `Alphafox-Issues`, not a quarterly execution list. If quarterly planning initiated the work, link its absolute Feishu task URL instead of duplicating workflow state.
+- **Tracker boundary** — Matt Skills issues, specs, tickets, triage items, and wayfinder maps belong in `AlphaFox-Issues`, not a quarterly execution list. If quarterly planning initiated the work, link its absolute Feishu task URL instead of duplicating workflow state.
 
 - **Create an issue** — one call sets body, section (triage role) and `Type`:
 

package/docs/agents/triage-labels.md

@@ -1,6 +1,6 @@
 # Triage Labels
 
-The skills speak in terms of five canonical triage roles. On this repo's tracker (Feishu Tasks) a role is not a label but a **section** of the Alphafox-Issues tasklist — a task sits in exactly one, so the state machine can't be violated. `issue-tracker.md` holds the section GUIDs and the command that moves a task between them.
+The skills speak in terms of five canonical triage roles. On this repo's tracker (Feishu Tasks) a role is not a label but a **section** of the AlphaFox-Issues tasklist — a task sits in exactly one, so the state machine can't be violated. `issue-tracker.md` holds the section GUIDs and the command that moves a task between them.
 
 | Label in mattpocock/skills | Section in our tracker | Meaning                                  |
 | -------------------------- | ---------------------- | ---------------------------------------- |

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

@@ -1,4 +1,4 @@
-# Alphafox CLI installation guide
+# AlphaFox CLI installation guide
 
 The following steps are designed for AI Agents. Some steps require the user
 to complete a browser or Device Flow approval. Always use
@@ -20,26 +20,25 @@ Skills do **not** register with Cursor / Claude Code / Codex from
 # Install CLI
 npm install -g @alphafox/cli
 
-# Install CLI SKILL (required) — project-local, current workspace
-npx -y skills add "$(npm root -g)/@alphafox/cli" -y
+# Verify and globally sync the exact co-versioned Skills bundle
+alphafox skills sync --format json --no-input
 ```
 
-If the local package path fails (older tarball without `skills/`, or
-`npm root -g` is wrong), fall back to the public GitHub source:
+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.
 
-```shell
-npx -y skills add alphafoxai/alphafox-cli -y
-```
-
-To install Skills for every project on this machine instead of the current
-repo, add `-g`:
+For future updates:
 
 ```shell
-npx -y skills add "$(npm root -g)/@alphafox/cli" -y -g
+alphafox update --check --format json --no-input
+alphafox update --format json --no-input
 ```
 
-Do not invent a second catalog. Skills must stay co-versioned with the CLI
-that was just installed.
+`alphafox update` upgrades the npm CLI first, then syncs its bundled Skills.
+Modified Skills are preserved and reported. Only use
+`alphafox skills sync --force --yes` when the user explicitly wants to replace
+them; a backup is created before replacement.
 
 ## Step 2: Login
 
@@ -88,7 +87,7 @@ 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
+Then they can ask the Agent to use AlphaFox. The entry skill `alphafox` routes
 to auth, market, engine-backtest, strategy, trading, and the rest.
 
 ## Human wizard (do not run this from an Agent)
@@ -100,6 +99,6 @@ stepping through the commands above:
 npx @alphafox/cli@latest install
 ```
 
-That wizard installs the CLI globally, runs `npx skills add … -y -g`,
+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.