vigiles 2.0.0 → 2.2.0

package/dist/cli.js

@@ -15,17 +15,25 @@ const node_path_1 = require("node:path");
 const glob_1 = require("glob");
 const generate_types_js_1 = require("./generate-types.js");
 const validate_js_1 = require("./validate.js");
+const types_js_1 = require("./types.js");
 const compile_js_1 = require("./compile.js");
 const proofs_js_1 = require("./proofs.js");
 const inline_js_1 = require("./inline.js");
+const frontmatter_js_1 = require("./frontmatter.js");
+const generate_schema_js_1 = require("./generate-schema.js");
+const compile_generator_js_1 = require("./compile-generator.js");
+const action_gate_js_1 = require("./action-gate.js");
+const refs_js_1 = require("./refs.js");
+const skill_runtime_js_1 = require("./skill-runtime.js");
 const linters_js_1 = require("./linters.js");
-const freshness_js_1 = require("./freshness.js");
+const integrity_js_1 = require("./integrity.js");
+const coverage_js_1 = require("./coverage.js");
+const orphans_js_1 = require("./orphans.js");
+const doc_refs_js_1 = require("./doc-refs.js");
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 const IGNORE_NODE_MODULES = ["node_modules/**"];
-// Config is loaded from .vigilesrc.json via validate.ts::loadConfig().
-// All settings (validation, compilation, freshness) are in one place.
 // ---------------------------------------------------------------------------
 // Spec loading
 // ---------------------------------------------------------------------------
@@ -98,9 +106,84 @@ function printErrors(specFile, errors) {
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
+/** Compile a generator-skill spec from source → SKILL.md. Returns validity. */
+function compileGeneratorSkillToFile(specPath, source) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_generator_js_1.compileGeneratorSkill)(source, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath} (generator skill)`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    for (const e of errors)
+        console.log(`  ${e.type}: ${e.message}`);
+    return false;
+}
+/** Compile a ClaudeSpec → its primary + any additional targets. */
+function compileClaudeToFile(spec, specPath, config) {
+    const basePath = process.cwd();
+    const { markdown, errors, linterResults, targets } = (0, compile_js_1.compileClaude)(spec, {
+        basePath,
+        specFile: specPath,
+        maxRules: config.maxRules,
+        maxTokens: config.maxTokens,
+        maxSectionLines: config.maxSectionLines,
+        catalogOnly: config.catalogOnly,
+        linters: config.linters,
+    });
+    const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
+    if (errors.length > 0) {
+        console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+        printErrors(specPath, errors);
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+        return false;
+    }
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
+    const outputNames = [primaryOutput];
+    for (const t of targets.slice(1)) {
+        const body = markdown
+            .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
+            .replace(/^# [^\n]+/, `# ${t}`);
+        const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
+        const targetPath = dir + t;
+        (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), (0, compile_js_1.addHash)(body, specPath));
+        outputNames.push(targetPath);
+    }
+    const linterCount = linterResults.filter((r) => r.exists).length;
+    console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
+    console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
+    return true;
+}
+/** Compile a declarative SkillSpec → SKILL.md. */
+function compileSkillToFile(spec, specPath) {
+    const outputPath = specPath.replace(/\.spec\.ts$/, "");
+    const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
+        basePath: process.cwd(),
+        specFile: specPath,
+    });
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
+    if (errors.length === 0) {
+        console.log(`\n✓ ${specPath} → ${outputPath}`);
+        return true;
+    }
+    console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
+    printErrors(specPath, errors);
+    return false;
+}
 async function compile(specPaths, config) {
     let allValid = true;
     for (const specPath of specPaths) {
+        // Generator skills can't be executed to markdown — compile from source.
+        const source = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), specPath), "utf-8");
+        if (/\bgenSkill\s*\(/.test(source)) {
+            if (!compileGeneratorSkillToFile(specPath, source))
+                allValid = false;
+            continue;
+        }
         const spec = await loadSpec(specPath);
         if (!spec) {
             console.log(`\n✗ ${specPath} — failed to load`);
@@ -108,69 +191,13 @@ async function compile(specPaths, config) {
             allValid = false;
             continue;
         }
-        const basePath = process.cwd();
         if (spec._specType === "claude") {
-            const { markdown: rawMarkdown, errors, linterResults, targets, } = (0, compile_js_1.compileClaude)(spec, {
-                basePath,
-                specFile: specPath,
-                maxRules: config.maxRules,
-                maxTokens: config.maxTokens,
-                maxSectionLines: config.maxSectionLines,
-                catalogOnly: config.catalogOnly,
-                linters: config.linters,
-            });
-            // Embed input hash for freshness tracking
-            let markdown = rawMarkdown;
-            if (config.freshnessMode === "input-hash") {
-                const inputs = (0, freshness_js_1.discoverInputs)(specPath, spec, basePath, config.freshnessInputs);
-                const inputHash = (0, freshness_js_1.computeInputHash)(inputs.files, basePath);
-                markdown = (0, freshness_js_1.addInputHash)(rawMarkdown, inputHash);
-            }
-            const linterCount = linterResults.filter((r) => r.exists).length;
-            const primaryOutput = specPath.replace(/\.spec\.ts$/, "");
-            if (errors.length === 0) {
-                // Write primary target
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
-                const outputNames = [primaryOutput];
-                // Write additional targets with swapped heading + recomputed hash
-                for (const t of targets.slice(1)) {
-                    // Strip hash, replace heading, recompute hash
-                    const body = markdown
-                        .replace(/^<!-- vigiles:[^\n]+\n\n?/, "")
-                        .replace(/^# [^\n]+/, `# ${t}`);
-                    const additional = (0, compile_js_1.addHash)(body, specPath);
-                    const dir = primaryOutput.substring(0, primaryOutput.lastIndexOf("/") + 1);
-                    const targetPath = dir + t;
-                    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, targetPath), additional);
-                    outputNames.push(targetPath);
-                }
-                console.log(`\n✓ ${specPath} → ${outputNames.join(", ")}`);
-                console.log(`  ${String(Object.keys(spec.rules).length)} rules (${String(linterCount)} linter-verified)`);
-            }
-            else {
-                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
-                printErrors(specPath, errors);
+            if (!compileClaudeToFile(spec, specPath, config))
                 allValid = false;
-                // Still write the file so the user can see partial output
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, primaryOutput), markdown);
-            }
         }
         else if (spec._specType === "skill") {
-            const outputPath = specPath.replace(/\.spec\.ts$/, "");
-            const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
-                basePath,
-                specFile: specPath,
-            });
-            if (errors.length === 0) {
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
-                console.log(`\n✓ ${specPath} → ${outputPath}`);
-            }
-            else {
-                console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
-                printErrors(specPath, errors);
+            if (!compileSkillToFile(spec, specPath))
                 allValid = false;
-                (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(basePath, outputPath), markdown);
-            }
         }
     }
     return allValid;
