@skhema/cli 0.5.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ SKHEMA_API_KEY=sk_live_… npx @skhema/cli init --yes --json
   future commands (never overwriting a different stored key without `--force`).
 - **Installs skills** into every detected agent platform (idempotent — reruns
   report `unchanged`).
-- **Registers the MCP server** (`https://mcp-server.skhema.com/mcp`, Streamable
+- **Registers the MCP server** (`https://mcp.skhema.com/mcp`, Streamable
   HTTP) in detected clients by safely merging a dedicated config file and writing
   a `.bak` backup — **or printing copy-paste instructions** when a client's config
   isn't cleanly writable. `--yes` registers non-interactively; without it, `init`

package/dist/cli.js

@@ -1,8 +1,9 @@
+import { CommanderError } from 'commander';
 import { createRequire } from 'module';
 import { isApprovedContributor } from './lib/auth/entitlements.js';
 import { getStoredCredentials } from './lib/auth/token-store.js';
 import { outputError } from './lib/output.js';
-import { buildProgram } from './program.js';
+import { buildProgram, resolveCommanderExitCode } from './program.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
 const program = buildProgram(pkg.version);
@@ -35,6 +36,17 @@ async function main() {
             }
         }
     }
-    await program.parseAsync();
+    try {
+        await program.parseAsync();
+    }
+    catch (err) {
+        // With exitOverride set, commander throws instead of exiting for every
+        // parser-level outcome (usage error, --help, --version). Map those onto the
+        // ExitCode contract; anything else is a real failure and should propagate.
+        if (err instanceof CommanderError) {
+            process.exit(resolveCommanderExitCode(err));
+        }
+        throw err;
+    }
 }
 main();

package/dist/commands/element.d.ts

@@ -1,7 +1,8 @@
 import { Command } from 'commander';
 /**
- * Element commands — the strategic building blocks in a workspace. All are
- * workspace-scoped via `--workspace` (falling back to the default workspace).
+ * Element commands — the strategic building blocks in a workspace. Most are
+ * workspace-scoped via `--workspace` (falling back to the default workspace);
+ * `types` is a local, network-free lookup of the method vocabulary.
  */
 export declare function registerElementCommands(program: Command): void;
 //# sourceMappingURL=element.d.ts.map

package/dist/commands/element.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../src/commands/element.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAkBnC;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA8S9D"}
+{"version":3,"file":"element.d.ts","sourceRoot":"","sources":["../../src/commands/element.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AA2EnC;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2T9D"}

package/dist/commands/element.js

@@ -1,3 +1,4 @@
+import { getElementDefinition, getElementsForComponent, SKHEMA_MAPPING, } from '@skhema/method';
 import chalk from 'chalk';
 import { resolveClient } from '../lib/api/client.js';
 import { asRecord, buildBody, coerceList, readPayloadFile, resolveWorkspaceId, } from '../lib/api/command-helpers.js';
@@ -8,9 +9,47 @@ function summarize(content) {
     const text = typeof content === 'string' ? content : '';
     return text.length > 48 ? `${text.slice(0, 47)}…` : text || '—';
 }
+/** Human-friendly rendering of an expected mood (e.g. `noun_phrase` → `noun phrase`). */
+function formatMood(mood) {
+    return mood ? mood.replace(/_/g, ' ') : '—';
+}
+/**
+ * The component → allowed-element-type mapping, read straight from
+ * `@skhema/method` (SKHEMA_MAPPING) in canonical component-flow order. This is
+ * the same vocabulary the backend enforces, so agents can discover the
+ * allow-list locally instead of probing it via `bad_request` errors.
+ */
+function buildElementTypeMapping() {
+    return SKHEMA_MAPPING.componentFlow.map((component) => ({
+        component: component.value,
+        label: component.label,
+        acronym: component.acronym,
+        elementTypes: getElementsForComponent(component.value).map((element) => ({
+            type: element.value,
+            label: element.label,
+            acronym: element.acronym,
+            mood: getElementDefinition(element.value)?.expectedMood ?? null,
+        })),
+    }));
+}
+/** Render the mapping as a per-component section with an element-type table. */
+function renderElementTypeMapping(mapping) {
+    logHeader('Element types by component');
+    for (const component of mapping) {
+        log('');
+        log(chalk.bold(`${component.label} ${chalk.dim(`(${component.acronym})`)}`));
+        logTable(['acronym', 'type', 'label', 'mood'], component.elementTypes.map((element) => [
+            element.acronym,
+            element.type,
+            element.label,
+            formatMood(element.mood),
+        ]));
+    }
+}
 /**
- * Element commands — the strategic building blocks in a workspace. All are
- * workspace-scoped via `--workspace` (falling back to the default workspace).
+ * Element commands — the strategic building blocks in a workspace. Most are
+ * workspace-scoped via `--workspace` (falling back to the default workspace);
+ * `types` is a local, network-free lookup of the method vocabulary.
  */
 export function registerElementCommands(program) {
     const element = program.command('element').description('Element commands');
@@ -200,4 +239,15 @@ export function registerElementCommands(program) {
             return data;
         });
     });
