diff --git a/plugins/magpie-setup/skills/setup/upgrade.md b/plugins/magpie-setup/skills/setup/upgrade.md
index d0409712c..cb275ed82 100644
--- a/plugins/magpie-setup/skills/setup/upgrade.md
+++ b/plugins/magpie-setup/skills/setup/upgrade.md
@@ -416,6 +416,36 @@ Copy the files, not a link to them.
 same package, so a plain `cp -R` from it leaves a link in the personal
 layer that points nowhere.
 Copy from the skill's directory, or follow the link with `cp -RL`.
+For marketplace installs, use the `setup_preflight/` directory next
+to this skill in the installed plugin. Get the destination from
+`python3 -m setup_preflight.layers` as in
+[`config` Step 0](config.md#step-0--pre-flight).
+The marketplace cache under `~/.claude/plugins/cache/` is read-denied
+to a sandboxed shell. For a marketplace install, ask the user to run
+the following commands in their own terminal, outside the sandbox.
+For a readable snapshot install, the commands can run in the sandbox.
+
+Set `source_dir` to that installed skill's `setup_preflight/` directory
+and `personal_dir` to the directory reported by `setup_preflight.layers`
+before running the commands. Use their actual paths, not placeholders.
+Check the new copy before replacing the old one:
+
+```bash
+(
+  target="$personal_dir/setup_preflight"
+
+  if [ -e "$target" ] || [ -L "$target" ]; then
+    temp="$(mktemp -d "$personal_dir/.preflight.XXXXXX")" || exit 1
+    cp -RL "$source_dir" "$temp/setup_preflight" &&
+      PYTHONPATH="$temp" python3 -P -m setup_preflight --skill magpie-setup --no-welcome ||
+      { rm -rf "$temp"; exit 1; }
+    mv "$target" "$temp/old" || { rm -rf "$temp"; exit 1; }
+    mv "$temp/setup_preflight" "$target" ||
+      { mv "$temp/old" "$target"; exit 1; }
+    rm -rf "$temp"
+  fi
+)
+```
 
 The fresh copy also carries the new version's isolated-setup
 fingerprint. When the secure-setup files changed in this upgrade, the