@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/commands/skills/source-resolvers.js

@@ -3,12 +3,43 @@
  *
  * Handles extracting tarballs and downloading npm packages to temp directories.
  * Callers are responsible for cleaning up temp directories after use.
+ *
+ * Every refusal is coded where it is raised: a source that is not a skill
+ * package is the invocation's mistake (`USAGE_INVALID`), one the OS will not
+ * read or the archive module will not extract is the input's
+ * (`INPUT_UNREADABLE`), and a registry that will not hand the package over is
+ * `EXTERNAL_API_FAILED` (`downloadNpmPackage`).
  */
-import { existsSync } from 'node:fs';
-import { mkdtemp, rm } from 'node:fs/promises';
-import { mkdirSyncReal, normalizedTmpdir, safePath, toForwardSlash } from '@vibe-agent-toolkit/utils';
-import * as tar from 'tar';
+import { readdirSync } from 'node:fs';
+import { disposeTempDir, disposeTempDirAfterFailure, everywhere, forEachInOrder, pathPresent, safePath, toForwardSlash, withFsFaultSync } from '@vibe-agent-toolkit/utils';
+import { ARCHIVE_LIMITS, extractArchive } from '@vibe-agent-toolkit/utils/archive';
+import { CommandRefusalError, errorMessageOf } from '../../utils/command-refusal.js';
+import { leftoverIssue, leftoverIssueOf } from '../../utils/document-writer.js';
+import { requireInputPath } from '../../utils/project-root-policy.js';
+import { makeStagingDir } from '../../utils/staging-dir.js';
 import { downloadNpmPackage } from '../claude/plugin/helpers.js';
+/**
+ * Whether `dir` holds a `SKILL.md`. Absent is `false`; a probe the OS refuses
+ * is that tree's fault on its own side — never "no skill here", which is what
+ * `existsSync` would have answered for both.
+ *
+ * @param dir - A source directory, or one of its immediate subdirectories
+ * @param within - The source directory the operator named (or VAT staged): links beneath it are read before followed
+ * @param side - Whose tree it is: `source` for the operator's directory, `environment` for one VAT extracted
+ */
+export function holdsSkillMd(dir, within, side) {
+    return pathPresent(safePath.join(dir, 'SKILL.md'), { follow: within }, everywhere(side), 'probe');
+}
+/**
+ * The entries of a source directory, refused on its own side when the OS will
+ * not list it (`INPUT_UNREADABLE` for the operator's, `RUN_INCOMPLETE` for VAT's staging).
+ *
+ * @param dir - The source directory to list
+ * @param side - Whose tree it is: `source` for the operator's directory, `environment` for one VAT extracted
+ */
+export function readSourceDir(dir, side) {
+    return withFsFaultSync({ side, origin: 'argument', action: 'list the source directory', path: dir }, () => readdirSync(dir, { withFileTypes: true }));
+}
 /**
  * Determine whether a source string is an npm: prefix or tarball path.
  */
