docs: use OPENCODE_CONFIG_DIR in install docs

Set the variable once at the top of each shell block with a default
fallback, then use it cleanly throughout. Supports custom config
directories without repeating the alternation on every line.

Based on cavanaug's work in PR #704.

Co-Authored-By: John Cavanaugh <cavanaug@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.opencode/INSTALL.md

@@ -3,71 +3,119 @@
 ## Prerequisites
 
 - [OpenCode.ai](https://opencode.ai) installed
+- Git installed
 
-## Installation
+## Installation Steps
 
-Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode`.
 
-```json
+### 1. Clone Superpowers
-{
-  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
-}
-```
-
-Restart OpenCode. That's it — the plugin auto-installs and registers all skills.
-
-Verify by asking: "Tell me about your superpowers"
-
-## Migrating from the old symlink-based install
-
-If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
 
 ```bash
-# Remove old symlinks
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-rm -f ~/.config/opencode/plugins/superpowers.js
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
-rm -rf ~/.config/opencode/skills/superpowers
-
-# Optionally remove the cloned repo
-rm -rf ~/.config/opencode/superpowers
-
-# Remove skills.paths from opencode.json if you added one for superpowers
 ```
 
-Then follow the installation steps above.
+### 2. Register the Plugin
+
+Create a symlink so OpenCode discovers the plugin:
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins"
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+```
+
+### 3. Symlink Skills
+
+Create a symlink so OpenCode's native skill tool discovers superpowers skills:
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills"
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
+```
+
+### 4. Restart OpenCode
+
+Restart OpenCode. The plugin will automatically inject superpowers context.
+
+Verify by asking: "do you have superpowers?"
 
 ## Usage
 
-Use OpenCode's native `skill` tool:
+### Finding Skills
+
+Use OpenCode's native `skill` tool to list available skills:
 
 ```
 use skill tool to list skills
+```
+
+### Loading a Skill
+
+Use OpenCode's native `skill` tool to load a specific skill:
+
+```
 use skill tool to load superpowers/brainstorming
 ```
 
+### Personal Skills
+
+Create your own skills in your OpenCode skills directory:
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
+```
+
+Create a `SKILL.md` in that directory:
+
+```markdown
+---
+name: my-skill
+description: Use when [condition] - [what it does]
+---
+
+# My Skill
+
+[Your skill content here]
+```
+
+### Project Skills
+
+Create project-specific skills in `.opencode/skills/` within your project.
+
+**Skill Priority:** Project skills > Personal skills > Superpowers skills
+
 ## Updating
 
-Superpowers updates automatically when you restart OpenCode.
+```bash
-
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-To pin a specific version:
+cd "$OPENCODE_CONFIG_DIR/superpowers"
-
+git pull
-```json
-{
-  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
-}
 ```
 
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+```bash
-2. Verify the plugin line in your `opencode.json`
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-3. Make sure you're running a recent version of OpenCode
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js"
+```
 
 ### Skills not found
 
-1. Use `skill` tool to list what's discovered
+```bash
-2. Check that the plugin is loading (see above)
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
+```
+
+Verify the symlink points to `$OPENCODE_CONFIG_DIR/superpowers/skills`. Use `skill` tool to list what's discovered.
 
 ### Tool mapping
 

.opencode/plugins/superpowers.js

@@ -2,7 +2,7 @@
  * Superpowers plugin for OpenCode.ai
  *
  * Injects superpowers bootstrap context via system prompt transform.
- * Auto-registers skills directory via config hook (no symlinks needed).
+ * Skills are discovered via OpenCode's native skill tool from symlinked directory.
  */
 
 import path from 'path';
@@ -84,18 +84,6 @@ ${toolMapping}
   };
 
   return {
-    // Inject skills path into live config so OpenCode discovers superpowers skills
-    // without requiring manual symlinks or config file edits.
-    // This works because Config.get() returns a cached singleton — modifications
-    // here are visible when skills are lazily discovered later.
-    config: async (config) => {
-      config.skills = config.skills || {};
-      config.skills.paths = config.skills.paths || [];
-      if (!config.skills.paths.includes(superpowersSkillsDir)) {
-        config.skills.paths.push(superpowersSkillsDir);
-      }
-    },
-
     // Use system prompt transform to inject bootstrap (fixes #226 agent reset bug)
     'experimental.chat.system.transform': async (_input, output) => {
       const bootstrap = getBootstrapContent();

docs/README.opencode.md

@@ -2,36 +2,182 @@
 
 Complete guide for using Superpowers with [OpenCode.ai](https://opencode.ai).
 
-## Installation
+## Quick Install
 
-Add superpowers to the `plugin` array in your `opencode.json` (global or project-level):
+Tell OpenCode:
 
-```json
+```
-{
+Clone https://github.com/obra/superpowers to my OpenCode config directory under superpowers/, then create a plugins/ directory there, then symlink superpowers/.opencode/plugins/superpowers.js to plugins/superpowers.js, then symlink superpowers/skills to skills/superpowers, then restart opencode.
-  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git"]
-}
 ```
 
-Restart OpenCode. The plugin auto-installs via Bun and registers all skills automatically.
+## Manual Installation
 
-Verify by asking: "Tell me about your superpowers"
+### Prerequisites
 
-### Migrating from the old symlink-based install
+- [OpenCode.ai](https://opencode.ai) installed
+- Git installed
 
-If you previously installed superpowers using `git clone` and symlinks, remove the old setup:
+> **Custom config directory:** If you've set `OPENCODE_CONFIG_DIR`, the commands below will use it automatically. Otherwise they default to `~/.config/opencode` (macOS/Linux) or `%USERPROFILE%\.config\opencode` (Windows).
+
+### macOS / Linux
 
 ```bash
-# Remove old symlinks
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
-rm -f ~/.config/opencode/plugins/superpowers.js
-rm -rf ~/.config/opencode/skills/superpowers
 
-# Optionally remove the cloned repo
+# 1. Install Superpowers (or update existing)
-rm -rf ~/.config/opencode/superpowers
+if [ -d "$OPENCODE_CONFIG_DIR/superpowers" ]; then
+  cd "$OPENCODE_CONFIG_DIR/superpowers" && git pull
+else
+  git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
+fi
 
-# Remove skills.paths from opencode.json if you added one for superpowers
+# 2. Create directories
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
+
+# 3. Remove old symlinks/directories if they exist
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers"
+
+# 4. Create symlinks
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js" "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ln -s "$OPENCODE_CONFIG_DIR/superpowers/skills" "$OPENCODE_CONFIG_DIR/skills/superpowers"
+
+# 5. Restart OpenCode
 ```
 
-Then follow the installation steps above.
+#### Verify Installation
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+ls -l "$OPENCODE_CONFIG_DIR/plugins/superpowers.js"
+ls -l "$OPENCODE_CONFIG_DIR/skills/superpowers"
+```
+
+Both should show symlinks pointing to the superpowers directory.
+
+### Windows
+
+**Prerequisites:**
+- Git installed
+- Either **Developer Mode** enabled OR **Administrator privileges**
+  - Windows 10: Settings → Update & Security → For developers
+  - Windows 11: Settings → System → For developers
+
+Pick your shell below: [Command Prompt](#command-prompt) | [PowerShell](#powershell) | [Git Bash](#git-bash)
+
+#### Command Prompt
+
+Run as Administrator, or with Developer Mode enabled:
+
+```cmd
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+
+:: 1. Install Superpowers
+git clone https://github.com/obra/superpowers.git "%OPENCODE_CONFIG_DIR%\superpowers"
+
+:: 2. Create directories
+mkdir "%OPENCODE_CONFIG_DIR%\plugins" 2>nul
+mkdir "%OPENCODE_CONFIG_DIR%\skills" 2>nul
+
+:: 3. Remove existing links (safe for reinstalls)
+del "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" 2>nul
+rmdir "%OPENCODE_CONFIG_DIR%\skills\superpowers" 2>nul
+
+:: 4. Create plugin symlink (requires Developer Mode or Admin)
+mklink "%OPENCODE_CONFIG_DIR%\plugins\superpowers.js" "%OPENCODE_CONFIG_DIR%\superpowers\.opencode\plugins\superpowers.js"
+
+:: 5. Create skills junction (works without special privileges)
+mklink /J "%OPENCODE_CONFIG_DIR%\skills\superpowers" "%OPENCODE_CONFIG_DIR%\superpowers\skills"
+
+:: 6. Restart OpenCode
+```
+
+#### PowerShell
+
+Run as Administrator, or with Developer Mode enabled:
+
+```powershell
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+
+# 1. Install Superpowers
+git clone https://github.com/obra/superpowers.git "$env:OPENCODE_CONFIG_DIR\superpowers"
+
+# 2. Create directories
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\plugins"
+New-Item -ItemType Directory -Force -Path "$env:OPENCODE_CONFIG_DIR\skills"
+
+# 3. Remove existing links (safe for reinstalls)
+Remove-Item "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Force -ErrorAction SilentlyContinue
+Remove-Item "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Force -ErrorAction SilentlyContinue
+
+# 4. Create plugin symlink (requires Developer Mode or Admin)
+New-Item -ItemType SymbolicLink -Path "$env:OPENCODE_CONFIG_DIR\plugins\superpowers.js" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\.opencode\plugins\superpowers.js"
+
+# 5. Create skills junction (works without special privileges)
+New-Item -ItemType Junction -Path "$env:OPENCODE_CONFIG_DIR\skills\superpowers" -Target "$env:OPENCODE_CONFIG_DIR\superpowers\skills"
+
+# 6. Restart OpenCode
+```
+
+#### Git Bash
+
+Note: Git Bash's native `ln` command copies files instead of creating symlinks. Use `cmd //c mklink` instead (the `//c` is Git Bash syntax for `/c`).
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+
+# 1. Install Superpowers
+git clone https://github.com/obra/superpowers.git "$OPENCODE_CONFIG_DIR/superpowers"
+
+# 2. Create directories
+mkdir -p "$OPENCODE_CONFIG_DIR/plugins" "$OPENCODE_CONFIG_DIR/skills"
+
+# 3. Remove existing links (safe for reinstalls)
+rm -f "$OPENCODE_CONFIG_DIR/plugins/superpowers.js" 2>/dev/null
+rm -rf "$OPENCODE_CONFIG_DIR/skills/superpowers" 2>/dev/null
+
+# 4. Create plugin symlink (requires Developer Mode or Admin)
+cmd //c "mklink \"$(cygpath -w "$OPENCODE_CONFIG_DIR/plugins/superpowers.js")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js")\""
+
+# 5. Create skills junction (works without special privileges)
+cmd //c "mklink /J \"$(cygpath -w "$OPENCODE_CONFIG_DIR/skills/superpowers")\" \"$(cygpath -w "$OPENCODE_CONFIG_DIR/superpowers/skills")\""
+
+# 6. Restart OpenCode
+```
+
+#### WSL Users
+
+If running OpenCode inside WSL, use the [macOS / Linux](#macos--linux) instructions instead.
+
+#### Verify Installation
+
+**Command Prompt:**
+```cmd
+if not defined OPENCODE_CONFIG_DIR set OPENCODE_CONFIG_DIR=%USERPROFILE%\.config\opencode
+dir /AL "%OPENCODE_CONFIG_DIR%\plugins"
+dir /AL "%OPENCODE_CONFIG_DIR%\skills"
+```
+
+**PowerShell:**
+```powershell
+if (-not $env:OPENCODE_CONFIG_DIR) { $env:OPENCODE_CONFIG_DIR = "$env:USERPROFILE\.config\opencode" }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\plugins" | Where-Object { $_.LinkType }
+Get-ChildItem "$env:OPENCODE_CONFIG_DIR\skills" | Where-Object { $_.LinkType }
+```
+
+Look for `<SYMLINK>` or `<JUNCTION>` in the output.
+
+#### Troubleshooting Windows
+
+**"You do not have sufficient privilege" error:**
+- Enable Developer Mode in Windows Settings, OR
+- Right-click your terminal → "Run as Administrator"
+
+**"Cannot create a file when that file already exists":**
+- Run the removal commands (step 3) first, then retry
+
+**Symlinks not working after git clone:**
+- Run `git config --global core.symlinks true` and re-clone
 
 ## Usage
 
@@ -45,19 +191,22 @@ use skill tool to list skills
 
 ### Loading a Skill
 
+Use OpenCode's native `skill` tool to load a specific skill:
+
 ```
 use skill tool to load superpowers/brainstorming
 ```
 
 ### Personal Skills
 
-Create your own skills in `~/.config/opencode/skills/`:
+Create your own skills in your OpenCode skills directory:
 
 ```bash
-mkdir -p ~/.config/opencode/skills/my-skill
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+mkdir -p "$OPENCODE_CONFIG_DIR/skills/my-skill"
 ```
 
-Create `~/.config/opencode/skills/my-skill/SKILL.md`:
+Create a `SKILL.md` in that directory:
 
 ```markdown
 ---
@@ -72,59 +221,125 @@ description: Use when [condition] - [what it does]
 
 ### Project Skills
 
-Create project-specific skills in `.opencode/skills/` within your project.
+Create project-specific skills in your OpenCode project:
 
-**Skill Priority:** Project skills > Personal skills > Superpowers skills
+```bash
-
+# In your OpenCode project
-## Updating
+mkdir -p .opencode/skills/my-project-skill
-
-Superpowers updates automatically when you restart OpenCode. The plugin is re-installed from the git repository on each launch.
-
-To pin a specific version, use a branch or tag:
-
-```json
-{
-  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v5.0.3"]
-}
 ```
 
-## How It Works
+Create `.opencode/skills/my-project-skill/SKILL.md`:
 
-The plugin does two things:
+```markdown
+---
+name: my-project-skill
+description: Use when [condition] - [what it does]
+---
 
-1. **Injects bootstrap context** via the `experimental.chat.system.transform` hook, adding superpowers awareness to every conversation.
+# My Project Skill
-2. **Registers the skills directory** via the `config` hook, so OpenCode discovers all superpowers skills without symlinks or manual config.
+
+[Your skill content here]
+```
+
+## Skill Locations
+
+OpenCode discovers skills from these locations:
+
+1. **Project skills** (`.opencode/skills/`) - Highest priority
+2. **Personal skills** (`~/.config/opencode/skills/`)
+3. **Superpowers skills** (`~/.config/opencode/skills/superpowers/`) - via symlink
+
+## Features
+
+### Automatic Context Injection
+
+The plugin automatically injects superpowers context via the `experimental.chat.system.transform` hook. This adds the "using-superpowers" skill content to the system prompt on every request.
+
+### Native Skills Integration
+
+Superpowers uses OpenCode's native `skill` tool for skill discovery and loading. Skills are symlinked into the skills directory so they appear alongside your personal and project skills.
 
 ### Tool Mapping
 
-Skills written for Claude Code are automatically adapted for OpenCode:
+Skills written for Claude Code are automatically adapted for OpenCode. The bootstrap provides mapping instructions:
 
 - `TodoWrite` → `todowrite`
 - `Task` with subagents → OpenCode's `@mention` system
 - `Skill` tool → OpenCode's native `skill` tool
 - File operations → Native OpenCode tools
 
+## Architecture
+
+### Plugin Structure
+
+**Location:** `$OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
+
+**Components:**
+- `experimental.chat.system.transform` hook for bootstrap injection
+- Reads and injects the "using-superpowers" skill content
+
+### Skills
+
+**Location:** `$OPENCODE_CONFIG_DIR/skills/superpowers/` (symlink to `$OPENCODE_CONFIG_DIR/superpowers/skills/`)
+
+Skills are discovered by OpenCode's native skill system. Each skill has a `SKILL.md` file with YAML frontmatter.
+
+## Updating
+
+```bash
+OPENCODE_CONFIG_DIR="${OPENCODE_CONFIG_DIR:-$HOME/.config/opencode}"
+cd "$OPENCODE_CONFIG_DIR/superpowers"
+git pull
+```
+
+Restart OpenCode to load the updates.
+
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check OpenCode logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+1. Check plugin exists: `ls $OPENCODE_CONFIG_DIR/superpowers/.opencode/plugins/superpowers.js`
-2. Verify the plugin line in your `opencode.json` is correct
+2. Check symlink/junction: `ls -l $OPENCODE_CONFIG_DIR/plugins/` (macOS/Linux) or `dir /AL "%OPENCODE_CONFIG_DIR%\plugins"` (Windows)
-3. Make sure you're running a recent version of OpenCode
+3. Check OpenCode logs: `opencode run "test" --print-logs --log-level DEBUG`
+4. Look for plugin loading message in logs
 
 ### Skills not found
 
-1. Use OpenCode's `skill` tool to list available skills
+1. Verify skills symlink: `ls -l $OPENCODE_CONFIG_DIR/skills/superpowers` (should point to superpowers/skills/)
-2. Check that the plugin is loading (see above)
+2. Use OpenCode's `skill` tool to list available skills
-3. Each skill needs a `SKILL.md` file with valid YAML frontmatter
+3. Check skill structure: each skill needs a `SKILL.md` file with valid frontmatter
+
+### Windows: Module not found error
+
+If you see `Cannot find module` errors on Windows:
+- **Cause:** Git Bash `ln -sf` copies files instead of creating symlinks
+- **Fix:** Use `mklink /J` directory junctions instead (see Windows installation steps)
 
 ### Bootstrap not appearing
 
-1. Check OpenCode version supports `experimental.chat.system.transform` hook
+1. Verify using-superpowers skill exists: `ls $OPENCODE_CONFIG_DIR/superpowers/skills/using-superpowers/SKILL.md`
-2. Restart OpenCode after config changes
+2. Check OpenCode version supports `experimental.chat.system.transform` hook
+3. Restart OpenCode after plugin changes
 
 ## Getting Help
 
 - Report issues: https://github.com/obra/superpowers/issues
 - Main documentation: https://github.com/obra/superpowers
 - OpenCode docs: https://opencode.ai/docs/
+
+## Testing
+
+Verify your installation:
+
+```bash
+# Check plugin loads
+opencode run --print-logs "hello" 2>&1 | grep -i superpowers
+
+# Check skills are discoverable
+opencode run "use skill tool to list all skills" 2>&1 | grep -i superpowers
+
+# Check bootstrap injection
+opencode run "what superpowers do you have?"
+```
+
+The agent should mention having superpowers and be able to list skills from `superpowers/`.

package.json

@@ -1,6 +0,0 @@
-{
-  "name": "superpowers",
-  "version": "5.0.3",
-  "type": "module",
-  "main": ".opencode/plugins/superpowers.js"
-}