diff --git a/README.md b/README.md
index 82648a2..f48fe30 100644
--- a/README.md
+++ b/README.md
@@ -83,6 +83,9 @@ Upgrade later:
 sudo baudbot update
 ```
 
+`baudbot update` already deploys runtime files and restarts the service. `baudbot restart` alone does not deploy code changes.
+For local, unmerged edits, run deploy from that checkout (for example `sudo ~/baudbot/bin/deploy.sh`).
+
 Install with a specific pi version (optional):
 
 ```bash
diff --git a/bin/baudbot b/bin/baudbot
index 2b99f4b..a0f6de8 100755
--- a/bin/baudbot
+++ b/bin/baudbot
@@ -128,7 +128,7 @@ usage() {
   echo -e "${BOLD}Lifecycle:${RESET}"
   echo "  start          Start the agent (systemd, or --direct for foreground)"
   echo "  stop           Stop the agent"
-  echo "  restart        Restart the agent"
+  echo "  restart        Restart the agent (does not deploy source changes)"
   echo "  status         Show agent status + deployed version + broker connection"
   echo "  logs           Tail agent logs"
   echo "  attach         Attach to control-agent by default; supports --pi/--tmux"
@@ -147,7 +147,7 @@ usage() {
   echo "  audit          Security posture audit"
   echo "  version        Show baudbot CLI version (+ git SHA when available)"
   echo "  test           Run test suite"
-  echo "  update         Build/test in temp checkout, publish git-free release, deploy"
+  echo "  update         Build/test in temp checkout, publish git-free release, deploy + restart"
   echo "  rollback       Re-deploy previous (or specified) git-free release snapshot"
   echo "  uninstall      Remove everything"
   echo ""
diff --git a/docs/operations.md b/docs/operations.md
index e33a25c..f1c5c15 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -22,16 +22,22 @@ sudo baudbot sessions
 ## Deployment and upgrades
 
 ```bash
-# Deploy source + config to runtime
-sudo baudbot deploy
+# Deploy source + config to runtime (for local source edits)
+sudo /path/to/your/checkout/bin/deploy.sh
 
 # Update from upstream with preflight checks and release publishing
+# (includes deploy + restart + health check)
 sudo baudbot update
 
 # Roll back to previous or specified release snapshot
 sudo baudbot rollback previous
 ```
 
+Notes:
+- `baudbot restart` only restarts the service; it does not copy source files into runtime.
+- Use `deploy.sh` when testing local, unmerged source edits.
+- Use `baudbot update` for release-based upgrades from git refs/branches.
+
 Provision with a pinned pi version (optional):
 
 ```bash