skill-check 0.1.0 → 1.0.0

package/dist/cli/main.js

@@ -1,15 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { pathToFileURL } from 'node:url';
 import { cancel as clackCancel, confirm, intro, isCancel, outro, select, text, } from '@clack/prompts';
 import { Command, CommanderError } from 'commander';
 import { Listr } from 'listr2';
 import ora from 'ora';
 import pc from 'picocolors';
-import { isCommandAvailable, isValidAgentScanRunner, resolveAgentScanInvocation, runAgentScan, } from '../core/agent-scan.js';
+import { deriveAgentScanSkillRoots, isCommandAvailable, isValidAgentScanRunner, resolveAgentScanInvocation, runAgentScan, summarizeAgentScanOutput, } from '../core/agent-scan.js';
 import { analyze, analyzeWithConfig, ensureInitConfig, resolveExitCode, writeIfRequested, } from '../core/analyze.js';
+import { buildSkillArtifact } from '../core/artifact.js';
 import { diffBaseline, loadBaseline, } from '../core/baseline.js';
+import { applyBodySplitPlan, planBodySplit, } from '../core/body-split.js';
+import { renderConclusionCard, } from '../core/conclusion-card.js';
 import { resolveConfig } from '../core/config.js';
+import { discoverSkillFiles } from '../core/discovery.js';
 import { detectDuplicates } from '../core/duplicates.js';
 import { CliError } from '../core/errors.js';
 import { applyAutoFixes, isFixableRuleId, } from '../core/fix.js';
@@ -19,13 +24,28 @@ import { renderHtml } from '../core/html-report.js';
 import { selectFixableDiagnostics } from '../core/interactive-fix.js';
 import { openInBrowser } from '../core/open-browser.js';
 import { computeSkillScores } from '../core/quality-score.js';
+import { isGitHubRepoUrl, materializeRemoteTarget, } from '../core/remote-target.js';
 import { renderMarkdownReport } from '../core/report.js';
 import { toSarif } from '../core/sarif.js';
+import { writeShareImage } from '../core/share-image.js';
 import { coreRules } from '../rules/core/index.js';
 const defaultIO = {
     stdout: (text) => process.stdout.write(text),
     stderr: (text) => process.stderr.write(text),
 };
+const ROOT_COMMANDS = new Set([
+    'check',
+    'split-body',
+    'report',
+    'security-scan',
+    'rules',
+    'new',
+    'diff',
+    'watch',
+    'init',
+    'help',
+    'version',
+]);
 function collectList(value, previous) {
     const parsed = value
         .split(',')
@@ -60,6 +80,7 @@ function addAgentScanOptions(command) {
         .option('--security-scan-mode <mode>', 'Security scan mode (default: llmsecurity)', 'llmsecurity')
         .option('--security-scan-paths <path>', 'Comma-separated paths to scan (repeatable)', collectList, [])
         .option('--security-scan-skills <path>', 'Comma-separated skills paths (repeatable)', collectList, [])
+        .option('--security-scan-verbose', 'Show full raw security scanner output')
         .option('--allow-installs', 'Allow automatic dependency installs for security scan runners')
         .option('--no-installs', 'Disallow dependency installs for security scan runners');
 }
@@ -83,18 +104,226 @@ function normalizeCliOptions(raw) {
         failOnWarning: Boolean(raw.failOnWarning),
     };
 }
+function withInferredSecurityScanSkills(scanOptions, skillFilePaths) {
+    if (scanOptions.skills && scanOptions.skills.length > 0) {
+        return scanOptions;
+    }
+    const inferredSkills = deriveAgentScanSkillRoots(skillFilePaths);
+    if (inferredSkills.length === 0) {
+        return scanOptions;
+    }
+    const [selectedSkillRoot] = inferredSkills;
+    if (!selectedSkillRoot) {
+        return scanOptions;
+    }
+    return {
+        ...scanOptions,
+        skills: [selectedSkillRoot],
+    };
+}
 function parseCommaSeparated(value) {
     return value
         .split(',')
         .map((entry) => entry.trim())
         .filter(Boolean);
 }
+export function normalizeRootCommandArgs(argv) {
+    if (argv.length === 0) {
+        return ['check', '.'];
+    }
+    const [first] = argv;
+    if (!first || ROOT_COMMANDS.has(first)) {
+        return argv;
+    }
+    if (first === '-h' || first === '--help') {
+        return argv;
+    }
+    if (first.startsWith('-')) {
+        return ['check', '.', ...argv];
+    }
+    return ['check', ...argv];
+}
+function shellQuoteArg(value) {
+    if (value.length === 0) {
+        return "''";
+    }
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) {
+        return value;
+    }
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+function buildShareableRunCommand(args) {
+    if (args.length === 0) {
+        return 'npx skill-check';
+    }
+    return `npx skill-check ${args.map(shellQuoteArg).join(' ')}`;
+}
 function normalizeCheckCommandOptions(raw) {
     return {
         fix: raw.fix === true,
         interactive: raw.interactive === true,
+        share: raw.share === true,
+        shareOut: typeof raw.shareOut === 'string' ? raw.shareOut : undefined,
+    };
+}
+function normalizeSplitBodyCommandOptions(raw) {
+    return {
+        write: raw.write === true,
+    };
+}
+function resolveCommandTarget(target, options = {}) {
+    if (!target || !isGitHubRepoUrl(target)) {
+        return {
+            target,
+            isRemote: false,
+        };
+    }
+    const materialized = materializeRemoteTarget(target, {
+        onProgress: options.onProgress,
+    });
+    return {
+        target: materialized.path,
+        isRemote: true,
+        cleanup: materialized.cleanup,
     };
 }
