@empirical-gauzza/cli 1.0.19 → 1.0.20

package/lib/installers/skill-variants/SKILL.mcp.md

@@ -0,0 +1,134 @@
+---
+name: empirical-memory
+description: Use Empirical to recall/save durable project context across sessions and projects, and to look up how to use Empirical itself - CLI commands, install/auth/workspace/kit/skill setup, docs.
+---
+
+# Empirical Memory (MCP mode)
+
+Use Empirical to carry durable context across projects and clients, and as the first stop for
+"how do I use Empirical" questions — command syntax, install/auth/workspace/kit/skill setup, or
+what Empirical can do. Don't answer those from general knowledge or by guessing: use the
+`memory_usage_guide` MCP tool for the current, agent-readable answer first.
+
+This variant is for installs where the user chose MCP as their integration mode. The connected
+Empirical MCP server is the primary and expected way to reach Empirical here — use its tools
+directly, not `empirical` CLI commands, as the first move.
+
+**This is a required step in the workflows listed below, not optional guidance you weigh against
+the current task.** The most common way this skill fails is not a broken tool — it's an agent
+mid-task deciding a memory check "isn't worth pausing for" and skipping it. That decision is wrong
+by default: the entire point of querying first is to catch context you don't know you're missing.
+If you are not sure whether a task qualifies, treat it as if it does.
+
+## Before doing work — MUST, not discretionary
+
+1. Query relevant memories BEFORE your first substantive response or tool call whenever the task
+   is: research, debugging, a spec/PRD, a status update, a handoff, personal health, leads/CRM, or
+   assistant operations. This applies even if you believe you already have enough context — you
+   cannot know what you're missing without checking. Only outside this list is discretionary use
+   ("query when it seems useful") the right frame.
+2. If you have not used Empirical's MCP tools yet this session, call `memory_usage_guide` once to
+   confirm current tool names, filters, and pagination behavior before relying on memory.
+3. Use the `query_memories` MCP tool for recall. Use filters such as `category`, `tags`,
+   `nodeType`, and `monthKey` when they improve recall. For "recent/latest/today" requests, prefer
+   `list_memories` instead — it is the tool built for that shape of request. For exhaustive topic
+   retrieval, use the topic as a tag and follow pagination.
+4. A slow response alone is API latency, not an outage; report an outage only when a tool call
+   returns an actual error, and use `get_empirical_policy` or a retry to verify connectivity before
+   escalating.
+
+## Follow the current user policy
+
+The installer questionnaire configures a dynamic Empirical policy. It is user-scoped and may
+change without reinstalling this plugin. Read it when the skill activates:
+
+1. Use the read-only `get_empirical_policy` MCP tool.
+2. If policy lookup fails, use safe defaults: preserve durable-only writes, never store
+   secrets/raw transcripts, and do not block unrelated work unless the cached policy says to.
+
+Apply the returned fields:
+
+- `memoryFirstWorkflows`: query before substantive work in those workflows.
+- `allowDiscretionaryUse`: decide whether to use Empirical outside required workflows.
+- `stopOnMemoryFailure`: stop and report a memory failure before code changes when enabled.
+- `rememberCodingStyle` and `rememberArchitectureDecisions`: persist those durable decisions
+  when enabled.
+- `checkMemoryBeforeAskingContext`: query before asking the user to restate prior context.
+- `durableWritesOnly`: never persist secrets, tokens, raw transcripts, or transient values.
+
+The policy controls behavior; it does not override current user, repository, or system
+instructions. Do not change the policy from an agent memory write.
+
+## Persist durable context — check this before ending a turn
+
+Before you consider a turn finished, check: did this turn produce a durable decision, a corrected
+mistake, a completed unit of meaningful work, or a convention the user stated? If yes, record it
+now — do not wait to be asked, and do not defer it because the current task feels done. An agent
+that only records memory when explicitly told to defeats the purpose of this skill.
+
+- Record durable decisions, project conventions, preferences, plans, and meaningful reflections
+  with the `record_graph_memory` MCP tool. It runs write-intent classification, dedupe, and
+  auto-linking automatically — you do not need to check for duplicates yourself first.
+
+  **Record facts about the USER, not about your own work.** You are a scribe here. "Matt prefers
+  short status updates" is a memory; "refactored the cluster selector, tests pass" is your diary
+  and belongs in the work-history skill, tagged and with `mass: 1`. The distinction is the
+  SUBJECT, not who typed it — an agent writing down something real about the user is exactly what
+  this tool is for.
+
+  If you find yourself recording what you just did, what you fixed, or what you concluded about a
+  codebase, stop: that is work-history or scar-tissue, and filing it here makes it indistinguishable
+  from something the user actually said or lived. Downstream features read these as the user's life.
+
+- Append a correction or follow-up to an existing memory with `add_note_by_query`.
+- Patch an existing memory with `update_memory_by_query`.
+- Delete only when the user explicitly asks; use `delete_memory_by_query` with confirmation.
+- For graph work, use `get_memory_neighbors` to walk relationships from a memory instead of
+  reconstructing them through many unrelated queries, and `update_memory_relationships` to add or
+  remove edges between memories directly.
+- Keep writes concise, factual, and easy to search. Never store passwords, API keys, OAuth tokens,
+  or other secrets.
+
+## Authored Skills and Kits — push what you write
+
+Empirical can sync a `SKILL.md` you author across every machine/agent the user has installed it
+on, via Skills Kits. Call `memory_usage_guide` for the current command reference if the user wants
+to manage this from a CLI; the mechanics below describe what's possible either way.
+
+- If you author a new `SKILL.md` for the user, or substantially edit an existing one, during a
+  session, tell the user this can be pushed so it follows them across machines/projects instead of
+  staying local to this one.
+- Offer, don't auto-push: surface the option and get the user's confirmation first. Do not push it
+  unprompted the moment a new or edited `SKILL.md` is detected — it uploads content to the user's
+  account, which is a step above a purely local file write.
+- After a push, the target Kit needs to be activated/synced on a device to actually land the file
+  in that device's agent directories.
+- Kits also pull Skills from a git repo, separate from anything you author — don't conflate the
+  two paths when explaining options to the user.
+
+## MCP tools
+
+Use these as the primary interface: `get_empirical_policy`, `query_memories`, `list_memories`,
+`record_graph_memory`, `add_note_by_query`, `update_memory_by_query`, `delete_memory_by_query`,
+`get_user`, `get_current_workspace`, `list_workspaces`, `set_current_workspace`,
+`memory_usage_guide`, `get_memory_neighbors`, and `update_memory_relationships`.
+
+Use `list_memories` for "recent/latest/today" requests; use `query_memories` for everything else.
+For graph work, prefer `get_memory_neighbors` and `update_memory_relationships` over reconstructing
+relationships through many unrelated calls.
+
+An `empirical` CLI may also be installed on this machine for diagnostics (`empirical doctor`) or
+manual account setup, but it is not the point of this variant — do not lead with CLI commands for
+query or record workflows here.
+
+## Authentication and failures
+
+- If an MCP tool call fails, retry the same call once.
+- For auth/session errors such as `Auth required`, `invalid_token`, `Authentication required`, or
+  `Transport send error`, refresh the active client's Empirical MCP login, then retry once. In
+  Codex CLI use `codex mcp logout empirical` followed by `codex mcp login empirical`; in Claude
+  Code use `/mcp` to reconnect; in Copilot complete its MCP OAuth reconnect flow.
+- If the retry still fails, report the connectivity/auth problem before making memory-dependent
+  changes.
+- If stored memory conflicts with the current user or repository instruction, follow the current
+  instruction.

