feat(FN-2493): add plugin add alias and normalize install guidance

- Route "fn plugin add" to the plugin install handler and update CLI help/usage text to document the alias
- Add bin routing tests that cover plugin add/install parity and updated error/help messaging
- Update getting-started, settings reference, and runtime plugin READMEs to standardize plugin installation examples
- Add a patch changeset for @runfusion/fusion and apply DirectoryPicker/PluginManager design-token styling refinements

.changeset/plugin-add-install-alias.md

@@ -0,0 +1,5 @@
+---
+"@runfusion/fusion": patch
+---
+
+Add `fn plugin add` as a backward-compatible alias for `fn plugin install`, and update plugin command help text to advertise the alias while keeping `install` as the canonical command.

docs/getting-started.md

@@ -27,7 +27,7 @@ The Paperclip Runtime Plugin (`fusion-plugin-paperclip-runtime`) provides an alt
 To install the plugin:
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-paperclip-runtime
+fn plugin install ./plugins/fusion-plugin-paperclip-runtime
 ```
 
 After installation, select the Paperclip runtime for an agent by setting `runtimeHint` in the agent's `runtimeConfig`:
@@ -51,7 +51,7 @@ The Hermes Runtime Plugin (`fusion-plugin-hermes-runtime`) registers an experime
 Install the plugin:
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-hermes-runtime
+fn plugin install ./plugins/fusion-plugin-hermes-runtime
 ```
 
 Configure an agent to use Hermes:
@@ -77,7 +77,7 @@ The OpenClaw Runtime Plugin (`fusion-plugin-openclaw-runtime`) registers an expe
 Install the plugin:
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-openclaw-runtime
+fn plugin install ./plugins/fusion-plugin-openclaw-runtime
 ```
 
 Configure an agent to use OpenClaw:

docs/settings-reference.md

@@ -300,9 +300,9 @@ To use plugin-provided runtimes like Paperclip, Hermes, or OpenClaw:
 1. Install one or more runtime plugins:
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-paperclip-runtime
+fn plugin install ./plugins/fusion-plugin-paperclip-runtime
-fn plugin add ./plugins/fusion-plugin-hermes-runtime
+fn plugin install ./plugins/fusion-plugin-hermes-runtime
-fn plugin add ./plugins/fusion-plugin-openclaw-runtime
+fn plugin install ./plugins/fusion-plugin-openclaw-runtime
 ```
 
 2. Create agents with the appropriate `runtimeConfig`:

packages/cli/src/__tests__/bin.test.ts

@@ -83,6 +83,13 @@ const commandMocks = vi.hoisted(() => ({
   runMessageRead: vi.fn(),
   runMessageDelete: vi.fn(),
   runAgentMailbox: vi.fn(),
+
+  runPluginList: vi.fn(),
+  runPluginInstall: vi.fn(),
+  runPluginUninstall: vi.fn(),
+  runPluginEnable: vi.fn(),
+  runPluginDisable: vi.fn(),
+  runPluginCreate: vi.fn(),
 }));
 
 vi.mock("../commands/dashboard.js", () => ({ runDashboard: commandMocks.runDashboard }));
@@ -187,6 +194,18 @@ vi.mock("../commands/message.js", () => ({
   runAgentMailbox: commandMocks.runAgentMailbox,
 }));
 
+vi.mock("../commands/plugin.js", () => ({
+  runPluginList: commandMocks.runPluginList,
+  runPluginInstall: commandMocks.runPluginInstall,
+  runPluginUninstall: commandMocks.runPluginUninstall,
+  runPluginEnable: commandMocks.runPluginEnable,
+  runPluginDisable: commandMocks.runPluginDisable,
+}));
+
+vi.mock("../commands/plugin-scaffold.js", () => ({
+  runPluginCreate: commandMocks.runPluginCreate,
+}));
+
 const originalArgv = process.argv;
 const originalExit = process.exit;
 const originalPiPackageDir = process.env.PI_PACKAGE_DIR;
@@ -370,6 +389,33 @@ describe("bin command routing and fallbacks", () => {
     expect(commandMocks.runMessageOutbox).toHaveBeenCalledWith("demo");
   });
 
