superacli 1.1.6 → 1.1.8

package/cli/discover.js

@@ -0,0 +1,157 @@
+const { listRegistryPlugins } = require("./plugins-registry")
+const { listInstalledPlugins, getPluginInstallGuidance } = require("./plugins-manager")
+
+const STOPWORDS = new Set([
+  "a", "an", "and", "as", "at", "be", "by", "do", "for", "from", "get", "how", "i", "in", "into",
+  "is", "it", "me", "of", "on", "or", "please", "that", "the", "this", "to", "use", "with"
+])
+
+const SYNONYMS = {
+  mail: "email",
+  mailbox: "email",
+  gmail: "email",
+  smtp: "email",
+  browse: "browser",
+  browsing: "browser",
+  browseruse: "browser-use",
+  web: "browser",
+  tweet: "twitter",
+  tweets: "twitter",
+  gcp: "google-cloud",
+  k8s: "kubernetes",
+}
+
+function tokenizeIntent(intent) {
+  const raw = String(intent || "").toLowerCase().replace(/[^a-z0-9\-\s]/g, " ")
+  const baseTokens = raw
+    .split(/\s+/)
+    .map(t => t.trim())
+    .filter(Boolean)
+    .filter(t => !STOPWORDS.has(t))
+
+  const expanded = []
+  for (const token of baseTokens) {
+    expanded.push(token)
+    if (SYNONYMS[token] && SYNONYMS[token] !== token) expanded.push(SYNONYMS[token])
+  }
+  return [...new Set(expanded)]
+}
+
+function countTokenHits(text, tokens) {
+  if (!text || tokens.length === 0) return []
+  const lower = String(text).toLowerCase()
+  return tokens.filter(t => lower.includes(t))
+}
+
+function scorePlugin(plugin, tokens, phrase, installedSet) {
+  const name = String(plugin.name || "")
+  const tags = Array.isArray(plugin.tags) ? plugin.tags.map(t => String(t)) : []
+  const description = String(plugin.description || "")
+
+  const nameHits = countTokenHits(name, tokens)
+  const tagHits = tags.flatMap(tag => countTokenHits(tag, tokens))
+  const descHits = countTokenHits(description, tokens)
+
+  const uniqueTagHits = [...new Set(tagHits)]
+  const uniqueDescHits = [...new Set(descHits)]
+  const baseScore = nameHits.length * 6 + uniqueTagHits.length * 5 + uniqueDescHits.length * 2
+  let score = baseScore
+
+  const phraseNormalized = String(phrase || "").trim().toLowerCase()
+  const phraseHit =
+    phraseNormalized.length > 2 &&
+    (`${name} ${description}`.toLowerCase().includes(phraseNormalized))
+
+  if (phraseHit) score += 4
+  if (installedSet.has(name)) score += 1
+  if (plugin.has_learn === true) score += 1
+
+  return {
+    plugin,
+    base_score: baseScore,
+    score,
+    matched_tokens: [...new Set([...nameHits, ...uniqueTagHits, ...uniqueDescHits])],
+    matched_fields: {
+      name: nameHits,
+      tags: uniqueTagHits,
+      description: uniqueDescHits,
+      phrase: phraseHit,
+    }
+  }
+}
+
+function discoverPluginsByIntent(intent, options = {}) {
+  const phrase = String(intent || "").trim()
+  if (!phrase) {
+    throw Object.assign(new Error("Missing --intent text"), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false,
+      suggestions: ["Run: supercli discover --intent \"send email\" --json"]
+    })
+  }
+
+  const limitRaw = options.limit
+  const limit = limitRaw === undefined || limitRaw === null ? 5 : Number(limitRaw)
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw Object.assign(new Error("Invalid --limit. Use a positive integer"), {
+      code: 85,
+      type: "invalid_argument",
+      recoverable: false,
+    })
+  }
+
+  const tokens = tokenizeIntent(phrase)
+  const plugins = listRegistryPlugins()
+  const installedSet = new Set(listInstalledPlugins().map(p => p.name))
+
+  const ranked = plugins
+    .map(plugin => scorePlugin(plugin, tokens, phrase, installedSet))
+    .filter(item => item.base_score > 0 || item.matched_fields.phrase)
+    .sort((a, b) => {
+      if (b.score !== a.score) return b.score - a.score
+      return a.plugin.name.localeCompare(b.plugin.name)
+    })
+
+  const top = ranked.slice(0, limit).map(item => {
+    const plugin = item.plugin
+    const guidance = getPluginInstallGuidance(plugin.name)
+    const installed = installedSet.has(plugin.name)
+    const nextSteps = []
+    if (plugin.has_learn === true) nextSteps.push(`supercli plugins learn ${plugin.name} --json`)
+    if (!installed) nextSteps.push(`supercli plugins install ${plugin.name}`)
+    if (guidance && Array.isArray(guidance.install_steps)) {
+      for (const cmd of guidance.install_steps.slice(0, 2)) {
+        if (installed && cmd.startsWith("supercli plugins install ")) continue
+        if (!nextSteps.includes(cmd)) nextSteps.push(cmd)
+      }
+    }
+
+    return {
+      name: plugin.name,
+      description: plugin.description,
+      tags: plugin.tags,
+      installed,
+      has_learn: plugin.has_learn === true,
+      source_type: (plugin.source && plugin.source.type) || "bundled",
+      score: item.score,
+      matched_tokens: item.matched_tokens,
+      matched_fields: item.matched_fields,
+      next_steps: nextSteps,
+    }
+  })
+
+  return {
+    intent: phrase,
+    tokens,
+    no_llm: true,
+    total_candidates: ranked.length,
+    returned: top.length,
+    plugins: top,
+  }
+}
+
+module.exports = {
+  tokenizeIntent,
+  discoverPluginsByIntent,
+}

