@vibe-agent-toolkit/cli 0.1.36 → 0.1.38

package/dist/utils/config-loader.js

@@ -5,32 +5,11 @@
  * - VAT_TEST_CONFIG: Override config file path for testing (absolute path)
  */
 import { readFileSync, existsSync } from 'node:fs';
-import { dirname, parse } from 'node:path';
+import { dirname } from 'node:path';
 import { ProjectConfigSchema } from '@vibe-agent-toolkit/resources';
 import { safePath } from '@vibe-agent-toolkit/utils';
-import * as yaml from 'js-yaml';
+import * as yaml from 'yaml';
 const CONFIG_FILENAME = 'vibe-agent-toolkit.config.yaml';
-/**
- * Find configuration file by walking up directory tree
- * @param startDir - Starting directory (defaults to cwd)
- * @returns Path to config file, or null if not found
- */
-export function findConfigPath(startDir) {
-    let currentDir = safePath.resolve(startDir ?? process.cwd());
-    const root = parse(currentDir).root;
-    while (currentDir !== root) {
-        const configPath = safePath.join(currentDir, CONFIG_FILENAME);
-        // eslint-disable-next-line security/detect-non-literal-fs-filename -- Dynamic path walking is required for config file search
-        if (existsSync(configPath)) {
-            return configPath;
-        }
-        const parent = dirname(currentDir);
-        if (parent === currentDir)
-            break; // safety: at filesystem root
-        currentDir = parent;
-    }
-    return null;
-}
 /**
  * Load and validate project configuration
  *
@@ -62,7 +41,7 @@ export function loadConfig(projectRoot) {
     try {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- configPath is derived from projectRoot parameter
         const content = readFileSync(configPath, 'utf-8');
-        const parsed = yaml.load(content);
+        const parsed = yaml.parse(content);
         // Validate with canonical schema from resources package
         const result = ProjectConfigSchema.safeParse(parsed);
         if (!result.success) {
@@ -84,58 +63,48 @@ export function getConfigDir(configPath) {
     return dirname(configPath);
 }
 /**
- * Module-level cache keyed by configRoot → parsed ProjectConfig (or null if
- * the file failed to load). Avoids re-parsing the same config yaml repeatedly
- * when audit walks up from many sibling skills.
+ * Layer 2 cache for {@link loadConfigCached}.
+ *
+ * Keyed by `projectRoot` → parsed {@link ProjectConfig} (or `null` if the
+ * file failed to load). Avoids re-parsing the same config yaml repeatedly
+ * when audit walks up from many sibling skills sharing one governing config.
+ *
+ * Tests that mutate fixtures between runs must call
+ * {@link resetLoadedConfigCache} to invalidate this cache.
  *
- * Tests that mutate fixtures between runs must call {@link resetGoverningConfigCache}
- * to invalidate this cache.
+ * See spec docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §8.
  */
-const governingConfigCache = new Map();
+const loadedConfigCache = new Map();
 /**
- * Reset the governing-config cache used by {@link findGoverningConfig}.
- * Call at the start of each `vat audit` invocation so in-process test suites
- * that mutate fixtures between runs do not observe stale config data.
+ * Reset the cache used by {@link loadConfigCached}.
+ *
+ * Call at the start of each independent CLI invocation (e.g. `vat audit`) so
+ * in-process callers don't observe stale config data across runs.
  */
