superacli 1.1.5 → 1.1.7

package/cli/plugins-registry.js

@@ -2,6 +2,7 @@ const fs = require("fs")
 const path = require("path")
 
 const REGISTRY_FILE = path.resolve(__dirname, "..", "plugins", "plugins.json")
+const BUNDLED_PLUGINS_DIR = path.resolve(__dirname, "..", "plugins")
 
 function invalid(message) {
   return Object.assign(new Error(message), {
@@ -31,24 +32,89 @@ function readRegistry() {
 }
 
 function normalizePlugin(entry) {
+  const source = entry.source && typeof entry.source === "object" ? entry.source : {}
   return {
     name: entry.name,
     description: entry.description || "",
     tags: Array.isArray(entry.tags) ? entry.tags.map(t => String(t)) : [],
-    source: entry.source && typeof entry.source === "object" ? entry.source : {},
-    has_learn: entry.has_learn === true
+    source,
+    has_learn: entry.has_learn === true,
+    install_guidance: entry.install_guidance && typeof entry.install_guidance === "object"
+      ? entry.install_guidance
+      : null,
   }
 }
 
-function listRegistryPlugins(filters = {}) {
+function readManifest(filePath) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"))
+    if (!parsed || typeof parsed !== "object" || !parsed.name || !Array.isArray(parsed.commands)) return null
+    return parsed
+  } catch {
+    return null
+  }
+}
+
+function discoverBundledPlugins() {
+  if (!fs.existsSync(BUNDLED_PLUGINS_DIR)) return []
+  let entries
+  try {
+    entries = fs.readdirSync(BUNDLED_PLUGINS_DIR, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  if (!Array.isArray(entries)) return []
+  const plugins = []
+
+  for (const entry of entries) {
+    if (!entry || !entry.isDirectory()) continue
+    const manifestPath = path.join(BUNDLED_PLUGINS_DIR, entry.name, "plugin.json")
+    if (!fs.existsSync(manifestPath)) continue
+    const manifest = readManifest(manifestPath)
+    if (!manifest) continue
+    plugins.push({
+      name: manifest.name,
+      description: manifest.description || "",
+      tags: Array.isArray(manifest.tags) ? manifest.tags.map(t => String(t)) : [],
+      source: {
+        type: "bundled",
+        manifest_path: path.relative(path.resolve(__dirname, ".."), manifestPath).replace(/\\/g, "/")
+      },
+      has_learn: !!manifest.learn,
+      install_guidance: manifest.install_guidance && typeof manifest.install_guidance === "object"
+        ? manifest.install_guidance
+        : null,
+    })
+  }
+
+  return plugins
+}
+
+function mergedRegistryPlugins() {
   const registry = readRegistry()
+  const discovered = discoverBundledPlugins()
+  const merged = new Map()
+
+  for (const plugin of discovered) {
+    const normalized = normalizePlugin(plugin)
+    merged.set(String(normalized.name || "").toLowerCase(), normalized)
+  }
+
+  for (const plugin of (registry.plugins || [])) {
+    const normalized = normalizePlugin(plugin)
+    merged.set(String(normalized.name || "").toLowerCase(), normalized)
+  }
+
+  return Array.from(merged.values())
+}
+
+function listRegistryPlugins(filters = {}) {
   const nameQuery = (filters.name || "").toLowerCase().trim()
   const tagQueries = (filters.tags || [])
     .map(t => String(t || "").toLowerCase().trim())
     .filter(Boolean)
 
-  return registry.plugins
-    .map(normalizePlugin)
+  return mergedRegistryPlugins()
     .filter(entry => {
       if (nameQuery) {
         const text = `${entry.name} ${entry.description}`.toLowerCase()
@@ -68,14 +134,14 @@ function listRegistryPlugins(filters = {}) {
 function getRegistryPlugin(name) {
   const lower = String(name || "").toLowerCase()
   if (!lower) return null
-  const registry = readRegistry()
-  const found = registry.plugins.find(p => String(p.name || "").toLowerCase() === lower)
-  return found ? normalizePlugin(found) : null
+  return mergedRegistryPlugins().find(p => String(p.name || "").toLowerCase() === lower) || null
 }
 
 module.exports = {
   REGISTRY_FILE,
+  BUNDLED_PLUGINS_DIR,
   readRegistry,
+  discoverBundledPlugins,
   listRegistryPlugins,
   getRegistryPlugin
 }

package/cli/plugins-store.js

@@ -2,21 +2,26 @@ const fs = require("fs")
 const os = require("os")
 const path = require("path")
 
-const DCLI_DIR = path.join(os.homedir(), ".dcli")
-const PLUGINS_FILE = path.join(DCLI_DIR, "plugins.lock.json")
+const SUPERCLI_DIR = path.join(os.homedir(), ".supercli")
+const SUPERCLI_PLUGINS_DIR = path.join(SUPERCLI_DIR, "plugins")
+const SUPERCLI_LOCAL_LOCK_FILE = path.join(SUPERCLI_PLUGINS_DIR, "plugins.lock.json")
+const SUPERCLI_SERVER_LOCK_FILE = path.join(SUPERCLI_PLUGINS_DIR, "server.lock.json")
 
-function ensureDir() {
-  if (!fs.existsSync(DCLI_DIR)) fs.mkdirSync(DCLI_DIR, { recursive: true })
+const LEGACY_DCLI_DIR = path.join(os.homedir(), ".dcli")
+const LEGACY_PLUGINS_FILE = path.join(LEGACY_DCLI_DIR, "plugins.lock.json")
+
+function ensurePluginsDir() {
+  if (!fs.existsSync(SUPERCLI_PLUGINS_DIR)) fs.mkdirSync(SUPERCLI_PLUGINS_DIR, { recursive: true })
 }
 
 function emptyLock() {
   return { version: 1, installed: {} }
 }
 
-function readPluginsLock() {
+function readLockFile(filePath) {
   try {
-    if (!fs.existsSync(PLUGINS_FILE)) return emptyLock()
-    const parsed = JSON.parse(fs.readFileSync(PLUGINS_FILE, "utf-8"))
+    if (!fs.existsSync(filePath)) return emptyLock()
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf-8"))
     if (!parsed || typeof parsed !== "object") return emptyLock()
     if (!parsed.installed || typeof parsed.installed !== "object") parsed.installed = {}
     return parsed
@@ -25,32 +30,88 @@ function readPluginsLock() {
   }
 }
 
-function writePluginsLock(lock) {
-  ensureDir()
-  fs.writeFileSync(PLUGINS_FILE, JSON.stringify(lock, null, 2))
+function writeLockFile(filePath, lock) {
+  ensurePluginsDir()
+  fs.writeFileSync(filePath, JSON.stringify(lock, null, 2))
   return lock
 }
 
+function readPluginsLock() {
+  if (fs.existsSync(SUPERCLI_LOCAL_LOCK_FILE)) {
+    return readLockFile(SUPERCLI_LOCAL_LOCK_FILE)
+  }
+
+  if (fs.existsSync(LEGACY_PLUGINS_FILE)) {
+    const legacy = readLockFile(LEGACY_PLUGINS_FILE)
+    writeLockFile(SUPERCLI_LOCAL_LOCK_FILE, legacy)
+    return legacy
+  }
+  return emptyLock()
+}
+
+function writePluginsLock(lock) {
+  return writeLockFile(SUPERCLI_LOCAL_LOCK_FILE, lock)
+}
+
+function readServerPluginsLock() {
+  return readLockFile(SUPERCLI_SERVER_LOCK_FILE)
+}
+
+function writeServerPluginsLock(lock) {
+  return writeLockFile(SUPERCLI_SERVER_LOCK_FILE, lock)
+}
+
 function listInstalledPlugins() {
   const lock = readPluginsLock()
   return Object.values(lock.installed)
 }
 
+function listServerInstalledPlugins() {
+  const lock = readServerPluginsLock()
+  return Object.values(lock.installed)
+}
+
+function pluginCommands(plugin) {
+  const commands = []
+  for (const cmd of (plugin.commands || [])) commands.push(cmd)
+  return commands
+}
+
 function getInstalledPluginCommands() {
-  const lock = readPluginsLock()
+  return listInstalledPlugins().flatMap(pluginCommands)
+}
+
+function getServerPluginCommands() {
+  return listServerInstalledPlugins().flatMap(pluginCommands)
+}
+
+function getEffectivePluginCommands() {
+  const localPlugins = listInstalledPlugins()
+  const serverPlugins = listServerInstalledPlugins()
+  const localNames = new Set(localPlugins.map(p => p.name))
+
   const commands = []
-  for (const plugin of Object.values(lock.installed)) {
-    for (const cmd of (plugin.commands || [])) {
-      commands.push(cmd)
-    }
+  for (const plugin of localPlugins) commands.push(...pluginCommands(plugin))
+  for (const plugin of serverPlugins) {
+    if (localNames.has(plugin.name)) continue
+    commands.push(...pluginCommands(plugin))
   }
   return commands
 }
 
 module.exports = {
-  PLUGINS_FILE,
+  SUPERCLI_DIR,
+  SUPERCLI_PLUGINS_DIR,
+  SUPERCLI_LOCAL_LOCK_FILE,
+  SUPERCLI_SERVER_LOCK_FILE,
+  LEGACY_PLUGINS_FILE,
   readPluginsLock,
   writePluginsLock,
+  readServerPluginsLock,
+  writeServerPluginsLock,
   listInstalledPlugins,
-  getInstalledPluginCommands
+  listServerInstalledPlugins,
+  getInstalledPluginCommands,
+  getServerPluginCommands,
+  getEffectivePluginCommands,
 }

package/cli/skills-mcp.js

@@ -93,7 +93,7 @@ function buildMcpServersUsageSkillMarkdown(options = {}) {
     "- Prefer passing secrets via runtime environment variables and CLI args, not committed files.",
     "- If your MCP args/env contain ${ENV_VAR} placeholders, export them before running mcp tools/call/doctor.",
     "- For named MCP servers, command-level adapter settings override server-level defaults on conflicts.",
-    "- Use `supercli skills teach --format skill.md` for general skills discovery guidance.",
+    "- Use `supercli skills teach --format skill.md` for general capability and skill-document discovery guidance.",
   ];
 
   return `---\n${renderYamlObject(frontmatter)}\n---\n\n${body.join("\n")}`;

package/cli/skills.js

@@ -2,6 +2,7 @@ const { createPlan } = require("./planner")
 const { buildMcpServersUsageSkillMarkdown: buildMcpUsage } = require("./skills-mcp")
 
 const PLUGINS_USAGE_SKILL_ID = "plugins.registry.usage"
+const PLUGINS_AUTHORING_SKILL_ID = "plugins.authoring.usage"
 const MCP_SERVERS_USAGE_SKILL_ID = "mcp.servers.usage"
 const {
   listProviders,
@@ -143,7 +144,7 @@ function buildTeachSkillMarkdown(options = {}) {
 
   const frontmatter = {
     skill_name: "teach_skills_usage",
-    description: "Introduces LLMs to SuperCLI skills commands and explains how to request and execute skills.",
+    description: "Introduces LLMs to SuperCLI capability and skill-document commands, and explains how to request capability docs and execute capabilities.",
     command: "skills teach",
     arguments: [
       {
@@ -178,7 +179,7 @@ function buildTeachSkillMarkdown(options = {}) {
     ]
   }
 
-  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI skills:\n\n1. List available skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch a specific skill:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the command with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n5. For plugin discovery and remote plugin installs, use:\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\n\`\`\`\n\n6. To index skills from a local directory (e.g., a project with docs/skills):\n\n\`\`\`bash\n# List current providers\nsupercli skills providers list --json\n\n# Add a local provider for a project\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\n\n# Sync the catalog to index new skills\nsupercli skills sync\n\n# Search skills from the new provider\nsupercli skills search <query> --provider myproject\n\n# Remove a provider if needed\nsupercli skills providers remove --name myproject\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\nsupercli skills sync\nsupercli skills search btc --provider myproject\n\`\`\``
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nThis skill teaches LLMs how to discover and use SuperCLI capabilities and skill documents:\n\n1. List available capability docs and catalog skills:\n\n\`\`\`bash\nsupercli skills list --json\n\`\`\`\n\n2. Fetch documentation for a specific capability:\n\n\`\`\`bash\nsupercli skills get <namespace.resource.action> --format skill.md\n\`\`\`\n\n3. Parse YAML frontmatter to understand command, arguments, output schema, and metadata.\n\n4. Execute the capability with validated arguments:\n\n\`\`\`bash\nsupercli <namespace> <resource> <action> --arg value --json\n\`\`\`\n\n5. For plugin discovery and remote plugin installs, use:\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\n\`\`\`\n\n6. To index skill documents from a local directory (e.g., a project with docs/skills):\n\n\`\`\`bash\n# List current providers\nsupercli skills providers list --json\n\n# Add a local provider for a project\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\n\n# Sync the catalog to index new skill documents\nsupercli skills sync\n\n# Search skill documents from the new provider\nsupercli skills search <query> --provider myproject\n\n# Remove a provider if needed\nsupercli skills providers remove --name myproject\n\`\`\`\n\n# Examples\n\n\`\`\`bash\nsupercli skills teach --format skill.md\nsupercli skills teach --format skill.md --show-dag\nsupercli skills providers add --name myproject --type local_fs --roots ./myproject/docs/skills\nsupercli skills sync\nsupercli skills search btc --provider myproject\n\`\`\``
 }
 
 function buildPluginsUsageSkillMarkdown(options = {}) {
@@ -223,6 +224,31 @@ function buildPluginsUsageSkillMarkdown(options = {}) {
   return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nUse this workflow for plugin discovery and installation:\n\n1. Explore registry metadata (name/description/tags):\n\n\`\`\`bash\nsupercli plugins explore --json\nsupercli plugins explore --name commiat --json\nsupercli plugins explore --tags git,ai --json\n\`\`\`\n\n2. Install by registry name:\n\n\`\`\`bash\nsupercli plugins install commiat --json\n\`\`\`\n\n3. Install directly from a remote git repository:\n\n\`\`\`bash\nsupercli plugins install --git https://github.com/org/repo.git --manifest-path plugins/supercli/plugin.json --ref main --json\n\`\`\`\n\n4. Validate installed plugin health and guidance:\n\n\`\`\`bash\nsupercli plugins doctor commiat --json\nsupercli plugins show commiat --json\n\`\`\`\n\n5. Use the namespace command exposed by the plugin.\n\n# Examples\n\n\`\`\`bash\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md\nsupercli skills get ${PLUGINS_USAGE_SKILL_ID} --format skill.md --show-dag\n\`\`\``
 }
 
+function buildPluginsAuthoringSkillMarkdown(options = {}) {
+  const frontmatter = {
+    skill_name: "plugins_authoring_usage",
+    description: "Explains how to design, implement, test, and register a new SuperCLI plugin.",
+    command: `skills get ${PLUGINS_AUTHORING_SKILL_ID}`,
+    arguments: [
+      { name: "format", type: "string", required: false, description: "Output format, default skill.md" },
+      { name: "show-dag", type: "boolean", required: false, description: "Include internal DAG for agent reasoning" }
+    ],
+    output_schema: { instruction: "string", examples: "array" },
+    metadata: { side_effects: false, risk_level: "safe", dag_supported: true }
+  }
+
+  if (options.showDag) {
+    frontmatter.dag = [
+      { id: 1, type: "inspect_existing_plugins" },
+      { id: 2, type: "design_plugin_shape", depends_on: [1] },
+      { id: 3, type: "author_manifest_docs_tests", depends_on: [2] },
+      { id: 4, type: "register_and_verify_plugin", depends_on: [3] }
+    ]
+  }
+
+  return `---\n${renderYamlObject(frontmatter)}\n---\n\n# Instruction\n\nUse this workflow when an agent needs to create a new SuperCLI plugin instead of installing an existing one.\n\n1. Inspect existing plugins and choose the closest reference pattern for command shape, output style, and test strategy.\n\n\`\`\`bash\nsupercli plugins explore --json\n\`\`\`\n\n2. Decide between wrapped commands, passthrough, or a hybrid plugin. Prefer wrapped commands for stable high-value flows and passthrough for broad upstream coverage.\n\n3. Pick the authoring location based on runtime context:\n- Package usage (most common, for example \`npx supercli\`): create the plugin under \`~/.supercli/plugins/local/<name>/\`.\n- SuperCLI source repo workflow: create the plugin under \`plugins/<name>/\`.\n\n4. Create at least:\n- \`plugin.json\`\n- \`README.md\`\n- \`skills/quickstart/SKILL.md\` when agents need focused usage guidance\n\n5. In \`plugin.json\`, define metadata, dependency checks, install guidance when setup is non-obvious, and commands using the right adapter.\n\n6. If working in the source repo, also register the plugin in \`plugins/plugins.json\` with description, tags, bundled manifest path, and \`has_learn\` when learn content exists.\n\n7. Add focused tests under \`__tests__/\` for command routing, install guidance, doctor checks, and learn content when applicable. Use fake binaries where possible.\n\n8. Run targeted verification:\n\n\`\`\`bash\nnpx jest __tests__/<plugin>-plugin.test.js --coverage=false --testTimeout=15000\nsupercli plugins install ~/.supercli/plugins/local/<name> --on-conflict replace --json\nsupercli plugins doctor <name> --json\n\`\`\`\n\n9. Keep terminology consistent:\n- Capability = executable command surface\n- Skill document = \`SKILL.md\` instruction artifact\n\n# Examples\n\n\`\`\`bash\nmkdir -p ~/.supercli/plugins/local/my-plugin/skills/quickstart\nsupercli plugins install ~/.supercli/plugins/local/my-plugin --on-conflict replace --json\nsupercli skills get ${PLUGINS_AUTHORING_SKILL_ID} --format skill.md\nsupercli skills get ${PLUGINS_AUTHORING_SKILL_ID} --format skill.md --show-dag\n\`\`\``
+}
+
 function buildMcpServersUsageSkillMarkdown(options = {}) {
   return buildMcpUsage({
     showDag: !!options.showDag,
@@ -240,6 +266,10 @@ function listSkillsMetadata(config) {
     name: PLUGINS_USAGE_SKILL_ID,
     description: "Discover and install plugins from the registry or remote git repos"
   })
+  commandSkills.push({
+    name: PLUGINS_AUTHORING_SKILL_ID,
+    description: "Design, implement, test, and register a new SuperCLI plugin"
+  })
   commandSkills.push({
     name: MCP_SERVERS_USAGE_SKILL_ID,
     description: "Manage MCP servers and execute MCP-backed commands (including browser-use style bridges)"
@@ -400,6 +430,11 @@ function handleSkillsCommand(options) {
       return true
     }
 
+    if (parsed.id === PLUGINS_AUTHORING_SKILL_ID) {
+      console.log(buildPluginsAuthoringSkillMarkdown({ showDag: !!flags["show-dag"] }))
+      return true
+    }
+
     if (parsed.id === MCP_SERVERS_USAGE_SKILL_ID) {
       console.log(buildMcpServersUsageSkillMarkdown({ showDag: !!flags["show-dag"] }))
       return true
@@ -423,11 +458,13 @@ function handleSkillsCommand(options) {
 
 module.exports = {
   PLUGINS_USAGE_SKILL_ID,
+  PLUGINS_AUTHORING_SKILL_ID,
   MCP_SERVERS_USAGE_SKILL_ID,
   normalizeSkillId,
   buildCommandSkillMarkdown,
   buildTeachSkillMarkdown,
   buildPluginsUsageSkillMarkdown,
+  buildPluginsAuthoringSkillMarkdown,
   buildMcpServersUsageSkillMarkdown,
   listSkillsMetadata,
   handleSkillsCommand,

package/cli/supercli.js

@@ -22,6 +22,7 @@ const {
 const { handleAskCommand } = require("./ask");
 const { handleSkillsCommand } = require("./skills");
 const { findNamespacePassthrough } = require("./namespace-passthrough");
+const { discoverPluginsByIntent } = require("./discover");
 
 const SERVER = process.env.SUPERCLI_SERVER;
 const hasServer = !!SERVER;
@@ -212,11 +213,14 @@ function renderTopLevelHelp(config) {
     console.log(
       "  Plugins: supercli plugins explore | supercli plugins learn <name> | supercli plugins install <name|path> | supercli plugins install --git <repo>",
     );
+    console.log(
+      '  Discover: supercli discover --intent "<task>" [--limit <n>] [--json]',
+    );
     console.log(
       "  MCP: supercli mcp list | supercli mcp add <name> --url <url> | supercli mcp tools --mcp-server <name> | supercli mcp call --mcp-server <name> --tool <tool> | supercli mcp bind --mcp-server <name> --tool <tool> --as <ns.res.act> | supercli mcp doctor --mcp-server <name> | supercli mcp remove <name>",
     );
     console.log(
-      "  Skills: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
+      "  Skill Docs: supercli skills list | supercli skills get <id> | supercli skills search --query <q> | supercli skills sync",
     );
     if (config.features?.ask || process.env.OPENAI_BASE_URL) {
       console.log('  AI: supercli ask "<your natural language query>"');
@@ -304,13 +308,30 @@ async function main() {
         output({
           version: "1.0",
           mode: "agent_bootstrap",
-          goal: "Use skills for command-safe execution",
-          next: [
-            "supercli skills teach --format skill.md",
-            "supercli skills list --json",
-            "supercli skills get <namespace.resource.action> --format skill.md"
+          name: "supercli",
+          what_is_supercli:
+            "Deterministic capability router for namespace.resource.action commands, plugin capabilities, MCP tool bindings, and SKILL.md skill documents.",
+          core_capabilities: ["commands", "plugins", "mcp", "skill_docs"],
+          first_steps: [
+            "supercli --help-json",
+            "supercli discover --intent \"<task>\" --json",
+            "supercli plugins learn <name> --json",
+            "supercli plugins install <name>",
+            "supercli commands --query <keyword> --limit 50 --json",
+            "supercli inspect <namespace> <resource> <action> --json"
           ],
-          note: "Use skills teach first, then fetch only the skill you need."
+          intent_workflow:
+            "If task command is unknown, use discover -> plugins learn -> plugins install -> commands/inspect -> execute.",
+          examples: {
+            send_email: [
+              'supercli discover --intent "send email" --json',
+              "supercli plugins learn resend --json",
+              "supercli plugins install resend",
+              "supercli commands --namespace resend --json"
+            ]
+          },
+          no_llm_discovery: true,
+          note: "Intent discovery is deterministic and does not call an LLM."
         });
         return;
       }
@@ -355,8 +376,8 @@ async function main() {
     }
 
     if (hasServer && positional[0] === "sync") {
-      await syncConfig(SERVER);
-      output({ ok: true, message: "Config synced" });
+      const result = await syncConfig(SERVER);
+      output({ ok: true, message: "Config synced", server_plugins: result.server_plugins || null });
       return;
     }
 
@@ -391,6 +412,13 @@ async function main() {
       return;
     }
 
+    if (positional[0] === "discover") {
+      const intent = flags.intent ? String(flags.intent) : ""
+      const result = discoverPluginsByIntent(intent, { limit: flags.limit })
+      output(result)
+      return;
+    }
+
     if (positional[0] === "skills") {
       const config = await loadConfig(SERVER);
       handleSkillsCommand({
@@ -407,14 +435,47 @@ async function main() {
 
     if (positional[0] === "commands") {
       const config = await loadConfig(SERVER);
-      const rows = config.commands.map((c) => ({
+      const namespaceFilter = flags.namespace ? String(flags.namespace).toLowerCase().trim() : ""
+      const resourceFilter = flags.resource ? String(flags.resource).toLowerCase().trim() : ""
+      const actionFilter = flags.action ? String(flags.action).toLowerCase().trim() : ""
+      const queryFilter = flags.query ? String(flags.query).toLowerCase().trim() : ""
+      const limit = flags.limit === undefined ? null : Number(flags.limit)
+      if (flags.limit !== undefined && (!Number.isFinite(limit) || limit <= 0 || !Number.isInteger(limit))) {
+        outputError({
+          code: 85,
+          type: "invalid_argument",
+          message: "Invalid --limit. Use a positive integer",
+          recoverable: false,
+        });
+        return;
+      }
+
+      let rows = config.commands.map((c) => ({
         command: `${c.namespace} ${c.resource} ${c.action}`,
+        namespace: c.namespace,
+        resource: c.resource,
+        action: c.action,
         description: c.description || "",
         adapter: c.adapter,
         args: (c.args || [])
           .map((a) => `--${a.name}${a.required ? "*" : ""}`)
           .join(" "),
       }));
+
+      rows = rows.filter((row) => {
+        if (namespaceFilter && row.namespace.toLowerCase() !== namespaceFilter) return false
+        if (resourceFilter && row.resource.toLowerCase() !== resourceFilter) return false
+        if (actionFilter && row.action.toLowerCase() !== actionFilter) return false
+        if (queryFilter) {
+          const haystack = `${row.command} ${row.description} ${row.adapter} ${row.args}`.toLowerCase()
+          if (!haystack.includes(queryFilter)) return false
+        }
+        return true
+      })
+
+      const total = rows.length
+      if (limit !== null) rows = rows.slice(0, limit)
+
       if (humanMode) {
         console.log("\n  ⚡ Commands\n");
         outputHumanTable(rows, [
@@ -423,9 +484,22 @@ async function main() {
           { key: "args", label: "Args" },
           { key: "description", label: "Description" },
         ]);
+        console.log(`  Returned: ${rows.length}/${total}`)
         console.log("");
       } else {
-        output({ version: "1.0", commands: rows });
+        output({
+          version: "1.0",
+          total,
+          returned: rows.length,
+          filters: {
+            namespace: namespaceFilter || null,
+            resource: resourceFilter || null,
+            action: actionFilter || null,
+            query: queryFilter || null,
+            limit: limit === null ? null : limit,
+          },
+          commands: rows,
+        });
       }
       return;
     }
@@ -691,6 +765,8 @@ async function main() {
         suggestions: [
           "Run: supercli commands",
           `Run: supercli ${namespace} ${resource}`,
+          `Run: supercli discover --intent "${namespace} ${resource} ${action}" --json`,
+          `Run: supercli plugins explore --name ${resource} --json`,
         ],
       });
       return;

package/docs/feature-gaps.md

@@ -1,16 +1,16 @@
 # Feature Gaps
 
-Comparison of the current release versus the broader skill-mesh vision from the latest brainstorming notes.
+Comparison of the current release versus the broader capability-mesh vision from the latest brainstorming notes.
 
 | Feature name | Description | Why it matters |
 | --- | --- | --- |
-| Unified skill registry service | Dedicated registry service that persists skill metadata, ownership, and lifecycle events outside the CLI runtime. | Enables organization-wide discovery, policy management, and sharing without relying on a single CLI process or local cache. |
-| Skill graph traversal API | Graph-native search endpoints ("related skills", capability clustering, semantic tags). | Agents can explore neighboring skills, infer dependencies, and auto-complete workflows instead of executing isolated commands. |
+| Unified capability registry service | Dedicated registry service that persists capability metadata, ownership, and lifecycle events outside the CLI runtime. | Enables organization-wide discovery, policy management, and sharing without relying on a single CLI process or local cache. |
+| Capability graph traversal API | Graph-native search endpoints ("related capabilities", capability clustering, semantic tags). | Agents can explore neighboring capabilities, infer dependencies, and auto-complete workflows instead of executing isolated commands. |
 | Mesh-wide governance & policy | Central rules for authentication, rate limits, approvals, and auditing across every harness/adapter. | Provides enterprise-grade controls so teams can safely expose sensitive CLIs/APIs without bespoke wrappers. |
-| Execution DAG orchestration | First-class scheduler for multi-skill plans with retries, checkpoints, and observability hooks. | Bridges `plan/execute` concepts with reliable automation, turning plans into production-grade workflows. |
+| Execution DAG orchestration | First-class scheduler for multi-capability plans with retries, checkpoints, and observability hooks. | Bridges `plan/execute` concepts with reliable automation, turning plans into production-grade workflows. |
 | Agent-facing HTTP interface | Stable HTTP/WebSocket endpoints that mirror CLI capabilities for direct agent/automation consumption. | Lets agents integrate via simple API calls rather than shelling out to the CLI, unlocking server-side agents and SaaS integrations. |
-| Skill composition toolkit | Declarative way to package multiple skills into composites or workflows that publish as new skills. | Encourages reuse, accelerates plugin development, and aligns with the "skill mesh" abstraction where every composite is also a skill. |
-| Telemetry & lineage for skills | Built-in tracing, metrics, and history for each skill invocation and plan. | Makes it possible to reason about reliability, enforce governance, and debug agent runs across heterogeneous tools. |
-| Plugin certification & discovery UX | Registry UX for tagging, ranking, and validating community plugins directly in `supercli plugins explore`. | Reduces trust friction for third-party harnesses and makes the discovery narrative match the README’s emphasis on skills-first exploration. |
+| Capability composition toolkit | Declarative way to package multiple capabilities into composites or workflows that publish as new capabilities. | Encourages reuse, accelerates plugin development, and aligns with the capability mesh abstraction where every composite is also a capability. |
+| Telemetry & lineage for capabilities | Built-in tracing, metrics, and history for each capability invocation and plan. | Makes it possible to reason about reliability, enforce governance, and debug agent runs across heterogeneous tools. |
+| Plugin certification & discovery UX | Registry UX for tagging, ranking, and validating community plugins directly in `supercli plugins explore`. | Reduces trust friction for third-party harnesses and makes the discovery narrative match the README's emphasis on capabilities-first exploration. |
 
-These gaps represent future-facing opportunities rather than committed roadmap items; they document the delta between today’s shipping features and the aspirational skill-mesh direction.
+These gaps represent future-facing opportunities rather than committed roadmap items; they document the delta between today's shipping features and the aspirational capability-mesh direction.

package/docs/features/azd-uipath-plugins.md

@@ -0,0 +1,43 @@
+# azd and uipath plugins
+
+This feature adds two new bundled plugin harnesses focused on non-interactive automation:
+
+- `azd` for Azure Developer CLI
+- `uipath` for UiPath CLI (`uipcli`)
+
+## Why these candidates
+
+- Both tools are active in 2025-2026 and documented for automation and CI/CD usage.
+- Both expose command surfaces that map well to supercli process adapters.
+- Both are complementary to existing bundled plugins.
+
+## Plugin design
+
+### azd
+
+- Binary check: `azd`
+- Curated wrappers:
+  - `azd cli version`
+  - `azd auth status` (`auth login --check-status --no-prompt`)
+  - `azd deploy all` (`deploy --all --no-prompt`)
+- Full passthrough: `supercli azd <upstream args...>`
+
+### uipath
+
+- Binary check: `uipcli`
+- Curated wrappers:
+  - `uipath cli version`
+  - `uipath package deploy --path ...` plus common auth flags
+- Full passthrough: `supercli uipath <upstream args...>`
+
+## Validation goals
+
+- Wrappers should remain deterministic and suitable for headless execution.
+- Passthrough ensures full upstream coverage without waiting for manifest updates.
+
+## Sources
+
+- Azure Developer CLI reference:
+  - https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/reference
+- UiPath CI/CD release notes (25.10):
+  - https://docs.uipath.com/cicd-integrations/standalone/2025.10/release-notes/cliv251003

package/docs/features/server-plugins.md

@@ -0,0 +1,62 @@
+# Server Plugins
+
+Server plugins let the SUPERCLI server distribute plugin capabilities to CLI clients during `supercli sync`.
+
+## Plugin Types
+
+- `json`: manifest-only plugins for simple command wrappers or remote integrations.
+- `zip`: packaged plugins for assets such as `skills/`, hook scripts, and auxiliary files.
+
+## Sync Model
+
+1. Client runs `supercli sync` with `SUPERCLI_SERVER` configured.
+2. Client fetches `/api/config` and `/api/plugins?format=json`.
+3. Client downloads only changed enabled server plugins by checksum.
+4. Client stores server plugins locally under `~/.supercli/plugins/server`.
+5. Runtime command graph merges base config + plugins.
+
+## Precedence Rules
+
+- Local plugins always win over server plugins when names collide.
+- Server plugins never override local-only plugins.
+- Sync diagnostics include shadowing details (`shadowed_by_local`).
+
+## Enable/Disable Behavior
+
+- Server plugin records include `enabled`.
+- `enabled=false` removes the plugin from effective server-synced state on next sync.
+- This only affects server-distributed plugins.
+
+## Hook Policy
+
+- Hook execution is policy-driven, not environment-variable-driven.
+- Effective policy resolution:
+  - per-plugin `hooks_policy` (`allow|deny|inherit`)
+  - fallback to global server default (`settings.default_hooks_policy`)
+- When denied, plugin sync still succeeds and reports skipped hooks.
+
+## ZIP Safety Controls
+
+- Default max ZIP size: `10MB` (configurable via server plugin settings).
+- ZIP payload validation includes:
+  - ZIP signature check
+  - unsafe path detection (`../`, absolute paths, drive roots)
+  - uncompressed-size threshold checks
+
+## Storage Paths
+
+- Client plugin root: `~/.supercli/plugins`
+- Local plugin lock: `~/.supercli/plugins/plugins.lock.json`
+- Server plugin lock: `~/.supercli/plugins/server.lock.json`
+- Server plugin content: `~/.supercli/plugins/server/<name>/<version>/`
+
+## API Surface
+
+- `GET /api/plugins?format=json` list plugins + settings
+- `POST /api/plugins` create/update JSON plugin
+- `POST /api/plugins/upload` upload ZIP plugin (multipart or JSON base64)
+- `PATCH /api/plugins/:name` update metadata (`enabled`, `hooks_policy`)
+- `DELETE /api/plugins/:name` remove plugin
+- `GET /api/plugins/:name/manifest` fetch manifest
+- `GET /api/plugins/:name/archive` fetch ZIP payload
+- `GET /api/plugins/settings` and `PUT /api/plugins/settings` manage defaults