@whenlabs/when 0.9.3 → 0.10.0

package/README.md

@@ -51,20 +51,28 @@ These tools are available to Claude in every session after install:
 | `velocity_history` | Show task history |
 | `stale_scan` | Detect documentation drift |
 | `stale_fix` | Auto-fix documentation drift (wrong paths, dead links, phantom env vars) |
+| `stale_auto_fix` | Scan + auto-fix drift in one call |
 | `envalid_validate` | Validate .env files against schemas |
 | `envalid_detect` | Find undocumented env vars in codebase |
 | `envalid_generate_schema` | Generate .env.schema from code analysis |
+| `envalid_auto_fix` | Detect undocumented vars + auto-generate schema entries |
 | `berth_status` | Show active ports and conflicts |
 | `berth_check` | Scan project for port conflicts |
 | `berth_resolve` | Auto-resolve port conflicts (kill or reassign) |
+| `berth_auto_resolve` | Check + auto-resolve conflicts in one call |
 | `aware_init` | Auto-detect stack, generate AI context files |
 | `aware_doctor` | Diagnose project health and config issues |
+| `aware_auto_sync` | Diagnose + auto-sync stale AI context files |
 | `vow_scan` | Scan and summarize dependency licenses |
 | `vow_check` | Validate licenses against policy |
 | `vow_hook_install` | Install pre-commit license check hook |
 
 > This table shows a highlights subset. Run `when <tool> --help` for all available commands per tool.
 
+### Cross-tool Intelligence
+
+Tools automatically suggest follow-up actions when they detect issues relevant to other tools. For example, `aware_init` triggers a `stale_scan` when it generates new files, and `envalid_detect` suggests `berth_register` when it finds service URL env vars. These cascading suggestions surface as "Tip:" lines in tool output.
+
 ## Multi-Editor Support
 
 Install MCP servers into other editors alongside Claude Code:
