@whenlabs/when 0.8.1 → 0.9.1

package/README.md

@@ -16,10 +16,9 @@ This is a one-time setup. After install, all six tools are available in every pr
 
 Running `npx @whenlabs/when install` will:
 
-1. Register **two MCP servers** in your Claude Code configuration:
-   - `velocity-mcp` — task timing and estimation tools
-   - `whenlabs` — stale, envalid, berth, aware, and vow tools
+1. Register a **single MCP server** (`whenlabs`) in your Claude Code configuration — all six tools, including velocity, are served from one server
 2. Inject **CLAUDE.md instructions** so Claude knows when to use each tool automatically — and prefers them over shell commands
+3. Clean up any legacy `velocity-mcp` registrations (velocity is now bundled)
 
 Once connected, Claude can call any tool directly without you asking. For example, after a refactor Claude might run `stale_scan` to check for doc drift, or before a release it might run `vow_check` to validate licenses.
 
@@ -46,17 +45,21 @@ These tools are available to Claude in every session after install:
 | `velocity_start_task` | Start timing a coding task |
 | `velocity_end_task` | End timing and record results |
 | `velocity_estimate` | Estimate time for a planned task |
-| `velocity_stats` | Show aggregate performance stats |
+| `velocity_stats` | Show aggregate performance stats with insights |
 | `velocity_history` | Show task history |
 | `stale_scan` | Detect documentation drift |
+| `stale_fix` | Auto-fix documentation drift (wrong paths, dead links, phantom env vars) |
 | `envalid_validate` | Validate .env files against schemas |
 | `envalid_detect` | Find undocumented env vars in codebase |
+| `envalid_generate_schema` | Generate .env.schema from code analysis |
 | `berth_status` | Show active ports and conflicts |
 | `berth_check` | Scan project for port conflicts |
+| `berth_resolve` | Auto-resolve port conflicts (kill or reassign) |
 | `aware_init` | Auto-detect stack, generate AI context files |
 | `aware_doctor` | Diagnose project health and config issues |
 | `vow_scan` | Scan and summarize dependency licenses |
 | `vow_check` | Validate licenses against policy |
+| `vow_hook_install` | Install pre-commit license check hook |
 
 ## Multi-Editor Support
 
@@ -78,12 +81,18 @@ You can also run tools directly from the command line:
 ```bash
 when init            # Onboard a project — detect stack, run all tools
 when stale scan
+when stale fix       # Auto-fix documentation drift
 when envalid validate
+when envalid detect --generate  # Generate schema from code
 when berth status
+when berth resolve   # Auto-resolve port conflicts
 when aware init
 when vow scan
+when vow hook install  # Install pre-commit license hook
 when status          # Show installation status
 when doctor          # Run all tools, show unified health report
+when doctor --watch  # Continuous monitoring dashboard
+when watch           # Background daemon for status line
 when ci              # Run checks for CI (exits 1 on issues)
 ```
 
@@ -93,7 +102,11 @@ One command to onboard any project. Auto-detects your stack, runs all 5 tools in
 
 ### `when doctor`
 
-Runs all 5 CLI tools against the current project and displays a unified health report card. Supports `--json` for machine-readable output.
+Runs all 5 CLI tools against the current project and displays a unified health report card. Supports `--json` for machine-readable output and `--watch` for continuous monitoring with a live dashboard.
+
+### `when watch`
+
+Background daemon that runs all 5 tools on intervals and writes results to `~/.whenlabs/status.json`. Powers the Claude Code status line integration. Use `--once` for a single scan or `--interval <seconds>` to customize the schedule.
 
 ### `when ci`
 
