trekoon 0.3.2 → 0.3.3

package/.agents/skills/trekoon/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: trekoon
-description: Use Trekoon to create issues/tasks, plan backlog and sprints, create epics, update status, track progress, and manage dependencies/sync across repository workflows.
+description: Use Trekoon only for agentic development planning and execution, limited to creating epics with tasks and subtasks, planning backlog/sprints, updating status, tracking progress, and managing dependencies/sync across repository workflows with agents. Only invoke Trekoon when explicitly requested by the user.
 ---
 
 # Trekoon Skill
@@ -61,6 +61,8 @@ This skill ships with bundled reference guides for planning and execution. Read
 them when the task calls for it — they extend this command reference with
 methodology and orchestration patterns.
 
+> **Path note:** Script paths below are relative to this skill's folder (where this SKILL.md lives), not the current project root. Resolve them from this skill folder when invoking Bash.
+
 | When | Read | What it covers |
 |---|---|---|
 | User asks to plan, design, or architect a feature | `reference/planning.md` | Decomposition into epic/task/subtask DAGs, writing standard, file scopes, owner assignment, dependency modeling, validation |
@@ -70,9 +72,7 @@ methodology and orchestration patterns.
 **Typical flow:**
 1. Read `reference/planning.md` and create the epic with tasks, subtasks, deps,
    owners.
-2. Read `reference/execution.md` (or `reference/execution-with-team.md` for Agent
-   Teams), run `session --epic`, build lane groups, dispatch agents, use
-   `task done` responses to orchestrate waves.
+2. Read `reference/execution.md` for the regular subagents flow OR `reference/execution-with-team.md` for the Agent Teams flow. Then run `session --epic`, build lane groups, dispatch agents, and use `task done` responses to orchestrate waves.
 3. This file (SKILL.md) provides the command reference and status machine rules
    that both planning and execution rely on.
 

package/README.md

@@ -49,13 +49,13 @@ These are the commands most people need to recognize quickly:
 | --- | --- |
 | Initialize a repo | `trekoon init` |
 | Install/open/update the local board | `trekoon board open`, `trekoon board update` |
-| Learn the CLI | `trekoon help [command]`, `trekoon quickstart` |
+| Learn the CLI | `trekoon [command] -h`, `trekoon [command] [subcommand] -h`, `trekoon quickstart` |
 | Plan work | `trekoon epic ...`, `trekoon task ...`, `trekoon subtask ...`, `trekoon dep ...` |
 | Track epic progress | `trekoon epic progress <id>` |
 | Start an execution session | `trekoon session`, `trekoon session --epic <id>` |
 | Get next-action suggestions | `trekoon suggest`, `trekoon suggest --epic <id>` |
 | Keep worktrees in sync | `trekoon sync ...` |
-| Install or refresh the AI skill | `trekoon skills install`, `trekoon skills update` |
+| Install or refresh the AI skill | `trekoon skills install`, `trekoon skills install -g`, `trekoon skills update` |
 | Maintenance | `trekoon events prune ...`, `trekoon migrate ...`, `trekoon wipe --yes` |
 
 Machine output modes:
