@whenlabs/when 0.9.3 → 0.11.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/action.yml

@@ -1,17 +1,79 @@
 name: 'WhenLabs CI Check'
 description: 'Run documentation drift, env validation, and license checks'
+branding:
+  icon: 'check-circle'
+  color: 'orange'
 inputs:
   tools:
-    description: 'Comma-separated tools to run'
+    description: 'Comma-separated tools to run (stale, envalid, vow)'
     default: 'stale,envalid,vow'
+  checks:
+    description: 'Alias for tools — select which checks to run (stale, envalid, vow)'
+    default: ''
   fail_on:
     description: 'Fail on: error, warning, or none'
     default: 'error'
+  comment:
+    description: 'Post results as a PR comment when running on a pull request'
+    default: 'false'
 runs:
   using: 'composite'
   steps:
     - uses: actions/setup-node@v4
       with:
         node-version: '20'
-    - run: npx @whenlabs/when ci --ci
+
+    - name: Cache npm
+      uses: actions/cache@v4
+      with:
+        path: ~/.npm
+        key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+        restore-keys: |
+          ${{ runner.os }}-node-
+
+    - name: Run WhenLabs checks
+      id: whenlabs_check
+      run: |
+        SELECTED="${{ inputs.checks != '' && inputs.checks || inputs.tools }}"
+        WHENLABS_TOOLS="$SELECTED" npx @whenlabs/when ci --ci 2>&1 | tee /tmp/whenlabs-output.txt
+        echo "exit_code=${PIPESTATUS[0]}" >> "$GITHUB_OUTPUT"
+      shell: bash
+
+    - name: Post PR comment
+      if: ${{ inputs.comment == 'true' && github.event_name == 'pull_request' }}
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          const output = fs.readFileSync('/tmp/whenlabs-output.txt', 'utf8');
+          const exitCode = '${{ steps.whenlabs_check.outputs.exit_code }}';
+          const status = exitCode === '0' ? '✅ All checks passed' : '❌ Issues found';
+          const body = [
+            '## WhenLabs CI Check',
+            '',
+            status,
+            '',
+            '<details><summary>Full output</summary>',
+            '',
+            '```',
+            output.trim(),
+            '```',
+            '',
+            '</details>',
+          ].join('\n');
+          await github.rest.issues.createComment({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            issue_number: context.issue.number,
+            body,
+          });
+
+    - name: Fail if issues found
+      if: ${{ inputs.fail_on != 'none' }}
+      run: |
+        EXIT="${{ steps.whenlabs_check.outputs.exit_code }}"
+        if [ "$EXIT" != "0" ]; then
+          echo "WhenLabs checks found issues. Set fail_on: none to suppress this failure."
+          exit 1
+        fi
       shell: bash

package/dist/chunk-JI5NCJQ2.js