@@ -83,7 +91,10 @@ Without flags, `install` targets Claude Code only.
 You can also run tools directly from the command line:
 
 ```bash
-when init            # Onboard a project — detect stack, run all tools
+when init            # Onboard a project — bootstrap configs, run all tools, auto-fix
+when config          # Show unified .whenlabs.yml config
+when config init     # Generate .whenlabs.yml from existing tool configs
+when config validate # Validate config structure
 when stale scan
 when stale fix       # Auto-fix documentation drift
 when envalid validate
@@ -102,7 +113,15 @@ when ci              # Run checks for CI (exits 1 on issues)
 
 ### `when init`
 
-One command to onboard any project. Auto-detects your stack, runs all 5 CLI tools in parallel, generates AI context files if missing, and shows a summary with next steps.
+One command to fully onboard any project:
+1. **Bootstrap** — creates `.env.schema`, `.vow.json`, `.stale.yml`, and registers berth ports based on your project
+2. **Scan** — runs all 5 CLI tools in parallel
+3. **Auto-fix** — automatically fixes stale drift if detected
+4. **Config** — generates a unified `.whenlabs.yml` from the bootstrapped configs
+
+### `when config`
+
+Manage the unified `.whenlabs.yml` project config. All six tools read their settings from this single file instead of separate config files. Subcommands: `init` (generate from existing configs), `validate` (check structure).
 
 ### `when doctor`
 

package/dist/chunk-JOMP6AU5.js

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+
+// src/utils/find-bin.ts
+import { resolve, dirname } from "path";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+function findBin(name) {
+  const pkgRoot = resolve(__dirname, "../..");
+  const localBin = resolve(pkgRoot, "node_modules", ".bin", name);
+  if (existsSync(localBin)) return localBin;
+  const directCli = resolve(pkgRoot, "node_modules", "@whenlabs", name, "dist", "cli.js");
+  if (existsSync(directCli)) return directCli;
+  return name;
+}
+
+// src/config/whenlabs-config.ts
+import { existsSync as existsSync2, readFileSync } from "fs";
+import { resolve as resolve2 } from "path";
+import { parse } from "yaml";
+var CONFIG_FILENAME = ".whenlabs.yml";
+function loadConfig(projectPath) {
+  const dir = projectPath ?? process.cwd();
+  const configPath = resolve2(dir, CONFIG_FILENAME);
+  if (!existsSync2(configPath)) return null;
+  try {
+    const raw = readFileSync(configPath, "utf-8");
+    const parsed = parse(raw);
+    if (!parsed || typeof parsed !== "object") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export {
+  findBin,
+  CONFIG_FILENAME,
+  loadConfig
+};

package/dist/index.js

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 import {
-  findBin
-} from "./chunk-2A2EZZF4.js";
+  CONFIG_FILENAME,
+  findBin,
+  loadConfig
+} from "./chunk-JOMP6AU5.js";
 import {
   getStatusPath
 } from "./chunk-4ZVSCJCJ.js";
 
 // src/index.ts
-import { Command as Command5 } from "commander";
+import { Command as Command6 } from "commander";
 
 // src/commands/delegate.ts
 import { Command } from "commander";
@@ -297,8 +299,9 @@ function createDoctorCommand() {
 import { Command as Command3 } from "commander";
 import { spawn as spawn3 } from "child_process";
 import { resolve as resolve2, dirname as dirname2, basename } from "path";
-import { existsSync as existsSync2, readFileSync } from "fs";
+import { existsSync as existsSync2, readFileSync, writeFileSync } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
+import { stringify } from "yaml";
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
 var c2 = {
   reset: "\x1B[0m",
@@ -312,12 +315,6 @@ var c2 = {
 function colorize2(text, ...codes) {
   return codes.join("") + text + c2.reset;
 }
-function findBin3(name) {
-  const pkgRoot = resolve2(__dirname2, "..");
-  const localBin = resolve2(pkgRoot, "node_modules", ".bin", name);
-  if (existsSync2(localBin)) return localBin;
-  return name;
-}
 function detectProject(cwd) {
   let name = basename(cwd);
   const pkgPath = resolve2(cwd, "package.json");
@@ -348,9 +345,25 @@ function detectProject(cwd) {
   }
   return { name, stack: stacks.length > 0 ? stacks.join(", ") : "unknown" };
 }
-function runTool2(bin, args) {
+function detectLicenseTemplate(cwd) {
+  const pkgPath = resolve2(cwd, "package.json");
+  if (existsSync2(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+      const license = (pkg.license ?? "").toLowerCase();
+      if (["mit", "isc", "apache-2.0", "apache2", "bsd-2-clause", "bsd-3-clause"].some((l) => license.includes(l))) {
+        return "opensource";
+      }
+      if (license) return "commercial";
+    } catch {
+    }
+  }
+  return "opensource";
+}
+function runTool2(bin, args, cwd) {
   return new Promise((resolveP) => {
     const child = spawn3(bin, args, {
+      cwd,
       env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" }
     });
     let stdout = "";
@@ -365,8 +378,75 @@ function runTool2(bin, args) {
     child.on("close", (code) => resolveP({ stdout, stderr, exitCode: code ?? 1 }));
   });
 }
+async function bootstrapConfigs(cwd) {
+  const results = [];
+  const hasEnv = existsSync2(resolve2(cwd, ".env"));
+  const hasEnvSchema = existsSync2(resolve2(cwd, ".env.schema"));
+  if (hasEnv && !hasEnvSchema) {
+    const { exitCode } = await runTool2(findBin("envalid"), ["init"], cwd);
+    if (exitCode === 0) {
+      results.push({ label: ".env.schema", action: "created", detail: "Created .env.schema from .env" });
+    } else if (exitCode === 127) {
+      results.push({ label: ".env.schema", action: "error", detail: "envalid not found" });
+    } else {
+      results.push({ label: ".env.schema", action: "error", detail: "envalid init failed" });
+    }
+  } else if (hasEnvSchema) {
+    results.push({ label: ".env.schema", action: "skipped", detail: "Skipped (already exists)" });
+  } else {
+    results.push({ label: ".env.schema", action: "skipped", detail: "Skipped (no .env found)" });
+  }
+  const hasVowConfig = existsSync2(resolve2(cwd, ".vow.json"));
+  if (!hasVowConfig) {
+    const template = detectLicenseTemplate(cwd);
+    const { exitCode } = await runTool2(findBin("vow"), ["init", "--template", template], cwd);
+    if (exitCode === 0) {
+      results.push({ label: ".vow.json", action: "created", detail: `Created .vow.json (template: ${template})` });
+    } else if (exitCode === 127) {
+      results.push({ label: ".vow.json", action: "error", detail: "vow not found" });
+    } else {
+      results.push({ label: ".vow.json", action: "error", detail: "vow init failed" });
+    }
+  } else {
+    results.push({ label: ".vow.json", action: "skipped", detail: "Skipped (already exists)" });
+  }
+  const hasStaleConfig = existsSync2(resolve2(cwd, ".stale.yml"));
+  let staleScanNeeded = false;
+  if (!hasStaleConfig) {
+    const { exitCode } = await runTool2(findBin("stale"), ["init"], cwd);
+    if (exitCode === 0) {
+      results.push({ label: ".stale.yml", action: "created", detail: "Created .stale.yml" });
+      staleScanNeeded = true;
+    } else if (exitCode === 127) {
+      results.push({ label: ".stale.yml", action: "error", detail: "stale not found" });
+    } else {
+      results.push({ label: ".stale.yml", action: "error", detail: "stale init failed" });
+    }
+  } else {
+    results.push({ label: ".stale.yml", action: "skipped", detail: "Skipped (already exists)" });
+  }
+  const { exitCode: berthCode } = await runTool2(findBin("berth"), ["register", "--yes", "--dir", cwd], cwd);
+  if (berthCode === 0) {
+    results.push({ label: "berth ports", action: "created", detail: "Registered project ports" });
+  } else if (berthCode === 127) {
+    results.push({ label: "berth ports", action: "error", detail: "berth not found" });
+  } else {
+    results.push({ label: "berth ports", action: "error", detail: "berth register failed" });
+  }
+  return { results, staleScanNeeded };
+}
+function bootstrapIcon(action) {
+  switch (action) {
+    case "created":
+      return colorize2("+", c2.green);
+    case "skipped":
+      return colorize2("-", c2.dim);
+    case "error":
+      return colorize2("!", c2.yellow);
+  }
+}
 async function scanStale(cwd) {
-  const { stdout, exitCode } = await runTool2(findBin3("stale"), ["scan", "--format", "json", "--path", cwd]);
+  const { stdout, exitCode } = await runTool2(findBin("stale"), ["scan", "--format", "json", "--path", cwd]);
   if (exitCode === 127) return { label: "Doc drift (stale)", status: "error", detail: "stale not found" };
   try {
     const json = JSON.parse(stdout);
@@ -377,7 +457,7 @@ async function scanStale(cwd) {
   }
 }
 async function scanEnvalid(cwd) {
-  const { stdout, exitCode } = await runTool2(findBin3("envalid"), ["validate", "--format", "json"]);
+  const { stdout, exitCode } = await runTool2(findBin("envalid"), ["validate", "--format", "json"]);
   if (exitCode === 127) return { label: "Env validation (envalid)", status: "error", detail: "envalid not found" };
   if (exitCode === 2 || stdout.includes("not found")) return { label: "Env validation (envalid)", status: "skipped", detail: "No .env.schema \u2014 run `envalid init`" };
   try {
@@ -389,7 +469,7 @@ async function scanEnvalid(cwd) {
   }
 }
 async function scanBerth(cwd) {
-  const { stdout, exitCode } = await runTool2(findBin3("berth"), ["check", cwd, "--json"]);
+  const { stdout, exitCode } = await runTool2(findBin("berth"), ["check", cwd, "--json"]);
   if (exitCode === 127) return { label: "Port conflicts (berth)", status: "error", detail: "berth not found" };
   try {
     const json = JSON.parse(stdout);
@@ -400,7 +480,7 @@ async function scanBerth(cwd) {
   }
 }
 async function scanVow(cwd) {
-  const { stdout, exitCode } = await runTool2(findBin3("vow"), ["scan", "--format", "json", "--path", cwd]);
+  const { stdout, exitCode } = await runTool2(findBin("vow"), ["scan", "--format", "json", "--path", cwd]);
   if (exitCode === 127) return { label: "License scan (vow)", status: "error", detail: "vow not found" };
   const jsonStart = stdout.indexOf("{");
   const jsonStr = jsonStart >= 0 ? stdout.slice(jsonStart) : stdout;
@@ -418,12 +498,12 @@ async function scanVow(cwd) {
 async function scanAware(cwd) {
   const hasConfig = existsSync2(resolve2(cwd, ".aware.json"));
   if (!hasConfig) {
-    const { exitCode: exitCode2 } = await runTool2(findBin3("aware"), ["init"]);
+    const { exitCode: exitCode2 } = await runTool2(findBin("aware"), ["init", "--force"], cwd);
     if (exitCode2 === 0) return { label: "AI context (aware)", status: "ok", detail: "Generated .aware.json and context files" };
     if (exitCode2 === 127) return { label: "AI context (aware)", status: "error", detail: "aware not found" };
     return { label: "AI context (aware)", status: "skipped", detail: "Could not generate \u2014 run `aware init` manually" };
   }
-  const { stdout, stderr, exitCode } = await runTool2(findBin3("aware"), ["doctor"]);
+  const { stdout, stderr, exitCode } = await runTool2(findBin("aware"), ["doctor"], cwd);
   if (exitCode === 127) return { label: "AI context (aware)", status: "error", detail: "aware not found" };
   const combined = (stdout + stderr).trim();
   const warnings = combined.split("\n").filter((l) => l.includes("\u26A0") || /warn/i.test(l)).length;
@@ -443,7 +523,7 @@ function statusIcon2(status) {
 }
 function createInitCommand() {
   const cmd = new Command3("init");
-  cmd.description("Interactive onboarding \u2014 detect stack, run all checks, suggest next steps");
+  cmd.description("Interactive onboarding \u2014 detect stack, bootstrap tool configs, run all checks");
   cmd.action(async () => {
     const cwd = process.cwd();
     console.log("");
@@ -454,6 +534,53 @@ function createInitCommand() {
     console.log(`  Stack:    ${colorize2(project.stack, c2.cyan)}`);
     console.log(`  Path:     ${colorize2(cwd, c2.dim)}`);
     console.log("");
+    process.stdout.write(colorize2("  Bootstrapping tool configs\u2026", c2.dim) + "\n");
+    const { results: bootstrapResults, staleScanNeeded } = await bootstrapConfigs(cwd);
+    process.stdout.write("\x1B[1A\x1B[2K");
+    console.log(colorize2("  Bootstrap", c2.bold));
+    console.log(colorize2("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500", c2.dim));
+    for (const r of bootstrapResults) {
+      const icon = bootstrapIcon(r.action);
+      const label = r.label.padEnd(20);
+      const detail = r.action === "created" ? colorize2(r.detail, c2.green) : r.action === "error" ? colorize2(r.detail, c2.yellow) : colorize2(r.detail, c2.dim);
+      console.log(`  ${icon}  ${label} ${detail}`);
+    }
+    const whenlabsConfigPath = resolve2(cwd, CONFIG_FILENAME);
+    if (!existsSync2(whenlabsConfigPath)) {
+      try {
+        const mergedConfig = {};
+        const staleConfigPath = resolve2(cwd, ".stale.yml");
+        if (existsSync2(staleConfigPath)) {
+          mergedConfig["stale"] = {};
+        }
+        const vowConfigPath = resolve2(cwd, ".vow.json");
+        if (existsSync2(vowConfigPath)) {
+          try {
+            const vowData = JSON.parse(readFileSync(vowConfigPath, "utf-8"));
+            mergedConfig["vow"] = {
+              ...typeof vowData.policy === "string" ? { policy: vowData.policy } : {},
+              ...typeof vowData.production_only === "boolean" ? { production_only: vowData.production_only } : {}
+            };
+          } catch {
+            mergedConfig["vow"] = {};
+          }
+        }
+        const envSchemaPath = resolve2(cwd, ".env.schema");
+        if (existsSync2(envSchemaPath)) {
+          mergedConfig["envalid"] = { schema: ".env.schema" };
+        }
+        mergedConfig["berth"] = {};
+        mergedConfig["aware"] = {};
+        mergedConfig["velocity"] = {};
+        writeFileSync(whenlabsConfigPath, stringify(mergedConfig, { lineWidth: 0 }), "utf-8");
+        console.log(`  ${colorize2("+", c2.green)}  ${colorize2(CONFIG_FILENAME, c2.bold)} ${colorize2("created", c2.green)}`);
+      } catch {
+        console.log(`  ${colorize2("!", c2.yellow)}  Could not generate ${colorize2(CONFIG_FILENAME, c2.bold)}`);
+      }
+    } else {
+      console.log(`  ${colorize2("-", c2.dim)}  ${colorize2(CONFIG_FILENAME, c2.bold)} ${colorize2("already exists", c2.dim)}`);
+    }
+    console.log("");
     process.stdout.write(colorize2("  Scanning project\u2026", c2.dim) + "\n");
     const results = await Promise.all([
       scanStale(cwd),
@@ -471,13 +598,32 @@ function createInitCommand() {
       const detail = r.status === "ok" ? colorize2(r.detail, c2.green) : r.status === "skipped" ? colorize2(r.detail, c2.dim) : r.status === "error" ? colorize2(r.detail, c2.yellow) : colorize2(r.detail, c2.red);
       console.log(`  ${icon}  ${label} ${detail}`);
     }
+    const staleResult = results.find((r) => r.label === "Doc drift (stale)");
+    if (staleResult?.status === "issues" || staleScanNeeded) {
+      process.stdout.write(colorize2("  Auto-fixing doc drift\u2026", c2.dim) + "\n");
+      const { exitCode: fixCode } = await runTool2(findBin("stale"), ["fix", "--apply"], cwd);
+      process.stdout.write("\x1B[1A\x1B[2K");
+      if (fixCode === 0) {
+        console.log(`  ${colorize2("\u2713", c2.green)}  ${colorize2("Doc drift auto-fixed", c2.green)}`);
+      } else if (fixCode === 127) {
+        console.log(`  ${colorize2("!", c2.yellow)}  ${colorize2("stale not found for auto-fix", c2.yellow)}`);
+      } else {
+        console.log(`  ${colorize2("-", c2.dim)}  ${colorize2("No high-confidence fixes available", c2.dim)}`);
+      }
+    }
     const issueCount = results.filter((r) => r.status === "issues").length;
     const errorCount = results.filter((r) => r.status === "error").length;
+    const bootstrapErrors = bootstrapResults.filter((r) => r.action === "error").length;
+    const bootstrapCreated = bootstrapResults.filter((r) => r.action === "created").length;
     console.log(colorize2("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500", c2.dim));
-    if (issueCount + errorCount === 0) {
+    if (issueCount + errorCount + bootstrapErrors === 0) {
       console.log(colorize2("  All clear \u2014 project looks healthy!", c2.green, c2.bold));
     } else {
-      console.log(colorize2(`  ${issueCount} tool(s) found issues, ${errorCount} could not run`, c2.yellow, c2.bold));
+      const parts = [];
+      if (bootstrapCreated > 0) parts.push(`${bootstrapCreated} config(s) created`);
+      if (issueCount > 0) parts.push(`${issueCount} scan(s) found issues`);
+      if (errorCount + bootstrapErrors > 0) parts.push(`${errorCount + bootstrapErrors} tool(s) could not run`);
+      console.log(colorize2(`  ${parts.join(", ")}`, c2.yellow, c2.bold));
     }
     console.log("");
     console.log(colorize2("  Next steps:", c2.bold));
@@ -498,7 +644,7 @@ function createInitCommand() {
 import { Command as Command4 } from "commander";
 import { join } from "path";
 import { homedir } from "os";
-import { mkdirSync, writeFileSync } from "fs";
+import { mkdirSync, writeFileSync as writeFileSync2 } from "fs";
 var STATUS_DIR = join(homedir(), ".whenlabs");
 function toolResultToStatus(r) {
   const count = r.issues + r.warnings;
@@ -535,10 +681,10 @@ function writeStatus(results) {
     },
     summary: buildSummary(results)
   };
-  writeFileSync(getStatusPath(), JSON.stringify(status, null, 2) + "\n");
+  writeFileSync2(getStatusPath(), JSON.stringify(status, null, 2) + "\n");
 }
 function sleep(ms) {
-  return new Promise((resolve4) => setTimeout(resolve4, ms));
+  return new Promise((resolve5) => setTimeout(resolve5, ms));
 }
 function createWatchCommand() {
   const cmd = new Command4("watch");
@@ -585,16 +731,213 @@ function createWatchCommand() {
   return cmd;
 }
 
+// src/commands/config.ts
+import { Command as Command5 } from "commander";
+import { existsSync as existsSync3, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { resolve as resolve3 } from "path";
+import { parse, stringify as stringify2 } from "yaml";
+var c3 = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m"
+};
+function colorize3(text, ...codes) {
+  return codes.join("") + text + c3.reset;
+}
+function readExistingToolConfigs(cwd) {
+  const config = {};
+  const stalePath = resolve3(cwd, ".stale.yml");
+  if (existsSync3(stalePath)) {
+    try {
+      const raw = readFileSync2(stalePath, "utf-8");
+      const parsed = parse(raw);
+      config.stale = {
+        ignore: Array.isArray(parsed?.ignore) ? parsed.ignore : void 0,
+        deep: typeof parsed?.deep === "boolean" ? parsed.deep : void 0
+      };
+    } catch {
+      config.stale = {};
+    }
+  }
+  const vowPath = resolve3(cwd, ".vow.json");
+  if (existsSync3(vowPath)) {
+    try {
+      const vow = JSON.parse(readFileSync2(vowPath, "utf-8"));
+      config.vow = {
+        policy: typeof vow.policy === "string" ? vow.policy : void 0,
+        production_only: typeof vow.production_only === "boolean" ? vow.production_only : void 0
+      };
+    } catch {
+    }
+  }
+  const schemaPath = resolve3(cwd, ".env.schema");
+  if (existsSync3(schemaPath)) {
+    config.envalid = { schema: ".env.schema" };
+  }
+  return config;
+}
+function generateDefaultConfig(cwd) {
+  const base = readExistingToolConfigs(cwd);
+  return {
+    stale: base.stale ?? {},
+    envalid: base.envalid ?? {},
+    vow: base.vow ?? {},
+    berth: {},
+    aware: {},
+    velocity: {}
+  };
+}
+function validateConfig(config) {
+  const errors = [];
+  if (config.stale !== void 0 && typeof config.stale !== "object") {
+    errors.push("stale: must be an object");
+  }
+  if (config.stale?.ignore !== void 0 && !Array.isArray(config.stale.ignore)) {
+    errors.push("stale.ignore: must be an array of strings");
+  }
+  if (config.stale?.deep !== void 0 && typeof config.stale.deep !== "boolean") {
+    errors.push("stale.deep: must be a boolean");
+  }
+  if (config.envalid !== void 0 && typeof config.envalid !== "object") {
+    errors.push("envalid: must be an object");
+  }
+  if (config.envalid?.schema !== void 0 && typeof config.envalid.schema !== "string") {
+    errors.push("envalid.schema: must be a string");
+  }
+  if (config.envalid?.environments !== void 0 && !Array.isArray(config.envalid.environments)) {
+    errors.push("envalid.environments: must be an array of strings");
+  }
+  if (config.vow !== void 0 && typeof config.vow !== "object") {
+    errors.push("vow: must be an object");
+  }
+  if (config.vow?.policy !== void 0 && typeof config.vow.policy !== "string") {
+    errors.push("vow.policy: must be a string");
+  }
+  if (config.vow?.production_only !== void 0 && typeof config.vow.production_only !== "boolean") {
+    errors.push("vow.production_only: must be a boolean");
+  }
+  if (config.berth !== void 0 && typeof config.berth !== "object") {
+    errors.push("berth: must be an object");
+  }
+  if (config.berth?.ports !== void 0) {
+    if (typeof config.berth.ports !== "object" || Array.isArray(config.berth.ports)) {
+      errors.push("berth.ports: must be a key/value map of port names to numbers");
+    } else {
+      for (const [k, v] of Object.entries(config.berth.ports)) {
+        if (typeof v !== "number") errors.push(`berth.ports.${k}: must be a number`);
+      }
+    }
+  }
+  if (config.aware !== void 0 && typeof config.aware !== "object") {
+    errors.push("aware: must be an object");
+  }
+  if (config.aware?.targets !== void 0 && !Array.isArray(config.aware.targets)) {
+    errors.push("aware.targets: must be an array of strings");
+  }
+  if (config.velocity !== void 0 && typeof config.velocity !== "object") {
+    errors.push("velocity: must be an object");
+  }
+  if (config.velocity?.project !== void 0 && typeof config.velocity.project !== "string") {
+    errors.push("velocity.project: must be a string");
+  }
+  return errors;
+}
+function createConfigCommand() {
+  const cmd = new Command5("config");
+  cmd.description("Manage unified .whenlabs.yml project config");
+  cmd.action(() => {
+    const cwd = process.cwd();
+    const configPath = resolve3(cwd, CONFIG_FILENAME);
+    console.log("");
+    console.log(colorize3("  when config", c3.bold, c3.cyan));
+    console.log(colorize3("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500", c3.dim));
+    if (!existsSync3(configPath)) {
+      console.log(`  ${colorize3("-", c3.dim)}  No ${colorize3(CONFIG_FILENAME, c3.bold)} found`);
+      console.log(`  ${colorize3("\u2022", c3.dim)} Run ${colorize3("when config init", c3.bold)} to generate one`);
+      console.log("");
+      return;
+    }
+    const raw = readFileSync2(configPath, "utf-8");
+    console.log(`  ${colorize3(configPath, c3.dim)}`);
+    console.log("");
+    for (const line of raw.split("\n")) {
+      console.log(`  ${line}`);
+    }
+  });
+  const initCmd = new Command5("init");
+  initCmd.description(`Generate ${CONFIG_FILENAME} from existing tool configs`);
+  initCmd.option("--force", "Overwrite existing config");
+  initCmd.action((options) => {
+    const cwd = process.cwd();
+    const configPath = resolve3(cwd, CONFIG_FILENAME);
+    console.log("");
+    console.log(colorize3("  when config init", c3.bold, c3.cyan));
+    console.log(colorize3("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500", c3.dim));
+    if (existsSync3(configPath) && !options.force) {
+      console.log(`  ${colorize3("-", c3.dim)}  ${colorize3(CONFIG_FILENAME, c3.bold)} already exists \u2014 use ${colorize3("--force", c3.bold)} to overwrite`);
+      console.log("");
+      return;
+    }
+    const config = generateDefaultConfig(cwd);
+    const yaml = stringify2(config, { lineWidth: 0 });
+    writeFileSync3(configPath, yaml, "utf-8");
+    console.log(`  ${colorize3("+", c3.green)}  Created ${colorize3(CONFIG_FILENAME, c3.bold)}`);
+    console.log("");
+    for (const line of yaml.split("\n")) {
+      if (line.trim()) console.log(`  ${colorize3(line, c3.dim)}`);
+    }
+    console.log("");
+  });
+  const validateCmd = new Command5("validate");
+  validateCmd.description(`Validate ${CONFIG_FILENAME} structure`);
+  validateCmd.action(() => {
+    const cwd = process.cwd();
+    const configPath = resolve3(cwd, CONFIG_FILENAME);
+    console.log("");
+    console.log(colorize3("  when config validate", c3.bold, c3.cyan));
+    console.log(colorize3("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500", c3.dim));
+    if (!existsSync3(configPath)) {
+      console.log(`  ${colorize3("-", c3.dim)}  No ${colorize3(CONFIG_FILENAME, c3.bold)} found \u2014 nothing to validate`);
+      console.log("");
+      return;
+    }
+    const config = loadConfig(cwd);
+    if (!config) {
+      console.log(`  ${colorize3("!", c3.yellow)}  Could not parse ${colorize3(CONFIG_FILENAME, c3.bold)} \u2014 invalid YAML`);
+      console.log("");
+      process.exitCode = 1;
+      return;
+    }
+    const errors = validateConfig(config);
+    if (errors.length === 0) {
+      console.log(`  ${colorize3("\u2713", c3.green)}  ${colorize3(CONFIG_FILENAME, c3.bold)} is valid`);
+    } else {
+      for (const err of errors) {
+        console.log(`  ${colorize3("\u2717", c3.red)}  ${err}`);
+      }
+      process.exitCode = 1;
+    }
+    console.log("");
+  });
+  cmd.addCommand(initCmd);
+  cmd.addCommand(validateCmd);
+  return cmd;
+}
+
 // src/index.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve3, dirname as dirname3 } from "path";
+import { readFileSync as readFileSync3 } from "fs";
+import { resolve as resolve4, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 var __dirname3 = dirname3(fileURLToPath3(import.meta.url));
-var { version } = JSON.parse(readFileSync2(resolve3(__dirname3, "..", "package.json"), "utf8"));
-var program = new Command5();
+var { version } = JSON.parse(readFileSync3(resolve4(__dirname3, "..", "package.json"), "utf8"));
+var program = new Command6();
 program.name("when").version(version).description("The WhenLabs developer toolkit \u2014 6 tools, one install");
 program.command("install").description("Install all WhenLabs tools globally (MCP server + CLAUDE.md instructions)").option("--cursor", "Install MCP servers into Cursor (~/.cursor/mcp.json)").option("--vscode", "Install MCP servers into VS Code (settings.json)").option("--windsurf", "Install MCP servers into Windsurf (~/.codeium/windsurf/mcp_config.json)").option("--all", "Install MCP servers into all supported editors").action(async (options) => {
-  const { install } = await import("./install-V24JHOA2.js");
+  const { install } = await import("./install-33GE3HKA.js");
   await install(options);
 });
 program.command("uninstall").description("Remove all WhenLabs tools").option("--cursor", "Remove MCP servers from Cursor").option("--vscode", "Remove MCP servers from VS Code").option("--windsurf", "Remove MCP servers from Windsurf").option("--all", "Remove MCP servers from all supported editors").action(async (options) => {
@@ -612,6 +955,7 @@ program.command("ci").description("Run stale, envalid, and vow checks \u2014 exi
 program.addCommand(createInitCommand());
 program.addCommand(createDoctorCommand());
 program.addCommand(createWatchCommand());
+program.addCommand(createConfigCommand());
 program.addCommand(createDelegateCommand("stale", "Detect documentation drift in your codebase"));
 program.addCommand(createDelegateCommand("envalid", "Validate .env files against a type-safe schema"));
 program.addCommand(createDelegateCommand("berth", "Detect and resolve port conflicts"));

package/dist/{install-V24JHOA2.js → install-33GE3HKA.js}

@@ -60,14 +60,21 @@ All six tools (including velocity) are available through the unified \`whenlabs\
 ### Tool Reference
 - \`berth_status\` \u2014 Show all active ports, Docker ports, and configured ports
 - \`berth_check\` \u2014 Scan a project directory for port conflicts
+- \`berth_auto_resolve\` \u2014 Check for conflicts and auto-resolve them in one step
 - \`stale_scan\` \u2014 Detect documentation drift in the codebase
+- \`stale_auto_fix\` \u2014 Scan for drift and auto-fix high-confidence issues in one step
 - \`envalid_validate\` \u2014 Validate .env files against their schema
 - \`envalid_detect\` \u2014 Find undocumented env vars in codebase
+- \`envalid_auto_fix\` \u2014 Detect undocumented env vars and auto-generate schema entries
 - \`aware_init\` \u2014 Auto-detect stack and generate AI context files
 - \`aware_doctor\` \u2014 Diagnose project health and config issues
+- \`aware_auto_sync\` \u2014 Diagnose and auto-sync stale AI context files in one step
 - \`vow_scan\` \u2014 Scan and summarize all dependency licenses
 - \`vow_check\` \u2014 Validate licenses against a policy file
 
+### Cross-tool Intelligence
+Tools provide follow-up suggestions when they detect issues relevant to other tools. When you see a "Tip:" in tool output, act on the suggestion \u2014 it means another tool can help.
+
 ### Proactive Background Scans
 WhenLabs tools run automatically in the background on a schedule. The status line shows findings:
 - \`stale:N\` \u2014 N docs have drifted from code. Run \`stale_scan\` and fix the drift.

package/dist/mcp.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   findBin
-} from "./chunk-2A2EZZF4.js";
+} from "./chunk-JOMP6AU5.js";
 
 // src/mcp/index.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -25,7 +25,7 @@ import { z } from "zod";
 // src/mcp/run-cli.ts
 import { spawn } from "child_process";
 import { join } from "path";
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from "fs";
 import { homedir } from "os";
 function runCli(bin, args, cwd) {
   return new Promise((res) => {
@@ -100,6 +100,39 @@ ${staleOutput}`);
         extras.push(`
 Note: Conflicts found in project "${projectName}".`);
       }
