@empirical-gauzza/cli 1.0.35 → 1.0.37

package/lib/empiricalTokensFormat.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// Empirical Tokens wording and the cost gate shared by every CLI command that can start a priced
+// action (`setup run`, `blueprint install`) or print a reset date (`usage`, `whoami`, error hints).
+
+// '<Month> <D> at <h:mm AM/PM> <TZ>' in this machine's time zone, e.g. 'October 31 at 8:00 PM EDT'.
+// The reset instant is 00:00 UTC on the 1st, so the local date can be the day before: date AND time
+// are always shown. This is a standalone copy of formatResetInstant in packages/shared (the CLI is
+// published on its own and does not import shared); both are pinned to the same fixtures in tests.
+// timeZone defaults to the machine's own; an invalid or empty one reads as UTC and says so. Returns
+// null for a missing or unreadable date so callers can fall back to neutral wording.
+function resetLabel(resetsAt, timeZone) {
+  if (resetsAt === undefined || resetsAt === null || resetsAt === '') return null;
+  const date = new Date(resetsAt);
+  if (Number.isNaN(date.getTime())) return null;
+  const machineZone = (() => {
+    try { return Intl.DateTimeFormat().resolvedOptions().timeZone; } catch (_error) { return null; }
+  })();
+  const requested = timeZone === undefined ? machineZone : timeZone;
+  const zones = [typeof requested === 'string' && requested.trim() ? requested.trim() : null, 'UTC'].filter(Boolean);
+  for (const zone of zones) {
+    try {
+      const parts = new Intl.DateTimeFormat('en-US', {
+        timeZone: zone, month: 'long', day: 'numeric', hour: 'numeric', minute: '2-digit', timeZoneName: 'short'
+      }).formatToParts(date);
+      const get = (type) => (parts.find((p) => p.type === type) || {}).value || '';
+      return `${get('month')} ${get('day')} at ${get('hour')}:${get('minute')} ${get('dayPeriod')} ${get('timeZoneName')}`;
+    } catch (_error) {
+      // Invalid time zone: try UTC.
+    }
+  }
+  return null;
+}
+
+// A charge is offered only to a real terminal; piped input never accepts one. EMPIRICAL_TEST_ASSUME_TTY=1
+// exists only so tests can drive the prompt through a pipe. It is not documented in --help on purpose,
+// it must be exactly '1', and nothing in the product sets it; setting it only lets a person who typed
+// 'y' at the prompt through a pipe, it never accepts a cost by itself.
+function isInteractiveTerminal() {
+  return Boolean(process.stdin.isTTY) || process.env.EMPIRICAL_TEST_ASSUME_TTY === '1';
+}
+
+// A priced start answered 200 with status 'cost_confirmation_required' and started nothing. This
+// resolves only when a person at a terminal typed y or yes; every other path (no prompter, no terminal,
+// any other reply) prints why nothing started and exits 1. The cost is never accepted on the person's
+// behalf: acceptance reaches the server only from --accept-cost or from this prompt.
+//   preview   the server's preview payload (message, empiricalTokenCost)
+//   prompter  createPrompter(...) result, or null for a non-interactive run
+//   warn      the CLI's stderr printer
+//   sanitize  terminal sanitiser for server text
+async function confirmCostOrExit(preview, { prompter, warn, sanitize = String }) {
+  warn(sanitize(preview.message || `This uses ${preview.empiricalTokenCost} Empirical Tokens.`));
+  if (!prompter || !isInteractiveTerminal()) {
+    warn('Nothing was started. Re-run with --accept-cost to start.');
+    process.exit(1);
+  }
+  const reply = (await prompter.askText('Start? (y/N)')).trim();
+  if (!/^(y|yes)$/i.test(reply)) {
+    warn('Nothing was started.');
+    process.exit(1);
+  }
+}
+
+const isCostPreview = (value) => Boolean(value) && value.status === 'cost_confirmation_required';
+
+module.exports = { resetLabel, isInteractiveTerminal, confirmCostOrExit, isCostPreview };

package/lib/help.js