package/cli/help-json.js

@@ -1,6 +1,7 @@
 function buildCapabilities(config, hasServer) {
   const commands = {
     help: { description: "List namespaces and commands" },
+    discover: { description: "Deterministic intent-to-plugin discovery", usage: "supercli discover --intent \"<task>\" [--limit <n>]" },
     config: { subcommands: ["show"] },
     plugins: { subcommands: ["list", "explore", "learn", "install", "remove", "show", "doctor"], description: "Manage local and remote command plugins" },
     mcp: { subcommands: ["list", "add", "tools", "call", "bind", "doctor", "remove"], description: "Manage local MCP server registry and invoke MCP tools" },
@@ -9,7 +10,7 @@ function buildCapabilities(config, hasServer) {
     plan: { description: "Create execution plan", usage: "supercli plan <ns> <res> <act> [--args]" },
     execute: { description: "Execute a stored plan", usage: "supercli execute <plan_id>" },
     skills: {
-      description: "Skill discovery and SKILL.md generation",
+      description: "Capability docs and SKILL.md catalog workflows",
       subcommands: ["list", "get", "teach", "sync", "search", "providers"]
     }
   }
@@ -20,6 +21,20 @@ function buildCapabilities(config, hasServer) {
     version: "1.0",
     name: "supercli",
     description: "Config-driven, AI-friendly dynamic CLI",
+    what_is_supercli: "A deterministic capability router that exposes namespace.resource.action commands, plugin-installed capabilities, MCP tool bindings, and SKILL.md-based skill docs.",
+    agent_onboarding: {
+      discovery_sequence: [
+        "supercli --json",
+        "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"
+      ],
+      fallback_rule: "If a command is not found, use discover/plugins explore/plugins learn before retrying.",
+      no_llm_discovery: true
+    },
     commands,
     namespaces: [...new Set((config.commands || []).map(c => c.namespace))],
     total_commands: (config.commands || []).length,

package/cli/plugin-install-guidance.js

@@ -1,3 +1,8 @@
+const fs = require("fs")
+const path = require("path")
+const { readPluginsLock } = require("./plugins-store")
+const { getRegistryPlugin } = require("./plugins-registry")
+
 const PLUGIN_INSTALL_GUIDANCE = {
   beads: {
     plugin: "beads",
@@ -9,35 +14,9 @@ const PLUGIN_INSTALL_GUIDANCE = {
     ],
     note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
   },
-  gwc: {
-    plugin: "gwc",
-    binary: "gws",
-    check: "gws --version",
-    install_steps: [
-      "npm install -g @googleworkspace/cli",
-      "gws --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  commiat: {
-    plugin: "commiat",
-    binary: "commiat",
-    check: "commiat --version",
-    install_steps: [
-      "npm install -g commiat",
-      "commiat --version"
-    ],
-    note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)."
-  },
-  docker: {
-    plugin: "docker",
-    binary: "docker",
-    check: "docker --version",
-    install_steps: [
-      "docker --version"
-    ],
-    note: "Install Docker Engine/Desktop using your OS package manager, then verify with docker --version."
-  },
+  gwc: { plugin: "gwc", binary: "gws", check: "gws --version", install_steps: ["npm install -g @googleworkspace/cli", "gws --version"], note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)." },
+  commiat: { plugin: "commiat", binary: "commiat", check: "commiat --version", install_steps: ["npm install -g commiat", "commiat --version"], note: "Installation is intentionally delegated to your LLM/automation flow (dcli/scli/supercli)." },
+  docker: { plugin: "docker", binary: "docker", check: "docker --version", install_steps: ["docker --version"], note: "Install Docker Engine/Desktop using your OS package manager, then verify with docker --version." },
   stripe: {
     plugin: "stripe",
     binary: "stripe",
@@ -294,7 +273,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills get blogwatcher:root.skill",
       "supercli blogwatcher blogs list --json"
     ],
-    note: "This hybrid plugin indexes the upstream BlogWatcher README and SKILL documents into the skills catalog and exposes non-interactive wrappers for the local CLI. BlogWatcher stores data under ~/.blogwatcher, so use an isolated HOME when you want disposable test data."
+    note: "This hybrid plugin indexes the upstream BlogWatcher README and SKILL documents into the skill-doc catalog and exposes non-interactive wrappers for the local CLI. BlogWatcher stores data under ~/.blogwatcher, so use an isolated HOME when you want disposable test data."
   },
   himalaya: {
     plugin: "himalaya",
@@ -366,7 +345,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider monty --json",
       "supercli monty python run \"1 + 2\" --json"
     ],
-    note: "This hybrid plugin indexes the upstream Monty README and CLAUDE (skills) documents and provides a sandboxed Python execution environment. It manages its own @pydantic/monty dependency globally."
+    note: "This hybrid plugin indexes the upstream Monty README and CLAUDE skill documents and provides a sandboxed Python execution environment. It manages its own @pydantic/monty dependency globally."
   },
   cline: {
     plugin: "cline",
@@ -397,7 +376,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli nullclaw cli version --json",
       "supercli nullclaw system status --json"
     ],
-    note: "This hybrid plugin indexes remote NullClaw docs into the local skills catalog and exposes the local nullclaw binary through wrapped commands plus passthrough. curl is required for remote doc retrieval."
+    note: "This hybrid plugin indexes remote NullClaw docs into the local skill-doc catalog and exposes the local nullclaw binary through wrapped commands plus passthrough. curl is required for remote doc retrieval."
   },
   "agency-agents": {
     plugin: "agency-agents",
@@ -408,7 +387,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider agency-agents --json",
       "supercli skills get agency-agents:engineering.engineering-frontend-developer"
     ],
-    note: "Install indexes remote markdown skills from https://github.com/msitarzewski/agency-agents (best effort, upstream paths may change)."
+    note: "Install indexes remote markdown skill documents from https://github.com/msitarzewski/agency-agents (best effort, upstream paths may change)."
   },
   "visual-explainer": {
     plugin: "visual-explainer",
@@ -419,7 +398,7 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli skills list --catalog --provider visual-explainer --json",
       "supercli skills get visual-explainer:visual-explainer.skill"
     ],
