min-agent 0.2.1 → 0.3.0

package/dist/cli.js

@@ -1,11 +1,14 @@
 import { runAgent } from "./agent.js";
-import { loadMcpConfig, saveMcpConfig, checkMcpServer, checkAllMcpServers, formatMcpServerBinding, } from "./mcp.js";
-import { discoverSkills, getSkills } from "./skills.js";
+import { loadMcpConfigFile, loadMcpConfigEntries, saveMcpConfig, checkMcpServer, checkAllMcpServers, formatMcpServerBinding, } from "./mcp.js";
+import { discoverSkills } from "./skills.js";
 import { loadMemories, addMemory, deleteMemory, searchMemories } from "./memory.js";
-import { runSetup, isConfigured, loadConfig, saveConfig, fetchModels, getConfigDir, getRulesFile } from "./config.js";
+import { runSetup, isConfigured, loadConfig, fetchModels, getConfigDir, getRulesFile, getActiveProvider } from "./config.js";
 import { setAutoApprove } from "./confirm.js";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import path from "path";
+import os from "os";
+import { fileURLToPath } from "url";
+import { initLogger, log } from "./logger.js";
 const rawArgs = process.argv.slice(2);
 // Extract leading global flags only, so subcommands can still use "-y"
 const args = [...rawArgs];
@@ -16,6 +19,45 @@ while (args[0] === "--yes" || args[0] === "-y") {
 }
 if (hasYes)
     setAutoApprove(true);
