docs: add npm install flow for 0.5.26

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.5.26
+
+- Added an explicit npm-based OpenCode installation path: `npm install -g @bybrawe/opencode-loop@latest` followed by `opencode-loop`.
+- Clarified that project-local `npm install @bybrawe/opencode-loop` alone does not perform the OpenCode installer step.
+- Documented update and uninstall flows for both `npx` and global npm installation methods.
+- Added matching npm installation instructions for the recommended dedicated `@bybrawe/opencode-goal` plugin.
+
+## 0.5.25
+
+- Added safe `--uninstall` support to the Loop installer while preserving unrelated OpenCode configuration and project Loop state.
+- Reworked README installation/removal guidance and moved install/update instructions to the top.
+- Documented coexistence with OpenCode Goals and recommends the dedicated Goals plugin for stronger persistent Goal contracts and host-verified completion.
+- Warned against driving the same session/work simultaneously with Loop's experimental `/loop-goal` and the dedicated `/goal` continuation system.
+
 ## 0.5.24
 
 - Cross-check stale OpenCode `busy`/`retry` status against the chronological session tail and only recover early when the latest assistant message has a real `time.completed`; an explicitly unfinished assistant tail is never force-finalized.

README.md

@@ -4,16 +4,38 @@
 
 OpenCode Loop adds `/loop`, scheduled prompt/command/shell jobs, compact scheduling, safe long-running continuation helpers, and the `opencode-loopd` background daemon.
 
-> **Current release: `0.5.25`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
+> **Current release: `0.5.26`.** Loop also contains an older experimental `/loop-goal` mode, but for strong persistent Goal contracts and host-verified completion, use the separate **OpenCode Goals** plugin described below.
 
 ## Install or update
 
-Recommended installation from any shell on Windows, macOS, or Linux:
+Choose either installation method below.
+
+### Option 1 — one-command install with `npx` (recommended)
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest
 ```
 
+Run the same command again whenever you want to update.
+
+### Option 2 — install with npm
+
+Install OpenCode Loop globally so its installer and daemon commands are available:
+
+```bash
+npm install -g @bybrawe/opencode-loop@latest
+opencode-loop
+```
+
+To update later:
+
+```bash
+npm install -g @bybrawe/opencode-loop@latest
+opencode-loop
+```
+
+`npm install @bybrawe/opencode-loop` by itself only adds the Node package to the current project. For a normal OpenCode installation, use the global npm method above or the recommended `npx` installer.
+
 The installer:
 
 - installs/updates the OpenCode Loop plugin;
@@ -29,18 +51,23 @@ Then **fully restart OpenCode** and verify:
 /loop-doctor
 ```
 
-Run the same command again whenever you want to update:
+### Uninstall
+
+If you use the `npx` installer:
 
 ```bash
-npx -y @bybrawe/opencode-loop@latest
+npx -y @bybrawe/opencode-loop@latest --uninstall
 ```
 
-### Uninstall
+If you installed OpenCode Loop globally with npm:
 
 ```bash
-npx -y @bybrawe/opencode-loop@latest --uninstall
+opencode-loop --uninstall
+npm uninstall -g @bybrawe/opencode-loop
 ```
 
+Run `opencode-loop --uninstall` before removing the global npm package so it can clean its OpenCode registrations and managed command files.
+
 Uninstall removes known OpenCode Loop package registrations, local plugin files, `/loop-*` command markdown files, and the Loop local command agent while preserving unrelated OpenCode configuration.
 
 Project Loop state is intentionally preserved under:
@@ -113,12 +140,21 @@ Loop is idle-safe: if a job becomes due while the session is busy, active tools
 
 OpenCode Loop still includes the older **experimental** `/loop-goal` workflow. It is useful for compatibility and lightweight outcome-driven automation, but it is not the strongest Goal implementation in this project family.
 
-For durable Goal Contracts, host-owned evidence, semantic verification, native Todo coordination, revision isolation, false-completion protection, restart recovery, Goal audit, budgets, and ordered Goals, install **OpenCode Goals**:
+For durable Goal Contracts, host-owned evidence, semantic verification, native Todo coordination, revision isolation, false-completion protection, restart recovery, Goal audit, budgets, and ordered Goals, install **OpenCode Goals**.
+
+Recommended one-command installer:
 
 ```bash
 npx -y @bybrawe/opencode-goal@latest
 ```
 
+Or install its CLI globally with npm and run the installer:
+
+```bash
+npm install -g @bybrawe/opencode-goal@latest
+opencode-goal
+```
+
 Then use:
 
 ```text
@@ -141,13 +177,21 @@ Do **not** run Loop’s `/loop-goal` and OpenCode Goals `/goal` against the same
 
 Likewise, avoid leaving a prompt-producing `/loop ...` job continuously injecting agent turns into a session while an OpenCode Goal is actively continuing. Use separate sessions or pause/remove that prompt loop until the Goal is done. Scheduled shell/command jobs should also be chosen carefully so they do not race files or verification.
 
-Install both when needed:
+Install both when needed with `npx`:
 
 ```bash
 npx -y @bybrawe/opencode-loop@latest
 npx -y @bybrawe/opencode-goal@latest
 ```
 
+Or install both globally with npm, then run both installers:
+
+```bash
+npm install -g @bybrawe/opencode-loop@latest @bybrawe/opencode-goal@latest
+opencode-loop
+opencode-goal
+```
+
 ## Core commands
 
 | Command | Purpose |
@@ -331,6 +375,13 @@ For new work where completion integrity matters, prefer the dedicated **OpenCode
 npx -y @bybrawe/opencode-goal@latest
 ```
 
+or:
+
+```bash
+npm install -g @bybrawe/opencode-goal@latest
+opencode-goal
+```
+
 ## State and checkpoints
 
 Loop runtime state:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bybrawe/opencode-loop",
-  "version": "0.5.25",
+  "version": "0.5.26",
   "description": "Claude Code/Codex style /loop and experimental goal mode for OpenCode: heartbeat scheduler, idle-safe loops, scheduled commands, compact scheduling, verification, checkpoints, and persistent coding goals.",
   "type": "module",
   "main": "src/index.js",