@@ -141,6 +141,14 @@ covers the full plan-to-completion workflow:
 - **Agent Teams** — TeamCreate/SendMessage pattern for parallel Claude Code
   instances (requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`)
 
+Install it per-repo or globally:
+
+```bash
+trekoon skills install          # repo-local (default)
+trekoon skills install -g       # global (~/.agents/skills/trekoon)
+trekoon update                  # refresh all installed links
+```
+
 The skill accepts arguments for quick entity-scoped actions:
 
 ```

package/docs/quickstart.md

@@ -229,6 +229,25 @@ Valid transitions:
 | `blocked` | `in_progress`, `todo` |
 | `done` | `in_progress` |
 
+## Install the AI skill
+
+Install the Trekoon skill so AI agents can plan and execute against your tracker:
+
+```bash
+trekoon skills install                # repo-local (default)
+trekoon skills install -g             # global (~/.agents/skills/trekoon)
+trekoon skills install --link --editor claude  # repo-local + editor symlink
+```
+
+After upgrading Trekoon, refresh all installed symlinks:
+
+```bash
+trekoon update                        # alias for: trekoon skills update
+```
+
+For detailed installation, editor linking, and example prompts, read
+[AI agents and the Trekoon skill](ai-agents.md).
+
 ## What to read next
 
 - [Command reference](commands.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "AI-first local issue tracker CLI.",
   "keywords": [
     "ai",
@@ -45,7 +45,7 @@
     "lint": "bunx tsc --noEmit"
   },
   "devDependencies": {
-    "@types/bun": "^1.3.9",
+    "@types/bun": "^1.3.11",
     "typescript": "^5.9.3"
   },
   "dependencies": {

package/src/board/assets/state/utils.js

@@ -143,7 +143,7 @@ export function normalizeSnapshot(rawSnapshot) {
       id: epicId,
       title: String(epic.title ?? "Untitled epic"),
       description: String(epic.description ?? "").replace(/\\n/g, "\n"),
-      status: String(epic.status ?? "todo"),
+      status: normalizeStatus(String(epic.status ?? "todo")),
       createdAt: Number(epic.createdAt ?? Date.now()),
       updatedAt: Number(epic.updatedAt ?? epic.createdAt ?? Date.now()),
       taskIds: epicTasks.map((task) => task.id),

package/src/commands/arg-parser.ts

@@ -42,6 +42,7 @@ export interface ParsedCompactFields {
 }
 
 const LONG_PREFIX = "--";
+const SHORT_FLAG_PATTERN = /^-([A-Za-z])$/u;
 
 export function parseArgs(args: readonly string[]): ParsedArgs {
   const positional: string[] = [];
@@ -57,6 +58,15 @@ export function parseArgs(args: readonly string[]): ParsedArgs {
       continue;
     }
 
+    // Short flag: single dash + single letter (e.g. -g).
+    const shortMatch = SHORT_FLAG_PATTERN.exec(token);
+    if (shortMatch) {
+      const key: string = shortMatch[1]!;
+      flags.add(key);
+      providedOptions.push(key);
+      continue;
+    }
+
     if (!token.startsWith(LONG_PREFIX)) {
       positional.push(token);
       continue;

package/src/commands/help.ts

@@ -30,7 +30,8 @@ const ROOT_HELP = [
   "  migrate      Migration status and rollback commands",
   "  session      One-call agent orientation (diagnostics + sync + next task)",
   "  sync         Cross-branch sync commands",
-  "  skills       Project-local skill install/update/link",
+  "  skills       Skill install/update/link (local and global)",
+  "  update       Alias for skills update",
 ].join("\n");
 
 const INIT_HELP = [
@@ -385,31 +386,46 @@ const SESSION_HELP = [
 const SKILLS_HELP = [
   "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",
   "",
   "Purpose:",
-  "  Install or refresh the project-local Trekoon skill asset.",
+  "  Install or refresh the Trekoon skill asset locally or globally.",
   "",
-  "Install behavior:",
-  "  - Always installs canonical file to:",
-  "      <cwd>/.agents/skills/trekoon/SKILL.md",
+  "Local install behavior (default):",
+  "  - Creates a directory symlink at <cwd>/.agents/skills/trekoon pointing to",
+  "    the bundled package source, so the skill always matches the installed version.",
   "  - Use --link to also create an editor symlink named 'trekoon'.",
   "  - --editor is required when --link is used (opencode|claude|pi).",
   "  - --to overrides the symlink root for --link only.",
   "  - Without --allow-outside-repo, link targets must resolve inside repo.",
   "  - --allow-outside-repo requires --link and disables that boundary check.",
   "",
+  "Global install behavior (-g|--global):",
+  "  - Creates a global anchor symlink at ~/.agents/skills/trekoon pointing to",
+  "    the bundled package source.",
+  "  - Creates per-editor symlinks under each editor's global skills directory",
+  "    (~/.claude/skills/, ~/.config/opencode/skills/, ~/.pi/skills/).",
+  "  - Use --editor to install for a single editor only.",
+  "",
   "Update behavior:",
-  "  - Refreshes canonical SKILL file in the install path above.",
-  "  - Auto-creates or refreshes editor symlinks when editor config dir exists.",
-  "  - Skips editors with no config dir or conflicting paths.",
+  "  - Probes and repairs both global and local anchor/editor symlinks.",
+  "  - Reports per-entry status: ok, repointed, created, migrated, skipped.",
+  "  - Skips entries that are not installed; creates local editor links when",
+  "    the editor config dir exists.",
+  "",
+  "Alias:",
+  "  trekoon update → trekoon skills update",
   "",
   "Examples:",
   "  trekoon skills install",
+  "  trekoon skills install -g",
+  "  trekoon skills install --global --editor claude",
   "  trekoon skills install --link --editor opencode",
   "  trekoon skills install --link --editor claude --to .claude/skills",
   "  trekoon skills install --link --editor pi --to ../shared/skills --allow-outside-repo",
   "  trekoon skills update",
+  "  trekoon update",
 ].join("\n");
 
 const COMMAND_HELP: Record<string, string> = {
@@ -426,6 +442,7 @@ const COMMAND_HELP: Record<string, string> = {
   migrate: MIGRATE_HELP,
   sync: SYNC_HELP,
   skills: SKILLS_HELP,
+  update: "Usage: trekoon update [--json|--toon]\n\nAlias for: trekoon skills update\n\nProbes and repairs all installed global and local skill symlinks.",
   help: "Usage: trekoon help [command] [--json|--toon]",
 };
 

package/src/commands/skills.ts

@@ -1,4 +1,5 @@
-import { copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readlinkSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, 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,62 @@ 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 create
+  // a circular symlink — 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 (existingIsSymlink) {
+        // Already a symlink — check whether it points to the correct target.
+        // Use realpathSync so OS-level symlinks (macOS /var → /private/var)
+        // do not cause false mismatches.
+        try {
+          const resolvedExisting: string = realpathSync(installedDir);
+          if (resolvedExisting === realpathSync(resolvedSourceDir)) {
+            // Symlink is already correct; idempotent success.
+            return { sourcePath, installedPath, installedDir };
+          }
+        } catch {
+          // Broken symlink — fall through to remove and recreate.
+        }
+        // Stale or broken symlink — remove and recreate.
+        rmSync(installedDir, { force: true });
+      } else if (existingIsDir) {
+        // Legacy directory install (file-copy era) — migrate by removing.
+        rmSync(installedDir, { recursive: true, force: true });
+      } else {
+        // Unexpected file — remove.
+        rmSync(installedDir, { force: true });
+      }
     }
+
+    const symlinkTarget: string = toRelativeSymlinkTarget(installedDir, resolvedSourceDir);
+    symlinkSync(symlinkTarget, installedDir, "dir");
   } catch (error: unknown) {
     const message = error instanceof Error ? error.message : "Unknown skills install failure";
     return failResult({
@@ -295,53 +341,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 +536,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 +593,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,83 +693,121 @@ 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)) {
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "skipped_no_editor_dir",
-      conflictCode: null,
-      existingTarget: null,
-    };
-  }
+type ProbeStatus = "ok" | "stale" | "broken" | "legacy" | "not_installed";
 
-  if (!existsSync(linkPath)) {
-    mkdirSync(dirname(linkPath), { recursive: true });
-    symlinkSync(symlinkTarget, linkPath, "dir");
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "created",
-      conflictCode: null,
-      existingTarget: null,
-    };
+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 };
   }
 
-  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");
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "refreshed",
-      conflictCode: null,
-      existingTarget: null,
-    };
+  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 };
   }
+}
 
-  const existingRawTarget: string = readlinkSync(linkPath);
-  const existingTarget: string = toAbsolutePath(dirname(linkPath), existingRawTarget);
+type RepairAction = "ok" | "repointed" | "created" | "migrated" | "skipped";
 
-  if (existingTarget !== expectedTarget) {
-    // Replace symlink pointing to a different target.
-    rmSync(linkPath, { force: true });
-    symlinkSync(symlinkTarget, linkPath, "dir");
-    return {
-      editor,
-      linkPath,
-      expectedTarget,
-      action: "refreshed",
-      conflictCode: null,
-      existingTarget,
-    };
+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" };
   }
+}
 