+  it("routes plugin install and add alias to the same install handler", async () => {
+    await runBin(["plugin", "install", "fusion-plugin-hermes-runtime", "-P", "demo"]);
+    await runBin(["plugin", "add", "fusion-plugin-hermes-runtime", "-P", "demo"]);
+
+    expect(commandMocks.runPluginInstall).toHaveBeenNthCalledWith(1, "fusion-plugin-hermes-runtime", {
+      projectName: "demo",
+    });
+    expect(commandMocks.runPluginInstall).toHaveBeenNthCalledWith(2, "fusion-plugin-hermes-runtime", {
+      projectName: "demo",
+    });
+  });
+
+  it("errors when plugin install source is missing", async () => {
+    await expect(runBin(["plugin", "add"])).rejects.toThrow("process.exit:1");
+    expect(errorSpy).toHaveBeenCalledWith(
+      "Usage: fn plugin install <path-or-package> (alias: fn plugin add <path-or-package>)",
+    );
+  });
+
+  it("shows plugin help guidance with install/add alias on unknown plugin subcommand", async () => {
+    await expect(runBin(["plugin", "oops"])).rejects.toThrow("process.exit:1");
+    expect(errorSpy).toHaveBeenCalledWith("Unknown subcommand: plugin oops");
+    expect(logSpy).toHaveBeenCalledWith(
+      "Try: fn plugin list | install | add (alias for install) | uninstall | enable | disable | create",
+    );
+  });
+
   it("routes node add with typed option parsing", async () => {
     await runBin([
       "node",

packages/cli/src/bin.ts

@@ -306,7 +306,8 @@ Usage:
   fn backup --restore <file> Restore database from a backup file
   fn backup --cleanup        Remove old backups exceeding retention limit
   fn plugin list | ls                List installed plugins
-  fn plugin install <path>           Install a plugin from path
+  fn plugin install <path-or-package> Install a plugin from path or package
+  fn plugin add <path-or-package>     Alias for plugin install
   fn plugin uninstall <id> [--force] Uninstall a plugin
   fn plugin enable <id>             Enable a plugin
   fn plugin disable <id>             Disable a plugin
@@ -1222,9 +1223,13 @@ async function main() {
           case "ls":
             await runPluginList(projectName);
             break;
-          case "install": {
+          case "install":
+          case "add": {
             const source = args[2];
-            if (!source) { console.error("Usage: fn plugin install <path-or-package>"); process.exit(1); }
+            if (!source) {
+              console.error("Usage: fn plugin install <path-or-package> (alias: fn plugin add <path-or-package>)");
+              process.exit(1);
+            }
             await runPluginInstall(source, { projectName });
             break;
           }
@@ -1255,7 +1260,7 @@ async function main() {
           }
           default:
             console.error(`Unknown subcommand: plugin ${sub || ""}`);
-            console.log("Try: fn plugin list | install | uninstall | enable | disable | create");
+            console.log("Try: fn plugin list | install | add (alias for install) | uninstall | enable | disable | create");
             process.exit(1);
         }
         break;

packages/dashboard/app/components/DirectoryPicker.css

@@ -16,34 +16,8 @@
 }
 
 .directory-picker-browse-btn {
-  display: inline-flex;
+  flex-shrink: 0;
-  align-items: center;
-  gap: 6px;
-  padding: 8px 14px;
-  background: var(--surface);
-  border: 1px solid var(--border);
-  border-radius: var(--radius-md);
-  color: var(--text);
-  font-size: 13px;
-  cursor: pointer;
   white-space: nowrap;
-  transition:
-    background-color var(--transition-fast),
-    border-color var(--transition-fast);
-}
-
-.directory-picker-browse-btn:hover {
-  background: var(--card-hover);
-  border-color: var(--text-dim);
-}
-
-.directory-picker-browse-btn:focus-visible {
-  outline: none;
-  box-shadow: var(--focus-ring-strong);
-}
-
-.directory-picker-browse-btn:active {
-  transform: scale(0.97);
 }
 
 .directory-picker-browser {
@@ -59,22 +33,20 @@
 .directory-picker-breadcrumbs {
   display: flex;
   align-items: center;
-  gap: 2px;
+  gap: var(--space-xs);
   padding: var(--space-sm) var(--space-md);
   background: var(--surface);
   border-bottom: 1px solid var(--border);
   overflow-x: auto;
   white-space: nowrap;
-  font-size: 12px;
 }
 
 .directory-picker-breadcrumb {
   background: none;
   border: none;
-  padding: 2px 4px;
+  padding: var(--space-xs);
   border-radius: var(--radius-sm);
   color: var(--todo);
-  font-size: 12px;
   cursor: pointer;
   font-family: var(--font-mono);
 }
@@ -84,6 +56,11 @@
   text-decoration: underline;
 }
 
+.directory-picker-breadcrumb:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring-strong);
+}
+
 .directory-picker-breadcrumb-item {
   display: inline-flex;
   align-items: center;
@@ -104,28 +81,22 @@
 
 .directory-picker-up-btn,
 .directory-picker-hidden-toggle {
-  display: inline-flex;
-  align-items: center;
-  gap: var(--space-xs);
-  padding: var(--space-xs) var(--space-sm);
-  background: none;
-  border: 1px solid transparent;
-  border-radius: var(--radius-sm);
   color: var(--text-muted);
-  font-size: 11px;
-  cursor: pointer;
-  transition: all var(--transition-fast);
 }
 
 .directory-picker-up-btn:hover,
 .directory-picker-hidden-toggle:hover {
-  background: var(--surface);
-  border-color: var(--border);
   color: var(--text);
 }
 
+.directory-picker-up-btn:focus-visible,
+.directory-picker-hidden-toggle:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring-strong);
+}
+
 .directory-picker-entries {
-  max-height: 240px;
+  max-height: calc(var(--space-2xl) * 8);
   overflow-y: auto;
   padding: var(--space-xs) 0;
 }
@@ -135,11 +106,10 @@
   align-items: center;
   gap: var(--space-sm);
   width: 100%;
-  padding: 6px var(--space-md);
+  padding: var(--space-xs) var(--space-md);
   background: none;
   border: none;
   color: var(--text);
-  font-size: 13px;
   cursor: pointer;
   text-align: left;
   transition: background-color var(--transition-fast);
@@ -149,6 +119,11 @@
   background: var(--card-hover);
 }
 