@@ -343,17 +370,7 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
         const ruleCount = Object.keys(rules).length;
         if (ruleCount < 2)
             continue;
-        // Guard against unknown rule kinds (legacy "check" artifacts, JS
-        // callers) that would crash ruleToText inside findSimilarRules.
-        // Same pattern as the try/catch in runProofSuite.
-        let pairs;
-        try {
-            pairs = (0, proofs_js_1.findSimilarRules)(rules, threshold);
-        }
-        catch (e) {
-            log(`  ⚠ ${specPath}: similarity check failed (${e instanceof Error ? e.message : String(e)})`);
-            continue;
-        }
+        const pairs = (0, proofs_js_1.findSimilarRules)(rules, threshold);
         if (pairs.length === 0)
             continue;
         if (specsWithDuplicates === 0) {
@@ -376,24 +393,117 @@ async function findDuplicateRules(threshold = 0.3, silent = false, scopeFiles) {
     log(`\n  ${String(totalPairs)} duplicate pair(s) in ${String(specsWithDuplicates)} spec(s). Consider merging or rewording.`);
     return { valid: false, pairCount: totalPairs };
 }
+/**
+ * Verify the file-qualified symbol references (`path.ext#symbol`) in instruction
+ * files: the named file must exist and define the named symbol. The author
+ * names the file, so this is a *declared* reference — a broken one is an error.
+ * Each named file is parsed on demand; there is no project-wide index. Returns
+ * the count of broken references.
+ */
+function verifyMarkdownSymbols(files, silent) {
+    if (files.length === 0)
+        return 0;
+    const cwd = process.cwd();
+    let printedHeader = false;
+    let errors = 0;
+    for (const f of files) {
+        let markdown;
+        try {
+            markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, f), "utf-8");
+        }
+        catch {
+            continue;
+        }
+        const broken = (0, refs_js_1.verifySymbolRefs)(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, f)));
+        if (broken.length === 0)
+            continue;
+        if (!silent) {
+            if (!printedHeader) {
+                console.log("\nSymbol reference check:\n");
+                printedHeader = true;
+            }
+            for (const b of broken) {
+                console.log(`  ✗ ${f}:${String(b.line)} ${b.reason}`);
+                ghAnnotate("error", b.reason, f, b.line);
+            }
+        }
+        errors += broken.length;
+    }
+    return errors;
+}
 /** Exit codes: 0 clean, 1 warnings only, 2 hard errors. */
 function auditExitCode(report) {
     if (report.hashErrors > 0 ||
         report.validationErrors > 0 ||
         report.inlineErrors > 0 ||
-        report.freshnessErrors > 0)
+        report.frontmatterErrors > 0 ||
+        report.integrityErrors > 0 ||
+        report.coverageErrors > 0 ||
+        report.symbolRefErrors > 0)
         return 2;
-    if (report.duplicatePairs > 0)
+    if (report.duplicatePairs > 0 ||
+        report.orphanCount > 0 ||
+        report.docRefErrors > 0)
         return 1;
-    // Coverage gaps and guidance counts are informational, not failures
+    // Guidance counts are informational, not failures
     return 0;
 }
 /**
- * Verify inline `<!-- vigiles:enforce ... -->` comments in an instruction
- * file. Each comment's linter rule goes through the same verification as
- * spec-declared enforce rules (existence, enabled status, closest-match
- * suggestions on typo).
+ * Verify one parsed enforce rule against the linter catalog/config, logging
+ * and annotating on failure. Returns true when the rule is valid+enabled.
+ */
+function verifyOneRule(rule, filePath, silent, linterOptions) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    const result = (0, linters_js_1.checkLinterRule)(rule.linterRule, process.cwd(), linterOptions);
+    if (!result.exists) {
+        const message = result.error ?? `Rule "${rule.linterRule}" not found`;
+        log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!silent)
+            ghAnnotate("error", message, filePath, rule.line);
+        return false;
+    }
+    if (result.enabled === "disabled") {
+        const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
+        log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!silent)
+            ghAnnotate("error", message, filePath, rule.line);
+        return false;
+    }
+    log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
+    return true;
+}
+/**
+ * Verify the `vigiles:file` / `vigiles:cmd` references a markdown file declares
+ * (inline comments or frontmatter lists), using the same engine spec mode uses:
+ * file paths via existsSync, npm scripts and script-runner commands via
+ * package.json / the filesystem. References resolve relative to the markdown
+ * file's own directory. Returns the number of stale references found.
  */
