cue-ai 0.9.0 → 0.9.2

package/src/lib/skill-clis.test.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for CLI extraction from SKILL.md frontmatter, the data behind the
+ * studio's "CLIs" tab. Recipe enrichment runs against the real on-disk
+ * cli-recipes.json.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  extractClisFromContent,
+  cliInstallHint,
+  hasRecipe,
+  aggregateProfileClis,
+} from "./skill-clis";
+
+const SKILL = (allowed: string) =>
+  `---\nname: demo\nallowed-tools: ${allowed}\n---\n\n# demo\n\nBody mentions Bash(should-not-leak:*) outside frontmatter.\n`;
+
+describe("extractClisFromContent", () => {
+  test("pulls tool names out of Bash(...) frontmatter refs", () => {
+    const clis = extractClisFromContent(SKILL("Bash(cargo:*), Bash(gh:*), Bash(curl:*)"));
+    expect(clis).toEqual(["cargo", "gh", "curl"]);
+  });
+
+  test("drops shell builtins, coreutils, and Claude tool names", () => {
+    const clis = extractClisFromContent(SKILL("Bash(Bash:*), Bash(Read:*), Bash(-:*), Bash(ls:*), Bash(grep:*), Bash(cargo:*)"));
+    expect(clis).toEqual(["cargo"]);
+  });
+
+  test("takes the first token of a multi-word command", () => {
+    const clis = extractClisFromContent(SKILL("Bash(npx medusa db:generate:*)"));
+    expect(clis).toEqual(["npx"]);
+  });
+
+  test("dedupes repeated tools, preserves first-seen casing", () => {
+    const clis = extractClisFromContent(SKILL("Bash(Cargo:*), Bash(cargo:*)"));
+    expect(clis).toEqual(["Cargo"]);
+  });
+
+  test("ignores Bash(...) that appears only in the body", () => {
+    const noFront = "# demo\n\nrun Bash(docker:*) here\n";
+    expect(extractClisFromContent(noFront)).toEqual([]);
+  });
+
+  test("returns [] when there's no allowed-tools", () => {
+    expect(extractClisFromContent("---\nname: demo\n---\n\n# demo\n")).toEqual([]);
+  });
+});
+
+describe("extractClisFromContent — Prerequisites + body sources", () => {
+  test("picks up a recipe tool from a ## Prerequisites table, even without frontmatter", () => {
+    const md = "---\nname: demo\n---\n\n# demo\n\n## Prerequisites\n\n| Tool | Install |\n|---|---|\n| `nmap` | `apt install nmap` |\n\n## Steps\n";
+    expect(extractClisFromContent(md)).toContain("nmap");
+  });
+
+  test("ignores non-recipe backticked tokens in Prerequisites (precision)", () => {
+    const md = "---\nname: demo\n---\n\n## Prerequisites\n\n- `totally-made-up-tool` — install somehow\n";
+    expect(extractClisFromContent(md)).toEqual([]);
+  });
+
+  test("catches a recipe tool used in command position in the body", () => {
+    const md = "---\nname: demo\n---\n\n# demo\n\nRun the suite:\n\n```bash\n$ cargo nextest run\n```\n";
+    expect(extractClisFromContent(md)).toContain("cargo");
+  });
+
+  test("does NOT catch a recipe tool name used as prose (precision)", () => {
+    const md = "---\nname: demo\n---\n\n# demo\n\nWe use cargo culting sparingly and just move on.\n";
+    // "cargo" mid-sentence and "just" mid-sentence are prose, not commands.
+    expect(extractClisFromContent(md)).toEqual([]);
+  });
+
+  test("prefers the longest recipe key at a position (cargo-nextest over cargo)", () => {
+    const md = "---\nname: demo\n---\n\n```\n$ cargo-nextest run\n```\n";
+    const clis = extractClisFromContent(md);
+    expect(clis).toContain("cargo-nextest");
+    expect(clis).not.toContain("cargo");
+  });
+});
+
+describe("cli-recipes enrichment", () => {
+  test("known tools resolve an install hint", () => {
+    // nmap is a stable entry in cli-recipes.json (apt/brew/...).
+    expect(hasRecipe("nmap")).toBe(true);
+    expect(cliInstallHint("nmap")).toMatch(/nmap/);
+  });
+
+  test("unknown tools have no recipe and an empty hint", () => {
+    expect(hasRecipe("definitely-not-a-cli-xyz")).toBe(false);
+    expect(cliInstallHint("definitely-not-a-cli-xyz")).toBe("");
+  });
+});
+
+describe("aggregateProfileClis", () => {
+  test("unions across skills, ranks by usage, records usedBy", () => {
+    const skills = [
+      { id: "rust/a", body: SKILL("Bash(cargo:*), Bash(rustup:*)") },
+      { id: "rust/b", body: SKILL("Bash(cargo:*)") },
+      { id: "ops/c", body: SKILL("Bash(gh:*)") },
+    ];
+    const clis = aggregateProfileClis(skills);
+    // cargo (2 users) ranks first
+    expect(clis[0]!.name).toBe("cargo");
+    expect(clis[0]!.usedBy).toEqual(["rust/a", "rust/b"]);
+    expect(clis.map((c) => c.name).sort()).toEqual(["cargo", "gh", "rustup"]);
+  });
+
+  test("skips missing (unresolved) skills", () => {
+    const clis = aggregateProfileClis([
+      { id: "x", body: SKILL("Bash(cargo:*)"), missing: true },
+    ]);
+    expect(clis).toEqual([]);
+  });
+});