+/** Parse common flags in any position; unknown args become positionals. */
+function parseFlags(argv) {
+    let model;
+    let provider;
+    let resume;
+    const images = [];
+    let port;
+    let host;
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const take = () => (argv[i + 1] ? argv[++i] : "");
+        if ((a === "--model" || a === "-m") && argv[i + 1]) {
+            model = take();
+        }
+        else if (a === "--provider" && argv[i + 1]) {
+            provider = take();
+        }
+        else if (a === "--resume" && argv[i + 1]) {
+            resume = take();
+        }
+        else if ((a === "--image" || a === "-i") && argv[i + 1]) {
+            images.push(take());
+        }
+        else if ((a === "--port" || a === "-p") && argv[i + 1]) {
+            port = parseInt(take(), 10);
+        }
+        else if (a === "--host" && argv[i + 1]) {
+            host = take();
+        }
+        else if (a === "--yes" || a === "-y") {
+            setAutoApprove(true);
+        }
+        else {
+            positionals.push(a);
+        }
+    }
+    return { model, provider, resume, images, port, host, positionals };
+}
 function printUsage() {
     console.log(`
 min-agent - Minimal AI coding agent
@@ -26,9 +68,13 @@ Usage:
   min-agent chat                    Start interactive multi-turn chat
   min-agent chat --resume <id>      Resume a previous session
   min-agent code                    AI coding mode (project-aware)
-  min-agent setup                   Configure API provider (interactive)
+  min-agent setup                   Configure providers (interactive)
   min-agent models                  List available models
   min-agent history                 List saved sessions
+  min-agent history delete <id>     Delete a saved session
+  min-agent history rename <id> <t> Rename a saved session
+  min-agent history export <id> [-o <file>]  Export a session as JSON
+  min-agent update                  Check for updates and upgrade
   min-agent rules                   Show loaded instruction rules
   min-agent rules edit              Edit global rules file
   min-agent memory                  List all memories
@@ -36,15 +82,18 @@ Usage:
   min-agent memory search <query>   Search memories
   min-agent memory delete <index>   Delete a memory by number
   min-agent mcp add <name> <cmd>    Add a local MCP server (stdio)
-  min-agent mcp add <name> --url <url> [--sse] [--token <t>]  Add remote MCP (HTTP)
+  min-agent mcp add <name> --url <url> [--sse] [--streamable-http] [--token <t>]  Add remote MCP (HTTP)
   min-agent mcp remove <name>       Remove an MCP server
   min-agent mcp list                List configured MCP servers
   min-agent mcp check               Check MCP server availability
   min-agent skills list             List available skills
+  min-agent skills info <name>      Show skill details
+  min-agent skills enable|disable <name...> [--project]  Toggle skills
   min-agent serve [--host H] [--port P]   HTTP API (see docs/API.md)
 
 Options:
   --model, -m <model>    Override model for this request
+  --provider <name>      Use a specific configured provider
   --image, -i <path>     Attach an image (can be used multiple times)
   --yes, -y              Auto-approve all confirmations (dangerous commands, file overwrites)
 
@@ -72,6 +121,10 @@ function parseMcpAddArgs(argv) {
     let url;
     let token;
     let sse = false;
+    let streamableHttp = false;
+    let project = false;
+    let timeout;
+    const environment = {};
     const cmd = [];
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -83,6 +136,14 @@ function parseMcpAddArgs(argv) {
             sse = true;
             continue;
         }
+        if (a === "--streamable-http") {
+            streamableHttp = true;
+            continue;
+        }
+        if (a === "--project") {
+            project = true;
+            continue;
+        }
         if (a === "--url" && argv[i + 1]) {
             url = argv[++i];
             continue;
@@ -91,9 +152,38 @@ function parseMcpAddArgs(argv) {
             token = argv[++i];
             continue;
         }
+        if (a === "--timeout" && argv[i + 1]) {
+            const value = parseInt(argv[++i], 10);
+            if (!Number.isFinite(value) || value <= 0) {
+                console.error(`Invalid --timeout value: ${argv[i]} (must be a positive number of ms)`);
+                process.exit(1);
+            }
+            timeout = value;
+            continue;
+        }
+        if (a === "--env") {
+            const kv = argv[i + 1];
+            if (!kv) {
+                console.error("Invalid --env: missing KEY=VALUE");
+                process.exit(1);
+            }
+            const eq = kv.indexOf("=");
+            if (eq <= 0) {
+                console.error(`Invalid --env format: ${kv} (use KEY=VALUE)`);
+                process.exit(1);
+            }
+            i++;
+            environment[kv.slice(0, eq)] = kv.slice(eq + 1);
+            continue;
+        }
         cmd.push(a);
     }
-    return { skipCheck, url, token, sse, cmd };
+    return { skipCheck, url, token, sse, streamableHttp, project, timeout, environment, cmd };
+}
+/** One-line, length-capped text for list output. */
+function truncate(text, max) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
 }
 function ensureProjectDefaults() {
     const projectConfigDir = path.join(process.cwd(), ".min-agent");
@@ -113,32 +203,38 @@ async function main() {
         process.exit(0);
     }
     if (args[0] === "--version" || args[0] === "-v") {
-        const pkgPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../package.json");
+        const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
         const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
         console.log(pkg.version);
         process.exit(0);
     }
     const command = args[0];
+    initLogger();
+    log("info", `min-agent started: ${command}`);
     switch (command) {
         case "setup": {
             await runSetup();
             break;
         }
         case "models": {
+            const flags = parseFlags(args.slice(1));
             const config = loadConfig();
-            if (!config.provider?.baseURL || !config.provider?.apiKey) {
+            const provider = flags.provider
+                ? config.providers?.find((p) => p.name === flags.provider)
+                : getActiveProvider(config);
+            if (!provider?.baseURL || !provider?.apiKey) {
                 console.error("Not configured. Run: min-agent setup");
                 process.exit(1);
             }
-            console.log("Fetching models...");
-            const models = await fetchModels(config.provider.baseURL, config.provider.apiKey);
+            console.log(`Fetching models (${provider.name ?? "default"})...`);
+            const models = await fetchModels(provider.baseURL, provider.apiKey);
             if (models.length === 0) {
                 console.log("No models found or unable to fetch model list.");
             }
             else {
                 console.log(`\nAvailable models (${models.length}):`);
                 for (const m of models) {
-                    const marker = m === config.provider.defaultModel ? " ← default" : "";
+                    const marker = m === provider.defaultModel ? " ← default" : "";
                     console.log(`  ${m}${marker}`);
                 }
             }
@@ -149,32 +245,18 @@ async function main() {
                 console.error("Not configured. Run: min-agent setup");
                 process.exit(1);
             }
-            // Parse --model / -m, --resume, and --image / -i flags
-            let modelOverride;
-            let resumeId;
-            const images = [];
-            const chatArgs = [];
-            for (let i = 1; i < args.length; i++) {
-                if ((args[i] === "--model" || args[i] === "-m") && args[i + 1]) {
-                    modelOverride = args[++i];
-                }
-                else if (args[i] === "--resume" && args[i + 1]) {
-                    resumeId = args[++i];
-                }
-                else if ((args[i] === "--image" || args[i] === "-i") && args[i + 1]) {
-                    images.push(args[++i]);
-                }
-                else {
-                    chatArgs.push(args[i]);
-                }
+            const { model: modelOverride, provider: providerOverride, resume: resumeId, images, positionals } = parseFlags(args.slice(1));
+            const message = positionals.join(" ");
+            if (resumeId && message) {
+                console.error("--resume <id> cannot be combined with a message; run `min-agent chat --resume <id>` to continue that session");
+                process.exit(1);
             }
-            const message = chatArgs.join(" ");
             if (!message) {
                 const { runTui } = await import("./tui-chat.js");
-                await runTui({ modelId: modelOverride, resumeSessionId: resumeId, mode: "chat" });
+                await runTui({ modelId: modelOverride, providerName: providerOverride, resumeSessionId: resumeId, mode: "chat", images });
             }
             else {
-                await runAgent(message, modelOverride, images.length > 0 ? images : undefined);
+                await runAgent(message, modelOverride, images.length > 0 ? images : undefined, providerOverride);
             }
             break;
         }
@@ -183,18 +265,9 @@ async function main() {
                 console.error("Not configured. Run: min-agent setup");
                 process.exit(1);
             }
-            let modelOverride;
-            let resumeId;
-            for (let i = 1; i < args.length; i++) {
-                if ((args[i] === "--model" || args[i] === "-m") && args[i + 1]) {
-                    modelOverride = args[++i];
-                }
-                else if (args[i] === "--resume" && args[i + 1]) {
-                    resumeId = args[++i];
-                }
-            }
+            const { model: modelOverride, provider: providerOverride, resume: resumeId } = parseFlags(args.slice(1));
             const { runTui } = await import("./tui-chat.js");
-            await runTui({ modelId: modelOverride, resumeSessionId: resumeId, mode: "code" });
+            await runTui({ modelId: modelOverride, providerName: providerOverride, resumeSessionId: resumeId, mode: "code" });
             break;
         }
         case "serve": {
@@ -202,16 +275,7 @@ async function main() {
                 console.error("Not configured. Run: min-agent setup");
                 process.exit(1);
             }
-            let servePort;
-            let serveHost;
-            for (let i = 1; i < args.length; i++) {
-                if ((args[i] === "--port" || args[i] === "-p") && args[i + 1]) {
-                    servePort = parseInt(args[++i], 10);
-                }
-                else if (args[i] === "--host" && args[i + 1]) {
-                    serveHost = args[++i];
-                }
-            }
+            const { port: servePort, host: serveHost } = parseFlags(args.slice(1));
             const { runServe } = await import("./serve.js");
             await runServe({ port: servePort, host: serveHost });
             break;
@@ -222,42 +286,59 @@ async function main() {
                 console.log(`Usage: min-agent mcp <command>
 
 Commands:
-  list              List configured MCP servers (name + status)
-  info <name>       Show details of a server
-  add <name> ...    Add a new server (stdio or remote)
-  remove <name>     Remove a server
-  enable <name>     Enable a disabled server
-  disable <name>    Disable a server
-  check             Test connectivity of all servers`);
+  list                          List configured MCP servers (name + status + scope)
+  info <name>                   Show details of a server
+  add <name> ...                Add a new server (stdio or remote)
+  remove <name> [--project]     Remove a server
+  enable <name...> [--project]  Enable a disabled server
+  disable <name...> [--project] Disable a server
+  check                         Test connectivity of all servers
+
+Add flags:
+  --project                     Write to .min-agent/mcp.json (project scope)
+  --url <url>                   Remote server URL
+  --sse | --streamable-http     Remote transport mode (default: auto)
+  --token <t>                   Bearer token for remote servers
+  --env KEY=VALUE               Extra env for stdio servers (repeatable)
+  --timeout <ms>                Connection/call timeout
+  --skip-check                  Skip validation before saving`);
                 process.exit(0);
             }
             switch (subcommand) {
                 case "add": {
                     const name = args[2];
                     if (!name) {
-                        console.error("Usage: min-agent mcp add <name> [--skip-check] <command...>");
-                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse] [--token <bearer>] [--skip-check]");
+                        console.error("Usage: min-agent mcp add <name> [--project] [--skip-check] <command...>");
+                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse|--streamable-http] [--token <bearer>] [--project] [--skip-check]");
+                        process.exit(1);
+                    }
+                    const { skipCheck, url, token, sse, streamableHttp, project, timeout, environment, cmd } = parseMcpAddArgs(args.slice(3));
+                    const scope = project ? "project" : "global";
+                    if (sse && streamableHttp) {
+                        console.error("--sse and --streamable-http are mutually exclusive");
                         process.exit(1);
                     }
