feat: add descriptions to plugin host enable toggles

packages/plugin-sdk/schema/manifest.schema.json

@@ -690,6 +690,10 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "enableDescriptionKey": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "fields": {
                   "type": "array",
                   "items": {

packages/plugin-sdk/src/manifest.ts

@@ -269,6 +269,7 @@ export interface PluginHostSettingsContribution {
   /** Boolean field rendered first, gating the rest of the section. */
   enableKey?: string;
   enableLabelKey?: string;
+  enableDescriptionKey?: string;
   /** What the enable switch reads before a host saves it. Off by default. */
   enableDefault?: boolean;
   /** Host editor strip the generated tab sits in. Defaults to "top". */
@@ -1143,6 +1144,7 @@ function validateSettings(settings: unknown, errors: string[]): void {
       [
         "enableKey",
         "enableLabelKey",
+        "enableDescriptionKey",
         "enableDefault",
         "editorGroup",
         "editorOrder",
@@ -1162,6 +1164,13 @@ function validateSettings(settings: unknown, errors: string[]): void {
       // An enable switch with no label is a blank row in the host editor.
       requireString(host.enableLabelKey, `${at}.enableLabelKey`, errors);
     }
+    if ("enableDescriptionKey" in host) {
+      requireString(
+        host.enableDescriptionKey,
+        `${at}.enableDescriptionKey`,
+        errors,
+      );
+    }
     if ("enableDefault" in host && typeof host.enableDefault !== "boolean") {
       errors.push(`${at}.enableDefault must be a boolean`);
     }

plugins/docker/locales/en.json

@@ -123,7 +123,8 @@
   "settings": {
     "host": {
       "enable": {
-        "label": "Enable Docker"
+        "label": "Enable Docker",
+        "description": "Manage containers on this host."
       },
       "containerRuntime": {
         "label": "Container Runtime",

plugins/docker/manifest.json

@@ -57,6 +57,7 @@
         "editorOrder": 30,
         "enableKey": "enableDocker",
         "enableLabelKey": "settings.host.enable.label",
+        "enableDescriptionKey": "settings.host.enable.description",
         "fields": [
           {
             "key": "containerRuntime",

plugins/file-manager/locales/en.json

@@ -12,7 +12,8 @@
   "settings": {
     "host": {
       "enable": {
-        "label": "Enable File Manager"
+        "label": "Enable File Manager",
+        "description": "Browse and edit files on this host over SFTP."
       },
       "defaultPath": {
         "label": "Default Path"

plugins/file-manager/manifest.json

@@ -75,6 +75,7 @@
         "editorOrder": 60,
         "enableKey": "enableFileManager",
         "enableLabelKey": "settings.host.enable.label",
+        "enableDescriptionKey": "settings.host.enable.description",
         "enableDefault": true,
         "fields": [
           {

plugins/session-recording/locales/en.json

@@ -21,7 +21,8 @@
     },
     "host": {
       "enable": {
-        "label": "Enable session recording"
+        "label": "Enable session recording",
+        "description": "Record terminal output for this host so you can play it back or download it later."
       }
     }
   },

plugins/session-recording/manifest.json

@@ -63,6 +63,7 @@
         "editorOrder": 85,
         "enableKey": "enableSessionRecording",
         "enableLabelKey": "settings.host.enable.label",
+        "enableDescriptionKey": "settings.host.enable.description",
         "fields": []
       }
     },

plugins/ssh-terminal/manifest.json

@@ -220,6 +220,7 @@
         "editorOrder": 12,
         "enableKey": "enableTerminal",
         "enableLabelKey": "settings.host.enableTerminal.label",
+        "enableDescriptionKey": "settings.host.enableTerminal.description",
         "enableDefault": true,
         "fields": [
           {

plugins/tmux-monitor/locales/en.json

@@ -20,7 +20,8 @@
   "settings": {
     "host": {
       "enable": {
-        "label": "Enable Tmux Monitor"
+        "label": "Enable Tmux Monitor",
+        "description": "Watch and attach to tmux sessions running on this host."
       }
     }
   },

plugins/tmux-monitor/manifest.json

@@ -50,6 +50,7 @@
       "host": {
         "enableKey": "enableTmuxMonitor",
         "enableLabelKey": "settings.host.enable.label",
+        "enableDescriptionKey": "settings.host.enable.description",
         "fields": []
       }
     },

plugins/tunnels/locales/en.json

@@ -153,7 +153,8 @@
   "settings": {
     "host": {
       "enable": {
-        "label": "Enable tunnels"
+        "label": "Enable tunnels",
+        "description": "Set up SSH tunnels through this host."
       }
     }
   }

plugins/tunnels/manifest.json

@@ -71,6 +71,7 @@
       "host": {
         "enableKey": "enableTunnel",
         "enableLabelKey": "settings.host.enable.label",
+        "enableDescriptionKey": "settings.host.enable.description",
         "fields": [
           {
             "key": "tunnelConnections",

src/backend/plugins/settings.ts

@@ -175,6 +175,7 @@ export function declaredFields(
           key: host.enableKey,
           type: "boolean",
           labelKey: host.enableLabelKey,
+          descriptionKey: host.enableDescriptionKey,
           default: host.enableDefault ?? false,
         },
       ]

src/backend/tests/plugins/settings-manifest.test.ts

@@ -301,6 +301,21 @@ describe("contributes.settings", () => {
     expect(errors.join(" ")).toContain("enableLabelKey");
   });
 
+  it("accepts an enableDescriptionKey and rejects an empty one", () => {
+    const host = { enableKey: "enableThing", enableLabelKey: "k", fields: [] };
+
+    expect(
+      validateManifest(
+        withSettings({ host: { ...host, enableDescriptionKey: "d" } }),
+      ),
+    ).toEqual([]);
+    expect(
+      validateManifest(
+        withSettings({ host: { ...host, enableDescriptionKey: "" } }),
+      ).join(" "),
+    ).toContain("enableDescriptionKey");
+  });
+
   it("rejects a key that would not be index-safe", () => {
     const errors = validateManifest(
       withSettings({

src/backend/tests/plugins/settings.test.ts

@@ -183,13 +183,18 @@ describe("declaredFields", () => {
       host: {
         enableKey: "enableThing",
         enableLabelKey: "k",
+        enableDescriptionKey: "d",
         fields: [{ key: "port", type: "number", labelKey: "k" }],
       },
     });
 
     const fields = declaredFields(withHost, "host");
     expect(fields.map((f) => f.key)).toEqual(["enableThing", "port"]);
-    expect(fields[0]).toMatchObject({ type: "boolean", default: false });
+    expect(fields[0]).toMatchObject({
+      type: "boolean",
+      default: false,
+      descriptionKey: "d",
+    });
   });
 
   it("finds a field by key", () => {

src/ui/api/plugins-api.ts

@@ -41,6 +41,7 @@ export interface PluginSettingsField {
 export interface PluginHostSettingsContribution {
   enableKey?: string;
   enableLabelKey?: string;
+  enableDescriptionKey?: string;
   enableDefault?: boolean;
   editorGroup?: "top" | "ssh";
   editorOrder?: number;

src/ui/settings/HostPluginSections.tsx

@@ -192,6 +192,7 @@ function HostPluginSection({
             key: enableKey,
             type: "boolean",
             labelKey: host.enableLabelKey,
+            descriptionKey: host.enableDescriptionKey,
           }}
           values={shown}
           setValue={setValue}