docs: strip git-install refs, canonicalize npm install paths

AGENTS.md

@@ -53,16 +53,10 @@ CHANGELOG.md       # Keep-a-Changelog format, backfilled through v0.1.2
 
 ## Distribution
 
-**Current blessed install (git-install, pre-npm):**
-```json
-{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.2"] }
-```
-
-**Future canonical install (npm, once published):**
+**Canonical install (npm):**
 ```json
 { "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] }
 ```
-Once npm is live, git-install references should be removed from docs.
 
 **Human CLI on PATH (optional, notify-only):**
 ```bash

README.md

@@ -91,22 +91,22 @@ scripts called from the agent via a bash tool.
 
 ## Install details
 
-### Recommended: git-install via `opencode.json` (coworkers / CI)
+### Recommended: npm install via `opencode.json` (coworkers / CI)
 
 Add the following entry to the `plugins` array in your `opencode.json`:
 
 ```json
 {
   "plugins": [
-    "opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1"
+    "@stablekernel/opencode-bgrun@0.1.2"
   ]
 }
 ```
 
 OpenCode installs the package into
-`~/.cache/opencode/packages/<spec>/node_modules/opencode-bgrun/` and loads the plugin
-automatically on startup. No PATH setup is needed for the **agent (tool) path** — the plugin
-resolves `bin/bgrun` by absolute path at runtime.
+`~/.cache/opencode/packages/@stablekernel/opencode-bgrun@<version>/node_modules/@stablekernel/opencode-bgrun/`
+and loads the plugin automatically on startup. No PATH setup is needed for the **agent (tool)
+path** — the plugin resolves `bin/bgrun` by absolute path at runtime.
 
 ### Local / dev install (repo clone)
 
@@ -131,18 +131,28 @@ is required for the tool registration and completion poller to become active.
 ### Optional: human shell CLI
 
 The **`bgrun` tool** (plugin-registered) is what AI agents call and it works automatically
-from the git-install — no PATH setup required. It also delivers the session-wake feature.
+from the npm install — no PATH setup required. It also delivers the session-wake feature.
 
 The human shell commands (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) are **optional and
 notify-only** — they fire a desktop notification on completion but do **not** wake an agent
-session. (Agent-wake is exclusively the plugin `bgrun` tool.) After a git-install via
+session. (Agent-wake is exclusively the plugin `bgrun` tool.) After an npm install via
 `opencode.json` those scripts are **not on your PATH**; typing `bgrun` in a terminal will
 produce `command not found`.
 
 #### Recommended: `install.sh --cli-only`
 
-Run `./install.sh --cli-only` to symlink just the four CLI scripts into `~/.local/bin` without
-touching the plugin or skill (which the git-install already provides):
+**Recommended:** install via npm global:
+
+```bash
+npm i -g @stablekernel/opencode-bgrun
+```
+
+This puts `bgrun`, `bgstatus`, `bgtail`, and `bgclean` on your PATH automatically via npm's
+bin map.
+
+Alternatively, if you have the repo cloned, run `./install.sh --cli-only` to symlink just
+the four CLI scripts into `~/.local/bin` without touching the plugin or skill (which the npm
+install already provides):
 
 ```bash
 # If you have the repo cloned:
@@ -153,25 +163,24 @@ touching the plugin or skill (which the git-install already provides):
 ```
 
 `--cli-only` also works **without a clone** when the plugin is already installed via the
-`opencode.json` git-spec. It auto-discovers the scripts inside OpenCode's package cache at:
+`opencode.json` npm spec. It auto-discovers the scripts inside OpenCode's package cache at:
 
 ```