+async function withResolvedTarget(target, run) {
+    const resolved = resolveCommandTarget(target);
+    try {
+        return await run(resolved);
+    }
+    finally {
+        resolved.cleanup?.();
+    }
+}
+function toErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function createRemoteTargetLoader(io) {
+    const useSpinner = shouldUseInteractiveUi(io);
+    const spinner = useSpinner ? ora() : null;
+    let finished = false;
+    let failedViaEvent = false;
+    const write = (message) => {
+        io.stderr(`${message}\n`);
+    };
+    const update = (message) => {
+        if (finished)
+            return;
+        if (spinner) {
+            if (spinner.isSpinning) {
+                spinner.text = message;
+            }
+            else {
+                spinner.start(message);
+            }
+            return;
+        }
+        write(`[remote] ${message}`);
+    };
+    const writeSpinnerPersistentLine = (message) => {
+        if (!spinner)
+            return;
+        write(`[remote] ${message}`);
+    };
+    const succeed = (message) => {
+        if (finished)
+            return;
+        if (spinner) {
+            if (spinner.isSpinning) {
+                spinner.succeed(message);
+            }
+            else {
+                write(`[remote] ${message}`);
+            }
+        }
+        else {
+            write(`[remote] ${message}`);
+        }
+        finished = true;
+    };
+    const failInternal = (message) => {
+        if (finished)
+            return;
+        if (spinner) {
+            if (spinner.isSpinning) {
+                spinner.fail(message);
+            }
+            else {
+                write(`[remote] ${message}`);
+            }
+        }
+        else {
+            write(`[remote] ${message}`);
+        }
+        finished = true;
+    };
+    return {
+        start: (url) => {
+            const message = `Preparing remote target: ${url}`;
+            writeSpinnerPersistentLine(message);
+            update(message);
+        },
+        onProgress: (event) => {
+            if (event.type === 'clone_start') {
+                const refLabel = event.ref ? ` (ref: ${event.ref})` : '';
+                const message = `Cloning ${event.cloneUrl}${refLabel}`;
+                writeSpinnerPersistentLine(message);
+                update(message);
+                return;
+            }
+            if (event.type === 'clone_done') {
+                const message = `Clone complete: ${event.checkoutPath}`;
+                writeSpinnerPersistentLine(message);
+                update(message);
+                return;
+            }
+            if (event.type === 'subpath_start') {
+                const message = `Resolving subpath: ${event.subpath}`;
+                writeSpinnerPersistentLine(message);
+                update(message);
+                return;
+            }
+            if (event.type === 'ready') {
+                succeed(`Remote target ready: ${event.targetPath}`);
+                return;
+            }
+            failedViaEvent = true;
+            failInternal(`Remote target failed: ${event.message}`);
+        },
+        fail: (error) => {
+            if (failedViaEvent)
+                return;
+            failInternal(`Remote target failed: ${toErrorMessage(error)}`);
+        },
+    };
+}
+async function withResolvedTargetFeedback(target, io, run) {
+    if (!target || !isGitHubRepoUrl(target)) {
+        return withResolvedTarget(target, run);
+    }
+    const loader = createRemoteTargetLoader(io);
+    loader.start(target);
+    let resolved;
+    try {
+        resolved = resolveCommandTarget(target, {
+            onProgress: (event) => loader.onProgress(event),
+        });
+        return await run(resolved);
+    }
+    catch (error) {
+        loader.fail(error);
+        throw error;
+    }
+    finally {
+        resolved?.cleanup?.();
+    }
+}
+function assertLocalOnlyTarget(target, commandName) {
+    if (!target || !isGitHubRepoUrl(target))
+        return;
+    throw new CliError(`${commandName} does not support GitHub URL targets yet. Clone locally and re-run ${commandName}.`, 2);
+}
 async function runInteractiveInit(cwd, target, options) {
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new CliError('Interactive init requires a TTY. Run without --interactive in non-interactive environments.', 2);
@@ -190,7 +419,8 @@ function normalizeAgentScanOptions(raw) {
         mode,
         paths: selectedPaths,
         skills: selectedSkills,
-        installPolicy: denyInstalls ? 'deny' : allowInstalls ? 'allow' : 'ask',
+        verbose: raw.securityScanVerbose === true,
+        installPolicy: denyInstalls ? 'deny' : 'allow',
     };
 }
 function shouldUseInteractiveUi(io) {
@@ -210,6 +440,37 @@ function shouldRenderBanner(io, format) {
         !isTruthyFlag(process.env.CI) &&
         !isTruthyFlag(process.env.SKILL_CHECK_NO_BANNER));
 }