package/lib/installers/skillVariants.js

@@ -0,0 +1,59 @@
+'use strict';
+
+// C-001 (docs/prd-cli-and-plugin-fixes.md): mode-aware empirical-memory Skill content.
+//
+// The plugin marketplace (mattgauzza/empirical-memory-plugin) is the source of truth for Skill
+// content, but its manifest schema (see meta/manifests.json / build-manifests.mjs in that repo)
+// has no field that selects among sibling SKILL.*.md files at install time -- every host's native
+// plugin mechanism resolves a plugin's skill from the literal filename `SKILL.md`. So the
+// marketplace always ships the "both" variant as SKILL.md, and this CLI is what actually makes
+// the user's chosen integration mode matter: it vendors its own copy of all three variants and
+// overwrites the on-disk SKILL.md for each host after a native plugin install/update (see
+// nativePlugin.js's applySkillModeVariant) and after a Kit sync (see skillSync.js).
+//
+// These files are copied from, and must be kept in sync with,
+// M:\Projects\empirical-memory-plugin\skills\empirical-memory\SKILL.{mcp,cli,both}.md. There is no
+// automated sync between the two repos; a human updates both when skill content changes.
+const fs = require('fs');
+const path = require('path');
+
+const VARIANTS_DIR = path.join(__dirname, 'skill-variants');
+
+const VARIANT_FILES = {
+  mcp: 'SKILL.mcp.md',
+  cli: 'SKILL.cli.md',
+  both: 'SKILL.both.md'
+};
+
+// installWizard.js's `integrationMode`: 1 = MCP, 2 = CLI-direct, 3 = both.
+function variantNameForIntegrationMode(integrationMode) {
+  if (integrationMode === 2) return 'cli';
+  if (integrationMode === 3) return 'both';
+  return 'mcp';
+}
+
+// Returns the variant's markdown content, or null if the vendored file is missing (e.g. a stale
+// CLI release published before a variant existed). Never throws -- callers must treat a missing
+// variant as "leave whatever is already installed" per the PRD's own risk mitigation, not as a
+// fatal error.
+function readSkillVariantContent(variantName) {
+  const fileName = VARIANT_FILES[variantName];
+  if (!fileName) return null;
+  const filePath = path.join(VARIANTS_DIR, fileName);
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (_error) {
+    return null;
+  }
+}
+
+function readSkillVariantForIntegrationMode(integrationMode) {
+  return readSkillVariantContent(variantNameForIntegrationMode(integrationMode));
+}
+
+module.exports = {
+  VARIANT_FILES,
+  variantNameForIntegrationMode,
+  readSkillVariantContent,
+  readSkillVariantForIntegrationMode
+};

