superacli 1.1.6 → 1.1.8

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;
@@ -57,6 +58,7 @@ const RESERVED_FLAGS = [
   "compact",
   "schema",
   "help-json",
+  "help",
   "no-color",
   "show-dag",
   "format",
@@ -102,15 +104,15 @@ function output(data) {
 }
 
 function makeStreamEmitter(commandName) {
-  if (humanMode) return null
+  if (humanMode) return null;
   return (event) => {
     output({
       version: "1.0",
       command: commandName,
       stream: true,
       data: event,
-    })
-  }
+    });
+  };
 }
 
 function outputHumanTable(rows, columns) {
@@ -192,11 +194,16 @@ function renderTopLevelHelp(config) {
   const namespaces = [...new Set(config.commands.map((c) => c.namespace))];
   if (humanMode) {
     console.log("\n  ⚡ SuperCLI\n");
+    console.log(
+      "  Deterministic capability router for namespace.resource.action commands, plugin capabilities, MCP tool bindings, and SKILL.md skill documents.\n",
+    );
     console.log("  Namespaces:\n");
     namespaces.forEach((ns) => {
       const resources = [
         ...new Set(
-          config.commands.filter((c) => c.namespace === ns).map((c) => c.resource),
+          config.commands
+            .filter((c) => c.namespace === ns)
+            .map((c) => c.resource),
         ),
       ];
       console.log(`    ${ns}`);
@@ -212,18 +219,21 @@ 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>"');
     }
     console.log("  Server: supercli --server");
     console.log(
-      "  Flags: --json | --human | --compact | --schema | --help-json | --server\n",
+      "  Flags: --help | --json | --human | --compact | --schema | --help-json | --server\n",
     );
     return;
   }
@@ -232,11 +242,18 @@ function renderTopLevelHelp(config) {
     version: "1.0",
     namespaces: namespaces.map((ns) => ({
       name: ns,
-      resources: [...new Set(config.commands.filter((c) => c.namespace === ns).map((c) => c.resource))]
-        .map((r) => ({
-          name: r,
-          actions: config.commands.filter((c) => c.namespace === ns && c.resource === r).map((c) => c.action),
-        })),
+      resources: [
+        ...new Set(
+          config.commands
+            .filter((c) => c.namespace === ns)
+            .map((c) => c.resource),
+        ),
+      ].map((r) => ({
+        name: r,
+        actions: config.commands
+          .filter((c) => c.namespace === ns && c.resource === r)
+          .map((c) => c.action),
+      })),
     })),
   });
 }
@@ -293,6 +310,64 @@ async function main() {
       }
     }
 
+    // Check for namespace passthrough before handling --help
+    // This allows commands like "cline --help --json" to pass through
+    {
+      const config = await loadConfig(SERVER);
+      const passthrough = findNamespacePassthrough(config, positional, rawArgs);
+      if (passthrough) {
+        const start = Date.now();
+        const result = await execute(
+          passthrough.command,
+          {
+            __rawArgs: passthrough.passthroughArgs,
+            __passthroughInteractive: humanMode && isTTY,
+          },
+          {
+            server: SERVER || "",
+            config,
+            onStreamEvent:
+              passthrough.command.adapterConfig &&
+              passthrough.command.adapterConfig.stream === "jsonl"
+                ? makeStreamEmitter(`${passthrough.namespace}.passthrough`)
+                : null,
+          },
+        );
+        const duration = Date.now() - start;
+        const envelope = {
+          version: "1.0",
+          command: `${passthrough.namespace}.passthrough`,
+          duration_ms: duration,
+          data: result,
+        };
+
+        if (
+          humanMode &&
+          result &&
+          typeof result === "object" &&
+          result.passthrough === true
+        ) {
+          return;
+        }
+        if (
+          humanMode &&
+          result &&
+          typeof result === "object" &&
+          typeof result.raw === "string"
+        ) {
+          console.log(result.raw);
+        } else {
+          output(envelope);
+        }
+        return;
+      }
+    }
+
+    if (flags.help) {
+      displayComprehensiveHelp();
+      return;
+    }
+
     if (flags["help-json"]) {
       const config = await loadConfig(SERVER);
       output(buildCapabilities(config, hasServer));
@@ -304,13 +379,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 +447,12 @@ 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 +487,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 +510,62 @@ 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 +574,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;
     }
@@ -580,45 +744,6 @@ async function main() {
       return;
     }
 
