@alphafox/cli 0.3.10 → 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/engine-backtest/coverage-notice.d.ts

@@ -0,0 +1,5 @@
+import type { TapeCoverageIssue, TapeCoverageNotice } from "./types";
+export declare function summarizeTapeCoverageNotice(issues: readonly TapeCoverageIssue[]): TapeCoverageNotice;
+/** Runtime guard: a missing field must not look like a clean tape. */
+export declare function requireTapeCoverageIssues(value: unknown): readonly TapeCoverageIssue[];
+export declare function snapshotCoverageIssues(issues: readonly TapeCoverageIssue[] | undefined): TapeCoverageIssue[] | undefined;

package/dist/engine-backtest/coverage-notice.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.summarizeTapeCoverageNotice = summarizeTapeCoverageNotice;
+exports.requireTapeCoverageIssues = requireTapeCoverageIssues;
+exports.snapshotCoverageIssues = snapshotCoverageIssues;
+const errors_1 = require("./errors");
+function symbolLabel(issue) {
+    const timeframe = issue.timeframe && issue.timeframe !== "*" ? ` ${issue.timeframe}` : "";
+    return `${issue.symbol}${timeframe}`;
+}
+function uniqueIssues(issues) {
+    const seen = new Set();
+    const unique = [];
+    for (const issue of issues) {
+        const key = `${issue.code}\u0000${issue.symbol}\u0000${issue.timeframe}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(issue);
+    }
+    return unique;
+}
+function summarizeTapeCoverageNotice(issues) {
+    const prefix = [];
+    const internal = [];
+    const other = [];
+    for (const item of issues) {
+        if (item.code === "prefix_gap") {
+            prefix.push(item);
+        }
+        else if (item.code === "internal_gap") {
+            internal.push(item);
+        }
+        else {
+            other.push(item);
+        }
+    }
+    const uniquePrefix = uniqueIssues(prefix);
+    const uniqueInternal = uniqueIssues(internal);
+    const uniqueOther = uniqueIssues(other);
+    const severity = uniqueInternal.length > 0
+        ? "warning"
+        : uniquePrefix.length + uniqueOther.length > 0
+            ? "notice"
+            : "none";
+    const messages = [];
+    if (uniqueInternal.length > 0) {
+        messages.push(`WARNING: missing mid-range candles (more severe): ${uniqueInternal
+            .map(symbolLabel)
+            .join(", ")}`);
+    }
+    if (uniquePrefix.length > 0) {
+        messages.push(`NOTICE: missing start candles (less severe): ${uniquePrefix
+            .map(symbolLabel)
+            .join(", ")}`);
+    }
+    if (uniqueOther.length > 0) {
+        messages.push(`NOTICE: other soft coverage gaps: ${uniqueOther
+            .map((issue) => `${symbolLabel(issue)} (${issue.code})`)
+            .join(", ")}`);
+    }
+    return {
+        severity,
+        prefix: uniquePrefix,
+        internal: uniqueInternal,
+        other: uniqueOther,
+        messages,
+    };
+}
+/** Must match alphafox-web `engineBacktestPersistedSnapshotSchema.coverageIssues`. */
+const PERSISTED_COVERAGE_ISSUE_CODES = new Set([
+    "market_missing",
+    "ohlcv_missing",
+    "invalid_ohlcv",
+    "non_monotonic",
+    "internal_gap",
+    "prefix_gap",
+    "suffix_gap",
+    "warmup_insufficient",
+    "load_failed",
+    "coverage_insufficient",
+]);
+/** Runtime guard: a missing field must not look like a clean tape. */
+function requireTapeCoverageIssues(value) {
+    if (!Array.isArray(value)) {
+        throw new errors_1.EngineBacktestError({
+            type: "runtime",
+            subtype: "missing_coverage_issues",
+            message: "Tape loader omitted coverageIssues; refusing to treat the tape as clean.",
+        });
+    }
+    return value;
+}
+function snapshotCoverageIssues(issues) {
+    if (!issues || issues.length === 0)
+        return undefined;
+    return issues.map((issue) => {
+        if (!PERSISTED_COVERAGE_ISSUE_CODES.has(issue.code)) {
+            throw new errors_1.EngineBacktestError({
+                type: "runtime",
+                subtype: "invalid_coverage_issue",
+                message: `Cannot persist unknown tape coverage issue code: ${issue.code}`,
+            });
+        }
+        return {
+            code: issue.code,
+            symbol: issue.symbol,
+            timeframe: issue.timeframe,
+            ...(issue.expected === undefined ? {} : { expected: issue.expected }),
+            ...(issue.actual === undefined ? {} : { actual: issue.actual }),
+            ...(issue.timestamp === undefined ? {} : { timestamp: issue.timestamp }),
+            ...(issue.message === undefined ? {} : { message: issue.message }),
+        };
+    });
+}

package/dist/engine-backtest/parse-args.d.ts

@@ -1,4 +1,4 @@
-import type { EngineBacktestRunArgs, EngineBacktestSweepArgs, ExecutionModel, InclusiveUtcDateRange } from "./types";
+import { type EngineBacktestRunArgs, type EngineBacktestSweepArgs, type ExecutionModel, type InclusiveUtcDateRange } from "./types";
 export declare const ENGINE_BACKTEST_RUN_USAGE: string[];
 export declare const ENGINE_BACKTEST_SWEEP_USAGE: string[];
 export declare function parseInclusiveUtcDateRange(rangeStart: string, rangeEnd: string): InclusiveUtcDateRange;

package/dist/engine-backtest/parse-args.js

@@ -9,6 +9,7 @@ exports.parseEngineBacktestSweepArgs = parseEngineBacktestSweepArgs;
 const errors_1 = require("./errors");
 const replay_timeframe_1 = require("./replay-timeframe");
 const sweep_kernel_1 = require("./sweep-kernel");
+const types_1 = require("./types");
 const DAY_MS = 86_400_000;
 const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
 const TIERS = new Set(["free", "pro", "pro_max"]);
@@ -107,7 +108,7 @@ function parseEngineBacktestRunArgs(args) {
     let to;
     let initialEquity;
     let tier;
-    let dataQualityMode = "strict";
+    let dataQualityMode = types_1.DEFAULT_DATA_QUALITY_MODE;
     let configSchemaVersion;
     let executionModelOverride;
     let persist = true;
@@ -343,7 +344,7 @@ function parseEngineBacktestSweepArgs(args) {
         return {
             help: true,
             createExperiment: false,
-            dataQualityMode: "strict",
+            dataQualityMode: types_1.DEFAULT_DATA_QUALITY_MODE,
             persist: true,
             replayTimeframe: replay_timeframe_1.ENGINE_BACKTEST_DEFAULT_REPLAY_TIMEFRAME,
             axesRaw,

package/dist/engine-backtest/persist.d.ts

@@ -1,5 +1,5 @@
 import type { ProfileName } from "../config/profiles";
-import type { CreateRunRequestBody, CreateSweepRequestBody, DataQualityMode, EngineBacktestMetrics, EngineBacktestScenario, EngineBacktestSweepPointRow, ExecutionModel, PersistedSnapshot, SweepMode, SweepSearchMode } from "./types";
+import type { CreateRunRequestBody, CreateSweepRequestBody, DataQualityMode, EngineBacktestMetrics, EngineBacktestScenario, EngineBacktestSweepPointRow, ExecutionModel, PersistedSnapshot, SweepMode, SweepSearchMode, TapeCoverageIssue } from "./types";
 /** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
 export declare const DEFAULT_EXECUTION_MODEL: ExecutionModel;
 export declare const SNAPSHOT_SCHEMA_VERSION: 1;
@@ -24,6 +24,7 @@ export declare function buildCreateRunRequest(input: {
     readonly dataQualityMode: DataQualityMode;
     readonly engineVersion: string;
     readonly equityCurve?: unknown;
+    readonly coverageIssues?: readonly TapeCoverageIssue[];
 }): CreateRunRequestBody;
 /**
  * Experiment detail URL. Locale prefix (`/zh`, `/en`) is optional — web
@@ -51,6 +52,7 @@ export declare function buildSweepBaseSnapshot(input: {
     readonly initialEquity: number;
     readonly subscriptionTier: PersistedSnapshot["subscriptionTier"];
     readonly dataQualityMode: DataQualityMode;
+    readonly coverageIssues?: readonly TapeCoverageIssue[];
     readonly symbols: readonly string[];
     readonly timeframes: readonly string[];
     readonly baseTimeframe: string;

package/dist/engine-backtest/persist.js

@@ -14,6 +14,7 @@ exports.buildCreateSweepRequest = buildCreateSweepRequest;
 exports.assertSweepCreateRequestSize = assertSweepCreateRequestSize;
 const errors_1 = require("./errors");
 const return_curve_1 = require("./return-curve");
+const coverage_notice_1 = require("./coverage-notice");
 /** Aligned with `@alphafoxai/backtest-runner` DEFAULT_EXECUTION_MODEL. */
 exports.DEFAULT_EXECUTION_MODEL = {
     pricePath: "ohlc_path_4",
@@ -59,6 +60,7 @@ function buildCreateRunRequest(input) {
     }
     const timeframes = uniqueSeriesField(scenario.tape.series, "timeframe");
     const engineVersion = input.engineVersion.trim() || "node-wasm";
+    const coverageIssues = (0, coverage_notice_1.snapshotCoverageIssues)(input.coverageIssues);
     const snapshot = {
         snapshotSchemaVersion: exports.SNAPSHOT_SCHEMA_VERSION,
         strategyDefinitionId: scenario.trader.strategyDefinitionId,
@@ -70,6 +72,7 @@ function buildCreateRunRequest(input) {
         initialEquity: scenario.exchange.initialEquity,
         subscriptionTier: scenario.trader.subscriptionTier,
         dataQualityMode: input.dataQualityMode,
+        ...(coverageIssues ? { coverageIssues } : {}),
         symbols,
         timeframes: timeframes.length > 0 ? timeframes : ["1m"],
         baseTimeframe: scenario.tape.baseTimeframe || "1m",
@@ -141,6 +144,7 @@ function buildSweepBaseSnapshot(input) {
     const timeframes = [
         ...new Set(input.timeframes.map((item) => item.trim()).filter(Boolean)),
     ];
+    const coverageIssues = (0, coverage_notice_1.snapshotCoverageIssues)(input.coverageIssues);
     return {
         snapshotSchemaVersion: exports.SNAPSHOT_SCHEMA_VERSION,
         strategyDefinitionId: input.definitionId,
@@ -152,6 +156,7 @@ function buildSweepBaseSnapshot(input) {
         initialEquity: input.initialEquity,
         subscriptionTier: input.subscriptionTier,
         dataQualityMode: input.dataQualityMode,
+        ...(coverageIssues ? { coverageIssues } : {}),
         symbols,
         timeframes: timeframes.length > 0 ? timeframes : ["1m"],
         baseTimeframe: input.baseTimeframe.trim() || "1m",

package/dist/engine-backtest/run-command.js

@@ -9,6 +9,7 @@ const profiles_1 = require("../config/profiles");
 const envelope_1 = require("../envelope");
 const client_1 = require("../http/client");
 const store_1 = require("../keychain/store");
+const coverage_notice_1 = require("./coverage-notice");
 const errors_1 = require("./errors");
 const load_config_1 = require("./load-config");
 const parse_args_1 = require("./parse-args");
@@ -336,6 +337,10 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
                 details: issues ? { issues } : undefined,
             });
         }
+        tapeResult = {
+            ...tapeResult,
+            coverageIssues: (0, coverage_notice_1.requireTapeCoverageIssues)(tapeResult.coverageIssues),
+        };
         const runId = mintId();
         const executionModel = {
             ...(runner.DEFAULT_EXECUTION_MODEL ?? persist_1.DEFAULT_EXECUTION_MODEL),
@@ -400,6 +405,7 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
                 dataQualityMode: args.dataQualityMode,
                 engineVersion,
                 equityCurve: result.equityCurve,
+                coverageIssues: tapeResult.coverageIssues,
             });
             const res = await postJson(api, profile, env, runsPath(experimentId), body, mintId);
             persistedRunId = extractEntityId(res.json);
@@ -419,7 +425,9 @@ async function executeEngineBacktestRun(args, flags, env = process.env, deps = {
             runId: persistedRunId,
             experimentUrl: (0, persist_1.experimentPageUrl)(profile.name, experimentId),
             persisted: Boolean(persistedRunId),
-            coverageWarnings: tapeResult.coverageWarnings ?? [],
+            coverageWarnings: tapeResult.coverageWarnings,
+            coverageIssues: tapeResult.coverageIssues,
+            coverageNotice: (0, coverage_notice_1.summarizeTapeCoverageNotice)(tapeResult.coverageIssues),
         };
     }
     finally {
@@ -441,6 +449,7 @@ function engineBacktestHelpData() {
             "runs.create is write (not high-risk-write); --yes is not required",
             "Do not pass --token; use alphafox auth login",
             "--replay-timeframe defaults to 1m (min 1m). Indicator series still download their native plan timeframes.",
+            "--data-quality defaults to basic: hard tape failures still stop, soft gaps finish the run and appear as coverageNotice (prefix_gap less severe, internal_gap more severe). Use --data-quality strict to fail on any gap.",
         ],
     };
 }

package/dist/engine-backtest/sweep-command.js

@@ -9,6 +9,7 @@ const profiles_1 = require("../config/profiles");
 const client_1 = require("../http/client");
 const paths_1 = require("../cache/paths");
 const store_1 = require("../keychain/store");
+const coverage_notice_1 = require("./coverage-notice");
 const errors_1 = require("./errors");
 const load_config_1 = require("./load-config");
 const parse_axes_1 = require("./parse-axes");
@@ -175,6 +176,7 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
             },
             buffers: {},
             coverageWarnings: [],
+            coverageIssues: [],
         };
         if (tapePlans.length > 0) {
             try {
@@ -209,6 +211,10 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
                     details: issues ? { issues } : undefined,
                 });
             }
+            tapeResult = {
+                ...tapeResult,
+                coverageIssues: (0, coverage_notice_1.requireTapeCoverageIssues)(tapeResult.coverageIssues),
+            };
         }
         emitProgress(flags, writeLine, "tape", 1);
         while (clients.length < concurrency) {
@@ -353,6 +359,7 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
                 initialEquity: args.initialEquity,
                 subscriptionTier,
                 dataQualityMode: args.dataQualityMode,
+                coverageIssues: tapeResult.coverageIssues,
                 symbols: tapeSymbols.length > 0 ? tapeSymbols : coverage.symbols,
                 timeframes: (0, persist_1.uniqueSeriesField)(tapeResult.tape.series, "timeframe"),
                 baseTimeframe: tapeResult.tape.baseTimeframe || args.replayTimeframe,
@@ -417,7 +424,9 @@ async function executeEngineBacktestSweep(args, flags, env = process.env, deps =
             experimentUrl: experimentId
                 ? (0, persist_1.experimentSweepPageUrl)(profile.name, experimentId)
                 : undefined,
-            coverageWarnings: tapeResult.coverageWarnings ?? [],
+            coverageWarnings: tapeResult.coverageWarnings,
+            coverageIssues: tapeResult.coverageIssues,
+            coverageNotice: (0, coverage_notice_1.summarizeTapeCoverageNotice)(tapeResult.coverageIssues),
             axes: coarsePlan.axes,
         };
     }

package/dist/engine-backtest/types.d.ts

@@ -1,5 +1,23 @@
 export type SubscriptionTier = "free" | "pro" | "pro_max";
 export type DataQualityMode = "strict" | "basic";
+/** New runs default to basic; `--data-quality strict` remains an explicit override. */
+export declare const DEFAULT_DATA_QUALITY_MODE: DataQualityMode;
+export interface TapeCoverageIssue {
+    readonly code: string;
+    readonly symbol: string;
+    readonly timeframe: string;
+    readonly expected?: number;
+    readonly actual?: number;
+    readonly timestamp?: number;
+    readonly message?: string;
+}
+export interface TapeCoverageNotice {
+    readonly severity: "none" | "notice" | "warning";
+    readonly prefix: readonly TapeCoverageIssue[];
+    readonly internal: readonly TapeCoverageIssue[];
+    readonly other: readonly TapeCoverageIssue[];
+    readonly messages: readonly string[];
+}
 export type PricePath = "ohlc_path_4" | "close_only";
 export interface ExecutionModel {
     readonly pricePath: PricePath;
@@ -202,6 +220,7 @@ export interface TapeLoadResult {
     readonly tape: EngineBacktestTapeInput;
     readonly buffers: Record<string, ArrayBuffer>;
     readonly coverageWarnings: readonly string[];
+    readonly coverageIssues: readonly TapeCoverageIssue[];
 }
 export interface BacktestClientLike {
     init(): Promise<string>;
@@ -265,6 +284,7 @@ export interface PersistedSnapshot {
     readonly initialEquity: number;
     readonly subscriptionTier: SubscriptionTier;
     readonly dataQualityMode: DataQualityMode;
+    readonly coverageIssues?: readonly TapeCoverageIssue[];
     readonly symbols: string[];
     readonly timeframes: string[];
     readonly baseTimeframe: string;
@@ -289,6 +309,8 @@ export interface EngineBacktestRunSuccess {
     readonly experimentUrl: string;
     readonly persisted: boolean;
     readonly coverageWarnings: readonly string[];
+    readonly coverageIssues: readonly TapeCoverageIssue[];
+    readonly coverageNotice: TapeCoverageNotice;
 }
 export interface EngineBacktestSweepPointRow {
     readonly coordinate: {
@@ -372,6 +394,8 @@ export interface EngineBacktestSweepSuccess {
     readonly experimentId?: string;
     readonly experimentUrl?: string;
     readonly coverageWarnings: readonly string[];
+    readonly coverageIssues: readonly TapeCoverageIssue[];
+    readonly coverageNotice: TapeCoverageNotice;
     readonly axes: ReadonlyArray<{
         readonly path: readonly string[];
         readonly current: number;

package/dist/engine-backtest/types.js

@@ -1,2 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_DATA_QUALITY_MODE = void 0;
+/** New runs default to basic; `--data-quality strict` remains an explicit override. */
+exports.DEFAULT_DATA_QUALITY_MODE = "basic";

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;