package/lib/kitCommands.js

@@ -14,9 +14,30 @@ const { httpJson, printApiError } = require('./http');
 const { parseOption, parseFlag } = require('./env');
 const { requireAccessToken, resolveApiBaseUrl, buildApiAuthHeaders } = require('./auth');
 const { withCliAnalyticsContext } = require('./memoryCommands');
-const { readDeviceConfig, writeDeviceConfig, ensureDeviceId, readPendingReview } = require('./deviceConfig');
+const { readDeviceConfig, writeDeviceConfig, ensureDeviceId, readPendingReview, readIntegrationMode } = require('./deviceConfig');
 const { performSync, printSyncSummary } = require('./skillSync');
 const { registerScheduledSync, deregisterScheduledSync } = require('./scheduledSync');
+const { detectInstallTargets } = require('./installers/detect');
+const { applySkillModeVariant } = require('./installers/nativePlugin');
+
+// C-001: `kit use`/`kit sync` are the second distribution path the PRD names for mode-aware
+// Skill content. skillSync.js's generalized Kit writer deliberately never writes empirical-memory
+// (see filterOutEmpiricalMemory in skillSync.js -- the server's resolved builtin for that name is
+// a placeholder, not the real plugin content), so a Kit sync alone would never re-apply a mode
+// change. Refresh it here instead, right after every sync, so `kit sync`/`kit use` -- not just
+// re-running the full installer -- keeps empirical-memory's Skill content matching whatever
+// integration mode the user last chose in `empirical install`.
+function refreshEmpiricalMemorySkillForCurrentMode({ dryRun, quiet }) {
+  if (dryRun) return;
+  const integrationMode = readIntegrationMode();
+  for (const target of detectInstallTargets()) {
+    try {
+      applySkillModeVariant(target.id, integrationMode);
+    } catch (error) {
+      if (!quiet) warn(`Warning: could not refresh empirical-memory skill content for ${target.label}: ${error.message}`);
+    }
+  }
+}
 
 // US-016: nag banner surfaced at the START of every interactive (non-`--quiet`) `kit`
 // subcommand — informational only, never blocks the subcommand's own work. `kit sync` is the
@@ -143,7 +164,7 @@ async function runKitRemoveSource(args) {
   log(JSON.stringify(result));
 }
 
