fix(docs): correct plugin documentation to match implementation

Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>

Author: factory-arman

docs/cli/configuration/plugins.mdx

@@ -1,22 +1,21 @@
 ---
 title: Plugins
-description: Extend Droid with shareable packages of skills, commands, hooks, and tools.
-keywords: ['plugins', 'extensions', 'marketplace', 'skills', 'commands', 'hooks', 'mcp', 'shareable']
+description: Extend Droid with shareable packages of skills, commands, and tools.
+keywords: ['plugins', 'extensions', 'marketplace', 'skills', 'commands', 'mcp', 'shareable']
 ---
 
-Plugins let you extend Droid with custom functionality that can be shared across projects and teams. A plugin bundles skills, slash commands, hooks, agents, and MCP servers into a single, distributable package.
+Plugins let you extend Droid with custom functionality that can be shared across projects and teams. A plugin bundles skills, slash commands, agents, and MCP servers into a single, distributable package.
 
 ## What are plugins?
 
-Plugins are directories containing a manifest file (`.factory-plugin/plugin.json`) and optional components like skills, commands, hooks, and agents. Unlike standalone configuration in `.factory/`, plugins are designed for sharing and distribution.
+Plugins are directories containing a manifest file (`.factory-plugin/plugin.json`) and optional components like skills, commands, and agents. Unlike standalone configuration in `.factory/`, plugins are designed for sharing and distribution.
 
 **Plugin components:**
 
 | Component | Purpose | Invocation |
 |-----------|---------|------------|
 | **Skills** | Reusable capabilities with instructions and tools | Model-invoked automatically based on task |
-| **Commands** | Slash commands for specific workflows | User-invoked via `/plugin-name:command` |
-| **Hooks** | Event handlers for automation | Triggered by events (PreToolUse, PostToolUse, etc.) |
+| **Commands** | Slash commands for specific workflows | User-invoked via `/command-name` |
 | **Agents** | Specialized subagent definitions | Called via Task tool |
 | **MCP Servers** | External tool integrations | Available as tools when plugin is active |
 
