@ogment-ai/cli 0.3.4 → 0.4.0

package/dist/cli.js

@@ -2,10 +2,10 @@
 import { realpathSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command, CommanderError } from "commander";
-import { runCallCommand } from "./commands/call.js";
-import { runDescribeCommand } from "./commands/describe.js";
-import { runInfoCommand } from "./commands/info.js";
-import { runServersCommand } from "./commands/servers.js";
+import { runAuthLoginCommand, runAuthLogoutCommand, runAuthStatusCommand, } from "./commands/auth.js";
+import { runCatalogCommand, runCatalogToolDetailsCommand, runCatalogToolsCommand, } from "./commands/catalog.js";
+import { runInvokeCommand } from "./commands/invoke.js";
+import { runStatusCommand } from "./commands/status.js";
 import { createBrowserOpener } from "./infra/browser.js";
 import { createFileCredentialsStore } from "./infra/credentials.js";
 import { createRuntimeConfig } from "./infra/env.js";
@@ -15,9 +15,11 @@ import { createAccountService } from "./services/account.js";
 import { createAuthService } from "./services/auth.js";
 import { createInfoService } from "./services/info.js";
 import { createMcpService } from "./services/mcp.js";
-import { UnexpectedError, ValidationError } from "./shared/errors.js";
+import { buildJsonSchemaExample } from "./shared/schema-example.js";
+import { ERROR_CODE } from "./shared/error-codes.js";
+import { AuthError, ContractMismatchError, NotFoundError, RemoteRequestError, UnexpectedError, ValidationError, } from "./shared/errors.js";
 import { EXIT_CODE, exitCodeForError } from "./shared/exit-codes.js";
