trekoon 0.3.2 → 0.3.4

package/src/commands/skills.ts

@@ -1,4 +1,5 @@
-import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -10,6 +11,7 @@ import { type CliContext, type CliResult } from "../runtime/command-types";
 const SKILLS_USAGE = [
   "Usage:",
   "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills install -g|--global [--editor opencode|claude|pi]",
   "  trekoon skills update",
 ].join("\n");
 const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
@@ -30,24 +32,6 @@ interface LinkTargetValidation {
   readonly outsideRepoLink: boolean;
 }
 
-type UpdateLinkAction = "created" | "refreshed" | "skipped_conflict" | "skipped_no_editor_dir";
-
-interface UpdateLinkEntry {
-  readonly editor: EditorName;
-  readonly linkPath: string;
-  readonly expectedTarget: string;
-  readonly action: UpdateLinkAction;
-  readonly conflictCode: "non_link" | "wrong_target" | null;
-  readonly existingTarget: string | null;
-}
-
-interface UpdateOutcome {
-  readonly sourcePath: string;
-  readonly installedPath: string;
-  readonly installedDir: string;
-  readonly links: readonly UpdateLinkEntry[];
-}
-
 function invalidArgs(message: string): CliResult {
   return failResult({
     command: "skills",
@@ -220,7 +204,12 @@ function resolveDefaultLinkPath(cwd: string, editor: EditorName): string {
 }
 
 function toRelativeSymlinkTarget(linkPath: string, targetPath: string): string {
-  const relativeTarget: string = relative(dirname(linkPath), resolve(targetPath));
+  // Use realpathNearestExistingAncestor for the link parent so the relative
+  // path is correct even when parts of the path are OS-level symlinks (e.g.
+  // macOS /var → /private/var).
+  const linkParent: string = realpathNearestExistingAncestor(dirname(linkPath));
+  const resolvedTarget: string = resolve(targetPath);
+  const relativeTarget: string = relative(linkParent, resolvedTarget);
   return relativeTarget === "" ? "." : relativeTarget;
 }
 
@@ -236,6 +225,19 @@ function resolveEditorConfigDir(cwd: string, editor: EditorName): string {
   return join(cwd, ".pi");
 }
 
+function resolveGlobalEditorSkillsDir(editor: EditorName): string {
+  const home: string = homedir();
+  if (editor === "opencode") {
+    return join(home, ".config", "opencode", "skills");
+  }
+
+  if (editor === "claude") {
+    return join(home, ".claude", "skills");
+  }
+
+  return join(home, ".pi", "skills");
+}
+
 function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; installedPath: string; installedDir: string } {
   const sourcePath: string = resolveBundledSkillFilePath();
   const sourceDir: string = resolveBundledSkillDirPath();
@@ -254,18 +256,60 @@ function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; i
     });
   }
 
