diff --git a/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
index 19e0759bcb..3c24db3b4d 100644
--- a/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
+++ b/skills/autonomous-ai-agents/hermes-agent/references/desktop-plugins.md
@@ -7,6 +7,19 @@ changes. A plugin can also talk to its own Python backend namespace
 (`ctx.rest`/`ctx.socket` → `/api/plugins/<id>`); the general Python plugin
 system (`~/.hermes/plugins/`) is otherwise documented separately.
 
+There are TWO on-disk doors, same contract and hot reload:
+
+- `$HERMES_HOME/desktop-plugins/<id>/plugin.js` — standalone desktop plugin.
+  Loads enabled by default.
+- `$HERMES_HOME/plugins/<id>/desktop/plugin.js` — the desktop HALF of a
+  unified agent-plugin package: the same folder that carries the Python
+  plugin (`plugin.yaml`) and its `dashboard/plugin_api.py` backend ships its
+  desktop UI beside them, so one feature installs/uninstalls as one folder.
+  This half is OPT-IN: it inventories in Settings → Plugins but stays off
+  until the user toggles it (matching the Python half's `plugins.enabled`
+  gate). Tell the user to flip it on after installing — don't debug a
+  "plugin not appearing" report before checking that toggle.
+
 Full human reference (every export, area payloads, backend, security):
 `website/docs/developer-guide/desktop-plugin-sdk.md`.
 
diff --git a/website/docs/developer-guide/desktop-plugin-sdk.md b/website/docs/developer-guide/desktop-plugin-sdk.md
index 1a1de9f9e9..6d4e88544b 100644
--- a/website/docs/developer-guide/desktop-plugin-sdk.md
+++ b/website/docs/developer-guide/desktop-plugin-sdk.md
@@ -501,11 +501,13 @@ The `desktop/plugin.js` half is an ordinary disk plugin — same contract, same
 imports, same `ctx.rest('/…')` reaching the `plugin_api.py` sitting beside it.
 Installing, sharing, or removing the feature is one folder.
 
-Two enable switches still apply, on purpose: the desktop half toggles in
-**Settings → Plugins** (renderer-side), while the Python half must be in
-`plugins.enabled` in `config.yaml` (the security boundary below). The desktop
-half degrades gracefully when the backend half is off — `ctx.rest` returns
-errors, not crashes.
+Two enable switches still apply, on purpose, and both default to **off**: the
+desktop half ships opt-in — it inventories in **Settings → Plugins** but stays
+disabled until the user toggles it — matching the Python half's
+`plugins.enabled` gate in `config.yaml` (the security boundary below). Dropping
+a package into `~/.hermes/plugins` is inert on every surface until the user
+says otherwise. The desktop half degrades gracefully when the backend half is
+off — `ctx.rest` returns errors, not crashes.
 
 :::note
 The scan is local to the machine the desktop app runs on. Against a remote