+    element
+        .command('types')
+        .description('List element types allowed in each component (method vocabulary, no network)')
+        .action(async () => {
+        await runCommand('element types', async () => {
+            const mapping = buildElementTypeMapping();
+            if (!getGlobalOptions().json)
+                renderElementTypeMapping(mapping);
+            return { components: mapping };
+        });
+    });
 }

package/dist/commands/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAenC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgO7D"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/commands/skills.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAwCnC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA6U7D"}

package/dist/commands/skills.js

@@ -1,10 +1,28 @@
+import readline from 'readline';
 import chalk from 'chalk';
 import ora from 'ora';
 import { getGlobalOptions, log, logHeader, logTable, outputError, outputSuccess, } from '../lib/output.js';
 import { listBundledSkills, readBundledSkill } from '../lib/skills/bundled.js';
-import { installSkills, updateSkills } from '../lib/skills/installer.js';
+import { installSkills, pruneSkills, updateSkills, } from '../lib/skills/installer.js';
 import { readLock } from '../lib/skills/lock.js';
 import { detectPlatforms } from '../lib/skills/platform-detect.js';
+function interactiveTerminal() {
+    return (Boolean(process.stdin.isTTY && process.stdout.isTTY) &&
+        !getGlobalOptions().json);
+}
+async function confirm(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const answer = await new Promise((resolve) => {
+        rl.question(`${question} [y/N]: `, (value) => {
+            rl.close();
+            resolve(value.trim().toLowerCase());
+        });
+    });
+    return answer === 'y' || answer === 'yes';
+}
 export function registerSkillsCommands(program) {
     const skills = program.command('skills').description('AI skills management');
     skills
@@ -171,4 +189,83 @@ export function registerSkillsCommands(program) {
             process.exit(1);
         }
     });
+    skills
+        .command('prune')
+        .description('Remove installed skills that are no longer bundled with this CLI (retired or renamed)')
+        .option('--platform <id>', 'Prune a specific platform only')
+        .option('--yes', 'Actually remove; without it, only preview what would go')
+        .action(async (options) => {
+        const opts = getGlobalOptions();
+        const spinner = opts.json || opts.quiet
+            ? null
+            : ora('Detecting agent platforms...').start();
+        try {
+            const platforms = detectPlatforms().filter((p) => p.detected);
+            const targets = options.platform
+                ? platforms.filter((p) => p.id === options.platform)
+                : platforms;
+            if (targets.length === 0) {
+                spinner?.warn(options.platform
+                    ? `Platform "${options.platform}" not detected.`
+                    : 'No agent platforms detected.');
+                if (opts.json)
+                    outputSuccess([], 'skills prune');
+                return;
+            }
+            // Preview first — this never writes.
+            const preview = await pruneSkills(targets, { apply: false });
+            if (preview.length === 0) {
+                spinner?.succeed('No retired skills to prune. Everything is current.');
+                if (opts.json)
+                    outputSuccess([], 'skills prune');
+                return;
+            }
+            spinner?.info(`Found ${preview.length} retired skill install(s) across ${new Set(preview.map((r) => r.platform.id)).size} platform(s).`);
+            // Mutate only with --yes, or after an interactive confirmation.
+            let apply = Boolean(options.yes);
+            if (!apply) {
+                if (interactiveTerminal()) {
+                    logHeader('Would remove');
+                    logTable(['Platform', 'Skill', 'Path'], preview.map((r) => [
+                        r.platform.name,
+                        r.skill,
+                        chalk.dim(r.targetPath),
+                    ]));
+                    apply = await confirm('Remove these skills?');
+                }
+            }
+            if (!apply) {
+                const results = preview;
+                if (opts.json) {
+                    outputSuccess(results, 'skills prune');
+                    return;
+                }
+                logHeader('Prune Preview (dry run — pass --yes to remove)');
+                logTable(['Platform', 'Skill', 'Path'], results.map((r) => [
+                    r.platform.name,
+                    r.skill,
+                    chalk.dim(r.targetPath),
+                ]));
+                log('');
+                log(chalk.dim('Re-run with --yes to remove these skills.'));
+                return;
+            }
+            const results = await pruneSkills(targets, { apply: true });
+            if (opts.json) {
+                outputSuccess(results, 'skills prune');
+                return;
+            }
+            logHeader('Prune Results');
+            logTable(['Platform', 'Skill', 'Status'], results.map((r) => [
+                r.platform.name,
+                r.skill,
+                chalk.red(r.action),
+            ]));
+        }
+        catch (error) {
+            spinner?.fail('Prune failed');
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills prune');
+            process.exit(1);
+        }
+    });
 }

package/dist/lib/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,sBAAsB,CAAA;AAChD,eAAO,MAAM,aAAa,QACgC,CAAA;AAC1D,eAAO,MAAM,YAAY,yBAAyB,CAAA;AAClD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,aAAa,SAAU,CAAA;AACpC,eAAO,MAAM,gBAAgB,mBAAmB,CAAA;AAChD,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAGzC,eAAO,MAAM,wBAAwB,YAAY,CAAA;AACjD,eAAO,MAAM,eAAe,YAAY,CAAA;AACxC,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAClD,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAC1C,eAAO,MAAM,WAAW,gBAAgB,CAAA;AACxC,eAAO,MAAM,eAAe,4BAA4B,CAAA;AAGxD,eAAO,MAAM,YAAY,QAC+B,CAAA;AAGxD,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAO/C,eAAO,MAAM,cAAc,QACwC,CAAA;AAMnE,eAAO,MAAM,YAAY,QACsD,CAAA;AAC/E,eAAO,MAAM,wBAAwB,QAEa,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/lib/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,sBAAsB,CAAA;AAChD,eAAO,MAAM,aAAa,QACgC,CAAA;AAC1D,eAAO,MAAM,YAAY,yBAAyB,CAAA;AAClD,eAAO,MAAM,oBAAoB,IAAI,CAAA;AACrC,eAAO,MAAM,kBAAkB,MAAM,CAAA;AACrC,eAAO,MAAM,aAAa,SAAU,CAAA;AACpC,eAAO,MAAM,gBAAgB,mBAAmB,CAAA;AAChD,eAAO,MAAM,gBAAgB,YAAY,CAAA;AAGzC,eAAO,MAAM,wBAAwB,YAAY,CAAA;AACjD,eAAO,MAAM,eAAe,YAAY,CAAA;AACxC,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAClD,eAAO,MAAM,YAAY,iBAAiB,CAAA;AAC1C,eAAO,MAAM,WAAW,gBAAgB,CAAA;AACxC,eAAO,MAAM,eAAe,4BAA4B,CAAA;AAGxD,eAAO,MAAM,YAAY,QAC+B,CAAA;AAGxD,eAAO,MAAM,eAAe,mBAAmB,CAAA;AAQ/C,eAAO,MAAM,cAAc,QACiC,CAAA;AAM5D,eAAO,MAAM,YAAY,QACsD,CAAA;AAC/E,eAAO,MAAM,wBAAwB,QAEa,CAAA"}

package/dist/lib/config.js

@@ -19,11 +19,12 @@ export const API_BASE_URL = process.env.SKHEMA_API_URL ?? 'https://api.skhema.co
 // Environment variable an unattended CI/agent run sets to supply an API key.
 export const API_KEY_ENV_VAR = 'SKHEMA_API_KEY';
 // Public Skhema MCP server endpoint (Streamable HTTP transport). This is the
-// protocol endpoint AI clients connect to — distinct from mcp.skhema.com (the
-// management dashboard). Auth is per-client browser OAuth on first use, so the
-// CLI only registers the URL; it never injects a credential here.
+// protocol endpoint AI clients connect to — mcp.skhema.com IS the MCP server.
+// (The human-facing management UI now lives at app.skhema.com/mcp.) Auth is
+// per-client browser OAuth on first use, so the CLI only registers the URL; it
+// never injects a credential here.
 // Override via env for staging/preview environments.
-export const MCP_SERVER_URL = process.env.SKHEMA_MCP_URL ?? 'https://mcp-server.skhema.com/mcp';
+export const MCP_SERVER_URL = process.env.SKHEMA_MCP_URL ?? 'https://mcp.skhema.com/mcp';
 // Supabase project configuration.
 // Publishable keys are safe to embed in client-side code (they are the new
 // replacement for the legacy anon key and rely on RLS + server-side auth

package/dist/lib/skills/installer.d.ts

@@ -1,4 +1,17 @@
-import type { DetectedPlatform, InstallResult } from './types.js';
+import type { DetectedPlatform, InstallResult, PruneResult } from './types.js';
 export declare function installSkills(platforms: DetectedPlatform[]): Promise<InstallResult[]>;
 export declare function updateSkills(platforms: DetectedPlatform[]): Promise<InstallResult[]>;
+/**
+ * Find skills we previously installed that are no longer bundled with this CLI
+ * (retired or renamed) and remove them from each platform.
+ *
+ * Attribution is anchored on the per-platform lock file: only skills recorded
+ * there by our own installer are candidates, so a skill authored by the user or
+ * another tool that happens to share the skills directory is never touched. With
+ * `apply: false` (the default), nothing is written — the returned list is a
+ * preview of what removal would do.
+ */
+export declare function pruneSkills(platforms: DetectedPlatform[], options?: {
+    apply: boolean;
+}): Promise<PruneResult[]>;
 //# sourceMappingURL=installer.d.ts.map

package/dist/lib/skills/installer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/installer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AA+DjE,wBAAsB,aAAa,CACjC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CA0C1B;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CAG1B"}
+{"version":3,"file":"installer.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/installer.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AA+D9E,wBAAsB,aAAa,CACjC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CA0C1B;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,gBAAgB,EAAE,GAC5B,OAAO,CAAC,aAAa,EAAE,CAAC,CAG1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,gBAAgB,EAAE,EAC7B,OAAO,GAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAqB,GAC7C,OAAO,CAAC,WAAW,EAAE,CAAC,CAmCxB"}

package/dist/lib/skills/installer.js

@@ -83,3 +83,43 @@ export async function updateSkills(platforms) {
     // Update uses the same logic as install — content comparison handles skip/update
     return installSkills(platforms);
 }
+/**
+ * Find skills we previously installed that are no longer bundled with this CLI
+ * (retired or renamed) and remove them from each platform.
+ *
+ * Attribution is anchored on the per-platform lock file: only skills recorded
+ * there by our own installer are candidates, so a skill authored by the user or
+ * another tool that happens to share the skills directory is never touched. With
+ * `apply: false` (the default), nothing is written — the returned list is a
+ * preview of what removal would do.
+ */
+export async function pruneSkills(platforms, options = { apply: false }) {
+    const bundledNames = new Set(getBundledSkills().map((skill) => skill.name));
+    const results = [];
+    for (const platform of platforms) {
+        const lock = readLock(platform);
+        const retired = Object.keys(lock.skills)
+            .filter((name) => !bundledNames.has(name))
+            .sort((a, b) => a.localeCompare(b));
+        for (const name of retired) {
+            const targetPath = path.join(platform.skillsDir, name);
+            if (options.apply) {
+                // Remove only the directory our lock attributes to this skill.
+                if (fs.existsSync(targetPath)) {
+                    fs.rmSync(targetPath, { recursive: true, force: true });
+                }
+                delete lock.skills[name];
+            }
+            results.push({
+                platform,
+                skill: name,
+                action: options.apply ? 'removed' : 'would-remove',
+                targetPath,
+            });
+        }
+        if (options.apply && retired.length > 0) {
+            writeLock(platform, lock);
+        }
+    }
+    return results;
+}

package/dist/lib/skills/types.d.ts

@@ -17,6 +17,12 @@ export interface InstallResult {
     action: 'installed' | 'updated' | 'skipped';
     targetPath: string;
 }
+export interface PruneResult {
+    platform: DetectedPlatform;
+    skill: string;
+    action: 'removed' | 'would-remove';
+    targetPath: string;
+}
 export interface SkillLock {
     version: string;
     installedAt: string;

package/dist/lib/skills/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;IAC3C,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CACZ,MAAM,EACN;QACE,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,MAAM,CAAA;KACpB,CACF,CAAA;CACF"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,EAAE,CAAA;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAAA;IAC3C,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,SAAS,GAAG,cAAc,CAAA;IAClC,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CACZ,MAAM,EACN;QACE,OAAO,EAAE,MAAM,CAAA;QACf,QAAQ,EAAE,MAAM,CAAA;QAChB,WAAW,EAAE,MAAM,CAAA;KACpB,CACF,CAAA;CACF"}

