@opengsd/gsd-path 1.4.0 → 1.6.0

package/scripts/install.mjs

@@ -212,9 +212,10 @@ export const EXPLICIT_ONLY_TARGETS = new Set([
   "cursor",
   "zed",
   "kimi",
+  "muse",
   "shared-agents",
 ]);
-const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed"]);
+const SHARED_AGENT_TARGETS = new Set(["codex", "antigravity", "zed", "muse"]);
 export const SHARED_AGENT_PROFILE = "shared-agents";
 export const CURSOR_AGENT_FILENAME = "gsd-path.md";
 export const CURSOR_AGENT_BACKUP_NAME = "cursor-agent-gsd-path.md";
@@ -228,7 +229,7 @@ const MANIFEST = JSON.parse(
 );
 
 function sharedInvocations(text) {
-  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed)\))?/g;
+  const pattern = /(`?)(\$gsd-path(?:-[a-z0-9]+)*|\$path)( status)?\1(?: \(Codex\) (?:and|or) (`?)\/(gsd-path(?:-[a-z0-9]+)*|path)( status)?\4 \((?:other hosts|Antigravity\/Zed\/Muse)\))?/g;
   return text.replace(pattern, (_match, quote, token, arguments_, pairedQuote, pairedSkill, pairedArguments) => {
     const skill = token.slice(1);
     const argumentsText = arguments_ || "";
@@ -237,7 +238,7 @@ function sharedInvocations(text) {
     }
     const codex = `${MANIFEST.hosts.codex.invocation_prefix}${skill}`;
     const others = `${MANIFEST.hosts.antigravity.invocation_prefix}${skill}`;
-    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed)`;
+    return `${quote}${codex}${argumentsText}${quote} (Codex) or ${quote}${others}${argumentsText}${quote} (Antigravity/Zed/Muse)`;
   });
 }
 export function skillNamesForManifest(manifest) {
@@ -355,7 +356,7 @@ export function defaultRoot(target, env = process.env) {
   }
   if (target === "antigravity") return absolutePath("~/.gemini/antigravity-cli/skills");
   if (target === "cursor") return absolutePath("~/.cursor/skills");
-  if (target === "zed") return absolutePath("~/.agents/skills");
+  if (target === "zed" || target === "muse") return absolutePath("~/.agents/skills");
   if (target === "kiro") {
     return absolutePath(path.join(env.KIRO_HOME || expandUser("~/.kiro"), "skills"));
   }
@@ -386,7 +387,9 @@ function isOwnedRouterAlias(skillDir) {
   const versionFile = path.join(skillDir, "VERSION");
   if (!isFile(versionFile)) return isManagedProjectRuntime(runtime); // installs before alias version stamping
   try {
-    return /^[0-9]+(?:\.[0-9]+)+$/.test(fs.readFileSync(versionFile, "utf8").trim());
+    return /^[0-9]+(?:\.[0-9]+)+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(
+      fs.readFileSync(versionFile, "utf8").trim()
+    );
   } catch {
     return false;
   }
@@ -1037,7 +1040,7 @@ async function applyTarget(plan, stagedRoot, transaction) {
     const destination = path.join(plan.root, name);
     hooks.reserveDirectory(destination);
     transaction.installed.push(destination);
-    fs.cpSync(path.join(stagedRoot, name), destination, { recursive: true, errorOnExist: true, force: false });
+    copyIntoReservedDirectory(path.join(stagedRoot, name), destination);
     await tick();
   }
   if (cursorAgent !== null) {
@@ -1051,6 +1054,18 @@ function reserveDirectory(destination) {
   fs.mkdirSync(destination);
 }
 
+// Node 26 rejects recursive cpSync when the destination directory already exists
+// and errorOnExist is set. Reserve the skill directory, then copy each staged entry.
+export function copyIntoReservedDirectory(source, destination) {
+  for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+    fs.cpSync(path.join(source, entry.name), path.join(destination, entry.name), {
+      recursive: true,
+      errorOnExist: true,
+      force: false,
+    });
+  }
+}
+
 function reserveFile(destination) {
   const descriptor = fs.openSync(destination, "wx", 0o644);
   try {
@@ -1192,7 +1207,7 @@ export function deploymentPlans(plans) {
     if (group.length > 1) {
       if (!targets.every((name) => SHARED_AGENT_TARGETS.has(name))) {
         throw new InstallerError(
-          `only Codex, Antigravity, and Zed may share a skills root: ${targets.join(", ")}`
+          `only Codex, Antigravity, Zed, and Muse may share a skills root: ${targets.join(", ")}`
         );
       }
       profile = SHARED_AGENT_PROFILE;
@@ -1545,8 +1560,53 @@ export async function install(sourceRoot, plans, options = {}) {
   return results;
 }
 
+// The desktop app's rule: a VERSION stamp or a SKILL.md that names gsd-path.
+function isInstalledSkill(skillDir) {
+  if (isFile(path.join(skillDir, "VERSION"))) return true;
+  try {
+    return fs.readFileSync(path.join(skillDir, "SKILL.md"), "utf8").includes("gsd-path");
+  } catch {
+    return false;
+  }
+}
+
+// Removes installed skills only. Project contracts and hooks stay.
+export function uninstall(plans, { dryRun = false } = {}) {
+  const found = deploymentPlans(plans).map((plan) => {
+    const owned = [];
+    const kept = [];
+    for (const name of isDirectory(plan.root) ? fs.readdirSync(plan.root).sort() : []) {
+      if (!isManagedName(name)) continue;
+      const entry = path.join(plan.root, name);
+      (isManagedInstallEntry(plan.root, name) && isInstalledSkill(entry) ? owned : kept).push(entry);
+    }
+    const agent = path.join(path.dirname(plan.root), "agents", CURSOR_AGENT_FILENAME);
+    if (plan.profile === "cursor" && isFile(agent)) owned.push(agent);
+    return { label: plan.targets.join("+"), root: plan.root, owned, kept };
+  });
+  const results = [];
+  const ownership = acquireInstallLocks(
+    dryRun ? [] : found.filter(({ owned }) => owned.length).map(({ root }) => root)
+  );
+  try {
+    for (const { label, root, owned, kept } of found) {
+      for (const entry of kept) results.push(`${label}: kept ${entry} (not owned by GSD Path)`);
+      for (const entry of owned) {
+        if (!dryRun) removePath(entry);
+        results.push(`${label}: ${dryRun ? "would remove" : "removed"} ${entry}`);
+      }
+      if (!owned.length) results.push(`${label}: nothing to remove (${root})`);
+    }
+  } catch (error) {
+    throw new InstallerError(`uninstall stopped: ${messageOf(error)}; fix the cause and run it again`);
+  } finally {
+    releaseInstallLocks(ownership.locks, ownership.createdDirectories);
+  }
+  return results;
+}
+
 // Documented project-relative skill roots (verified against each host's
-// official skills docs). Codex, Zed, and Antigravity all discover the
+// official skills docs). Codex, Zed, Muse, and Antigravity all discover the
 // project-level .agents/skills standard directory.
 export function localRoot(target, projectDir) {
   const relative = LOCAL_ROOTS[target];
@@ -1565,10 +1625,16 @@ export function detectInstalls(targets, rootFor) {
   return plans;
 }
 
+const UNINSTALL_CONFLICTS = [
+  "update", "hooks", "hooks-init", "hooks-refresh", "hooks-refresh-full",
+  "runtime-restore", "runtime-upgrade", "runtime-migrate", "doctor", "member-of",
+];
+
 export function parseCli(argv) {
   const options = {
     all: { type: "boolean", default: false },
     update: { type: "boolean", default: false },
+    uninstall: { type: "boolean", default: false },
     "dry-run": { type: "boolean", default: false },
     local: { type: "boolean", default: false },
     project: { type: "string" },
@@ -1655,13 +1721,16 @@ function usage() {
     "Docs: DOCS.md (hub) · QUICK.md (first run) · FULL.md · UPDATE.md\n\n" +
     "usage: gsd-path            (no flags on a terminal opens the interactive wizard)\n" +
     "       gsd-path [--all] [--update] [--local] [--dry-run] [--project PATH]\n" +
-    "              [--hooks] [--hooks-init] [--hooks-refresh] [--hooks-refresh-full] [target flags]\n\n" +
+    "              [--hooks] [--hooks-init] [--hooks-refresh] [--hooks-refresh-full] [target flags]\n" +
+    "       gsd-path --uninstall [--all] [--local] [--dry-run] [target flags]\n\n" +
     "  First install:  gsd-path --all --dry-run && gsd-path --all\n" +
     "  New repo:       gsd-path --all --project /path/to/repo\n" +
     "  Update skills:  gsd-path --update   (or npx @opengsd/gsd-path@latest --update)\n\n" +
     `targets: ${flags}\n` +
     "  --update              refresh existing installs in place; with --project also\n" +
     "                        keeps its selected runtime and project contracts\n" +
+    "  --uninstall           remove installed GSD Path skills from the selected targets;\n" +
+    "                        keeps other skills, host settings, project contracts, and hooks\n" +
     "  --local               install into this project's per-host skill dirs\n" +
     "  --project PATH        write project contracts and status runtime; requires Python 3.9+\n" +
     "  --doctor              read-only health check of installs, hooks, and state\n" +
@@ -1712,6 +1781,20 @@ export async function main(argv, env = process.env) {
     : path.resolve(SCRIPT_DIRECTORY, "..");
   const project =
     values.project !== undefined ? absolutePath(values.project) : null;
+  if (values.uninstall) {
+    const conflicts = UNINSTALL_CONFLICTS.filter((name) => values[name]).map((name) => `--${name}`);
+    if (conflicts.length) {
+      ui.error(`--uninstall cannot be combined with ${conflicts.join(", ")}`);
+      return 2;
+    }
+    if (project !== null) {
+      ui.error(
+        "--uninstall removes installed skills only; project contracts and hooks are not removed " +
+          "(.project/, .gsd-path/, the AGENTS.md block, guard hooks). Run it without --project."
+      );
+      return 2;
+    }
+  }
   const migrateAndUpdate = values["runtime-migrate"] && values.update;
   if (migrateAndUpdate && (project === null || values["runtime-restore"] || values["runtime-upgrade"] || values.doctor || values["hooks-init"] || values["hooks-refresh"] || values["hooks-refresh-full"])) {
     ui.error("--runtime-migrate --update requires --project and cannot be combined with another runtime, doctor, or hook operation");
@@ -1807,7 +1890,10 @@ export async function main(argv, env = process.env) {
     }
   }
   const sourceRootForInstall = sourceRoot;
-  const scope = local ? `project ${values.update ? "update in" : "install into"} ${process.cwd()}` : `global ${values.update ? "update" : "install"}`;
+  const [verb, localVerb] = values.uninstall
+    ? ["uninstall", "uninstall from"]
+    : values.update ? ["update", "update in"] : ["install", "install into"];
+  const scope = local ? `project ${localVerb} ${process.cwd()}` : `global ${verb}`;
   const mode = scope + (values["dry-run"] ? " · dry run" : "");
   ui.banner(mode);
   let plans;
@@ -1840,7 +1926,7 @@ export async function main(argv, env = process.env) {
   }
   const spin = ui.spinner("Preparing");
   try {
-    const results = await install(sourceRootForInstall, plans, {
+    const results = values.uninstall ? uninstall(plans, { dryRun: values["dry-run"] }) : await install(sourceRootForInstall, plans, {
       project,
       dryRun: values["dry-run"],
       env,
@@ -1855,6 +1941,8 @@ export async function main(argv, env = process.env) {
     }
     const closing = values["dry-run"]
       ? "Dry run — nothing was written."
+      : values.uninstall
+        ? "Done. Restart active agent sessions."
       : values.update
         ? "Updated. Previous copies are in each root's disabled-gsd-skills backup."
         : "Done. Restart active agent sessions, then invoke the router explicitly.";

package/scripts/install.py

@@ -124,7 +124,7 @@ STATUS_STATE_FIELDS = frozenset(
         "integration_source",
     }
 )
-STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request"})
+STATUS_INTEGRATION_MODES = frozenset({"direct", "pull-request", "external-landing"})
 STATUS_INTEGRATION_SOURCES = frozenset({"default", "milestone"})
 STATUS_SLUG = re.compile(r"^[a-z0-9][a-z0-9-]*$")
 STATUS_BRANCH = re.compile(r"^gsd-path/M(\d{3,})$")
@@ -220,30 +220,52 @@ def _cursor_guard_entry(interpreter: str) -> dict:
     }
 
 
-def pre_commit_hook(interpreter: str) -> str:
-    return (
-        "#!/bin/sh\n"
-        "# gsd-path guard: archive immutability before commit.\n"
-        f"exec {interpreter} \"$(git rev-parse --show-toplevel)/"
-        f"{HOOKS_DIRECTORY}/git_guard.py\" pre-commit\n"
+CHAINED_HOOK_SUFFIX = ".gsd-path-chained"
+
+
+def _chained_hook_lines(name: str, guard: str) -> List[str]:
+    """Shell lines that run the guard, then the hook that was there before it."""
+    lines = [f'chained="$(dirname "$0")/{name}{CHAINED_HOOK_SUFFIX}"']
+    if name == "pre-push":
+        # Git gives pre-push its ref updates on stdin; both hooks need them.
+        return lines + [
+            "input=$(cat)",
+            '[ -n "$input" ] && input="$input\n"',
+            f'printf %s "$input" | {guard} || exit 1',
+            'if [ -x "$chained" ]; then printf %s "$input" | exec "$chained" "$@"; fi',
+        ]
+    return lines + [f"{guard} || exit 1", 'if [ -x "$chained" ]; then exec "$chained" "$@"; fi']
+
+
+def _git_hook(name: str, purpose: str, arguments: str, interpreter: str, chained: bool) -> str:
+    """chained=True also runs `<hook>.gsd-path-chained`, the user's own hook."""
+    guard = (
+        f"{interpreter} \"$(git rev-parse --show-toplevel)/"
+        f"{HOOKS_DIRECTORY}/git_guard.py\" {name}{arguments}"
     )
+    head = f"#!/bin/sh\n# gsd-path guard: {purpose}\n"
+    if not chained:
+        return f"{head}exec {guard}\n"
+    return head + "\n".join(_chained_hook_lines(name, guard)) + "\n"
 
 
-def commit_msg_hook(interpreter: str) -> str:
-    return (
-        "#!/bin/sh\n"
-        "# gsd-path guard: archive immutability and ship-commit purity.\n"
-        f"exec {interpreter} \"$(git rev-parse --show-toplevel)/"
-        f"{HOOKS_DIRECTORY}/git_guard.py\" commit-msg \"$1\"\n"
+def pre_commit_hook(interpreter: str, chained: bool = False) -> str:
+    return _git_hook(
+        "pre-commit", "archive immutability before commit.", "", interpreter, chained
     )
 
 
-def pre_push_hook(interpreter: str) -> str:
-    return (
-        "#!/bin/sh\n"
-        "# gsd-path guard: bound branches publish only as ship commits.\n"
-        f"exec {interpreter} \"$(git rev-parse --show-toplevel)/"
-        f"{HOOKS_DIRECTORY}/git_guard.py\" pre-push \"$@\"\n"
+def commit_msg_hook(interpreter: str, chained: bool = False) -> str:
+    return _git_hook(
+        "commit-msg", "archive immutability and ship-commit purity.", ' "$1"',
+        interpreter, chained,
+    )
+
+
+def pre_push_hook(interpreter: str, chained: bool = False) -> str:
+    return _git_hook(
+        "pre-push", "bound branches publish only as ship commits.", ' "$@"',
+        interpreter, chained,
     )
 
 
@@ -254,7 +276,6 @@ GIT_HOOKS = (
 )
 GIT_HOOK_NAMES = tuple(name for name, _ in GIT_HOOKS)
 MEMBER_HOOK_MARKER = "gsd-path member guard"
-CHAINED_HOOK_SUFFIX = ".gsd-path-chained"
 
 
 def member_hook(interpreter: str, name: str) -> str:
@@ -271,19 +292,8 @@ def member_hook(interpreter: str, name: str) -> str:
         '  echo "gsd-path guard: member marker is unreadable; run members.py repair --repo <coordinator>" >&2',
         "  exit 1",
         "}",
-        f'chained="$(dirname "$0")/{name}{CHAINED_HOOK_SUFFIX}"',
     ]
-    if name == "pre-push":
-        # Git gives pre-push its ref updates on stdin; both hooks need them.
-        lines += [
-            "input=$(cat)",
-            '[ -n "$input" ] && input="$input\n"',
-            f'printf %s "$input" | {guard} || exit 1',
-            'if [ -x "$chained" ]; then printf %s "$input" | exec "$chained" "$@"; fi',
-        ]
-    else:
-        lines += [f"{guard} || exit 1", 'if [ -x "$chained" ]; then exec "$chained" "$@"; fi']
-    return "\n".join(lines) + "\n"
+    return "\n".join(lines + _chained_hook_lines(name, guard)) + "\n"
 
 
 def install_member_hooks(coordinator: Path, member: Path, dry_run: bool = False) -> List[str]:
@@ -505,9 +515,9 @@ HOST_NOTES = {
     "kiro": KIRO_NOTE,
 }
 EXPLICIT_ONLY_TARGETS = frozenset(
-    {"claude", "grok", "copilot", "qwen", "cursor", "zed", "kimi", "shared-agents"}
+    {"claude", "grok", "copilot", "qwen", "cursor", "zed", "kimi", "muse", "shared-agents"}
 )
-SHARED_AGENT_TARGETS = frozenset({"codex", "antigravity", "zed"})
+SHARED_AGENT_TARGETS = frozenset({"codex", "antigravity", "zed", "muse"})
 SHARED_AGENT_PROFILE = "shared-agents"
 CURSOR_AGENT_FILENAME = "gsd-path.md"
 CURSOR_AGENT_BACKUP_NAME = "cursor-agent-gsd-path.md"
@@ -533,7 +543,7 @@ def _shared_invocations(text: str) -> str:
         others = f"{hosts['antigravity']['invocation_prefix']}{skill}"
         return (
             f"{quote}{codex}{arguments}{quote} (Codex) or "
-            f"{quote}{others}{arguments}{quote} (Antigravity/Zed)"
+            f"{quote}{others}{arguments}{quote} (Antigravity/Zed/Muse)"
         )
 
     return re.sub(
@@ -542,7 +552,7 @@ def _shared_invocations(text: str) -> str:
         r"(?: \(Codex\) (?:and|or) (?P<paired_quote>`?)/"
         r"(?P<paired_skill>gsd-path(?:-[a-z0-9]+)*|path)"
         r"(?P<paired_arguments> status)?(?P=paired_quote)"
