trekoon 0.1.5 → 0.1.7

package/README.md

@@ -52,7 +52,8 @@ npm i -g trekoon
 - `trekoon subtask <create|list|update|delete>`
 - `trekoon dep <add|remove|list>`
 - `trekoon sync <status|pull|resolve>`
-- `trekoon skills install [--link --editor opencode|claude] [--to <path>]`
+- `trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]`
+- `trekoon skills update`
 - `trekoon wipe --yes`
 
 Global output modes:
@@ -160,6 +161,15 @@ trekoon sync pull --from main
 trekoon sync resolve <conflict-id> --use ours
 ```
 
+`sync pull` machine output includes diagnostics counters and hints so agents can
+react deterministically:
+
+- `diagnostics.malformedPayloadEvents`
+- `diagnostics.applyRejectedEvents`
+- `diagnostics.quarantinedEvents`
+- `diagnostics.conflictEvents`
+- `diagnostics.errorHints`
+
 ### 6) Install project-local Trekoon skill for agents
 
 `trekoon skills install` always writes the bundled skill file into the current
@@ -173,17 +183,29 @@ You can also create a project-local editor link:
 trekoon skills install
 trekoon skills install --link --editor opencode
 trekoon skills install --link --editor claude
+trekoon skills install --link --editor pi
 trekoon skills install --link --editor opencode --to ./.custom-editor/skills
+trekoon skills update
 ```
 
 Path behavior:
 
 - Default opencode link path: `.opencode/skills/trekoon`
 - Default claude link path: `.claude/skills/trekoon`
+- Default pi link path: `.pi/skills/trekoon`
 - `--to <path>` overrides the editor root for link creation only.
 - `--to` does **not** move or copy `SKILL.md` to that path.
+- By default, link targets must resolve inside the repository root.
+- Use `--allow-outside-repo` only for intentional external links.
+- When override is used, install prints a warning and includes confirmation
+  fields in machine output.
 - Re-running install is idempotent: it refreshes `SKILL.md` and reuses/replaces
   the same symlink target.
+- `trekoon skills update` is idempotent: it refreshes canonical
+  `.agents/skills/trekoon/SKILL.md` and reports default link states for
+  opencode/claude/pi as `missing`, `valid`, or `conflict`.
+- Update does not mutate default links; conflicts are reported with actionable
+  path context.
 - If the link destination exists as a non-link path, install fails with an
   actionable conflict error.
 
@@ -215,7 +237,7 @@ Trekoon does not mutate global editor config directories.
 - [ ] `trekoon sync status` shows no unresolved conflicts
 - [ ] done tasks/subtasks are marked completed
 - [ ] dependency graph has no stale blockers
-- [ ] final AI check: `trekoon --json epic show <epic-id>`
+- [ ] final AI check: `trekoon --toon epic show <epic-id>`
 
 ## Implementation principles
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "AI-first local issue tracker CLI.",
   "license": "MIT",
   "type": "module",

package/src/commands/dep.ts

@@ -1,7 +1,8 @@
 import { parseArgs } from "./arg-parser";
 
