@lousy-agents/agent-shell 4.0.2 → 5.0.0

package/README.md

@@ -1,6 +1,6 @@
-# agent-shell
+# @lousy-agents/agent-shell
 
-![agent-shell demo](https://raw.githubusercontent.com/lousy-agents/agents/HEAD/media/agent-shell.gif)
+![agent-shell demo](https://raw.githubusercontent.com/zpratt/lousy-agents/main/media/agent-shell.gif)
 
 A flight recorder for npm script execution.
 
@@ -9,22 +9,24 @@ agent-shell is an npm `script-shell` shim that independently records what script
 ## Quick Start
 
 ```bash
-# Install as a dev dependency
-npm install -D @lousy-agents/agent-shell
+# Install globally
+npm install -g @lousy-agents/agent-shell
 
 # Configure npm to use agent-shell as the script shell
-echo 'script-shell=./node_modules/.bin/agent-shell' >> .npmrc
+echo 'script-shell=agent-shell' >> .npmrc
 
 # Add event storage to .gitignore
 echo '.agent-shell/' >> .gitignore
 
 # Verify it's working
-npx agent-shell --version
+agent-shell --version
 
 # Run any npm script — events are recorded automatically
 npm test
 ```
 
+> **Why global?** agent-shell is configured as npm's `script-shell`, so it must be available _before_ `npm ci` or `npm install` runs. A local dev dependency creates a circular dependency: npm needs agent-shell to execute the install script, but agent-shell isn't available until the install completes. Installing globally keeps the shim on `PATH` independent of `node_modules`.
+
 ## How It Works
 
 When npm runs a script (e.g., `npm test`), it invokes the configured `script-shell` instead of `/bin/sh`. agent-shell wraps the real shell:
@@ -174,11 +176,11 @@ npm run lint && npm test && npm run build
 
 ### npm fails with "script-shell not found"
 
-Your `.npmrc` references `agent-shell` but it's not installed:
+Your `.npmrc` references `agent-shell` but it's not installed globally:
 
 ```bash
-# Fix: install the package
-npm install -D @lousy-agents/agent-shell
+# Fix: install the package globally
+npm install -g @lousy-agents/agent-shell
 
 # Or: bypass temporarily
 AGENTSHELL_PASSTHROUGH=1 npm test
@@ -198,7 +200,7 @@ Remove the `script-shell` line from `.npmrc`:
 
 ```bash
 # Edit .npmrc and delete this line:
-# script-shell=./node_modules/.bin/agent-shell
+# script-shell=agent-shell
 
 # Or remove it with sed:
 sed -i '' '/script-shell/d' .npmrc
@@ -207,7 +209,7 @@ sed -i '' '/script-shell/d' .npmrc
 Then optionally uninstall:
 
 ```bash
-npm uninstall @lousy-agents/agent-shell
+npm uninstall -g @lousy-agents/agent-shell
 ```
 
 ### Verify the shim is active

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lousy-agents/agent-shell",
-    "version": "4.0.2",
+    "version": "5.0.0",
     "description": "A flight recorder for npm script execution",
     "type": "module",
     "repository": {