@kynetic-ai/spec 0.1.2 → 0.4.0

package/dist/cli/commands/doctor.js

@@ -0,0 +1,152 @@
+/**
+ * kspec doctor command - unified health check
+ *
+ * AC: @doctor-command
+ */
+import chalk from "chalk";
+import { output, isJsonMode } from "../output.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { getDoctorReport, } from "../../parser/doctor.js";
+/**
+ * Register the doctor command
+ */
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Check kspec health (shadow branch, setup, daemon)")
+        .option("--json", "Output as JSON")
+        .action(async () => {
+        try {
+            const report = await getDoctorReport(process.cwd());
+            if (isJsonMode()) {
+                // AC: @doctor-command ac-json-output
+                output(report);
+            }
+            else {
+                formatDoctorReport(report);
+            }
+            // AC: @doctor-command ac-exit-zero, ac-exit-one
+            // AC: @trait-semantic-exit-codes ac-1, ac-2
+            // Exit 0 if healthy (no errors, warnings ok), exit 1 if any errors
+            if (report.overall.healthy) {
+                process.exit(EXIT_CODES.SUCCESS);
+            }
+            else {
+                process.exit(EXIT_CODES.ERROR);
+            }
+        }
+        catch (err) {
+            if (isJsonMode()) {
+                // AC: @trait-json-output ac-3
+                output({ error: err instanceof Error ? err.message : String(err) });
+            }
+            else {
+                console.error(chalk.red(`Error: ${err instanceof Error ? err.message : String(err)}`));
+            }
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+/**
+ * Get color for severity level
+ */
+function getSeverityColor(severity) {
+    switch (severity) {
+        case "ok":
+            return chalk.green;
+        case "warning":
+            return chalk.yellow;
+        case "error":
+            return chalk.red;
+    }
+}
+/**
+ * Get icon for severity level
+ */
+function getSeverityIcon(severity) {
+    switch (severity) {
+        case "ok":
+            return "✓";
+        case "warning":
+            return "⚠";
+        case "error":
+            return "✗";
+    }
+}
+/**
+ * Format a single check result
+ */
+function formatCheck(check) {
+    const color = getSeverityColor(check.severity);
+    const icon = getSeverityIcon(check.severity);
+    console.log(`  ${color(icon)} ${check.message}`);
+    if (check.guidance) {
+        console.log(chalk.gray(`    ${check.guidance}`));
+    }
+}
+/**
+ * Format the doctor report for human-readable output
+ */
+function formatDoctorReport(report) {
+    console.log(chalk.bold("\n=== kspec doctor ===\n"));
+    // Shadow section
+    // AC: @doctor-command ac-shadow-healthy, ac-not-initialized
+    console.log(chalk.bold.blue("Shadow Branch"));
+    if (report.shadow.checks.length === 0) {
+        console.log(chalk.gray("  No checks performed"));
+    }
+    else {
+        for (const check of report.shadow.checks) {
+            formatCheck(check);
+        }
+    }
+    console.log();
+    // Setup section (only if shadow is initialized)
+    // AC: @doctor-command ac-setup-agent-hooks, ac-setup-skills-agents-md, ac-partial-init
+    if (report.shadow.initialized) {
+        console.log(chalk.bold.blue("Setup"));
+        if (report.setup.checks.length === 0) {
+            console.log(chalk.gray("  No checks performed"));
+        }
+        else {
+            for (const check of report.setup.checks) {
+                formatCheck(check);
+            }
+        }
+        console.log();
+        // Daemon section
+        // AC: @doctor-command ac-daemon-running, ac-daemon-not-running, ac-daemon-unreachable
+        console.log(chalk.bold.blue("Daemon"));
+        if (report.daemon.checks.length === 0) {
+            console.log(chalk.gray("  No checks performed"));
+        }
+        else {
+            for (const check of report.daemon.checks) {
+                formatCheck(check);
+            }
+        }
+        console.log();
+    }
+    // Overall verdict
+    // AC: @doctor-command ac-overall-verdict
+    console.log(chalk.bold("─".repeat(40)));
+    if (report.overall.healthy) {
+        console.log(chalk.green.bold("✓ Healthy"));
+        if (report.overall.warningCount > 0) {
+            console.log(chalk.yellow(`  ${report.overall.warningCount} warning(s)`));
+        }
+    }
+    else {
+        console.log(chalk.red.bold("✗ Issues found"));
+        const parts = [];
+        if (report.overall.errorCount > 0) {
+            parts.push(chalk.red(`${report.overall.errorCount} error(s)`));
+        }
+        if (report.overall.warningCount > 0) {
+            parts.push(chalk.yellow(`${report.overall.warningCount} warning(s)`));
+        }
+        console.log(`  ${parts.join(", ")}`);
+    }
+    console.log();
+}
+//# sourceMappingURL=doctor.js.map

package/dist/cli/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/export.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Export Command
+ *
+ * Exports kspec data to JSON or HTML format for static site hosting.
+ * AC: @gh-pages-export ac-1, ac-2, ac-3, ac-4, ac-5, ac-6, ac-7
+ */
+import type { Command } from "commander";
+/**
+ * Register the export command.
+ */
+export declare function registerExportCommand(program: Command): void;
+//# sourceMappingURL=export.d.ts.map

package/dist/cli/commands/export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/export.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUzC;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4I5D"}

package/dist/cli/commands/export.js

@@ -0,0 +1,134 @@
+/**
+ * Export Command
+ *
+ * Exports kspec data to JSON or HTML format for static site hosting.
+ * AC: @gh-pages-export ac-1, ac-2, ac-3, ac-4, ac-5, ac-6, ac-7
+ */
+import * as fs from "node:fs/promises";
+import chalk from "chalk";
+import { calculateExportStats, formatBytes, generateHtmlExport, generateJsonSnapshot, } from "../../export/index.js";
+import { EXIT_CODES } from "../exit-codes.js";
+import { error, info, output, success } from "../output.js";
+/**
+ * Register the export command.
+ */
+export function registerExportCommand(program) {
+    program
+        .command("export")
+        .description("Export kspec data to JSON or HTML format")
+        .requiredOption("--format <format>", "Output format (json or html)", "json")
+        .option("-o, --output <path>", "Output file path (defaults to stdout for JSON)")
+        .option("--include-validation", "Include validation results in the export", false)
+        .option("--dry-run", "Show what would be exported without writing files", false)
+        .action(async (options) => {
+        try {
+            // Validate format
+            // AC: @gh-pages-export ac-1, ac-6
+            if (options.format !== "json" && options.format !== "html") {
+                error(`Invalid format: ${options.format}. Must be 'json' or 'html'.`);
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // HTML format requires output file
+            // AC: @gh-pages-export ac-6
+            if (options.format === "html" && !options.output) {
+                error("HTML format requires --output <path>");
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // Only show progress when not outputting JSON to stdout (keep stdout clean for piping)
+            const jsonToStdout = options.format === "json" && !options.output && !options.dryRun;
+            if (!jsonToStdout) {
+                info("Generating snapshot...");
+            }
+            // Generate the snapshot
+            // AC: @gh-pages-export ac-1, ac-2, ac-3, ac-4, ac-5
+            const snapshot = await generateJsonSnapshot(options.includeValidation);
+            // AC: @trait-dry-run ac-1, ac-2, ac-3 - Show preview without writing
+            if (options.dryRun) {
+                const stats = calculateExportStats(snapshot);
+                // AC: @trait-dry-run ac-3 - Clear indication this is a preview
+                // AC: @gh-pages-export ac-7
+                const dryRunOutput = {
+                    dry_run: true,
+                    format: options.format,
+                    output: options.output || "(stdout)",
+                    stats: {
+                        tasks: stats.taskCount,
+                        items: stats.itemCount,
+                        inbox: stats.inboxCount,
+                        observations: stats.observationCount,
+                        agents: stats.agentCount,
+                        workflows: stats.workflowCount,
+                        conventions: stats.conventionCount,
+                        estimated_size: formatBytes(stats.estimatedSizeBytes),
+                    },
+                    validation_included: options.includeValidation,
+                    ...(options.includeValidation && snapshot.validation
+                        ? {
+                            validation_summary: {
+                                valid: snapshot.validation.valid,
+                                errors: snapshot.validation.errorCount,
+                                warnings: snapshot.validation.warningCount,
+                            },
+                        }
+                        : {}),
+                };
+                output(dryRunOutput, () => {
+                    console.log(chalk.cyan("\n=== Dry Run - No files will be written ===\n"));
+                    console.log(chalk.gray("Format:"), options.format);
+                    console.log(chalk.gray("Output:"), options.output || "(stdout)");
+                    console.log();
+                    console.log(chalk.gray("─".repeat(40)));
+                    console.log(chalk.bold("Export Statistics:"));
+                    console.log(chalk.gray("─".repeat(40)));
+                    console.log(`  Tasks:        ${stats.taskCount}`);
+                    console.log(`  Items:        ${stats.itemCount}`);
+                    console.log(`  Inbox:        ${stats.inboxCount}`);
+                    console.log(`  Observations: ${stats.observationCount}`);
+                    console.log(`  Agents:       ${stats.agentCount}`);
+                    console.log(`  Workflows:    ${stats.workflowCount}`);
+                    console.log(`  Conventions:  ${stats.conventionCount}`);
+                    console.log();
+                    console.log(`  Estimated size: ${chalk.cyan(formatBytes(stats.estimatedSizeBytes))}`);
+                    if (options.includeValidation && snapshot.validation) {
+                        console.log();
+                        console.log(chalk.gray("─".repeat(40)));
+                        console.log(chalk.bold("Validation:"));
+                        console.log(chalk.gray("─".repeat(40)));
+                        const validIcon = snapshot.validation.valid
+                            ? chalk.green("✓")
+                            : chalk.red("✗");
+                        console.log(`  Status: ${validIcon} ${snapshot.validation.valid ? "Valid" : "Invalid"}`);
+                        console.log(`  Errors: ${snapshot.validation.errorCount}`);
+                        console.log(`  Warnings: ${snapshot.validation.warningCount}`);
+                    }
+                    console.log();
+                });
+                return;
+            }
+            // Generate output based on format
+            let content;
+            if (options.format === "json") {
+                // AC: @gh-pages-export ac-1
+                content = JSON.stringify(snapshot, null, 2);
+            }
+            else {
+                // AC: @gh-pages-export ac-6
+                content = generateHtmlExport(snapshot);
+            }
+            // Write or output
+            if (options.output) {
+                await fs.writeFile(options.output, content, "utf-8");
+                success(`Exported to ${options.output}`);
+            }
+            else {
+                // JSON to stdout (no success message to keep output clean)
+                console.log(content);
+            }
+        }
+        catch (err) {
+            error("Export failed", err);
+            process.exit(EXIT_CODES.ERROR);
+        }
+    });
+}
+//# sourceMappingURL=export.js.map

package/dist/cli/commands/export.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export.js","sourceRoot":"","sources":["../../../src/cli/commands/export.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/help.d.ts

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import type { Command } from "commander";
 /**
  * Register the help command
  */

package/dist/cli/commands/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoNpC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyB1D"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/help.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAkVzC;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8D1D"}

package/dist/cli/commands/help.js

@@ -1,9 +1,10 @@
-import chalk from 'chalk';
-import { program } from '../index.js';
-import { extractCommandTree, findCommand, flattenCommandTree, formatCommandUsage, } from '../introspection.js';
-import { helpContent } from '../help/content.js';
-import { output } from '../output.js';
-import { EXIT_CODES } from '../exit-codes.js';
+// AC: @auto-cli-docs ac-2, ac-3, ac-4, ac-5
+import chalk from "chalk";
+import { EXIT_CODES, EXIT_CODE_METADATA } from "../exit-codes.js";
+import { helpContent } from "../help/content.js";
+import { program } from "../index.js";
+import { extractCommandTree, findCommand, flattenCommandTree, formatCommandUsage, } from "../introspection.js";
+import { output, setJsonMode, isJsonMode } from "../output.js";
 /**
  * Show help for a specific topic (command or concept)
  */
@@ -11,7 +12,7 @@ function showTopic(topic) {
     // Extract command tree from program
     const tree = extractCommandTree(program);
     // Try to find as a command first
-    const command = findCommand(tree, topic.split(' '));
+    const command = findCommand(tree, topic.split(" "));
     if (command) {
         showCommandHelp(command);
         return;
@@ -24,7 +25,7 @@ function showTopic(topic) {
     }
     // Not found
     console.log(chalk.red(`Unknown topic: ${topic}`));
-    console.log(`\nAvailable topics: ${getAllTopics(tree).join(', ')}`);
+    console.log(`\nAvailable topics: ${getAllTopics(tree).join(", ")}`);
     console.log(`\nRun 'kspec help' to see all topics.`);
     process.exit(EXIT_CODES.ERROR);
 }
@@ -36,13 +37,13 @@ function showCommandHelp(command) {
     // Title: use content title, or command name
     const title = content?.title || `${command.name} - ${command.description}`;
     console.log(chalk.bold.cyan(title));
-    console.log(chalk.gray('─'.repeat(40)));
+    console.log(chalk.gray("─".repeat(40)));
     // Usage
-    console.log(chalk.bold('\nUsage:'));
+    console.log(chalk.bold("\nUsage:"));
     console.log(`  ${formatCommandUsage(command)}`);
     // Subcommands (auto-generated from Commander)
     if (command.subcommands.length > 0) {
-        console.log(chalk.bold('\nCommands:'));
+        console.log(chalk.bold("\nCommands:"));
         for (const sub of command.subcommands) {
             const nameCol = sub.name.padEnd(20);
             console.log(`  ${chalk.green(nameCol)} ${sub.description}`);
@@ -50,7 +51,7 @@ function showCommandHelp(command) {
     }
     // Options (auto-generated from Commander)
     if (command.options.length > 0) {
-        console.log(chalk.bold('\nOptions:'));
+        console.log(chalk.bold("\nOptions:"));
         for (const opt of command.options) {
             // Format flags column
             const flagsCol = opt.flags.padEnd(30);
@@ -60,17 +61,17 @@ function showCommandHelp(command) {
     // Conceptual content (curated)
     if (content) {
         if (content.concept.trim()) {
-            console.log(chalk.bold('\nDetails:'));
+            console.log(chalk.bold("\nDetails:"));
             console.log(content.concept.trim());
         }
         if (content.examples && content.examples.length > 0) {
-            console.log(chalk.bold('\nExamples:'));
+            console.log(chalk.bold("\nExamples:"));
             for (const example of content.examples) {
                 console.log(chalk.green(`  ${example}`));
             }
         }
         if (content.seeAlso && content.seeAlso.length > 0) {
-            console.log(chalk.gray(`\nSee also: ${content.seeAlso.map((t) => `kspec help ${t}`).join(', ')}`));
+            console.log(chalk.gray(`\nSee also: ${content.seeAlso.map((t) => `kspec help ${t}`).join(", ")}`));
         }
     }
 }
@@ -80,16 +81,16 @@ function showCommandHelp(command) {
 function showConceptHelp(topic, content) {
     const title = content.title || topic;
     console.log(chalk.bold.cyan(title));
-    console.log(chalk.gray('─'.repeat(40)));
+    console.log(chalk.gray("─".repeat(40)));
     console.log(content.concept.trim());
     if (content.examples && content.examples.length > 0) {
-        console.log(chalk.bold('\nExamples:'));
+        console.log(chalk.bold("\nExamples:"));
         for (const example of content.examples) {
             console.log(chalk.green(`  ${example}`));
         }
     }
     if (content.seeAlso && content.seeAlso.length > 0) {
-        console.log(chalk.gray(`\nSee also: ${content.seeAlso.map((t) => `kspec help ${t}`).join(', ')}`));
+        console.log(chalk.gray(`\nSee also: ${content.seeAlso.map((t) => `kspec help ${t}`).join(", ")}`));
     }
 }
 /**
@@ -97,7 +98,7 @@ function showConceptHelp(topic, content) {
  */
 function getAllTopics(tree) {
     const commands = flattenCommandTree(tree)
-        .filter((cmd) => cmd.name !== 'kspec') // Skip root
+        .filter((cmd) => cmd.name !== "kspec") // Skip root
         .map((cmd) => cmd.name);
     const concepts = Object.keys(helpContent).filter((key) => !commands.includes(key));
     return [...new Set([...commands, ...concepts])];
@@ -107,17 +108,17 @@ function getAllTopics(tree) {
  */
 function showTopicList() {
     const tree = extractCommandTree(program);
-    console.log(chalk.bold.cyan('kspec help'));
-    console.log(chalk.gray('─'.repeat(40)));
-    console.log('\nExtended help for kspec commands and concepts.\n');
+    console.log(chalk.bold.cyan("kspec help"));
+    console.log(chalk.gray("─".repeat(40)));
+    console.log("\nExtended help for kspec commands and concepts.\n");
     // Show top-level commands (auto-generated)
-    console.log(chalk.bold('Commands:'));
+    console.log(chalk.bold("Commands:"));
     for (const cmd of tree.subcommands) {
         const nameCol = cmd.name.padEnd(12);
         console.log(`  ${chalk.green(nameCol)} ${cmd.description}`);
     }
     // Show concept topics (curated)
-    console.log(chalk.bold('\nConcepts:'));
+    console.log(chalk.bold("\nConcepts:"));
     const conceptTopics = Object.keys(helpContent).filter((key) => {
         // Concepts are topics that don't match command names
         return !tree.subcommands.some((cmd) => cmd.name === key);
@@ -128,25 +129,25 @@ function showTopicList() {
         const nameCol = topic.padEnd(12);
         console.log(`  ${chalk.green(nameCol)} ${title}`);
     }
-    console.log(chalk.gray('\nUsage: kspec help <topic>'));
-    console.log(chalk.gray('       kspec help --all        (full reference)'));
-    console.log(chalk.gray('       kspec help --json       (structured output)'));
+    console.log(chalk.gray("\nUsage: kspec help <topic>"));
+    console.log(chalk.gray("       kspec help --all        (full reference)"));
+    console.log(chalk.gray("       kspec help --json       (structured output)"));
 }
 /**
  * Show full reference (all commands with options)
  */
 function showFullReference() {
     const tree = extractCommandTree(program);
-    const allCommands = flattenCommandTree(tree).filter((cmd) => cmd.name !== 'kspec');
-    console.log(chalk.bold.cyan('kspec - Full Command Reference'));
-    console.log(chalk.gray('─'.repeat(60)));
+    const allCommands = flattenCommandTree(tree).filter((cmd) => cmd.name !== "kspec");
+    console.log(chalk.bold.cyan("kspec - Full Command Reference"));
+    console.log(chalk.gray("─".repeat(60)));
     for (const cmd of allCommands) {
         console.log(chalk.bold(`\n${formatCommandUsage(cmd)}`));
         if (cmd.description) {
             console.log(`  ${cmd.description}`);
         }
         if (cmd.options.length > 0) {
-            console.log(chalk.gray('  Options:'));
+            console.log(chalk.gray("  Options:"));
             for (const opt of cmd.options) {
                 console.log(chalk.gray(`    ${opt.flags.padEnd(30)} ${opt.description}`));
             }
@@ -165,18 +166,143 @@ function showJson() {
     };
     output(data);
 }
+/**
+ * Show exit codes documentation
+ * AC: @cli-schema-introspection ac-2
+ */
+function showExitCodes() {
+    console.log(chalk.bold.cyan("kspec - Exit Codes"));
+    console.log(chalk.gray("─".repeat(60)));
+    console.log("\nExit codes returned by kspec commands:\n");
+    for (const exitCode of EXIT_CODE_METADATA) {
+        console.log(chalk.bold(`${exitCode.code} - ${exitCode.name}`));
+        console.log(`  ${exitCode.description}`);
+        console.log(chalk.gray(`  Commands: ${exitCode.commands}`));
+        console.log();
+    }
+}
+/**
+ * Output exit codes as JSON
+ * AC: @cli-schema-introspection ac-3
+ */
+function showExitCodesJson() {
+    const exitCodesData = EXIT_CODE_METADATA.map((ec) => ({
+        code: ec.code,
+        name: ec.name,
+        description: ec.description,
+        commands: ec.commands,
+    }));
+    output(exitCodesData);
+}
+/**
+ * Generate JSON Schema for a command
+ * AC: @cli-schema-introspection ac-4
+ */
+function showCommandJsonSchema(topic) {
+    const tree = extractCommandTree(program);
+    const command = findCommand(tree, topic.split(" "));
+    if (!command) {
+        console.error(chalk.red(`Unknown command: ${topic}`));
+        process.exit(EXIT_CODES.NOT_FOUND);
+    }
+    // Build JSON Schema object
+    const schema = {
+        $schema: "http://json-schema.org/draft-07/schema#",
+        type: "object",
+        title: `${command.name} command options`,
+        description: command.description,
+        properties: {},
+        required: [],
+    };
+    const properties = {};
+    const required = [];
+    // Add arguments as properties
+    for (const arg of command.arguments) {
+        const propName = arg.name;
+        properties[propName] = {
+            type: arg.variadic ? "array" : "string",
+            description: arg.description,
+        };
+        if (arg.variadic) {
+            properties[propName].items = {
+                type: "string",
+            };
+        }
+        if (arg.required) {
+            required.push(propName);
+        }
+    }
+    // Add options as properties
+    for (const opt of command.options) {
+        // Extract option name from flags (e.g., "-f, --force" -> "force")
+        const flagMatch = opt.flags.match(/--([a-zA-Z0-9-]+)/);
+        if (!flagMatch)
+            continue;
+        const propName = flagMatch[1];
+        // Determine type from flags
+        let type = "boolean";
+        if (opt.flags.includes("<")) {
+            type = "string";
+        }
+        else if (opt.flags.includes("[")) {
+            type = "string";
+        }
+        const propSchema = {
+            type,
+            description: opt.description,
+        };
+        if (opt.defaultValue !== undefined) {
+            propSchema.default = opt.defaultValue;
+        }
+        properties[propName] = propSchema;
+        if (opt.required) {
+            required.push(propName);
+        }
+    }
+    schema.properties = properties;
+    if (required.length > 0) {
+        schema.required = required;
+    }
+    output(schema);
+}
 /**
  * Register the help command
  */
 export function registerHelpCommand(program) {
     program
-        .command('help [topic]')
-        .description('Extended help for commands and concepts')
-        .option('--all', 'Show full command reference')
-        .option('--json', 'Output as JSON')
+        .command("help [topic]")
+        .description("Extended help for commands and concepts")
+        .option("--all", "Show full command reference")
+        .option("--json", "Output as JSON")
+        .option("--exit-codes", "Show exit code documentation")
+        .option("--json-schema", "Output JSON Schema for command (use with topic)")
         .action((topic, options) => {
-        // Handle flags
-        if (options?.json) {
+        // Handle exit codes flag
+        if (options?.exitCodes) {
+            // AC: @cli-schema-introspection ac-2, ac-3
+            // Note: globalJsonMode is already set by preAction hook if --json flag present
+            if (isJsonMode()) {
+                showExitCodesJson();
+            }
+            else {
+                showExitCodes();
+            }
+            return;
+        }
+        // Handle JSON schema flag
+        if (options?.jsonSchema) {
+            if (!topic) {
+                console.error(chalk.red("Error: --json-schema requires a command topic"));
+                process.exit(EXIT_CODES.USAGE_ERROR);
+            }
+            // AC: @cli-schema-introspection ac-4
+            setJsonMode(true);
+            showCommandJsonSchema(topic);
+            return;
+        }
+        // AC: @cli-schema-introspection ac-1, ac-5
+        // If --json flag is present (globalJsonMode set by preAction hook), show JSON
+        if (isJsonMode()) {
             showJson();
             return;
         }