docs: clarify update vs restart deploy behavior

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

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 ""

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