diff --git a/packages/cloud-connection/README.md b/packages/cloud-connection/README.md
index 64efb21d7b..d40d737e08 100644
--- a/packages/cloud-connection/README.md
+++ b/packages/cloud-connection/README.md
@@ -27,11 +27,25 @@ import {
 const cloudUrl = resolveCloudUrl(); // OS_CLOUD_URL, 'off' disables
 
 const plugins = [
+  // Cloud-gated: these ARE the control-plane client, so a resolved URL is
+  // their precondition. Skipped entirely when cloud is off.
   ...(cloudUrl ? [
     new MarketplaceProxyPlugin({ controlPlaneUrl: cloudUrl }),
-    new MarketplaceInstallLocalPlugin({ controlPlaneUrl: cloudUrl }),
     new CloudConnectionPlugin({ singleEnvironment: true, controlPlaneUrl: cloudUrl }),
   ] : []),
+  // NOT cloud-gated: this is the documented air-gapped path, so it mounts
+  // unconditionally. `cloudUrl || 'off'` — never the bare `cloudUrl` — because
+  // the constructor re-resolves whatever it is given through
+  // resolveCloudUrl(), which reads '' as "unset" and substitutes the public
+  // DEFAULT_CLOUD_URL. 'off' is one of the documented disable sentinels and
+  // is the value that actually resolves to no cloud.
+  new MarketplaceInstallLocalPlugin({ controlPlaneUrl: cloudUrl || 'off' }),
+  // NOT cloud-gated: features.marketplace is derived from what is actually
+  // mounted, not from this constructor call, so a cloud-less runtime reports
+  // marketplace: false on its own — there is nothing here to keep in sync.
+  // `''` here, unlike its neighbor above, is correct as-is: this plugin does
+  // NOT re-resolve controlPlaneUrl through resolveCloudUrl(), so '' means
+  // "stay on this origin" rather than "unset" — do not "fix" it to 'off'.
   new RuntimeConfigPlugin({ controlPlaneUrl: '', singleEnvironment: true, installLocal: true }),
 ];
 ```