@aigne/cli 1.74.0-beta.1 → 1.74.0-beta.2

package/dist/commands/explain.cjs

@@ -0,0 +1,340 @@
+
+//#region src/commands/explain.ts
+/**
+* List of all available commands with their descriptions.
+* Used by `aigne explain` without arguments.
+*/
+const availableCommands = [
+	{
+		name: "run",
+		description: "Run an AIGNE agent"
+	},
+	{
+		name: "skill",
+		description: "Run Agent Skills from directories"
+	},
+	{
+		name: "eval",
+		description: "Evaluate an agent against test cases"
+	},
+	{
+		name: "test",
+		description: "Run agent tests"
+	},
+	{
+		name: "create",
+		description: "Create a new agent project"
+	},
+	{
+		name: "serve-mcp",
+		description: "Serve agent as MCP server"
+	},
+	{
+		name: "observe",
+		description: "Start observability server"
+	},
+	{
+		name: "hub",
+		description: "Manage AIGNE Hub connections"
+	},
+	{
+		name: "explain",
+		description: "Show command documentation"
+	}
+];
+/**
+* Registry of all command documentation.
+*/
+const commandDocs = {
+	"hub list": {
+		command: "aigne hub list",
+		purpose: "List all connected AIGNE Hub instances",
+		input: ["--json: Output in JSON format", "--view=<type>: Output view (default|json|llm|human)"],
+		outputs: {
+			default: "<url> <status> (one per line, space-separated)",
+			json: "{\"schema_version\":\"1.0\",\"hubs\":[{\"url\":\"...\",\"status\":\"active|inactive\"}]}",
+			llm: "URL <url>\\nSTATUS <status> (per hub)"
+		},
+		errors: ["No hubs connected: outputs nothing (default) or empty array (json)"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "In TTY: displays formatted table. Non-TTY: outputs machine truth (url status per line)"
+	},
+	"hub status": {
+		command: "aigne hub status",
+		purpose: "Show detailed status of the active AIGNE Hub connection",
+		input: [
+			"--json: Output in JSON format",
+			"--view=<type>: Output view (default|json|llm|human)",
+			"In TTY: prompts to select hub"
+		],
+		outputs: {
+			default: "<hub> <status> <user_name> <email> (space-separated)",
+			json: "{\"schema_version\":\"1.0\",\"hub\":\"...\",\"status\":\"...\",\"user\":{...},\"credits\":{...}}",
+			llm: "HUB <url>\\nSTATUS <status>\\nUSER_NAME <name>\\nUSER_EMAIL <email>\\nCREDITS_AVAILABLE <n>"
+		},
+		errors: ["No hubs connected: outputs error message", "Network error: displays connection failure"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "In TTY: prompts to select hub, shows formatted status. Non-TTY: uses active hub, outputs machine truth"
+	},
+	"hub connect": {
+		command: "aigne hub connect [url]",
+		purpose: "Connect to an AIGNE Hub instance",
+		input: ["url (optional): Hub URL to connect to", "If no URL: prompts for selection"],
+		outputs: { default: "Success or error message" },
+		errors: ["Invalid URL: validation error", "Connection failed: network error"],
+		sideEffects: ["Stores hub credentials in secure storage", "Sets connected hub as active"],
+		defaultBehavior: "Prompts for official or custom hub, then opens browser for authentication"
+	},
+	"hub use": {
+		command: "aigne hub use",
+		purpose: "Switch to a different connected AIGNE Hub",
+		input: ["Prompts to select from connected hubs"],
+		outputs: { default: "Success message with selected hub" },
+		errors: ["No hubs connected: displays warning"],
+		sideEffects: ["Updates active hub in secure storage"],
+		defaultBehavior: "Displays list of connected hubs, sets selected as active"
+	},
+	"hub remove": {
+		command: "aigne hub remove",
+		purpose: "Remove a connected AIGNE Hub",
+		input: ["Prompts to select hub to remove"],
+		outputs: { default: "Success message with removed hub" },
+		errors: ["No hubs connected: displays warning"],
+		sideEffects: ["Removes hub credentials from secure storage", "If removing active hub, switches to next available"],
+		defaultBehavior: "Prompts to select hub, removes credentials, updates active if needed"
+	},
+	run: {
+		command: "aigne run [path]",
+		purpose: "Run an AIGNE agent from a directory or URL",
+		input: [
+			"path (optional): Path to agent directory or URL to an aigne project",
+			"entry-agent (optional): Name of the agent to run",
+			"--interactive/--chat: Run in interactive chat mode",
+			"--input/-i: Input to the agent",
+			"--model: AI model to use",
+			"--json: Output in JSON format",
+			"--view: Output view type (default|json|llm|human)"
+		],
+		outputs: {
+			default: "Agent response output",
+			json: "{\"schema_version\":\"1.0\",\"input\":{...},\"output\":{...},\"duration_ms\":N}",
+			llm: "AGENT <name>\\nINPUT <message>\\nOUTPUT <response>\\nDURATION <ms>"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 5: Agent execution failed",
+			"exit 6: Invalid input format",
+			"exit 7: Model connection failed"
+		],
+		sideEffects: ["May create files if agent has file tools", "May make network requests"],
+		defaultBehavior: "Loads agent from current directory if no path. Interactive mode if TTY and no --input"
+	},
+	skill: {
+		command: "aigne skill <paths..>",
+		purpose: "Run Agent Skills from specified directories",
+		input: [
+			"paths: One or more paths to Agent Skill directories",
+			"--interactive/--chat: Run in interactive chat mode",
+			"--input/-i: Input message to the skill",
+			"--model: AI model to use",
+			"--json: Output in JSON format",
+			"--view: Output view type (default|json|llm|human)"
+		],
+		outputs: {
+			default: "Skill execution output",
+			json: "{\"schema_version\":\"1.0\",\"input\":{...},\"output\":{...},\"duration_ms\":N}"
+		},
+		errors: [
+			"exit 1: Skill directory not found",
+			"exit 5: Skill execution failed",
+			"exit 6: Invalid input"
+		],
+		sideEffects: [
+			"May execute bash commands (with user confirmation)",
+			"May create/modify files in workspace",
+			"May make network requests"
+		],
+		defaultBehavior: "Creates AgentSkillManager with BashAgent and AskUserQuestion. Mounts skill directories as AFS modules"
+	},
+	eval: {
+		command: "aigne eval [path]",
+		purpose: "Evaluate an AIGNE agent against test cases",
+		input: [
+			"path (optional): Path to agent directory",
+			"--json: Output in JSON format",
+			"--view: Output view type"
+		],
+		outputs: {
+			default: "<test-id> <status> <score> <duration> (one per line)",
+			json: "{\"schema_version\":\"1.0\",\"results\":[...],\"summary\":{...}}",
+			llm: "EVAL <test-id>\\nSTATUS <PASS|FAIL>\\nSCORE <n>"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 4: Partial test failure",
+			"exit 5: Evaluation error"
+		],
+		sideEffects: ["May make LLM API calls for evaluation"],
+		defaultBehavior: "Loads agent from current directory, runs all test cases, reports results"
+	},
+	test: {
+		command: "aigne test",
+		purpose: "Run agent tests in the specified directory",
+		input: ["--filter: Filter tests by name pattern", "--json: Output in JSON format"],
+		outputs: {
+			default: "<spec> <status> <passed> <failed> (one per line)",
+			json: "{\"schema_version\":\"1.0\",\"specs\":[...],\"summary\":{...}}"
+		},
+		errors: ["exit 1: No tests found", "exit 4: Some tests failed"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "Runs all tests in the current directory using node --test"
+	},
+	create: {
+		command: "aigne create [path]",
+		purpose: "Create a new AIGNE agent project",
+		input: [
+			"path (optional): Directory to create the project in",
+			"--template: Project template to use",
+			"--json: Output in JSON format"
+		],
+		outputs: {
+			default: "created <path>",
+			json: "{\"schema_version\":\"1.0\",\"path\":\"...\",\"template\":\"...\",\"files_created\":[...]}"
+		},
+		errors: ["exit 3: Directory already exists", "exit 6: Invalid template"],
+		sideEffects: ["Creates directory structure", "Creates configuration files"],
+		defaultBehavior: "Interactive prompts for project name and template if not specified"
+	},
+	"serve-mcp": {
+		command: "aigne serve-mcp [path]",
+		purpose: "Serve agents as an MCP (Model Context Protocol) server",
+		input: [
+			"path (optional): Path to agent directory",
+			"--host: Host to bind (default: localhost)",
+			"--port: Port to listen on",
+			"--pathname: URL pathname (default: /mcp)",
+			"--json: Output startup info in JSON format"
+		],
+		outputs: {
+			default: "listening <host>:<port><pathname>",
+			json: "{\"schema_version\":\"1.0\",\"status\":\"listening\",\"host\":\"...\",\"port\":N,\"path\":\"...\"}"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 5: Server startup failed",
+			"exit 7: Port already in use"
+		],
+		sideEffects: ["Starts HTTP server", "Listens for MCP connections"],
+		defaultBehavior: "Loads agent from current directory, starts MCP server on localhost"
+	},
+	observe: {
+		command: "aigne observe",
+		purpose: "Start the observability server for agent debugging",
+		input: [
+			"--port: Port to listen on",
+			"--host: Host to bind",
+			"--json: Output startup info in JSON format"
+		],
+		outputs: {
+			default: "listening <host>:<port>",
+			json: "{\"schema_version\":\"1.0\",\"status\":\"listening\",\"host\":\"...\",\"port\":N}"
+		},
+		errors: ["exit 5: Server startup failed", "exit 7: Port already in use"],
+		sideEffects: ["Starts HTTP server", "Provides tracing and debugging UI"],
+		defaultBehavior: "Starts observability server on default port"
+	},
+	hub: {
+		command: "aigne hub <command>",
+		purpose: "Manage AIGNE Hub connections",
+		input: ["command: list|connect|use|status|remove"],
+		outputs: { default: "Varies by subcommand" },
+		errors: ["See individual subcommand documentation"],
+		sideEffects: ["Varies by subcommand - see aigne explain hub <subcommand>"],
+		defaultBehavior: "Shows hub command help if no subcommand specified"
+	},
+	explain: {
+		command: "aigne explain [command..]",
+		purpose: "Show machine-readable documentation for CLI commands",
+		input: ["command (optional): Command path to explain (e.g., hub list)"],
+		outputs: { default: "Without args: lists available commands. With args: shows structured documentation for the command" },
+		errors: ["ERROR unknown_command: Command not found in documentation"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "Lists all available commands if no command specified"
+	}
+};
+/**
+* Print command documentation in structured format.
+*/
+function printCommandDoc(doc) {
+	console.log(`COMMAND ${doc.command}`);
+	console.log("");
+	console.log("PURPOSE");
+	console.log(`  ${doc.purpose}`);
+	console.log("");
+	console.log("INPUT");
+	for (const input of doc.input) console.log(`  ${input}`);
+	console.log("");
+	console.log("OUTPUT default:");
+	console.log(`  ${doc.outputs.default}`);
+	if (doc.outputs.json) {
+		console.log("OUTPUT --json:");
+		console.log(`  ${doc.outputs.json}`);
+	}
+	if (doc.outputs.llm) {
+		console.log("OUTPUT --view=llm:");
+		console.log(`  ${doc.outputs.llm}`);
+	}
+	console.log("");
+	console.log("ERRORS");
+	for (const error of doc.errors) console.log(`  ${error}`);
+	console.log("");
+	console.log("SIDE EFFECTS");
+	for (const effect of doc.sideEffects) console.log(`  ${effect}`);
+	console.log("");
+	console.log("DEFAULT BEHAVIOR");
+	console.log(`  ${doc.defaultBehavior}`);
+}
+/**
+* Print list of all available commands.
+*/
+function printAvailableCommands() {
+	console.log("AVAILABLE COMMANDS");
+	for (const cmd of availableCommands) console.log(`  ${cmd.name.padEnd(12)} ${cmd.description}`);
+	console.log("");
+	console.log("Use 'aigne explain <command>' for detailed documentation.");
+}
+/**
+* Create the explain command.
+*/
+function createExplainCommand() {
+	return {
+		command: "explain [command..]",
+		describe: "Show machine-readable documentation for a command",
+		builder: (yargs) => yargs.positional("command", {
+			type: "string",
+			describe: "Command path to explain (e.g., hub list)",
+			array: true,
+			default: []
+		}),
+		handler: (args) => {
+			const commands = args.command;
+			if (commands.length === 0) {
+				printAvailableCommands();
+				return;
+			}
+			const commandPath = commands.join(" ");
+			const doc = commandDocs[commandPath];
+			if (!doc) {
+				console.log(`ERROR unknown_command ${commandPath}`);
+				console.log("");
+				printAvailableCommands();
+				process.exitCode = 1;
+				return;
+			}
+			printCommandDoc(doc);
+		}
+	};
+}
+
+//#endregion
+exports.createExplainCommand = createExplainCommand;

package/dist/commands/explain.mjs

@@ -0,0 +1,340 @@
+//#region src/commands/explain.ts
+/**
+* List of all available commands with their descriptions.
+* Used by `aigne explain` without arguments.
+*/
+const availableCommands = [
+	{
+		name: "run",
+		description: "Run an AIGNE agent"
+	},
+	{
+		name: "skill",
+		description: "Run Agent Skills from directories"
+	},
+	{
+		name: "eval",
+		description: "Evaluate an agent against test cases"
+	},
+	{
+		name: "test",
+		description: "Run agent tests"
+	},
+	{
+		name: "create",
+		description: "Create a new agent project"
+	},
+	{
+		name: "serve-mcp",
+		description: "Serve agent as MCP server"
+	},
+	{
+		name: "observe",
+		description: "Start observability server"
+	},
+	{
+		name: "hub",
+		description: "Manage AIGNE Hub connections"
+	},
+	{
+		name: "explain",
+		description: "Show command documentation"
+	}
+];
+/**
+* Registry of all command documentation.
+*/
+const commandDocs = {
+	"hub list": {
+		command: "aigne hub list",
+		purpose: "List all connected AIGNE Hub instances",
+		input: ["--json: Output in JSON format", "--view=<type>: Output view (default|json|llm|human)"],
+		outputs: {
+			default: "<url> <status> (one per line, space-separated)",
+			json: "{\"schema_version\":\"1.0\",\"hubs\":[{\"url\":\"...\",\"status\":\"active|inactive\"}]}",
+			llm: "URL <url>\\nSTATUS <status> (per hub)"
+		},
+		errors: ["No hubs connected: outputs nothing (default) or empty array (json)"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "In TTY: displays formatted table. Non-TTY: outputs machine truth (url status per line)"
+	},
+	"hub status": {
+		command: "aigne hub status",
+		purpose: "Show detailed status of the active AIGNE Hub connection",
+		input: [
+			"--json: Output in JSON format",
+			"--view=<type>: Output view (default|json|llm|human)",
+			"In TTY: prompts to select hub"
+		],
+		outputs: {
+			default: "<hub> <status> <user_name> <email> (space-separated)",
+			json: "{\"schema_version\":\"1.0\",\"hub\":\"...\",\"status\":\"...\",\"user\":{...},\"credits\":{...}}",
+			llm: "HUB <url>\\nSTATUS <status>\\nUSER_NAME <name>\\nUSER_EMAIL <email>\\nCREDITS_AVAILABLE <n>"
+		},
+		errors: ["No hubs connected: outputs error message", "Network error: displays connection failure"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "In TTY: prompts to select hub, shows formatted status. Non-TTY: uses active hub, outputs machine truth"
+	},
+	"hub connect": {
+		command: "aigne hub connect [url]",
+		purpose: "Connect to an AIGNE Hub instance",
+		input: ["url (optional): Hub URL to connect to", "If no URL: prompts for selection"],
+		outputs: { default: "Success or error message" },
+		errors: ["Invalid URL: validation error", "Connection failed: network error"],
+		sideEffects: ["Stores hub credentials in secure storage", "Sets connected hub as active"],
+		defaultBehavior: "Prompts for official or custom hub, then opens browser for authentication"
+	},
+	"hub use": {
+		command: "aigne hub use",
+		purpose: "Switch to a different connected AIGNE Hub",
+		input: ["Prompts to select from connected hubs"],
+		outputs: { default: "Success message with selected hub" },
+		errors: ["No hubs connected: displays warning"],
+		sideEffects: ["Updates active hub in secure storage"],
+		defaultBehavior: "Displays list of connected hubs, sets selected as active"
+	},
+	"hub remove": {
+		command: "aigne hub remove",
+		purpose: "Remove a connected AIGNE Hub",
+		input: ["Prompts to select hub to remove"],
+		outputs: { default: "Success message with removed hub" },
+		errors: ["No hubs connected: displays warning"],
+		sideEffects: ["Removes hub credentials from secure storage", "If removing active hub, switches to next available"],
+		defaultBehavior: "Prompts to select hub, removes credentials, updates active if needed"
+	},
+	run: {
+		command: "aigne run [path]",
+		purpose: "Run an AIGNE agent from a directory or URL",
+		input: [
+			"path (optional): Path to agent directory or URL to an aigne project",
+			"entry-agent (optional): Name of the agent to run",
+			"--interactive/--chat: Run in interactive chat mode",
+			"--input/-i: Input to the agent",
+			"--model: AI model to use",
+			"--json: Output in JSON format",
+			"--view: Output view type (default|json|llm|human)"
+		],
+		outputs: {
+			default: "Agent response output",
+			json: "{\"schema_version\":\"1.0\",\"input\":{...},\"output\":{...},\"duration_ms\":N}",
+			llm: "AGENT <name>\\nINPUT <message>\\nOUTPUT <response>\\nDURATION <ms>"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 5: Agent execution failed",
+			"exit 6: Invalid input format",
+			"exit 7: Model connection failed"
+		],
+		sideEffects: ["May create files if agent has file tools", "May make network requests"],
+		defaultBehavior: "Loads agent from current directory if no path. Interactive mode if TTY and no --input"
+	},
+	skill: {
+		command: "aigne skill <paths..>",
+		purpose: "Run Agent Skills from specified directories",
+		input: [
+			"paths: One or more paths to Agent Skill directories",
+			"--interactive/--chat: Run in interactive chat mode",
+			"--input/-i: Input message to the skill",
+			"--model: AI model to use",
+			"--json: Output in JSON format",
+			"--view: Output view type (default|json|llm|human)"
+		],
+		outputs: {
+			default: "Skill execution output",
+			json: "{\"schema_version\":\"1.0\",\"input\":{...},\"output\":{...},\"duration_ms\":N}"
+		},
+		errors: [
+			"exit 1: Skill directory not found",
+			"exit 5: Skill execution failed",
+			"exit 6: Invalid input"
+		],
+		sideEffects: [
+			"May execute bash commands (with user confirmation)",
+			"May create/modify files in workspace",
+			"May make network requests"
+		],
+		defaultBehavior: "Creates AgentSkillManager with BashAgent and AskUserQuestion. Mounts skill directories as AFS modules"
+	},
+	eval: {
+		command: "aigne eval [path]",
+		purpose: "Evaluate an AIGNE agent against test cases",
+		input: [
+			"path (optional): Path to agent directory",
+			"--json: Output in JSON format",
+			"--view: Output view type"
+		],
+		outputs: {
+			default: "<test-id> <status> <score> <duration> (one per line)",
+			json: "{\"schema_version\":\"1.0\",\"results\":[...],\"summary\":{...}}",
+			llm: "EVAL <test-id>\\nSTATUS <PASS|FAIL>\\nSCORE <n>"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 4: Partial test failure",
+			"exit 5: Evaluation error"
+		],
+		sideEffects: ["May make LLM API calls for evaluation"],
+		defaultBehavior: "Loads agent from current directory, runs all test cases, reports results"
+	},
+	test: {
+		command: "aigne test",
+		purpose: "Run agent tests in the specified directory",
+		input: ["--filter: Filter tests by name pattern", "--json: Output in JSON format"],
+		outputs: {
+			default: "<spec> <status> <passed> <failed> (one per line)",
+			json: "{\"schema_version\":\"1.0\",\"specs\":[...],\"summary\":{...}}"
+		},
+		errors: ["exit 1: No tests found", "exit 4: Some tests failed"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "Runs all tests in the current directory using node --test"
+	},
+	create: {
+		command: "aigne create [path]",
+		purpose: "Create a new AIGNE agent project",
+		input: [
+			"path (optional): Directory to create the project in",
+			"--template: Project template to use",
+			"--json: Output in JSON format"
+		],
+		outputs: {
+			default: "created <path>",
+			json: "{\"schema_version\":\"1.0\",\"path\":\"...\",\"template\":\"...\",\"files_created\":[...]}"
+		},
+		errors: ["exit 3: Directory already exists", "exit 6: Invalid template"],
+		sideEffects: ["Creates directory structure", "Creates configuration files"],
+		defaultBehavior: "Interactive prompts for project name and template if not specified"
+	},
+	"serve-mcp": {
+		command: "aigne serve-mcp [path]",
+		purpose: "Serve agents as an MCP (Model Context Protocol) server",
+		input: [
+			"path (optional): Path to agent directory",
+			"--host: Host to bind (default: localhost)",
+			"--port: Port to listen on",
+			"--pathname: URL pathname (default: /mcp)",
+			"--json: Output startup info in JSON format"
+		],
+		outputs: {
+			default: "listening <host>:<port><pathname>",
+			json: "{\"schema_version\":\"1.0\",\"status\":\"listening\",\"host\":\"...\",\"port\":N,\"path\":\"...\"}"
+		},
+		errors: [
+			"exit 1: Agent not found",
+			"exit 5: Server startup failed",
+			"exit 7: Port already in use"
+		],
+		sideEffects: ["Starts HTTP server", "Listens for MCP connections"],
+		defaultBehavior: "Loads agent from current directory, starts MCP server on localhost"
+	},
+	observe: {
+		command: "aigne observe",
+		purpose: "Start the observability server for agent debugging",
+		input: [
+			"--port: Port to listen on",
+			"--host: Host to bind",
+			"--json: Output startup info in JSON format"
+		],
+		outputs: {
+			default: "listening <host>:<port>",
+			json: "{\"schema_version\":\"1.0\",\"status\":\"listening\",\"host\":\"...\",\"port\":N}"
+		},
+		errors: ["exit 5: Server startup failed", "exit 7: Port already in use"],
+		sideEffects: ["Starts HTTP server", "Provides tracing and debugging UI"],
+		defaultBehavior: "Starts observability server on default port"
+	},
+	hub: {
+		command: "aigne hub <command>",
+		purpose: "Manage AIGNE Hub connections",
+		input: ["command: list|connect|use|status|remove"],
+		outputs: { default: "Varies by subcommand" },
+		errors: ["See individual subcommand documentation"],
+		sideEffects: ["Varies by subcommand - see aigne explain hub <subcommand>"],
+		defaultBehavior: "Shows hub command help if no subcommand specified"
+	},
+	explain: {
+		command: "aigne explain [command..]",
+		purpose: "Show machine-readable documentation for CLI commands",
+		input: ["command (optional): Command path to explain (e.g., hub list)"],
+		outputs: { default: "Without args: lists available commands. With args: shows structured documentation for the command" },
+		errors: ["ERROR unknown_command: Command not found in documentation"],
+		sideEffects: ["None - read-only operation"],
+		defaultBehavior: "Lists all available commands if no command specified"
+	}
+};
+/**
+* Print command documentation in structured format.
+*/
+function printCommandDoc(doc) {
+	console.log(`COMMAND ${doc.command}`);
+	console.log("");
+	console.log("PURPOSE");
+	console.log(`  ${doc.purpose}`);
+	console.log("");
+	console.log("INPUT");
+	for (const input of doc.input) console.log(`  ${input}`);
+	console.log("");
+	console.log("OUTPUT default:");
+	console.log(`  ${doc.outputs.default}`);
+	if (doc.outputs.json) {
+		console.log("OUTPUT --json:");
+		console.log(`  ${doc.outputs.json}`);
+	}
+	if (doc.outputs.llm) {
+		console.log("OUTPUT --view=llm:");
+		console.log(`  ${doc.outputs.llm}`);
+	}
+	console.log("");
+	console.log("ERRORS");
+	for (const error of doc.errors) console.log(`  ${error}`);
+	console.log("");
+	console.log("SIDE EFFECTS");
+	for (const effect of doc.sideEffects) console.log(`  ${effect}`);
+	console.log("");
+	console.log("DEFAULT BEHAVIOR");
+	console.log(`  ${doc.defaultBehavior}`);
+}
+/**
+* Print list of all available commands.
+*/
+function printAvailableCommands() {
+	console.log("AVAILABLE COMMANDS");
+	for (const cmd of availableCommands) console.log(`  ${cmd.name.padEnd(12)} ${cmd.description}`);
+	console.log("");
+	console.log("Use 'aigne explain <command>' for detailed documentation.");
+}
+/**
+* Create the explain command.
+*/
+function createExplainCommand() {
+	return {
+		command: "explain [command..]",
+		describe: "Show machine-readable documentation for a command",
+		builder: (yargs) => yargs.positional("command", {
+			type: "string",
+			describe: "Command path to explain (e.g., hub list)",
+			array: true,
+			default: []
+		}),
+		handler: (args) => {
+			const commands = args.command;
+			if (commands.length === 0) {
+				printAvailableCommands();
+				return;
+			}
+			const commandPath = commands.join(" ");
+			const doc = commandDocs[commandPath];
+			if (!doc) {
+				console.log(`ERROR unknown_command ${commandPath}`);
+				console.log("");
+				printAvailableCommands();
+				process.exitCode = 1;
+				return;
+			}
+			printCommandDoc(doc);
+		}
+	};
+}
+
+//#endregion
+export { createExplainCommand };
+//# sourceMappingURL=explain.mjs.map