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

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

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

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

package/dist/commands/agent/install-path.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/install-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA+B,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAElF,qFAAqF;AACrF,qBAAa,0BAA2B,SAAQ,QAAQ;gBAC1C,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAOtD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKlF"}
+{"version":3,"file":"install-path.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/install-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAA+B,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAIlF,qFAAqF;AACrF,qBAAa,0BAA2B,SAAQ,QAAQ;gBAC1C,SAAS,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAOtD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKlF"}

package/dist/commands/agent/install-path.js

@@ -20,10 +20,11 @@
  * anything else.
  */
 import { isSingleFsSegment, safePath, VatError } from '@vibe-agent-toolkit/utils';
+import { AGENT_NAME_ESCAPES_SCOPE_CODE } from '../../utils/command-error-codes.js';
 /** Thrown when the positional cannot name an entry directly under the scope root. */
 export class AgentNameEscapesScopeError extends VatError {
     constructor(agentName, targetLocation) {
-        super('AGENT_NAME_ESCAPES_SCOPE', `Refusing to touch "${agentName}": an agent name must be a single path segment ` +
+        super(AGENT_NAME_ESCAPES_SCOPE_CODE, `Refusing to touch "${agentName}": an agent name must be a single path segment ` +
             `directly under ${targetLocation} (no separators, not "." or "..").`);
     }
 }

package/dist/commands/agent/install-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"install-path.js","sourceRoot":"","sources":["../../../src/commands/agent/install-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAElF,qFAAqF;AACrF,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,SAAiB,EAAE,cAAsB;QACnD,KAAK,CACH,0BAA0B,EAC1B,sBAAsB,SAAS,iDAAiD;YAC9E,kBAAkB,cAAc,oCAAoC,CACvE,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB,EAAE,SAAiB;IACxE,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,0BAA0B,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC"}
+{"version":3,"file":"install-path.js","sourceRoot":"","sources":["../../../src/commands/agent/install-path.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAElF,OAAO,EAAE,6BAA6B,EAAE,MAAM,oCAAoC,CAAC;AAEnF,qFAAqF;AACrF,MAAM,OAAO,0BAA2B,SAAQ,QAAQ;IACtD,YAAY,SAAiB,EAAE,cAAsB;QACnD,KAAK,CACH,6BAA6B,EAC7B,sBAAsB,SAAS,iDAAiD;YAC9E,kBAAkB,cAAc,oCAAoC,CACvE,CAAC;IACJ,CAAC;CACF;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB,EAAE,SAAiB;IACxE,IAAI,CAAC,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,0BAA0B,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAClE,CAAC;IACD,OAAO,QAAQ,CAAC,IAAI,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;AAClD,CAAC"}

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

@@ -0,0 +1,89 @@
+/**
+ * The document `vat agent install` 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 agent per run: `examined` is 1, the agent named. An install that could
+ * not finish is the envelope's error branch, never a finding, so an install
+ * publishes `ok` or `error`.
+ */
+import { z } from 'zod';
+import type { ExaminedDeclaration } from '../../utils/run-integrity.js';
+/** What `examined` counts for `vat agent install`, and the remedy when it is zero. */
+export declare const AGENT_INSTALL_EXAMINED: ExaminedDeclaration;
+declare const AgentInstallDataSchema: z.ZodObject<{
+    /** The agent name as given. */
+    agent: z.ZodString;
+    /** Where the agent is now installed. */
+    installPath: z.ZodString;
+    /** `true` for a `--dev` symlink to the built bundle, `false` for a copy. */
+    symlink: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    agent: string;
+    installPath: string;
+    symlink: boolean;
+}, {
+    agent: string;
+    installPath: string;
+    symlink: boolean;
+}>;
+export type AgentInstallData = z.infer<typeof AgentInstallDataSchema>;
+/** The document this command publishes. */
+export declare const AGENT_INSTALL_REPORT_SCHEMA: import("@vibe-agent-toolkit/schema").ReportZodSchema<z.ZodObject<{
+    /** The agent name as given. */
+    agent: z.ZodString;
+    /** Where the agent is now installed. */
+    installPath: z.ZodString;
+    /** `true` for a `--dev` symlink to the built bundle, `false` for a copy. */
+    symlink: z.ZodBoolean;
+}, "strict", z.ZodTypeAny, {
+    agent: string;
+    installPath: string;
+    symlink: boolean;
+}, {
+    agent: string;
+    installPath: string;
+    symlink: boolean;
+}>, 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 {};
+//# sourceMappingURL=install-schema.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-schema.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/install-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAExE,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,EAAE,mBAGpC,CAAC;AAEF,QAAA,MAAM,sBAAsB;IAC1B,+BAA+B;;IAE/B,wCAAwC;;IAExC,4EAA4E;;;;;;;;;;EAEnE,CAAC;AAEZ,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAEtE,2CAA2C;AAC3C,eAAO,MAAM,2BAA2B;IAXtC,+BAA+B;;IAE/B,wCAAwC;;IAExC,4EAA4E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAOgB,CAAC"}

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

@@ -0,0 +1,29 @@
+/**
+ * The document `vat agent install` 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 agent per run: `examined` is 1, the agent named. An install that could
+ * not finish is the envelope's error branch, never a finding, so an install
+ * publishes `ok` or `error`.
+ */
+import { FindingSchema, reportSchema } from '@vibe-agent-toolkit/schema';
+import { z } from 'zod';
+/** What `examined` counts for `vat agent install`, and the remedy when it is zero. */
+export const AGENT_INSTALL_EXAMINED = {
+    unit: 'agents named',
+    whenZero: 'No agent was installed — name one built agent: vat agent install <agentName>.',
+};
+const AgentInstallDataSchema = z.object({
+    /** The agent name as given. */
+    agent: z.string(),
+    /** Where the agent is now installed. */
+    installPath: z.string(),
+    /** `true` for a `--dev` symlink to the built bundle, `false` for a copy. */
+    symlink: z.boolean(),
+}).strict();
+/** The document this command publishes. */
+export const AGENT_INSTALL_REPORT_SCHEMA = reportSchema(AgentInstallDataSchema, FindingSchema);
+//# sourceMappingURL=install-schema.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"install-schema.js","sourceRoot":"","sources":["../../../src/commands/agent/install-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,sFAAsF;AACtF,MAAM,CAAC,MAAM,sBAAsB,GAAwB;IACzD,IAAI,EAAE,cAAc;IACpB,QAAQ,EAAE,+EAA+E;CAC1F,CAAC;AAEF,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IACtC,+BAA+B;IAC/B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,wCAAwC;IACxC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;IACvB,4EAA4E;IAC5E,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;CACrB,CAAC,CAAC,MAAM,EAAE,CAAC;AAIZ,2CAA2C;AAC3C,MAAM,CAAC,MAAM,2BAA2B,GAAG,YAAY,CAAC,sBAAsB,EAAE,aAAa,CAAC,CAAC"}

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

@@ -9,7 +9,13 @@ export interface InstallOptions {
     debug?: boolean;
 }
 /**
- * Install agent command
+ * Install agent command.
+ *
+ * The install is ONE tree-change plan: the copy, or the `--dev` link, is staged
+ * beside the install and swapped in whole, so a refused run leaves any previous
+ * install exactly as it was — every refusal publishes NOTHING_FINISHED, and
+ * that is the truth. A previous install the swap parked and the OS would not
+ * let VAT remove is a warning naming it, on a run that finished.
  */
 export declare function installAgent(agentName: string, options: InstallOptions): Promise<void>;
 //# sourceMappingURL=install.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/install.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgBH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CA0Ef"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../../src/commands/agent/install.ts"],"names":[],"mappings":"AAAA;;GAEG;AAmBH,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAWD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,IAAI,CAAC,CAaf"}