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

package/dist/commands/agent/build-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-schema.js","sourceRoot":"","sources":["../../../src/commands/agent/build-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAwB;IACvD,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,mJAAmJ;CAC9J,CAAC;AAEF,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,mCAAmC;IACnC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,mEAAmE;IACnE,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IAC1B,qCAAqC;IACrC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,6CAA6C;IAC7C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;CAC3B,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,yBAAyB,GAAG,YAAY,CAAC,oBAAoB,EAAE,aAAa,CAAC,CAAC"}

package/dist/commands/agent/build.d.ts

@@ -4,6 +4,7 @@
 export interface BuildCommandOptions {
     target?: string;
     output?: string;
+    force?: boolean;
     debug?: boolean;
 }
 /**

package/dist/commands/agent/build.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/build.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA8Cf"}
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/build.ts"],"names":[],"mappings":"AAAA;;GAEG;AAeH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAWD;;GAEG;AACH,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA+Cf"}

package/dist/commands/agent/build.js

@@ -1,56 +1,86 @@
 /**
  * Agent build command - Package agents for deployment targets
  */
-import { buildAgentSkill } from '@vibe-agent-toolkit/agent-skills';
-import { ExitCode } from '@vibe-agent-toolkit/schema';
+import { buildAgentSkill, isSkillPackagingInputError } from '@vibe-agent-toolkit/agent-skills';
+import { buildReport, toFindings } from '@vibe-agent-toolkit/schema';
+import { issueLocation, relativeEscapesRoot, safePath } from '@vibe-agent-toolkit/utils';
 import { resolveAgentPath } from '../../utils/agent-discovery.js';
-import { handleCommandError } from '../../utils/command-error.js';
+import { CommandRefusalError, refusalCodeOf } from '../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, leftoverIssue, NOTHING_FINISHED } from '../../utils/document-writer.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeYamlOutput } from '../../utils/output.js';
 import { requireProjectRoot } from '../../utils/project-root-policy.js';
