@skillrecordings/cli 0.11.2 → 0.12.0

package/dist/index.js

@@ -19837,8 +19837,8 @@ var require_snapshot_recorder = __commonJS({
   "../../node_modules/.bun/undici@7.20.0/node_modules/undici/lib/mock/snapshot-recorder.js"(exports, module) {
     "use strict";
     init_esm_shims();
-    var { writeFile: writeFile7, readFile: readFile10, mkdir: mkdir2 } = __require("fs/promises");
-    var { dirname: dirname4, resolve: resolve7 } = __require("path");
+    var { writeFile: writeFile9, readFile: readFile10, mkdir: mkdir2 } = __require("fs/promises");
+    var { dirname: dirname6, resolve: resolve7 } = __require("path");
     var { setTimeout: setTimeout2, clearTimeout: clearTimeout2 } = __require("timers");
     var { InvalidArgumentError, UndiciError } = require_errors();
     var { hashId, isUrlExcludedFactory, normalizeHeaders, createHeaderFilters } = require_snapshot_utils();
@@ -20069,12 +20069,12 @@ var require_snapshot_recorder = __commonJS({
           throw new InvalidArgumentError("Snapshot path is required");
         }
         const resolvedPath = resolve7(path);
-        await mkdir2(dirname4(resolvedPath), { recursive: true });
+        await mkdir2(dirname6(resolvedPath), { recursive: true });
         const data2 = Array.from(this.#snapshots.entries()).map(([hash, snapshot]) => ({
           hash,
           snapshot
         }));
-        await writeFile7(resolvedPath, JSON.stringify(data2, null, 2), { flush: true });
+        await writeFile9(resolvedPath, JSON.stringify(data2, null, 2), { flush: true });
       }
       /**
        * Clears all recorded snapshots
@@ -74544,6 +74544,63 @@ import { Command as Command4 } from "commander";
 // src/commands/auth/index.ts
 init_esm_shims();
 
+// src/core/adaptive-help.ts
+init_esm_shims();
+var ABBREVIATED_THRESHOLD = 2;
+var MINIMAL_THRESHOLD = 5;
+var ROOT_DESCRIPTIONS = {
+  full: "Skill Recordings support agent CLI \u2014 triage, investigate, and manage customer conversations.\n\n  Getting Started:\n    1. skill auth setup        Configure 1Password secrets (Front API token, DB, etc.)\n    2. skill auth status        Verify your credentials are working\n    3. skill front inbox        See what needs attention right now\n\n  Common Workflows:\n    Triage inbox          skill front inbox \u2192 skill front triage\n    Investigate ticket    skill front conversation <id> --messages\n    Bulk cleanup          skill front bulk-archive --older-than 30d\n    Generate report       skill front report --inbox support\n    Check deploys         skill deploys\n\n  For AI Agents (Claude Code, MCP):\n    skill mcp              Start JSON-RPC server with 9 Front tools\n    skill plugin sync      Install the Claude Code plugin\n    All commands support --json for structured, HATEOAS-enriched output",
+  abbreviated: "Skill Recordings support agent CLI \u2014 triage and investigate support conversations.\n\n  Start here:\n    skill auth setup        Configure 1Password + secrets\n    skill front inbox       See what needs attention\n    skill front triage      Auto-categorize conversations\n\n  Common:\n    skill front conversation <id> --messages\n    skill front reply <id>\n    skill deploys\n    skill mcp\n",
+  minimal: "Skill Recordings support agent CLI. Try: skill front inbox, skill front triage, skill auth status. Use --help for details."
+};
+var FRONT_DESCRIPTIONS = {
+  full: "Front conversations, inboxes, tags, archival, and reporting.\n\n  Prerequisites:\n    FRONT_API_TOKEN must be set. Run: skill auth setup\n\n  Start here:\n    skill front inbox                    See unassigned conversations\n    skill front inbox support             List conversations in a specific inbox\n    skill front triage                    AI-powered categorization of inbox items\n\n  Investigate a conversation:\n    skill front conversation <id> -m      Full conversation with messages\n    skill front message <id>              Single message details + body\n\n  Take action:\n    skill front assign <id>               Assign to a teammate\n    skill front reply <id>                Draft a reply (HITL, never auto-sends)\n    skill front tag <id>                  Add a tag\n    skill front archive <id>              Archive a resolved conversation\n\n  Bulk operations:\n    skill front bulk-archive              Archive old/spam conversations\n    skill front report                    Volume + tag + sender forensics\n\n  All commands accept --json for HATEOAS-enriched output with _links and _actions.",
+  abbreviated: "Front API workflows for inbox triage and conversation actions.\n\n  Common:\n    skill front inbox\n    skill front triage\n    skill front conversation <id> -m\n    skill front reply <id>\n    skill front archive <id>\n\n  Requires FRONT_API_TOKEN (skill auth setup).",
+  minimal: "Front API commands (inbox, triage, assign, reply, archive). Requires FRONT_API_TOKEN."
+};
+var AUTH_DESCRIPTIONS = {
+  full: "Manage CLI authentication and secrets.\n\n  First time? Start here:\n    skill auth setup          Interactive wizard \u2014 connects to 1Password vault,\n                              configures FRONT_API_TOKEN, DATABASE_URL, and more.\n                              Requires: `op` CLI installed (brew install 1password-cli)\n\n  Check your setup:\n    skill auth status          Shows which secrets are configured and which are missing\n    skill auth whoami          Verify your 1Password service account identity\n\n  All Skill Recordings employees have access to the Support vault in 1Password.\n  The setup wizard handles everything \u2014 no manual token pasting needed.",
+  abbreviated: "Manage CLI authentication and 1Password secrets.\n\n  Start:\n    skill auth setup\n    skill auth status\n    skill auth whoami\n\n  Requires the 1Password CLI (`op`).",
+  minimal: "Auth and 1Password setup commands."
+};
+var INNGEST_DESCRIPTIONS = {
+  full: "Inngest event and workflow commands.\n\n  Debug pipeline runs:\n    skill inngest runs --status failed --after 1h    Recent failures\n    skill inngest events --after 12h                 Recent events\n    skill inngest investigate <run-id>                Deep-dive a specific run\n\n  Requires: INNGEST_SIGNING_KEY, INNGEST_EVENT_KEY in env",
+  abbreviated: "Inngest events and workflow runs.\n\n  Common:\n    skill inngest runs --status failed --after 1h\n    skill inngest events --after 12h\n    skill inngest investigate <run-id>\n\n  Requires INNGEST_SIGNING_KEY, INNGEST_EVENT_KEY.",
+  minimal: "Inngest events and runs debugging. Requires INNGEST_SIGNING_KEY and INNGEST_EVENT_KEY."
+};
+var GROUP_DESCRIPTIONS = {
+  root: ROOT_DESCRIPTIONS,
+  front: FRONT_DESCRIPTIONS,
+  auth: AUTH_DESCRIPTIONS,
+  inngest: INNGEST_DESCRIPTIONS
+};
+var getGroupCommandCount = (state, group) => {
+  if (group === "root") return state.totalRuns;
+  const prefix = `${group}.`;
+  let total = 0;
+  for (const [name, entry] of Object.entries(state.commands)) {
+    if (name === group || name.startsWith(prefix)) {
+      total += entry.count;
+    }
+  }
+  return total;
+};
+var resolveProficiencyLevel = (state, group) => {
+  if (!state) return "full";
+  const count = getGroupCommandCount(state, group);
+  if (count >= MINIMAL_THRESHOLD) return "minimal";
+  if (count >= ABBREVIATED_THRESHOLD) return "abbreviated";
+  return "full";
+};
+var getAdaptiveDescription = (group, state) => {
+  const level = resolveProficiencyLevel(state, group);
+  return GROUP_DESCRIPTIONS[group][level];
+};
+var getRootAdaptiveDescription = (state) => getAdaptiveDescription("root", state);
+var getFrontAdaptiveDescription = (state) => getAdaptiveDescription("front", state);
+var getAuthAdaptiveDescription = (state) => getAdaptiveDescription("auth", state);
+var getInngestAdaptiveDescription = (state) => getAdaptiveDescription("inngest", state);
+
 // src/core/context.ts
 init_esm_shims();
 
@@ -75582,8 +75639,8 @@ var buildContext = async (command, json) => {
     quiet: opts.quiet
   });
 };
-function registerAuthCommands(program3) {
-  const auth = program3.command("auth").description("Manage CLI auth status");
+function registerAuthCommands(program3, usageState2) {
+  const auth = program3.command("auth").description(getAuthAdaptiveDescription(usageState2));
   auth.command("status").description("Show active auth provider and secret availability").option("--json", "Output as JSON").action(async (options, command) => {
     const ctx = await buildContext(command, options.json);
     await statusAction(ctx, options);
@@ -96087,8 +96144,8 @@ async function getTeammate(ctx, id, options) {
     process.exitCode = cliError.exitCode;
   }
 }
-function registerFrontCommands(program3) {
-  const front = program3.command("front").description("Front conversations, inboxes, tags, archival, and reporting");
+function registerFrontCommands(program3, usageState2) {
+  const front = program3.command("front").description(getFrontAdaptiveDescription(usageState2));
   front.command("message").description("Get a message by ID (body, author, recipients, attachments)").argument("<id>", "Message ID (e.g., msg_xxx)").option("--json", "Output as JSON").action(
     async (id, options, command) => {
       const opts = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {
@@ -97377,8 +97434,8 @@ function registerSignalCommand(inngest) {
 }
 
 // src/commands/inngest/index.ts
-function registerInngestCommands(program3) {
-  const inngest = program3.command("inngest").description("Inngest API commands");
+function registerInngestCommands(program3, usageState2) {
+  const inngest = program3.command("inngest").description(getInngestAdaptiveDescription(usageState2));
   registerEventsCommands(inngest);
   registerRunsCommands(inngest);
   registerSignalCommand(inngest);
@@ -115844,6 +115901,529 @@ async function wizard(ctx, options = {}) {
   }
 }
 
+// src/core/auto-update.ts
+init_esm_shims();
+import { spawn } from "child_process";
+import { writeFile as writeFile7 } from "fs/promises";
+import { homedir as homedir2 } from "os";
+import { dirname as dirname4, join as join12 } from "path";
+var CONFIG_DIR_NAME = "skill-cli";
+var AUTO_UPDATE_STATE_FILE = "auto-update.json";
+var DEFAULT_PACKAGE = "@skillrecordings/cli";
+var REGISTRY_BASE = "https://registry.npmjs.org/";
+var CHECK_THROTTLE_MS = 60 * 60 * 1e3;
+var UPDATE_THROTTLE_MS = 24 * 60 * 60 * 1e3;
+var AutoUpdateStore = class {
+  filePath;
+  now;
+  constructor(options = {}) {
+    const configDir = resolveConfigDir(options.configDir);
+    this.filePath = join12(configDir, AUTO_UPDATE_STATE_FILE);
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  getNow() {
+    return this.now();
+  }
+  async load() {
+    try {
+      if (await pathExists(this.filePath)) {
+        const data2 = await readJson(this.filePath);
+        if (isAutoUpdateState(data2)) return data2;
+      }
+    } catch {
+    }
+    return {};
+  }
+  async save(state) {
+    try {
+      await ensureDir(dirname4(this.filePath));
+      await writeFile7(this.filePath, JSON.stringify(state, null, 2), "utf-8");
+    } catch {
+    }
+  }
+};
+function resolveConfigDir(configDir) {
+  if (configDir) return configDir;
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome && xdgConfigHome.trim() !== "") {
+    return join12(xdgConfigHome, CONFIG_DIR_NAME);
+  }
+  return join12(homedir2(), ".config", CONFIG_DIR_NAME);
+}
+function isAutoUpdateState(value) {
+  if (!value || typeof value !== "object") return false;
+  const state = value;
+  if (state.lastCheckAt !== void 0 && typeof state.lastCheckAt !== "string") {
+    return false;
+  }
+  if (state.lastUpdateAt !== void 0 && typeof state.lastUpdateAt !== "string") {
+    return false;
+  }
+  if (state.lastKnownVersion !== void 0 && typeof state.lastKnownVersion !== "string") {
+    return false;
+  }
+  return true;
+}
+function isAutoUpdateDisabled() {
+  return process.env.SKILL_NO_AUTO_UPDATE === "1";
+}
+function isWithinWindow(timestamp, now, windowMs) {
+  if (!timestamp) return false;
+  const parsed = Date.parse(timestamp);
+  if (Number.isNaN(parsed)) return false;
+  return now.getTime() - parsed < windowMs;
+}
+function normalizePackageName(name) {
+  if (name.startsWith("@")) {
+    return name.replace("/", "%2F");
+  }
+  return name;
+}
+function parseSemver(version) {
+  const trimmed = version.trim().replace(/^v/, "");
+  if (!trimmed) return null;
+  const [core, prerelease] = trimmed.split("-", 2);
+  if (!core) return null;
+  const parts = core.split(".");
+  if (parts.length < 3) return null;
+  const major = Number.parseInt(parts[0] ?? "", 10);
+  const minor = Number.parseInt(parts[1] ?? "", 10);
+  const patch = Number.parseInt(parts[2] ?? "", 10);
+  if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch)) {
+    return null;
+  }
+  return { major, minor, patch, prerelease };
+}
+function compareSemver(a, b) {
+  const parsedA = parseSemver(a);
+  const parsedB = parseSemver(b);
+  if (!parsedA || !parsedB) return 0;
+  if (parsedA.major !== parsedB.major) {
+    return parsedA.major > parsedB.major ? 1 : -1;
+  }
+  if (parsedA.minor !== parsedB.minor) {
+    return parsedA.minor > parsedB.minor ? 1 : -1;
+  }
+  if (parsedA.patch !== parsedB.patch) {
+    return parsedA.patch > parsedB.patch ? 1 : -1;
+  }
+  if (parsedA.prerelease && !parsedB.prerelease) return -1;
+  if (!parsedA.prerelease && parsedB.prerelease) return 1;
+  if (parsedA.prerelease && parsedB.prerelease) {
+    if (parsedA.prerelease === parsedB.prerelease) return 0;
+    return parsedA.prerelease > parsedB.prerelease ? 1 : -1;
+  }
+  return 0;
+}
+function resolvePackageManager(userAgent) {
+  const ua = userAgent ?? process.env.npm_config_user_agent ?? "";
+  if (ua.startsWith("bun")) return "bun";
+  if (ua.includes("bun")) return "bun";
+  if (ua.startsWith("npm")) return "npm";
+  return "npm";
+}
+async function checkForUpdate(options) {
+  const packageName = options.packageName ?? DEFAULT_PACKAGE;
+  const fetchFn = options.fetchFn ?? fetch;
+  const store2 = new AutoUpdateStore({
+    configDir: options.configDir,
+    now: options.now
+  });
+  const now = store2.getNow();
+  const state = await store2.load();
+  if (isWithinWindow(state.lastCheckAt, now, CHECK_THROTTLE_MS)) {
+    const latest = state.lastKnownVersion;
+    const updateAvailable2 = latest ? compareSemver(latest, options.currentVersion) > 0 : false;
+    return { updateAvailable: updateAvailable2, latestVersion: latest, checked: false };
+  }
+  let latestVersion;
+  try {
+    const registryUrl = `${REGISTRY_BASE}${normalizePackageName(packageName)}`;
+    const response = await fetchFn(registryUrl, {
+      headers: { Accept: "application/json" }
+    });
+    if (response.ok) {
+      const data2 = await response.json();
+      latestVersion = data2["dist-tags"]?.latest;
+    }
+  } catch {
+  }
+  state.lastCheckAt = now.toISOString();
+  if (latestVersion) {
+    state.lastKnownVersion = latestVersion;
+  }
+  await store2.save(state);
+  const updateAvailable = latestVersion !== void 0 && compareSemver(latestVersion, options.currentVersion) > 0;
+  return { updateAvailable, latestVersion, checked: true };
+}
+async function performUpdate(options = {}) {
+  const packageName = options.packageName ?? DEFAULT_PACKAGE;
+  const store2 = new AutoUpdateStore({
+    configDir: options.configDir,
+    now: options.now
+  });
+  const now = store2.getNow();
+  const packageManager = resolvePackageManager(options.userAgent);
+  const spawnFn = options.spawnFn ?? spawn;
+  const [command, args] = packageManager === "bun" ? ["bun", ["add", "-g", packageName]] : ["npm", ["install", "-g", packageName]];
+  const exitCode = await new Promise((resolve7) => {
+    try {
+      const child = spawnFn(command, args, {
+        stdio: "ignore",
+        env: process.env
+      });
+      child.on("error", () => resolve7(1));
+      child.on("close", (code) => resolve7(code ?? 1));
+    } catch {
+      resolve7(1);
+    }
+  });
+  if (exitCode === 0) {
+    const state = await store2.load();
+    state.lastUpdateAt = now.toISOString();
+    await store2.save(state);
+    return true;
+  }
+  return false;
+}
+async function autoUpdateAfterCommand(options) {
+  if (isAutoUpdateDisabled()) return;
+  if (options.isDevMode) return;
+  if (options.commandName === "mcp") return;
+  if (options.format === "json") return;
+  const store2 = new AutoUpdateStore({
+    configDir: options.configDir,
+    now: options.now
+  });
+  const now = store2.getNow();
+  const state = await store2.load();
+  if (isWithinWindow(state.lastUpdateAt, now, UPDATE_THROTTLE_MS)) return;
+  const check = await (options.checkForUpdateFn ?? checkForUpdate)({
+    currentVersion: options.currentVersion,
+    packageName: options.packageName,
+    configDir: options.configDir,
+    now: options.now
+  });
+  if (!check.updateAvailable) return;
+  state.lastUpdateAt = now.toISOString();
+  await store2.save(state);
+  const updated = await (options.performUpdateFn ?? performUpdate)({
+    packageName: options.packageName,
+    configDir: options.configDir,
+    now: options.now
+  });
+  if (updated) return;
+}
+
+// src/core/hint-engine.ts
+init_esm_shims();
+var DEFAULT_MAX_HINTS = 2;
+var getCommandCount = (state, command) => state.commands[command]?.count ?? 0;
+var hasCommand = (state, command) => getCommandCount(state, command) > 0;
+var hasCommandPrefix = (state, prefix) => Object.entries(state.commands).some(
+  ([name, entry]) => name.startsWith(prefix) && entry.count > 0
+);
+var hasMilestone = (state, milestone) => state.milestones[milestone]?.achieved ?? false;
+var shouldSuppressHints = (context) => context.quiet === true || context.format === "json";
+var resolveMaxHints = (context) => context.maxHints ?? DEFAULT_MAX_HINTS;
+var toHint = (rule) => ({
+  id: rule.id,
+  message: rule.message,
+  audience: rule.audience
+});
+var DEFAULT_HINT_RULES = [
+  {
+    id: "onboarding.wizard",
+    audience: "onboarding",
+    message: "New here? Run `skill wizard` to set up your first product.",
+    showWhen: (state) => state.totalRuns <= 2 && !hasCommand(state, "wizard"),
+    retireWhen: (state) => hasCommand(state, "wizard") || hasMilestone(state, "wizard_completed")
+  },
+  {
+    id: "onboarding.auth",
+    audience: "onboarding",
+    message: "Configure credentials with `skill init` to unlock the full CLI.",
+    showWhen: (state) => state.totalRuns >= 1 && !hasMilestone(state, "auth_configured"),
+    retireWhen: (state) => hasMilestone(state, "auth_configured")
+  },
+  {
+    id: "discovery.health",
+    audience: "discovery",
+    message: "Check integrations fast with `skill health <app-slug>`.",
+    showWhen: (state) => state.totalRuns >= 2 && !hasCommand(state, "health"),
+    retireWhen: (state) => hasCommand(state, "health")
+  },
+  {
+    id: "discovery.front.inbox",
+    audience: "discovery",
+    message: "List recent conversations via `skill front inbox <name-or-id>`.",
+    showWhen: (state) => state.totalRuns >= 1 && !hasCommand(state, "front.inbox"),
+    retireWhen: (state) => hasCommand(state, "front.inbox")
+  },
+  {
+    id: "discovery.inngest",
+    audience: "discovery",
+    message: "Inspect workflows with `skill inngest stats --after 1d`.",
+    showWhen: (state) => state.totalRuns >= 3 && !hasCommandPrefix(state, "inngest."),
+    retireWhen: (state) => hasCommandPrefix(state, "inngest.")
+  },
+  {
+    id: "discovery.axiom",
+    audience: "discovery",
+    message: 'Query logs quickly with `skill axiom query "<APL>" --since 24h`.',
+    showWhen: (state) => state.totalRuns >= 3 && !hasCommandPrefix(state, "axiom."),
+    retireWhen: (state) => hasCommandPrefix(state, "axiom.")
+  },
+  {
+    id: "context.front.triage",
+    audience: "contextual",
+    postRun: true,
+    message: "Tip: `skill front triage <inbox-id>` surfaces unassigned threads.",
+    showWhen: (state, context) => context.command === "front.inbox" && !hasCommand(state, "front.triage"),
+    retireWhen: (state) => hasCommand(state, "front.triage")
+  },
+  {
+    id: "context.front.conversation",
+    audience: "contextual",
+    postRun: true,
+    message: "Tip: `skill front conversation <id> -m` shows the full thread.",
+    showWhen: (state, context) => context.command === "front.message" && !hasCommand(state, "front.conversation"),
+    retireWhen: (state) => hasCommand(state, "front.conversation")
+  },
+  {
+    id: "context.inngest.run",
+    audience: "contextual",
+    postRun: true,
+    message: "Tip: drill in with `skill inngest run <id>` or `skill inngest trace <run-id>`.",
+    showWhen: (state, context) => context.command === "inngest.failures" && !hasCommand(state, "inngest.run") && !hasCommand(state, "inngest.trace"),
+    retireWhen: (state) => hasCommand(state, "inngest.run") || hasCommand(state, "inngest.trace")
+  }
+];
+var HintEngine = class {
+  rules;
+  constructor(rules = DEFAULT_HINT_RULES) {
+    this.rules = rules;
+  }
+  getHints(state, context) {
+    if (shouldSuppressHints(context)) return [];
+    const maxHints = resolveMaxHints(context);
+    if (maxHints <= 0) return [];
+    const hints = [];
+    for (const rule of this.rules) {
+      if (rule.postRun) continue;
+      if (!rule.showWhen(state, context)) continue;
+      if (rule.retireWhen(state, context)) continue;
+      hints.push(toHint(rule));
+      if (hints.length >= maxHints) break;
+    }
+    return hints;
+  }
+  getPostRunHint(state, context) {
+    if (shouldSuppressHints(context)) return null;
+    const maxHints = resolveMaxHints(context);
+    if (maxHints <= 0) return null;
+    const previouslyShown = context.previouslyShown ?? 0;
+    if (previouslyShown >= maxHints) return null;
+    for (const rule of this.rules) {
+      if (!rule.postRun) continue;
+      if (!rule.showWhen(state, context)) continue;
+      if (rule.retireWhen(state, context)) continue;
+      return toHint(rule);
+    }
+    return null;
+  }
+};
+var writeHints = (hints, stderr) => {
+  for (const hint of hints) {
+    stderr.write(`${hint.message}
+`);
+  }
+};
+
+// src/core/telemetry.ts
+init_esm_shims();
+import { Axiom as Axiom2 } from "@axiomhq/js";
+var DEFAULT_DATASET = "support-agent";
+var axiomClient = null;
+function isTelemetryDisabled() {
+  return process.env.SKILL_NO_TELEMETRY === "1";
+}
+function getAxiomClient2() {
+  const token = process.env.AXIOM_TOKEN;
+  if (!token) return null;
+  if (!axiomClient) {
+    axiomClient = new Axiom2({ token });
+  }
+  return axiomClient;
+}
+function resolveTelemetryUser() {
+  const raw = process.env.USER ?? process.env.LOGNAME ?? process.env.USERNAME ?? "";
+  const trimmed = raw.trim();
+  if (!trimmed) return void 0;
+  const base = trimmed.split("@")[0]?.trim();
+  return base || void 0;
+}
+async function sendTelemetryEvent(event) {
+  if (isTelemetryDisabled()) return;
+  const client = getAxiomClient2();
+  if (!client) return;
+  const dataset = process.env.AXIOM_DATASET || DEFAULT_DATASET;
+  const safeEvent = {
+    command: event.command,
+    duration: event.duration,
+    success: event.success,
+    platform: event.platform,
+    user: event.user
+  };
+  try {
+    await client.ingest(dataset, {
+      _time: (/* @__PURE__ */ new Date()).toISOString(),
+      ...safeEvent
+    });
+  } catch {
+  }
+}
+
+// src/core/usage-tracker.ts
+init_esm_shims();
+import { writeFile as writeFile8 } from "fs/promises";
+import { homedir as homedir3 } from "os";
+import { dirname as dirname5, join as join13 } from "path";
+var CONFIG_DIR_NAME2 = "skill-cli";
+var USAGE_FILE_NAME = "usage.json";
+function resolveConfigDir2(configDir) {
+  if (configDir) return configDir;
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome && xdgConfigHome.trim() !== "") {
+    return join13(xdgConfigHome, CONFIG_DIR_NAME2);
+  }
+  return join13(homedir3(), ".config", CONFIG_DIR_NAME2);
+}
+function createDefaultState(now) {
+  return {
+    firstRun: now.toISOString(),
+    totalRuns: 0,
+    commands: {},
+    milestones: {}
+  };
+}
+function isUsageState(value) {
+  if (!value || typeof value !== "object") return false;
+  const state = value;
+  if (typeof state.firstRun !== "string") return false;
+  if (typeof state.totalRuns !== "number") return false;
+  if (!state.commands || typeof state.commands !== "object") return false;
+  if (!state.milestones || typeof state.milestones !== "object") return false;
+  for (const entry of Object.values(state.commands)) {
+    if (!entry || typeof entry !== "object") return false;
+    if (typeof entry.count !== "number") return false;
+    if (typeof entry.firstRun !== "string") return false;
+    if (typeof entry.lastRun !== "string") return false;
+  }
+  for (const entry of Object.values(state.milestones)) {
+    if (!entry || typeof entry !== "object") return false;
+    if (typeof entry.achieved !== "boolean") return false;
+    if (entry.achievedAt !== void 0 && typeof entry.achievedAt !== "string") {
+      return false;
+    }
+  }
+  return true;
+}
+var UsageTracker = class {
+  filePath;
+  now;
+  statePromise;
+  constructor(options = {}) {
+    const configDir = resolveConfigDir2(options.configDir);
+    this.filePath = join13(configDir, USAGE_FILE_NAME);
+    this.now = options.now ?? (() => /* @__PURE__ */ new Date());
+  }
+  async loadState() {
+    if (!this.statePromise) {
+      this.statePromise = this.loadStateInternal();
+    }
+    return this.statePromise;
+  }
+  async loadStateInternal() {
+    try {
+      if (await pathExists(this.filePath)) {
+        const data2 = await readJson(this.filePath);
+        if (isUsageState(data2)) {
+          return data2;
+        }
+      }
+    } catch {
+    }
+    return createDefaultState(this.now());
+  }
+  async saveState(state) {
+    try {
+      await ensureDir(dirname5(this.filePath));
+      await writeFile8(this.filePath, JSON.stringify(state, null, 2), "utf-8");
+    } catch {
+    }
+  }
+  async record(command, _opts = {}) {
+    const state = await this.loadState();
+    const nowIso = this.now().toISOString();
+    state.totalRuns += 1;
+    const existing = state.commands[command];
+    if (existing) {
+      existing.count += 1;
+      existing.lastRun = nowIso;
+    } else {
+      state.commands[command] = {
+        count: 1,
+        firstRun: nowIso,
+        lastRun: nowIso
+      };
+    }
+    await this.saveState(state);
+    return state;
+  }
+  async getUsage() {
+    return this.loadState();
+  }
+  async getCommandCount(command) {
+    const state = await this.loadState();
+    return state.commands[command]?.count ?? 0;
+  }
+  async hasMilestone(name) {
+    const state = await this.loadState();
+    return state.milestones[name]?.achieved ?? false;
+  }
+  async setMilestone(name) {
+    const state = await this.loadState();
+    const existing = state.milestones[name];
+    if (!existing || !existing.achieved) {
+      state.milestones[name] = {
+        achieved: true,
+        achievedAt: this.now().toISOString()
+      };
+      await this.saveState(state);
+    }
+  }
+  async totalRuns() {
+    const state = await this.loadState();
+    return state.totalRuns;
+  }
+  async daysSinceFirstRun() {
+    const state = await this.loadState();
+    const firstRunMs = Date.parse(state.firstRun);
+    if (Number.isNaN(firstRunMs)) return 0;
+    const diffMs = this.now().getTime() - firstRunMs;
+    if (diffMs <= 0) return 0;
+    return Math.floor(diffMs / (1e3 * 60 * 60 * 24));
+  }
+};
+var cachedUsageTracker;
+function getUsageTracker() {
+  if (!cachedUsageTracker) {
+    cachedUsageTracker = new UsageTracker();
+  }
+  return cachedUsageTracker;
+}
+
 // src/mcp/server.ts
 init_esm_shims();
 import { createInterface as createInterface2 } from "readline";