-    note: "Install indexes normalized markdown skills from https://github.com/javimosch/visual-explainer (plugins/visual-explainer-normalized)."
+    note: "Install indexes normalized markdown skill documents from https://github.com/javimosch/visual-explainer (plugins/visual-explainer-normalized)."
   },
   resend: {
     plugin: "resend",
@@ -431,15 +410,91 @@ const PLUGIN_INSTALL_GUIDANCE = {
       "supercli resend login",
       "supercli resend cli doctor --json"
     ],
-    note: "This hybrid plugin indexes the upstream resend-cli README into the skills catalog and provides a wrapped interface for sending emails and checking environment health. It manages its own resend-cli dependency globally."
+    note: "This hybrid plugin indexes the upstream resend-cli README into the skill-doc catalog and provides a wrapped interface for sending emails and checking environment health. It manages its own resend-cli dependency globally."
+  },
+  "cocoindex-code": {
+    plugin: "cocoindex-code",
+    binary: "cocoindex-code",
+    check: "cocoindex-code --help",
+    install_steps: [
+      "pipx install cocoindex-code",
+      "cocoindex-code --help",
+      "supercli plugins install cocoindex-code",
+      "supercli cocoindex index build --json",
+      "supercli cocoindex code search --query \"where is auth middleware\" --limit 5 --json",
+      "supercli cocoindex mcp search --query \"where is auth middleware\" --limit 5 --json"
+    ],
+    note: "The plugin auto-registers local MCP server cocoindex-code, exposes fast direct search as cocoindex.code.search, and keeps cocoindex.mcp.search available for MCP-native flows. Use direct mcp call for advanced filters like languages/paths."
   }
 
 }
 
