muxed 0.2.1 → 0.2.3

package/dist/cli.mjs

@@ -11,12 +11,13 @@ import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontex
 import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
 import { LATEST_PROTOCOL_VERSION } from "@modelcontextprotocol/sdk/types.js";
 import crypto from "node:crypto";
-import { execFile, fork } from "node:child_process";
+import { execFile, execSync, fork } from "node:child_process";
 import http from "node:http";
 import { compile } from "json-schema-to-typescript";
 import net from "node:net";
 import { Command } from "commander";
 import { PostHog } from "posthog-node";
+import { fileURLToPath } from "node:url";
 import * as readline from "node:readline/promises";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -77,6 +78,7 @@ const DaemonConfigSchema = z.object({
 	connectTimeout: z.number().optional(),
 	requestTimeout: z.number().optional(),
 	healthCheckInterval: z.number().optional(),
+	healthCheckTimeout: z.number().optional(),
 	maxRestartAttempts: z.number().optional(),
 	maxTotalTimeout: z.number().optional(),
 	taskExpiryTimeout: z.number().optional(),
@@ -120,6 +122,7 @@ const DAEMON_DEFAULTS = {
 	connectTimeout: 3e4,
 	requestTimeout: 3e4,
 	healthCheckInterval: 3e4,
+	healthCheckTimeout: 1e4,
 	maxRestartAttempts: -1,
 	maxTotalTimeout: 3e5,
 	taskExpiryTimeout: 36e5,
@@ -698,6 +701,7 @@ var ServerManager = class {
 	stopped = false;
 	connectTimeout;
 	healthCheckInterval;
+	healthCheckTimeout;
 	maxRestartAttempts;
 	onHealthChange;
 	constructor(name, config, options) {
@@ -705,6 +709,7 @@ var ServerManager = class {
 		this.config = config;
 		this.connectTimeout = options?.connectTimeout;
 		this.healthCheckInterval = options?.healthCheckInterval ?? 3e4;
+		this.healthCheckTimeout = options?.healthCheckTimeout ?? 1e4;
 		this.maxRestartAttempts = options?.maxRestartAttempts ?? -1;
 	}
 	setHealthCallback(cb) {
@@ -911,7 +916,7 @@ var ServerManager = class {
 		if (!this.client || this.status !== "connected") return;
 		this.lastHealthCheck = /* @__PURE__ */ new Date();
 		try {
-			await this.client.ping();
+			await this.client.ping({ timeout: this.healthCheckTimeout });
 			if (this.consecutiveFailures > 0) getLogger().info(`Health check recovered after ${this.consecutiveFailures} failures`, this.name);
 			this.consecutiveFailures = 0;
 		} catch (err) {
@@ -966,10 +971,14 @@ var ServerManager = class {
 		if (!this.client) return;
 		this.tools = (await this.client.listTools()).tools;
 	}
+	ensureConnected() {
+		if (!this.client || this.status !== "connected") throw new Error(`Server "${this.name}" is not connected`);
+		return this.client;
+	}
 	async callTool(name, args, timeout) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		const options = timeout ? { signal: AbortSignal.timeout(timeout) } : void 0;
-		return await this.client.callTool({
+		return await client.callTool({
 			name,
 			arguments: args
 		}, void 0, options);
@@ -982,8 +991,7 @@ var ServerManager = class {
 		this.resources = (await this.client.listResources()).resources;
 	}
 	async readResource(uri) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.readResource({ uri });
+		return await this.ensureConnected().readResource({ uri });
 	}
 	listPrompts() {
 		return this.prompts;
@@ -993,40 +1001,35 @@ var ServerManager = class {
 		this.prompts = (await this.client.listPrompts()).prompts;
 	}
 	async getPrompt(name, args) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.getPrompt({
+		return await this.ensureConnected().getPrompt({
 			name,
 			arguments: args
 		});
 	}
 	async complete(ref, argument) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		if (!this.capabilities?.completions) throw new Error(`Server "${this.name}" does not support completions`);
-		return await this.client.complete({
+		return await client.complete({
 			ref,
 			argument
 		});
 	}
 	async listTasks(cursor) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
+		const client = this.ensureConnected();
 		if (!this.capabilities?.experimental?.tasks) throw new Error(`Server "${this.name}" does not support tasks`);
-		return await this.client.experimental.tasks.listTasks(cursor);
+		return await client.experimental.tasks.listTasks(cursor);
 	}
 	async getTask(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.getTask(taskId);
+		return await this.ensureConnected().experimental.tasks.getTask(taskId);
 	}
 	async getTaskResult(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.getTaskResult(taskId);
+		return await this.ensureConnected().experimental.tasks.getTaskResult(taskId);
 	}
 	async cancelTask(taskId) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		return await this.client.experimental.tasks.cancelTask(taskId);
+		return await this.ensureConnected().experimental.tasks.cancelTask(taskId);
 	}
 	async callToolWithTask(name, args) {
-		if (!this.client) throw new Error(`Server "${this.name}" is not connected`);
-		const stream = this.client.experimental.tasks.callToolStream({
+		const stream = this.ensureConnected().experimental.tasks.callToolStream({
 			name,
 			arguments: args
 		});
@@ -1180,6 +1183,7 @@ var ServerPool = class {
 			const manager = new ServerManager(name, serverConfig, {
 				connectTimeout: config.daemon?.connectTimeout,
 				healthCheckInterval: config.daemon?.healthCheckInterval,
+				healthCheckTimeout: config.daemon?.healthCheckTimeout,
 				maxRestartAttempts: config.daemon?.maxRestartAttempts
 			});
 			manager.setHealthCallback((serverName, status, error) => {
@@ -1481,6 +1485,7 @@ var ServerPool = class {
 			const manager = new ServerManager(name, serverConfig, {
 				connectTimeout: newConfig.daemon?.connectTimeout,
 				healthCheckInterval: newConfig.daemon?.healthCheckInterval,
+				healthCheckTimeout: newConfig.daemon?.healthCheckTimeout,
 				maxRestartAttempts: newConfig.daemon?.maxRestartAttempts
 			});
 			manager.setHealthCallback((serverName, status, error) => {
@@ -1496,6 +1501,7 @@ var ServerPool = class {
 				const newManager = new ServerManager(name, serverConfig, {
 					connectTimeout: newConfig.daemon?.connectTimeout,
 					healthCheckInterval: newConfig.daemon?.healthCheckInterval,
+					healthCheckTimeout: newConfig.daemon?.healthCheckTimeout,
 					maxRestartAttempts: newConfig.daemon?.maxRestartAttempts
 				});
 				newManager.setHealthCallback((serverName, status, error) => {
@@ -1639,6 +1645,240 @@ function filterFields(data, fields) {
 	}
 	return data;
 }
+const DEFAULT_BUDGET = 48e3;
+function isLeaf(schema) {
+	const type = schema.type;
+	if (type === "string" || type === "number" || type === "integer" || type === "boolean" || type === "null") {
+		if (!schema.anyOf && !schema.oneOf && !schema.allOf) return true;
+	}
+	if (schema.$ref) return true;
+	if (!schema.properties && !schema.items && !schema.additionalProperties && !schema.patternProperties && !schema.anyOf && !schema.oneOf && !schema.allOf && !schema.if && !schema.not) return true;
+	return false;
+}
+function buildHint(schema) {
+	const parts = [];
+	const props = schema.properties;
+	if (props) {
+		const count = Object.keys(props).length;
+		const required = schema.required;
+		if (required && required.length > 0) parts.push(`${count} properties, ${required.length} required`);
+		else parts.push(`${count} ${count === 1 ? "property" : "properties"}`);
+		return parts.join(", ");
+	}
+	if (schema.type === "object" && schema.additionalProperties) return `map<string, ${schema.additionalProperties.type ?? "unknown"}>`;
+	if (schema.items) {
+		const items = schema.items;
+		if (items.type === "object" && items.properties) {
+			const count = Object.keys(items.properties).length;
+			return `items: object (${count} ${count === 1 ? "property" : "properties"})`;
+		}
+		return `items: ${items.type ?? "unknown"}`;
+	}
+	for (const keyword of ["anyOf", "oneOf"]) {
+		const variants = schema[keyword];
+		if (variants) return `${keyword}: ${variants.length} variants`;
+	}
+	if (schema.allOf) return `allOf: ${schema.allOf.length} schemas`;
+	if (schema.enum) return `enum: ${schema.enum.length} values`;
+	return schema.type ?? "schema";
+}
+function buildCollapsedNode(schema) {
+	const result = {};
+	if (schema.type) result.type = schema.type;
+	if (schema.description) result.description = schema.description;
+	result._collapsed = true;
+	result._hint = buildHint(schema);
+	return result;
+}
+function collapseChild(schema, childDepth, maxDepth) {
+	if (typeof schema !== "object" || schema === null) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (isLeaf(schema)) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (childDepth > maxDepth) return {
+		schema: buildCollapsedNode(schema),
+		hasCollapsed: true
+	};
+	return collapseNode(schema, childDepth, maxDepth);
+}
+function collapseNode(schema, currentDepth, maxDepth) {
+	if (typeof schema !== "object" || schema === null) return {
+		schema,
+		hasCollapsed: false
+	};
+	if (isLeaf(schema)) return {
+		schema,
+		hasCollapsed: false
+	};
+	let hasCollapsed = false;
+	const result = {};
+	for (const [key, value] of Object.entries(schema)) switch (key) {
+		case "properties": {
+			const props = value;
+			const newProps = {};
+			for (const [propName, propSchema] of Object.entries(props)) {
+				const collapsed = collapseChild(propSchema, currentDepth + 1, maxDepth);
+				newProps[propName] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result.properties = newProps;
+			break;
+		}
+		case "items": {
+			const collapsed = collapseChild(value, currentDepth + 1, maxDepth);
+			result.items = collapsed.schema;
+			if (collapsed.hasCollapsed) hasCollapsed = true;
+			break;
+		}
+		case "additionalProperties":
+			if (typeof value === "object" && value !== null) {
+				const collapsed = collapseChild(value, currentDepth + 1, maxDepth);
+				result.additionalProperties = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			} else result.additionalProperties = value;
+			break;
+		case "patternProperties": {
+			const patterns = value;
+			const newPatterns = {};
+			for (const [pattern, patternSchema] of Object.entries(patterns)) {
+				const collapsed = collapseChild(patternSchema, currentDepth + 1, maxDepth);
+				newPatterns[pattern] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result.patternProperties = newPatterns;
+			break;
+		}
+		case "anyOf":
+		case "oneOf":
+		case "allOf": {
+			const variants = value;
+			const newVariants = [];
+			for (const variant of variants) {
+				const collapsed = collapseNode(variant, currentDepth, maxDepth);
+				newVariants.push(collapsed.schema);
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result[key] = newVariants;
+			break;
+		}
+		case "if":
+		case "then":
+		case "else":
+		case "not": {
+			const collapsed = collapseNode(value, currentDepth, maxDepth);
+			result[key] = collapsed.schema;
+			if (collapsed.hasCollapsed) hasCollapsed = true;
+			break;
+		}
+		case "$defs":
+		case "definitions": {
+			const defs = value;
+			const newDefs = {};
+			for (const [defName, defSchema] of Object.entries(defs)) {
+				const collapsed = collapseChild(defSchema, currentDepth + 1, maxDepth);
+				newDefs[defName] = collapsed.schema;
+				if (collapsed.hasCollapsed) hasCollapsed = true;
+			}
+			result[key] = newDefs;
+			break;
+		}
+		default: result[key] = value;
+	}
+	return {
+		schema: result,
+		hasCollapsed
+	};
+}
+function collapseSchema(schema, maxDepth) {
+	return collapseNode(schema, 0, Math.max(0, maxDepth));
+}
+function extractSubtree(schema, path) {
+	const segments = path.split(".");
+	let current = schema;
+	for (const segment of segments) {
+		if (!current || typeof current !== "object") return void 0;
+		const props = current.properties;
+		if (props && segment in props) {
+			current = props[segment];
+			continue;
+		}
+		if (segment === "items" && current.items) {
+			current = current.items;
+			continue;
+		}
+		if (segment === "additionalProperties" && typeof current.additionalProperties === "object") {
+			current = current.additionalProperties;
+			continue;
+		}
+		const index = parseInt(segment, 10);
+		if (!isNaN(index)) {
+			for (const keyword of [
+				"anyOf",
+				"oneOf",
+				"allOf"
+			]) {
+				const variants = current[keyword];
+				if (variants && index >= 0 && index < variants.length) {
+					current = variants[index];
+					break;
+				}
+			}
+			if (current !== schema) continue;
+		}
+		const patterns = current.patternProperties;
+		if (patterns && segment in patterns) {
+			current = patterns[segment];
+			continue;
+		}
+		return;
+	}
+	return current;
+}
+function autoDepth(schemas, budgetChars = DEFAULT_BUDGET) {
+	if (schemas.length === 0) return {
+		depth: 0,
+		fullyExpanded: true
+	};
+	let depth = 1;
+	let lastFit = 0;
+	let lastFullyExpanded = false;
+	const depth0 = schemas.map((s) => collapseSchema(s, 0));
+	const depth0Size = depth0.reduce((sum, r) => sum + JSON.stringify(r.schema).length, 0);
+	const depth0Expanded = depth0.every((r) => !r.hasCollapsed);
+	if (depth0Size > budgetChars) return {
+		depth: 0,
+		fullyExpanded: depth0Expanded
+	};
+	lastFit = 0;
+	lastFullyExpanded = depth0Expanded;
+	if (depth0Expanded) return {
+		depth: 0,
+		fullyExpanded: true
+	};
+	for (depth = 1; depth <= 20; depth++) {
+		const results = schemas.map((s) => collapseSchema(s, depth));
+		const totalSize = results.reduce((sum, r) => sum + JSON.stringify(r.schema).length, 0);
+		const fullyExpanded = results.every((r) => !r.hasCollapsed);
+		if (totalSize > budgetChars) return {
+			depth: lastFit,
+			fullyExpanded: lastFullyExpanded
+		};
+		lastFit = depth;
+		lastFullyExpanded = fullyExpanded;
+		if (fullyExpanded) return {
+			depth,
+			fullyExpanded: true
+		};
+	}
+	return {
+		depth: lastFit,
+		fullyExpanded: lastFullyExpanded
+	};
+}
 function createDaemonServer(serverPool, config) {
 	const socketPath = getSocketPath();
 	let idleTimer;
@@ -1667,11 +1907,37 @@ function createDaemonServer(serverPool, config) {
 				result: serverPool.listServers()
 			};
 			case "tools/list": {
-				const server = params?.server;
+				const p = params;
+				const tools = serverPool.listAllTools(p?.server);
+				if (p?.includeSchema) {
+					const schemas = tools.map(({ tool }) => tool.inputSchema ?? {});
+					const depth = p.schemaDepth ?? autoDepth(schemas, p.schemaBudget).depth;
+					return {
+						jsonrpc: "2.0",
+						id,
+						result: tools.map(({ server, tool }) => ({
+							server,
+							tool: {
+								name: tool.name,
+								title: tool.title,
+								description: tool.description,
+								annotations: tool.annotations,
+								inputSchema: collapseSchema(tool.inputSchema ?? {}, depth).schema
+							}
+						}))
+					};
+				}
 				return {
 					jsonrpc: "2.0",
 					id,
-					result: serverPool.listAllTools(server)
+					result: tools.map(({ server, tool }) => ({
+						server,
+						tool: {
+							name: tool.name,
+							title: tool.title,
+							annotations: tool.annotations
+						}
+					}))
 				};
 			}
 			case "tools/call": {
@@ -1764,10 +2030,34 @@ function createDaemonServer(serverPool, config) {
 						data: toErrorData(found.error)
 					}
 				};
+				let tool = found.tool;
+				if (p.path) {
+					const subtree = extractSubtree(tool.inputSchema ?? {}, p.path);
+					if (!subtree) return {
+						jsonrpc: "2.0",
+						id,
+						error: {
+							code: -32602,
+							message: `Path not found in schema: ${p.path}`,
+							data: {
+								code: "SCHEMA_PATH_NOT_FOUND",
+								path: p.path
+							}
+						}
+					};
+					tool = {
+						...tool,
+						inputSchema: subtree
+					};
+				}
+				if (p.schemaDepth !== void 0) tool = {
+					...tool,
+					inputSchema: collapseSchema(tool.inputSchema ?? {}, p.schemaDepth).schema
+				};
 				return {
 					jsonrpc: "2.0",
 					id,
-					result: found.tool
+					result: tool
 				};
 			}
 			case "tools/validate": {
@@ -1845,10 +2135,36 @@ function createDaemonServer(serverPool, config) {
 					}
 				};
 				try {
+					const matches = serverPool.grepTools(p.pattern);
+					if (p.includeSchema) {
+						const schemas = matches.map(({ tool }) => tool.inputSchema ?? {});
+						const depth = p.schemaDepth ?? autoDepth(schemas, p.schemaBudget).depth;
+						return {
+							jsonrpc: "2.0",
+							id,
+							result: matches.map(({ server, tool }) => ({
+								server,
+								tool: {
+									name: tool.name,
+									title: tool.title,
+									description: tool.description,
+									annotations: tool.annotations,
+									inputSchema: collapseSchema(tool.inputSchema ?? {}, depth).schema
+								}
+							}))
+						};
+					}
 					return {
 						jsonrpc: "2.0",
 						id,
-						result: serverPool.grepTools(p.pattern)
+						result: matches.map(({ server, tool }) => ({
+							server,
+							tool: {
+								name: tool.name,
+								title: tool.title,
+								annotations: tool.annotations
+							}
+						}))
 					};
 				} catch (err) {
 					return {
@@ -2536,16 +2852,32 @@ async function ensureDaemon(configPath) {
 		400
 	]);
 }
-async function sendRequest(method, params) {
+async function sendRequest(method, params, timeout = 9e4) {
 	const socketPath = getSocketPath();
 	return new Promise((resolve, reject) => {
 		const socket = net.createConnection(socketPath);
 		let buffer = "";
+		let settled = false;
+		const timer = setTimeout(() => {
+			if (settled) return;
+			settled = true;
+			socket.destroy();
+			reject(/* @__PURE__ */ new Error(`Request timed out after ${timeout}ms`));
+		}, timeout);
 		socket.on("error", (err) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
 			if (err.code === "ENOENT") reject(/* @__PURE__ */ new Error("Daemon is not running. Run `muxed status` to check."));
 			else if (err.code === "ECONNREFUSED") reject(/* @__PURE__ */ new Error("Daemon may have crashed. Try running a command to auto-restart it."));
 			else reject(err);
 		});
+		socket.on("close", () => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			reject(/* @__PURE__ */ new Error("Daemon closed the connection before sending a response"));
+		});
 		socket.on("connect", () => {
 			const request = {
 				jsonrpc: "2.0",
@@ -2559,6 +2891,9 @@ async function sendRequest(method, params) {
 			buffer += data.toString();
 			const newlineIndex = buffer.indexOf("\n");
 			if (newlineIndex === -1) return;
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
 			const line = buffer.slice(0, newlineIndex).trim();
 			socket.destroy();
 			try {
@@ -2604,7 +2939,6 @@ function formatTools(tools) {
 	return formatTable([
 		"Tool",
 		"Title",
-		"Description",
 		"Hints"
 	], tools.map(({ server, tool }) => {
 		const hints = [];
@@ -2614,7 +2948,6 @@ function formatTools(tools) {
 		return [
 			`${server}/${tool.name}`,
 			tool.title ?? "—",
-			truncate(tool.description ?? "", 60),
 			hints.join(" ")
 		];
 	}));
@@ -2848,6 +3181,24 @@ function formatInit(result) {
 		lines.push("");
 		lines.push("All discovered servers already exist in muxed config. Nothing to do.");
 	}
+	if (result.instructionResults && result.instructionResults.length > 0) {
+		lines.push("");
+		lines.push("Instructions:");
+		for (const r of result.instructionResults) switch (r.action) {
+			case "created":
+				lines.push(`  ${r.target} \u2014 created (v${r.newVersion})`);
+				break;
+			case "updated":
+				lines.push(`  ${r.target} \u2014 updated (v${r.previousVersion} \u2192 v${r.newVersion})`);
+				break;
+			case "up-to-date":
+				lines.push(`  ${r.target} \u2014 up-to-date (v${r.previousVersion})`);
+				break;
+			case "skipped":
+				lines.push(`  ${r.target} \u2014 skipped`);
+				break;
+		}
+	}
 	return lines.join("\n");
 }
 function formatMcpServer(name, config, scope) {
@@ -2957,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");
@@ -3016,20 +3370,55 @@ 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").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 result = await sendRequest("tools/list", server ? { server } : void 0);
+	const params = {};
+	if (server) params.server = server;
+	if (opts.include === "schema") params.includeSchema = true;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/list", params);
 	capture("tools_listed", {
 		filtered_by_server: !!server,
 		tool_count: result.length
 	});
 	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").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 result = await sendRequest("tools/info", { name: serverTool });
+	const params = { name: serverTool };
+	if (opts.path) params.path = opts.path;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/info", params);
 	if (opts.json) console.log(formatJson(result));
 	else {
 		const slashIndex = serverTool.indexOf("/");
@@ -3048,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 = {};
@@ -3187,20 +3582,38 @@ 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").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 result = await sendRequest("tools/grep", { pattern });
+	const params = { pattern };
+	if (opts.include === "schema") params.includeSchema = true;
+	if (opts.depth !== void 0) params.schemaDepth = opts.depth;
+	const result = await sendRequest("tools/grep", params);
 	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("/");
@@ -3217,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" }));
@@ -3269,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;
@@ -3283,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("/");
@@ -3313,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("/");
@@ -3338,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("/");
@@ -3358,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("/");
@@ -3372,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("/");
@@ -3665,6 +4085,418 @@ function getMuxedConfigPath(scope, explicitPath) {
 	if (scope === "local") return path.join(process.cwd(), "muxed.config.json");
 	return path.join(home, ".muxed", "config.json");
 }
+let cached = null;
+function getVersion() {
+	if (cached) return cached;
+	const dir = path.dirname(fileURLToPath(import.meta.url));
+	for (const rel of ["../package.json", "../../package.json"]) {
+		const p = path.resolve(dir, rel);
+		try {
+			const pkg = JSON.parse(fs.readFileSync(p, "utf-8"));
+			if (pkg.name === "muxed" && pkg.version) {
+				cached = pkg.version;
+				return cached;
+			}
+		} catch {}
+	}
+	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);
+	for (let i = 0; i < 3; i++) {
+		const na = pa[i] ?? 0;
+		const nb = pb[i] ?? 0;
+		if (na < nb) return -1;
+		if (na > nb) return 1;
+	}
+	return 0;
+}
+const MUXED_BLOCK_RE = /<muxed\s+version="([^"]+)">\n?([\s\S]*?)\n?<\/muxed>/;
+const MDC_VERSION_RE = /muxed_version:\s*(.+)/;
+function extractMuxedVersion(content, format) {
+	if (format === "tagged") return content.match(MUXED_BLOCK_RE)?.[1]?.trim() ?? null;
+	const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
+	if (!fmMatch) return null;
+	return fmMatch[1].match(MDC_VERSION_RE)?.[1]?.trim() ?? null;
+}
+function getInstructionTargets(opts) {
+	const home = os.homedir();
+	const cwd = process.cwd();
+	const targets = [];
+	targets.push({
+		name: "CLAUDE.md (global)",
+		filePath: path.join(home, ".claude", "CLAUDE.md"),
+		format: "tagged",
+		scope: "global"
+	});
+	targets.push({
+		name: "AGENTS.md (global)",
+		filePath: path.join(home, ".codex", "AGENTS.md"),
+		format: "tagged",
+		scope: "global"
+	});
+	const cursorDir = path.join(cwd, ".cursor");
+	if (fs.existsSync(cursorDir)) targets.push({
+		name: ".cursor/rules/muxed.mdc",
+		filePath: path.join(cursorDir, "rules", "muxed.mdc"),
+		format: "owned",
+		scope: "local"
+	});
+	if (opts.local) {
+		targets.push({
+			name: "CLAUDE.md (local)",
+			filePath: path.join(cwd, "CLAUDE.md"),
+			format: "tagged",
+			scope: "local"
+		});
+		targets.push({
+			name: "AGENTS.md (local)",
+			filePath: path.join(cwd, "AGENTS.md"),
+			format: "tagged",
+			scope: "local"
+		});
+	}
+	return targets;
+}
+let cachedHasBun = null;
+function hasBun() {
+	if (cachedHasBun !== null) return cachedHasBun;
+	try {
+		execSync("bun --version", { stdio: "ignore" });
+		cachedHasBun = true;
+	} catch {
+		cachedHasBun = false;
+	}
+	return cachedHasBun;
+}
+function buildStaticInstructions() {
+	const bun = hasBun();
+	const run = bun ? "bunx" : "npx";
+	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.
+
+\`\`\`typescript
+import { createClient } from 'muxed/client';
+
+const client = await createClient();
+
+// Batch multiple MCP operations in one script execution
+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: \`${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 CLI proxy - usage instructions
+globs:
+alwaysApply: true
+muxed_version: ${version}
+---
+
+${content}
+`;
+}
+function injectInstructions(target, instructions, version, opts) {
+	const base = {
+		target: target.name,
+		filePath: target.filePath
+	};
+	let existing = null;
+	if (fs.existsSync(target.filePath)) existing = fs.readFileSync(target.filePath, "utf-8");
+	if (target.format === "owned") {
+		if (existing !== null) {
+			const existingVersion = extractMuxedVersion(existing, "owned");
+			if (existingVersion && compareSemver(existingVersion, version) >= 0) return {
+				...base,
+				action: "up-to-date",
+				previousVersion: existingVersion
+			};
+			if (!opts.dryRun) {
+				const dir = path.dirname(target.filePath);
+				if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+				fs.writeFileSync(target.filePath, buildMdcFile(instructions, version));
+			}
+			return {
+				...base,
+				action: existingVersion ? "updated" : "created",
+				previousVersion: existingVersion ?? void 0,
+				newVersion: version
+			};
+		}
+		if (!opts.dryRun) {
+			const dir = path.dirname(target.filePath);
+			if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(target.filePath, buildMdcFile(instructions, version));
+		}
+		return {
+			...base,
+			action: "created",
+			newVersion: version
+		};
+	}
+	const block = wrapTaggedBlock(instructions, version);
+	if (existing === null) {
+		if (!opts.dryRun) {
+			const dir = path.dirname(target.filePath);
+			if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+			fs.writeFileSync(target.filePath, block + "\n");
+		}
+		return {
+			...base,
+			action: "created",
+			newVersion: version
+		};
+	}
+	const existingVersion = extractMuxedVersion(existing, "tagged");
+	if (existingVersion !== null) {
+		if (compareSemver(existingVersion, version) >= 0) return {
+			...base,
+			action: "up-to-date",
+			previousVersion: existingVersion
+		};
+		if (!opts.dryRun) {
+			const updated = existing.replace(MUXED_BLOCK_RE, block);
+			fs.writeFileSync(target.filePath, updated);
+		}
+		return {
+			...base,
+			action: "updated",
+			previousVersion: existingVersion,
+			newVersion: version
+		};
+	}
+	if (!opts.dryRun) {
+		const separator = existing.endsWith("\n") ? "\n" : "\n\n";
+		fs.writeFileSync(target.filePath, existing + separator + block + "\n");
+	}
+	return {
+		...base,
+		action: "created",
+		newVersion: version
+	};
+}
+function injectAllInstructions(opts) {
+	const targets = getInstructionTargets({ local: opts.local });
+	const instructions = buildStaticInstructions();
+	const version = getVersion();
+	return targets.map((target) => injectInstructions(target, instructions, version, opts));
+}
 async function confirm(message, opts) {
 	const rl = readline.createInterface({
 		input: opts?.input ?? process.stdin,
@@ -3732,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("--no-delete", "Keep original server entries in agent configs").option("--no-replace", "Don't add muxed entry to agent configs").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();
@@ -3755,7 +4598,7 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 	}
 	if (!opts.dryRun && imported.length > 0) writeMuxedConfig(muxedPath, result.merged);
 	const modifiedFiles = [];
-	const shouldDelete = isInteractive ? await confirm("Remove imported servers from agent config files? (backups will be created)") : opts.delete;
+	const shouldDelete = isInteractive ? await confirm("Remove imported servers from agent config files? (backups will be created)") : !!opts.delete;
 	if (!opts.dryRun && shouldDelete) for (const dc of discovered) try {
 		modifyAgentConfig(dc, {
 			delete: true,
@@ -3765,6 +4608,10 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 	} catch (err) {
 		warnings.push(`Failed to modify ${dc.configPath}: ${err instanceof Error ? err.message : String(err)}`);
 	}
+	const instructionResults = (isInteractive ? await confirm("Inject muxed CLI instructions into agent files? (CLAUDE.md, AGENTS.md)") : opts.instructions) ? injectAllInstructions({
+		local: !!opts.local,
+		dryRun: !!opts.dryRun
+	}) : [];
 	const initResult = {
 		discovered: discovered.map((d) => ({
 			agent: d.agent.name,
@@ -3778,14 +4625,17 @@ const initCommand = new Command("init").description("Discover and import MCP ser
 		warnings,
 		modifiedFiles,
 		muxedConfigPath: muxedPath,
-		dryRun: opts.dryRun ?? false
+		dryRun: opts.dryRun ?? false,
+		instructionResults
 	};
 	capture("init_run", {
 		dry_run: opts.dryRun ?? false,
 		imported_count: imported.length,
 		conflict_count: conflicts.length,
 		warning_count: warnings.length,
-		discovered_agents: initResult.discovered.map((d) => d.agent)
+		discovered_agents: initResult.discovered.map((d) => d.agent),
+		instruction_targets: instructionResults.length,
+		instruction_actions: instructionResults.map((r) => r.action)
 	});
 	console.log(opts.json ? formatJson(initResult) : formatInit(initResult));
 });
@@ -3838,180 +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",
-	info: (n) => `npx muxed info ${n}`,
-	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" })`,
-	info: (n) => `muxed:exec({ "command": "info ${n}" })`,
-	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: ALWAYS CHECK SCHEMA FIRST (MANDATORY)
-${f.info("<server>/<tool>")}           # REQUIRED before ANY call - View JSON schema
-
-# STEP 3: OPTIONAL - Validate arguments before calling (dry-run)
-${f.callDryRun("<server>/<tool>", "<json>")}  # Validate args without executing
-
-# STEP 4: Only after checking schema, make the call
-${f.call("<server>/<tool>", "<json>")}  # Only run AFTER info
-${f.callStdin("<server>/<tool>")}       # Invoke with JSON input (AFTER info)
-${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 details
-${f.info("<server>/<tool>")}          # View JSON schema for input and output if available
-
-# 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();
@@ -4025,6 +4710,22 @@ function parseCommand(command) {
 		args: trimmed.slice(spaceIndex + 1).trim()
 	};
 }
+function parseFlags(args) {
+	const flags = {};
+	const positionalParts = [];
+	const parts = args.split(/\s+/);
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (part.startsWith("--") && i + 1 < parts.length) {
+			const key = part.slice(2);
+			flags[key] = parts[++i];
+		} else positionalParts.push(part);
+	}
+	return {
+		positional: positionalParts.join(" "),
+		flags
+	};
+}
 function textResult(data) {
 	return { content: [{
 		type: "text",
@@ -4046,16 +4747,31 @@ async function handleToolCommand(command, input) {
 		switch (subcommand) {
 			case "servers": return textResult(await sendRequest("servers/list"));
 			case "tools": {
+				const { positional, flags } = parseFlags(args);
 				const params = {};
-				if (args) params.server = args;
+				if (positional) params.server = positional;
+				if (flags.include === "schema") params.includeSchema = true;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
 				return textResult(await sendRequest("tools/list", params));
 			}
-			case "grep":
+			case "grep": {
 				if (!args) return errorResult("Usage: grep <pattern>");
-				return textResult(await sendRequest("tools/grep", { pattern: args }));
-			case "info":
-				if (!args) return errorResult("Usage: info <server/tool>");
-				return textResult(await sendRequest("tools/info", { name: args }));
+				const { positional, flags } = parseFlags(args);
+				if (!positional) return errorResult("Usage: grep <pattern>");
+				const params = { pattern: positional };
+				if (flags.include === "schema") params.includeSchema = true;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
+				return textResult(await sendRequest("tools/grep", params));
+			}
+			case "info": {
+				if (!args) return errorResult("Usage: info <server/tool> [--path <path>] [--depth <n>]");
+				const { positional, flags } = parseFlags(args);
+				if (!positional) return errorResult("Usage: info <server/tool>");
+				const params = { name: positional };
+				if (flags.path) params.path = flags.path;
+				if (flags.depth) params.schemaDepth = parseInt(flags.depth, 10);
+				return textResult(await sendRequest("tools/info", params));
+			}
 			case "call": {
 				if (!args) return errorResult("Usage: call <server/tool>");
 				const result = await sendRequest("tools/call", {
@@ -4194,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);
@@ -4220,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);
@@ -4247,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);
@@ -4275,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);
@@ -4295,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);
@@ -4318,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;
@@ -4359,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);
@@ -4369,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);
@@ -4390,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("0.1.0");
+	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:");