package/src/lib/skill-clis.ts

@@ -0,0 +1,232 @@
+/**
+ * Extract the external CLI tools a skill depends on, for the studio's "CLIs"
+ * tab. The high-fidelity signal is a SKILL.md's frontmatter `allowed-tools:`
+ * list — `Bash(<tool>:*)` entries name exactly what the skill shells out to.
+ * We parse those, drop shell builtins / coreutils / Claude's own tool names,
+ * and enrich each surviving tool with an install hint from
+ * `resources/cli-recipes.json` when one exists.
+ *
+ * Paths resolve per-call from env so tests can point CUE_REPO_ROOT at a
+ * fixture without touching the real recipes file.
+ */
+
+import { readFileSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+function repoRoot(): string {
+  return (
+    process.env.CUE_REPO_ROOT ??
+    process.env.SOUL_REPO_ROOT ??
+    resolve(dirname(fileURLToPath(import.meta.url)), "..", "..")
+  );
+}
+function recipesPath(): string {
+  return join(repoRoot(), "resources", "cli-recipes.json");
+}
+
+export interface ProfileCli {
+  /** Tool name as declared in `Bash(<name>…)`. */
+  name: string;
+  /** Best-effort install command from cli-recipes.json, or "" if no recipe. */
+  install: string;
+  /** True when cli-recipes.json has a recipe for this tool. */
+  known: boolean;
+  /** Skill ids (e.g. "rust/cargo-nextest") that declare this CLI. */
+  usedBy: string[];
+}
+
+// Not external CLIs: Claude's own tool names + shell builtins / coreutils that
+// every box already has. Dropping these keeps the tab to real dependencies.
+const NON_CLI = new Set([
+  "-", "bash", "read", "write", "edit", "multiedit", "notebookedit", "glob",
+  "grep", "task", "webfetch", "websearch", "todowrite", "ls", "cat", "head",
+  "tail", "find", "echo", "cd", "mkdir", "rmdir", "rm", "cp", "mv", "sed",
+  "awk", "sort", "uniq", "wc", "cut", "tr", "xargs", "test", "sleep", "env",
+  "export", "source", "pwd", "touch", "chmod", "chown", "dirname", "basename",
+  "true", "false", "set", "printf", "tee", "comm", "diff", "date", "seq",
+  "tput", "which", "type", "eval", "exit", "return", "local", "for", "while",
+  "if", "then", "fi", "do", "done", "case", "esac",
+]);
+
+/** Split a SKILL.md into its frontmatter block and body. */
+function splitFrontmatter(content: string): { front: string; body: string } {
+  const lines = content.split("\n");
+  if (lines[0] !== "---") return { front: "", body: content };
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === "---") return { front: lines.slice(1, i).join("\n"), body: lines.slice(i + 1).join("\n") };
+  }
+  return { front: "", body: content };
+}
+
+/** Source A — `Bash(<tool>…)` refs in the `allowed-tools:` frontmatter. */
+function clisFromFrontmatter(front: string, out: Map<string, string>): void {
+  const re = /Bash\(\s*([^):*\s]+)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(front)) !== null) {
+    const raw = m[1]!.trim();
+    const key = raw.toLowerCase();
+    if (!raw || NON_CLI.has(key)) continue;
+    if (!out.has(key)) out.set(key, raw);
+  }
+}
+
+/** Pull the `## Prerequisites` section body, or "" if the skill has none. */
+function prerequisitesSection(body: string): string {
+  const lines = body.split("\n");
+  const start = lines.findIndex((l) => /^#{1,6}\s+Prerequisites\b/i.test(l));
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^#{1,6}\s+/.test(lines[i]!)) { end = i; break; }
+  }
+  return lines.slice(start + 1, end).join("\n");
+}
+
+/** Source B — backticked tool names in `## Prerequisites`, recipe-bounded. */
+function clisFromPrerequisites(body: string, out: Map<string, string>): void {
+  const section = prerequisitesSection(body);
+  if (!section) return;
+  const re = /`([a-zA-Z][a-zA-Z0-9._-]*)`/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(section)) !== null) {
+    const raw = m[1]!.trim();
+    const key = raw.toLowerCase();
+    if (NON_CLI.has(key)) continue;
+    // Precision gate: only accept Prerequisites tokens that are real recipes.
+    if (!hasRecipe(raw)) continue;
+    if (!out.has(key)) out.set(key, raw);
+  }
+}
+
+let bodyScanCache: { root: string; re: RegExp | null } | null = null;
+/**
+ * A single command-position regex over all recipe keys, longest-first so
+ * `cargo-nextest` wins over `cargo`. "Command position" = start of line, or
+ * right after a backtick / `$` / pipe / `>` (optionally a `$ ` prompt). This
+ * keeps prose mentions ("use cargo wisely") out while catching real command
+ * usage ("`cargo nextest`", "$ nmap -sV").
+ */
+function bodyScanRegex(): RegExp | null {
+  const root = repoRoot();
+  if (bodyScanCache && bodyScanCache.root === root) return bodyScanCache.re;
+  const keys = Object.keys(loadRecipes()).sort((a, b) => b.length - a.length);
+  const re = keys.length
+    ? new RegExp(`(?:^|[\\n\`$|>])[ \\t]*(?:\\$[ \\t]*)?(${keys.map(escapeRe).join("|")})(?![\\w-])`, "gm")
+    : null;
+  bodyScanCache = { root, re };
+  return re;
+}
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Concatenate only the code spans of a markdown body — fenced blocks (``` or
+ * ~~~) and inline `code` — each on its own line. Restricting the body scan to
+ * code keeps English-ambiguous recipe keys (`just`, `cross`, `uv`) from
+ * matching prose: a tool in code is a command, a word in a sentence is not.
+ */
+function codeRegions(body: string): string {
+  const out: string[] = [];
+  const fence = /(?:```|~~~)[^\n]*\n([\s\S]*?)(?:```|~~~)/g;
+  let m: RegExpExecArray | null;
+  let stripped = body;
+  while ((m = fence.exec(body)) !== null) out.push(m[1]!);
+  // Remove fenced blocks before scanning inline code so their backticks don't
+  // confuse the inline matcher.
+  stripped = body.replace(fence, "\n");
+  const inline = /`([^`\n]+)`/g;
+  while ((m = inline.exec(stripped)) !== null) out.push(m[1]!);
+  return out.join("\n");
+}
+
+/** Source C — recipe-key tools used in command position inside code spans. */
+function clisFromBody(body: string, out: Map<string, string>): void {
+  const re = bodyScanRegex();
+  if (!re) return;
+  const code = codeRegions(body);
+  if (!code) return;
+  re.lastIndex = 0;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(code)) !== null) {
+    const raw = m[1]!;
+    const key = raw.toLowerCase();
+    if (NON_CLI.has(key)) continue;
+    if (!out.has(key)) out.set(key, raw);
+  }
+}
+
+/**
+ * CLI tools a skill depends on, merged from three sources, deduped (first-seen
+ * casing preserved), minus shell builtins / Claude tools:
+ *  A. frontmatter `allowed-tools: Bash(<tool>…)` — explicit, any tool.
+ *  B. `## Prerequisites` backticked tools — recipe-bounded for precision.
+ *  C. command-position mentions of cli-recipes.json tools in the body.
+ */
+export function extractClisFromContent(content: string): string[] {
+  const { front, body } = splitFrontmatter(content);
+  const out = new Map<string, string>();
+  clisFromFrontmatter(front, out);
+  clisFromPrerequisites(body, out);
+  clisFromBody(body, out);
+  return [...out.values()];
+}
+
+let recipesCache: { root: string; recipes: Record<string, Record<string, string>> } | null = null;
+function loadRecipes(): Record<string, Record<string, string>> {
+  const root = repoRoot();
+  if (recipesCache && recipesCache.root === root) return recipesCache.recipes;
+  let recipes: Record<string, Record<string, string>> = {};
+  try {
+    const raw = JSON.parse(readFileSync(recipesPath(), "utf8")) as Record<string, unknown>;
+    for (const [k, v] of Object.entries(raw)) {
+      if (k.startsWith("$")) continue; // skip $schema-comment
+      if (v && typeof v === "object") recipes[k] = v as Record<string, string>;
+    }
+  } catch {
+    recipes = {};
+  }
+  recipesCache = { root, recipes };
+  return recipes;
+}
+
+/** Best-effort one-line install command for a CLI, or "" when unknown. */
+export function cliInstallHint(name: string): string {
+  const r = loadRecipes()[name];
+  if (!r) return "";
+  if (r.apt) return `apt install ${r.apt}`;
+  if (r.brew) return `brew install ${r.brew}`;
+  if (r.pacman) return `pacman -S ${r.pacman}`;
+  if (r.dnf) return `dnf install ${r.dnf}`;
+  if (r.pipx) return `pipx install ${r.pipx}`;
+  if (r.pip) return `pip install ${r.pip}`;
+  if (r.npm) return `npm i -g ${r.npm}`;
+  if (r.script) return r.script;
+  if (r.manual) return r.manual;
+  return "";
+}
+
+/** True when cli-recipes.json has a recipe for this tool. */
+export function hasRecipe(name: string): boolean {
+  return Boolean(loadRecipes()[name]);
+}
+
+/**
+ * Aggregate the CLIs across a set of skills into a per-profile list, ranked by
+ * how many skills use each (then alphabetical). `skills` carries each skill's
+ * id + full SKILL.md body (already loaded by the caller).
+ */
+export function aggregateProfileClis(skills: { id: string; body: string; missing?: boolean }[]): ProfileCli[] {
+  const map = new Map<string, string[]>();
+  for (const s of skills) {
+    if (s.missing) continue;
+    for (const cli of extractClisFromContent(s.body)) {
+      if (!map.has(cli)) map.set(cli, []);
+      map.get(cli)!.push(s.id);
+    }
+  }
+  return [...map.entries()]
+    .map(([name, usedBy]) => ({ name, install: cliInstallHint(name), known: hasRecipe(name), usedBy }))
+    .sort((a, b) => b.usedBy.length - a.usedBy.length || a.name.localeCompare(b.name));
+}