+function normalizeInstallGuidance(guidance, pluginName) {
+  if (!guidance || typeof guidance !== "object" || Array.isArray(guidance)) return null
+  const normalized = {
+    plugin: typeof guidance.plugin === "string" && guidance.plugin ? guidance.plugin : String(pluginName || ""),
+    binary: typeof guidance.binary === "string" ? guidance.binary : "",
+    check: typeof guidance.check === "string" ? guidance.check : "",
+    install_steps: Array.isArray(guidance.install_steps) ? guidance.install_steps.map(step => String(step)).filter(Boolean) : [],
+    note: typeof guidance.note === "string" ? guidance.note : "",
+  }
+  if (!normalized.plugin) return null
+  return (!normalized.binary && !normalized.check && normalized.install_steps.length === 0 && !normalized.note) ? null : normalized
+}
+
+function readManifestGuidance(manifestPath, pluginName) {
+  if (!manifestPath || !fs.existsSync(manifestPath)) return null
+  try {
+    const parsed = JSON.parse(fs.readFileSync(manifestPath, "utf-8"))
+    return normalizeInstallGuidance(parsed.install_guidance, pluginName || parsed.name)
+  } catch {
+    return null
+  }
+}
+
+function findInstalledPlugin(name) {
+  const lower = String(name || "").toLowerCase().trim()
+  if (!lower) return null
+  const lock = readPluginsLock()
+  return Object.values(lock.installed || {}).find(p => String(p && p.name || "").toLowerCase() === lower) || null
+}
+
+function resolveRegistryManifestPath(entry) {
+  if (!entry || !entry.source || typeof entry.source !== "object") return null
+  const manifestPath = entry.source.manifest_path
+  if (!manifestPath || typeof manifestPath !== "string") return null
+  if (path.isAbsolute(manifestPath)) return manifestPath
+  return path.resolve(__dirname, "..", manifestPath)
+}
+
 function getPluginInstallGuidance(name) {
-  return PLUGIN_INSTALL_GUIDANCE[name] || null
+  const lower = String(name || "").toLowerCase().trim()
+  if (!lower) return null
+
+  const installed = findInstalledPlugin(lower)
+  if (installed) {
+    const stored = normalizeInstallGuidance(installed.install_guidance, installed.name)
+    if (stored) return stored
+    const resolved = installed.resolved_from && installed.resolved_from.manifest_path ? readManifestGuidance(installed.resolved_from.manifest_path, installed.name) : null
+    if (resolved) return resolved
+  }
+
+  const registryEntry = getRegistryPlugin(lower)
+  if (registryEntry) {
+    const inline = normalizeInstallGuidance(registryEntry.install_guidance, registryEntry.name)
+    if (inline) return inline
+    const fromManifest = readManifestGuidance(resolveRegistryManifestPath(registryEntry), registryEntry.name)
+    if (fromManifest) return fromManifest
+  }
+
+  const bundledManifest = path.resolve(__dirname, "..", "plugins", lower, "plugin.json")
+  const bundled = readManifestGuidance(bundledManifest, lower)
+  if (bundled) return bundled
+
+  return PLUGIN_INSTALL_GUIDANCE[lower] || null
 }
 
 module.exports = {
-  getPluginInstallGuidance
+  getPluginInstallGuidance,
+  normalizeInstallGuidance,
 }

package/cli/plugins-manager.js

@@ -15,6 +15,7 @@ const BUNDLED_PLUGINS = {
   beads: path.resolve(__dirname, "..", "plugins", "beads", "plugin.json"),
   gwc: path.resolve(__dirname, "..", "plugins", "gwc", "plugin.json"),
   docker: path.resolve(__dirname, "..", "plugins", "docker", "plugin.json"),
+  squirrelscan: path.resolve(__dirname, "..", "plugins", "squirrelscan", "plugin.json"),
   "agency-agents": path.resolve(__dirname, "..", "plugins", "agency-agents", "plugin.json"),
   "visual-explainer": path.resolve(__dirname, "..", "plugins", "visual-explainer", "plugin.json")
 }
@@ -356,8 +357,8 @@ function runStoredHook(pluginName, kind, storedHook) {
   }
 }
 
-function checkBinary(binary) {
-  const r = spawnSync(binary, ["--version"], { encoding: "utf-8", timeout: 5000 })
+function checkBinary(binary, args) {
+  const r = spawnSync(binary, args || ["--version"], { encoding: "utf-8", timeout: 5000 })
   if (r.error) {
     return {
       binary,
@@ -393,7 +394,7 @@ function doctorPlugin(name) {
   const checks = []
   for (const check of (plugin.checks || [])) {
     if (check && check.type === "binary" && check.name) {
-      checks.push({ type: "binary", ...checkBinary(check.name) })
+      checks.push({ type: "binary", ...checkBinary(check.name, check.args) })
     }
   }
 

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")}`;