-  const installedPath: string = join(cwd, ".agents", "skills", "trekoon", "SKILL.md");
-  const installedDir: string = dirname(installedPath);
+  const installedDir: string = join(cwd, ".agents", "skills", "trekoon");
+  const installedPath: string = join(installedDir, "SKILL.md");
+  const parentDir: string = dirname(installedDir);
+  const resolvedSourceDir: string = resolve(sourceDir);
+
+  // Self-reference guard: when cwd IS the package dir (e.g. developing Trekoon
+  // itself), the source dir and installed dir are the same path. Do not copy
+  // over itself — the directory already contains the bundled files.
+  if (resolve(installedDir) === resolvedSourceDir) {
+    return { sourcePath, installedPath, installedDir };
+  }
 
   try {
-    mkdirSync(installedDir, { recursive: true });
-    copyFileSync(sourcePath, installedPath);
-    // Copy reference guides if they exist in the bundled source.
-    const sourceRefDir: string = join(sourceDir, "reference");
-    if (existsSync(sourceRefDir)) {
-      const installedRefDir: string = join(installedDir, "reference");
-      cpSync(sourceRefDir, installedRefDir, { recursive: true });
+    mkdirSync(parentDir, { recursive: true });
+
+    // Check what currently occupies the install path (lstat does not follow symlinks).
+    let existingIsSymlink = false;
+    let existingIsDir = false;
+    let pathOccupied = false;
+
+    try {
+      const stat = lstatSync(installedDir);
+      pathOccupied = true;
+      existingIsSymlink = stat.isSymbolicLink();
+      existingIsDir = stat.isDirectory();
+    } catch {
+      // Nothing at the path — proceed to create.
+    }
+
+    if (pathOccupied) {
+      if (existingIsDir && !existingIsSymlink) {
+        // Real directory — check whether contents are already up to date.
+        try {
+          const sourceContents = readFileSync(sourcePath, "utf8");
+          const installedContents = readFileSync(installedPath, "utf8");
+          if (sourceContents === installedContents) {
+            // Already up to date; idempotent success.
+            return { sourcePath, installedPath, installedDir };
+          }
+        } catch {
+          // Can't read installed file — refresh below.
+        }
+        // Stale copy — remove and recopy.
+        rmSync(installedDir, { recursive: true, force: true });
+      } else if (existingIsSymlink) {
+        // Legacy symlink (pre-copy era) — remove and replace with copy.
+        rmSync(installedDir, { force: true });
+      } else {
+        // Unexpected file — remove.
+        rmSync(installedDir, { force: true });
+      }
     }
+
+    cpSync(resolvedSourceDir, installedDir, { recursive: true });
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -295,53 +339,188 @@ function replaceOrCreateSymlink(
   repoRoot: string,
   allowOutsideRepo: boolean,
 ): CliResult | null {
+  // Ensure parent dirs exist before computing the relative target so that
+  // realpathNearestExistingAncestor resolves correctly (avoids macOS
+  // /var → /private/var mismatch when parent chain is missing).
+  mkdirSync(dirname(linkPath), { recursive: true });
+
+  const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+  if (boundaryFailure) {
+    return boundaryFailure;
+  }
+
   const symlinkTarget: string = toRelativeSymlinkTarget(linkPath, targetPath);
 
-  if (!existsSync(linkPath)) {
-    mkdirSync(dirname(linkPath), { recursive: true });
-    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
-    if (boundaryFailure) {
-      return boundaryFailure;
-    }
+  // Use lstatSync to detect broken symlinks that existsSync would miss
+  // (existsSync follows symlinks, so a broken symlink returns false).
+  let occupied = false;
+  let isSymlink = false;
+
+  try {
+    const stat = lstatSync(linkPath);
+    occupied = true;
+    isSymlink = stat.isSymbolicLink();
+  } catch {
+    // Nothing at the path — proceed to create.
+  }
+
+  if (!occupied) {
     symlinkSync(symlinkTarget, linkPath, "dir");
     return null;
   }
 
-  const existing = lstatSync(linkPath);
-  if (!existing.isSymbolicLink()) {
-    // Replace stale directory or file with symlink to the canonical location.
+  if (!isSymlink) {
     rmSync(linkPath, { recursive: true, force: true });
-    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
-    if (boundaryFailure) {
-      return boundaryFailure;
-    }
     symlinkSync(symlinkTarget, linkPath, "dir");
     return null;
   }
 
-  const existingRawTarget: string = readlinkSync(linkPath);
-  const existingAbsoluteTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
-  const expectedTarget: string = resolve(targetPath);
-  if (existingAbsoluteTarget !== expectedTarget) {
-    // Replace symlink pointing to a different target.
-    rmSync(linkPath, { force: true });
-    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
-    if (boundaryFailure) {
-      return boundaryFailure;
-    }
-    symlinkSync(symlinkTarget, linkPath, "dir");
+  // Use realpathSync to resolve OS-level symlinks (macOS /var → /private/var)
+  // for a consistent comparison with the target.
+  const resolvedExisting: string = realpathSync(linkPath);
+  const resolvedExpected: string = realpathSync(resolve(targetPath));
+  if (resolvedExisting === resolvedExpected) {
+    // Already correct — avoid needless tear-down and recreation.
     return null;
   }
 
   rmSync(linkPath, { force: true });
-  const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
-  if (boundaryFailure) {
-    return boundaryFailure;
-  }
   symlinkSync(symlinkTarget, linkPath, "dir");
   return null;
 }
 
+interface GlobalEditorLinkEntry {
+  readonly editor: EditorName;
+  readonly linkPath: string;
+  readonly linkTarget: string;
+  readonly action: "created" | "refreshed" | "already_ok";
+}
+
+interface GlobalInstallOutcome {
+  readonly sourcePath: string;
+  readonly sourceDir: string;
+  readonly globalAnchorPath: string;
+  readonly globalAnchorAction: "created" | "refreshed" | "already_ok";
+  readonly editorLinks: readonly GlobalEditorLinkEntry[];
+}
+
+function ensureSymlink(
+  linkPath: string,
+  targetPath: string,
+): "created" | "refreshed" | "already_ok" {
+  const resolvedTarget: string = resolve(targetPath);
+
+  // Self-reference guard: source and target are the same path (dev mode).
+  if (resolve(linkPath) === resolvedTarget) {
+    return "already_ok";
+  }
+
+  // Ensure parent dirs exist before computing the relative target so that
+  // realpathNearestExistingAncestor resolves correctly.
+  mkdirSync(dirname(linkPath), { recursive: true });
+  const symlinkTarget: string = toRelativeSymlinkTarget(linkPath, resolvedTarget);
+
+  let existingIsSymlink = false;
+  let pathOccupied = false;
+
+  try {
+    const stat = lstatSync(linkPath);
+    pathOccupied = true;
+    existingIsSymlink = stat.isSymbolicLink();
+  } catch {
+    // Nothing at the path.
+  }
+
+  if (pathOccupied) {
+    if (existingIsSymlink) {
+      // Use realpathSync so OS-level symlinks (macOS /var → /private/var) do
+      // not cause false mismatches.
+      try {
+        const resolvedExisting: string = realpathSync(linkPath);
+        const resolvedExpectedReal: string = realpathSync(resolvedTarget);
+        if (resolvedExisting === resolvedExpectedReal) {
+          return "already_ok";
+        }
+      } catch {
+        // Broken symlink — fall through to remove and recreate.
+      }
+      rmSync(linkPath, { force: true });
+    } else {
+      rmSync(linkPath, { recursive: true, force: true });
+    }
+    symlinkSync(symlinkTarget, linkPath, "dir");
+    return "refreshed";
+  }
+
+  symlinkSync(symlinkTarget, linkPath, "dir");
+  return "created";
+}
+
+function runGlobalInstall(editors: readonly EditorName[]): CliResult {
+  const sourcePath: string = resolveBundledSkillFilePath();
+  const sourceDir: string = resolveBundledSkillDirPath();
+  if (!existsSync(sourcePath)) {
+    return failResult({
+      command: "skills.install",
+      human: `Bundled skill asset not found at ${sourcePath}`,
+      data: { code: "missing_asset", sourcePath },
+      error: { code: "missing_asset", message: "Bundled skill asset not found" },
+    });
+  }
+
+  try {
+    // Step 1: Global anchor  ~/.agents/skills/trekoon → bundled package dir.
+    const globalAnchorPath: string = join(homedir(), ".agents", "skills", "trekoon");
+    const globalAnchorAction = ensureSymlink(globalAnchorPath, sourceDir);
+
+    // Step 2: Editor links  <editor-global-skills>/trekoon → global anchor.
+    const editorLinks: GlobalEditorLinkEntry[] = editors.map((editor) => {
+      const editorSkillsDir: string = resolveGlobalEditorSkillsDir(editor);
+      const linkPath: string = join(editorSkillsDir, "trekoon");
+      const action = ensureSymlink(linkPath, globalAnchorPath);
+      return { editor, linkPath, linkTarget: globalAnchorPath, action };
+    });
+
+    const outcome: GlobalInstallOutcome = {
+      sourcePath,
+      sourceDir,
+      globalAnchorPath,
+      globalAnchorAction,
+      editorLinks,
+    };
+
+    const editorSummary: string = editorLinks
+      .map((entry) => `- ${entry.editor}: ${entry.action} (${entry.linkPath})`)
+      .join("\n");
+
+    return okResult({
+      command: "skills.install",
+      human: [
+        "Installed Trekoon skill globally.",
+        `Global anchor: ${globalAnchorPath} (${globalAnchorAction})`,
+        "Editor links:",
+        editorSummary,
+      ].join("\n"),
+      data: {
+        global: true,
+        sourcePath: outcome.sourcePath,
+        sourceDir: outcome.sourceDir,
+        globalAnchorPath: outcome.globalAnchorPath,
+        globalAnchorAction: outcome.globalAnchorAction,
+        editorLinks: outcome.editorLinks,
+      },
+    });
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown global install failure";
+    return failResult({
+      command: "skills.install",
+      human: `Failed to install skill globally: ${message}`,
+      data: { code: "install_failed", message },
+      error: { code: "install_failed", message },
+    });
+  }
+}
+
 function runSkillsInstall(context: CliContext): CliResult {
   const parsed = parseArgs(context.args);
   const missingValue = readMissingOptionValue(parsed.missingOptionValues, "editor", "to");
@@ -355,11 +534,41 @@ function runSkillsInstall(context: CliContext): CliResult {
     return invalidArgs("Unexpected positional arguments for skills install.");
   }
 
+  const wantsGlobal: boolean = hasFlag(parsed.flags, "global", "g");
   const wantsLink: boolean = hasFlag(parsed.flags, "link");
   const allowOutsideRepo: boolean = hasFlag(parsed.flags, ALLOW_OUTSIDE_REPO_FLAG);
   const rawEditor: string | undefined = readOption(parsed.options, "editor");
   const rawTo: string | undefined = readOption(parsed.options, "to");
 
+  // Validate editor early (shared by both modes).
+  if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, pi", {
+      editor: rawEditor,
+      allowedEditors: EDITOR_NAMES,
+    });
+  }
+
+  // Global mode validation.
+  if (wantsGlobal) {
+    if (rawTo !== undefined) {
+      return invalidInput("skills.install", "--to is not supported with --global.", { to: rawTo });
+    }
+
+    if (wantsLink) {
+      return invalidInput("skills.install", "--link is not supported with --global.", {});
+    }
+
+    if (allowOutsideRepo) {
+      return invalidInput("skills.install", `--${ALLOW_OUTSIDE_REPO_FLAG} is not supported with --global.`, {});
+    }
+
+    const editors: readonly EditorName[] = rawEditor
+      ? [rawEditor as EditorName]
+      : EDITOR_NAMES;
+    return runGlobalInstall(editors);
+  }
+
+  // Local mode validation.
   if (allowOutsideRepo && !wantsLink) {
     return invalidInput("skills.install", `--${ALLOW_OUTSIDE_REPO_FLAG} requires --link.`, {
       allowOutsideRepo,
@@ -382,13 +591,6 @@ function runSkillsInstall(context: CliContext): CliResult {
     return invalidArgs("skills install --link requires --editor opencode|claude|pi.");
   }
 
-  if (rawEditor !== undefined && !EDITOR_NAMES.includes(rawEditor as EditorName)) {
-    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, pi", {
-      editor: rawEditor,
-      allowedEditors: EDITOR_NAMES,
-    });
-  }
-
   const editor: EditorName | undefined = rawEditor as EditorName | undefined;
 
   const installResult = installCanonicalSkill(context.cwd);
@@ -489,85 +691,210 @@ function runSkillsInstall(context: CliContext): CliResult {
   });
 }
 
-function updateEditorLink(
-  cwd: string,
-  editor: EditorName,
-  installedDir: string,
-): UpdateLinkEntry {
-  const linkPath: string = resolveDefaultLinkPath(cwd, editor);
-  const expectedTarget: string = resolve(installedDir);
-  const symlinkTarget: string = toRelativeSymlinkTarget(linkPath, expectedTarget);
-  const editorConfigDir: string = resolveEditorConfigDir(cwd, editor);
-
-  if (!existsSync(editorConfigDir)) {
+type ProbeStatus = "ok" | "stale" | "broken" | "legacy" | "not_installed";
+
+interface ProbeResult {
+  readonly path: string;
+  readonly expectedTarget: string;
+  readonly status: ProbeStatus;
+  readonly currentTarget: string | null;
+}
+
+function probeSymlink(linkPath: string, expectedTarget: string): ProbeResult {
+  const resolvedExpected: string = resolve(expectedTarget);
+
+  // Self-reference guard: source and install are the same path (dev mode).
+  if (resolve(linkPath) === resolvedExpected) {
+    return { path: linkPath, expectedTarget: resolvedExpected, status: "ok", currentTarget: resolvedExpected };
+  }
+
+  try {
+    const stat = lstatSync(linkPath);
+
+    if (stat.isSymbolicLink()) {
+      const rawTarget: string = readlinkSync(linkPath);
+      const resolvedCurrent: string = resolve(dirname(linkPath), rawTarget);
+
+      // Check if symlink target actually exists on disk.
+      const targetExists: boolean = existsSync(linkPath);
+      if (!targetExists) {
+        return { path: linkPath, expectedTarget: resolvedExpected, status: "broken", currentTarget: resolvedCurrent };
+      }
+
+      if (resolvedCurrent === resolvedExpected) {
+        return { path: linkPath, expectedTarget: resolvedExpected, status: "ok", currentTarget: resolvedCurrent };
+      }
+
+      return { path: linkPath, expectedTarget: resolvedExpected, status: "stale", currentTarget: resolvedCurrent };
+    }
+
+    if (stat.isDirectory()) {
+      return { path: linkPath, expectedTarget: resolvedExpected, status: "legacy", currentTarget: null };
+    }
+
+    // Unexpected file type — treat as legacy.
+    return { path: linkPath, expectedTarget: resolvedExpected, status: "legacy", currentTarget: null };
+  } catch {
+    return { path: linkPath, expectedTarget: resolvedExpected, status: "not_installed", currentTarget: null };
+  }
+}
+
+type RepairAction = "ok" | "repointed" | "created" | "migrated" | "skipped";
+
+interface RepairResult {
+  readonly probe: ProbeResult;
+  readonly action: RepairAction;
+}
+
+function repairSymlink(probe: ProbeResult): RepairResult {
+  switch (probe.status) {
+    case "ok":
+      return { probe, action: "ok" };
+
+    case "stale":
+    case "broken": {
+      rmSync(probe.path, { force: true });
+      mkdirSync(dirname(probe.path), { recursive: true });
+      const target: string = toRelativeSymlinkTarget(probe.path, probe.expectedTarget);
+      symlinkSync(target, probe.path, "dir");
+      return { probe, action: "repointed" };
+    }
+
+    case "legacy": {
+      rmSync(probe.path, { recursive: true, force: true });
+      mkdirSync(dirname(probe.path), { recursive: true });
+      const target: string = toRelativeSymlinkTarget(probe.path, probe.expectedTarget);
+      symlinkSync(target, probe.path, "dir");
+      return { probe, action: "migrated" };
+    }
+
+    case "not_installed":
+      return { probe, action: "skipped" };
+  }
+}
+
+/** Probe and repair, but skip (don't create) when not already installed. */
+function probeAndRepairIfInstalled(linkPath: string, expectedTarget: string): RepairResult {
+  const probe = probeSymlink(linkPath, expectedTarget);
+  if (probe.status === "not_installed") {
+    return { probe, action: "skipped" };
+  }
+  return repairSymlink(probe);
+}
+
+/** Probe and repair local anchor using directory copy instead of symlinks. */
+function probeAndRepairLocalAnchor(installedDir: string, sourceDir: string): RepairResult {
+  const resolvedExpected: string = resolve(sourceDir);
+  const sourcePath: string = join(sourceDir, "SKILL.md");
+  const installedPath: string = join(installedDir, "SKILL.md");
+
+  // Self-reference guard: source and install are the same path (dev mode).
+  if (resolve(installedDir) === resolvedExpected) {
     return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "skipped_no_editor_dir",
-      conflictCode: null,
-      existingTarget: null,
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "ok", currentTarget: resolvedExpected },
+      action: "ok",
     };
   }
 
-  if (!existsSync(linkPath)) {
-    mkdirSync(dirname(linkPath), { recursive: true });
-    symlinkSync(symlinkTarget, linkPath, "dir");
+  let existingIsSymlink = false;
+  let existingIsDir = false;
+  let pathOccupied = false;
+
+  try {
+    const stat = lstatSync(installedDir);
+    pathOccupied = true;
+    existingIsSymlink = stat.isSymbolicLink();
+    existingIsDir = stat.isDirectory();
+  } catch {
+    // Not installed.
+  }
+
+  if (!pathOccupied) {
     return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "created",
-      conflictCode: null,
-      existingTarget: null,
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "not_installed", currentTarget: null },
+      action: "skipped",
     };
   }
 
-  const entry = lstatSync(linkPath);
-  if (!entry.isSymbolicLink()) {
-    // Replace stale directory or file with symlink to the canonical location.
-    rmSync(linkPath, { recursive: true, force: true });
-    mkdirSync(dirname(linkPath), { recursive: true });
-    symlinkSync(symlinkTarget, linkPath, "dir");
+  if (existingIsSymlink) {
+    // Legacy symlink — migrate to directory copy.
+    let currentTarget: string | null = null;
+    try {
+      const rawTarget = readlinkSync(installedDir);
+      currentTarget = resolve(dirname(installedDir), rawTarget);
+    } catch {
+      // Broken symlink.
+    }
+    rmSync(installedDir, { force: true });
+    mkdirSync(dirname(installedDir), { recursive: true });
+    cpSync(resolvedExpected, installedDir, { recursive: true });
     return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "refreshed",
-      conflictCode: null,
-      existingTarget: null,
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "legacy", currentTarget },
+      action: "migrated",
     };
   }
 
-  const existingRawTarget: string = readlinkSync(linkPath);
-  const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+  if (existingIsDir) {
+    // Real directory — check if contents match.
+    try {
+      const sourceContents = readFileSync(sourcePath, "utf8");
+      const installedContents = readFileSync(installedPath, "utf8");
+      if (sourceContents === installedContents) {
+        return {
+          probe: { path: installedDir, expectedTarget: resolvedExpected, status: "ok", currentTarget: null },
+          action: "ok",
+        };
+      }
+    } catch {
+      // Can't read — treat as stale.
+    }
 
-  if (existingTarget !== expectedTarget) {
-    // Replace symlink pointing to a different target.
-    rmSync(linkPath, { force: true });
-    symlinkSync(symlinkTarget, linkPath, "dir");
+    // Stale copy — refresh.
+    rmSync(installedDir, { recursive: true, force: true });
+    mkdirSync(dirname(installedDir), { recursive: true });
+    cpSync(resolvedExpected, installedDir, { recursive: true });
     return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "refreshed",
-      conflictCode: null,
-      existingTarget,
+      probe: { path: installedDir, expectedTarget: resolvedExpected, status: "stale", currentTarget: null },
+      action: "repointed",
     };
   }
 
-  rmSync(linkPath, { force: true });
-  symlinkSync(symlinkTarget, linkPath, "dir");
+  // Unexpected file type — remove and copy.
+  rmSync(installedDir, { force: true });
+  mkdirSync(dirname(installedDir), { recursive: true });
+  cpSync(resolvedExpected, installedDir, { recursive: true });
   return {
-    editor,
-    linkPath,
-    expectedTarget,
-    action: "refreshed",
-    conflictCode: null,
-    existingTarget,
+    probe: { path: installedDir, expectedTarget: resolvedExpected, status: "legacy", currentTarget: null },
+    action: "migrated",
   };
 }
 