+function emitShareStatus(io, message) {
+    io.stderr(`${pc.dim(`share: ${message}`)}\n`);
+}
+function renderAgentScanCompactSummary(summary, verboseHint = true) {
+    const lines = [];
+    if (summary.noSkillsOrServers) {
+        lines.push(`${pc.bold('Security scan summary:')} ${pc.yellow('no servers or skills found')}`);
+    }
+    else {
+        const skillsValue = typeof summary.skillsFound === 'number'
+            ? String(summary.skillsFound)
+            : 'unknown';
+        const targetText = summary.scannedTarget
+            ? pc.dim(summary.scannedTarget)
+            : pc.dim('(unknown target)');
+        lines.push(`${pc.bold('Security scan summary:')} skills=${pc.cyan(skillsValue)} target=${targetText}`);
+    }
+    const codes = Object.entries(summary.findingsByCode)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([code, count]) => `${code}:${count}`);
+    if (summary.findingsTotal > 0) {
+        lines.push(`${pc.bold('Findings:')} ${pc.yellow(String(summary.findingsTotal))}${codes.length > 0 ? ` ${pc.dim(`(${codes.join(', ')})`)}` : ''}`);
+    }
+    else {
+        lines.push(`${pc.bold('Findings:')} ${pc.green('0')}`);
+    }
+    if (verboseHint) {
+        lines.push(pc.dim('Use --security-scan-verbose to view full scanner output.'));
+    }
+    return `${lines.join('\n')}\n`;
+}
 function renderAsciiBanner() {
     const art = [
         '  ____  _  _____ _     _        ____ _   _ _____ ____ _  __',
@@ -236,34 +497,13 @@ function renderAutoFixSummary(summary) {
     }
     return `${lines.join('\n')}\n\n`;
 }
-function formatInvocation(invocation) {
-    return [invocation.command, ...invocation.args]
-        .map((part) => (part.includes(' ') ? `"${part}"` : part))
-        .join(' ');
-}
-async function ensureSecurityScanInstallConsent(scanOptions, invocation, io, format) {
+async function ensureSecurityScanInstallConsent(scanOptions, invocation) {
     const mayInstallDependency = invocation.command !== 'mcp-scan' && !isCommandAvailable('mcp-scan');
     if (!mayInstallDependency)
         return;
     if (scanOptions.installPolicy === 'allow')
         return;
-    const guidance = 'Re-run with --allow-installs, install mcp-scan manually, or skip scan with --no-security-scan.';
-    if (scanOptions.installPolicy === 'deny') {
-        throw new CliError(`Security scan may install dependencies via ${invocation.command}. ${guidance}`, 2);
-    }
-    const interactivePromptAllowed = shouldUseInteractiveUi(io) &&
-        format === 'text' &&
-        !isTruthyFlag(process.env.CI);
-    if (!interactivePromptAllowed) {
-        throw new CliError(`Security scan may install dependencies via ${invocation.command} but interactive approval is unavailable. ${guidance}`, 2);
-    }
-    const accepted = await confirm({
-        message: `Security scan may install "mcp-scan" with: ${formatInvocation(invocation)}. Continue?`,
-        initialValue: false,
-    });
-    if (isCancel(accepted) || !accepted) {
-        throw new CliError('Security scan install was declined. Re-run with --no-security-scan or --allow-installs.', 2);
-    }
+    throw new CliError(`Security scan may install dependencies via ${invocation.command}. Re-run without --no-installs, install mcp-scan manually, or skip scan with --no-security-scan.`, 2);
 }
 async function runValidationPipeline(cwd, config, interactiveUi) {
     const useTaskUi = interactiveUi && config.output.format === 'text';
@@ -286,6 +526,25 @@ async function runValidationPipeline(cwd, config, interactiveUi) {
     }
     return context.result;
 }
+async function runValidationForShare(cwd, config, io) {
+    const interactiveUi = shouldUseInteractiveUi(io);
+    if (interactiveUi) {
+        const spinner = ora('Preparing share output: validating skills...').start();
+        try {
+            const result = await analyzeWithConfig(cwd, config);
+            spinner.succeed(`Validated ${result.summary.skillCount} skill(s); diagnostics ${result.diagnostics.length}.`);
+            return result;
+        }
+        catch (error) {
+            spinner.fail('Validation failed.');
+            throw error;
+        }
+    }
+    emitShareStatus(io, 'validating skills...');
+    const result = await analyzeWithConfig(cwd, config);
+    emitShareStatus(io, `validated ${result.summary.skillCount} skill(s); diagnostics ${result.diagnostics.length}.`);
+    return result;
+}
 async function runAgentScanWithFeedback(scanOptions, target, io, format) {
     const useInteractiveFeedback = shouldUseInteractiveUi(io) && format === 'text';
     const invocation = resolveAgentScanInvocation({
@@ -299,19 +558,21 @@ async function runAgentScanWithFeedback(scanOptions, target, io, format) {
     if (format === 'text') {
         io.stdout(`${pc.dim('Security scan engine:')} ${pc.bold('agent-scan (mcp-scan)')} ${pc.dim('via')} ${pc.cyan(invocation.command)}\n`);
     }
-    await ensureSecurityScanInstallConsent(scanOptions, invocation, io, format);
+    await ensureSecurityScanInstallConsent(scanOptions, invocation);
     if (useInteractiveFeedback) {
         ora().info('Running security scan...');
     }
     try {
-        const exitCode = runAgentScan({
+        const scanResult = runAgentScan({
             cwd: process.cwd(),
             targetPath: target,
             mode: scanOptions.mode,
             runner: scanOptions.runner,
             paths: scanOptions.paths,
             skills: scanOptions.skills,
+            verbose: scanOptions.verbose,
         });
+        const exitCode = scanResult.status;
         if (useInteractiveFeedback) {
             if (exitCode === 0) {
                 ora().succeed('Security scan completed without blocking findings.');
@@ -320,6 +581,20 @@ async function runAgentScanWithFeedback(scanOptions, target, io, format) {
                 ora().warn('Security scan reported findings.');
             }
         }
+        if (!scanOptions.verbose && format === 'text') {
+            const combinedOutput = `${scanResult.stdout}\n${scanResult.stderr}`.trim();
+            const summary = summarizeAgentScanOutput(combinedOutput);
+            io.stdout(renderAgentScanCompactSummary(summary));
+        }
+        if (!scanOptions.verbose && format !== 'text' && exitCode !== 0) {
+            const combinedOutput = `${scanResult.stdout}\n${scanResult.stderr}`.trim();
+            if (combinedOutput) {
+                const tail = combinedOutput.split(/\r?\n/).slice(-8).join('\n').trim();
+                if (tail) {
+                    io.stderr(`${tail}\n`);
+                }
+            }
+        }
         return exitCode;
     }
     catch (error) {
@@ -329,7 +604,44 @@ async function runAgentScanWithFeedback(scanOptions, target, io, format) {
         throw error;
     }
 }
+function resolveValidationStatus(result) {
+    if (result.summary.errorCount > 0)
+        return 'FAIL';
+    if (result.summary.warningCount > 0)
+        return 'WARN';
+    return 'PASS';
+}
+function resolveSecurityStatus(enabled, scanExitCode) {
+    if (!enabled)
+        return 'SKIPPED';
+    return scanExitCode === 0 ? 'PASS' : 'FAIL';
+}
+function computeOverallScore(scores) {
+    if (scores.length === 0)
+        return null;
+    const total = scores.reduce((sum, score) => sum + score.score, 0);
+    return Math.round(total / scores.length);
+}
+function countAffectedFiles(diagnostics) {
+    return new Set(diagnostics.map((diagnostic) => diagnostic.file)).size;
+}
+function formatSourceRange(range) {
+    return `${range.startLine}-${range.endLine}`;
+}
+function toErrorText(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function renderSplitPlanLine(plan, maxBodyLines) {
+    if (plan.status === 'noop') {
+        return `${pc.cyan('[NOOP]')} ${plan.skillRelativePath} body lines ${plan.beforeLineCount} <= max ${maxBodyLines}\n`;
+    }
+    if (plan.status === 'blocked') {
+        return `${pc.red('[BLOCKED]')} ${plan.skillRelativePath} ${plan.reason ?? 'Cannot split body automatically.'}\n`;
+    }
+    return `${pc.green('[PLAN]')} ${plan.skillRelativePath} lines ${plan.beforeLineCount} -> ${plan.afterLineCount}\n`;
+}
 export async function runCli(argv, io = defaultIO) {
+    const originalArgv = [...argv];
     const program = new Command();
     let finalExitCode = 0;
     let bannerRendered = false;
@@ -351,182 +663,325 @@ export async function runCli(argv, io = defaultIO) {
         .description('Run validation checks')
         .option('--fix', 'Apply safe automatic fixes for supported validation findings')
         .option('--interactive', 'Prompt before applying each fix (use with --fix)')
+        .option('--share', 'Render a share card (text format only)')
+        .option('--share-out <path>', 'Write share card image file (default: ./skill-check-share.png)')
         .option('--no-open', 'Do not open HTML report in browser')
         .option('--baseline <path>', 'Compare against a previous JSON run')
         .action(async (target, rawOptions) => {
+        const checkStartedAt = performance.now();
+        const runCommand = buildShareableRunCommand(originalArgv);
         const options = normalizeCliOptions(rawOptions);
         const checkOptions = normalizeCheckCommandOptions(rawOptions);
         const scanOptions = normalizeAgentScanOptions(rawOptions);
-        const config = await resolveConfig(process.cwd(), target, options);
-        maybeRenderBanner(config.output.format);
-        let result = await runValidationPipeline(process.cwd(), config, shouldUseInteractiveUi(io));
-        let fixSummary;
-        if (checkOptions.fix) {
-            if (checkOptions.interactive && shouldUseInteractiveUi(io)) {
-                const { accepted, skipped } = await selectFixableDiagnostics(result);
-                if (accepted.length > 0) {
-                    const filteredResult = {
-                        ...result,
-                        diagnostics: accepted,
-                    };
-                    fixSummary = applyAutoFixes(filteredResult);
-                    fixSummary.unsupportedDiagnostics +=
-                        result.diagnostics.length - accepted.length - skipped;
+        if (checkOptions.fix && target && isGitHubRepoUrl(target)) {
+            throw new CliError('Cannot use --fix with a GitHub URL target. Clone locally to apply persistent fixes.', 2);
+        }
+        await withResolvedTargetFeedback(target, io, async (resolvedTarget) => {
+            const cwd = resolvedTarget.isRemote && resolvedTarget.target
+                ? resolvedTarget.target
+                : process.cwd();
+            const config = await resolveConfig(cwd, resolvedTarget.target, options);
+            if (!checkOptions.share) {
+                maybeRenderBanner(config.output.format);
+            }
+            if (checkOptions.share && config.output.format !== 'text') {
+                throw new CliError('--share requires text output format.', 2);
+            }
+            if (checkOptions.shareOut && !checkOptions.share) {
+                throw new CliError('--share-out requires --share.', 2);
+            }
+            const runValidation = async () => {
+                if (checkOptions.share) {
+                    return runValidationForShare(cwd, config, io);
+                }
+                return runValidationPipeline(cwd, config, shouldUseInteractiveUi(io));
+            };
+            let result = await runValidation();
+            let fixSummary;
+            if (checkOptions.fix) {
+                if (checkOptions.interactive && shouldUseInteractiveUi(io)) {
+                    const { accepted, skipped } = await selectFixableDiagnostics(result);
+                    if (accepted.length > 0) {
+                        const filteredResult = {
+                            ...result,
+                            diagnostics: accepted,
+                        };
+                        fixSummary = applyAutoFixes(filteredResult);
+                        fixSummary.unsupportedDiagnostics +=
+                            result.diagnostics.length - accepted.length - skipped;
+                    }
+                    else {
+                        fixSummary = {
+                            requestedDiagnostics: result.diagnostics.length,
+                            supportedDiagnostics: 0,
+                            unsupportedDiagnostics: result.diagnostics.length,
+                            appliedFixes: 0,
+                            filesUpdated: 0,
+                            updatedFiles: [],
+                        };
+                    }
                 }
                 else {
-                    fixSummary = {
-                        requestedDiagnostics: result.diagnostics.length,
-                        supportedDiagnostics: 0,
-                        unsupportedDiagnostics: result.diagnostics.length,
-                        appliedFixes: 0,
-                        filesUpdated: 0,
-                        updatedFiles: [],
+                    fixSummary = applyAutoFixes(result);
+                }
+                if (fixSummary.appliedFixes > 0) {
+                    result = await runValidation();
+                }
+            }
+            const duplicateDiags = detectDuplicates(result.skills);
+            if (duplicateDiags.length > 0) {
+                result = {
+                    ...result,
+                    diagnostics: [...result.diagnostics, ...duplicateDiags],
+                    summary: {
+                        ...result.summary,
+                        warningCount: result.summary.warningCount +
+                            duplicateDiags.filter((d) => d.severity === 'warn')
+                                .length,
+                        errorCount: result.summary.errorCount +
+                            duplicateDiags.filter((d) => d.severity === 'error')
+                                .length,
+                    },
+                };
+            }
+            const scores = computeSkillScores(result.skills, result.diagnostics);
+            const format = result.config.output.format;
+            let baselineDiff;
+            const baselinePath = typeof rawOptions.baseline === 'string'
+                ? rawOptions.baseline
+                : undefined;
+            if (baselinePath) {
+                const baselineDiags = loadBaseline(path.resolve(process.cwd(), baselinePath));
+                baselineDiff = diffBaseline(result.diagnostics, baselineDiags);
+            }
+            if (format === 'json') {
+                const jsonData = toJson(result);
+                jsonData.scores = scores;
+                if (baselineDiff) {
+                    jsonData.baseline = {
+                        new: baselineDiff.newDiagnostics.length,
+                        fixed: baselineDiff.fixedDiagnostics.length,
+                        unchanged: baselineDiff.unchanged.length,
                     };
                 }
+                const output = `${JSON.stringify(jsonData, null, 2)}\n`;
+                io.stdout(output);
+                const written = writeIfRequested(result.config, output);
+                if (written)
+                    io.stdout(`Wrote ${written}\n`);
+            }
+            else if (format === 'sarif') {
+                const output = `${JSON.stringify(toSarif(result), null, 2)}\n`;
+                io.stdout(output);
+                const written = writeIfRequested(result.config, output);
+                if (written)
+                    io.stdout(`Wrote ${written}\n`);
+            }
+            else if (format === 'github') {
+                const output = toGitHubAnnotations(result);
+                if (output)
+                    io.stdout(output);
+            }
+            else if (format === 'html') {
+                const html = renderHtml(result, scores);
+                const reportPath = result.config.output.reportPath ??
+                    path.join(result.config.cwd, 'skill-check-report.html');
+                const parent = path.dirname(reportPath);
+                fs.mkdirSync(parent, { recursive: true });
+                fs.writeFileSync(reportPath, html);
+                const shouldOpen = Boolean(process.stdout.isTTY) &&
+                    !process.env.CI &&
+                    rawOptions.noOpen !== true;
+                if (shouldOpen) {
+                    try {
+                        openInBrowser(reportPath);
+                    }
+                    catch {
+                        // ignore open failures
+                    }
+                }
+                io.stdout(`Wrote ${reportPath}\n`);
             }
             else {
-                fixSummary = applyAutoFixes(result);
+                if (!checkOptions.share) {
+                    if (fixSummary) {
+                        io.stdout(renderAutoFixSummary(fixSummary));
+                    }
+                    io.stdout(renderText(result, scores, {
+                        includeConclusion: false,
+                    }));
+                }
             }
-            if (fixSummary.appliedFixes > 0) {
-                result = await runValidationPipeline(process.cwd(), config, shouldUseInteractiveUi(io));
+            if (baselineDiff && (format === 'text' || format === 'html')) {
+                io.stdout(`${pc.bold('Baseline:')} ${pc.green(`${baselineDiff.fixedDiagnostics.length} fixed`)} ${pc.red(`${baselineDiff.newDiagnostics.length} new`)} ${pc.dim(`${baselineDiff.unchanged.length} unchanged`)}\n`);
             }
-        }
-        const duplicateDiags = detectDuplicates(result.skills);
-        if (duplicateDiags.length > 0) {
-            result = {
-                ...result,
-                diagnostics: [...result.diagnostics, ...duplicateDiags],
-                summary: {
-                    ...result.summary,
-                    warningCount: result.summary.warningCount +
-                        duplicateDiags.filter((d) => d.severity === 'warn').length,
-                    errorCount: result.summary.errorCount +
-                        duplicateDiags.filter((d) => d.severity === 'error').length,
-                },
-            };
-        }
-        const scores = computeSkillScores(result.skills, result.diagnostics);
-        const format = result.config.output.format;
-        let baselineDiff;
-        const baselinePath = typeof rawOptions.baseline === 'string'
-            ? rawOptions.baseline
-            : undefined;
-        if (baselinePath) {
-            const baselineDiags = loadBaseline(path.resolve(process.cwd(), baselinePath));
-            baselineDiff = diffBaseline(result.diagnostics, baselineDiags);
-        }
-        if (format === 'json') {
-            const jsonData = toJson(result);
-            jsonData.scores = scores;
-            if (baselineDiff) {
-                jsonData.baseline = {
-                    new: baselineDiff.newDiagnostics.length,
-                    fixed: baselineDiff.fixedDiagnostics.length,
-                    unchanged: baselineDiff.unchanged.length,
-                };
+            const validationExitCode = resolveExitCode(result);
+            let exitCode = validationExitCode;
+            if (format === 'html') {
+                io.stdout(`${pc.bold('Validation:')} ${validationExitCode === 0 ? pc.green('PASS') : pc.red('FAIL')}\n`);
             }
-            const output = `${JSON.stringify(jsonData, null, 2)}\n`;
-            io.stdout(output);
-            const written = writeIfRequested(result.config, output);
-            if (written)
-                io.stdout(`Wrote ${written}\n`);
-        }
-        else if (format === 'sarif') {
-            const output = `${JSON.stringify(toSarif(result), null, 2)}\n`;
-            io.stdout(output);
-            const written = writeIfRequested(result.config, output);
-            if (written)
-                io.stdout(`Wrote ${written}\n`);
-        }
-        else if (format === 'github') {
-            const output = toGitHubAnnotations(result);
-            if (output)
-                io.stdout(output);
-        }
-        else if (format === 'html') {
-            const html = renderHtml(result, scores);
-            const reportPath = result.config.output.reportPath ??
-                path.join(result.config.cwd, 'skill-check-report.html');
-            const parent = path.dirname(reportPath);
-            fs.mkdirSync(parent, { recursive: true });
-            fs.writeFileSync(reportPath, html);
-            const shouldOpen = Boolean(process.stdout.isTTY) &&
-                !process.env.CI &&
-                rawOptions.noOpen !== true;
-            if (shouldOpen) {
-                try {
-                    openInBrowser(reportPath);
+            let scanExitCode;
+            if (scanOptions.enabled) {
+                if (checkOptions.share) {
+                    emitShareStatus(io, 'running security scan...');
                 }
-                catch {
-                    // ignore open failures
+                const effectiveScanOptions = withInferredSecurityScanSkills(scanOptions, result.skills.map((skill) => skill.filePath));
+                scanExitCode = await runAgentScanWithFeedback(effectiveScanOptions, resolvedTarget.target, io, format);
+                if (format === 'html') {
+                    io.stdout(`${pc.bold('Security scan:')} ${scanExitCode === 0 ? pc.green('PASS') : pc.red('FAIL')}\n`);
+                }
+                if (scanExitCode !== 0) {
+                    exitCode = 1;
                 }
             }
-            io.stdout(`Wrote ${reportPath}\n`);
-        }
-        else {
-            if (fixSummary) {
-                io.stdout(renderAutoFixSummary(fixSummary));
+            else if (format === 'html') {
+                io.stdout(`${pc.bold('Security scan:')} ${pc.yellow('SKIPPED')}\n`);
             }
-            io.stdout(renderText(result, scores));
-        }
-        if (baselineDiff && (format === 'text' || format === 'html')) {
-            io.stdout(`${pc.bold('Baseline:')} ${pc.green(`${baselineDiff.fixedDiagnostics.length} fixed`)} ${pc.red(`${baselineDiff.newDiagnostics.length} new`)} ${pc.dim(`${baselineDiff.unchanged.length} unchanged`)}\n`);
-        }
-        const validationExitCode = resolveExitCode(result);
-        let exitCode = validationExitCode;
-        if (format === 'text' || format === 'html') {
-            io.stdout(`${pc.bold('Validation:')} ${validationExitCode === 0 ? pc.green('PASS') : pc.red('FAIL')}\n`);
+            else if (checkOptions.share) {
+                emitShareStatus(io, 'security scan skipped.');
+            }
+            if (format === 'text') {
+                const conclusion = renderConclusionCard({
+                    skillCount: result.summary.skillCount,
+                    errorCount: result.summary.errorCount,
+                    warningCount: result.summary.warningCount,
+                    affectedFileCount: countAffectedFiles(result.diagnostics),
+                    overallScore: computeOverallScore(scores),
+                    validationStatus: resolveValidationStatus(result),
+                    securityStatus: resolveSecurityStatus(scanOptions.enabled, scanExitCode),
+                    elapsedMs: performance.now() - checkStartedAt,
+                    runCommand,
+                    mode: checkOptions.share ? 'share' : 'default',
+                });
+                io.stdout(`${conclusion.card}\n`);
+                if (conclusion.fullCommandPlain) {
+                    io.stdout(`${conclusion.fullCommandPlain}\n`);
+                }
+                if (checkOptions.share) {
+                    emitShareStatus(io, 'rendering share image...');
+                    const shareOutputPath = path.resolve(process.cwd(), checkOptions.shareOut ?? 'skill-check-share.png');
+                    const shareText = conclusion.fullCommandPlain
+                        ? `${conclusion.card}\n${conclusion.fullCommandPlain}`
+                        : conclusion.card;
+                    const writtenPath = writeShareImage(shareText, shareOutputPath);
+                    io.stdout(`${pc.bold('Share image:')} ${writtenPath}\n`);
+                    emitShareStatus(io, `share image written: ${writtenPath}`);
+                }
+            }
+            finalExitCode = exitCode;
+        });
+    })));
+    program
+        .command('split-body [target]')
+        .description('Preview or apply section-based body split into references/*.md files')
+        .option('--write', 'Apply split changes to files')
+        .option('--config <path>', 'Path to skill-check config file')
+        .option('--max-body-lines <n>', 'Override max body lines', parseNumber)
+        .option('--include <glob>', 'Additional include glob(s)', collectList, [])
+        .option('--exclude <glob>', 'Additional exclude glob(s)', collectList, [])
+        .action(async (target, rawOptions) => {
+        assertLocalOnlyTarget(target, 'split-body');
+        const splitOptions = normalizeSplitBodyCommandOptions(rawOptions);
+        const options = normalizeCliOptions(rawOptions);
+        if (options.format) {
+            throw new CliError('split-body does not support --format. It always prints text output.', 2);
         }
-        if (scanOptions.enabled) {
-            const scanExitCode = await runAgentScanWithFeedback(scanOptions, target, io, format);
-            if (format === 'text' || format === 'html') {
-                io.stdout(`${pc.bold('Security scan:')} ${scanExitCode === 0 ? pc.green('PASS') : pc.red('FAIL')}\n`);
+        const config = await resolveConfig(process.cwd(), target, options);
+        const skillFiles = await discoverSkillFiles(config);
+        const skills = skillFiles.map((filePath) => buildSkillArtifact(filePath, config.cwd));
+        const plans = skills.map((skill) => planBodySplit(skill, config.limits.maxBodyLines));
+        io.stdout(`${pc.bold('split-body')} ${pc.dim(splitOptions.write ? 'apply' : 'preview')}\n`);
+        io.stdout(`${pc.dim('max-body-lines:')} ${config.limits.maxBodyLines}\n`);
+        io.stdout(`${pc.dim('skills evaluated:')} ${skills.length}\n\n`);
+        let plannedCount = 0;
+        let blockedCount = 0;
+        let noopCount = 0;
+        let writtenSkillCount = 0;
+        let writtenReferenceCount = 0;
+        for (const plan of plans) {
+            io.stdout(renderSplitPlanLine(plan, config.limits.maxBodyLines));
+            if (plan.status === 'blocked') {
+                blockedCount += 1;
+                continue;
+            }
+            if (plan.status === 'noop') {
+                noopCount += 1;
+                continue;
+            }
+            plannedCount += 1;
+            for (const reference of plan.referencesToCreate) {
+                const details = `(${reference.relativePath}, source lines ${formatSourceRange(reference.sourceLineRange)})`;
+                if (splitOptions.write) {
+                    io.stdout(`  ${pc.green('create')} ${details}\n`);
+                }
+                else {
+                    io.stdout(`  ${pc.dim('would create')} ${details}\n`);
+                }
+            }
+            if (splitOptions.write) {
+                try {
+                    const applied = applyBodySplitPlan(plan);
+                    if (applied.updatedSkill) {
+                        writtenSkillCount += 1;
+                    }
+                    writtenReferenceCount += applied.writtenReferenceFiles.length;
+                }
+                catch (error) {
+                    throw new CliError(`Failed to write split-body output for ${plan.skillRelativePath}: ${toErrorText(error)}`, 1);
+                }
             }
-            if (scanExitCode !== 0) {
-                exitCode = 1;
+            if (plan.afterLineCount > config.limits.maxBodyLines) {
+                io.stdout(`${pc.yellow('[WARN]')} ${plan.skillRelativePath} still exceeds limit after split. Refine with docs/skills/split-into-references/SKILL.md.\n`);
             }
         }
-        else if (format === 'text' || format === 'html') {
-            io.stdout(`${pc.bold('Security scan:')} ${pc.yellow('SKIPPED')}\n`);
+        io.stdout('\n');
+        io.stdout(`${pc.bold('Summary:')} planned=${plannedCount} blocked=${blockedCount} noop=${noopCount}\n`);
+        if (splitOptions.write) {
+            io.stdout(`${pc.bold('Writes:')} updated_skills=${writtenSkillCount} created_references=${writtenReferenceCount}\n`);
         }
-        finalExitCode = exitCode;
-    })));
+        finalExitCode = blockedCount > 0 ? 2 : 0;
+    });
     addSharedOptions(program
         .command('report [target]')
         .description('Generate markdown health report')
         .option('--no-open', 'Do not open HTML report in browser')
         .action(async (target, rawOptions) => {
         const options = normalizeCliOptions(rawOptions);
-        const result = await analyze(process.cwd(), target, options);
-        const format = result.config.output.format;
-        if (format === 'html') {
-            const html = renderHtml(result);
-            const reportPath = result.config.output.reportPath ??
-                path.join(result.config.cwd, 'skill-check-report.html');
-            const parent = path.dirname(reportPath);
-            fs.mkdirSync(parent, { recursive: true });
-            fs.writeFileSync(reportPath, html);
-            const shouldOpen = Boolean(process.stdout.isTTY) &&
-                !process.env.CI &&
-                rawOptions.noOpen !== true;
-            if (shouldOpen) {
-                try {
-                    openInBrowser(reportPath);
-                }
-                catch {
-                    // ignore open failures
+        await withResolvedTargetFeedback(target, io, async (resolvedTarget) => {
+            const cwd = resolvedTarget.isRemote && resolvedTarget.target
+                ? resolvedTarget.target
+                : process.cwd();
+            const result = await analyze(cwd, resolvedTarget.target, options);
+            const format = result.config.output.format;
+            if (format === 'html') {
+                const html = renderHtml(result);
+                const reportPath = result.config.output.reportPath ??
+                    path.join(result.config.cwd, 'skill-check-report.html');
+                const parent = path.dirname(reportPath);
+                fs.mkdirSync(parent, { recursive: true });
+                fs.writeFileSync(reportPath, html);
+                const shouldOpen = Boolean(process.stdout.isTTY) &&
+                    !process.env.CI &&
+                    rawOptions.noOpen !== true;
+                if (shouldOpen) {
+                    try {
+                        openInBrowser(reportPath);
+                    }
+                    catch {
+                        // ignore open failures
+                    }
                 }
+                io.stdout(`Wrote ${reportPath}\n`);
             }
-            io.stdout(`Wrote ${reportPath}\n`);
-        }
-        else {
-            const markdown = renderMarkdownReport(result);
-            const written = writeIfRequested(result.config, markdown);
-            io.stdout(markdown);
-            if (written)
-                io.stdout(`Wrote ${written}\n`);
-        }
-        finalExitCode = resolveExitCode(result);
+            else {
+                const markdown = renderMarkdownReport(result);
+                const written = writeIfRequested(result.config, markdown);
+                io.stdout(markdown);
+                if (written)
+                    io.stdout(`Wrote ${written}\n`);
+            }
+            finalExitCode = resolveExitCode(result);
+        });
     }));
     addAgentScanOptions(program
         .command('security-scan [target]')
@@ -537,8 +992,16 @@ export async function runCli(argv, io = defaultIO) {
             securityScan: true,
         });
         maybeRenderBanner('text');
-        const scanExitCode = await runAgentScanWithFeedback(scanOptions, target, io, 'text');
-        finalExitCode = scanExitCode === 0 ? 0 : 1;
+        await withResolvedTargetFeedback(target, io, async (resolvedTarget) => {
+            const scanCwd = resolvedTarget.isRemote && resolvedTarget.target
+                ? resolvedTarget.target
+                : process.cwd();
+            const discoveryConfig = await resolveConfig(scanCwd, resolvedTarget.target, {});
+            const discoveredSkillFiles = await discoverSkillFiles(discoveryConfig);
+            const effectiveScanOptions = withInferredSecurityScanSkills(scanOptions, discoveredSkillFiles);
+            const scanExitCode = await runAgentScanWithFeedback(effectiveScanOptions, resolvedTarget.target, io, 'text');
+            finalExitCode = scanExitCode === 0 ? 0 : 1;
+        });
     }));
     program
         .command('rules [ruleId]')
@@ -610,6 +1073,8 @@ export async function runCli(argv, io = defaultIO) {
         .command('diff <pathA> <pathB>')
         .description('Compare diagnostics between two skill directories')
         .action(async (pathA, pathB) => {
+        assertLocalOnlyTarget(pathA, 'diff');
+        assertLocalOnlyTarget(pathB, 'diff');
         const resultA = await analyze(process.cwd(), pathA, {});
         const resultB = await analyze(process.cwd(), pathB, {});
         const keyFn = (d) => `${d.ruleId}|${d.message}`;
@@ -640,15 +1105,19 @@ export async function runCli(argv, io = defaultIO) {
         .command('watch [target]')
         .description('Watch for changes and re-run validation')
         .action(async (target, rawOptions) => {
+        assertLocalOnlyTarget(target, 'watch');
         const options = normalizeCliOptions(rawOptions);
         const config = await resolveConfig(process.cwd(), target, options);
         const watchDirs = config.rootsAbs.length > 0 ? config.rootsAbs : [config.cwd];
         io.stdout(`${pc.cyan('Watching')} ${watchDirs.join(', ')} for changes...\n`);
         const runCheck = async () => {
             try {
+                const startedAt = performance.now();
                 const result = await analyzeWithConfig(process.cwd(), config);
                 const scores = computeSkillScores(result.skills, result.diagnostics);
-                io.stdout(`\n${renderText(result, scores)}`);
+                io.stdout(`\n${renderText(result, scores, {
+                    elapsedMs: performance.now() - startedAt,
+                })}`);
             }
             catch (err) {
                 io.stderr(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -696,7 +1165,8 @@ export async function runCli(argv, io = defaultIO) {
         finalExitCode = 0;
     });
     try {
-        await program.parseAsync(argv, { from: 'user' });
+        const normalizedArgv = normalizeRootCommandArgs(argv);
+        await program.parseAsync(normalizedArgv, { from: 'user' });
         return finalExitCode;
     }
     catch (error) {