@@ -118,7 +131,7 @@ when ci --json       # Machine-readable JSON output
 npx @whenlabs/when uninstall
 ```
 
-Removes both MCP servers and cleans up CLAUDE.md instructions.
+Removes the MCP server and cleans up CLAUDE.md instructions.
 
 ## License
 

package/dist/chunk-4ZVSCJCJ.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+// src/utils/status-provider.ts
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync, statSync } from "fs";
+var STATUS_PATH = join(homedir(), ".whenlabs", "status.json");
+function getStatusPath() {
+  return STATUS_PATH;
+}
+function readStatus() {
+  if (!existsSync(STATUS_PATH)) return null;
+  try {
+    const raw = readFileSync(STATUS_PATH, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function formatStatusLine() {
+  const data = readStatus();
+  if (!data) return null;
+  const tools = data.tools;
+  const parts = [];
+  for (const [key, info] of Object.entries(tools)) {
+    const label = key === "envalid" ? "env" : key === "vow" ? "lic" : key;
+    if (info.status === "ok") {
+      parts.push(`\u2713${label}`);
+    } else if (info.status === "issues") {
+      parts.push(`\u2717${label}:${info.count}`);
+    } else {
+      parts.push(`!${label}`);
+    }
+  }
+  return parts.join(" ");
+}
+function isStale(maxAgeMs = 120 * 60 * 1e3) {
+  if (!existsSync(STATUS_PATH)) return true;
+  try {
+    const stat = statSync(STATUS_PATH);
+    return Date.now() - stat.mtimeMs > maxAgeMs;
+  } catch {
+    return true;
+  }
+}
+
+export {
+  getStatusPath,
+  readStatus,
+  formatStatusLine,
+  isStale
+};

package/dist/index.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
+import {
+  getStatusPath
+} from "./chunk-4ZVSCJCJ.js";
 
 // src/index.ts
-import { Command as Command4 } from "commander";
+import { Command as Command5 } from "commander";
 
 // src/commands/delegate.ts
 import { Command } from "commander";
@@ -47,25 +50,15 @@ function createDelegateCommand(name, description, binName) {
 
 // src/commands/doctor.ts
 import { Command as Command2 } from "commander";
+
+// src/utils/tool-runner.ts
 import { spawn as spawn2 } from "child_process";
 import { resolve as resolve2, dirname as dirname2 } from "path";
 import { existsSync as existsSync2 } from "fs";
 import { fileURLToPath as fileURLToPath2 } from "url";
 var __dirname2 = dirname2(fileURLToPath2(import.meta.url));
-var c = {
-  reset: "\x1B[0m",
-  bold: "\x1B[1m",
-  green: "\x1B[32m",
-  yellow: "\x1B[33m",
-  red: "\x1B[31m",
-  cyan: "\x1B[36m",
-  dim: "\x1B[2m"
-};
-function colorize(text, ...codes) {
-  return codes.join("") + text + c.reset;
-}
 function findBin2(name) {
-  const pkgRoot = resolve2(__dirname2, "..");
+  const pkgRoot = resolve2(__dirname2, "..", "..");
   const localBin = resolve2(pkgRoot, "node_modules", ".bin", name);
   if (existsSync2(localBin)) return localBin;
   return name;
@@ -215,6 +208,29 @@ async function checkAware() {
     exitCode
   };
 }
+async function runAllChecks(cwd) {
+  return Promise.all([
+    checkStale(cwd),
+    checkEnvalid(cwd),
+    checkBerth(cwd),
+    checkVow(cwd),
+    checkAware()
+  ]);
+}
+
+// src/commands/doctor.ts
+var c = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  red: "\x1B[31m",
+  cyan: "\x1B[36m",
+  dim: "\x1B[2m"
+};
+function colorize(text, ...codes) {
+  return codes.join("") + text + c.reset;
+}
 function statusIcon(result) {
   switch (result.status) {
     case "ok":
@@ -257,13 +273,7 @@ function createDoctorCommand() {
     if (!options.json) {
       process.stdout.write(colorize("  Running health checks\u2026", c.dim) + "\n");
     }
-    const results = await Promise.all([
-      checkStale(cwd),
-      checkEnvalid(cwd),
-      checkBerth(cwd),
-      checkVow(cwd),
-      checkAware()
-    ]);
+    const results = await runAllChecks(cwd);
     const hasIssues = results.some((r) => r.status === "issues" || r.status === "error");
     if (options.json) {
       const output = {
@@ -491,11 +501,102 @@ function createInitCommand() {
   return cmd;
 }
 
+// src/commands/watch.ts
+import { Command as Command4 } from "commander";
+import { join } from "path";
+import { homedir } from "os";
+import { mkdirSync, writeFileSync } from "fs";
+var STATUS_DIR = join(homedir(), ".whenlabs");
+function toolResultToStatus(r) {
+  const count = r.issues + r.warnings;
+  if (r.status === "error") {
+    return { status: "error", count, detail: r.detail };
+  }
+  if (r.status === "issues") {
+    return { status: "issues", count, detail: r.detail };
+  }
+  return { status: "ok", count: 0, detail: r.detail };
+}
+function buildSummary(results) {
+  const map = {};
+  for (const r of results) map[r.name] = r;
+  const stalePart = `stale:${map["stale"]?.issues ?? 0}`;
+  const envPart = `env:${(map["envalid"]?.issues ?? 0) + (map["envalid"]?.warnings ?? 0)}`;
+  const portsPart = `ports:${map["berth"]?.issues ?? 0}`;
+  const licPart = `lic:${(map["vow"]?.issues ?? 0) + (map["vow"]?.warnings ?? 0)}`;
+  const awarePart = `aware:${map["aware"]?.status === "ok" || map["aware"]?.status === "skipped" ? "ok" : "stale"}`;
+  return `${stalePart} ${envPart} ${portsPart} ${licPart} ${awarePart}`;
+}
+function writeStatus(results) {
+  mkdirSync(STATUS_DIR, { recursive: true });
+  const toolsMap = {};
+  for (const r of results) toolsMap[r.name] = r;
+  const status = {
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    tools: {
+      stale: toolResultToStatus(toolsMap["stale"]),
+      envalid: toolResultToStatus(toolsMap["envalid"]),
+      berth: toolResultToStatus(toolsMap["berth"]),
+      vow: toolResultToStatus(toolsMap["vow"]),
+      aware: toolResultToStatus(toolsMap["aware"])
+    },
+    summary: buildSummary(results)
+  };
+  writeFileSync(getStatusPath(), JSON.stringify(status, null, 2) + "\n");
+}
+function sleep(ms) {
+  return new Promise((resolve4) => setTimeout(resolve4, ms));
+}
+function createWatchCommand() {
+  const cmd = new Command4("watch");
+  cmd.description("Run all 5 WhenLabs tools on a schedule and write results to ~/.whenlabs/status.json");
+  cmd.option("--once", "Run a single scan and exit");
+  cmd.option("--interval <seconds>", "Override the default scan interval (seconds)", "60");
+  cmd.action(async (options) => {
+    const cwd = process.cwd();
+    const intervalSec = Math.max(10, parseInt(options.interval ?? "60", 10));
+    let stopped = false;
+    const shutdown = () => {
+      stopped = true;
+      process.stderr.write("\nwatch: shutting down gracefully\n");
+      process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    const runScan = async () => {
+      const start = Date.now();
+      process.stderr.write(`watch: scanning... `);
+      const results = await runAllChecks(cwd);
+      writeStatus(results);
+      const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
+      const summary = buildSummary(results);
+      process.stderr.write(`done in ${elapsed}s  [${summary}]
+`);
+      const hasIssues = results.some((r) => r.status === "issues" || r.status === "error");
+      return hasIssues;
+    };
+    if (options.once) {
+      const hasIssues = await runScan();
+      process.exit(hasIssues ? 1 : 0);
+      return;
+    }
+    process.stderr.write(`watch: started (interval=${intervalSec}s, status=${getStatusPath()})
+`);
+    while (!stopped) {
+      await runScan();
+      for (let i = 0; i < intervalSec && !stopped; i++) {
+        await sleep(1e3);
+      }
+    }
+  });
+  return cmd;
+}
+
 // src/index.ts
-var program = new Command4();
+var program = new Command5();
 program.name("when").version("0.1.0").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-HPF26YW2.js");
+  const { install } = await import("./install-TFEGFWJ5.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) => {
@@ -503,7 +604,7 @@ program.command("uninstall").description("Remove all WhenLabs tools").option("--
   await uninstall(options);
 });
 program.command("status").description("Show installation status and velocity stats").action(async () => {
-  const { status } = await import("./status-LOZGVOA3.js");
+  const { status } = await import("./status-QWAHXHNA.js");
   await status();
 });
 program.command("ci").description("Run stale, envalid, and vow checks \u2014 exits 1 if any tool finds issues").option("--ci", "Output GitHub Actions annotations (::error file=X::message)").option("--json", "Machine-readable JSON output").action(async (options) => {
@@ -512,6 +613,7 @@ program.command("ci").description("Run stale, envalid, and vow checks \u2014 exi
 });
 program.addCommand(createInitCommand());
 program.addCommand(createDoctorCommand());
+program.addCommand(createWatchCommand());
 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-TFEGFWJ5.js

@@ -0,0 +1,447 @@
+#!/usr/bin/env node
+import {
+  ALL_EDITORS,
+  installForEditor,
+  registerMcpServer
+} from "./chunk-3PDLNC63.js";
+import {
+  injectBlock
+} from "./chunk-NYUYV3UL.js";
+
+// src/commands/install.ts
+import { join } from "path";
+import { homedir } from "os";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync } from "fs";
+var CLAUDE_MD_PATH = join(homedir(), ".claude", "CLAUDE.md");
+var SCRIPTS_DIR = join(homedir(), ".claude", "scripts");
+var STATUSLINE_PATH = join(SCRIPTS_DIR, "statusline.py");
+var SETTINGS_PATH = join(homedir(), ".claude", "settings.json");
+var OLD_START_MARKER = "<!-- velocity-mcp:start -->";
+var OLD_END_MARKER = "<!-- velocity-mcp:end -->";
+var CLAUDE_MD_CONTENT = `# WhenLabs Toolkit
+
+## Task Timing (velocity-mcp)
+
+Velocity tools are part of the unified \`whenlabs\` MCP server. Follow these rules for EVERY session:
+
+1. **Before starting any discrete coding task**, call \`velocity_start_task\` with:
+   - Appropriate \`category\` (scaffold, implement, refactor, debug, test, config, docs, deploy)
+   - Relevant \`tags\` (e.g. typescript, react, sqlite, api)
+   - Clear \`description\` of what you're about to do
+   - \`estimated_files\` if you know how many files you'll touch
+   - \`project\` set to the current project name (auto-detected from git remote or directory name)
+
+2. **After completing each task**, call \`velocity_end_task\` with:
+   - The \`task_id\` from the start call
+   - \`status\`: completed, failed, or abandoned
+   - \`actual_files\`: how many files were actually modified
+   - \`notes\`: any useful context about what happened
+
+3. **When creating a multi-step plan**, call \`velocity_estimate\` to provide the user with a time estimate before starting work.
+
+4. **If the user asks about speed or performance**, call \`velocity_stats\` to show aggregate data.
+
+### Guidelines
+- Every discrete unit of work should be tracked \u2014 don't batch multiple unrelated changes into one task
+- If a task is abandoned or fails, still call \`velocity_end_task\` with the appropriate status
+- Use consistent tags across sessions so the similarity matching can find comparable historical tasks
+- Keep descriptions concise but specific enough to be useful for future matching
+
+## WhenLabs MCP Tools (ALWAYS prefer these over shell commands)
+
+All six tools (including velocity) are available through the unified \`whenlabs\` MCP server. **ALWAYS use these MCP tools instead of running shell commands like lsof, grep, or manual checks.** These tools are purpose-built and give better results:
+
+| When to use | Call this tool | NOT this |
+|-------------|---------------|----------|
+| Check ports or port conflicts | \`berth_status\` or \`berth_check\` | \`lsof\`, \`netstat\`, \`ss\` |
+| Scan dependency licenses | \`vow_scan\` or \`vow_check\` | manual \`npm ls\`, \`license-checker\` |
+| Check if docs are stale | \`stale_scan\` | manual file comparison |
+| Validate .env files | \`envalid_validate\` or \`envalid_detect\` | manual .env inspection |
+| Generate AI context files | \`aware_init\` or \`aware_doctor\` | manual CLAUDE.md creation |
+
+### Tool Reference
+- \`berth_status\` \u2014 Show all active ports, Docker ports, and configured ports
+- \`berth_check\` \u2014 Scan a project directory for port conflicts
+- \`stale_scan\` \u2014 Detect documentation drift in the codebase
+- \`envalid_validate\` \u2014 Validate .env files against their schema
+- \`envalid_detect\` \u2014 Find undocumented env vars in codebase
+- \`aware_init\` \u2014 Auto-detect stack and generate AI context files
+- \`aware_doctor\` \u2014 Diagnose project health and config issues
+- \`vow_scan\` \u2014 Scan and summarize all dependency licenses
+- \`vow_check\` \u2014 Validate licenses against a policy file
+
+### 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.
+- \`env:N\` \u2014 N .env issues found. Run \`envalid_validate\` and help the user fix them.
+- \`ports:N\` \u2014 N port conflicts. Run \`berth_status\` and suggest resolution.
+- \`lic:N?\` \u2014 N packages with unknown licenses. Run \`vow_scan\` for details.
+- \`aware:stale\` \u2014 AI context files are outdated. Run \`aware_init\` to regenerate.
+
+**When you see any of these in the status line, proactively tell the user and offer to fix the issue.** Do not wait for the user to ask.`;
+var STATUSLINE_SCRIPT = `#!/usr/bin/env python3
+"""WhenLabs status line for Claude Code \u2014 with proactive background tool scans."""
+
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+CACHE_DIR = Path.home() / ".whenlabs" / "cache"
+CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+# Scan intervals in seconds
+INTERVALS = {
+    "berth":   900,   # 15 min
+    "stale":   1800,  # 30 min
+    "envalid": 1800,  # 30 min
+    "vow":     3600,  # 60 min
+    "aware":   3600,  # 60 min
+}
+
+
+class C:
+    AMBER = "\\033[38;2;196;106;26m"
+    BLUE = "\\033[38;2;59;130;246m"
+    CYAN = "\\033[38;2;34;211;238m"
+    GREEN = "\\033[38;2;34;197;94m"
+    RED = "\\033[38;2;239;68;68m"
+    YELLOW = "\\033[38;2;234;179;8m"
+    GRAY = "\\033[38;2;156;163;175m"
+    DIM = "\\033[2m"
+    RESET = "\\033[0m"
+    SEP = f"\\033[38;2;107;114;128m \\u30fb \\033[0m"
+
+
+def git_info(cwd):
+    try:
+        subprocess.run(["git", "rev-parse", "--git-dir"], cwd=cwd, capture_output=True, check=True, timeout=1)
+        branch = subprocess.run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd, capture_output=True, text=True, timeout=1).stdout.strip()
+        status = subprocess.run(["git", "status", "--porcelain"], cwd=cwd, capture_output=True, text=True, timeout=1).stdout
+        clean = len([l for l in status.strip().split("\\n") if l]) == 0
+        color = C.GREEN if clean else C.YELLOW
+        icon = "\\u2713" if clean else "\\u00b1"
+        return f"{color}{branch} {icon}{C.RESET}"
+    except Exception:
+        return None
+
+
+def mcp_servers(data):
+    servers = []
+    try:
+        cfg = Path.home() / ".claude.json"
+        if cfg.exists():
+            with open(cfg) as f:
+                servers.extend(json.load(f).get("mcpServers", {}).keys())
+    except Exception:
+        pass
+    cwd = data.get("workspace", {}).get("current_dir", "")
+    if cwd:
+        for p in [Path(cwd) / ".mcp.json", Path(cwd) / ".claude" / ".mcp.json"]:
+            try:
+                if p.exists():
+                    with open(p) as f:
+                        servers.extend(json.load(f).get("mcpServers", {}).keys())
+            except Exception:
+                pass
+    seen = set()
+    return [s for s in servers if not (s in seen or seen.add(s))]
+
+
+def context_pct(data):
+    try:
+        cw = data["context_window"]
+        size = cw["context_window_size"]
+        usage = cw.get("current_usage", {})
+        tokens = usage.get("input_tokens", 0) + usage.get("cache_creation_input_tokens", 0) + usage.get("cache_read_input_tokens", 0)
+        pct = (tokens * 100) // size
+        color = C.GREEN if pct < 40 else C.YELLOW if pct < 70 else C.RED
+        return f"{C.DIM}{color}{pct}%{C.RESET}"
+    except Exception:
+        return None
+
+
+def cost_info(data):
+    try:
+        cfg = Path.home() / ".claude.json"
+        if cfg.exists():
+            with open(cfg) as f:
+                if json.load(f).get("oauthAccount", {}).get("accountUuid"):
+                    return None
+    except Exception:
+        pass
+    try:
+        cost = data.get("cost", {}).get("total_cost_usd")
+        if cost:
+            color = C.GREEN if cost < 1 else C.YELLOW if cost < 5 else C.RED
+            return f"{color}\${cost:.2f}{C.RESET}"
+    except Exception:
+        pass
+    return None
+
+
+# --- Background tool scanning ---
+
+def cache_path(tool, cwd):
+    project = Path(cwd).name if cwd else "global"
+    return CACHE_DIR / f"{tool}_{project}.json"
+
+
+def should_run(tool, cwd):
+    cp = cache_path(tool, cwd)
+    if not cp.exists():
+        return True
+    try:
+        cached = json.loads(cp.read_text())
+        return (time.time() - cached.get("timestamp", 0)) > INTERVALS[tool]
+    except Exception:
+        return True
+
+
+def run_bg(tool, args, cwd):
+    cp = cache_path(tool, cwd)
+    snippet = (
+        "import subprocess, json, time, os; "
+        f"args = {args!r}; "
+        f"cwd = {cwd!r}; "
+        f"out_path = {str(cp)!r}; "
+        "env = {**os.environ, 'FORCE_COLOR': '0', 'NO_COLOR': '1'}; "
+        "r = subprocess.run(args, cwd=cwd, capture_output=True, text=True, env=env, timeout=60); "
+        "cache = {'timestamp': time.time(), 'output': r.stdout + r.stderr, 'code': r.returncode}; "
+        "open(out_path, 'w').write(json.dumps(cache))"
+    )
+    try:
+        subprocess.Popen(
+            [sys.executable, "-c", snippet],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            start_new_session=True,
+        )
+    except Exception:
+        pass
+
+
+def read_cache(tool, cwd):
+    cp = cache_path(tool, cwd)
+    if not cp.exists():
+        return None
+    try:
+        return json.loads(cp.read_text())
+    except Exception:
+        return None
+
+
+def parse_stale(cached):
+    if not cached or cached["code"] != 0:
+        return None
+    out = cached["output"]
+    drifted = out.count("\\u2717")
+    if drifted > 0:
+        return f"{C.RED}stale:{drifted}{C.RESET}"
+    if "\\u2713" in out or "No drift" in out.lower() or "clean" in out.lower():
+        return f"{C.GREEN}stale:ok{C.RESET}"
+    return None
+
+
+def parse_envalid(cached):
+    if not cached:
+        return None
+    out = cached["output"]
+    if cached["code"] != 0:
+        errors = sum(1 for line in out.split("\\n") if "\\u2717" in line or "error" in line.lower() or "missing" in line.lower())
+        if errors > 0:
+            return f"{C.RED}env:{errors}{C.RESET}"
+        return f"{C.YELLOW}env:?{C.RESET}"
+    return f"{C.GREEN}env:ok{C.RESET}"
+
+
+def parse_berth(cached):
+    if not cached:
+        return None
+    out = cached["output"]
+    conflicts = out.lower().count("conflict")
+    if conflicts > 0:
+        return f"{C.RED}ports:{conflicts}{C.RESET}"
+    return None
+
+
+def parse_vow(cached):
+    if not cached:
+        return None
+    out = cached["output"]
+    unknown = 0
+    for line in out.split("\\n"):
+        low = line.lower()
+        if "unknown" in low or "unlicensed" in low:
+            for word in line.split():
+                if word.isdigit():
+                    unknown += int(word)
+                    break
+            else:
+                unknown += 1
+    if unknown > 0:
+        return f"{C.YELLOW}lic:{unknown}?{C.RESET}"
+    return None
+
+
+def parse_aware(cached):
+    if not cached:
+        return None
+    out = cached["output"]
+    if cached["code"] != 0 or "stale" in out.lower() or "outdated" in out.lower() or "drift" in out.lower():
+        return f"{C.YELLOW}aware:stale{C.RESET}"
+    return None
+
+
+def run_scans(cwd):
+    if not cwd:
+        return []
+
+    scans = {
+        "stale":   (["npx", "--yes", "@whenlabs/stale", "scan"], parse_stale),
+        "envalid": (["npx", "--yes", "@whenlabs/envalid", "validate"], parse_envalid),
+        "berth":   (["npx", "--yes", "@whenlabs/berth", "check", "."], parse_berth),
+        "vow":     (["npx", "--yes", "@whenlabs/vow", "scan"], parse_vow),
+        "aware":   (["npx", "--yes", "@whenlabs/aware", "doctor"], parse_aware),
+    }
+
+    for tool, (args, _) in scans.items():
+        if should_run(tool, cwd):
+            run_bg(tool, args, cwd)
+            break
+
+    results = []
+    for tool, (_, parser) in scans.items():
+        cached = read_cache(tool, cwd)
+        if cached:
+            parsed = parser(cached)
+            if parsed:
+                results.append(parsed)
+
+    return results
+
+
+def main():
+    try:
+        data = json.loads(sys.stdin.read())
+    except Exception:
+        return
+
+    parts = []
+
+    cwd = data.get("workspace", {}).get("current_dir", "")
+    if cwd:
+        parts.append(f"{C.BLUE}{Path(cwd).name}{C.RESET}")
+
+    if cwd:
+        g = git_info(cwd)
+        if g:
+            parts.append(g)
+
+    servers = mcp_servers(data)
+    if servers:
+        names = " ".join(servers)
+        parts.append(f"{C.AMBER}{C.DIM}{names}{C.RESET}")
+
+    c = cost_info(data)
+    if c:
+        parts.append(c)
+
+    model = data.get("model", {}).get("display_name", "")
+    if model:
+        short = "".join(ch for ch in model if ch.isalpha()).lower()
+        parts.append(f"{C.GRAY}{short}{C.RESET}")
+
+    ctx = context_pct(data)
+    if ctx:
+        parts.append(ctx)
+
+    ver = data.get("version")
+    if ver:
+        parts.append(f"{C.DIM}{C.GRAY}v{ver}{C.RESET}")
+
+    scan_results = run_scans(cwd)
+
+    print(C.SEP.join(parts))
+
+    if scan_results:
+        print(f"{C.DIM}{C.GRAY}  tools:{C.RESET} {f' {C.DIM}|{C.RESET} '.join(scan_results)}")
+
+
+if __name__ == "__main__":
+    main()
+`;
+function installStatusLine() {
+  try {
+    mkdirSync(SCRIPTS_DIR, { recursive: true });
+    writeFileSync(STATUSLINE_PATH, STATUSLINE_SCRIPT, "utf-8");
+    chmodSync(STATUSLINE_PATH, 493);
+    let settings = {};
+    if (existsSync(SETTINGS_PATH)) {
+      try {
+        settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+      } catch {
+        settings = {};
+      }
+    }
+    const statuslineCmd = `python3 ${STATUSLINE_PATH}`;
+    const currentCmd = settings.statusLine?.command;
+    if (currentCmd !== statuslineCmd) {
+      settings.statusLine = { type: "command", command: statuslineCmd };
+      writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    }
+    return { installed: true, message: "Status line installed (proactive background scans)" };
+  } catch (err) {
+    return { installed: false, message: `Status line install failed: ${err.message}` };
+  }
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function hasOldBlock(filePath) {
+  if (!existsSync(filePath)) return false;
+  const content = readFileSync(filePath, "utf-8");
+  return content.includes(OLD_START_MARKER) && content.includes(OLD_END_MARKER);
+}
+function removeOldBlock(filePath) {
+  if (!existsSync(filePath)) return;
+  let content = readFileSync(filePath, "utf-8");
+  const pattern = new RegExp(
+    `\\n?${escapeRegex(OLD_START_MARKER)}[\\s\\S]*?${escapeRegex(OLD_END_MARKER)}\\n?`,
+    "g"
+  );
+  content = content.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
+  writeFileSync(filePath, content, "utf-8");
+}
+async function install(options = {}) {
+  console.log("\n\u{1F527} WhenLabs toolkit installer\n");
+  const editorFlags = options.all ? ALL_EDITORS : [
+    options.cursor && "cursor",
+    options.vscode && "vscode",
+    options.windsurf && "windsurf"
+  ].filter(Boolean);
+  const claudeOnly = editorFlags.length === 0;
+  if (claudeOnly) {
+    const mcpResult = registerMcpServer();
+    console.log(mcpResult.success ? `  \u2713 ${mcpResult.message}` : `  \u2717 ${mcpResult.message}`);
+    injectBlock(CLAUDE_MD_PATH, CLAUDE_MD_CONTENT);
+    console.log(`  \u2713 CLAUDE.md instructions written to ${CLAUDE_MD_PATH}`);
+    const slResult = installStatusLine();
+    console.log(slResult.installed ? `  \u2713 ${slResult.message}` : `  \u2717 ${slResult.message}`);
+    if (hasOldBlock(CLAUDE_MD_PATH)) {
+      removeOldBlock(CLAUDE_MD_PATH);
+      console.log("  \u2713 Removed legacy velocity-mcp markers (migrated to whenlabs block)");
+    }
+  } else {
+    for (const editor of editorFlags) {
+      const result = installForEditor(editor);
+      console.log(result.success ? `  \u2713 ${result.message}` : `  \u2717 ${result.message}`);
+    }
+  }
+  console.log("\nInstallation complete. Run `when status` to verify.\n");
+}
+export {
+  install
+};

package/dist/mcp.js

@@ -100,7 +100,7 @@ Note: Conflicts found in project "${projectName}".`);
 }
 var server = new McpServer({
   name: "whenlabs",
-  version: "0.2.0"
+  version: "0.3.0"
 });
 var velocityDb = initDb();
 var velocityQueries = new TaskQueries(velocityDb);
@@ -137,6 +137,25 @@ server.tool(
     return { content: [{ type: "text", text: output + extras.join("") }] };
   }
 );
+server.tool(
+  "stale_fix",
+  "Auto-fix documentation drift \u2014 generate fixes for wrong file paths, dead links, phantom env vars, outdated scripts",
+  {
+    path: z.string().optional().describe("Project directory to scan (defaults to cwd)"),
+    format: z.enum(["terminal", "diff"]).optional().describe("Output format (default: terminal)"),
+    apply: z.coerce.boolean().optional().describe("Apply high-confidence fixes directly"),
+    dryRun: z.coerce.boolean().optional().describe("Show what --apply would do without writing")
+  },
+  async ({ path, format, apply, dryRun }) => {
+    const args = ["fix"];
+    if (format) args.push("--format", format);
+    if (apply) args.push("--apply");
+    if (dryRun) args.push("--dry-run");
+    const result = await runCli("stale", args, path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "stale_init",
   "Generate a .stale.yml config file for customizing documentation drift detection",
@@ -263,6 +282,21 @@ server.tool(
     return { content: [{ type: "text", text: output }] };
   }
 );
+server.tool(
+  "envalid_generate_schema",
+  "Generate .env.schema from code analysis \u2014 infer types, required-ness, and sensitivity from usage patterns",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    output: z.string().optional().describe("Output file path (default: .env.schema)")
+  },
+  async ({ path, output }) => {
+    const args = ["detect", "--generate"];
+    if (output) args.push("-o", output);
+    const result = await runCli("envalid", args, path);
+    const outputText = formatOutput(result);
+    return { content: [{ type: "text", text: outputText }] };
+  }
+);
 server.tool(
   "envalid_hook_status",
   "Check if the envalid pre-commit git hook is installed",
@@ -379,6 +413,25 @@ server.tool(
     return { content: [{ type: "text", text: output }] };
   }
 );
+server.tool(
+  "berth_resolve",
+  "Auto-resolve port conflicts \u2014 detect conflicts and fix via kill or reassign strategy",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    strategy: z.enum(["kill", "reassign", "auto"]).optional().describe("Resolution strategy (default: auto)"),
+    kill: z.coerce.boolean().optional().describe("Allow killing processes (required for kill/auto strategies)"),
+    dryRun: z.coerce.boolean().optional().describe("Show what would be done without making changes")
+  },
+  async ({ path, strategy, kill, dryRun }) => {
+    const args = ["resolve"];
+    if (strategy) args.push("--strategy", strategy);
+    if (kill) args.push("--kill");
+    if (dryRun) args.push("--dry-run");
+    const result = await runCli("berth", args, path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "berth_predict",
   "Predict port conflicts from project config files before starting \u2014 dry-run conflict check",
@@ -427,9 +480,14 @@ server.tool(
 server.tool(
   "aware_diff",
   "Show project changes since last sync \u2014 see what drifted in your codebase",
-  { path: z.string().optional().describe("Project directory (defaults to cwd)") },
-  async ({ path }) => {
-    const result = await runCli("aware", ["diff"], path);
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)"),
+    exitCode: z.coerce.boolean().optional().describe("Return exit code 1 if changes detected (useful for CI)")
+  },
+  async ({ path, exitCode }) => {
+    const args = ["diff"];
+    if (exitCode) args.push("--exit-code");
+    const result = await runCli("aware", args, path);
     const output = formatOutput(result);
     return { content: [{ type: "text", text: output }] };
   }
@@ -579,6 +637,42 @@ server.tool(
     return { content: [{ type: "text", text: outputText }] };
   }
 );
+server.tool(
+  "vow_hook_install",
+  "Install a pre-commit git hook that checks dependency licenses before each commit",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "install"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+server.tool(
+  "vow_hook_uninstall",
+  "Remove the vow pre-commit license check hook",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "uninstall"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
+server.tool(
+  "vow_hook_status",
+  "Check if the vow pre-commit license check hook is installed",
+  {
+    path: z.string().optional().describe("Project directory (defaults to cwd)")
+  },
+  async ({ path }) => {
+    const result = await runCli("vow", ["hook", "status"], path);
+    const output = formatOutput(result);
+    return { content: [{ type: "text", text: output }] };
+  }
+);
 server.tool(
   "vow_attribution",
   "Generate THIRD_PARTY_LICENSES.md \u2014 list all dependencies with their licenses for compliance",

package/dist/{status-LOZGVOA3.js → status-QWAHXHNA.js}

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
+import {
+  formatStatusLine,
+  isStale,
+  readStatus
+} from "./chunk-4ZVSCJCJ.js";
 import {
   hasBlock
 } from "./chunk-NYUYV3UL.js";
@@ -36,6 +41,16 @@ async function status() {
     `  CLAUDE.md instructions:    ${claudeMdInstalled ? "\u2713 installed" : "\u2717 not installed"}`
   );
   console.log(`  CLAUDE.md path:            ${CLAUDE_MD_PATH}`);
+  const watchData = readStatus();
+  if (watchData) {
+    const line = formatStatusLine();
+    const stale = isStale();
+    const age = stale ? " (stale)" : "";
+    console.log(`
+  Watch results${age}:        ${line}`);
+    console.log(`  Last scan:               ${watchData.timestamp}`);
+    console.log(`  Summary:                 ${watchData.summary}`);
+  }
   const allGood = mcpRegistered && claudeMdInstalled;
   if (allGood) {
     console.log("\n  Everything is set up. Run `when --help` to see available tools.\n");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whenlabs/when",
-  "version": "0.8.1",
+  "version": "0.9.1",
   "description": "The WhenLabs developer toolkit — 6 tools, one install",
   "type": "module",
   "main": "dist/index.js",
@@ -29,12 +29,12 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@whenlabs/aware": "^0.1.2",
-    "@whenlabs/berth": "^0.1.0",
-    "@whenlabs/envalid": "^0.1.2",
-    "@whenlabs/stale": "^0.1.0",
-    "@whenlabs/velocity-mcp": "^0.1.2",
-    "@whenlabs/vow": "^0.1.3",
+    "@whenlabs/aware": "^0.1.3",
+    "@whenlabs/berth": "^0.1.3",
+    "@whenlabs/envalid": "^0.1.3",
+    "@whenlabs/stale": "^0.1.3",
+    "@whenlabs/velocity-mcp": "^0.1.3",
+    "@whenlabs/vow": "^0.1.4",
     "commander": "^12.0.0",
     "zod": "^4.3.6"
   },

package/dist/install-HPF26YW2.js

@@ -1,124 +0,0 @@
-#!/usr/bin/env node
-import {
-  ALL_EDITORS,
-  installForEditor,
-  registerMcpServer
-} from "./chunk-3PDLNC63.js";
-import {
-  injectBlock
-} from "./chunk-NYUYV3UL.js";
-
-// src/commands/install.ts
-import { join } from "path";
-import { homedir } from "os";
-import { existsSync, readFileSync, writeFileSync } from "fs";
-var CLAUDE_MD_PATH = join(homedir(), ".claude", "CLAUDE.md");
-var OLD_START_MARKER = "<!-- velocity-mcp:start -->";
-var OLD_END_MARKER = "<!-- velocity-mcp:end -->";
-var CLAUDE_MD_CONTENT = `# WhenLabs Toolkit
-
-## Task Timing (velocity-mcp)
-
-Velocity tools are part of the unified \`whenlabs\` MCP server. Follow these rules for EVERY session:
-
-1. **Before starting any discrete coding task**, call \`velocity_start_task\` with:
-   - Appropriate \`category\` (scaffold, implement, refactor, debug, test, config, docs, deploy)
-   - Relevant \`tags\` (e.g. typescript, react, sqlite, api)
-   - Clear \`description\` of what you're about to do
-   - \`estimated_files\` if you know how many files you'll touch
-   - \`project\` set to the current project name (auto-detected from git remote or directory name)
-
-2. **After completing each task**, call \`velocity_end_task\` with:
-   - The \`task_id\` from the start call
-   - \`status\`: completed, failed, or abandoned
-   - \`actual_files\`: how many files were actually modified
-   - \`notes\`: any useful context about what happened
-
-3. **When creating a multi-step plan**, call \`velocity_estimate\` to provide the user with a time estimate before starting work.
-
-4. **If the user asks about speed or performance**, call \`velocity_stats\` to show aggregate data.
-
-### Guidelines
-- Every discrete unit of work should be tracked \u2014 don't batch multiple unrelated changes into one task
-- If a task is abandoned or fails, still call \`velocity_end_task\` with the appropriate status
-- Use consistent tags across sessions so the similarity matching can find comparable historical tasks
-- Keep descriptions concise but specific enough to be useful for future matching
-
-## WhenLabs MCP Tools (ALWAYS prefer these over shell commands)
-
-All six tools (including velocity) are available through the unified \`whenlabs\` MCP server. **ALWAYS use these MCP tools instead of running shell commands like lsof, grep, or manual checks.** These tools are purpose-built and give better results:
-
-| When to use | Call this tool | NOT this |
-|-------------|---------------|----------|
-| Check ports or port conflicts | \`berth_status\` or \`berth_check\` | \`lsof\`, \`netstat\`, \`ss\` |
-| Scan dependency licenses | \`vow_scan\` or \`vow_check\` | manual \`npm ls\`, \`license-checker\` |
-| Check if docs are stale | \`stale_scan\` | manual file comparison |
-| Validate .env files | \`envalid_validate\` or \`envalid_detect\` | manual .env inspection |
-| Generate AI context files | \`aware_init\` or \`aware_doctor\` | manual CLAUDE.md creation |
-
-### Tool Reference
-- \`berth_status\` \u2014 Show all active ports, Docker ports, and configured ports
-- \`berth_check\` \u2014 Scan a project directory for port conflicts
-- \`stale_scan\` \u2014 Detect documentation drift in the codebase
-- \`envalid_validate\` \u2014 Validate .env files against their schema
-- \`envalid_detect\` \u2014 Find undocumented env vars in codebase
-- \`aware_init\` \u2014 Auto-detect stack and generate AI context files
-- \`aware_doctor\` \u2014 Diagnose project health and config issues
-- \`vow_scan\` \u2014 Scan and summarize all dependency licenses
-- \`vow_check\` \u2014 Validate licenses against a policy file
-
-### 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.
-- \`env:N\` \u2014 N .env issues found. Run \`envalid_validate\` and help the user fix them.
-- \`ports:N\` \u2014 N port conflicts. Run \`berth_status\` and suggest resolution.
-- \`lic:N?\` \u2014 N packages with unknown licenses. Run \`vow_scan\` for details.
-- \`aware:stale\` \u2014 AI context files are outdated. Run \`aware_init\` to regenerate.
-
-**When you see any of these in the status line, proactively tell the user and offer to fix the issue.** Do not wait for the user to ask.`;
-function escapeRegex(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-}
-function hasOldBlock(filePath) {
-  if (!existsSync(filePath)) return false;
-  const content = readFileSync(filePath, "utf-8");
-  return content.includes(OLD_START_MARKER) && content.includes(OLD_END_MARKER);
-}
-function removeOldBlock(filePath) {
-  if (!existsSync(filePath)) return;
-  let content = readFileSync(filePath, "utf-8");
-  const pattern = new RegExp(
-    `\\n?${escapeRegex(OLD_START_MARKER)}[\\s\\S]*?${escapeRegex(OLD_END_MARKER)}\\n?`,
-    "g"
-  );
-  content = content.replace(pattern, "\n").replace(/\n{3,}/g, "\n\n").trimEnd() + "\n";
-  writeFileSync(filePath, content, "utf-8");
-}
-async function install(options = {}) {
-  console.log("\n\u{1F527} WhenLabs toolkit installer\n");
-  const editorFlags = options.all ? ALL_EDITORS : [
-    options.cursor && "cursor",
-    options.vscode && "vscode",
-    options.windsurf && "windsurf"
-  ].filter(Boolean);
-  const claudeOnly = editorFlags.length === 0;
-  if (claudeOnly) {
-    const mcpResult = registerMcpServer();
-    console.log(mcpResult.success ? `  \u2713 ${mcpResult.message}` : `  \u2717 ${mcpResult.message}`);
-    injectBlock(CLAUDE_MD_PATH, CLAUDE_MD_CONTENT);
-    console.log(`  \u2713 CLAUDE.md instructions written to ${CLAUDE_MD_PATH}`);
-    if (hasOldBlock(CLAUDE_MD_PATH)) {
-      removeOldBlock(CLAUDE_MD_PATH);
-      console.log("  \u2713 Removed legacy velocity-mcp markers (migrated to whenlabs block)");
-    }
-  } else {
-    for (const editor of editorFlags) {
-      const result = installForEditor(editor);
-      console.log(result.success ? `  \u2713 ${result.message}` : `  \u2717 ${result.message}`);
-    }
-  }
-  console.log("\nInstallation complete. Run `when status` to verify.\n");
-}
-export {
-  install
-};