+      try {
+        const cacheFiles = readdirSync(CACHE_DIR).filter((f) => f.startsWith("stale_"));
+        for (const cacheFile of cacheFiles) {
+          const cached = JSON.parse(readFileSync(join(CACHE_DIR, cacheFile), "utf8"));
+          if (/\b\d{4,5}\b/.test(cached.output || "")) {
+            extras.push("\nTip: Port references found in documentation \u2014 stale_scan may need re-run after resolving conflicts.");
+            break;
+          }
+        }
+      } catch {
+      }
+    }
+  }
+  if (toolName === "envalid_detect") {
+    const serviceUrlMatches = output.match(/\b[A-Z_]*(?:HOST|PORT|URL|URI)[A-Z_]*\b/g);
+    if (serviceUrlMatches && serviceUrlMatches.length > 0) {
+      const examples = [...new Set(serviceUrlMatches)].slice(0, 3).join(", ");
+      extras.push(`
+Tip: Service URLs detected (${examples}, etc.) \u2014 run berth_register to track their ports for conflict detection.`);
+    }
+  }
+  if (toolName === "velocity_end_task") {
+    const largeChange = /actual_files["\s:]+([1-9]\d)/i.test(output) || /\b([6-9]|\d{2,})\s+files?\b/i.test(output);
+    if (largeChange) {
+      extras.push("\nTip: Large change detected \u2014 consider running stale_scan to check for documentation drift.");
+    }
+  }
+  if (toolName === "vow_scan") {
+    const cacheFile = join(CACHE_DIR, `vow_scan_${deriveProject(path)}.json`);
+    const isFirstScan = !existsSync(cacheFile);
+    const hasNewPackages = /new package|added|installed/i.test(output);
+    if (isFirstScan || hasNewPackages) {
+      extras.push("\nTip: Dependency changes detected \u2014 run aware_sync to update AI context files with new library info.");
     }
   }
   return extras;
@@ -157,6 +190,32 @@ function registerStaleTools(server2) {
       return { content: [{ type: "text", text: output }] };
     }
   );