+.directory-picker-entry:focus-visible {
+  outline: none;
+  box-shadow: var(--focus-ring-strong);
+}
+
 .directory-picker-entry-icon {
   color: var(--todo);
   flex-shrink: 0;
@@ -175,7 +150,6 @@
   gap: var(--space-sm);
   padding: var(--space-xl);
   color: var(--text-muted);
-  font-size: 13px;
 }
 
 .directory-picker-error {
@@ -184,11 +158,10 @@
   gap: var(--space-sm);
   padding: var(--space-md);
   margin: var(--space-sm) var(--space-md);
-  background: rgba(248, 81, 73, 0.1);
+  background: color-mix(in srgb, var(--color-error) 10%, transparent);
-  border: 1px solid var(--error);
+  border: 1px solid var(--color-error);
   border-radius: var(--radius-md);
-  color: var(--error);
+  color: var(--color-error);
-  font-size: 13px;
 }
 
 .directory-picker-actions {
@@ -207,7 +180,6 @@
   overflow: hidden;
   text-overflow: ellipsis;
   white-space: nowrap;
-  font-size: 12px;
   font-family: var(--font-mono);
   color: var(--text-muted);
 }

packages/dashboard/app/components/DirectoryPicker.tsx

@@ -108,7 +108,7 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
       <div className="directory-picker-input-row">
         <input
           type="text"
-          className="directory-picker-input"
+          className="input directory-picker-input"
           value={value}
           onChange={(e) => onChange(e.target.value)}
           onKeyDown={onInputKeyDown}
@@ -116,7 +116,7 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
         />
         <button
           type="button"