package/dist/program.d.ts

@@ -1,4 +1,16 @@
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
+/**
+ * Resolve the process exit code for a parser-level {@link CommanderError}.
+ *
+ * Commander's own defaults are inconsistent (unknown option → 1, unknown
+ * command silently swallowed → 0, missing subcommand → 1). We collapse them
+ * onto the CLI's stable {@link ExitCode} contract: printing help or the version
+ * is an informational success (`0`), and every other parser failure — unknown
+ * option, unknown/missing command, missing or excess argument — is a usage
+ * error ({@link ExitCode.Usage}). Commander tags the informational cases with
+ * `exitCode === 0`, which is the only discriminator we need.
+ */
+export declare function resolveCommanderExitCode(err: CommanderError): number;
 /**
  * Assemble the full skhema CLI program. The runtime entry (cli.ts) and the
  * docs reference generator both build from here, so every registered command

package/dist/program.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAiDrD"}
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAsBnD;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAqErD"}

package/dist/program.js

@@ -16,8 +16,23 @@ import { registerStrategyCommands } from './commands/strategy.js';
 import { registerWebhookCommands } from './commands/webhook.js';
 import { registerWorkspaceCommands } from './commands/workspace.js';
 import { setApiKeyFlag } from './lib/api/credential-context.js';
+import { ExitCode } from './lib/api/run-command.js';
 import { showBanner } from './lib/banner.js';
 import { setGlobalOptions } from './lib/output.js';
+/**
+ * Resolve the process exit code for a parser-level {@link CommanderError}.
+ *
+ * Commander's own defaults are inconsistent (unknown option → 1, unknown
+ * command silently swallowed → 0, missing subcommand → 1). We collapse them
+ * onto the CLI's stable {@link ExitCode} contract: printing help or the version
+ * is an informational success (`0`), and every other parser failure — unknown
+ * option, unknown/missing command, missing or excess argument — is a usage
+ * error ({@link ExitCode.Usage}). Commander tags the informational cases with
+ * `exitCode === 0`, which is the only discriminator we need.
+ */
+export function resolveCommanderExitCode(err) {
+    return err.exitCode === 0 ? ExitCode.Ok : ExitCode.Usage;
+}
 /**
  * Assemble the full skhema CLI program. The runtime entry (cli.ts) and the
  * docs reference generator both build from here, so every registered command
@@ -25,6 +40,15 @@ import { setGlobalOptions } from './lib/output.js';
  */
 export function buildProgram(version) {
     const program = new Command();
+    // Throw a CommanderError instead of calling process.exit directly, so the
+    // entry point can map every parser-level failure onto the ExitCode taxonomy.
+    // Set before registering subcommands: commander copies the exit callback into
+    // each child at `.command()` time, so this one call covers the whole tree.
+    program.exitOverride();
+    // The default `.action()` below (banner on bare invocation) otherwise
+    // suppresses commander's implicit `help` command, so `skhema help [command]`
+    // would fall through to the unknown-command guard. Re-enable it explicitly.
+    program.helpCommand(true);
     program
         .name('skhema')
         .description('Skhema CLI — drive the Skhema Public API from your terminal, CI, or agent')
@@ -43,7 +67,16 @@ export function buildProgram(version) {
         setApiKeyFlag(opts.apiKey);
     })
         .action(() => {
-        // Show banner when run with no subcommand
+        // A bare `skhema` invocation shows the banner. Any leftover operand means
+        // an unknown command was given: commander routes it here (the default
+        // action) instead of erroring, so we must reject it ourselves — otherwise
+        // the banner prints and the process exits 0, hiding the mistake.
+        if (program.args.length > 0) {
+            program.error(`unknown command '${program.args[0]}'`, {
+                code: 'commander.unknownCommand',
+                exitCode: ExitCode.Usage,
+            });
+        }
         showBanner(version);
         program.help();
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skhema/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Skhema CLI - Authentication and AI skills management for agent platforms",
   "type": "module",
   "main": "dist/index.js",
@@ -42,7 +42,7 @@
   },
   "dependencies": {
     "@skhema/agent-sdk": "0.1.4",
-    "@skhema/method": "0.3.0",
+    "@skhema/method": "0.4.0",
     "@skhema/sdk": "0.2.4",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",