-import { DomainError } from "../domain/types";
+import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
+import { DomainError } from "../domain/types";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 import { openTrekoonDatabase } from "../storage/database";
@@ -42,10 +43,11 @@ export async function runDep(context: CliContext): Promise<CliResult> {
     const sourceId: string = parsed.positional[1] ?? "";
     const dependsOnId: string = parsed.positional[2] ?? "";
     const domain = new TrackerDomain(database.db);
+    const mutations = new MutationService(database.db, context.cwd);
 
     switch (subcommand) {
       case "add": {
-        const dependency = domain.addDependency(sourceId, dependsOnId);
+        const dependency = mutations.addDependency(sourceId, dependsOnId);
 
         return okResult({
           command: "dep.add",
@@ -54,7 +56,7 @@ export async function runDep(context: CliContext): Promise<CliResult> {
         });
       }
       case "remove": {
-        const removed: number = domain.removeDependency(sourceId, dependsOnId);
+        const removed: number = mutations.removeDependency(sourceId, dependsOnId);
 
         return okResult({
           command: "dep.remove",

package/src/commands/epic.ts

@@ -1,7 +1,8 @@
 import { hasFlag, parseArgs, parseStrictPositiveInt, readEnumOption, readMissingOptionValue, readOption } from "./arg-parser";
 
-import { DomainError, type EpicRecord } from "../domain/types";
+import { MutationService } from "../domain/mutation-service";
 import { TrackerDomain } from "../domain/tracker-domain";
+import { DomainError, type EpicRecord } from "../domain/types";
 import { formatHumanTable } from "../io/human-table";
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
@@ -235,6 +236,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
     const parsed = parseArgs(context.args);
     const subcommand: string | undefined = parsed.positional[0];
     const domain = new TrackerDomain(database.db);
+    const mutations = new MutationService(database.db, context.cwd);
 
     switch (subcommand) {
       case "create": {
@@ -248,7 +250,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
         const title: string | undefined = readOption(parsed.options, "title", "t");
         const description: string | undefined = readOption(parsed.options, "description", "d");
         const status: string | undefined = readOption(parsed.options, "status", "s");
-        const epic = domain.createEpic({
+        const epic = mutations.createEpic({
           title: title ?? "",
           description: description ?? "",
           status,
@@ -467,7 +469,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
 
           const targets = updateAll ? [...domain.listEpics()] : ids.map((id) => domain.getEpicOrThrow(id));
           const epics = targets.map((target) =>
-            domain.updateEpic(target.id, {
+            mutations.updateEpic(target.id, {
               status,
               description: append === undefined ? undefined : appendLine(target.description, append),
             }),
@@ -500,7 +502,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
           append === undefined
             ? description
             : appendLine(domain.getEpicOrThrow(epicId).description, append);
-        const epic = domain.updateEpic(epicId, { title, description: nextDescription, status });
+        const epic = mutations.updateEpic(epicId, { title, description: nextDescription, status });
 
         return okResult({
           command: "epic.update",
@@ -510,7 +512,7 @@ export async function runEpic(context: CliContext): Promise<CliResult> {
       }
       case "delete": {
         const epicId: string = parsed.positional[1] ?? "";
-        domain.deleteEpic(epicId);
+        mutations.deleteEpic(epicId);
 
         return okResult({
           command: "epic.delete",

package/src/commands/help.ts

@@ -42,7 +42,7 @@ const COMMAND_HELP: Record<string, string> = {
   migrate: "Usage: trekoon migrate <status|rollback> [--to-version <n>]",
   sync: "Usage: trekoon sync <subcommand> [options]",
   skills:
-    "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>] (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md)",
+    "Usage: trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo] | trekoon skills update (--to sets symlink root for --link only; install path always <cwd>/.agents/skills/trekoon/SKILL.md; links must resolve inside repo unless --allow-outside-repo is set; update refreshes canonical SKILL and reports default link states)",
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/skills.ts

@@ -1,5 +1,5 @@
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { hasFlag, parseArgs, readMissingOptionValue, readOption } from "./arg-parser";
@@ -7,10 +7,16 @@ import { hasFlag, parseArgs, readMissingOptionValue, readOption } from "./arg-pa
 import { failResult, okResult } from "../io/output";
 import { type CliContext, type CliResult } from "../runtime/command-types";
 
-const SKILLS_USAGE = "Usage: trekoon skills install [--link --editor opencode|claude] [--to <path>]";
-const EDITOR_NAMES = ["opencode", "claude"] as const;
+const SKILLS_USAGE = [
+  "Usage:",
+  "  trekoon skills install [--link --editor opencode|claude|pi] [--to <path>] [--allow-outside-repo]",
+  "  trekoon skills update",
+].join("\n");
+const EDITOR_NAMES = ["opencode", "claude", "pi"] as const;
+const ALLOW_OUTSIDE_REPO_FLAG = "allow-outside-repo";
 
 type EditorName = (typeof EDITOR_NAMES)[number];
+type LinkStateStatus = "missing" | "valid" | "conflict";
 
 interface InstallOutcome {
   readonly sourcePath: string;
@@ -18,6 +24,28 @@ interface InstallOutcome {
   readonly installedDir: string;
   readonly linkPath: string | null;
   readonly linkTarget: string | null;
+  readonly outsideRepoLink: boolean;
+}
+
+interface LinkTargetValidation {
+  readonly linkRoot: string;
+  readonly outsideRepoLink: boolean;
+}
+
+interface LinkState {
+  readonly editor: EditorName;
+  readonly linkPath: string;
+  readonly expectedTarget: string;
+  readonly status: LinkStateStatus;
+  readonly existingTarget: string | null;
+  readonly conflictCode: "non_link" | "wrong_target" | null;
+}
+
+interface UpdateOutcome {
+  readonly sourcePath: string;
+  readonly installedPath: string;
+  readonly installedDir: string;
+  readonly links: readonly LinkState[];
 }
 
 function invalidArgs(message: string): CliResult {
@@ -68,12 +96,183 @@ function resolveLinkRoot(cwd: string, editor: EditorName, toOverride: string | u
     return join(cwd, ".opencode", "skills");
   }
 
-  return join(cwd, ".claude", "skills");
+  if (editor === "claude") {
+    return join(cwd, ".claude", "skills");
+  }
+
+  return join(cwd, ".pi", "skills");
+}
+
+function isPathInsideRoot(pathValue: string, rootPath: string): boolean {
+  const normalizedPath: string = resolve(pathValue);
+  const normalizedRoot: string = resolve(rootPath);
+  const relativePath: string = relative(normalizedRoot, normalizedPath);
+  return relativePath === "" || (!relativePath.startsWith("..") && !isAbsolute(relativePath));
+}
+
+function realpathNearestExistingAncestor(pathValue: string): string {
+  let cursor: string = resolve(pathValue);
+
+  while (!existsSync(cursor)) {
+    const parent: string = dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+
+    cursor = parent;
+  }
+
+  return realpathSync(cursor);
+}
+
+function validateLinkRoot(
+  cwd: string,
+  editor: EditorName,
+  toOverride: string | undefined,
+  allowOutsideRepo: boolean,
+): CliResult | LinkTargetValidation {
+  const linkRoot: string = resolveLinkRoot(cwd, editor, toOverride);
+  const repoRoot: string = realpathSync(cwd);
+  const effectiveTargetRoot: string = realpathNearestExistingAncestor(linkRoot);
+  const insideRepo: boolean = isPathInsideRoot(effectiveTargetRoot, repoRoot);
+
+  if (insideRepo) {
+    return {
+      linkRoot,
+      outsideRepoLink: false,
+    };
+  }
+
+  if (!allowOutsideRepo) {
+    return failResult({
+      command: "skills.install",
+      human: [
+        "Refusing to link skills outside repository root by default.",
+        `Requested link root: ${linkRoot}`,
+        `Resolved existing target ancestor: ${effectiveTargetRoot}`,
+        `Repository root: ${repoRoot}`,
+        `If intentional, re-run with --${ALLOW_OUTSIDE_REPO_FLAG} to override.`,
+      ].join("\n"),
+      data: {
+        code: "outside_repo_target",
+        linkRoot,
+        effectiveTargetRoot,
+        repoRoot,
+        overrideFlag: `--${ALLOW_OUTSIDE_REPO_FLAG}`,
+      },
+      error: {
+        code: "outside_repo_target",
+        message: "Link target is outside repository root",
+      },
+    });
+  }
+
+  return {
+    linkRoot,
+    outsideRepoLink: true,
+  };
+}
+
+function revalidateLinkParentBoundary(
+  repoRoot: string,
+  linkPath: string,
+  allowOutsideRepo: boolean,
+): CliResult | null {
+  if (allowOutsideRepo) {
+    return null;
+  }
+
+  const linkParentRealpath: string = realpathSync(dirname(linkPath));
+  const insideRepo: boolean = isPathInsideRoot(linkParentRealpath, repoRoot);
+  if (insideRepo) {
+    return null;
+  }
+
+  return failResult({
+    command: "skills.install",
+    human: [
+      "Refusing to link skills outside repository root by default.",
+      `Requested link root: ${dirname(linkPath)}`,
+      `Resolved existing target ancestor: ${linkParentRealpath}`,
+      `Repository root: ${repoRoot}`,
+      `If intentional, re-run with --${ALLOW_OUTSIDE_REPO_FLAG} to override.`,
+    ].join("\n"),
+    data: {
+      code: "outside_repo_target",
+      linkRoot: dirname(linkPath),
+      effectiveTargetRoot: linkParentRealpath,
+      repoRoot,
+      overrideFlag: `--${ALLOW_OUTSIDE_REPO_FLAG}`,
+    },
+    error: {
+      code: "outside_repo_target",
+      message: "Link target is outside repository root",
+    },
+  });
+}
+
+function resolveDefaultLinkPath(cwd: string, editor: EditorName): string {
+  return join(resolveLinkRoot(cwd, editor, undefined), "trekoon");
+}
+
+function installCanonicalSkill(cwd: string): CliResult | { sourcePath: string; installedPath: string; installedDir: string } {
+  const sourcePath: string = resolveBundledSkillFilePath();
+  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",
+      },
+    });
+  }
+
+  const installedPath: string = join(cwd, ".agents", "skills", "trekoon", "SKILL.md");
+  const installedDir: string = dirname(installedPath);
+
+  try {
+    mkdirSync(installedDir, { recursive: true });
+    copyFileSync(sourcePath, installedPath);
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : "Unknown skills install failure";
+    return failResult({
+      command: "skills.install",
+      human: `Failed to install skill: ${message}`,
+      data: {
+        code: "install_failed",
+        message,
+      },
+      error: {
+        code: "install_failed",
+        message,
+      },
+    });
+  }
+
+  return {
+    sourcePath,
+    installedPath,
+    installedDir,
+  };
 }
 
-function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult | null {
+function replaceOrCreateSymlink(
+  linkPath: string,
+  targetPath: string,
+  repoRoot: string,
+  allowOutsideRepo: boolean,
+): CliResult | null {
   if (!existsSync(linkPath)) {
     mkdirSync(dirname(linkPath), { recursive: true });
+    const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+    if (boundaryFailure) {
+      return boundaryFailure;
+    }
     symlinkSync(targetPath, linkPath, "dir");
     return null;
   }
@@ -116,10 +315,64 @@ function replaceOrCreateSymlink(linkPath: string, targetPath: string): CliResult
   }
 
   rmSync(linkPath, { force: true });
+  const boundaryFailure = revalidateLinkParentBoundary(repoRoot, linkPath, allowOutsideRepo);
+  if (boundaryFailure) {
+    return boundaryFailure;
+  }
   symlinkSync(targetPath, linkPath, "dir");
   return null;
 }
 
+function inspectDefaultLink(cwd: string, editor: EditorName, installedDir: string): LinkState {
+  const linkPath: string = resolveDefaultLinkPath(cwd, editor);
+  const expectedTarget: string = resolve(installedDir);
+
+  if (!existsSync(linkPath)) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      status: "missing",
+      existingTarget: null,
+      conflictCode: null,
+    };
+  }
+
+  const entry = lstatSync(linkPath);
+  if (!entry.isSymbolicLink()) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      status: "conflict",
+      existingTarget: null,
+      conflictCode: "non_link",
+    };
+  }
+
+  const existingRawTarget: string = readlinkSync(linkPath);
+  const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+  if (existingTarget !== expectedTarget) {
+    return {
+      editor,
+      linkPath,
+      expectedTarget,
+      status: "conflict",
+      existingTarget,
+      conflictCode: "wrong_target",
+    };
+  }
+
+  return {
+    editor,
+    linkPath,
+    expectedTarget,
+    status: "valid",
+    existingTarget,
+    conflictCode: null,
+  };
+}
+
 function runSkillsInstall(context: CliContext): CliResult {
   const parsed = parseArgs(context.args);
   const missingValue = readMissingOptionValue(parsed.missingOptionValues, "editor", "to");
@@ -134,9 +387,16 @@ function runSkillsInstall(context: CliContext): CliResult {
   }
 
   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");
 
+  if (allowOutsideRepo && !wantsLink) {
+    return invalidInput("skills.install", `--${ALLOW_OUTSIDE_REPO_FLAG} requires --link.`, {
+      allowOutsideRepo,
+    });
+  }
+
   if (!wantsLink && rawEditor !== undefined) {
     return invalidInput("skills.install", "--editor requires --link.", {
       editor: rawEditor,
@@ -150,11 +410,11 @@ function runSkillsInstall(context: CliContext): CliResult {
   }
 
   if (wantsLink && rawEditor === undefined) {
-    return invalidArgs("skills install --link requires --editor opencode|claude.");
+    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", {
+    return invalidInput("skills.install", "Invalid --editor value. Use: opencode, claude, pi", {
       editor: rawEditor,
       allowedEditors: EDITOR_NAMES,
     });
@@ -162,51 +422,54 @@ function runSkillsInstall(context: CliContext): CliResult {
 
   const editor: EditorName | undefined = rawEditor as EditorName | undefined;
 
-  const sourcePath: string = resolveBundledSkillFilePath();
-  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",
-      },
-    });
+  const installResult = installCanonicalSkill(context.cwd);
+  if ("ok" in installResult) {
+    return installResult;
   }
 
-  const installPath = join(context.cwd, ".agents", "skills", "trekoon", "SKILL.md");
-  const installDir = dirname(installPath);
-
   let outcome: InstallOutcome;
 
   try {
-    mkdirSync(installDir, { recursive: true });
-    copyFileSync(sourcePath, installPath);
-
     let linkPath: string | null = null;
     let linkTarget: string | null = null;
 
     if (wantsLink && editor !== undefined) {
-      const linkRoot: string = resolveLinkRoot(context.cwd, editor, rawTo);
+      const validation = validateLinkRoot(context.cwd, editor, rawTo, allowOutsideRepo);
+      if ("ok" in validation) {
+        return validation;
+      }
+
+      const linkRoot: string = validation.linkRoot;
       linkPath = join(linkRoot, "trekoon");
-      linkTarget = installDir;
-      const linkFailure = replaceOrCreateSymlink(linkPath, linkTarget);
+      linkTarget = installResult.installedDir;
+      const linkFailure = replaceOrCreateSymlink(
+        linkPath,
+        linkTarget,
+        realpathSync(context.cwd),
+        allowOutsideRepo,
+      );
       if (linkFailure) {
         return linkFailure;
       }
-    }
 
-    outcome = {
-      sourcePath,
-      installedPath: installPath,
-      installedDir: installDir,
-      linkPath,
-      linkTarget,
-    };
+      outcome = {
+        sourcePath: installResult.sourcePath,
+        installedPath: installResult.installedPath,
+        installedDir: installResult.installedDir,
+        linkPath,
+        linkTarget,
+        outsideRepoLink: validation.outsideRepoLink,
+      };
+    } else {
+      outcome = {
+        sourcePath: installResult.sourcePath,
+        installedPath: installResult.installedPath,
+        installedDir: installResult.installedDir,
+        linkPath,
+        linkTarget,
+        outsideRepoLink: false,
+      };
+    }
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -227,6 +490,11 @@ function runSkillsInstall(context: CliContext): CliResult {
     command: "skills.install",
     human: outcome.linkPath
       ? [
+          ...(outcome.outsideRepoLink
+            ? [
+                `WARNING: Linking outside repository root because --${ALLOW_OUTSIDE_REPO_FLAG} was provided.`,
+              ]
+            : []),
           "Installed Trekoon skill and linked editor path.",
           `Source: ${outcome.sourcePath}`,
           `Installed file: ${outcome.installedPath}`,
@@ -245,6 +513,80 @@ function runSkillsInstall(context: CliContext): CliResult {
       linked: outcome.linkPath !== null,
       linkPath: outcome.linkPath,
       linkTarget: outcome.linkTarget,
+      outsideRepoLink: outcome.outsideRepoLink,
+      outsideRepoOverrideUsed: outcome.outsideRepoLink,
+      outsideRepoOverrideFlag: outcome.outsideRepoLink ? `--${ALLOW_OUTSIDE_REPO_FLAG}` : null,
+    },
+  });
+}
+
+function runSkillsUpdate(context: CliContext): CliResult {
+  const parsed = parseArgs(context.args);
+  if (parsed.positional.length > 1) {
+    return invalidArgs("Unexpected positional arguments for skills update.");
+  }
+
+  if (parsed.flags.size > 0 || parsed.options.size > 0) {
+    return invalidArgs("skills update takes no options.");
+  }
+
+  const installResult = installCanonicalSkill(context.cwd);
+  if ("ok" in installResult) {
+    return failResult({
+      command: "skills.update",
+      human: installResult.human,
+      data: installResult.data,
+      error:
+        installResult.error ?? {
+          code: "install_failed",
+          message: "Failed to refresh canonical skill",
+        },
+    });
+  }
+
+  const links: readonly LinkState[] = EDITOR_NAMES.map((editor) =>
+    inspectDefaultLink(context.cwd, editor, installResult.installedDir),
+  );
+
+  const outcome: UpdateOutcome = {
+    sourcePath: installResult.sourcePath,
+    installedPath: installResult.installedPath,
+    installedDir: installResult.installedDir,
+    links,
+  };
+
+  const linkSummary: string = outcome.links
+    .map((entry) => {
+      if (entry.status === "missing") {
+        return `- ${entry.editor}: missing (${entry.linkPath})`;
+      }
+
+      if (entry.status === "valid") {
+        return `- ${entry.editor}: valid (${entry.linkPath} -> ${entry.expectedTarget})`;
+      }
+
+      if (entry.conflictCode === "non_link") {
+        return `- ${entry.editor}: conflict (non-link path at ${entry.linkPath})`;
+      }
+
+      return `- ${entry.editor}: conflict (points to ${entry.existingTarget})`;
+    })
+    .join("\n");
+
+  return okResult({
+    command: "skills.update",
+    human: [
+      "Updated Trekoon skill in canonical path.",
+      `Source: ${outcome.sourcePath}`,
+      `Installed file: ${outcome.installedPath}`,
+      "Default link states:",
+      linkSummary,
+    ].join("\n"),
+    data: {
+      sourcePath: outcome.sourcePath,
+      installedPath: outcome.installedPath,
+      installedDir: outcome.installedDir,
+      links: outcome.links,
     },
   });
 }
@@ -259,6 +601,8 @@ export async function runSkills(context: CliContext): Promise<CliResult> {
   switch (subcommand) {
     case "install":
       return runSkillsInstall(context);
+    case "update":
+      return runSkillsUpdate(context);
     default:
       return invalidArgs(`Unknown skills subcommand '${subcommand}'.`);
   }