+import { packagingFailedIssue } from '../skills/build.js';
+/** `vat agent build` has no `--strict` and publishes no finding: the gate is fixed. */
+const GATE = { strict: false };
+/** The one deployment target VAT builds. */
+const SKILL_TARGET = 'skill';
+/** One agent per run. */
+const AGENTS_BUILT = 1;
 /**
  * Build an agent for a specific deployment target
  */
 export async function buildCommand(pathOrName, options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
     const startTime = Date.now();
+    let report;
+    // Kept outside the try: a packager refusal is located at the agent, under the project root.
+    let projectRoot;
+    let agentPath;
     try {
         // Spec §7: `vat agent build` requires a projectRoot.
-        requireProjectRoot(process.cwd(), 'vat agent build');
-        const target = options.target ?? 'skill';
-        logger.debug(`Building agent for target: ${target}`);
-        // Resolve agent path
-        const agentPath = await resolveAgentPath(pathOrName, logger);
-        logger.debug(`Agent path resolved: ${agentPath}`);
-        // Build based on target
-        let result;
-        if (target === 'skill') {
-            logger.info('Building Agent Skill...');
-            // Only pass outputPath if explicitly provided by user
-            const buildOptions = options.output
-                ? { agentPath, target, outputPath: options.output }
-                : { agentPath, target };
-            result = await buildAgentSkill(buildOptions);
-        }
-        else {
-            throw new Error(`Unsupported build target: ${target}`);
+        projectRoot = requireProjectRoot(process.cwd(), 'vat agent build');
+        // A target VAT does not build is the invocation's mistake, refused before the agent is resolved or read.
+        const target = options.target ?? SKILL_TARGET;
+        if (target !== SKILL_TARGET) {
+            throw new CommandRefusalError('USAGE_INVALID', `Unsupported build target: ${target} (supported: ${SKILL_TARGET})`);
         }
-        const duration = Date.now() - startTime;
-        // Output success result
-        writeYamlOutput({
-            status: 'success',
-            agent: result.agent.name,
+        agentPath = await resolveAgentPath(pathOrName, logger);
+        logger.debug(`Agent path resolved: ${agentPath}`);
+        logger.info('Building Agent Skill...');
+        // Only pass outputPath if explicitly provided by user
+        const result = await buildAgentSkill({
+            agentPath,
             target,
-            output: result.outputPath,
-            files: result.files,
-            duration: `${duration}ms`,
+            ...(options.output ? { outputPath: options.output } : {}),
+            ...(options.force === true && { replaceExistingOutput: true }),
         });
-        logger.info(`Build completed in ${duration}ms`);
+        const durationMs = Date.now() - startTime;
+        logger.info(`Build completed in ${durationMs}ms`);
         logger.info(`Output: ${result.outputPath}`);
-        process.exit(ExitCode.OK);
+        report = buildReport({
+            examined: AGENTS_BUILT,
+            // A previous build the swap parked and the OS would not let VAT remove: the build is done, the leftover named.
+            findings: toFindings(result.residue.map(({ message, path }) => leftoverIssue(message, path))),
+            data: { agent: result.agent.name, target, output: result.outputPath, files: result.files },
+            gate: GATE,
+            durationMs,
+        });
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'AgentBuild');
+        const refusal = buildRefusalOf(error, agentPath, projectRoot);
+        endWithRefusal('agent build', refusal.code, error, 'yaml', GATE, refusal.finished);
     }
+    endWithReport('agent build', report, 'yaml');
+}
+/**
+ * The refusal a build that threw ends on. A coded cause keeps its own code. The
+ * packager refusing the generated bundle's content — content the adopter's
+ * prompt and output directory decide — is the `SKILL_PACKAGING_FAILED` finding
+ * at the agent on a run that stopped (`RUN_INCOMPLETE`), as `vat skill test run`
+ * publishes it; anything uncoded is a defect, `INTERNAL_ERROR`.
+ */
+function buildRefusalOf(error, agentPath, projectRoot) {
+    const code = refusalCodeOf(error);
+    if (code !== 'INTERNAL_ERROR' || !isSkillPackagingInputError(error))
+        return { code, finished: NOTHING_FINISHED };
+    const issue = packagingFailedIssue(error instanceof Error ? error.message : String(error), agentLocation(agentPath, projectRoot), 'rebuild', error);
+    return { code: 'RUN_INCOMPLETE', finished: { examined: 0, findings: toFindings([issue]), data: null } };
+}
+/** The agent's path relative to the project root, or `undefined` when it is outside it (or unknown). */
+function agentLocation(agentPath, projectRoot) {
+    if (agentPath === undefined || projectRoot === undefined)
+        return undefined;
+    const location = issueLocation(safePath.resolve(agentPath), projectRoot);
+    return relativeEscapesRoot(location) ? undefined : location;
 }
 //# sourceMappingURL=build.js.map

package/dist/commands/agent/build.js.map

@@ -1 +1 @@
-{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/commands/agent/build.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AAEtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAQxE;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAkB,EAClB,OAA4B;IAE5B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,qDAAqD;QACrD,kBAAkB,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,iBAAiB,CAAC,CAAC;QAErD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;QACzC,MAAM,CAAC,KAAK,CAAC,8BAA8B,MAAM,EAAE,CAAC,CAAC;QAErD,qBAAqB;QACrB,MAAM,SAAS,GAAG,MAAM,gBAAgB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QAC7D,MAAM,CAAC,KAAK,CAAC,wBAAwB,SAAS,EAAE,CAAC,CAAC;QAElD,wBAAwB;QACxB,IAAI,MAAM,CAAC;QACX,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAC;YACvC,sDAAsD;YACtD,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM;gBACjC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE;gBACnD,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;YAC1B,MAAM,GAAG,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC;QAC/C,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,EAAE,CAAC,CAAC;QACzD,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAExC,wBAAwB;QACxB,eAAe,CAAC;YACd,MAAM,EAAE,SAAS;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI;YACxB,MAAM;YACN,MAAM,EAAE,MAAM,CAAC,UAAU;YACzB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,QAAQ,EAAE,GAAG,QAAQ,IAAI;SAC1B,CAAC,CAAC;QAEH,MAAM,CAAC,IAAI,CAAC,sBAAsB,QAAQ,IAAI,CAAC,CAAC;QAChD,MAAM,CAAC,IAAI,CAAC,WAAW,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC"}
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/commands/agent/build.ts"],"names":[],"mappings":"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"}

package/dist/commands/agent/import-schema.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The document `vat agent import` 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 (the cycle
+ * `report-schemas.ts` describes).
+ *
+ * One skill per run: `examined` is 1 when it was imported. An import that could
+ * not finish is the envelope's error branch — the refusal `importSkillToAgent`
+ * names at its cause — never a finding, so an import publishes `ok` or `error`.
+ */
+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 agent import`, and the remedy when it is zero. */
+export declare const AGENT_IMPORT_EXAMINED: ExaminedDeclaration;
+declare const AgentImportDataSchema: z.ZodObject<{
+    /** The agent.yaml the import wrote. */
+    agentPath: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    agentPath: string;
+}, {
+    agentPath: string;
+}>;
+export type AgentImportData = z.infer<typeof AgentImportDataSchema>;
+/** The document this command publishes. */
+export declare const AGENT_IMPORT_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The agent.yaml the import wrote. */
+    agentPath: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    agentPath: string;
+}, {
+    agentPath: 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 AgentImportReport = Report<AgentImportData>;
+export {};
+//# sourceMappingURL=import-schema.d.ts.map

package/dist/commands/agent/import-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/import-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA+B,KAAK,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,qFAAqF;AACrF,eAAO,MAAM,qBAAqB,EAAE,mBAGnC,CAAC;AAEF,QAAA,MAAM,qBAAqB;IACzB,uCAAuC;;;;;;EAE9B,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,2CAA2C;AAC3C,eAAO,MAAM,0BAA0B;IAPrC,uCAAuC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAOmD,CAAC;AAE7F,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC"}

package/dist/commands/agent/import-schema.js

@@ -0,0 +1,25 @@
+/**
+ * The document `vat agent import` 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 (the cycle
+ * `report-schemas.ts` describes).
+ *
+ * One skill per run: `examined` is 1 when it was imported. An import that could
+ * not finish is the envelope's error branch — the refusal `importSkillToAgent`
+ * names at its cause — never a finding, so an import publishes `ok` or `error`.
+ */
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat agent import`, and the remedy when it is zero. */
+export const AGENT_IMPORT_EXAMINED = {
+    unit: 'skills imported',
+    whenZero: 'No skill was imported — point the command at a SKILL.md file.',
+};
+const AgentImportDataSchema = z.object({
+    /** The agent.yaml the import wrote. */
+    agentPath: z.string(),
+}).strict();
+/** The document this command publishes. */
+export const AGENT_IMPORT_REPORT_SCHEMA = reportSchema(AgentImportDataSchema, FindingSchema);
+//# sourceMappingURL=import-schema.js.map

package/dist/commands/agent/import-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-schema.js","sourceRoot":"","sources":["../../../src/commands/agent/import-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAe,MAAM,4BAA4B,CAAC;AACtF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,qFAAqF;AACrF,MAAM,CAAC,MAAM,qBAAqB,GAAwB;IACxD,IAAI,EAAE,iBAAiB;IACvB,QAAQ,EAAE,+DAA+D;CAC1E,CAAC;AAEF,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,uCAAuC;IACvC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;CACtB,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,0BAA0B,GAAG,YAAY,CAAC,qBAAqB,EAAE,aAAa,CAAC,CAAC"}

package/dist/commands/agent/import.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/import.ts"],"names":[],"mappings":"AAAA;;GAEG;AAWH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA+Cf"}
+{"version":3,"file":"import.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/import.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,MAAM,WAAW,oBAAoB;IACnC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAiBD,wBAAsB,aAAa,CACjC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAoCf"}

package/dist/commands/agent/import.js

@@ -2,19 +2,31 @@
  * Agent import command - convert SKILL.md to agent.yaml
  */
 import { importSkillToAgent } from '@vibe-agent-toolkit/agent-skills';
-import { ExitCode } from '@vibe-agent-toolkit/schema';
-import { safePath } from '@vibe-agent-toolkit/utils';
-import { handleCommandError } from '../../utils/command-error.js';
+import { buildReport } from '@vibe-agent-toolkit/schema';
+import { isVatError, safePath, TREE_DEST_OCCUPIED_CODE } from '@vibe-agent-toolkit/utils';
+import { CommandRefusalError, refusalCodeOf } from '../../utils/command-refusal.js';
+import { endWithRefusal, endWithReport, NOTHING_FINISHED } from '../../utils/document-writer.js';
 import { createLogger } from '../../utils/logger.js';
-import { writeYamlOutput } from '../../utils/output.js';
+/** `vat agent import` has no `--strict` and publishes no finding: the gate is fixed. */
+const GATE = { strict: false };
+/** One skill per run. */
+const SKILLS_IMPORTED = 1;
+/**
+ * An occupied output: the invocation's to fix. `--force` is advised only where it would serve — a
+ * file there, and the flag not given; under `--force` the one thing still refused is a directory.
+ */
+function occupiedOutputRefusal(error, forced) {
+    if (!isVatError(error, TREE_DEST_OCCUPIED_CODE))
+        return error;
+    return new CommandRefusalError('USAGE_INVALID', forced ? error.message : `${error.message}. Use --force to overwrite.`, { cause: error });
+}
 export async function importCommand(skillPath, options) {
     const logger = createLogger(options.debug ? { debug: true } : {});
     const startTime = Date.now();
+    let report;
     try {
-        // Resolve path
         const resolvedSkillPath = safePath.resolve(skillPath);
         logger.debug(`Importing Agent Skill: ${resolvedSkillPath}`);
-        // Import SKILL.md to agent.yaml
         const importOptions = {
             skillPath: resolvedSkillPath,
             force: options.force ?? false,
@@ -22,30 +34,24 @@ export async function importCommand(skillPath, options) {
         if (options.output) {
             importOptions.outputPath = safePath.resolve(options.output);
         }
-        const result = await importSkillToAgent(importOptions);
-        if (!result.success) {
-            // Import failed
-            const output = {
-                status: 'error',
-                error: result.error,
-                duration: `${Date.now() - startTime}ms`,
-            };
-            writeYamlOutput(output);
-            logger.error(`Import failed: ${result.error}`);
-            process.exit(ExitCode.ERROR);
-        }
-        // Import successful
-        const output = {
-            status: 'success',
-            agentPath: result.agentPath,
-            duration: `${Date.now() - startTime}ms`,
-        };
-        writeYamlOutput(output);
+        const result = await importSkillToAgent(importOptions).catch((error) => {
+            throw occupiedOutputRefusal(error, importOptions.force === true);
+        });
+        // The library names the refusal where it was raised; nothing was written.
+        if (!result.success)
+            throw new CommandRefusalError(result.refusal, result.error);
         logger.info(`Successfully imported Agent Skill to: ${result.agentPath}`);
-        process.exit(ExitCode.OK);
+        report = buildReport({
+            examined: SKILLS_IMPORTED,
+            findings: [],
+            data: { agentPath: result.agentPath },
+            gate: GATE,
+            durationMs: Date.now() - startTime,
+        });
     }
     catch (error) {
-        handleCommandError(error, logger, startTime, 'AgentImport');
+        endWithRefusal('agent import', refusalCodeOf(error), error, 'yaml', GATE, NOTHING_FINISHED);
     }
+    endWithReport('agent import', report, 'yaml');
 }
 //# sourceMappingURL=import.js.map

package/dist/commands/agent/import.js.map

@@ -1 +1 @@
-{"version":3,"file":"import.js","sourceRoot":"","sources":["../../../src/commands/agent/import.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,MAAM,4BAA4B,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAGrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAClE,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQxD,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,SAAiB,EACjB,OAA6B;IAE7B,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,IAAI,CAAC;QACH,eAAe;QACf,MAAM,iBAAiB,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACtD,MAAM,CAAC,KAAK,CAAC,0BAA0B,iBAAiB,EAAE,CAAC,CAAC;QAE5D,gCAAgC;QAChC,MAAM,aAAa,GAA6C;YAC9D,SAAS,EAAE,iBAAiB;YAC5B,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,KAAK;SAC9B,CAAC;QAEF,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnB,aAAa,CAAC,UAAU,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAC9D,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,aAAa,CAAC,CAAC;QAEvD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,gBAAgB;YAChB,MAAM,MAAM,GAAG;gBACb,MAAM,EAAE,OAAO;gBACf,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,QAAQ,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI;aACxC,CAAC;YAEF,eAAe,CAAC,MAAM,CAAC,CAAC;YACxB,MAAM,CAAC,KAAK,CAAC,kBAAkB,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC/B,CAAC;QAED,oBAAoB;QACpB,MAAM,MAAM,GAAG;YACb,MAAM,EAAE,SAAS;YACjB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,QAAQ,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,IAAI;SACxC,CAAC;QAEF,eAAe,CAAC,MAAM,CAAC,CAAC;QACxB,MAAM,CAAC,IAAI,CAAC,yCAAyC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC;QACzE,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IAC5B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,CAAC,CAAC;IAC9D,CAAC;AACH,CAAC"}
+{"version":3,"file":"import.js","sourceRoot":"","sources":["../../../src/commands/agent/import.ts"],"names":[],"mappings":"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"}

package/dist/commands/agent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,wBAAgB,kBAAkB,IAAI,OAAO,CAsS5C;AAED,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAoBpC,wBAAgB,kBAAkB,IAAI,OAAO,CAqY5C;AAED,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC"}

package/dist/commands/agent/index.js

@@ -52,6 +52,17 @@ Description:
     - agents/
     - . (current directory)
 
+Output (YAML on stdout; the human list on stderr):
+  status: ok | findings;  examined: 3 (the search paths scanned)
+  findings[]: SCAN_PATH_UNREADABLE (warning) per search path, agent
+    directory or manifest the OS would not read — the list is then a
+    floor, not the answer
+  data: { root, agents: [{ name, version, path }] } — path relative to root
+
+Exit Codes (derived from the document):
+  0 - ok, or findings (an unreadable path is a warning)
+  2 - error: only a defect in VAT (INTERNAL_ERROR)
+
 Requirements:
   projectRoot: optional (tolerates absence)
   config:      not used
@@ -67,6 +78,7 @@ Example:
         .description('Build agent for deployment target')
         .option('--target <type>', 'Build target (skill, langchain, etc.)', 'skill')
         .option('--output <path>', 'Output directory (default: dist/vat-bundles/<target>/<agent>)')
+        .option('--force', 'Replace a previous build at <output>/<agent> (swapped in whole once built); without it, one that holds anything is refused')
         .option('--debug', DEBUG_OPTION_DESC)
         .action(buildCommand)
         .addHelpText('after', `
@@ -76,15 +88,43 @@ Description:
 
   Argument: agent name OR path to agent directory/manifest file
 
+  VAT never deletes or overwrites what it did not produce. With --output, an
+  <output>/<agent-name>/ that already holds anything is refused (USAGE_INVALID)
+  and left exactly as it was, unless --force says it is a previous build to
+  replace. An empty directory is replaced as-is; an output holding the agent's
+  own source is refused even with --force. The default location is VAT's and
+  is replaced. Every source is read before anything is written, and the build
+  is written whole beside its output and swapped in: a failure partway leaves
+  a previous build exactly as it was.
+
 Targets:
   - skill: Agent Skills (for Claude Desktop/Code)
   - More targets coming soon (langchain, etc.)
 
-Output:
-  Default location: dist/vat-bundles/<target>/<agent-name>/
-
-Exit Codes:
-  0 - Success  |  1 - Build error  |  2 - System error
+Output (YAML on stdout):
+  status: ok | error;  examined: 1 (the agent built)
+  data: { agent, target, output, files }
+  findings[]: SKILL_PACKAGING_FAILED on the error branch; on success, a
+    TREE_CLEANUP_INCOMPLETE warning naming a previous build the swap replaced
+    that the OS would not let VAT remove
+  Default build location: dist/vat-bundles/<target>/<agent-name>/
+
+Exit Codes (derived from the document):
+  0 - ok: the agent was built
+  2 - error: nothing was built — USAGE_INVALID (a --target other than
+      skill, no projectRoot, the path or name names no manifest, no
+      package.json encloses the agent and --output was not given, an
+      --output whose agent directory holds something and no --force, or an
+      output holding the agent's own source),
+      CONFIG_INVALID (the manifest does not validate, declares no system
+      prompt, or its $ref names no file), INPUT_UNREADABLE (an agent
+      search path looked up by name, the manifest, its system prompt,
+      scripts/, LICENSE.txt or package.json cannot be read, or the system
+      prompt, LICENSE.txt or a file under scripts/ is a named pipe, socket or
+      device), RUN_INCOMPLETE (the packager refused the bundle's content — a
+      SKILL_PACKAGING_FAILED finding at the agent — or the OS would not let
+      the build write its output: a full disk, a read-only or unwritable
+      --output, a file in its way; no finding)
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)
@@ -96,6 +136,7 @@ Examples:
   $ vat agent build agent-generator                    # Build as Agent Skill
   $ vat agent build agent-generator --target skill     # Explicit target
   $ vat agent build ./my-agent --output ./my-skill     # Custom output path
+  $ vat agent build ./my-agent --output ./my-skill --force  # Replace the previous build there
 `);
     agent
         .command('run <pathOrName> <userInput>')
@@ -111,7 +152,7 @@ Description:
   User input: The input text/query for the agent
 
 Exit Codes:
-  0 - Success  |  1 - Execution error  |  2 - System error
+  0 - Success  |  2 - Any failure (the agent did not load, or the run failed)
 
 Examples:
   $ vat agent run agent-generator "Create a code review agent"
@@ -137,19 +178,28 @@ Requirements:
 Description:
   Validates agent manifest schema (using @vibe-agent-toolkit/schema),
   LLM configuration, tool definitions, and resource availability. Outputs
-  YAML validation report to stdout, errors to stderr.
+  the report envelope (YAML) to stdout, findings to stderr.
 
   Argument: agent name OR path to agent directory/manifest file
 
 Validation Checks:
-  - Manifest schema (apiVersion, kind, metadata, spec)
-  - LLM provider and model configuration
-  - Tool configurations (RAG databases)
-  - Resource files (prompts, docs, templates)
-  - Prompt references ($ref paths)
-
-Exit Codes:
-  0 - Valid  |  1 - Validation errors  |  2 - System error
+  - Manifest schema (apiVersion, kind, metadata, spec) — AGENT_MANIFEST_INVALID
+  - Tool configurations (RAG databases) — AGENT_REFERENCE_MISSING,
+    AGENT_RAG_NO_SOURCES
+  - Resource files and prompt $ref paths — AGENT_REFERENCE_MISSING,
+    AGENT_REFERENCE_UNREADABLE
+
+Output (YAML on stdout):
+  status: ok | findings | error;  examined: 1 (the manifest read)
+  findings[]: each located at the manifest, relative to data.root
+  data: { root, manifest: { name, version, path } }
+
+Exit Codes (derived from the document):
+  0 - ok, or findings with no error-severity finding
+  1 - findings with an error-severity finding
+  2 - error: no manifest to judge — USAGE_INVALID (the path or name names
+      no manifest), INPUT_UNREADABLE (the manifest is unreadable or not
+      YAML, or an agent search path looked up by name cannot be read)
 
 Requirements:
   projectRoot: required (errors if no vibe-agent-toolkit.config.yaml or .git/ ancestor)
@@ -184,8 +234,18 @@ Conversion:
   - Preserves version from metadata.version or defaults to 0.1.0
   - Validates frontmatter before conversion
 
-Exit Codes:
-  0 - Success  |  1 - Validation/conversion error  |  2 - System error
+Output (YAML on stdout):
+  status: ok | error;  examined: 1 (the skill imported)
+  data: { agentPath }
+
+Exit Codes (derived from the document):
+  0 - ok: agent.yaml was written
+  2 - error: nothing was written — USAGE_INVALID (no SKILL.md at the path,
+      or something is already at the output and --force was not given),
+      INPUT_UNREADABLE (the SKILL.md cannot be read, or no Agent Skills schema
+      accepts its frontmatter), RUN_INCOMPLETE (the OS would not let VAT
+      examine or write the output). A --output whose directory does not exist
+      yet is made.
 
 Examples:
   $ vat agent import ./my-skill/SKILL.md              # Import to same directory
@@ -204,15 +264,34 @@ Examples:
         .addHelpText('after', `
 Description:
   Installs a built agent skill to Agent Skills directory. By default,
-  copies to user scope (~/.claude/skills/). Use --dev for symlink mode
+  copies to user scope. Use --dev for symlink mode
   (rapid development iteration).
 
 Scopes:
-  - user: ~/.claude/skills/ (default, personal skills)
-  - project: ./.claude/skills/ (project-local skills)
-
-Exit Codes:
-  0 - Success  |  1 - Installation error  |  2 - System error
+  - user: $CLAUDE_CONFIG_DIR/skills/, else ~/.claude/skills/ (default, personal skills)
+  - project: .claude/skills/ under the working directory (--cwd sets it)
+
+Output (YAML on stdout):
+  status: ok | error;  examined: 1 (the agent named)
+  data: { agent, installPath, symlink } — symlink is true under --dev
+  findings: a TREE_CLEANUP_INCOMPLETE warning naming a replaced install
+    VAT could not remove (the new one is in place)
+
+Exit Codes (derived from the document):
+  0 - ok: the agent was installed
+  2 - error: nothing was installed — USAGE_INVALID (an unknown --scope or
+      --runtime, a name that is not one path segment or names no agent,
+      anything but an empty directory is at the install path and --force
+      was not given, or no package.json encloses the agent),
+      NOT_IMPLEMENTED (--dev on Windows), CONFIG_INVALID (the manifest does
+      not validate), INPUT_UNREADABLE (the bundle was never built, holds a
+      named pipe, socket or device or a symlink that leads out of it or
+      nowhere, or a search path, the manifest or any file in the bundle
+      cannot be read), RUN_INCOMPLETE (the install path cannot be examined,
+      or a write under the scope directory failed).
+      The copy or link is staged beside the install and swapped in whole,
+      so a refused run, --force --dev included, leaves a previous install
+      as it was
 
 Examples:
   $ vat agent install agent-generator                  # Install to user scope
@@ -235,11 +314,23 @@ Description:
   Handles both copied installations and symlinks.
 
 Scopes:
-  - user: ~/.claude/skills/ (default)
-  - project: ./.claude/skills/
-
-Exit Codes:
-  0 - Success  |  1 - Not installed  |  2 - System error
+  - user: $CLAUDE_CONFIG_DIR/skills/, else ~/.claude/skills/ (default)
+  - project: .claude/skills/ under the working directory (--cwd sets it)
+
+Output (YAML on stdout):
+  status: ok | error;  examined: 1 (the agent named)
+  data: { agent, installPath, wasSymlink } — wasSymlink for a --dev install
+    (only the link is removed, never its target)
+
+Exit Codes (derived from the document):
+  0 - ok: the install was removed
+  2 - error: USAGE_INVALID (an unknown --scope or --runtime, a name that is
+      not one path segment, or the agent is not installed in that scope:
+      nothing was removed), RUN_INCOMPLETE (the install path cannot be
+      examined or moved off its path: nothing was removed). The install is
+      first moved off its path whole, then deleted: a deletion the OS stops
+      after that is still RUN_INCOMPLETE, but the uninstall is done — data is
+      present, and a TREE_CLEANUP_INCOMPLETE warning names where the rest is
 
 Examples:
   $ vat agent uninstall agent-generator                  # Remove from user scope
@@ -259,15 +350,19 @@ Description:
 
 Scopes:
   - all: Scan all scopes (default)
-  - user: Only ~/.claude/skills/
-  - project: Only ./.claude/skills/
-
-Output:
-  YAML summary → stdout (for programmatic parsing)
-  Human-readable list → stderr
-
-Exit Codes:
-  0 - Success  |  2 - System error
+  - user: Only $CLAUDE_CONFIG_DIR/skills/, else ~/.claude/skills/
+  - project: Only .claude/skills/ under the working directory (--cwd sets it)
+
+Output (YAML on stdout; the human list on stderr):
+  status: ok | findings | error;  examined: the scopes scanned
+  findings[]: SCAN_PATH_UNREADABLE (warning) per scope directory the OS
+    would not list — the list is then a floor, not the answer; its field
+    is the scope, its location the scope directory's last two segments
+  data: { scanned, skills: [{ name, scope, type: symlink | directory, path }] }
+
+Exit Codes (derived from the document):
+  0 - ok, or findings (an unreadable scope is a warning)
+  2 - error: USAGE_INVALID (a --scope or --runtime it does not know)
 
 Examples:
   $ vat agent installed                    # List all installed skills