+function verifyMarkdownRefs(files, commands, filePath, silent) {
+    const basePath = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), filePath));
+    let errorCount = 0;
+    const report = (err, line) => {
+        if (!silent) {
+            console.log(`  ✗ line ${String(line)}: ${err.message}`);
+            ghAnnotate("error", err.message, filePath, line);
+        }
+        errorCount++;
+    };
+    for (const f of files) {
+        const err = (0, compile_js_1.validateFileRef)(f.path, basePath);
+        if (err)
+            report(err, f.line);
+    }
+    for (const c of commands) {
+        const err = (0, compile_js_1.validateCommandRef)(c.command, basePath);
+        if (err)
+            report(err, c.line);
+    }
+    return errorCount;
+}
 function verifyInlineRules(filePath, silent, linterOptions) {
     const log = (msg) => {
         if (!silent)
@@ -404,11 +514,14 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), filePath), "utf-8");
     }
     catch {
-        return { ok: true, errorCount: 0, ruleCount: 0 };
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
-    const { rules, errors: parseErrors } = (0, inline_js_1.parseInlineRules)(content);
-    if (rules.length === 0 && parseErrors.length === 0) {
-        return { ok: true, errorCount: 0, ruleCount: 0 };
+    const { rules, files, commands, errors: parseErrors, } = (0, inline_js_1.parseInlineRules)(content);
+    if (rules.length === 0 &&
+        files.length === 0 &&
+        commands.length === 0 &&
+        parseErrors.length === 0) {
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
     }
     let errorCount = 0;
     log(`\n${filePath} (inline mode):`);
@@ -420,28 +533,118 @@ function verifyInlineRules(filePath, silent, linterOptions) {
         }
     }
     for (const rule of rules) {
-        const result = (0, linters_js_1.checkLinterRule)(rule.linterRule, process.cwd(), linterOptions);
-        if (!result.exists) {
-            const message = result.error ?? `Rule "${rule.linterRule}" not found`;
-            log(`  ✗ line ${String(rule.line)}: ${message}`);
+        if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
-            if (!silent) {
-                ghAnnotate("error", message, filePath, rule.line);
-            }
+    }
+    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
+    return {
+        ok: errorCount === 0,
+        errorCount,
+        ruleCount: rules.length + files.length + commands.length,
+        ruleNames: rules.map((r) => r.linterRule),
+    };
+}
+/**
+ * Verify `vigiles.enforce` rules declared in a file's YAML frontmatter.
+ * Same engine as inline/spec rules. Rules whose reference already appeared
+ * in `exclude` (e.g. declared inline in the same file) are skipped so a
+ * rule present in both sources is reported once, not twice.
+ */
+function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let content;
+    try {
+        content = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(process.cwd(), filePath), "utf-8");
+    }
+    catch {
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
+    }
+    const { rules: allRules, files, commands, errors: parseErrors, } = (0, frontmatter_js_1.parseFrontmatterRules)(content);
+    const rules = allRules.filter((r) => !exclude.has(r.linterRule));
+    if (rules.length === 0 &&
+        files.length === 0 &&
+        commands.length === 0 &&
+        parseErrors.length === 0) {
+        return { ok: true, errorCount: 0, ruleCount: 0, ruleNames: [] };
+    }
+    let errorCount = 0;
+    log(`\n${filePath} (frontmatter mode):`);
+    for (const err of parseErrors) {
+        log(`  ✗ line ${String(err.line)}: ${err.message}`);
+        errorCount++;
+        if (!silent) {
+            ghAnnotate("error", err.message, filePath, err.line);
         }
-        else if (result.enabled === "disabled") {
-            const message = `Rule "${rule.linterRule}" exists but is disabled in ${result.linter} config`;
-            log(`  ✗ line ${String(rule.line)}: ${message}`);
+    }
+    for (const rule of rules) {
+        if (!verifyOneRule(rule, filePath, silent, linterOptions))
             errorCount++;
-            if (!silent) {
-                ghAnnotate("error", message, filePath, rule.line);
-            }
+    }
+    errorCount += verifyMarkdownRefs(files, commands, filePath, silent);
+    return {
+        ok: errorCount === 0,
+        errorCount,
+        ruleCount: rules.length + files.length + commands.length,
+        ruleNames: rules.map((r) => r.linterRule),
+    };
+}
+/**
+ * Verify inline `<!-- vigiles:enforce -->` comments and `vigiles:` YAML
+ * frontmatter in instruction files that aren't managed by a spec.
+ *
+ * Spec mode is the source of truth when it exists, so a literal
+ * `<!-- vigiles:enforce ... -->` snippet that survived into compiled
+ * markdown (or an example in a spec-managed file) must not trip audit. A
+ * file is spec-managed iff it has a sibling `<file>.spec.ts` OR its own
+ * `<!-- vigiles:sha256:... compiled from <spec> -->` header. A rule
+ * declared both inline and in frontmatter is verified once (inline wins as
+ * the first source). See docs/markdown-mode.md.
+ */
+function verifyMarkdownModeRules(files, silent, config) {
+    const totals = {
+        inlineErrors: 0,
+        inlineRules: 0,
+        frontmatterErrors: 0,
+        frontmatterRules: 0,
+    };
+    if (!silent && files.length > 0) {
+        console.log("\nInline + frontmatter rule verification:");
+    }
+    const linterOptions = {
+        catalogOnly: config?.catalogOnly,
+        linters: config?.linters,
+    };
+    const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from .+?\s*-->/;
+    for (const filePath of files) {
+        const abs = (0, node_path_1.resolve)(process.cwd(), filePath);
+        if ((0, node_fs_1.existsSync)(`${abs}.spec.ts`))
+            continue; // managed by sibling spec
+        let content;
+        try {
+            content = (0, node_fs_1.readFileSync)(abs, "utf-8");
         }
-        else {
-            log(`  ✓ line ${String(rule.line)}: ${rule.linterRule}`);
+        catch {
+            continue;
         }
-    }
-    return { ok: errorCount === 0, errorCount, ruleCount: rules.length };
+        if (compiledFromRe.test(content))
+            continue; // managed via hash header
+        const inline = verifyInlineRules(filePath, silent, linterOptions);
+        totals.inlineErrors += inline.errorCount;
+        totals.inlineRules += inline.ruleCount;
+        const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
+        totals.frontmatterErrors += fm.errorCount;
+        totals.frontmatterRules += fm.ruleCount;
+    }
+    if (!silent &&
+        files.length > 0 &&
+        totals.inlineRules === 0 &&
+        totals.frontmatterRules === 0) {
+        console.log("  (no inline vigiles:enforce comments or vigiles: frontmatter found)");
+    }
+    return totals;
 }
 /**
  * Unified audit command: verify hashes, report coverage gaps, detect duplicates,
@@ -468,45 +671,10 @@ async function audit(restArgs, flags, config) {
     const hashResult = files.length > 0
         ? check(files, silent)
         : { valid: true, hashErrors: 0, validationErrors: 0 };
-    // 1b. Verify inline vigiles:enforce comments in any instruction file
-    // that isn't already managed by a .spec.ts. Spec mode is the source of
-    // truth when it exists, so a literal `<!-- vigiles:enforce ... -->`
-    // snippet that survived into the compiled markdown (or an
-    // explanatory example in a spec-managed file) must not trip audit.
-    // A file is spec-managed iff it has a sibling `<file>.spec.ts` OR its
-    // own `<!-- vigiles:sha256:... compiled from <spec> -->` header.
-    // See docs/inline-mode.md.
-    let inlineErrors = 0;
-    let inlineRules = 0;
-    if (!silent && files.length > 0) {
-        console.log("\nInline rule verification:");
-    }
-    const compiledFromRe = /<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from .+?\s*-->/;
-    for (const filePath of files) {
-        const abs = (0, node_path_1.resolve)(process.cwd(), filePath);
-        if ((0, node_fs_1.existsSync)(`${abs}.spec.ts`)) {
-            continue; // managed by sibling spec
-        }
-        let content;
-        try {
-            content = (0, node_fs_1.readFileSync)(abs, "utf-8");
-        }
-        catch {
-            continue;
-        }
-        if (compiledFromRe.test(content)) {
-            continue; // managed by the spec referenced in the hash header
-        }
-        const result = verifyInlineRules(filePath, silent, {
-            catalogOnly: config?.catalogOnly,
-            linters: config?.linters,
-        });
-        inlineErrors += result.errorCount;
-        inlineRules += result.ruleCount;
-    }
-    if (!silent && files.length > 0 && inlineRules === 0) {
-        console.log("  (no inline vigiles:enforce comments found)");
-    }
+    // 1b. Verify inline + frontmatter rules in instruction files not managed
+    // by a spec. See verifyMarkdownModeRules / docs/markdown-mode.md.
+    const md = verifyMarkdownModeRules(files, silent, config);
+    const { inlineErrors, inlineRules, frontmatterErrors, frontmatterRules } = md;
     // 2. Coverage gaps (discover)
     if (!silent)
         console.log("\nLinter rule coverage:\n");
@@ -519,25 +687,63 @@ async function audit(restArgs, flags, config) {
     const dups = await findDuplicateRules(0.3, silent, restArgs.length > 0 ? files : undefined);
     // 4. Guidance rule count (strengthen suggestions moved to /strengthen skill)
     const guidanceCount = await countGuidanceRules(silent);
-    // 5. Freshness check
-    const freshnessSeverity = config?.rules.freshness;
-    let freshnessErrors = 0;
-    if (freshnessSeverity) {
+    // 5. Integrity check (hand-edit detection via SHA-256 hash)
+    const integritySeverity = config?.rules.integrity ?? "warn";
+    let integrityErrors = 0;
+    if (integritySeverity) {
         if (!silent)
-            console.log("\nFreshness check:\n");
-        const mode = config?.freshnessMode ?? "strict";
-        freshnessErrors = await checkFreshness(files, mode, config, freshnessSeverity, silent);
+            console.log("\nIntegrity check:\n");
+        integrityErrors = checkIntegrityForFiles(files, integritySeverity, silent);
+    }
+    // 6. Coverage thresholds (gates CI when severity is "error")
+    const coverageErrors = await checkCoverageThresholds(coverage, config, silent);
+    // 7. Orphan docs check — find .md files no other markdown references.
+    // Enforces the `vigiles/orphan-docs` built-in rule when declared in a
+    // spec. Include/exclude come from .vigilesrc.json#orphans (tsconfig-
+    // style globs); default include is docs/ + research/ for the
+    // vigiles-repo convention.
+    if (!silent)
+        console.log("\nOrphan docs check:\n");
+    const orphanReport = (0, orphans_js_1.findOrphanDocs)({
+        basePath: process.cwd(),
+        include: config?.orphans?.include,
+        exclude: config?.orphans?.exclude,
+    });
+    if (!silent) {
+        for (const line of (0, orphans_js_1.formatOrphanReport)(orphanReport).split("\n")) {
+            console.log(`  ${line}`);
+        }
+    }
+    // 8. Validate vigiles builder calls inside markdown code blocks. Default
+    // is to validate every ref; illustrative blocks opt out via
+    // `<!-- vigiles:ignore -->` (single block) or
+    // `<!-- vigiles:ignore-file -->` (whole file). Same engine as spec.ts.
+    if (!silent)
+        console.log("\nMarkdown code block refs:\n");
+    const docRefReport = (0, doc_refs_js_1.findDocRefs)({ basePath: process.cwd() });
+    if (!silent) {
+        for (const line of (0, doc_refs_js_1.formatDocRefReport)(docRefReport).split("\n")) {
+            console.log(`  ${line}`);
+        }
     }
+    // 9. Verify code-shaped symbol references live (see src/refs.ts).
+    const symbolRefErrors = verifyMarkdownSymbols(files, silent);
     const report = {
         hashErrors: hashResult.hashErrors,
         validationErrors: hashResult.validationErrors,
         inlineErrors,
         inlineRules,
+        frontmatterErrors,
+        frontmatterRules,
         duplicatePairs: dups.pairCount,
         coverageEnabled: coverage.enabled,
         coverageDocumented: coverage.documented,
         strengthenSuggestions: guidanceCount,
-        freshnessErrors,
+        integrityErrors,
+        coverageErrors,
+        orphanCount: orphanReport.orphans.length,
+        docRefErrors: docRefReport.errors.length,
+        symbolRefErrors,
         files,
     };
     if (summary) {
@@ -557,15 +763,23 @@ function printAuditSummary(report) {
         parts.push(`${String(report.validationErrors)} validation errors`);
     if (report.inlineErrors > 0)
         parts.push(`${String(report.inlineErrors)} inline errors`);
+    if (report.frontmatterErrors > 0)
+        parts.push(`${String(report.frontmatterErrors)} frontmatter errors`);
     if (report.duplicatePairs > 0)
         parts.push(`${String(report.duplicatePairs)} duplicates`);
+    if (report.orphanCount > 0)
+        parts.push(`${String(report.orphanCount)} orphan docs`);
+    if (report.docRefErrors > 0)
+        parts.push(`${String(report.docRefErrors)} broken doc refs`);
+    if (report.symbolRefErrors > 0)
+        parts.push(`${String(report.symbolRefErrors)} broken symbol refs`);
     const undocumented = report.coverageEnabled - report.coverageDocumented;
     if (undocumented > 0)
         parts.push(`${String(undocumented)} undocumented rules`);
     if (report.strengthenSuggestions > 0)
         parts.push(`${String(report.strengthenSuggestions)} guidance (run /strengthen to upgrade)`);
-    if (report.freshnessErrors > 0)
-        parts.push(`${String(report.freshnessErrors)} stale (run vigiles compile)`);
+    if (report.integrityErrors > 0)
+        parts.push(`${String(report.integrityErrors)} tampered (edit the .spec.ts source)`);
     if (parts.length === 0) {
         console.log("vigiles: clean");
     }
@@ -883,6 +1097,15 @@ async function setup(args) {
         console.log(`  npm scripts: ${String(typesResult.scripts.length)}`);
     }
     console.log(`✓ Generated ${outPath}`);
+    // Also emit a JSON Schema so `vigiles:` markdown frontmatter (Level 1)
+    // gets rule-name autocomplete + typo squiggles from the editor's YAML LSP.
+    const schemaResult = (0, generate_schema_js_1.generateSchema)({
+        basePath: process.cwd(),
+        linters: (0, validate_js_1.loadConfig)().linters,
+    });
+    const schemaPath = ".vigiles/schema.json";
+    (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), schemaPath), schemaResult.json);
+    console.log(`✓ Generated ${schemaPath} (point frontmatter at it with \`# yaml-language-server: $schema=./${schemaPath}\`)`);
     // Step 5: Compile specs
     console.log("\nCompiling specs...");
     const specs = findSpecs();
@@ -991,6 +1214,7 @@ async function setup(args) {
         ...targets,
         ...specPathsList,
         ".vigiles/generated.d.ts",
+        ".vigiles/schema.json",
         ...(shouldInstallPlugin ? [".claude/settings.json"] : []),
         ...(strict ? [".vigilesrc.json"] : []),
     ];
@@ -999,7 +1223,7 @@ async function setup(args) {
 // ---------------------------------------------------------------------------
 // Strengthen: guidance() → enforce() suggestions
 // ---------------------------------------------------------------------------
-async function checkFreshness(files, mode, config, severity, silent) {
+function checkIntegrityForFiles(files, severity, silent) {
     const log = (msg) => {
         if (!silent)
             console.log(msg);
@@ -1010,79 +1234,66 @@ async function checkFreshness(files, mode, config, severity, silent) {
         const abs = (0, node_path_1.resolve)(basePath, filePath);
         if (!(0, node_fs_1.existsSync)(abs))
             continue;
-        const content = (0, node_fs_1.readFileSync)(abs, "utf-8");
-        // Find the spec that compiled this file
-        const hashMatch = content.match(/<!--\s*vigiles:sha256:[a-f0-9]+\s+compiled from (.+?)\s*-->/);
-        if (!hashMatch) {
-            // No hash = hand-written file, skip freshness check
-            continue;
-        }
-        let result;
-        const specFile = hashMatch[1];
-        if (mode === "strict") {
-            // Recompile in memory and diff
-            const spec = await loadSpec(specFile);
-            if (!spec || spec._specType !== "claude") {
-                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
-                continue;
-            }
-            const compiled = (0, compile_js_1.compileClaude)(spec, {
-                basePath,
-                specFile,
-                maxRules: config?.maxRules,
-                maxTokens: config?.maxTokens,
-                maxSectionLines: config?.maxSectionLines,
-                catalogOnly: config?.catalogOnly,
-                linters: config?.linters,
-            });
-            // Compare markdown body (strip hash/input lines)
-            const metaRe = /^<!-- vigiles:(sha256|inputs):[^\n]+ -->\r?\n?/gm;
-            const existingBody = content.replace(metaRe, "").trim();
-            const compiledBody = compiled.markdown.replace(metaRe, "").trim();
-            if (existingBody === compiledBody) {
-                result = { fresh: true, mode: "strict" };
-            }
-            else {
-                result = {
-                    fresh: false,
-                    mode: "strict",
-                    reason: "Output would differ if recompiled — run `vigiles compile`",
-                };
-            }
-        }
-        else if (mode === "input-hash") {
-            const specFile = hashMatch[1];
-            const spec = await loadSpec(specFile);
-            if (!spec || spec._specType !== "claude") {
-                log(`  ? ${filePath} — can't load spec "${specFile}", skipping`);
-                continue;
-            }
-            const inputs = (0, freshness_js_1.discoverInputs)(specFile, spec, basePath, config?.freshnessInputs);
-            result = (0, freshness_js_1.checkInputHashFreshness)(content, inputs.files, basePath);
-        }
-        else {
-            // output-hash mode
-            result = (0, freshness_js_1.checkOutputHashFreshness)(content);
-        }
-        if (!result.fresh) {
+        const result = (0, integrity_js_1.checkIntegrity)((0, node_fs_1.readFileSync)(abs, "utf-8"));
+        if (!result.intact) {
             errorCount++;
             const marker = severity === "error" ? "✗" : "⚠";
-            log(`  ${marker} ${filePath} — ${result.reason ?? "stale"}`);
-            if (result.changedFiles && result.changedFiles.length > 0) {
-                for (const f of result.changedFiles) {
-                    log(`    changed: ${f}`);
-                }
-            }
+            log(`  ${marker} ${filePath} — ${result.reason ?? "tampered"}`);
         }
         else if (!silent) {
-            log(`  ✓ ${filePath} — fresh (${mode})`);
+            log(`  ✓ ${filePath}`);
         }
     }
     if (errorCount === 0) {
-        log("  All files fresh.");
+        log("  All compiled files intact.");
     }
     return severity === "error" ? errorCount : 0;
 }
+/**
+ * Apply the configured coverage thresholds. Returns the number of failing
+ * thresholds (so the audit can fail CI when severity is "error").
+ *
+ * Loads specs directly via loadSpec() when the scripts threshold is set —
+ * avoids depending on a pre-built `dist/` tree, which the setup-generated
+ * CI step doesn't guarantee.
+ */
+async function checkCoverageThresholds(coverage, config, silent) {
+    const severity = (0, types_js_1.ruleSeverity)(config?.rules.coverage);
+    if (!severity)
+        return 0;
+    const opts = (0, types_js_1.ruleOptions)(config?.rules.coverage);
+    if (!opts)
+        return 0;
+    const log = (msg) => {
+        if (!silent)
+            console.log(msg);
+    };
+    let failing = 0;
+    if (!silent)
+        console.log("\nCoverage thresholds:\n");
+    if (opts.linterRules !== undefined) {
+        const pct = coverage.enabled > 0
+            ? Math.round((coverage.documented / coverage.enabled) * 100)
+            : 100;
+        const ok = pct >= opts.linterRules;
+        if (!ok)
+            failing++;
+        const marker = ok ? "✓" : severity === "error" ? "✗" : "⚠";
+        log(`  ${marker} linterRules: ${String(pct)}% (threshold: ${String(opts.linterRules)}%)`);
+    }
+    if (opts.scripts !== undefined) {
+        // Load all claude specs so coverage doesn't depend on a built dist/.
+        const loaded = await Promise.all(findSpecs().map(loadSpec));
+        const claudeSpecs = loaded.filter((s) => s?._specType === "claude");
+        const metric = (0, coverage_js_1.computeScriptCoverage)(process.cwd(), opts.scripts, claudeSpecs);
+        const ok = metric.passing;
+        if (!ok)
+            failing++;
+        const marker = ok ? "✓" : severity === "error" ? "✗" : "⚠";
+        log(`  ${marker} scripts: ${String(metric.percent)}% (threshold: ${String(opts.scripts)}%)`);
+    }
+    return severity === "error" ? failing : 0;
+}
 async function countGuidanceRules(silent = false) {
     const specs = findSpecs();
     if (specs.length === 0)
@@ -1165,6 +1376,43 @@ function handleGenerateTypes(args, restArgs) {
     (0, node_fs_1.writeFileSync)(fullOut, result.dts);
     console.log(`\n✓ Generated ${outPath}`);
 }
+function handleGenerateSchema(args, restArgs) {
+    const checkOnly = args.includes("--check");
+    const outPath = restArgs[0] ?? ".vigiles/schema.json";
+    console.log("Scanning linters...\n");
+    const result = (0, generate_schema_js_1.generateSchema)({
+        basePath: process.cwd(),
+        linters: (0, validate_js_1.loadConfig)().linters,
+    });
+    for (const l of result.linters) {
+        console.log(`  ${l.linter}: ${String(l.count)} rules`);
+    }
+    console.log(`  schema enum: ${String(result.ruleNames.length)} rule names`);
+    const fullOut = (0, node_path_1.resolve)(process.cwd(), outPath);
+    if (checkOnly) {
+        if (!(0, node_fs_1.existsSync)(fullOut)) {
+            console.log(`\n✗ ${outPath} does not exist. Run \`vigiles generate-schema\` to create it.`);
+            process.exit(1);
+        }
+        const existing = (0, node_fs_1.readFileSync)(fullOut, "utf-8");
+        if (existing.trim() === result.json.trim()) {
+            console.log(`\n✓ ${outPath} is up to date`);
+        }
+        else {
+            console.log(`\n✗ ${outPath} is stale. Run \`vigiles generate-schema\` to update.`);
+            process.exit(1);
+        }
+        return;
+    }
+    const outDir = fullOut.substring(0, fullOut.lastIndexOf("/"));
+    if (outDir && !(0, node_fs_1.existsSync)(outDir)) {
+        (0, node_fs_1.mkdirSync)(outDir, { recursive: true });
+    }
+    (0, node_fs_1.writeFileSync)(fullOut, result.json);
+    console.log(`\n✓ Generated ${outPath}`);
+    console.log("  Add to your markdown frontmatter:\n" +
+        `    # yaml-language-server: $schema=./${outPath}`);
+}
 function printUsage(command) {
     console.log("vigiles — compile typed specs to instruction files");
     console.log("");
@@ -1181,6 +1429,8 @@ function printUsage(command) {
     console.log("Plumbing:");
     console.log("  vigiles generate-types [out]  Emit .d.ts from project state");
     console.log("  vigiles generate-types --check  Verify .d.ts is up to date");
+    console.log("  vigiles generate-schema [out] Emit JSON Schema for vigiles: frontmatter");
+    console.log("  vigiles generate-schema --check Verify schema.json is up to date");
     if (command && command !== "--help") {
         console.log(`\nUnknown command: "${command}"`);
         process.exit(1);
@@ -1189,6 +1439,242 @@ function printUsage(command) {
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
+/**
+ * Emit GitHub Actions annotations for an audit report. Skipped when --json or
+ * --summary is active — those modes promise clean machine-readable stdout, and
+ * ::error/::warning lines would contaminate output parsed as JSON.
+ */
+function annotateAuditForGitHub(report, flags) {
+    const structuredOutput = flags.includes("--json") || flags.includes("--summary");
+    if (!isGitHubActions() || structuredOutput)
+        return;
+    if (report.hashErrors > 0) {
+        ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
+    }
+    if (report.validationErrors > 0) {
+        ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
+    }
+    if (report.duplicatePairs > 0) {
+        ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
+    }
+}
+/**
+ * Run a compiled skill's deterministic gate ladder: execute each step gate in
+ * order (short-circuiting on the first failure), then the result gate. This is
+ * the v0 runtime — it enforces the `vigiles:gate`/`vigiles:result` markers a
+ * compiled SKILL.md carries. It does not yet drive the model through the prose
+ * steps (that needs a live harness).
+ */
+function runSkillCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles run-skill <SKILL.md>");
+        process.exit(2);
+    }
+    const path = (0, node_path_1.resolve)(process.cwd(), target);
+    if (!(0, node_fs_1.existsSync)(path)) {
+        console.error(`Not found: ${target}`);
+        process.exit(2);
+    }
+    const gates = (0, skill_runtime_js_1.parseSkillGates)((0, node_fs_1.readFileSync)(path, "utf-8"));
+    if (gates.steps.length === 0 && !gates.result) {
+        console.log(`No vigiles:gate / vigiles:result markers in ${target}.`);
+        return;
+    }
+    console.log(`Running gate ladder for ${target}:\n`);
+    const report = (0, skill_runtime_js_1.runSkillGates)(gates, process.cwd());
+    for (const r of report.results) {
+        const label = r.at === "result" ? "result" : `step ${String(r.at)}`;
+        console.log(`  ${r.ok ? "✓" : "✗"} ${label} — ${(0, skill_runtime_js_1.gateLabel)(r.gate)}`);
+        if (!r.ok && r.output) {
+            console.log(r.output
+                .split("\n")
+                .map((l) => `      ${l}`)
+                .join("\n"));
+        }
+    }
+    if (report.ok) {
+        console.log("\n✓ All gates passed.");
+    }
+    else {
+        const where = report.blockedAt === "result"
+            ? "the result gate"
+            : `step ${String(report.blockedAt)}`;
+        console.log(`\n✗ Blocked at ${where} — fix it before the skill is done.`);
+        process.exit(2);
+    }
+}
+/**
+ * Stop-hook entrypoint: run the active skill's result gate and decide whether
+ * the agent may stop. Exit 2 (with the reason on stderr) blocks the stop and
+ * feeds the message back to the model; exit 0 allows it and clears the marker.
+ */
+function skillHookCommand() {
+    const decision = (0, skill_runtime_js_1.evaluateStopHook)(process.cwd());
+    if (decision.allow) {
+        if (decision.message)
+            console.log(decision.message);
+        (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+        return;
+    }
+    console.error(decision.message);
+    process.exit(2);
+}
+/** Mark a skill active so the Stop hook enforces its result gate. */
+function skillStartCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles skill-start <SKILL.md>");
+        process.exit(2);
+    }
+    (0, skill_runtime_js_1.setActiveSkill)(process.cwd(), target);
+    console.log(`Active skill: ${target}`);
+}
+/** Dispatch the skill-runtime subcommands. Returns false if unrecognized. */
+function handleSkillCommand(command, restArgs) {
+    switch (command) {
+        case "run-skill":
+            runSkillCommand(restArgs[0]);
+            return true;
+        case "skill-start":
+            skillStartCommand(restArgs[0]);
+            return true;
+        case "skill-done":
+            (0, skill_runtime_js_1.clearActiveSkill)(process.cwd());
+            return true;
+        case "skill-hook":
+            skillHookCommand();
+            return true;
+        case "action-hook":
+            actionHookCommand();
+            return true;
+        case "refs":
+            refsCommand(restArgs[0]);
+            return true;
+        case "refs-hook":
+            refsHookCommand();
+            return true;
+        default:
+            return false;
+    }
+}
+/**
+ * PostToolUse-hook entrypoint for action gates. Reads the tool event on stdin,
+ * runs the matching action gates from `.vigiles/action-gates.json`, and blocks
+ * (exit 2 + reason on stderr) if any fails — plan-agnostic, so it works inside
+ * dynamic workflows where there is no static step to attach a gate to.
+ */
+function actionHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let event = { tool: "" };
+    try {
+        const j = JSON.parse(raw);
+        event = { tool: j.tool_name ?? "", input: j.tool_input };
+    }
+    catch {
+        /* malformed input → no event, allow */
+    }
+    const decision = (0, action_gate_js_1.evaluateAction)(event, (0, action_gate_js_1.loadActionGates)(process.cwd()), process.cwd());
+    if (!decision.allow) {
+        console.error(decision.message);
+        process.exit(2);
+    }
+}
+const INSTRUCTION_FILE = /^(SKILL|CLAUDE|AGENTS)\.md$/;
+function isInstructionFile(file) {
+    return INSTRUCTION_FILE.test((0, node_path_1.basename)(file));
+}
+/**
+ * Inspect an instruction file's symbol references: broken file-qualified refs
+ * (`path.ext#symbol` whose file/symbol is wrong) and code-shaped references not
+ * yet marked. Emits one line per finding via `log`; returns whether any issue
+ * was found. `basePath` is the file's own directory (where paths resolve).
+ */
+function reportRefIssues(markdown, basePath, log) {
+    const broken = (0, refs_js_1.verifySymbolRefs)(markdown, basePath);
+    const unmarked = (0, refs_js_1.unmarkedCodeRefs)(markdown);
+    for (const b of broken) {
+        log(`  ✗ line ${String(b.line)}: ${b.reason}`);
+    }
+    for (const u of unmarked) {
+        const callee = u.text.replace(/\s*\([^)]*\)\s*$/, "");
+        log(`  ✗ line ${String(u.line)}: \`${u.text}\` is an unmarked code reference — ` +
+            `mark it as \`vigiles:symbol path/to/file.ext#${callee}\` or add <!-- vigiles:ignore --> if it is prose`);
+    }
+    return broken.length > 0 || unmarked.length > 0;
+}
+/** `vigiles refs <file>` — check a file's symbol references (exit 2 on issues). */
+function refsCommand(target) {
+    if (!target) {
+        console.error("Usage: vigiles refs <instruction-file.md>");
+        process.exit(2);
+    }
+    const cwd = process.cwd();
+    let markdown;
+    try {
+        markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, target), "utf-8");
+    }
+    catch {
+        console.error(`Cannot read ${target}`);
+        process.exit(2);
+    }
+    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, target)), (m) => {
+        console.log(m);
+    });
+    if (bad)
+        process.exit(2);
+    console.log(`✓ ${target}: all code references are marked and resolve.`);
+}
+/**
+ * PostToolUse-hook entrypoint: when the agent edits an instruction file, force
+ * every code reference to carry a file-qualified mark (`path.ext#symbol`) and
+ * verify the marked ones against the named file. Exit 2 (reason on stderr)
+ * blocks the edit and feeds the fix back to the agent — the harness makes the
+ * agent mark its references, at write time, with full context. `vigiles:ignore`
+ * opts a prose span out.
+ */
+function refsHookCommand() {
+    let raw = "";
+    try {
+        raw = (0, node_fs_1.readFileSync)(0, "utf-8");
+    }
+    catch {
+        /* no stdin */
+    }
+    let file = "";
+    try {
+        const j = JSON.parse(raw);
+        file = j.tool_input?.file_path ?? "";
+    }
+    catch {
+        /* malformed → nothing to do */
+    }
+    if (!file || !isInstructionFile(file))
+        return;
+    const cwd = process.cwd();
+    const target = (0, node_path_1.relative)(cwd, (0, node_path_1.resolve)(cwd, file)) || file;
+    let markdown;
+    try {
+        markdown = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(cwd, file), "utf-8");
+    }
+    catch {
+        return;
+    }
+    const lines = [];
+    const bad = reportRefIssues(markdown, (0, node_path_1.dirname)((0, node_path_1.resolve)(cwd, file)), (m) => {
+        lines.push(m);
+    });
+    if (bad) {
+        console.error(`vigiles: fix the code references in ${target}:`);
+        for (const l of lines)
+            console.error(l);
+        process.exit(2);
+    }
+}
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
@@ -1232,23 +1718,8 @@ async function main() {
             // audit = verify + discover + guidance count
             const flags = args.slice(1).filter((a) => a.startsWith("--"));
             const report = await audit(restArgs, flags, config);
+            annotateAuditForGitHub(report, flags);
             const exitCode = auditExitCode(report);
-            // Skip GH annotations when --json or --summary is active —
-            // those modes promise clean machine-readable stdout, and
-            // ::error/::warning lines would contaminate the output for
-            // callers parsing it as JSON.
-            const structuredOutput = flags.includes("--json") || flags.includes("--summary");
-            if (isGitHubActions() && !structuredOutput) {
-                if (report.hashErrors > 0) {
-                    ghAnnotate("error", `${String(report.hashErrors)} compiled file(s) with stale hash — run vigiles compile`);
-                }
-                if (report.validationErrors > 0) {
-                    ghAnnotate("error", `${String(report.validationErrors)} spec validation failure(s) — see audit output`);
-                }
-                if (report.duplicatePairs > 0) {
-                    ghAnnotate("warning", `${String(report.duplicatePairs)} near-duplicate rule pair(s) detected — consider merging`);
-                }
-            }
             if (exitCode !== 0) {
                 process.exit(exitCode);
             }
@@ -1258,8 +1729,12 @@ async function main() {
         case "generate-types":
             handleGenerateTypes(args, restArgs);
             break;
+        case "generate-schema":
+            handleGenerateSchema(args, restArgs);
+            break;
         default:
-            printUsage(command);
+            if (!handleSkillCommand(command, restArgs))
+                printUsage(command);
             break;
     }
 }