-  rmSync(linkPath, { force: true });
-  symlinkSync(symlinkTarget, linkPath, "dir");
-  return {
-    editor,
-    linkPath,
-    expectedTarget,
-    action: "refreshed",
-    conflictCode: null,
-    existingTarget,
-  };
+/** 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);
+}
+
+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 {
@@ -578,67 +820,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 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})`;
-      }
+  const entries: UpdateEntry[] = [];
+  const home: string = homedir();
 
-      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 → bundled package dir.
+    const localAnchorPath: string = join(context.cwd, ".agents", "skills", "trekoon");
+    entries.push({ scope: "local", label: "anchor", repair: probeAndRepairIfInstalled(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,
+      })),
     },
   });
 }

package/src/runtime/cli-shell.ts

@@ -34,6 +34,7 @@ const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
   "sync",
   "skills",
   "suggest",
+  "update",
   "wipe",
 ];
 
@@ -398,6 +399,10 @@ export async function executeShell(parsed: ParsedInvocation, cwd: string = proce
     case "suggest":
       result = await runSuggest(context);
       break;
+    case "update":
+      // Route `trekoon update` to `trekoon skills update` internally.
+      result = await runSkills({ ...context, args: ["update", ...context.args] });
+      break;
     default:
       result = failResult({
         command: "shell",