-          className="directory-picker-browse-btn"
+          className="btn btn-secondary btn-sm directory-picker-browse-btn"
           onClick={handleToggleBrowser}
           aria-label={browser.isOpen ? "Close directory browser" : "Browse directories"}
         >
@@ -130,6 +130,7 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
           {/* Breadcrumbs */}
           <div className="directory-picker-breadcrumbs">
             <button
+              type="button"
               className="directory-picker-breadcrumb"
               onClick={() => handleNavigate("/")}
               title="Root"
@@ -142,6 +143,7 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
                 <span key={segPath} className="directory-picker-breadcrumb-item">
                   <ChevronRight size={12} className="directory-picker-breadcrumb-sep" />
                   <button
+                    type="button"
                     className="directory-picker-breadcrumb"
                     onClick={() => handleNavigate(segPath)}
                     title={segPath}
@@ -157,7 +159,8 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
           <div className="directory-picker-toolbar">
             {browser.parentPath && (
               <button
-                className="directory-picker-up-btn"
+                type="button"
+                className="btn btn-sm btn-secondary directory-picker-up-btn"
                 onClick={() => handleNavigate(browser.parentPath!)}
                 aria-label="Go to parent directory"
                 title="Parent directory"
@@ -167,7 +170,8 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
               </button>
             )}
             <button
-              className="directory-picker-hidden-toggle"
+              type="button"
+              className="btn btn-sm btn-secondary directory-picker-hidden-toggle"
               onClick={handleToggleHidden}
               aria-label={browser.showHidden ? "Hide hidden directories" : "Show hidden directories"}
               title={browser.showHidden ? "Hide hidden" : "Show hidden"}
@@ -195,6 +199,7 @@ export function DirectoryPicker({ value, onChange, placeholder, onInputKeyDown,
               ) : (
                 browser.entries.map((entry) => (
                   <button
+                    type="button"
                     key={entry.path}
                     className="directory-picker-entry"
                     onClick={() => handleNavigate(entry.path)}

packages/dashboard/app/components/PluginManager.css

@@ -43,7 +43,7 @@
   border-radius: var(--radius-sm);
   background: var(
     --bg-tertiary,
-    color-mix(in srgb, var(--text-muted) 18%, transparent)
+    color-mix(in srgb, var(--text-muted) 12%, transparent)
   );
   font-size: 0.85em;
 }

packages/dashboard/app/components/__tests__/DirectoryPicker.test.tsx

@@ -52,7 +52,12 @@ describe("DirectoryPicker", () => {
 
     const input = screen.getByPlaceholderText("Select a directory") as HTMLInputElement;
     expect(input.value).toBe("/some/path");
-    expect(screen.getByText("Browse")).toBeDefined();
+    expect(input.classList.contains("input")).toBe(true);
+
+    const browseButton = screen.getByRole("button", { name: "Browse directories" });
+    expect(browseButton.classList.contains("btn")).toBe(true);
+    expect(browseButton.classList.contains("btn-secondary")).toBe(true);
+    expect(browseButton.classList.contains("btn-sm")).toBe(true);
   });
 
   it("calls onChange when typing in the input", () => {

plugins/fusion-plugin-hermes-runtime/README.md

@@ -23,7 +23,7 @@ cp -r fusion-plugin-hermes-runtime ~/.fusion/plugins/
 ### Option 2: Install via CLI
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-hermes-runtime
+fn plugin install ./plugins/fusion-plugin-hermes-runtime
 ```
 
 ## Runtime Metadata

plugins/fusion-plugin-openclaw-runtime/README.md

@@ -23,7 +23,7 @@ cp -r fusion-plugin-openclaw-runtime ~/.fusion/plugins/
 ### Option 2: Install via CLI
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-openclaw-runtime
+fn plugin install ./plugins/fusion-plugin-openclaw-runtime
 ```
 
 ## Runtime Metadata

plugins/fusion-plugin-paperclip-runtime/README.md

@@ -36,7 +36,7 @@ pi
 Install the plugin as a local plugin:
 
 ```bash
-fn plugin add ./plugins/fusion-plugin-paperclip-runtime
+fn plugin install ./plugins/fusion-plugin-paperclip-runtime
 ```
 
 Verify installation: