Polish docs from 5-agent review

- INSTALL.md: add prerequisites, Windows note, verify step, clone
  deletion in uninstall
- README.codex.md: fix Windows section (junctions not symlinks),
  add description field guidance, consistent terminology
- install-codex.mjs: accurate link type labels (symlink vs junction)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.codex/INSTALL.md

@@ -1,6 +1,11 @@
 # Installing Superpowers for Codex
 
-Quick setup to enable superpowers skills in Codex via native skill discovery.
+Quick setup to enable superpowers skills in Codex. The installer links your skills into Codex's native discovery path so they load automatically.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) (v16+)
+- Git
 
 ## Installation
 
@@ -14,21 +19,31 @@ Quick setup to enable superpowers skills in Codex via native skill discovery.
    node ~/.codex/superpowers/.codex/install-codex.mjs
    ```
 
-3. **Restart Codex** to discover the skills.
+3. **Restart Codex** (quit and relaunch the CLI) to discover the skills.
+
+**Windows:** The installer creates a junction (`mklink /J`), which works without Developer Mode.
 
 ## What the installer does
 
-- Creates a symlink: `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills`
-- Adds a small gatekeeper block to `~/.codex/AGENTS.md`
+- Links `~/.agents/skills/superpowers` → `~/.codex/superpowers/skills` (symlink on macOS/Linux, junction on Windows)
+- Adds a gatekeeper block to `~/.codex/AGENTS.md` that tells Codex to use superpowers skills
 - If you had the old bootstrap setup, it removes it automatically
 
+## Verify
+
+```bash
+ls -la ~/.agents/skills/superpowers
+```
+
+You should see a symlink (or junction) pointing to your superpowers skills directory.
+
 ## Updating
 
 ```bash
 cd ~/.codex/superpowers && git pull
 ```
 
-Skills update instantly through the symlink.
+Skills update instantly through the link.
 
 ## Uninstalling
 
@@ -36,4 +51,4 @@ Skills update instantly through the symlink.
 rm ~/.agents/skills/superpowers
 ```
 
-Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`.
+Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers:end -->` from `~/.codex/AGENTS.md`. Optionally delete the clone: `rm -rf ~/.codex/superpowers`.

.codex/install-codex.mjs

@@ -64,19 +64,21 @@ function createSymlink() {
     }
   }
 
-  // Create the symlink (or junction on Windows)
+  // Create the link (symlink on macOS/Linux, junction on Windows)
+  const linkType = isWindows ? 'junction' : 'dir';
+  const linkLabel = isWindows ? 'junction' : 'symlink';
   try {
-    symlinkSync(repoSkillsDir, symlinkPath, 'junction');
-    console.log(`✓ Created symlink: ${symlinkPath} → ${repoSkillsDir}`);
+    symlinkSync(repoSkillsDir, symlinkPath, linkType);
+    console.log(`✓ Created ${linkLabel}: ${symlinkPath} → ${repoSkillsDir}`);
   } catch (err) {
     if (isWindows) {
-      // Symlink failed on Windows — try junction via mklink /J
+      // Node API failed on Windows — try junction via cmd.exe
       try {
         execSync(`cmd /c mklink /J "${symlinkPath}" "${repoSkillsDir}"`, { stdio: 'pipe' });
         console.log(`✓ Created junction: ${symlinkPath} → ${repoSkillsDir}`);
       } catch (junctionErr) {
-        console.error(`✗ Failed to create symlink or junction: ${junctionErr.message}`);
-        console.error(`  On Windows, enable Developer Mode or run as administrator.`);
+        console.error(`✗ Failed to create junction: ${junctionErr.message}`);
+        console.error(`  Try running PowerShell as administrator.`);
         process.exit(1);
       }
     } else {