package/src/lib/skill-dependencies.ts

@@ -36,13 +36,21 @@ function parseExplicitDeps(content: string): string[] {
 /**
  * Detect implicit MCP dependencies from mcp__<server>__<tool> references.
  */
+/**
+ * Pseudo-MCP names the *host* provides, not something cue installs. `conductor`
+ * is the host orchestrator that exposes tools like
+ * `mcp__conductor__AskUserQuestion`; skills reference it only as documentation,
+ * so it must never be reported as a missing dependency.
+ */
+const HOST_PROVIDED_MCPS = new Set(["conductor"]);
+
 function parseImplicitDeps(content: string): string[] {
   const refs = content.match(/mcp__([a-zA-Z][a-zA-Z0-9_-]*)__/g);
   if (!refs) return [];
   const servers = new Set<string>();
   for (const ref of refs) {
     const match = ref.match(/^mcp__([a-zA-Z][a-zA-Z0-9_-]*)__$/);
-    if (match) servers.add(match[1]!);
+    if (match && !HOST_PROVIDED_MCPS.has(match[1]!)) servers.add(match[1]!);
   }
   return [...servers];
 }

package/src/lib/skill-deps.ts

@@ -5,7 +5,7 @@
  * resolution and "why is this skill included?" explanations.
  */
 
-import { readFileSync, existsSync, readdirSync } from "node:fs";
+import { readFileSync, existsSync, } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 

package/src/lib/skill-linter.ts

@@ -11,7 +11,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { join, resolve, dirname } from "node:path";
+import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { parseCLIsFromContent, parseMetadataFromContent } from "../commands/optimizer";

package/src/lib/skill-quality.ts

@@ -6,7 +6,6 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { listProfiles, loadProfile } from "./profile-loader";
 
 const REPO_ROOT = process.env.CUE_REPO_ROOT ?? process.env.SOUL_REPO_ROOT ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 

package/src/lib/skill-sandbox.test.ts

@@ -1,7 +1,7 @@
 import { describe, test, expect, beforeAll, afterAll } from "bun:test";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
-import { parseAllowedTools, validateToolUsage, auditSkillPermissions, generateSandboxReport } from "./skill-sandbox";
+import { parseAllowedTools, validateToolUsage, generateSandboxReport } from "./skill-sandbox";
 
 const TEST_ROOT = join(import.meta.dir, "..", "..", "__test_sandbox__");
 

package/src/lib/skills-lock.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeEach, afterAll } from "bun:test";
-import { mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 

package/src/lib/telemetry-consent.ts

@@ -17,15 +17,13 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { configDir } from "./config-paths";
 
 const CONSENT_RECORD_VERSION = 1;
 
-export function configDir(): string {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  return join(xdg && xdg.length > 0 ? xdg : join(homedir(), ".config"), "cue");
-}
+// Re-exported for back-compat: external callers import `configDir` from here.
+export { configDir };
 
 export function consentPath(): string {
   return join(configDir(), ".telemetry-consent");

package/src/lib/telemetry-report.test.ts

@@ -1,9 +1,9 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { mkdtempSync, rmSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { analyticsPath, enable } from "./telemetry-consent";
+import { enable } from "./telemetry-consent";
 import { recordEvent } from "./analytics";
 import { compositeReport, missLeaderboard, topSkills, zombies } from "./telemetry-report";
 

package/src/lib/token-budget.ts

@@ -0,0 +1,111 @@
+/**
+ * Token-budget accounting for materialized profiles — pure, filesystem-free.
+ *
+ * Extracted from commands/launch.ts (which re-exports these for back-compat).
+ * The *formatting* of the budget (colors, the CLI banner block) stays in
+ * launch.ts; this module is just the measurement math, so it's unit-testable
+ * in isolation and reusable by other surfaces (status, doctor, dashboard).
+ */
+
+import type { ResolvedProfile } from "../../profiles/_types";
+
+export interface SkillTokens {
+  /** Tokens for the YAML frontmatter (always-on, loaded into skill router). */
+  frontmatter: number;
+  /** Tokens for the rest of SKILL.md (load-on-activate). */
+  body: number;
+}
+
+export interface TokenBreakdown {
+  /** Sum of frontmatter tokens across every skill — the real always-on cost. */
+  alwaysOn: number;
+  /** Sum of body tokens — the ceiling if every skill activates this session. */
+  maxIfAllActivate: number;
+  /** Skill count for the header line. */
+  totalSkills: number;
+  /**
+   * Per-profile attribution of `alwaysOn` for composite selectors (length > 1).
+   * Each skill is credited to the first part that declares it, so per-part
+   * numbers sum to `alwaysOn` (no double-counting from overlap). Empty for
+   * single-part profiles. `icon` carries the part's emoji when declared.
+   */
+  byProfile: { name: string; icon?: string; tokens: number; skillCount: number }[];
+  /** Skills sorted by body size, descending — for the "heaviest if activated" hint. */
+  heaviestBodies: { id: string; tokens: number }[];
+}
+
+export function computeTokenBreakdown(
+  profile: ResolvedProfile,
+  parts: ResolvedProfile[] | undefined,
+  tokensForSkill: (id: string) => SkillTokens,
+): TokenBreakdown {
+  let alwaysOn = 0;
+  let maxIfAllActivate = 0;
+  const heaviestBodies: { id: string; tokens: number }[] = [];
+  for (const s of profile.skills.local) {
+    const { frontmatter, body } = tokensForSkill(s.id);
+    alwaysOn += frontmatter;
+    maxIfAllActivate += body;
+    if (body > 0) heaviestBodies.push({ id: s.id, tokens: body });
+  }
+  heaviestBodies.sort((a, b) => b.tokens - a.tokens);
+
+  const byProfile: TokenBreakdown["byProfile"] = [];
+  if (parts && parts.length > 1) {
+    const credited = new Set<string>();
+    for (const part of parts) {
+      let pTokens = 0;
+      let pCount = 0;
+      for (const s of part.skills.local) {
+        if (credited.has(s.id)) continue;
+        credited.add(s.id);
+        const { frontmatter } = tokensForSkill(s.id);
+        if (frontmatter > 0) {
+          pTokens += frontmatter;
+          pCount += 1;
+        }
+      }
+      byProfile.push({ name: part.name, icon: part.icon, tokens: pTokens, skillCount: pCount });
+    }
+  }
+
+  return {
+    alwaysOn,
+    maxIfAllActivate,
+    totalSkills: profile.skills.local.length,
+    byProfile,
+    heaviestBodies,
+  };
+}
+
+/**
+ * Extract frontmatter byte length from a SKILL.md string. Returns
+ * `{ frontmatter, body }` byte counts. Falls back to a token count of zero
+ * when the file lacks the leading `---` block (still legal but rare).
+ */
+export function splitSkillBytes(source: string): { frontmatter: number; body: number } {
+  if (!source.startsWith("---\n") && !source.startsWith("---\r\n")) {
+    return { frontmatter: 0, body: source.length };
+  }
+  // Find the closing `---` on its own line. Search starts after the opener.
+  const closer = source.indexOf("\n---", 4);
+  if (closer === -1) {
+    return { frontmatter: source.length, body: 0 };
+  }
+  // Include the closing `---\n` in the frontmatter block.
+  const fmEnd = source.indexOf("\n", closer + 1);
+  const cut = fmEnd === -1 ? source.length : fmEnd + 1;
+  return { frontmatter: cut, body: source.length - cut };
+}
+
+/**
+ * Map an always-on token count to the bands we color in the CLI banner and
+ * the tmux pane-border badge. Single source of truth so the two displays
+ * never drift apart on threshold values.
+ */
+export function tokenLevelEmoji(alwaysOn: number): "🔴" | "🟠" | "🟡" | "🟢" {
+  return alwaysOn > 15000 ? "🔴"
+    : alwaysOn > 10000 ? "🟠"
+      : alwaysOn > 5000 ? "🟡"
+        : "🟢";
+}

package/src/lib/trigger-gaps.test.ts

@@ -103,6 +103,76 @@ describe("computeTriggerGaps", () => {
     expect(rows.map((r) => r.id)).toEqual(["b", "a", "c"]);
   });
 
+  test("word-boundary: single-word trigger does NOT match inside a larger word", () => {
+    const skills = [skill("meta/analyze", "analyze", ["analyze"])];
+    // "reanalyze" / "analyzer" must not count as the bare word "analyze".
+    const prompts = ["please reanalyze the data", "run the analyzer"];
+    expect(
+      computeTriggerGaps({ skills, userPrompts: prompts, hits: new Map() }),
+    ).toEqual([]);
+  });
+
+  test("word-boundary: 'help' does not match 'helpful' / 'helper'", () => {
+    const skills = [skill("meta/help", "help", ["help"])];
+    const prompts = ["that was helpful", "ask the helper agent"];
+    expect(
+      computeTriggerGaps({ skills, userPrompts: prompts, hits: new Map() }),
+    ).toEqual([]);
+  });
+
+  test("weak single-word trigger only counts when it dominates a short prompt", () => {
+    const skills = [skill("meta/help", "help", ["help"])];
+    const longPrompt =
+      "i need some help refactoring this enormous function that spans several files and modules";
+    expect(longPrompt.length).toBeGreaterThan(80);
+    // Long prompt that merely contains "help" → not an invocation.
+    expect(
+      computeTriggerGaps({ skills, userPrompts: [longPrompt], hits: new Map() }),
+    ).toEqual([]);
+    // Short, trigger-dominant prompt → genuine.
+    const rows = computeTriggerGaps({
+      skills, userPrompts: ["help"], hits: new Map(),
+    });
+    expect(rows[0]?.gap).toBe(1);
+  });
+
+  test("slash-command trigger matches at any prompt length", () => {
+    const skills = [skill("caveman/caveman", "caveman", ["/caveman"])];
+    const longPrompt =
+      "please switch to /caveman mode because this explanation has gotten far too verbose for me";
+    expect(longPrompt.length).toBeGreaterThan(80);
+    const rows = computeTriggerGaps({
+      skills, userPrompts: [longPrompt], hits: new Map(),
+    });
+    expect(rows[0]?.gap).toBe(1);
+  });
+
+  test("multi-word trigger matches at any length (word-boundary, not substring)", () => {
+    const skills = [skill("caveman/caveman-commit", "caveman-commit", ["commit message"])];
+    const longPrompt =
+      "after you finish the refactor, write a clear commit message that explains the reasoning behind it";
+    expect(longPrompt.length).toBeGreaterThan(80);
+    const rows = computeTriggerGaps({
+      skills, userPrompts: [longPrompt], hits: new Map(),
+    });
+    expect(rows[0]?.gap).toBe(1);
+  });
+
+  test("weakTriggerMaxPromptChars is configurable", () => {
+    const skills = [skill("meta/help", "help", ["help"])];
+    const prompt = "help me please"; // 14 chars
+    // Default (80) → counts.
+    expect(
+      computeTriggerGaps({ skills, userPrompts: [prompt], hits: new Map() })[0]?.gap,
+    ).toBe(1);
+    // Tightened to 4 → the 14-char prompt is now "too long" for a weak trigger.
+    expect(
+      computeTriggerGaps({
+        skills, userPrompts: [prompt], hits: new Map(), weakTriggerMaxPromptChars: 4,
+      }),
+    ).toEqual([]);
+  });
+
   test("limit caps the row count", () => {
     const skills = Array.from({ length: 5 }, (_, i) =>
       skill(`s${i}`, `s${i}`, [`trigger phrase ${i}`]),