@@ -29,44 +28,49 @@ Plugins are directories containing a manifest file (`.factory-plugin/plugin.json
 
 Start with standalone configuration in `.factory/` for quick iteration, then convert to a plugin when you're ready to share.
 
-## Installing plugins
+## Managing plugins
 
-### From a marketplace
+Droid provides two ways to manage plugins:
 
-Register a marketplace first, then install plugins from it:
+### Interactive UI (recommended)
 
-```bash
-# Add a marketplace
-/plugin marketplace add owner/repo
+Use the `/plugins` slash command to open the plugin manager:
 
-# Install a plugin
-/plugin install plugin-name@marketplace-name
 ```
-
-### From a local directory
-
-Test plugins during development with the `--plugin-dir` flag:
-
-```bash
-droid --plugin-dir ./my-plugin
+/plugins
 ```
 
-### Managing plugins
+This opens a tabbed interface:
+- **Browse** - View and install plugins from registered marketplaces
+- **Installed** - Manage installed plugins (view info, update, uninstall)
+- **Marketplaces** - Add, update, or remove marketplaces
 
-```bash
-# List installed plugins
-/plugin
+**Navigation:**
+- Left/Right arrows: Switch between tabs
+- Up/Down arrows: Navigate within a tab
+- Enter: Select/confirm
+- Escape: Go back or close
 
-# Disable a plugin
-/plugin disable plugin-name@marketplace-name
+### CLI commands (for scripting)
 
-# Re-enable a plugin
-/plugin enable plugin-name@marketplace-name
+For automation, use CLI commands from your shell (not as slash commands):
 
-# Uninstall a plugin
-/plugin uninstall plugin-name@marketplace-name
+```bash
+# Marketplace management
+droid plugin marketplace add <url>
+droid plugin marketplace remove <name>
+droid plugin marketplace list
+droid plugin marketplace update [name]
+
+# Plugin management
+droid plugin install <plugin@marketplace> [--scope user|project]
+droid plugin uninstall <plugin@marketplace> [--scope user|project]
+droid plugin update [plugin@marketplace] [--scope user|project]
+droid plugin list [--scope user|project]
 ```
 
+Plugin IDs use the format `pluginName@marketplaceName` (e.g., `security-guidance@claude-plugins-official`).
+
 ## Plugin structure
 
 Every plugin follows this directory structure:
@@ -80,16 +84,14 @@ my-plugin/
 ├── skills/                   # Agent skills (optional)
 │   └── my-skill/
 │       └── SKILL.md
-├── agents/                   # Subagent definitions (optional)
+├── droids/                   # Subagent definitions (optional)
 │   └── my-agent.md
-├── hooks/                    # Event handlers (optional)
-│   └── hooks.json
-├── .mcp.json                 # MCP server configs (optional)
+├── mcp.json                  # MCP server configs (optional)
 └── README.md                 # Documentation
 ```
 
 <Warning>
-Don't put `commands/`, `skills/`, `agents/`, or `hooks/` inside the `.factory-plugin/` directory. Only `plugin.json` goes inside `.factory-plugin/`. All other directories must be at the plugin root level.
+Don't put `commands/`, `skills/`, or `droids/` inside the `.factory-plugin/` directory. Only `plugin.json` goes inside `.factory-plugin/`. All other directories must be at the plugin root level.
 </Warning>
 
 ### Plugin manifest
@@ -109,7 +111,7 @@ The manifest at `.factory-plugin/plugin.json` defines your plugin's identity:
 
 | Field | Purpose |
 |-------|---------|
-| `name` | Unique identifier and skill namespace. Commands are prefixed with this (e.g., `/my-plugin:command`). |
+| `name` | Unique identifier for the plugin. |
 | `description` | Shown in the plugin manager when browsing or installing. |
 | `version` | Track releases using semantic versioning. |
 | `author` | Optional. Helpful for attribution. |
@@ -120,63 +122,99 @@ When installing plugins, you choose an installation scope:
 
 | Scope | Location | Visibility |
 |-------|----------|------------|
-| **User** | `~/.factory/plugins/` | Available across all your projects |
-| **Project** | `.factory/settings.json` | Shared with teammates via git |
-| **Local** | Local config only | Your machine, this project only |
+| **User** | `~/.factory/` | Available across all your projects |
+| **Project** | `<project>/.factory/` | Shared with teammates via git |
+
+<Note>
+**Org scope**: Plugins enabled via organization managed settings are automatically installed with `org` scope. You cannot manually set org scope.
+</Note>
+
+A plugin can only exist at one scope. To change scope, uninstall first and reinstall.
+
+## Version tracking
+
+Plugins are versioned by Git commit hash, not semantic version. When you update a plugin, Droid fetches the latest commit from the marketplace repository.
+
+<Note>
+Version pinning is not supported. Updates always fetch the latest version from the marketplace.
+</Note>
 
 ## Marketplaces
 
 Marketplaces are catalogs of plugins that you can browse and install from.
 
 ### Adding marketplaces
 
+Via UI: `/plugins` → Marketplaces tab → "Add new marketplace" → enter URL
+
+Via CLI:
+
 ```bash
 # From GitHub
-/plugin marketplace add owner/repo
+droid plugin marketplace add https://github.com/owner/repo
 
 # From other Git hosts
-/plugin marketplace add https://gitlab.com/company/plugins.git
+droid plugin marketplace add https://gitlab.com/company/plugins.git
 
-# From local path
-/plugin marketplace add ./my-marketplace
+# From local path (for development)
+droid plugin marketplace add /path/to/local/marketplace
 ```
 
 ### Managing marketplaces
 
-```bash
-# List all marketplaces
-/plugin marketplace list
+Via UI: `/plugins` → Marketplaces tab → select marketplace → choose action (Update, Disable auto-update, Delete)
 
-# Update marketplace listings
-/plugin marketplace update marketplace-name
+Via CLI:
 
-# Remove a marketplace
-/plugin marketplace remove marketplace-name
+```bash
+droid plugin marketplace list
+droid plugin marketplace update [marketplace-name]
+droid plugin marketplace remove <marketplace-name>
 ```
 
+<Note>
+Removing a marketplace does not uninstall plugins from that marketplace. Installed plugins remain functional from cache.
+</Note>
+
 ### Team marketplaces
 
-Configure automatic marketplace installation for your team by adding to `.factory/settings.json`:
+Configure automatic marketplace and plugin installation by adding to `.factory/settings.json`:
 
 ```json
 {
-  "extraKnownMarketplaces": [
-    "your-org/internal-plugins"
-  ],
-  "enabledPlugins": [
-    "code-standards@your-org-internal-plugins"
-  ]
+  "extraKnownMarketplaces": {
+    "your-org-internal-plugins": {
+      "source": {
+        "source": "github",
+        "repo": "your-org/internal-plugins"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "code-standards@your-org-internal-plugins": true
+  }
 }
 ```
 
+When Droid starts, it automatically:
+1. Registers any marketplaces from `extraKnownMarketplaces` that aren't already registered
+2. Installs any plugins from `enabledPlugins` that aren't already installed
+
+The installation scope depends on where the setting is defined:
+- Org-managed settings → `org` scope
+- User settings → `user` scope
+- Project settings → `project` scope
+
 ## Discovering plugins
 
 ### Official Factory plugins
 
-Factory maintains an official plugin marketplace at `Factory-AI/factory-plugins` with curated plugins:
+Factory maintains an official plugin marketplace at `Factory-AI/factory-plugins` with curated plugins.
+
+Add via `/plugins` UI or CLI:
 
 ```bash
-/plugin marketplace add Factory-AI/factory-plugins
+droid plugin marketplace add https://github.com/Factory-AI/factory-plugins
 ```
 
 **Available plugins:**
@@ -186,11 +224,11 @@ Factory maintains an official plugin marketplace at `Factory-AI/factory-plugins`
 | **droid-evolved** | Skills for continuous learning: session navigation, human writing, skill creation, visual design, frontend design, browser automation |
 | **security-engineer** | Security review, threat modeling, commit scanning, and vulnerability validation |
 
-Install with:
+Install via `/plugins` UI (Browse tab) or CLI:
 
 ```bash
-/plugin install droid-evolved@factory-plugins
-/plugin install security-engineer@factory-plugins
+droid plugin install droid-evolved@factory-plugins
+droid plugin install security-engineer@factory-plugins
 ```
 
 ### Community plugins
@@ -215,15 +253,15 @@ Droid is compatible with plugins built for Claude Code. If you find a Claude Cod
 
 <CardGroup cols={2}>
   <Card title="Building plugins" href="/guides/building/building-plugins" icon="hammer">
-    Learn how to create your own plugins with skills, commands, and hooks.
+    Learn how to create your own plugins with skills and commands.
   </Card>
   <Card title="Skills" href="/cli/configuration/skills" icon="wand-magic-sparkles">
     Understand how skills work and how to create them.
   </Card>
   <Card title="Custom commands" href="/cli/configuration/custom-slash-commands" icon="terminal">
     Create user-invoked slash commands.
   </Card>
-  <Card title="Hooks" href="/cli/configuration/hooks-guide" icon="bolt">
-    Automate workflows with event-driven hooks.
+  <Card title="Custom Droids" href="/cli/configuration/custom-droids" icon="robot">
+    Create specialized subagents for your plugins.
   </Card>
 </CardGroup>