-        r" \((?:other hosts|Antigravity/Zed)\))?",
+        r" \((?:other hosts|Antigravity/Zed/Muse)\))?",
         replace,
         text,
     )
@@ -620,7 +630,7 @@ def default_root(target: str, environ: Optional[Mapping[str, str]] = None) -> Pa
         return absolute_path(Path("~/.gemini/antigravity-cli/skills"))
     if target == "cursor":
         return absolute_path(Path("~/.cursor/skills"))
-    if target == "zed":
+    if target in ("zed", "muse"):
         return absolute_path(Path("~/.agents/skills"))
     if target == "kiro":
         return absolute_path(Path(env.get("KIRO_HOME") or "~/.kiro") / "skills")
@@ -656,7 +666,15 @@ def _is_owned_router_alias(skill_dir: Path) -> bool:
         version = version_file.read_text(encoding="utf-8").strip()
     except (OSError, UnicodeError):
         return False
-    return re.fullmatch(r"[0-9]+(?:\.[0-9]+)+", version) is not None
+    return (
+        re.fullmatch(
+            r"[0-9]+(?:\.[0-9]+)+"
+            r"(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?"
+            r"(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?",
+            version,
+        )
+        is not None
+    )
 
 
 def _is_managed_install_entry(root: Path, name: str) -> bool:
