From 9a5f251ae6c0720cfd022b401c289db5d304a921 Mon Sep 17 00:00:00 2001
From: gaoguobin <31329849+gaoguobin@users.noreply.github.com>
Date: Wed, 20 May 2026 15:45:41 +0800
Subject: [PATCH] docs: repair stale Windows skill junctions

---
 .codex/INSTALL.md   | 12 +++++++++---
 .codex/UNINSTALL.md |  3 ++-
 .codex/UPDATE.md    | 24 ++++++++++++++++++++++--
 3 files changed, 33 insertions(+), 6 deletions(-)

diff --git a/.codex/INSTALL.md b/.codex/INSTALL.md
index 70edef8..0ff2621 100644
--- a/.codex/INSTALL.md
+++ b/.codex/INSTALL.md
@@ -36,6 +36,7 @@ Run this PowerShell block exactly:
 $repoRoot = Join-Path $HOME '.codex\codex-environment-backup'
 $skillsRoot = Join-Path $HOME '.agents\skills'
 $skillNamespace = Join-Path $skillsRoot 'codex-environment-backup'
+$expectedSkillTarget = Join-Path $repoRoot 'skills'
 
 if (-not (Get-Command git -ErrorAction SilentlyContinue)) {
     throw 'git is required before installing codex-environment-backup.'
@@ -69,14 +70,19 @@ if (Test-Path $repoRoot) {
     throw 'codex-environment-backup is already installed. Follow UPDATE.md instead.'
 }
 
-if (Test-Path $skillNamespace) {
-    throw 'The skill namespace link already exists. Remove it or follow UNINSTALL.md before reinstalling.'
+$skillItem = Get-Item -LiteralPath $skillNamespace -Force -ErrorAction SilentlyContinue
+if ($skillItem) {
+    if (($skillItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) {
+        Remove-Item -LiteralPath $skillNamespace -Force
+    } else {
+        throw 'The skill namespace path already exists and is not a link. Remove it or follow UNINSTALL.md before reinstalling.'
+    }
 }
 
 New-Item -ItemType Directory -Force -Path $skillsRoot | Out-Null
 git clone https://github.com/gaoguobin/codex-environment-backup.git $repoRoot
 & $pythonCmd -m pip install --user -e $repoRoot
-cmd /d /c "mklink /J `"$skillNamespace`" `"$repoRoot\skills`""
+cmd /d /c "mklink /J `"$skillNamespace`" `"$expectedSkillTarget`""
 & $pythonCmd -m agent_environment_backup --profile codex doctor
 ```
 
diff --git a/.codex/UNINSTALL.md b/.codex/UNINSTALL.md
index 4b1a378..6237c91 100644
--- a/.codex/UNINSTALL.md
+++ b/.codex/UNINSTALL.md
@@ -62,7 +62,8 @@ if ($pythonCmd) {
     & $pythonCmd -m pip uninstall -y agent-environment-backup codex-environment-backup
 }
 
-if (Test-Path $skillNamespace) {
+$skillItem = Get-Item -LiteralPath $skillNamespace -Force -ErrorAction SilentlyContinue
+if ($skillItem) {
     cmd /d /c "rmdir `"$skillNamespace`""
 }
 
diff --git a/.codex/UPDATE.md b/.codex/UPDATE.md
index 5732b29..a836547 100644
--- a/.codex/UPDATE.md
+++ b/.codex/UPDATE.md
@@ -23,6 +23,7 @@ Run this PowerShell block exactly:
 ```powershell
 $repoRoot = Join-Path $HOME '.codex\codex-environment-backup'
 $skillNamespace = Join-Path $HOME '.agents\skills\codex-environment-backup'
+$expectedSkillTarget = Join-Path $repoRoot 'skills'
 $pythonCmd = $null
 
 foreach ($candidate in @('python3', 'python')) {
@@ -56,9 +57,28 @@ git -C $repoRoot pull --ff-only
 & $pythonCmd -m pip uninstall -y codex-environment-backup
 & $pythonCmd -m pip install --user -e $repoRoot
 
-if (-not (Test-Path $skillNamespace)) {
+$skillItem = Get-Item -LiteralPath $skillNamespace -Force -ErrorAction SilentlyContinue
+$recreateSkillLink = $false
+if (-not $skillItem) {
+    $recreateSkillLink = $true
+} elseif (($skillItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0) {
+    $target = $skillItem.Target
+    if ($target -is [array]) {
+        $target = $target[0]
+    }
+    $currentTarget = [IO.Path]::GetFullPath([string]$target)
+    $wantedTarget = [IO.Path]::GetFullPath($expectedSkillTarget)
+    if ($currentTarget -ne $wantedTarget -or -not (Test-Path (Join-Path $skillNamespace 'codex-environment-backup\SKILL.md'))) {
+        Remove-Item -LiteralPath $skillNamespace -Force
+        $recreateSkillLink = $true
+    }
+} elseif (-not (Test-Path (Join-Path $skillNamespace 'codex-environment-backup\SKILL.md'))) {
+    throw "Existing skill namespace is not a link and does not contain codex-environment-backup/SKILL.md: $skillNamespace"
+}
+
+if ($recreateSkillLink) {
     New-Item -ItemType Directory -Force -Path (Split-Path -Parent $skillNamespace) | Out-Null
-    cmd /d /c "mklink /J `"$skillNamespace`" `"$repoRoot\skills`""
+    cmd /d /c "mklink /J `"$skillNamespace`" `"$expectedSkillTarget`""
 }
 
 & $pythonCmd -m agent_environment_backup --profile codex doctor