docs(opencode): fix pin example, local-path examples, and V2 log troubleshooting

Restore the version-pin example for both config keys and state the V2
constraint (the pinned ref must include OpenCode V2 support). Replace the
`~/...` local-package examples with absolute paths: OpenCode does not expand
`~`, and a tilde entry is installed as a package spec rather than loaded as a
directory. Point V2 troubleshooting at `opencode run --standalone
--print-logs`, since plugin logs are server-role and hidden without
`--standalone`. Describe where the bootstrap lands when native compaction
retains user messages under the default keep budget.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

.opencode/INSTALL.md

@@ -69,23 +69,31 @@ use skill tool to load brainstorming
 
 ## Updating
 
-### OpenCode V1
-
-OpenCode V1 installs Superpowers through a git-backed package spec. Some OpenCode
+OpenCode installs Superpowers through a git-backed package spec. Some OpenCode
 and Bun versions pin that resolved git dependency in a lockfile or cache, so a
 restart may not pick up the newest Superpowers commit. If updates do not appear,
 clear OpenCode's package cache or reinstall the plugin.
 
-### OpenCode V2
+To pin a specific version, add a tag or commit to the spec (same form for the
+V1 `plugin` key and the V2 `plugins` key):
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.3.0"]
+}
+```
 
-For V2, a pin must reference a release or immutable commit containing this
-integration.
+On V2, pin a tag or commit that includes OpenCode V2 support; `v6.3.0` and
+earlier releases load only on V1.
 
 ## Troubleshooting
 
 ### Plugin not loading
 
-1. Check logs: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`
+1. Check logs. V1: `opencode run --print-logs "hello" 2>&1 | grep -i superpowers`.
+   V2 loads plugins in the background server, so add `--standalone`:
+   `opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers`,
+   or inspect `~/.local/share/opencode/log/opencode.log` filtering for `role=server`.
 2. Verify the plugin line in your `opencode.json`
 3. Make sure you're running a recent version of OpenCode
 
@@ -101,14 +109,15 @@ package:
 npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
 ```
 
-Then use the installed package path in `opencode.json` for your OpenCode
-version:
+Then use the absolute path of the installed package in `opencode.json` for your
+OpenCode version. OpenCode does not expand `~`; a `~/...` entry is treated as a
+package name, not a local directory.
 
 **V1:**
 
 ```json
 {
-  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
 }
 ```
 
@@ -116,7 +125,7 @@ version:
 
 ```json
 {
-  "plugins": ["~/.config/opencode/node_modules/superpowers"]
+  "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
 }
 ```
 

docs/README.opencode.md

@@ -101,17 +101,22 @@ skills. This behavior is unchanged by the migration.
 
 ## Updating
 
-### V1 (`opencode`)
-
 OpenCode installs Superpowers through a git-backed package spec. Some OpenCode
 and Bun versions pin that resolved git dependency in a lockfile or cache, so a
 restart may not pick up the newest Superpowers commit. If updates do not appear,
 clear OpenCode's package cache or reinstall the plugin.
 
-### V2 (`opencode` 2.0.4 or later)
+To pin a specific version, add a tag or commit to the spec (same form for the
+V1 `plugin` key and the V2 `plugins` key):
+
+```json
+{
+  "plugin": ["superpowers@git+https://github.com/obra/superpowers.git#v6.3.0"]
+}
+```
 
-For V2, a pin must reference a release or immutable commit containing this
-integration.
+On V2, pin a tag or commit that includes OpenCode V2 support; `v6.3.0` and
+earlier releases load only on V1.
 
 ## How It Works
 
@@ -127,8 +132,11 @@ The plugin does two things, using host-flavor-specific APIs:
 Controller sessions receive the using-superpowers bootstrap in transient model
 context. Delegated child sessions keep access to native skills but do not receive
 the controller bootstrap. A manual fork without a parent session keeps controller
-behavior. After V2 native compaction removes all user messages, the plugin appends
-a transient bootstrap message after the checkpoint; saved history is unchanged.
+behavior. When V2 native compaction retains earlier user messages (the default
+`compaction.keep.tokens` budget), the bootstrap goes into the first retained user
+message ahead of the checkpoint, as in an uncompacted session. When compaction
+removes all user messages, the plugin appends a transient bootstrap message after
+the checkpoint. Saved history is unchanged either way.
 
 If session lookup fails, the plugin keeps bootstrap for that request and retries
 on the next request. Failed lookups are not cached as controller decisions.
@@ -174,13 +182,14 @@ In short, V2 renamed `task` → `subagent` (the agent name moved from `subagent_
 opencode run --print-logs "hello" 2>&1 | grep -i superpowers
 ```
 
-**V2:** Check the server log:
+**V2:** Plugins load in the background server, whose logs `--print-logs` only
+shows with `--standalone`:
 
 ```
-opencode service status
+opencode run --standalone --print-logs "hello" 2>&1 | grep -i superpowers
 ```
 
-Then inspect `~/.local/share/opencode/log/opencode.log`, filtering for `role=server`.
+Or inspect `~/.local/share/opencode/log/opencode.log`, filtering for `role=server`.
 
 Also verify the plugin path in your `opencode.json` is correct and that you're
 running a recent version of OpenCode.
@@ -197,14 +206,15 @@ package:
 npm install superpowers@git+https://github.com/obra/superpowers.git --prefix "$HOME\.config\opencode"
 ```
 
-Then use the installed package path in `opencode.json` for your OpenCode
-version:
+Then use the absolute path of the installed package in `opencode.json` for your
+OpenCode version. OpenCode does not expand `~`; a `~/...` entry is treated as a
+package name, not a local directory.
 
 **V1:**
 
 ```json
 {
-  "plugin": ["~/.config/opencode/node_modules/superpowers"]
+  "plugin": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
 }
 ```
 
@@ -212,7 +222,7 @@ version:
 
 ```json
 {
-  "plugins": ["~/.config/opencode/node_modules/superpowers"]
+  "plugins": ["C:\\Users\\<you>\\.config\\opencode\\node_modules\\superpowers"]
 }
 ```
 

index.js

@@ -3,6 +3,7 @@
 // OpenCode V2 hosts (2.0.4 or later) require config plugin entries to be directories
 // with an index entrypoint (`index.js`) and reject bare file paths
 // ("configured plugin path must be a directory"). npm/git package installs
-// resolve via package.json `main`; this file only serves the directory form
-// (e.g. `"plugins": ["~/superpowers"]` or a `node_modules/superpowers` path).
+// resolve via package.json `main`; this file only serves the directory form,
+// an absolute path such as `"plugins": ["/path/to/superpowers"]` (`~` is not
+// expanded).
 export { default } from "./.opencode/plugins/superpowers.js";