@@ -116348,13 +116928,64 @@ var runtimeTarget = `bun-${process.platform}-${process.arch}`;
 var buildVersion = typeof BUILD_VERSION !== "undefined" && BUILD_VERSION.length > 0 ? BUILD_VERSION : "0.0.0-dev";
 var buildCommit = typeof BUILD_COMMIT !== "undefined" && BUILD_COMMIT.length > 0 ? BUILD_COMMIT : "dev";
 var buildTarget = typeof BUILD_TARGET !== "undefined" && BUILD_TARGET.length > 0 ? BUILD_TARGET : runtimeTarget;
+var isDevBuild = buildVersion.includes("dev") || buildCommit === "dev";
 var versionLabel = `skill v${buildVersion} (${buildCommit}) ${buildTarget}`;
 var program2 = new Command4();
-program2.name("skill").description("CLI tool for managing app integrations").version(versionLabel).option("-f, --format <format>", "Output format (json|text|table)").option("-v, --verbose", "Enable verbose output").option("-q, --quiet", "Suppress non-error output").option(
+var hintEngine = new HintEngine();
+var usageTracker = getUsageTracker();
+var usageState = await (async () => {
+  try {
+    return await usageTracker.getUsage();
+  } catch {
+    return null;
+  }
+})();
+var hintCounts = /* @__PURE__ */ new WeakMap();
+var commandStartTimes = /* @__PURE__ */ new WeakMap();
+var resolveCommandName = (command) => {
+  const names = [];
+  let current = command;
+  while (current) {
+    const name = current.name();
+    if (name) names.unshift(name);
+    current = current.parent;
+  }
+  if (names[0] === "skill") names.shift();
+  return names.join(".");
+};
+var resolveHintContext = (command) => {
+  const opts = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {
+    ...command.parent?.opts(),
+    ...command.opts()
+  };
+  const outputJson = opts.json === true || opts.format === "json";
+  const suppressForPipe = process.env.SKILL_CLI_FORCE_HINTS === "1" ? false : process.stdout.isTTY !== true;
+  return {
+    command: resolveCommandName(command),
+    format: outputJson ? "json" : opts.format,
+    quiet: opts.quiet === true || suppressForPipe
+  };
+};
+var resolveMilestones = (commandName) => {
+  switch (commandName) {
+    case "wizard":
+      return ["wizard_completed"];
+    case "auth.setup":
+    case "init":
+      return ["auth_configured"];
+    default:
+      return [];
+  }
+};
+program2.name("skill").description(getRootAdaptiveDescription(usageState)).version(versionLabel).option("-f, --format <format>", "Output format (json|text|table)").option("-v, --verbose", "Enable verbose output").option("-q, --quiet", "Suppress non-error output").option(
   "--rate-limit <n>",
   "Override Front API rate limit per minute",
   (v) => Number.parseInt(v, 10)
 );
+program2.addHelpText(
+  "after",
+  "\n  Need help? Start with:\n    skill auth setup            Set up credentials (1Password)\n    skill front inbox            See what needs attention\n    skill --help                 This message\n"
+);
 program2.hook("preAction", (thisCommand, actionCommand) => {
   const opts = typeof actionCommand.optsWithGlobals === "function" ? actionCommand.optsWithGlobals() : thisCommand.opts();
   const rateLimit = opts.rateLimit;
@@ -116362,18 +116993,105 @@ program2.hook("preAction", (thisCommand, actionCommand) => {
     process.env.SKILL_RATE_LIMIT = String(rateLimit);
   }
 });
+program2.hook("preAction", (_thisCommand, actionCommand) => {
+  commandStartTimes.set(actionCommand, Date.now());
+});
+program2.hook("preAction", async (_thisCommand, actionCommand) => {
+  try {
+    const context = resolveHintContext(actionCommand);
+    const state = await usageTracker.getUsage();
+    const hints = hintEngine.getHints(state, context);
+    writeHints(hints, process.stderr);
+    hintCounts.set(actionCommand, hints.length);
+  } catch {
+  }
+});
+program2.hook("postAction", async (_thisCommand, actionCommand) => {
+  try {
+    const context = resolveHintContext(actionCommand);
+    const state = await usageTracker.record(context.command);
+    const milestones = resolveMilestones(context.command);
+    for (const milestone of milestones) {
+      await usageTracker.setMilestone(milestone);
+    }
+    const previouslyShown = hintCounts.get(actionCommand) ?? 0;
+    const postHint = hintEngine.getPostRunHint(state, {
+      ...context,
+      previouslyShown
+    });
+    if (postHint) writeHints([postHint], process.stderr);
+  } catch {
+  }
+  try {
+    const startTime = commandStartTimes.get(actionCommand) ?? Date.now();
+    const duration = Math.max(0, Date.now() - startTime);
+    const exitCode = process.exitCode ?? 0;
+    const commandName = resolveCommandName(actionCommand);
+    void sendTelemetryEvent({
+      command: commandName,
+      duration,
+      success: exitCode === 0,
+      platform: process.platform,
+      user: resolveTelemetryUser()
+    });
+  } catch {
+  }
+  try {
+    const context = resolveHintContext(actionCommand);
+    await autoUpdateAfterCommand({
+      commandName: context.command,
+      currentVersion: buildVersion,
+      format: context.format,
+      isDevMode: isDevBuild
+    });
+  } catch {
+  }
+});
 program2.command("init").description("Initialize a new app integration (quick mode)").argument(
   "[name]",
   "Name of the integration (required in non-interactive mode)"
-).option("--json", "Output result as JSON (machine-readable)").action(init2);
-program2.command("wizard").description("Interactive wizard for setting up a new property").option("--json", "Output result as JSON (machine-readable)").action(wizard);
+).option("--json", "Output result as JSON (machine-readable)").action(async (name, options, command) => {
+  const opts = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {
+    ...command.parent?.opts(),
+    ...command.opts()
+  };
+  const ctx = await createContext({
+    format: options.json ? "json" : opts.format,
+    verbose: opts.verbose,
+    quiet: opts.quiet
+  });
+  await init2(ctx, name, options);
+});
+program2.command("wizard").description("Interactive wizard for setting up a new property").option("--json", "Output result as JSON (machine-readable)").action(async (options, command) => {
+  const opts = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {
+    ...command.parent?.opts(),
+    ...command.opts()
+  };
+  const ctx = await createContext({
+    format: options.json ? "json" : opts.format,
+    verbose: opts.verbose,
+    quiet: opts.quiet
+  });
+  await wizard(ctx, options);
+});
 program2.command("health").description("Test integration endpoint health").argument(
   "[slug|url]",
   "App slug (from database) or URL (e.g., https://totaltypescript.com)"
 ).option(
   "-s, --secret <secret>",
   "Webhook secret (required for direct URL mode)"
-).option("-l, --list", "List all registered apps").option("--ids-only", "Output only IDs (one per line)").option("--json", "Output result as JSON (machine-readable)").action(health2);
+).option("-l, --list", "List all registered apps").option("--ids-only", "Output only IDs (one per line)").option("--json", "Output result as JSON (machine-readable)").action(async (slugOrUrl, options, command) => {
+  const opts = typeof command.optsWithGlobals === "function" ? command.optsWithGlobals() : {
+    ...command.parent?.opts(),
+    ...command.opts()
+  };
+  const ctx = await createContext({
+    format: options.json ? "json" : opts.format,
+    verbose: opts.verbose,
+    quiet: opts.quiet
+  });
+  await health2(ctx, slugOrUrl, options);
+});
 program2.command("eval").description("Run evals against a dataset").argument("<type>", "Eval type (e.g., routing)").argument("<dataset>", "Path to dataset JSON file").option("--json", "Output result as JSON (machine-readable)").option(
   "--min-precision <number>",
   "Minimum precision threshold (default: 0.92)",
@@ -116410,8 +117128,8 @@ program2.command("eval").description("Run evals against a dataset").argument("<t
   });
 });
 registerDbStatusCommand(program2);
-registerFrontCommands(program2);
-registerInngestCommands(program2);
+registerFrontCommands(program2, usageState);
+registerInngestCommands(program2, usageState);
 registerAxiomCommands(program2);
 registerEvalLocalCommands(program2);
 registerEvalPipelineCommands(program2);
@@ -116424,9 +117142,11 @@ registerMemoryCommands(program2);
 registerFaqCommands(program2);
 registerDeployCommands(program2);
 registerKbCommands(program2);
-registerAuthCommands(program2);
+registerAuthCommands(program2, usageState);
 registerPluginSyncCommand(program2);
-program2.command("mcp").description("Start MCP server for AI coding agent integration").action(async () => {
+program2.command("mcp").description(
+  "Start MCP server for AI coding agent integration.\n  Exposes 9 Front tools over JSON-RPC stdio for Claude Code, Cursor, etc.\n  Tools: inbox, conversation, message, assign, reply, tag, archive, search, report\n  Usage: skill mcp  (then connect your AI editor to stdin/stdout)"
+).action(async () => {
   const server = createMcpServer();
   await server.start();
 });