+type UpdateScope = "global" | "local";
+
+interface UpdateEntry {
+  readonly scope: UpdateScope;
+  readonly label: string;
+  readonly repair: RepairResult;
+}
+
+function formatUpdateEntry(entry: UpdateEntry): string {
+  const { scope, label, repair } = entry;
+  const prefix = `${scope} ${label}`;
+
+  switch (repair.action) {
+    case "ok":
+      return `  ok  ${prefix}`;
+    case "repointed":
+      return `  fix ${prefix} repointed`;
+    case "created":
+      return `  new ${prefix} created`;
+    case "migrated":
+      return `  fix ${prefix} migrated from legacy dir`;
+    case "skipped":
+      return `  --  ${prefix} not installed`;
+  }
+}
+
 function runSkillsUpdate(context: CliContext): CliResult {
   const parsed = parseArgs(context.args);
   if (parsed.positional.length > 1) {
@@ -578,67 +905,89 @@ function runSkillsUpdate(context: CliContext): CliResult {
     return invalidArgs("skills update takes no options.");
   }
 
-  const installResult = installCanonicalSkill(context.cwd);
-  if ("ok" in installResult) {
+  const sourceDir: string = resolveBundledSkillDirPath();
+  const sourcePath: string = resolveBundledSkillFilePath();
+
+  if (!existsSync(sourcePath)) {
     return failResult({
       command: "skills.update",
-      human: installResult.human,
-      data: installResult.data,
-      error:
-        installResult.error ?? {
-          code: "install_failed",
-          message: "Failed to refresh canonical skill",
-        },
+      human: `Bundled skill asset not found at ${sourcePath}`,
+      data: { code: "missing_asset", sourcePath },
+      error: { code: "missing_asset", message: "Bundled skill asset not found" },
     });
   }
 
-  const links: readonly UpdateLinkEntry[] = EDITOR_NAMES.map((editor) =>
-    updateEditorLink(context.cwd, editor, installResult.installedDir),
-  );
+  const entries: UpdateEntry[] = [];
+  const home: string = homedir();
 
-  const outcome: UpdateOutcome = {
-    sourcePath: installResult.sourcePath,
-    installedPath: installResult.installedPath,
-    installedDir: installResult.installedDir,
-    links,
-  };
-
-  const linkSummary: string = outcome.links
-    .map((entry) => {
-      if (entry.action === "created") {
-        return `- ${entry.editor}: created (${entry.linkPath} -> ${entry.expectedTarget})`;
-      }
-
-      if (entry.action === "refreshed") {
-        return `- ${entry.editor}: refreshed (${entry.linkPath} -> ${entry.expectedTarget})`;
-      }
+  try {
+    // Global anchor: ~/.agents/skills/trekoon → bundled package dir.
+    const globalAnchorPath: string = join(home, ".agents", "skills", "trekoon");
+    entries.push({ scope: "global", label: "anchor", repair: probeAndRepairIfInstalled(globalAnchorPath, sourceDir) });
+
+    // Global editor links: <editor-global-skills>/trekoon → global anchor.
+    for (const editor of EDITOR_NAMES) {
+      const editorSkillsDir: string = resolveGlobalEditorSkillsDir(editor);
+      const linkPath: string = join(editorSkillsDir, "trekoon");
+      entries.push({ scope: "global", label: editor, repair: probeAndRepairIfInstalled(linkPath, globalAnchorPath) });
+    }
 
-      if (entry.action === "skipped_no_editor_dir") {
-        return `- ${entry.editor}: skipped (no editor config dir)`;
+    // Local anchor: <cwd>/.agents/skills/trekoon — directory copy of bundled source.
+    const localAnchorPath: string = join(context.cwd, ".agents", "skills", "trekoon");
+    entries.push({ scope: "local", label: "anchor", repair: probeAndRepairLocalAnchor(localAnchorPath, sourceDir) });
+
+    // Local editor links: <cwd>/.<editor>/skills/trekoon → local anchor.
+    for (const editor of EDITOR_NAMES) {
+      const editorConfigDir: string = resolveEditorConfigDir(context.cwd, editor);
+      const linkPath: string = resolveDefaultLinkPath(context.cwd, editor);
+
+      if (!existsSync(editorConfigDir)) {
+        const probe: ProbeResult = {
+          path: linkPath,
+          expectedTarget: resolve(localAnchorPath),
+          status: "not_installed",
+          currentTarget: null,
+        };
+        entries.push({ scope: "local", label: editor, repair: { probe, action: "skipped" } });
+        continue;
       }
 
-      if (entry.conflictCode === "non_link") {
-        return `- ${entry.editor}: conflict (non-link path at ${entry.linkPath})`;
+      const probe = probeSymlink(linkPath, localAnchorPath);
+      if (probe.status === "not_installed") {
+        // Editor config dir exists but no link yet — create it.
+        const action = ensureSymlink(linkPath, localAnchorPath);
+        entries.push({ scope: "local", label: editor, repair: { probe, action: action === "already_ok" ? "ok" : "created" } });
+      } else {
+        const repair = repairSymlink(probe);
+        entries.push({ scope: "local", label: editor, repair });
       }
+    }
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown update failure";
+    return failResult({
+      command: "skills.update",
+      human: `Failed to update skill: ${message}`,
+      data: { code: "update_failed", message },
+      error: { code: "update_failed", message },
+    });
+  }
 
-      return `- ${entry.editor}: conflict (points to ${entry.existingTarget})`;
-    })
-    .join("\n");
+  const summary: string = entries.map(formatUpdateEntry).join("\n");
 
   return okResult({
     command: "skills.update",
-    human: [
-      "Updated Trekoon skill in canonical path.",
-      `Source: ${outcome.sourcePath}`,
-      `Installed file: ${outcome.installedPath}`,
-      "Editor links:",
-      linkSummary,
-    ].join("\n"),
+    human: ["Trekoon skill update:", summary].join("\n"),
     data: {
-      sourcePath: outcome.sourcePath,
-      installedPath: outcome.installedPath,
-      installedDir: outcome.installedDir,
-      links: outcome.links,
+      sourceDir,
+      entries: entries.map((e) => ({
+        scope: e.scope,
+        label: e.label,
+        path: e.repair.probe.path,
+        expectedTarget: e.repair.probe.expectedTarget,
+        status: e.repair.probe.status,
+        action: e.repair.action,
+        currentTarget: e.repair.probe.currentTarget,
+      })),
     },
   });
 }