Selaa lähdekoodia

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>
Drew Ritter 7 kuukautta sitten
vanhempi
sitoutus
bcccc69271
3 muutettua tiedostoa jossa 35 lisäystä ja 16 poistoa
  1. 21 6
      .codex/INSTALL.md
  2. 8 6
      .codex/install-codex.mjs
  3. 6 4
      docs/README.codex.md

+ 21 - 6
.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`.

+ 8 - 6
.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 {

+ 6 - 4
docs/README.codex.md

@@ -31,11 +31,11 @@ Fetch and follow instructions from https://raw.githubusercontent.com/obra/superp
 
 3. Restart Codex.
 
-The installer creates a symlink from `~/.agents/skills/superpowers` to the repo's `skills/` directory and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.
+The installer links `~/.agents/skills/superpowers` to the repo's `skills/` directory (symlink on macOS/Linux, junction on Windows) and adds a gatekeeper block to `~/.codex/AGENTS.md`. Existing users with the old bootstrap setup are migrated automatically.
 
 ### Windows
 
-The installer tries symlinks first, then falls back to junctions (`mklink /J`) if symlinks require Developer Mode. Both work for Codex skill discovery.
+The installer creates a junction (`mklink /J`) on Windows, which works without Developer Mode. On macOS/Linux it creates a standard symlink. Both work for Codex skill discovery.
 
 ## How It Works
 
@@ -88,6 +88,8 @@ description: Use when [condition] - [what it does]
 [Your skill content here]
 ```
 
+The `description` field is how Codex decides when to activate a skill automatically — write it as a clear trigger condition.
+
 ## Updating
 
 ```bash
@@ -112,9 +114,9 @@ Then remove the block between `<!-- superpowers:begin -->` and `<!-- superpowers
 2. Check skills exist: `ls ~/.codex/superpowers/skills`
 3. Restart Codex — skills are discovered at startup
 
-### Windows symlink issues
+### Windows junction issues
 
-If the installer reports symlink failure, ensure Developer Mode is enabled or run as administrator. The installer will attempt a junction fallback automatically.
+The installer creates junctions on Windows, which normally work without special permissions. If junction creation fails, try running PowerShell as administrator.
 
 ### Node.js not found