+  server2.tool(
+    "stale_auto_fix",
+    "Scan for documentation drift and auto-fix high-confidence issues in one step",
+    {
+      path: z.string().optional().describe("Project directory to scan (defaults to cwd)"),
+      deep: z.coerce.boolean().optional().describe("Enable AI-powered deep analysis")
+    },
+    async ({ path, deep }) => {
+      const scanArgs = ["scan"];
+      if (deep) scanArgs.push("--deep");
+      const scanResult = await runCli("stale", scanArgs, path);
+      const scanOutput = formatOutput(scanResult);
+      writeCache("stale_scan", deriveProject(path), scanOutput, scanResult.code);
+      writeCache("stale_auto_fix", deriveProject(path), scanOutput, scanResult.code);
+      if (scanResult.code !== 0) {
+        const fixResult = await runCli("stale", ["fix", "--apply"], path);
+        const fixOutput = formatOutput(fixResult);
+        const combined = `${scanOutput}
+--- Auto-fix applied ---
+${fixOutput}`;
+        writeCache("stale_auto_fix", deriveProject(path), combined, fixResult.code);
+        return { content: [{ type: "text", text: combined }] };
+      }
+      return { content: [{ type: "text", text: scanOutput }] };
+    }
+  );
 }
 
 // src/mcp/envalid.ts