@@ -13,7 +13,7 @@ function showHelp() {
   log('');
   log('Usage:');
   log('  empirical install');
-  log('  empirical plugin install <codex|copilot|claude|all> [--all-optional]');
+  log('  empirical plugin install <codex|copilot|claude|all> [--all-optional|--voice]');
   log('  empirical plugin check [--force]');
   log('  empirical policy show [--refresh]');
   log('  empirical policy set --json <policy>');
@@ -25,6 +25,7 @@ function showHelp() {
   log('                                               Mint a new API key (--replace-all wipes the existing ones)');
   log('  empirical auth revoke-key (--key-id <id> | --all)');
   log('                                               Revoke one API key, or every key on the account');
+  log('  empirical usage [--json]                     Memory, installs and Empirical Tokens this month');
   log('  empirical oauth bootstrap headless [--print-access-token]');
   log('                                                First-time token setup for CI/headless/API-key use');
   log('  empirical oauth bootstrap headless --write-env [--env-output <path>]');
@@ -38,9 +39,11 @@ function showHelp() {
   log('  empirical oauth client show');
   log('  empirical oauth client clear');
   log('  empirical workspace list                     List workspaces you can select, and which one is active');
-  log('  empirical workspace current                  Show the currently active workspace');
+  log('  empirical workspace current                  Show the active workspace and where it comes from (env, project, global)');
   log('  empirical workspace select [<number|name>]   Set the active workspace (prompts if omitted)');
-  log('  empirical workspace use <number|name|id>     Alias for `workspace select`');
+  log('  empirical workspace use <number|name|id>     Alias for `workspace select`. Inside a git repo binds THIS project;');
+  log('                                                --global sets the machine-wide default, --project forces a binding');
+  log('  empirical workspace unbind                   Remove this project\'s workspace binding');
   log('  empirical workspace create <name> [--description <text>]');
   log('                                                Create a new shared team workspace');
   log('  empirical workspace invite create [--role reader|writer|manager] [--expires-in-days <n>] [--max-uses <n>]');
@@ -50,6 +53,15 @@ function showHelp() {
   log('  empirical workspace delete <number|name|id> [--confirm]');
   log('                                                Soft-delete a team workspace (dry-run without --confirm)');
   log('');
+  log('Guided setups:');
+  log('  empirical setup list                          List guided setups');
+  log('  empirical setup run <setupId> [--accept-cost] Run one interactively');
+  log('  empirical setup run <setupId> --answers <f>   Run from a JSON file of answers');
+  log('  empirical setup resume <sessionId>            Show the current question');
+  log('  empirical setup answer <sessionId> <key> <v>  Answer a question');
+  log('  empirical setup confirm <sessionId> <hash>    Confirm and install a reviewed draft');
+  log('  empirical setup finish <sessionId>            Finish a scripted setup early');
+  log('');
   log('Options:');
   log('  install                        Interactive installer for Codex/Copilot/Claude CLI integration');
   log('  plugin install <target>        Install core plugin; add --all-optional or capability flags');

package/lib/http.js

@@ -52,8 +52,10 @@ function httpErrorFromResponse(method, urlString, statusCode, data) {
 
   const error = new Error(parts.join(' '));
   error.statusCode = statusCode;
+  error.serverMessage = baseMsg;
   error.code = data.code || null;
   error.upgradeUrl = upgradeUrl;
+  error.details = data.details && typeof data.details === 'object' ? data.details : null;
   error.retryAfterSeconds = retryAfterSeconds;
   return error;
 }
@@ -61,14 +63,19 @@ function httpErrorFromResponse(method, urlString, statusCode, data) {
 // Prints a structured JSON error line to stderr so scripts/agents parsing CLI
 // output can branch on `code` (e.g. RATE_LIMITED, PLAN_LIMIT_MEMORY_REACHED)
 // and act on `upgradeUrl`/`retryAfterSeconds` without string-parsing `message`.
-function printApiError(error) {
-  warn(JSON.stringify({
+// JSON.stringify escapes C0 controls but not C1 (0x80 to 0x9f), which some terminals act on.
+function formatApiError(error) {
+  return JSON.stringify({
     error: true,
     code: error.code || 'api_error',
     message: error.message,
     ...(error.retryAfterSeconds != null && { retryAfterSeconds: error.retryAfterSeconds }),
     ...(error.upgradeUrl && { upgradeUrl: error.upgradeUrl })
-  }));
+  }).replace(/[\x80-\x9f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}
+
+function printApiError(error) {
+  warn(formatApiError(error));
 }
 
 function httpJson(urlString, method, payload, headers = {}, timeoutMs = 0) {
@@ -186,6 +193,7 @@ function httpForm(urlString, method, params, headers = {}) {
 module.exports = {
   httpGet,
   httpErrorFromResponse,
+  formatApiError,
   printApiError,
   httpJson,
   httpForm

package/lib/installWizard.js

@@ -32,6 +32,7 @@ function pluginNamesForInstallerOptions(options = {}) {
   if (options.recordWorkHistory !== false) names.push('empirical-work-history');
   if (options.recordScarTissue !== false) names.push('empirical-scar-tissue');
   if (options.recordTodos === true) names.push('empirical-todo');
+  if (options.installVoicePlugin === true) names.push('empirical-voice');
   return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
 }
 
@@ -405,5 +406,6 @@ async function runInstallFlow() {
 }
 
 module.exports = {
-  runInstallFlow
+  runInstallFlow,
+  pluginNamesForInstallerOptions
 };

package/lib/installers/coreMemoryBlock.js

@@ -23,7 +23,8 @@ const PLUGIN_DESCRIPTIONS = {
   [CORE_PLUGIN_NAME]: 'query and save durable project/user context - the core memory skill',
   'empirical-work-history': 'record concise summaries of completed work for future agents',
   'empirical-scar-tissue': 'record recurring failure patterns and prevention guidance',
-  'empirical-todo': 'track actionable follow-ups by project'
+  'empirical-todo': 'track actionable follow-ups by project',
+  'empirical-voice': "write in the person's saved voice whenever you write as them"
 };
 
 function describePlugin(name) {

package/lib/installers/nativePlugin.js

@@ -17,7 +17,7 @@ const { skillFilePath } = require('../skillPaths');
 
 const EMPIRICAL_PLUGIN_SOURCE = process.env.EMPIRICAL_PLUGIN_SOURCE || 'mattgauzza/empirical-memory-plugin';
 const CORE_PLUGIN_NAME = 'empirical-memory';
-const OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo'];
+const OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo', 'empirical-voice'];
 
 function runPluginCommand(command, args, options = {}) {
   return runResolvedCommand(command, args, { stdio: 'inherit', ...options });

package/lib/installers/promptBlocks.js

@@ -23,6 +23,7 @@ const INSTALL_PROMPT_OPTIONS_DEFAULTS = Object.freeze({
   recordWorkHistory: true,
   recordScarTissue: true,
   recordTodos: false,
+  installVoicePlugin: false,
   storeInstructionArtifacts: false,
   checkMemoryBeforeAskingContext: true,
   durableWritesOnly: true
@@ -75,6 +76,8 @@ function normalizeInstallPromptOptions(options = {}) {
       options.recordScarTissue !== false,
     recordTodos:
       options.recordTodos === true,
+    installVoicePlugin:
+      options.installVoicePlugin === true,
     storeInstructionArtifacts:
       options.storeInstructionArtifacts === true,
     checkMemoryBeforeAskingContext:
@@ -228,6 +231,7 @@ function formatPromptOptionSummary(promptOptions) {
     ['Record timestamped work history', promptOptions.recordWorkHistory],
     ['Record scar-tissue guidance', promptOptions.recordScarTissue],
     ['Enable project-based Todo skill', promptOptions.recordTodos],
+    ['Install the writing voice skill', promptOptions.installVoicePlugin],
     ['Store/recall instruction artifacts', promptOptions.storeInstructionArtifacts],
     ['Check memory before asking for context', promptOptions.checkMemoryBeforeAskingContext],
     ['Store durable context only', promptOptions.durableWritesOnly]
@@ -313,6 +317,10 @@ async function collectInstallerPromptOptions() {
     'Install the project-based Todo skill for actionable follow-ups?',
     false
   );
+  const installVoicePlugin = await askYesNo(
+    'Install the writing voice skill so agents write as you once you have saved a voice?',
+    false
+  );
   const storeInstructionArtifacts = await askYesNo(
     'Store and recall instruction artifacts (AGENTS.md/CLAUDE.md/skills-style rules) in Empirical?',
     false
@@ -337,6 +345,7 @@ async function collectInstallerPromptOptions() {
     recordWorkHistory,
     recordScarTissue,
     recordTodos,
+    installVoicePlugin,
     storeInstructionArtifacts,
     checkMemoryBeforeAskingContext,
     durableWritesOnly

package/lib/memoryCommands.js

@@ -33,7 +33,9 @@ function renderMemoryResultsTable(items) {
   const rows = (Array.isArray(items) ? items : []).map((m) => ({
     id: m.id || m._id || '',
     category: m.category || '',
-    summary: truncateForTable(m.summary, 60),
+    // A row marked usage 'style_preference_only' (a writing voice memory) says so, so a person
+    // reading the table sees what an agent reading the JSON sees.
+    summary: truncateForTable(m.summary, 60) + (m.usage === 'style_preference_only' ? ' [style]' : ''),
     // The recall front door emits `score` (toQueryRow plus score in mcp/tools/memory.ts); the
     // older /query route emitted rankScore/similarityScore. Read all three so the column is not
     // blank against a real /recall row. On the list pathways score is deliberately absent, and
@@ -59,7 +61,7 @@ const REMIND_STATES = ['pending', 'notified', 'acknowledged', 'cancelled'];
 // the 90-line global help wall bin/empirical.js otherwise short-circuits every --help to.
 
 const MEMORY_SUBCOMMAND_USAGE = {
-  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--pretty] [--format table]',
+  query: 'Usage: empirical memory query --match <query> [--top-k 3] [--category <cat>] [--tags <t1,t2>] [--tags-all <t1,t2>] [--status <s1,s2>] [--due-before <ISO date>] [--due-after <ISO date>] [--remind-state pending,notified] [--path semantic|list|graph|hebbian] [--hops 1|2] [--workspaces <n|name|id,...>] [--all-workspaces] [--pretty] [--format table]',
   get: 'Usage: empirical memory get --memory-id <id> [--pretty]',
   list: 'Usage: empirical memory list [--category <cat>] [--tags <t1,t2>] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]',
   record: 'Usage: empirical memory record --category <cat> (--summary <text> | --summary - | --summary-file <path>) [--tags t1,t2] [--node-type observation] [--json-file <path>] [--no-dedupe] [--no-auto-link] [--author-type user|agent]',
@@ -192,6 +194,56 @@ function printMemoryResolveError(result) {
 
 // ─── Memory subcommands ───────────────────────────────────────────────────────
 
+/**
+ * Turn `--workspaces` selectors (list numbers, names, or ids) into workspace ids using the
+ * per-user listing (/api/v1/users/me/workspaces, the same list `workspace list` prints; number 1
+ * is always the Default Workspace). An id (ws_...) passes through without a lookup. An unknown
+ * name is fatal at the terminal rather than a 403 or an empty answer after the round trip.
+ */
+async function resolveWorkspaceIdsForQuery({ baseUrl, accessToken, selectors = [], all = false }) {
+  const needsListing = all || selectors.some((s) => !/^ws_/.test(s));
+  let options = [];
+  if (needsListing) {
+    const listUrl = new URL('/api/v1/users/me/workspaces', baseUrl).toString();
+    let payload;
+    try {
+      payload = await httpJson(listUrl, 'GET', undefined, buildApiAuthHeaders(accessToken));
+    } catch (error) {
+      printApiError(error);
+      process.exit(1);
+    }
+    options = [
+      ...(payload?.defaultOption ? [payload.defaultOption] : []),
+      ...(Array.isArray(payload?.workspaces) ? payload.workspaces : [])
+    ].filter((o) => o && o.workspaceId);
+  }
+  if (all) return [...new Set(options.map((o) => o.workspaceId))];
+
+  const ids = [];
+  for (const selector of selectors) {
+    if (/^ws_/.test(selector)) { ids.push(selector); continue; }
+    const asNumber = Number(selector);
+    let match = null;
+    if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= options.length) {
+      match = options[asNumber - 1];
+    } else {
+      const lower = selector.toLowerCase();
+      const byLabel = options.filter((o) => String(o.label || '').toLowerCase() === lower || String(o.key || '').toLowerCase() === lower);
+      if (byLabel.length > 1) {
+        warn(`Ambiguous workspace "${selector}". Use its list number or workspace id.`);
+        process.exit(1);
+      }
+      match = byLabel[0] || null;
+    }
+    if (!match) {
+      warn(`Workspace not found: "${selector}". Run \`empirical workspace list\` to see names and numbers.`);
+      process.exit(1);
+    }
+    ids.push(match.workspaceId);
+  }
+  return [...new Set(ids)];
+}
+
 async function runMemoryQuery(args) {
   const match = parseOption(args, '--match', '');
   if (!match) {
@@ -208,6 +260,17 @@ async function runMemoryQuery(args) {
   // --status filters data.status. Both are optional and additive to --tags/--category.
   const tagsAllRaw = parseOption(args, '--tags-all', '');
   const tagsAll = tagsAllRaw ? tagsAllRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  // Multi-workspace recall (2026-09-24). --workspaces takes list numbers, names, or ids; names
+  // and numbers are resolved against the same listing `workspace list` prints, so the server
+  // contract stays ids-only. --all-workspaces sends every selectable workspace. Without either
+  // flag the query is scoped to the single active workspace exactly as before.
+  const workspacesRaw = parseOption(args, '--workspaces', '');
+  const workspaceSelectors = workspacesRaw ? workspacesRaw.split(',').map((w) => w.trim()).filter(Boolean) : [];
+  const allWorkspaces = parseFlag(args, '--all-workspaces');
+  if (workspaceSelectors.length && allWorkspaces) {
+    warn('Pass either --workspaces or --all-workspaces, not both.');
+    process.exit(1);
+  }
   const statusRaw = parseOption(args, '--status', '');
   const status = statusRaw ? statusRaw.split(',').map((s) => s.trim()).filter(Boolean) : [];
   const pretty = parseFlag(args, '--pretty');
@@ -278,6 +341,14 @@ async function runMemoryQuery(args) {
   if (category) body.category = category;
   if (tags.length) body.tags = tags;
   if (tagsAll.length) body.tagsAll = tagsAll;
+  if (workspaceSelectors.length || allWorkspaces) {
+    body.workspaceIds = await resolveWorkspaceIdsForQuery({
+      baseUrl,
+      accessToken,
+      selectors: workspaceSelectors,
+      all: allWorkspaces
+    });
+  }
   if (status.length) body.status = status;
   if (dueFilters.dueBefore) body.dueBefore = dueFilters.dueBefore;
   if (dueFilters.dueAfter) body.dueAfter = dueFilters.dueAfter;
@@ -1130,6 +1201,7 @@ module.exports = {
   withCliAnalyticsContext,
   resolveMemoryByQuery,
   printMemoryResolveError,
+  resolveWorkspaceIdsForQuery,
   runMemoryQuery,
   runMemoryGet,
   runMemoryList,

package/lib/pluginCommands.js

@@ -4,7 +4,7 @@ const { log, warn, uiHeader, uiSuccess } = require('./ui');
 const { detectInstallTargets } = require('./installers/detect');
 const {
   installNativePlugin,
-  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo']
+  OPTIONAL_PLUGIN_NAMES = ['empirical-work-history', 'empirical-scar-tissue', 'empirical-todo', 'empirical-voice']
 } = require('./installers/nativePlugin');
 const { checkNativePluginUpdates } = require('./pluginUpdateCheck');
 const { addInstalledHosts } = require('./deviceConfig');
@@ -35,6 +35,7 @@ function resolvePluginNames(args = []) {
   if (args.includes('--all-optional') || args.includes('--work-history')) names.push('empirical-work-history');
   if (args.includes('--all-optional') || args.includes('--scar-tissue')) names.push('empirical-scar-tissue');
   if (args.includes('--all-optional') || args.includes('--todo')) names.push('empirical-todo');
+  if (args.includes('--all-optional') || args.includes('--voice')) names.push('empirical-voice');
   return names.filter((name) => name === 'empirical-memory' || OPTIONAL_PLUGIN_NAMES.includes(name));
 }
 
@@ -82,7 +83,7 @@ async function runPluginCommand(args = []) {
   }
   log('');
   log('Native plugin installation does not configure MCP or credentials.');
-  log('Optional packages: --work-history, --scar-tissue, --todo, or --all-optional.');
+  log('Optional packages: --work-history, --scar-tissue, --todo, --voice, or --all-optional.');
   log('Use `empirical auth login` for normal CLI OAuth, or the full `empirical install` flow for MCP setup.');
 }