-export function resetGoverningConfigCache() {
-    governingConfigCache.clear();
+export function resetLoadedConfigCache() {
+    loadedConfigCache.clear();
 }
 /**
- * Walk UP from `skillDir` looking for the nearest-ancestor
- * `vibe-agent-toolkit.config.yaml`. Loads and caches the config on first hit.
- *
- * Returns the parsed config plus the `configRoot` (directory that contained the
- * yaml), or `null` if no config is found anywhere up the tree.
+ * Cached variant of {@link loadConfig} keyed by `projectRoot`.
  *
- * **Cache behavior:** Both successful loads and parse failures are cached
- * (failures as `null`) so a broken config doesn't re-parse on every skill in
- * the same scan. A test that edits a broken config into a good one between
- * calls must invoke {@link resetGoverningConfigCache} to pick up the new
- * state — the audit CLI entrypoint already does this via `resetAuditCaches()`.
+ * Both successful loads and parse failures are cached (failures as `null`)
+ * so a broken config doesn't re-parse on every skill in the same scan. A
+ * test that edits a broken config into a good one between calls must invoke
+ * {@link resetLoadedConfigCache} (audit's `resetAuditCaches()` does this).
  */
-export function findGoverningConfig(skillDir) {
-    const configPath = findConfigPath(skillDir);
-    if (configPath === null) {
-        return null;
-    }
-    const configRoot = dirname(configPath);
-    const cached = governingConfigCache.get(configRoot);
-    if (cached !== undefined) {
-        return cached === null ? null : { config: cached, configRoot };
-    }
+export function loadConfigCached(projectRoot) {
+    const cached = loadedConfigCache.get(projectRoot);
+    if (cached !== undefined)
+        return cached ?? undefined;
     try {
-        const config = loadConfig(configRoot);
-        if (config === undefined) {
-            governingConfigCache.set(configRoot, null);
-            return null;
-        }
-        governingConfigCache.set(configRoot, config);
-        return { config, configRoot };
+        const config = loadConfig(projectRoot);
+        loadedConfigCache.set(projectRoot, config ?? null);
+        return config;
     }
     catch {
-        // Invalid config — cache as null so we don't re-parse on every skill.
-        governingConfigCache.set(configRoot, null);
-        return null;
+        // Cache failures as null so a broken config doesn't re-parse per skill.
+        loadedConfigCache.set(projectRoot, null);
+        return undefined;
     }
 }
 //# sourceMappingURL=config-loader.js.map

package/dist/utils/config-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EAAE,mBAAmB,EAAsB,MAAM,+BAA+B,CAAC;AACxF,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B,MAAM,eAAe,GAAG,gCAAgC,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CAAC,WAAmB;IAC5C,sEAAsE;IACtE,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;IAEjG,uIAAuI;IACvI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,CAAC;QACH,uHAAuH;QACvH,MAAM,OAAO,GAAG,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAEnC,wDAAwD;QACxD,MAAM,MAAM,GAAG,mBAAmB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAErD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CACb,+BAA+B,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,CACtD,CAAC;QACJ,CAAC;QAED,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,OAAO,OAAO,CAAC,UAAU,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,iBAAiB,GAAsC,IAAI,GAAG,EAAE,CAAC;AAEvE;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,iBAAiB,CAAC,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,WAAmB;IAClD,MAAM,MAAM,GAAG,iBAAiB,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAClD,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,IAAI,SAAS,CAAC;IACrD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;QACvC,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC;QACnD,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,iBAAiB,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;QACzC,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/utils/logger.d.ts

@@ -4,6 +4,7 @@
  */
 export interface Logger {
     info: (message: string) => void;
+    warn: (message: string) => void;
     error: (message: string) => void;
     debug: (message: string) => void;
 }

package/dist/utils/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAgBhE"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjC,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,YAAY,CAAC,OAAO,GAAE,aAAkB,GAAG,MAAM,CAmBhE"}

package/dist/utils/logger.js

@@ -8,6 +8,9 @@ export function createLogger(options = {}) {
         info: (message) => {
             process.stderr.write(`${message}\n`);
         },
+        warn: (message) => {
+            process.stderr.write(`${message}\n`);
+        },
         error: (message) => {
             process.stderr.write(`${message}\n`);
         },

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAYH,MAAM,UAAU,YAAY,CAAC,UAAyB,EAAE;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IAErC,OAAO;QACL,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,EAAE;YACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,EAAE;YACzB,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,OAAO,IAAI,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,MAAM,UAAU,YAAY,CAAC,UAAyB,EAAE;IACtD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,KAAK,CAAC;IAErC,OAAO;QACL,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE;YACxB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,EAAE;YACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;QACvC,CAAC;QACD,KAAK,EAAE,CAAC,OAAe,EAAE,EAAE;YACzB,IAAI,KAAK,EAAE,CAAC;gBACV,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,OAAO,IAAI,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/utils/output.js

@@ -2,17 +2,17 @@
  * Output utilities for structured data
  * YAML output on stdout, logs on stderr
  */
-import * as yaml from 'js-yaml';
+import * as yaml from 'yaml';
 /**
  * Write YAML output to stdout with document markers
  * @param data - Data to serialize as YAML
  */
 export function writeYamlOutput(data) {
     process.stdout.write('---\n');
-    process.stdout.write(yaml.dump(data, {
+    process.stdout.write(yaml.stringify(data, {
         indent: 2,
         lineWidth: 120,
-        noRefs: true,
+        aliasDuplicateObjects: false,
     }));
     process.stdout.write('---\n');
 }

package/dist/utils/output.js.map

@@ -1 +1 @@
-{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAEhC;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE;QACnC,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,GAAG;QACd,MAAM,EAAE,IAAI;KACb,CAAC,CAAC,CAAC;IACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,IAAY,EACZ,MAAc,EACd,OAAe;IAEf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC;AAClE,CAAC"}
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE;QACxC,MAAM,EAAE,CAAC;QACT,SAAS,EAAE,GAAG;QACd,qBAAqB,EAAE,KAAK;KAC7B,CAAC,CAAC,CAAC;IACJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AAChC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW;IAC/B,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QACnC,IAAI,OAAO,CAAC,MAAM,CAAC,iBAAiB,EAAE,CAAC;YACrC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,IAAY,EACZ,MAAc,EACd,OAAe;IAEf,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI,IAAI,MAAM,KAAK,OAAO,IAAI,CAAC,CAAC;AAClE,CAAC"}

package/dist/utils/project-root-policy.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CLI-boundary policy helpers for projectRoot resolution.
+ *
+ * Per docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §7,
+ * each command picks one of these to fulfill its declared policy:
+ *
+ *  - `required`     → {@link requireProjectRoot}     — fails fast with a clear message.
+ *  - `loud-cwd`     → {@link projectRootOrLoudCwd}   — falls back to cwd with a stderr warning.
+ *  - `tolerate null`→ {@link projectRootOrNull}      — returns null; caller handles it.
+ *
+ * These helpers MUST be invoked at the CLI dispatch boundary (top-level command
+ * `.action(...)` callbacks). Inner library functions should take the resolved
+ * root as a parameter — never call `findProjectRoot` themselves.
+ */
+import type { Logger } from './logger.js';
+/**
+ * `required` policy — refuse to run if no projectRoot can be discovered.
+ *
+ * @throws Error with a clear "command requires a config or git ancestor" message.
+ */
+export declare function requireProjectRoot(startDir: string, commandName: string): string;
+/**
+ * `loud-cwd` policy — fall back to cwd with an explicit stderr log message.
+ *
+ * The message format is documented in spec §7 and asserted by integration tests:
+ *   `no vibe-agent-toolkit.config.yaml or .git/ ancestor found; using <cwd> as projectRoot`
+ */
+export declare function projectRootOrLoudCwd(startDir: string, logger: Logger): string;
+/**
+ * `tolerate null` policy — return `string | null`; caller handles either case.
+ */
+export declare function projectRootOrNull(startDir: string): string | null;
+//# sourceMappingURL=project-root-policy.d.ts.map

package/dist/utils/project-root-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-root-policy.d.ts","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAShF;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEjE"}

package/dist/utils/project-root-policy.js

@@ -0,0 +1,49 @@
+/**
+ * CLI-boundary policy helpers for projectRoot resolution.
+ *
+ * Per docs/superpowers/specs/2026-05-17-root-model-and-leading-slash-design.md §7,
+ * each command picks one of these to fulfill its declared policy:
+ *
+ *  - `required`     → {@link requireProjectRoot}     — fails fast with a clear message.
+ *  - `loud-cwd`     → {@link projectRootOrLoudCwd}   — falls back to cwd with a stderr warning.
+ *  - `tolerate null`→ {@link projectRootOrNull}      — returns null; caller handles it.
+ *
+ * These helpers MUST be invoked at the CLI dispatch boundary (top-level command
+ * `.action(...)` callbacks). Inner library functions should take the resolved
+ * root as a parameter — never call `findProjectRoot` themselves.
+ */
+import { findProjectRoot, safePath } from '@vibe-agent-toolkit/utils';
+/**
+ * `required` policy — refuse to run if no projectRoot can be discovered.
+ *
+ * @throws Error with a clear "command requires a config or git ancestor" message.
+ */
+export function requireProjectRoot(startDir, commandName) {
+    const root = findProjectRoot(startDir);
+    if (root === null) {
+        throw new Error(`${commandName} requires a vibe-agent-toolkit.config.yaml or .git/ ancestor. ` +
+            `Run from inside a VAT project or initialize one.`);
+    }
+    return root;
+}
+/**
+ * `loud-cwd` policy — fall back to cwd with an explicit stderr log message.
+ *
+ * The message format is documented in spec §7 and asserted by integration tests:
+ *   `no vibe-agent-toolkit.config.yaml or .git/ ancestor found; using <cwd> as projectRoot`
+ */
+export function projectRootOrLoudCwd(startDir, logger) {
+    const root = findProjectRoot(startDir);
+    if (root !== null)
+        return root;
+    const cwd = safePath.resolve(startDir);
+    logger.warn(`no vibe-agent-toolkit.config.yaml or .git/ ancestor found; using ${cwd} as projectRoot`);
+    return cwd;
+}
+/**
+ * `tolerate null` policy — return `string | null`; caller handles either case.
+ */
+export function projectRootOrNull(startDir) {
+    return findProjectRoot(startDir);
+}
+//# sourceMappingURL=project-root-policy.js.map

package/dist/utils/project-root-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-root-policy.js","sourceRoot":"","sources":["../../src/utils/project-root-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAItE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,WAAmB;IACtE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,GAAG,WAAW,gEAAgE;YAC5E,kDAAkD,CACrD,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAAgB,EAAE,MAAc;IACnE,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,MAAM,CAAC,IAAI,CACT,oEAAoE,GAAG,iBAAiB,CACzF,CAAC;IACF,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACnC,CAAC"}

package/dist/utils/resource-loader.d.ts

@@ -6,7 +6,7 @@ import { GitTracker } from '@vibe-agent-toolkit/utils';
 import type { Logger } from './logger.js';
 export interface ResourceLoadResult {
     scanPath: string;
-    projectRoot: string | null;
+    projectRoot: string;
     config: ProjectConfig | undefined;
     registry: ResourceRegistry;
     gitTracker: GitTracker | undefined;
@@ -16,16 +16,21 @@ export interface ResourceLoadResult {
  *
  * Common pattern for CLI commands that need to:
  * 1. Determine scan path
- * 2. Find project root and load config
+ * 2. Load config from the pre-resolved project root
  * 3. Create registry and crawl
  *
  * Behavior:
  * - When path argument provided: use as baseDir, ignore config patterns (use defaults)
- * - When no path argument: use project root/cwd as baseDir, apply config patterns
+ * - When no path argument: use project root as baseDir, apply config patterns
+ *
+ * Per CLI-boundary rule (spec §5): `projectRoot` MUST be resolved by the
+ * caller using one of the policy helpers in `project-root-policy.ts`. This
+ * function does not call `findProjectRoot` itself.
  *
  * @param pathArg - Path argument from CLI (optional)
+ * @param projectRoot - Pre-resolved project root from the CLI boundary
  * @param logger - Logger instance
  * @returns Resource load result with registry and metadata
  */
-export declare function loadResourcesWithConfig(pathArg: string | undefined, logger: Logger): Promise<ResourceLoadResult>;
+export declare function loadResourcesWithConfig(pathArg: string | undefined, projectRoot: string, logger: Logger): Promise<ResourceLoadResult>;
 //# sourceMappingURL=resource-loader.d.ts.map

package/dist/utils/resource-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resource-loader.d.ts","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAGvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CAmE7B"}
+{"version":3,"file":"resource-loader.d.ts","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAGvD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,aAAa,GAAG,SAAS,CAAC;IAClC,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,UAAU,GAAG,SAAS,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,kBAAkB,CAAC,CA2D7B"}

package/dist/utils/resource-loader.js

@@ -4,50 +4,47 @@
 import { ResourceRegistry, } from '@vibe-agent-toolkit/resources';
 import { GitTracker } from '@vibe-agent-toolkit/utils';
 import { loadConfig } from './config-loader.js';
-import { findProjectRoot } from './project-root.js';
 /**
  * Load resources from a path with config support
  *
  * Common pattern for CLI commands that need to:
  * 1. Determine scan path
- * 2. Find project root and load config
+ * 2. Load config from the pre-resolved project root
  * 3. Create registry and crawl
  *
  * Behavior:
  * - When path argument provided: use as baseDir, ignore config patterns (use defaults)
- * - When no path argument: use project root/cwd as baseDir, apply config patterns
+ * - When no path argument: use project root as baseDir, apply config patterns
+ *
+ * Per CLI-boundary rule (spec §5): `projectRoot` MUST be resolved by the
+ * caller using one of the policy helpers in `project-root-policy.ts`. This
+ * function does not call `findProjectRoot` itself.
  *
  * @param pathArg - Path argument from CLI (optional)
+ * @param projectRoot - Pre-resolved project root from the CLI boundary
  * @param logger - Logger instance
  * @returns Resource load result with registry and metadata
  */
-export async function loadResourcesWithConfig(pathArg, logger) {
-    // Find project root and load config
-    const projectRoot = findProjectRoot(process.cwd());
-    const config = projectRoot ? loadConfig(projectRoot) : undefined;
+export async function loadResourcesWithConfig(pathArg, projectRoot, logger) {
+    // Config lookup is anchored at the resolved projectRoot.
+    const config = loadConfig(projectRoot);
     if (config) {
-        logger.debug(`Loaded config from ${projectRoot ?? 'unknown'}`);
-    }
-    // Create and initialize GitTracker if we have a project root
-    let gitTracker;
-    if (projectRoot) {
-        gitTracker = new GitTracker(projectRoot);
-        await gitTracker.initialize();
-        const stats = gitTracker.getStats();
-        logger.debug(`GitTracker initialized with ${stats.cacheSize} tracked files`);
+        logger.debug(`Loaded config from ${projectRoot}`);
     }
+    // Create and initialize GitTracker anchored at the resolved projectRoot.
+    const gitTracker = new GitTracker(projectRoot);
+    await gitTracker.initialize();
+    const stats = gitTracker.getStats();
+    logger.debug(`GitTracker initialized with ${stats.cacheSize} tracked files`);
     // Create registry and crawl
     // Build options conditionally to satisfy exactOptionalPropertyTypes
-    const registryOptions = {};
+    const registryOptions = {
+        baseDir: projectRoot,
+        gitTracker,
+    };
     if (config?.resources?.collections) {
         registryOptions.config = config;
     }
-    if (projectRoot) {
-        registryOptions.baseDir = projectRoot;
-    }
-    if (gitTracker) {
-        registryOptions.gitTracker = gitTracker;
-    }
     const registry = new ResourceRegistry(registryOptions);
     let crawlOptions;
     if (pathArg) {
@@ -61,11 +58,10 @@ export async function loadResourcesWithConfig(pathArg, logger) {
         };
     }
     else {
-        // No path argument: crawl from project root (or cwd) with config patterns
-        const scanPath = projectRoot ?? process.cwd();
-        logger.debug(`No path argument, using: ${scanPath}`);
+        // No path argument: crawl from projectRoot with config patterns
+        logger.debug(`No path argument, using: ${projectRoot}`);
         crawlOptions = {
-            baseDir: scanPath,
+            baseDir: projectRoot,
             // Apply include patterns from config (if specified)
             ...(config?.resources?.include ? { include: config.resources.include } : {}),
             // Apply exclude patterns from config (if specified)
@@ -74,7 +70,7 @@ export async function loadResourcesWithConfig(pathArg, logger) {
     }
     await registry.crawl(crawlOptions);
     return {
-        scanPath: pathArg ?? (projectRoot ?? process.cwd()),
+        scanPath: pathArg ?? projectRoot,
         projectRoot,
         config,
         registry,

package/dist/utils/resource-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"resource-loader.js","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resource-loader.js","sourceRoot":"","sources":["../../src/utils/resource-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,GAGjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAWhD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,OAA2B,EAC3B,WAAmB,EACnB,MAAc;IAEd,yDAAyD;IACzD,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,CAAC;IAEvC,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,KAAK,CAAC,sBAAsB,WAAW,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,yEAAyE;IACzE,MAAM,UAAU,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IAC/C,MAAM,UAAU,CAAC,UAAU,EAAE,CAAC;IAC9B,MAAM,KAAK,GAAG,UAAU,CAAC,QAAQ,EAAE,CAAC;IACpC,MAAM,CAAC,KAAK,CAAC,+BAA+B,KAAK,CAAC,SAAS,gBAAgB,CAAC,CAAC;IAE7E,4BAA4B;IAC5B,oEAAoE;IACpE,MAAM,eAAe,GAA4B;QAC/C,OAAO,EAAE,WAAW;QACpB,UAAU;KACX,CAAC;IACF,IAAI,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;QACnC,eAAe,CAAC,MAAM,GAAG,MAAM,CAAC;IAClC,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,eAAe,CAAC,CAAC;IAEvD,IAAI,YAAY,CAAC;IAEjB,IAAI,OAAO,EAAE,CAAC;QACZ,0EAA0E;QAC1E,kEAAkE;QAClE,MAAM,CAAC,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,KAAK,CAAC,0CAA0C,CAAC,CAAC;QAEzD,YAAY,GAAG;YACb,OAAO,EAAE,OAAO;YAChB,8DAA8D;SAC/D,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,gEAAgE;QAChE,MAAM,CAAC,KAAK,CAAC,4BAA4B,WAAW,EAAE,CAAC,CAAC;QAExD,YAAY,GAAG;YACb,OAAO,EAAE,WAAW;YACpB,oDAAoD;YACpD,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5E,oDAAoD;YACpD,GAAG,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC7E,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAEnC,OAAO;QACL,QAAQ,EAAE,OAAO,IAAI,WAAW;QAChC,WAAW;QACX,MAAM;QACN,QAAQ;QACR,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/utils/validate-help-files.js

@@ -7,7 +7,7 @@
  */
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import { safePath } from '@vibe-agent-toolkit/utils';
 /**
  * Required help documentation files
@@ -47,7 +47,7 @@ export function validateHelpFiles() {
  * Run validation if this file is executed directly
  * (via tsx or node during build process)
  */
-if (import.meta.url === `file://${String(process.argv[1] ?? '')}`) {
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     try {
         validateHelpFiles();
         console.log('✓ All required help documentation files exist');

package/dist/utils/validate-help-files.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate-help-files.js","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD;;;GAGG;AACH,MAAM,mBAAmB,GAAG;IAC1B,UAAU,EAAO,iDAAiD;IAClE,cAAc,EAAG,kEAAkE;IACnF,QAAQ,EAAS,sDAAsD;IACvE,UAAU,EAAO,0DAA0D;CACnE,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAEnD,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,QAAQ,IAAI,mBAAmB,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAClD,qHAAqH;QACrH,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,+CAA+C,QAAQ,MAAM;YAC7D,uEAAuE;YACvE,8CAA8C,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,UAAU,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;IAClE,IAAI,CAAC;QACH,iBAAiB,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}
+{"version":3,"file":"validate-help-files.js","sourceRoot":"","sources":["../../src/utils/validate-help-files.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAExD,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD;;;GAGG;AACH,MAAM,mBAAmB,GAAG;IAC1B,UAAU,EAAO,iDAAiD;IAClE,cAAc,EAAG,kEAAkE;IACnF,QAAQ,EAAS,sDAAsD;IACvE,UAAU,EAAO,0DAA0D;CACnE,CAAC;AAEX;;;;GAIG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;IAEnD,MAAM,YAAY,GAAa,EAAE,CAAC;IAElC,KAAK,MAAM,QAAQ,IAAI,mBAAmB,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAClD,qHAAqH;QACrH,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1B,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,IAAI,KAAK,CACb,+CAA+C,QAAQ,MAAM;YAC7D,uEAAuE;YACvE,8CAA8C,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/E,IAAI,CAAC;QACH,iBAAiB,EAAE,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,+CAA+C,CAAC,CAAC;QAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAChD,OAAO,CAAC,KAAK,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC"}

package/docs/agent.md

@@ -93,6 +93,31 @@ vat agent validate ./my-custom-agent/agent.yaml
 - `OPENAI_API_KEY` - API key for OpenAI
 - `GOOGLE_API_KEY` - API key for Google (Gemini)
 
+## Requirements
+
+Each `vat agent` subcommand declares its own `projectRoot` and config policy:
+
+| Subcommand | `projectRoot` | Config |
+|---|---|---|
+| `vat agent list` | optional (tolerates absence) | not used |
+| `vat agent installed` | N/A | not used |
+| `vat agent build <pathOrName>` | required (errors without `vibe-agent-toolkit.config.yaml` or `.git/` ancestor) | required file with `agents.*` fields populated |
+| `vat agent run <pathOrName> <input>` | optional (path-explicit; tolerates absence) | optional (uses defaults if absent) |
+| `vat agent validate <pathOrName>` | required | optional (uses defaults if absent) |
+| `vat agent import <skillPath>` | N/A | not used |
+| `vat agent install <agentName>` | N/A | not used |
+| `vat agent uninstall <agentName>` | N/A | not used |
+
+**Why `build` and `validate` require `projectRoot`:** both are explicit-adoption
+operations. Building or source-validating an agent without an authoring
+boundary would silently accept arbitrary trees as "the project" and would not
+participate in the unified validation framework. `vat agent run` is
+path-explicit and runs from anywhere; `vat agent list` discovers without
+needing a project context.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ## See Also
 
 - [@vibe-agent-toolkit/agent-schema](../../agent-schema/README.md) - Schema reference

package/docs/audit.md

@@ -555,6 +555,31 @@ Windows users: Use forward slashes even on Windows - they work correctly in Node
 
 SKILL.md files can use any line ending (LF, CRLF) - the parser handles both.
 
+## Requirements
+
+`vat audit` has an unusual policy because it operates on per-skill
+governing context rather than a single top-level `projectRoot`:
+
+- **`projectRoot`**: per-skill walk-up. There is no single `projectRoot` for an
+  audit run. Each `SKILL.md` discovered during scanning walks up to its own
+  nearest `vibe-agent-toolkit.config.yaml`-or-`.git/` ancestor and uses that as
+  *its* `projectRoot`. Skills with no governing config or git ancestor are
+  reported as ungoverned (an audit finding, not a fatal error). This lets `vat
+  audit` work on external community trees, downloaded plugin bundles, and
+  monorepos with multiple sub-package configs.
+- **Config**: accept defaults. Per-skill `validation.severity` and
+  `validation.allow` overrides come from whichever
+  `vibe-agent-toolkit.config.yaml` each skill walks up to. The audit itself
+  always exits 0 (advisory) regardless of severity outcomes.
+
+The per-skill walk-up is cached via a module-level two-layer cache and pre-warmed
+during top-down descent for efficiency on large trees.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for the `projectRoot` ladder and the audit walk-up model. See
+[`docs/skill-quality-and-compatibility.md`](../../../docs/skill-quality-and-compatibility.md)
+for VAT's advisory-audit stance.
+
 ## Related Commands
 
 - `vat agent audit <path>` - Legacy skill-only audit (deprecated)

package/docs/doctor.md

@@ -260,6 +260,19 @@ fi
 - **Skipped:** When running installed VAT globally
 - **Fix:** Run `bun run build` in VAT source directory
 
+## Requirements
+
+- **`projectRoot`**: optional. `vat doctor` tolerates a missing `projectRoot`
+  and reports its absence as a diagnostic finding rather than refusing to run.
+  This is by design: doctor is the command users invoke when they suspect their
+  setup is wrong, so it must run anywhere.
+- **Config**: not used as input. Doctor checks whether a config file *exists*
+  and parses as a finding, but it does not consume config fields to drive its
+  behavior.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ## Tips
 
 - Run `vat doctor` before reporting issues to verify environment

package/docs/index.md

@@ -332,6 +332,25 @@ The `vat` wrapper automatically detects your execution context:
 When running global `vat` from within the toolkit repository, it automatically
 switches to dev mode and shows the `-dev` suffix.
 
+## Requirements
+
+Every VAT command declares a `projectRoot` policy and a config policy. The
+short version:
+
+- **`projectRoot` = the VAT authoring boundary.** Discovered as: nearest
+  `vibe-agent-toolkit.config.yaml` → else nearest `.git/` → else `null`.
+- **Per-command policy varies.** Some commands require it (`vat skills build`,
+  `vat agent build`, `vat build`, `vat verify`). Some tolerate its absence
+  (`vat skills validate --user`, `vat agent list`, `vat rag *` with `--db`).
+  Some have a **loud-cwd fallback** that warns to stderr and continues
+  (`vat resources scan`, `vat resources validate`).
+- **`vat audit` is special:** there is no single `projectRoot`; each scanned
+  skill walks up to its own governing context.
+
+Every command's `--help` output includes a `Requirements:` section declaring
+its policy. The full matrix and rationale live in
+[Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md).
+
 ## Configuration
 
 Place `vibe-agent-toolkit.config.yaml` at project root:

package/docs/mcp.md

@@ -310,6 +310,22 @@ All implementations must:
 
 See [MCP Gateway README](../../gateway-mcp/README.md) for planned features.
 
+## Requirements
+
+Both MCP subcommands run as server / discovery operations and do not consume a
+VAT authoring context:
+
+- **`vat mcp list-collections`**
+  - **`projectRoot`**: N/A.
+  - **Config**: not used.
+- **`vat mcp serve <package>`**
+  - **`projectRoot`**: N/A. The server resolves `<package>` from `node_modules`
+    or an explicit path; project context is not needed.
+  - **Config**: not used.
+
+See [Roots and Config — Canonical Concepts](../../../docs/concepts/roots-and-config.md)
+for terminology.
+
 ## See Also
 
 - [MCP Gateway README](../../gateway-mcp/README.md)