@@ -303,6 +362,28 @@ function registerEnvalidTools(server2) {
       return { content: [{ type: "text", text: output }] };
     }
   );
+  server2.tool(
+    "envalid_auto_fix",
+    "Detect undocumented env vars and auto-generate schema entries",
+    {
+      path: z2.string().optional().describe("Project directory (defaults to cwd)")
+    },
+    async ({ path }) => {
+      const detectResult = await runCli("envalid", ["detect"], path);
+      const detectOutput = formatOutput(detectResult);
+      writeCache("envalid_detect", deriveProject(path), detectOutput, detectResult.code);
+      const hasUndocumented = /undocumented|missing from schema/i.test(detectOutput);
+      if (hasUndocumented) {
+        const generateResult = await runCli("envalid", ["detect", "--generate"], path);
+        const generateOutput = formatOutput(generateResult);
+        const combined = `${detectOutput}
+--- Auto-generated schema entries ---
+${generateOutput}`;
+        return { content: [{ type: "text", text: combined }] };
+      }
+      return { content: [{ type: "text", text: detectOutput }] };
+    }
+  );
 }
 
 // src/mcp/berth.ts
@@ -443,6 +524,30 @@ function registerBerthTools(server2) {
       return { content: [{ type: "text", text: output }] };
     }
   );