-~/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun/bin
+~/.cache/opencode/packages/@stablekernel/opencode-bgrun@<version>/node_modules/@stablekernel/opencode-bgrun/bin/
 ```
 
-The version tag in the path is discovered dynamically, so it keeps working across version
+The version segment in the path is discovered dynamically, so it keeps working across version
 bumps. To use this mode you need the `install.sh` script itself — grab it from the repo or
 copy it from the cache dir above.
 
 To remove: `./uninstall.sh --cli-only`.
 
 #### Manual alternative
 
-If you prefer, symlink directly from the cache. The path contains `#`, `:`, and `@` so it
-**must be quoted**:
+If you prefer, symlink directly from the npm global cache:
 
 ```bash
-PKG="$HOME/.cache/opencode/packages/opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1/node_modules/opencode-bgrun"
+PKG="$HOME/.cache/opencode/packages/@stablekernel/opencode-bgrun@0.1.2/node_modules/@stablekernel/opencode-bgrun"
 mkdir -p "$HOME/.local/bin"
 for cmd in bgrun bgstatus bgtail bgclean; do
   ln -sf "$PKG/bin/$cmd" "$HOME/.local/bin/$cmd"

install.sh

@@ -6,12 +6,12 @@
 #   • Symlinks bin/, plugin/, and skill/ into the user's config dirs.
 #
 # --cli-only: PATH-only install for users who already have the plugin installed
-#   via the git-install spec in opencode.json.
+#   via the npm plugin spec in opencode.json.
 #   • Skips npm, plugin symlink, and skill symlink.
 #   • Discovers CLI scripts from (a) this repo clone or (b) the OpenCode cache.
 #
 # Safe to re-run; replaces existing symlinks, never clobbers real files.
-# Coworkers: use the git-install plugin spec in the README instead.
+# Coworkers: use the npm plugin spec in the README instead.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
@@ -34,7 +34,7 @@ Usage: install.sh [OPTIONS]
 Options:
   --cli-only    Install only the 4 CLI scripts (bgrun bgstatus bgtail bgclean)
                 onto PATH (~/.local/bin/).  Skips npm install, plugin symlink,
-                and skill symlink.  Useful for git-install users who already
+                and skill symlink.  Useful for npm-install users who already
                 have the plugin loaded via opencode.json and just want shell
                 access to the bg* helpers.
 
@@ -46,8 +46,9 @@ Modes:
 
   --cli-only    PATH-only install.  Source priority:
                   1. <repo>/bin/  (if running from a clone)
-                  2. ~/.cache/opencode/packages/opencode-bgrun@.../bin/
-                     (auto-discovered from OpenCode's plugin cache)
+                   2. ~/.cache/opencode/packages/@stablekernel/opencode-bgrun@.../
+                         node_modules/@stablekernel/opencode-bgrun/bin/
+                      (auto-discovered from OpenCode's plugin cache)
                 If neither source is found, installation fails with guidance.
 EOF
 }
@@ -118,17 +119,15 @@ if [ "$CLI_ONLY" -eq 1 ]; then
         ok "Linking CLI from: $CLI_SRC  (repo clone)"
     else
         # (b) Discover from OpenCode plugin cache
-        # The cache path contains @ : # and an embedded / in the package spec,
-        # so the package spec spans two path segments:
-        #   opencode-bgrun@github:stablekernel  /  opencode-bgrun#v0.1.1
-        # We glob over both segments to handle any version.
+        # The npm cache path is well-formed: @stablekernel/opencode-bgrun@<version>/
+        # We glob over the version segment to handle any installed version.
         CACHE_MATCH=""
         CACHE_COUNT=0
 
         # Expand the glob manually; iterate over potential matches.
         # Using a for loop with a glob is safe — bash expands it before the loop.
         # We use a sub-glob for the two-segment package spec, then check each hit.
-        for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do
+        for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do
             # If the glob found no matches, bash leaves the literal pattern —
             # check that the candidate actually exists as a directory.
             if [ -d "$candidate" ]; then
@@ -144,15 +143,15 @@ if [ "$CLI_ONLY" -eq 1 ]; then
             printf "  To fix, do one of:\n"
             printf "    1. Run this script from a repo clone (git clone stablekernel/opencode-bgrun).\n"
             printf "    2. Add the plugin to opencode.json first:\n"
-            printf "         \"plugins\": [\"opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1\"]\n"
+            printf "         \"plugins\": [\"@stablekernel/opencode-bgrun@0.1.2\"]\n"
             printf "       then let OpenCode fetch it, and re-run: install.sh --cli-only\n"
             exit 1
         fi
 
         if [ "$CACHE_COUNT" -gt 1 ]; then
             warn "Multiple cached plugin versions found — using the last (lexically highest) match."
             warn "Matches found:"
-            for candidate in "$HOME"/.cache/opencode/packages/opencode-bgrun@*/opencode-bgrun*/node_modules/opencode-bgrun/bin; do
+            for candidate in "$HOME"/.cache/opencode/packages/@stablekernel/opencode-bgrun@*/node_modules/@stablekernel/opencode-bgrun/bin; do
                 if [ -d "$candidate" ]; then
                     warn "  $candidate"
                 fi

skill/run-bg/SKILL.md

@@ -82,7 +82,7 @@ as a fallback when no `.session` sidecar is present.
 
 **The plugin is required on OpenCode.** Without it, the human desktop notification still
 fires, but there is no live agent wake. Install the plugin by adding
-`opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1` to the `plugin` array in your
+`@stablekernel/opencode-bgrun@0.1.2` to the `plugin` array in your
 `opencode.json` (recommended), or run `./install.sh` from a repo clone for local dev.
 Restart OpenCode either way. See Setup below.
 
@@ -108,18 +108,19 @@ deliverables. Today `bgrun` handles them at the notification rung only.
 
 ## Setup (one-time)
 
-**1. Recommended — plugin via git-install:**
+**1. Recommended — plugin via npm:**
 Add the spec to the `plugin` array in your `opencode.json`:
 ```json
-{ "plugin": ["opencode-bgrun@github:stablekernel/opencode-bgrun#v0.1.1"] }
+{ "plugin": ["@stablekernel/opencode-bgrun@0.1.2"] }
 ```
 OpenCode fetches the package automatically on next start. Restart OpenCode to load the
 plugin. This gives you the agent-facing `bgrun` tool and the session-wake feature. It does
 **not** put the human shell CLIs (`bgrun`, `bgstatus`, `bgtail`, `bgclean`) on your PATH.
 
 **2. Human shell CLI (optional, notify-only):**
-To also get the shell CLIs on your PATH, run `./install.sh --cli-only`. It works from a
-clone, or auto-discovers the git-installed package in OpenCode's cache without a clone.
+Recommended: `npm i -g @stablekernel/opencode-bgrun` — puts all four CLI scripts on your
+PATH via npm's bin map. Alternatively, run `./install.sh --cli-only` from a clone, or
+auto-discovers the npm-installed package in OpenCode's cache without a clone.
 `./install.sh --help` shows all modes. Remove with `./uninstall.sh --cli-only`.
 
 **3. Local dev (from a clone):**

uninstall.sh

@@ -62,7 +62,7 @@ done
 # Usage: remove_link <dest>
 # Accepted roots:
 #   1. $SCRIPT_DIR   (dev/clone install)
-#   2. $HOME/.cache/opencode/packages/  containing "opencode-bgrun"  (git-install)
+#   2. $HOME/.cache/opencode/packages/  containing "@stablekernel/opencode-bgrun"  (npm install)
 remove_link() {
     local dest="$1"