@phnx-labs/agents-cli 1.18.2 → 1.18.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 1.18.3
+
+**Plugins** ([#22](https://github.com/phnx-labs/agents-cli/issues/22))
+
+- `agents plugins sync` now installs plugins via Claude Code's native marketplace path — `<versionHome>/.{claude,openclaw}/plugins/marketplaces/agents-cli/plugins/<name>/` — instead of flattening contents into `~/.claude/skills/<plugin>--<skill>/`. Skills resolve as `/plugin:skill` (the documented form) instead of `/plugin--skill`. Plugins appear in Claude's `/plugins` UI under Installed and respond to `/plugin enable`, `/plugin disable`.
+- A synthetic `agents-cli` marketplace is materialized per version: `.claude-plugin/marketplace.json` is synthesized from discovered plugins, an entry is added to `<versionHome>/.claude/plugins/known_marketplaces.json`, and `settings.json#enabledPlugins["<plugin>@agents-cli"]` is flipped to `true`. Removal is symmetric — last plugin out drops the marketplace dir and the known_marketplaces entry.
+- The sync now copies the whole plugin tree verbatim (single `fs.cpSync`) instead of re-implementing per-feature merges into `settings.json`. Every Claude plugin feature — skills, commands, subagents, hooks, `.mcp.json`, `.lsp.json`, `monitors/monitors.json`, `bin/`, `settings.json` — is preserved end-to-end. `${CLAUDE_PLUGIN_ROOT}` and `${CLAUDE_PLUGIN_DATA}` are left intact so Claude can expand them at runtime; only `${user_config.*}` (agents-cli-specific) is pre-expanded in copied text files.
+- Legacy dual-dash layout from prior versions is auto-migrated at sync time — `~/.claude/skills/<plugin>--*`, `~/.claude/commands/<plugin>--*.md`, `~/.claude/agents/<plugin>--*.md`, `plugin-bin/<plugin>/`, and namespaced `mcpServers["<plugin>--*"]` entries are removed after the marketplace install succeeds.
+- `agents plugins view <name>` surfaces every feature the plugin ships: Skills, Commands, Subagents, Hooks, MCP Servers, LSP Servers, Monitors, Bin, Scripts, Settings. The `agents view <agent>@<version>` Plugins section gains MCP/LSP/Monitor/Bin/Settings counts. New `discoverPluginMcpServers`, `discoverPluginLspServers`, `discoverPluginMonitors` helpers parse `.mcp.json`, `.lsp.json`, and `monitors/monitors.json`.
+
 ## 1.18.2
 
 **Teams**

package/dist/commands/plugins.js

@@ -149,7 +149,19 @@ Examples:
         if (plugin.skills.length > 0) {
             console.log(chalk.bold('\n  Skills'));
             for (const skill of plugin.skills) {
-                console.log(`    ${chalk.cyan(`${plugin.name}:${skill}`)}`);
+                console.log(`    ${chalk.cyan(`/${plugin.name}:${skill}`)}`);
+            }
+        }
+        if (plugin.commands.length > 0) {
+            console.log(chalk.bold('\n  Commands'));
+            for (const cmd of plugin.commands) {
+                console.log(`    ${chalk.cyan(`/${plugin.name}:${cmd}`)}`);
+            }
+        }
+        if (plugin.agentDefs.length > 0) {
+            console.log(chalk.bold('\n  Subagents'));
+            for (const a of plugin.agentDefs) {
+                console.log(`    ${chalk.magenta(a)}`);
             }
         }
         if (plugin.hooks.length > 0) {
@@ -158,12 +170,40 @@ Examples:
                 console.log(`    ${chalk.yellow(hook)}`);
             }
         }
+        if (plugin.mcpServers.length > 0) {
+            console.log(chalk.bold('\n  MCP Servers'));
+            for (const s of plugin.mcpServers) {
+                console.log(`    ${chalk.green(s)}`);
+            }
+        }
+        if (plugin.lspServers.length > 0) {
+            console.log(chalk.bold('\n  LSP Servers'));
+            for (const s of plugin.lspServers) {
+                console.log(`    ${chalk.green(s)}`);
+            }
+        }
+        if (plugin.monitors.length > 0) {
+            console.log(chalk.bold('\n  Monitors'));
+            for (const m of plugin.monitors) {
+                console.log(`    ${chalk.blue(m)}`);
+            }
+        }
+        if (plugin.bin.length > 0) {
+            console.log(chalk.bold('\n  Bin'));
+            for (const b of plugin.bin) {
+                console.log(`    ${chalk.white(b)}`);
+            }
+        }
         if (plugin.scripts.length > 0) {
             console.log(chalk.bold('\n  Scripts'));
             for (const script of plugin.scripts) {
                 console.log(`    ${chalk.gray(script)}`);
             }
         }
+        if (plugin.hasSettings) {
+            console.log(chalk.bold('\n  Settings'));
+            console.log(`    ${chalk.gray('settings.json')}`);
+        }
         // Show installation status per agent version
         console.log(chalk.bold('\n  Installation Status'));
         let anyInstalled = false;
@@ -572,20 +612,24 @@ function formatPluginDetail(plugin, targets) {
         lines.push('  ' + chalk.gray('Supports: ') + supported.join(chalk.gray(' · ')));
     }
     lines.push('  ' + chalk.gray(formatPath(plugin.root)));
-    if (plugin.skills.length > 0) {
-        lines.push('');
-        lines.push(chalk.bold('  Skills'));
-        lines.push('  ' + plugin.skills.map((s) => chalk.cyan(s)).join(chalk.gray(', ')));
-    }
-    if (plugin.hooks.length > 0) {
-        lines.push('');
-        lines.push(chalk.bold('  Hooks'));
-        lines.push('  ' + plugin.hooks.map((h) => chalk.yellow(h)).join(chalk.gray(', ')));
-    }
-    if (plugin.scripts.length > 0) {
+    const section = (label, items, colorFn) => {
+        if (items.length === 0)
+            return;
         lines.push('');
-        lines.push(chalk.bold('  Scripts'));
-        lines.push('  ' + plugin.scripts.map((s) => chalk.white(s)).join(chalk.gray(', ')));
+        lines.push(chalk.bold(`  ${label}`));
+        lines.push('  ' + items.map(colorFn).join(chalk.gray(', ')));
+    };
+    section('Skills', plugin.skills.map((s) => `/${plugin.name}:${s}`), chalk.cyan);
+    section('Commands', plugin.commands.map((c) => `/${plugin.name}:${c}`), chalk.cyan);
+    section('Subagents', plugin.agentDefs, chalk.magenta);
+    section('Hooks', plugin.hooks, chalk.yellow);
+    section('MCP Servers', plugin.mcpServers, chalk.green);
+    section('LSP Servers', plugin.lspServers, chalk.green);
+    section('Monitors', plugin.monitors, chalk.blue);
+    section('Bin', plugin.bin, chalk.white);
+    section('Scripts', plugin.scripts, chalk.white);
+    if (plugin.hasSettings) {
+        section('Settings', ['settings.json'], chalk.gray);
     }
     if (targets.length > 0) {
         lines.push('');

package/dist/commands/view.js

@@ -604,19 +604,28 @@ async function showAgentResources(agentId, requestedVersion) {
             const versionStr = agentData.version ? ` (${agentData.version})` : '';
             const agentHeader = home ? termLink(agentData.agentName, home) : agentData.agentName;
             console.log(`  ${chalk.bold(agentHeader)}${chalk.gray(versionStr)}:`);
+            const pluralize = (n, singular) => `${n} ${singular}${n === 1 ? '' : 's'}`;
             for (const p of plugins) {
                 const linkedName = termLink(p.name, linkTarget(p.root));
                 const parts = [];
                 if (p.skills.length > 0)
-                    parts.push(`${p.skills.length} skill${p.skills.length === 1 ? '' : 's'}`);
+                    parts.push(pluralize(p.skills.length, 'skill'));
                 if (p.commands.length > 0)
-                    parts.push(`${p.commands.length} command${p.commands.length === 1 ? '' : 's'}`);
-                if (p.hooks.length > 0)
-                    parts.push(`${p.hooks.length} hook${p.hooks.length === 1 ? '' : 's'}`);
+                    parts.push(pluralize(p.commands.length, 'command'));
                 if (p.agentDefs.length > 0)
-                    parts.push(`${p.agentDefs.length} subagent${p.agentDefs.length === 1 ? '' : 's'}`);
-                if (p.hasMcp)
-                    parts.push('mcp');
+                    parts.push(pluralize(p.agentDefs.length, 'subagent'));
+                if (p.hooks.length > 0)
+                    parts.push(pluralize(p.hooks.length, 'hook'));
+                if (p.mcpServers.length > 0)
+                    parts.push(`${p.mcpServers.length} MCP`);
+                if (p.lspServers.length > 0)
+                    parts.push(`${p.lspServers.length} LSP`);
+                if (p.monitors.length > 0)
+                    parts.push(pluralize(p.monitors.length, 'monitor'));
+                if (p.bin.length > 0)
+                    parts.push(pluralize(p.bin.length, 'bin'));
+                if (p.hasSettings)
+                    parts.push('settings');
                 const contents = parts.length > 0 ? chalk.gray(` (${parts.join(', ')})`) : '';
                 console.log(`    ${chalk.cyan(linkedName)}${contents} ${chalk.cyan('[user]')}`);
             }

package/dist/lib/plugin-marketplace.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Native plugin marketplace install path for Claude / OpenClaw.
+ *
+ * Plugins managed by agents-cli are exposed as a synthetic local marketplace
+ * named "agents-cli" under each version's plugin directory:
+ *
+ *   <versionHome>/.{claude,openclaw}/plugins/
+ *     known_marketplaces.json            # registers the "agents-cli" marketplace
+ *     marketplaces/agents-cli/
+ *       .claude-plugin/marketplace.json  # synthesized catalog
+ *       plugins/<plugin>/                # copied plugin source
+ *
+ * Plus the version's settings.json gets `enabledPlugins["<plugin>@agents-cli"] = true`.
+ *
+ * This produces native `/plugin:skill` slash namespacing, visibility in `/plugins`,
+ * and `/plugin enable|disable` support — matching the Claude Code spec at
+ * https://code.claude.com/docs/en/plugins and /plugin-marketplaces.
+ */
+import type { AgentId, DiscoveredPlugin } from './types.js';
+export declare const MARKETPLACE_NAME = "agents-cli";
+interface MarketplacePluginEntry {
+    name: string;
+    source: string;
+    description?: string;
+    version?: string;
+    author?: {
+        name: string;
+        email?: string;
+    };
+}
+interface MarketplaceManifest {
+    $schema?: string;
+    name: string;
+    description?: string;
+    owner: {
+        name: string;
+        email?: string;
+    };
+    plugins: MarketplacePluginEntry[];
+}
+export declare function marketplaceRoot(agent: AgentId, versionHome: string): string;
+export declare function marketplaceManifestPath(agent: AgentId, versionHome: string): string;
+export declare function pluginInstallDir(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
+export declare function knownMarketplacesPath(agent: AgentId, versionHome: string): string;
+/**
+ * Copy plugin source into marketplace install dir.
+ * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ */
+export declare function copyPluginToMarketplace(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): string;
+/**
+ * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the list of
+ * plugins installed under <marketplace>/plugins/. Always run after add or remove
+ * so the manifest stays in lockstep with on-disk contents.
+ */
+export declare function syncMarketplaceManifest(agent: AgentId, versionHome: string): MarketplaceManifest | null;
+/**
+ * Register the agents-cli marketplace in known_marketplaces.json so Claude Code
+ * discovers it on startup. Idempotent: re-running just refreshes lastUpdated.
+ */
+export declare function registerMarketplace(agent: AgentId, versionHome: string): void;
+/**
+ * Drop the agents-cli marketplace entry from known_marketplaces.json.
+ * Called when the last plugin under it is removed.
+ */
+export declare function unregisterMarketplace(agent: AgentId, versionHome: string): void;
+/**
+ * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
+ * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
+ * preserving every other key.
+ */
+export declare function enablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string): void;
+/**
+ * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
+ */
+export declare function disablePluginInSettings(pluginName: string, agent: AgentId, versionHome: string): void;
+/**
+ * Remove a plugin's installed marketplace directory. Returns true if the dir
+ * existed and was removed.
+ */
+export declare function removePluginFromMarketplace(pluginName: string, agent: AgentId, versionHome: string): boolean;
+/**
+ * Return true if the marketplace has no plugins left under it.
+ */
+export declare function marketplaceIsEmpty(agent: AgentId, versionHome: string): boolean;
+/**
+ * Drop the entire marketplace directory. Called after the last plugin removal.
+ */
+export declare function removeEmptyMarketplaceDir(agent: AgentId, versionHome: string): void;
+/**
+ * Detect whether a plugin is installed via the native marketplace path.
+ */
+export declare function isInstalledInMarketplace(pluginName: string, agent: AgentId, versionHome: string): boolean;
+export {};

package/dist/lib/plugin-marketplace.js

@@ -0,0 +1,239 @@
+/**
+ * Native plugin marketplace install path for Claude / OpenClaw.
+ *
+ * Plugins managed by agents-cli are exposed as a synthetic local marketplace
+ * named "agents-cli" under each version's plugin directory:
+ *
+ *   <versionHome>/.{claude,openclaw}/plugins/
+ *     known_marketplaces.json            # registers the "agents-cli" marketplace
+ *     marketplaces/agents-cli/
+ *       .claude-plugin/marketplace.json  # synthesized catalog
+ *       plugins/<plugin>/                # copied plugin source
+ *
+ * Plus the version's settings.json gets `enabledPlugins["<plugin>@agents-cli"] = true`.
+ *
+ * This produces native `/plugin:skill` slash namespacing, visibility in `/plugins`,
+ * and `/plugin enable|disable` support — matching the Claude Code spec at
+ * https://code.claude.com/docs/en/plugins and /plugin-marketplaces.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const MARKETPLACE_NAME = 'agents-cli';
+function pluginsRootForVersion(agent, versionHome) {
+    return path.join(versionHome, `.${agent}`, 'plugins');
+}
+export function marketplaceRoot(agent, versionHome) {
+    return path.join(pluginsRootForVersion(agent, versionHome), 'marketplaces', MARKETPLACE_NAME);
+}
+export function marketplaceManifestPath(agent, versionHome) {
+    return path.join(marketplaceRoot(agent, versionHome), '.claude-plugin', 'marketplace.json');
+}
+export function pluginInstallDir(plugin, agent, versionHome) {
+    return path.join(marketplaceRoot(agent, versionHome), 'plugins', plugin.name);
+}
+export function knownMarketplacesPath(agent, versionHome) {
+    return path.join(pluginsRootForVersion(agent, versionHome), 'known_marketplaces.json');
+}
+function settingsPath(agent, versionHome) {
+    return path.join(versionHome, `.${agent}`, 'settings.json');
+}
+/**
+ * Copy plugin source into marketplace install dir.
+ * Source of truth remains ~/.agents/plugins/<name>/ — this is a per-version snapshot.
+ */
+export function copyPluginToMarketplace(plugin, agent, versionHome) {
+    const dest = pluginInstallDir(plugin, agent, versionHome);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (fs.existsSync(dest)) {
+        fs.rmSync(dest, { recursive: true, force: true });
+    }
+    fs.cpSync(plugin.root, dest, { recursive: true, dereference: false });
+    return dest;
+}
+/**
+ * Re-synthesize <marketplace>/.claude-plugin/marketplace.json from the list of
+ * plugins installed under <marketplace>/plugins/. Always run after add or remove
+ * so the manifest stays in lockstep with on-disk contents.
+ */
+export function syncMarketplaceManifest(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    const pluginsDir = path.join(root, 'plugins');
+    if (!fs.existsSync(pluginsDir))
+        return null;
+    const entries = [];
+    for (const entry of fs.readdirSync(pluginsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const manifestFile = path.join(pluginsDir, entry.name, '.claude-plugin', 'plugin.json');
+        if (!fs.existsSync(manifestFile))
+            continue;
+        let manifest;
+        try {
+            manifest = JSON.parse(fs.readFileSync(manifestFile, 'utf-8'));
+        }
+        catch {
+            continue;
+        }
+        entries.push({
+            name: manifest.name,
+            source: `./plugins/${manifest.name}`,
+            description: manifest.description,
+            version: manifest.version,
+            ...(manifest.author ? { author: manifest.author } : {}),
+        });
+    }
+    const manifest = {
+        $schema: 'https://anthropic.com/claude-code/marketplace.schema.json',
+        name: MARKETPLACE_NAME,
+        description: 'Plugins managed by agents-cli',
+        owner: { name: 'agents-cli' },
+        plugins: entries.sort((a, b) => a.name.localeCompare(b.name)),
+    };
+    const manifestPath = marketplaceManifestPath(agent, versionHome);
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+    return manifest;
+}
+/**
+ * Register the agents-cli marketplace in known_marketplaces.json so Claude Code
+ * discovers it on startup. Idempotent: re-running just refreshes lastUpdated.
+ */
+export function registerMarketplace(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    const knownPath = knownMarketplacesPath(agent, versionHome);
+    let known = {};
+    if (fs.existsSync(knownPath)) {
+        try {
+            known = JSON.parse(fs.readFileSync(knownPath, 'utf-8'));
+        }
+        catch {
+            known = {};
+        }
+    }
+    known[MARKETPLACE_NAME] = {
+        source: { source: 'local', path: root },
+        installLocation: root,
+        lastUpdated: new Date().toISOString(),
+    };
+    fs.mkdirSync(path.dirname(knownPath), { recursive: true });
+    fs.writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Drop the agents-cli marketplace entry from known_marketplaces.json.
+ * Called when the last plugin under it is removed.
+ */
+export function unregisterMarketplace(agent, versionHome) {
+    const knownPath = knownMarketplacesPath(agent, versionHome);
+    if (!fs.existsSync(knownPath))
+        return;
+    let known;
+    try {
+        known = JSON.parse(fs.readFileSync(knownPath, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    if (!(MARKETPLACE_NAME in known))
+        return;
+    delete known[MARKETPLACE_NAME];
+    if (Object.keys(known).length === 0) {
+        try {
+            fs.unlinkSync(knownPath);
+        }
+        catch { /* ignore */ }
+    }
+    else {
+        fs.writeFileSync(knownPath, JSON.stringify(known, null, 2) + '\n', 'utf-8');
+    }
+}
+/**
+ * Mark a plugin as enabled in <versionHome>/.{agent}/settings.json under
+ * enabledPlugins["<plugin>@agents-cli"]: true. Reads, mutates, writes —
+ * preserving every other key.
+ */
+export function enablePluginInSettings(pluginName, agent, versionHome) {
+    const sPath = settingsPath(agent, versionHome);
+    let settings = {};
+    if (fs.existsSync(sPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(sPath, 'utf-8'));
+        }
+        catch {
+            settings = {};
+        }
+    }
+    if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+        settings.enabledPlugins = {};
+    }
+    const enabled = settings.enabledPlugins;
+    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    if (enabled[key] === true)
+        return;
+    enabled[key] = true;
+    fs.mkdirSync(path.dirname(sPath), { recursive: true });
+    fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Remove the enabledPlugins key for this plugin. Inverse of enablePluginInSettings.
+ */
+export function disablePluginInSettings(pluginName, agent, versionHome) {
+    const sPath = settingsPath(agent, versionHome);
+    if (!fs.existsSync(sPath))
+        return;
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(sPath, 'utf-8'));
+    }
+    catch {
+        return;
+    }
+    const enabled = settings.enabledPlugins;
+    if (!enabled)
+        return;
+    const key = `${pluginName}@${MARKETPLACE_NAME}`;
+    if (!(key in enabled))
+        return;
+    delete enabled[key];
+    if (Object.keys(enabled).length === 0) {
+        delete settings.enabledPlugins;
+    }
+    fs.writeFileSync(sPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}
+/**
+ * Remove a plugin's installed marketplace directory. Returns true if the dir
+ * existed and was removed.
+ */
+export function removePluginFromMarketplace(pluginName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
+    if (!fs.existsSync(installed))
+        return false;
+    fs.rmSync(installed, { recursive: true, force: true });
+    return true;
+}
+/**
+ * Return true if the marketplace has no plugins left under it.
+ */
+export function marketplaceIsEmpty(agent, versionHome) {
+    const pluginsDir = path.join(marketplaceRoot(agent, versionHome), 'plugins');
+    if (!fs.existsSync(pluginsDir))
+        return true;
+    const remaining = fs.readdirSync(pluginsDir, { withFileTypes: true })
+        .filter(d => d.isDirectory() && !d.name.startsWith('.'));
+    return remaining.length === 0;
+}
+/**
+ * Drop the entire marketplace directory. Called after the last plugin removal.
+ */
+export function removeEmptyMarketplaceDir(agent, versionHome) {
+    const root = marketplaceRoot(agent, versionHome);
+    if (!fs.existsSync(root))
+        return;
+    fs.rmSync(root, { recursive: true, force: true });
+}
+/**
+ * Detect whether a plugin is installed via the native marketplace path.
+ */
+export function isInstalledInMarketplace(pluginName, agent, versionHome) {
+    const installed = path.join(marketplaceRoot(agent, versionHome), 'plugins', pluginName);
+    return fs.existsSync(path.join(installed, '.claude-plugin', 'plugin.json'));
+}

package/dist/lib/plugins.d.ts

@@ -35,6 +35,12 @@ export declare function discoverPluginCommands(pluginRoot: string): string[];
 export declare function discoverPluginAgentDefs(pluginRoot: string): string[];
 /** Discover executable files in a plugin's bin/ directory. */
 export declare function discoverPluginBin(pluginRoot: string): string[];
+/** Discover MCP server names from .mcp.json at the plugin root. */
+export declare function discoverPluginMcpServers(pluginRoot: string): string[];
+/** Discover LSP server keys from .lsp.json at the plugin root. */
+export declare function discoverPluginLspServers(pluginRoot: string): string[];
+/** Discover monitor names from monitors/monitors.json. */
+export declare function discoverPluginMonitors(pluginRoot: string): string[];
 /**
  * Expand plugin variables in a string.
  *
@@ -60,15 +66,18 @@ export declare function checkPluginDependencies(manifest: PluginManifest): strin
 /**
  * Sync a plugin to a specific agent version's home directory.
  *
- * For Claude:
- *   1. Copy plugin skills into version's skills dir (prefixed: pluginName--skillName)
- *   2. Copy plugin commands into version's commands dir (prefixed: pluginName--cmdName.md)
- *   3. Copy plugin agent defs into version's agents dir (prefixed: pluginName--agentName.md)
- *   4. Copy plugin bin/ into version home plugin-bin/<pluginName>/, note path in settings
- *   5. Read hooks/hooks.json, expand vars, merge into settings.json hooks
- *   6. Read .mcp.json, expand vars, merge mcpServers into settings.json
- *   7. Read settings.json, merge non-permission keys non-destructively into settings.json
- *   8. Read settings.json permissions, expand vars, merge into settings.json
+ * For plugins-capable agents (claude, openclaw):
+ *   1. Copy plugin source into <versionHome>/.<agent>/plugins/marketplaces/agents-cli/plugins/<name>/
+ *   2. Pre-expand ${user_config.*} variables in copied text files (Claude doesn't know this var).
+ *   3. (Re-)synthesize the marketplace.json catalog from the installed plugins.
+ *   4. Register the synthetic marketplace in known_marketplaces.json.
+ *   5. Mark <plugin>@agents-cli enabled in settings.json#enabledPlugins.
+ *   6. Migrate (remove) legacy dual-dash skills/commands/agents/bin/hooks/mcp entries.
+ *
+ * Claude/OpenClaw natively handle the plugin's skills, commands, agents, hooks,
+ * MCP servers, bin/, settings.json, and permissions once the plugin lives at the
+ * native install path and is marked enabled — see
+ * https://code.claude.com/docs/en/plugins.
  */
 export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): {
     success: boolean;
@@ -82,8 +91,9 @@ export declare function syncPluginToVersion(plugin: DiscoveredPlugin, agent: Age
     settings: boolean;
 };
 /**
- * Check if a plugin is synced to a version by inspecting the version home.
- * Checks skills, commands, agent defs, bin, hook commands, and permissions.
+ * Check if a plugin is synced to a version. True when the plugin lives at the
+ * native marketplace install path. Legacy dual-dash entries are not counted —
+ * they're treated as stale and migrated away on the next sync.
  */
 export declare function isPluginSynced(plugin: DiscoveredPlugin, agent: AgentId, versionHome: string): boolean;
 /**
@@ -102,8 +112,10 @@ export declare function removePluginFromVersion(pluginName: string, pluginRoot:
     mcp: number;
 };
 /**
- * Remove orphaned plugin skill directories from a version home.
- * Soft-deletes to ~/.agents/.trash/plugins/.
+ * Remove orphaned plugin entries from a version home. An entry is "orphan" if
+ * its plugin name is not in the active plugin set. Soft-deletes the affected
+ * marketplace plugin dir to ~/.agents/.trash/plugins/. Also cleans up any
+ * legacy dual-dash skills/ directories from older agents-cli versions.
  */
 export declare function cleanOrphanedPluginSkills(agent: AgentId, versionHome: string, activePluginNames: Set<string>, version?: string): string[];
 export interface VersionPluginDiff {