fusion/docs/plugin-management.md

Plugin Management Guide

← Docs index

This guide is the canonical end-user workflow for managing Fusion plugins across the full lifecycle: discover, install, enable/disable, configure, use, update, uninstall, and troubleshoot.

Plugin author/developer details (manifest, SDK APIs, hooks, routes, and runtime implementation) live in Plugin Authoring.

1) Plugin basics

Fusion uses two plugin surfaces in Settings:

• Fusion Plugins (Settings → Plugins → Fusion Plugins): extend Fusion behavior (tools, routes, UI slots/views, runtimes)
• Pi Extensions (Settings → Plugins → Pi Extensions): manage pi extension packages/sources

These are related but different systems; do not treat Pi Extensions as Fusion Plugins.

Lifecycle states

State	Meaning
installed	Registered but not started yet
started	Loaded and active
stopped	Disabled/stopped
error	Failed to load or failed at runtime

Common locations

Location	Purpose
~/.fusion/plugins/	Default local plugin install location
Bundled plugin manifests (shipped with Fusion)	Discoverable/installable from Plugin Manager
Custom local path (absolute path)	Install plugin from a local directory

2) Discover available plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Review bundled entries in Bundled Plugins and currently installed entries.
3. Check each plugin’s status/state in the manager.

Expected outcome: You can see what is already installed, what is bundled and available, and each plugin’s current lifecycle state.

CLI

1. Run:

   fn plugin list
   

2. Review installed plugin IDs and status.

Expected outcome: You have a terminal view of installed plugins for scripting/remote workflows.

3) Install plugins

Install bundled plugin (dashboard)

1. Go to Settings → Plugins → Fusion Plugins.
2. In Bundled Plugins, click Install for the plugin.

Expected outcome: Plugin is registered and appears with an initial state (typically installed then started when enabled/loaded).

Install from local path (dashboard)

1. Go to Settings → Plugins → Fusion Plugins.
2. Use Install and provide an absolute plugin path.
3. Confirm installation.

Expected outcome: Plugin is added to your local plugin set and appears in the manager.

Install from local path (CLI)

1. Run:

   fn plugin install <path>
   

2. Confirm the plugin appears in:

   fn plugin list
   

Expected outcome: Plugin is installed from the specified path and visible in plugin listings.

4) Enable, disable, and reload plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Toggle plugin enable/disable controls.
3. Use reload controls when available.

Expected outcome: Plugin transitions between runtime states (started / stopped) and reflects transitions in the manager.

CLI

fn plugin enable <id>
fn plugin disable <id>

Expected outcome: Plugin is enabled or disabled by ID.

5) Configure plugin settings

1. Go to Settings → Plugins → Fusion Plugins.
2. Open the plugin settings editor (gear/settings action).
3. Update fields and save.

Expected outcome: Plugin-defined settings are persisted and used by that plugin at runtime.

6) Verify plugin is working

After installing/enabling, verify success signals relevant to that plugin:

• New agent tools become available in runtime/tooling surfaces
• Plugin routes are reachable through plugin API paths
• Plugin UI slots/views appear in dashboard surfaces (tabs, sections, cards, nav entries)
• Runtime-providing plugins become available for runtime hint selection/usage
• Plugin state remains started (not error)

If you need capability-level details for a specific plugin, check its README and Plugin Authoring.

7) Update plugins

Fusion does not use a dedicated fn plugin update command. Update by reinstalling the desired plugin version/source.

Dashboard

1. Reinstall from the bundled entry or updated local path.
2. Re-check state and behavior in the plugin manager.

CLI

1. Re-run install against the updated source path:

   fn plugin install <path>
   

2. Confirm with:

   fn plugin list
   

Expected outcome: Updated plugin build/version is installed and operational.

8) Uninstall plugins

Dashboard

1. Open Settings → Plugins → Fusion Plugins.
2. Uninstall the target plugin.

Expected outcome: Plugin is removed from the installed list and no longer active.

CLI

1. Run:

   fn plugin uninstall <id> --force
   

2. Verify removal:

   fn plugin list
   

Expected outcome: Plugin is removed by ID.

9) Dashboard vs CLI mapping

Workflow	Dashboard path	CLI command
List installed plugins	Settings → Plugins → Fusion Plugins	fn plugin list
Install plugin	Settings → Plugins → Fusion Plugins → Install	fn plugin install <path>
Enable plugin	Settings → Plugins → Fusion Plugins → Enable toggle	fn plugin enable <id>
Disable plugin	Settings → Plugins → Fusion Plugins → Disable toggle	fn plugin disable <id>
Uninstall plugin	Settings → Plugins → Fusion Plugins → Uninstall	fn plugin uninstall <id> --force
Scaffold new plugin (authoring)	n/a (developer workflow)	fn plugin create <name>

10) Troubleshooting

Plugin is in error state

1. Open Settings → Plugins → Fusion Plugins and inspect state/transition feedback.
2. Disable then re-enable the plugin.
3. Confirm plugin source path and dependencies are valid.
4. If needed, uninstall and reinstall the plugin.

Plugin installed but features are not visible

1. Confirm plugin state is started.
2. Verify what that plugin actually contributes (tools/routes/UI/runtime) in plugin docs.
3. Confirm you are checking the correct dashboard surface (for example nav view vs settings section vs task detail slot).

Confusion between Fusion Plugins and Pi Extensions

1. Use Fusion Plugins for Fusion plugin lifecycle management.
2. Use Pi Extensions only for pi extension sources/extensions/skills/prompts/themes.

Need implementation/API details

Use Plugin Authoring for manifest fields, lifecycle hook signatures, UI/runtime contribution contracts, and SDK examples.