@skhema/cli 0.4.2 → 0.4.4

package/dist/cli.js

@@ -1,63 +1,11 @@
-import { Command } from 'commander';
 import { createRequire } from 'module';
-import { registerAgentCommands } from './commands/agent.js';
-import { registerApiCommands } from './commands/api.js';
-import { registerAuthCommands } from './commands/auth.js';
-import { registerComponentCommands } from './commands/component.js';
-import { registerContributeCommands } from './commands/contribute.js';
-import { registerElementCommands } from './commands/element.js';
-import { registerWorkspaceExportCommand } from './commands/export.js';
-import { registerInitCommand } from './commands/init.js';
-import { registerLinkCommands } from './commands/link.js';
-import { registerResourceCommands } from './commands/resource.js';
-import { registerSkillsCommands } from './commands/skills.js';
-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 { isApprovedContributor } from './lib/auth/entitlements.js';
 import { getStoredCredentials } from './lib/auth/token-store.js';
-import { showBanner } from './lib/banner.js';
-import { outputError, setGlobalOptions } from './lib/output.js';
+import { outputError } from './lib/output.js';
+import { buildProgram } from './program.js';
 const require = createRequire(import.meta.url);
 const pkg = require('../package.json');
-const program = new Command();
-program
-    .name('skhema')
-    .description('Skhema CLI — drive the Skhema Public API from your terminal, CI, or agent')
-    .version(pkg.version)
-    .option('--json', 'Output structured JSON')
-    .option('--verbose', 'Verbose output')
-    .option('--quiet', 'Suppress non-essential output')
-    .option('--api-key <key>', 'Use this API key for this invocation (highest credential precedence)')
-    .hook('preAction', (thisCommand) => {
-    const opts = thisCommand.opts();
-    setGlobalOptions({
-        json: opts.json ?? false,
-        verbose: opts.verbose ?? false,
-        quiet: opts.quiet ?? false,
-    });
-    setApiKeyFlag(opts.apiKey);
-})
-    .action(() => {
-    // Show banner when run with no subcommand
-    showBanner(pkg.version);
-    program.help();
-});
-registerInitCommand(program);
-registerAuthCommands(program);
-registerWorkspaceCommands(program);
-registerElementCommands(program);
-registerLinkCommands(program);
-registerWorkspaceExportCommand(program);
-registerComponentCommands(program);
-registerStrategyCommands(program);
-registerResourceCommands(program);
-registerWebhookCommands(program);
-registerAgentCommands(program);
-registerApiCommands(program);
-registerSkillsCommands(program);
-registerContributeCommands(program);
+const program = buildProgram(pkg.version);
 async function main() {
     // Gate all contribute invocations (including --help) before Commander parses.
     // Commander handles --help internally before preAction fires, so we check early.

package/dist/commands/document.d.ts

@@ -0,0 +1,10 @@
+import { Command } from 'commander';
+/**
+ * Document commands — workspace-authored narrative artifacts (board updates,
+ * team briefs, decision briefs, custom docs). All are workspace-scoped via
+ * `--workspace` (falling back to the default set by `skhema workspace use`).
+ * The routes carry the workspace id in the path, so — unlike `workspace list`
+ * — no organizationId is forwarded; the gateway authorizes via workspace access.
+ */
+export declare function registerDocumentCommands(program: Command): void;
+//# sourceMappingURL=document.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/commands/document.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAqBnC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgK/D"}

package/dist/commands/document.js

@@ -0,0 +1,122 @@
+import chalk from 'chalk';
+import { resolveClient } from '../lib/api/client.js';
+import { asRecord, buildBody, coerceList, readPayloadFile, resolveWorkspaceId, } from '../lib/api/command-helpers.js';
+import { runCommand, UsageError } from '../lib/api/run-command.js';
+import { getGlobalOptions, log, logHeader, logTable } from '../lib/output.js';
+/** Print a single document as a label block (human output only). */
+function printDocument(document) {
+    const d = asRecord(document);
+    logHeader(String(d.title ?? d.id ?? 'Document'));
+    log(`  Id:       ${chalk.cyan(String(d.id ?? '—'))}`);
+    if (d.docType)
+        log(`  Type:     ${String(d.docType)}`);
+    if (d.updatedAt)
+        log(`  Updated:  ${String(d.updatedAt)}`);
+}
+/**
+ * Document commands — workspace-authored narrative artifacts (board updates,
+ * team briefs, decision briefs, custom docs). All are workspace-scoped via
+ * `--workspace` (falling back to the default set by `skhema workspace use`).
+ * The routes carry the workspace id in the path, so — unlike `workspace list`
+ * — no organizationId is forwarded; the gateway authorizes via workspace access.
+ */
+export function registerDocumentCommands(program) {
+    const document = program.command('document').description('Document commands');
+    const withWorkspace = (cmd) => cmd.option('--workspace <id>', 'Workspace id (defaults to `skhema workspace use`)');
+    withWorkspace(document.command('list').description('List documents')).action(async (options) => {
+        await runCommand('document list', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.documents.list(workspaceId);
+            const rows = coerceList(data, 'documents');
+            if (!getGlobalOptions().json) {
+                logHeader(`Documents (${rows.length})`);
+                if (rows.length === 0)
+                    log(chalk.dim('  No documents.'));
+                else
+                    logTable(['Title', 'Type', 'Updated', 'Id'], rows.map((r) => {
+                        const d = asRecord(r);
+                        return [
+                            String(d.title ?? '—'),
+                            String(d.docType ?? '—'),
+                            String(d.updatedAt ?? '—'),
+                            String(d.id ?? '—'),
+                        ];
+                    }));
+            }
+            return data;
+        });
+    });
+    withWorkspace(document.command('get <document-id>').description('Get a document by id')).action(async (documentId, options) => {
+        await runCommand('document get', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.documents.get(workspaceId, documentId);
+            if (!getGlobalOptions().json)
+                printDocument(asRecord(data).document ?? data);
+            return data;
+        });
+    });
+    withWorkspace(document
+        .command('create')
+        .description('Create a document')
+        .option('--title <title>', 'Document title')
+        .option('--doc-type <type>', 'Document type (board_update | team_brief | decision_brief | custom)')
+        .option('--content <content>', 'Document content')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')).action(async (options) => {
+        await runCommand('document create', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const body = buildBody(readPayloadFile(options.file), {
+                title: options.title,
+                docType: options.docType,
+                content: options.content,
+            });
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('Nothing to create. Pass document fields as flags or a --file payload.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.documents.create(workspaceId, body);
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Document created.'));
+                printDocument(asRecord(data).document ?? data);
+            }
+            return data;
+        });
+    });
+    withWorkspace(document
+        .command('update <document-id>')
+        .description('Update a document')
+        .option('--title <title>', 'Document title')
+        .option('--doc-type <type>', 'Document type (board_update | team_brief | decision_brief | custom)')
+        .option('--content <content>', 'Document content')
+        .option('--file <path>', 'JSON payload file for the full body ("-" for stdin)')).action(async (documentId, options) => {
+        await runCommand('document update', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const body = buildBody(readPayloadFile(options.file), {
+                title: options.title,
+                docType: options.docType,
+                content: options.content,
+            });
+            if (Object.keys(body).length === 0) {
+                throw new UsageError('Nothing to update. Pass document fields as flags or a --file payload.');
+            }
+            const { client } = await resolveClient();
+            const data = await client.documents.update(workspaceId, documentId, body);
+            if (!getGlobalOptions().json) {
+                log(chalk.green('Document updated.'));
+                printDocument(asRecord(data).document ?? data);
+            }
+            return data;
+        });
+    });
+    withWorkspace(document.command('delete <document-id>').description('Delete a document')).action(async (documentId, options) => {
+        await runCommand('document delete', async () => {
+            const workspaceId = resolveWorkspaceId(options.workspace);
+            const { client } = await resolveClient();
+            const data = await client.documents.delete(workspaceId, documentId);
+            if (!getGlobalOptions().json)
+                log(chalk.green(`Deleted document ${documentId}.`));
+            return data;
+        });
+    });
+}

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;AAanC,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA4I7D"}
+{"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"}