-    {
-      const config = await loadConfig(SERVER);
-      const passthrough = findNamespacePassthrough(config, positional, rawArgs);
-      if (passthrough) {
-        const start = Date.now();
-        const result = await execute(
-          passthrough.command,
-          {
-            __rawArgs: passthrough.passthroughArgs,
-            __passthroughInteractive: humanMode && isTTY,
-          },
-          {
-            server: SERVER || "",
-            config,
-            onStreamEvent: passthrough.command.adapterConfig && passthrough.command.adapterConfig.stream === "jsonl"
-              ? makeStreamEmitter(`${passthrough.namespace}.passthrough`)
-              : null,
-          },
-        );
-        const duration = Date.now() - start;
-        const envelope = {
-          version: "1.0",
-          command: `${passthrough.namespace}.passthrough`,
-          duration_ms: duration,
-          data: result,
-        };
-
-        if (humanMode && result && typeof result === "object" && result.passthrough === true) {
-          return;
-        }
-        if (humanMode && result && typeof result === "object" && typeof result.raw === "string") {
-          console.log(result.raw);
-        } else {
-          output(envelope);
-        }
-        return;
-      }
-    }
-
     if (positional.length === 1) {
       const config = await loadConfig(SERVER);
       const cmds = config.commands.filter((c) => c.namespace === positional[0]);
@@ -691,6 +816,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;
@@ -736,9 +863,10 @@ async function main() {
     const result = await execute(cmd, uFlags, {
       server: SERVER || "",
       config,
-      onStreamEvent: cmd.adapterConfig && cmd.adapterConfig.stream === "jsonl"
-        ? makeStreamEmitter(`${namespace}.${resource}.${action}`)
-        : null,
+      onStreamEvent:
+        cmd.adapterConfig && cmd.adapterConfig.stream === "jsonl"
+          ? makeStreamEmitter(`${namespace}.${resource}.${action}`)
+          : null,
     });
     const duration = Date.now() - start;
 
@@ -798,4 +926,68 @@ async function main() {
   }
 }
 
+function displayComprehensiveHelp() {
+  console.log("\n  ⚡ SuperCLI - Universal Capability Router for AI Agents\n");
+  console.log("  Repository: https://github.com/javimosch/supercli\n");
+  console.log(
+    "  Discover and execute capabilities across CLIs, APIs, MCP servers, workflows, and custom automations through a single agent-friendly interface.\n",
+  );
+
+  console.log("  📋 QUICK OVERVIEW:");
+  console.log("    • Capabilities: namespace.resource.action commands");
+  console.log("    • Plugin System: Install external CLIs as harnesses");
+  console.log("    • MCP Support: Model Context Protocol server integration");
+  console.log("    • Skill Docs: Agent-facing guidance in SKILL.md format");
+  console.log("    • AI Integration: Natural language query execution\n");
+
+  console.log("  🚀 GETTING STARTED:");
+  console.log("    supercli help                  # List available harnesses");
+  console.log(
+    "    supercli skills teach          # Learn about skill documents",
+  );
+  console.log("    supercli plugins explore       # Browse available plugins");
+  console.log(
+    '    supercli discover --intent "<task>"  # Find capabilities for a task\n',
+  );
+
+  console.log("  🔧 CORE COMMANDS:");
+  console.log(
+    "    supercli <namespace> <resource> <action>  # Execute capability",
+  );
+  console.log(
+    "    supercli inspect <ns> <res> <act>       # View command details",
+  );
+  console.log(
+    "    supercli plan <ns> <res> <act>          # Create execution plan",
+  );
+  console.log("    supercli execute <plan_id>              # Run stored plan");
+  console.log(
+    '    supercli ask "<query>"                  # Natural language execution\n',
+  );
+
+  console.log("  🧩 PLUGIN MANAGEMENT:");
+  console.log("    supercli plugins list           # Show installed plugins");
+  console.log("    supercli plugins install <name> # Install a plugin");
+  console.log("    supercli plugins explore        # Browse plugin registry\n");
+
+  console.log("  📖 DOCUMENTATION & RESOURCES:");
+  console.log("    Full README: https://github.com/javimosch/supercli#readme");
+  console.log("    Supported Harnesses: docs/supported-harnesses.md");
+  console.log("    Plugin Creation Guide: docs/plugin-harness-guide.md\n");
+
+  console.log("  🏷️  OUTPUT MODES:");
+  console.log("    (default)   JSON if piped, human-readable if TTY");
+  console.log("    --json      Structured JSON envelope");
+  console.log("    --human     Formatted tables and key-value output");
+  console.log("    --compact   Compressed JSON (shortened keys)\n");
+
+  console.log("  🐛 EXIT CODES:");
+  console.log("    0  success");
+  console.log("    82 validation_error");
+  console.log("    85 invalid_argument");
+  console.log("    92 resource_not_found");
+  console.log("    105 integration_error");
+  console.log("    110 internal_error\n");
+}
+
 main();

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