diff --git a/README.md b/README.md
index 41c117a4d..184fd9247 100644
--- a/README.md
+++ b/README.md
@@ -95,12 +95,16 @@ The result: AI agents that work *with* your development process, not around it.
 
 ```bash
 npm install -g aidevops
+aidevops update  # Deploy agents (required after npm install)
 ```
 
+> **Note**: npm suppresses postinstall output. Run `aidevops update` to deploy agents to `~/.aidevops/agents/`. The CLI will remind you if agents need updating.
+
 **Bun** (fast alternative):
 
 ```bash
 bun install -g aidevops
+aidevops update  # Deploy agents
 ```
 
 **Homebrew** (macOS/Linux):
diff --git a/aidevops.sh b/aidevops.sh
index d6119423d..ddcf72ad7 100755
--- a/aidevops.sh
+++ b/aidevops.sh
@@ -1702,6 +1702,26 @@ main() {
         echo ""
     fi
     
+    # Check if agents need updating (skip for update command itself)
+    if [[ "$command" != "update" && "$command" != "upgrade" && "$command" != "u" ]]; then
+        local cli_version agents_version
+        cli_version=$(get_version)
+        if [[ -f "$AGENTS_DIR/VERSION" ]]; then
+            agents_version=$(cat "$AGENTS_DIR/VERSION")
+        else
+            agents_version="not installed"
+        fi
+        
+        if [[ "$agents_version" == "not installed" ]]; then
+            echo -e "${YELLOW}[WARN]${NC} Agents not installed. Run: aidevops update"
+            echo ""
+        elif [[ "$cli_version" != "$agents_version" ]]; then
+            echo -e "${YELLOW}[WARN]${NC} Version mismatch - CLI: $cli_version, Agents: $agents_version"
+            echo -e "       Run: aidevops update"
+            echo ""
+        fi
+    fi
+    
     case "$command" in
         init|i)
             shift