@klhapp/skillmux 1.11.1 → 1.11.2

package/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.11.2](https://github.com/klhq/skillmux/compare/v1.11.1...v1.11.2) (2026-09-05)
+
+
+### Added
+
+* **target:** add built-in target migration ([#189](https://github.com/klhq/skillmux/issues/189)) ([fe85951](https://github.com/klhq/skillmux/commit/fe85951f1728907ce0faa9fe5df79677ea278973))
+* **target:** add safe marker rehome workflow ([#187](https://github.com/klhq/skillmux/issues/187)) ([b8601aa](https://github.com/klhq/skillmux/commit/b8601aa9dc81d2c4a882c6d810d9922ba596e701))
+
+
+### Chores
+
+* **release:** force version 1.11.2 ([1ee9cbc](https://github.com/klhq/skillmux/commit/1ee9cbcfbfcbd9650f8e7f2d2dbbd54cdb0777ac))
+
 ## [1.11.1](https://github.com/klhq/skillmux/compare/v1.11.0...v1.11.1) (2026-09-03)
 
 

package/docs/configuration.md

@@ -291,7 +291,6 @@ paths = ["/Users/you/code/repo1"]    # only synced for paths that exist locally
 skills = ["pdf-extractor"]           # must not overlap [core]
 
 [targets.claude-code]
-dir = "/Users/you/.claude/skills"
 host = "workhorse"                    # optional; init adds the current hostname
 project_groups = ["repo1"]           # which [project.*] groups materialize into this target; [] means none
 ```
@@ -299,7 +298,7 @@ project_groups = ["repo1"]           # which [project.*] groups materialize into
 - `[core].skills`: symlinked into every `[targets.*]` dir on `sync`. Capped at 25 skills; `sync` fails if a listed skill id isn't actually in the vault.
 - `[project.<group>].skills`: symlinked only into `<path>/<relative path from $HOME to the target dir>`, for each `paths` entry, and only for targets whose `project_groups` names that group. `paths` entries must resolve under `$HOME` (that's how the pin path is derived). A skill can't appear in both `[core]` and the same `[project.*]` group.
 - `[project.<group>].paths` can list the same project's checkout on more than one machine (e.g. `["/home/alice/code/repo1", "/Users/alice/code/repo1"]`). `sync` silently skips any entry that doesn't exist on the machine it's running on (see below), so one shared manifest can span machines with different checkout locations without needing per-machine manifests.
-- `[targets.<name>]`: one entry per adopted surface. `skillmux init --agent <name> --yes` writes these for each supported agent and scopes newly added targets to the current hostname; `skillmux target add <name> --dir <dir> --yes` writes one directly for a directory not tied to any supported agent. Hand-editing is fine as long as `sync` is still allowed to own the directory (see below). An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
+- `[targets.<name>]`: one entry per adopted surface. Built-in names (`agent-skills`, `claude-code`, and `codex`) derive their directories from the name and omit `dir`. A custom target requires `dir`; create one with `skillmux target add <name> --dir <dir> --yes`. `skillmux target migrate --yes` removes legacy built-in `dir` fields without touching target files. An optional `host` limits the target to an exact machine-hostname match; omit it for a global, backward-compatible target. A host mismatch is reported and skipped before any target filesystem operation. `project_groups` is an explicit list, not a boolean: a target only receives the specific groups it names, never every group in the manifest.
 
 **Pin/unpin without hand-editing.** `skillmux core pin`/`unpin` mutate `[core]` for you, and `skillmux project pin`/`unpin` mutate `[project.*]`, validating with the same rules `sync` enforces (skill must resolve from `vault_path`, no duplicate pins, `[core]` stays under the 25-skill cap) before writing anything:
 

package/docs/skill-management.md

@@ -298,6 +298,21 @@ command surface and route table.
 `skillmux target remove <name> --yes` removes the manifest record and preserves
 the target directory, marker, and files. Cleanup stays under your control.
 
+Built-in targets (`agent-skills`, `claude-code`, and `codex`) resolve their
+native directories from their names. Their manifest entries store only host and
+project-group configuration. Custom targets retain an explicit `dir`. To remove
+legacy built-in `dir` fields without changing any target files, run
+`skillmux target migrate --dry-run` and then `skillmux target migrate --yes`.
+
+When a managed target's marker still names a previous vault checkout after a
+vault move, use `skillmux target rehome <name> --yes`. It validates every
+recorded managed symlink in the target and its existing project pins before
+updating their `.skillmux` markers to the configured `vault_path`. Use
+`--dry-run` first to inspect the marker paths. Rehome never creates or removes
+skill links. It retargets a link only when it resolves exactly to the previous
+`vault_path` recorded in its marker, and it refuses legacy markers or any link
+that cannot be proven to belong to either the previous or configured vault.
+
 Restore a managed target to one symlink that exposes the full vault:
 
 ```sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.11.1",
+  "version": "1.11.2",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/cli.ts

@@ -651,6 +651,8 @@ usage:
   skillmux target show <name>
   skillmux target add <name> [--dir <dir>] --yes
   skillmux target remove <name> --yes
+  skillmux target rehome <name> --yes
+  skillmux target migrate --yes
 
 --dir may be omitted when <name> is a built-in target with a deterministic
 path: agent-skills, claude-code, codex. Any other <name> requires --dir.
@@ -803,7 +805,7 @@ Setup:
                 [--agent <name>...] [--target <name>...] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
   skillmux project <list|show|add-path|remove-path|pin|unpin|attach|detach>
-  skillmux target <list|show|add|remove>  (a target is a directory sync writes into)
+  skillmux target <list|show|add|remove|rehome|migrate>  (a target is a directory sync writes into)
   skillmux core <pin|unpin> <skill_id>... [--yes] [--dry-run] [--json]
   skillmux skill which <skill_id>  (local vault shadow resolution; unrelated to MCP routing)
   skillmux config init --vault <path> --yes

package/src/commands/project.ts

@@ -14,6 +14,7 @@ import {
   updateProjectTargets,
   upsertProject,
   validateManifest,
+  resolveTargetDir,
   writeManifestAtomic,
 } from "../manifest";
 import {
@@ -51,7 +52,7 @@ export function configuredTargetForSurface(
 ): string | undefined {
   if (manifest.targets[surface.targetName]) return surface.targetName;
   return Object.entries(manifest.targets).find(
-    ([, target]) => expandHome(target.dir) === surface.path,
+    ([name, target]) => resolveTargetDir(name, target) === surface.path,
   )?.[0];
 }
 
@@ -325,7 +326,10 @@ export async function runProject(
     // agent-skills) — show the resolved directory, not just the target name,
     // so it's clear at confirmation time which physical folder this affects.
     const targetDirs = Object.fromEntries(
-      targets.map((t) => [t, manifest.targets[t]?.dir ?? "(unknown)"]),
+      targets.map((t) => {
+        const target = manifest.targets[t];
+        return [t, target ? resolveTargetDir(t, target) : "(unknown)"];
+      }),
     );
     const targetsDisplay = targets
       .map((t) => `${t} (${targetDirs[t]})`)

package/src/commands/sync.ts

@@ -5,6 +5,7 @@ import {
   parseManifest,
   resolveManifestPath,
   validateManifest,
+  resolveTargetDir,
 } from "../manifest";
 import { emitSuccess, isInteractive, warn } from "../output";
 import {
@@ -129,7 +130,7 @@ export async function runSync(args: string[]): Promise<void> {
       targetSummaries.push({ target: targetName, status: "skipped_host_mismatch" });
       continue;
     }
-    const targetDir = expandHome(target.dir);
+    const targetDir = resolveTargetDir(targetName, target);
 
     if (restoreMonolith) {
       const result = restoreMonolithTarget(targetDir, vaultPath);

package/src/commands/target.ts

@@ -1,3 +1,5 @@
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
 import { expandHome } from "../config";
 import {
   BUILT_IN_TARGET_NAMES,
@@ -6,8 +8,9 @@ import {
   SUPPORTED_AGENT_IDS,
 } from "../init-agents";
 import { planInitManifest, applyInit } from "../init";
-import { writeManifestAtomic } from "../manifest";
+import { resolveTargetDir, writeManifestAtomic } from "../manifest";
 import { emitSuccess, unknownSubcommandError } from "../output";
+import { applyTargetMarkerRehome, planTargetMarkerRehome, resolveProjectPinDir } from "../sync";
 import { confirmIfNeeded, loadManifestContext } from "./shared";
 
 export async function runTarget(
@@ -15,7 +18,7 @@ export async function runTarget(
   args: string[],
   options: { isJson: boolean; dryRun: boolean },
 ): Promise<void> {
-  const { vaultPath, manifestPath, manifest } = await loadManifestContext();
+  const { config, vaultPath, manifestPath, manifest } = await loadManifestContext();
 
   if (subCommand === "list" || subCommand === "show") {
     const names =
@@ -27,9 +30,9 @@ export async function runTarget(
       const target = manifest.targets[name]!;
       const agents = SUPPORTED_AGENT_IDS.filter((agent) => {
         const surface = planAgentSurfaces([agent]).surfaces[0];
-        return surface !== undefined && surface.path === expandHome(target.dir);
+        return surface !== undefined && surface.path === resolveTargetDir(name, target);
       });
-      return { name, ...target, agents };
+      return { name, ...target, dir: resolveTargetDir(name, target), agents };
     });
     emitSuccess({ isJson: options.isJson }, { targets }, () => {
       if (targets.length === 0) {
@@ -106,7 +109,7 @@ export async function runTarget(
     if (options.dryRun) {
       emitSuccess(
         { isJson: options.isJson },
-        { name, preserved_dir: manifest.targets[name]!.dir },
+        { name, preserved_dir: resolveTargetDir(name, manifest.targets[name]!) },
         () => console.log(`target remove: ${name} (files preserved, dry-run)`),
       );
       return;
@@ -122,7 +125,7 @@ export async function runTarget(
     )
       return;
     const targets = { ...manifest.targets };
-    const removedDir = manifest.targets[name]!.dir;
+    const removedDir = resolveTargetDir(name, manifest.targets[name]!);
     delete targets[name];
     writeManifestAtomic(manifestPath, { ...manifest, targets });
     emitSuccess(
@@ -136,5 +139,87 @@ export async function runTarget(
     return;
   }
 
-  throw unknownSubcommandError("target", subCommand, ["list", "show", "add", "remove"]);
+  if (subCommand === "rehome") {
+    const name = args[0];
+    const target = name ? manifest.targets[name] : undefined;
+    if (!name || !target) {
+      throw new Error(name ? `target "${name}" does not exist` : "usage: skillmux target rehome <name> --yes");
+    }
+    if (target.host !== undefined && target.host !== hostname()) {
+      throw new Error(`target "${name}" is scoped to host ${target.host}, not ${hostname()}`);
+    }
+
+    const targetDir = resolveTargetDir(name, target);
+    if (!existsSync(targetDir)) throw new Error(`target "${name}" directory does not exist: ${targetDir}`);
+    const dirs = [targetDir];
+    for (const groupName of target.project_groups) {
+      const group = manifest.project?.[groupName];
+      if (!group) continue;
+      for (const projectPath of group.paths) {
+        if (!existsSync(projectPath)) continue;
+        const pinDir = resolveProjectPinDir(targetDir, projectPath);
+        if (existsSync(pinDir)) dirs.push(pinDir);
+      }
+    }
+    const plans = dirs.map((dir) =>
+      planTargetMarkerRehome(dir, name, vaultPath, config.local_vault_paths.map(expandHome)),
+    );
+    const markerPaths = plans.map((plan) => plan.markerPath);
+    if (options.dryRun) {
+      emitSuccess(
+        { isJson: options.isJson },
+        { name, marker_paths: markerPaths },
+        () => console.log(`target rehome: ${name} (${markerPaths.length} markers, dry-run)`),
+      );
+      return;
+    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: args.includes("--yes"),
+        isJson: options.isJson,
+        prompt: `rehome ${markerPaths.length} ${name} marker(s) to ${vaultPath}?`,
+        nonInteractiveError: "skillmux target rehome requires --yes when run non-interactively",
+      }))
+    )
+      return;
+    applyTargetMarkerRehome(plans, vaultPath);
+    emitSuccess(
+      { isJson: options.isJson },
+      { name, marker_paths: markerPaths },
+      () => console.log(`target "${name}" rehomed ${markerPaths.length} marker(s) to ${vaultPath}`),
+    );
+    return;
+  }
+
+  if (subCommand === "migrate") {
+    const builtInTargets = Object.entries(manifest.targets).filter(([name]) =>
+      BUILT_IN_TARGET_NAMES.has(name),
+    );
+    if (options.dryRun) {
+      emitSuccess(
+        { isJson: options.isJson },
+        { migrated_targets: builtInTargets.map(([name]) => name) },
+        () => console.log(`target migrate: ${builtInTargets.length} built-in target(s) (dry-run)`),
+      );
+      return;
+    }
+    if (
+      !(await confirmIfNeeded({
+        confirmed: args.includes("--yes"),
+        isJson: options.isJson,
+        prompt: `remove redundant dir fields from ${builtInTargets.length} built-in target(s)?`,
+        nonInteractiveError: "skillmux target migrate requires --yes when run non-interactively",
+      }))
+    )
+      return;
+    writeManifestAtomic(manifestPath, manifest);
+    emitSuccess(
+      { isJson: options.isJson },
+      { migrated_targets: builtInTargets.map(([name]) => name) },
+      () => console.log(`target migrate: normalized ${builtInTargets.length} built-in target(s)`),
+    );
+    return;
+  }
+
+  throw unknownSubcommandError("target", subCommand, ["list", "show", "add", "remove", "rehome", "migrate"]);
 }

package/src/completions.ts

@@ -138,7 +138,7 @@ ${commands}
     elif [[ "$words[2]" == "eval" && CURRENT == 3 ]]; then
         _values 'eval command' promote
     elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
-        _values 'target command' list show add remove
+        _values 'target command' list show add remove rehome migrate
     elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
         _values 'skill command' which
     elif [[ "$words[2]" == "core" && CURRENT == 3 ]]; then
@@ -185,7 +185,7 @@ complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subco
 complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l dry-run -d "Print the plan without writing"
 complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l yes -d "Apply without prompts"
 complete -c skillmux -n "__fish_seen_subcommand_from eval; and __fish_seen_subcommand_from promote" -l json -d "Emit a JSON envelope"
-complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
+complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove rehome migrate" -d "Manage targets"
 complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
 complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"
 complete -c skillmux -n "__fish_seen_subcommand_from local-vault" -a "init" -d "Initialize a local_vault_paths marker"

package/src/init.ts

@@ -22,6 +22,7 @@ import {
   CORE_SKILL_LIMIT,
   MANIFEST_FILENAME,
 } from "./manifest";
+import { BUILT_IN_TARGET_NAMES } from "./init-agents";
 import {
   adoptTarget,
   preflightAdoptTarget,
@@ -244,9 +245,13 @@ export function planInitManifest(
           const existingTarget = existingManifest.targets[target.name];
           return [
             target.name,
-            existingTarget
-              ? { ...existingTarget, dir: target.dir }
-              : { dir: target.dir, host: hostname(), project_groups: [] },
+            BUILT_IN_TARGET_NAMES.has(target.name)
+              ? existingTarget
+                ? { ...existingTarget, dir: undefined }
+                : { host: hostname(), project_groups: [] }
+              : existingTarget
+                ? { ...existingTarget, dir: target.dir }
+                : { dir: target.dir, host: hostname(), project_groups: [] },
           ];
         }),
       ),

package/src/manifest.ts

@@ -2,6 +2,7 @@ import { existsSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { expandHome } from "./config";
+import { BUILT_IN_TARGET_NAMES, resolveBuiltInTarget } from "./init-agents";
 import { resolveSkillRoot, SKILL_ID_PATTERN } from "./vault";
 
 export const MANIFEST_FILENAME = "skillmux.toml";
@@ -24,7 +25,7 @@ const projectGroupSchema = z.object({
 }).strict();
 
 const targetSchema = z.object({
-  dir: z.string().min(1),
+  dir: z.string().min(1).optional(),
   host: z.string().min(1).optional(),
   project_groups: z.array(groupNameSchema).default([]),
 }).strict();
@@ -39,10 +40,31 @@ export type ProjectGroup = z.infer<typeof projectGroupSchema>;
 export type Target = z.infer<typeof targetSchema>;
 export type Manifest = z.infer<typeof manifestSchema>;
 
+export function resolveTargetDir(
+  name: string,
+  target: Target,
+  options: { home?: string; codexHome?: string } = {},
+): string {
+  if (BUILT_IN_TARGET_NAMES.has(name)) {
+    return resolveBuiltInTarget(name, {
+      ...options,
+      codexHome: options.codexHome ?? (process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined),
+    }).path;
+  }
+  if (!target.dir) throw new Error(`[targets.${name}] requires dir for a custom target`);
+  return expandHome(target.dir);
+}
+
 export function parseManifest(toml: string): Manifest {
   const parsed = Bun.TOML.parse(toml) as Record<string, unknown>;
   try {
-    return manifestSchema.parse(parsed);
+    const manifest = manifestSchema.parse(parsed);
+    for (const [name, target] of Object.entries(manifest.targets)) {
+      if (!BUILT_IN_TARGET_NAMES.has(name) && !target.dir) {
+        throw new Error(`[targets.${name}] requires dir for a custom target`);
+      }
+    }
+    return manifest;
   } catch (error) {
     if (error instanceof z.ZodError) {
       for (const issue of error.issues) {
@@ -85,9 +107,10 @@ export function serializeManifest(manifest: Manifest): string {
   }
 
   for (const [name, target] of Object.entries(manifest.targets)) {
+    const dir = BUILT_IN_TARGET_NAMES.has(name) ? "" : `\ndir = ${JSON.stringify(target.dir)}`;
     const host = target.host ? `\nhost = ${JSON.stringify(target.host)}` : "";
     sections.push(
-      `[targets.${name}]\ndir = ${JSON.stringify(target.dir)}${host}\nproject_groups = ${tomlStringArray(target.project_groups)}`,
+      `[targets.${name}]${dir}${host}\nproject_groups = ${tomlStringArray(target.project_groups)}`,
     );
   }
 

package/src/sync.ts

@@ -1,6 +1,20 @@
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
 import { homedir } from "node:os";
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { findSymlinks } from "./install";
 import { resolveSkillRoot } from "./vault";
 
@@ -76,7 +90,29 @@ function writeTargetMarker(
   const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
   const serialized = JSON.stringify(marker, null, 2);
   if (!existsSync(markerPath) || readFileSync(markerPath, "utf-8") !== serialized) {
-    writeFileSync(markerPath, serialized);
+    writeFileAtomic(markerPath, serialized);
+  }
+}
+
+function writeFileAtomic(path: string, contents: string): void {
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, contents);
+    renameSync(temporaryPath, path);
+  } catch (error) {
+    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
+    throw error;
+  }
+}
+
+function replaceSymlinkAtomic(path: string, target: string): void {
+  const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    symlinkSync(target, temporaryPath);
+    renameSync(temporaryPath, path);
+  } catch (error) {
+    if (existsSync(temporaryPath)) unlinkSync(temporaryPath);
+    throw error;
   }
 }
 
@@ -227,6 +263,102 @@ export function preflightAdoptTarget(dir: string, targetName: string, vaultPath:
   }
 }
 
+export interface TargetMarkerRehomePlan {
+  dir: string;
+  markerPath: string;
+  marker: SkillmuxMarker;
+  links: TargetLinkRehomePlan[];
+}
+
+interface TargetLinkRehomePlan {
+  entryPath: string;
+  previousTarget: string;
+  nextTarget: string;
+}
+
+/**
+ * Proves every managed entry resolves either to its active source or exactly to
+ * the vault recorded in its marker. Only the latter links are re-pointed.
+ */
+export function planTargetMarkerRehome(
+  dir: string,
+  targetName: string,
+  vaultPath: string,
+  localVaultPaths: string[] = [],
+): TargetMarkerRehomePlan {
+  const markerPath = join(dir, SKILLMUX_MARKER_FILENAME);
+  if (!existsSync(markerPath)) {
+    throw new Error(`${dir} has a legacy marker; rehome requires .skillmux ownership`);
+  }
+  const marker = readSkillmuxMarker(dir);
+  if (!marker) throw new Error(`${dir} is not owned by skillmux`);
+  if (marker.role !== "target") throw new Error(`${dir} has a local_vault marker, not target ownership`);
+  if (marker.schema_version !== 1) {
+    throw new Error(`${dir} has a legacy marker; rehome requires schema_version 1`);
+  }
+  if (marker.target !== targetName) {
+    throw new Error(`${dir} is owned by target "${marker.target}", not "${targetName}"`);
+  }
+
+  const links: TargetLinkRehomePlan[] = [];
+  for (const skillId of marker.managed_entries ?? []) {
+    if (basename(skillId) !== skillId) {
+      throw new Error(`${dir} marker has an invalid managed entry "${skillId}"`);
+    }
+    const entryPath = join(dir, skillId);
+    if (!lstatSync(entryPath).isSymbolicLink()) {
+      throw new Error(`${entryPath} is not the managed symlink recorded by ${dir}`);
+    }
+    const sourceRoot = resolveSkillRoot(skillId, vaultPath, localVaultPaths) ?? vaultPath;
+    const expectedPath = join(sourceRoot, skillId);
+    if (!existsSync(expectedPath)) {
+      throw new Error(`${entryPath} cannot be proven to resolve from the configured vault's ${skillId}`);
+    }
+    const resolvedEntryPath = realpathSync(entryPath);
+    if (resolvedEntryPath === realpathSync(expectedPath)) continue;
+
+    const previousPath = join(marker.vault_path!, skillId);
+    if (!existsSync(previousPath) || resolvedEntryPath !== realpathSync(previousPath)) {
+      throw new Error(`${entryPath} does not resolve to the configured vault's ${skillId}`);
+    }
+    links.push({ entryPath, previousTarget: readlinkSync(entryPath), nextTarget: expectedPath });
+  }
+
+  return { dir, markerPath, marker, links };
+}
+
+/** Applies only preflighted rehome plans. All plans are validated before the first write. */
+export function applyTargetMarkerRehome(plans: TargetMarkerRehomePlan[], vaultPath: string): void {
+  const completedLinks: TargetLinkRehomePlan[] = [];
+  const completedMarkers: TargetMarkerRehomePlan[] = [];
+  try {
+    for (const plan of plans) {
+      for (const link of plan.links) {
+        replaceSymlinkAtomic(link.entryPath, link.nextTarget);
+        completedLinks.push(link);
+      }
+    }
+    for (const plan of plans) {
+      writeTargetMarker(
+        plan.dir,
+        plan.marker.target!,
+        vaultPath,
+        plan.marker.managed_entries ?? [],
+        plan.marker.created_at,
+      );
+      completedMarkers.push(plan);
+    }
+  } catch (error) {
+    for (const plan of completedMarkers.reverse()) {
+      writeFileAtomic(plan.markerPath, JSON.stringify(plan.marker, null, 2));
+    }
+    for (const link of completedLinks.reverse()) {
+      replaceSymlinkAtomic(link.entryPath, link.previousTarget);
+    }
+    throw error;
+  }
+}
+
 /**
  * Marks an existing directory as skillmux-owned without touching its content —
  * the consented, one-time adoption skillmux init performs (see SkillmuxMarker in