@klhapp/skillmux 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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)
+
+
+### Added
+
+* **cli:** install asks before writing to the vault ([#185](https://github.com/klhq/skillmux/issues/185)) ([7f12d02](https://github.com/klhq/skillmux/commit/7f12d02def0f306d963d37920f2407c8cffe1c04))
+
+
+### Fixed
+
+* **cli:** reject full-vault agents on project attach, clarify agent vs target ([#184](https://github.com/klhq/skillmux/issues/184)) ([118aff5](https://github.com/klhq/skillmux/commit/118aff5f46fb9e83c8c0e068890b96fe0a02311d))
+* **security:** gate install/update on scan findings, plus CLI help cleanup ([#182](https://github.com/klhq/skillmux/issues/182)) ([daffd8a](https://github.com/klhq/skillmux/commit/daffd8af89ebee1fbd4c05870c328baf747bbea3))
+
 ## [1.11.0](https://github.com/klhq/skillmux/compare/v1.10.0...v1.11.0) (2026-09-02)
 
 

package/README.md

@@ -207,7 +207,14 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
-Skillmux validates `SKILL.md` and scans candidate content before copying it into the vault. Use `--fail-on low|medium|high` to turn selected findings into an install gate.
+Skillmux validates `SKILL.md` and scans candidate content before copying it
+into the vault, then asks before writing. Pass `--yes` to approve up front;
+a non-interactive run needs it, because `install` refuses to write unattended.
+
+A high-severity finding aborts the install by default. `--fail-on
+low|medium|high|none` moves that threshold, and it names the lowest severity
+that still aborts, so a lower value is stricter: `low` aborts on low, medium
+and high, while `none` installs despite any finding.
 
 Useful management commands:
 
@@ -260,7 +267,7 @@ Read [MCP routing](docs/mcp-routing.md) for transports, client instructions, ret
 | --- | --- | --- |
 | Claude Code | `~/.claude/skills` | Configure in the agent |
 | Codex | `$CODEX_HOME/skills` or `~/.codex/skills` | Configure in the agent |
-| Gemini CLI, OpenCode, GitHub Copilot, Windsurf | `~/.agents/skills` | Configure in the agent |
+| OpenCode, GitHub Copilot, Windsurf | Shared `~/.agents/skills` | Configure in the agent |
 | Antigravity | `~/.gemini/config/skills` | Configure in the agent |
 | Goose, Hermes | Manual full-vault setup | Manual registration |
 | Custom agents | Any directory through a custom target | Stdio or Streamable HTTP |

package/docs/cli.md

@@ -494,13 +494,20 @@ When `--json` or `SKILLMUX_JSON=true` is set, all output is emitted to `stdout`
 }
 ```
 
-The `context` field identifies the execution context (`"local"` or `{ "name": "<context>", "server": "<url>" }`). The `target` field carries identical content but is deprecated and slated for removal in the next major version; consumers should read `context`.
+The `context` field identifies the execution context (`"local"` or `{ "name": "<context>", "server": "<url>" }`). The `target` field carries identical content but is deprecated; consumers should read `context`. It stays in the payload as a compatibility alias so existing automation keeps parsing, and no removal is planned.
 
 `skillmux init` additionally repeats its payload as deprecated top-level
 `command`, `phase`, `dry_run`, `applied`, `plan`, and `result` keys, which
 predate this envelope. They carry exactly the same content as `data` and are
-kept only so existing automation keeps working. Read `data` instead; the
-duplicated keys will be removed in the next major version.
+kept only so existing automation keeps working. Read `data` instead. The
+duplicated keys stay for the same reason as `target` above, and no removal
+is planned.
+
+`skillmux scan --format json` is the one exception to the envelope. It
+predates this contract and prints a bare `{"scanned": N, "findings": [...]}`
+object instead. It is deprecated and warns on stderr, which leaves stdout
+parseable for existing consumers. Use the global `--json` for anything new,
+and read `data` for the same fields.
 
 ### Exit codes
 

package/docs/concepts.md

@@ -116,9 +116,13 @@ Skillmux maps it to the product's skill directory and safe instruction-file
 conventions.
 
 A **target** is a physical directory managed by sync. Several agents can map
-to one target. Gemini CLI, OpenCode, GitHub Copilot, and Windsurf share
+to one target. OpenCode, GitHub Copilot, and Windsurf share
 `~/.agents/skills`, so Skillmux deduplicates that directory.
 
+The mapping is not total. `goose` and `hermes` use full-vault delivery and
+map to no target at all, so commands that take `--agent` as a stand-in for a
+target reject them.
+
 Custom targets let you manage another directory without adding a product
 adapter:
 

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/getting-started.md

@@ -102,6 +102,10 @@ skillmux install owner/repo
 skillmux install owner/repo/path/to/skill
 ```
 
+`install` scans the skill, shows what it found, and asks before writing to
+the vault. Add `--yes` to approve up front, which a non-interactive run
+requires. See [Managing skills](skill-management.md#install-from-git).
+
 Or create a small skill:
 
 ```sh

package/docs/skill-management.md

@@ -27,20 +27,32 @@ Skillmux clones into a temporary directory, validates the selected skill,
 scans its text files, and copies it to `vault_path`. Existing skill IDs require
 `--force`.
 
-Preview the destination without copying:
+Nothing is written to the vault until you approve it. The scan result prints
+first, then `install` asks for confirmation, so you decide with the findings
+already on screen. Pass `--yes` to approve up front. A non-interactive run
+(no TTY, or `--json`) fails instead of installing unattended, the same way
+`skillmux update` behaves, so scripts and CI must opt in explicitly:
 
 ```sh
-skillmux install owner/repo --dry-run
+skillmux install owner/repo --yes
 ```
 
-Set a scan gate when you want findings to block installation:
+Preview the destination without copying. `--dry-run` writes nothing, so it
+never asks for confirmation:
 
 ```sh
-skillmux install owner/repo --fail-on high
+skillmux install owner/repo --dry-run
 ```
 
 The scanner detects suspicious prompt-injection patterns, secrets, and risky
-instructions. Findings remain advisory unless you pass `--fail-on`.
+instructions. A high-severity finding aborts the install by default. Use
+`--fail-on` to move that threshold, where a lower one is stricter, and
+`--fail-on none` to install despite any finding:
+
+```sh
+skillmux install owner/repo --fail-on low     # also abort on low and medium
+skillmux install owner/repo --fail-on none    # never abort on findings
+```
 
 `install` refuses a `file://` source by default — a `file://` URL reaches the
 local filesystem directly, so honoring one unconditionally would let anything
@@ -74,13 +86,21 @@ Leaving `allowed_hosts` unset (the default) leaves both commands unrestricted.
 ```sh
 skillmux scan
 skillmux scan ~/skills/candidate
-skillmux scan --format json
+skillmux scan --json
 skillmux scan --fail-on medium
 ```
 
 With no path, `scan` checks the configured vault. `--json` wraps the result in
-the standard CLI automation envelope, while `--format json` selects the
-scanner's raw JSON rendering.
+the standard CLI automation envelope.
+
+Unlike `install` and `update`, `scan` has no default threshold: it reports
+what it finds and exits 0 regardless, so adding it to a pipeline never
+changes that pipeline's exit code by itself. Pass `--fail-on` when you want
+it to gate. The value names the lowest severity that still fails, so a lower
+value is stricter.
+
+`--format text|json` is deprecated. It still works, but it prints JSON
+outside the standard envelope and now warns on stderr. Use `--json` instead.
 
 ## Check and pull upstream updates
 
@@ -278,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.0",
+  "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

@@ -543,6 +543,11 @@ usage:
   skillmux config diff
   skillmux config status
 
+config init bootstraps this machine's config file from a populated vault. It
+is not a prerequisite for anything: "skillmux init --vault <path>" runs the
+same bootstrap when no config exists, so reach for config init only when you
+are setting up the config without the guided init.
+
 Accepts --context <name> / --server <url> to target a remote deployment.`,
 
   completions: `completions: generate a shell completion script
@@ -566,7 +571,20 @@ usage:
   sync: `sync: apply the manifest to native agent target directories
 
 usage:
-  skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]`,
+  skillmux sync [--dry-run] [--restore-monolith] [--install-hook] [--yes] [--json]
+
+--dry-run prints what would change without writing. --yes approves creating
+a target directory that does not exist yet; without it, an unseen directory
+is skipped rather than created.
+
+--install-hook installs a git post-merge hook in the vault checkout so a
+"git pull" re-syncs the targets automatically.
+
+--restore-monolith undoes managed-pin delivery for a target: instead of
+individual pinned skills, the target directory is replaced by a single
+symlink to the whole vault. It refuses to touch a directory skillmux does
+not own, one carrying a local_vault marker, or one whose marker points at a
+different vault.`,
 
   init: `init: guided setup for native skill management
 
@@ -608,6 +626,15 @@ usage:
   skillmux project attach <group> (--agent <id>... | --target <name>...) --yes
   skillmux project detach <group> (--agent <id>... | --target <name>...) --yes
 
+--agent and --target both name sync targets, and either may be repeated.
+--target <name> names a target directly, including a custom one created by
+"skillmux target add". --agent <id> is shorthand for "whatever target that
+agent maps to", resolved from the targets init already configured, so it
+fails if that agent was never set up or maps to no target at all (goose and
+hermes use full-vault delivery and have none). Several agents can share one
+target, so attaching two agents that map to the same directory attaches it
+once.
+
 --register-mcp is the project-local counterpart to "skillmux init
 --register-mcp": only for claude-code (the only agent whose own CLI has a
 project MCP scope — codex's mcp add has no scope flag, so it's always
@@ -624,9 +651,16 @@ 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.`,
+path: agent-skills, claude-code, codex. Any other <name> requires --dir.
+
+A target is a directory, not a product. Several agents can map to the same
+one (opencode, github-copilot and windsurf all share agent-skills), which is
+why "skillmux project attach" accepts --agent as shorthand for the target
+that agent resolves to.`,
 
   core: `core: pin or unpin core-tier skills
 
@@ -649,22 +683,60 @@ Accepts --context <name> / --server <url> to prune a remote deployment's audit d
   scan: `scan: check the vault for install-time or integrity issues
 
 usage:
-  skillmux scan [path] [--format text|json] [--fail-on low|medium|high] [--json]`,
+  skillmux scan [path] [--fail-on low|medium|high|none] [--json]
+
+Scans [path], or the configured vault when omitted. Reporting only: it
+exits 0 whatever it finds unless --fail-on names a severity, which is why
+it has no default threshold while install and update default to high.
+
+--format text|json is deprecated: it emits JSON outside the standard
+envelope. Use --json instead; --format will be removed in a future 1.x
+release.`,
 
   install: `install: install a skill from a git source
 
 usage:
-  skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]`,
+  skillmux install <repo>[/path] [--yes] [--force] [--fail-on low|medium|high|none] [--dry-run] [--allow-local-source] [--json]
+
+--yes approves writing the skill into the vault. Without it an interactive
+run asks first, and a non-interactive one (no TTY, or --json) fails rather
+than installing unattended, matching "skillmux update".
+
+The fetched skill is scanned before it is written to the vault. --fail-on
+sets the severity that aborts the install and defaults to high; pass
+--fail-on none to install despite findings. A lower threshold is stricter:
+low aborts on low, medium and high.
+
+--force overwrites a skill that already exists in the vault instead of
+refusing. --dry-run reports where the skill would land without writing.
+--allow-local-source permits a file:// or local path source, which is
+otherwise rejected.`,
 
   outdated: `outdated: list installed skills with a newer upstream version
 
 usage:
-  skillmux outdated [--allow-local-source] [--json]`,
+  skillmux outdated [--allow-local-source] [--json]
+
+Read-only: it reports what "skillmux update" would change and writes
+nothing. --allow-local-source includes skills installed from a local or
+file:// source, which are skipped by default because their upstream is a
+path on this machine rather than a shared remote.`,
 
   update: `update: update one or all skills to their latest source version
 
 usage:
-  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]`,
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high|none] [--json]
+
+Updates every installed skill, or just <skill-id>. --yes is required to
+apply non-interactively. --dry-run prints the plan without writing.
+
+--fail-on works exactly as it does for install and defaults to high, so a
+skill whose new version carries a high-severity finding is skipped rather
+than updated; --fail-on none restores the old permissive behavior.
+
+--force updates a skill whose local content no longer matches the hash
+recorded at install time, which otherwise blocks the update to avoid
+discarding local edits. --allow-local-source permits local/file:// sources.`,
 
   eval: `eval: run retrieval evaluation against the holdout set
 
@@ -725,17 +797,20 @@ See docs/deployment.md for server deployment examples.`);
   console.log(`usage: skillmux <command> [options]
 
 Setup:
-  skillmux config init --vault <path> --yes
   skillmux init [--agent <name>...] [--vault <path>] [--core <skill_id>...]
-                [--migrate-full-vault] [--no-instructions] [--no-sync]
+                [--migrate-full-vault] [--show-mcp-setup] [--register-mcp]
+                [--no-instructions] [--no-sync]
                 [--interactive|--yes|--dry-run] [--json]
   skillmux project init [path] [--name <group>] [--skill <skill_id>...]
                 [--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>
+  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
+                (bootstraps this machine's config on its own; not a
+                prerequisite, since "skillmux init --vault" does the same)
 
 Init agents:
   ${SUPPORTED_AGENT_IDS.join(", ")}
@@ -748,7 +823,7 @@ Operations:
   skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]
   skillmux eval promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]
   skillmux outdated [--allow-local-source] [--json]
-  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high] [--json]
+  skillmux update [skill-id] [--yes] [--dry-run] [--force] [--allow-local-source] [--fail-on low|medium|high|none] [--json]
 
 Commands:
   serve, index, sync, init, project, target, core, report, audit, scan, install, outdated, update,

package/src/commands/init.ts

@@ -144,9 +144,9 @@ interface InitJsonPayload {
  * through the shared handler and needs no bridging.
  *
  * DEPRECATED: the duplicated top-level `command`/`phase`/`dry_run`/`applied`/
- * `plan`/`result` keys should be dropped in the next major version, leaving
- * only the standard envelope. init is local-only, so `target` is always
- * "local".
+ * `plan`/`result` keys are a compatibility alias for `data`. They stay so
+ * existing automation keeps parsing, and no removal is planned. init is
+ * local-only, so `target` is always "local".
  */
 function initJsonEnvelope(payload: InitJsonPayload): string {
   return JSON.stringify({

package/src/commands/install.ts

@@ -14,32 +14,39 @@ import {
 } from "../install";
 import { emitSuccess } from "../output";
 import { hashSkillContent, writeSkillOrigin } from "../provenance";
-import { renderScanText, scanExitCode, type ScanSeverity } from "../scan";
+import {
+  FAIL_ON_USAGE,
+  parseFailOn,
+  renderScanText,
+  resolveMutatingFailOn,
+  scanExitCode,
+  type FailOnOption,
+} from "../scan";
 import { isGlobalFlag } from "../global-flags";
+import { confirmIfNeeded } from "./shared";
 
 function parseInstallArgs(args: string[]): {
   repo?: string;
   force: boolean;
   dryRun: boolean;
-  failOn?: ScanSeverity;
+  failOn?: FailOnOption;
   allowLocalSource: boolean;
+  yes: boolean;
 } {
   let repo: string | undefined;
   let force = false;
   let dryRun = false;
-  let failOn: ScanSeverity | undefined;
+  let failOn: FailOnOption | undefined;
   let allowLocalSource = false;
+  let yes = false;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
     if (option === "--force") force = true;
+    else if (option === "--yes") yes = true;
     else if (option === "--dry-run") dryRun = true;
     else if (option === "--allow-local-source") allowLocalSource = true;
     else if (option === "--fail-on") {
-      const value = args[++i];
-      if (value !== "low" && value !== "medium" && value !== "high") {
-        throw new Error("--fail-on must be low, medium, or high");
-      }
-      failOn = value;
+      failOn = parseFailOn(args[++i]);
     } else if (isGlobalFlag(option, "--json", "--verbose")) {
       // handled globally by main()'s isJson/isVerbose flags; recognized here so they aren't rejected
     } else if (option?.startsWith("--")) {
@@ -50,17 +57,17 @@ function parseInstallArgs(args: string[]): {
       repo = option;
     }
   }
-  return { repo, force, dryRun, failOn, allowLocalSource };
+  return { repo, force, dryRun, failOn, allowLocalSource, yes };
 }
 
 export async function runInstall(
   args: string[],
   options: { isJson: boolean },
 ): Promise<void> {
-  const { repo, force, dryRun, failOn, allowLocalSource } = parseInstallArgs(args);
+  const { repo, force, dryRun, failOn, allowLocalSource, yes } = parseInstallArgs(args);
   if (!repo) {
     throw new Error(
-      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]",
+      `usage: skillmux install <repo>[/path] [--yes] [--force] [--fail-on ${FAIL_ON_USAGE}] [--dry-run] [--allow-local-source] [--json]`,
     );
   }
 
@@ -85,10 +92,16 @@ export async function runInstall(
     );
     if (!options.isJson) console.log(renderScanText({ scanned: 1, findings }));
 
-    if (scanExitCode(findings, failOn) !== 0) {
+    // Defaults to blocking on a high-severity finding. Printing the findings
+    // and installing anyway is the wrong default for the command that pulls
+    // remote content into the vault.
+    const effectiveFailOn = resolveMutatingFailOn(failOn);
+    if (scanExitCode(findings, effectiveFailOn) !== 0) {
       process.exitCode = 1;
       console.error(
-        `aborting install: a finding met the --fail-on ${failOn} threshold`,
+        `aborting install: a finding met the --fail-on ${effectiveFailOn} threshold` +
+          (failOn === undefined ? " (the default)" : "") +
+          `; re-run with --fail-on none to install anyway`,
       );
       return;
     }
@@ -107,6 +120,16 @@ export async function runInstall(
       return;
     }
 
+    // Confirm after the scan, so an interactive user decides with the findings
+    // already on screen, and after the --dry-run return, which writes nothing.
+    const proceed = await confirmIfNeeded({
+      confirmed: yes,
+      isJson: options.isJson,
+      prompt: `install:\n  ${resolved.skillId} <- ${source.url}\n?`,
+      nonInteractiveError: "skillmux install requires --yes when run non-interactively",
+    });
+    if (!proceed) return;
+
     const commit = resolveCloneCommit(cloneDir);
     const targetDir = installIntoVault(
       vaultPath,

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];
 }
 
@@ -59,7 +60,23 @@ function configuredTargetsForAgents(
   manifest: ReturnType<typeof parseManifest>,
   agents: readonly string[],
 ): string[] {
-  return planAgentSurfaces(agents).surfaces.map((surface) => {
+  const plan = planAgentSurfaces(agents);
+
+  // planAgentSurfaces silently drops any agent with no surfaceId, which is how
+  // full-vault agents (goose, hermes) are modelled: they get the whole vault
+  // rather than a sync target directory. Dropping one here used to make
+  // "project attach --agent goose" a successful no-op, so refuse instead.
+  const covered = new Set<string>(plan.surfaces.flatMap((surface) => surface.agents));
+  for (const agent of agents) {
+    if (!covered.has(agent)) {
+      throw new Error(
+        `agent "${agent}" uses full-vault delivery and maps to no sync target; ` +
+          `name a target directly with --target instead`,
+      );
+    }
+  }
+
+  return plan.surfaces.map((surface) => {
     const target = configuredTargetForSurface(manifest, surface);
     if (target) return target;
     const agent = surface.agents[0]!;
@@ -309,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/scan.ts

@@ -1,6 +1,7 @@
 import { expandHome, loadConfig } from "../config";
-import { emitSuccess } from "../output";
+import { emitSuccess, warn } from "../output";
 import {
+  parseFailOn,
   renderScanJson,
   renderScanText,
   scanExitCode,
@@ -12,10 +13,12 @@ import { isGlobalFlag } from "../global-flags";
 function parseScanArgs(args: string[]): {
   path?: string;
   format: "text" | "json";
+  formatExplicit: boolean;
   failOn?: ScanSeverity;
 } {
   let path: string | undefined;
   let format: "text" | "json" = "text";
+  let formatExplicit = false;
   let failOn: ScanSeverity | undefined;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
@@ -24,12 +27,13 @@ function parseScanArgs(args: string[]): {
       if (value !== "text" && value !== "json")
         throw new Error("--format must be text or json");
       format = value;
+      formatExplicit = true;
     } else if (option === "--fail-on") {
-      const value = args[++i];
-      if (value !== "low" && value !== "medium" && value !== "high") {
-        throw new Error("--fail-on must be low, medium, or high");
-      }
-      failOn = value;
+      // scan accepts "none" for symmetry with install/update, where it is the
+      // opt-out. Here it is already the default: scan reports, and the caller
+      // opts into a non-zero exit code.
+      const parsed = parseFailOn(args[++i]);
+      failOn = parsed === "none" ? undefined : parsed;
     } else if (isGlobalFlag(option, "--json")) {
       // handled globally by main()'s isJson flag; recognized here so it isn't rejected
     } else if (option?.startsWith("--")) {
@@ -40,14 +44,20 @@ function parseScanArgs(args: string[]): {
       path = option;
     }
   }
-  return { path, format, failOn };
+  return { path, format, formatExplicit, failOn };
 }
 
 export async function runScan(
   args: string[],
   options: { isJson: boolean },
 ): Promise<void> {
-  const { path, format, failOn } = parseScanArgs(args);
+  const { path, format, formatExplicit, failOn } = parseScanArgs(args);
+  if (formatExplicit) {
+    // --format predates the shared --json envelope and is the last command
+    // flag that emits JSON outside it. Kept working for existing callers;
+    // the warning goes to stderr so stdout stays machine-parseable.
+    warn("--format is deprecated and will be removed in a future 1.x release; use --json instead");
+  }
   const rootPath = path
     ? expandHome(path)
     : expandHome((await loadConfig()).vault_path);

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/commands/update.ts

@@ -14,7 +14,15 @@ import {
 import { emitSuccess } from "../output";
 import { hashSkillContent, readSkillOrigin, writeSkillOrigin } from "../provenance";
 import type { SkillOrigin } from "../provenance";
-import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
+import {
+  FAIL_ON_USAGE,
+  parseFailOn,
+  resolveMutatingFailOn,
+  scanExitCode,
+  type FailOnOption,
+  type ScanFinding,
+  type ScanSeverity,
+} from "../scan";
 import { SKILL_ID_PATTERN } from "../vault";
 import { confirmIfNeeded } from "./shared";
 import { checkOutdated } from "./outdated";
@@ -175,14 +183,14 @@ function parseUpdateArgs(args: string[]): {
   yes: boolean;
   dryRun: boolean;
   force: boolean;
-  failOn?: ScanSeverity;
+  failOn?: FailOnOption;
   allowLocalSource: boolean;
 } {
   let skillId: string | undefined;
   let yes = false;
   let dryRun = false;
   let force = false;
-  let failOn: ScanSeverity | undefined;
+  let failOn: FailOnOption | undefined;
   let allowLocalSource = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -191,11 +199,7 @@ function parseUpdateArgs(args: string[]): {
     else if (arg === "--force") force = true;
     else if (arg === "--allow-local-source") allowLocalSource = true;
     else if (arg === "--fail-on") {
-      const value = args[++i];
-      if (value !== "low" && value !== "medium" && value !== "high") {
-        throw new Error("--fail-on must be low, medium, or high");
-      }
-      failOn = value;
+      failOn = parseFailOn(args[++i]);
     } else if (isGlobalFlag(arg, "--json")) {
       // handled globally
     } else if (arg?.startsWith("--")) {
@@ -215,7 +219,10 @@ export async function runUpdate(args: string[], options: { isJson: boolean }): P
   const vaultPath = expandHome(config.vault_path);
 
   const candidates = await resolveCandidateOrigins(vaultPath, skillId, allowLocalSource, config.egress?.allowed_hosts);
-  const plan = await buildPlan(vaultPath, candidates, failOn, force, config.egress?.allowed_hosts);
+  // Same default as install: block on a high-severity finding unless the
+  // caller explicitly opts out with --fail-on none.
+  const effectiveFailOn = resolveMutatingFailOn(failOn);
+  const plan = await buildPlan(vaultPath, candidates, effectiveFailOn, force, config.egress?.allowed_hosts);
   try {
     const toWrite = plan.filter((item) => item.kind === "update");
 

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/output.ts

@@ -4,7 +4,7 @@ export interface JsonEnvelope<T = any> {
   schema_version: 1;
   ok: boolean;
   context: string | { name: string; server: string };
-  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
   target: string | { name: string; server: string };
   data: T | null;
   error: { code: string; message: string; details?: any } | null;
@@ -12,7 +12,7 @@ export interface JsonEnvelope<T = any> {
 
 export function formatJsonEnvelope<T>(opts: {
   ok: boolean;
-  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
   target?: ResolvedContext | string | { name: string; server: string };
   context?: ResolvedContext | string | { name: string; server: string };
   data?: T;
@@ -62,7 +62,7 @@ export class CliError extends Error {
 export function emitSuccess<T>(
   ctx: {
     isJson: boolean;
-    /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+    /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
     target?: ResolvedContext | string | { name: string; server: string };
     context?: ResolvedContext | string | { name: string; server: string };
   },

package/src/scan.ts

@@ -264,3 +264,37 @@ export function scanExitCode(findings: RuleMatch[], failOn: ScanSeverity | undef
   const threshold = SEVERITY_RANK[failOn];
   return findings.some((f) => SEVERITY_RANK[f.severity] >= threshold) ? 1 : 0;
 }
+
+/**
+ * A parsed `--fail-on` value. "none" is accepted on the command line to mean
+ * "never fail" and is not a finding severity, which is why it is kept out of
+ * ScanSeverity itself.
+ *
+ * Note the ordering: a lower threshold is stricter. `low` fails on low, medium
+ * and high; `high` fails only on high.
+ */
+export type FailOnOption = ScanSeverity | "none";
+
+export const FAIL_ON_USAGE = "low|medium|high|none";
+
+export function parseFailOn(value: string | undefined): FailOnOption {
+  if (value !== "low" && value !== "medium" && value !== "high" && value !== "none") {
+    throw new Error("--fail-on must be low, medium, high, or none");
+  }
+  return value;
+}
+
+/**
+ * Resolves the threshold for the commands that fetch remote content into the
+ * vault (install, update). They default to blocking on a high-severity finding,
+ * because printing a warning and proceeding anyway is the wrong default on the
+ * supply-chain path. `--fail-on none` restores the permissive behavior.
+ *
+ * `skillmux scan` deliberately does NOT use this: it is a reporting command
+ * whose exit code the caller opts into, and giving it a default would change
+ * the exit code of existing CI pipelines that just run `skillmux scan`.
+ */
+export function resolveMutatingFailOn(failOn: FailOnOption | undefined): ScanSeverity | undefined {
+  if (failOn === undefined) return "high";
+  return failOn === "none" ? undefined : failOn;
+}

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