@@ -1199,6 +1217,35 @@ def _rollback_target(transaction: TargetTransaction) -> None:
     _remove_empty_directories(transaction.created_directories)
 
 
+def _chained_hook_path(hook: Path) -> Path:
+    return hook.with_name(f"{hook.name}{CHAINED_HOOK_SUFFIX}")
+
+
+def _foreign_git_hook(hook: Path) -> bool:
+    """A regular hook file that no GSD Path installer wrote."""
+    if hook.is_symlink() or not hook.is_file():
+        return False
+    text = hook.read_text(encoding="utf-8", errors="replace")
+    return MEMBER_HOOK_MARKER not in text and not _is_managed_git_hook_content(text)
+
+
+def _require_chainable_git_hook(project: Path, hook: Path) -> None:
+    """A foreign hook is kept as `<hook>.gsd-path-chained` and runs after the guard."""
+    chained = _chained_hook_path(hook)
+    if _lexists(chained):
+        raise InstallerError(f"cannot chain {hook}: {chained} already exists")
+    # ponytail: only the repository's own .git/hooks. A core.hooksPath directory
+    # can be tracked (Husky) or shared by other repositories, so a rename there
+    # reaches other people; chain it when a design for tracked hooks exists.
+    if not _same_path(hook.parent, project / ".git" / "hooks"):
+        raise InstallerError(
+            f"cannot chain {hook}: its hooks directory is not this repository's "
+            ".git/hooks (core.hooksPath or a linked worktree). Rename it to "
+            f"{chained.name} yourself, then rerun: the guard runs it after its own "
+            "check. See HOOKS.md."
+        )
+
+
 def _project_destinations(
     project: Path,
     selected: Sequence[str],
@@ -1260,9 +1307,9 @@ def _project_destinations(
             )
         if hooks_dir is not None:
             for hook_name, generator in GIT_HOOKS:
-                destinations.append(
-                    (hooks_dir / hook_name, None, generator(interpreter), True)
-                )
+                hook = hooks_dir / hook_name
+                chained = _lexists(_chained_hook_path(hook)) or _foreign_git_hook(hook)
+                destinations.append((hook, None, generator(interpreter, chained), True))
     return destinations
 
 
@@ -1664,6 +1711,13 @@ def _validate_project(
             managed = (
                 _update_replacement(project, destination, hooks_dir) if update else None
             )
+            if (
+                hooks_dir is not None
+                and _same_path(destination.parent, hooks_dir)
+                and _foreign_git_hook(destination)
+            ):
+                _require_chainable_git_hook(project, destination)
+                continue
             if destination.is_symlink() or (merge is None and not update):
                 raise _existing_contract_error(destination)
             if merge is not None:
@@ -1710,6 +1764,21 @@ def _apply_project(
             _apply_agents(source_root, destination, transaction)
             continue
         merge = mergers.get(destination)
+        if (
+            hooks_dir is not None
+            and _same_path(destination.parent, hooks_dir)
+            and _foreign_git_hook(destination)
+        ):
+            original = destination.read_bytes()
+            mode = destination.stat().st_mode & 0o777
+            chained = _chained_hook_path(destination)
+            with chained.open("xb") as output:
+                transaction.copied.append(chained)
+                output.write(original)
+            chained.chmod(mode)
+            _atomic_write(destination, (content or "").encode("utf-8"), 0o755)
+            transaction.replaced.append((destination, original, mode))
+            continue
         if _lexists(destination) and not destination.is_symlink():
             replaceable = (
                 update
@@ -2151,7 +2220,9 @@ def _validate_hooks_refresh(
                     raise InstallerError(
                         f"refusing to refresh a symlink: {hook_path}"
                     )
-                if _lexists(hook_path) and not _is_managed_git_hook(hook_path):
+                if _foreign_git_hook(hook_path):
+                    _require_chainable_git_hook(project, hook_path)
+                elif _lexists(hook_path) and not _is_managed_git_hook(hook_path):
                     raise InstallerError(
                         f"not a managed GSD Path git hook: {hook_path}"
                     )
@@ -2259,7 +2330,7 @@ def _deployment_plans(plans: Sequence[TargetPlan]) -> List[DeploymentPlan]:
             if not target_set <= SHARED_AGENT_TARGETS:
                 labels = ", ".join(targets)
                 raise InstallerError(
-                    "only Codex, Antigravity, and Zed may share a skills root: "
+                    "only Codex, Antigravity, Zed, and Muse may share a skills root: "
                     f"{labels}"
                 )
             profile = SHARED_AGENT_PROFILE
@@ -2836,6 +2907,8 @@ def doctor(
     else:
         for name in PROJECT_RUNTIME_SCRIPTS:
             destination = runtime / name
+            if pinned and not _lexists(destination):
+                continue  # a valid older selected runtime lacks helpers added later
             if destination.is_symlink():
                 push("fail", f"project: runtime {name} is a symlink")
                 runtime_current = False
@@ -2995,7 +3068,9 @@ def doctor(
                         if not _is_managed_git_hook_content(hook_text):
                             push("warn", f"hooks: {label} is not a managed GSD Path git hook")
                         elif not any(
-                            hook_text == generator(candidate)
+                            hook_text == generator(
+                                candidate, _lexists(_chained_hook_path(hook_path))
+                            )
                             for candidate in INTERPRETER_CANDIDATES
                         ):
                             push("warn", f"hooks: {label} is stale — run --hooks-refresh-full")
@@ -3275,6 +3350,87 @@ def install(
     return results
 
 
+def _is_installed_skill(skill_dir: Path) -> bool:
+    """The desktop app's rule: a VERSION stamp or a SKILL.md that names gsd-path."""
+    if (skill_dir / "VERSION").is_file():
+        return True
+    try:
+        return "gsd-path" in (skill_dir / "SKILL.md").read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return False
+
+
+def uninstall(plans: Sequence[TargetPlan], dry_run: bool = False) -> List[str]:
+    """Remove installed skills only. Project contracts and hooks stay."""
+    found = []
+    for plan in _deployment_plans(plans):
+        owned, kept = [], []
+        names = sorted(entry.name for entry in plan.root.iterdir()) if plan.root.is_dir() else []
+        for name in names:
+            if not _is_managed_name(name):
+                continue
+            entry = plan.root / name
+            if _is_managed_install_entry(plan.root, name) and _is_installed_skill(entry):
+                owned.append(entry)
+            else:
+                kept.append(entry)
+        agent = plan.root.parent / "agents" / CURSOR_AGENT_FILENAME
+        if plan.profile == "cursor" and agent.is_file():
+            owned.append(agent)
+        found.append(("+".join(plan.targets), plan.root, owned, kept))
+    results = []
+    locks, created = _acquire_install_locks(
+        [] if dry_run else [root for _, root, owned, _ in found if owned]
+    )
+    try:
+        for label, root, owned, kept in found:
+            results.extend(f"{label}: kept {entry} (not owned by GSD Path)" for entry in kept)
+            for entry in owned:
+                if not dry_run:
+                    _remove_path(entry)
+                results.append(f"{label}: {'would remove' if dry_run else 'removed'} {entry}")
+            if not owned:
+                results.append(f"{label}: nothing to remove ({root})")
+    except OSError as error:
+        raise InstallerError(
+            f"uninstall stopped: {error}; fix the cause and run it again"
+        ) from error
+    finally:
+        _release_install_locks(locks, created)
+    return results
+
+
+def _runtime_provenance(arguments, source_root: Path):
+    """Owner-recorded provenance from --runtime-provenance-* upgrade flags.
+
+    When the supplied source root is a git checkout and no patch reference
+    was given, its HEAD sha is recorded with one best-effort rev-parse.
+    Provenance is display/audit metadata on the runtime declaration only; it
+    never joins the pinned digest or runtime validation.
+    """
+    supplied = (arguments.runtime_provenance_source, arguments.runtime_provenance_patch,
+                arguments.runtime_provenance_note)
+    recorded = {key: value for key, value in zip(runtime_store.PROVENANCE_KEYS, supplied) if value}
+    if not recorded:
+        return None
+    if "patch_ref" not in recorded:
+        try:
+            head = subprocess.run(["git", "rev-parse", "--show-toplevel", "HEAD"], cwd=source_root,
+                                  capture_output=True, encoding="utf-8", check=True)
+            toplevel, _, sha = head.stdout.strip().partition("\n")
+            if sha and Path(toplevel).resolve() == Path(source_root).resolve():
+                recorded["patch_ref"] = sha
+        except (OSError, subprocess.CalledProcessError):
+            pass
+    return recorded
+
+
+UNINSTALL_CONFLICTS = (
+    "update", "hooks", "hooks-init", "hooks-refresh", "hooks-refresh-full",
+    "runtime-restore", "runtime-upgrade", "runtime-migrate", "doctor", "member-of",
+)
+
+
 def parser() -> argparse.ArgumentParser:
     argument_parser = argparse.ArgumentParser(description=__doc__)
     for target in TARGETS:
@@ -3283,6 +3439,12 @@ def parser() -> argparse.ArgumentParser:
     argument_parser.add_argument("--adapter-request", action="store_true", help=argparse.SUPPRESS)
     argument_parser.add_argument("--all", action="store_true", dest="all_targets")
     argument_parser.add_argument("--update", action="store_true")
+    argument_parser.add_argument(
+        "--uninstall",
+        action="store_true",
+        help="remove installed GSD Path skills from the selected targets; "
+        "keeps other skills, host settings, project contracts, and hooks",
+    )
     argument_parser.add_argument("--local", action="store_true")
     argument_parser.add_argument("--dry-run", action="store_true")
     argument_parser.add_argument("--project", type=Path)
@@ -3291,6 +3453,9 @@ def parser() -> argparse.ArgumentParser:
     runtime_actions = argument_parser.add_mutually_exclusive_group()
     for action in ("restore", "upgrade", "migrate"):
         runtime_actions.add_argument(f"--runtime-{action}", action="store_true")
+    argument_parser.add_argument("--runtime-provenance-source")
+    argument_parser.add_argument("--runtime-provenance-patch")
+    argument_parser.add_argument("--runtime-provenance-note")
     argument_parser.add_argument("--hooks", action="store_true")
     argument_parser.add_argument("--hooks-init", action="store_true")
     argument_parser.add_argument("--hooks-refresh", action="store_true")
@@ -3334,8 +3499,27 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
     project = (
         absolute_path(arguments.project) if arguments.project is not None else None
     )
+    if arguments.uninstall:
+        conflicts = [
+            f"--{name}" for name in UNINSTALL_CONFLICTS
+            if getattr(arguments, name.replace("-", "_"))
+        ]
+        if conflicts:
+            print(f"error: --uninstall cannot be combined with {', '.join(conflicts)}", file=sys.stderr)
+            return 2
+        if project is not None:
+            print(
+                "error: --uninstall removes installed skills only; project contracts and hooks "
+                "are not removed (.project/, .gsd-path/, the AGENTS.md block, guard hooks). "
+                "Run it without --project.",
+                file=sys.stderr,
+            )
+            return 2
     runtime_action = next((action for action in ("restore", "upgrade", "migrate")
                            if getattr(arguments, "runtime_" + action)), None)
+    provenance = _runtime_provenance(arguments, source_root)
+    if provenance is not None and runtime_action != "upgrade":
+        argument_parser.error("--runtime-provenance-* requires --runtime-upgrade")
     if runtime_action:
         if project is None:
             argument_parser.error(f"--runtime-{runtime_action} requires --project")
@@ -3343,7 +3527,8 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
             _validate_project_git_root(project)
             locks, created = ([], []) if arguments.dry_run else _acquire_install_locks([project / HOOKS_DIRECTORY])
             try:
-                pin = runtime_store.operate(source_root, project, runtime_action, dry_run=arguments.dry_run)
+                pin = runtime_store.operate(source_root, project, runtime_action,
+                                            dry_run=arguments.dry_run, provenance=provenance)
             finally:
                 _release_install_locks(locks, created)
             print(f"runtime: {runtime_action} {pin['version']} ({pin['digest']})"
@@ -3477,7 +3662,7 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         )
         return 1
     try:
-        for result in install(
+        for result in uninstall(plans, arguments.dry_run) if arguments.uninstall else install(
             source_root,
             plans,
             project,