+  server2.tool(
+    "berth_auto_resolve",
+    "Check for port conflicts and auto-resolve them",
+    {
+      path: z3.string().optional().describe("Project directory (defaults to cwd)"),
+      strategy: z3.enum(["kill", "reassign", "auto"]).optional().describe("Resolution strategy (default: auto)")
+    },
+    async ({ path, strategy }) => {
+      const checkResult = await runCli("berth", ["check", path || "."]);
+      const checkOutput = formatOutput(checkResult);
+      writeCache("berth_check", deriveProject(path), checkOutput, checkResult.code);
+      const hasConflicts = /conflict/i.test(checkOutput);
+      if (hasConflicts) {
+        const resolveArgs = ["resolve", "--strategy", strategy || "auto", "--kill"];
+        const resolveResult = await runCli("berth", resolveArgs, path);
+        const resolveOutput = formatOutput(resolveResult);
+        const combined = `${checkOutput}
+--- Auto-resolve applied ---
+${resolveOutput}`;
+        return { content: [{ type: "text", text: combined }] };
+      }
+      return { content: [{ type: "text", text: checkOutput }] };
+    }
+  );
 }
 
 // src/mcp/aware.ts
@@ -534,6 +639,28 @@ function registerAwareTools(server2) {
       return { content: [{ type: "text", text: output }] };
     }
   );