-                    const { skipCheck, url, token, sse, cmd } = parseMcpAddArgs(args.slice(3));
                     let entry;
                     if (url?.trim()) {
                         entry = {
                             url: url.trim(),
                             enabled: true,
-                            remoteTransport: sse ? "sse" : "auto",
+                            remoteTransport: streamableHttp ? "streamable-http" : sse ? "sse" : "auto",
+                            ...(timeout ? { timeout } : {}),
                         };
                         if (token?.trim())
                             entry.token = token.trim();
                     }
                     else if (cmd.length > 0) {
-                        entry = { command: cmd, enabled: true };
+                        entry = { command: cmd, enabled: true, ...(timeout ? { timeout } : {}) };
                     }
                     else {
-                        console.error("Usage: min-agent mcp add <name> [--skip-check] <command...>");
-                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse] [--token <bearer>] [--skip-check]");
+                        console.error("Usage: min-agent mcp add <name> [--project] [--skip-check] <command...>");
+                        console.error("   or: min-agent mcp add <name> --url <https://host/mcp> [--sse|--streamable-http] [--token <bearer>] [--project] [--skip-check]");
                         process.exit(1);
                     }
+                    if (Object.keys(environment).length > 0)
+                        entry.environment = environment;
                     let detectedTools = 0;
                     if (!skipCheck) {
                         console.log(`Validating MCP server "${name}"...`);
@@ -271,41 +352,47 @@ Commands:
                     else {
                         console.log(`Skipping MCP validation for "${name}" (--skip-check).`);
                     }
-                    const config = loadMcpConfig();
+                    const config = loadMcpConfigFile(scope);
                     config.mcpServers[name] = entry;
-                    saveMcpConfig(config);
+                    saveMcpConfig(config, scope);
                     const toolsSuffix = skipCheck ? "" : ` (${detectedTools} tools detected)`;
-                    console.log(`✓ MCP server "${name}" added: ${formatMcpServerBinding(entry)}${toolsSuffix}`);
+                    const scopeSuffix = project ? " [project]" : "";
+                    console.log(`✓ MCP server "${name}" added${scopeSuffix}: ${formatMcpServerBinding(entry)}${toolsSuffix}`);
                     break;
                 }
                 case "remove": {
-                    const name = args[2];
+                    const project = args.includes("--project");
+                    const scope = project ? "project" : "global";
+                    const name = args.slice(2).find((a) => a !== "--project");
                     if (!name) {
-                        console.error("Usage: min-agent mcp remove <name>");
+                        console.error("Usage: min-agent mcp remove <name> [--project]");
                         process.exit(1);
                     }
-                    const config = loadMcpConfig();
+                    const config = loadMcpConfigFile(scope);
                     if (!config.mcpServers[name]) {
-                        console.error(`MCP server "${name}" not found`);
+                        const elsewhere = loadMcpConfigEntries().find((e) => e.name === name);
+                        console.error(elsewhere
+                            ? `MCP server "${name}" is defined in ${elsewhere.scope} scope, not ${scope}.`
+                            : `MCP server "${name}" not found`);
                         process.exit(1);
                     }
                     delete config.mcpServers[name];
-                    saveMcpConfig(config);
-                    console.log(`✓ MCP server "${name}" removed`);
+                    saveMcpConfig(config, scope);
+                    console.log(`✓ MCP server "${name}" removed${project ? " [project]" : ""}`);
                     break;
                 }
                 case "list": {
-                    const config = loadMcpConfig();
-                    const servers = Object.entries(config.mcpServers);
-                    if (servers.length === 0) {
+                    const entries = loadMcpConfigEntries();
+                    if (entries.length === 0) {
                         console.log("No MCP servers configured.");
                         console.log("Add one with: min-agent mcp add <name> <command...>");
                     }
                     else {
                         console.log("MCP Servers:");
-                        for (const [name, cfg] of servers) {
-                            const status = cfg.enabled === false ? "\x1b[90mdisabled\x1b[0m" : "\x1b[32menabled\x1b[0m";
-                            console.log(`  ${name}  ${status}`);
+                        for (const { name, config, scope } of entries) {
+                            const status = config.enabled === false ? "\x1b[90mdisabled\x1b[0m" : "\x1b[32menabled\x1b[0m";
+                            const scopeMark = scope === "project" ? " \x1b[90m[project]\x1b[0m" : "";
+                            console.log(`  ${name}  ${status}${scopeMark}`);
                         }
                         console.log("\nUse: min-agent mcp info <name>  for details");
                     }
@@ -317,25 +404,39 @@ Commands:
                         console.error("Usage: min-agent mcp info <name>");
                         process.exit(1);
                     }
-                    const config = loadMcpConfig();
-                    const cfg = config.mcpServers[name];
-                    if (!cfg) {
+                    const found = loadMcpConfigEntries().find((e) => e.name === name);
+                    if (!found) {
                         console.error(`MCP server "${name}" not found`);
                         process.exit(1);
                     }
+                    const cfg = found.config;
                     console.log(`Name:      ${name}`);
+                    console.log(`Scope:     ${found.scope}`);
                     console.log(`Status:    ${cfg.enabled === false ? "disabled" : "enabled"}`);
                     console.log(`Binding:   ${formatMcpServerBinding(cfg)}`);
                     if (cfg.command)
                         console.log(`Command:   ${Array.isArray(cfg.command) ? cfg.command.join(" ") : `${cfg.command} ${(cfg.args ?? []).join(" ")}`.trim()}`);
-                    if (cfg.url)
+                    if (cfg.url) {
                         console.log(`URL:       ${cfg.url}`);
+                        if (cfg.remoteTransport)
+                            console.log(`Transport: ${cfg.remoteTransport}`);
+                        if (cfg.oauth === false)
+                            console.log(`OAuth:     disabled`);
+                        else if (cfg.oauth)
+                            console.log(`OAuth:     enabled${cfg.oauth.clientId ? ` (clientId set)` : ""}`);
+                    }
+                    if (cfg.headers)
+                        console.log(`Headers:   ${Object.keys(cfg.headers).join(", ")} (values hidden)`);
                     if (cfg.token)
                         console.log(`Token:     ***`);
                     if (cfg.environment)
                         console.log(`Env:       ${Object.keys(cfg.environment).join(", ")}`);
                     if (cfg.timeout)
                         console.log(`Timeout:   ${cfg.timeout}ms`);
+                    if (cfg.connectTimeout)
+                        console.log(`ConnectTimeout: ${cfg.connectTimeout}ms`);
+                    if (cfg.callTimeout)
+                        console.log(`CallTimeout:    ${cfg.callTimeout}ms`);
                     break;
                 }
                 case "check": {
@@ -370,39 +471,43 @@ Commands:
                     break;
                 }
                 case "enable": {
-                    const names = args.slice(2);
+                    const project = args.includes("--project");
+                    const scope = project ? "project" : "global";
+                    const names = args.slice(2).filter((a) => a !== "--project");
                     if (names.length === 0) {
-                        console.error("Usage: min-agent mcp enable <name...>");
+                        console.error("Usage: min-agent mcp enable <name...> [--project]");
                         process.exit(1);
                     }
-                    const config = loadMcpConfig();
+                    const config = loadMcpConfigFile(scope);
                     for (const name of names) {
                         if (!config.mcpServers[name]) {
-                            console.error(`MCP server "${name}" not found`);
+                            console.error(`MCP server "${name}" not found${project ? " in project scope" : ""}`);
                             continue;
                         }
                         config.mcpServers[name].enabled = true;
-                        console.log(`✓ MCP server "${name}" enabled`);
+                        console.log(`✓ MCP server "${name}" enabled${project ? " [project]" : ""}`);
                     }
-                    saveMcpConfig(config);
+                    saveMcpConfig(config, scope);
                     break;
                 }
                 case "disable": {
-                    const names = args.slice(2);
+                    const project = args.includes("--project");
+                    const scope = project ? "project" : "global";
+                    const names = args.slice(2).filter((a) => a !== "--project");
                     if (names.length === 0) {
-                        console.error("Usage: min-agent mcp disable <name...>");
+                        console.error("Usage: min-agent mcp disable <name...> [--project]");
                         process.exit(1);
                     }
-                    const config = loadMcpConfig();
+                    const config = loadMcpConfigFile(scope);
                     for (const name of names) {
                         if (!config.mcpServers[name]) {
-                            console.error(`MCP server "${name}" not found`);
+                            console.error(`MCP server "${name}" not found${project ? " in project scope" : ""}`);
                             continue;
                         }
                         config.mcpServers[name].enabled = false;
-                        console.log(`✓ MCP server "${name}" disabled`);
+                        console.log(`✓ MCP server "${name}" disabled${project ? " [project]" : ""}`);
                     }
-                    saveMcpConfig(config);
+                    saveMcpConfig(config, scope);
                     break;
                 }
                 default:
@@ -412,6 +517,74 @@ Commands:
             break;
         }
         case "history": {
+            const subcommand = args[1];
+            if (subcommand === "delete") {
+                const id = args[2];
+                if (!id) {
+                    console.error("Usage: min-agent history delete <id>");
+                    process.exit(1);
+                }
+                const { deleteSession } = await import("./sessions.js");
+                if (deleteSession(id)) {
+                    console.log(`✓ 会话 ${id} 已删除`);
+                }
+                else {
+                    console.error(`会话 ${id} 不存在`);
+                    process.exit(1);
+                }
+                break;
+            }
+            if (subcommand === "rename") {
+                const id = args[2];
+                const title = args.slice(3).join(" ");
+                if (!id || !title) {
+                    console.error("Usage: min-agent history rename <id> <title>");
+                    process.exit(1);
+                }
+                const { renameSession } = await import("./sessions.js");
+                if (renameSession(id, title)) {
+                    console.log(`✓ 会话 ${id} 已重命名为: ${title}`);
+                }
+                else {
+                    console.error(`会话 ${id} 不存在`);
+                    process.exit(1);
+                }
+                break;
+            }
+            if (subcommand === "export") {
+                const id = args[2];
+                if (!id) {
+                    console.error("Usage: min-agent history export <id> [-o <file>]");
+                    process.exit(1);
+                }
+                const { loadSession } = await import("./sessions.js");
+                const session = loadSession(id);
+                if (!session) {
+                    console.error(`会话 ${id} 不存在`);
+                    process.exit(1);
+                }
+                const json = JSON.stringify(session, null, 2);
+                const outIdx = args.indexOf("-o");
+                const outFile = outIdx !== -1 ? args[outIdx + 1] : undefined;
+                if (outFile) {
+                    try {
+                        writeFileSync(outFile, json, "utf-8");
+                        console.log(`✓ 会话 ${id} 已导出到 ${outFile}`);
+                    }
+                    catch (err) {
+                        console.error(`导出失败: ${err.message}`);
+                        process.exit(1);
+                    }
+                }
+                else {
+                    if (outIdx !== -1) {
+                        console.error("Usage: min-agent history export <id> [-o <file>]（-o 后缺少文件路径）");
+                        process.exit(1);
+                    }
+                    console.log(json);
+                }
+                break;
+            }
             const { listSessions } = await import("./sessions.js");
             const sessions = listSessions();
             if (sessions.length === 0) {
@@ -502,89 +675,174 @@ Commands:
                 console.log(`Usage: min-agent skills <command>
 
 Commands:
-  list              List skills (name + status)
-  info <name>       Show details of a skill
-  enable <name>     Enable a disabled skill
-  disable <name>    Disable a skill`);
+  list                    List skills (name + status + description)
+  info <name>             Show details of a skill
+  new <name>              Create a new skill scaffold
+  enable <name...>        Enable disabled skills
+  disable <name...>       Disable skills
+
+Options (enable/disable):
+  --project               Apply to this project only (.min-agent/config.json)
+  --global                Apply to every project (default, ~/.min-agent/config.json)
+
+Options (list/info):
+  --json                  Machine-readable JSON output
+
+Options (new):
+  --global                Create in ~/.agents/skills/ instead of .min-agent/skills/
+
+Project scope wins over global, so a skill disabled globally can be
+re-enabled for one repo with: min-agent skills enable <name> --project
+
+Skills are discovered in (later paths override earlier ones):
+  ~/.agents/skills/       .min-agent/skills/       .agents/skills/
+  .opencode/skills/       .claude/skills/`);
                 process.exit(0);
             }
             switch (subcommand) {
                 case "info": {
-                    const name = args[2];
+                    const flags = args.slice(2);
+                    const name = flags.find((a) => !a.startsWith("-"));
                     if (!name) {
-                        console.error("Usage: min-agent skills info <name>");
+                        console.error("Usage: min-agent skills info <name> [--json]");
                         process.exit(1);
                     }
                     discoverSkills({ silent: true });
-                    const { getSkill } = await import("./skills.js");
+                    const { getSkill, getAllSkills } = await import("./skills.js");
                     const skill = getSkill(name);
                     if (!skill) {
-                        console.error(`Skill "${name}" not found`);
+                        const names = getAllSkills().map((s) => s.name);
+                        console.error(`Skill "${name}" not found.${names.length ? ` Available: ${names.join(", ")}` : " No skills discovered."}`);
                         process.exit(1);
                     }
-                    const config = loadConfig();
-                    const isDisabled = (config.disabledSkills ?? []).includes(name);
+                    if (flags.includes("--json")) {
+                        console.log(JSON.stringify(skill, null, 2));
+                        break;
+                    }
                     console.log(`Name:        ${skill.name}`);
-                    console.log(`Status:      ${isDisabled ? "disabled" : "enabled"}`);
+                    console.log(`Status:      ${skill.enabled ? "enabled" : `disabled (${skill.disabledScope} scope)`}`);
+                    if (skill.version)
+                        console.log(`Version:     ${skill.version}`);
                     console.log(`Description: ${skill.description}`);
                     console.log(`Location:    ${skill.location}`);
+                    if (skill.allowedTools.length > 0)
+                        console.log(`Tools:       ${skill.allowedTools.join(", ")}`);
+                    if (skill.requiredBins.length > 0)
+                        console.log(`Requires:    ${skill.requiredBins.join(", ")}`);
+                    if (skill.content.trim()) {
+                        console.log("\n--- Content ---\n");
+                        console.log(skill.content.trim());
+                    }
                     break;
                 }
-                case "enable": {
-                    const names = args.slice(2);
+                case "enable":
+                case "disable": {
+                    const flags = args.slice(2);
+                    const scope = flags.includes("--project") ? "project" : "global";
+                    const names = flags.filter((a) => a !== "--project" && a !== "--global");
+                    const unknownFlag = flags.find((a) => a.startsWith("-") && a !== "--project" && a !== "--global");
+                    if (unknownFlag) {
+                        console.error(`Unknown option: ${unknownFlag} (use --project or --global)`);
+                        process.exit(1);
+                    }
                     if (names.length === 0) {
-                        console.error("Usage: min-agent skills enable <name...>");
+                        console.error(`Usage: min-agent skills ${subcommand} <name...> [--project]`);
+                        process.exit(1);
+                    }
+                    discoverSkills({ silent: true });
+                    const { getAllSkills, setSkillEnabled, getStaleDisabledSkills } = await import("./skills.js");
+                    const known = new Set(getAllSkills().map((s) => s.name));
+                    const stale = new Set(getStaleDisabledSkills());
+                    // `enable` must accept stale names so they can be cleaned up from config;
+                    // `disable` on an unknown name is always an error.
+                    const unknown = names.filter((n) => !known.has(n) && !(subcommand === "enable" && stale.has(n)));
+                    if (unknown.length > 0) {
+                        console.error(`Skill${unknown.length > 1 ? "s" : ""} not found: ${unknown.join(", ")}`);
+                        console.error(known.size ? `Available: ${[...known].join(", ")}` : "No skills discovered.");
                         process.exit(1);
                     }
-                    const config = loadConfig();
-                    config.disabledSkills = (config.disabledSkills ?? []).filter((s) => !names.includes(s));
-                    saveConfig(config);
-                    for (const name of names)
-                        console.log(`✓ Skill "${name}" enabled`);
+                    for (const result of setSkillEnabled(names, subcommand === "enable", scope)) {
+                        console.log(`✓ Skill "${result.name}" ${subcommand}d (${scope} scope)`);
+                        if (result.blockedBy) {
+                            console.log(`\x1b[33m  ⚠ still ${result.enabled ? "enabled" : "disabled"} — overridden by ${result.blockedBy} scope\x1b[0m`);
+                        }
+                    }
                     break;
                 }
-                case "disable": {
-                    const names = args.slice(2);
-                    if (names.length === 0) {
-                        console.error("Usage: min-agent skills disable <name...>");
+                case "new": {
+                    const flags = args.slice(2);
+                    const name = flags.find((a) => !a.startsWith("-"));
+                    if (!name || !/^[\w-]+$/.test(name)) {
+                        console.error("Usage: min-agent skills new <name> [--global]  (name: letters, digits, _ or -)");
                         process.exit(1);
                     }
-                    const config = loadConfig();
-                    const disabled = config.disabledSkills ?? [];
-                    for (const name of names) {
-                        if (!disabled.includes(name))
-                            disabled.push(name);
-                        console.log(`✓ Skill "${name}" disabled`);
+                    const global = flags.includes("--global");
+                    const root = global ? path.join(os.homedir(), ".agents", "skills") : path.join(process.cwd(), ".min-agent", "skills");
+                    const dir = path.join(root, name);
+                    if (existsSync(path.join(dir, "SKILL.md"))) {
+                        console.error(`Skill "${name}" already exists at ${dir}`);
+                        process.exit(1);
                     }
-                    config.disabledSkills = disabled;
-                    saveConfig(config);
+                    mkdirSync(dir, { recursive: true });
+                    writeFileSync(path.join(dir, "SKILL.md"), `---\nname: ${name}\ndescription: What this skill does\n# version: 1.0.0\n# allowed-tools: [read, grep]\n# metadata:\n#   requires:\n#     bins: ["some-cli"]\n---\n\n# ${name}\n\nWrite the skill instructions here.\n`, "utf-8");
+                    console.log(`✓ Created skill "${name}" at ${path.join(dir, "SKILL.md")}`);
                     break;
                 }
                 case "list": {
+                    const json = args.includes("--json");
                     discoverSkills({ silent: true });
-                    const skills = getSkills();
-                    const config = loadConfig();
-                    const disabledNames = config.disabledSkills ?? [];
-                    if (skills.length === 0 && disabledNames.length === 0) {
+                    const { getAllSkills, getStaleDisabledSkills } = await import("./skills.js");
+                    const all = getAllSkills().sort((a, b) => a.name.localeCompare(b.name));
+                    const stale = getStaleDisabledSkills();
+                    if (json) {
+                        console.log(JSON.stringify({
+                            count: all.length,
+                            enabled_count: all.filter((s) => s.enabled).length,
+                            stale_disabled: stale,
+                            skills: all.map((s) => ({
+                                name: s.name,
+                                description: s.description,
+                                location: s.location,
+                                enabled: s.enabled,
+                                ...(s.disabledScope ? { disabled_scope: s.disabledScope } : {}),
+                                ...(s.version ? { version: s.version } : {}),
+                                ...(s.allowedTools.length ? { allowed_tools: s.allowedTools } : {}),
+                                ...(s.requiredBins.length ? { requires_bins: s.requiredBins } : {}),
+                            })),
+                        }, null, 2));
+                        break;
+                    }
+                    if (all.length === 0 && stale.length === 0) {
                         console.log("No skills found. Add SKILL.md files in .min-agent/skills/<name>/");
                         break;
                     }
-                    console.log("Skills:");
-                    for (const skill of skills) {
-                        console.log(`  ${skill.name}  \x1b[32menabled\x1b[0m`);
+                    console.log(`Skills (${all.filter((s) => s.enabled).length} enabled, ${all.filter((s) => !s.enabled).length} disabled):`);
+                    for (const skill of all) {
+                        const status = skill.enabled
+                            ? "\x1b[32menabled \x1b[0m"
+                            : `\x1b[90mdisabled(${skill.disabledScope === "project" ? "proj" : "glob"})\x1b[0m`;
+                        console.log(`  ${skill.name}  ${status}  \x1b[90m${truncate(skill.description, 60)}\x1b[0m`);
+                        console.log(`    \x1b[90m${skill.location}\x1b[0m`);
                     }
-                    for (const n of disabledNames) {
-                        console.log(`  ${n}  \x1b[90mdisabled\x1b[0m`);
+                    if (stale.length > 0) {
+                        console.log(`\n\x1b[33m⚠ disabledSkills/enabledSkills entries matching no skill: ${stale.join(", ")}\x1b[0m`);
+                        console.log(`\x1b[33m  Remove them with: min-agent skills enable ${stale.join(" ")} (add --project if the entry is project-scoped)\x1b[0m`);
                     }
                     console.log("\nUse: min-agent skills info <name>  for details");
                     break;
                 }
                 default:
-                    console.error("Usage: min-agent skills -h");
+                    console.error(`Unknown skills command: ${subcommand}`);
+                    console.error("Available: list, info, new, enable, disable  (see: min-agent skills -h)");
                     process.exit(1);
             }
             break;
         }
+        case "update": {
+            const { runUpdate } = await import("./updater.js");
+            await runUpdate();
+            break;
+        }
         case "init": {
             ensureProjectDefaults();
             console.log(`✓ Initialized .min-agent/ in ${process.cwd()}`);