-async function runKitList(args) {
+async function runKitList(args) {
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
   const url = new URL('/api/v1/kits', baseUrl).toString();
@@ -157,112 +178,166 @@ async function runKitList(args) {
   }
 
   const result = (response && response.data) ? response.data : response;
-  log(JSON.stringify(result));
-}
-
-async function fetchInventoryJson(url, accessToken) {
-  try {
-    return await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    printApiError(error);
-    process.exit(1);
-  }
-}
-
-async function listOwnedKits(baseUrl, accessToken) {
-  const response = await fetchInventoryJson(new URL('/api/v1/kits', baseUrl).toString(), accessToken);
-  return response?.data?.kits || response?.kits || [];
-}
-
-async function runSkillList(args) {
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const kitFilter = parseOption(args, '--kit', '');
-  const kits = await listOwnedKits(baseUrl, accessToken);
-  const selectedKits = kitFilter
-    ? kits.filter((kit) => kit.kitId === kitFilter || kit.name === kitFilter)
-    : kits;
-  const skills = [];
-
-  for (const kit of selectedKits) {
-    const response = await fetchInventoryJson(
-      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/resolved`, baseUrl).toString(),
-      accessToken
-    );
-    const kitSkills = response?.data?.skills || response?.skills || [];
-    for (const skill of kitSkills) {
-      skills.push({
-        ...skill,
-        kitId: kit.kitId,
-        kitName: kit.name,
-        isDefault: Boolean(kit.isDefault)
-      });
-    }
-  }
-
-  log(JSON.stringify({ skills }));
-}
-
-async function runDeviceList() {
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const kits = await listOwnedKits(baseUrl, accessToken);
-  const devicesById = new Map();
-
-  for (const kit of kits.filter((candidate) => !candidate.isDefault)) {
-    const response = await fetchInventoryJson(
-      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/devices`, baseUrl).toString(),
-      accessToken
-    );
-    const devices = response?.data?.devices || response?.devices || [];
-    for (const device of devices) {
-      const existing = devicesById.get(device.deviceId) || {
-        ...device,
-        kits: []
-      };
-      existing.kits.push({
-        kitId: kit.kitId,
-        kitName: kit.name,
-        active: Boolean(device.active)
-      });
-      devicesById.set(device.deviceId, existing);
-    }
-  }
-
-  log(JSON.stringify({ devices: [...devicesById.values()] }));
-}
-
-async function runDeviceShow(args) {
-  const deviceId = args[0] && !args[0].startsWith('--') ? args[0] : '';
-  if (!deviceId) {
-    warn('Usage: empirical device show <deviceId>');
-    process.exit(1);
-  }
-
-  const accessToken = requireAccessToken();
-  const baseUrl = resolveApiBaseUrl();
-  const response = await fetchInventoryJson(
-    new URL(`/api/v1/devices/${encodeURIComponent(deviceId)}/resolved`, baseUrl).toString(),
-    accessToken
-  );
-  const data = response?.data || response || {};
-  log(JSON.stringify({ deviceId, ...data }));
-}
-
-async function runDeviceCommand(subArgs) {
-  const sub = subArgs[0];
-  const rest = subArgs.slice(1);
-  return withCliAnalyticsContext(
-    { command: `device.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
-    async () => {
-      if (sub === 'list') return runDeviceList(rest);
-      if (sub === 'show') return runDeviceShow(rest);
-      warn('Unknown device subcommand: ' + (sub || '(none)'));
-      warn('Usage: empirical device <list|show> [options]');
-      process.exit(1);
-    }
-  );
-}
+  log(JSON.stringify(result));
+}
+
+async function fetchInventoryJson(url, accessToken) {
+  try {
+    return await httpJson(url, 'GET', undefined, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    printApiError(error);
+    process.exit(1);
+  }
+}
+
+async function listOwnedKits(baseUrl, accessToken) {
+  const response = await fetchInventoryJson(new URL('/api/v1/kits', baseUrl).toString(), accessToken);
+  return response?.data?.kits || response?.kits || [];
+}
+
+// C-006: fetch every resolved skill across the caller's kits (or just `kitFilter`'s kit), each
+// annotated with which kit it came from. Shared by `skill list` (the human-facing listing) and
+// `resolveAuthoredSkillId` (name -> authoredSkillId lookup for `skill history`/`skill rollback`)
+// so both read the exact same data — a name that resolves for one resolves the same way for
+// the other.
+async function fetchAllResolvedSkills(baseUrl, accessToken, kitFilter) {
+  const kits = await listOwnedKits(baseUrl, accessToken);
+  const selectedKits = kitFilter
+    ? kits.filter((kit) => kit.kitId === kitFilter || kit.name === kitFilter)
+    : kits;
+  const skills = [];
+
+  for (const kit of selectedKits) {
+    const response = await fetchInventoryJson(
+      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/resolved`, baseUrl).toString(),
+      accessToken
+    );
+    const kitSkills = response?.data?.skills || response?.skills || [];
+    for (const skill of kitSkills) {
+      skills.push({
+        ...skill,
+        kitId: kit.kitId,
+        kitName: kit.name,
+        isDefault: Boolean(kit.isDefault)
+      });
+    }
+  }
+
+  return skills;
+}
+
+async function runSkillList(args) {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const kitFilter = parseOption(args, '--kit', '');
+  const skills = await fetchAllResolvedSkills(baseUrl, accessToken, kitFilter);
+
+  // C-006: name, resolvedVersion (its version) and authoredSkillId are the fields that matter
+  // for finding/using a skill again later — authoredSkillId in particular is the ONLY way to
+  // reach `skill history`/`skill rollback`, and until now it was never shown here (only ever
+  // printed once, in the JSON blob `skill push` prints at push time). Every other field from
+  // the resolved payload is still included; this just guarantees those three are always present
+  // per row, even for skill types (git_custom/builtin) where authoredSkillId is absent.
+  const rows = skills.map((skill) => ({
+    name: skill.name,
+    resolvedVersion: skill.resolvedVersion,
+    authoredSkillId: skill.authoredSkillId || null,
+    ...skill
+  }));
+
+  log(JSON.stringify({ skills: rows }));
+}
+
+// C-006: `skill history`/`skill rollback` historically required the raw authoredSkillId, which
+// the user only ever sees once (the JSON `skill push` prints at push time). This lets either
+// command accept the skill's NAME instead, resolved against the same data `skill list` shows.
+// Direct authoredSkillId matches win outright (no ambiguity possible — it's a unique id); name
+// matches must be unique among authored skills (only authored skills have an authoredSkillId,
+// hence history/rollback) or this throws a clear, actionable error.
+async function resolveAuthoredSkillId(identifier, baseUrl, accessToken, kitFilter) {
+  const skills = await fetchAllResolvedSkills(baseUrl, accessToken, kitFilter);
+
+  const directMatch = skills.find((skill) => skill.authoredSkillId === identifier);
+  if (directMatch) return directMatch.authoredSkillId;
+
+  const nameMatches = skills.filter((skill) => skill.authoredSkillId && skill.name === identifier);
+
+  if (nameMatches.length === 1) return nameMatches[0].authoredSkillId;
+
+  if (nameMatches.length > 1) {
+    const locations = nameMatches
+      .map((skill) => `${skill.kitName || skill.kitId} (${skill.authoredSkillId})`)
+      .join(', ');
+    throw new Error(
+      `"${identifier}" matches ${nameMatches.length} authored skills: ${locations}. Pass the authoredSkillId instead, or narrow with --kit.`
+    );
+  }
+
+  throw new Error(
+    `No authored skill named or with id "${identifier}" was found${kitFilter ? ` in kit "${kitFilter}"` : ''}. Run 'empirical skill list' to see authoredSkillId per skill.`
+  );
+}
+
+async function runDeviceList() {
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const kits = await listOwnedKits(baseUrl, accessToken);
+  const devicesById = new Map();
+
+  for (const kit of kits.filter((candidate) => !candidate.isDefault)) {
+    const response = await fetchInventoryJson(
+      new URL(`/api/v1/kits/${encodeURIComponent(kit.kitId)}/devices`, baseUrl).toString(),
+      accessToken
+    );
+    const devices = response?.data?.devices || response?.devices || [];
+    for (const device of devices) {
+      const existing = devicesById.get(device.deviceId) || {
+        ...device,
+        kits: []
+      };
+      existing.kits.push({
+        kitId: kit.kitId,
+        kitName: kit.name,
+        active: Boolean(device.active)
+      });
+      devicesById.set(device.deviceId, existing);
+    }
+  }
+
+  log(JSON.stringify({ devices: [...devicesById.values()] }));
+}
+
+async function runDeviceShow(args) {
+  const deviceId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!deviceId) {
+    warn('Usage: empirical device show <deviceId>');
+    process.exit(1);
+  }
+
+  const accessToken = requireAccessToken();
+  const baseUrl = resolveApiBaseUrl();
+  const response = await fetchInventoryJson(
+    new URL(`/api/v1/devices/${encodeURIComponent(deviceId)}/resolved`, baseUrl).toString(),
+    accessToken
+  );
+  const data = response?.data || response || {};
+  log(JSON.stringify({ deviceId, ...data }));
+}
+
+async function runDeviceCommand(subArgs) {
+  const sub = subArgs[0];
+  const rest = subArgs.slice(1);
+  return withCliAnalyticsContext(
+    { command: `device.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
+    async () => {
+      if (sub === 'list') return runDeviceList(rest);
+      if (sub === 'show') return runDeviceShow(rest);
+      warn('Unknown device subcommand: ' + (sub || '(none)'));
+      warn('Usage: empirical device <list|show> [options]');
+      process.exit(1);
+    }
+  );
+}
 
 async function runKitAutosync(args) {
   const kitId = args[0] && !args[0].startsWith('--') ? args[0] : '';
@@ -398,6 +473,7 @@ async function runKitUse(args) {
     process.exit(1);
   }
   printSyncSummary(syncResult, quiet);
+  refreshEmpiricalMemorySkillForCurrentMode({ dryRun, quiet });
 
   // US-012: fetch this Kit's own autoSyncEnabled flag and reconcile the local scheduled task to
   // match it. A failure here is fetched best-effort — it must never turn a successful `kit use`
@@ -434,6 +510,7 @@ async function runKitSync(args) {
   }
 
   printSyncSummary(result, quiet);
+  refreshEmpiricalMemorySkillForCurrentMode({ dryRun, quiet });
 }
 
 async function runKitCommand(subArgs) {
@@ -527,14 +604,24 @@ async function runSkillPush(args) {
 }
 
 async function runSkillHistory(args) {
-  const authoredSkillId = args[0] && !args[0].startsWith('--') ? args[0] : '';
-  if (!authoredSkillId) {
-    warn('Usage: empirical skill history <authoredSkillId>');
+  const identifier = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  if (!identifier) {
+    warn('Usage: empirical skill history <authoredSkillId|name> [--kit <kitId>]');
     process.exit(1);
   }
 
+  const kitFilter = parseOption(args, '--kit', '');
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
+
+  let authoredSkillId;
+  try {
+    authoredSkillId = await resolveAuthoredSkillId(identifier, baseUrl, accessToken, kitFilter);
+  } catch (error) {
+    warn(error.message);
+    process.exit(1);
+  }
+
   const url = new URL(
     `/api/v1/skills/${encodeURIComponent(authoredSkillId)}/history`,
     baseUrl
@@ -553,17 +640,27 @@ async function runSkillHistory(args) {
 }
 
 async function runSkillRollback(args) {
-  const authoredSkillId = args[0] && !args[0].startsWith('--') ? args[0] : '';
+  const identifier = args[0] && !args[0].startsWith('--') ? args[0] : '';
   const toVersionRaw = parseOption(args, '--to-version', '');
   const toVersion = Number(toVersionRaw);
 
-  if (!authoredSkillId || !toVersionRaw || !Number.isInteger(toVersion) || toVersion < 1) {
-    warn('Usage: empirical skill rollback <authoredSkillId> --to-version <n>');
+  if (!identifier || !toVersionRaw || !Number.isInteger(toVersion) || toVersion < 1) {
+    warn('Usage: empirical skill rollback <authoredSkillId|name> --to-version <n> [--kit <kitId>]');
     process.exit(1);
   }
 
+  const kitFilter = parseOption(args, '--kit', '');
   const accessToken = requireAccessToken();
   const baseUrl = resolveApiBaseUrl();
+
+  let authoredSkillId;
+  try {
+    authoredSkillId = await resolveAuthoredSkillId(identifier, baseUrl, accessToken, kitFilter);
+  } catch (error) {
+    warn(error.message);
+    process.exit(1);
+  }
+
   const url = new URL(
     `/api/v1/skills/${encodeURIComponent(authoredSkillId)}/rollback`,
     baseUrl
@@ -588,13 +685,13 @@ async function runSkillCommand(subArgs) {
   return withCliAnalyticsContext(
     { command: `skill.${sub || 'unknown'}`, subcommand: sub || 'unknown' },
     async () => {
-      if (sub === 'push') return runSkillPush(rest);
-      if (sub === 'list') return runSkillList(rest);
+      if (sub === 'push') return runSkillPush(rest);
+      if (sub === 'list') return runSkillList(rest);
       if (sub === 'history') return runSkillHistory(rest);
       if (sub === 'rollback') return runSkillRollback(rest);
 
       warn('Unknown skill subcommand: ' + (sub || '(none)'));
-      warn('Usage: empirical skill <list|push|history|rollback> [options]');
+      warn('Usage: empirical skill <list|push|history|rollback> [options]');
       process.exit(1);
     }
   );
@@ -609,11 +706,11 @@ module.exports = {
   runKitDevices,
   runKitDeactivate,
   runKitUse,
-  runKitSync,
-  runSkillList,
-  runDeviceList,
-  runDeviceShow,
-  runDeviceCommand,
+  runKitSync,
+  runSkillList,
+  runDeviceList,
+  runDeviceShow,
+  runDeviceCommand,
   runKitCommand,
   runSkillPush,
   runSkillHistory,