-import { APP_DESCRIPTION, APP_NAME, AGENT_SUCCESS_HINT, VERSION } from "./shared/constants.js";
+import { APP_DESCRIPTION, APP_NAME, VERSION } from "./shared/constants.js";
 class CliExitError extends Error {
     exitCode;
     constructor(exitCode) {
@@ -76,7 +78,7 @@ const asGlobalOptions = (command) => {
     const options = command.optsWithGlobals();
     return {
         apiKey: options.apiKey,
-        json: options.json,
+        human: options.human,
         nonInteractive: options.nonInteractive,
         quiet: options.quiet,
         yes: options.yes,
@@ -84,7 +86,7 @@ const asGlobalOptions = (command) => {
 };
 const mapGlobalOutputOptions = (options) => {
     return {
-        json: options.json,
+        human: options.human,
         nonInteractive: options.nonInteractive,
         quiet: options.quiet,
         yes: options.yes,
@@ -93,177 +95,169 @@ const mapGlobalOutputOptions = (options) => {
 const throwCommandError = (error) => {
     throw new CliExitError(exitCodeForError(error));
 };
-const isRecord = (value) => {
-    return typeof value === "object" && value !== null;
+const nextAction = (id, title, command, reason, when = null) => {
+    return {
+        command,
+        id,
+        reason,
+        title,
+        when,
+    };
+};
+const hasPlaceholderTokens = (command) => {
+    return command.includes("<") || command.includes(">");
+};
+const nextActionsForError = (error) => {
+    const fallbackByCode = {
+        [ERROR_CODE.authDeviceExpired]: {
+            command: "ogment auth login",
+            reason: "Device code expired; restart login to continue.",
+            title: "Restart login",
+        },
+        [ERROR_CODE.authDevicePending]: {
+            command: "ogment auth status",
+            reason: "Authorization is pending; check whether credentials are now available.",
+            title: "Check auth status",
+        },
+        [ERROR_CODE.authInvalidCredentials]: {
+            command: "ogment auth logout",
+            reason: "Credentials are invalid; clear local state before re-authenticating.",
+            title: "Reset auth state",
+        },
+        [ERROR_CODE.authRequired]: {
+            command: "ogment auth login",
+            reason: "Authentication is required before catalog or invoke commands can run.",
+            title: "Authenticate",
+        },
+        [ERROR_CODE.remoteRateLimited]: {
+            command: "ogment status",
+            reason: "Remote rate limit detected; check diagnostics before retrying.",
+            title: "Inspect diagnostics",
+        },
+        [ERROR_CODE.remoteUnavailable]: {
+            command: "ogment status",
+            reason: "Remote service is unavailable; check connectivity and endpoint health.",
+            title: "Inspect diagnostics",
+        },
+        [ERROR_CODE.toolInputSchemaViolation]: {
+            command: "ogment catalog",
+            reason: "Tool contract did not validate; inspect available servers and tool metadata.",
+            title: "Inspect catalog",
+        },
+        [ERROR_CODE.toolNotFound]: {
+            command: "ogment catalog",
+            reason: "Requested tool could not be found; rediscover servers and tools.",
+            title: "Rediscover tools",
+        },
+        [ERROR_CODE.transportRequestFailed]: {
+            command: "ogment status",
+            reason: "Transport request failed; inspect connectivity diagnostics.",
+            title: "Inspect diagnostics",
+        },
+        [ERROR_CODE.contractVersionUnsupported]: {
+            command: "ogment --version",
+            reason: "Contract mismatch detected; verify CLI version and upgrade before retrying.",
+            title: "Inspect CLI version",
+        },
+        [ERROR_CODE.internalUnexpected]: {
+            command: "ogment status",
+            reason: "Unexpected failure detected; run diagnostics before retrying the workflow.",
+            title: "Inspect diagnostics",
+        },
+        [ERROR_CODE.validationInvalidInput]: {
+            command: "ogment --help",
+            reason: "Input validation failed; inspect canonical command syntax.",
+            title: "Show command help",
+        },
+    };
+    const fallback = fallbackByCode[error.code];
+    const suggestedCommand = typeof error.suggestedCommand === "string" && !hasPlaceholderTokens(error.suggestedCommand)
+        ? error.suggestedCommand
+        : undefined;
+    const command = suggestedCommand ?? fallback?.command;
+    if (command === undefined) {
+        return [];
+    }
+    return [
+        nextAction(`recover_${error.code.toLowerCase()}`, fallback?.title ?? "Run suggested command", command, fallback?.reason ?? `Suggested recovery for error ${error.code}.`, "immediate"),
+    ];
 };
-const ensureSuccess = (result, output) => {
+const ensureSuccess = (result, output, context) => {
     if (result.status === "error") {
-        output.error(result.error);
+        output.error(result.error, {
+            command: context.command,
+            entity: context.entity ?? null,
+            nextActions: nextActionsForError(result.error),
+        });
         throwCommandError(result.error);
     }
     return result.value;
 };
-const formatSchemaType = (property) => {
-    if (Array.isArray(property.enum) && property.enum.length > 0) {
-        return property.enum.map(String).join(" | ");
-    }
-    if (property.type === "array" && typeof property.items?.type === "string") {
-        return `${property.items.type}[]`;
-    }
-    if (typeof property.type === "string" && property.type.length > 0) {
-        return property.type;
-    }
-    return "unknown";
+const nextActionsForLogin = (payload, mode) => {
+    return [
+        nextAction("check_auth_status", "Check auth status", "ogment auth status", `Verify persisted credentials after ${mode} login for ${payload.agentName}.`, "immediate"),
+        nextAction("discover_servers", "Discover servers", "ogment catalog", `Logged in as ${payload.agentName} via ${mode}; discover available servers.`, "after_auth"),
+    ];
 };
-const renderSchemaParameters = (output, schema) => {
-    const required = new Set();
-    const requiredValue = schema["required"];
-    if (Array.isArray(requiredValue)) {
-        for (const item of requiredValue) {
-            if (typeof item === "string") {
-                required.add(item);
-            }
-        }
-    }
-    const propertiesValue = schema["properties"];
-    if (!isRecord(propertiesValue)) {
-        output.info("    Parameters: none");
-        return;
+const nextActionsForAuthStatus = (payload) => {
+    if (!payload.loggedIn) {
+        return [
+            nextAction("login", "Authenticate", "ogment auth login", "No API key is configured locally; login is required.", "immediate"),
+        ];
+    }
+    return [
+        nextAction("discover_servers", "Discover servers", "ogment catalog", `Authenticated via ${payload.apiKeySource}; discover servers next.`, "after_auth"),
+    ];
+};
+const nextActionsForCatalogSummary = (payload, context, filters) => {
+    const actions = [];
+    const targetServer = payload.servers.find((server) => server.toolCount > 0);
+    if (targetServer !== undefined) {
+        actions.push(nextAction("inspect_tools", "Inspect tools", `ogment catalog tools ${targetServer.serverId}`, `${targetServer.serverId} has ${targetServer.toolCount} available tools.`, "if_tool_count_gt_0"));
     }
-    const entries = Object.entries(propertiesValue);
-    if (entries.length === 0) {
-        output.info("    Parameters: none");
-        return;
+    if (filters.serverId !== null) {
+        actions.push(nextAction("inspect_selected_server_tools", "Inspect selected server tools", `ogment catalog tools ${filters.serverId}`, `Inspect tools on ${filters.serverId} after narrowing catalog output.`, "if_server_selected"));
     }
-    output.info("    Parameters:");
-    for (const [name, propertyValue] of entries) {
-        if (!isRecord(propertyValue)) {
-            continue;
-        }
-        const property = propertyValue;
-        const type = formatSchemaType(property);
-        const requirement = required.has(name) ? "required" : "optional";
-        const description = typeof property.description === "string" && property.description.length > 0
-            ? ` - ${property.description}`
-            : "";
-        output.info(`      ${name} (${type}, ${requirement})${description}`);
+    if (context.nextCursor !== null) {
+        const limitFlag = context.limit === null ? "" : ` --limit ${context.limit}`;
+        actions.push(nextAction("next_catalog_page", "Load next page", `ogment catalog --cursor ${context.nextCursor}${limitFlag}`, `More servers are available after cursor ${context.nextCursor}.`, "if_more_servers"));
     }
+    return actions;
 };
-const renderSchemaBlock = (output, label, schema) => {
-    if (schema === undefined) {
-        output.info(`    ${label}: unavailable`);
-        return;
-    }
-    output.info(`    ${label}:`);
-    const lines = JSON.stringify(schema, null, 2).split("\n");
-    for (const line of lines) {
-        output.info(`      ${line}`);
-    }
+const nextActionsForCatalogTools = (payload) => {
+    const firstTool = payload.tools[0];
+    if (firstTool === undefined) {
+        return [];
+    }
+    return [
+        nextAction("inspect_tool", "Inspect tool details", `ogment catalog tool ${payload.server.serverId} ${firstTool.name}`, `Inspect schema for ${payload.server.serverId}/${firstTool.name} before invoking.`, "if_tools_available"),
+    ];
 };
-const renderServersListHuman = (output, servers) => {
-    if (servers.length === 0) {
-        output.info("No servers available.");
-        return;
-    }
-    for (const server of servers) {
-        const description = typeof server.description === "string" && server.description.length > 0
-            ? ` - ${server.description}`
-            : "";
-        output.info(`${server.path} (${server.orgSlug}) ${server.name}${description}`);
-    }
-    output.info("Inspect tools with: ogment servers <path>");
+const toInlineJsonArgument = (value) => {
+    const serialized = JSON.stringify(value);
+    const escaped = serialized.replaceAll("'", String.raw `'\''`);
+    return `'${escaped}'`;
 };
-const renderServerDetailsHuman = (output, payload) => {
-    output.info(`Server ${payload.server.name} (${payload.server.path}, ${payload.server.orgSlug})`);
-    if (payload.tools.length === 0) {
-        output.info("No tools available.");
-        return;
-    }
-    for (const tool of payload.tools) {
-        const description = typeof tool.description === "string" && tool.description.length > 0
-            ? ` - ${tool.description}`
-            : "";
-        output.info(`  ${tool.name}${description}`);
-        renderSchemaParameters(output, tool.inputSchema);
-        renderSchemaBlock(output, "Input schema", tool.inputSchema);
-        renderSchemaBlock(output, "Output schema", tool.outputSchema);
-    }
+const nextActionsForCatalogToolDetails = (payload, exampleInput) => {
+    const inputArgument = toInlineJsonArgument(exampleInput);
+    return [
+        nextAction("invoke_tool", "Invoke this tool", `ogment invoke ${payload.server.serverId}/${payload.name} --input ${inputArgument}`, `Invoke ${payload.server.serverId}/${payload.name} with schema-shaped input.`, "after_tool_inspection"),
+    ];
 };
-const formatLatency = (latencyMs) => {
-    if (latencyMs === null) {
-        return "n/a";
-    }
-    return `${latencyMs}ms`;
+const nextActionsForInvoke = (payload) => {
+    return [
+        nextAction("inspect_tool", "Inspect tool schema", `ogment catalog tool ${payload.serverId} ${payload.toolName}`, `Review ${payload.serverId}/${payload.toolName} schema for the next invocation.`, "after_invoke"),
+    ];
 };
-const renderInfoHuman = (output, payload) => {
-    output.info(`Diagnostics status: ${payload.summary.status.toUpperCase()}`);
-    output.info(`Generated at: ${payload.generatedAt}`);
-    output.info("");
-    output.info("Runtime:");
-    output.info(`  CLI version: ${payload.runtime.cliVersion}`);
-    output.info(`  Node version: ${payload.runtime.nodeVersion}`);
-    output.info(`  Platform: ${payload.runtime.platform} (${payload.runtime.processArch})`);
-    output.info(`  Environment: ${payload.runtime.executionEnvironment}`);
-    output.info("");
-    output.info("Config:");
-    output.info(`  Base URL: ${payload.config.baseUrl} (${payload.config.baseUrlSource})`);
-    output.info(`  Config dir: ${payload.config.configDir}`);
-    output.info(`  Credentials path: ${payload.config.credentialsPath}`);
-    output.info("");
-    output.info("Auth:");
-    output.info(`  API key source: ${payload.auth.apiKeySource}`);
-    output.info(`  API key present: ${payload.auth.apiKeyPresent ? "yes" : "no"}`);
-    output.info(`  API key fingerprint: ${payload.auth.apiKeyPreview ?? "none"}`);
-    output.info(`  Credentials file exists: ${payload.auth.credentialsFileExists ? "yes" : "no"}`);
-    if (payload.auth.credentialsFileLoadError !== null) {
-        output.info(`  Credentials load error: ${payload.auth.credentialsFileLoadError}`);
-    }
-    output.info("");
-    output.info("Remote:");
-    output.info(`  Ping endpoint: ${payload.remote.ping.endpoint}`);
-    output.info(`  Ping reachable: ${payload.remote.ping.reachable ? "yes" : "no"}`);
-    output.info(`  Ping latency: ${formatLatency(payload.remote.ping.latencyMs)}`);
-    if (payload.remote.ping.status !== null) {
-        output.info(`  Ping status: ${payload.remote.ping.status} ${payload.remote.ping.statusText ?? ""}`.trimEnd());
-    }
-    if (payload.remote.ping.error !== null) {
-        output.info(`  Ping error: ${payload.remote.ping.error}`);
-    }
-    output.info(`  Account check: ${payload.remote.account.status}`);
-    output.info(`  Account latency: ${formatLatency(payload.remote.account.latencyMs)}`);
-    if (payload.remote.account.serverCount !== null) {
-        output.info(`  Server count: ${payload.remote.account.serverCount}`);
-    }
-    if (payload.remote.account.orgCount !== null) {
-        output.info(`  Organization count: ${payload.remote.account.orgCount}`);
-    }
-    if (payload.remote.account.serverPaths.length > 0) {
-        output.info(`  Server paths: ${payload.remote.account.serverPaths.join(", ")}`);
-    }
-    if (payload.remote.account.message !== null) {
-        output.info(`  Account message: ${payload.remote.account.message}`);
-    }
-    output.info("");
-    output.info("Documentation:");
-    output.info(`  Config precedence: ${payload.documentation.configPrecedence.join(" -> ")}`);
-    output.info("  Quick commands:");
-    for (const command of payload.documentation.quickCommands) {
-        output.info(`    ${command}`);
-    }
-    if (payload.summary.issues.length > 0) {
-        output.info("");
-        output.info("Issues:");
-        for (const issue of payload.summary.issues) {
-            output.info(`  - ${issue}`);
-        }
-    }
-    if (payload.summary.nextActions.length > 0) {
-        output.info("");
-        output.info("Next actions:");
-        for (const action of payload.summary.nextActions) {
-            output.info(`  - ${action}`);
-        }
-    }
+const nextActionsForStatus = (payload) => {
+    if (!payload.auth.apiKeyPresent) {
+        return [
+            nextAction("login", "Authenticate", "ogment auth login", "Status detected no API key; authenticate first.", "immediate"),
+        ];
+    }
+    return [
+        nextAction("discover_servers", "Discover servers", "ogment catalog", `Connectivity is ${payload.summary.status}; discover available servers.`, "after_status"),
+    ];
 };
 const createProgram = (runtime) => {
     const program = new Command();
@@ -275,8 +269,8 @@ const createProgram = (runtime) => {
         .name(APP_NAME)
         .description(APP_DESCRIPTION)
         .version(VERSION)
-        .option("--apiKey <key>", "API key override")
-        .option("--json", "Output machine-readable JSON")
+        .option("--api-key <key>", "API key override")
+        .option("--human", "Render output for humans")
         .option("--quiet", "Suppress non-essential output")
         .option("--non-interactive", "Disable interactive behavior")
         .option("--yes", "Assume yes for any confirmation")
@@ -285,121 +279,381 @@ const createProgram = (runtime) => {
         runtime.output.configure(mapGlobalOutputOptions(options));
         runtime.context.apiKeyOverride = options.apiKey;
     });
-    program
+    const authCommand = program.command("auth").description("Authentication workflows");
+    const runLoginFlow = async (mode, apiKey) => {
+        const loginInvocation = (() => {
+            if (mode === "api_key") {
+                return {
+                    commandOptions: {
+                        apiKey: apiKey ?? "",
+                        mode: "apiKey",
+                    },
+                    invokedCommand: "ogment auth login --api-key <redacted>",
+                };
+            }
+            if (mode === "browser") {
+                return {
+                    commandOptions: {
+                        mode: "browser",
+                    },
+                    invokedCommand: "ogment auth login --browser",
+                };
+            }
+            const deviceCommand = "ogment auth login";
+            return {
+                commandOptions: {
+                    mode: "device",
+                    onPending: ({ userCode, verificationUri }) => {
+                        const pendingNextActions = [
+                            nextAction("check_login_status", "Check login status", "ogment auth status", `Approve ${userCode} at ${verificationUri}, then verify local auth state.`, "immediate"),
+                            nextAction("restart_device_login", "Restart login", "ogment auth login", `Restart login if code ${userCode} expires before approval.`, "if_expired"),
+                        ];
+                        runtime.output.success({
+                            state: "pending",
+                            userCode,
+                            verificationUri,
+                        }, {
+                            command: deviceCommand,
+                            entity: {
+                                mode,
+                                state: "pending",
+                                userCode,
+                                verificationUri,
+                            },
+                            humanMessage: `Open ${verificationUri} and enter code ${userCode}`,
+                            nextActions: pendingNextActions,
+                        });
+                    },
+                },
+                invokedCommand: deviceCommand,
+            };
+        })();
+        const { commandOptions, invokedCommand } = loginInvocation;
+        const result = await runAuthLoginCommand(runtime.context, commandOptions);
+        const data = ensureSuccess(result, runtime.output, {
+            command: invokedCommand,
+            entity: {
+                mode,
+            },
+        });
+        let humanMessage = `Logged in as ${data.agentName}.`;
+        if (data.alreadyLoggedIn) {
+            humanMessage = `Already logged in as ${data.agentName}.`;
+        }
+        else if (mode === "api_key") {
+            humanMessage = `Imported API key for ${data.agentName}.`;
+        }
+        runtime.output.success(data, {
+            command: invokedCommand,
+            entity: {
+                agentName: data.agentName,
+                alreadyLoggedIn: data.alreadyLoggedIn,
+                mode,
+            },
+            humanMessage,
+            nextActions: nextActionsForLogin(data, mode),
+        });
+    };
+    const loginWorkflowCommand = authCommand
         .command("login")
-        .description("Authenticate with Ogment")
-        .option("--device", "Use device flow explicitly")
-        .action(async (options) => {
-        const result = await runtime.context.services.auth.login({
-            device: options.device === true,
-            nonInteractive: runtime.output.nonInteractive,
-            onPending: ({ userCode, verificationUri }) => {
-                runtime.output.info(`Open ${verificationUri}`);
-                runtime.output.info(`Enter code: ${userCode}`);
+        .description("Authenticate with Ogment using device flow (recommended)")
+        .option("--browser", "Fallback: use browser callback flow");
+    loginWorkflowCommand.action(async (options, command) => {
+        const { apiKey } = asGlobalOptions(command);
+        if (options.browser === true && apiKey !== undefined) {
+            throw new ValidationError({
+                details: "--browser with --api-key",
+                message: "Use only one login mode: default device, --browser, or --api-key.",
+                suggestedCommand: "ogment auth login",
+            });
+        }
+        if (apiKey !== undefined) {
+            await runLoginFlow("api_key", apiKey);
+            return;
+        }
+        if (options.browser === true) {
+            await runLoginFlow("browser");
+            return;
+        }
+        await runLoginFlow("device");
+    });
+    authCommand
+        .command("status")
+        .description("Show local authentication status")
+        .action(async () => {
+        const command = "ogment auth status";
+        const result = await runAuthStatusCommand(runtime.context);
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+        });
+        runtime.output.success(data, {
+            command,
+            entity: {
+                apiKeySource: data.apiKeySource,
+                loggedIn: data.loggedIn,
             },
+            humanMessage: data.loggedIn
+                ? `Authenticated (${data.apiKeySource}).`
+                : "Not authenticated.",
+            nextActions: nextActionsForAuthStatus(data),
         });
-        const data = ensureSuccess(result, runtime.output);
-        const humanMessage = data.alreadyLoggedIn
-            ? `Already logged in as ${data.agentName}.`
-            : `Logged in as ${data.agentName}. ${AGENT_SUCCESS_HINT}`;
-        runtime.output.success(data, humanMessage);
     });
-    program
+    authCommand
         .command("logout")
         .description("Revoke token and delete local credentials")
         .action(async () => {
-        const result = await runtime.context.services.auth.logout();
-        const data = ensureSuccess(result, runtime.output);
-        let humanMessage = "Not logged in.";
+        const command = "ogment auth logout";
+        const result = await runAuthLogoutCommand(runtime.context);
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+        });
+        let message = "Not logged in.";
         if (data.localCredentialsDeleted) {
-            humanMessage = data.revoked
+            message = data.revoked
                 ? "Logged out and revoked API key."
-                : "Local credentials deleted. Server revocation not confirmed.";
+                : "Logged out locally. Server revocation not confirmed.";
         }
-        runtime.output.success(data, humanMessage);
+        runtime.output.success(data, {
+            command,
+            entity: {
+                localCredentialsDeleted: data.localCredentialsDeleted,
+                revoked: data.revoked,
+            },
+            humanMessage: message,
+            nextActions: [
+                nextAction("login", "Authenticate again", "ogment auth login", "Logout completed; authenticate again before further tool calls.", "after_logout"),
+            ],
+        });
     });
-    program
-        .command("servers [path]")
-        .description("List servers or inspect tools for one server")
-        .action(async (path) => {
-        const result = await runServersCommand(runtime.context, { path });
-        const data = ensureSuccess(result, runtime.output);
-        if (runtime.output.mode === "human") {
-            if ("servers" in data) {
-                renderServersListHuman(runtime.output, data.servers);
-                return;
-            }
-            renderServerDetailsHuman(runtime.output, data);
-            return;
+    const catalogCommand = program
+        .command("catalog")
+        .description("Discover servers and tools with progressive disclosure")
+        .option("--server <server-id>", "Filter to one server id")
+        .option("--cursor <cursor>", "Pagination cursor")
+        .option("--limit <limit>", "Maximum items to return");
+    catalogCommand.action(async (options) => {
+        const parsedLimit = typeof options.limit === "string" ? Number.parseInt(options.limit, 10) : undefined;
+        const command = [
+            "ogment catalog",
+            ...(options.server === undefined ? [] : [`--server ${options.server}`]),
+            ...(options.cursor === undefined ? [] : [`--cursor ${options.cursor}`]),
+            ...(parsedLimit === undefined || Number.isNaN(parsedLimit) ? [] : [`--limit ${parsedLimit}`]),
+        ].join(" ");
+        if (options.server !== undefined && options.cursor !== undefined) {
+            throw new ValidationError({
+                details: `--server ${options.server} with --cursor ${options.cursor}`,
+                message: "Invalid catalog options. --server cannot be combined with --cursor.",
+                suggestedCommand: `ogment catalog --server ${options.server}`,
+            });
+        }
+        if (options.limit !== undefined && (parsedLimit === undefined || Number.isNaN(parsedLimit))) {
+            throw new ValidationError({
+                details: options.limit,
+                message: "Invalid --limit value. Expected an integer.",
+                suggestedCommand: "ogment catalog --limit 20",
+            });
         }
-        runtime.output.success(data);
+        if (parsedLimit !== undefined && parsedLimit < 1) {
+            throw new ValidationError({
+                details: options.limit ?? String(parsedLimit),
+                message: "Invalid --limit value. Expected a positive integer.",
+                suggestedCommand: "ogment catalog --limit 20",
+            });
+        }
+        const result = await runCatalogCommand(runtime.context, {
+            cursor: options.cursor,
+            limit: parsedLimit,
+            serverId: options.server,
+        });
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+            entity: {
+                cursor: options.cursor ?? null,
+                limit: parsedLimit ?? null,
+                serverId: options.server ?? null,
+            },
+        });
+        const outputData = {
+            servers: data.servers,
+        };
+        runtime.output.success(outputData, {
+            command,
+            entity: {
+                cursor: options.cursor ?? null,
+                limit: parsedLimit ?? null,
+                serverCount: data.servers.length,
+                serverId: options.server ?? null,
+            },
+            humanMessage: data.nextCursor === null
+                ? `${data.servers.length} server(s) available.`
+                : `${data.servers.length} server(s) shown. More available with --cursor ${data.nextCursor}.`,
+            nextActions: nextActionsForCatalogSummary(outputData, {
+                limit: parsedLimit ?? null,
+                nextCursor: data.nextCursor,
+            }, {
+                serverId: options.server ?? null,
+            }),
+            pagination: {
+                nextCursor: data.nextCursor,
+            },
+        });
     });
-    program
-        .command("call <serverPath> <toolName> [argsJson]")
-        .description("Call a tool on an Ogment server")
-        .action(async (serverPath, toolName, argsJson) => {
-        const result = await runCallCommand(runtime.context, {
-            argsJson,
-            serverPath,
+    catalogCommand
+        .command("tools <serverId>")
+        .description("List tool summaries for one server")
+        .action(async (serverId) => {
+        const command = `ogment catalog tools ${serverId}`;
+        const result = await runCatalogToolsCommand(runtime.context, { serverId });
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+            entity: {
+                serverId,
+            },
+        });
+        runtime.output.success(data, {
+            command,
+            entity: {
+                serverId: data.server.serverId,
+                toolCount: data.tools.length,
+            },
+            humanMessage: `${data.tools.length} tool(s) available on ${data.server.serverId}.`,
+            nextActions: nextActionsForCatalogTools(data),
+        });
+    });
+    catalogCommand
+        .command("tool <serverId> <toolName>")
+        .description("Inspect full schema for one tool")
+        .option("--example", "Include a generated example input payload")
+        .action(async (serverId, toolName, options) => {
+        const command = [
+            "ogment catalog tool",
+            serverId,
             toolName,
+            ...(options.example === true ? ["--example"] : []),
+        ].join(" ");
+        const result = await runCatalogToolDetailsCommand(runtime.context, { serverId, toolName });
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+            entity: {
+                serverId,
+                toolName,
+            },
         });
-        const data = ensureSuccess(result, runtime.output);
-        if (runtime.output.mode === "human") {
-            runtime.output.json(data.result);
-            return;
+        const exampleInput = buildJsonSchemaExample(data.inputSchema);
+        const outputData = options.example === true ? { ...data, exampleInput } : data;
+        runtime.output.success(outputData, {
+            command,
+            entity: {
+                serverId: data.server.serverId,
+                toolName: data.name,
+            },
+            humanMessage: `Loaded schema for ${data.server.serverId}/${data.name}.`,
+            nextActions: nextActionsForCatalogToolDetails(data, exampleInput),
+        });
+    });
+    program
+        .command("invoke <target>")
+        .description("Invoke a tool using <server-id>/<tool-name>")
+        .option("--input <value>", "Input payload: inline JSON object, @path, or - for stdin")
+        .action(async (target, options) => {
+        let inputSource = "none";
+        let command = `ogment invoke ${target}`;
+        if (options.input !== undefined) {
+            if (options.input === "-") {
+                inputSource = "stdin";
+                command = `ogment invoke ${target} --input -`;
+            }
+            else if (options.input.startsWith("@")) {
+                inputSource = "file";
+                command = `ogment invoke ${target} --input ${options.input}`;
+            }
+            else {
+                inputSource = "inline_json";
+                command = `ogment invoke ${target} --input <json>`;
+            }
         }
-        runtime.output.success(data);
+        const result = await runInvokeCommand(runtime.context, {
+            input: options.input,
+            target,
+        });
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+            entity: {
+                inputSource,
+                target,
+            },
+        });
+        runtime.output.success(data, {
+            command,
+            entity: {
+                inputSource,
+                serverId: data.serverId,
+                toolName: data.toolName,
+            },
+            humanMessage: `Invoked ${data.serverId}/${data.toolName}.`,
+            nextActions: nextActionsForInvoke(data),
+        });
     });
     program
-        .command("info")
+        .command("status")
         .description("Show runtime configuration and connectivity diagnostics")
         .action(async () => {
+        const command = "ogment status";
         if (runtime.infoService === undefined) {
             throw new UnexpectedError({
                 message: "Info service is not configured",
             });
         }
-        const result = await runInfoCommand({
+        const result = await runStatusCommand({
             apiKeyOverride: runtime.context.apiKeyOverride,
         }, {
             infoService: runtime.infoService,
         });
-        const data = ensureSuccess(result, runtime.output);
-        if (runtime.output.mode === "human") {
-            renderInfoHuman(runtime.output, data);
-            return;
-        }
-        runtime.output.success(data);
-    });
-    program
-        .command("describe")
-        .description("Describe this CLI as a tool set for agent registration")
-        .action(() => {
-        const result = runDescribeCommand();
-        const data = ensureSuccess(result, runtime.output);
-        runtime.output.json(data);
+        const data = ensureSuccess(result, runtime.output, {
+            command,
+        });
+        runtime.output.success(data, {
+            command,
+            entity: {
+                summaryStatus: data.summary.status,
+            },
+            humanMessage: `Diagnostics status: ${data.summary.status.toUpperCase()}`,
+            nextActions: nextActionsForStatus(data),
+        });
     });
     program.action(() => {
-        if (runtime.output.mode === "json") {
-            runtime.output.success({
-                commands: ["login", "logout", "servers", "call", "info", "describe"],
-            });
-            return;
-        }
-        runtime.output.info(`${APP_NAME} v${VERSION}`);
-        runtime.output.info(APP_DESCRIPTION);
-        runtime.output.info("");
-        runtime.output.info("Commands:");
-        runtime.output.info("  login [--device]");
-        runtime.output.info("  servers [path]");
-        runtime.output.info("  call <serverPath> <toolName> [argsJson]");
-        runtime.output.info("  info");
-        runtime.output.info("  logout");
-        runtime.output.info("  describe");
+        runtime.output.success({
+            commands: [
+                "auth login",
+                "auth status",
+                "auth logout",
+                "catalog",
+                "catalog tools <server-id>",
+                "catalog tool <server-id> <tool-name>",
+                "invoke <server-id>/<tool-name>",
+                "status",
+            ],
+        }, {
+            command: "ogment",
+            entity: null,
+            humanMessage: "Select a command to continue.",
+            nextActions: [
+                nextAction("login", "Authenticate", "ogment auth login", "Authenticate first so catalog and invoke commands can run.", "immediate"),
+                nextAction("catalog", "Discover servers", "ogment catalog", "List accessible servers and tool counts.", "after_auth"),
+            ],
+        });
     });
     return program;
 };
 const normalizeCommanderError = (error) => {
+    if (error instanceof AuthError ||
+        error instanceof ContractMismatchError ||
+        error instanceof NotFoundError ||
+        error instanceof RemoteRequestError ||
+        error instanceof UnexpectedError ||
+        error instanceof ValidationError) {
+        return error;
+    }
     if (error instanceof CommanderError) {
         return new ValidationError({
             details: error.message,
@@ -423,6 +677,13 @@ const normalizeCliArgv = (argv) => {
     }
     return argv;
 };
+const commandFromArgv = (argv) => {
+    const normalized = normalizeCliArgv(argv);
+    if (normalized.length === 0) {
+        return "ogment";
+    }
+    return `ogment ${normalized.join(" ")}`;
+};
 export const runCli = async (argv = process.argv.slice(2), runtime = createRuntime()) => {
     const program = createProgram(runtime);
     try {
@@ -437,7 +698,11 @@ export const runCli = async (argv = process.argv.slice(2), runtime = createRunti
             return EXIT_CODE.success;
         }
         const normalized = normalizeCommanderError(error);
-        runtime.output.error(normalized);
+        runtime.output.error(normalized, {
+            command: commandFromArgv(argv),
+            entity: null,
+            nextActions: nextActionsForError(normalized),
+        });
         return exitCodeForError(normalized);
     }
 };