@vibe-validate/cli 0.16.0 → 0.17.0-rc.10

package/dist/commands/pre-commit.js

@@ -9,7 +9,7 @@ import { getRemoteBranch } from '@vibe-validate/config';
 import { loadConfig } from '../utils/config-loader.js';
 import { detectContext } from '../utils/context-detector.js';
 import { runValidateWorkflow } from '../utils/validate-workflow.js';
-import { execSync } from 'node:child_process';
+import { selectToolsToRun, runSecretScan, showPerformanceWarning, showSecretsDetectedError, formatToolName, hasGitleaksConfig, isGitleaksAvailable, } from '../utils/secret-scanning.js';
 import chalk from 'chalk';
 export function preCommitCommand(program) {
     program
@@ -55,56 +55,50 @@ export function preCommitCommand(program) {
             const verbose = options.verbose ?? false;
             // Step 5: Run secret scanning if enabled
             const secretScanning = config.hooks?.preCommit?.secretScanning;
-            if (secretScanning?.enabled && secretScanning?.scanCommand) {
+            if (secretScanning?.enabled) {
                 console.log(chalk.blue('\n🔒 Running secret scanning...'));
-                try {
-                    const result = execSync(secretScanning.scanCommand, {
-                        encoding: 'utf8',
-                        stdio: 'pipe',
-                    });
-                    // Show scan output if verbose
-                    if (verbose && result) {
-                        console.log(chalk.gray(result));
-                    }
-                    console.log(chalk.green('✅ No secrets detected'));
+                // Determine which tools to run (autodetect or explicit command)
+                const toolsToRun = selectToolsToRun(secretScanning.scanCommand);
+                if (toolsToRun.length === 0) {
+                    console.warn(chalk.yellow('⚠️  No secret scanning tools configured or available'));
+                    console.warn(chalk.gray('   Install gitleaks or add .secretlintrc.json'));
                 }
-                catch (error) {
-                    // Secret scanning failed (either tool missing or secrets found)
-                    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
-                        // Tool not found
-                        const toolName = secretScanning.scanCommand.split(' ')[0];
-                        console.error(chalk.red('\n❌ Secret scanning tool not found'));
-                        console.error(chalk.yellow(`   Command: ${chalk.white(secretScanning.scanCommand)}`));
-                        console.error(chalk.yellow(`   Tool '${toolName}' is not installed or not in PATH`));
-                        console.error(chalk.blue('\n💡 Fix options:'));
-                        console.error(chalk.gray('   1. Install the tool (e.g., brew install gitleaks)'));
-                        console.error(chalk.gray('   2. Disable scanning: set hooks.preCommit.secretScanning.enabled=false'));
-                        process.exit(1);
-                    }
-                    else if (error && typeof error === 'object' && 'stderr' in error && 'stdout' in error) {
-                        // Tool ran but found secrets
-                        const stderr = 'stderr' in error && error.stderr ? String(error.stderr) : '';
-                        const stdout = 'stdout' in error && error.stdout ? String(error.stdout) : '';
-                        console.error(chalk.red('\n❌ Secret scanning detected potential secrets in staged files\n'));
-                        // Show scan output
-                        if (stdout) {
-                            console.error(stdout);
+                else {
+                    const results = [];
+                    // Run each tool
+                    for (const { tool, command } of toolsToRun) {
+                        const result = runSecretScan(tool, command, verbose);
+                        results.push(result);
+                        // Handle skipped scans (e.g., gitleaks not available but config exists)
+                        if (result.skipped) {
+                            if (hasGitleaksConfig() && !isGitleaksAvailable()) {
+                                console.warn(chalk.yellow(`⚠️  Found .gitleaks.toml but gitleaks command not available, skipping`));
+                                console.warn(chalk.gray('   Install gitleaks: brew install gitleaks'));
+                            }
+                            continue;
                         }
-                        if (stderr) {
-                            console.error(stderr);
+                        // Show verbose output if requested
+                        if (verbose && result.output) {
+                            console.log(chalk.gray(result.output));
+                        }
+                        // Show performance warning if scan was slow (hardcoded 5s threshold)
+                        if (result.passed) {
+                            showPerformanceWarning(tool, result.duration, 5000);
                         }
-                        console.error(chalk.blue('\n💡 Fix options:'));
-                        console.error(chalk.gray('   1. Remove secrets from staged files'));
-                        console.error(chalk.gray('   2. Use .gitleaksignore to mark false positives (if using gitleaks)'));
-                        console.error(chalk.gray('   3. Disable scanning: set hooks.preCommit.secretScanning.enabled=false'));
-                        process.exit(1);
                     }
-                    else {
-                        // Unknown error
-                        console.error(chalk.red('\n❌ Secret scanning failed with unknown error'));
-                        console.error(chalk.gray(String(error)));
+                    // Check if any scans failed
+                    const failedScans = results.filter(r => !r.passed && !r.skipped);
+                    if (failedScans.length > 0) {
+                        showSecretsDetectedError(failedScans);
                         process.exit(1);
                     }
+                    // Success message
+                    const ranTools = results.filter(r => !r.skipped);
+                    if (ranTools.length > 0) {
+                        const toolNames = ranTools.map(r => formatToolName(r.tool)).join(', ');
+                        const totalDuration = ranTools.reduce((sum, r) => sum + r.duration, 0);
+                        console.log(chalk.green(`✅ No secrets detected (${toolNames}, ${totalDuration}ms)`));
+                    }
                 }
             }
             // Step 6: Run validation with caching
@@ -125,15 +119,8 @@ export function preCommitCommand(program) {
             else {
                 console.error(chalk.red('\n❌ Pre-commit checks failed'));
                 console.error(chalk.yellow('   Fix errors before committing.'));
-                // Show agent-friendly error details
-                console.error(chalk.blue('\n📋 Error details:'), chalk.white('vibe-validate state'));
-                // Find the failed step's command (v0.15.0+: rerunCommand removed, use step.command)
-                const failedStep = result.phases
-                    ?.flatMap(phase => phase.steps)
-                    .find(step => step.name === result.failedStep);
-                if (failedStep?.command) {
-                    console.error(chalk.blue('🔄 To retry:'), chalk.white(failedStep.command));
-                }
+                // Note: Error details and YAML output are already shown by runValidateWorkflow
+                // No need to duplicate the error display here
                 process.exit(1);
             }
         }
@@ -157,9 +144,10 @@ The \`pre-commit\` command runs a comprehensive pre-commit workflow to ensure yo
 
 ## How It Works
 
-1. Runs sync-check (fails if branch behind origin/main)
-2. Runs validate (with caching)
-3. Reports git status (warns about unstaged files)
+1. Runs secret scanning (if enabled in config)
+2. Runs sync-check (fails if branch behind origin/main)
+3. Runs validate (with caching)
+4. Reports git status (warns about unstaged files)
 
 ## Options
 
@@ -207,6 +195,90 @@ echo "npx vibe-validate pre-commit" > .husky/pre-commit
 git commit -m "Your message"
 \`\`\`
 
+## Secret Scanning
+
+Secret scanning prevents accidental commits of credentials (API keys, tokens, passwords).
+
+### Autodetect Mode (Recommended)
+
+Enable in config without specifying \`scanCommand\`:
+
+\`\`\`yaml
+hooks:
+  preCommit:
+    secretScanning:
+      enabled: true
+\`\`\`
+
+Automatically runs tools based on config files:
+- \`.gitleaks.toml\` or \`.gitleaksignore\` → runs gitleaks
+- \`.secretlintrc.json\` → runs secretlint (via npx)
+- Both files → runs both tools (defense-in-depth)
+
+### Tool Setup
+
+**Option 1: gitleaks (recommended - fast, 160+ secret types)**
+\`\`\`bash
+# Install
+macOS:   brew install gitleaks
+Linux:   https://github.com/gitleaks/gitleaks#installation
+Windows: winget install gitleaks
+
+# Create config (empty file enables autodetect)
+touch .gitleaksignore
+
+# Handle false positives (add fingerprints from gitleaks output)
+echo "path/to/file.txt:generic-api-key:123" >> .gitleaksignore
+\`\`\`
+
+**Option 2: secretlint (npm-based, always available)**
+\`\`\`bash
+# Install
+npm install --save-dev @secretlint/secretlint-rule-preset-recommend secretlint
+
+# Create config
+cat > .secretlintrc.json << 'EOF'
+{
+  "rules": [
+    {"id": "@secretlint/secretlint-rule-preset-recommend"}
+  ]
+}
+EOF
+
+# Handle false positives
+cat > .secretlintignore << 'EOF'
+.jscpd/
+**/dist/**
+**/node_modules/**
+EOF
+\`\`\`
+
+**Option 3: Both (defense-in-depth)**
+\`\`\`bash
+# Set up both tools - autodetect runs both automatically
+# gitleaks: fast native binary
+# secretlint: npm-based with different detection patterns
+\`\`\`
+
+### Explicit Command Mode
+
+For custom tools or specific flags:
+
+\`\`\`yaml
+hooks:
+  preCommit:
+    secretScanning:
+      enabled: true
+      scanCommand: "gitleaks protect --staged --verbose --config .gitleaks.toml"
+\`\`\`
+
+### Troubleshooting
+
+- **"No secrets detected"** - Working correctly, no secrets found
+- **"Secret scanning enabled but no tools available"** - Install gitleaks or create .secretlintrc.json
+- **False positives** - Add to .gitleaksignore or .secretlintignore
+- **Slow scans** - Warning shown if scan takes >5 seconds
+
 ## Error Recovery
 
 ### If sync check fails

package/dist/commands/pre-commit.js.map

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

package/dist/commands/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAczC,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAgLjD;AAwbD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAiSzC"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/commands/run.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAazC,wBAAgB,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAwLjD;AAyeD;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CA0SzC"}

package/dist/commands/run.js

@@ -4,13 +4,12 @@
  * Executes a command and extracts LLM-friendly error output using vibe-validate extractors.
  * Provides concise, structured error information to save AI agent context windows.
  */
-import { execSync } from 'node:child_process';
 import { writeFile, readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { join, resolve, relative } from 'node:path';
 import { autoDetectAndExtract } from '@vibe-validate/extractors';
 import { getRunOutputDir, ensureDir } from '../utils/temp-files.js';
-import { getGitTreeHash, encodeRunCacheKey, extractYamlWithPreamble } from '@vibe-validate/git';
-import { spawnCommand, parseVibeValidateOutput } from '@vibe-validate/core';
+import { getGitTreeHash, encodeRunCacheKey, extractYamlWithPreamble, addNote, readNote } from '@vibe-validate/git';
+import { spawnCommand, parseVibeValidateOutput, getGitRoot } from '@vibe-validate/core';
 import yaml from 'yaml';
 import chalk from 'chalk';
 export function runCommand(program) {
@@ -20,6 +19,7 @@ export function runCommand(program) {
         .argument('<command...>', 'Command to execute (multiple words supported)')
         .option('--check', 'Check if cached result exists without executing')
         .option('--force', 'Force execution and update cache (bypass cache read)')
+        .option('--cwd <directory>', 'Working directory relative to git root (default: git root)')
         .option('--head <lines>', 'Display first N lines of output after YAML (on stderr)', Number.parseInt)
         .option('--tail <lines>', 'Display last N lines of output after YAML (on stderr)', Number.parseInt)
         .option('--verbose', 'Display all output after YAML (on stderr)')
@@ -57,6 +57,10 @@ export function runCommand(program) {
                     actualOptions.force = true;
                     i++;
                 }
+                else if (arg === '--cwd' && i + 1 < argv.length) {
+                    actualOptions.cwd = argv[i + 1];
+                    i += 2;
+                }
                 else if (arg === '--head' && i + 1 < argv.length) {
                     actualOptions.head = Number.parseInt(argv[i + 1], 10);
                     i += 2;
@@ -82,9 +86,12 @@ export function runCommand(program) {
             process.exit(0);
         }
         try {
+            // Note: Plugin loading is handled by the runner (in @vibe-validate/core)
+            // when running via validate command. For standalone run commands, plugins
+            // are not needed since run is primarily for caching/extraction, not validation.
             // Handle --check flag (cache status check only)
             if (actualOptions.check) {
-                const cachedResult = await tryGetCachedResult(commandString);
+                const cachedResult = await tryGetCachedResult(commandString, actualOptions.cwd);
                 if (cachedResult) {
                     // Cache hit - output cached result and exit with code 0
                     process.stdout.write('---\n');
@@ -103,26 +110,26 @@ export function runCommand(program) {
             let result;
             let context = { preamble: '', stderr: '' };
             if (!actualOptions.force) {
-                const cachedResult = await tryGetCachedResult(commandString);
+                const cachedResult = await tryGetCachedResult(commandString, actualOptions.cwd);
                 if (cachedResult) {
                     result = cachedResult;
                 }
                 else {
                     // Cache miss - execute command
-                    const executeResult = await executeAndExtract(commandString);
+                    const executeResult = await executeAndExtract(commandString, actualOptions.cwd);
                     result = executeResult.result;
                     context = executeResult.context;
                     // Store result in cache
-                    await storeCacheResult(commandString, result);
+                    await storeCacheResult(commandString, result, actualOptions.cwd);
                 }
             }
             else {
                 // Force flag - bypass cache and execute
-                const executeResult = await executeAndExtract(commandString);
+                const executeResult = await executeAndExtract(commandString, actualOptions.cwd);
                 result = executeResult.result;
                 context = executeResult.context;
                 // Update cache with fresh result
-                await storeCacheResult(commandString, result);
+                await storeCacheResult(commandString, result, actualOptions.cwd);
             }
             // CRITICAL: Write complete YAML to stdout and flush BEFORE any stderr
             // This ensures even if callers use 2>&1, YAML completes first
@@ -180,24 +187,49 @@ export function runCommand(program) {
     });
 }
 /**
- * Get working directory relative to git root
+ * Get working directory relative to git root for cache key
  * Returns empty string for root, "packages/cli" for subdirectory
+ *
+ * IMPORTANT: For cache key generation, we use the ACTUAL directory where the command
+ * is invoked from (process.cwd()), not where it runs. This ensures cache keys are
+ * accurate - running "npm test" from packages/cli is different than from git root.
+ *
+ * @param explicitCwd - Optional explicit cwd from --cwd flag (relative to git root)
+ * @returns Working directory path relative to git root (empty string for root)
  */
-function getWorkingDirectory() {
+function getWorkingDirectory(explicitCwd) {
     try {
-        const gitRoot = execSync('git rev-parse --show-toplevel', {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        const gitRoot = getGitRoot();
+        if (!gitRoot) {
+            throw new Error('Not in a git repository');
+        }
+        // Use explicit --cwd if provided
+        if (explicitCwd) {
+            // Resolve path relative to git root
+            const resolved = resolve(gitRoot, explicitCwd);
+            // Security: Prevent directory traversal outside git root
+            if (!resolved.startsWith(gitRoot)) {
+                throw new Error(`Invalid --cwd: "${explicitCwd}" - must be within git repository`);
+            }
+            // Return normalized relative path
+            const relativePath = relative(gitRoot, resolved);
+            return relativePath || ''; // Empty string if resolved to git root
+        }
+        // Use actual current directory for cache key (process.cwd() relative to git root)
+        // This ensures cache keys reflect WHERE the command was invoked from, not where it runs
         const cwd = process.cwd();
-        // If cwd is git root, return empty string
-        if (cwd === gitRoot) {
+        const relativePath = relative(gitRoot, cwd);
+        // If outside git repo or at git root, return empty string
+        if (relativePath.startsWith('..') || !relativePath) {
             return '';
         }
-        // Return relative path from git root
-        return cwd.substring(gitRoot.length + 1); // +1 to remove leading slash
+        return relativePath;
     }
-    catch {
+    catch (error) {
+        // Re-throw validation errors
+        if (error instanceof Error && error.message.includes('Invalid --cwd')) {
+            throw error;
+        }
         // Not in a git repository - return empty string
         return '';
     }
@@ -206,7 +238,7 @@ function getWorkingDirectory() {
  * Try to get cached result for a command
  * Returns null if no cache hit or if not in a git repository
  */
-async function tryGetCachedResult(commandString) {
+async function tryGetCachedResult(commandString, explicitCwd) {
     try {
         // Get tree hash
         const treeHash = await getGitTreeHash();
@@ -215,16 +247,13 @@ async function tryGetCachedResult(commandString) {
             return null;
         }
         // Get working directory
-        const workdir = getWorkingDirectory();
+        const workdir = getWorkingDirectory(explicitCwd);
         // Encode cache key
         const cacheKey = encodeRunCacheKey(commandString, workdir);
         // Construct git notes ref path: refs/notes/vibe-validate/run/{treeHash}/{cacheKey}
         const refPath = `vibe-validate/run/${treeHash}/${cacheKey}`;
-        // Try to read git note
-        const noteContent = execSync(`git notes --ref=${refPath} show HEAD 2>/dev/null || true`, {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-        }).trim();
+        // Try to read git note using secure readNote function
+        const noteContent = readNote(refPath, 'HEAD');
         if (!noteContent) {
             // Cache miss
             return null;
@@ -256,7 +285,7 @@ async function tryGetCachedResult(commandString) {
 /**
  * Store result in cache (only successful runs - exitCode === 0)
  */
-async function storeCacheResult(commandString, result) {
+async function storeCacheResult(commandString, result, explicitCwd) {
     try {
         // Only cache successful runs (v0.15.0+)
         // Failed runs may be transient or environment-specific
@@ -270,7 +299,7 @@ async function storeCacheResult(commandString, result) {
             return;
         }
         // Get working directory
-        const workdir = getWorkingDirectory();
+        const workdir = getWorkingDirectory(explicitCwd);
         // Encode cache key
         const cacheKey = encodeRunCacheKey(commandString, workdir);
         // Construct git notes ref path
@@ -288,14 +317,12 @@ async function storeCacheResult(commandString, result) {
             ...(result.extraction ? { extraction: result.extraction } : {}), // Conditionally include extraction
             ...(result.outputFiles ? { outputFiles: result.outputFiles } : {}),
         };
-        // Store in git notes using heredoc to avoid quote escaping issues
+        // Store in git notes using secure addNote function
+        // SECURITY FIX: Eliminates heredoc injection vulnerability
         const noteYaml = yaml.stringify(cacheNote);
-        // Use heredoc format for multi-line YAML
         try {
-            execSync(`cat <<'EOF' | git notes --ref=${refPath} add -f -F - HEAD\n${noteYaml}\nEOF`, {
-                stdio: 'ignore',
-                shell: '/bin/bash', // Ensure bash for heredoc support
-            });
+            // Use secure addNote with stdin piping (no shell, no heredoc)
+            addNote(refPath, 'HEAD', noteYaml, true);
             // eslint-disable-next-line sonarjs/no-ignored-exceptions -- Cache storage failure is non-critical
         }
         catch (_error) {
@@ -318,10 +345,31 @@ function stripAnsiCodes(text) {
 /**
  * Execute a command and extract errors from its output
  */
-async function executeAndExtract(commandString) {
-    return new Promise((resolve, reject) => {
+async function executeAndExtract(commandString, explicitCwd) {
+    return new Promise((resolvePromise, rejectPromise) => {
         const startTime = Date.now();
-        const child = spawnCommand(commandString);
+        // Resolve cwd if provided (relative to git root)
+        let resolvedCwd;
+        if (explicitCwd) {
+            try {
+                const gitRoot = getGitRoot();
+                if (!gitRoot) {
+                    rejectPromise(new Error('Not in a git repository'));
+                    return;
+                }
+                resolvedCwd = resolve(gitRoot, explicitCwd);
+                // Security: Validate path is within git root
+                if (!resolvedCwd.startsWith(gitRoot)) {
+                    rejectPromise(new Error(`Invalid --cwd: "${explicitCwd}" - must be within git repository`));
+                    return;
+                }
+            }
+            catch (error) {
+                rejectPromise(new Error(`Failed to resolve --cwd: ${error instanceof Error ? error.message : 'unknown error'}`));
+                return;
+            }
+        }
+        const child = spawnCommand(commandString, { cwd: resolvedCwd });
         let stdout = '';
         let stderr = '';
         const combinedLines = [];
@@ -372,7 +420,7 @@ async function executeAndExtract(commandString) {
                     preamble: yamlResult.preamble,
                     stderr: stderr.trim(),
                 };
-                resolve({ result: mergedResult, context: contextOutput });
+                resolvePromise({ result: mergedResult, context: contextOutput });
                 return;
             }
             // For extraction, combine both streams (stderr has useful error context)
@@ -383,7 +431,7 @@ async function executeAndExtract(commandString) {
                 stdout,
                 stderr,
                 combined: combinedOutput,
-            });
+            }, exitCode);
             const extraction = (exitCode !== 0 || rawExtraction.totalErrors > 0) ? rawExtraction : undefined;
             // Get tree hash for result (async operation needs to be awaited)
             getGitTreeHash()
@@ -426,7 +474,7 @@ async function executeAndExtract(commandString) {
                         combined: combinedFile,
                     },
                 };
-                resolve({ result, context: { preamble: '', stderr: '' } });
+                resolvePromise({ result, context: { preamble: '', stderr: '' } });
             })
                 .catch(async () => {
                 // If tree hash fails, use timestamp-based fallback
@@ -470,12 +518,12 @@ async function executeAndExtract(commandString) {
                         combined: combinedFile,
                     },
                 };
-                resolve({ result, context: { preamble: '', stderr: '' } });
+                resolvePromise({ result, context: { preamble: '', stderr: '' } });
             });
         });
         // Handle spawn errors (e.g., command not found)
         child.on('error', (error) => {
-            reject(error);
+            rejectPromise(error);
         });
     });
 }
@@ -548,6 +596,10 @@ function mergeNestedYaml(outerCommand, yamlOutput, outerExitCode, outerDurationS
         };
     }
 }
+// Note: loadPluginsIfConfigured() has been removed.
+// Plugin loading is now handled exclusively by the runner (in @vibe-validate/core)
+// when executing validation. This prevents redundant plugin loading on every
+// `vv run` invocation, which was causing 2.4x+ performance regression during tests.
 /**
  * Show verbose help with detailed documentation
  */
@@ -619,6 +671,15 @@ $ vibe-validate run --force "pnpm test"
 # Useful for flaky tests or time-sensitive commands
 \`\`\`
 
+**Working directory** (--cwd):
+\`\`\`bash
+$ vibe-validate run --cwd packages/cli "npm test"
+# Runs command in packages/cli directory (relative to git root)
+# Cache keys include working directory for correct cache hits
+\`\`\`
+
+**NEW in v0.17.0**: The \`--cwd\` flag allows running commands in subdirectories while maintaining consistent cache behavior. Paths are relative to git root, ensuring cache hits regardless of where you invoke the command.
+
 ### Cache Storage
 
 Cache is stored in git notes at:
@@ -856,6 +917,7 @@ Arguments:
 Options:
   --check             Check if cached result exists without executing
   --force             Force execution and update cache (bypass cache read)
+  --cwd <directory>   Working directory relative to git root (default: git root)
   --head <lines>      Display first N lines of output after YAML (on stderr)
   --tail <lines>      Display last N lines of output after YAML (on stderr)
   --verbose           Display all output after YAML (on stderr)
@@ -866,6 +928,7 @@ Examples:
   vv run cargo test --all-features         # Rust
   vv run go test ./...                     # Go
   vv run npm test                          # Node.js
+  vv run --cwd packages/cli npm test      # Run in subdirectory
   vv run --verbose npm test                # With output display
 
 For detailed documentation, use: vibe-validate run --help --verbose