muxed 0.2.2 → 0.2.3

package/dist/cli.mjs

@@ -3308,7 +3308,10 @@ function formatTable(headers, rows) {
 		...rows.map((row) => row.map((cell, i) => padRight(cell, widths[i])).join("  "))
 	].join("\n");
 }
-const serversCommand = new Command("servers").description("List connected MCP servers and their connection status").option("--json", "Output as JSON").action(async (opts) => {
+const serversCommand = new Command("servers").description("List connected MCP servers and their status").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed servers              List all servers with connection state
+  muxed servers --json       JSON output for scripting`).action(async (opts) => {
 	const configPath = serversCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("servers/list");
@@ -3367,7 +3370,18 @@ async function shutdown() {
 		if (_client) await _client.shutdown();
 	} catch {}
 }
-const toolsCommand = new Command("tools").description("List all available tools, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").option("--include <fields>", "Include additional fields (e.g. \"schema\")").option("--depth <n>", "Schema collapse depth (requires --include schema)", parseInt).action(async (server, opts) => {
+const toolsCommand = new Command("tools").description("List available tools across all servers").argument("[server]", "Show tools from this server only").option("--json", "Output as JSON (machine-readable)").option("--include <fields>", "Include extra fields: \"schema\" adds input schemas").option("--depth <n>", "Collapse schemas deeper than N levels (use with --include schema)", parseInt).addHelpText("after", `
+Schema options:
+  --include schema        Add input schemas to each tool in the output.
+  --include schema --depth N  Collapse schemas beyond N levels. Nodes deeper than N
+                          are replaced with { _collapsed: true, _hint: "..." }.
+                          Depth is auto-selected to fit a token budget if omitted.
+
+Examples:
+  muxed tools                              List all tools (names + descriptions)
+  muxed tools postgres                     List tools from the "postgres" server only
+  muxed tools --include schema             List with full input schemas
+  muxed tools --include schema --depth 1   List with schemas collapsed at depth 1`).action(async (server, opts) => {
 	const configPath = toolsCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const params = {};
@@ -3381,7 +3395,24 @@ const toolsCommand = new Command("tools").description("List all available tools,
 	});
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
-const infoCommand = new Command("info").description("Show input schema and description for a specific tool").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").option("--json", "Output as JSON").option("--path <path>", "Extract a subtree of the input schema (e.g. \"filters.tags\")").option("--depth <n>", "Collapse schema at this depth", parseInt).action(async (serverTool, opts) => {
+const infoCommand = new Command("info").description("Show a tool's input schema — REQUIRED before calling any tool").argument("<server/tool>", "server_name/tool_name (e.g. postgres/query)").option("--json", "Output as JSON (machine-readable)").option("--path <path>", "Show only a subtree of the schema (e.g. \"filters.tags\")").option("--depth <n>", "Collapse schema deeper than N levels", parseInt).addHelpText("after", `
+Schema exploration:
+  --depth N   Show schema to N levels deep. Nodes beyond that depth are
+              replaced with a summary: { _collapsed: true, _hint: "5 properties, 2 required" }.
+              Scalar fields (string, number, boolean) are always shown regardless of depth.
+              Start with --depth 1 for an overview, increase to explore deeper.
+
+  --path P    Extract a subtree using dot-separated path. Navigates through:
+              properties (by name), items, additionalProperties, anyOf/oneOf (by index).
+              Combine with --depth to control how much of the subtree is shown.
+
+Examples:
+  muxed info postgres/query                        Full schema
+  muxed info github/create_issue --depth 1         Top-level fields only, nested objects collapsed
+  muxed info github/create_issue --depth 2         Two levels deep
+  muxed info slack/search --path "filters"         Only the "filters" property subtree
+  muxed info slack/search --path "filters.tags"    Drill into filters.tags
+  muxed info api/create --path "body.items" --depth 1  Subtree with depth limit`).action(async (serverTool, opts) => {
 	const configPath = infoCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const params = { name: serverTool };
@@ -3406,7 +3437,13 @@ function readStdin() {
 		process.stdin.on("error", reject);
 	});
 }
-const callCommand = new Command("call").description("Execute a tool with JSON arguments (use - for stdin, --async for background)").argument("<server/tool>", "Tool identifier (e.g. myserver/mytool)").argument("[json]", "JSON arguments (use - for stdin)").option("--timeout <ms>", "Request timeout in milliseconds").option("--async", "Use task-based execution (return task handle immediately)").option("--dry-run", "Validate arguments against tool schema without executing").option("--fields <paths>", "Comma-separated dot-notation paths to extract from response").option("--json", "Output as JSON").action(async (serverTool, jsonArgs, opts) => {
+const callCommand = new Command("call").description("Execute a tool with JSON arguments").argument("<server/tool>", "server_name/tool_name (e.g. postgres/query)").argument("[json]", "JSON object with arguments, or - to read from stdin").option("--dry-run", "Validate arguments without executing (catches errors early)").option("--fields <paths>", "Extract specific fields from response (comma-separated dot-notation)").option("--timeout <ms>", "Timeout in milliseconds").option("--async", "Run in background, return a task ID instead of waiting").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed call postgres/query '{"sql": "SELECT * FROM users LIMIT 5"}'
+  muxed call fs/read_file '{"path": "/tmp/data.json"}' --fields "content"
+  muxed call server/tool '{"a": 1}' --dry-run     Validate without executing
+  echo '{"sql": "..."}' | muxed call db/query -    Read args from stdin
+  muxed call analytics/export '{}' --async         Returns task ID immediately`).action(async (serverTool, jsonArgs, opts) => {
 	const configPath = callCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	let parsedArgs = {};
@@ -3545,7 +3582,16 @@ const callCommand = new Command("call").description("Execute a tool with JSON ar
 		process.exit(1);
 	}
 });
-const grepCommand = new Command("grep").description("Search tools by regex pattern across names, titles, and descriptions").argument("<pattern>", "Regex pattern to search").option("--json", "Output as JSON").option("--include <fields>", "Include additional fields (e.g. \"schema\")").option("--depth <n>", "Schema collapse depth (requires --include schema)", parseInt).action(async (pattern, opts) => {
+const grepCommand = new Command("grep").description("Search tools by name or description (regex)").argument("<pattern>", "Regex pattern to match against tool names and descriptions").option("--json", "Output as JSON (machine-readable)").option("--include <fields>", "Include extra fields: \"schema\" adds input schemas").option("--depth <n>", "Collapse schemas deeper than N levels (use with --include schema)", parseInt).addHelpText("after", `
+Schema options:
+  --include schema        Add input schemas to matching tools.
+  --include schema --depth N  Collapse schemas beyond N levels.
+
+Examples:
+  muxed grep "search"                              Find tools related to searching
+  muxed grep "file|read"                           Regex: tools matching "file" or "read"
+  muxed grep "query" --include schema --depth 1    Matches with top-level schema
+  muxed grep "query" --json                        Machine-readable output for scripting`).action(async (pattern, opts) => {
 	const configPath = grepCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const params = { pattern };
@@ -3555,13 +3601,19 @@ const grepCommand = new Command("grep").description("Search tools by regex patte
 	capture("tools_searched", { result_count: result.length });
 	console.log(opts.json ? formatJson(result) : formatTools(result));
 });
-const resourcesCommand = new Command("resources").description("List available resources, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
+const resourcesCommand = new Command("resources").description("List available MCP resources across all servers").argument("[server]", "Show resources from this server only").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed resources              List all resources
+  muxed resources github       List resources from the "github" server only`).action(async (server, opts) => {
 	const configPath = resourcesCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("resources/list", server ? { server } : void 0);
 	console.log(opts.json ? formatJson(result) : formatResources(result));
 });
-const readCommand = new Command("read").description("Fetch and display the contents of a resource by server/resource").argument("<server/resource>", "Resource identifier (e.g. myserver/myresource)").argument("[uri]", "Resource URI (optional, uses resource name as URI if not provided)").option("--json", "Output as JSON").action(async (serverResource, uri, opts) => {
+const readCommand = new Command("read").description("Fetch and display the contents of an MCP resource").argument("<server/resource>", "server_name/resource_name (e.g. github/repos)").argument("[uri]", "Custom URI (defaults to the resource name)").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed read github/repos                  Read using resource name as URI
+  muxed read github/repos "github://repos" Read with explicit URI`).action(async (serverResource, uri, opts) => {
 	const configPath = readCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = serverResource.indexOf("/");
@@ -3578,8 +3630,10 @@ const readCommand = new Command("read").description("Fetch and display the conte
 function getExplicitConfig$1(cmd) {
 	return cmd.parent?.parent?.opts().config;
 }
-const daemonCommand = new Command("daemon").description("Start, stop, reload, or check status of the muxed background daemon").enablePositionalOptions();
-daemonCommand.command("start").description("Start the daemon process in the background").option("--json", "Output as JSON").action(async (opts) => {
+const daemonCommand = new Command("daemon").description("Manage the muxed background daemon").enablePositionalOptions().addHelpText("after", `
+The daemon auto-starts on first CLI command and shuts down after 5 min idle.
+These subcommands are for manual lifecycle control.`);
+daemonCommand.command("start").description("Start the daemon (usually not needed — auto-starts on first command)").option("--json", "Output as JSON (machine-readable)").action(async (opts) => {
 	const configPath = getExplicitConfig$1(daemonCommand);
 	if (await isDaemonRunning()) {
 		if (opts.json) console.log(formatJson({ status: "already_running" }));
@@ -3630,13 +3684,13 @@ daemonCommand.command("stop").description("Stop the running daemon process").act
 		console.log("Daemon is not running");
 	}
 });
-daemonCommand.command("reload").description("Reload config and reconnect changed servers without restarting").option("--json", "Output as JSON").action(async (opts) => {
+daemonCommand.command("reload").description("Reload config and reconnect changed servers (no restart)").option("--json", "Output as JSON (machine-readable)").action(async (opts) => {
 	const configPath = getExplicitConfig$1(daemonCommand);
 	await ensureDaemon(configPath);
 	const result = await sendRequest("config/reload", { configPath });
 	console.log(opts.json ? formatJson(result) : formatReload(result));
 });
-daemonCommand.command("status").description("Show daemon status including uptime and connected servers").option("--json", "Output as JSON").action(async (opts) => {
+daemonCommand.command("status").description("Show PID, uptime, and connected servers").option("--json", "Output as JSON (machine-readable)").action(async (opts) => {
 	if (!await isDaemonRunning()) {
 		console.log("Daemon is not running");
 		return;
@@ -3644,13 +3698,15 @@ daemonCommand.command("status").description("Show daemon status including uptime
 	const result = await sendRequest("daemon/status");
 	console.log(opts.json ? formatJson(result) : formatStatus(result));
 });
-const promptsCommand = new Command("prompts").description("List available prompt templates, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
+const promptsCommand = new Command("prompts").description("List available MCP prompt templates across all servers").argument("[server]", "Show prompts from this server only").option("--json", "Output as JSON (machine-readable)").action(async (server, opts) => {
 	const configPath = promptsCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("prompts/list", server ? { server } : void 0);
 	console.log(opts.json ? formatJson(result) : formatPrompts(result));
 });
-const promptCommand = new Command("prompt").description("Render a prompt template with optional JSON arguments").argument("<server/prompt>", "Prompt identifier (e.g. myserver/myprompt)").argument("[args-json]", "JSON arguments").option("--json", "Output as JSON").action(async (serverPrompt, argsJson, opts) => {
+const promptCommand = new Command("prompt").description("Render a prompt template with arguments").argument("<server/prompt>", "server_name/prompt_name (e.g. myserver/summarize)").argument("[args-json]", "JSON object with template arguments").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed prompt myserver/summarize '{"text": "..."}'`).action(async (serverPrompt, argsJson, opts) => {
 	const configPath = promptCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = serverPrompt.indexOf("/");
@@ -3674,7 +3730,10 @@ const promptCommand = new Command("prompt").description("Render a prompt templat
 	});
 	console.log(opts.json ? formatJson(result) : formatPromptMessages(result));
 });
-const completionsCommand = new Command("completions").description("Get auto-completion suggestions for prompt or resource arguments").argument("<type>", "Reference type (prompt or resource)").argument("<name>", "Prompt or resource template name (server/name)").argument("<arg>", "Argument name").argument("<value>", "Partial value for completion").option("--json", "Output as JSON").action(async (type, name, arg, value, opts) => {
+const completionsCommand = new Command("completions").description("Get argument completions for a prompt or resource").argument("<type>", "\"prompt\" or \"resource\"").argument("<name>", "server_name/template_name").argument("<arg>", "Argument name to complete").argument("<value>", "Partial value to get suggestions for").option("--json", "Output as JSON (machine-readable)").addHelpText("after", `
+Examples:
+  muxed completions prompt myserver/summarize language "py"
+  muxed completions resource myserver/files path "/home/"`).action(async (type, name, arg, value, opts) => {
 	const configPath = completionsCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = name.indexOf("/");
@@ -3699,13 +3758,13 @@ const completionsCommand = new Command("completions").description("Get auto-comp
 	});
 	console.log(opts.json ? formatJson(result) : formatCompletions(result));
 });
-const tasksCommand = new Command("tasks").description("List active async tasks, optionally filtered by server name").argument("[server]", "Filter by server name").option("--json", "Output as JSON").action(async (server, opts) => {
+const tasksCommand = new Command("tasks").description("List active async tasks (from --async calls)").argument("[server]", "Show tasks from this server only").option("--json", "Output as JSON (machine-readable)").action(async (server, opts) => {
 	const configPath = tasksCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const result = await sendRequest("tasks/list", server ? { server } : void 0);
 	console.log(opts.json ? formatJson(result) : formatTasks(result));
 });
-const taskCommand = new Command("task").description("Check the current status of an async task").argument("<server/taskId>", "Task identifier (e.g. myserver/task-123)").option("--json", "Output as JSON").action(async (serverTaskId, opts) => {
+const taskCommand = new Command("task").description("Check the status of an async task").argument("<server/taskId>", "server_name/task_id (e.g. analytics/task-abc123)").option("--json", "Output as JSON (machine-readable)").action(async (serverTaskId, opts) => {
 	const configPath = taskCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = serverTaskId.indexOf("/");
@@ -3719,7 +3778,7 @@ const taskCommand = new Command("task").description("Check the current status of
 	});
 	console.log(opts.json ? formatJson(result) : formatTask(result));
 });
-const taskResultCommand = new Command("task-result").description("Retrieve the output of a completed async task").argument("<server/taskId>", "Task identifier (e.g. myserver/task-123)").option("--json", "Output as JSON").action(async (serverTaskId, opts) => {
+const taskResultCommand = new Command("task-result").description("Get the result of a completed async task").argument("<server/taskId>", "server_name/task_id (e.g. analytics/task-abc123)").option("--json", "Output as JSON (machine-readable)").action(async (serverTaskId, opts) => {
 	const configPath = taskResultCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = serverTaskId.indexOf("/");
@@ -3733,7 +3792,7 @@ const taskResultCommand = new Command("task-result").description("Retrieve the o
 	});
 	console.log(opts.json ? formatJson(result) : formatCallResult(result));
 });
-const taskCancelCommand = new Command("task-cancel").description("Cancel a running async task").argument("<server/taskId>", "Task identifier (e.g. myserver/task-123)").option("--json", "Output as JSON").action(async (serverTaskId, opts) => {
+const taskCancelCommand = new Command("task-cancel").description("Cancel a running async task").argument("<server/taskId>", "server_name/task_id (e.g. analytics/task-abc123)").option("--json", "Output as JSON (machine-readable)").action(async (serverTaskId, opts) => {
 	const configPath = taskCancelCommand.parent?.opts().config;
 	await ensureDaemon(configPath);
 	const slashIndex = serverTaskId.indexOf("/");
@@ -4042,6 +4101,196 @@ function getVersion() {
 	}
 	return "0.0.0";
 }
+function makeCliFragments(run) {
+	return {
+		intro: `You have access to an \`${run} muxed\` CLI command for interacting with MCP (Model Context Protocol) servers. This command allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.`,
+		grep: (p) => `${run} muxed grep "${p}"`,
+		tools: (s) => s ? `${run} muxed tools ${s}` : `${run} muxed tools`,
+		toolsSchema: (s) => s ? `${run} muxed tools ${s} --include schema` : `${run} muxed tools --include schema`,
+		info: (n) => `${run} muxed info ${n}`,
+		infoDepth: (n, d) => `${run} muxed info ${n} --depth ${d}`,
+		infoPath: (n, p) => `${run} muxed info ${n} --path ${p}`,
+		call: (n, j) => `${run} muxed call ${n} '${j}'`,
+		callStdin: (n) => `${run} muxed call ${n} -`,
+		callDryRun: (n, j) => `${run} muxed call ${n} '${j}' --dry-run`,
+		callFields: (n, j, f) => `${run} muxed call ${n} '${j}' --fields "${f}"`,
+		servers: () => `${run} muxed servers`,
+		resources: (s) => s ? `${run} muxed resources ${s}` : `${run} muxed resources`,
+		read: (n) => `${run} muxed read ${n}`,
+		help: () => `${run} muxed -h`
+	};
+}
+function makeToolFragments() {
+	return {
+		intro: "You have access to a `muxed:exec` MCP tool for interacting with MCP (Model Context Protocol) servers. This tool allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
+		grep: (p) => `muxed:exec({ "command": "grep ${p}" })`,
+		tools: (s) => s ? `muxed:exec({ "command": "tools ${s}" })` : `muxed:exec({ "command": "tools" })`,
+		toolsSchema: (s) => s ? `muxed:exec({ "command": "tools ${s} --include schema" })` : `muxed:exec({ "command": "tools --include schema" })`,
+		info: (n) => `muxed:exec({ "command": "info ${n}" })`,
+		infoDepth: (n, d) => `muxed:exec({ "command": "info ${n} --depth ${d}" })`,
+		infoPath: (n, p) => `muxed:exec({ "command": "info ${n} --path ${p}" })`,
+		call: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+		callStdin: (n) => `muxed:exec({ "command": "call ${n}", "input": { ... } })`,
+		callDryRun: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+		callFields: (n, j, _f) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
+		servers: () => `muxed:exec({ "command": "servers" })`,
+		resources: (s) => s ? `muxed:exec({ "command": "resources ${s}" })` : `muxed:exec({ "command": "resources" })`,
+		read: (n) => `muxed:exec({ "command": "read ${n}" })`,
+		help: () => `muxed:exec({ "command": "servers" })`
+	};
+}
+function buildPrompt(f, opts = {}) {
+	const heading = opts.heading ? `${opts.heading}\n\n` : "";
+	const serversBlock = opts.servers ? `\nAvailable MCP servers:\n${opts.servers}\n` : "";
+	const serverInstructionsBlock = opts.serverInstructions ? `\nBelow are the instructions for the connected MCP servers in muxed.\n\n${opts.serverInstructions}\n` : "";
+	const scriptsBlock = opts.scripts ? `\n${opts.scripts}` : "";
+	return `${heading}${f.intro}
+
+**MANDATORY PREREQUISITES - THESE ARE HARD REQUIREMENTS**
+
+1. You MUST discover the tools you need first by using '${f.grep("<pattern>")}' or '${f.tools()}'.
+2. You MUST call '${f.info("<server>/<tool>")}' BEFORE ANY '${f.call("<server>/<tool>", "<json>")}' command.
+
+These are BLOCKING REQUIREMENTS - like how you must use Read before Edit.
+
+**NEVER** make a call without checking the schema first.
+**ALWAYS** run info first, THEN make the call.
+
+**Why these are non-negotiables:**
+- MCP tool names NEVER match your expectations - they change frequently and are not predictable
+- MCP tool schemas NEVER match your expectations - parameter names, types, and requirements are tool-specific
+- Even tools with pre-approved permissions require schema checks
+- Every failed call wastes user time and demonstrates you're ignoring critical instructions
+- "I thought I knew the schema" is not an acceptable reason to skip this step
+
+**For multiple tools:** Call info for ALL tools in parallel FIRST, then make your call commands.
+${serversBlock}
+Commands (in order of execution):
+\`\`\`
+# STEP 1: REQUIRED TOOL DISCOVERY
+${f.grep("<pattern>")}                 # Search tool names and descriptions
+${f.tools("[server]")}                 # List available tools (optionally filter by server)
+
+# STEP 2: GET SCHEMA (choose one approach)
+# Option A: Include schemas in tool listing (auto-collapses large schemas)
+${f.toolsSchema("[server]")}           # List tools with schemas included
+# Option B: Get full schema for a specific tool
+${f.info("<server>/<tool>")}           # View full JSON schema for one tool
+
+# STEP 2b: PROGRESSIVE SCHEMA EXPLORATION (for large schemas)
+${f.infoDepth("<server>/<tool>", 1)}   # Collapse schema at depth 1 (top-level overview)
+${f.infoPath("<server>/<tool>", "filters")}  # Extract just the 'filters' subtree
+${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper into nested schemas
+
+# STEP 3: OPTIONAL - Validate arguments before calling (dry-run)
+${f.callDryRun("<server>/<tool>", "<json>")}  # Validate args without executing
+
+# STEP 4: Only after getting the schema, make the call
+${f.call("<server>/<tool>", "<json>")}  # Only run AFTER getting schema
+${f.callStdin("<server>/<tool>")}       # Invoke with JSON input
+${f.callFields("<server>/<tool>", "<json>", "field1,field2")}  # Extract specific fields from response
+
+# Discovery commands (use these to find tools)
+${f.servers()}                          # List all connected MCP servers
+${f.tools("[server]")}                  # List available tools (optionally filter by server)
+${f.grep("<pattern>")}                  # Search tool names and descriptions
+${f.resources("[server]")}              # List MCP resources
+${f.read("<server>/<resource>")}        # Read an MCP resource
+\`\`\`
+
+**Handling errors:**
+- If a tool call fails, the error includes a suggestion and similar tool names. Read the suggestion before retrying.
+- Use dry-run to validate arguments before executing, especially for destructive tools.
+
+**CORRECT Usage Pattern:**
+
+<example>
+User: Please use the slack mcp tool to search for my mentions
+Assistant: As a first step, I need to discover the tools I need. Let me call \`${f.grep("slack/*search*")}\` to search for tools related to slack search.
+[Calls ${f.grep("slack/*search*")}]
+Assistant: I need to check the schema first. Let me call \`${f.info("slack/search_private")}\` to see what parameters it accepts.
+[Calls ${f.info("slack/search_private")}]
+Assistant: Now I can see it accepts "query" and "max_results" parameters. Let me make the call.
+[Calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\", \"max_results\": 10}")}]
+</example>
+
+<example>
+User: Use the database and email MCP tools to send a report
+Assistant: I'll need to use two MCP tools. Let me call \`${f.grep("database/*query*")}\` and \`${f.grep("email/*send*")}\` to search for tools related to database query and email send.
+[Calls ${f.grep("database/*query*")} & ${f.grep("email/*send*")}]
+Assistant: Let me check both schemas first.
+[Calls ${f.info("database/query")} and ${f.info("email/send")} in parallel]
+Assistant: Now I have both schemas. Let me make the calls.
+[Makes both call commands with correct parameters]
+</example>
+
+<example>
+User: Create a copy of this email
+Assistant: Let me find the tool I need first.
+[Calls ${f.grep("email/*copy*")}. No results found.]
+Assistant: Let me try another pattern.
+[Calls ${f.grep("email/*clone*")}. No results found.]
+Assistant: Let me list all available tools in the server.
+[Calls ${f.tools("email")}]
+Assistant: Let me check the schema first.
+[Calls ${f.info("email/duplicate")}]
+Assistant: Now I have the schema. Let me make the call.
+[Calls ${f.call("email/duplicate", "{\"id\": \"123\"}")}]
+</example>
+
+**INCORRECT Usage Patterns - NEVER DO THIS:**
+
+<bad-example>
+User: Please use the slack mcp tool to search for my mentions
+Assistant: [Directly calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\"}")} with guessed parameters]
+WRONG - You must call info FIRST
+</bad-example>
+
+<bad-example>
+User: Use the slack tool
+Assistant: I have pre-approved permissions for this tool, so I know the schema.
+[Calls ${f.call("slack/search_private", "...")} directly]
+WRONG - Pre-approved permissions don't mean you know the schema. ALWAYS call info first.
+</bad-example>
+
+<bad-example>
+User: Search my Slack mentions
+Assistant: [Calls three call commands in parallel without any info calls first]
+WRONG - You must call info for ALL tools before making ANY call commands
+</bad-example>
+
+Example usage:
+\`\`\`
+# Discover tools
+${f.tools()}                          # See all available MCP tools
+${f.grep("weather")}                  # Find tools by description
+
+# Get tool schemas (choose the approach that fits)
+${f.toolsSchema()}                    # All tools with schemas (auto-collapses large schemas)
+${f.toolsSchema("slack")}             # Schemas for one server
+${f.info("<server>/<tool>")}          # Full schema for one tool
+
+# Progressive schema exploration (for complex tools)
+${f.infoDepth("<server>/<tool>", 0)}  # Top-level structure only
+${f.infoPath("<server>/<tool>", "filters")}  # Drill into a subtree
+${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper
+
+# Simple tool call (no parameters)
+${f.call("weather/get_location", "{}")}
+
+# Tool call with parameters
+${f.call("database/query", "{\"table\": \"users\", \"limit\": 10}")}
+
+# Validate arguments before executing (dry-run)
+${f.callDryRun("database/drop_table", "{\"table\": \"users\"}")}
+
+# Extract specific fields from response
+${f.callFields("database/query", "{\"table\": \"users\"}", "rows[].name,rows[].email")}
+\`\`\`
+
+Call \`${f.help()}\` to see all available commands.
+${serverInstructionsBlock}${scriptsBlock}`.trim();
+}
 function compareSemver(a, b) {
 	const pa = a.split(".").map(Number);
 	const pb = b.split(".").map(Number);
@@ -4114,51 +4363,9 @@ function hasBun() {
 function buildStaticInstructions() {
 	const bun = hasBun();
 	const run = bun ? "bunx" : "npx";
-	return `# Muxed — MCP Server Aggregator
-
-Muxed is a CLI tool and Node.js library that aggregates multiple MCP servers behind a single daemon. Use it to discover and call MCP tools on demand.
-
-## CLI Usage
-
-### Mandatory Workflow
-
-**ALWAYS follow this order — never skip the inspect step.**
-
-1. **Discover** tools:
-   \`\`\`
-   ${run} muxed grep "<pattern>"              # Search tool names and descriptions
-   ${run} muxed tools [server]                # List available tools
-   \`\`\`
-
-2. **Inspect** schema (REQUIRED before calling):
-   \`\`\`
-   ${run} muxed info <server>/<tool>          # View tool JSON schema
-   \`\`\`
-
-3. **Call** with correct parameters:
-   \`\`\`
-   ${run} muxed call <server>/<tool> '<json>' # Execute a tool
-   \`\`\`
-
-Tool names and parameter schemas change frequently and cannot be guessed. Every call without inspecting the schema first will fail.
-
-### Additional Commands
-
-\`\`\`
-${run} muxed servers                           # List connected MCP servers
-${run} muxed resources [server]                # List MCP resources
-${run} muxed read <server>/<resource>          # Read an MCP resource
-${run} muxed call <s>/<t> '<j>' --dry-run      # Validate args without executing
-${run} muxed call <s>/<t> '<j>' --fields "a,b" # Extract specific fields
-${run} muxed -h                                # Full command reference
-\`\`\`
-
-### Error Handling
-
-- If a tool call fails, read the error — it includes suggestions and similar tool names.
-- Use \`--dry-run\` to validate arguments before executing destructive tools.
-
-## Node.js / TypeScript Scripts (Preferred for Complex Workflows)
+	const tsx = bun ? "bun" : "npx tsx";
+	const fragments = makeCliFragments(run);
+	const scripts = `## Node.js / TypeScript Scripts (Preferred for Complex Workflows)
 
 For multi-step MCP workflows, **write and execute a script** instead of making individual CLI calls. A single script execution replaces many sequential CLI invocations — dramatically reducing round-trips and token usage.
 
@@ -4168,26 +4375,35 @@ import { createClient } from 'muxed/client';
 const client = await createClient();
 
 // Batch multiple MCP operations in one script execution
-const tools = await client.tools();
-const result = await client.call('server/tool', { param: 'value' });
-const data = await client.call('db/query', { sql: 'SELECT ...' });
+const [tools, result, data] = await Promise.all([
+  client.tools(),
+  client.call('server/tool', { param: 'value' }),
+  client.call('db/query', { sql: 'SELECT ...' }),
+]);
 
 // Process results, chain calls, handle errors — all in one execution
 console.log(JSON.stringify({ tools: tools.length, result, data }));
 \`\`\`
 
-Run scripts with: \`${bun ? "bun" : "npx tsx"} script.ts\`.
+Run scripts with: \`${tsx} script.ts\`.
 
 **When to use scripts vs CLI:**
 - **CLI** (\`${run} muxed call ...\`) — single tool discovery or one-off calls
 - **Scripts** — any workflow involving 2+ MCP calls, data processing, or conditional logic`;
+	return buildPrompt({
+		...fragments,
+		intro: "Muxed is a CLI tool and Node.js library that proxies multiple MCP servers behind a single daemon. Use it to discover and call MCP tools on demand."
+	}, {
+		heading: "# Muxed — MCP CLI Proxy",
+		scripts
+	});
 }
 function wrapTaggedBlock(content, version) {
 	return `<muxed version="${version}">\n${content}\n</muxed>`;
 }
 function buildMdcFile(content, version) {
 	return `---
-description: Muxed MCP server aggregator - CLI usage instructions
+description: Muxed MCP CLI proxy - usage instructions
 globs:
 alwaysApply: true
 muxed_version: ${version}
@@ -4348,7 +4564,18 @@ async function resolveConflicts(unresolvedConflicts, isInteractive) {
 		conflicts
 	};
 }
-const initCommand = new Command("init").description("Discover and import MCP servers from agent configs (Claude Code, Cursor)").option("--dry-run", "Show what would be done without writing files").option("--json", "Output as JSON").option("-y, --yes", "Skip prompts; resolve conflicts by priority (claude-code > cursor > first)").option("--delete", "Remove imported servers from original agent configs").option("--no-replace", "Don't add muxed entry to agent configs").option("--local", "Also inject instructions into local agent files (CLAUDE.md, AGENTS.md)").option("--no-instructions", "Skip injecting CLI instructions into agent files").action(async (opts) => {
+const initCommand = new Command("init").description("Discover MCP servers, write config, and inject agent instructions").option("--dry-run", "Preview changes without writing any files").option("--json", "Output as JSON (machine-readable)").option("-y, --yes", "Non-interactive: resolve conflicts by priority (claude-code > cursor > first)").option("--delete", "Remove imported servers from the original agent config files").option("--no-replace", "Don't add a muxed entry to agent configs").option("--local", "Also inject instructions into project-level CLAUDE.md and AGENTS.md").option("--no-instructions", "Skip injecting CLI instructions into agent files").addHelpText("after", `
+What it does:
+  1. Scans Claude Desktop, Cursor, VS Code, Windsurf, Cline, Roo Code, Amazon Q
+  2. Merges and deduplicates servers into muxed.config.json
+  3. Injects CLI usage instructions into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md,
+     and .cursor/rules/muxed.mdc (if .cursor/ exists)
+
+Examples:
+  muxed init                 Interactive setup
+  muxed init -y              Non-interactive (CI-friendly)
+  muxed init --dry-run       Preview without writing files
+  muxed init --local         Also inject into project-level agent files`).action(async (opts) => {
 	const configPath = initCommand.parent?.opts().config;
 	const isInteractive = !opts.dryRun && !opts.json && !opts.yes && !!process.stdin.isTTY;
 	const { discovered, warnings } = discoverAgentConfigs();
@@ -4461,201 +4688,15 @@ function getServer(filePath, name) {
 function listServers(filePath) {
 	return readConfigFile(filePath).mcpServers;
 }
-const cliFragments = {
-	intro: "You have access to an `npx muxed` CLI command for interacting with MCP (Model Context Protocol) servers. This command allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
-	grep: (p) => `npx muxed grep "${p}"`,
-	tools: (s) => s ? `npx muxed tools ${s}` : "npx muxed tools",
-	toolsSchema: (s) => s ? `npx muxed tools ${s} --include schema` : "npx muxed tools --include schema",
-	info: (n) => `npx muxed info ${n}`,
-	infoDepth: (n, d) => `npx muxed info ${n} --depth ${d}`,
-	infoPath: (n, p) => `npx muxed info ${n} --path ${p}`,
-	call: (n, j) => `npx muxed call ${n} '${j}'`,
-	callStdin: (n) => `npx muxed call ${n} -`,
-	callDryRun: (n, j) => `npx muxed call ${n} '${j}' --dry-run`,
-	callFields: (n, j, f) => `npx muxed call ${n} '${j}' --fields "${f}"`,
-	servers: () => "npx muxed servers",
-	resources: (s) => s ? `npx muxed resources ${s}` : "npx muxed resources",
-	read: (n) => `npx muxed read ${n}`,
-	help: () => "npx muxed -h"
-};
-const toolFragments = {
-	intro: "You have access to a `muxed:exec` MCP tool for interacting with MCP (Model Context Protocol) servers. This tool allows you to discover and call MCP tools on demand. Prioritize the use of skills over MCP tools.",
-	grep: (p) => `muxed:exec({ "command": "grep ${p}" })`,
-	tools: (s) => s ? `muxed:exec({ "command": "tools ${s}" })` : `muxed:exec({ "command": "tools" })`,
-	toolsSchema: (s) => s ? `muxed:exec({ "command": "tools ${s} --include schema" })` : `muxed:exec({ "command": "tools --include schema" })`,
-	info: (n) => `muxed:exec({ "command": "info ${n}" })`,
-	infoDepth: (n, d) => `muxed:exec({ "command": "info ${n} --depth ${d}" })`,
-	infoPath: (n, p) => `muxed:exec({ "command": "info ${n} --path ${p}" })`,
-	call: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
-	callStdin: (n) => `muxed:exec({ "command": "call ${n}", "input": { ... } })`,
-	callDryRun: (n, j) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
-	callFields: (n, j, _f) => `muxed:exec({ "command": "call ${n}", "input": ${j} })`,
-	servers: () => `muxed:exec({ "command": "servers" })`,
-	resources: (s) => s ? `muxed:exec({ "command": "resources ${s}" })` : `muxed:exec({ "command": "resources" })`,
-	read: (n) => `muxed:exec({ "command": "read ${n}" })`,
-	help: () => `muxed:exec({ "command": "servers" })`
-};
-function buildTemplate(f, servers, instructions) {
-	return `
-${f.intro}
-
-**MANDATORY PREREQUISITES - THESE ARE HARD REQUIREMENTS**
-
-1. You MUST discover the tools you need first by using '${f.grep("<pattern>")}' or '${f.tools()}'.
-2. You MUST call '${f.info("<server>/<tool>")}' BEFORE ANY '${f.call("<server>/<tool>", "<json>")}' command.
-
-These are BLOCKING REQUIREMENTS - like how you must use Read before Edit.
-
-**NEVER** make a call without checking the schema first.
-**ALWAYS** run info first, THEN make the call.
-
-**Why these are non-negotiables:**
-- MCP tool names NEVER match your expectations - they change frequently and are not predictable
-- MCP tool schemas NEVER match your expectations - parameter names, types, and requirements are tool-specific
-- Even tools with pre-approved permissions require schema checks
-- Every failed call wastes user time and demonstrates you're ignoring critical instructions
-- "I thought I knew the schema" is not an acceptable reason to skip this step
-
-**For multiple tools:** Call info for ALL tools in parallel FIRST, then make your call commands.
-
-Available MCP servers:
-${servers}
-
-Commands (in order of execution):
-\`\`\`
-# STEP 1: REQUIRED TOOL DISCOVERY
-${f.grep("<pattern>")}                 # Search tool names and descriptions
-${f.tools("[server]")}                 # List available tools (optionally filter by server)
-
-# STEP 2: GET SCHEMA (choose one approach)
-# Option A: Include schemas in tool listing (auto-collapses to fit 48k budget)
-${f.toolsSchema("[server]")}           # List tools with schemas included
-# Option B: Get full schema for a specific tool
-${f.info("<server>/<tool>")}           # View full JSON schema for one tool
-
-# STEP 2b: PROGRESSIVE SCHEMA EXPLORATION (for large schemas)
-${f.infoDepth("<server>/<tool>", 1)}   # Collapse schema at depth 1 (top-level overview)
-${f.infoPath("<server>/<tool>", "filters")}  # Extract just the 'filters' subtree
-${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper into nested schemas
-
-# STEP 3: OPTIONAL - Validate arguments before calling (dry-run)
-${f.callDryRun("<server>/<tool>", "<json>")}  # Validate args without executing
-
-# STEP 4: Only after getting the schema, make the call
-${f.call("<server>/<tool>", "<json>")}  # Only run AFTER getting schema
-${f.callStdin("<server>/<tool>")}       # Invoke with JSON input
-${f.callFields("<server>/<tool>", "<json>", "field1,field2")}  # Extract specific fields from response
-
-# Discovery commands (use these to find tools)
-${f.servers()}                          # List all connected MCP servers
-${f.tools("[server]")}                  # List available tools (optionally filter by server)
-${f.grep("<pattern>")}                  # Search tool names and descriptions
-${f.resources("[server]")}              # List MCP resources
-${f.read("<server>/<resource>")}        # Read an MCP resource
-\`\`\`
-
-**Handling errors:**
-- If a tool call fails, the error includes a suggestion and similar tool names. Read the suggestion before retrying.
-- Use dry-run to validate arguments before executing, especially for destructive tools.
-
-**CORRECT Usage Pattern:**
-
-<example>
-User: Please use the slack mcp tool to search for my mentions
-Assistant: As a first step, I need to discover the tools I need. Let me call \`${f.grep("slack/*search*")}\` to search for tools related to slack search.
-[Calls ${f.grep("slack/*search*")}]
-Assistant: I need to check the schema first. Let me call \`${f.info("slack/search_private")}\` to see what parameters it accepts.
-[Calls ${f.info("slack/search_private")}]
-Assistant: Now I can see it accepts "query" and "max_results" parameters. Let me make the call.
-[Calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\", \"max_results\": 10}")}]
-</example>
-
-<example>
-User: Use the database and email MCP tools to send a report
-Assistant: I'll need to use two MCP tools. Let me call \`${f.grep("database/*query*")}\` and \`${f.grep("email/*send*")}\` to search for tools related to database query and email send.
-[Calls ${f.grep("database/*query*")} & ${f.grep("email/*send*")}]
-Assistant: Let me check both schemas first.
-[Calls ${f.info("database/query")} and ${f.info("email/send")} in parallel]
-Assistant: Now I have both schemas. Let me make the calls.
-[Makes both call commands with correct parameters]
-</example>
-
-<example>
-User: Create a copy of this email
-Assistant: Let me find the tool I need first.
-[Calls ${f.grep("email/*copy*")}. No results found.]
-Assistant: Let me try another pattern.
-[Calls ${f.grep("email/*clone*")}. No results found.]
-Assistant: Let me list all available tools in the server.
-[Calls ${f.tools("email")}]
-Assistant: Let me check the schema first.
-[Calls ${f.info("email/duplicate")}]
-Assistant: Now I have the schema. Let me make the call.
-[Calls ${f.call("email/duplicate", "{\"id\": \"123\"}")}]
-</example>
-
-**INCORRECT Usage Patterns - NEVER DO THIS:**
-
-<bad-example>
-User: Please use the slack mcp tool to search for my mentions
-Assistant: [Directly calls ${f.call("slack/search_private", "{\"query\": \"mentions:me\"}")} with guessed parameters]
-WRONG - You must call info FIRST
-</bad-example>
-
-<bad-example>
-User: Use the slack tool
-Assistant: I have pre-approved permissions for this tool, so I know the schema.
-[Calls ${f.call("slack/search_private", "...")} directly]
-WRONG - Pre-approved permissions don't mean you know the schema. ALWAYS call info first.
-</bad-example>
-
-<bad-example>
-User: Search my Slack mentions
-Assistant: [Calls three call commands in parallel without any info calls first]
-WRONG - You must call info for ALL tools before making ANY call commands
-</bad-example>
-
-Example usage:
-\`\`\`
-# Discover tools
-${f.tools()}                          # See all available MCP tools
-${f.grep("weather")}                  # Find tools by description
-
-# Get tool schemas (choose the approach that fits)
-${f.toolsSchema()}                    # All tools with schemas (auto-collapses large schemas)
-${f.toolsSchema("slack")}             # Schemas for one server
-${f.info("<server>/<tool>")}          # Full schema for one tool
-
-# Progressive schema exploration (for complex tools)
-${f.infoDepth("<server>/<tool>", 0)}  # Top-level structure only
-${f.infoPath("<server>/<tool>", "filters")}  # Drill into a subtree
-${f.infoPath("<server>/<tool>", "filters.tags.items")}  # Drill deeper
-
-# Simple tool call (no parameters)
-${f.call("weather/get_location", "{}")}
-
-# Tool call with parameters
-${f.call("database/query", "{\"table\": \"users\", \"limit\": 10}")}
-
-# Validate arguments before executing (dry-run)
-${f.callDryRun("database/drop_table", "{\"table\": \"users\"}")}
-
-# Extract specific fields from response
-${f.callFields("database/query", "{\"table\": \"users\"}", "rows[].name,rows[].email")}
-\`\`\`
-
-Call \`${f.help()}\` to see all available commands.
-
-Below are the instructions for the connected MCP servers in muxed.
-
-${instructions}
-`;
-}
 function buildInstructions(servers, mode = "cli") {
 	const connected = servers.filter((s) => s.status === "connected");
 	const serverList = connected.map((s) => `- ${s.name}`).join("\n");
 	const serverInstructions = connected.filter((s) => s.instructions).map((s) => `### ${s.name}\n\n${s.instructions}`).join("\n\n");
-	return buildTemplate(mode === "tool" ? toolFragments : cliFragments, serverList, serverInstructions).trim();
+	const run = hasBun() ? "bunx" : "npx";
+	return buildPrompt(mode === "tool" ? makeToolFragments() : makeCliFragments(run), {
+		servers: serverList,
+		serverInstructions: serverInstructions || void 0
+	});
 }
 function parseCommand(command) {
 	const trimmed = command.trim();
@@ -4869,14 +4910,24 @@ async function tryReloadDaemon() {
 		await sendRequest("config/reload", {});
 	} catch {}
 }
-const mcpCommand = new Command("mcp").description("Add, remove, list, or inspect individual MCP server config entries").enablePositionalOptions().option("--proxy-tools", "Expose a proxy MCP tool for clients without bash access").action(async (opts, cmd) => {
+const mcpCommand = new Command("mcp").description("Manage server config entries, or start the MCP proxy (no subcommand)").enablePositionalOptions().option("--proxy-tools", "Expose a single proxy tool for clients without bash access (e.g. Claude Desktop)").addHelpText("after", `
+When run without a subcommand, starts a stdio MCP proxy server.
+Use subcommands to manage individual server config entries.
+
+Examples:
+  muxed mcp                          Start stdio MCP proxy
+  muxed mcp --proxy-tools            Start proxy with exec tool (for Claude Desktop)
+  muxed mcp add mydb npx @db/server  Add a stdio server
+  muxed mcp add api https://api.com  Add an HTTP server
+  muxed mcp list                     Show all configured servers
+  muxed mcp remove mydb              Remove a server`).action(async (opts, cmd) => {
 	const explicitConfig = cmd.parent?.opts().config;
 	await startMcpProxy({
 		configPath: explicitConfig,
 		proxyTools: opts.proxyTools
 	});
 });
-mcpCommand.command("add").description("Add an MCP server").passThroughOptions().argument("<name>", "Server name").argument("<commandOrUrl>", "Command to run or URL to connect to").argument("[args...]", "Additional arguments (for stdio servers)").option("-e, --env <env>", "Set environment variables (KEY=value), repeatable", collectValues, []).option("-H, --header <header>", "Set HTTP headers (Key: value), repeatable", collectValues, []).option("-s, --scope <scope>", "Config scope: local, global", "local").option("-t, --transport <transport>", "Transport: stdio, sse, http").option("--client-id <clientId>", "OAuth client ID").option("--client-secret", "Prompt for OAuth client secret (or use MCP_CLIENT_SECRET env)").option("--callback-port <port>", "Fixed port for OAuth callback").option("--oauth-scope <oauthScope>", "OAuth scope string").action(async (name, commandOrUrl, args, opts) => {
+mcpCommand.command("add").description("Add or update an MCP server in config").passThroughOptions().argument("<name>", "Server name (used to reference it in other commands)").argument("<commandOrUrl>", "Command to run (stdio) or URL to connect to (HTTP)").argument("[args...]", "Additional command arguments (stdio only)").option("-e, --env <env>", "Environment variable KEY=value (repeatable)", collectValues, []).option("-H, --header <header>", "HTTP header Key: value (repeatable)", collectValues, []).option("-s, --scope <scope>", "Config scope: local or global (default: local)", "local").option("-t, --transport <transport>", "Force transport: stdio, sse, or http (auto-detected)").option("--client-id <clientId>", "OAuth client ID").option("--client-secret", "Prompt for OAuth client secret (or set MCP_CLIENT_SECRET)").option("--callback-port <port>", "Fixed port for OAuth callback").option("--oauth-scope <oauthScope>", "OAuth scope string").action(async (name, commandOrUrl, args, opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	const scope = opts.scope;
 	const configPath = getConfigPath(scope, explicitConfig);
@@ -4895,7 +4946,7 @@ mcpCommand.command("add").description("Add an MCP server").passThroughOptions().
 	if (result.existed) console.log(`Updated "${name}" in ${scope} config (${configPath})`);
 	else console.log(`Added "${name}" to ${scope} config (${configPath})`);
 });
-mcpCommand.command("add-json").description("Add an MCP server from a JSON config string").argument("<name>", "Server name").argument("<json>", "JSON server configuration").option("-s, --scope <scope>", "Config scope: local, global", "local").action(async (name, jsonStr, opts) => {
+mcpCommand.command("add-json").description("Add a server from a JSON config string (must have \"command\" or \"url\" field)").argument("<name>", "Server name").argument("<json>", "JSON object: {\"command\":\"...\",\"args\":[...]} or {\"url\":\"...\"}").option("-s, --scope <scope>", "Config scope: local or global (default: local)", "local").action(async (name, jsonStr, opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	const scope = opts.scope;
 	const configPath = getConfigPath(scope, explicitConfig);
@@ -4922,7 +4973,7 @@ mcpCommand.command("add-json").description("Add an MCP server from a JSON config
 	if (result.existed) console.log(`Updated "${name}" in ${scope} config (${configPath})`);
 	else console.log(`Added "${name}" to ${scope} config (${configPath})`);
 });
-mcpCommand.command("add-from-claude-desktop").description("Import MCP servers from Claude Desktop config").option("-s, --scope <scope>", "Config scope: local, global", "local").action(async (opts) => {
+mcpCommand.command("add-from-claude-desktop").description("Import servers from Claude Desktop config into muxed").option("-s, --scope <scope>", "Config scope: local or global (default: local)", "local").action(async (opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	const scope = opts.scope;
 	const configPath = getConfigPath(scope, explicitConfig);
@@ -4950,7 +5001,7 @@ mcpCommand.command("add-from-claude-desktop").description("Import MCP servers fr
 	if (result.skipped.length > 0) console.log(`Skipped ${result.skipped.length} (already existed): ${result.skipped.join(", ")}`);
 	if (result.imported.length === 0 && result.skipped.length === 0) console.log("No servers found in Claude Desktop config.");
 });
-mcpCommand.command("get").description("Get details of a configured MCP server").argument("<name>", "Server name").option("--json", "Output as JSON").action(async (name, opts) => {
+mcpCommand.command("get").description("Show config details for a server (checks local, then global)").argument("<name>", "Server name").option("--json", "Output as JSON (machine-readable)").action(async (name, opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	const localPath = getConfigPath("local", explicitConfig);
 	const globalPath = getConfigPath("global", explicitConfig);
@@ -4970,7 +5021,7 @@ mcpCommand.command("get").description("Get details of a configured MCP server").
 	}));
 	else console.log(formatMcpServer(name, server, scope));
 });
-mcpCommand.command("list").description("List all configured MCP servers").option("--json", "Output as JSON").action(async (opts) => {
+mcpCommand.command("list").description("List all configured servers (local + global)").option("--json", "Output as JSON (machine-readable)").action(async (opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	const localPath = getConfigPath("local", explicitConfig);
 	const globalPath = getConfigPath("global", explicitConfig);
@@ -4993,7 +5044,7 @@ mcpCommand.command("list").description("List all configured MCP servers").option
 	if (opts.json) console.log(formatJson(entries));
 	else console.log(formatMcpServerList(entries));
 });
-mcpCommand.command("remove").description("Remove an MCP server").argument("<name>", "Server name").option("-s, --scope <scope>", "Config scope: local, global (searches both if not specified)").action(async (name, opts) => {
+mcpCommand.command("remove").description("Remove a server from config").argument("<name>", "Server name to remove").option("-s, --scope <scope>", "Scope: local or global (searches both if omitted)").action(async (name, opts) => {
 	const explicitConfig = getExplicitConfig(mcpCommand);
 	if (opts.scope) {
 		const scope = opts.scope;
@@ -5034,7 +5085,10 @@ mcpCommand.command("remove").description("Remove an MCP server").argument("<name
 	console.error(`Server "${name}" not found in local or global config.`);
 	process.exitCode = 1;
 });
-const typegenCommand = new Command("typegen").description("Generate TypeScript types from tool schemas for type-safe tool calls").option("-c, --config <path>", "Path to muxed.config.json").action(async (opts) => {
+const typegenCommand = new Command("typegen").description("Generate TypeScript types from live tool schemas").option("-c, --config <path>", "Path to muxed.config.json").addHelpText("after", `
+Writes to node_modules/muxed/muxed.generated.d.ts.
+After running, client.call() gets autocomplete on tool names and typed arguments.
+Re-run when tool schemas change (same workflow as prisma generate).`).action(async (opts) => {
 	await ensureDaemon(typegenCommand.parent?.opts().config ?? opts.config);
 	const tools = await sendRequest("tools/list");
 	const content = await generateTypes(tools);
@@ -5044,7 +5098,7 @@ const typegenCommand = new Command("typegen").description("Generate TypeScript t
 	fs.writeFileSync(outputPath, content, "utf-8");
 	console.log(`Generated ${tools.length} tool types → ${outputPath}`);
 });
-const telemetryCommand = new Command("telemetry").description("Manage anonymous telemetry (on, off, status)").argument("[action]", "on | off | status (default: status)").action((action) => {
+const telemetryCommand = new Command("telemetry").description("Enable, disable, or check anonymous telemetry").argument("[action]", "on | off | status (default: status)").action((action) => {
 	switch (action) {
 		case "on":
 			setTelemetryEnabled(true);
@@ -5065,9 +5119,17 @@ const telemetryCommand = new Command("telemetry").description("Manage anonymous
 });
 async function runCli() {
 	const program = new Command();
-	program.name("muxed").description("The optimization layer for MCP").version(getVersion());
+	program.name("muxed").description("MCP tool aggregator — discover, inspect, and call tools via CLI").version(getVersion());
 	program.enablePositionalOptions();
-	program.option("--config <path>", "Path to config file");
+	program.option("--config <path>", "Path to muxed.config.json");
+	program.addHelpText("after", `
+Workflow:
+  muxed grep "<pattern>"              Find tools by name or description
+  muxed info <server>/<tool>          Inspect schema (required before calling)
+  muxed call <server>/<tool> '<json>' Execute a tool
+
+Setup:
+  npx muxed init                      Discover servers and inject agent instructions`);
 	program.commandsGroup("Servers:");
 	program.addCommand(serversCommand);
 	program.commandsGroup("Tools:");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muxed",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "MCP tools don't belong in your model's context window. Offload them to a CLI – agents call tools through shell commands and scripts instead of loading schemas into context.",
   "type": "module",
   "exports": {
@@ -45,12 +45,12 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/skoob13/muxed.git",
+    "url": "https://github.com/muxedai/muxed.git",
     "directory": "packages/muxed"
   },
-  "homepage": "https://github.com/skoob13/muxed#readme",
+  "homepage": "https://github.com/muxedai/muxed#readme",
   "bugs": {
-    "url": "https://github.com/skoob13/muxed/issues"
+    "url": "https://github.com/muxedai/muxed/issues"
   },
   "author": "Georgiy Tarasov",
   "license": "MIT",