@@ -25,25 +56,52 @@ export function isNpmOrTarballSource(source) {
  * Caller must clean up tempDir when finished.
  */
 export async function extractTarballToTemp(tarballPath) {
-    const tempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-skills-tgz-'));
-    mkdirSyncReal(tempDir, { recursive: true });
-    await tar.extract({ file: tarballPath, cwd: tempDir });
-    const packageDir = safePath.join(tempDir, 'package');
-    if (!existsSync(packageDir)) {
-        throw new Error(`Tarball does not contain a package/ directory: ${tarballPath}`);
-    }
+    // The argument first: absent is the invocation's mistake, unreadable the input's.
+    requireInputPath(tarballPath, tarballPath, { origin: 'argument', message: `Path does not exist: ${tarballPath}` }, everywhere('source'));
+    const tempDir = await makeStagingDir('vat-skills-tgz-');
+    const packageDir = await discardingOnFailure(tempDir, async () => {
+        // One entry at a time: when the extraction throws, nothing is still being written under the staging.
+        await extractArchive({ file: tarballPath, side: 'source' }, tempDir, { format: 'tar', limits: ARCHIVE_LIMITS });
+        // A probe of the temp tree this process just extracted — VAT's own directory, not the user's path:
+        // one the OS refuses is the environment's fault, never "not an npm pack tarball".
+        const extracted = safePath.join(tempDir, 'package');
+        if (!pathPresent(extracted, { follow: tempDir }, everywhere('environment'), 'confirmed')) {
+            throw new CommandRefusalError('USAGE_INVALID', `Tarball does not contain a package/ directory (not an npm pack tarball): ${tarballPath}`);
+        }
+        return extracted;
+    });
     return { tempDir, packageDir };
 }
+/**
+ * Run `work` over a temp directory this process minted, disposing of the
+ * directory when `work` throws: the caller only learns about a temp directory
+ * it is handed back, so one minted on a failing path is otherwise left behind.
+ * The work's error is rethrown unchanged; a directory that will not go is
+ * recorded beside it (`suppressedFaultsOf`), never thrown in its place.
+ *
+ * @param tempDir - The directory to dispose of on failure
+ * @param work - What to do with it
+ */
+export async function discardingOnFailure(tempDir, work) {
+    try {
+        return await work();
+    }
+    catch (error) {
+        await disposeTempDirAfterFailure(tempDir, error);
+        throw error;
+    }
+}
 /**
  * Find the dist/skills/ directory inside a downloaded npm package.
  * Throws if the package was not built with "vat skills build".
  */
 export function findSkillsDirInNpmPackage(packageDir) {
     const distSkills = safePath.join(packageDir, 'dist', 'skills');
-    if (existsSync(distSkills)) {
+    // The package is in VAT's own staging: a probe the OS refuses is the environment's fault, never "no dist/skills/".
+    if (pathPresent(distSkills, { follow: packageDir }, everywhere('environment'), 'confirmed')) {
         return distSkills;
     }
-    throw new Error(`npm package does not contain dist/skills/: ${packageDir}\n` +
+    throw new CommandRefusalError('USAGE_INVALID', `npm package does not contain dist/skills/: ${packageDir}\n` +
         `Was the package built with "vat skills build"?`);
 }
 /**
@@ -53,42 +111,59 @@ export function findSkillsDirInNpmPackage(packageDir) {
  */
 export async function resolveNpmOrTarballSource(source) {
     if (source.startsWith('npm:')) {
-        const tempDir = await mkdtemp(safePath.join(normalizedTmpdir(), 'vat-skills-npm-'));
-        mkdirSyncReal(tempDir, { recursive: true });
-        const packageDir = downloadNpmPackage(source, tempDir);
-        return {
-            skillsDir: findSkillsDirInNpmPackage(packageDir),
-            tempDirs: [tempDir],
-        };
+        const tempDir = await makeStagingDir('vat-skills-npm-');
+        const skillsDir = await discardingOnFailure(tempDir, async () => findSkillsDirInNpmPackage(await downloadNpmPackage(source, tempDir)));
+        return { skillsDir, tempDirs: [tempDir] };
     }
     // Local .tgz / .tar.gz tarball
     const { tempDir, packageDir } = await extractTarballToTemp(source);
-    return {
-        skillsDir: findSkillsDirInNpmPackage(packageDir),
-        tempDirs: [tempDir],
-    };
+    const skillsDir = await discardingOnFailure(tempDir, () => findSkillsDirInNpmPackage(packageDir));
+    return { skillsDir, tempDirs: [tempDir] };
 }
 /**
- * Remove the temp directories a resolved source left behind.
+ * Dispose of the temp directories a resolved source left behind, once the work on it is done.
  *
- * Best-effort by design — the command's answer is already out, and a temp
+ * Best-effort by design — the command's answer is already decided, and a temp
  * directory that will not go (an `EBUSY` on Windows, a handle a scanner still
  * holds) must not turn a finished install into a failed one. But best-effort
- * is not silent: a directory left behind is named, so the operator can remove
- * what this run could not. `force: true` already tolerates one that is gone.
+ * is not silent: each directory left behind is returned as the one
+ * `TREE_CLEANUP_INCOMPLETE` warning naming it, for the report. One already gone
+ * is not a failure; one outside the temp directory is never removed, only named.
  *
  * @param tempDirs - What {@link resolveNpmOrTarballSource} minted
- * @param logger - Where a directory that stays is reported
+ * @returns A warning per directory that stays, in the order the dirs were minted
  */
-export async function removeResolvedTempDirs(tempDirs, logger) {
-    for (const dir of tempDirs) {
-        try {
-            await rm(dir, { recursive: true, force: true });
-        }
-        catch (error) {
-            const reason = error instanceof Error ? error.message : String(error);
-            logger.warn(`Could not remove temp directory ${toForwardSlash(dir)}: ${reason}`);
-        }
+export async function removeResolvedTempDirs(tempDirs) {
+    // Independent removals; what stays is named in the order the dirs were minted.
+    const outcomes = await Promise.allSettled(tempDirs.map((dir) => disposeTempDir(dir)));
+    return outcomes.flatMap((outcome, index) => {
+        if (outcome.status === 'fulfilled')
+            return outcome.value === undefined ? [] : [leftoverIssueOf(outcome.value)];
+        const dir = toForwardSlash(tempDirs[index] ?? '');
+        return [leftoverIssue(`Could not remove temp directory ${dir}: ${errorMessageOf(outcome.reason)}`, dir)];
+    });
+}
+/**
+ * Run `work` over a resolved source's temp directories, then dispose of them. A failure of
+ * `work` is rethrown unchanged, a directory that will not go recorded beside it
+ * (`suppressedFaultsOf`); once `work` succeeded, what stays comes back as `leftovers` — the
+ * warnings for the report beside its value.
+ *
+ * @param tempDirs - What {@link resolveNpmOrTarballSource} minted
+ * @param work - What to do while they exist
+ */
+export async function withResolvedTempDirs(tempDirs, work) {
+    let value;
+    try {
+        value = await work();
+    }
+    catch (error) {
+        await forEachInOrder(tempDirs, async (dir) => {
+            // Its leftover is recorded beside `error`, which is the answer.
+            await disposeTempDirAfterFailure(dir, error);
+        });
+        throw error;
     }
+    return { value, leftovers: await removeResolvedTempDirs(tempDirs) };
 }
 //# sourceMappingURL=source-resolvers.js.map

package/dist/commands/skills/source-resolvers.js.map

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

package/dist/commands/skills/validate-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-command.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/validate-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,wBAAgB,qBAAqB,IAAI,OAAO,CAqH/C"}
+{"version":3,"file":"validate-command.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/validate-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,wBAAgB,qBAAqB,IAAI,OAAO,CAgH/C"}

package/dist/commands/skills/validate-command.js

@@ -2,32 +2,16 @@
  * Skills validate command - Commander.js wrapper
  */
 import { Command } from 'commander';
-import { rejectUnscopablePath } from './scope-guard.js';
 import { validateCommand } from './validate.js';
-/**
- * What a mis-scoped `vat skills validate` used to do.
- *
- * In a package where the bare invocation validates 13 skills, one mistyped
- * character rescoped it to nothing and still reported success — the same
- * "went wide / went narrow and reported success" defect
- * `rejectPositionalArguments` was added to `vat verify` / `vat validate` /
- * `vat build` for, arrived at from the opposite direction. `vat skills build`
- * carried the identical hole and is guarded by the same module.
- */
-const SCOPE_SUBJECT = {
-    command: 'vat skills validate',
-    silentSuccess: 'nothing to validate',
-};
 export function createValidateCommand() {
     const command = new Command('validate');
     command
         .description('Validate skills for packaging (reads skills config from config yaml)')
         .argument('[path]', 'Path to directory with config yaml (default: current directory)')
         .option('--skill <name>', 'Validate specific skill only')
-        .option('-v, --verbose', 'Show all validated skills and every individual finding, including excluded reference paths')
+        .option('-v, --verbose', 'Print every finding in full on stderr, with allowed issues and excluded reference paths')
         .option('-d, --debug', 'Enable debug logging')
         .action(async (pathArg, options) => {
-        rejectUnscopablePath(SCOPE_SUBJECT, pathArg);
         await validateCommand(pathArg, options);
     })
         .addHelpText('after', `
@@ -83,42 +67,38 @@ Validation Config:
   whole skill). All codes are configurable via severity (error/warning/ignore)
   or allow entries. Expired allow entries are reported as ALLOW_EXPIRED warnings.
 
-Output:
-  YAML summary → stdout (for programmatic parsing)
-  Findings report → stderr (for human reading)
-
-  The stdout summary always publishes:
-    - status: success/warning/error (worst actionable severity in the run)
-    - issueCounts / runIssueCounts: the run total, always with all three
-      buckets, and the run-level (project config) share of it. The run total
-      always equals the sum of the per-skill rows plus runIssueCounts.
-    - skillsValidated: number of skills validated (the true denominator)
-    - durationSecs: validation time
-
-  By default, results[] is one row per skill WITH findings — its issue counts
-  and a per-code tally, dominant code first. A skill with no findings is
-  omitted from the listing entirely; a zero count is an absent field, never
-  "errors: 0". stderr prints the same thing as one line per skill.
-
-  --verbose publishes every validated skill (findings or not) with its full
-  detail: allErrors, ignoredErrors, observations, evidence and complete
-  metadata on stdout, one block per individual finding on stderr. That form is
-  meant for redirect-then-grep, not for reading — on a 90-skill repo it is
-  ~30x the default output.
-
-  Run-level findings (validation.allow entries no skill matched) are printed
-  in full in both forms; they belong to the project config, not to any skill.
+Output (YAML on stdout — the report envelope):
+  status: ok | findings | error. findings means at least one finding was
+          published; error means the run did not finish (error.code says why).
+  examined: the number of skills validated.
+  summary: the findings by severity — every skill's plus the run's.
+  findings[]: every finding, flat — {code, severity, message, location, …};
+          location is relative to data.root. Run-level findings (validation.allow
+          entries no skill matched) are here too, with no skill attached.
+  data.root: the directory the config was read from.
+  data.skills[]: one row per skill validated, clean or not —
+          {name, status, summary, allowed}. allowed counts the findings
+          validation.allow suppressed; they are never published as findings.
+
+  stderr is the human report: one line per skill with findings and every
+  error in full. --verbose adds every warning and info in full, the allowed
+  issues and the excluded reference paths. The document is the same either way.
 
   A run that validated ZERO skills — skills.include globs that matched no
-  SKILL.md — is refused, not passed: one non-overridable RESOURCE_CHECK_BROKEN
-  at error naming the globs, status: error, exit 1. A config with no skills:
-  block at all is "nothing to validate": no document, exit 0.
-
-Exit Codes:
-  0 - All validations passed (or all errors allowed by valid config)
-  1 - Validation errors found (severity=error, not allowed), or the run
-      validated no skill (skills.include matched nothing)
-  2 - System error (config invalid, skill path not found)
+  SKILL.md, or a config with no skills: block — is not a clean run: the
+  document carries one non-overridable RESOURCE_CHECK_BROKEN at error, exit 1,
+  and stderr names the globs that matched nothing.
+
+Exit Codes (derived from the document):
+  0 - status ok, or findings with no error-severity finding (warnings and
+      info never fail this command; allowed findings are not published)
+  1 - status findings with at least one error-severity finding, including
+      a run that validated no skill
+  2 - status error: the run did not finish — USAGE_INVALID for a [path] that
+      names no directory holding a config, an unknown --skill, or no project
+      root; INPUT_UNREADABLE for a directory the OS will not list, or a file
+      in the git repository the OS will not let git read (named);
+      CONFIG_INVALID for a config that does not parse
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)

package/dist/commands/skills/validate-command.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-command.js","sourceRoot":"","sources":["../../../src/commands/skills/validate-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,oBAAoB,EAA2B,MAAM,kBAAkB,CAAC;AACjF,OAAO,EAAqC,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnF;;;;;;;;;GASG;AACH,MAAM,aAAa,GAAuB;IACxC,OAAO,EAAE,qBAAqB;IAC9B,aAAa,EAAE,qBAAqB;CACrC,CAAC;AAEF,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAExC,OAAO;SACJ,WAAW,CAAC,sEAAsE,CAAC;SACnF,QAAQ,CAAC,QAAQ,EAAE,iEAAiE,CAAC;SACrF,MAAM,CAAC,gBAAgB,EAAE,8BAA8B,CAAC;SACxD,MAAM,CAAC,eAAe,EAAE,4FAA4F,CAAC;SACrH,MAAM,CAAC,aAAa,EAAE,sBAAsB,CAAC;SAC7C,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,OAAqC,EAAE,EAAE;QACnF,oBAAoB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC7C,MAAM,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkGL,CACI,CAAC;IAEJ,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"validate-command.js","sourceRoot":"","sources":["../../../src/commands/skills/validate-command.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAqC,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnF,MAAM,UAAU,qBAAqB;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;IAExC,OAAO;SACJ,WAAW,CAAC,sEAAsE,CAAC;SACnF,QAAQ,CAAC,QAAQ,EAAE,iEAAiE,CAAC;SACrF,MAAM,CAAC,gBAAgB,EAAE,8BAA8B,CAAC;SACxD,MAAM,CAAC,eAAe,EAAE,yFAAyF,CAAC;SAClH,MAAM,CAAC,aAAa,EAAE,sBAAsB,CAAC;SAC7C,MAAM,CAAC,KAAK,EAAE,OAA2B,EAAE,OAAqC,EAAE,EAAE;QACnF,MAAM,eAAe,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC,CAAC;SACD,WAAW,CACV,OAAO,EACP;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8FL,CACI,CAAC;IAEJ,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/commands/skills/validate-schema.d.ts

@@ -0,0 +1,199 @@
+/**
+ * The document `vat skills validate` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **One base, one meaning of `summary`.** `data.root` is the directory the
+ * config was read from, stated once; every finding's `location` is relative to
+ * it. `summary` — on the envelope and on a skill row — always counts FINDINGS
+ * by severity; the number of skills validated is the envelope's `examined`.
+ * Every finding is on the envelope, flat: a skill's own and the run's
+ * (`ALLOW_UNUSED`), so a row is a tally, never a second list.
+ */
+import { type Report } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat skills validate`, and the remedy when it is zero. */
+export declare const SKILLS_VALIDATE_EXAMINED: ExaminedDeclaration;
+declare const SkillsValidateDataSchema: z.ZodObject<{
+    /** The directory the config was read from — the ONE base every finding `location` is relative to. */
+    root: z.ZodString;
+    /** One row per skill validated, in validation order. */
+    skills: z.ZodArray<z.ZodObject<{
+        /** The skill's name, as discovery read it from its frontmatter. */
+        name: z.ZodString;
+        status: z.ZodEnum<["ok", "findings"]>;
+        /** The findings this skill published, by severity. */
+        summary: z.ZodObject<{
+            errors: z.ZodNumber;
+            warnings: z.ZodNumber;
+            info: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            info: number;
+            errors: number;
+            warnings: number;
+        }, {
+            info: number;
+            errors: number;
+            warnings: number;
+        }>;
+        /** Findings `validation.allow` suppressed for this skill — a count, never published as findings. */
+        allowed: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }, {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    skills: {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }[];
+    root: string;
+}, {
+    skills: {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }[];
+    root: string;
+}>;
+export type SkillsValidateData = z.infer<typeof SkillsValidateDataSchema>;
+/** The document this command publishes. */
+export declare const SKILLS_VALIDATE_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The directory the config was read from — the ONE base every finding `location` is relative to. */
+    root: z.ZodString;
+    /** One row per skill validated, in validation order. */
+    skills: z.ZodArray<z.ZodObject<{
+        /** The skill's name, as discovery read it from its frontmatter. */
+        name: z.ZodString;
+        status: z.ZodEnum<["ok", "findings"]>;
+        /** The findings this skill published, by severity. */
+        summary: z.ZodObject<{
+            errors: z.ZodNumber;
+            warnings: z.ZodNumber;
+            info: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            info: number;
+            errors: number;
+            warnings: number;
+        }, {
+            info: number;
+            errors: number;
+            warnings: number;
+        }>;
+        /** Findings `validation.allow` suppressed for this skill — a count, never published as findings. */
+        allowed: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }, {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    skills: {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }[];
+    root: string;
+}, {
+    skills: {
+        name: string;
+        status: "ok" | "findings";
+        summary: {
+            info: number;
+            errors: number;
+            warnings: number;
+        };
+        allowed: number;
+    }[];
+    root: string;
+}>, z.ZodObject<Omit<{
+    code: z.ZodString;
+    severity: z.ZodEnum<["error", "warning", "info", "ignore"]>;
+    message: z.ZodString;
+    location: z.ZodOptional<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>;
+    line: z.ZodOptional<z.ZodNumber>;
+    field: z.ZodOptional<z.ZodString>;
+    link: z.ZodOptional<z.ZodString>;
+    fix: z.ZodOptional<z.ZodString>;
+    reference: z.ZodOptional<z.ZodString>;
+    suggestion: z.ZodOptional<z.ZodString>;
+}, "severity"> & {
+    severity: z.ZodEnum<["error", "warning", "info"]>;
+    column: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}, {
+    code: string;
+    message: string;
+    severity: "error" | "warning" | "info";
+    fix?: string | undefined;
+    reference?: string | undefined;
+    location?: string | undefined;
+    line?: number | undefined;
+    field?: string | undefined;
+    link?: string | undefined;
+    suggestion?: string | undefined;
+    column?: number | undefined;
+}>>;
+export type SkillsValidateReport = Report<SkillsValidateData>;
+export {};
+//# sourceMappingURL=validate-schema.d.ts.map

package/dist/commands/skills/validate-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/skills/validate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAqD,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAC5G,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,EAAE,mBAMtC,CAAC;AAaF,QAAA,MAAM,wBAAwB;IAC5B,qGAAqG;;IAErG,wDAAwD;;QAZxD,mEAAmE;;;QAGnE,sDAAsD;;;;;;;;;;;;;;QAEtD,oGAAoG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS3F,CAAC;AAEZ,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E,2CAA2C;AAC3C,eAAO,MAAM,6BAA6B;IATxC,qGAAqG;;IAErG,wDAAwD;;QAZxD,mEAAmE;;;QAGnE,sDAAsD;;;;;;;;;;;;;;QAEtD,oGAAoG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAcJ,CAAC;AAEnG,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/commands/skills/validate-schema.js

@@ -0,0 +1,44 @@
+/**
+ * The document `vat skills validate` publishes, apart from the command.
+ *
+ * A sibling module because the published-shape registry imports it and the
+ * command imports the writer that imports the registry: a schema declared in
+ * the command module itself would be an import cycle, read before it is
+ * initialised.
+ *
+ * 🔑 **One base, one meaning of `summary`.** `data.root` is the directory the
+ * config was read from, stated once; every finding's `location` is relative to
+ * it. `summary` — on the envelope and on a skill row — always counts FINDINGS
+ * by severity; the number of skills validated is the envelope's `examined`.
+ * Every finding is on the envelope, flat: a skill's own and the run's
+ * (`ALLOW_UNUSED`), so a row is a tally, never a second list.
+ */
+import { FindingSchema, reportSchema, SeverityCountsSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat skills validate`, and the remedy when it is zero. */
+export const SKILLS_VALIDATE_EXAMINED = {
+    unit: 'skills',
+    whenZero: 'The run validated no skill, so it is not a verdict: the `skills.include` globs in'
+        + ' vibe-agent-toolkit.config.yaml matched no SKILL.md (usually a typo in the glob, a renamed'
+        + ' directory, or a `skills.exclude` that swallows every match), or the config declares no `skills:` block. Fix the patterns so they discover the skills this'
+        + ' project ships; stderr names the globs this run used.',
+};
+/** One validated skill — every one, clean or not. */
+const SkillRowSchema = z.object({
+    /** The skill's name, as discovery read it from its frontmatter. */
+    name: z.string(),
+    status: z.enum(['ok', 'findings']),
+    /** The findings this skill published, by severity. */
+    summary: SeverityCountsSchema,
+    /** Findings `validation.allow` suppressed for this skill — a count, never published as findings. */
+    allowed: z.number().int().nonnegative(),
+}).strict();
+const SkillsValidateDataSchema = z.object({
+    /** The directory the config was read from — the ONE base every finding `location` is relative to. */
+    root: z.string(),
+    /** One row per skill validated, in validation order. */
+    skills: z.array(SkillRowSchema),
+}).strict();
+/** The document this command publishes. */
+export const SKILLS_VALIDATE_REPORT_SCHEMA = reportSchema(SkillsValidateDataSchema, FindingSchema);
+//# sourceMappingURL=validate-schema.js.map

package/dist/commands/skills/validate-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-schema.js","sourceRoot":"","sources":["../../../src/commands/skills/validate-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,oBAAoB,EAAe,MAAM,4BAA4B,CAAC;AAC5G,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,wFAAwF;AACxF,MAAM,CAAC,MAAM,wBAAwB,GAAwB;IAC3D,IAAI,EAAE,QAAQ;IACd,QAAQ,EAAE,mFAAmF;UACzF,4FAA4F;UAC5F,4JAA4J;UAC5J,uDAAuD;CAC5D,CAAC;AAEF,qDAAqD;AACrD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,mEAAmE;IACnE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAClC,sDAAsD;IACtD,OAAO,EAAE,oBAAoB;IAC7B,oGAAoG;IACpG,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;CACxC,CAAC,CAAC,MAAM,EAAE,CAAC;AAEZ,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,qGAAqG;IACrG,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,wDAAwD;IACxD,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC;CAChC,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,6BAA6B,GAAG,YAAY,CAAC,wBAAwB,EAAE,aAAa,CAAC,CAAC"}