@@ -0,0 +1,496 @@
+#!/usr/bin/env node
+
+// src/mcp/velocity-dashboard.ts
+import { writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { execSync } from "child_process";
+import { TaskQueries, initDb } from "@whenlabs/velocity-mcp/lib";
+var DASH_DIR = join(homedir(), ".whenlabs");
+var DASH_PATH = join(DASH_DIR, "dashboard.html");
+function parseTags(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw ? raw.split(",").map((t) => t.trim()).filter(Boolean) : [];
+  }
+}
+function fmtDuration(seconds) {
+  if (seconds < 60) return `${Math.round(seconds)}s`;
+  if (seconds < 3600) return `${Math.round(seconds / 60)}m`;
+  const h = Math.floor(seconds / 3600);
+  const m = Math.round(seconds % 3600 / 60);
+  return m > 0 ? `${h}h ${m}m` : `${h}h`;
+}
+function buildCategoryStats(tasks) {
+  const map = /* @__PURE__ */ new Map();
+  for (const t of tasks) {
+    if (!t.duration_seconds) continue;
+    const existing = map.get(t.category) ?? { count: 0, total: 0 };
+    existing.count++;
+    existing.total += t.duration_seconds;
+    map.set(t.category, existing);
+  }
+  return Array.from(map.entries()).map(([category, { count, total }]) => ({
+    category,
+    count,
+    avgDuration: total / count,
+    totalDuration: total
+  })).sort((a, b) => b.count - a.count);
+}
+function buildTagCounts(tasks) {
+  const map = /* @__PURE__ */ new Map();
+  for (const t of tasks) {
+    for (const tag of parseTags(t.tags)) {
+      map.set(tag, (map.get(tag) ?? 0) + 1);
+    }
+  }
+  return Array.from(map.entries()).map(([tag, count]) => ({ tag, count })).sort((a, b) => b.count - a.count).slice(0, 15);
+}
+function svgBarChart(data, opts) {
+  const { width = 520, barHeight = 32, color = "#6366f1", valueFormatter = String } = opts;
+  if (data.length === 0) return '<p style="color:#888;font-size:13px">No data yet.</p>';
+  const maxVal = Math.max(...data.map((d) => d.value), 1);
+  const labelWidth = 120;
+  const valueWidth = 70;
+  const chartWidth = width - labelWidth - valueWidth - 16;
+  const height = data.length * (barHeight + 8) + 16;
+  const bars = data.map((d, i) => {
+    const barW = Math.max(2, d.value / maxVal * chartWidth);
+    const y = i * (barHeight + 8) + 8;
+    const sub = d.subtitle ? `<text x="${labelWidth + barW + 6}" y="${y + barHeight / 2 + 4}" font-size="10" fill="#999">${d.subtitle}</text>` : "";
+    return `
+    <text x="${labelWidth - 6}" y="${y + barHeight / 2 + 4}" text-anchor="end" font-size="12" fill="#ddd" font-family="system-ui,sans-serif">${d.label}</text>
+    <rect x="${labelWidth}" y="${y}" width="${barW}" height="${barHeight}" rx="4" fill="${color}" opacity="0.85"/>
+    <text x="${labelWidth + barW + 6}" y="${y + barHeight / 2 + 4}" font-size="12" fill="#e2e8f0" font-family="system-ui,sans-serif">${valueFormatter(d.value)}${sub ? "" : ""}</text>
+    ${sub}`;
+  }).join("");
+  return `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">${bars}</svg>`;
+}
+function generateHtml(tasks) {
+  const now = /* @__PURE__ */ new Date();
+  const sevenDaysAgo = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1e3);
+  const recentTasks = tasks.filter((t) => t.ended_at && new Date(t.ended_at) >= sevenDaysAgo).sort((a, b) => new Date(b.ended_at).getTime() - new Date(a.ended_at).getTime()).slice(0, 20);
+  const catStats = buildCategoryStats(tasks);
+  const tagCounts = buildTagCounts(tasks);
+  const totalTasks = tasks.length;
+  const totalSeconds = tasks.reduce((sum, t) => sum + (t.duration_seconds ?? 0), 0);
+  const avgSeconds = totalTasks > 0 ? totalSeconds / totalTasks : 0;
+  const completedCount = tasks.filter((t) => t.status === "completed").length;
+  const catChartData = catStats.map((c) => ({
+    label: c.category,
+    value: c.count,
+    subtitle: fmtDuration(c.avgDuration) + " avg"
+  }));
+  const durationChartData = catStats.filter((c) => c.avgDuration > 0).map((c) => ({
+    label: c.category,
+    value: Math.round(c.avgDuration),
+    subtitle: ""
+  }));
+  const tagChartData = tagCounts.map((t) => ({
+    label: t.tag,
+    value: t.count
+  }));
+  const catChart = svgBarChart(catChartData, {
+    color: "#6366f1",
+    valueFormatter: (v) => `${v} tasks`
+  });
+  const durationChart = svgBarChart(durationChartData, {
+    color: "#10b981",
+    valueFormatter: fmtDuration
+  });
+  const tagChart = svgBarChart(tagChartData, {
+    color: "#f59e0b",
+    valueFormatter: (v) => `${v}`
+  });
+  const recentRows = recentTasks.map((t) => {
+    const tags = parseTags(t.tags);
+    const dur = t.duration_seconds ? fmtDuration(t.duration_seconds) : "\u2014";
+    const statusColor = t.status === "completed" ? "#10b981" : t.status === "failed" ? "#ef4444" : "#94a3b8";
+    const tagBadges = tags.slice(0, 4).map((tag) => `<span class="tag">${tag}</span>`).join("");
+    return `
+      <tr>
+        <td><span class="cat-badge cat-${t.category}">${t.category}</span></td>
+        <td class="desc">${t.description}</td>
+        <td>${tagBadges}</td>
+        <td style="color:${statusColor};text-align:center">${t.status ?? "\u2014"}</td>
+        <td style="text-align:right;color:#94a3b8">${dur}</td>
+      </tr>`;
+  }).join("");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>Velocity Dashboard</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    font-family: system-ui, -apple-system, sans-serif;
+    background: #0f172a;
+    color: #e2e8f0;
+    min-height: 100vh;
+    padding: 24px;
+  }
+  .header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 28px;
+    border-bottom: 1px solid #1e293b;
+    padding-bottom: 16px;
+  }
+  .header h1 { font-size: 22px; font-weight: 700; color: #f1f5f9; }
+  .header .subtitle { font-size: 12px; color: #64748b; margin-top: 2px; }
+  .badge-when {
+    background: #6366f1;
+    color: #fff;
+    font-size: 11px;
+    font-weight: 600;
+    padding: 3px 10px;
+    border-radius: 999px;
+  }
+  .stats-grid {
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    gap: 14px;
+    margin-bottom: 28px;
+  }
+  @media (max-width: 700px) { .stats-grid { grid-template-columns: repeat(2, 1fr); } }
+  .stat-card {
+    background: #1e293b;
+    border: 1px solid #334155;
+    border-radius: 10px;
+    padding: 16px 20px;
+  }
+  .stat-card .label { font-size: 11px; color: #64748b; text-transform: uppercase; letter-spacing: .05em; }
+  .stat-card .value { font-size: 28px; font-weight: 700; color: #f1f5f9; margin: 4px 0 2px; }
+  .stat-card .sub { font-size: 11px; color: #64748b; }
+  .charts-grid {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 18px;
+    margin-bottom: 28px;
+  }
+  @media (max-width: 900px) { .charts-grid { grid-template-columns: 1fr; } }
+  .chart-card {
+    background: #1e293b;
+    border: 1px solid #334155;
+    border-radius: 10px;
+    padding: 18px 20px;
+  }
+  .chart-card.full { grid-column: 1 / -1; }
+  .chart-card h2 { font-size: 13px; font-weight: 600; color: #94a3b8; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 14px; }
+  .table-card {
+    background: #1e293b;
+    border: 1px solid #334155;
+    border-radius: 10px;
+    padding: 18px 20px;
+    overflow-x: auto;
+  }
+  .table-card h2 { font-size: 13px; font-weight: 600; color: #94a3b8; text-transform: uppercase; letter-spacing: .05em; margin-bottom: 14px; }
+  table { width: 100%; border-collapse: collapse; font-size: 13px; }
+  th { text-align: left; color: #64748b; font-weight: 500; font-size: 11px; text-transform: uppercase; padding: 6px 10px; border-bottom: 1px solid #334155; }
+  td { padding: 8px 10px; border-bottom: 1px solid #1e293b; vertical-align: middle; }
+  tr:last-child td { border-bottom: none; }
+  .desc { max-width: 340px; color: #cbd5e1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .tag {
+    display: inline-block;
+    background: #334155;
+    color: #94a3b8;
+    font-size: 10px;
+    padding: 1px 7px;
+    border-radius: 999px;
+    margin-right: 3px;
+  }
+  .cat-badge {
+    display: inline-block;
+    font-size: 10px;
+    font-weight: 600;
+    padding: 2px 8px;
+    border-radius: 999px;
+    text-transform: uppercase;
+    letter-spacing: .03em;
+  }
+  .cat-scaffold { background:#1e3a5f; color:#60a5fa; }
+  .cat-implement { background:#1a2e3b; color:#38bdf8; }
+  .cat-refactor  { background:#1e3b2e; color:#4ade80; }
+  .cat-debug     { background:#3b2020; color:#f87171; }
+  .cat-test      { background:#2d2b3b; color:#a78bfa; }
+  .cat-config    { background:#2d2a1a; color:#fbbf24; }
+  .cat-docs      { background:#1e2e3b; color:#7dd3fc; }
+  .cat-deploy    { background:#1e2e1e; color:#86efac; }
+  .generated-at { font-size: 11px; color: #475569; margin-top: 20px; text-align: right; }
+</style>
+</head>
+<body>
+<div class="header">
+  <div>
+    <h1>Velocity Dashboard</h1>
+    <div class="subtitle">Generated ${now.toLocaleString()}</div>
+  </div>
+  <span class="badge-when">@whenlabs/when</span>
+</div>
+
+<div class="stats-grid">
+  <div class="stat-card">
+    <div class="label">Total Tasks</div>
+    <div class="value">${totalTasks}</div>
+    <div class="sub">${completedCount} completed</div>
+  </div>
+  <div class="stat-card">
+    <div class="label">Total Time</div>
+    <div class="value">${fmtDuration(totalSeconds)}</div>
+    <div class="sub">across all tasks</div>
+  </div>
+  <div class="stat-card">
+    <div class="label">Avg Duration</div>
+    <div class="value">${fmtDuration(avgSeconds)}</div>
+    <div class="sub">per task</div>
+  </div>
+  <div class="stat-card">
+    <div class="label">Categories</div>
+    <div class="value">${catStats.length}</div>
+    <div class="sub">active categories</div>
+  </div>
+</div>
+
+<div class="charts-grid">
+  <div class="chart-card">
+    <h2>Tasks by Category</h2>
+    ${catChart}
+  </div>
+  <div class="chart-card">
+    <h2>Avg Duration by Category</h2>
+    ${durationChart}
+  </div>
+  <div class="chart-card full">
+    <h2>Top Tags</h2>
+    ${tagChart}
+  </div>
+</div>
+
+<div class="table-card">
+  <h2>Recent Tasks (last 7 days)</h2>
+  ${recentRows ? `<table>
+    <thead><tr>
+      <th>Category</th><th>Description</th><th>Tags</th><th style="text-align:center">Status</th><th style="text-align:right">Duration</th>
+    </tr></thead>
+    <tbody>${recentRows}</tbody>
+  </table>` : '<p style="color:#888;font-size:13px">No tasks in the last 7 days.</p>'}
+</div>
+
+<div class="generated-at">Generated by <code>when velocity dashboard</code></div>
+</body>
+</html>`;
+}
+async function generateDashboard() {
+  const db = initDb();
+  const queries = new TaskQueries(db);
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const yearAgo = new Date(Date.now() - 365 * 24 * 60 * 60 * 1e3).toISOString();
+  const tasks = queries.getCompletedInRange(yearAgo, now);
+  db.close();
+  const html = generateHtml(tasks);
+  mkdirSync(DASH_DIR, { recursive: true });
+  writeFileSync(DASH_PATH, html, "utf8");
+  const catStats = buildCategoryStats(tasks);
+  const totalSeconds = tasks.reduce((sum, t) => sum + (t.duration_seconds ?? 0), 0);
+  const topCats = catStats.slice(0, 3).map((c) => `${c.category}(${c.count})`).join(", ");
+  const summary = [
+    `Total tasks: ${tasks.length}`,
+    `Total time: ${fmtDuration(totalSeconds)}`,
+    `Top categories: ${topCats || "none yet"}`,
+    `Dashboard written to: ${DASH_PATH}`
+  ].join("\n");
+  return { path: DASH_PATH, summary };
+}
+function openFile(filePath) {
+  const platform = process.platform;
+  try {
+    if (platform === "darwin") {
+      execSync(`open "${filePath}"`, { stdio: "ignore" });
+    } else if (platform === "linux") {
+      execSync(`xdg-open "${filePath}"`, { stdio: "ignore" });
+    }
+  } catch {
+  }
+}
+function registerVelocityDashboard(server) {
+  server.tool(
+    "velocity_dashboard",
+    "Generate an HTML dashboard with charts showing task timing stats \u2014 opens in browser",
+    {},
+    async () => {
+      const { path, summary } = await generateDashboard();
+      openFile(path);
+      const text = `Dashboard generated and opened in browser.
+
+${summary}`;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// 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;
+  }
+}
+
+// src/mcp/run-cli.ts
+import { spawn } from "child_process";
+import { join as join2 } from "path";
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync2, readdirSync } from "fs";
+import { homedir as homedir2 } from "os";
+function runCli(bin, args, cwd) {
+  return new Promise((res) => {
+    const child = spawn(findBin(bin), args, {
+      cwd: cwd || process.cwd(),
+      env: { ...process.env, FORCE_COLOR: "0", NO_COLOR: "1" }
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => stdout += d);
+    child.stderr.on("data", (d) => stderr += d);
+    child.on("error", (err) => res({ stdout, stderr: err.message, code: 1 }));
+    child.on("close", (code) => res({ stdout, stderr, code: code ?? 0 }));
+  });
+}
+var CACHE_DIR = join2(homedir2(), ".whenlabs", "cache");
+function writeCache(tool, project, output, code) {
+  try {
+    mkdirSync2(CACHE_DIR, { recursive: true });
+    const file = join2(CACHE_DIR, `${tool}_${project}.json`);
+    writeFileSync2(file, JSON.stringify({ timestamp: Date.now(), output, code }));
+  } catch {
+  }
+}
+function deriveProject(path) {
+  const dir = path || process.cwd();
+  return dir.replace(/\\/g, "/").split("/").filter(Boolean).pop() || "unknown";
+}
+function readAwareProjectName(path) {
+  try {
+    const awareFile = join2(path || process.cwd(), ".aware.json");
+    if (!existsSync3(awareFile)) return null;
+    const data = JSON.parse(readFileSync2(awareFile, "utf8"));
+    return data.name || data.project || null;
+  } catch {
+    return null;
+  }
+}
+function formatOutput(result) {
+  const parts = [];
+  if (result.stdout.trim()) parts.push(result.stdout.trim());
+  if (result.stderr.trim()) parts.push(result.stderr.trim());
+  return parts.join("\n") || "No output";
+}
+async function checkTriggers(toolName, result, path) {
+  const output = result.stdout || result.stderr || "";
+  const extras = [];
+  if (toolName === "aware_init") {
+    const madeChanges = /wrote|created|updated|generated/i.test(output);
+    if (madeChanges) {
+      const staleResult = await runCli("stale", ["scan"], path);
+      const staleOutput = staleResult.stdout || staleResult.stderr || "";
+      writeCache("stale", deriveProject(path), staleOutput, staleResult.code);
+      if (staleOutput.trim()) {
+        extras.push(`
+--- Auto-triggered stale_scan (stack change detected) ---
+${staleOutput}`);
+      }
+    }
+  }
+  if (toolName === "vow_scan") {
+    const hasUnknown = /unknown|UNKNOWN|unlicensed/i.test(output);
+    if (hasUnknown) {
+      extras.push("\nNote: Unknown licenses detected \u2014 check README for license accuracy claims.");
+    }
+  }
+  if (toolName === "berth_check") {
+    const hasConflicts = /conflict|in use|occupied|taken/i.test(output);
+    if (hasConflicts) {
+      const projectName = readAwareProjectName(path);
+      if (projectName) {
+        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(readFileSync2(join2(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 = join2(CACHE_DIR, `vow_scan_${deriveProject(path)}.json`);
+    const isFirstScan = !existsSync3(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;
+}
+
+export {
+  findBin,
+  CONFIG_FILENAME,
+  loadConfig,
+  runCli,
+  CACHE_DIR,
+  writeCache,
+  deriveProject,
+  formatOutput,
+  checkTriggers,
+  generateDashboard,
+  registerVelocityDashboard
+};