+  server2.tool(
+    "aware_auto_sync",
+    "Diagnose project health and auto-sync stale AI context files",
+    {
+      path: z4.string().optional().describe("Project directory (defaults to cwd)")
+    },
+    async ({ path }) => {
+      const doctorResult = await runCli("aware", ["doctor"], path);
+      const doctorOutput = formatOutput(doctorResult);
+      writeCache("aware_doctor", deriveProject(path), doctorOutput, doctorResult.code);
+      const needsSync = /stale|outdated|drift/i.test(doctorOutput);
+      if (needsSync) {
+        const syncResult = await runCli("aware", ["sync"], path);
+        const syncOutput = formatOutput(syncResult);
+        const combined = `${doctorOutput}
+--- Auto-sync applied ---
+${syncOutput}`;
+        return { content: [{ type: "text", text: combined }] };
+      }
+      return { content: [{ type: "text", text: doctorOutput }] };
+    }
+  );
 }
 
 // src/mcp/vow.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whenlabs/when",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "The WhenLabs developer toolkit — 6 tools, one install",
   "type": "module",
   "main": "dist/index.js",
@@ -36,6 +36,7 @@
     "@whenlabs/velocity-mcp": "^0.1.3",
     "@whenlabs/vow": "^0.1.4",
     "commander": "^12.0.0",
+    "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/dist/chunk-2A2EZZF4.js

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-
-// src/utils/find-bin.ts
-import { resolve, dirname } from "path";
-import { existsSync } from "fs";
-import { fileURLToPath } from "url";
-var __dirname = dirname(fileURLToPath(import.meta.url));
-function findBin(name) {
-  const pkgRoot = resolve(__dirname, "../..");
-  const localBin = resolve(pkgRoot, "node_modules", ".bin", name);
-  if (existsSync(localBin)) return localBin;
-  const directCli = resolve(pkgRoot, "node_modules", "@whenlabs", name, "dist", "cli.js");
-  if (existsSync(directCli)) return directCli;
-  return name;
-}
-
-export {
-  findBin
-};