Clarify paid Docker compose image override

docs/DOCKER.md

@@ -7,7 +7,10 @@ Pulse is distributed as a lightweight, Alpine-based Docker image.
 > does not include the private Pulse Pro runtime hooks. Use
 > <https://pulserelay.pro/download.html> with your activation key, then run the
 > private registry login and `PULSE_IMAGE=license.pulserelay.pro/pulse-pro:<version>`
-> compose commands shown there.
+> compose commands shown there. Those commands require the compose file image
+> line to use the `PULSE_IMAGE` variable, as shown below. If your compose file
+> hardcodes `image: rcourtman/pulse:...`, replace that line with the variable
+> form or with the private image shown on the download page before restarting.
 
 ## 🚀 Quick Start
 
@@ -31,7 +34,7 @@ Create a `docker-compose.yml` file:
 ```yaml
 services:
   pulse:
-    image: rcourtman/pulse:vX.Y.Z
+    image: ${PULSE_IMAGE:-rcourtman/pulse:vX.Y.Z}
     container_name: pulse
     restart: unless-stopped
     ports:
@@ -50,6 +53,10 @@ volumes:
 
 Run with: `docker compose up -d`
 
+The `PULSE_IMAGE` variable lets the same compose file run either the public
+community image or, for eligible paid customers, the private Pulse Pro image
+shown on <https://pulserelay.pro/download.html>.
+
 ---
 
 ## ⚙️ Configuration
@@ -183,7 +190,10 @@ Paid Pulse Pro Docker installs use the private Pulse Pro registry rather than
 the public `rcourtman/pulse` image. Open <https://pulserelay.pro/download.html>,
 paste your activation key, run the Docker login command shown there, then run
 the shown `PULSE_IMAGE=license.pulserelay.pro/pulse-pro:<version> docker compose pull`
-and `docker compose up -d` commands from the host that already runs Pulse.
+and `docker compose up -d` commands from the host that already runs Pulse. If
+your compose file has a hardcoded `image: rcourtman/pulse:...` line, change it
+to `image: ${PULSE_IMAGE:-rcourtman/pulse:vX.Y.Z}` or directly to the private
+image shown on the download page before running those commands.
 
 ### Disabling Update Features
 
@@ -197,7 +207,7 @@ Pulse provides granular control over update features via environment variables o
 ```yaml
 services:
   pulse:
-    image: rcourtman/pulse:vX.Y.Z
+    image: ${PULSE_IMAGE:-rcourtman/pulse:vX.Y.Z}
     environment:
       - PULSE_DISABLE_DOCKER_UPDATE_ACTIONS=true
 ```

docs/INSTALL.md

@@ -6,7 +6,10 @@ Pulse offers flexible installation options from Docker to enterprise-ready Kuber
 > public `rcourtman/pulse` Docker image are community builds. They can accept an
 > activation key, but they do not include the private Pulse Pro runtime hooks.
 > Use <https://pulserelay.pro/download.html> with your activation key to get the
-> private Pulse Pro Docker image or Linux archive.
+> private Pulse Pro Docker image or Linux archive. For Docker Compose, use the
+> `PULSE_IMAGE`-aware image line shown below, or replace a hardcoded
+> `rcourtman/pulse` image line with the private image shown on the download
+> page.
 
 ## 🚀 Quick Start (Recommended)
 
@@ -48,7 +51,7 @@ Create a `docker-compose.yml` file:
 ```yaml
 services:
   pulse:
-    image: rcourtman/pulse:vX.Y.Z
+    image: ${PULSE_IMAGE:-rcourtman/pulse:vX.Y.Z}
     container_name: pulse
     restart: unless-stopped
     ports:
@@ -63,6 +66,11 @@ volumes:
   pulse_data:
 ```
 
+The `PULSE_IMAGE` variable lets paid Docker users switch the same compose file
+to the private Pulse Pro image shown on
+<https://pulserelay.pro/download.html> without rebuilding the file around a
+second deployment path.
+
 > **Note**: Plain text passwords set via `PULSE_AUTH_PASS` are auto-hashed on startup. For production, prefer Quick Security Setup or a pre-hashed bcrypt value.
 > **Note**: Docker monitoring requires the unified agent on the Docker host with socket access; the Pulse server container does not need `/var/run/docker.sock`. See [UNIFIED_AGENT.md](UNIFIED_AGENT.md).
 

docs/UPGRADE_v6.md

@@ -150,7 +150,11 @@ an activation key, but they do not include the private Pulse Pro runtime hooks.
 Use <https://pulserelay.pro/download.html> with your activation key instead.
 Docker users should run the private registry login and
 `PULSE_IMAGE=license.pulserelay.pro/pulse-pro:<version>` compose commands shown
-there. Direct Linux users should download the private Pulse Pro archive from the
+there. Those commands require your compose file image line to use the
+`PULSE_IMAGE` variable. If your compose file hardcodes
+`image: rcourtman/pulse:...`, replace that line with the variable form from
+`docker-compose.yml` or directly with the private image shown on the download
+page. Direct Linux users should download the private Pulse Pro archive from the
 same page.
 
 #### v5 License Migration

docs/release-control/v6/internal/subsystems/deployment-installability.md

@@ -226,7 +226,11 @@ server-side update execution surfaces.
    where paid customers are likely to install or upgrade, and generated public
    release bodies must send Relay, Pulse Pro, and eligible legacy customers to
    `https://pulserelay.pro/download.html` for the private Pulse Pro Docker image
-   or Linux archive.
+   or Linux archive. Public Docker and install docs must also preserve a
+   `PULSE_IMAGE`-aware compose image line and warn that any hardcoded
+   `image: rcourtman/pulse:...` line must be replaced before the private
+   Pulse Pro compose commands can move an existing Docker install off the
+   community image.
    The repo-root VERSION file is part of the same governed boundary and must
    not drift as an
    unowned release-cut switch: changing the version string for a new RC or

scripts/release_control/release_promotion_policy_test.py

@@ -357,6 +357,8 @@ class ReleasePromotionPolicyTest(unittest.TestCase):
         )
         self.assertIn("`pulse-pro-v...` archives identify `Pulse Pro`", contract)
         self.assertIn("https://pulserelay.pro/download.html", contract)
+        self.assertIn("PULSE_IMAGE`-aware compose image line", normalize_ws(contract))
+        self.assertIn("hardcoded `image: rcourtman/pulse:...`", normalize_ws(contract))
         self.assertIn("control_plane.py --branch-for-version", content)
         self.assertIn('git fetch --prune origin main "${REQUIRED_BRANCH}" --tags', content)
         self.assertIn('REQUIRED_BRANCH: ${{ steps.branch_policy.outputs.required_branch }}', content)