package/dist/commands/skills.js

@@ -1,7 +1,9 @@
 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 { readLock } from '../lib/skills/lock.js';
 import { detectPlatforms } from '../lib/skills/platform-detect.js';
 export function registerSkillsCommands(program) {
     const skills = program.command('skills').description('AI skills management');
@@ -57,12 +59,71 @@ export function registerSkillsCommands(program) {
     });
     skills
         .command('list')
-        .description('Show detected platforms and installed skills')
+        .description('List the Skhema skills bundled with this CLI')
+        .action(async () => {
+        try {
+            const bundled = listBundledSkills();
+            const detected = detectPlatforms().filter((p) => p.detected);
+            const withInstalls = bundled.map((skill) => ({
+                name: skill.name,
+                description: skill.description,
+                installedOn: detected
+                    .filter((p) => readLock(p).skills[skill.name] !== undefined)
+                    .map((p) => p.id),
+            }));
+            if (getGlobalOptions().json) {
+                outputSuccess({ skills: withInstalls, detectedPlatforms: detected.length }, 'skills list');
+                return;
+            }
+            logHeader(`Skhema Skills (${withInstalls.length})`);
+            const truncate = (text, max) => text.length > max ? `${text.slice(0, max - 1)}…` : text;
+            logTable(['Name', 'Description', 'Installed'], withInstalls.map((skill) => [
+                skill.name,
+                truncate(skill.description, 60),
+                skill.installedOn.length === 0
+                    ? chalk.dim('not installed')
+                    : `${skill.installedOn.length}/${detected.length} platforms`,
+            ]));
+            log('');
+            log(chalk.dim('Run `skhema skills show <name>` to read a skill, `skhema skills platforms` for install locations.'));
+        }
+        catch (error) {
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills list');
+            process.exit(1);
+        }
+    });
+    skills
+        .command('show <name>')
+        .description('Print a bundled skill (frontmatter and documentation)')
+        .action(async (name) => {
+        try {
+            const skill = readBundledSkill(name);
+            if (!skill) {
+                const available = listBundledSkills()
+                    .map((s) => s.name)
+                    .join(', ');
+                outputError(`Skill "${name}" is not bundled with this CLI. Available: ${available}`, 'skills show');
+                process.exit(1);
+            }
+            if (getGlobalOptions().json) {
+                outputSuccess(skill, 'skills show');
+                return;
+            }
+            log(skill.content);
+        }
+        catch (error) {
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills show');
+            process.exit(1);
+        }
+    });
+    skills
+        .command('platforms')
+        .description('Show detected agent platforms and their skills directories')
         .action(async () => {
         try {
             const platforms = detectPlatforms();
             if (getGlobalOptions().json) {
-                outputSuccess(platforms, 'skills list');
+                outputSuccess(platforms, 'skills platforms');
                 return;
             }
             logHeader('Agent Platforms');
@@ -74,7 +135,7 @@ export function registerSkillsCommands(program) {
             logTable(['Platform', 'Status', 'Skills Directory'], rows);
         }
         catch (error) {
-            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills list');
+            outputError(error instanceof Error ? error.message : 'Unknown error', 'skills platforms');
             process.exit(1);
         }
     });

package/dist/lib/api/command-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/api/command-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAKzC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAsB1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,WAAW,CAMb;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAQlE"}
+{"version":3,"file":"command-helpers.d.ts","sourceRoot":"","sources":["../../../src/lib/api/command-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAKzC;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAQxD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAuB1E;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,WAAW,CAMb;AAED,4EAA4E;AAC5E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIhE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,EAAE,CAQlE"}

package/dist/lib/api/command-helpers.js

@@ -29,7 +29,8 @@ export function readPayloadFile(filePath) {
         throw new UsageError(`Could not read payload file "${filePath}": ${err instanceof Error ? err.message : String(err)}`);
     }
     try {
-        const parsed = JSON.parse(raw);
+        // Strip a leading UTF-8 BOM so a byte-identical-looking file parses.
+        const parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
         if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
             throw new Error('expected a JSON object');
         }

package/dist/lib/api/passthrough.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"passthrough.d.ts","sourceRoot":"","sources":["../../../src/lib/api/passthrough.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAW7C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAyBrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,EAAE,EAAE;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CA+B9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,GACxB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CASzB"}
+{"version":3,"file":"passthrough.d.ts","sourceRoot":"","sources":["../../../src/lib/api/passthrough.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAW7C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAQvD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAyBrE;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,EAAE,EAAE;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAC3C,SAAS,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CACjC,GACA,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC,CA2C9C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,MAAM,EAAE,GAAG,SAAS,GACxB,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CASzB"}

package/dist/lib/api/passthrough.js

@@ -79,10 +79,19 @@ export async function resolveDataBody(raw, io) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(text);
+        // Strip a leading UTF-8 BOM (editors and some `echo`/redirect toolchains
+        // prepend one); JSON.parse chokes on it, which surfaced as the opaque
+        // "--data is not valid JSON" even for a well-formed @file. Mirrors curl.
+        parsed = JSON.parse(text.replace(/^\uFEFF/, ''));
     }
-    catch {
-        throw new UsageError('--data is not valid JSON.');
+    catch (err) {
+        // Name the source so a failed @file is not mistaken for the literal form.
+        const label = raw === '-'
+            ? 'from stdin'
+            : raw.startsWith('@')
+                ? `file "${raw.slice(1)}"`
+                : 'value';
+        throw new UsageError(`--data ${label} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
     if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
         throw new UsageError('--data must be a JSON object.');

package/dist/lib/api/payload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/lib/api/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9C,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAczD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,WAAW,CAad"}
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../../src/lib/api/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9C,8DAA8D;AAC9D,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAatD;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAezD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB,GAAG,WAAW,CAad"}

package/dist/lib/api/payload.js

@@ -22,7 +22,8 @@ export function parseJsonFile(source) {
     const raw = readFileOrStdin(source);
     let parsed;
     try {
-        parsed = JSON.parse(raw);
+        // Strip a leading UTF-8 BOM so a byte-identical-looking file parses.
+        parsed = JSON.parse(raw.replace(/^\uFEFF/, ''));
     }
     catch {
         throw new UsageError(`Payload in ${source === '-' ? 'stdin' : source} is not valid JSON.`);

package/dist/lib/docs/reference-generator.d.ts

@@ -0,0 +1,2 @@
+export declare function generateCliReference(): string;
+//# sourceMappingURL=reference-generator.d.ts.map

package/dist/lib/docs/reference-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-generator.d.ts","sourceRoot":"","sources":["../../../src/lib/docs/reference-generator.ts"],"names":[],"mappings":"AA6IA,wBAAgB,oBAAoB,IAAI,MAAM,CAyE7C"}

package/dist/lib/docs/reference-generator.js

@@ -0,0 +1,185 @@
+import { buildProgram } from '../../program.js';
+import { ExitCode } from '../api/run-command.js';
+/**
+ * Generate the public CLI reference as MDX, by walking the same commander
+ * program tree the runtime executes (src/program.ts). Deterministic and
+ * version-independent: the output changes only when commands, arguments,
+ * options, or exit codes change — never on a plain version bump.
+ *
+ * The committed copy lives at docs/cli-reference.mdx and is drift-tested
+ * (src/__tests__/cli-reference-drift.test.ts). The deployed copy is
+ * skhema-web content/docs/api/cli.mdx — sync it when this file changes.
+ */
+/** Human meanings for the stable exit-code contract (run-command.ts). */
+const EXIT_CODE_MEANINGS = {
+    Ok: 'Success',
+    Error: 'Generic or API error (non-specific 4xx/5xx, unexpected failure)',
+    Usage: 'Usage error — bad or missing arguments, caught before any API call',
+    AuthRequired: 'No usable credential — authenticate first',
+    Denied: 'Permission or plan denied (HTTP 403 or 402)',
+    RateLimited: 'Rate limited (HTTP 429)',
+};
+/** Escape plain text for MDX prose and table cells. */
+function esc(text) {
+    return text
+        .replace(/\\/g, '\\\\')
+        .replace(/</g, '\\<')
+        .replace(/\{/g, '\\{')
+        .replace(/\}/g, '\\}')
+        .replace(/\|/g, '\\|')
+        .replace(/\n/g, ' ');
+}
+/**
+ * Escape a string destined for an inline-code span INSIDE a GFM table cell.
+ * Table cell-splitting on `|` happens before inline-code parsing, so a pipe
+ * inside backticks still breaks the row (and can leak `<` into JSX position —
+ * this took down /docs/api/cli via `--data <json|@file|->`). GFM honours
+ * `\|` everywhere in a table row, including within code spans.
+ */
+function escCode(text) {
+    return text.replace(/\|/g, '\\|');
+}
+/** Render an argument the way commander's help does: <required> / [optional]. */
+function argName(arg) {
+    const name = arg.name() + (arg.variadic ? '...' : '');
+    return arg.required ? `<${name}>` : `[${name}]`;
+}
+/** Full invocation path from the root program down to this command. */
+function commandPath(cmd) {
+    const parts = [];
+    let current = cmd;
+    while (current) {
+        parts.unshift(current.name());
+        current = current.parent;
+    }
+    return parts.join(' ');
+}
+function usageLine(cmd) {
+    const pieces = [commandPath(cmd)];
+    const args = cmd.registeredArguments.map(argName);
+    if (args.length > 0)
+        pieces.push(...args);
+    const visibleOptions = cmd.options.filter((option) => !option.hidden);
+    if (visibleOptions.length > 0)
+        pieces.push('[options]');
+    if (cmd.commands.length > 0)
+        pieces.push('<command>');
+    return pieces.join(' ');
+}
+function renderDefault(option) {
+    if (option.defaultValue === undefined)
+        return '';
+    return `\`${JSON.stringify(option.defaultValue)}\``;
+}
+function renderOptionsTable(cmd) {
+    const visible = cmd.options.filter((option) => !option.hidden);
+    if (visible.length === 0)
+        return [];
+    const hasDefaults = visible.some((option) => option.defaultValue !== undefined);
+    const lines = [];
+    if (hasDefaults) {
+        lines.push('| Option | Description | Default |');
+        lines.push('| --- | --- | --- |');
+        for (const option of visible) {
+            lines.push(`| \`${escCode(option.flags)}\` | ${esc(option.description ?? '')} | ${renderDefault(option)} |`);
+        }
+    }
+    else {
+        lines.push('| Option | Description |');
+        lines.push('| --- | --- |');
+        for (const option of visible) {
+            lines.push(`| \`${escCode(option.flags)}\` | ${esc(option.description ?? '')} |`);
+        }
+    }
+    lines.push('');
+    return lines;
+}
+function renderArgumentsTable(cmd) {
+    const args = cmd.registeredArguments.filter((arg) => arg.description);
+    if (args.length === 0)
+        return [];
+    const lines = ['| Argument | Description |', '| --- | --- |'];
+    for (const arg of args) {
+        lines.push(`| \`${argName(arg)}\` | ${esc(arg.description)} |`);
+    }
+    lines.push('');
+    return lines;
+}
+function renderCommand(cmd, depth) {
+    if (cmd.name() === 'help')
+        return [];
+    const lines = [];
+    const heading = '#'.repeat(Math.min(depth + 2, 6));
+    lines.push(`${heading} \`${commandPath(cmd)}\``);
+    lines.push('');
+    lines.push('```sh');
+    lines.push(usageLine(cmd));
+    lines.push('```');
+    lines.push('');
+    const description = cmd.description();
+    if (description) {
+        lines.push(esc(description));
+        lines.push('');
+    }
+    lines.push(...renderArgumentsTable(cmd));
+    lines.push(...renderOptionsTable(cmd));
+    for (const sub of cmd.commands) {
+        lines.push(...renderCommand(sub, depth + 1));
+    }
+    return lines;
+}
+export function generateCliReference() {
+    const program = buildProgram('0.0.0-reference');
+    const lines = [];
+    lines.push('---');
+    lines.push('title: CLI Reference');
+    lines.push('description: Every skhema command — usage, arguments, options, and the exit-code contract. Generated from the CLI itself.');
+    lines.push('---');
+    lines.push('');
+    lines.push('{/* AUTO-GENERATED from the @skhema/cli command tree — do not edit by hand.');
+    lines.push('    Regenerate with `npm run generate:cli-reference` in skhema-packages/skhema-cli. */}');
+    lines.push('');
+    lines.push('This page is generated from the CLI itself, so it always matches the installed command surface. For a guided tour, start with [Using the CLI](/docs/guides/using-the-cli).');
+    lines.push('');
+    lines.push('```sh');
+    lines.push('npm install -g @skhema/cli');
+    lines.push('```');
+    lines.push('');
+    lines.push('## `skhema`');
+    lines.push('');
+    lines.push('```sh');
+    lines.push('skhema [options] <command>');
+    lines.push('```');
+    lines.push('');
+    lines.push(esc(program.description()));
+    lines.push('');
+    lines.push('### Global options');
+    lines.push('');
+    lines.push('Available on every command.');
+    lines.push('');
+    lines.push('| Option | Description |');
+    lines.push('| --- | --- |');
+    for (const option of program.options.filter((o) => !o.hidden)) {
+        lines.push(`| \`${escCode(option.flags)}\` | ${esc(option.description ?? '')} |`);
+    }
+    lines.push('');
+    lines.push('### Exit codes');
+    lines.push('');
+    lines.push('Exit codes are a stable contract — scripts, CI steps, and agents can branch on them.');
+    lines.push('');
+    lines.push('| Code | Meaning |');
+    lines.push('| --- | --- |');
+    for (const [key, meaning] of Object.entries(EXIT_CODE_MEANINGS)) {
+        lines.push(`| \`${ExitCode[key]}\` | ${meaning} |`);
+    }
+    lines.push('');
+    lines.push('## Commands');
+    lines.push('');
+    for (const cmd of program.commands) {
+        lines.push(...renderCommand(cmd, 1));
+    }
+    return (lines
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trimEnd() + '\n');
+}

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

@@ -0,0 +1,16 @@
+/** A skill shipped inside the @skhema/cli package (skills/, synced at build). */
+export interface BundledSkill {
+    name: string;
+    description: string;
+    dir: string;
+}
+export declare function getBundledSkillsDir(): string;
+/** Enumerate the bundled skills with their frontmatter metadata. */
+export declare function listBundledSkills(): BundledSkill[];
+/** Read a bundled skill's full SKILL.md, or null if it is not bundled. */
+export declare function readBundledSkill(name: string): {
+    name: string;
+    description: string;
+    content: string;
+} | null;
+//# sourceMappingURL=bundled.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundled.d.ts","sourceRoot":"","sources":["../../../src/lib/skills/bundled.ts"],"names":[],"mappings":"AAOA,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,wBAAgB,mBAAmB,IAAI,MAAM,CAG5C;AA6BD,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,YAAY,EAAE,CAmBlD;AAED,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,GACX;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAM/D"}

package/dist/lib/skills/bundled.js

@@ -0,0 +1,66 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export function getBundledSkillsDir() {
+    // Navigate from dist/lib/skills/bundled.js (or src/… under tsx) to skills/
+    return path.resolve(__dirname, '..', '..', '..', 'skills');
+}
+/**
+ * Parse the SKILL.md frontmatter block. The bundled skills use simple
+ * single-line `key: value` pairs between `---` fences.
+ */
+function parseFrontmatter(content) {
+    const result = {};
+    const lines = content.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return result;
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '---')
+            break;
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        let value = line.slice(colon + 1).trim();
+        // Unwrap YAML-style quoting ("…" or '…') around single-line values.
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        result[line.slice(0, colon).trim()] = value;
+    }
+    return result;
+}
+/** Enumerate the bundled skills with their frontmatter metadata. */
+export function listBundledSkills() {
+    const skillsDir = getBundledSkillsDir();
+    if (!fs.existsSync(skillsDir))
+        return [];
+    return fs
+        .readdirSync(skillsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => {
+        const dir = path.join(skillsDir, entry.name);
+        const skillFile = path.join(dir, 'SKILL.md');
+        let description = '';
+        if (fs.existsSync(skillFile)) {
+            const meta = parseFrontmatter(fs.readFileSync(skillFile, 'utf-8'));
+            description = meta.description ?? '';
+        }
+        return { name: entry.name, description, dir };
+    })
+        .filter((skill) => fs.existsSync(path.join(skill.dir, 'SKILL.md')))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Read a bundled skill's full SKILL.md, or null if it is not bundled. */
+export function readBundledSkill(name) {
+    const skillFile = path.join(getBundledSkillsDir(), name, 'SKILL.md');
+    if (!fs.existsSync(skillFile))
+        return null;
+    const content = fs.readFileSync(skillFile, 'utf-8');
+    const meta = parseFrontmatter(content);
+    return { name, description: meta.description ?? '', content };
+}

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;AAgFjE,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,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"}

package/dist/lib/skills/installer.js

@@ -1,28 +1,13 @@
 import crypto from 'crypto';
 import fs from 'fs';
 import path from 'path';
-import { fileURLToPath } from 'url';
+import { listBundledSkills } from './bundled.js';
 import { readLock, writeLock } from './lock.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-function getBundledSkillsDir() {
-    // Navigate from dist/lib/skills/installer.js to skills/
-    return path.resolve(__dirname, '..', '..', '..', 'skills');
-}
 function getFileChecksum(content) {
     return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
 }
 function getBundledSkills() {
-    const skillsDir = getBundledSkillsDir();
-    if (!fs.existsSync(skillsDir))
-        return [];
-    return fs
-        .readdirSync(skillsDir, { withFileTypes: true })
-        .filter((entry) => entry.isDirectory())
-        .map((entry) => ({
-        name: entry.name,
-        dir: path.join(skillsDir, entry.name),
-    }));
+    return listBundledSkills();
 }
 function copySkillToPlatform(skillDir, skillName, platform) {
     const targetDir = path.join(platform.skillsDir, skillName);

package/dist/program.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * Assemble the full skhema CLI program. The runtime entry (cli.ts) and the
+ * docs reference generator both build from here, so every registered command
+ * is — structurally — part of the generated reference.
+ */
+export declare function buildProgram(version: string): Command;
+//# sourceMappingURL=program.d.ts.map

package/dist/program.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"program.d.ts","sourceRoot":"","sources":["../src/program.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAoBnC;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAgDrD"}

package/dist/program.js

@@ -0,0 +1,65 @@
+import { Command } from 'commander';
+import { registerAgentCommands } from './commands/agent.js';
+import { registerApiCommands } from './commands/api.js';
+import { registerAuthCommands } from './commands/auth.js';
+import { registerComponentCommands } from './commands/component.js';
+import { registerContributeCommands } from './commands/contribute.js';
+import { registerDocumentCommands } from './commands/document.js';
+import { registerElementCommands } from './commands/element.js';
+import { registerWorkspaceExportCommand } from './commands/export.js';
+import { registerInitCommand } from './commands/init.js';
+import { registerLinkCommands } from './commands/link.js';
+import { registerResourceCommands } from './commands/resource.js';
+import { registerSkillsCommands } from './commands/skills.js';
+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 { showBanner } from './lib/banner.js';
+import { setGlobalOptions } from './lib/output.js';
+/**
+ * Assemble the full skhema CLI program. The runtime entry (cli.ts) and the
+ * docs reference generator both build from here, so every registered command
+ * is — structurally — part of the generated reference.
+ */
+export function buildProgram(version) {
+    const program = new Command();
+    program
+        .name('skhema')
+        .description('Skhema CLI — drive the Skhema Public API from your terminal, CI, or agent')
+        .version(version)
+        .option('--json', 'Output structured JSON')
+        .option('--verbose', 'Verbose output')
+        .option('--quiet', 'Suppress non-essential output')
+        .option('--api-key <key>', 'Use this API key for this invocation (highest credential precedence)')
+        .hook('preAction', (thisCommand) => {
+        const opts = thisCommand.opts();
+        setGlobalOptions({
+            json: opts.json ?? false,
+            verbose: opts.verbose ?? false,
+            quiet: opts.quiet ?? false,
+        });
+        setApiKeyFlag(opts.apiKey);
+    })
+        .action(() => {
+        // Show banner when run with no subcommand
+        showBanner(version);
+        program.help();
+    });
+    registerInitCommand(program);
+    registerAuthCommands(program);
+    registerWorkspaceCommands(program);
+    registerElementCommands(program);
+    registerLinkCommands(program);
+    registerWorkspaceExportCommand(program);
+    registerComponentCommands(program);
+    registerStrategyCommands(program);
+    registerDocumentCommands(program);
+    registerResourceCommands(program);
+    registerWebhookCommands(program);
+    registerAgentCommands(program);
+    registerApiCommands(program);
+    registerSkillsCommands(program);
+    registerContributeCommands(program);
+    return program;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skhema/cli",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Skhema CLI - Authentication and AI skills management for agent platforms",
   "type": "module",
   "main": "dist/index.js",
@@ -37,23 +37,26 @@
     "check": "npm run typecheck && npm run lint && npm run format:check",
     "check:fix": "npm run format && npm run lint:fix",
     "prepublishOnly": "npm run build",
-    "postinstall": "node dist/postinstall.js || true"
+    "postinstall": "node dist/postinstall.js || true",
+    "generate:cli-reference": "tsx scripts/generate-cli-reference.ts"
   },
   "dependencies": {
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "ora": "^8.0.0",
     "@skhema/agent-sdk": "0.1.4",
     "@skhema/method": "0.3.0",
-    "@skhema/sdk": "0.2.1"
+    "@skhema/sdk": "0.2.2",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.0"
   },
   "devDependencies": {
+    "@mdx-js/mdx": "3.1.1",
     "@skhema/linter": "2.2.0",
     "@skhema/prettier-config": "1.0.0",
     "@types/node": "^22.0.0",
     "eslint": "^9.0.0",
     "prettier": "^3.0.0",
     "prettier-plugin-organize-imports": "^4.3.0",
+    "remark-gfm": "4.0.1",
     "tsx": "^4.7.0",
     "typescript": "^5.0.0",
     "vitest": "^4.0.0"